EMC Document Sciences xEditor 4.5 SP1 User Guide · File SaveSaveAs SavesworkitemtothexPressiondatabaseratherthanthe filesystem Edit FindReplace GoTo TheFind,Replace,andGoTofunctionsinWordaremanaged

EMC® Document Sciences®

xEditorVersion 4.5 SP1

User Guide

EMC CorporationCorporate Headquarters

Hopkinton, MA 01748-91031-508-435-1000www.EMC.com

Legal Notice

Copyright © 2003-2016 EMC Corporation. All Rights Reserved.

EMC believes the information in this publication is accurate as of its publication date. The information is subject to changewithout notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATIONMAKES NO REPRESENTATIONSOR WARRANTIES OF ANY KINDWITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLYDISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. Adobe and Adobe PDFLibrary are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarksused herein are the property of their respective owners.

Documentation Feedback

Your opinion matters. We want to hear from you regarding our product documentation. If you have feedbackabout how we can make our documentation better or easier to use, please send us your feedback directly [email protected]

Table of Contents

Revision History ................................................................................................................... 9

Chapter 1 Introduction ................................................................................................. 11Information Boxes ............................................................................................ 11EMC Document Sciences Technical Support ....................................................... 11

Chapter 2 Getting Started with xEditor ........................................................................ 13The xEditor Interface ........................................................................................ 13Logging Off...................................................................................................... 13Copy and Paste ................................................................................................ 13xPressionHome ................................................................................................ 14

Chapter 3 Working In xEditor for xResponse ............................................................... 15How Does xEditor Work?.................................................................................. 15The Document Actions Panel............................................................................. 16The xResponse Toolbar ................................................................................. 16The Table of Contents — Optional Paragraphs Section .................................... 17The xResponse Menu .................................................................................... 17Properties .................................................................................................... 17

Working With Optional Paragraphs ................................................................... 18Universal Content............................................................................................. 18Empty Line Processing...................................................................................... 18Multi-page TIFF ............................................................................................... 19Form Fields ...................................................................................................... 19Tab Leaders...................................................................................................... 20Finding Existing Content .................................................................................. 20Subdocument Merge......................................................................................... 20Microsoft Word Features and Functions ............................................................. 20Protection .................................................................................................... 22

Known Issues................................................................................................... 22Undo ........................................................................................................... 23

Chapter 4 Working in xEditor for xRevise and Custom Applications ........................... 25How Does xEditor Work?.................................................................................. 26The xEditor Interface ........................................................................................ 26The Document Actions Pane.......................................................................... 26The xRevise Toolbar...................................................................................... 28The Table of Contents Section ........................................................................ 29TOC Icons ................................................................................................ 31

The Information Panel .................................................................................. 31The Command Bar........................................................................................ 33

3

Table of Contents

The xRevise Menu ........................................................................................ 34Finding Existing Content .................................................................................. 34xEditor’s Find Utility .................................................................................... 34Microsoft Word Find and Replace.................................................................. 36

Adding New Content ....................................................................................... 37Deleting and Undeleting Revision Units............................................................. 38Editing in xEditor ............................................................................................. 38Debugging an Edit Session ............................................................................ 38View ............................................................................................................ 38Table Rows................................................................................................... 39Table Wrapping ............................................................................................ 39When Designing a Document for xEditor ....................................................... 39General Guidelines ................................................................................... 39Universal Content..................................................................................... 40HTML Formatted Text from Customer Data ............................................... 40

Moving Revision Units ................................................................................. 40Hidden Text and Page Layouts ...................................................................... 41Fonts ........................................................................................................... 41Special Characters ........................................................................................ 41Form Fields .................................................................................................. 42Tables .......................................................................................................... 43Document Protection .................................................................................... 43Avoiding Proxy Authentication Error............................................................. 44Add Server to Proxy Server Exceptions ...................................................... 44Modify machine.config on the Client Machine ............................................ 44

Braces in Content.......................................................................................... 45Optional Content.............................................................................................. 45Table and Paragraph Merge............................................................................... 46Content Separators ........................................................................................... 46Merged Paragraphs and Content Separators................................................... 46

Subdocument Merge......................................................................................... 46Variables .......................................................................................................... 47Variable Scope .............................................................................................. 47Selecting Variables ........................................................................................ 48Variable Color .............................................................................................. 52Editing Variables .......................................................................................... 52Copy and Paste ............................................................................................ 54Drag and Drop ............................................................................................. 54Variable Formats .......................................................................................... 54Protection and Variables ............................................................................... 55Variable Navigator ....................................................................................... 55NULL Variables............................................................................................ 56

Subtotals, Index Headings, and Table Headings and Footers ............................... 56Variables in Optional Content............................................................................ 56Track Changes.................................................................................................. 57Microsoft Word Features and Functions ............................................................. 57Microsoft Word Features Altered by xEditor .................................................. 57Unsupported Microsoft Word Functions ........................................................ 58Editing Actions in xEditor ............................................................................. 59Microsoft Word Styles................................................................................... 59Content Controls .......................................................................................... 59

Form Fields ...................................................................................................... 60Protection ........................................................................................................ 61

4

Table of Contents

Read Only Protection........................................................................................ 62xEditor Focus While Loading ........................................................................... 62Tab Leaders...................................................................................................... 63

Chapter 5 xEditor Web Services .................................................................................. 65The IDocumentItem Web Service ....................................................................... 65searchDocumentItem .................................................................................... 66Syntax ..................................................................................................... 66Parameters ............................................................................................... 66Sample..................................................................................................... 67

The createDocumentItem Method.................................................................. 68Syntax ..................................................................................................... 69Parameters ............................................................................................... 69

The getDocumentItemInfo Method ................................................................ 70Syntax ..................................................................................................... 71Parameters ............................................................................................... 71Examples ................................................................................................. 72

The publishAndReturnDocumentItem Method............................................... 74Syntax ..................................................................................................... 75Parameters ............................................................................................... 75

The documentItemsAssignedToUser Method ................................................. 75Syntax ..................................................................................................... 75Parameters ............................................................................................... 76

The reassignDocumentItemToUser Method.................................................... 76Syntax ..................................................................................................... 76Parameters ............................................................................................... 76

The updatePrimaryVariables Method ............................................................ 77Syntax ..................................................................................................... 77Parameters ............................................................................................... 77

The copyDocumentItem Method ................................................................... 78Syntax ..................................................................................................... 78Parameters ............................................................................................... 78

The addExternalContentByLink Method ........................................................ 79Syntax ..................................................................................................... 79Parameters ............................................................................................... 79

addExternalContentByStream ....................................................................... 80Syntax ..................................................................................................... 81Parameters ............................................................................................... 81

The reorderExternalContent Method ............................................................. 82Syntax ..................................................................................................... 82Parameters ............................................................................................... 82

The addAnnotation Method .......................................................................... 83Syntax ..................................................................................................... 83Parameters ............................................................................................... 83

The deleteExternalContent Method................................................................ 84Syntax ..................................................................................................... 84Parameters ............................................................................................... 84

The createAuthenticationToken Method......................................................... 84Syntax ..................................................................................................... 84Parameters ............................................................................................... 86

The complete DocumentItem Method ............................................................ 86Syntax ..................................................................................................... 86Parameters ............................................................................................... 86

The deleteDocumentItem Method.................................................................. 87Syntax ..................................................................................................... 87Parameters ............................................................................................... 87

The publishRevisionUnits Method................................................................. 88Syntax ..................................................................................................... 88

5

Table of Contents

Parameters ............................................................................................... 89The setCarryForwardDocumentItem Method ................................................. 89Syntax ..................................................................................................... 89Parameters ............................................................................................... 90

The clearCarryForwardDocumentItem Method .............................................. 90Syntax ..................................................................................................... 90Parameters ............................................................................................... 90

The updateRUVariables Method .................................................................... 91Syntax ..................................................................................................... 91Parameters ............................................................................................... 91

The submitDocumentItem Method ................................................................ 92Syntax ..................................................................................................... 92Parameters ............................................................................................... 92

The approveDocumentItem Method .............................................................. 92Syntax ..................................................................................................... 92Parameters ............................................................................................... 93

The rejectDocumentItem Method................................................................... 93Syntax ..................................................................................................... 93Parameters ............................................................................................... 93

Calling the xEditor StartUp Application ............................................................. 94Syntax ......................................................................................................... 94Parameters ................................................................................................... 94Samples ....................................................................................................... 95Starting xEditor the First Time....................................................................... 95

Chapter 6 Administering xEditor ................................................................................. 97Administering xEditor for xResponse ................................................................ 98Temporary Files............................................................................................ 98Known Issues............................................................................................... 98Multiple Microsoft Word Versions ............................................................. 98Opening xEditor After “Failed to start editor” Error ................................... 98

The Log ....................................................................................................... 99Administering xEditor for xRevise and Custom Applications .............................. 99Spell Check for Form Fields......................................................................... 100Variable Color ............................................................................................ 100Track Changes............................................................................................ 100The Log ..................................................................................................... 100Localization ............................................................................................... 101Customizing Carry Forward........................................................................ 101DEFAULT_CONFIG.xml......................................................................... 101

xEditor Installation and Setup ......................................................................... 102Preparing Your Environment....................................................................... 103Java Runtime Environment ..................................................................... 103Microsoft .NET Framework ..................................................................... 103Visual Basic for Applications ................................................................... 104Internet Explorer Settings........................................................................ 104Adobe PDFMaker................................................................................... 105

How Smart Client Handles Updates ............................................................ 105Starting xEditor the First Time..................................................................... 105Installing xEditor........................................................................................ 106Pushing the xEditor Installation from the Server ........................................... 107Client Verification....................................................................................... 107

User Configuration ......................................................................................... 108Siteminder ..................................................................................................... 108Workflow....................................................................................................... 108Enabling xEditor Functions ............................................................................. 108

6

Table of Contents

Cache Management ........................................................................................ 109Ribbon Configuration .................................................................................... 109How to Make Changes to Your Microsoft Word Ribbon ................................ 110Additional Configuration Steps for xRevise Users......................................... 111Language Specific Configuration Files ......................................................... 111Creating a CustomW2007_DEFAULT_CONFIG.xml for xRevise ................... 111Element Properties ..................................................................................... 112Excluded, Repurposed, and Unsupported Commands .................................. 114

xEditor Event Notification............................................................................... 117Local Files ...................................................................................................... 117xEditor Localization........................................................................................ 118Microsoft Word Issues .................................................................................... 118Microsoft Word Add-Ons............................................................................ 118Multiple Microsoft Word Versions ............................................................... 118Balloons ..................................................................................................... 119Undo ......................................................................................................... 119Undo After Paste Not Supported ............................................................. 119Using Undo............................................................................................ 119

Table Rules and Read Only Protection ......................................................... 119Inserting Table Rows................................................................................... 120

Avoiding the Failed to Merge Content Error ..................................................... 120Hidden Text Panel .......................................................................................... 120Runtime Error when Closing xEditor ............................................................... 120xEditor and Terminal Service Logon ................................................................ 121Upgrading from Earlier Versions ..................................................................... 121Clearing an Application File on the Client Machine .......................................... 121Charts............................................................................................................ 122

Appendix A Words Excluded from SQL Full Text Search .............................................. 123Exclusion Table .............................................................................................. 123

7

Table of Contents

List of Tables

8

Revision History

Revision Date Description

October 2016 Updated xEditor’s Find Utility, page 34 with anote about revision unit searches.

June 2014 Initial publication.

9

Revision History

10

Chapter 1Introduction

Welcome to xEditor, a Microsoft Word-based editor that enables you to use Microsoft Word’spowerful editing and composition features while modifying or building documents from approvedcontent created in xDesign.

Information BoxesThe following colored boxes alert you to special information in the documentation.

Caution: The caution box warns you that a fatal error, unsatisfactory output, or loss of data mayoccur if you do not follow the directions carefully.

Tip: A tip offers suggestions to simplify a task or describes a useful shortcut. They may also describean alternate way to use the techniques described in the text.

Note: A note offers information that emphasizes or supplements important points of the main text.

EMC Document Sciences Technical SupportFor more information or to solve a problem, contact EMC Document Sciences Technical Support:

Online Support: https://support.emc.com

Telephone Support:

United States: 800-782-4362Canada: 800-543-4782Worldwide: +1-508-497-7901

For additional worldwide access numbers, visit:

http://www.emc.com/collateral/contact-us/h4165-csc-phonelist-ho.pdf

11

https://support.emc.com

http://www.emc.com/collateral/contact-us/h4165-csc-phonelist-ho.pdf

Introduction

12

Chapter 2Getting Started with xEditor

xEditor is a Microsoft Word-based editor that enables you to use Microsoft Word’s powerful editingand composition features. xEditor is used for editing by xResponse, xRevise, and by customapplications created with the xPression Web Services. xResponse uses a subset of xEditor’s featureswhile xRevise and your custom application are able to use the entire xEditor feature set. For thisreason, the user interface is slightly different for xResponse.

The xEditor InterfaceThe main difference between Microsoft Word’s interface and xEditor is the addition of the DocumentActions panel, which is displayed in Microsoft Word Task Pane. The following image shows theDocument Actions panels for xResponse and xRevise.

Logging OffTo avoid xEditor from consuming additional license seats ensure you follow these procedures whenlogging off.

1. First, close your xEditor windows. If multiple xEditor windows remain open, they will toconsume extra license seats each time a document is saved.

2. Log off xRevise, xResponse, or your custom application. You should always log off before closingthe application browser window. If you close the browser first, the session will remain activeand the license seat will not be available to other users. Your session will eventually closeautomatically, and your xPression administrator can also close the session if necessary.

3. Close the browser window.

Copy and PastePaste operations cannot be reversed using the Undo feature if the content contains variables.

13

Getting Started with xEditor

xPressionHomeThe term “xPressionHome” refers to the location where xPression was installed on your server. Bydefault on Windows servers, the location is C:\xPression, but your installer may have selecteda different location during installation. Please consult with your administrators or IT personnel todetermine the location where they installed xPression. Throughout the xPression documentation, wewill refer to this location as “xPressionHome”.

14

Chapter 3Working In xEditor for xResponse

Editing documents in xEditor is very similar to editing documents in Microsoft Word. Most MicrosoftWord functions are fully supported, and the interface is virtually identical except as noted above.However, certain limitation do apply and should be considered when working with xEditor.

This section contains the following topics:• How Does xEditor Work?, page 15

• The Document Actions Panel, page 16

• Working With Optional Paragraphs, page 18

• Universal Content, page 18

• Empty Line Processing, page 18

• Multi-page TIFF, page 19

• Form Fields, page 19

• Tab Leaders, page 20

• Finding Existing Content, page 20

• Microsoft Word Features and Functions, page 20

• Known Issues, page 22

Note: If an xEditor work item contains many Word style changes, Microsoft Word may unexpectedlyremove all Word styles and apply Normal style to the entire document. If Word displays thefollowing message, select No:Recording Clipboard style sheet will require copying many styles.Do you want to use Normal style instead?

How Does xEditor Work?When you enter into an editing session, Microsoft Word will load and open your document forediting. When a document is open in xEditor, it is locked for all other activity. You or other xResponseusers will be unable to use the Submit, Delete, or Assign features with the locked document. IfxEditor stops without properly closing the document, the same user can reopen the locked document.

If the xResponse session closes, whether by user action or timeout, and a work item remains open inxEditor, the work item will remain locked until the xEditor session is closed. A message displays

15

Working In xEditor for xResponse

when the xResponse session closes with a work item locked reminding the user to close the editorwhen finished editing.

You must log off xEditor whenever your user session closes. xEditor will not close automatically. It ispossible to continue working even though the xResponse session has timed out.

The Document Actions PanelThe Document Actions panel resides in the Task Pane. It opens docked to the right side of thewindow by default, but you can relocate it if desired. You can access all xRevise functions throughthe Document Actions panel. Word provides a number of functions through the Task pane, suchas the XML Structure pane. You can switch panes by clicking the title bar currently displayed andselecting the desired pane from the list.

Clicking the x button in the upper-right corner of the Task pane will close it. To reopen the Task pane,select Task Pane from the Viewmenu or right-click in the toolbar area, below the menus, and selectTask Pane from the menu.

The Document Actions panel contains task pane controls, a toolbar and two display areas.

• The xResponse Toolbar, page 16

• The Table of Contents — Optional Paragraphs Section, page 17

• The xResponse Menu, page 17

• Properties, page 17

The xResponse Toolbar

The buttons on the xResponse toolbar, near the top of the pane, perform these functions.

Button Description

xResponse Opens a drop-down list that provides access to administrative features:• Cache Settings opens the Cache Settings dialog box. See Cache Managementfor details.

• xResponse Log opens the xResponse log in a text editor. See The Log.

• About xResponse opens a pop-up with the current xResponse.dll version.This information can be useful when troubleshooting your xResponseinstallation.

Save Saves the document. This increments the revision number for any section thathas been changed since the last time that the document was saved. This alsocreates a new xPression database object. Note that xPression removes unusedxPression database objects to prevent problems with search and other issues.

16


Button Description

Preview Opens the document in the PDF preview window.

Annotation Displays any annotations associated with the document. Annotations cannotbe edited in xEditor. After creating an annotation xEditor will not allowanother annotation to be added until the work item is saved. Annotations canalso be attached in the xResponse client interface or xDesign.

The Table of Contents — Optional Paragraphs Section

This section displays a table of contents, or work item structure, when your document makes use ofOptional Paragraphs. This section does not appear when the document does not contain OptionalParagraphs. Optional Paragraphs are created in xDesign. They enable you to choose which textappears in the final document. When text is marked as “optional” by your document designers inxDesign, it appears in the xEditor Table of Contents with a check box (for multi-select content) or radiobutton (for single-select content). See Working With Optional Paragraphs, page 18 for instructions onhow to use this feature. For more background on Optional Paragraphs, see the xDesign User Guide.

The xResponse Menu

The Microsoft Word ribbon includes an xResponse tab. This ribbon enables you to open the TaskPane. It also provides functions that are also available in the xResponse menu on the Task Pane.

• Show xResponse — opens the Task Pane.

• Show Log — opens the xResponse log in a text editor. See The Log.

• About xResponse — opens a pop-up with the current xResponse.dll version. This information canbe useful when troubleshooting your xResponse installation.

Properties

Properties are established when the document is created. Once created, they cannot be changed inxResponse, so this part of the Document Actions panel is read-only. The following properties aredisplayed when the highest level node is selected:

• Name

• Work ID

• Last Saved Time

• Customer Key

• Category Name

• Publisher Type

• Document Protection

17


Working With Optional ParagraphsA section of text can be designated as “optional” when it is created in xDesign. You are neverrequired to include optional material in the xResponse work item. Optional Paragraphs enable youto choose which text appears in the final document. When text is marked as “optional” by yourdocument designers in xDesign, it appears in the xEditor Table of Contents with a check box (formulti-select content) or radio button (for single-select content).

The following icons are used with work items that include optional paragraphs.

Icon Description

Multi Select Multi-select Optional Paragraph Group - This type of Optional Paragraph isidentified by the use of checkboxes. You can select one or more OptionalParagraphs from the Optional Paragraph group. You could also choose toselect none of the Optional Paragraphs for inclusion in the final document.

Single Select Single-select Optional Paragraph Group - This type of Optional Paragraphis identified by the use of radio buttons. You can select only one OptionalParagraph from the Optional Paragraph Group.

Universal ContentThe document designer can include external content, such as PDFs, multi-page TIFFs, and others. Insome cases editing opportunities for external content are limited. There is no indication in xResponsewhat type of external content is present. Inline universal content is not supported in xEditor, anduniversal content cannot be used as an optional paragraph. xResponse will not allow a documentwith inline universal content or universal content being used as optional paragraphs to be usedas a work item.

Page numbering preferences, Even/Odd page settings, and Inherit Layout settings are not honored inUniversal Content (UC) for documents used with xEditor. Universal Content is converted to an imagefor viewing and previewing, so when UC is viewed in xEditor or opened for “Preview as Word” itwill appear exactly as it would if the UC were opened directly, but output will be correct.

The Use Master Definition option is not respected in documents intended for use in xEditor. Elementsin the Universal Content will not be included in the master document table of contents in xEditordocuments.

Any table styles contained in a Word Doc or Word Docx universal content will not appear in anytable style list in xEditor.

Empty Line ProcessingEmpty lines are normally discarded. This is typically preferred in cases where there may be textin some cases, but when there is no text there should be no blank line either. For example, manydocuments include an ADDR2 line, but if there is no second address line the resulting blank is

18


discarded so that there is no space between ADDR1 and the City, State, Zip Code line that typicallyfollows the address lines.

Under certain circumstances xEditor inserts a non-printing character in blank lines, which results inthe blank line being retained. To avoid this, use a paragraph style for the line that may not containtext which indents the line.

Multi-page TIFFMulti-page TIFFs (images in the Tagged Image File Format) can be included by the documentdesigner as external content. External TIFFs are not indicated in the xEditor TOC for xResponseand the xResponse user does not have the ability to specify which pages are included in output ormodify the external content in any way.

Form FieldsThe document designer can include form fields in the document. Only check box, text box, anddrop-down list form fields from the Legacy Tools selection are supported. Form fields are used toenable users of the document to make limited changes to the document. The section of the documentthat contains the form fields must be under Filling in Forms protection. Since xResponse documentsmay be assembled from multiple xDesign content items, and Filling in Forms protection is notcompatible with Read Only protection, any document that contains form fields cannot use ReadOnly protection. The document designer can create a document with unprotected sections alongwith sections under Filling in Forms protection.

Multiple paragraphs are supported in text box form fields, but are not supported for fillable PDFoutput.

The xDesign document designer can use variables to populate drop-down lists and text boxes.xResponse converts all variables to static text when the document is assembled, so the consequencesfor changing variables in xResponse are the same as editing any other content.

The xEditor user can modify the contents of form fields, but cannot modify text outside of the formfields in sections that are under Filling in Forms protection.

New form fields cannot be added in xEditor. Content that includes form fields can be searched andinserted into other sections as long as the target section is under Filling In Forms protection.

The content of form fields cannot be automatically spell-checked in xResponse, regardless of whicheditor is used.

Bookmarks are mandatory for form fields. Never remove the bookmark for a form field.

Form fields are functional in Fillable PDF output. The xPression administrator can provide an outputprofile that supports fillable PDF output.

19


Tab LeadersThe document designer can choose to use tab leaders in indexes to provide a uniform appearance.However, because of the method used to prepare the document for use with xEditor, tab leadersettings cannot be passed. So it will be necessary to reset the index and apply any desired tab leaderfor any document using tab leaders in an index.

Finding Existing ContentxEditor for xResponse does not provide a search function other than Word’s native Search feature.There are some limitations to Word’s Search feature, along with some others. See Microsoft WordFeatures and Functions.

Subdocument MergeWhen you create a work item, xPression automatically creates a revision unit and inserts a paragraphbreak when a subdocument is encountered. If the subdocument is a paragraph that is marked tobe merged with the paragraph preceding it, the paragraph merge is ignored either in xEditor orin the publishing output. If you want to merge paragraphs in this situation, set the value of theTreatSubdocAsAutomaticRevisionUnit property in revise.properties to false. When the value isset to false, xPression does not create a revision unit for a subdocument. However a revision unit isstill created for a subdocument that starts with a section, which is assigned a unique revision unitname. This property works for work item creation only, and has no impact on existing work items.Any changes of this property value will not take effect until you restart the server.

Microsoft Word Features and Functions

Caution: It is possible to open multiple instances of MS Word, so be sure to save your workand close xEditor when finished. Instances of Word appear in the Task Manager as MSWORDprocesses.

Microsoft Word will occasionally display document Auto Recovery task pane when launched inxEditor. xEditor does not support this Auto Recovery feature. When presented with the AutoRecovery pane, please close the pane by clicking Close. Do not attempt to recover any files.

xEditor supports most Microsoft Word features and functions. Some functions are not supportedbecause xEditor provides a similar function for use within the xPression environment. For example,Word’s New function is not supported because work items for xResponse must be created in xDesign;they cannot originate in xResponse.

Caution: Many add-ons are available for Microsoft Word. Using xEditor with third-partyadd-ons may produce unexpected results.

20


By default Microsoft Word displays comments and changes in balloons. If balloons are displayedand adjacent sections have different page settings, Word will break the page between these sections.This may result in an extra page being added to the document. This effect will occur in cases wheresubdocuments have different page settings than adjacent sections, and so the unexpected pagebreak may have no apparent cause without understanding this behavior. To prevent the unexpectedbreak, either turn off balloons or redesign the document and all subdocuments to have the samepage settings.

The following Word functions are either not available with xEditor, or the stock functionality ismodified by xEditor. It may be possible to enable toolbar buttons or menu item for those that are notsupported, but the function is still overridden by xEditor. It is also possible disable others, see thexRevise User Guide for more information on enabling and disabling toolbar and menu items.

The following functions are not supported by xEditor, but cannot be suppressed in the interface.

Function Description

Create or ModifyStyle

xEditor does not support creating new styles. When xEditor detects a newstyle, the style is deleted and a message is displayed. xEditor does not supportmodifying styles. Users should not modify styles because satisfactory resultscannot be guaranteed.

New Window Word does not allow this option while running with xEditor because an XMLexpansion pack is attached. This limitation is imposed by Word.

The following Word features work differently in xEditor.

Feature Description

Created On The Created On option for Insert Auto Text does not insert the actual date thedocument was created. It always inserts “Created on 6/19/2007 10:14:00 AM.”It is recommended that users avoid using this option.

CTRL+A The CTRL+A hotkey combination selects the entire document in Word.CTRL+A behaves differently in xEditor. In xEditor CTRL+A selects thecurrent section but never selects optional paragraphs.

Protection xEditor supports Read Only and Forms Fill-In protection types for work itemcontent with some restrictions. See Protection.

The following Word functions are overridden or modified by custom xEditor functions.

Word Menu Function xEditor Implementation

File SaveSave As Saves work item to the xPression database rather than thefile system

Edit FindReplace

Go To

The Find, Replace, and Go To functions in Word are managedthrough a single dialog box with each function beingrepresented with a tab and the user can freely switch amongthem. In xEditor, the tabs other than the one specificallyopened from the menu are not available. For example, if youselect Find from the menu, the Replace and Go To tabs willbe grayed out and unavailable. To access the other functions,select them directly from the menu. See Finding ExistingContent .

21



Tools Spelling andGrammar

Spelling and Grammar is available, but the functionshave been modified to accommodate special needs andcircumstances introduced to the document by xEditor. Thedifferences are not readily apparent to the user.

Tools Compare Merge xEditor allows comparison and merge with historical copiesof the current document, or Word documents from the filesystem.

The following Microsoft Word functions are not supported and cannot be used with xEditor.

Word Menu/ Control Set Function

File Send To, Version, Properties

View Document MapThumbnails

Format Theme, Text Direction, Auto Shape, Auto Format

Tools Shared Workspace, Track Changes, Mail Merge, Templates andAdd-InsNote that Track Changes is used by the application. Itcannot be turned off.

Insert Diagram, Picture, Object

Window Compare Side by Side with

Task Pane Mail Merge, Protect Document, XML Structure

All other standard Word functions and features are available and perform as expected with xEditor.You can further restrict the options available with Toolbar Configuration, but you cannot enablefeatures disabled by xEditor.

Protection

xEditor supports Read Only and Filling in Forms protection types for work item content for bothxRevise and xResponse, but only one type within a given document. The first type encountered willbe used for the entire document. Protection must be established in xDesign when the document iscreated. Turning off protection in xEditor is not supported.

Known IssuesWhen you are previewing and editing documents in xResponse, please be aware that once xEditorhas been launched for a document, you cannot return to the Preview page to make changes to youroptional paragraphs. After the xEditor has been launched for a document, the only place where youcan make changes to optional paragraphs for that document is in xEditor.

22


For example, when you are at the Preview page, you have the ability to:• Make changes to your optional paragraphs

• Edit the document

• Distribute the document

If you choose to edit the document, xResponse will launch xEditor. Once this occurs, you cannotreturn to the Preview page to make changes to your optional paragraphs. However, if you choose todistribute the document, bypassing the editor, you are allowed to return to the Preview page to makechanges to your optional paragraphs. This is allowed because xEditor was never launched.

Undo

In some cases it is necessary to click Undo twice to restore the document to its status prior to makingan edit. For example, if a word is selected and then replaced by typing a new word, the first undowill delete all but the first letter of the new word and the second undo will replace the remainingletter with the original word. This behavior is because of the way Microsoft Word records the actions.The select action is an action and the replace action is another action, so Word requires two undoactions to completely restore the original text. The same behavior can be observed in MicrosoftWord without xEditor.

23


24

Chapter 4Working in xEditor for xRevise andCustom Applications

Editing documents in xEditor is very similar to editing documents in Microsoft Word. Most MicrosoftWord functions are fully supported, and the interface is virtually identical to Microsoft Word.However, certain limitation do apply and should be considered when working with xEditor.• How Does xEditor Work?, page 26

• The xEditor Interface, page 26

•• Finding Existing Content, page 34

• Adding New Content, page 37

• Deleting and Undeleting Revision Units, page 38

• Editing in xEditor, page 38

• Optional Content, page 45

• Table and Paragraph Merge, page 46

• Content Separators, page 46

• Variables, page 47

• Subtotals, Index Headings, and Table Headings and Footers, page 56

• Variables in Optional Content, page 56

• Track Changes, page 57

• Microsoft Word Features and Functions, page 57

• Form Fields, page 60

• Protection, page 61

• Read Only Protection, page 62

• xEditor Focus While Loading , page 62

• Tab Leaders, page 63

Note: If an xEditor work item contains many Word style changes, Microsoft Word may unexpectedlyremove all Word styles and apply Normal style to the entire document. If Word displays thefollowing message, select No:

25

Working in xEditor for xRevise and Custom Applications

Recording Clipboard style sheet will require copying many styles.Do you want to use Normal style instead?

How Does xEditor Work?When you enter into an editing session, Microsoft Word will load and open your document forediting. When a document is open in xEditor, it is locked for all other activity. You or other xResponseusers will be unable to use the Submit, Delete, or Assign features with the locked document. IfxEditor stops without properly closing the document, the same user can reopen the locked document.

If the xResponse session closes, whether by user action or timeout, and a work item remains open inxEditor, the work item will remain locked until the xEditor session is closed. A message displayswhen the xResponse session closes with a work item locked reminding the user to close the editorwhen finished editing.

You must log off xEditor whenever your user session closes. xEditor will not close automatically. It ispossible to continue working even though the xResponse session has timed out. It is possible to openmultiple instances of Microsoft Word, so be sure to save your work and close xEditor when finished.Instances of Word appear in the Task Manager as MSWORD processes.

Microsoft Word will occasionally display document Auto Recovery task pane when launched inxEditor. xEditor does not support this Auto Recovery feature. When presented with the AutoRecovery pane, please close the pane by clicking Close. Do not attempt to recover any files.

xEditor is an extension of Microsoft Word. To close xEditor, simply close the Word instance hostingit. For example, clicking the Close button in the upper-right corner of the Word window will closeWord and xEditor. Ensure that all work is saved before closing the application. Note that Word’s autosave feature does not save your work to the xPression database.

The xEditor InterfaceFor an overview of the xEditor interface, see the following topics:• The Document Actions Pane, page 26

• The xRevise Toolbar, page 28

• The Table of Contents Section, page 29

• The Information Panel, page 31

• The Command Bar, page 33

• The xRevise Menu, page 34

The Document Actions Pane

The Document Actions pane resides in the Task Pane. It opens docked to the right side of thewindow by default, but you can relocate it if desired. You can access all xRevise functions throughthe Document Actions pane. Word provides a number of functions through the Task pane, such as

26


the XML Structure pane. You can switch panes by clicking the title bar currently displayed andselecting the desired pane from the list.

Tip: Clicking the x button in the upper-right corner of the Task pane will close it. To reopen the Taskpane, select Task Pane from the View menu or right-click in the toolbar area, below the menus,and select Task Pane from the menu.

The Document Actions pane contains task pane controls, a toolbar and display areas.

27


The xRevise Toolbar

The buttons on the xRevise toolbar, near the top of the pane, perform these functions.• xRevise

Opens a drop-down list that provides the following options:— Search Results displays Search Results in the lower pane.

— Show/Hide deleted revision units toggles showing and hiding deleted revision units. SeeDeleting and Undeleting Revision Units.

— Cache Settings opens the Cache Settings dialog box. SeeCache Management for details.

— xEditor log opens the xEditor log in a text editor. SeeThe Log .

— About xRevise opens a pop-up with the current xRevise.dll version. This information can beuseful when troubleshooting your xRevise installation.

— Preferences opens the Preferences dialog box where the user can designate a key combinationto navigate to the next region that is not under Read Only protection.

• Debug

The Debug button is not normally displayed, but xEditor can be configured to display it by thexPression administrator. This feature should be enabled and used only as directed by EMCDocument Sciences Technical Support.

• Forward / Backward

Moves the focus to the next or previous variable in the document. Clicking repeatedly will scrollthrough all variables in the work item until the end of the document, beginning or end dependingon which button is being used, at which point scrolling will stop.

• Save

Saves the document. This increments the revision number for any section that has been changedsince the last time that the document was saved. This also creates a new xPression databaseobject. Note that xPression removes unused xPression database objects to prevent problemswith search and other issues.

• Preview

Opens the document in the PDF preview window.

• Spell check for form field

Opens the spell check for form fields. This is an extension of Microsoft Word’s spell check feature.See Spell Check for Form Fields. This button appears if the work item contains form fields and asection under Filling In Forms protection only.

• Insert RU

Opens the Insert RU window in the Task pane where you provide a name, jurisdiction(s), andlanguage for the new revision unit. The new RU is inserted after the element that is currentlyselected in the TOC, either an RU or the root element. See Adding New Content.

28


• Search

Opens the Search window in the Task pane. See Finding Existing Content, page 34 for details onusing the Search function.

• Goto Next Editable Region

Microsoft Word’s Read Only protection option provides the ability to prevent edits in thedocument except in designated regions. Clicking this button moves the focus to the next regionthat is not under Read Only protection.

The Table of Contents Section

The TOC shows the document structure. Nodes in the tree represent Revision Units. or RUs. RUs areestablished in the document when it is created in xDesign, and function as content items or sections.All xRevise work items contain at least one RU. An asterisk is appended to the node’s name when anychange is made that affects the assembly, such as adding or moving an RU. You can add new contentitems, which are displayed in the same manner as those created in xDesign.

When you select a Revision Unit in the TOC, the cursor is moved to the beginning of the RU in theedit pane and the Revision Unit’s properties are displayed in the Properties window as shown inbelow. Double-clicking an RU in the TOC selects the entire RU in the edit pane. RUs with unsavedchanges are indicated with an asterisk in the TOC.

Move RUs in the TOC by clicking the RU and dragging it to the desired location. Moved RUs aremarked with an asterisk showing that there was a change, even if the content of the RU remainsthe same.

Multi-page TIFFs and PDFs can be included in the document by the document designer. The externalcontent item is represented as an RU in the TOC. If the document designer does not establish an RUfor the external content, an RU will be created when the work item is created. The external content’sRU is represented in the TOC by a distinctive icon. The external content’s RU will include a childnode for each page, if the content includes multiple pages. Each page can be excluded if desired.To skip a page right-click the page’s node and select Exclude from the context menu. To restore apage that had been marked for exclusion, right-click the node and select Include. Page selections areretained for subsequent sessions. External PDF other than universal content PDF does not supportExclude/Include.

The document designer can add a variety of document types as external content in addition toPDF and TIFF, including universal content and other xDesign documents. The distinction betweenexternal content and master document content is not apparent to the xEditor user, except in the casesof PDF and TIFF external content. External content cannot be added by the xEditor user.

The Table of Contents is disabled when working in headers and footers, so navigating with the TOCis not possible when in Header/Footer mode. To exit Header/Footer mode, click outside the headeror footer region, or click Close Header/Footer.

29


Some xEditor functions are not available through the toolbar, but can be accessed by right-clickingthe document node or any RU in the TOC. The right-click menu for the document node providesthe following options.• Save As

Opens the Save dialog box and enables you to save the document as a file to any selected location.Saving the file in this way allows you to open the file without going through xRevise, but changeswill not be available to xRevise.

• Annotation

Displays any annotations associated with the document. Annotations cannot be edited in xEditor.After creating an annotation xEditor will not allow another annotation to be added until the workitem is saved. Annotations can also be attached in the xRevise client interface or xDesign. Newannotations can be added to the work item using the New Annotation button on the CommandBar.

• Compare to File

Opens the Compare window where you can compare the current work item with either a workitem stored in the xRevise history for this item, or a Word document stored on the local file system.The work item must be saved before this feature can be used.

• Compare to Work Item

Opens the Microsoft Word Compare feature to compare the current document to another workitem using this Microsoft Word feature rather than Carry Forward.

• Carry Forward

Opens the xRevise Carry Forward utility to compare the current document to another work itemusing this xRevise feature.

The right-click menu for the RUs provides the following options.• Delete/Undelete

Deletes or undeletes the selected revision unit. The title of the option changes appropriately withthe delete status of the RU. You cannot delete the last RU in the document, so this option isavailable only if there is another RU in the document. See Deleting and Undeleting Revision Units .

• Annotation

Displays any annotations for the work item. Annotations cannot be edited or deleted oncecreated. Annotations can be added to xRevise work items through the xRevise desktop or theNew Annotation button on the Command Bar in xEditor. Annotations can be as long as desired.Only one annotation can be added at a time. Save the work item to add a new annotation.

• Revert

Discards all unsaved changes to the RU.

• Include/Exclude

These options are available for each page in a multi-page TIFF. Select the appropriate option toinclude or exclude the page. All pages are included by default.

30


TOC Icons

The following icons appear in the xEditor Table of Contents.• Document Node

The top node of the current document representing the entire document. All other nodes in theTOC are below this node.

• Revision Unit

xRevise documents are divided into Revision Units. Each RU is represented with this icon. SomeRUs have further child nodes.

• External Content

The document designer can include external content in the document. Each piece of externalcontent is contained in its own RU represented by this icon. Multi-page TIFF and PDF contentrepresents each page in the external item as a child node of this icon.

• External Content Page

Each page in a multi-page external content item is represented by this icon under the ExternalContent RU node. If the external content is a multi-page TIFF right-clicking the child node opens acontext menu that provides the option of skipping the page.

• Multi Select

Multi-select Optional Content Group - Any combination of optional content under a MultiselectOptional Content Group can be selected. Clicking a selected item deselects it. You are neverrequired to select optional content. See Optional Content, page 45.

• Single Select

Single-select Optional Content Group - Only one optional content item under a Single-selectOptional Content Group can be selected. Selecting an item deselects any currently selected item.Clicking a selected item deselects it. You are never required to select optional content. SeeOptional Content, page 45.

The Information Panel

Immediately below the TOC section is the Information Panel, which consists of several grids thatshow details related to the current selection. Each grid in this panel displays the indicated informationrelated to the selected element. By default the Variables grid is expanded and the Properties andAttributes grids are collapsed. Click the maximizer icon to maximize or collapse each section.

Properties are established when the document or revision unit is created. Once created, they cannotbe changed in xRevise, so this grid is read-only except when creating a new revision unit. Thefollowing properties are displayed when the highest level node is selected:

• Name

• Work ID

• Last Saved Time

• Customer Key

31


• Category Name

32


• Publisher Type

• Document Protection

When a Revision Unit is selected the following properties are displayed:

• Name

• Create Date

• Revision

Optional content that has been marked for Merge by the document designer is indicated with a MergeParagraphs section. The xEditor user cannot designate content for merge.

If the Revision Unit includes an annotation the date the annotation was created and a portion ofthe annotation is displayed. If the Revision Unit was inserted from search results and containsvariables, then the variables are displayed as well. If an optional content group is selected the nameand optional group type (single or multi) is displayed.

The Create Date for a revision unit is established as the current date when the RU is created or whenit is manually inserted into xRevise. RUs created from content item search are initially assigned theCreate Date for the content item, but are changed to the current date when the RU is saved or edited,or upon exit. Note that xDesign content items do not necessarily correlate to an xRevise revision unit.

Attributes depend on the attribute set used by the document that created the work item. The RUcannot be renamed if the Revision is 1 or greater.

Note: The value for an attribute may be blank (nothing indicated for the attribute) or <none> if thereis no value for the attribute. If the value is blank it indicates that either the value was set to “no value”in xDesign, or that a search and insert was performed and the value never set. If the value is <none> itindicates that the value was not set at all, not even to “no value,” in xDesign.

The Variables grid displays the type, name, value, and source for each variable used in the documentif the document node is selected or the RU if an RU is selected. Refer to Variables for moreinformation on using the Variables grid.

The Command Bar

The Command Bar, located at the top of the Information Panel of the Task Pane, provides accessto several features provided for working with variables, and enables adding a new annotation tothe work item.• Toggle Variable Editing

The Variables grid must be in Edit mode to allow variable editing. Click this button to toggle Editmode on and off. Toggling the Edit mode cannot override certain protections that may be imposedon variables: some variables can never be edited, some variables may be under protectionestablished by the document designer, and the xPression administrator can prevent any variableediting. See Editing Variables for more information on working with variables and variable values.

• Variable Navigator

33


Opens the Variable Navigator, which displays all values that have been applied to the selectedvariable and where it is used within the work item. Values must have been saved to appear in thehistory. See Variable Navigator for more information on the Revision History dialog box.

• New Annotation

Opens the New Annotation dialog box, enabling you to add a new annotation to the work item.

The xRevise Menu

When running xEditor, Word’s menu bar includes an xRevise menu. The main purpose for this menuis to provide a convenient means of opening the Task Pane in the event that it closes. It also providessome functions that are also available in the xRevise menu on the Task Pane.

• Show xRevise opens the Task Pane.

• Show Log opens the xEditor log in a text editor. SeeThe Log .

• About xRevise opens a pop-up with the current xRevise.dll version. This information can beuseful when troubleshooting your xRevise installation.

Finding Existing ContentContent that you, or other xRevise users, have created for other work items can be reused. Use theFind utility to locate any combination of text, content item descriptions, or content attributes. Clickthe Search button to open the Content Search dialog box. Configure your search statement, then clickSearch. Microsoft Word’s Find and Replace feature is also available, but is significantly modified foruse with xEditor. See Microsoft Word Find and Replace.

xEditor’s Find Utility

Full Text Search must be enabled in the database if you want to search using the In Content option.Refer to the xPression Installation Guide for more information on enabling Full Text Search. Word’sSearch feature is available for searching for content in the current document without Full Text Searchbeing enabled.

Note: To enable searches on Revision Units, you must uncomment "AddUsageDataForReviseRUs=true" in revise.properties. For more information, see revise.properties in the xPression ServerAdministration Guide.

The Content Search dialog box consists of three sections with the indicated options.

34


For?• In Name

Type the name of the Revision Unit in this field.

• In Content

Type all, or a portion, of the search string. Full Text Search must be enabled to use this feature.Refer to the xPression Installation Guide for instructions on enabling Full Text Search.

How?• Match

Choose whether you want to return any item that contains Any word or phrase in For?, or Exactword or phrase in For?.

• In

By default, both standard and custom content for all versions is included in the search. You canlimit the potential size of the search results by choosing an option other than the default.— All Content returns content regardless of origin or revision number.

— Standard Content only returns content created in xDesign with revision number of 0. Doesnot return Revision Units.

— Standard Content - Latest Version only searches xDesign content for the most recent version(highest version number). Does not return Revision Units.

— Revision Unit (revised) returns any standard or custom content, and Revision Units with arevision number of 0.

With Attributes

• Jurisdiction

Choose the desired jurisdiction(s) or click All to choose all jurisdictions.

• Language

Select the language attribute from the list.

• Customer Defined Attribute

Specify the value for any customer defined attributes. Since these attributes are created inxAdmin, specific usage and valid values depend upon how these custom attributes are designed.

Click Search when you are ready to start the search. Search results display in a window below theTOC. Search results are sorted by last modified date, from latest to earliest. Double-click the item fora detailed view. Properties are displayed below the item.

You can drag content from the Search Result window to the TOC and drop it to the desired location.The content item will become a new Revision Unit. When you drag an item into the document youwill be prompted to rename it and choose attributes. Duplicate names are not allowed.

The Search Results toolbar provides these functions:

If the searched item exists in multiple documents each document is listed in the Owner Documentsection of the Search Results. In addition to the customer key, which would identify the work itemwhere the content is used, the Owner Document section shows the following for each work item:

35


Status, Current State, Last Modified time stamp, and whether it is in use. This information is forthe document, not the specific RU.• Preview Search Result

Opens a document viewer and shows the selected search item.

• Insert to Cursor

Inserts the selected content item into the document at the current cursor location.

The xEditor Find utility is limited to 101 return items. In addition, databases have the ability toexclude certain common words. SQL and Oracle provide similar support to exclude noise. SeeWords Excluded from SQL Full Text Search for a complete list of excluded words for SQL. DB2 doesnot support stop word processing. See DB2 Text Search and Net Search Extender Comparison forinformation on DB2 full text search noise filtering support.

Microsoft Word Find and Replace

Microsoft Word’s Find and Replace feature is also available for searching, with some modifications.The Find and Replace dialog box, as modified by xEditor, is identical for all supported MicrosoftWord versions. Find and Replace will not find variables, hidden text, or DCPI fields, such as subtotalsand indexes. Features that are available in xEditor have the same functionality as provided inMicrosoft Word. Find and Replace is accessed in the same manner as in Microsoft Word.

The following standard Search features are not available in xEditor.

• Format— Formatting information, such as font settings, paragraph settings, tab settings, and soforth are not supported for searching in xEditor.

• Special— Special characters, such as paragraph marks, tab characters, fields, and so forth are notsupported for searching in xEditor.

• Sounds Like— Searching for phonetically similar text is not supported in xEditor.

• All Word Forms— Searching for all word forms, such as verb tenses, is not supported in xEditor.

• Ignore Whitespace— This option, available on some versions of Microsoft Word, is not availablein xEditor, regardless of the Microsoft Word version used with xEditor.

• Ignore Punctuation— This option, available on some versions of Microsoft Word, is not availablein xEditor, regardless of the Microsoft Word version used with xEditor.

36

http://publib.boulder.ibm.com/infocenter/db2luw/v9r5/index.jsp?topic=/com.ibm.db2.luw.admin.ts.doc/doc/c0052757.html


• Match Prefix— This option, available on some versions of Microsoft Word, is not available inxEditor, regardless of the Microsoft Word version used with xEditor.

• Match Suffix— This option, available on some versions of Microsoft Word, is not available inxEditor, regardless of the Microsoft Word version used with xEditor.

The Replace function will not replace text in variables or hidden text. The following standard Replaceoptions are not available in xEditor.

• Format— Formatting information, such as font settings, paragraph settings, tab settings, and soforth are not supported for replace in xEditor.

• Special— Special characters, such as paragraph marks, tab characters, fields, and so forth arenot supported for replace in xEditor.

• Match Case— All searches are case-insensitive.

• Find whole words only— Find and Replace in xEditor cannot distinguish whole words.

• Use Wildcards—Wildcard searches are not supported in Find and Replace with xEditor.

• Search Up— Searches in xEditor always proceed top to bottom.

The only choices in theWhere list are All Content and Main Body Text only.

The only elements available on the Find and Replace dialog box are Find what, Where, and Replacewith (on the Replace tab only). The Goto tab is not available.

Adding New ContentYou can add new content to the document with the New RU function. Creating a new revision unit,rather than adding content to an existing one, can help in managing content that was added inthe transactional application.

To add a new RU:

1. In the TOC, select the element after which the new RU should appear. You will be able to movethe RU after it is created if necessary.

2. From the xEditor toolbar, click the New RU button. The Insert RU pane opens.

3. Define the Name, Jurisdiction, and Language for the RU. If you use the optional jurisdictionattribute, select at least one Jurisdiction from the list, or click All to select all jurisdictions.

Once the RU is created the Name, Jurisdiction, or Language cannot be changed.

4. Provide any customer defined attributes as required. Since customer defined attributes arespecific to your category, information on their correct usage must be provided by the xPressionadministrator or another resource familiar with details of the category.

5. Click Insert.

The name of a new revision unit in the TOC is includes an asterisk until saved.

New external content RUs cannot be added in xEditor.

37


Note: With an earlier version of xEditor, a section break is automatically added at the beginning ofthe document when you create a new revision unit. From 4.5 SP1, no section break is added at thebeginning of the document for a new revision unit.

Deleting and Undeleting Revision UnitsTo delete a revision, right-click the revision unit in the TOC and then click Delete/Undelete. DeletedRUs appear in the TOC with a deleted mark. You can toggle between showing and not showingdeleted sections by clicking Hide deleted TextPieces.

Revision units containing Universal Content cannot be moved, inserted or deleted. A message openswhen attempting to perform an action on an RU that contains Universal Content.

Note: The xPression administrator can configure xEditor so that deleted RUs are not shown.

To restore a deleted RU, right-click the RU and then click Delete/Undelete.

Editing in xEditorxEditor is the editor application used by xRevise and xResponse. Although it is the same editor inboth applications, this chapter is concerned with xEditor for xRevise. Some of the recommendationshere may not be applicable in xResponse. xEditor extends and modifies Microsoft Word. MostMicrosoft Word features and functions are supported.

Debugging an Edit Session

xRevise saves a cache of the changes to your document in the following location:

For Windows 7 and Windows Server 2008 — C:\Users\[user]\AppData\Roaming\EMC DocumentSciences

View

Use Word’s Print Layout view when editing in xEditor. This will give a closer representation of thefinal output. There are nuances within Word when copying styled paragraphs when in Normal view.

The PDF Preview is a representation of the document as it will be published, not as it appearsin Microsoft Word through xEditor.

Images in the Microsoft Word preview may not be the same size as in the final output.

Subdocument icons in the TOC are for informational purposes. If all subdocuments are removedfrom the document, a subdocument icon will remain in the TOC. This remaining icon will haveno impact on the output or the revision unit.

38


Table Rows

Clear formatting on newly added table rows. When a row is inserted in Word, the cell attributesof the row which was highlighted prior to the insert will be used in the newly added row. If thesource cell had hidden text for formatting a customer file replacement, the new cell will also havethe hidden text attribute on.

Table Wrapping

Table wrapping around text boxes is not supported.

When Designing a Document for xEditor

This section contains general guidelines for creating a document in xDesign that is intended for usewith xEditor for xRevise. Some of the guidelines here will not apply to documents intended for usewith xResponse or custom IDDK applications that use xEditor.

General Guidelines

When designing a document in xDesign for xRevise, or similar custom applications created in IDDKthat use xEditor, preview the xDesign assembly in Microsoft Word to see what the end users will seein xEditor. Then, preview it in the published output format (For example: PDF, PS, AFP, and so forth).

If leading or trailing spaces are needed on a Rule Variable, be sure to select to Format the replacementin the content item in xDesign. Uncheck all the options for formatting and the format option"KEEPSPACES" will be generated. If this is not done, then leading spaces may or may not besuppressed. Suppression will be determined by what precedes the rule variable.

Variables for xEditor can be global or local. Any variable from the primary table of the primary datasource are global variables. Any other variables, whether from secondary tables or from variablerules, are local variables for the xEditor user. The xEditor user can change the values of variables inmost cases. When a global variable value is changed, it is changed for each instance of the variablethroughout the document. When a local variable value is changed, it is changed for all instances ofthe variable within the selected RU. The xEditor user will not be able to change variable values insome cases, such as when protection is applied or the variable is a primary key for its table. Note thatthe xPression administrator can configure xEditor so that variables can always be changed, never bechanged, or to honor protection in the document.

Variables can be linked to OP variables. When the xEditor user changes these variables the OPvariable is updated accordingly. This is invisible to the xEditor user.

Variables can be used to populate Text and Drop-down List form fields. Variables used in form fieldsbehave more like static text in xEditor, so changes to a variable in a form field will not impact otherinstances of that variable elsewhere in the document or RU. There is no indication to the xEditor userthat a form field has been populated with a variable.

39


If you insert a CompuSet image though a variable, the image does not appear in xEditor. The imagevariable is only resolved during Compuset publishing.

xEditor does not allow carriage returns in any variable.

Section rules that define the beginning of a revision unit cannot be included inside a documentloop, unless the revision unit name includes a variable so that the RU name is unique in eachiteration of the loop.

xEditor supports multi-page TIFF, but all pages must be the same size.

When an image is referenced from a file path and the image name contains a space, xEditormay incorrectly process the file name. File names containing multiple consecutive spaces are notsupported. It is not recommended to use spaces in image names.

Universal Content

Page numbering preferences, Even/Odd page settings, and Inherit Layout settings are not honored inUniversal Content (UC) for documents used with xEditor. Universal Content is converted to an imagefor viewing and previewing, so when UC is viewed in xEditor or opened for “Preview as Word” itwill appear exactly as it would if the UC were opened directly, but output will be correct.

“Use Master Definition” is not respected in documents intended for use in xEditor. Elements inthe Universal Content will not be included in the master document table of contents in xEditordocuments.

Total Page number is not accurate for Universal Content when using Preview as Word, but is accuratewhen published or Previewed as PDF.

In work items containing Universal Content the Move, Insert, and Delete RU options will not beavailable. A message opens when attempting to perform any of these actions on a work item thatcontains Universal Content.

HTML Formatted Text from Customer Data

In some cases it is useful to use HTML formatting in customer data and then apply that formattedtext to the document with a variable rule in xDesign. However, the text introduced into the documentin this fashion need not be handled as variable content in xEditor, and in many cases cannot behandled as variable content effectively. There are specific requirements for the document designerwhen introducing variable content in this way. Refer to the xDesign User Guide and the xDesign Styleand Formatting Guide for detailed information on designing documents.

Moving Revision Units

Revision units can be moved in the TOC by dragging to the desired location, or deleted as required.Moved RUs are marked with an asterisk to indicate a change, even if the only change was to movethe RU.

40


To ensure proper RU performance certain factors should be considered when creating a documentwith subdocuments, in particular if it is intended that the document should include subdocumentsbeing used as RUs that are intended to be moveable in xEditor. Revision units should be definedwithin the subdocument rather than defining the subdocument as an RU in the master document.RUs may be system generated otherwise, and this may cause problems when trying to move theseRUs. Any required section breaks must be inside the subdocument to maintain integrity of thesubdocument.

Revision units containing Universal Content cannot be moved.

If header and footer design is to be maintained throughout a document that includes multiple revisionunits, and these RUs are independent of one another, then the headers and footers must be definedwithin each RU. To keep headers and footers blank use a non-printing character, such as an En Space.

If the RU should start with an even or odd page breaking section break, the section break should be atthe start of the subdocument rather than the master document.

Subdocuments intended to be moveable should have the same RU name as the subdocument name.

Ensure that the first subdocument includes a Section Break Continuous at the top of the firstcontent item. This will ensure that, if this subdocument is moved, it will not inherit formattingfrom a preceding RU.

Hidden Text and Page Layouts

When you click Show/Hide in xRevise, Word will repaginate the document. If there is a significantamount of hidden text above the cursor position, a different text location in the document willprobably be displayed. The physical page location will remain the same but the text location willbe different (for example, if on page 7 before the Show/Hide is selected, you will still be on page 7after selecting Show/Hide).

Fonts

xEditor obtains fonts from the xPression server. Ensure that any fonts needed by xRevise usersare installed on the xPression server.

Special Characters

Certain characters have special properties when used in form fields and so cannot be used directly.Instead they must be represented in customer data using symbolic entities:• < (Less Than) - <

• > (Greater Than) - >

• “ (Double Quotes) - ""

• ’ (Single Quotes) - "

41


• & (Ampersand) - &

• • (Carriage Return) - &#13;

For example, to use the Less Than symbol (<) in form fields make an element, custdata.lessthan forexample, in the customer data equal to <. Then, place the value as a variable in the form fieldby typing {custdata.lessthan} in the form field default content. This will appear as “<” wherever thevariable “{custdata.lessthan}” appears.

Form Fields

Variables are supported in Text and Drop-down list form fields. Variables cannot be used to set thestate of a Check Box form field. The xEditor user cannot add form fields to the document, so therequirements for using them in form fields are outside the scope of this class. Any variables that thedocument designer includes in form fields are dynamic and the value will change as the referencechanges. The xEditor user can change values in the form field, but if the value of a variable is changedthen it becomes static text and is no longer updated if the value of the variable changes. Variableformatting is not supported in form fields. Variables in form fields appear in black rather than red asis the case with variables elsewhere in the document.

Variables and static text in form fields can be combined in any conceivable permutation. For example:• {Variable}

• Static Text

• Static Text {Variable}

• {Variable} Static Text

• {Variable} Static Text {Variable}

• Static Text {Variable} Static Text{Variable}…

• {Variable}{Variable}…

42


When published as Fillable PDF output form fields are published as the appropriate type of fieldwith the value selected or specified by the xRevise user presented as the default. When publishedas any other output format form fields are converted to static text when published. Form fields arepresented as static text in PDF preview.

Note: Fillable PDF documents enable the user to change the values in the form fields, but AdobeReader does not support saving PDFs with the changed field values. The changed document can beprinted with the changed values. Adobe Acrobat Professional supports saving the PDF file with thechanged values.

Tables

The font size in tables that are located in optional content may not be correct in xEditor with MicrosoftWord 2007 or 2010. This condition can be corrected by applying a custom table style to the table.Although the problem is seen in xEditor, it must be repaired in xDesign.

To correct a font size problem by applying a custom table style:

1. In xDesign, create a new version of the content item with the font size problem and open itfor editing.

2. Select (highlight) the entire table.

3. In the Table Styles group of the Design ribbon, click theMore arrow located immediately tothe right of the table style graphics.

4. Click New Table Style. The Create New Style from Formatting dialog box opens.

5. Provide a name for the new style in the Name field.

6. Ensure thatWhole table is selected from the Apply formatting to list.

7. Select the desired font size from the font size list.

8. Ensure that New documents based on this template is selected.

9. Click OK.

10. With the entire table still selected click theMore button in the Table Styles group of the Designribbon.

11. Locate the Custom table styles. The table style created in steps 4 through 9 will be present inthis group. If other custom table styles have been created, you can identify the one that youcreated by hovering the cursor over the style until the tooltip with the style name displays.Click the newly-created style.

12. Save, submit, approve, generate XML for, and update the document version.

Document Protection

Documents with form fields must use Filling In Forms protection. Form fields are not compatiblewith Read Only protection. Read Only protection applies to the entire document, but Filling In Forms

43


protection applies to individual sections. So a document with Filling In Forms protection may includesections that are not protected as long as those sections do not contain a form field.

xRevise documents assemble as a single, large document. So if the document includes sub-documentsit is important that the sub-documents are not under Read Only protection if there are form fieldselsewhere in the document. It is possible for a sub-document with Read Only protection to causeRead Only protection to be applied to the rest of the document, even if no protection was appliedto the master document or other sub-documents in the work item. Form fields are supported inoptional content.

Avoiding Proxy Authentication Error

If the xEditor client machine has a proxy server enabled in the Internet Explorer settings, and thatproxy server requires user authentication, a ReviseWebServices.xEditorLogin failed error may occur.There are two methods to avoid this error.

Add Server to Proxy Server Exceptions

In most cases the authentication error can be avoided by adding the proxy server name to theExceptions list. To add the proxy server perform the following procedure.

1. From the Internet Explorer Tools menu, select Internet Options.

2. On the Connections tab click LAN Settings.

3. In the Proxy Server area click the Advanced button.

4. Type the name of the proxy server in the field in the Exceptions section.

5. Click OK as required to close all Internet Options dialog boxes that were opened during thisprocedure.

Modify machine.config on the Client Machine

In some cases the rights to add the proxy server as in the above procedure are not available. In thiscase it is recommended to modify the machine.config file on the client machine.

1. Open machine.config from C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\CONFIGin a text editor.

2. Add the following section to machine.config:<system.net><defaultProxy enabled="true" useDefaultCredentials="true">

44


<proxyproxyaddress="http://Proxy Server Name or IP:Proxy Server Port"bypassonlocal="false"/><bypasslist>

<add address="xPressionServer\.Company\.Com"/></bypasslist></defayltProxy></system.net>

Italicized items should be replaced with actual values.

3. Save machine.config and close the text editor.

Braces in Content

The use of braces (curly brackets, {}) in content is discouraged. xPression uses braces to identifyvariables and any other use may cause errors in the document.

Optional ContentA section can be designated as optional when it is created in xDesign. Optional sections are indicatedin the xRevise TOC by a checkbox. If you clear the checkbox, the section is not included when thedocument is published. You are never required to choose any optional content.

Revision units must contain some content other than optional content. If a revision unit contains onlyoptional content an error will occur when the xEditor user selects any optional content in that RU.

The document designer can mark content for Merge. When adjacent content is marked for mergethe items are combined into a single paragraph. Optional content that has been marked for merge isindicated along with Properties in the Merge Paragraphs section of the grid. Paragraphs must beadjacent to be merged. If one of the content items includes form fields then both must be protectedwith Filling In Forms protection; xEditor will not apply protection.

If optional content that includes any variables is selected, and the variables exist elsewhere in the RU,the variable instances will remain editable variables as long as all instances of the variable have thesame value throughout the RU. If the variable has different values within the RU, all instances will beconverted to static text. In this case the static text will be editable, but will no longer be treated as avariable. See Variables, page 47 for more information on working with variables in xEditor.

Note: Variables in work items that were created in earlier version of xPression and upgraded toxPression 4.0 or later will be converted to static text in most cases, regardless of value.

Refer to Administering the xPression Server for information on changing xRevise properties, and thexDesign User Guide for information on establishing Optional Content.

45


Table and Paragraph MergeParagraph and table merges across Revision Units are ignored when assembling for the editor, butnot when assembling for xPublish. If possible it is recommended that paragraphs and tables formerge occupy the same RU to avoid confusion when working in the editor.

Content SeparatorsAlthough a work item may look like a single, continuous document when you’re previewing orediting it, what you’re actually working with is a series of concatenated content items separated bya series of HTML tags. These protected content separators mark the “boundaries” of each contentitem. Every content separator consists of the content item information sandwiched between twocontinuous page breaks.

xPression doesn’t insert a separator before the first content item in a work item. Why? Because it’s thefirst content item in a document that decides the initial page layout. For example, if you start withtext having no particular margins, Word will choose a default for you.

Merged Paragraphs and Content Separators

The Paragraph Insert function in xDesign enables the document designer to indicate to xPressionthat a series of paragraphs, possibly from separate content items, should be merged into a singleparagraph at the time of assembly. xRevise treats merged content items as one object. Only the firstof a set of merged content items will have a separation marker. If you make a change anywhere inthe merged text, xRevise replaces the first content item, and marks all subsequent merged contentitems as deleted in the table of contents.

Subdocument MergeWhen you create a work item, xPression automatically creates a revision unit and inserts a paragraphbreak when a subdocument is encountered. If the subdocument is a paragraph that is marked tobe merged with the paragraph preceding it, the paragraph merge is ignored either in xEditor orin the publishing output. If you want to merge paragraphs in this situation, set the value of theTreatSubdocAsAutomaticRevisionUnit property in revise.properties to false. When the value isset to false, xPression does not create a revision unit for a subdocument. However a revision unit isstill created for a subdocument that starts with a section, which is assigned a unique revision unitname. This property works for work item creation only, and has no impact on existing work items.Any changes of this property value will not take effect until you restart the server.

46


VariablesThe document designer can use variables to customize the document with customer information.When you create a new work item, xRevise retrieves values for the variables in the document. Thedocument designer can insert variables with the Insert Variable tool in xDesign, or by using a variablerule. When working with the document, the values are displayed and the variables are retained untildeleted. Instances of the same variable with different values in a given RU are converted to plain textwhen the document is assembled for xRevise.

The Variable Navigation buttons on the xEditor Task Pane toolbar enable you to move through allvariables in the document sequentially, either forward (top to bottom) or backward (bottom to top).

A “NULL variable” is an xDesign variable or an xPression Customer Data field that has no valueassigned. This is not the same as a variable with a value of “0”, or “ “ (space), or some other valuethat can be interpreted as “nothing”, but no value applied at all. Usually variables are initializedwith some value, but in some cases this is not desirable, so these variables will be null variables. Bydefault NULL variables are not displayed in the document, but they exist and may be displayed inthe variable name format as a placeholder in the document. Refer to the xAdmin User Guide fordetails on configuring xEditor to display NULL variables. NULL variables are not included in outputeven if they are displayed in the editor.

The xPression administrator can configure xEditor so that the TOC is disabled. The TOC mustbe enabled to work with variables in xEditor.

Variable Scope

Variables can be either fglobal or local. Global variables are drawn from the primary table of theprimary data source and local variables are either from secondary tables or variable rules. When thevalue of a global variable is changed in xEditor all instances of the variable throughout the documentare updated to reflect the change. When the value of a local variable is changed all instances of thevariable in the selected RU are updated to reflect the change. So, for example, the same local variablemay appear in any number of RUs, and may initially have the same value in each, but the value canbe changed in xEditor so that the value differs from one RU to another, but a global variable willalways have the same variable wherever it is used in the document.

Variables are displayed in the Variable section of the Task Pane arranged in groups. Variables fromvariable rules appear in the first group, variables from the primary table (global variables) next,and any variables from secondary tables (local variables) after the global variables. Only relevantvariables are shown in the Task Pane, so when the document node is selected in the TOC, onlyglobal variables are shown. Only variables that are actually used in the document or selected RU aredisplayed; the entire table membership is not shown unless all variables in the table are used.

The Variable Navigator shows all instances of the variable and enables you to update the values ofindividual instances of local variables. See Variable Navigator for more details.

47


Selecting Variables

To maintain variable integrity it is necessary to modify Microsoft Word’s standard behavior whenmaking selections. This impact is most apparent in certain navigation keys and key combinationsand in triple-click behavior. The standard behavior for triple-click is to select the entire paragraph,but if the point where the triple-click is directed is a variable the result will be to select the variableonly. Triple-click in a paragraph that contains a variable will select the entire paragraph, includingthe variable.

Some keys and key combinations behave somewhat differently in xEditor when a variable isinvolved. Microsoft Word provides the ability to map key combinations to other actions. Mappingkey combinations to specific actions overrides the effects noted here. Some keys and combinationshave slightly different effects when a range is selected than when only the insertion point cursor is inuse. In some cases mapping key combinations is not supported.

The following key combinations should not be overridden with mapping.• SHIFT+BACKSPACE

The entire variable will be selected. This key combination should not be mapped to any otheraction.

• CTRL+SEMICOLON

Shifts focus from the edit window to the Variables grid entry for the selected variable. This keycombination should not be mapped to any other action.

The following keys and key combinations have the effect indicated with the cursor insertion pointonly. That is, no range of text is selected.• Left ArrowSHIFT+Left ArrowCTRL+Left Arrow

When a user enters a variable from the right by using the Left Arrow key, alone or in the notedcombinations, the entire range of the variable will be selected.

When a variable is currently selected SHIFT + Left Arrow will not deselect the variable.

• Right ArrowSHIFT+Right ArrowCTRL+Right Arrow

When a user enters a variable from the left by using the Right Arrow key, alone or in the notedcombinations, the entire range of the variable will be selected.

When a variable is currently selected SHIFT + Right Arrow will not deselect the variable.

• Down ArrowCTRL+Down Arrow

When a user enters a variable from the top by using the Down Arrow key or CTRL+Down Arrowthe entire range of the variable will be selected.

• Up ArrowCTRL+Up Arrow

When a user enters a variable from the bottom by using the Up Arrow key or CTRL+Up Arrowthe entire range of the variable will be selected.

48


• SHIFT+Down Arrow

When a user enters a variable from the top by using the SHIFT+Down Arrow key the entire rangeof the variable will be selected and will also select from the start position.

• SHIFT+Up Arrow

When a user enters a variable from the bottom by using the SHIFT+Up Arrow key the entire rangeof the variable will be selected and will also select from the end position.

• CTRL+SHIFT+Left Arrow

When a user enters a variable from the right by using the CTRL+SHIFT+Left Arrow key theselected range will start at the original position and include the entire variable plus any contentpreceding the variable until a space character is encountered.

• CTRL+SHIFT+Right Arrow

When a user enters a variable from the left by using the CTRL+SHIFT+Right Arrow key theselected range will start at the original position and include the entire variable plus any contentfollowing the variable until a space character is encountered.

• CTRL+SHIFT+Down Arrow

When a user enters a variable from the top by using the CTRL+SHIFT+Down Arrow key theselected range will start at the original position and include the entire variable.

• CTRL+SHIFT+Up Arrow

When a user enters a variable from the bottom by using the CTRL+SHIFT+Up Arrow key theselected range will start at the original position and include the entire variable.

• Page UpCTRL+Page Up

When the selection insertion point lands in a variable the entire variable will be selected.

• Page DownCTRL+Page Down

When the selection insertion point lands in a variable the entire variable will be selected

• SHIFT+Page Up

When the selection insertion point lands in a variable the entire variable will be selected inaddition to other standard Word selection

• SHIFT+Page Down


• BACKSPACE

The entire variable will be selected.

• CTRL+BACKSPACE

The entire variable will be deleted and any content preceding the variable until a space isencountered.

• CTRL+SHIFT+BACKSPACE

49


No effect.

• DELETE

The entire variable will be selected

• CTRL+DELETE

The entire variable will be deleted

• CTRL+SHIFT+DELETE

No effect.

The following keys and combinations have the effect indicated when a range of text is selected.• Left ArrowCTRL+Left Arrow

When a user enters a variable from the right by using the Left Arrow key, alone or in the notedcombinations, the entire range of the variable will be selected.

• Right ArrowCTRL+Right Arrow

When a user enters a variable from the left by using the Right Arrow key, alone or in the notedcombinations, the entire range of the variable will be selected.

• Down ArrowCTRL+Down Arrow

When a user enters a variable from the top by using the Down Arrow key or CTRL+Down Arrowthe entire range of the variable will be selected.

• Up ArrowCTRL+Up Arrow

When a user enters a variable from the bottom by using the Up Arrow key or CTRL+Up Arrowthe entire range of the variable will be selected.

• SHIFT+Left Arrow

When a user enters a variable from the right by using the SHIFT+Left Arrow key the entire rangeof the variable will be selected in addition to the existing selection.

• SHIFT+Right Arrow

When a user enters a variable from the left by using the SHIFT+Right Arrow key the entire rangeof the variable will be selected in addition to the existing selection

• SHIFT+Down Arrow

When a user enters a variable from the top by using the SHIFT+Down Arrow key the entire rangeof the variable will be selected and will also select from the start position.

• SHIFT+Up Arrow

When a user enters a variable from the bottom by using the SHIFT+Up Arrow key the entire rangeof the variable will be selected and will also select from the end position.

• CTRL+SHIFT+Left Arrow

50


When a user enters a variable from the right by using the CTRL+SHIFT+Left Arrow key theselected range will start at the original position and include the entire variable plus any contentpreceding the variable until a space character is encountered.

• CTRL+SHIFT+Right Arrow

When a user enters a variable from the left by using the CTRL+SHIFT+Right Arrow key theselected range will start at the original position and include the entire variable plus any contentfollowing the variable until a space character is encountered.

• CTRL+SHIFT+Down Arrow

When a user enters a variable from the top by using the CTRL+SHIFT+Down Arrow key theselected range will start at the original position and include the entire variable.

• CTRL+SHIFT+Up Arrow

When a user enters a variable from the bottom by using the CTRL+SHIFT+Up Arrow key theselected range will start at the original position and include the entire variable.

• Page UpCTRL+Page Up

When the Selection IP lands in a variable the entire variable will be selected and the formerselection will be collapsed.

• Page DownCTRL+Page Down

When the Selection IP lands in a variable the entire variable will be selected and the formerselection will be collapsed.

• SHIFT+Page Up


• SHIFT+Page Down


• BACKSPACE

The entire selection range will be deleted.

• CTRL+BACKSPACE

Collapses the selection range to the start and then the entire variable will be deleted and anycontent preceding the variable until a space is encountered.

• CTRL+SHIFT+BACKSPACE

No effect.

• DELETE

The entire variable will be deleted.

• CTRL+DELETE

51


Collapses the selection range to the start and then the entire variable will be deleted

• CTRL+SHIFT+DELETE

No effect.

Variable Color

Variables can be displayed either in standard text color or in a special color, such as red or tan. You canapply a special color to variables to distinguish them from ordinary text using the variable coloringfeature. However, for documents containing many variables, turning on the variable coloring mightaffect the loading performance. When you open a work item, you can turn on or turn off the variablecoloring by clicking the Turning on or off variable coloring button in xEditor. For a new work item,whether the variable coloring is turned on and in which color is determined by the default settingsconfigured in xAdmin. For a work item that was previous opened, whether the variable coloring isturned on is determined by the toggle state of the Turning on or off variable coloring button.

You also can define a paragraph style to apply colors on variables, which does not affect the loadingperformance.

Editing Variables

Variable values can be changed, and variable instances can be deleted, unless the variable is protectedor the primary key for the table. See Protection and Variables for more information on how protectionaffects editing variables. Variable instances can be deleted as any other content; select the variableinstance and press BACKSPACE or DELETE for example. It is not possible to delete part of a variable,but the same effect can be achieved by editing the variable value.

Note: When a variable instance is deleted it cannot be restored after the document has been saved.However, it will be included in xRevise reports along with its entire history, including when it wasdeleted and by whom. See the xRevise User Guide for more information on the xRevise reportingfeature.

Only one variable instance can be selected at a time, except when selecting a range of text, which caninclude multiple variables. In any case, only the entire variable instance can be selected. Variableinstances can be placed directly next to one another. It is possible to insert text between adjacentvariables without impacting either of the variables.

Note: Since selecting the entire variable is forced, selecting surrounding characters can be difficultunder certain circumstances. If the variable contains a space and there is a character to the immediateright of the variable, and you try to select the character to the right of the variable with a mouse actionmoving from right to left, the variable will also be selected. It is possible to select the character byplacing the cursor between the variable and the following character and using a mouse action fromleft to right, but this can be difficult. To select the consecutive character to the right of a variable it isrecommended to select the variable, press RIGHT ARROW and then press SHIFT+Right Arrow.

Variable values cannot be changed in the same way as other content. All changes to variable values,except date variables, are made in the Variable grid section of the Task Pane. Date variables arechanged using the Date Picker. To begin editing a variable other than a date variable, double-click thevariable or select the variable and press CTRL+SEMICOLON. The cursor is moved to the variable’s

52


edit field in the Task Pane where the desired changes can be made as required. When complete, pressENTER or click anywhere in the edit window and the cursor is returned to the document. To exit theVariable grid and abandon any changes, press ESC. If a variable is selected without choosing to editthe variable, any typing is added as plain text just prior to the variable instance in the edit window.

Note: If a variable is selected double-clicking will not behave as expected. Normally, whenediting in the body of a document, double-clicking in the header or footer will switch to edit theheader/footer. But if a variable is selected while editing the body of the document, double-clicking inthe header or footer will activate variable editing in the grid. Also, when editing in the header/footer,double-clicking outside the header or footer will switch to editing in the body of the document. Butif a variable is selected while editing in the header or footer, double-clicking outside the header orfooter will activate variable editing in the grid.

Most variables are changed by typing in the edit field of the Variables Grid, but date variables providea date picker. Date variables cannot be edited directly; the only way to edit a date variable is withthe Date Picker. Note that the date picker does not close automatically; click outside the edit area(in the TOC or menu areas for example) to close the date picker. See Variable Formats for moreinformation on how xEditor handles variable formats.

The Toggle Variable Editing button toggles Edit mode off and on in the Variables grid. When inVariable Edit mode the edit fields for the variables in the Task Pane are clear and the variable typeicons are bold, when not in edit mode the edit fields are shaded and the variable type icons aredimmed. Some variables, such as primary key variables for the table, cannot be edited at all and areindicated with a lock icon. The xPression administrator can configure xEditor so that variables cannever be edited, always be edited, or to honor the protection status established by the documentdesigner.

Note: To apply changes to a variable value press the ENTER key. Navigating away from the variable’sedit field with a mouse action will discard any changes to the variable. When navigating away from avariable with a mouse action the value indicated in the variable’s edit field will return to the originalvalue either when another RU is selected or another variable is selected for editing.

Changes must be saved to be applied. Unsaved changes to variable values are shown in bold in theTask Pane, and an asterisk at the document node in the TOC indicates unsaved changes are present.Note that unlike other content no asterisk appears for the RU containing the changed variable, even ifthe variable change is local to an RU. The current value applied to the variable is displayed, even ifnot saved, but other unsaved changes to variable values do not appear in the revision history.

Variables can be used to populate Text and Drop-down List form fields. When variables in form fieldsare changed in xEditor they are converted to static text. Variable values that were used to populateform fields are edited directly in the form field rather than the variable grid. Changing these instancesdoes not change the value in the grid or in any other instances of the variable, but will be reflectedin the preview. Likewise, changes to the value of a variable used to populate form fields made inthe grid do not change the value in the form fields. So, if a variable is used to populate both a formfield and an instance outside of the form field, these values can initially be the same but changedindependently of one another. Note that variables in form fields are not displayed in red as is thecase with variables outside of form fields, and the fact that the same variable was used both insideand outside of a form field is not necessarily obvious in xEditor.

Date variables (See Variable Formats, page 54 for details on variable formats) can be modified eitherdirectly or with the Date Picker. Click the Date icon to open the Date Picker and select the desireddate from the calendar-formatted Date Picker. The Date Picker is a standard Microsoft user interface

53


device; simply select the desired date and it is applied to the selected variable. Direct changes to thedate are allowed in the Variables grid as well, but there are some restrictions:• The BACKSPACE key cannot be used to go back one character.

• Arrow keys move from element to element rather than character to character. For example, fromthe Day element to the Month element rather than the end of the day element to the middleas may be expected.

• Pressing ENTER or ESC while manually editing have no effect. Click outside the grid to applychanges and remove focus from the Variable grid.

Copy and Paste

Variables can be copied and pasted, either alone or along with surrounding text. However, whenpasted the variable is converted to static text and will not be updated if the variable value issubsequently changed.

Drag and Drop

Drag and drop cannot be used with variables or DCPI fields, such as subtotals or indexes. Drag anddrop is not allowed when the current selection contains a variable or DCPI field. Dropping data into avariable or DCPI field is not allowed.

Variable Formats

Each variable has a specific format. There are many variable formats available, such as string, date,integer, float, and so forth. The format for each variable is indicated in the Variable grid by an icon.Each variable format has certain limitations. String format, for example, is the least limited formatin that it can contain virtually any character. By contrast, date variables can contain only dates andnumeric variable types can contain only numeric values. xEditor strictly enforces variable formats, soit will not allow a variable to be changed in a manner not supported by the variable’s format. Forexample, placing letters of the alphabet into a numeric variable is not allowed. Some variable typeshave length limits and xEditor will not permit values that exceed the limit.

Certain variable types have formatting options that the document designer can define. For example,“12/31/2010” and “December 31, 2010” both refer to the same day and could be expressed in a datevariable. The document designer can use the same date variable throughout the document, but applydifferent date formats in different places. xEditor will honor the variety of formats and display thedate in the specified format for each instance. The document designer can also specify the number ofdecimal places for numeric variables, and this is honored as well. So if the xEditor changes a numericvalue to “99.09” and the document designer had limited that variable to a single decimal place,xEditor would display it as “99.1”.

The xEditor user cannot change the format of any variable. If the output needs to show some valuethat is not supported by the variable, the xEditor user has no choice but to delete the variable andreplace it with static text.

54


Note: xEditor generally imposes no restrictions on variable types and honors restrictions imposedby the database from which they are obtained, but carriage returns cannot be used in any variable,regardless of format.

Protection and Variables

The xPression administrator can configure xEditor to allow or not allow editing of variables. Thefollowing options are available in xEditor Configuration in xAdmin.• Auto-detect protected variables

Allows editing variables that are not otherwise protected. This setting is recommended for mostcases where document protection is to be used. When this setting is selected and the documentcontains a variable with instances in both protected and unprotected regions, the variable isconsidered protected throughout and cannot be edited.

• All variables are editable

Allows editing of any variable, even if that variable is in a region is protected from editing.

• No variables are editable

Does not allow editing any variable.

The variable editing option applies to all xEditor users for the specified application. So if xEditor isconfigured for xRevise to allow all variables to be edited, then all variables in all xRevise documentsin that xPression environment can be edited by any xEditor user, except primary key variables thatcan never be edited. However, in that same xPression environment, there can be a custom applicationcreated with the Interactive Document Development Kit (IDDK) where no variable editing is allowed,and users of that application would not be able to edit any variable in any document.

Variable Navigator

The Variable Navigator displays the history of changes to the selected variable and where the variableis used in the work item (global variables) or revision unit (local variables). Saved changes to variablerevisions are recorded in the revision history. Each change is assigned a version number, which isincremented with each saved change. The value used in a previous version can be restored from theVariable Navigator by selecting the desired value and clicking Set. This does not revert to the selectedversion. Rather, it creates a new version with a new version number that is a copy of the selectedversion. In no case does the actual value in the data source change. You can also apply changes tothe selected variable, subject to the same limitations as apply to making changes in the Variablesgrid. Variable scope is clearly indicated in the Variable Navigator. If the variable is global, then anychanges made are applied to all instances of the variable. If the variable is local then instances ofthe variable can be selected can be selected so that changes are applied to selected instances only.As with applying a historic version, clicking Set applies the new value. In any case clicking Canceldiscards any changes and closes the Variable Navigator, and Reset discards changes without closingthe Variable Navigator.

55


NULL Variables

A “NULL variable” is an xDesign variable or an xPression Customer Data field that has no valueassigned. This is not the same as a variable with a value of “0”, or “ “ (space), or some other value thatcan be interpreted as “nothing”, but no value applied at all. Usually variables are initialized withsome value, but in some cases this is not desirable, so these variables will be null variables.

For example, data that should be manually entered for each new version of a work item can have aNULL value, and so will be readily identified in xEditor by their placeholders in the document and inthe Information panel. They can be modified in the Information panel as any other variable. Theycannot be modified in the main text. If a value is applied, it is immediately updated in the editwindow. If the changed value is deleted, the placeholder is restored.

Values can also be applied to NULL variables with an external application when the work item iscreated, in which case the xRevise user may not be aware that the value was applied when thework item was created.

By default NULL variables are not displayed in the document, but they exist and may be displayed inthe variable name format as a placeholder in the document. To make null variables visible, select theShow NULL variables in Word on the Variables tab of the xRevise Configuration page in xAdmin.NULL variables are not included in output even if they are displayed in the editor.

Note: If the work item uses Filling in Forms protection and contains form fields, the NULL variablefeature is not available and the xAdmin setting is ignored. In these documents, NULL variables willnot be accessible through the xEditor interface.

Subtotals, Index Headings, and Table Headingsand FootersThe document designer can use xPublish commands to create table headings and footers and indexheadings. These elements are not automatically protected in xEditor, but can be protected usingsupported Word protection features. Note that Filling In Forms protection is required if the documentincludes form fields and that Read Only protection is not compatible with Filling In Forms protection.

The document designer can use a variety of functions to provide subtotals in the document. The valueof subtotals, table headings and footers, and indexes are resolved when the document is published.Therefore they are shown as placeholders in xEditor. They cannot be modified in xEditor, but canbe deleted.

Variables in Optional ContentIf an optional content is selected that includes any variables, and the variables exist elsewhere in theRU, the variable instances will remain editable variables as long as all instances of the variable havethe same value throughout the RU. If the variable has different values within the RU, all instanceswill be converted to static text. In this case the static text will be editable, but will no longer be treatedas a variable. See Optional Content, page 45 for more information on working with optional content.

56


Track ChangesxEditor uses the Microsoft Word Track Changes feature. Changes made to documents in xEditor willappear red and underlined by default. To stop showing changes in the edit window, select the Finaldisplay option, rather than the default Final Showing Markup option. The Accept and Reject optionsare not available for Track Changes in xEditor.

Microsoft Word Features and FunctionsxEditor supports most Microsoft Word features and functions. Some functions are not supportedbecause xEditor provides a similar function for use within the xPression environment. For example,Word’s New function is not supported because work items for xRevise must be created in xDesign;they cannot originate in xRevise. Microsoft Word’s selection logic has been modified to maintainvariable integrity. See Selecting Variables.

Some Microsoft Word functions are not supported by xEditor. In some cases, your administrator canremove the function from xEditor, but some unsupported functions cannot be removed. Additionally,xEditor alters the standard behavior of some functions. For a complete list of unsupported andaltered functions, see Microsoft Word Features Altered by xEditor, page 57 and UnsupportedMicrosoft Word Functions, page 58.

Review the following topics for information about how xEditor interacts with Microsoft Word.• Microsoft Word Features Altered by xEditor, page 57

• Unsupported Microsoft Word Functions, page 58

• Editing Actions in xEditor, page 59

• Microsoft Word Styles, page 59

• Content Controls, page 59

Microsoft Word Features Altered by xEditor

The following Word features work differently in xEditor.• Created On

The Created On option for Insert Auto Text does not insert the actual date the document wascreated. It always inserts “Created on 6/19/2007 10:14:00 AM.” It is recommended that usersavoid using this option.

• CTRL+A

The CTRL+A hotkey combination selects the entire document in Word. CTRL+A behavesdifferently in xEditor, depending on whether the document includes optional content or not. If thedocument does not include any optional content, then the entire RU is selected. If the documentincludes optional content, then the text of the current node is selected.

57


• Protection

xEditor supports Read Only and Forms Fill-In protection types with some restrictions. SeeProtection.

• Drag and Drop

Drag and drop is not allowed if the current selection includes a variable or a DCPI field. xEditorwill not permit data to be dropped into a variable or DCPI field.

The following Word functions are overridden or modified by custom xEditor functions.


File SaveSave As Saves work item to the xPression database rather than thefile system

Edit FindReplace

Go To

The Find, Replace, and Go To functions in Word are modifiedsignificantly from the standard implementation. See FindingExisting Content.

Tools Spelling andGrammar

Spelling and Grammar is available, but the functionshave been modified to accommodate special needs andcircumstances introduced to the document by xEditor. Thedifferences are not readily apparent to the user.

Tools Compare Merge xEditor allows comparison and merge with historical copiesof the current document, or Word documents from the filesystem.


Unsupported Microsoft Word Functions

The following Word functions are not supported and cannot be used with xEditor.• File

New, Send To , Version, Properties

• View

Document Map, Thumbnails

• Insert

Diagram, Picture, Object

• Format

Theme, Text Direction, Auto Shape, Auto Format

• Tools

Shared Workspace, Track Changes, Mail Merge, Templates and Add-Ins

Note that Track Changes is used by the application. Unlike other items in this list, it cannot beturned off.

58


• Window

Compare Side by Side with

• Task Pane

Mail Merge, Protect Document, XML Structure

The following functions are not supported by xEditor, but cannot be suppressed in the interface.• Create or Modify Style

xEditor does not support creating new styles. When xEditor detects a new style, the style isdeleted and a message is displayed. xEditor does not support modifying styles. Users should notmodify styles because satisfactory results cannot be guaranteed.

• New Window

Word does not allow this option while running with xEditor because an XML expansion pack isattached. This limitation is imposed by Word.

Editing Actions in xEditor

Access to headers and footers and to the spell check and grammar check features are accessed directlythrough the Microsoft Word interface. Headers and footers are accessed either by double-clicking inthe header or footer or from the Header or Footer tools on the Insert ribbon.

Note: When a variable is selected double-clicking will not transition to or from headers and footers.This restriction is necessary to maintain variable integrity.

Spelling and Grammar are available from the Review ribbon in Microsoft Word 2007 or 2010. Bothversions of Word have options for automatic grammar and spelling, and these options are availablein xEditor.

Editing options for CompuSet content has not changed with xEditor. CompuSet code can be modifiedas before. CompuSet code can be shown or hidden using the Show/Hide hidden text button. Referto the CompuSet documentation for information on working directly with CompuSet. Exercisecaution when working with CompuSet code; documents with faulty CompuSet commands will mostlikely be rendered unusable.

Microsoft Word Styles

Paragraph styles should not be created in xRevise. They should be added to the xDesign templateand made available to xRevise through the xPression server. Character styles should not be usedin xRevise.

Content Controls

Microsoft Word 2007 and 2010 offers several options in the Controls group of the Developer ribbon.The only items in this group that are supported by xEditor are the Check Box, Text Form Field, and

59


Drop-Down Form Field options from the Legacy Tools list. Any of the other content controls willproduce unexpected results and should be avoided.

Form FieldsxPression supports Drop Down, Text, and Check Box form fields in documents. Form fields areadded to the document in xDesign; they cannot be added in xEditor, but they can be modified.Variables are supported in Drop Down and Text form fields. Variables, whether in form fields ornot, return the value of the variable when the document is assembled regardless of the protectedstate of the document. Variables cannot be used to establish the state of Check Boxes. In MicrosoftWord 2007 or 2010 the supported form fields must be selected from the Legacy Tools list in theControls section of the Developer ribbon.

Documents that include form fields and are intended for use with xResponse or xRevise must useFilling In Forms protection in any section that includes a form field. Since Read Only protection isapplied to the entire document if it is applied to any part of the document, documents with formfields cannot include any section with Read Only protection.

Form fields in documents that have been properly added and protected in xDesign are included inthe document when used to create a work item in xResponse or xRevise. If the default value of thevariable is changed in xEditor then the variable is converted to static text and will no longer behandled as a variable in Carry Forward and Search operations.

Note: Variables located within iterative structures, such as loops and table rules, are cached when thedocument is assembled and converted to static text, so the variables will not update after the workitem is created. Also, if a variable is repeated within a Revision Unit the value of the first instance ofthe variable is applied to all instances of the variable within that RU, even if the variable changeswhile the RU is being processed.

Documents with Word form fields can be used as work items in xEditor. When the xEditor useropens a work item with form field values are set to the default values, which are established by thedocument designer. The xEditor user can change the values of the fields normally. The TAB key canbe used to move through form fields in the document.

The xEditor user can change the value by selecting or typing the desired value, depending on the typeof form field. The selected or specified value is retained for future sessions. xEditor users cannotmodify any form field property except the value. xEditor will retain the variables as default valuesand drop list items only if the default value, that is the value established in xDesign, of the form fieldhas not been modified. If the default value is changed, then the default value and the drop list itemswill be converted to static text. This will be apparent in Carry Back, Carry Forward (if variables arechanged) and search and insert of customized revision units. In these cases changes in variable valueswill not be applied to the modified form fields.

Content that includes form fields can be searched and inserted into other sections as long as thetarget section is under Filling In Forms protection.

xRevise users cannot specify an output profile for previews, so the preview PDF will always showform fields as static text. xResponse users can choose to define an output profile for previews, but ifnone is specified the preview will show form fields as static text.

When the document is published as standard PDF the form field is converted to static text with theselected value. When published as Fill-in PDF the field is published as a form field with the value

60


selected or specified by the xEditor user presented as the default. If the value of a variable used in aform field is not set the field will publish as empty.

Variables in search results can be dragged into content as is the case with other search results.

It is possible to create the Form Field and then remove the bookmark from the Form Fields Optionsdialog box under Field Settings. The bookmark is required for Form Fields. Ensure that the field’sBookmark setting has some value, if the default is not desired.

Multiple paragraphs, sections of text separated by a carriage return, are supported in text formfields except for Fillable PDF output.

Variables and static text can be combined in any conceivable permutation in a form field. For example:• {Variable}

• Static Text

• Static Text {Variable}

• {Variable} Static Text

• {Variable} Static Text {Variable}

• Static Text {Variable} Static Text{Variable}……

• {Variable}{Variable}……

Form fields are established in xDesign. Form Fields cannot be added in xEditor, but limitations onform fields apply for any document used in xEditor.

ProtectionxEditor supports Read Only and Forms Filling in Forms protection types for work item contentfor both xRevise and xResponse, but only one type within a given document. Protection must beestablished in xDesign when the document is created.

Documents should be protected with only one form of protection. Mixing protection type within adocument is not recommended. If an xPublish master document includes an xPublish sub-documentwith Read Only protection, then the entire document is protected with Read Only protection.CompuSet sub-documents are processed in a way that makes any protection applied irrelevant to themaster document. Specific selections in documents with Read Only protection can be made availablefor editing. Documents using Filling In Forms protection can have sections that are not protected.

The reason mixed protection types are not recommended is because of the way protection is appliedwhen the document is merged. Only the first protection type encountered is honored, and ReadOnly protection applies to the document while Filling In Forms protection applies to individualsections. So if a Read Only section follows a Filling In Forms section, the Read Only section will notbe protected. However if a Filling In Forms section follows a Read Only section then the entiredocument is read-only except for any regions marked as available for editing in designated ReadOnly sections. There may be cases where this behavior can be exploited, but there is a high potentialfor unintended results, especially in complex documents, and so the use of mixed protection typeswithin a document is not recommended. The xEditor user cannot resolve problems that arise fromimproper use of protection, but should be aware that they may occur and should be referred tothe document designer for resolution.

61


There is no validation for protection; it is the document designer’s responsibility to ensure that theproper protection is applied to the document.

In xRevise when an RU is added through the Search and Insert feature the current work itemprotection is extended to the inserted content:• If the work item content is protected with ’read-only’, the inserted revision unit content will alsobe protected with read-only protection. This means if there are no editable regions identified inthe inserted content, all the content will be protected from edit.

• If the work item content is protected with ’forms fill-in’ (Section) protection, the inserted revisionunit content will also be protected with ’forms fill-in’ protection, if there is a section in the insertedcontent marked as protected.

• If the work item content is not protected, the inserted revision unit content will also not beprotected - regardless of the protection state of the inserted content.

The xEditor user cannot apply protection to the work item content if it is not already protected.Turning protection off in xEditor is not supported.

Read Only ProtectionRead only protection enables you to apply protection to the entire document and to designate certainregions–from a single word to a series of paragraphs–as available for editing to any users. You candesignate multiple, non-continuous sections as available for editing.

To scroll through the editable regions of the document, click the Goto Next Editable Region on thexRevise tool bar. Also, the xEditor user can designate a key combination that will scroll throughthe editable regions when pressed.

xEditor Focus While LoadingUnder certain circumstances focus will shift from the current application to xEditor when workingwith certain non-xPression applications while loading a work item in xEditor. For example, if a userswitches to an e-mail application while loading a document in xEditor and composes an e-mailmessage, in some cases the focus will shift to xEditor and typing begin to be applied to the documentin xEditor instead of the e-mail application. This is a known issue related to a value in the registrybeing changed from its default to 0. The registry setting is changed when certain applications areloaded and xPression is not able to change the value back to the default. Because of this the problemcannot be solved by a code change in xEditor or any other xPression component.

To avoid this issue it is recommended that users avoid using any application that may impact thisregistry setting. In cases where this cannot be avoided, it is possible to manually change the registrysetting.

Caution: Changes to the registry can result in unexpected results and can be difficult totroubleshoot, so changing registry settings should be attempted by qualified personnel only.Always make a backup before making changes to the registry.

62


This procedure involves making a change to the registry. Since this should be attempted by qualifiedpersonnel only, the minimum information is provided rather than complete information on workingwith the registry.

To prevent switching focus to xEditor:

1. In the Windows registry, locate and make a backup of the HKEY_CURRENT_USER\CONTROLPANEL\DESKTOP\ForegroundLockTimeout entry.

2. Change the value of HKEY_CURRENT_USER\CONTROL PANEL\DESKTOP\ForegroundLockTimeout from 0 to 30d40.

3. Save and close the registry editor.

Tab LeadersThe document designer can choose to use tab leaders in indexes to provide a uniform appearance.However, because of the method used to prepare the document for use with xEditor, tab leadersettings cannot be passed. So it will be necessary to reset the index and apply any desired tab leaderfor any document using tab leaders in an index.

63


64

Chapter 5xEditor Web Services

The xEditor Web Services serve as an extension of IQuickDoc for solution-specific capabilities. TheseWeb Services methods add considerable power to how you assemble, edit/manipulate, publish,and return data about published documents. They allow external systems to query, and in somecases, update information in xPression without accessing the xPression database. The Web Servicesmethods are more powerful, and therefore more complex, using complex types and requiring moresophistication in coding.

•

•

•• The IDocumentItem Web Service, page 65

• Calling the xEditor StartUp Application, page 94

The IDocumentItem Web ServiceThis web service provides methods that work with editable document work items. TheIDocumentItem web service WSDL will be found at:http://<server>:<port>/xDevKit/services/DocumentItem?wsdl

This Web Service contains the following methods:• searchDocumentItem, page 66

• The createDocumentItem Method, page 68

• The getDocumentItemInfo Method, page 70

• The publishAndReturnDocumentItem Method, page 74

• The documentItemsAssignedToUser Method, page 75

• The reassignDocumentItemToUser Method, page 76

• The updatePrimaryVariables Method , page 77

• The copyDocumentItem Method, page 78

65

xEditor Web Services

• The addExternalContentByLink Method, page 79

• addExternalContentByStream, page 80

• The reorderExternalContent Method, page 82

• The addAnnotation Method, page 83

• The deleteExternalContent Method, page 84

• The createAuthenticationToken Method, page 84

• The complete DocumentItem Method, page 86

• The deleteDocumentItem Method, page 87

• The publishRevisionUnits Method, page 88

• The setCarryForwardDocumentItem Method, page 89

• The clearCarryForwardDocumentItem Method, page 90

• The updateRUVariables Method, page 91

• The submitDocumentItem Method, page 92

• The approveDocumentItem Method, page 92

• The rejectDocumentItem Method, page 93

searchDocumentItem

The searchDocumentItem method enables you to search for a work item based on criteria.

Return Value: A string array of work item IDs. If the method fails, it returns a SOAP Fault thatindicates the reason for the failure.

Syntax

String documentItemIDs = searchDocumentItem(requestContext, searchCriteriaXML)

Parameters

requestContext : String

An XML document that passes user credentials for authentication. It also passes the name of theapplication for which the user is authenticated. In xPression, users are given access rights to specificapplications because each application has a different set of access rights. By specifying the applicationname, you are requesting the access rights granted to the user for that specific application.

66


Please be aware that the application name you use must grant permissions that are appropriate foryour request. For this method, the following xPression applications are valid:• xPression Revise

• xPression DevKit

For more information, see .

searchCriteriaXML : String

An XML string representing the search criteria. The criteria can use the following elements:• SEARCHCRITERIA — The root element of the search criteria XML file. The isCompletedparameter can be set to true or false. If set to true, you are indicating that you want to search acompleted work item.

• SECTION— The section element serves the same function as parenthesis in a Boolean logic or aSQL query. The <PHASE> element is the only subelement allowed in a <SECTION>.

• PHASE — The phase element encapsulates each piece of criteria in the searchCriteria file.

• CATEGORY_NAME — Supply the name of the category you want to search.

• DOC_NAME — Supply the name of the document you want to search for.

• CURRENT_OWNER — Supply the user name of the document’s current owner.

• DOC_STATUS — Supply the document status.

• TIMESTAMP— Identifies the last modified time of the work item. The date format is configuredin the revise.properties file in the reviseDateFindFormat property.

• CUSTOMERKEY — Enables you to search the customer key for values. This element mustappear inside a PHASE element, and can contain any number of KEY_VALUE elements. EachKEY_VALUE element is implicitly joined by an OR operator. The following sample contains threeKEY_VALUE elements, which will return three sets of work items.

• ORDERBY — Enables you to sort the list of returned work items. Placing parameters in thiselement will order the returned values in ascending order. If TIMESTAMP is used in theORDERBY element, the work items are sorted in descending order.

Sample

<?xml version="1.0" encoding="UTF-8"?><SEARCHCRITERIA isCompleted="false"><SECTION><PHASE><CATEGORY_NAME><VALUE>xRevis*</VALUE>

</CATEGORY_NAME></PHASE><AND /><PHASE><CUSTOMER_KEYS>

<KEY_VALUE name="AUTOPAY_KEY" category=" xRevis_Automatic Payment">1</KEY_VALUE>

<KEY_VALUE name="AUTOPAY_KEY" category="External Content">1</KEY_VALUE>

<KEY_VALUE name="AUTOPAY_KEY" category="xEditor_UC">1</KEY_VALUE>

67


</CUSTOMER_KEYS></PHASE><AND /><PHASE><DOC_NAME><VALUE>*</VALUE>

</DOC_NAME></PHASE><OR /><PHASE>

<TIMESTAMP><VALUE>02-22-11</VALUE>

</TIMESTAMP></PHASE>

</SECTION><ORDERBY><VALUE>CATEGORY_NAME</VALUE><VALUE>TIMESTAMP</VALUE>

</ORDERBY></SEARCHCRITERIA>

The createDocumentItem Method

The createDocumentItem web service method enables you to create a document work item inxPression. A document work item is a version of an assembled document that can be revised beforepublishing. Examples of revision include:

• Selection of optional paragraphs

• Editing of the document

• Adding an annotation

• Updating the primary variables of the document

68


Document template assembly rules are always executed based on the original customer data usedto create the document work item. Changes made to the customer data after the work item iscreated will have no affect on the document execution rules. The changes are simply treated astext variable replacements.

The customer data that you input into this method will be applied to the default data sourcedefinition assigned to the category that contains your document. This method is only guaranteedto process one document record of data, so ensure that you only send one record of input data. Ifmultiple records are given as input, the method may try (and fail) to determine and use the firstrecord in the XML customer data.

Return Value: A String that uniquely identifies the newly-created document work item that wascreated within the application specified in the Request Context. If the method fails, it returns a SOAPFault that indicates the reason for the failure.

Syntax

String documentItemID = createDocumentItem(requestContext, documentName,customerData, assignToUserName)

Parameters






documentName : String

A string specifying the name of the document for which you want to create a work item. Thedocument must reside on the xPression Server.

customerData : String

The value for this parameter depends upon the type of data source assigned to the category thatcontains the document you want to publish. If your data source is an XML document, you mustprovide a single record of XML customer data. If your data source is a relational database, youmust provide keys for the relational database data source. You can provide the primary key forthe customer data using the following format:<Keys><Key name="keyName1">keyValue</Key><Key name="keyName2">keyValue</Key>

69


</Keys>

assignToUserName : String

The username of the user to whom you want to assign the document.

The getDocumentItemInfo Method

The getDocumentItemInfo method retrieves information about document items. The information isreturned as an XML document. The amount of data returned for some work items could be quitelarge, resulting in a decrease in performance. To help avoid the potential performance decrease,this method enables you to limit the amount of information returned through the infoToReturnparameter. You can return information about the following items by passing the specified term inthe infoToReturn parameter:• Annotation— For each annotation in the document, the method returns the annotation type, theuser who created the annotation, the timestamp, and the annotation note itself.

• ASL— A description of all objects in the document.

• Document— Basic information about the document, including the document item ID, thedocument name, the document category, the publishing type, and the customer key of the user forwhom the work item was assembled.

• External Content— A list of all external content in the document. For each piece of externalcontent, xPression this method reports the external content name and path, the total number ofpages, the date the external content was created, the external content type, the URL of the link tothe external content, and the location of the external content.

• General— Shows general information about he work item, including the user who is currentlyassigned to the work item (owner), the work item user who created the work item (user), thework item category, the customer key used to create the work item, the time and date of thelast modification to the work item, the ASL ID (which is used to retrieve information about thework item), the current status and state of the work item, the publisher type, and an indicationif the work item is locked.

• History— Shows the history of the work item, including when it was created, submitted,approved, and rejected. For each state, it reports the action, the user, the owner, the currentstate, and the date/time stamp.

• Optional Paragraphs— Lists all the optional paragraphs in the work item. It displays eachoptional paragraph group, the group type, and whether or not it is configured for handlingin batch. It also lists all the optional paragraphs in the optional paragraph group, listing thename, ID, an indication that the optional paragraph is shared or not, an indicator if the optionalparagraph is selected or not, and the version number.

• Revision Units— Identifies each revision unit in the document. It also shows the name of therevision unit, the revision number, the version, the date it was created, the RevisionUnit cachedata ID (CRC), the original ID, and an indicator if the revision unit is shared or not.

• Variables—Lists all variables used in the work item. It lists the variable name and the value of thevariable for the current customer key. The variables in the returned list are organized into Global,Primary, and Revision Unit specific variables. The following is an example of the returned XML:

<?xml version="1.0"?>

70


<Variables><PrimaryVariables><Variable name="ISDA.CALCULATIONAGENT" value="Party B"/><Variable name="ISDA.COUNTERPARTYNAME" value="Soros"/></PrimaryVariables><RUVariables name="Schedule Introduction" id="27601"><Variable name="PRINCIPAL.NAME" value="EMC"/></RUVariables><RUVariables name="Part 1 - Termination Provisions" id="27602"><Variable name="OPTIONSBANKRUPTCY.SPECIFIED" value="None Specified"/></RUVariables></Variables>

• Work in Progress Change History— Captures the history of changes in variables.

Return Value: This method returns an XML document containing the requested information. If themethod fails, it returns a SOAP Fault that indicates the reason for the failure. To see an exampleof a returned XML file, see Examples, page 72.

Syntax

String documentItemInfoXML = getDocumentItemInfo (requestContext,documentItemIDs, infoToReturn)

Parameters






documentItemIDs : String[]

An array of unique identifiers for document items.

infoToReturn : String[]

An optional parameter specifying a subset of the information to return. If this parameter is null or haszero strings then all information will be queried and returned in the XML document. You may giveany of these Strings as input into the method:• “Annotations”

• “ASL”

• “Document”

71


• “ExternalContent”

• “General”

• “History” — These items are stored under the <Audit> tag.

• “OptionalParagraphs”

• “RevisionUnits”

• “Variables”

• “WIPChangeHistory”

See the description of this method (The getDocumentItemInfo Method, page 70) for details aboutwhat information is returned for each string.

Examples

This section contains an example of the XML returned from this method.<DocumentItems><DocumentItem id="7311" name="Auto Policy"><Annotations><Annotation type="document"><Item user="tester" timestamp="2010-03-29T10:22:32"note="Passed verification."/>

</Annotation></Annotations><ASL BDTid="2202" name="Auto Policy" style1="8652" style2="8653"categoryName="Auto" customerKeys="1" publisherType="xPublish"><Section name="Sect1"/><CRObject name="Introduction" shared="false" version="1.00" originalID="-1"revision="0"crc="2531604323" objID="8803" createDate="2010-03-29"/>

</ASL><Document><Name>Auto Policy</Name><Category>Auto</Category><CustomerKey>1</CustomerKey><PublisherType>xPublish</PublisherType></Document><ExternalContents><ExternalContent id="3415"><Name>C:\xPression\CustomerData\Strat.pdf</Name><TotalPages>1</TotalPages><CreateDate>2010-01-26</CreateDate><Type>PDF</Type><Link>C:\xPression\CustomerData\Strat.pdf</Link><From>file</From></ExternalContent></ExternalContents><General><User>tester</User><Owner>tester</Owner><Category>StringsOfVariables</Category><CustomerKeys>1</CustomerKeys><Modified>2010-03-29T09:59:21</Modified><ASL_ID>8912</ASL_ID><Status>Pending</Status><State>Active</State><PublisherType>2</PublisherType>

72


<LockingState><Locked>False</Locked></LockingState></General><Audit><Action action="Checked in" user="tester" datetime="2010-03-29T09:59:22"/>Workflow submitter="tester" currentowner="tester" currentstate="Active"datetime="2010-03-29T10:03:46"/>

</Audit><OptionalParagraphs><OptionalParagraphGroup name="StringsofVariables_Multiple" selection="multi"handlingInBatch="none"><OptionalParagraph><Name>Word_Variable_Field/Name><Id>8643</Id><Shared>false</Shared><Selected>false</Selected><Version>1.00</Version></OptionalParagraph>/OptionalParagraphGroup></OptionalParagraphs><RevisionUnits><RevisionUnit id="8803"><Name>Introduction</Name><Revision>0</Revision><Version>1.00</Version><CreateDate>2010-03-29</CreateDate><CRC>2531604323</CRC><OriginalID>-1</OriginalID><Shared>false</Shared></RevisionUnit></RevisionUnits><Variables><Variable name="V_STR_2" value="CA"/><Variable name="V_STR_1" value="StringValue"/></Variables><WorkItemHistory name="StringsOfVariables_xPub" workItemId="7311"createDate="2010-03-29T09:59:21" serverVer="4.0"><GlobalVariables><Variable name="AUTOPAY.AUTOPAY_KEY" type="integer" currentVer="0"><Version ver="0"><Value>1</Value></Version></Variable></GlobalVariables><RevisionUnits><RevisionUnit id="8803" name="Introduction"><Variables><Definitions><Variable name="V_STR_2" type="string" currentVer="0"><Version ver="0"><Value>CA<Value></Version></Variable></Definitions></Variables></RevisionUnit></RevisionUnits></WorkItemHistory><DocumentItem><DocumentItems>

73


The publishAndReturnDocumentItem Method

The publishAndReturnDocumentItem web service method enables you to publish a documentwork item to an output profile. This method works identically to the QuickDoc web service methodpublishAndReturnDocument, except that the document generated comes from a document work iteminstead of customer data. In order to successfully return the document to your calling application, theoutput profile you specify must contain an output stream whose distribution definition is definedwith the “Return to Calling Application” option.

Return Value: This method returns at most one “Return to calling application” output stream if oneis identified in the output profile. If no output streams are defined with a distribution definitionmarked as “Return to Calling Application”, the method will return a zero length byte array whensuch documents are successfully published. If more than one output stream contains a distributiondefinition marked as “Return to Calling Application”, this method selects any one of the definedoutput profiles. You cannot control which output profile it selects. If the method fails, it returns aSOAP Fault that indicates the reason for the failure.

74


Syntax

Byte[] document = publishAndReturnDocumentItem(requestContext, documentItemID,outputProfileName)

Parameters






documentItemID : String

The unique identifier for the document item.

outputProfileName : String

A string specifying the name of an output profile valid for use for with the specified document. Theoutput profile must reside on the xPression Server.

The documentItemsAssignedToUser Method

The documentItemsAssignedToUser method returns a list of document item IDs for any documentitems assigned to a given user. You can return information about these document items through asubsequent Web Service call by using the document item IDs returned from this method as inputinto the documentItemInfo method.

Return Value: This method returns an array of Strings (one String per document item) containing thedocument item IDs of document items assigned to the user. If the method fails, it returns a SOAPFault that indicates the reason for the failure.

Syntax

String[] documentItemIDs = documentItemsAssignedToUser(requestContext, userName)

75


Parameters






userName : String

The username of the user for whom you want to return a list of assigned document items.

The reassignDocumentItemToUser Method

The reassignDocumentItemToUser method moves the document item from its currently assigneduser to the user name given as input. If the method fails, it returns a SOAP Fault that indicates thereason for the failure.

Return Value: This method returns a string message when the method successfully reassigns awork item.

Syntax

String successMessage = reassignDocumentItemToUser (requestContext,documentItemID, assignToUserName)

Parameters



76


The application name you use must grant permissions that are appropriate for your request. For thismethod, the following xPression applications are valid:• xPression Revise






The username to whom you want to assign the work item.

The updatePrimaryVariables Method

This method enables you to update the value of a variable in the primary table. This method cannotbe used to update the value of a primary key.

Return Value: This method returns a string message when the method successfully updates theprimary variables.

Syntax

String message = String updatePrimaryVariables(String requestContext,String documentItemID, String primaryVariableInfo) throws AxisFault;

Parameters






77




primaryVariableInfo : String

XML code that identifies the variable names and values. For example:<Variables><Variable name="AUTOPAY.FIRST_NAME" value="John"/><Variable name="AUTOPAY.LAST_NAME" value="Anderson"/></Variables>

OR<Variables><PrimaryVariables><Variable name="AUTOPAY.FIRST_NAME" value="John"/><Variable name="AUTOPAY.LAST_NAME" value="Anderson"/></PrimaryVariables></Variables>

The copyDocumentItem Method

The copyDocumentItem method makes a copy of a document work item and assigns it to thespecified user. The most common use of this method is to copy a completed document work itemfrom history to make a new editable document work item. The advantage of using this method is thatit enables you to reuse all the previous customizations of that work item.

Return Value: This method returns a string message that identifies the newly copied document workitem. If the method fails, it returns a SOAP Fault that indicates the reason for the failure.

Syntax

String newDocumentItemId = copyDocumentItem (requestContext, documentItemID,assignToUserName)

Parameters



78






The unique identifier for the document item that you want to copy.


The username to which you will assign the work item.

The addExternalContentByLink Method

This method enables you to add external content to your document as a Revision Unit. You definethe external content by supplying the path of the content on your file system, network location, orlocation in an ECM repository.

Return Value: This method returns a string identifying the Revision Unit ID of the external content.

Syntax

String RUID = addExternalContentByLink(String requestContext,String documentItemID, String ruName, String externalContentLink,String format, String position, String options) throws AxisFault;

Parameters








79


ruName : String

The name for the external content Revision Unit.

externalContentLink : String

The link to the location of the external content. You can supply a path to a location on the server, aURL, or an ECM path. The following three formats are supported: local file, Url and ecm. Examples:• Local Path Syntax

<drive>\<path>\<filename>

Local Path ExampleC:\xPression\UC\A40127.pdf

• URL Syntaxhttp://<machine name>/<path>/<filename>

URL Examplehttp://localhost/UC/A40127.pdf

• ECM Path Syntax (syntax is case sensitive)ecm::<ecmConfigName>?uri=/<path>/<filename>?version=<version>

ECM Path Exampleecm::DCTMServer?uri=/UC/A40127.pdf?version=CURRENT

format : String

The external content file format. Valid values include:• “.pdf”

• “word.doc”— not supported when using a URL link. Only supported for local path and ECM link.

• “.tif”

position : String

When you add external content to the document, you must specify the position in the documentwhere you want the external content to appear. You specify the position by identifying the RevisionUnit ID of the Revision Unit that should follow the external content. The external content will beplaced ahead of the Revision Unit you identify with this parameter. If you want to place the contentat the end of the document, supply a null value.

options : String

This parameter is unused at this time, but is included for future updates.

addExternalContentByStream

This method enables you to add external content to your document as a Revision Unit. This methodadds the byte array of the external content to the specified document item.

Return Value: This method returns a string identifying the revision unit ID of the external content.

80


Syntax

String RUID = addExternalContentByStream(String requestContext,String documentItemID, String ruName, String externalContent,String format, String position, String options) throws AxisFault;

Parameters








ruName : String

The name for the external content Revision Unit.

externalContentLink : String

Supply the byte array for the external content.

format : String

The external content file format. Valid values include:• “.pdf”

• “word.doc”— not supported when using a URL link. Only supported for local path and ECM link.

• “.tif”

position : String

When you add external content to the document, you must specify the position in the documentwhere you want the external content to appear. You specify the position by identifying the RevisionUnit ID of the Revision Unit that should follow the external content. The external content will beplaced ahead of the Revision Unit you identify with this parameter. If you want to place the contentat the end of the document, supply a null value.

options : String

This parameter is unused at this time, but is included for future updates.

81


The reorderExternalContent Method

Enables you to move an external content Revision Unit to a new position in the document.

Return Value: This method returns a status message indicating whether or not the external contentRevision Unit was reordered successfully.

Syntax

String message = reorderExternalContent(String requestContext,String documentItemID, String externalContentID, String targetPosition)throws AxisFault;

Parameters








externalContentID : String

The ID of the external content item that you want to reorder.

targetPosition : String

When you reorder external content in your document, you must specify the position in the documentwhere you want the external content to appear. You specify the position by identifying the RevisionUnit ID of the Revision Unit that should follow the external content. The external content will beplaced ahead of the Revision Unit you identify with this parameter. If you want to place the contentat the end of the document, supply a null value.

82


The addAnnotation Method

This method enables you to enables you to add comments to individual work items. Notes canbe Client Level type or Document Level type. Client Level notes attach to all documents with thesame document ID and the same first primary key, while Document Level notes attach to a specificwork item.

Syntax

String message = addAnnotation (String requestContext,String documentItemID, String annotationInfo) throws AxisFault;

Parameters








annotationInfo : String

The XML formatted string that contains the annotation content. The string should be formattedas in the following example:<Annotations><Annotation type="document"><Item note="annotation text"/><Item note="annotation text"/><Item note="annotation text"/>

</Annotation><Annotation type="client"><Item note="client">

</Annotation></Annotations>

83


The deleteExternalContent Method

This method enables you to delete a specified piece of external content.

Return Value: This method returns a status message indicating whether or not the external contentwas removed successfully.

Syntax

String message = deleteExternalContent (String requestContext,String documentItemID, String externalContentID) throws AxisFault;

Parameters








externalContentID : String

The ID of the external content that you want to delete.

The createAuthenticationToken Method

This method enables you to create a string authentication token that will be used to log on to thexEditor if the user credentials are valid.

Return Value: Returns a string authentication token. Upon failure, an AxisFault exception is thrown.

Syntax

String tokenID = createAuthenticationToken(String requestContext, long timeout)

84


throws AxisFault;

85


Parameters






timeout : String

The number of milliseconds that the token should be active.

The complete DocumentItem Method

The completeDocumentItem method changes the state of a document work item from a state where itcan be manipulated into a state where it is locked and can only be referenced for historical purposes.At that point, the document work item is considered “completed”. Should you need to make changesto the document work item, copy it to a new document work item through the copyDocumentItemweb service method.

Return Value: This method returns a string message when the method successfully completes thedocument work item. If the method fails, it returns a SOAP Fault that indicates the reason for thefailure.

Syntax

String successMessage = completeDocumentItem (requestContext, documentItemID)

Parameters



86






The unique identifier for the document item that you want to move to a “completed” state. Once thedocument work item has been completed, it can not be edited.

The deleteDocumentItem Method

The deleteDocumentItem method deletes the specified document work item and associated historyfrom the server.

Return Value: This message returns a string message when the method successfully deletes thedocument work item. If the method fails, it returns a SOAP Fault that indicates the reason for thefailure.

Syntax

String successMessage = deleteDocumentItem (requestContext, documentItemID)

Parameters







The unique identifier for the document item that you want to delete.

87


The publishRevisionUnits Method

The publishRevisionUnits method provides a means of selectively publishing portions of adocuments. For example, to present relevant portions for review to a specialist for review or topublish different portions of the document to different output channels.

Return Value: This method returns a byte array, containing the resulting document, or null if nodocument is returned. This depends on the Output Profile that is passed. If the profile contains astream with “Return to caller” distribution, then that stream is returned.

Syntax

byte[] resultDoc = publishRevisionUnits (requestContext, documentItemID,ruNames, addTitles, opName)

88


Parameters



If documentItemID refers to a work item, then the user must have write, approve, or admin rights. Ifit refers to a completed item, then the user must have read, write, approve, or admin rights.


The unique identifier for the document item whose partial content is being requested.

ruNames:String[]

A list of the revision unit names to publish. Note that RU names are required to be unique in adocument work item.

addTitles:String

Pass the string “true” to request titles. Titles are a small paragraph inserted by the method, containingthe RU name. This parameter is optional since document template designs differ; in some cases theRUs that have been published may be apparent from the content, but in other cases it may not beapparent.

opName:String

The name of an output profile defined to the server (with xAdmin). It must belong to the correctpublishing engine (xPublish or CompuSet) for the work item.

The setCarryForwardDocumentItem Method

This Web Service enables you to place a Work in Progress into Carry Forward mode.

Return Value: As success message is returned if the method completes successfully. If the methodfails, it returns a SOAP Fault that indicates the reason for the failure.

Syntax

String setCarryForwardDocumentItem (requestContext, documentItemID, CFCompareID)

89


Parameters


An XML document that passes user credentials for authentication. It also passes the name of theapplication for which the user is authenticated. In xPression, users are given access rights to specificapplications because each application has a different set of access rights. By specifying the applicationname, you are requesting the access rights granted to the user for that specific application. The useryou provide must have Write or Admin permission for the category/application combination.




The unique identifier for the document item that you want to place into Carry Forward mode.

CFCompareID : String

The work item ID for the document that you want to use for comparison in Carry Forward mode.

The clearCarryForwardDocumentItem Method

This Web Service enables you to stop Carry Forward mode for a Work in Progress.

Return Value: As success message is returned if the method completes successfully. If the methodfails, it returns a SOAP Fault that indicates the reason for the failure.

Syntax

String clearCarryForwardDocumentItem (requestContext, documentItemID)

Parameters





90


documentItemID : String[]

The unique identifier for the document item that you want to remove from Carry Forward mode.

The updateRUVariables Method

This Web Service enables you to update the value of a Revision Unit specific variable.

Return Value: This method returns a string message when the method successfully updates theprimary variables. If the method fails, it returns a SOAP Fault that indicates the reason for the failure.

Syntax

updateRUVariables(requestContext, documentItemID, ruVariableInfo)

Parameters







ruVariableInfo : String

XML code that identifies the variable names and values that you want to update. For example:<Variables><RUVariables><Variable name="AUTOPAY.FIRST_NAME" value="John"/><Variable name="AUTOPAY.LAST_NAME" value="Anderson"/></RUVariables></Variables>

91


The submitDocumentItem Method

This Web Service enables you to submit document items to the next stage in your workflow.

Return Value: If successful, this webservice returns “Document item: [documentitemID] has beensubmitted successfully.” If the method fails, it returns a SOAP Fault that indicates the reason forthe failure.

Syntax

String submitDocumentItem (requestContext, workflowState, documentItemID)

Parameters





workflowState : String[]

The name of the workflow state to which the document item will be submitted. It is not the currentworkflow state, it is the destination workflow state.


The unique identifier for the document item that you want to submit.

The approveDocumentItem Method

This Web Service enables you to approve a specified document item.

Return Value: If successful, this webservice returns “Document item: [documentitemID] has beenapproved.” If the method fails, it returns a SOAP Fault that indicates the reason for the failure.

Syntax

String approveDocumentItem (requestContext, documentItemID)

92


Parameters






The unique identifier for the document item that you want to submit.

The rejectDocumentItem Method

This Web Service enables you to reject a specified document item.

Return Value: If successful, this webservice returns “Document item: [documentitemID] has beenrejected.” If the method fails, it returns a SOAP Fault that indicates the reason for the failure.

Syntax

String rejectDocumentItem (requestContext, documentItemID)

Parameters






The unique identifier for the document item that you want to reject.

93


Calling the xEditor StartUp ApplicationThe xEditor StartUp application is a ClickOnce application that installs xEditor to the client machine,sets up a data directory for xEditor, and launches xEditor with the correct initialization data. You callthe xEditor StartUp application through an HTTP query string. Before calling the xEditor StartUpapplication, you must first call the The createAuthenticationToken Method, page 84 to create anauthentication token.

SyntaxxEditorStartup.application?TOK=%valid_user_token%&ID=%work_item_id%&URL=%xEditor_web_services_URL%&CNF=%xEditor_configuration_name%

xEditorStartup.application resides in the ...\xRevise.ear\xPression_Revise.war\xEditor directory onyour server. The URL for xEditorStartup.application is:http://<server_name>:<port_number>/xRevise/xEditor/xEditorStartup.application

Parameters

Required Parameters:

TOK

A valid user token generated by calling The createAuthenticationToken Method, page 84.

ID

The ID of the work item to be edited.

URL

The URL for the private xEditor web services. This is the same URL used to launch the xReviseweb applications. This URL is needed so that xEditor can locate the private web services it uses tocommunicate with the server. The syntax is:http://<server_name>:<port_number>/xRevise

CNF

The name of the xEditor configuration that you want to apply when launching xEditor. xEditorconfigurations are defined in the Resource Management section of xAdmin.

Optional Parameters:

INSTL

The value of this parameter is either T or F. This parameter enables you to activate or deactivate theStartUp application’s xEditor Update/Install feature. If the value is T (the default value), the featureis activated. If the value is F, the feature is deactivated. Additionally, if the value is F, the StartUpapplication will continue to verify that the current xEditor installation is valid, but it will not promptyou to update the install. To read more about this feature, see Starting xEditor the First Time, page 95.

CID

94


This parameter is for xRevise only. CID is the compare work item ID. Use this parameter if you arecomparing two items in Carry Forward.

Samples

For xRevise:xEditorStartup.application?TOK=1234&ID=101&URL="http://localhost:7001/xRevise"&CNF=Revise&INSTL=F

Starting xEditor the First Time

The client installation itself is largely automatic. If all required components are present, a messagedisplays.

xRevise uses a Smart Client to open xEditor when you select a work item from the xRevise desktop.The Smart Client ensures:• xEditor is installed

• is ready to use

• is the appropriate version

• presents the correct feature set

Smart Client needs to install some components on the first use. This first-time process occurs onlyonce per machine, even if other applications that used xEditor are used on that machine. StartingxEditor takes substantially longer the first time because of the initial installation procedure.

xEditor Manager is a component of xEditor that improves xEditor startup performance whenloading work items for editing. The initial installation adds an xEditor Manager shortcut to theSTARTUP folder. This queues an instance of xEditor when the machine starts up to the extentpossible, though login may be required for each time a work item is opened for editing in xEditor.This reduces the amount of time required for xEditor to open a work item. There will be an instanceof WINWORD.EXE running, with all required supporting software. This instance appears in TaskManager and can be shut down, but if it is shut down xEditor will take longer to open work itemsthan would otherwise be the case. The shortcut can be deleted if desired, but xEditor startup willbe much slower.

95


96

Chapter 6Administering xEditor

This chapter contains information for administrators of xEditor. The chapter contains some generaladministrative topics, as well as separate sections for administering xEditor in xResponse, xRevise, orcustom applications.• Administering xEditor for xResponse, page 98

• Administering xEditor for xRevise and Custom Applications, page 99

• xEditor Installation and Setup, page 102

• User Configuration, page 108

• Siteminder, page 108

• Workflow, page 108

• Enabling xEditor Functions, page 108

• Cache Management, page 109

• Ribbon Configuration , page 109

• xEditor Event Notification, page 117

• Local Files, page 117

• xEditor Localization, page 118

• Microsoft Word Issues, page 118

• Avoiding the Failed to Merge Content Error, page 120

• Hidden Text Panel, page 120

• Runtime Error when Closing xEditor, page 120

• xEditor and Terminal Service Logon, page 121

• Upgrading from Earlier Versions, page 121

• Clearing an Application File on the Client Machine, page 121

• Charts, page 122

97

Administering xEditor

Administering xEditor for xResponseThis section contains the following issues pertaining to the administration of xEditor for xResponse.Ensure you also review the general xEditor administrative topics in this chapter.

• Temporary Files, page 98

• Known Issues, page 98

• The Log, page 99

Temporary Files

xResponse uses temporary (temp) folders to hold documents while processing work items. Thesefolders are cleared when the user logs off or the browser is closed. There is now an option to retainthe contents of temp folders. This is primarily intended as a troubleshooting tool. To retain thecontent of temp folders set the following property in eCor.properties:deleteResponseTempFolders = false

By default this property is treated as true, and should only be changed as required for troubleshootingpurposes to avoid accumulating excessive temporary files.

Known Issues

Please review the following known issues:• Multiple Microsoft Word Versions, page 98

• Opening xEditor After “Failed to start editor” Error, page 98

Multiple Microsoft Word Versions

It is possible to have multiple versions of Microsoft Word installed on the same machine, butMicrosoft recommends against this configuration. EMC Document Sciences recommends againstit as well for any machine where xEditor is used. xEditor will attempt to use the latest version ofMicrosoft Word installed on the machine, but Microsoft Office Automation will attempt to load thelast used version. If the last version used is not the newest Microsoft Word version, an error willoccur when xEditor opens.

Opening xEditor After “Failed to start editor” Error

In some cases xEditor will fail to start with “Failed to start editor. Exception from HRESULT:0x8004063B.” This usually occurs when the Primary Editing Language is set to a language other thanEnglish. The issue can be avoided with the following procedure. This procedure does not affect thesetting in Microsoft Word.

98


To reset the default language setting for xEditor:1. Press CTRL+ALT+DEL.

2. Select Task Manager.

3. On the Processes tab, locate and select xEditorManager.exe, and then click End Process.

4. Staying on the Processes tab, locate and selectWinWord.exe, and then click End Process.

5. Close Task Manager.

6. Click Start and point to Startup.

7. Right-click xEditorManager.exe and then click Delete.

8. Restart the computer.

9. Open a document in Microsoft Word and then close it. The document should be a standardMicrosoft Word document, not an xDesign or other xPression document.

10. Click Start and then click Control Panel.

11. Click Add or Remove Programs.

12. Select xEditor and then click Remove. Confirm the request to remove xEditor as required.

13. Open xResponse.

14. Open a Letter. xEditor will automatically install as a first-time installation.

The Log

xResponse creates a log file that records the configuration setting used to start xEditor, the elapsedtime for all web service calls, and errors with stack traces. When a failure occurs, a message openswith a link that opens the file in a text editor.

You can also open the log file by selecting xResponse Log from the xResponse menu on the xEditortoolbar. The log file is located in C:\Documents and Settings\[USER]\Application Data\EMCDocument Sciences\[xResponse]\[server]\xResponse.log.

Administering xEditor for xRevise and CustomApplicationsThis section contains the following issues pertaining to the administration of xEditor for xReviseand your custom application. Ensure you also review the general xEditor administrative topicsin this chapter.• Spell Check for Form Fields, page 100

• Variable Color, page 100

• Track Changes, page 57

• The Log, page 100

99


• Localization, page 101

• Customizing Carry Forward, page 101

Spell Check for Form Fields

Microsoft Word does not provide the ability to spell check form fields. xEditor has been enhancedto provide spell checking for form fields. Spell checking of form fields can be done on demandor automatically when the document is saved.

Note: Since Microsoft Word does not support spell check in form fields there is a limitation whenmaking corrections to the content through the Spelling and Grammar dialog box. When makingcorrections do not delete the entire content of the form field. If the content is empty Word willimmediately delete the form field. When this occurs xPression will record an error indicating “Atleast one form field is deleted by spell check process.” To avoid this error type the correction firstand then delete the incorrect content.

To run a spell check, turn off Track Changes and then click Spell check for form field on the xRevisetoolbar. This button is available only if the document contains form fields and only if the documentincludes a section with Filling In Forms protection.

xEditor can be configured to automatically spell check form fields whenever the document is saved.Refer to xAdmin User Guide for more information xEditor configuration options.

Note: The protected text outside of the form field can be changed from this dialog box, even though itcannot be changed in the Editor itself. To avoid making text associated with form fields vulnerable tochange in this manner place the form field in a table cell.

Variable Color

The default setting of variable color is configured in xAdmin. Refer to the xAdmin User Guide formore information on the xEditor configuration.

Track Changes

Track Changes configuration is done in xAdmin. Refer to the xAdmin User Guide for more informationon the xEditor configuration.

The Log

xRevise creates a log file that records the configuration setting used to start xEditor, the elapsedtime for all web service calls, and errors with stack traces. When a failure occurs, a message openswith a link that opens the file in a text editor.

100


You can also open the log file by selecting xEditor log from the xRevise menu on the xEditor toolbar.The log file is located in C:\Documents and Settings\[USER]\Application Data\EMC DocumentSciences\[xRevise]\[server]\xEditor.log.

Localization

xEditor determines what language resource file to load based on the Windows language and regionsettings of the machine where it is installed. xEditor selects the appropriate language resources inthe following manner:

• First it tries to find a resource file with the exact match for language and region

• If it cannot find an exact match then it will try to find a resource file to match the language

• If it cannot find the exact match or a language match, then it will use the default languageresource: US English.

Customizing Carry Forward

Carry Forward determines which RUs should be included in the final version of a work item beingcarried forward as described in The Comparison Process. These decisions are made based onDEFAULT_CONFIG.xml, located in {xPressionHome, page 14Dir}\\xEditor\\CarryForwardConfigby default, or the configuration file identified in xAdmin.

DEFAULT_CONFIG.xml

The location of the file is fixed, but a different file can be specified. It is possible to modify theDEFAULT_CONFIG.xml file, but it is recommended that a new file be created and identified inxAdmin for custom configurations. There is no option to restore DEFAULT_CONFIG.xml to itsoriginal state after it has been modified.

The DEFAULT_CONFIG.xml file establishes the values for each possible case to be considered.Cases can have a value of Compare, Baseline, or none, but not all cases support each possiblevalue. For example:<BaselineNo><Compare id="RUC_1" value="Compare" variables="default"/><CompareDeleted id="RUC_101" value="None" variables="default"/></BaselineNo>

RUC_1 and RUC_101 are located in a node called BaselineNo. Referring to the case descriptions inThe Comparison Process we see that RUC_101 is not relevant at this time, so the only value supportedfor RUC_101 is “none”. Referring again to The Comparison Process we see that RUC_1 is a case wherethere is no version of the RU in the baseline version. Since there is no baseline version of the RU,this case supports “Compare” and “none” only. If the case value refers to a version where no RUexists, an error will be recorded in the CF.log.

An example of a case where all three values are valid is RUC_107:

101


<RevisionsCompare id="RUC_107" value="Compare" variables="default"/>

In this case there is an RU with the same name in each version, but they are not identical. The“Compare” (LY) version is carried forward to preserve changes made to the non-variable portion ofthe RU. In this case the value could be changed to “baseline” to discard the changes to non-variablecontent, or the RU could be discarded entirely by changing the value to “none”.

Note: DEFAULT_CONFIG.xml, or the designated configuration file, establishes Carry Forward logicwhether the Carry Forward Review is skipped or not.

There is a Reset to Defaults button that will reset the configuration file to DEFAULT_CONFIG.xml.This button does not restore the file to the original configuration if it has been changed, so it isrecommended to use a different file for custom configurations and leave the DEFAULT_CONFIG.xmlfile unchanged.

To customize the Carry Forward comparison:

1. Create a custom configuration file. You can make a copy of the default file as a starting point, orcreate a new file using your stock file as a guide.

Note: It is possible to modify the default configuration file, but there is no mechanism to restore itto its original state, so the recommended policy for using a custom configuration is to create acustom file and change the reference in xAdmin. The default file should be left unchanged tosimplify returning to the default configuration.

2. In your new custom file set the values for each case in your active configuration file. Supportedvalues are “Compare”, “Baseline”, and “none”.

Caution: Not all cases support all values. Cases that find that there is no RU with the namein question in one of the versions cannot use that version as a value. The “none” value isalways supported.

3. Log on to xAdmin and open the xEditor Configuration page.

4. Open the Carry Forward tab.

5. In the Configuration Options section, click Find File.

6. Locate and select the file created in step 1.

7. Save the file, restart the xPression server, and test the Carry Forward feature to ensure that thedesired results are achieved without errors.

xEditor Installation and SetupxEditor must be installed on the client machine. Installation is automatic the first time xEditor iscalled. Installation is required once per machine only, even if multiple applications with differentxEditor configurations are used on the same machine. The correct configuration for the callingapplication will be used automatically.

102


Please review the following topics:• Preparing Your Environment, page 103

• How Smart Client Handles Updates, page 105

• Starting xEditor the First Time, page 105

• Installing xEditor, page 106

• Pushing the xEditor Installation from the Server, page 107

• Client Verification, page 107

Preparing Your Environment

To ensure your environment is ready for xEditor, review the following topics:• Java Runtime Environment, page 103

• Microsoft .NET Framework, page 103

• Visual Basic for Applications, page 104

• Internet Explorer Settings, page 104

• Adobe PDFMaker, page 105

Java Runtime Environment

In some cases you may need to install the Java Runtime Environment (JRE) on your client machines.If you have problems displaying the Microsoft Word editing window, download JRE from the SunMicrosystems website and install it on your client machine. xRevise requires JRE 1.4.3 or higher andthe Java Development Kit 1.4 or 1.5.

Microsoft .NET Framework

In many cases Microsoft .NET Framework will already be installed. If .NET is not present, thenxResponse will display a message with a link to a download site where you can obtain the installationpackage for .NET Framework. If you receive this message, download the .NET Framework packageand follow the installation instructions provided by Microsoft.

After successfully installing .NET Framework:1. Log off xResponse.

2. Close and reopen Internet Explorer.

3. Log on to xResponse and select the work item that you want to open.

103


Visual Basic for Applications

Several versions of Microsoft Office are available. In some cases, such as Microsoft Office ProfessionalPlus 2007, Visual Basic for Applications (VBA) is installed by default. In others, such as MicrosoftOffice Enterprise 2007, VBA is not installed by default. xEditor requires VBA when using MicrosoftOffice Word 2007 or 2010. In installations where a version of Microsoft Office that does not installVBA by default it is necessary to install VBA manually. If VBA is not installed an error will occurwhen attempting to use xEditor with Microsoft Word 2007 or 2010.

To verify and install VBA:1. Open Add or Remove Programs from Microsoft Windows Control Panel. The UI varies

somewhat depending on the operating system version. Refer to the Microsoft Windowsdocumentation for information on using Control Panel and the Add or Remove Programs feature.

2. Locate and select the Microsoft Office entry and click Change. The installation wizard opens.

3. On the Change Your Installation step select Add or Remove Features and then click Continue.

4. Expand the Office Shared Features node.

5. Locate the Visual Basic for Applications node. If the node indicates that VBA is not installed, clickthe node and select Run from My Computer and then click Continue.

6. Click Close to close the installation wizard. Close Windows Control Panel.

Internet Explorer Settings

Automatically detect settings in Microsoft Internet Explorer’s Local Area Network (LAN) Settingsshould NOT be selected. Significant performance degradation for xEditor has been noted when thisoption is selected. It will be noted as a Warning in the xEditor log if selected.

You do not need to enable cookies or Java to use xEditor.

It is recommended that the Run .NET Framework-reliant components not signed with Authenticodein the Certificate Manager be enabled. xEditor is a signed .NET application but cannot runsuccessfully when this setting is false (disabled). In some organizations security policy does notallow this setting to be enabled. In these cases it is necessary to manually apply the EMC digitalcertificate to the trusted area. When the EMC digital certificate is applied xEditor is trusted andcan run successfully.

To apply the digital certificate:

1. Obtain the certificate file.

2. Open Windows Explorer and locate the certificate file. The file has a .p7b extension.

3. Right-click the file and select Install Certificate to open the Certificate Import Wizard and thenclick Next.

4. Input the password for the certificate and then click Next.

5. Select Place all certificates in the following store and then click Browse to open the SelectCertificate Store dialog box.

104


6. Select Trusted Root Certification Authorities from the tree view and then click OK.

7. Reopen the Select Certificate Store dialog box as in step 5 and select Trusted Publisher from thetree view and then click OK.

8. On the Certificate Import Wizard, Certificate Store step, click Next.

9. Click Finish to complete the installation and close the Certificate Import Wizard.

Adobe PDFMaker

xEditor can not exist on a system in which Word has the Adobe Acrobat PDFMaker add-in forAcrobat 9 enabled. This is an issue with the Adobe add-in, and not xEditor. The add-in mustbe disabled for xEditor to function.

How Smart Client Handles Updates

xEditor uses Smart Client to ensure that xEditor is installed and that the best version is available. A“Smart Client” in an application environment that delivers an application over an HTTP connection.It provides automated installations and updates with minimal user interaction. Smart Client runsevery time a document is opened for editing with xEditor. Smart Client is based on Microsoft .NETtechnology.

Smart Client may determine that the xEditor versions on the client and server are not the same. If theclient version is newer the option to downgrade to the server version is offered, if the client version isolder the option to upgrade is offered. xEditor will offer to upgrade or downgrade the client versionso that it matches the xEditor version used on the server. When upgrading or downgrading, theSmart Client only updates the relevant components and does not perform a full installation.

To avoid potential compatibility issues the xEditor version on the client must match the xEditorversion on the server. If you choose not to upgrade or downgrade, xEditor will not launch.

Starting xEditor the First Time

The client installation itself is largely automatic. If all required components are present, a messagedisplays.

xResponse uses a Smart Client to open xEditor when you select a work item from the xResponseworkspace. The Smart Client ensures that xEditor:

• is installed

• is ready to use

• is the appropriate version

• presents the correct feature set

105


Smart Client needs to install some components on the first use. This first-time process occurs onlyonce per machine, even if other applications that used xEditor are used on that machine. StartingxEditor takes substantially longer the first time because of the initial installation procedure.

The initial installation adds a shortcut to ALL USERS \start menu\programs\startup. This queues apre-WIP version of xEditor when the machine starts up. This reduces the amount of time required forxEditor to open a work item. There will be an instance of WINWORD.EXE running, with all requiredsupporting software. This instance appears in Task Manager and can be shut down, but if it is shutdown xEditor will take longer to open work items than would otherwise be the case.

Installing xEditor

To install xEditor on the client machine:

1. When the xPression Editor Startup message appears, click Install.Depending on your Microsoft Word macro security setting, you may receive a Security Warningthat xEditor.dot contains macros. xEditor uses macros to override some Word functions, sochoose Enable Macros if you receive this message.

2. The xEditor Setup Wizard starts. Click Next.

106


3. In the Select Installation Folder step you can choose where to install xEditor.A default location for xEditor is offered, but you can choose another location. To install to adifferent location, type the desired path in the Folder field, or click Browse and choose a locationfrom the Browse for Folder dialog box.Click Disk Cost to see if enough disk space is available.Click Next to proceed with the installation.

4. The Confirm Installation step confirms that Smart Client is ready to proceed with the installation.Click Next to proceed.

5. A status bar shows the progress of the installation. A message opens when the installation iscomplete. Click Close to close the installation wizard and open xEditor.

xEditor will appear in the Windows Add and Remove Programs list in Control Panel, which you canuse to remove xEditor if necessary. If you open a document that needs xEditor after uninstalling theeditor, Smart Client will initiate the installation process.

The installation applies to either xRevise or xResponse, regardless of which one you were using whenyou started the installation.

Note: Whenever xEditor starts it creates a temporary configuration file, config.txt, on the client. Thisfile is deleted after use unless running in debug mode. It is strictly for internal, session-specific useand should not be modified by the user.

Pushing the xEditor Installation from the Server

The xEditor installation is drawn from the xPression server. In some environments client machineslack the permissions to conduct the installation as described above. In this case xEditor can be pushedto the client machine by the network administrator or any qualified person with appropriate access.

When an installation is pushed, it does not have the capability to detect a previous version. Therefore,if a previous version exists on the target machine, you must push the uninstallation of the previousversion, before pushing the new installation.

The xEditor installer is stored in a ZIP file, xEditorInstaller.zip, which is located in the server-deployedxPression_Revise.war and xPression_Response.war files. The method for installing depends onyour network environment.

Client VerificationTo verify a client installation:1. Ensure that the .NET components are enabled. Refer to the Installer’s Handbook for detailed

instructions.

2. In Internet Explorer, open the Tools menu, click Internet Options, point to Security, and thenclick Trusted Sites. Ensure that the xPression server is included.

3. Open Internet Explorer. On the Toolsmenu, click Internet Options. On the General tab, clickDelete to delete temporary files and cookies.

4. Open a work item in xEditor.

107


5. Use Internet Explorer to open xRevise, then change the URL to http://<[server]:[port]>/xRevise/services. Substitute your actual server name and port number in the indicated location. Ensurethat the available services are appropriate.

User ConfigurationThe only configuration requirement is that the user must have read, write, and create access to thedirectory ’C:\Documents and Settings\[user]\Application Data\EMC Document Sciences’ to use thexEditor application. xEditor needs to write log and other files to this location.

SiteminderxPression supports Siteminder for single-sign on authentication. In environments where Siteminderis used it may be necessary to configure the xRevise client so that an authentication error can beavoided. There are two methods for avoiding this condition. Refer to the xPression Installation Guidefor details on configuring your system to work with Siteminder.

WorkflowUser groups as well as individual users can be identified as approvers and submitters. Exercisecaution when making user groups approvers. When a document is submitted to a group for approval,then no individual user will own the work item and so the hyperlink to open the document in xEditorwill be inactive for all users. This design feature ensures that work items are available for editing to aspecific individual only. To activate the hyperlink select the work item, click the Reassign button onthe Actions bar, and then assign the work item to the current user or another user as desired.

When a document is locked for editing and a user attempts to Submit, Delete, or Carry Forward thedocument an error will be generated.• If a Submit is attempted and the submitter has multiple approvers the error is displayed in a popupwindow. If the submitter has only one approver the error is displayed on the xRevise desktop.

• If a Delete or Carry Forward is attempted the error will display in a popup window regardlessthe number of approvers for the submitter.

Workflow is optional. If no workflow is established then the Submit and Approve actions will haveno effect. The buttons are active, but a message will display indicating that no workflow exists for thecategory. The Complete button is available and work items can be completed even if no workflowhas been established.

Enabling xEditor FunctionsYou can enable or disable functions in the xEditor interface through the Resource Management menuin xAdmin. See the xAdmin User Guide for instructions.

108


Cache ManagementxResponse caches work items locally to improve performance. First-time load performance for awork item may be somewhat slower due to the need for web service calls to retrieve the work itemfrom the xPression server.

The xPression Administrator can configure the system to clear the cache automatically. The primaryreason for automatically clearing the local cache is for security. In cases where xEditor users workwith documents that contain sensitive information, deleting local copies of the document helps toprevent unauthorized access to this information. The administrator can configure the system todelete cached files after a set amount of time or when the cache size exceeds a specified amount.The administrator can also disable local caching.

If the system is not configured to automatically delete cached files, the cache should be clearedmanually as required to prevent an excessive accumulation of files. You can clear the xResponse cachemanually, through the Windows file system, or through the xResponse interface.

To clear the cache from the Windows file system:1. Close xEditor. It is not necessary to close xResponse or xRevise, but if you have a work item open

the associated cache file will not be deleted.

2. On the client machine, locate the cache files.For xResponse: Cache files are stored in [Drive]:\Documents and Settings\[WINDOWS_LOGIN_NAME]\Temporary Internet Files\Response and in [Drive]:\Documents andSettings\[WINDOWS_LOGIN_NAME]\Local Settings\Application Data\EMC DocumentSciences\Response. Each work item has its own folder.For xRevise: On Windows 7 and Windows Server 2008: C:\Users\[user]\AppData\Roaming\EMC Document Sciences

3. Delete some or all of the cached files. You can delete work item folders if desired.The xPression Administrator can configure the system so that the Local Work Item Cache dialogbox is available to the local user. If the dialog box is available the local user can use it to clear thecache manually.

To clear the document cache from the Local Work Item Cache dialog box:1. Log on to xResponse or xRevise and open any work item. When using this method the entire

cache will be cleared, so the current work item does not matter.

2. From the xResponse or xRevise menu, select Cache Settings. The Local Work Item CacheSettings dialog box opens showing the current settings. If the dialog box has not been enabledit will still open, but will indicate that the feature is disabled.

3. Click Clear Now.

Ribbon ConfigurationYou can change the Microsoft Word ribbon configuration to enable or suppress the elements on theribbon. While changes that you make through the Word interface are limited to the current session,change made through a configuration file will last beyond the current session. Changes made in the

109


configuration file affect all users of the application on the xPression server where the configurationfile is located. Each server can have a different configuration.

The configuration files are located in the xEditor folder of your xPressionHome directory. This fileused to be located in the EAR directory, please note the new location. EMC Document Sciencesprovides sample configuration files to help you get started:

W2007–2010_DEFAULT_CONFIG.xml for Microsoft Word 2007 and 2010environments.

Simply copy and rename the appropriate configuration file to create your custom configurationfile. Once your file is configured, you must specify the configuration file in xAdmin to enable it forthe server.

To make changes to your Microsoft Word ribbon, see the following topics:• How to Make Changes to Your Microsoft Word Ribbon, page 110

• Additional Configuration Steps for xRevise Users, page 111

• Language Specific Configuration Files, page 111

• Creating a Custom W2007_DEFAULT_CONFIG.xml for xRevise, page 111

• Element Properties, page 112

• Excluded, Repurposed, and Unsupported Commands, page 114

How to Make Changes to Your Microsoft Word Ribbon

When you configure the ribbon for Word 2010, be aware of the following things:• Disabling an option in ribbon configuration for xEditor also disables the corresponding keyboardshortcut. For example, if you disable the Bold option using the following setting, the CTRL+Bshortcut is also disabled.<command idMso="Bold" enabled="false"/>

• This configuration only enables or disables options on the Microsoft Word ribbon, not options onthe Word Backstage page. For example, even if you disable all print-related commands in theconfiguration file, the Print option on the Word Backstage page is still enabled.

To make changes to the Microsoft Word ribbon configuration on your server, complete the followingsteps:

1. Go to the xEditor folder of your xPressionHome directory and locate the appropriateconfiguration file.

2. Copy and rename the file.

3. Locate the item to be enabled or suppressed and set the enabled property as appropriate. Forexample:<command idMso="Font" enabled="false"/><command idMso="Bold" enabled="false"/>

In this example, the Font and Bold options would not be available on the ribbon in xEditor.

4. Once you have made all of your changes, save the file.

110


5. Log in to xAdmin.

6. Click Resource Management, then click xEditor Configuration.

7. Click the configuration for the application you want to configure.

8. Click theWord tab.

9. In the Word Configuration Options section, click Find File for your version of Microsoft Word.

10. xAdmin displays a pop-up window that shows the files located in the xEditor folder of yourxPressionHome directory. Select the file your customized and click OK.

11. Click Save.

Additional Configuration Steps for xRevise Users

Toolbar Configuration may not function if the server’s IP address is not correctly identified inxRevise.dll.manifest. The toolbar configuration will not be recognized if the server’s IP addressis not correctly identified in this file.

To set the server IP address in xRevise.dll.manifest:1. Locate and open xRevise.dll.manifest.

2. Ensure that all IP address references are correct for your server.

3. Save xRevise.dll.manifest.

Language Specific Configuration Files

You can create language specific configuration files for non-English implementations.

Creating a Custom W2007_DEFAULT_CONFIG.xml forxRevise

The standard toolbar is in English, but you can create a custom toolbar for any language ifMicrosoft Word 2007 or 2010 is used with xEditor. If the language-specific configurationfile that matches the language that the user uses for Word is not available, the defaultW2007–2010_DEFAULT_CONFIG.xml file is used.

To create a custom W2007–2010_DEFAULT_CONFIG.xml:1. Open W2007–2010_DEFAULT_CONFIG.xml and save a copy with the appropriate name as in

these examples:• German — German_W2007–2010_DEFAULT_CONFIG.xml

• French — French_W2007–2010_DEFAULT_CONFIG.xml

111


• English — USEnglishUS_W2007–2010_DEFAULT_CONFIG.xml

• Spanish — Spanish_W2007–2010_DEFAULT_CONFIG.xml

See the note following this procedure.Refer to http://msdn2.microsoft.com/en-us/library/Aa432635.aspx for a detailed list of languagenames. For example, Canadian French would be FrenchCanadian.

2. Translate the toolbar names to the name used byWord. Also, you can determine the name used byright-clicking the toolbar. The name is not necessarily the typical translation of the English name.

3. Translate the name of each toolbar control in the <Command> sections. You do not need totranslate names for buttons that you want to remain displayed and active. As with the toolbarnames, you must use the name that Word uses for the control and this is not necessarily the mostcommon translation of the English name. You can determine the name by holding your cursorover the button momentarily and using the name shown in the tooltip.

4. Translate menus as required using the labels that appear in your version of Word.

5. Save the configuration file in .../xPression_Revise/html/xReviseFatClient/xRevise_version/Utility/.

Element Properties

The following table lists all of the available elements and their properties.• ToolBars

Contains all of the Toolbar elements, which establish the configuration for each individual toolbar.This element has no properties.

• Toolbar

Located between the opening and closing ToolBars tags, this tag establishes the configuration fora specific toolbar. In addition to its properties, the HideControls and DisableControls elementsreside between its opening and closing tags.— Name is the name of the toolbar.

— Visible can be either true or false and determines whether the toolbar is visible or not.

— DisableAllChild disables all controls on the toolbar. When this property is true, you do notneed to specify individual controls to be disabled.

• HideControls

Located between the opening and closing Toolbar tag, controls identified with this tag are hiddenon the toolbar identified in the Toolbar tag.

Name is the name of the control to be hidden.

• Disable- Controls

Located between the opening and closing Toolbar tag, controls identified with this tag are disabledon the toolbar identified in the Toolbar tag.

Name is the name of the control to be disabled. The control remains visible.

112


• Control

Each Control element located within a HideControls or DisableControls section identifies a controlto be hidden or disabled.

ShortCuts disables any keyboard shortcuts associated with the control. This is necessary if youwant to eliminate the function entirely since the shortcut will still work even if the control hasbeen hidden or disabled. You must identify each shortcut combination, separating keys withcommas and different shortcut combinations with the pipe symbol as in this example.<Control Name="Save" ShortCuts="(control,s)|(shift,f12)|(alt,shift,f12)"></Control>

• Menus

Contains all of the Menu elements, which establish the configuration for each individual menu.This element has no properties.

• Menu

Located between the opening and closing Menus tags, this tag establishes the configuration for aspecific menu. In addition to its properties, the HideControls and DisableControls elements residebetween its opening and closing tags. This element only applies to xResponse.— Name is the name of the menu.

— Visible can be either true or false and determines whether the menu is visible or not.

— DisableAllChild disables all controls on the menu. When this property is true, you do notneed to specify individual controls to be disabled.

• HideControls

Located between the opening and closing Menu tag, controls identified with this tag are hiddenon the menu identified in the Menu tag.

Name is the name of the control to be hidden.

• Disable- Controls

Located between the opening and closing Menu tag, controls identified with this tag are disabledon the menu identified in the Menu tag.

Name is the name of the control to be disabled. The control remains visible.

• Control

Each Control element located within a HideControls or DisableControls section identifies a controlto be hidden or disabled.

ShortCuts disables any keyboard shortcuts associated with the control. This is necessary if youwant to eliminate the function entirely since the shortcut will still work even if the control hasbeen hidden or disabled. You must identify each shortcut combination, separating keys withcommas and different shortcut combinations with the pipe symbol as in this example.<Control Name="Save" ShortCuts="(control,s)|(shift,f12)|(alt,shift,f12)"></Control>

113


Excluded, Repurposed, and Unsupported Commands

The following Word functions are either not available with xEditor, or the stock functionality ismodified by xEditor. It may be possible to enable toolbar buttons or menu item for those that are notsupported, but the function is still overridden by xEditor.

The following functions are not supported by xEditor, but cannot be suppressed in the interface.• Create or Modify Style

xEditor does not support creating new styles. When xEditor detects a new style, the style isdeleted and a message is displayed. xEditor does not support modifying styles. Users should notmodify styles because satisfactory results cannot be guaranteed.

• New Window

Word does not allow this option while running with xEditor because an XML expansion pack isattached. This limitation is imposed by Word.

The following Word features work differently in xEditor.• Created On

The Created On option for Insert Auto Text does not insert the actual date the document wascreated. It always inserts “Created on 6/19/2007 10:14:00 AM.” It is recommended that usersavoid using this option.

• CTRL+A

The CTRL+A hotkey combination selects the entire document in Word. CTRL+A behavesdifferently in xEditor, depending on whether the document includes optional content or not. If thedocument does not include any optional content, then the entire RU is selected. If the documentincludes optional content, then the text of the current node is selected.

• Protection

xEditor supports Read Only and Forms Fill-In protection types with some restrictions. SeeProtection.

• Drag and Drop

Drag and drop is not allowed if the current selection includes a variable or a DCPI field. xEditorwill not permit data to be dropped into a variable or DCPI field.

The following Word functions are suppressed, not supported, and cannot be enabled with a customribbon configuration.

From the Office menu:• Send Menu

All items including E-mail, E-mail as PDF Attachment, E-mail as XPS Attachment, and Internet Fax

• Version History

• Properties

• Save As Menu

All items including Save as Word Document, Save as Word Template, Save as Word 97–2003Document, PDF or XPS, and Other Formats

114


• Publish Menu

Create Document Workspace

• Office Menu

Find add-ins for other file formats

From the Home tab:• Paragraph section

Distributed toggle

• Quick Styles

Save Selection as New and Save Quick Style Set

From the Insert tab:• Insert Picture from File

• Insert Shapes

• Insert Drawing Canvas

• Insert Smart Art

• Ink Group

• Property

• Building Blocks Organizer

• Get More on Office Online

• Save Selection To Quick Part Gallery

• WordArt

From Page Layout tab:• Themes

• Text Direction

From Review tab:• Track Changes

• Accept All Changes in Document

• Accept All Changes Shown

• Accept and Move to Next

• Reject All Changes in Document

• Reject All Changes Shown

• Reject and Move to Next

From View tab:• Document Map

• Thumbnails

• Side by Side

115


From Developer tab:• XML group

• Structure

• Schema

• Transformation

• Expansion Packs

• Templates group

• Document

• Document Panel

From Table Tools Layout tab:• Text Direction

• Web Component

• Auto Format

• Auto Format as you Type

• Auto Format Now

• Auto Format Options

• Microsoft Office PowerPoint

The following functions have been repurposed for xEditor. They can be disabled, but the originalfunction cannot be restored.

From the Office menu:• Save

• Save As

• Application Options

From the Home tab:• Find

• Replace

• GoTo

• Paste

• Paste Special

• Paste Hyperlink

From the Page Layout tab:• Page Setup

From the Review tab:• Spelling and Grammar

• Restrict Formatting

116


• Compare Two Versions

• Accept Change

• Reject Change


xEditor Event NotificationxEditor event notification is an optional feature that provides a means of informing applications thatuse xEditor that Open, Save and Close actions have occurred with xEditor. xRevise, xResponse, andcustom applications created with IDDK can use the event notification feature as long as a listenerhas been created and the listener has been identified for the application in xAdmin. The applicationuser must have read/write access to C:\Documents and Settings\%CURRENT_USER%\ApplicationData\EMC Document Sciences.

For more information, see the Resource Management section of the xAdmin User Guide.

Local FilesxEditor creates a file structure on the client to avoid excessive calls to the server, and so toimprove performance. The files stored here are the application files downloaded from theserver, not the assembled document files. The structure is located under C:\Documents andSettings\[user]\Application Data\EMC Document Sciences\[server_port]\[document]. The variableparts are as follows:

• [user] - The current Windows user (not necessarily the xResponse user)

• [server_port] - The server name and port, localhost_8080 for example

• [document] - The work ID of the document

This process means that loading a document will take longer the first time than in subsequent sessions.

If the W2007_DEFAULT_CONFIG.xml file is changed, the local copy for each document on eachclient machine must be deleted to apply the changes. It is possible that different documents can havedifferent ribbon configurations in xEditor if this file is not deleted when changes are made on theserver. Smart Client automatically replaces the file on the client machine if the file is necessary.

xEditor saves a Word-format (.doc) copy of the document in the \[document] folder. This file cannotbe opened outside of xEditor. A message opens when the user attempts to open this file directly inWord.

117


xEditor LocalizationxEditor determines what language resource file to load based on the Windows language and regionsettings of the machine where it is installed. The server locale need not match the client locale.xEditor selects the appropriate language resources in the following manner:

• First it tries to find a resource file with the exact match for language and region

• If it cannot find an exact match then it will try to find a resource file to match the language

• If it cannot find the exact match or a language match, then it will use the default languageresource: US English.

Microsoft Word IssuesReview the following Microsoft Word topics:• Microsoft Word Add-Ons, page 118

• Multiple Microsoft Word Versions, page 118

• Balloons, page 119

• Undo, page 119

• Table Rules and Read Only Protection , page 119

• Inserting Table Rows, page 120

Microsoft Word Add-Ons

Many add-ons are available for Microsoft Word. Using xEditor with third-party add-ons mayproduce unexpected results.

Multiple Microsoft Word Versions

It is possible to have multiple versions of Microsoft Word installed on the same machine, butMicrosoft recommends against this configuration. EMC Document Sciences recommends againstit as well for any machine where xEditor is used. xEditor will attempt to use the latest version ofMicrosoft Word installed on the machine, but Microsoft Office Automation will attempt to load thelast used version. If the last version used is not the newest Microsoft Word version, an error willoccur when xEditor opens.

118


Balloons

By default Microsoft Word displays comments and changes in balloons. If balloons are displayedand adjacent sections have different page settings, Word will break the page between these sections.This may result in an extra page being added to the document. This effect will occur in cases wheresubdocuments have different page settings than adjacent sections, and so the unexpected pagebreak may have no apparent cause without understanding this behavior. To prevent the unexpectedbreak, either turn off balloons or redesign the document and all subdocuments to have the samepage settings.

Undo

See the following known issues:• Undo After Paste Not Supported, page 119

• Using Undo, page 119

Undo After Paste Not Supported

Using Undo after pasting into the editor is not supported.

Using Undo

In some cases it is necessary to click Undo twice to restore the document to its status prior to makingan edit. For example, if a word is selected and then replaced by typing a new word, the first undowill delete all but the first letter of the new word and the second undo will replace the remainingletter with the original word. This behavior is because of the way Microsoft Word records the actions.The select action is an action and the replace action is another action, so Word requires two undoactions to completely restore the original text. The same behavior can be observed in MicrosoftWord without xEditor.

Table Rules and Read Only Protection

Table rules under Read Only protection with an exception region in the table will cause an error whenattempting to open the document in xEditor. It is recommended to avoid placing table rules underRead Only protection. Consider using a content read loop instead.

119


Inserting Table Rows

In xEditor with Microsoft Word 2007, rows inserted in tables may initially have a height of 0 pixels,so it appears that a row was not inserted. The row height can be corrected by resetting row heightfor the table. This problem is caused by the way Word 2007 handles document formatting andcannot be addressed in xEditor at this time. Rows inserted in Microsoft Word 2007 without xEditorbehave the same way.

Note: This problem does not affect rows added to the end of a table by placing the cursor in theright-most cell of the last row of a table and pressing TAB.

Avoiding the Failed to Merge Content ErrorA Failed to Merge Content error will occur when opening the work item in xEditor if a variablewith a value of NULL is preceded by a combination of page fields and tabs. To avoid this, set thevariable value to a blank space rather than NULL.

Hidden Text PanelThe Hidden Text panel is displayed when the cursor is positioned in a region of hidden text. This canhelp prevent inadvertently inserting hidden text, which is used for document formatting.

You can set the following two options from the xEditor Configuration section in xAdmin to determinethe Hidden Text panel’s behavior:• Enable hidden text monitoring — Hidden Text Monitoring is not enabled by default. Whenenabled, the Hidden Text panel is displayed in a document when the cursor is positioned in aregion of hidden text.

• Allow users to un-hide the selection — When selected the Unhide button on the Hidden TextPanel is available. Normally, any text added to an area of hidden text will be hidden text, but ifthe Unhide button is clicked any text added following the point where the Unhide button wasclicked will be normal text.

For more information, see xAdmin User Guide

Runtime Error when Closing xEditorA runtime error may occur when closing xEditor if Adobe Acrobat is installed and the 7.0.8 update toAcrobat has not been installed. Adobe provides the following options to resolve this issue:• Install the Acrobat 7.0.8 update

• Lower the security level within Microsoft Word

• Rename the Normal.dot template file

120


This issue applies to other Microsoft Office applications. In xPression it has only been noted withxEditor, which uses Microsoft Word. Refer to document number 331273 on the Adobe Support pagefor detailed information and instructions related to this issue.

Removing the Adobe add-in from Word also corrects the issue as it manifests in xEditor.

xEditor and Terminal Service LogonxEditor will not start if a mandatory profile is used to launch xEditor through a Terminal Serviceconnection, unless .NET Framework 3.5 is installed. To resolve this problem, install the appropriateversion of .NET Framework, which is available for download from the Microsoft Download Center.

Upgrading from Earlier VersionsEnabling multiple paragraphs in text form fields involved changes to the function that parses content,so paragraph merge does not produce the same results as in previous versions. When paragraphsare merged the paragraph end character for the earlier paragraph in the merge should be removed,but was not necessarily removed in earlier versions of xPression, including some xPression 3 SP1builds. In cases where the earlier result is desired it is recommended that a space be added to thebeginning of the customer data. for example:"<SAMPLE_TAG>sample_data </SAMPLE_TAG>" "<SAMPLE_TAG>sample_data </SAMPLE_TAG>"

Clearing an Application File on the ClientMachineThe W2007_DEFAULT_CONFIG.xml file is used to customize the Word toolbars and ribbon(Microsoft Word 2007 and 2010) available in xEditor. The file is downloaded to the client machine forperformance reasons. If deleted from the client machine the file will be automatically downloadedfrom the server. The only performance impact of this is when loading xEditor since the file must bedownloaded again. There are no other application files downloaded and cached on the client machine.

121


ChartsCharts (DDGs) are not supported in xEditor. Documents that use charts cannot be used to createxRevise work items.

122

Appendix A

Words Excluded from SQL Full TextSearch

The following words are excluded from SQL full text searches. Including these words will limit thenumber of returned items in some searches. In addition, individual letters are excluded.

Exclusion Tableabout because did have its never said the very who 7

after been do her just no same their want will 8

all before does here like now see them was with 9

also being each him make of should then way would 0

an between else him-self

many on since there we you $

and both for his me only so these well your

another but from how might or some through were 1

any by get if more other still to what 2

are came got in most our such too when 3

as can has into much out take under where 4

at come had is must over than up which 5

be could he it my re that use while 6

123