Xpression Xframework Development Guide

Transcript

EMC ® Document Sciences ® xPression ® xFramework Version 4.5 SP1 Development Guide EMC Corporation Corporate Headquarters Hopkinton, MA 01748-9103 1-508-435-1000 www.EMC.com Legal Notice Copyright © 2003-2015 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS 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 PDF Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarks used 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 feedback about how we can make our documentation better or easier to use, please send us your feedback directly at [email protected] Table of Contents Revision History Chapter 1 Chapter 2 Chapter 3 .................................................................................................................. 21 Introduction ................................................................................................. 23 Information Boxes ............................................................................................ 23 EMC Document Sciences Technical Support ....................................................... 23 ...................................... What Has Changed? ......................................................................................... Authentication ................................................................................................ About the requestContext Parameter ............................................................. Using requestContext with Documentum-Based Documents ....................... requestContext Examples .......................................................................... Setting Up Your Application.............................................................................. Adding Your Application Definition .............................................................. Configuring Your Application with xAdmin................................................... Associating Attribute Sets with Your Application ....................................... Assigning Data Sources to Your Application .............................................. Setting Up Access Rights for Your Application ........................................... Configuring Workflow for Your Application............................................... IQuickDoc Configuration .................................................................................. Error Messages ................................................................................................. The CompuSet Bridge ....................................................................................... xPressionHome ................................................................................................ 25 ........................................................................ xPresso for Word Documents in Workflow Enabled Categories............................ The categoriesForUser Method .......................................................................... Syntax ......................................................................................................... Parameters ................................................................................................... The documentsForCategory Method .................................................................. Syntax ......................................................................................................... Parameters ................................................................................................... The descriptionForDocument Method................................................................ Syntax ......................................................................................................... Parameters ................................................................................................... The thumbnailForDocument Method ................................................................. Syntax ......................................................................................................... Parameters ................................................................................................... The designToolForDocument Method ................................................................ Syntax ......................................................................................................... Parameters ................................................................................................... The outputProfilesForDocument Method ........................................................... 33 About xFramework and the xPression DevKit API The IQuickDoc Web Service 25 26 26 27 27 28 28 30 30 30 31 31 31 32 32 32 34 34 34 34 35 35 35 35 36 36 37 37 37 38 38 38 39 3 Table of Contents Chapter 4 4 Syntax ......................................................................................................... Parameters ................................................................................................... 39 39 The versionsForDocumentWithWorkflowStatus Method ..................................... Syntax ......................................................................................................... Parameters ................................................................................................... 40 40 41 The publishDocument Method .......................................................................... Syntax ......................................................................................................... Parameters ................................................................................................... Sample......................................................................................................... 42 42 43 44 The publishDocuments Method ........................................................................ Syntax ......................................................................................................... Parameters ................................................................................................... Sample......................................................................................................... 44 45 45 46 The publishAndReturnDocument Method ......................................................... Syntax ......................................................................................................... Parameters ................................................................................................... 47 48 48 The publishAndReturnDocumentMultipleStream Method .................................. Syntax ......................................................................................................... Parameters ................................................................................................... 49 50 50 The getTemplateFields Method.......................................................................... Syntax ......................................................................................................... Parameters ................................................................................................... Examples ..................................................................................................... With NULL customerData Value ............................................................... With Supplied customerData..................................................................... 51 51 51 52 53 53 The getDataCollectionTemplate Method ............................................................ Syntax ......................................................................................................... Parameters ................................................................................................... Examples ..................................................................................................... With NULL customerData Value ............................................................... With Supplied customerData..................................................................... 53 54 54 55 55 56 ............................................................. WorkflowDocumentBrowsingService................................................................. listWorkFlowAvailableCategories .................................................................. Syntax ..................................................................................................... Parameters ............................................................................................... listWorkFlowAvailableDocuments ................................................................. Syntax ..................................................................................................... Parameters ............................................................................................... getDocumentType ........................................................................................ Syntax ..................................................................................................... Parameters ............................................................................................... getDocumentVersions ................................................................................... Syntax ..................................................................................................... Parameters ............................................................................................... DataBrowsingService ........................................................................................ getDefaultDS ................................................................................................ Syntax ..................................................................................................... Parameters ............................................................................................... listKeys ........................................................................................................ Syntax ..................................................................................................... Parameters ............................................................................................... getDataRecordXML ...................................................................................... Syntax ..................................................................................................... 57 Workflow Integration Web Services 57 57 57 58 58 58 58 59 59 60 60 60 60 61 61 61 62 63 63 63 63 64 Table of Contents Chapter 5 Parameters ............................................................................................... 65 WorkflowService .............................................................................................. listLifeCycles ................................................................................................ Syntax ..................................................................................................... Parameters ............................................................................................... statusInLifecycle ........................................................................................... Syntax ..................................................................................................... Parameters ............................................................................................... previewPDF ................................................................................................. Syntax ..................................................................................................... Parameters ............................................................................................... previewHTML ............................................................................................. Syntax ..................................................................................................... Parameters ............................................................................................... workflowBegins ........................................................................................... Syntax ..................................................................................................... Parameters ............................................................................................... setLifecycleStatus ......................................................................................... Syntax ..................................................................................................... Parameters ............................................................................................... workflowEnds .............................................................................................. Syntax ..................................................................................................... Parameters ............................................................................................... 65 65 66 66 66 66 66 67 67 67 68 68 68 69 69 69 69 69 70 71 71 71 .................................................................. The IDocumentItem Web Service ....................................................................... searchDocumentItem .................................................................................... Syntax ..................................................................................................... Parameters ............................................................................................... Sample..................................................................................................... The createDocumentItem Method .................................................................. Syntax ..................................................................................................... Parameters ............................................................................................... The getDocumentItemInfo Method ................................................................ Syntax ..................................................................................................... Parameters ............................................................................................... Examples ................................................................................................. The publishAndReturnDocumentItem Method............................................... Syntax ..................................................................................................... Parameters ............................................................................................... The publishAndReturnDocumentMultipleStream Method .............................. Syntax ..................................................................................................... Parameters ............................................................................................... The documentItemsAssignedToUser Method ................................................. Syntax ..................................................................................................... Parameters ............................................................................................... The reassignDocumentItemToUser Method .................................................... Syntax ..................................................................................................... Parameters ............................................................................................... The updatePrimaryVariables Method ............................................................ Syntax ..................................................................................................... Parameters ............................................................................................... The copyDocumentItem Method ................................................................... Syntax ..................................................................................................... Parameters ............................................................................................... The addExternalContentByLink Method ........................................................ Syntax ..................................................................................................... Parameters ............................................................................................... 73 xPression DevKit Web Services 73 74 74 74 76 77 77 78 78 80 80 81 82 83 83 84 85 85 85 86 87 87 87 87 88 88 88 89 89 90 90 90 90 5 Table of Contents addExternalContentByStream ....................................................................... Syntax ..................................................................................................... Parameters ............................................................................................... The reorderExternalContent Method ............................................................. Syntax ..................................................................................................... Parameters ............................................................................................... The addAnnotation Method .......................................................................... Syntax ..................................................................................................... Parameters ............................................................................................... The deleteExternalContent Method................................................................ Syntax ..................................................................................................... Parameters ............................................................................................... The createAuthenticationToken Method ......................................................... Syntax ..................................................................................................... Parameters ............................................................................................... The complete DocumentItem Method ............................................................ Syntax ..................................................................................................... Parameters ............................................................................................... The deleteDocumentItem Method.................................................................. Syntax ..................................................................................................... Parameters ............................................................................................... The publishRevisionUnits Method ................................................................. Syntax ..................................................................................................... Parameters ............................................................................................... The setCarryForwardDocumentItem Method ................................................. Syntax ..................................................................................................... Parameters ............................................................................................... The clearCarryForwardDocumentItem Method ............................................ Syntax ................................................................................................... Parameters ............................................................................................. The updateRUVariables Method .................................................................. Syntax ................................................................................................... Parameters ............................................................................................. The submitDocumentItem Method .............................................................. Syntax ................................................................................................... Parameters ............................................................................................. The approveDocumentItem Method ............................................................ Syntax ................................................................................................... Parameters ............................................................................................. The rejectDocumentItem Method................................................................. Syntax ................................................................................................... Parameters ............................................................................................. Chapter 6 6 92 92 92 93 93 93 94 94 94 95 95 95 96 96 96 96 97 97 97 97 98 98 98 98 99 99 99 100 100 100 100 101 101 101 101 102 102 102 102 103 103 103 Calling the xEditor StartUp Application ........................................................... Syntax ....................................................................................................... Parameters ................................................................................................. Samples ..................................................................................................... Starting xEditor the First Time ..................................................................... 104 104 104 105 105 ............................................................................... The getCatalogInfo Method ............................................................................. Syntax ....................................................................................................... Parameters ................................................................................................. Sample Returned Document ........................................................................ The searchForDocuments Method ................................................................... Simple Search Criteria ................................................................................ Advanced Search Criteria ............................................................................ Syntax ....................................................................................................... Parameters ................................................................................................. 107 xCatalog Web Service 107 107 107 108 108 109 109 111 111 Table of Contents Chapter 7 Chapter 8 Chapter 9 The getDocumentInfo Method ......................................................................... Syntax ....................................................................................................... Parameters ................................................................................................. 112 113 113 ...................................................................... What Types of Output are Counted? ................................................................ Output Statistics Report Details ....................................................................... Summary Report Content ........................................................................... Summary and Detail Report Content ........................................................... Batch Details .......................................................................................... Transaction Details ................................................................................. API and Web Services Details .................................................................. Sample Summary and Details Report ....................................................... Output Statistics Reporting Web Services ......................................................... getSummaryPublishingReport..................................................................... Syntax ................................................................................................... Parameters ............................................................................................. getDetailedPublishingReport ...................................................................... Syntax ................................................................................................... Parameters ............................................................................................. getCompressedSummaryPublishingReport .................................................. Syntax ................................................................................................... Parameters ............................................................................................. getCompressedDetailedPublishingReport .................................................... Syntax ................................................................................................... Parameters ............................................................................................. clearDetailPublishingReport ........................................................................ Syntax ................................................................................................... Parameters ............................................................................................. 115 Output Statistics Reporting xPressForms Web Services for Reporting 115 116 117 118 118 119 119 120 121 121 121 122 122 122 123 123 123 123 125 125 125 126 126 126 ................................................ 127 Get Report Method ......................................................................................... Syntax ....................................................................................................... Parameters ................................................................................................. 127 127 127 Get Report For Fields Method ......................................................................... Syntax ....................................................................................................... Parameters ................................................................................................. 129 129 129 Search for Forms Method ................................................................................ Simple Search Criteria ................................................................................ Advanced Search Criteria ............................................................................ Syntax ....................................................................................................... Parameters ................................................................................................. Search for Forms Customized View Method ..................................................... Simple Search Criteria ................................................................................ Advanced Search Criteria ............................................................................ Syntax ....................................................................................................... Parameters ................................................................................................. 130 130 131 132 132 132 133 134 134 135 Get Search Field List Method ........................................................................... Syntax ....................................................................................................... Parameters ................................................................................................. Return Value .............................................................................................. 135 135 135 135 Deprecated xPressForms Web Services ............................................................. 136 ...................................................... 137 RESTful HTTP Body Structure......................................................................... 137 xPression RESTful Services for Batch 7 Table of Contents Chapter 10 8 The General.security Element .......................................................................... Authorization ............................................................................................. 139 139 The Job.start.xml and Job.start Elements........................................................... The Job Element ......................................................................................... The xPressionPublishJob Element ................................................................ The JobOption Element ............................................................................... 140 140 140 141 The Job.status Element .................................................................................... Syntax ....................................................................................................... Returned Information ................................................................................. Common Data ....................................................................................... Statistics with Details Data ...................................................................... Statistics with Errors Data ....................................................................... Sample Responses for Job.Status .................................................................. Completed Job with “Statistics” Reporting Level ...................................... Completed Job with “Statistics with Details” Reporting Level.................... Stopped Job with “Statistics with Errors” Reporting Level ......................... Job That is Not Started ............................................................................ Job That is Still Running .......................................................................... 141 141 142 142 143 144 144 144 145 146 147 147 The Job Queue All Element ............................................................................. Syntax ....................................................................................................... Returned Information ................................................................................. 147 147 148 Return a List of all Job Names ......................................................................... 149 Return a List of all Queued Jobs....................................................................... 150 Return a List of all Running Jobs...................................................................... Return the Status of a Particular Job ................................................................. 150 151 Start a Batch Job with an Existing Job Definition ............................................... 152 Start a Batch Job with a Job Definition XML File................................................ Configuring xPression for RESTful Batch Services ............................................ Enable xPression for Concurrent Batch Processing ........................................ Configure Servers for RESTful Service Batch Processing ................................ Service Notification .................................................................................... 153 154 154 155 155 ......................................................... Web Services .................................................................................................. Authentication ........................................................................................... About the requestContext Parameter ....................................................... requestContext Examples .................................................................... Access Rights for Document Item Web Services ............................................ createDocumentItem................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. createAuthenticationToken.......................................................................... Syntax ................................................................................................... Parameters ............................................................................................. publishAndReturnDocumentItem ............................................................... Syntax ................................................................................................... Parameters ............................................................................................. deleteDocumentItem .................................................................................. Syntax ................................................................................................... Parameters ............................................................................................. Example................................................................................................. reassignDocumentItemToUser..................................................................... Syntax ................................................................................................... Parameters ............................................................................................. documentItemsAssignedToUser .................................................................. 159 xDesign Online Editor Web Services 159 160 160 160 161 162 162 162 163 163 163 164 164 164 165 165 165 165 166 166 166 167 Table of Contents Chapter 11 Syntax ................................................................................................... Parameters ............................................................................................. searchDocumentItems ................................................................................ Syntax ................................................................................................... Parameters ............................................................................................. Example................................................................................................. unlockDocumentItem ................................................................................. Syntax ................................................................................................... Parameters ............................................................................................. addAnnotation ........................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Example................................................................................................. getDocumentItemInfo ................................................................................. Syntax ................................................................................................... Parameters ............................................................................................. Example................................................................................................. openDocumentItem .................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Example................................................................................................. submitDocumentItem ................................................................................. Syntax ................................................................................................... Parameters ............................................................................................. rejectDocumentItem ................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. approveDocumentItem ............................................................................... Syntax ................................................................................................... Parameters ............................................................................................. documentItemsAssignedToUserReturnInfo .................................................. Syntax ................................................................................................... Parameters ............................................................................................. searchDocumentItemReturnInfo .................................................................. Syntax ................................................................................................... Parameters ............................................................................................. copyDocumentItem .................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. addExternalContentByStream ..................................................................... Syntax ................................................................................................... Parameters ............................................................................................. addExternalContentByLink ......................................................................... Syntax ................................................................................................... Parameters ............................................................................................. deleteExternalContent ................................................................................ Syntax ................................................................................................... Parameters ............................................................................................. Clean Up xDesign Online Editor Temp Folders ............................................. 167 167 167 168 168 169 170 170 171 171 171 171 172 172 173 173 174 175 176 176 176 177 178 178 178 178 178 179 180 180 180 181 181 182 182 182 184 184 184 185 186 186 186 187 187 188 188 188 188 ................................................ Before You Begin ............................................................................................ Internet Explorer Settings ............................................................................ User Configuration ..................................................................................... How xEditor Handles Updates ........................................................................ Running xEditor the First Time ....................................................................... Installing xEditor ........................................................................................ Pushing the xEditor Installation from the Server ........................................... 191 The xPression DevKit xEditor Component 191 191 192 192 192 193 193 9 Table of Contents 10 Opening xEditor After “Failed to start editor. Exception from HRESULT: 0x8004063B” ................................................................................. 194 The xEditor Interface ...................................................................................... The Document Actions Pane........................................................................ The xEditor Toolbar .................................................................................... The Table of Contents Section ...................................................................... TOC Icons .............................................................................................. The Information Panel ................................................................................ The Command Bar...................................................................................... The xEditor Menu....................................................................................... 194 194 195 196 197 198 199 199 Deleting and Undeleting Revision Units........................................................... 199 Optional Content ............................................................................................ 200 Localization ................................................................................................... 200 xEditor Functions ........................................................................................... 200 Cache Management ........................................................................................ 201 The Log ......................................................................................................... 201 Finding Existing Content ................................................................................ xEditor’s Find Utility .................................................................................. Microsoft Word Find and Replace ................................................................ 202 202 203 Adding New Content ..................................................................................... 204 Using xEditor ................................................................................................. Closing xEditor .......................................................................................... Track Changes ............................................................................................ Local Files .................................................................................................. Microsoft Word Features and Functions ....................................................... Hidden Table Borders ............................................................................. Editing Actions in xEditor ....................................................................... Form Fields ................................................................................................ Protection .................................................................................................. Read Only Protection .................................................................................. 204 205 205 205 206 208 208 208 210 211 Configuring Microsoft Word Ribbons .............................................................. Language Specific Configuration Files ......................................................... Element Properties ..................................................................................... Excluded, Repurposed, and Unsupported Commands .................................. 212 213 213 214 Opening a Work Item in xEditor ...................................................................... Table and Paragraph Merge ......................................................................... Content Separators ..................................................................................... Merged Paragraphs and Content Separators ............................................. Variables .................................................................................................... Variable Scope ........................................................................................ Selecting Variables .................................................................................. Editing Variables .................................................................................... Copy and Paste ...................................................................................... Drag and Drop ....................................................................................... Variable Formats .................................................................................... Protection and Variables ......................................................................... Variable Navigator ................................................................................. Subtotals, Index Headings, and Table Headings and Footers ......................... Variables in Optional Content...................................................................... Purging WIP Work Items ............................................................................ Carry Forward ............................................................................................... Opening Carry Forward .............................................................................. Review Helper ........................................................................................... The Carry Forward Review Pane ................................................................. 218 218 218 218 218 220 220 224 226 226 226 227 227 228 228 228 228 229 229 230 Table of Contents Chapter 12 Chapter 13 The Carry Forward Review Toolbar ......................................................... The Document Structure Tree .................................................................. The Information Panel ............................................................................ Editing Content in Carry Forward ........................................................... Working with Variables in Carry Forward ................................................ Headers and Footers in Carry Forward ................................................... Revision Numbers ...................................................................................... Revision Numbering Outside Carry Forward ........................................... Revision Numbering in Carry Forward .................................................... The Editor Log ........................................................................................... The Auto Carry Forward Log ...................................................................... 230 231 232 234 235 236 236 236 237 237 237 .......................................................................... Access Rights ................................................................................................. The xCatalog Interface .................................................................................... Menu Bar ................................................................................................... The File Menu ........................................................................................ The Edit Menu ....................................................................................... The Help Menu ...................................................................................... Browse and Search Pane.............................................................................. Browse Pane........................................................................................... Adding a Tag or Folder ....................................................................... Renaming a Tag or Folder ................................................................... Deleting a Tag or Folder ...................................................................... Copying and Pasting a Tag or Folder.................................................... Marking a Folder as Required ............................................................. Search Pane ............................................................................................ Advanced Search ................................................................................ Example......................................................................................... Staging Area Pane .................................................................................. Document List ............................................................................................ Document Detail Area ................................................................................ Information Tab ...................................................................................... Tags Tab ................................................................................................. Notes Tab ............................................................................................... Custom Fields Tab .................................................................................. Properties Tab ........................................................................................ Using xCatalog ............................................................................................... Login ......................................................................................................... Importing and Exporting Documents ........................................................... Importing Documents ............................................................................. Troubleshooting - Importing Large Files............................................... Exporting Documents ............................................................................. Working with Documents ........................................................................... Adding Tags to Documents ..................................................................... Changing Document Status ..................................................................... Deleting Documents ............................................................................... Managing Custom Fields ............................................................................ Adding Fields ........................................................................................ Renaming a Field .................................................................................... Defining or Changing a Field’s Default Value ........................................... Deleting a Custom Field .......................................................................... Creating Document Reports ........................................................................ Logging Out ............................................................................................... 239 The xCatalog Component 239 240 240 240 241 241 242 242 242 243 243 243 244 244 246 247 247 248 248 249 249 249 250 250 251 251 251 252 252 253 253 253 254 254 255 255 256 256 256 257 258 .................................................................................. 259 xPression Server Components ......................................................................... 259 System Architecture 11 Table of Contents Chapter 14 12 The xPression Assembly Engine .................................................................. The xPression Publishers Engine ................................................................. The xPublish Engine ............................................................................... Distribution Controller Engine .................................................................... Execution Architecture............................................................................ Distribution Types .................................................................................. xPression Batch Engine ............................................................................... 260 260 261 262 262 262 262 xFramework Components ............................................................................... WebServices API ........................................................................................ Java API ..................................................................................................... EAI Adapter ............................................................................................... xPression Web Services ............................................................................... xPression Java API ...................................................................................... 263 263 263 263 263 264 xPression Integration Strategies ....................................................................... Real-Time Interaction.................................................................................. Real-Time Interaction - APIs.................................................................... Real-Time Interaction - Portals................................................................. Near-Time Interaction ................................................................................. Batch Interaction ........................................................................................ xPression Integration Decision Tree ............................................................. 264 265 265 265 265 266 266 ......................................................... Before You Begin ............................................................................................ Initial Questions ......................................................................................... Adding Your Application Definition ............................................................ Configuring Your Application with xAdmin................................................. Associating Attribute Sets with Your Application ..................................... Assigning Data Sources to Your Application ............................................ Setting Up Access Rights for Your Application ......................................... Configuring Workflow for Your Application............................................. Authentication and Access Control .............................................................. Authentication ....................................................................................... Access Control ....................................................................................... Logging ..................................................................................................... Licensing ................................................................................................... Using WebServices with xPresso Packages ....................................................... Web Services Processing Diagram .................................................................... The Document Requester Web Service ............................................................. Requesting a Document by Customer Key.................................................... Syntax ................................................................................................... Parameters ............................................................................................. Requesting a Document by XML Customer Data .......................................... Syntax ................................................................................................... Parameters ............................................................................................. Request Document by Output Profile ........................................................... Syntax ................................................................................................... Parameters ............................................................................................. The Document Composer Web Service ............................................................. The Compose Document Method ................................................................ Syntax ................................................................................................... Parameters ............................................................................................. The xPression Request Web Service ................................................................. The Publish Document Method ................................................................... Syntax ................................................................................................... Parameters ............................................................................................. The Preview HTML Method ........................................................................ 267 Deprecated xPression Web Services 267 268 268 269 269 270 270 270 271 271 271 271 271 271 272 273 273 273 274 274 275 275 276 277 277 277 278 278 278 278 279 279 280 280 Table of Contents Syntax ................................................................................................... Parameters ............................................................................................. The Preview PDF Method ........................................................................... When Used with xPublish Documents ..................................................... Username and Password Filter ................................................................ Syntax ................................................................................................... Parameters ............................................................................................. The View Categories for User Method.......................................................... Syntax ................................................................................................... Parameters ............................................................................................. The View Documents in Category Method ................................................... Syntax ................................................................................................... Parameters ............................................................................................. The View Output Profiles for Document Method .......................................... Syntax ................................................................................................... Parameters ............................................................................................. The Get BDT Method .................................................................................. Syntax ................................................................................................... Parameters ............................................................................................. The Get Assembled Document Method ........................................................ Syntax ................................................................................................... Parameters ............................................................................................. The Publish MSOHTML Document Method ................................................. Syntax ................................................................................................... Parameters ............................................................................................. The Publish And Return Document Method ................................................. Syntax ................................................................................................... Parameters ............................................................................................. 280 281 281 281 281 282 282 282 282 282 283 283 283 283 284 285 285 285 285 286 286 286 286 286 287 287 287 288 The xResponse Web Service............................................................................. The Assign Document to User Method ......................................................... Syntax ................................................................................................... Parameters ............................................................................................. The Retrieve Work In Progress IDs Assigned to a User Method ..................... Syntax ................................................................................................... Parameters ............................................................................................. The Reassign Work Item Method ................................................................. Syntax ................................................................................................... Parameters ............................................................................................. The Create Work Item Method .................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Publish and Return Document .................................................................... Syntax ................................................................................................... Parameters ............................................................................................. The Revise Request Web Service ...................................................................... The Assign Document To User Method ........................................................ Syntax ................................................................................................... Parameters ............................................................................................. The Retrieve Work In Progress IDs Assigned to a User Method ..................... Syntax ................................................................................................... Parameters ............................................................................................. The Reassign Work Item Method ................................................................. Syntax ................................................................................................... Parameters ............................................................................................. The Query Work ItemStatus Method ............................................................ Syntax ................................................................................................... Parameters ............................................................................................. The Complete Item Method ......................................................................... 288 288 289 289 290 290 290 290 291 291 291 291 292 292 292 292 293 293 293 293 294 294 294 295 295 295 296 296 296 296 13 Table of Contents Chapter 15 14 Syntax ................................................................................................... Parameters ............................................................................................. The Preview Work Item In PDF Method ....................................................... Syntax ................................................................................................... Parameters ............................................................................................. The Update Work Item Primary Data Method .............................................. Syntax ................................................................................................... Parameters ............................................................................................. Returns .................................................................................................. Notes ..................................................................................................... The Delete Work Item Method ..................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Returns .................................................................................................. The Publish and Return Work Item Method ................................................. Syntax ................................................................................................... Parameters ............................................................................................. Returns .................................................................................................. 296 296 297 297 297 297 297 298 298 298 298 299 299 299 299 299 299 300 Errors ............................................................................................................ 300 ......................................................... Writing an XPression Facade Java Class ........................................................... Objectives .................................................................................................. Dependencies ............................................................................................. Creating a Simple Properties File ................................................................. Connecting to xPression .............................................................................. Retrieving Categories.................................................................................. Retrieving Document Names....................................................................... Retrieving a Document ............................................................................... Writing a Quote Generator Application ............................................................ Objectives .................................................................................................. Dependencies ............................................................................................. Initial Setup ............................................................................................... Creating Standard Header and Footer Pages ................................................ Presenting a List of Categories ..................................................................... Presenting a List of Documents ................................................................... Presenting Input Fields ............................................................................... Generating a PDF Quote ............................................................................. Summary ................................................................................................... Deploying an xPression Application ................................................................ J2EE Application Assembly ......................................................................... J2EE Web Application Overview ................................................................. J2EE Enterprise JavaBeans Overview ........................................................... J2EE Utility Classes Overview ..................................................................... Web Application Archive Construction ........................................................ Command Reference ...................................................................................... Method Name ............................................................................................ Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... The XPressionFacade Class ............................................................................. getAppName ............................................................................................. Syntax ................................................................................................... Sample................................................................................................... getBusinessDocuments ............................................................................... Syntax ................................................................................................... 301 The Deprecated xPression Java API 301 301 302 302 302 304 305 305 306 306 307 307 308 309 311 313 315 320 320 320 321 321 321 322 323 323 323 323 324 325 325 325 325 325 326 Table of Contents Parameters ............................................................................................. Sample................................................................................................... getCategories ............................................................................................. Syntax ................................................................................................... Sample................................................................................................... getDocumentPackedMSOHTML ................................................................. Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... getDocumentPackedMSOHTML (overloaded) .............................................. Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... getDocumentPDF ....................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... getDocumentPDF (overloaded) ................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... getHaveStartSession ................................................................................... Syntax ................................................................................................... Sample................................................................................................... getOutputProfiles ....................................................................................... Syntax ................................................................................................... Sample................................................................................................... getSchema.................................................................................................. Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... getStartSession ........................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... initServerConnection .................................................................................. Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... setStatus .................................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. publishDocument ....................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... publishDocument (overloaded) ................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Sample................................................................................................... 326 326 326 326 326 328 328 328 328 329 329 329 330 331 331 331 331 332 332 332 334 334 334 334 335 335 335 336 336 336 336 336 336 337 337 337 337 337 338 338 338 338 339 339 339 339 340 340 340 341 Ending a Session ............................................................................................ removeSession() ......................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. The XPressionDocument Class ........................................................................ getDocumentData....................................................................................... Syntax ................................................................................................... Sample................................................................................................... 342 342 342 342 342 342 342 343 15 Table of Contents Chapter 16 16 getDocumentFormat ................................................................................... Syntax ................................................................................................... Sample................................................................................................... getDocumentName..................................................................................... Syntax ................................................................................................... Sample................................................................................................... 343 343 343 344 344 344 xPression Facade Exceptions ........................................................................... XPressionFrameworkException ................................................................... NoAuthorizedRightException ................................................................. NoStartSessionException ........................................................................ NoSuchTargetException .......................................................................... XPressionEJBException ........................................................................... XPressionProcessException ..................................................................... 345 345 345 345 345 347 347 The Deprecated xPression EAI Adapter .................................................... 349 xAdapter Architectural Overview .................................................................... Listener Technology .................................................................................... Request Processor ....................................................................................... xPression Batch Wrapper ............................................................................ Transformation Engine................................................................................ 350 350 350 350 351 xAdapter Deployment Architecture ................................................................. 351 xAdapter Components .................................................................................... Web Services Integration ............................................................................. Publish Document Web Service Method ................................................... Preview PDF Web Service Method ........................................................... Post For Batch Web Service Method ......................................................... Categories For User Web Service Method ................................................. Documents For Category Web Service Method ......................................... Output Profiles For Document Web Service Method ................................. Variables for Document Web Service Method ........................................... JMS-Based Messaging Mechanism ............................................................... Publish Document Message..................................................................... Preview PDF Message............................................................................. Post For Batch Message ........................................................................... XML Message Error Handling ..................................................................... Malformed XML ..................................................................................... Request Type Not Supported ................................................................... XML Missing a Required Parameter ......................................................... Transformation Engine................................................................................ Example property file settings ................................................................. Using UTF–8 Format for Adapter Properties ............................................ XML File Export for Batch Execution ........................................................... 351 352 352 353 354 354 355 356 356 357 358 361 363 367 367 368 368 368 369 370 371 Adapter Configuration Information ................................................................. 374 Creating the Adapter Application .................................................................... Adding Your Application Definition ............................................................ 375 375 Configuring Your Application with xAdmin..................................................... Associating Attribute Sets with Your Application ......................................... Assigning Categories to Your Application .................................................... Assigning Data Sources to Your Application ................................................ Setting Up Access Rights for Your Application ............................................. Configure Your Batch Scripts ........................................................................... 376 376 377 377 377 377 Verifying Your Installation .............................................................................. JMS ........................................................................................................... 378 378 XML Files ...................................................................................................... Publish Document ...................................................................................... 380 380 Table of Contents Appendix A Appendix B Preview with PDF ...................................................................................... Post for Batch ............................................................................................. 381 382 Error Messages ............................................................................................... Error Descriptions ...................................................................................... Event Descriptions...................................................................................... 383 385 387 The Webtool Utility .................................................................................... 389 Registering Webtool.dll ................................................................................... 389 The Encryption Utility .................................................................................... encrypt ...................................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Java Sample ........................................................................................... Visual Basic ............................................................................................ decrypt ...................................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Java ....................................................................................................... Visual Basic ............................................................................................ 389 390 390 390 390 390 391 391 391 391 391 The Pack Utility .............................................................................................. pack .......................................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Java ....................................................................................................... Visual Basic ............................................................................................ unpack....................................................................................................... Syntax ................................................................................................... Parameters ............................................................................................. Java ....................................................................................................... Visual Basic ............................................................................................ 392 392 392 392 392 393 393 393 394 394 394 ....................................................................................... The Complete AppList.dtd .............................................................................. The AppList and Application Elements ........................................................ The WorkFlow Element............................................................................... The AccessRights Element ........................................................................... The RequiredAttributes and Attr Elements ................................................... A Complete AppList.xml Example................................................................... 397 The AppList DTD 397 398 399 399 400 401 17 Table of Contents List of Figures Figure 1. xEditor works with Microsoft 2007 (shown) and 2010. The xEditor Task Pane is the same for both versions. ................................................................... 194 Figure 2. The following graphic shows the xPRS Server engine simplified data flow. ............ 260 Figure 3. The following graphic shows the xPublish engine simplified data flow. ................. 261 Figure 4. The following graphic shows the batch engine execution architecture. ................... 263 Figure 5. There are three main xPression integration strategies: Real-Time (Request/Reply), Near-Time, and Batch. This diagram shows how xFramework integrates with the xPRS server. ................................................... 264 Figure 6. The following image shows the document requester functional flow. ..................... 272 Figure 7. On your development machine create a folder structure that resembles the following image, which shows the Quote_Gen.war folder structure. ............. 307 Figure 8. The resulting page should look like this when launched in your browser. .............. 311 Figure 9. The resulting GetDocuments.jsp page should look like this when launched in your browser................................................................................ 313 Figure 10. Figure 11. Figure 12. Figure 13. The resulting GetInputs.jsp page should look like this when launched in your browser. This graphic only shows a sampling of the user input fields displayed on getInputs.jsp. ..................................................................... The resulting Preview.jsp page should look like this when launched in your browser. ................................................................................................. The following image shows the J2EE application assembly. ................................... 315 320 320 These components and their relationships are shown in the diagram and discussed below. ........................................................................................... 350 Figure 15. The xAdapter, deployed on a WebSphere cluster of two Windows servers, would look like the following image. ................................................... The following image shows how to edit the batchrunner.bat file. ........................... 351 378 Figure 16. The following image shows how to retrieve the WDSL. ......................................... 378 Figure 17. Figure 18. The following image shows testing the JMS. ......................................................... The following image shows the WebSphere Embedded Messaging page. ............... 379 380 Figure 14. 18 Table of Contents List of Tables 19 Table of Contents 20 Revision History Revision Date Description May, 2015 Updated the syntax of unlockDocumentItem. June, 2014 Initial publication. 21 Preface 22 Chapter 1 Introduction Welcome to xFramework. This book is geared towards intermediate or higher level programmers. Information Boxes The 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 may occur 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 describe an 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 Support For more information or to solve a problem, contact EMC Document Sciences Technical Support: Online Support: https://support.emc.com Telephone Support: http://www.emc.com/collateral/contact-us/h4165-csc-phonelist-ho.pdf United States: 800–782–4362 Canada: 800–543–4782 Worldwide: +1–508–497–7901 23 Introduction 24 Chapter 2 About xFramework and the xPression DevKit API With version 4.0, xPression introduces a new Web Service API that conforms to the WS-I Basic Profile. The old xFramework Web Service API, Java API, and xAdapter have been deprecated. Although these items will be supported for backward compatibility in the current version, EMC Document Sciences encourages you to use the new Web Service API as it offers better performance, greater flexibility, and better security. Please review the following topics: • What Has Changed?, page 25 • Authentication , page 26 • Setting Up Your Application, page 28 • IQuickDoc Configuration, page 31 • Error Messages, page 32 • The CompuSet Bridge, page 32 • xPressionHome, page 32 What Has Changed? When the original xPression API was developed, it conformed to generally accepted SOAP standards. These standards have undergone significant changes in recent years, which created the need for an updated API. The new API provides many improvements and enhancements to the old API. In this new design, xPression provides the IQuickDoc and IDocumentItem Web Services. The IQuickDoc Web Service is a set of Web Service methods that provide the simplest and most commonly used xPression services. They are delivered as part of any xPression installation. IDocumentItem is an xPression DevKit Web Service. xPression DevKit is an extension of iQuickDoc for solutions-specific functions. It is an add-on feature that can be purchased separately from EMC Document Sciences. The new xPression Web Services API contains the following changes over the old API: • Web Services-only API — The new API does not use the old Java API or the EAI Adapter. All coding is done through Web Services. • New flexible authentication model — For more information, see Authentication , page 26. 25 About xFramework and the xPression DevKit API • Embedded components — xPression DevKit enables you to embed components into your application. • Improved error messages and codes — For more information, see Error Messages, page 32. • New xPressForms Web Service methods for xPressForms users — For more information, see Chapter 8, xPressForms Web Services for Reporting. Note: xPression DevKit is known formally as the Interactive Document Development Kit (IDDK). Authentication xPression uses a new authentication model that enables easier integration with a variety of single sign-on products and security models. All entry points into xPression will take an XML document which contains user credentials and any other information needed to authenticate and authorize the request. You can specify these credentials in any compatible format, for example: encrypted, plain text, and token. The XML document is passed through the requestContext parameter that must be defined for all Web Service calls. This new authentication model eliminates the need to pass hard-coded parameters for every security-sensitive request, and enables you to integrate without having to change the signature of any xPression entry points. It also enables you to create Java User Exit code to perform more sophisticated integrations. Note: Single Sign-On (Trusted UserID/Groups) can only be used when the enableTrustedUser parameter in the systemconfig.properties file is set to True. This properties file is located in your xPressionHome directory. By default, this directory is C:\xPression and is located on your server. About the requestContext Parameter This parameter is used in all Web Service methods. It enables you to pass an XML document containing user credentials for authentication. It also passes the name of the xPression application for which the user is authenticated. In xPression, users are granted access rights to specific applications because some applications have different sets of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. In general, for core xPression services (client and server functions), you can supply credentials for the user under any application for which the user is authenticated. For solution applications (xPressForms, xPression DevKit, xResponse, xRevise), you must supply credentials for the exact application you are using. The xPression Web Service methods that use the requestContext parameter can determine the application name even if you do not supply the name in the parameter. xPression uses the following logic, based on the type of document you are using, to determine the application name: • CompuSet Documents — xPression chooses xPression Design as the application. • xPublish Documents — xPression chooses xPression Design as the application. 26 About xFramework and the xPression DevKit API • xPresso for InDesign Documents — xPression chooses Adobe InDesign as the application . • xPresso for Word Documents — xPression chooses Microsoft Word as the application. • xPresso for Dreamweaver Documents — xPression chooses Adobe Dreamweaver as the application. Using requestContext with Documentum-Based Documents When attempting to access documents stored on a Documentum repository, ensure that the user in the requestContext parameter passes both xPression server authentication (usually LDAP or NT authentication) as well as Documentum authentication. This means that the user name should exist on both the server and the Documentum Repository. To publish a document on Documentum, the user needs to have the Documentum role of xpression_dashboard. Additionally, do not use the element when accessing Documentum-based documents through Single Sign-On (Trusted UserID and Groups). Example: t1 requestContext Examples The following examples show how to structure your XML document for the requestContext parameter. Unencrypted userid/password John pass xPression Framework Weak encrypted userid/password A23B45C67 27 About xFramework and the xPression DevKit API A2KS4SLDK6DKOQWI xPression Response Single Sign-On (Trusted UserID/Groups) John Administrator xPression Design User xPression Revise User xPression Revise Setting Up Your Application When you create your own application, you must add that application to the applist.xml file stored on your server. This file contains a list of the xPression applications installed in your environment. It also contains attribute, workflow, and access rights information for the xPression applications defined to this file. The xPression installation program generates this file upon installation. Creating a new application name is optional. For the vast majority of users, one of the existing application names will be sufficient. Adding Your Application Definition To add the application definition to AppList.xml: 1. Locate AppList.xml on your xPression server. It is located in the xPressionHome directory. By default, this file is stored in: C:\xPression. 2. Open the file for editing. 28 About xFramework and the xPression DevKit API 3. Type the application element between the tags. Your application name must not contain apostrophes (’). For example: 4. If your application supports workflow, type the workflow element. For example: 5. Type the access rights your application supports, including whether or not they’re hierarchical. For example: 6. Type the required attributes, if any. For example: 7. Type the closing element at the bottom of your application definition. 8. Save AppList.xml and exit your text editor. Once complete, your application definition should appear similar to the following: 29 About xFramework and the xPression DevKit API This sample application definition has workflow and access rights, but no required attributes. Configuring Your Application with xAdmin Now that you’ve added your application definition to AppList.xml, it’s time to configure it with xAdmin. To configure your application in xAdmin, complete the following steps: 1. Associating Attribute Sets with Your Application, page 30 2. Assigning Data Sources to Your Application, page 30 3. Setting Up Access Rights for Your Application, page 31 4. Configuring Workflow for Your Application, page 31 (optional) Associating Attribute Sets with Your Application Before you can configure categories, data sources, access rights, and workflow for your application, you must first associate one or more attribute sets with your application. To associate attributes with your application: 1. Start xAdmin. 2. Click Category Management, then Attribute Sets. 3. Click an attribute set that you want to associate with your application. When you click the attribute set name, the Attribute Set page appears. Alternatively, you can also create a new attribute set. For more information about creating attribute sets, see the xAdmin User Guide. 4. Select your application from the list and click Save. 5. To assign more categories to your application, repeat steps 1 - 4. Assigning Data Sources to Your Application To assign data sources to your application: 1. Select a category you’ve already assigned to your application. 2. Click the Data Sources tab. 3. Select a data source group from the list and click Set Application. 4. Select your application from the drop-down list. 5. A page appears that enables you to associate your available data sources with your application. Select the data sources you want to assign to your application and click Add. 6. In the Default Data Source list, select a default data source for your application and click Save. 7. To assign additional data sources to your application, repeat steps 2 - 7. 30 About xFramework and the xPression DevKit API Setting Up Access Rights for Your Application To set up access rights for your application: 1. Click the Access Rights tab for a category you’ve assigned to your application. 2. Click view/change for your application, then click Add. 3. Select users from the list of available users and click Add. The users will appear in the Selected Users list. 4. Click Save. The selected users for the category now have access to your application. 5. When the list of users reappears, select the access levels for each user and click Save. 6. To add additional users, repeat steps 1 through 5. Configuring Workflow for Your Application If your application supports workflow, you can configure your application to assign users as submitters and approvers. Please consult the xAdmin User Guide to assist you in setting up workflow for your application. IQuickDoc Configuration IQuickDoc Web Services users should correct an Axis2 bug before implementing the IQuickDoc Web Services. Failing to perform this manual update can cause errors if you use HTTP Binding and attempt to validate the WSDL. To perform the update, complete the following steps: 1. Open the WSDL for editing. The IQuickDoc Web Service WSDL can be found here: http://:/xFramework/services/QuickDoc?wsdl 2. In the HTTP Binding section of the WSDL, change the value of the part attribute to parameters for each operation. For example: 3. Add the SOAPFaultException element for each operation. For example: 31 About xFramework and the xPression DevKit API 4. Save and close the file. Error Messages Each Web Service returns error messages in the following format: - For example: 3143 - Unable to retrieve the next customer record. Check the connection to the customer data source. The CompuSet Bridge The CompuSet Bridge is an optional feature that enables xPression users with legacy CompuSet applications to leverage their CompuSet assets with xPression. Several web services have been provided for use with this option. Since the CompuSet Bridge requires a license and is intended for implementation with legacy products, details of these web services are provided with the CompuSet Bridge documentation. Refer to the xPression CompuSet User Guide for more information. xPressionHome The term “xPressionHome” refers to the location where xPression was installed on your server. By default on Windows servers, the location is C:\xPression, but your installer may have selected a different location during installation. Please consult with your administrators or IT personnel to determine the location where they installed xPression. Throughout the xPression documentation, we will refer to this location as “xPressionHome”. 32 Chapter 3 The IQuickDoc Web Service The IQuickDoc Web Service provides access to the simplest and most commonly used xPression services. Because IQuickDoc uses simple signatures, the WSDL can be easily consumed by any SOAP toolkit implementing the WS-I Basic Profile. As a Web Service with a simple signature, IQuickDoc makes no use of complex types. These Web Service methods are easy to implement and can help you get started integrating with xPression very quickly. All xPression customers have access to the IQuickDoc Web Service. This Web Service can be used by Documentum Edition and Enterprise Edition customers. If you are working with xPresso for Word documents in workflow enabled categories, please see xPresso for Word Documents in Workflow Enabled Categories, page 34. Note: DataDirect xQuery APIs are not supported in the IQuickDoc Web Service. The IQuickDoc Web Service WSDL can be found here: http://:/xFramework/services/QuickDoc?wsdl The IQuickDoc WSDL contains the following methods: • The categoriesForUser Method, page 34 • The documentsForCategory Method, page 35 • The descriptionForDocument Method, page 35 • The thumbnailForDocument Method, page 37 • The designToolForDocument Method, page 38 • The outputProfilesForDocument Method, page 39 • The versionsForDocumentWithWorkflowStatus Method, page 40 • The publishDocument Method, page 42 • The publishDocuments Method , page 44 • The publishAndReturnDocument Method, page 47 • The publishAndReturnDocumentMultipleStream Method, page 49 • The getDataCollectionTemplate Method, page 53 33 The IQuickDoc Web Service xPresso for Word Documents in Workflow Enabled Categories If you are using xPresso for Word documents that reside in workflow enabled categories, be aware that the web service currently respect only the system level workflow setting on your server. The web services will not override the system level setting with a user level setting. The system level setting determines the lowest level of workflow status that can be published on a given server. This also applies to web services that return information about documents. • pending — The server will publish and web services will return information for any document that is pending or higher. • submitted — The server will publish and web services will return information for only approved and submitted documents. • approved — The server will publish and web services will return information for only approved documents. The categoriesForUser Method The categoriesForUser web service method returns a list of categories that are available to the user whose information is passed in the requestContext parameter. This method may complete successfully without returning any category names if the user has not been given access rights to any xPression categories. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Return Value : This method returns zero or more Strings in a String array. Each String in the array represents the name of a category the user is eligible to access. Syntax String[] categoryNames = categoriesForUser(requestContext) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. 34 The IQuickDoc Web Service The documentsForCategory Method The documentsForCategory web service method returns a list of all xDesign and xPresso documents contained in the defined category. This list is returned as a String array that contains one document name for every document that resides in the defined category. This method can complete successfully without returning any document names, indicating that the category is empty. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Return Value: This method returns zero or more Strings in a String array. Each String in the array represents the name of a document inside the requested category that the user is eligible to access. Syntax String[] documentNames = documentsForCategory(requestContext, categoryName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. categoryName: String A string specifying the name of the category for which you want to list all available documents. The descriptionForDocument Method The descriptionForDocument method retrieves a textual description of a document deployed on the xPression Server. If the document does not have defined description, the method will return a zero length String. You can request the description for a specific version of the document, or for the latest version (highest version number) of the document. To request the latest version, simply request the document using the document name without any including and version information. To request a specific version of the document, supply a version number as shown in the parameters section below. Return Value: A String containing the textual description of the document given as input. If the method fails, the method will return a SOAP Exception with an error code and error message appropriate to the type of error encountered. 35 The IQuickDoc Web Service Syntax String description = descriptionForDocument(requestContext, documentName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. If you are requesting information about an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String A string specifying the name of a document whose description you want to retrieve. • To request the latest version of the document, simply supply the document name. Note: This does not apply to xPresso for Word documents, for which you must supply a specific version number. • To request a specific version of the document, supply the document name and version number as follows: /filename?version=versionnumber where /filename is the name of the document and versionnumber is either a version number or the string “LATEST”. The string “LATEST” selects the highest version number available. For example: /sampledoc?version=2.1 Note: For xPresso for Word documents, you cannot just use the string “LATEST”; a specific version number must be supplied. • If you want to retrieve this information for xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename?version=version where path is the folder path on the repository, filename is the name of the file, and version is the version number. 36 The IQuickDoc Web Service The thumbnailForDocument Method The thumbnailForDocument method retrieves the thumbnail image for a document deployed on the xPression Server. Some documents may not have thumbnails defined. If no thumbnail is defined, the method will complete successfully and return a zero byte length stream. You can request the thumbnail for a specific version of the document, or for the latest version (highest version number) of the document. To request the latest version, simply request the document using the document name without any including and version information. To request a specific version of the document, supply a version number as shown in the parameters section below. Return Value: If successful, this method returns a byte array representing a thumbnail image of the document. If the method fails, the method returns a SOAP Exception with an appropriate error code and message. Syntax byte[] thumbnailImage = thumbnailForDocument(requestContext, documentName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application under which the user is authenticated on the xPression Server. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. If you are requesting thumbnails for an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String A string specifying the name of a document whose thumbnail you want to retrieve. • To request the latest version of the document, simply supply the document name. Note: This does not apply to xPresso for Word documents, for which you must supply a specific version number. • To request a specific version of the document, supply the document name and version number as follows: /filename?version=versionnumber 37 The IQuickDoc Web Service where /filename is the name of the document and versionnumber is either a version number or the string “LATEST”. The string “LATEST” selects the highest version number available. For example: /sampledoc?version=2.1 Note: For xPresso for Word documents, you cannot just use the string “LATEST”; a specific version number must be supplied. • If you want to retrieve this information for xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename?version=version where path is the folder path on the repository, filename is the name of the file, and version is the version number. The designToolForDocument Method The designToolForDocument web service method returns a description of the design tool that created the specified document. Return Value: A String containing the textual description of the design tool which created the specified document. The following list shows examples of valid return values: • xDesign CompuSet — xDesign (CompuSet-based document) • xDesign xPublish — xDesign (xPublish-based document) • xPressoForInDesign — xPresso for Abobe InDesign • xPressoForDW — xPresso for Dreamweaver • xPressoForWord — xPresso for Word (prior to version 4.5) • xWord Designer — xPresso for Word (version 4.5 or later) If the method fails, the method will return a SOAP Exception with an error code and error message appropriate to the type of error encountered. Syntax String designTool = designToolForDocument(requestContext, documentName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. 38 The IQuickDoc Web Service Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. If you are requesting information about an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String A string specifying the name of a document that resides on the xPression Server. This method returns the design tool name of the document specified with this parameter. If you want to retrieve this information for xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename?version=version where path is the folder path on the repository, filename is the name of the file, and version is the version number. The outputProfilesForDocument Method The outputProfilesForDocument method returns a list of output profiles that the xPression administrator has associated with the specified document. In xAdmin, the administrator can associate a subset of output profiles with a document to identify which output profiles are best suited for the particular document. This list is then available to users of xResponse, xRevise, and any custom correspondence application created for use with xPression. Return Value: This method returns a String array that contains one output profile name for every output profile assigned to the specified document. If no output profiles were associated with the document, this method will return all available output profiles. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String[] outputProfiles = outputProfilesForDocument(requestContext, documentName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. 39 The IQuickDoc Web Service Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. If you are requesting information about an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String A string specifying the name of a document that resides on the xPression server. This method will return a list of any output profiles associated with the document specified in this parameter. If you want to retrieve this information for xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename?version=version where path is the folder path on the repository, filename is the name of the file, and version is the version number. The versionsForDocumentWithWorkflowStatus Method The versionsForDocumentWithWorkflowStatus method returns the version number and the workflow status for the specified document. Workflow status applies only to xPresso for Word documents that reside in workflow-enabled categories. This method should only be used with xPresso documents. Return Value: This method returns a String array that contains the version number for each version of the specified document. If you are using this method with xPresso for Word documents, the method also reports the workflow status of the document version (when such information exists). If the xPresso for Word document resides on a Documentum repository or your xPression category does not have workflow functionality enabled, no workflow status will be reported. The version number is reported first followed by the workflow status of the version. Workflow-enabled xPresso for Word example: 1.0 Pending 1.1 Submitted 2.0 Approved If the method fails, it returns a SOAP Fault that indicates the reason for the failure. If the method is used with an xDesign document, xPression will generate an UnsupportedOperationException. Syntax String[] versionWithStatus = versionsForDocumentWithWorkflowStatus (requestContext, documentName) 40 The IQuickDoc Web Service Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. 41 The IQuickDoc Web Service If you are requesting information about an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String A string specifying the name of a document. The document must reside on the xPression Server. The document name string contains the following elements: If you want to access xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename The publishDocument Method The publishDocument method enables you to publish a document. This method is more efficient than publishAndReturnDocument because it does not return any documents back to the caller. This is the best method to use if you do not need to return the document to the calling application. The customer data that you input into this method will be applied to the default data source definition assigned to the category that contains your document. This method is only guaranteed to process one document record of data, so ensure that you send only one record of input data. If multiple records are given as input, the method may try (and fail) to determine and use the first record in the XML customer data. Some types of output profiles are not compatible with some documents. For example, CompuSet documents cannot use xPublish profiles and xPublish documents cannot use CompuSet profiles. xPresso for Dreamweaver documents cannot use output profiles that produce formats other than HTML. xPresso for InDesign documents cannot use output profiles that produce HTML. If you attempt to publish a document through an incompatible output profile, this method will return the error message: 9022-The document with type {Document type}(e.g.xPressoInDesign) can not be supported. Also, InvaildDocumentTypeException will appear in the xPression log. Return Value: A String message confirming the document was successfully published. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String message = publishDocument(requestContext, documentName, customerData, outputProfileName) 42 The IQuickDoc Web Service Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. If you are publishing an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String A string specifying the name of a document you wish to publish. The document must reside on the xPression Server. For documents that reside in the xPression database, use the following URL for documentName: /filename?version=versionnumber where /filename is the name of the document and versionnumber is either a version number or the string “LATEST”. The string “LATEST” selects the highest version number available. For example: /sampledoc?version=2.1 If you want to publish xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename?version=version where path is the folder path on the repository, filename is the name of the file, and version is the version number. customerData : String The value for this parameter depends upon the type of data source assigned to the category that contains the document you want to publish. If your data source is an XML document, you must provide a single record of XML customer data. If your data source is a relational database, you must provide keys for the relational database data source. The following is an example of an XML string containing the key values for a specific customer record: 1 ENGLISH outputProfileName : String A string specifying the name of an output profile valid for use for with the specified document. The output profile must reside on the xPression Server. 43 The IQuickDoc Web Service Sample This sample shows how to use the method with a SOAP web service call. UserName Password xPression Response]]> Pay Pilot Check Stub PayPilot [email protected] 3 1 0046668888 Refund Death 100 4 2 0046669999 Loan Death 200 ]]> The publishDocuments Method The publishDocuments method immediately publishes documents according to variable data XML passed in as a parameter of the method. The method call will not return until all records in the variable data are processed, so take care to limit the amount of variable data passed or the web service method may time out. This service does not support xPresso for Dreamweaver packages. If the method is successful, a String message will be returned indicating the name of the document and the output profile used. If the method fails it generates an AxisFault. 44 The IQuickDoc Web Service Syntax publishDocuments(String requestContext, String[] documentPackageNames, String outputProfileName, String customerData) Parameters requestContext: String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. If you are requesting information about an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentPackageNames: String An array of strings that contains the names for the packages you want to publish. These document packages must already be deployed on the xPression Server, and they must each use the same schema file. The package names must not include the file extension. 45 The IQuickDoc Web Service For documents that reside in the xPression database, use the following URL for documentName: /filename?version=versionnumber where /filename is the name of the document and versionnumber is either a version number or the string “LATEST”. The string “LATEST” selects the highest version number available. For example: /sampledoc?version=2.1 outputProfileName: String The name of the publish profile to use when publishing the document package. The publish profile must be defined in advance. customerData: String An XML document containing variable data which conforms to the XML schema required by the document packages selected. Sample This sample shows how to use the method with a SOAP web service call. UserName Password xPression Response]]> Pay Pilot Check Stub Pay Pilot Statement Pay Pilot Summary PayPilot [email protected] 3 1 0046668888 Refund Death 100 4 2 0046669999 Loan Death 200 ]]> 46 The IQuickDoc Web Service The publishAndReturnDocument Method The publishAndReturnDocument method enables you to publish a document and return it to your calling application. When calling this method, you supply the document name, the customer data, and the name of the output profile with which to publish the document. In order to successfully return the document to your calling application, the output profile you specify must contain an output stream whose distribution definition is defined with the “Return to Calling Application” option. If no output streams are defined with a distribution definition marked as “Return to Calling Application”, the method will return a zero length byte array when such documents are successfully published. If more than one output stream contains a distribution definition marked as “Return to Calling Application”, this method selects any one of the defined output profiles. You cannot control which output profile it selects.When the job completes, the xPression Server will notify the URL defined in the Listener with the following XML structured message The customer data that you input into this method will be applied to the default data source definition assigned to the category that contains your document. This method is only guaranteed to process one document record of data, so ensure that you only send one record of input data. If multiple records are given as input, the method may try (and fail) to determine and use the first record in the XML customer data. Some types of output profiles are not compatible with some documents. For example, CompuSet documents cannot use xPublish profiles and xPublish documents cannot use CompuSet profiles. xPresso for Dreamweaver documents cannot use output profiles that produce formats other than HTML. xPresso for InDesign documents cannot use output profiles that produce HTML. If you attempt to publish a document through an incompatible output profile, this method will return the error message: 9022-The document with type {Document type}(e.g.xPressoInDesign) can not be supported. Also, InvaildDocumentTypeException will appear in the xPression log. Return Value: This method returns a byte array representing the document that was published and returned. The format of the document is determined by the output profile. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. If your distribution definition does not use the “Return to calling application” option, this method will return a null value. The following code is an example of the SOAP fault code: soapenv:Server 9550-Unexpected error occurred. Please check log for further information. - caused by : null 47 The IQuickDoc Web Service Syntax byte[] document = publishAndReturnDocument(requestContext, documentName, customerData, outputProfileName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. If you are publishing an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String A string specifying the name of a document you wish to publish. The document must reside on the xPression Server. For documents that reside in the xPression database, use the following URL for documentName: /filename?version=versionnumber where /filename is the name of the document and versionnumber is either a version number or the string “LATEST”. The string “LATEST” selects the highest version number available. For example: /sampledoc?version=2.1 If you want to publish xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename?version=version where path is the folder path on the repository, filename is the name of the file, and version is the version number. customerData : String The value for this parameter depends upon the type of data source assigned to the category that contains the document you want to publish. If your data source is an XML document, you must provide a single record of XML customer data. If your data source is a relational database, you must provide keys for the relational database data source. The following is an example of an XML string containing the key values for a specific customer record: 1 ENGLISH 48 The IQuickDoc Web Service outputProfileName : String A string specifying the name of an output profile valid for use for with the specified document. The output profile must reside on the xPression Server. The publishAndReturnDocumentMultipleStream Method The publishAndReturnDocumentMultipleStream method enables you to publish a document and return it to your calling application using multiple streams. When calling this method, you supply the document name, the customer data, and the name of the output profile with which to publish the document. This method only works with xPublish documents. In order to successfully return the document to your calling application, the output profile you specify must contain an output stream whose distribution definition is defined with the “Return to Calling Application” option. If no output streams are defined with a distribution definition marked as “Return to Calling Application”, the method will return a zero length byte array when such documents are successfully published. If more than one output stream contains a distribution definition marked as “Return to Calling Application”, this method returns all the document data associated with those streams. If you want to return document metadata with this method, please define the metadata in the Distribution Definition. The customer data that you input into this method will be applied to the default data source definition assigned to the category that contains your document. This method is only guaranteed to process one document record of data, so ensure that you only send one record of input data. If multiple records are given as input, the method may try (and fail) to determine and use the first record in the XML customer data. Some types of output profiles are not compatible with some documents. For example, CompuSet documents cannot use xPublish profiles and xPublish documents cannot use CompuSet profiles. xPresso for Dreamweaver documents cannot use output profiles that produce formats other than HTML. xPresso for InDesign documents cannot use output profiles that produce HTML. If you attempt to publish a document through an incompatible output profile, this method will return the error message: 9022-The document with type {Document type}(e.g.xPressoInDesign) can not be supported. Also, InvaildDocumentTypeException will appear in the xPression log. Return Value: This method returns a byte array representing the document that was published and returned. The format of the document is determined by the output profile. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. If your distribution definition does not use the “Return to calling application” option, this method will return a null value. 49 The IQuickDoc Web Service Syntax MultiStream multistream= publishAndReturnDocumentMultipleStream(requestContext, documentName, customerData, outputProfileName, includeMetaData) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression application names are valid: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. If you are publishing an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String A string specifying the name of a document you wish to publish. The document must reside on the xPression Server. For documents that reside in the xPression database, use the following URL for documentName: /filename?version=versionnumber where /filename is the name of the document and versionnumber is either a version number or the string “LATEST”. The string “LATEST” selects the highest version number available. For example: /sampledoc?version=2.1 If you want to publish xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename?version=version where path is the folder path on the repository, filename is the name of the file, and version is the version number. customerData : String The value for this parameter depends upon the type of data source assigned to the category that contains the document you want to publish. If your data source is an XML document, you must provide a single record of XML customer data. If your data source is a relational database, you must provide keys for the relational database data source. The following is an example of an XML string containing the key values for a specific customer record: 1 50 The IQuickDoc Web Service ENGLISH outputProfileName : String A string specifying the name of an output profile valid for use for with the specified document. The output profile must reside on the xPression Server. includeMetaData : Boolean If set to true, this method will also return the Generic Index metadata file. The metadata file is an XML formatted index that lists values for all defined output variables in the output stream, and, optionally, media counts. See the documentation for Distribution Definitions in the xAdmin User Guide for more information about this metadata file. If set to false, no metadata is returned. The getTemplateFields Method This method enables you to extract data from an xPresso for Word package. If you use this method without defining any customer data, the method returns data for all the variables used in the specified template. If you supply customer data to the method, the method returns only the data that is not included in the customer data you supplied. This method works exclusively with xPresso for Word documents created in xPression 4.5 or later. It does not support xPresso for Adobe InDesign, xPresso for Dreamweaver, or xDesign. Return Value: This method returns a string that contains data for all the variables used in the specified template. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax getTemplateFields(requestContext, documentName, customerData) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Use “Word” as the application name. This value will grant permissions that are appropriate for your request. For more information, see About the requestContext Parameter, page 26. If you are publishing an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String 51 The IQuickDoc Web Service A string specifying the name of a document. The document must reside on the xPression Server. The document name string contains the following elements: /document_name?version=version_number where document_name is the name of the document, and version_number is the document version number. For example: /document?version=1.2 If you want to select the newest, highest number version, use the following URL: /document?version=LATEST If a version number is not needed, use the following URL, which returns the latest version: /document If you want to access xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename?version=version where path is the folder path on the repository, filename is the name of the file, and version is the version number. customerData : String You can supply existing customer data for this parameter in XML format, or supply NULL for the value. If you supply customer data, this method does not return data for any of the fields that you supplied. If you use NULL, this data returns all the data for the package. For example, if your document contains the following three fields: ,

, , and you supply the field in your customer data, this method only returns information for the

and fields. If you are requesting an effective date-enabled xPresso for Word document: • You must supply effective date information in your customer data. If you do not supply effective date information, this method will generate an error. • Do not supply a version number with the document name. Doing so could result in selecting a document that is no longer effective. If you are requesting a workflow-enable xPresso for Word document, only Approved documents can be handled using this method. Examples These examples show input for the following two scenarios: • With NULL customerData Value, page 55 • With Supplied customerData, page 56 52 The IQuickDoc Web Service With NULL customerData Value Input XML user password Word ]]> /doc?version=1.1 With Supplied customerData Input XML user password Word ]]> /doc?version=1.1 JackJones

1400 S. Lane St.

Omaha 2004-02-20 ]]> The getDataCollectionTemplate Method Caution: This method is deprecated. Use the getTemplateFields method instead. 53 The IQuickDoc Web Service This method enables you to extract the Data Collection Template from an xPresso for Word package. If you use this method without defining any customer data, the method will return all the data in the Data Collection Template. If you supply customer data to the method, the method will return only the data not included in the customer data you supplied. This method works exclusively with xPresso for Word documents created in xPression 4.5 or later. It does not support xPresso for Adobe InDesign, xPresso for Dreamweaver, or xDesign. Return Value: This method returns a String that contains the Data Collection Template. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax getDataCollectionTemplate(requestContext, documentName, customerData) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Use “Word” as the application name. This value will grant permissions that are appropriate for your request. For more information, see About the requestContext Parameter, page 26. If you are publishing an xPresso document stored in the Documentum xPression Repository, ensure the user name is authenticated on the xPression Server and in the Documentum repository. In the Documentum repository, the user must be assigned the xpression_dashboard role. For more information, see Using requestContext with Documentum-Based Documents, page 27. documentName : String A string specifying the name of a document. The document must reside on the xPression Server. The document name string contains the following elements: /document_name?version=version_number where document_name is the name of the document, and version_number is the document version number. For example: /document?version=1.2 If you want to select the newest, highest number version, use the following URL: /document?version=LATEST If a version number is not needed, use the following URL, which returns the latest version: /document 54 The IQuickDoc Web Service If you want to access xPresso documents stored on your Documentum xPression Repository you must supply a path to the document on the Documentum repository. The path should be formatted as follows: ecm::Documentum xPression Repository:/path/filename?version=version where path is the folder path on the repository, filename is the name of the file, and version is the version number. customerData : String You can supply existing customer data for this parameter in XML format, or supply NULL for the value. If you supply customer data, the Data Collection Template will not include data for any of the fields that you supplied. If you use NULL, the method will return the entire Data Collection Template for the package. For example: If your Data Collection Template contains the following three fields: ,

, And you supply the field in your customer data The returned Data Collection Template will only include information for the

and fields. If you are requesting an effective date-enabled xPresso for Word document: • You must supply effective date information in your customer data. If you do not supply effective date information, this method will generate an error. • Do not supply a version number with the document name. Doing so could result in selecting a document that is no longer effective. Examples These examples show input for the following two scenarios: • With NULL customerData Value, page 55 • With Supplied customerData, page 56 With NULL customerData Value Input XML user password Word ]]> 55 The IQuickDoc Web Service /doc?version=1.1 With Supplied customerData Input XML user password Word ]]> /doc?version=1.1 JackJones

1400 S. Lane St.

Omaha 2004-02-20 ]]> 56 Chapter 4 Workflow Integration Web Services The following Web Services are available to all xPression Enterprise Edition users. These Web Services enable you to set the states of your documents for use with the xPression Life Cycle feature. xPression uses the following Workflow Integration Web Services: • WorkflowDocumentBrowsingService, page 57 • DataBrowsingService, page 61 • WorkflowService, page 65 WorkflowDocumentBrowsingService This Web Service enables you to select a document version for previewing. The WorkflowDocumentBrowsingService Web Service WSDL can be found here: http://:/xFramework/services/WorkflowDocumentBrowsingService?wsdl This Web Service contains the following methods: • listWorkFlowAvailableCategories, page 57 • listWorkFlowAvailableDocuments, page 58 • getDocumentType, page 59 • getDocumentVersions, page 60 listWorkFlowAvailableCategories This method provides a list of all categories for which you have defined the workflow Life Cycle setting. Return Value: This method returns zero or more Strings in a String array. Each String in the array represents the name of a category for which you have defined the workflow Life Cycle setting. Syntax String[] listWorkflowAvailableCategories(requestContext) 57 Workflow Integration Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. listWorkFlowAvailableDocuments This method lists all documents in a category that are eligible to be submitted to a workflow. The method filters out documents currently in a workflow and documents which can not be edited (for example, xPresso documents without a source template file). Return Value: This method returns zero or more Strings in a String array. Each String in the array represents the name of a document eligible to be submitted to a workflow. Syntax String[] listWorkflowAvailableDocuments(requestContext, cateName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. cateName : String The name of the category where the method will search for eligible documents. 58 Workflow Integration Web Services getDocumentType This method identifies the publisher type for a specified document. Return Value: This method returns a String identifying the publisher type of the specified document. The return values can be: • CompuSet — for CompuSet documents • xPublish — for xDesign xPublish documents • xPressoInDesign — for xPresso for Adobe InDesign documents • xWordDesigner — for xPresso for Word documents • xPressoDreamWeaver — for xPresso for Dreamweaver documents Syntax String[] getDocumentType(requestContext, docName) 59 Workflow Integration Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. docName : String The name of the document whose publisher type you want identified by the method. getDocumentVersions This method retrieves the version effective date or version number of a specified xPresso document, depending on the type of the document. This method does not return information about documents created in xDesign. Return Value: This method returns a string identifying the version date or version number of the specified document. • For xPublish documents, the method returns the version effective date in the yyyy-mm-dd format. • For xWord documents, the method returns the major and minor version numbers, for example, 1.0, 1.1, 2.0. Syntax String[] getDocumentVersions(requestContext, docName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. 60 Workflow Integration Web Services docName : String The name of the document whose version you want identified by the method. DataBrowsingService This Web Service enables you to select customer data The IQuickDoc Web Service WSDL can be found here: http://:/xFramework/services/DataBrowsingService?wsdl This Web Service contains the following methods: • getDefaultDS, page 61 • listKeys, page 63 • getDataRecordXML, page 63 getDefaultDS This method retrieves the default data source of a specified document. For each category defined on your server, xPression enables you to set the default data source for any application that publishes a document from that category. The default data source is not selected by name, it is selected when you specify an application. xPression will then look at the category settings and determine which data source was defined as the default data source for that application. When using this method, you can call the default data source by specifying an application name in the requestContext parameter or letting the method determine the application by document type. The method uses the following logic when determining the default data source by application type: • CompuSet Documents — xPression chooses xPression Design as the application and selects the default data source specified for xPression Design in the category. • xPublish Documents — xPression chooses xPression Design as the application and selects the default data source specified for xPression Design in the category. • xPresso for InDesign Documents — xPression chooses xPresso for InDesign as the application and selects the default data source specified for xPresso for InDesign in the category. • xPresso for Word Documents — xPression chooses xPresso for Word as the application and selects the default data source specified for xPresso for Word in the category. • xPresso for Dreamweaver Documents — xPression chooses xPresso for Dreamweaver as the application and selects the default data source specified for xPresso for Dreamweaver in the category. Return Value: This method returns a String identifying the default data source name. Syntax String[] getDefaultDS(requestContext, docName) 61 Workflow Integration Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. 62 Workflow Integration Web Services Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. docName : String The name of the document whose default data source you want to identify. listKeys This method lists all of the customer data keys in a specified xPublish data source. Return Value: This method returns zero or more Strings in a String array. Each String in the array represents a customer key. Note: This method does not support xPresso data sources. Syntax String[] listKeys(requestContext, dsName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. dsName : String The name of the data source for which you want to return a list of customer keys. getDataRecordXML This method retrieves the XML for one customer data record. Return Value: This method returns an XML document containing the data from one customer record. 63 Workflow Integration Web Services Syntax String[] getDataRecordXML(requestContext, dsName, keyValues) 64 Workflow Integration Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. dsName : String The name of the data source you want to use. keyValues : String The key value that you want to use to retrieve a data record from the data source. WorkflowService This Web Service enables you to preview a document and change the Life Cycle status of a document in a workflow. The IQuickDoc Web Service WSDL can be found here: http://:/xFramework/services/WorkflowService?wsdl This Web Service contains the following methods: • listLifeCycles, page 65 • statusInLifecycle, page 66 • previewPDF, page 67 • previewHTML, page 68 • workflowBegins, page 69 • setLifecycleStatus, page 69 • workflowEnds, page 71 listLifeCycles This method returns a list of all Life Cycles defined in xAdmin. Return Value: This method returns zero or more Strings in a String array. Each String in the array represents a Life Cycle definition in xAdmin. 65 Workflow Integration Web Services Syntax String[] listLifecycles(requestContext) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. statusInLifecycle This method lists all the available statuses in a given Life Cycle. Return Value: This method returns zero or more Strings in a String array. Each String in the array represents a status in a Life Cycle. Syntax String[] statusInLifecycle(requestContext, lifecycleName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. lifecycleName : String The name of the Life Cycle for which you want to return all available statuses. 66 Workflow Integration Web Services previewPDF This method uses the “PDF to Caller” output profile to preview a document in PDF format. Return Value: This method returns a binary array, which is the preview PDF file. Syntax byte[] previewPDF(requestContext, docName, version, dsName, customerData) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. docName : String The name of the document that you want to preview. version : String The version parameter is only used for xPresso documents. This parameter identifies the version of the specified document that you want to preview. For both xWord and xInDesign documents, the version is expressed as the major and minor version numbers in the x.x format, for example, 1.0, 1.1, 2.0. dsName : String The name of the data source that you want to use when previewing the document. customerData : String The value for this parameter depends upon the type of data source assigned to the category that contains the document you want to publish. If your data source is an XML document, you must provide a single record of XML customer data. If your data source is a relational database, you must provide keys for the relational database data source. The following is an example of an XML string containing the key values for a specific customer record: 1 ENGLISH 67 Workflow Integration Web Services previewHTML This method uses the “HTML to Caller” output profile to preview a document in HTML format. Return Value: This method returns a byte array, which is the resulting preview HTML file. Syntax byte[] previewHTML(requestContext, docName, version, dsName, customerData) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. docName : String The name of the document that you want to preview. version : String The version parameter is only used for xPresso documents. This parameter identifies the version of the specified document that you want to preview. For both xWord and xInDesign documents, the version is expressed as the major and minor version numbers in the x.x format, for example, 1.0, 1.1, 2.0. dsName : String The name of the data source that you want to use when previewing the document. customerData : String The value for this parameter depends upon the type of data source assigned to the category that contains the document you want to publish. If your data source is an XML document, you must provide a single record of XML customer data. If your data source is a relational database, you must provide keys for the relational database data source. The following is an example of an XML string containing the key values for a specific customer record: 1 ENGLISH 68 Workflow Integration Web Services workflowBegins This method enables you to notify xPression that a document is being submitted to a workflow. Syntax String[] workflowBegins(requestContext, docName, version) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. docName : String The name of the document that you want to submit to a workflow. version : String The version parameter is only used for xPresso documents. This parameter identifies the version of the specified document that you want to preview. For both xWord and xInDesign documents, the version is expressed as the major and minor version numbers in the x.x format, for example, 1.0, 1.1, 2.0. setLifecycleStatus This method enables you to change the Life Cycle status of a specified document. The workflowBegins method should be called before this method. Syntax String[] setLifeCycleStatus(requestContext, docName, version, status) 69 Workflow Integration Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. 70 Workflow Integration Web Services docName : String The name of the document for which you want to change the Life Cycle status. version : String The version parameter is only used for xPresso documents. This parameter identifies the version of the specified document that you want to preview. For both xWord and xInDesign documents, the version is expressed as the major and minor version numbers in the x.x format, for example, 1.0, 1.1, 2.0. status : String The name of the status that you want to apply to the specified document. Please ensure this status is a valid status in your Life Cycle. workflowEnds This method enables you to notify xPression that a document is exiting a workflow. Syntax String[] workFlowEnds(requestContext, docName, version, boolean successFlag) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. All valid application names are acceptable, including: xPression Design, xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see About the requestContext Parameter, page 26. docName : String The name of the document that you want to exit a workflow. version : String The version parameter is only used for xPresso documents. This parameter identifies the version of the specified document that you want to preview. For both xWord and xInDesign documents, the version is expressed as the major and minor version numbers in the x.x format, for example, 1.0, 1.1, 2.0. successFlag : Boolean 71 Workflow Integration Web Services If successFlag=true, then xPression will approve all pending content items (both CompuSet and xPublish). If successFlag=false, then xPression will leave the content items at their current status level. 72 Chapter 5 xPression DevKit Web Services xPression DevKit is a purchasable add-on for Enterprise Edition customers. It serves as an extension of IQuickDoc for solution-specific capabilities. These Web 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 some cases, update information in xPression without accessing the xPression database. The Web Services methods are more powerful, and therefore more complex, using complex types and requiring more sophistication in coding. Although more xPression DevKit Web Service methods will be released in the future, currently xPression DevKit contains only the IDocumentItem and xCatalog Web Services. xPression DevKit also contains xEditor, a component you can embed in your application. xEditor is a Microsoft Word-based editor that enables you to use Microsoft Word’s powerful editing and composition features to edit work items for your correspondence application. For more information, see Chapter 11, The xPression DevKit xEditor Component. The IDocumentItem Web Service This web service provides methods that work with editable document work items. The IDocumentItem web service WSDL will be found at: http://:/xDevKit/services/DocumentItem?wsdl This Web Service contains the following methods: • searchDocumentItem, page 74 • The createDocumentItem Method, page 77 • The getDocumentItemInfo Method, page 78 • The publishAndReturnDocumentItem Method, page 82 • The publishAndReturnDocumentMultipleStream Method, page 84 • The documentItemsAssignedToUser Method, page 85 • The reassignDocumentItemToUser Method, page 87 • The updatePrimaryVariables Method , page 88 • The copyDocumentItem Method, page 89 • The addExternalContentByLink Method, page 90 73 xPression DevKit Web Services • addExternalContentByStream, page 92 • The reorderExternalContent Method, page 93 • The addAnnotation Method, page 94 • The deleteExternalContent Method, page 95 • The createAuthenticationToken Method, page 96 • The complete DocumentItem Method, page 96 • The deleteDocumentItem Method, page 97 • The publishRevisionUnits Method, page 98 • The setCarryForwardDocumentItem Method, page 99 • The clearCarryForwardDocumentItem Method, page 100 • The updateRUVariables Method, page 100 • The submitDocumentItem Method, page 101 • The approveDocumentItem Method, page 102 • The rejectDocumentItem Method, page 103 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 that indicates 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 the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. 74 xPression DevKit Web Services Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. 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 isCompleted parameter can be set to true or false. If set to true, you are indicating that you want to search a completed work item. • SECTION— The section element serves the same function as parenthesis in a Boolean logic or a SQL query. The element is the only subelement allowed in a

. • 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 configured in the revise.properties file in the reviseDateFindFormat property. • CUSTOMERKEY — Enables you to search the customer key for values. This element must appear inside a PHASE element, and can contain any number of KEY_VALUE elements. Each KEY_VALUE element is implicitly joined by an OR operator. The following two samples return the same sets of work items. — Sample 1: 1 1 1 — Sample 2: 1 1 1 75 xPression DevKit Web Services You can use an AND operator to connect multiple elements. The following sample contains three KEY_VALUE elements, A, B, and C, which returns the result of the logical conjunction: (A AND B) OR C. 7 2 Ms You can also use AND operators in conjunction with OR operators. The following sample contains three KEY_VALUE elements, A, B, and C, which returns the result of the logical conjunction: A AND (B OR C). 7 2 Ms • ORDERBY — Enables you to sort the list of returned work items. Placing parameters in this element will order the returned values in ascending order. If TIMESTAMP is used in the ORDERBY element, the work items are sorted in descending order. Sample

xRevis* 1 1 1 76 xPression DevKit Web Services * 02-22-11

CATEGORY_NAME TIMESTAMP The createDocumentItem Method The createDocumentItem web service method enables you to create a document work item in xPression. A document work item is a version of an assembled document that can be revised before publishing. Examples of revision include: • Selection of optional paragraphs • Editing of the document • Adding an annotation • Updating the primary variables of the document Document template assembly rules are always executed based on the original customer data used to create the document work item. Changes made to the customer data after the work item is created will have no affect on the document execution rules. The changes are simply treated as text variable replacements. The customer data that you input into this method will be applied to the default data source definition assigned to the category that contains your document. This method is only guaranteed to process one document record of data, so ensure that you only send one record of input data. If multiple records are given as input, the method may try (and fail) to determine and use the first record in the XML customer data. Note: If you create a large number of work items with this Web Service and encounter errors because too many files are open, adjust the “threads number” and “limit” values in the SoapUI Return Value: A String that uniquely identifies the newly-created document work item that was created within the application specified in the Request Context. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String documentItemID = createDocumentItem(requestContext, documentName, customerData, assignToUserName) 77 xPression DevKit Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. documentName : String A string specifying the name of the document for which you want to create a work item. The document must reside on the xPression Server. customerData : String The value for this parameter depends upon the type of data source assigned to the category that contains the document you want to publish. If your data source is an XML document, you must provide a single record of XML customer data. If your data source is a relational database, you must provide keys for the relational database data source. You can provide the primary key for the customer data using the following format: keyValue keyValue 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 is returned as an XML document. The amount of data returned for some work items could be quite large, 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 infoToReturn parameter. You can return information about the following items by passing the specified term in the infoToReturn parameter: • Annotation — For each annotation in the document, the method returns the annotation type, the user who created the annotation, the timestamp, and the annotation note itself. • ASL — A description of all objects in the document. 78 xPression DevKit Web Services • Document — Basic information about the document, including the document item ID, the document name, the document category, the publishing type, and the customer key of the user for whom the work item was assembled. • External Contents — A list of all external content in the document. For each piece of external content, this method reports the external content name, the external content type, the URL of the link to the external content, and the location of the external content. If the external content was added by an external content rule in xDesign, the name will be NULL. • General — Shows general information about the work item, including the user who is currently assigned to the work item (owner), the work item user who created the work item (user), the work item category, the customer key used to create the work item, the time and date of the last modification to the work item, the ASL ID (which is used to retrieve information about the work item), the current status and state of the work item, the publisher type, and an indication if 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 user who is currently assigned to the work item (owner), the current state, and the date/time stamp. • Optional Paragraphs — Lists all the optional paragraphs in the work item. It displays each optional paragraph group, the group type, and whether or not it is configured for handling in batch. It also lists all the optional paragraphs in the optional paragraph group, listing the name, ID, an indication that the optional paragraph is shared or not, an indicator if the optional paragraph is selected or not, and the version number. • Revision Units — Identifies each revision unit in the document. It also shows the name of the revision unit, the revision number, the version, the date it was created, the RevisionUnit cache data 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 the variable 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: • 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 the method fails, it returns a SOAP Fault that indicates the reason for the failure. To see an example of a returned XML file, see Examples, page 81. 79 xPression DevKit Web Services Syntax String documentItemInfoXML = getDocumentItemInfo (requestContext, documentItemIDs, infoToReturn) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. 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 has zero strings then all information will be queried and returned in the XML document. You may give any of these Strings as input into the method: • “Annotations” • “ASL” • “Document” • “ExternalContents” • “General” • “History” — These items are stored under the tag. • “OptionalParagraphs” • “RevisionUnits” • “Variables” • “WIPChangeHistory” See the description of this method (The getDocumentItemInfo Method, page 78) for details about what information is returned for each string. 80 xPression DevKit Web Services Examples This section contains an example of the XML returned from this method.

Auto Policy Auto 1 xPublish externalPDF PDF /external/Strat.pdf file tester tester StringsOfVariables 1 2010-03-29T09:59:21 8912 Pending Active 2 False Workflow submitter="tester" currentowner="tester" currentstate="Active" datetime="2010-03-29T10:03:46"/> Word_Variable_Field/Name> 8643 false false 1.00 /OptionalParagraphGroup> 81 xPression DevKit Web Services Introduction 0 1.00 2010-03-29 2531604323 -1 false 1 CA The publishAndReturnDocumentItem Method The publishAndReturnDocumentItem web service method enables you to publish a document work item to an output profile. This method works identically to the QuickDoc web service method publishAndReturnDocument, except that the document generated comes from a document work item instead of customer data. In order to successfully return the document to your calling application, the output profile you specify must contain an output stream whose distribution definition is defined with the “Return to Calling Application” option. Return Value: This method returns at most one “Return to calling application” output stream if one is identified in the output profile. If no output streams are defined with a distribution definition marked as “Return to Calling Application”, the method will return a zero length byte array when such documents are successfully published. If more than one output stream contains a distribution definition marked as “Return to Calling Application”, this method selects any one of the defined output profiles. You cannot control which output profile it selects. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. 82 xPression DevKit Web Services Syntax MultiStrea multistream = publishAndReturnDocumentItem(requestContext, documentItemID, outputProfileName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. 83 xPression DevKit Web Services 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. The output profile must reside on the xPression Server. The publishAndReturnDocumentMultipleStream Method The publishAndReturnDocumentMultipleStream web service method enables you to publish a document work item to an output profile using multiple streams. This method works identically to the QuickDoc web service method publishAndReturnDocumentMultipleStream, except that the document generated comes from a document work item instead of customer data. In order to successfully return the document to your calling application, the output profile you specify must contain an output stream whose distribution definition is defined with the “Return to Calling Application” option. If no output streams are defined with a distribution definition marked as “Return to Calling Application”, the method will return a zero length byte array when such documents are successfully published. If more than one output stream contains a distribution definition marked as “Return to Calling Application”, this method returns all the document data associated with those streams. The customer data that you input into this method will be applied to the default data source definition assigned to the category that contains your document. This method is only guaranteed to process one document record of data, so ensure that you only send one record of input data. If multiple records are given as input, the method may try (and fail) to determine and use the first record in the XML customer data. Some types of output profiles are not compatible with some documents. For example, CompuSet documents cannot use xPublish profiles and xPublish documents cannot use CompuSet profiles. xPresso for Dreamweaver documents cannot use output profiles that produce formats other than HTML. xPresso for InDesign documents cannot use output profiles that produce HTML. If you attempt to publish a document through an incompatible output profile, this method will return the error message: 9022-The document with type {Document type}(e.g.xPressoInDesign) can not be supported. Also, InvaildDocumentTypeException will appear in the xPression log. Return Value: This method returns a byte array representing the document that was published and returned. The format of the document is determined by the output profile. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. If your distribution definition does not use the “Return to calling application” option, this method will return a null value. 84 xPression DevKit Web Services Syntax MultiStrea multistream = publishAndReturnDocumentMultipleStream(requestContext, workItemId, outputProfileName, includeMetaData) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. workItemID : 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. The output profile must reside on the xPression Server. includeMetaData : Boolean If set to true, this method will also return the Generic Index metadata file. The metadata file is an XML formatted index that lists values for all defined output variables in the output stream, and, optionally, media counts. See the documentation for Distribution Definitions in the xAdmin User Guide for more information about this metadata file. If set to false, no metadata is returned. The documentItemsAssignedToUser Method The documentItemsAssignedToUser method returns a list of document item IDs for any document items assigned to a given user. You can return information about these document items through a subsequent Web Service call by using the document item IDs returned from this method as input into the documentItemInfo method. Return Value: This method returns an array of Strings (one String per document item) containing the document item IDs of document items assigned to the user. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. 85 xPression DevKit Web Services Syntax String[] documentItemIDs = documentItemsAssignedToUser(requestContext, userName) 86 xPression DevKit Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. 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 assigned user to the user name given as input. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Return Value: This method returns a string message when the method successfully reassigns a work item. Syntax String successMessage = reassignDocumentItemToUser (requestContext, documentItemID, assignToUserName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. 87 xPression DevKit Web Services Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. documentItemID : String The unique identifier for the document item. assignToUserName : String 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 cannot be used to update the value of a primary key. Return Value: This method returns a string message when the method successfully updates the primary variables. Syntax String message = String updatePrimaryVariables(String requestContext, String documentItemID, String primaryVariableInfo) throws AxisFault; Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. 88 xPression DevKit Web Services documentItemID : String The unique identifier for the document item. primaryVariableInfo : String XML code that identifies the variable names and values. For example: OR The copyDocumentItem Method The copyDocumentItem method makes a copy of a document work item and assigns it to the specified user. The most common use of this method is to copy a completed document work item from history to make a new editable document work item. The advantage of using this method is that it 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 work item. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String newDocumentItemId = copyDocumentItem (requestContext, documentItemID, assignToUserName) 89 xPression DevKit Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. documentItemID : String The unique identifier for the document item that you want to copy. assignToUserName : String 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 define the external content by supplying the path of the content on your file system, network location, or location 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 requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. 90 xPression DevKit Web Services Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. documentItemID : String The unique identifier for the document item. 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, a URL, or an ECM path. The following three formats are supported: local file, Url and ecm. Examples: • Local Path Syntax \\ Local Path Example C:\xPression\UC\A40127.pdf • URL Syntax http://// URL Example http://localhost/UC/A40127.pdf • ECM Path Syntax (syntax is case sensitive) ecm::?uri=//?version= ECM Path Example ecm::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 document where you want the external content to appear. You specify the position by identifying the Revision Unit ID of the Revision Unit that should follow the external content. The external content will be placed ahead of the Revision Unit you identify with this parameter. If you want to place the content at the end of the document, supply a null value. options : String 91 xPression DevKit Web Services 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 method adds 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. Syntax String RUID = addExternalContentByStream(String requestContext, String documentItemID, String ruName, String externalContent, String format, String position, String options) throws AxisFault; Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. documentItemID : String The unique identifier for the document item. ruName : String The name for the external content Revision Unit. externalContentLink : String Supply the byte array for the external content. format : String 92 xPression DevKit Web Services 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 document where you want the external content to appear. You specify the position by identifying the Revision Unit ID of the Revision Unit that should follow the external content. The external content will be placed ahead of the Revision Unit you identify with this parameter. If you want to place the content at the end of the document, supply a null value. options : String This parameter is unused at this time, but is included for future updates. 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 content Revision Unit was reordered successfully. Syntax String message = reorderExternalContent(String requestContext, String documentItemID, String externalContentID, String targetPosition) throws AxisFault; Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. 93 xPression DevKit Web Services documentItemID : String The unique identifier for the document item. 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 document where you want the external content to appear. You specify the position by identifying the Revision Unit ID of the Revision Unit that should follow the external content. The external content will be placed ahead of the Revision Unit you identify with this parameter. If you want to place the content at the end of the document, supply a null value. The addAnnotation Method This method enables you to enables you to add comments to individual work items. Notes can be Client Level type or Document Level type. Client Level notes attach to all documents with the same document ID and the same first primary key, while Document Level notes attach to a specific work item. Syntax String message = addAnnotation (String requestContext, String documentItemID, String annotationInfo) throws AxisFault; Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. documentItemID : String The unique identifier for the document item. 94 xPression DevKit Web Services annotationInfo : String The XML formatted string that contains the annotation content. The string should be formatted as in the following example: 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 content was removed successfully. Syntax String message = deleteExternalContent (String requestContext, String documentItemID, String externalContentID) throws AxisFault; Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. documentItemID : String The unique identifier for the document item. externalContentID : String 95 xPression DevKit Web Services 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 the xEditor 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) throws AxisFault; Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. 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 it can 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 changes to the document work item, copy it to a new document work item through the copyDocumentItem web service method. 96 xPression DevKit Web Services Return Value: This method returns a string message when the method successfully completes the document work item. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String successMessage = completeDocumentItem (requestContext, documentItemID) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. documentItemID : String The unique identifier for the document item that you want to move to a “completed” state. Once the document work item has been completed, it can not be edited. The deleteDocumentItem Method The deleteDocumentItem method deletes the specified document work item and associated history from the server. Return Value: This message returns a string message when the method successfully deletes the document work item. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String successMessage = deleteDocumentItem (requestContext, documentItemID) 97 xPression DevKit Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name For more information, see About the requestContext Parameter, page 26. documentItemID : String The unique identifier for the document item that you want to delete. The publishRevisionUnits Method The publishRevisionUnits method provides a means of selectively publishing portions of a documents. For example, to present relevant portions for review to a specialist for review or to publish different portions of the document to different output channels. Return Value: This method returns a byte array, containing the resulting document, or null if no document is returned. This depends on the Output Profile that is passed. If the profile contains a stream with “Return to caller” distribution, then that stream is returned. Syntax byte[] resultDoc = publishRevisionUnits (requestContext, documentItemID, ruNames, addTitles, opName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. If documentItemID refers to a work item, then the user must have write, approve, or admin rights. If it refers to a completed item, then the user must have read, write, approve, or admin rights. 98 xPression DevKit Web Services documentItemID : String 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 a document work item. addTitles:String Pass the string “true” to request titles. Titles are a small paragraph inserted by the method, containing the RU name. This parameter is optional since document template designs differ; in some cases the RUs that have been published may be apparent from the content, but in other cases it may not be apparent. opName:String The name of an output profile defined to the server (with xAdmin). It must belong to the correct publishing 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 method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String setCarryForwardDocumentItem (requestContext, documentItemID, CFCompareID) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. The user you provide must have Write or Admin permission for the category/application combination. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name documentItemID : String 99 xPression DevKit Web Services 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 method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String clearCarryForwardDocumentItem (requestContext, documentItemID) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. The user you provide must have Write or Admin permission for the category/application combination. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name 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 specified Revision Unit variables. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. 100 xPression DevKit Web Services Syntax updateRUVariables(requestContext, documentItemID, ruVariableInfo) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. The user you provide must have Write or Admin permission for the category/application combination. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name documentItemID : String The unique identifier for the document item. ruVariableInfo : String XML code that identifies the variable names and values that you want to update. For example: 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 been submitted successfully.” If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String submitDocumentItem (requestContext, workflowState, documentItemID) 101 xPression DevKit Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. The user you provide must have Write or Admin permission for the category/application combination. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name workflowState : String[] The name of the workflow state to which the document item will be submitted. It is not the current workflow state, it is the destination workflow state. documentItemID : String[] 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 been approved.” If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String approveDocumentItem (requestContext, documentItemID) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. The user you provide must have Write or Admin permission for the category/application combination. 102 xPression DevKit Web Services Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name documentItemID : String[] 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 been rejected.” If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String rejectDocumentItem (requestContext, documentItemID) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. The user you provide must have Write or Admin permission for the category/application combination. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Revise • xPression DevKit • Your custom application name documentItemID : String[] The unique identifier for the document item that you want to reject. 103 xPression DevKit Web Services Calling the xEditor StartUp Application The 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 call the xEditor StartUp application through an HTTP query string. Before calling the xEditor StartUp application, you must first call the The createAuthenticationToken Method, page 96 to create an authentication token. Syntax xEditorStartup.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 on your server. The URL for xEditorStartup.application is: http://:/xRevise/xEditor/xEditorStartup.application Parameters Required Parameters: TOK A valid user token generated by calling The createAuthenticationToken Method, page 96. 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 xRevise web applications. This URL is needed so that xEditor can locate the private web services it uses to communicate with the server. The syntax is: http://:/xRevise CNF The name of the xEditor configuration that you want to apply when launching xEditor. xEditor configurations 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 the StartUp application’s xEditor Update/Install feature. If the value is T (the default value), the feature is activated. If the value is F, the feature is deactivated. Additionally, if the value is F, the StartUp application will continue to verify that the current xEditor installation is valid, but it will not prompt you to update the install. To read more about this feature, see Running xEditor the First Time, page 192 and How xEditor Handles Updates, page 192. CID 104 xPression DevKit Web Services This parameter is for xRevise only. CID is the compare work item ID. Use this parameter if you are comparing 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 message displays. 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 only once per machine, even if other applications that used xEditor are used on that machine. Starting xEditor takes substantially longer the first time because of the initial installation procedure. xEditor Manager is a component of xEditor that improves xEditor startup performance when loading work items for editing. The initial installation adds an xEditor Manager shortcut to the STARTUP folder. This queues an instance of xEditor when the machine starts up to the extent possible, 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 instance of WINWORD.EXE running, with all required supporting software. This instance appears in Task Manager and can be shut down, but if it is shut down xEditor will take longer to open work items than would otherwise be the case. The shortcut can be deleted if desired, but xEditor startup will be much slower. 105 xPression DevKit Web Services 106 Chapter 6 xCatalog Web Service Currently, xCatalog provides three Web Service methods: getDocumentInfo, searchForDocuments, and getCatalogInfo. This Web Service is part of the new xPression Web Service API. It conforms to the WS-I Basic Profile. The URL for the xCatalog Webservice WSDL is: http://localhost:8080/xCatalog/services/DocumentWebServices?wsdl This Web Service contains the following methods: • The getCatalogInfo Method, page 107 • The searchForDocuments Method, page 108 • The getDocumentInfo Method, page 112 The getCatalogInfo Method This method enables you to get a list of metadata tags for the documents in your xCatalog system. Return Value: This method returns an XML document containing all tags and custom fields in the xCatalog system. Syntax public java.lang.String getCatalogInfo(java.lang.String requestContext) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. 107 xCatalog Web Service Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Catalog • your customer application name For more information, see About the requestContext Parameter, page 26. Sample Returned Document The following is a sample of returned XML from this method. The searchForDocuments Method This method enables you to search for and return information about specified documents. You can search for documents based on criteria such as document name, document description, document status and more. You can refine the resulting list of documents by using criteria to further refine your search. There are two types of search criteria: Simple search and Advanced searches. In Simple searches, multiple occurrences of the same criteria types are treated with an OR condition. In Advanced searches, the relationships between multiple occurrences of the same criteria types can be either AND or OR condition. The following list shows all the criteria types: • Name • Date • Unique_ID 108 xCatalog Web Service • Description • Status • Custom_Field • Content • Tag Simple Search Criteria To define simple search criteria, you supply an XML formatted string in the searchCriteria parameter of the Web Service method. In the following XML example, we are searching for forms whose name contains “WC”, description contains “Declaration”, content contains the string, “liability”, variable name contains “Address”, and that has a tag named “CA” in the “State” tag folder. WC Declaration liability Address State::CA Multiple occurrences of the same filter type are treated with an OR condition. However, the element operates under different rules. Multiple elements for the same folder name use the OR condition, but multiple elements using different folders use the AND condition. For example: Line of Business::Homeowner Line of Business::Property State::CA State::FL This search is looking for forms with either the “Homeowner” or “Property” tag in the Line of Business folder and either the “CA” or “FL” tags in the State folder. Written as a mathematical statement, the search criteria would be: (Line of Business = Homeowner or Property) and (State = CA or FL). Advanced Search Criteria To define advanced search criteria, you supply an XML formatted string in the searchCriteria parameter of the Web Service method. The XML format for advanced searches is different than the format for simple searches. In an advanced search, you must explicitly specify the relationship between the search strings. You can do that by using the element to apply parenthesis (), AND, and OR. For example: ( WC or HO ) 109 xCatalog Web Service 110 xCatalog Web Service If you have only a single value in a search category, you can simplify the XML by excluding the Operator element. DSC xPressForms implies the AND operator to the relationship between search categories. For example, the following XML is searching for a document whose name is WC and whose UniqueID is DSC. WC DSC If you using the Date category for your search, you can use only one and element for each search. For example: 2008-11-20 2008-12-20 Syntax public java.lang.String searchForDocuments(java.lang.String requestContext, java.lang.String searchCriteria, java.lang.String format, java.lang.String[] infoToReturn)throws org.apache.axis.AxisFault Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Catalog • your customer application name For more information, see About the requestContext Parameter, page 26. 111 xCatalog Web Service searchCriteria : String The search criteria in XML format. For example: WC 2008-11-20 DSC Declaration liability Address My Favorite::NCCI State::CA format : String The format of the report returned by the method. Valid values are: XML and CSV. infoToReturn : String An optional parameter specifying a subset of the information to return. If this parameter is null or has zero strings then all information will be queried and returned in the XML document. You may give any of these Strings as input into the method: • “Document” • “Description” • “Status” • “Category” • “Tags” • “Notes” • “Custom_Fields” The getDocumentInfo Method This method enables you to retrieve information about the specified document(s). The method returns the information in a report that can be in XML or CSV (comma delimited variable) format. You can define the method to return the entire set or a subset of the following data: • Document • Description • Status • Category • Tags • Notes • Custom_Fields Return Value: This method returns a report with the requested information. The report file can be in XML or CSV format. 112 xCatalog Web Service Syntax public java.lang.String getDocumentInfo(java.lang.String requestContext, java.lang.String[] docNames, java.lang.String format, java.lang.String[] infoToReturn) throws org.apache.axis.AxisFault Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, the following xPression applications are valid: • xPression Catalog • your customer application name For more information, see About the requestContext Parameter, page 26. docNames : String The names of the document(s). This method will create a report with the requested information for each document specified in this parameter. format : String The format of the report returned by the method. Valid values are: XML and CSV. infoToReturn : String An optional parameter specifying a subset of the information to return. If this parameter is null or has zero strings then all information will be queried and returned in the XML document. You may give any of these Strings as input into the method: • “Document” • “Description” • “Status” • “Category” • “Tags” 113 xCatalog Web Service • “Notes” • “Custom_Fields” 114 Chapter 7 Output Statistics Reporting The output statistics reporting web services give you the ability to return page count statistics about any documents published within a specified date range. This information is of interest to license holders with usage-based licenses. Statistics are specific to the server, so activity on a development server is not considered in the report for the production server. Usage limits apply to production servers only, but the information is available on non-production servers as well to assist with usage planning. See the following topics: • What Types of Output are Counted?, page 115. • Output Statistics Report Details, page 116. • Output Statistics Reporting Web Services, page 121. What Types of Output are Counted? This feature will capture page output data from the following modes of publishing: • Batch — includes all forms of batch, including xAdapter batch. • Transactional — includes publishing from our transactional applications, xResponse and xRevise. • API — includes publishing through our API and Web Services. The specific xPression Web Service methods are: — xPressionWebService/DocumentRequester: requestDocuments — xPressionWebService/DocumentRequester: requestDocumentsByOutputProfile — xPressionWebService/DocumentRequester: requestDocumentsWithData — xPressionWebService/xPressionRequest: publishAndReturnDocument — xPressionWebService/xPressionRequest: publishDocument — xPressionWebService/xPressionRequest: publishMSOHTMLDocument — xPressionWebService/xResponseRequest: publishAndReturnDocument — xPressionWebService/xReviseRequest: publishAndReturnWorkItem The specific xResponse method is: DocumentRequestService: publishAndReturnDocument 115 Output Statistics Reporting The specific QuickDoc methods are: — publishDocument — publishDocuments — publishAndReturnDocument The specific DevKit methods is: DocumentItem: publishAndReturnDocumentItem The specific xAdapter method is: xPressionRequest.jws: publishDocument The specific JFramework methods are: — com.dsc.uniarch.ejbController.Instantiater: publishInstantiatedDocument(long) — com.dsc.uniarch.ejbController.Publisher: publishInstantiatedDocument(long) — com.dsc.uniarch.ejbController.Publisher: publishPassedInstantiatedDocument (byte[],long, String,String,int,long ) — com.dsc.uniarch.ejbController.Publisher: publishPassedInstantiatedDocument (byte[],long, String,String,int) For non-paginated output formats like HTML and DOCX, this feature counts each customer record as one page of output. However, more pages will be counted if the document contains a subdocument which requires conversion to an image in order to be included in the output. In this case, the pages of the subdocument will also be counted. The following items and actions are not captured by this feature: • Creating a “Preview” of a document • Blank pages inserted by Output Processing • CompuSet documents • Publishing with a "QueueForBatch" Output Profile. The published document will be counted when batch processes the document from the batch queue. The act of placing the document in the queue is not counted. Output Statistics Report Details The output statistics report is returned in an XML format. There are two types of reports, each returning a different level of information: • Summary — This type of report returns information about how many pages were produced on each date in the date range. The pages are also identified by how they were published, providing numbers for batch, transactional, and API published pages. See Summary Report Content, page 117 for more information. • Summary and Detail — This type of report returns everything returned in a Summary report, along with additional information about each publish action. See Summary and Detail Report Content, page 118 for more information. 116 Output Statistics Reporting Summary Report Content A Summary report identifies the number of pages produced during the specified date range. The pages are also identified by how they were published, providing numbers for batch, transactional, and API published pages. Below you will find a sample Summary report.

A Summary report contains the following elements: Summary This element identifies the values you defined for the creation of the report, and also provides the total number of pages identified in the report. The element contains the following parameters: • customerID — The ID of the customer that owns the xPression license. • customerName — The name of the customer that owns the xPression license • startDate — the start date you defined when requesting the report. • endDate — the end date you defined when requesting the report. • totalPageCount — identifies the total number of pages identified in the report. 117 Output Statistics Reporting Report This element contains all elements and data returned for a single day in the specified date range. There will be one Report element for each day where a page was produced. Within the Report element are three additional elements identifying the pages produced through batch, transactional applications, and APIs. • Batch — This element identifies the number of pages produced through batch. • Transaction — This element identifies the total number of pages produced through xResponse and xRevise. Sub-elements identify the pages produced through each individual application. • Api — This element identifies the total number of pages produced through xPression APIs and web services. These sub-elements identify the pages produced through: DocumentRequesterService, xPressionRequest, QuickDocService, IDDK, and JFramework. Summary and Detail Report Content A Summary and Details report contains all the information included in a Summary Report, but also includes additional information about each publish action. • Batch Details, page 118 • Transaction Details, page 119 • API and Web Services Details, page 119 • Sample Summary and Details Report, page 120 Batch Details For batch, this report provides additional information in the element that identify the specific batch job used. Like a summary report, the Batch element contains a “pages” parameter that shows the number pages generated through batch. For each batch job returned, the report will include the following information: • Run — Identifies a batch run. The Batch element can contain one or more of these elements. This element contains the following parameters: — start — The start time of the batch job. — end — The completion time of the batch job. — job — The Job Definition name. — runID — The job run ID as listed in xDashboard. — op — The Output Profile used to publish the document. — status — The final status of the job. This will indicate success or failure. — pages — The number of pages published by the batch job. For example: 118 Output Statistics Reporting Transaction Details For transactional applications, this report provides additional information about the transaction in the or elements. Like a summary report, the Transaction element contains a “pages” parameter that shows the number pages generated through transactional applications. For each transaction returned, the report will include the following information: • xResponse and xRevise — Identifies xResponse or xRevise transactions. These elements contains a “pages” parameter that shows the number pages generated through xResponse or xRevise. — Publish — Identifies a publish action. The xResponse or xRevise elements can contain one or more of these elements. This element contains the following parameters: — time — The timestamp indicating when the transaction was published. — user — The username of the user who executed the transaction. — doc — The name of the document that was published. — docVersion — The version of the document that was published. Only 4.2 and newer xResponse and xRevise work items contain this information. — op — The Output Profile used to publish the document. — status — The final status of the job. This will indicate success or failure. — pages — The number of pages published by the transaction. For example: API and Web Services Details For API and web services, this report provides additional information about the API call. Like a summary report, the API element contains a “pages” parameter that shows the number pages generated through the API. For each document published through an API or web service, the report will include an element for each of the API and Web Service calls that are monitored. These elements contain a “pages” parameter which identifies the number of pages generated through that method. The method elements are: • DocumentRequesterService • xResponseDocumentRequestService • xAdapterXPressionRequestService • QuickDocService 119 Output Statistics Reporting • xPressionRequest • xResponseRequest • xReviseRequest • xDevKit • JFramework For each of these elements that was used, the following information is returned: • Call — this element identifies an API or Web Service call. Your method element can contain more than one of these elements. This element contains the following parameters. — time — The timestamp indicating when the document was published. — user — The username of the user who executed the API or web service. — doc — The name of the document that was published. — docVersion — The version of the document that was published. — op — The Output Profile used to publish the document. — status — The final status of the job. This will indicate success or failure. — pages — The number of pages published by the API or web service. For example: Sample Summary and Details Report Below you will find a sample Summary and Details report.

Output Statistics Reporting Web Services Before attempting to generate an output statistic report, ensure that you have configured the reporting level of your server in xDashboard. You must specify which level of reporting you want xPression to capture on this server. The server will not capture output statistics data until this setting is configured. Once configured, xPression will capture data for all documents subsequently published by xPression. See the xDashboard User Guide for more information. EMC Document Sciences provides the following output statistics reporting web service methods: • getSummaryPublishingReport, page 121 • getDetailedPublishingReport, page 122 • getCompressedSummaryPublishingReport, page 123 • getCompressedDetailedPublishingReport, page 125 • clearDetailPublishingReport, page 126 The Output Statistics Reporting Web Services WSDL can be found at: http://:/xFramework/services/PublishingReport?wsdl getSummaryPublishingReport Use this method to get a Summary level report. This method returns a byte array representing the XML formatted report. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String getSummaryPublishingReport = getSummaryPublishingReport(requestContext, startDate, endDate) 121 Output Statistics Reporting Parameters requestContext : String An XML document that passes user credentials for authentication. In most cases it also passes the name of the application for which the user is authenticated. For this method, you do not need to supply ApplicationName information. Do not include the ApplicationName element in your requestContext XML file. The only users authorized to use this Web Service are those who are authorized to access the xDashboard Server Management page. Access is granted through the xAdmin User Management page. All the credentials types (Unencrypted userid/password, Weak encrypted userid/password and Trusted UserID/Groups) are supported. The xpressionsa super administrative user cannot be authenticated for this Web Service using Trusted UserID and Groups authentication. For more information, see About the requestContext Parameter, page 26. startDate : String The starting date of the date range used to create the report. The report will provide information based on the documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. endDate : String The ending date of the date range used to create the report. The report will provide information based on the documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. getDetailedPublishingReport Use this method to get a Summary and Detail level report. This method returns a byte array representing the XML formatted report. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String getDetailedPublishingReport = getDetailedPublishingReport(requestContext, startDate, endDate) 122 Output Statistics Reporting Parameters requestContext : String An XML document that passes user credentials for authentication. In most cases it also passes the name of the application for which the user is authenticated. For this method, you do not need to supply ApplicationName information. Do not include the ApplicationName element in your requestContext XML file. The only users authorized to use this Web Service are those who are authorized to access the xDashboard Server Management page. Access is granted through the xAdmin User Management page. All the credentials types (Unencrypted userid/password, Weak encrypted userid/password and Trusted UserID/Groups) are supported. The xpressionsa super administrative user cannot be authenticated for this Web Service using Trusted UserID and Groups authentication. For more information, see About the requestContext Parameter, page 26. startDate : String The starting date of the date range used to create the report. The report will provide information based on the documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. endDate : String The ending date of the date range used to create the report. The report will provide information based on the documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. getCompressedSummaryPublishingReport Use this method to get a Summary level report compressed in a zip file. This method returns a byte array representing the XML formatted report in a zip file. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax byte[] getCompressedSummaryPublishingReport = getCompressedSummaryPublishingReport(requestContext, startDate, endDate) Parameters requestContext : String An XML document that passes user credentials for authentication. In most cases it also passes the name of the application for which the user is authenticated. For this method, you do not need to supply ApplicationName information. Do not include the ApplicationName element in your requestContext XML file. The only users authorized to use this Web Service are those who are authorized to access the xDashboard Server Management page. Access is granted through the xAdmin User Management page. All the credentials types (Unencrypted userid/password, Weak 123 Output Statistics Reporting encrypted userid/password and Trusted UserID/Groups) are supported. The xpressionsa super administrative user cannot be authenticated for this Web Service using Trusted UserID and Groups authentication. For more information, see About the requestContext Parameter, page 26. 124 Output Statistics Reporting startDate : String The starting date of the date range used to create the report. The report will provide information based on the documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. endDate : String The ending date of the date range used to create the report. The report will provide information based on the documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. getCompressedDetailedPublishingReport Use this method to get a Summary and Detail level report compressed in a zip file. This method returns a byte array representing the XML formatted report in a zip file. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax byte[] getCompressedDetailedPublishingReport = getCompressedDetailedPublishingReport(requestContext, startDate, endDate) Parameters requestContext : String An XML document that passes user credentials for authentication. In most cases it also passes the name of the application for which the user is authenticated. For this method, you do not need to supply ApplicationName information. Do not include the ApplicationName element in your requestContext XML file. The only users authorized to use this Web Service are those who are authorized to access the xDashboard Server Management page. Access is granted through the xAdmin User Management page. All the credentials types (Unencrypted userid/password, Weak encrypted userid/password and Trusted UserID/Groups) are supported. The xpressionsa super administrative user cannot be authenticated for this Web Service using Trusted UserID and Groups authentication. For more information, see About the requestContext Parameter, page 26. startDate : String The starting date of the date range used to create the report. The report will provide information based on the documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. endDate : String The ending date of the date range used to create the report. The report will provide information based on the documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. 125 Output Statistics Reporting clearDetailPublishingReport This method enables you to delete data from a defined date range. It deletes only the detailed portion of the captured data. The summary data is never deleted. Additionally, you cannot delete data from the current day. Ensure your date range does not contain today’s date. Syntax void clearDetailPublishingReport = clearDetailPublishingReport(requestContext, startDate, endDate) Parameters requestContext : String An XML document that passes user credentials for authentication. In most cases it also passes the name of the application for which the user is authenticated. For this method, you do not need to supply ApplicationName information. Do not include the ApplicationName element in your requestContext XML file. The only users authorized to use this Web Service are those who are authorized to access the xDashboard Server Management page. Access is granted through the xAdmin User Management page. All the credentials types (Unencrypted userid/password, Weak encrypted userid/password and Trusted UserID/Groups) are supported. The xpressionsa super administrative user cannot be authenticated for this Web Service using Trusted UserID and Groups authentication. For more information, see About the requestContext Parameter, page 26. startDate : String The starting date of the date range that you want to delete report details. xPression will clear the detailed information for all documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. endDate : String The ending date of the date range that you want to delete report details. xPression will clear the detailed information for all documents published during this date range. Dates should be supplied in the following format: yyyy-mm-dd. 126 Chapter 8 xPressForms Web Services for Reporting The xPressForms Web Service for reporting contains the following methods: Get Report, Get Report for Fields, Search for Forms, Search for Forms Customized View, and Get Search Field List. The URL for the xPressForms Webservices WSDL is: http://localhost:8080/xPressForms/services/xPressFormsWebServices?wsdl • Get Report Method, page 127 • Get Report For Fields Method, page 129 • Search for Forms Method, page 130 • Search for Forms Customized View Method, page 132 • Get Search Field List Method, page 135 • Deprecated xPressForms Web Services, page 136 Get Report Method This method returns a report on the specified documents. Syntax getReport("string docNames", "string format" "string username", "string password") Parameters docnames : String The name of the documents on which to create a report. You can specify more than one document name. The document names are separated by a comma and enclosed in quotes. format : String 127 xPressForms Web Services for Reporting The format of the report. You can choose XML or CSV (comma delimited variable file). 128 xPressForms Web Services for Reporting username: String The name of the xPressForms user. password: String The xPressForms user’s password. The following example shows the method creating an XML formatted report for three specific documents. getReport(“document1, document2, document3”, “XML”, “username”, “password”) Get Report For Fields Method This method returns a report for certain fields (XML element names) in specified documents. The method will only return information about the specified fields in the specified document. You can specify more than one document name and more than one field. The document names are separated by a comma and enclosed in quotes. The field names are also separated by a comma and enclosed in quotes. Syntax getReportForFields("string docNames", "string format", "string fields", "string username", "string password") Parameters docnames : String The name of the documents on which to create a report. You can specify more than one document name. The document names are separated by a comma and enclosed in quotes. format : String The format of the report. You can choose XML or CSV (comma delimited variable file) fields: String The XML element names that this report will include. This value is case sensitive. username: String The name of the xPressForms user. password: String The xPressForms user’s password. The following example shows the method creating an XML formatted report for three specific documents. 129 xPressForms Web Services for Reporting getReport(“document1, document2, document3”, “XML”, “Form, Description, Status, Object_Type”) Search for Forms Method Returns a report on forms that contains an XML report with all requested fields. You can search for forms based on form name, form description, pieces of form content, variables contained in the form, and tags associated with the form. You can add multiple filter criteria to your search to further refine the resulting list. You can implement either a simple search or an advanced search. The following are allowed search criteria: • Name • Date • UID (Unique ID) • Description • Content • Variable • Tag • Operator (Advanced Search only) • Date, StartDate/EndDate (Advanced Search only) • Status (Advanced Search only) The format of the resulting report is the same as the xPressForms Get Report method. If the specified tag does not exist in the system or does not belong to this user, an exception will be thrown back to caller. Simple Search Criteria To define simple search criteria, you supply an XML formatted string in the “criteria” parameter of the Web Service method. In the following XML example, we are searching for forms whose name contains “WC”, description contains “Declaration”, content contains the string, “liability”, variable name contains “Address”, and that has a tag named “CA” in the “State” tag folder. WC Declaration liability Address State::CA 130 xPressForms Web Services for Reporting Multiple occurrences of the same filter type are treated with an OR condition. However, the element operates under different rules. Multiple elements for the same folder name use the OR condition, but multiple elements using different folders use the AND condition. For example: Line of Business::Homeowner Line of Business::Property State::CA State::FL This search is looking for forms with either the “Homeowner” or “Property” tag in the Line of Business folder and either the “CA” or “FL” tags in the State folder. Written as a mathematical statement, the search criteria would be: (Line of Business = Homeowner or Property) and (State = CA or FL). Advanced Search Criteria To define advanced search criteria, you supply an XML formatted string in the “criteria” parameter of the Web Service method. The XML format for advanced searches is different than the format for simple searches. In an advanced search, you must explicitly specify the relationship between the search strings. You can do that by using the element to apply parenthesis (), AND, and OR. For example: ( WC or HO ) If you have only a single value in a search category, you can simplify the XML by excluding the Operator element. DSC 131 xPressForms Web Services for Reporting xPressForms implies the AND operator to the relationship between search categories. For example, the following XML is searching for a document whose name is WC and whose UniqueID is DSC. WC DSC If you using the Date category for your search, you can use only one and element for each search. For example: 2008-11-20 2008-12-20 Syntax searchForForms("String criteria", "String format", "String username", "String password") Parameters criteria : String The search criteria in XML format. See Simple Search Criteria , page 130 and . format : String The format of the report. You can choose XML or CSV (comma delimited variable file) username: String The name of the xPressForms user. password: String The xPressForms user’s password. Search for Forms Customized View Method Returns a report with specified fields on forms that satisfy the search criteria. The search criteria and format are same as the searchForForms method. The formats of the parameter fields and the resulting report are the same as the getReportForFields method. 132 xPressForms Web Services for Reporting You can search for forms based on form name, form description, pieces of form content, variables contained in the form, and tags associated with the form. You can add multiple filter criteria to your search to further refine the resulting list. You can implement either a simple search or an advanced search. The following are allowed search criteria: • Name • Date • UID (Unique ID) • Description • Content • Variable • Tag • Operator (Advanced Search only) • Date, StartDate/EndDate (Advanced Search only) • Status (Advanced Search only) Simple Search Criteria To define simple search criteria, you supply an XML formatted string in the “criteria” parameter of the Web Service method. In the following XML example, we are searching for forms whose name contains “WC”, description contains “Declaration”, content contains the string, “liability”, variable name contains “Address”, and that has a tag named “CA” in the “State” tag folder. WC Declaration liability Address State::CA Multiple occurrences of the same filter type are treated with an OR condition. However, the element operates under different rules. Multiple elements for the same folder name use the OR condition, but multiple elements using different folders use the AND condition. For example: Line of Business::Homeowner Line of Business::Property State::CA State::FL This search is looking for forms with either the “Homeowner” or “Property” tag in the Line of Business folder and either the “CA” or “FL” tags in the State folder. Written as a mathematical statement, the search criteria would be: (Line of Business = Homeowner or Property) and (State = CA or FL). 133 xPressForms Web Services for Reporting Advanced Search Criteria To define advanced search criteria, you supply an XML formatted string in the “criteria” parameter of the Web Service method. The XML format for advanced searches is different than the format for simple searches. In an advanced search, you must explicitly specify the relationship between the search strings. You can do that by using the element to apply parenthesis (), AND, and OR. For example: ( WC or HO ) If you have only a single value in a search category, you can simplify the XML by excluding the Operator element. DSC xPressForms implies the AND operator to the relationship between search categories. For example, the following XML is searching for a document whose name is WC and whose UniqueID is DSC. WC DSC If you using the Date category for your search, you can use only one and element for each search. For example: 2008-11-20 2008-12-20 Syntax searchForForms("String criteria", "String format", "String fields", "String username", "String password") 134 xPressForms Web Services for Reporting Parameters criteria : String The search criteria in XML format. See Simple Search Criteria , page 133 and Advanced Search Criteria, page 134. format : String The format of the report. You can choose XML or CSV (comma delimited variable file) fields: String The XML element names that this report will include. This value is case sensitive. username: String The name of the xPressForms user. password: String The password for the xPressForms username. For example, with the following XML search criteria: Get Search Field List Method xDesign uses the getSearchFieldList web service to implement the xPressForms connectivity feature. getSearchFieldList returns all searchable fields and tags in the XML form. Syntax String getSearchFieldList(username, password) Parameters username : String Username to access xPressForm. It is the same as the xDesign username. password : String Password to access xPressForm. It is the same as the xDesign password. Return Value XML that contains all searchable field names as well as tags. For fields, label attribute has field description. Name attribute has field name that will be used when calling searchForForms. 135 xPressForms Web Services for Reporting Deprecated xPressForms Web Services The getCategory, getCategories, and isAvailable web services have been deprecated. 136 Chapter 9 xPression RESTful Services for Batch xPression provides a set of RESTful services and an embedded daemon process which can be called and tasked with processing your job requests. This configuration enables you to run batch services without the requirement that you install job scheduling agents on the xPression Server. The daemon process is embedded on each xPression Server in your cluster. If you do not want a particular server to operate as a batch processor, simply deactivate the daemon on that server. Your scheduling application should send requests through RESTful HTTP POST protocol to the provided calling application RESTful services. The services will query the needed information from the xPression Repository and queue the job for batch processing. When sending requests through RESTful HTTP POST protocol to the provided calling application, you must add the Request.ContentType = "application/xml" command in the C# client. When queued, xPression sets the job Status to –1, which means the job is “Not Started”. When xPression selects a queued job for processing, the xPression Server “checks out” the job from the queue, ensuring that no other xPression Server can process the same job. The server that “checks out” the job is the “Owner”. While the job is checked out, the status is 0, which means it is “Started”. When the job completes, the Status is 1. xPression sends a completion event to the owner listener, which reports the event to your batch scheduler application. If the job failed with errors, the Status is >1. From xPression 4.5 SP1, xPression RESTFUL services are improved so that jobs can be picked up individually by each thread instead of being picked up after the termination of all threads. The return of the job creation is the request ID of the job from the T_BATCH_QUEUE table in string format. All other returns are in XML format. Note: The request ID is different from the job history ID in the xDashboard. RESTful HTTP Body Structure For all HTTP requests, the body root element is XServicesRequest, which is followed by sub-elements. Each request must include the General.security element at the top to authenticate the request. The body of the RESTful Web Services uses the following structure: xPression Batch 137 xPression RESTful Services for Batch 138 xPression RESTful Services for Batch The General.security element authenticates your request. It can be followed by additional elements that provide information to your service. For example: statistics with details Note: The value of must be all lowercase with the strict spelling of the desired option. Otherwise the default “statistics” will be applied. For example, if the value in the above sample were “statistic with detail” instead, it would be ignored and treated as “statistics”. The General.security Element The General.security element is required for all RESTful services. This element enables you to provide user credentials to the service. A RequestContext element for General.security contains the following parameters: xpression xpression xpression Administrator xPression Batch The element identifies the method of authorization. Valid values are “UserID and Password” and “Trusted UserID and Groups”. Both of these methods are authenticated by comparing the value you or your xPression administrator supply to the key/values defined in the BatchRunner.properties file. xPression Batch web services users, please contact your xPression administrator if you have problems with authorization. All other xPression users, please see Authorization, page 139 for more information about configuring authorization. The ApplicationName element identifies the application for which the user is authorized. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Ensure you use xPression Batch for all RESTful HTTP requests. Authorization xPression Batch web services users, please contact your xPression administrator if you have problems with authorization. For all other xPression users, use the following steps to set up trusted user IDs and groups, complete the following steps: 1. Navigate to C:\xPression on the xPression Server where you want to configure authorization. 2. Locate BatchRunner.properties and open it for editing. 139 xPression RESTful Services for Batch 3. Locate the BatchServiceAuthorizedUsersAndGroups property. If the property does not exist, please add the property. 4. Update the property by adding users and groups separated by a colon (;). BatchServiceAuthorizedUsersAndGroups={users};{groups} 5. Save and close the file. The Job.start.xml and Job.start Elements The Job.start.xml and Job.start RequestContext elements enable you to start a batch job. The Job.start service (/xFramework/restful/services/job/start) enables you to run a job already defined in xDashboard. The Job.start.xml service (/xFramework/restful/services/job/start/xml) enables you to create and start a new job by supplying XML inline with the request. Both elements use the same sub-elements and parameters. Differences are noted below. For an example of these elements in use, see Start a Batch Job with an Existing Job Definition, page 152 and Start a Batch Job with a Job Definition XML File, page 153. These elements contain the following sub-elements: • The Job Element, page 140 • The xPressionPublishJob Element, page 140 • The JobOption Element, page 141 To ensure the service notifies your scheduler when a job is complete, see Service Notification, page 155. See a sample Job.start.xml element below. The Job Element The Job element contains the following two parameters: • version — Supply a value of 2.0 for this parameter. • name — If you are using “Job.start”, the value for this parameter should be the name of the Job Definition as it exists in xDashboard. If you are using “Job.start.xml”, the value for this parameter should be the name you want to assign to the new job. The xPressionPublishJob Element This element represents the XML job definition. For a full explanation of the parameters and syntax of an XML job definition, see “Manually Creating Your Job Definition” in the xPression Batch Processing Guide. 140 xPression RESTful Services for Batch The JobOption Element This element enables you to implement the job options available through command line batch processing parameters in xPression. None of these options are required. Please see the xPression Batch Processing Guide for information about each parameter. Note: For xPression Batch Web Services Users — xPression web services support all command line parameters except: -r and -j. Please see your xPression administrator for assistance with setting up and supporting these Job Option parameters. The Job.status Element This element enables you to query the status of a job. Please see the following topics: • Syntax, page 141 • Returned Information, page 142 • Sample Responses for Job.Status, page 144 Syntax To query the status of a job run, use the Job.status element as follows: 23984759875 statistics with details Note: The value of must be all lowercase with the strict spelling of the desired option. Otherwise the default “statistics” will be applied. For example, if the value in the above sample were “statistic with detail” instead, it would be ignored and treated as “statistics”. The queueID is the identifier for a job in the queue. For an example of this element in use, see Return the Status of a Particular Job, page 151. The ReturnInfo parameter identifies the format of the returned data. You can specify : • statistics — This level collects only batch statistics, such as start time, end time, and publish type. • statistics with errors — This level collects all the statistics information and information about failed customer documents. • statistics with details — This level collects all the statistics information and customer document information for all documents. 141 xPression RESTful Services for Batch The ReturnInfo parameter does not specify which information the server should record, it simply identifies what level of information to return to the user. The Job Level parameter in your XML Job Definition or xDashboard Job Definition determines what level of information the server records. If you use ReturnInfo to request a greater level of information than the Job Level option specified, you will not receive all of the requested information. Ensure the level of information you specify in your Job Level is greater than or equal to the level you specify in the ReturnInfo parameter. When running the Job Status RESTful Web Service to return “statistics with errors”, please be aware that the Web Service will not always return detailed error information. If the batch process for a customer record fails before the document can be assembled, xPression is only able to return the error message, but not the details of the error message. In this case, the error occurs before xPression is able to enter the diagnose phase, and therefore no details are returned. The default value of the ReturnInfo parameter is “statistics”, and the specified level must be all lowercase. Values that include uppercase characters are ignored and treated as “statistics” only. To see samples of the information returned by this element, see Sample Responses for Job.Status, page 144. Returned Information Depending on the value of your ReturnInfo parameter, this element will return different levels of information. All queries will return data in the Common element. If you selected Statistics with Errors or Statistics with Details in your ReturnInfo parameter, the Statistics with Details or Statistics with Errors elements will also appear. Common Data All queries will return the following information: • JOB — The element for information about the job. There can be one or more JOB elements in the returned data. The JOB element contains the following parameters: — name — the Job name. — runId — the batch job run ID. — processId — The ID of the process running the job, as reported in xDashboard. — queueId — The queueID is the identifier for a job in the queue. — logPath — When the job is completed, the path and file name of the job log file will be recorded here. • Percentage — The completion percentage of the job. — Step — The completion percentage of the specified job step. This element contains one “name” parameter which identifies the name of the job step. • State — Identifies the current state of the job. 142 xPression RESTful Services for Batch • ReturnCode — This parameter reports the following values: — -1 = the job is not started — 0 = the job is running. — 1 = the job completed with success — >1 = the job failed with errors • Statistics — The container element for statistic information. This element can contain sub-elements for each level of detail you requested through the ReturnInfo parameter. The potential sub-elements are Common, Statistics with Details, and Statistic with Errors. — Common — This element The Common container element contains the following basic information: — PublishProfile — The name of the publish profile. — StartTime — The time/date stamp that identifies when the job started. — EndTime — The time/date stamp that identifies when the job ended. — DistributionNumber — The number of records processed through the distribution controller for print, E-mail, or archive distribution. — Error — Reports error messages generated during the job run. — ReportingLevel — Indicates the level of information you requested. Statistics with Details Data The following data will be returned for any query that specifies Statistics with Details for the ReturnInfo parameter: • StatisticWithDetails — This element contains one DATA container element for each customer record processed by the batch job. Each DATA container element contains the following information: — CustomerKey — The customer key for the record that was processed. — Bdt — The name of the xPression document that was processed by the job. — DataSource — The name of the data source used to process the customer record. — Status — Displays the final status of the job: Success, Failure, or Success with failure records. — StepName — The name of the job step being processed. — StepType — The Job Step type. 1 = Assemble, 2 = Queued Documents, and 3 = Custom Documents. — PublishType — The document type. 1 = xDesign, 2 = xPresso. — Category — The name of the category that contains the xPression document being processed. 143 xPression RESTful Services for Batch — DSG — The name of the data source group that contains the data source being processed. — FileName — The output file name. Statistics with Errors Data The StatisticWithErrors element contains all the information included in the Statistics with Details element, and also contains an “Error” element. The Error element reports the error message generated by any failed records. Sample Responses for Job.Status This section provides sample responses for Job Status queries: • Completed Job with “Statistics” Reporting Level, page 144 • Completed Job with “Statistics with Details” Reporting Level, page 145 • Stopped Job with “Statistics with Errors” Reporting Level, page 146 • Job That is Not Started, page 147 • Job That is Still Running, page 147 Completed Job with “Statistics” Reporting Level 100.0 100.0 COMPLETED 1 PDF to File 2 1318228001015 1318228628840 0 3 144 xPression RESTful Services for Batch Completed Job with “Statistics with Details” Reporting Level 100.0 100.0 COMPLETED 1 PDF to File 2 1318230517569 1318231110411 0 3 [AUTOPAY_KEY=1] Automatic Payment Letter AUTOPAY-XML 1 1 1 2 PDF to File Automatic Payment Letter AUTOMATIC PAYMENT LETTER C:/xPression/Publish/output/BatchParam.pdf 145 xPression RESTful Services for Batch Stopped Job with “Statistics with Errors” Reporting Level 100.0 STOPPED 3 PDF to File 2 1318087490687 1318087649345 0 Error during read. 3 [AUTOPAY_KEY=1] Automatic Payment Letter AUTOPAY-XML 2 1 1 2 PDF to File Automatic Payment Letter AUTOMATIC PAYMENT LETTER EJB Exception: ; nested exception is: java.lang.NullPointerException 146 xPression RESTful Services for Batch Job That is Not Started This sample shows returned data for a job that has not yet started. -1 Job That is Still Running 100.0 100.0 RUNNING 0 PDF to File 2 1317960478623 3 The Job Queue All Element This element is used for the /jobs/queue/all service: Return a List of all Queued Jobs, page 150. This element enables you to filter the results of the query by the status of the job. This element and the General.security element are the only two elements needed for the /jobs/queue/all service. • Syntax, page 147 • Returned Information, page 148 Syntax To return a list of all queued jobs, use the following format: 147 xPression RESTful Services for Batch -1,0 The Filter element can only contain one Status element. The Status element defines which status levels you want to return. Status codes are defined as follows: • -1 — Job not started • 0 — Job “checked out” for processing • 1 — Job complete • >1 — Job failed with errors Returned Information This service returns a list of all queued jobs. It returns the following data. • JOB — The element for information about the job. There can be one or more JOB elements in the returned data. The JOB element contains the following parameters: — name — The Job name. — Status — The current status of the job. When queued, xPression sets the job Status to –1, which means the job is “Not Started”. When xPression selects a queued job for processing, the xPression Server “checks out” the job from the queue, ensuring that no other xPression Server can process the same job. The server that “checks out” the job is the “Owner”. While the job is checked out, the status is 0, which means it is “Started”. When the job completes, the Status is 1. xPression sends a completion event to the owner listener, which reports the event to your batch scheduler application. If the job failed with errors, the Status is >1. — runID — The batch job run ID. — queueID — The queueID is the identifier for a job in the queue. 148 xPression RESTful Services for Batch This data is returned in the following format: autopay 1 3969401362522230860562071312531 2685201361864770579462071311531 Job2 1 1966463550093566940132071314531 2969915873062562401369071313531 Return a List of all Job Names To query xPression for a list of all existing Job names, use the following service URL and supply user credentials through the General.security element in the service body. Service URL: http://:/xFramework/restful/services/jobs/all/list/names Service Body: xpression [email protected] xpression xPression Batch For specific about the General.security syntax and options, see The General.security Element, page 139. This service will return a list of all job names. The data is returned in the following format: Notices Notices2 autopay 149 xPression RESTful Services for Batch Return a List of all Queued Jobs To query xPression for a list of all currently queued jobs, use the following service URL, supply user credentials through the General.security element, and optionally filter the results with the Job.queue.all element in the service body. Service URL: http://:/xFramework/restful/services/jobs/queue/all Service Body: xpression [email protected] xpression xPression Batch -1,0 For specific information about the General.security syntax and options, see The General.security Element, page 139. For specific information about filtering your results with the Job.queue.all, see The Job Queue All Element, page 147 for more information. To see a sample of the returned information for this service, see Returned Information, page 148. Return a List of all Running Jobs To query xPression for a list of all currently running jobs use the following service URL and supply user credentials through the General.security element. Service URL: http://:/xFramework/restful/services/jobs/running/list Service Body: xpression [email protected] xpression xPression Batch 150 xPression RESTful Services for Batch For specific about the General.security syntax and options, see The General.security Element, page 139. This service returns the following details about the job: • JOB — The element for information about the job. There can be one or more JOB elements in the returned data. The JOB element contains the following parameters: — name — the Job name. — runId — the batch job run ID. — jobID — The ID of job. — StartTime — Timestamp identifying when the job started. The data is returned in the following format: autopay 4258863931015641131191138131693 20 1318311946941 null Return the Status of a Particular Job To query xPression for the status of a particular job use the following service URL, supply user credentials through the General.security element, and define your job status query in the Job.status element. Web services supports the return of a single job status only; multiple web service calls are required for multiple jobs. 151 xPression RESTful Services for Batch Service URL: http://:/xFramework/restful/services/job/status Service Body: xpression [email protected] xpression xPression Batch 4366817659012001047974313115310 statistics with details Note: The value of must be all lowercase with the strict spelling of the desired option. Otherwise the default “statistics” will be applied. For example, if the value in the above sample were “statistic with detail” instead, it would be ignored and treated as “statistics”. For specific information about the syntax and options available to the General.security and Job.status elements, see The General.security Element, page 139 and The Job.status Element, page 141. To view sample returned data, see Sample Responses for Job.Status, page 144. Start a Batch Job with an Existing Job Definition To start a batch job with an existing Job Definition use the following service URL, supply user credentials through the General.security element, and define the job definition in the Job.start element. Service URL: http://:/xFramework/restful/services/job/start Service Body: xpression [email protected] xpression xPression Batch -o C:\CustomerData\BILS.xml 152 xPression RESTful Services for Batch For specific information about the syntax and options available to the General.security and Job.start elements, see The General.security Element, page 139 and The Job.start.xml and Job.start Elements, page 140. Start a Batch Job with a Job Definition XML File To create and start a new job by supplying a manually created Job Definition XML file, use the following service URL, supply the user credentials in the General.security element, and supply the job definition information in the Job.start.xml element. For more information about creating a Job Definition file and the parameters displayed below, please see “Manually Creating Your Job Definition” in the xPression Batch Processing Guide. Service URL: http://:/xFramework/restful/services/job/start/xml Service Body: xpression [email protected] xpression xPression Batch -ignoreDebug 153 xPression RESTful Services for Batch For specific information about the syntax and options available to the General.security and Job.start elements, see The General.security Element, page 139 and The Job.start.xml and Job.start Elements, page 140. Configuring xPression for RESTful Batch Services Your can configure the daemon process according to your needs and its capabilities. Your administrator can also customize the configuration of xPression batch processing. See the following topics: • Enable xPression for Concurrent Batch Processing, page 154 • Configure Servers for RESTful Service Batch Processing, page 155 • Service Notification, page 155 Enable xPression for Concurrent Batch Processing You or your xPression Administrator can configure xPression to support the running of batch jobs concurrently in the batch queue. xPression Batch web services users, please contact your xPression administrator to configure xPression for concurrent processing. All other xPression users, complete the following steps: 1. On the server where you want to enable concurrent batch processing, navigate to the xPressionHome directory. 2. Open BatchRunner.properties for editing. 3. Locate the ServiceBatchThreadSize property. If this property does not exist, please add it. 154 xPression RESTful Services for Batch 4. Set the value of this parameter to the number of concurrent jobs that you want processed by this cluster node. For example: ServiceBatchThreadSize=7 5. Save and close the file. Configure Servers for RESTful Service Batch Processing You or your xPression administrator can configure individual servers in your cluster to process only those batch jobs initiated by the RESTful services. This enables the servers to move interactive batch requests to the front of the queue so they do not compete for resources with other batch jobs. xPression Batch web services users, please contact your xPression administrator to configure the servers in your cluster. For all other xPression users, please use the following steps. The configuration is accomplished by setting the EnableBatchServiceProcessor property to “True” or “False”. To activate the scheduler on a particular server, set the value to “True”. To deactivate the scheduler on a particular server, set the value to “False”. Perform these steps on any server in the cluster that you want enable or disable for processing batch jobs initiated by the RESTful services. 1. On the server where you want to enable or disable the processing of batch jobs initiated by the RESTful services, navigate to the xPressionHome directory. 2. Open BatchRunner.properties for editing. 3. Locate the EnableBatchServiceProcessor property. 4. To enable the processing of batch jobs initiated by the RESTful services, change the value of the property to True. To disenable the processing of batch jobs initiated by the RESTful services, change the value of the property to False. 5. Save and close the file. Service Notification If you want this service to notify your batch scheduler when the job is complete, you must first make a change to the Event.xml file in your xPressionHome directory. Once that is complete, you can configure the listener in xAdmin. Note: For xPression Batch Web Service Users — You must request that your xPression administrator configure the Event.xml file for you. Once that is complete, you can work with your administrator to configure the listener in xAdmin (steps 4–11 below). To configure a listener in xAdmin, use the following steps: 1. First, navigate to C:\xPression and open the Event.xml file for editing. 2. Add the following text to the end of the file: 155 xPression RESTful Services for Batch 156 xPression RESTful Services for Batch 3. Restart the xPression Server. 4. Start xAdmin and navigate to the following page: Resource Management > Event Management. The Event Management page provides a means of informing the scheduler when a job has been completed. Event Notification for all applications is managed on the Event Notification Management screen of Resource Management. Items on the page are arranged in the following columns: • Event Listener URL The URL of the event listener. The names are hyperlinks; clicking the link opens the Edit dialog box. • Application The name of the application associated with the events. 5. Click the Add Event Listener button. If the Event Listener already exists and you want to edit it, click the name of the listener. The Add/Edit Event interface opens. The page consists of two tabs: General and Events. 6. If creating a new listener, type the URL for the listener in Listener URL. The listener URL is limited to 256 characters. 7. The Actions bar in the Applications section of the General tab provides two buttons: Add Application and Delete Application. When creating a new listener, or adding another application for the listener, click Add Application. 8. Select xPression_Batch from the list. The Events tab becomes available when an application is added to the listener. 9. Open the Events tab. The listener URL is displayed read-only for reference. 10. Choose the application for which the events are to be subscribed from the list. 11. Click Save to save the listener configuration. When the job completes, the xPression Server will notify the URL defined in the Listener with JSON structured message. With Internet Explorer or Firefox, the message is automatically converted to the following XML structured message: 0/1 queueid jobid xBatch Completed xPressionBatch The element reports the returned code and it can report either a 1, 2, or 3. • 1 — The job was successful. • 2 — The job succeeded with failure records. • 3 — The job failed. 157 xPression RESTful Services for Batch The and elements identifies the job and queue IDs for the currently running batch job. The element reports error messages when the job fails. If the job succeeds, the element will contain no value. 158 Chapter 10 xDesign Online Editor Web Services You can use the methods provided by the xDesign Online Editor Web Services to create, open, and edit document work items. Web Services This web service provides methods that work with editable document work items and the xDesign Online Editor. The web service WSDL will be found at: http://:/xResponse/services/DocumentRequestService?wsdl When you use xPression Web Services to create, open, or edit a work item, xPression creates temporary folders to support the action. These folders are not deleted when your session ends. See Clean Up xDesign Online Editor Temp Folders, page 188 for more information. The web service contains the following methods: • createDocumentItem • createAuthenticationToken • publishAndReturnDocumentItem • deleteDocumentItem • reassignDocumentItemToUser • documentItemsAssignedToUser • searchDocumentItem • unlockDocumentItem • addAnnotation • getDocumentItemInfo • openDocumentItem • submitDocumentItem • rejectDocumentItem • approveDocumentItem • documentItemsAssignedToUserReturnInfo 159 xDesign Online Editor Web Services • searchDocumentItemReturnInfo • copyDocumentItem • addExternalContentByStream, page 185 • addExternalContentByLink, page 186 • deleteExternalContent, page 188 Authentication xPression uses an authentication model that enables easier integration with a with variety of single sign-on products and security models. All entry points into xPression will take an XML document which contains user credentials and any other information needed to authenticate and authorize the request. You can specify these credentials in any compatible format, for example: encrypted, plain text, and token. The XML document is passed through the requestContext parameter that must be defined for all Web Service calls. This new authentication model eliminates the need to pass hard-coded parameters for every security-sensitive request, and enables you to integrate without having to change the signature of any xPression entry points. It also enables you to create Java User Exit code to perform more sophisticated integrations. Note: Single Sign-On (Trusted UserID/Groups) can only be used when the enableTrustedUser parameter in the systemconfig.properties file is set to True. This properties file is located in your xPressionHome directory. By default, this directory is C:\xPression and is located on your server. About the requestContext Parameter This parameter is used in all Web Service methods. It enables you to pass an XML document containing user credentials for authentication. It also passes the name of the xPression application for which the user is authenticated. In xPression, users are granted access rights to specific applications because some applications have different sets of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. In general, for core xPression services (client and server functions), you can supply credentials for the user under any application for which the user is authenticated. For xResponse, you must supply credentials for the exact application you are using. requestContext Examples The following examples show how to structure your XML document for requestContext. Unencrypted userid/password 160 xDesign Online Editor Web Services John pass xPression Response Weak encrypted userid/password A23B45C67 A2KS4SLDK6DKOQWI xPression Response Single Sign-On (Trusted UserID/Groups) John Administrator xPression Design User xPression Response User xPression Response Access Rights for Document Item Web Services Web service methods that access document work items use access rights to determine if the requesting user is authorized to execute the method. The user must have the appropriate access rights to perform actions with the work items. For some of the methods, the web service user must be the current owner of the document item, or have xResponse Admin access rights in the document’s category, to execute the web service. For these methods, a user that is not the owner of the work item, and does not have xResponse Admin rights, can not execute a web service with that work item. xResponse Admin access rights are specified through category access rights in xAdmin. For more information, see the xAdmin User Guide. The specific access rights required for each method (if any) are listed in the method description. 161 xDesign Online Editor Web Services createDocumentItem The createDocumentItem web service method enables you to create a document work item in xPression. A document work item is a version of an assembled document that can be revised before publishing. Examples of revision include: • Selection of optional paragraphs • Editing of the document • Adding an annotation Document template assembly rules are always executed based on the original customer data used to create the document work item. Changes made to the customer data after the work item is created will have no affect on the document execution rules. The changes are simply treated as text variable replacements. The customer data that you input into this method will be applied to the default data source definition assigned to the category that contains your document. This method is only guaranteed to process one document record of data, so ensure that you only send one record of input data. If multiple records are given as input, the method may try (and fail) to determine and use the first record in the XML customer data. To execute this method, you must have Read access, or xResponse Admin access for the category that contains this document. Return Value: A String that uniquely identifies the newly-created document work item that was created within the application specified in the Request Context. The returned string is the work item’s ID, and should be tracked for use in subsequent operations, such as opening, publishing, or deleting a document. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String documentItemID = createDocumentItem(requestContext, documentName, customerData, assignToUserName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentName : String 162 xDesign Online Editor Web Services A string specifying the name of the document for which you want to create a work item. The document must reside on the xPression Server. customerData : String A string specifying a single record of XML customer data. You can provide the primary key for the customer data using the following format: keyValue keyValue assignToUserName : String The username of the user to whom you want to assign the document. createAuthenticationToken The createAuthenticationToken method enables you to create a string authentication token that will be used in the openDocumentItem method to launch the xDesign Online Editor and open a document 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) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. timeout : String The number of milliseconds that the token should be active. 163 xDesign Online Editor Web Services publishAndReturnDocumentItem The publishAndReturnDocumentItem web service method enables you to publish a document work item to an output profile. The output profile determines whether the document is returned or distributed without being returned. In order to successfully return the document to your calling application, the output profile you specify must contain an output stream whose distribution definition is defined with the "Return to Calling Application" option. If the output stream determines that the document is distributed instead of returned, and the document publishes successfully, this method returns a zero length byte array. To execute this method, the work item must currently be assigned to you, and you must have Read or Write access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns at most one "Return to calling application" output stream if one is identified in the output profile. If no output streams are defined with a distribution definition marked as "Return to Calling Application", the method will return a zero length byte array when such documents are successfully published. If more than one output stream contains a distribution definition marked as "Return to Calling Application", this method selects any one of the defined output profiles. You cannot control which output profile it selects. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax byte[] document = publishAndReturnDocumentItem(requestContext, documentItemID, outputProfileName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String The unique identifier for the document item, which is provided by the createDocumentItem method. outputProfileName : String A string specifying the name of an output profile valid for use for with the specified document. The output profile must reside on the xPression Server. 164 xDesign Online Editor Web Services deleteDocumentItem The deleteDocumentItem method deletes the specified document work items and associated histories from the server. To execute this method, the work item must currently be assigned to you, and you must have Read or Write access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This message returns a string message when the method successfully deletes the document work items. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information on the structure for the deleteDocumentItem method, see Example, page 165 . Syntax String successMessage = deleteDocumentItem (requestContext, documentItemID) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String[] An array of unique identifiers for the document items that you want to delete. You may provide multiple identifiers to delete multiple documents at one time. Document IDs are provided by the createDocumentItem method. Example The following example shows how to structure the deleteDocumentItem method. auser 165 xDesign Online Editor Web Services apassword xPression Response ]]> 603 604 reassignDocumentItemToUser The reassignDocumentItemToUser method moves the document item from its currently assigned user to the user name given as input. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. To execute this method, the work item must currently be assigned to you, and you must have Read or Write access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns a string message when the method successfully reassigns a work item. For example: "Work item with id: 605 has been reassigned to a user successfully." Syntax String successMessage = reassignDocumentItemToUser (requestContext, documentItemID, assignToUserName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String The unique identifier for the document item, which is provided by the createDocumentItem method. assignToUserName : String The username to whom you want to assign the work item. The new user must have Read access in the document category. 166 xDesign Online Editor Web Services documentItemsAssignedToUser The documentItemsAssignedToUser method returns a list of document item IDs for any document items assigned to a given user. You can return information about these document items through a subsequent Web Service call by using the document item IDs returned from this method as input into the documentItemInfo method. To execute this method, the work item must currently be assigned to you, and you must have Read access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns an array of Strings (one String per document item) containing the document item IDs of document items assigned to the user. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String[] documentItemIDs = documentItemsAssignedToUser(requestContext, userName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. userName : String The username of the user for whom you want to return a list of assigned document items. searchDocumentItems The searchDocumentItems method enables you to search for a work item based on criteria. To execute this method, the work item you search for must currently be assigned to you, and you must have Read access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: A string array of work item IDs. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. 167 xDesign Online Editor Web Services Syntax String[] documentItemIds= searchDocumentItems (requestContext, searchCriteriaXML) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. searchCriteriaXML : String An XML string representing the search criteria. The AND connector will be used when searching with multiple criteria. For an example of a search criteria XML file, see Example, page 169. The criteria can use the following elements: • SEARCHCRITERIA. The root element of the search criteria XML file. • SECTION. The , , and element are the only subelements allowed in a

. • PHASE. The phase element encapsulates each piece of criteria in the searchCriteria file. PHASE can contain at least one of the following criteria: — CATEGORY_NAME. Supply the name of the category you want to search. — CREATED. Supply the date that the work items were created. Enter the value in the format that is specified in the eCor.properties (by default, responseDateSearchForamt=mm-dd-yy). For example, if you supply 03-28-12, it will search for all work items created between March 28, 2012 00:00:00 and March 28, 2012 23:59:59. If you supply multiple VALUES, it will be treated as an OR relationship between the days. — REQUESTER. Supply the name of the author who created or owns the work item. See REASSIGNER for more information. — REASSIGNER. Supply the name of the person who reassigned a work item to other users. For example, say there are two users, "user1" and "user2". User "user1" created work item 101, so the requester is "user1" and the reassigner is "empty". If user "user1" reassigns the work item to user "user2", the requester is now "user2", and the reassigner is "user1". — NAME. Supply the name of the document you want to search for. — CUSTOMER_KEYS. Enables you to search the customer key for values. This element can contain any number of KEY_VALUE elements. Each KEY_VALUE element is implicitly joined by an OR operator. — EDITOR. Supply the value of "tce" to specify the xDesign Online Editor. 168 xDesign Online Editor Web Services — STATUS. Supply the document status: Active, Pending Approval, Approved, or Rejected. — DATE_RANGE. Enables you to search within a specific date range. This element can contain RELATIVE or ABSOLUTE elements, which can contain OLDER, NEWER, FROM, or TO elements. • ORDERBY. Enables you to sort the list of returned work items. Placing parameters in this element will order the returned values in ascending order. The %, *, ?, and _ wildcard characters are supported for use in the CATEGORY_NAME, REQUESTER, REASSIGNER, NAME, CUSTOMER_KEYS, and EDITOR criteria. They are not supported in the CREATED, STATUS, and DATERANGE criteria, although no error will appear in the log. The full schema for the XML search criteria is located in . Example The following example shows how to structure the searchDocumentItems method. test Iam@EMC2038 xPression Response ]]>

Automatic Payment Letter * tce 03-28-12 Automatic Payment Letter Active xpression

169 xDesign Online Editor Web Services

1

NAME CATEGORY_NAME ]]> The following are additional examples of the DATERANGE element: 08-16-11 08-16-11 2 //Month Day Hour Minute 08-16-11 2 4 unlockDocumentItem The unlockDocumentItem method enables you to unlock a document item that has been opened and locked. To execute this method, the work item must currently be assigned to you, and you must have Read or Write access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns a string message when the method successfully unlocks a work item. For example: "Work item with id 605 has been unlocked successfully." Syntax String successMessage = unlockDocumentItem (requestContext, documentItemID) 170 xDesign Online Editor Web Services Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String A unique identifier for the document item, which is provided by the createDocumentItem method. addAnnotation The addAnnotation method enables you to add comments to individual work items. Notes can be Client Level type or Document Level type. Client Level notes attach to all documents with the same document ID and the same first primary key, while Document Level notes attach to a specific work item. To execute this method, the work item must currently be assigned to you, and you must have Read or Write access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns a string message when the method successfully adds the annotation to the work item. For example: "Annotation has been added to work item with 605 successfully." For more information on the structure for the addAnnotation method, see Example, page 172 . Syntax String statusMessage annotationText) = addAnnotation(requestContext, documentItemID, Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. 171 xDesign Online Editor Web Services Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String The unique identifier for the document item, which is provided by the createDocumentItem method. annotationInfo : String The XML formatted string that contains the annotation content. Example The following example shows how to structure the addAnnotation method: auser apassword xPression Response ]]> 605 updated customer address getDocumentItemInfo The getDocumentItemInfo method retrieves information about document items. The information is returned as an XML document. The amount of data returned for some work items could be quite large, 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 infoToReturn parameter. You can return information about the following items by passing the specified term in the infoToReturn parameter: • General. Shows general information about the work item, including the user who is currently assigned to the work item (owner), the work item user who created the work item (user), the work item category, the customer key used to create the work item, the time and date of the last modification to the work item, the ASL ID (which is used to retrieve information about the 172 xDesign Online Editor Web Services work item), the current status and state of the work item, the publisher type, and an indication if the work item is locked. • Document. Basic information about the document, including the document item ID, the document name, the document category, the publishing type, and the customer key of the user for whom the work item was assembled. • Annotation. For each annotation in the document, the method returns the annotation type, the user who created the annotation, the timestamp, and the annotation note itself. • Optional Paragraphs. Lists all the optional paragraphs in the work item. It displays each optional paragraph group, the group type, and whether or not it is configured for handling in batch. It also lists all the optional paragraphs in the optional paragraph group, listing the name, ID, an indication that the optional paragraph is shared or not, an indicator if the optional paragraph is selected or not, and the version number. • External Contents — A list of all external content in the document. For each piece of external content, this method reports the external content name, the external content type, the URL of the link to the external content, and the location of the external content. If the external content was added by an external content rule in xDesign, the name will be NULL. This information will be returned as follows: aaa PDF c:\pdf2htmlEX.pdf file To execute this method, the work item must currently be assigned to you, and you must have Read or Write access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns an XML document containing the requested information. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information on the structure for the getDocumentItemInfo method, and for a sample of the return XML, see Example, page 174 . Syntax String info = getDocumentItemInfo(requestContext, documentItemID, infoToReturn) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application 173 xDesign Online Editor Web Services name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String[] An array of unique identifiers for document items. Document IDs are provided by the createDocumentItem method. Information will only be returned for those items that you are allowed to access. If you have xResponse Admin access rights, you will see information for all the document items you request. Otherwise, you will only see information for those items for which you are the current owner. infoToReturn : String[] An optional parameter specifying a subset of the information to return. If this parameter is null or has zero strings, then all information will be queried and returned in the XML document. You may give any of these Strings as input into the method: • "General" • "Document" • "Annotations" • "OptionalParagraphs" • "ExternalContents" See the description of this method (The getDocumentItemInfo Method) for details about what information is returned for each string. Example The following example shows how to structure the getDocumentItemInfo method, and is followed by a sample of a response: auser password xPression Response ]]> 101 174 xDesign Online Editor Web Services The following is an example of a response to the above request: 8218944010464221449 test Automatic Payment Letter Active 2 False Automatic Payment Letter Automatic Payment Letter 1 xPublish 2012-03-28 14:54:31 2012-03-28 14:54:31 ]]> openDocumentItem The openDocumentItem method is used to open a document in the xDesign Online Editor within your own web application. This method requires the following items: • A token, already generated by the createAuthenticationToken method. The token will be used to verify user credentials, and then launch the xDesign Online Editor and open the specified document if the credentials are valid. • The document ID for the document to be opened, supplied by the createDocumentItem method. • An XML configuration file, used to determine which buttons in the xDesign Online Editor are enabled or disabled. 175 xDesign Online Editor Web Services Once a work item is opened, a lock will be added until you unlock it using the unlockDocumentItem method. To execute this method, the work item must currently be assigned to you, and you must have Read or Write access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns a URL that can be used to load the xDesign Online Editor into your custom application. The URL should be applied to the iframe into which you want to load the editor, by suppling the URL in the iframe src parameter. For more information on the structure for the openDocumentItem method, and for a sample of the return value, see Example, page 176 . Syntax String tceHtml = openDocumentItem(token, documentItemID, configuration) Parameters token : String A valid user token generated by the createAuthenticationToken method. documentItemID : String The unique identifier for the document item, which is provided by the createDocumentItem method. configuration : String An XML string representing the button configuration to be used in the editor. To see the entire editor configuration schema, see . Example The following example shows how to structure the openDocumentItem method, and is followed by a sample of a response: 49354c64-5265-49a5-8afb-1c0f9fdb3500 605 176 xDesign Online Editor Web Services http://localhost:8080 ]]> For more information on the PostMessage configuration in the editor configuration file, see . The following is an example of a response to the above request: 1789206527339793453 http://10.32.220.82:7001/xResponse/html/Edit? token=b48cb7a4-f5bf-42bf-af89-ba3818a0876c&filename=1332917665889 submitDocumentItem The submitDocumentItem method enables you to submit a document item to the next stage in your workflow, as defined in the category to which the document belongs. Once the document item has been submitted, it will be available for the next approver to see it and approve it. To execute this method, the work item must currently be assigned to you, and you must have Read or Write access to the document category. Return Value: This method returns a string message when the method successfully submits the document item. For example: "Document item: 100 has been submitted successfully." If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For example, the method will fail if the workflow is not defined. 177 xDesign Online Editor Web Services Syntax String submitMessage = submitDocumentItem(requestContext, documentItemID) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. workflowState : String[] The name of the workflow state to which the document item will be submitted. It is not the current workflow state, it is the destination workflow state. documentItemID : String[] The unique identifier for document item you want to submit. Document IDs are provided by the createDocumentItem method. rejectDocumentItem The rejectDocumentItem method enables you to reject a specified document item. You can add a note including the reason for the rejection using the addAnnotation method. To execute this method, the work item must currently be assigned to you, and you must have Approve access to the document category. Return Value: This method returns a string message when the method successfully rejects the document item. For example: "Document item: 102 has been rejected." If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For example, the method will fail if the document item is not in the pending approval list. Syntax String rejectedMessage Parameters requestContext : String 178 = rejectDocumentItem(requestContext, documentItemID) xDesign Online Editor Web Services An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String[] The unique identifier for document item you want to reject. Document IDs are provided by the createDocumentItem method. approveDocumentItem The approveDocumentItem method enables you to approve a specified document item. To execute this method, the work item must currently be assigned to you, and you must have Approve access to the document category. Return Value: This method returns a string message when the method successfully approves the document item. For example: "Document item: 100 has been approved." If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For example, the method will fail if the document item is not in the pending approval list. 179 xDesign Online Editor Web Services Syntax String approveMessage = approveDocumentItem(requestContext, documentItemID) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String[] The unique identifier for the document item you want to approve. Document IDs are provided by the createDocumentItem method. documentItemsAssignedToUserReturnInfo The documentItemsAssignedToUserReturnInfo method retrieves information about all of the document items currently assigned to the specified user. The information is returned as an XML document. The amount of data returned for some work items could be quite large, 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 infoToReturn parameter. You can return information about the following items by passing the specified term in the infoToReturn parameter: • General. Shows general information about the work item, including the user who is currently assigned to the work item (owner), the work item user who created the work item (user), the work item category, the customer key used to create the work item, the time and date of the last modification to the work item, the ASL ID (which is used to retrieve information about the work item), the current status and state of the work item, the publisher type, and an indication if the work item is locked. • Document. Basic information about the document, including the document item ID, the document name, the document category, the publishing type, and the customer key of the user for whom the work item was assembled. • Annotation. For each annotation in the document, the method returns the annotation type, the user who created the annotation, the timestamp, and the annotation note itself. • Optional Paragraphs. Lists all the optional paragraphs in the work item. It displays each optional paragraph group, the group type, and whether or not it is configured for handling in batch. It also lists all the optional paragraphs in the optional paragraph group, listing the name, ID, an 180 xDesign Online Editor Web Services indication that the optional paragraph is shared or not, an indicator if the optional paragraph is selected or not, and the version number. • External Contents - A list of all external content in the document. For each piece of external content, this method reports the external content name, the external content type, the URL of the link to the external content, and the location of the external content. If the external content was added by an external content rule in xDesign, the name will be NULL. This information will be returned as follows: aaa PDF c:\pdf2htmlEX.pdf file To execute this method, the work item must currently be assigned to you, and you must have Read access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns an XML document containing the requested information. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String documentItemInfos = documentItemsAssignedToUserReturnInfo(requestContext, userName, infoToReturn) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. userName : String The username of the user for whom you want to return information about assigned document items. infoToReturn : String[] 181 xDesign Online Editor Web Services An optional parameter specifying a subset of the information to return. If this parameter is null or has zero strings, then all information will be queried and returned in the XML document. You may give any of these Strings as input into the method: • "General" • "Document" • "Annotations" • "OptionalParagraphs" • "ExternalContents" See the description of the getDocumentItemInfo method for details about what information is returned for each string. searchDocumentItemReturnInfo The searchDocumentItemReturnInfo method enables you to search for a work item based on criteria, and retrieves information about the located item. The information is returned as an XML document. The amount of data returned for some work items could be quite large, 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 infoToReturn parameter. To execute this method, the work item must currently be assigned to you, and you must have Read access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns an XML document containing the requested information. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String documentItemInfos= searchDocumentItemReturnInfo (requestContext, searchCriteriaXML, infoToReturn) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. searchCriteriaXML : String 182 xDesign Online Editor Web Services An XML string representing the search criteria. The AND connector will be used when searching with multiple criteria. For an example of a search criteria XML file, see Example, page 169. The criteria can use the following elements: • SEARCHCRITERIA. The root element of the search criteria XML file. • SECTION. The , , and element are the only subelements allowed in a

. • PHASE. The phase element encapsulates each piece of criteria in the searchCriteria file. PHASE can contain at least one of the following criteria: — CATEGORY_NAME. Supply the name of the category you want to search. — CREATED. Supply the date that the work items were created. Enter the value in the format that is specified in the eCor.properties (by default, responseDateSearchForamt=mm-dd-yy). For example, if you supply 03-28-12, it will search for all work items created between March 28, 2012 00:00:00 and March 28, 2012 23:59:59. If you supply multiple VALUES, it will be treated as an OR relationship between the days. — REQUESTER. Supply the name of the author who created or owns the work item. See REASSIGNER for more information. — REASSIGNER. Supply the name of the person who reassigned a work item to other users. For example, say there are two users, "user1" and "user2". User "user1" created work item 101, so the requester is "user1" and the reassigner is "empty". If user "user1" reassigns the work item to user "user2", the requester is now "user2", and the reassigner is "user1". — NAME. Supply the name of the document you want to search for. — CUSTOMER_KEYS. Enables you to search the customer key for values. This element can contain any number of KEY_VALUE elements. Each KEY_VALUE element is implicitly joined by an OR operator. — EDITOR. Supply the value of "tce" to specify the xDesign Online Editor. — STATUS. Supply the document status: Active, Pending Approval, Approved, or Rejected. — DATE_RANGE. Enables you to search within a specific date range. This element can contain RELATIVE or ABSOLUTE elements, which can contain OLDER, NEWER, FROM, or TO elements. • ORDERBY. Enables you to sort the list of returned work items. Placing parameters in this element will order the returned values in ascending order. The %, *, ?, and _ wildcard characters are supported for use in the CATEGORY_NAME, REQUESTER, REASSIGNER, NAME, CUSTOMER_KEYS, and EDITOR criteria. They are not supported in the CREATED, STATUS, and DATERANGE criteria, although no error will appear in the log. The full schema for the XML search criteria is located in . infoToReturn : String[] 183 xDesign Online Editor Web Services An optional parameter specifying a subset of the information to return. If this parameter is null or has zero strings, then all information will be queried and returned in the XML document. You may give any of these Strings as input into the method: • "General" • "Document" • "Annotations" • "OptionalParagraphs" See the description of the getDocumentItemInfo method for details about what information is returned for each string. copyDocumentItem The copyDocumentItem method makes a copy of a document work item and assigns it to the specified user. The advantage of using this method is that it enables you to reuse all the previous customizations of that work item. To execute this method, the work item must currently be assigned to you, and you must have Read or Write access to the document category; or you must have xResponse Admin access to the category that contains the document. Return Value: This method returns a string message that identifies the newly copied document work item. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String newDocumentItemId = copyDocumentItem (requestContext, documentItemID, assignToUserName) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String The unique identifier for the document item, which is provided by the createDocumentItem method. assignToUserName : String 184 xDesign Online Editor Web Services The username to whom you want to assign the work item. addExternalContentByStream This method enables you to add external content to your document as a byte stream. This method adds the byte array of the external content to the end of the specified document. Return Value: This method returns a string message if the method was successful. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. 185 xDesign Online Editor Web Services Syntax String ret = addExternalContentByStream (requestContext, documentItemID, externalContent, format, name) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String The unique identifier for the document item, which is provided by the createDocumentItem method. externalContent : byte [] The byte array for the external content. format : String The file format of the external content. Choose one of the following valid values: • pdf • word.doc - not supported when using a URL link. This format is only supported for use with Local Path and ECM link. • tif, tiff - both "tif" and "tiff" are valid values. name : String The name of the external content. This name is referenced by the getDocumentItemInfo and deleteExternalContent methods. The name should be unique, especially if there are multiple external content additions that may need to be deleted at a later date. addExternalContentByLink This method enables you to add external content to your document through a link. This method adds the byte array of the external content to the end of the specified document. Return Value: This method returns a string message if the method was successful. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. 186 xDesign Online Editor Web Services Syntax String ret = addExternalContentByLink (requestContext, documentItemID, externalContentLink, format, name) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String The unique identifier for the document item, which is provided by the createDocumentItem method. externalContentLink : String A link to the location of the external content. You can supply a local file path on your server, a URL, or an ECM path. • Local File Path Syntax - \\. For example: C:\xPression\externalcontent\sample.pdf • URL Syntax - http:///path/. For example: http://10.0.0.0/externalcontent/sample.pdf • ECM Path Syntax - ecm::?uri=//?version=. For example: ecm::DCTMServer?uri=/externalcontent/sample.pdf?version=CURRENT format : String The file format of the external content. Choose one of the following valid values: • pdf • word.doc - not supported when using a URL link. This format is only supported for use with Local Path and ECM link. • tif, tiff - both "tif" and "tiff" are valid values. name : String The name of the external content. This name is referenced by the getDocumentItemInfo and deleteExternalContent methods. The name should be unique, especially if there are multiple external content additions that may need to be deleted at a later date. 187 xDesign Online Editor Web Services deleteExternalContent This method enables you to delete a specified piece of external content. Return Value: This method returns a string message if the method was successful. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Syntax String ret = deleteExternalContent (requestContext, documentItemID, name) Parameters requestContext : String An XML document that passes user credentials for authentication. It also passes the name of the application for which the user is authenticated. In xPression, users are given access rights to specific applications because each application has a different set of access rights. By specifying the application name, you are requesting the access rights granted to the user for that specific application. Please be aware that the application name you use must grant permissions that are appropriate for your request. For this method, only the xPression Response application is valid. For more information, see Authentication, page 160. documentItemID : String The unique identifier for the document item, which is provided by the createDocumentItem method. name : String The name of the external content that you want to delete. This is the name used when adding the external content through the addExternalContentByLink and addExternalContentByStream methods. This method can only delete external content that was added through Web Services. This method cannot delete external content added in xDesign. Clean Up xDesign Online Editor Temp Folders When you use xPression Web Services to create, open, or edit a work item, xPression creates temporary folders to support the action. These folders are not deleted when your session ends. When opening the editor from xResponse, the temp files will be deleted when you log out. You can now configure xPression to clean up these folders automatically. To enable this feature, you need to perform two tasks: 1. On your xPression Server, open ecor.properties for editing. This file is located in your xPressionHome directory. 2. Locate the following section: #Delete xResponse temporary folders when "last modified" time exceeds 188 xDesign Online Editor Web Services threshold. 189 xDesign Online Editor Web Services TimeAmountSinceLastModifiedInHours=8 #Scan xResponse temporary folders on this interval. 30 seconds min, 1800 seconds max. FolderScannerSleepTimeInSeconds=30 3. Set the TimeAmountSinceLastModifiedInHours property to the number of hours you want the temporary folders to persist before they can be deleted. This value must be a whole number. 4. Set the FolderScannerSleepTimeInSeconds property to the number of seconds you want to set as the interval for the feature to scan the temporary folders. 5. Save and close the file. 6. Next, you have to activate the feature. You do this in xAdmin. Log in to xAdmin, click the System Management menu, then click Service Management. 7. There will be a item in the list for the "xResponse Temporary Folders Cleanup" service. Click Start to start the service. If you want to stop the service, you can do that from this same page. You must manually start this service each time you restart the xPression Server. 190 Chapter 11 The xPression DevKit xEditor Component xEditor is a Microsoft Word-based editor that enables you to use Microsoft Word’s powerful editing and composition features. xEditor is used for editing by xRevise, xResponse and by custom applications created with the xPression DevKit. Refer to the xAdmin User Guide for details on available configuration options. This chapter describes xEditor and its controls, general setup procedures such as how to install it, and what Microsoft Word features and functions are supported and which are modified to work with xPression work items. Before You Begin xEditor can not exist on a system in which Word has the Adobe Acrobat PDFMaker add-in for Acrobat 9 enabled. This is an issue with the Adobe add-in, and not xEditor. The add-in must be disabled for xEditor to function. In many cases Microsoft .NET Framework will already be installed. If .NET is not present, then xEditor will display a message with a link to a download site where you can obtain the installation package for .NET Framework. If you receive this message, download the .NET Framework package and follow the installation instructions provided by Microsoft. After successfully installing .NET Framework: 1. Log off xEditor. 2. Close and reopen Internet Explorer. 3. Log on to xEditor and select the work item that you want to open. Internet Explorer Settings Automatically detect settings in Microsoft Internet Explorer’s Local Area Network (LAN) Settings should NOT be selected. Significant performance degradation for xEditor has been noted when this option is selected. It will be noted as a Warning in the xEditor log if selected. 191 The xPression DevKit xEditor Component User Configuration The only configuration requirement is that the user must have read, write, and create access to the directory ’C:\Documents and Settings\[user]\Application Data\EMC Document Sciences’ to use the xEditor application. xEditor needs to write log and other files to this location. You do not need to enable cookies or Java to use xEditor. How xEditor 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 runs every time a document is opened for editing with xEditor. Smart Client is based on Microsoft .NET technology. Smart Client may determine that the xEditor versions on the client and server are not the same. If the client version is newer the option to downgrade to the server version is offered, if the client version is older the option to upgrade is offered. xEditor will offer to upgrade or downgrade the client version so that it matches the xEditor version used on the server. When upgrading or downgrading, the Smart 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 xEditor version on the server. If you choose not to upgrade or downgrade, xEditor will not launch. Running xEditor the First Time The client installation itself is largely automatic. If all required components are present, a message displays. xEditor uses a Smart Client to open xEditor when you open a work item for editing. The Smart Client ensures: • xEditor is installed • 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 only once per machine, even if multiple applications that employ xEditor are used on that machine. The initial installation adds a shortcut to ALL USERS \start menu\programs\startup. This queues a pre-WIP version of xEditor when the machine starts up. This reduces the amount of time required for xEditor to open a work item. There will be an instance of WINWORD.EXE running, with all required supporting software. This instance appears in Task Manager and can be shut down, but if it is shut down xEditor will take longer to open work items than would otherwise be the case. 192 The xPression DevKit xEditor Component 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 Warning that xEditor.dot contains macros. xEditor uses macros to override some Word functions, so choose Enable Macros if you receive this message. 2. The xEditor Setup Wizard starts. Click Next. 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 a different location, type the desired path in the Folder field, or click Browse and choose a location from 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 is complete. 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 can use to remove xEditor if necessary. If you open a document that needs xEditor after uninstalling the editor, Smart Client will initiate the installation process. The installation applies to either xRevise, xResponse, or any xPression DevKit application that uses xEditor regardless of which one you were using when you started the installation. Note: Whenever xEditor starts it creates a temporary configuration file, config.txt, on the client. This file is deleted after use unless running in debug mode. It is strictly for internal, session-specific use and 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 machines lack the permissions to conduct the installation as described above. In this case xEditor can be pushed to the client machine by the network administrator or any qualified person with appropriate access. The xEditor installer is stored in a ZIP file, xEditorInstaller.zip, which is located in the server-deployed xPression_Revise.war and xPression_Response.war files. The method for installing depends on your network environment. 193 The xPression DevKit xEditor Component Opening xEditor After “Failed to start editor. Exception from HRESULT: 0x8004063B” 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 than English. The issue can be avoided with the following procedure. This procedure does not affect the setting in Microsoft Word. 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 select WinWord.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 standard Microsoft 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. Load xEditor from your IDDK application. xEditor will automatically install as first-time installation. The xEditor Interface xEditor enables Microsoft Word to act as the editor. The main difference between Word’s interface and xEditor is the addition of the Document Actions pane, which is displayed in Word’s Task Pane. Figure 1. xEditor works with Microsoft 2007 (shown) and 2010. The xEditor Task Pane is the same for both versions. The Document Actions Pane The Document Actions pane resides in the Task Pane. It opens docked to the right side of the window by default, but you can relocate it if desired. You can access all xEditor functions through 194 The xPression DevKit xEditor Component the Document Actions pane. Word provides a number of functions through the Task pane, such as the XML Structure pane. You can switch panes by clicking the title bar currently displayed and selecting 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 Task pane, 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 two display areas. • The xEditor Toolbar • Table of Contents • Properties The xEditor Toolbar The buttons on the xEditor toolbar, near the top of the pane, perform these functions. • xEditor — 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. See Deleting and Undeleting Revision Units. — Cache Settings opens the Cache Settings dialog box. See Cache Management for details. — xEditor Log opens the xEditor log in a text editor. See The Log. • Debug — The Debug button is not normally displayed, but xEditor can be configured to display it by the xPression administrator. This feature should be enabled and used only as directed by EMC Document Sciences Solution Support. • Forward Backward — Moves the focus to the next or previous variable in the document. 195 The xPression DevKit xEditor Component • Save — Saves the document. This increments the revision number for any section that has been changed since the last time that the document was saved. This also creates a new xPression database object. Note that xPression removes unused xPression database objects to prevent problems with search and other issues. • Search — Opens the Search window in the Task pane. See Finding Existing Content, page 202 for details on using the Search function. • 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. This button appears if the work item contains form fields and a section under Filling In Forms protection only. • Insert RU — Opens the Insert RU window in the Task pane where you provide a name, jurisdiction(s), and language for the new revision unit. The new RU is inserted after the element that is currently selected in the TOC, either an RU or the root element. See Adding New Content. The Table of Contents Section The TOC shows the document structure. Nodes in the tree represent Revision Units. or RUs. RUs are established in the document when it is created in xDesign, and function as content items or sections. All xEditor work items contain at least one RU. An asterisk is appended to the node’s name when any change is made that affects the assembly, such as adding or moving an RU. You can add new content items, 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 the edit pane and the Revision Unit’s properties are displayed in the Properties window as shown in below. Double-clicking an RU in the TOC selects the entire RU in the edit pane. RUs with unsaved changes 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 are marked with an asterisk showing that there was a change, even if the content of the RU remains the same. Multi-page TIFFs and PDFs can be included in the document by the document designer. The external content item is represented as an RU in the TOC. If the document designer does not establish an RU for the external content, an RU will be created when the work item is created. The external content’s RU is represented in the TOC by a distinctive icon. The external content’s RU will include a child node 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 a page that had been marked for exclusion, right-click the node and select Include. Page selections are retained for subsequent sessions. External PDF other than universal content PDF does not support Exclude/Include. The document designer can add a variety of document types as external content in addition to PDF and TIFF, including universal content and other xDesign documents. The distinction between external content and master document content is not apparent to the xEditor user, except in the cases of 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 TOC is not possible when in Header/Footer mode. To exit Header/Footer mode, click outside the header or footer region, or click Close Header/Footer. 196 The xPression DevKit xEditor Component Some xEditor functions are not available through the toolbar, but can be accessed by right-clicking the document node or any RU in the TOC. The right-click menu for the document node provides the 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 xEditor, but changes will not be available to xEditor. • 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 work item is saved. Annotations can also be attached in xDesign. New annotations can be added to the work item using the New Annotation button on the Command Bar. • Compare to File — Opens the Compare window where you can compare the current work item with either a work item stored in the xEditor 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. 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 with the delete status of the RU. You cannot delete the last RU in the document, so this option is available 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 once created. Annotations can be added to xEditor work items with the New 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 to include or exclude the page. All pages are included by default. 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 the TOC are below this node. • Revision Unit — xEditor documents are divided into Revision Units. Each RU is represented with this icon. Some RUs have further child nodes. • External Content — The document designer can include external content in the document. Each piece of external content is contained in its own RU represented by this icon. Multi-page TIFF and PDF content represents 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 External Content RU node. If the external content is a multi-page TIFF right-clicking the child node opens a context menu that provides the option of skipping the page. 197 The xPression DevKit xEditor Component • Multi Select — Multi-select Optional Content Group - Any combination of optional content under a Multiselect Optional Content Group can be selected. Clicking a selected item deselects it. You are never required to select optional content. See Optional Content, page 200. • Single Select — Single-select Optional Content Group - Only one optional content item under a Single-select Optional 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. See Optional Content, page 200. The Information Panel Immediately below the TOC section is the Information Panel, which consists of several grids that show details related to the current selection. Each grid in this panel displays the indicated information related to the selected element. By default the Variables grid is expanded and the Properties and Attributes 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 cannot be changed in xRevise, so this grid is read-only except when creating a new revision unit. The following properties are displayed when the highest level node is selected: • Name • Work ID • Last Saved Time • Customer Key • Category Name • 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 Merge Paragraphs 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 of the annotation is displayed. If the Revision Unit was inserted from search results and contains variables, then the variables are displayed as well. If an optional content group is selected the name and 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 when it is manually inserted into xRevise. RUs created from content item search are initially assigned the Create 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 RU cannot be renamed if the Revision is 1 or greater. 198 The xPression DevKit xEditor Component Note: The value for an attribute may be blank (nothing indicated for the attribute) or if there is 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 it indicates 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 document if the document node is selected or the RU if an RU is selected. Refer to Variables for more information on using the Variables grid. The Command Bar The Command Bar, located at the top of the Information Panel of the Task Pane, provides access to several features provided for working with variables, and enables adding a new annotation to the work item. • Toggle Variable Editing The Variables grid must be in Edit mode to allow variable editing. Click this button to toggle Edit mode on and off. Toggling the Edit mode cannot override certain protections that may be imposed on variables: some variables can never be edited, some variables may be under protection established by the document designer, and the xPression administrator can prevent any variable editing. See Editing Variables for more information on working with variables and variable values. • Variable Navigator Opens the Variable Navigator, which displays all values that have been applied to the selected variable and where it is used within the work item. Values must have been saved to appear in the history. 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 xEditor Menu When running xEditor, Word’s menu bar includes an xEditor menu. The main purpose for this menu is to provide a convenient means of opening the Task Pane in the event that it closes. It also provides some functions that are also available in the xEditor menu on the Task Pane. • Show xEditor opens the Task Pane. • Show Log opens the xEditor log in a text editor. See The Log . Deleting and Undeleting Revision Units To delete a revision, right-click the revision unit in the TOC and then click Delete/Undelete. Deleted RUs appear in the TOC with a deleted mark. You can toggle between showing and not showing deleted sections by clicking Hide deleted TextPieces. 199 The xPression DevKit xEditor Component 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. Optional Content A section can be designated as optional when it is created in xDesign. Optional sections are indicated in the xEditor TOC by a checkbox. If you clear the checkbox, the section is not included when the document is published. You are never required to choose any optional content. The document designer can mark content for Merge. When adjacent content is marked for merge the items are combined into a single paragraph. Optional content that has been marked for merge is indicated along with Properties in the Merge Paragraphs section of the grid. Paragraphs must be adjacent to be merged. If one of the content items includes form fields then both must be protected with 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 the same value throughout the RU. If the variable has different values within the RU, all instances will be converted to static text. In this case the static text will be editable, but will no longer be treated as a variable. See Variables, page 218 for more information on working with variables in xEditor. Note: Variables in work items that were created in earlier version of xPression and upgraded to xPresson 4.0 will be converted to static text in most cases, regardless of value. Localization xEditor determines what language resource file to load based on the Windows language and region settings of the machine where it is installed. 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 language resource: US English. xEditor Functions xEditor supports most Microsoft Word features and it provides additional functionality to support functions needed to work within the xPression environment. Refer to Microsoft Word Features and Functions for detailed information on xEditor’s impact on standard Word functions. Note: Paragraph styles should not be created in xEditor. They should be added to the xDesign template and made available to xEditor through the xPression server. Character styles should not be used in xEditor. 200 The xPression DevKit xEditor Component Cache Management xEditor caches work items locally to improve performance. First-time load performance for a work item may be somewhat slower due to the need for web service calls to retrieve the work item from the xPression server. The xPression Administrator can configure the system to clear the cache automatically. The primary reason for automatically clearing the local cache is for security. In cases where xEditor users work with documents that contain sensitive information, deleting local copies of the document helps to prevent unauthorized access to this information. The administrator can configure the system to delete cached files after a set amount of time or when the cache size exceeds a specified amount. If the system is not configured to automatically delete cached files, the cache should be cleared manually as required to prevent an excessive accumulation of files. You can clear the xRevise cache manually, through the Windows file system, or through the xRevise interface. To clear the xEditor document cache from the Local Work Item Cache dialog box: 1. Log on to 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 application menu, select Cache Management. The Local Work Item Cache Settings dialog box opens showing the current settings. If the dialog box has not been enabled it will still open, but will indicate that the feature is disabled. 3. Click Clear Now. To clear the xEditor cache from the Windows file system: 1. Close xEditor. It is not necessary to close the host application, 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. Cache files are stored in [Drive]:\Documents and Settings\[WINDOWS_LOGIN_NAME]\Application Data\EMC Document Sciences\. Each work item has its own folder. 3. Delete some or all of the cached files. You can delete work item folders if desired. The Log xEditor creates a log file that records the configuration setting used to start xEditor, the elapsed time for all web service calls, and errors with stack traces. When a failure occurs, a message opens with a link that opens the file in a text editor. You can also open the log file by selecting xEditor Log from the xEditor menu on the xEditor toolbar. The log file is located in C:\Documents and Settings\[USER]\Application Data\EMC Document Sciences\[xEditor]\[server]\xEditor.log. 201 The xPression DevKit xEditor Component Finding Existing Content Content that you, or other xEditor users, have created for other work items can be reused. Use the Find utility to locate any combination of text, content item descriptions, or content attributes. Click the Search button or right click the section and select Find Content. Configure your search statement, then click the Search button on the toolbar. Microsoft Word’s Find and Replace feature is also available, but is significantly modified for use with xEditor. 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’s Search feature is also available for searching the current document. These functions are available in the Find window: • 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 Installer’s Handbook for instructions on enabling Full Text Search. • Search Options: Search For — By default, both standard and custom content for all versions is included in the search. You can limit 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. Does not 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 a revision number of 0. • Search Options: Match — Choose whether you want to return any item that contains a word or phrase, or only exact matches. • Match These Attributes — Content attributes will vary, and may not be associated with a work item at all. Press Start Search when you are ready to start the search. Search results display in a window below the TOC. Search results are sorted by last modified date, from latest to earliest. Double-click the item for a 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 you will be prompted to rename it. Duplicate names are not allowed. 202 The xPression DevKit xEditor Component The Search Results toolbar provides these functions: • 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. If the searched item exists in multiple documents each document is listed in the Owner Document section of the Search Results. In addition to the customer key, which would identify the work item where the content is used, the Owner Document section shows the following for each work item: Status, Current State, Last Modified time stamp, and whether it is in use. This information is for the document, not the specific RU. The xEditor Find utility is limited to 101 return items. In addition, databases have the ability to exclude certain common words. SQL and Oracle provide similar support to exclude noise. A complete list of words excluded from SQL full text search is available in the xRevise User Guide. DB2 does not support stop word processing. See DB2 Text Search and Net Search Extender Comparison for information 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 versions of Microsoft Word. Find and Replace will not find variables, hidden text, or DCPI fields, such as subtotals and indexes. Features that are available in xEditor have the same functionality as provided in Microsoft 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 so forth are not supported for searching in xEditor. • Special — Special characters, such as paragraph marks, tab characters, fields, and so forth are not supported 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. 203 The xPression DevKit xEditor Component • Ignore Whitespace — This option, available on some versions of Microsoft Word, is not available in xEditor, regardless of the Microsoft Word version used with xEditor. • Ignore Punctuation —This option, available on some versions of Microsoft Word, is not available in xEditor, regardless of the Microsoft Word version used with xEditor. • Match Prefix — This option, available on some versions of Microsoft Word, is not available in xEditor, regardless of the Microsoft Word version used with xEditor. • Match Suffix — This option, available on some versions of Microsoft Word, is not available in xEditor, regardless of the Microsoft Word version used with xEditor. The Replace function will not replace text in variables or hidden text. The following standard Replace options are not available in xEditor. • Format — Formatting information, such as font settings, paragraph settings, tab settings, and so forth are not supported for replace in xEditor. • Special — Special characters, such as paragraph marks, tab characters, fields, and so forth are not supported for replace in xEditor. Adding New Content You 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 in the 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 move the RU after it is created if necessary. 2. From the xEditor toolbar, click the New RU button. The Insert RU pane opens. 3. Provide a name for the new RU in the Name field. 4. If you use the optional jurisdiction attribute, select at least one Jurisdiction from the list. 5. Select a Language from the list. Once the RU is created the Name, Jurisdiction, or Language cannot be changed. 6. 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. Using xEditor Editing documents in xEditor is very similar to editing documents in Microsoft Word. Most Word 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. 204 The xPression DevKit xEditor Component You must log off xEditor whenever your user session closes. xEditor will not close automatically. It is possible to continue working even though the host application session has timed out. Caution: It is possible to open multiple 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. If the host application session closes, whether by user action or timeout, and a work item remains open in xEditor, the work item will remain locked until the xEditor session is closed. A message displays when the host application session closes with a work item locked reminding the user to close the editor when finished editing. It is necessary to lock documents when they are open in xEditor. While a document is locked, you will not be able to use the Submit, Delete, Carry Forward, or Assign actions. A message will display when any of these actions are attempted. The text of the message is “Work Item has been locked, you need to unlock this work item first.” If xEditor stops without properly closing the document, the same user can reopen the document. Microsoft Word will occasionally display document Auto Recovery task pane when launched in xEditor. xEditor does not support this Auto Recovery feature. When presented with the Auto Recovery pane, please close the pane by clicking Close. Do not attempt to recover any files. Closing xEditor xEditor is an extension of Microsoft Word. To close xEditor, simply close the Word instance hosting it. For example, clicking the Close button in the upper-right corner of the Word window will close Word and xEditor. Ensure that all work is saved before closing the application. Note that Word’s auto save feature does not save your work to the xPression database. Track Changes xEditor uses Word’s Track Changes feature, so changes made to documents in xEditor will appear in red and underlined by default. Select the Final display option, rather than the default Final Showing Markup option, to suppress showing changes in the Edit window. In Microsoft Word 2007 and 2010 the display option is located in the Tracking section of the Review ribbon. Refer to your Microsoft Word documentation for more information on Track Changes and the display options. The Accept and Reject options are not available for Track Changes in xEditor. Local Files xEditor creates a file structure on the client to avoid excessive calls to the server, and so to improve performance. The files stored here are the application files downloaded from the server, not the assembled document files. The structure is located under C:\Documents and 205 The xPression DevKit xEditor Component Settings\[user]\Application Data\EMC Document Sciences\[server_port]\[document]. The variable parts are as follows: • [user] - The current Windows user (not necessarily the xEditor 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 W2003_DEFAULT_CONFIG.xml file is changed, the local copy for each document on each client machine must be deleted to apply the changes. It is possible that different documents can have different toolbar configurations in xEditor if this file is not deleted when changes are made on the server. Smart Client automatically replaces the file on the client machine if the file is necessary. xEditor saves a Word-format copy of the document in the \[document] folder. This file cannot be opened outside of xEditor. A message opens when the user attempts to open this file directly in Word. Microsoft Word Features and Functions xEditor supports most Microsoft Word features and functions. Some functions are not supported because xEditor provides a similar function for use within the xPression environment. For example, Word’s New function is not supported because work items for xEditor must be created in xDesign; they cannot originate in xEditor. Microsoft Word’s selection logic has been modified to maintain variable integrity. See Selecting Variables. Caution: Many add-ons are available for Microsoft Word. Using xEditor with third-party add-ons may produce unexpected results. The following Word functions are either not available with xEditor, or the stock functionality is modified by xEditor. It may be possible to enable toolbar buttons or menu item for those that are not supported, but the function is still overridden by xEditor. It is also possible disable others, see Ribbon Configuration 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. • Create or Modify Style xEditor does not support creating new styles. When xEditor detects a new style, the style is deleted and a message is displayed. xEditor does not support modifying styles. Users should not modify styles because satisfactory results cannot be guaranteed. • New Window Word does not allow this option while running with xEditor because an XML expansion pack is attached. This limitation is imposed by Word. The following Word features work differently in xEditor. • Created On 206 The xPression DevKit xEditor Component The Created On option for Insert Auto Text does not insert the actual date the document 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, depending on whether the document includes optional paragraphs or not. If the document does not include any optional paragraphs, then the entire RU is selected. If the document includes optional paragraphs, then the text of the current node is selected. • Protection xEditor supports Read Only and Forms Fill-In protection types with some restrictions. See Protection. • Drag and Drop Drag and drop is not allowed if the current selection includes a variable or a DCPI field. xEditor will not permit data to be dropped into a variable or DCPI field. 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 the file system Edit FindReplace The Find, Replace, and Go To functions in Word are modified significantly from the standard implementation. See Finding Existing Content. Go To Tools Spelling and Grammar Spelling and Grammar is available, but the functions have been modified to accommodate special needs and circumstances introduced to the document by xEditor. The differences are not readily apparent to the user. Tools Compare Merge xEditor allows comparison and merge with historical copies of the current document, or Word documents from the file system. The following Word functions are not supported and cannot be used with xEditor. • File 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 207 The xPression DevKit xEditor Component Note that Track Changes is used by the application. Unlike other items in this list, it cannot be turned off. • 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 enable features disabled by xEditor. Hidden Table Borders If a document that includes a table with a hidden border is created in Microsoft Word 2003 and the document is subsequently opened in a later version of Microsoft Word, the table border will not be hidden and the tag or style in the document will be updated accordingly. Editing Actions in xEditor Access to headers and footers and to the spell check and grammar check features is provided directly through the Microsoft Word interface. Headers and footers are accessed either by double-clicking in the 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. Options for automatic grammar and spelling provided by Microsoft Word are available in xEditor. Editing options for CompuSet content has not changed with xEditor. CompuSet code can be modified as before. CompuSet code can be shown or hidden using the Show/Hide hidden text button. Refer to the CompuSet documentation for information on working directly with CompuSet. Exercise caution when working with CompuSet code; documents with faulty CompuSet commands will most likely be rendered unusable. Form Fields xPression supports Drop Down, Text, and Check Box form fields in documents. Form fields are added 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 or not, return the value of the variable when the document is assembled regardless of the protected state of the document. Variables cannot be used to establish the state of Check Boxes. Supported form fields must be selected from the Legacy Tools list in the Controls section of the Developer ribbon when the document is created in xDesign. 208 The xPression DevKit xEditor Component Documents that include form fields and are intended for use with xEditor must use Filling In Forms protection in any section that includes a form field. Since Read Only protection is applied to the entire document if it is applied to any part of the document, documents with form fields cannot include any section with Read Only protection. Form fields in documents that have been properly added and protected in xDesign are included in the document when used to create a work item in xEditor. If the default value of the variable is changed in xEditor then the variable is converted to static text and will no longer be handled as a variable in Carry Forward and Search operations. Note: Variables located within iterative structures, such as loops and table rules, are cached when the document is assembled and converted to static text, so the variables will not update after the work item is created. Also, if a variable is repeated within a Revision Unit the value of the first instance of the variable is applied to all instances of the variable within that RU, even if the variable changes while the RU is being processed. Documents with Word form fields can be used as work items in xEditor. When the xEditor user opens a work item with form field values are set to the default values, which are established by the document designer. The xEditor user can change the values of the fields normally. The TAB key can be 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 type of form field. The selected or specified value is retained for future sessions. xEditor users cannot modify any form field property except the value. xEditor will retain the variables as default values and drop list items only if the default value, that is the value established in xDesign, of the form field has not been modified. If the default value is changed, then the default value and the drop list items will be converted to static text. This will be apparent in Carry Back, Carry Forward (if variables are changed) and search and insert of customized revision units. In these cases changes in variable values will not be applied to the modified form fields. Content that includes form fields can be searched and inserted into other sections as long as the target section is under Filling In Forms protection. Some applications may not permit users to specify an output profile for previews, so the preview PDF will always show form fields as static text. In applications that do, if none 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 the selected value. When published as Fill-in PDF the field is published as a form field with the value selected or specified by the xEditor user presented as the default. If the value of a variable used in a form 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 Options dialog box under Field Settings. The bookmark is required for Form Fields. Ensure that the field’s Bookmark setting has some value, if the default is not desired. Multiple paragraphs, sections of text separated by a carriage return, are supported in text form fields 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} 209 The xPression DevKit xEditor Component • {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 on form fields apply for any document used in xEditor. Protection xEditor supports Read Only and Forms Filling in Forms protection types for work item content, but only one type within a given document. Protection must be established in xDesign when the document is created. Documents should be protected with only one form of protection. Mixing protection type within a document is not recommended. If an xPublish master document includes an xPublish sub-document with 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 the master document. Specific selections in documents with Read Only protection can be made available for 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 applied when the document is merged. Only the first protection type encountered is honored, and Read Only protection applies to the document while Filling In Forms protection applies to individual sections. So if a Read Only section follows a Filling In Forms section, the Read Only section will not be protected. However if a Filling In Forms section follows a Read Only section then the entire document is read-only except for any regions marked as available for editing in designated Read Only sections. There may be cases where this behavior can be exploited, but there is a high potential for unintended results, especially in complex documents, and so the use of mixed protection types within a document is not recommended. The xEditor user cannot resolve problems that arise from improper use of protection, but should be aware that they may occur and should be referred to the document designer for resolution. There is no validation for protection; it is the document designer’s responsibility to ensure that the proper protection is applied to the document. 210 The xPression DevKit xEditor Component In xEditor when an RU is added through the Search and Insert feature the current work item protection is extended to the inserted content: • If the work item content is protected with ’read-only’, the inserted revision unit content will also be protected with read-only protection. This means if there are no editable regions identified in the 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 revision unit content will also be protected with ’forms fill-in’ protection, if there is a section in the inserted content marked as protected. • If the work item content is not protected, the inserted revision unit content will also not be protected - 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. Read Only Protection Read only protection enables you to apply protection to the entire document and to designate certain regions–from a single word to a series of paragraphs–as available for editing to any users. You can designate multiple, non-continuous sections as available for editing. Regions not designated as available for editing can be edited only if the user turns protection off. xEditor users can turn protection off for the current session if using a custom ribbon where the Protect Document item has been enabled. Refer to the xAdmin User Guide for information on creating custom toolbars and ribbons. 211 Configuring Microsoft Word Ribbons You can change the Microsoft Word ribbon configuration to enable or suppress the elements on the ribbon. While changes that you make through the Word interface are limited to the current session, change made through a configuration file wile last beyond the current session. Changes made in the configuration file affect all users of the application on the xPression server where the configuration file is located. Each server can have a different configuration. The configuration files are located in the xEditor folder of your xPressionHome directory. This file used to be located in the EAR directory, please note the new location. EMC Document Sciences provides sample configuration files to help you get started: • W2003_DEFAULT_CONFIG.xml for Microsoft Word 2003 environments • W2007–2010_DEFAULT_CONFIG.xml for Microsoft Word 2007 and 2010 environments. Simply copy and rename the appropriate configuration file to create your custom configuration file. Once your file is configured, you must specify the configuration file in xAdmin to enable it for the server. To make changes to the Microsoft Word ribbon configuration on your server, complete the following steps: 1. Go to the xEditor folder of your xPressionHome directory and locate the appropriate configuration file. 2. Copy and rename the file. 3. Locate the item to be enabled or suppressed and set the enabled property as appropriate. For example: 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. 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 the Word 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 your xPressionHome directory. Select the file your customized and click OK. 11. Click Save. 212 Preface Language Specific Configuration Files You can create language specific configuration files for non-English implementations if you are using Microsoft Word 2007 or 2010. Language specific configuration files are not supported for Microsoft Word 2003. 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 for a specific toolbar. In addition to its properties, the HideControls and DisableControls elements reside 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 not need to specify individual controls to be disabled. • HideControls Located between the opening and closing Toolbar tag, controls identified with this tag are hidden on 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 disabled on the toolbar identified in the Toolbar 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 control to be hidden or disabled. ShortCuts disables any keyboard shortcuts associated with the control. This is necessary if you want to eliminate the function entirely since the shortcut will still work even if the control has been hidden or disabled. You must identify each shortcut combination, separating keys with commas and different shortcut combinations with the pipe symbol as in this example. • Menus Contains all of the Menu elements, which establish the configuration for each individual menu. This element has no properties. 213 Preface • Menu Located between the opening and closing Menus tags, this tag establishes the configuration for a specific menu. In addition to its properties, the HideControls and DisableControls elements reside between 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 not need to specify individual controls to be disabled. • HideControls Located between the opening and closing Menu tag, controls identified with this tag are hidden on 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 disabled on 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 control to be hidden or disabled. ShortCuts disables any keyboard shortcuts associated with the control. This is necessary if you want to eliminate the function entirely since the shortcut will still work even if the control has been hidden or disabled. You must identify each shortcut combination, separating keys with commas and different shortcut combinations with the pipe symbol as in this example. Excluded, Repurposed, and Unsupported Commands The following Word functions are either not available with xEditor, or the stock functionality is modified by xEditor. It may be possible to enable toolbar buttons or menu item for those that are not supported, 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 is deleted and a message is displayed. xEditor does not support modifying styles. Users should not modify styles because satisfactory results cannot be guaranteed. • New Window Word does not allow this option while running with xEditor because an XML expansion pack is attached. This limitation is imposed by Word. 214 Preface 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 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, depending on whether the document includes optional content or not. If the document does not include any optional content, then the entire RU is selected. If the document includes 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. See Protection. • Drag and Drop Drag and drop is not allowed if the current selection includes a variable or a DCPI field. xEditor will 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 custom ribbon 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–2003 Document, PDF or XPS, and Other Formats • 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 215 Preface 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 From Developer tab: • XML group • Structure • Schema • Transformation • Expansion Packs • Templates group • Document • Document Panel 216 Preface 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 original function 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 • Compare Two Versions • Accept Change • Reject Change 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 enable features disabled by xEditor. 217 Preface Opening a Work Item in xEditor The specific method for opening a document in xEditor for an xPression DevKit application depends on the host application. Some factors in the process should be considered. Table and Paragraph Merge Paragraph and table merges across Revision Units are ignored when assembling for the editor, but not when assembling for xPublish. If possible it is recommended that paragraphs and tables for merge occupy the same RU to avoid confusion when working in the editor. Content Separators Although a work item may look like a single, continuous document when you’re previewing or editing it, what you’re actually working with is a series of concatenated content items separated by a series of HTML tags. These protected content separators mark the “boundaries” of each content item. Every content separator consists of the content item information sandwiched between two continuous page breaks. xPression doesn’t insert a separator before the first content item in a work item. Why? Because it’s the first content item in a document that decides the initial page layout. For example, if you start with text 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 xPression that a series of paragraphs, possibly from separate content items, should be merged into a single paragraph at the time of assembly. xEditor treats merged content items as one object. Only the first of a set of merged content items will have a separation marker. If you make a change anywhere in the merged text, xEditor replaces the first content item, and marks all subsequent merged content items as deleted in the table of contents. Variables The document designer can use variables to customize the document with customer information. When you create a new work item, xEditor retrieves values for the variables in the document. The document designer can insert variables with the Insert Variable tool in xDesign, or by using a variable rule. When working with the document, the values are displayed and the variables are retained until deleted. Instances of the same variable with different values in a given RU are converted to plain text when the document is assembled for xEditor. Variables are usually displayed in red to distinguish them from ordinary text, but appear as static text in form fields. The color used to indicate variables can be changed by the xPression administrator. 218 Preface The Variable Navigation buttons on the xEditor Task Pane toolbar enable you to move through all variables in the document sequentially, either forward (top to bottom) or backward (bottom to top). The xPression administrator can configure xEditor so that the TOC is disabled. The TOC must be enabled to work with variables in xEditor. 219 Preface Variable Scope Variables can be either global or local. Global variables are drawn from the primary table of the primary data source and local variables are either from secondary tables or variable rules. When the value of a global variable is changed in xEditor all instances of the variable throughout the document are updated to reflect the change. When the value of a local variable is changed all instances of the variable in the selected RU are updated to reflect the change. So, for example, the same local variable may appear in any number of RUs, and may initially have the same value in each, but the value can be changed in xEditor so that the value differs from one RU to another, but a global variable will always 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 from variable 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 relevant variables are shown in the Task Pane, so when the document node is selected in the TOC, only global variables are shown. Only variables that are actually used in the document or selected RU are displayed; 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 of individual instances of local variables. See Variable Navigator for more details. Selecting Variables To maintain variable integrity it is necessary to modify Microsoft Word’s standard behavior when making selections. This impact is most apparent in certain navigation keys and key combinations and 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 variable only. Triple-click in a paragraph that contains a variable will select the entire paragraph, including the variable. Some keys and key combinations behave somewhat differently in xEditor when a variable is involved. Microsoft Word provides the ability to map key combinations to other actions. Mapping key combinations to specific actions overrides the effects noted here. Some keys and combinations have slightly different effects when a range is selected than when only the insertion point cursor is in use. 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 other action. • SHIFT+SEMICOLON Shifts focus from the edit window to the Variables grid entry for the selected variable. This key combination should not be mapped to any other action. 220 Preface The following keys and key combinations have the effect indicated with the cursor insertion point only. That is, no range of text is selected. • Left Arrow SHIFT+Left Arrow CTRL+Left Arrow When a user enters a variable from the right by using the Left Arrow key, alone or in the noted combinations, the entire range of the variable will be selected. When a variable is currently selected SHIFT + Left Arrow will not deselect the variable. • Right Arrow SHIFT+Right Arrow CTRL+Right Arrow When a user enters a variable from the left by using the Right Arrow key, alone or in the noted combinations, the entire range of the variable will be selected. When a variable is currently selected SHIFT + Right Arrow will not deselect the variable. • Down Arrow CTRL+Down Arrow When a user enters a variable from the top by using the Down Arrow key or CTRL+Down Arrow the entire range of the variable will be selected. • Up Arrow CTRL+Up Arrow When a user enters a variable from the bottom by using the Up Arrow key or CTRL+Up Arrow the entire range of the variable will be selected. • SHIFT+Down Arrow When a user enters a variable from the top by using the SHIFT+Down Arrow key the entire range of 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 range of 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 the selected range will start at the original position and include the entire variable plus any content preceding 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 the selected range will start at the original position and include the entire variable plus any content following 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 the selected range will start at the original position and include the entire variable. 221 Preface • CTRL+SHIFT+Up Arrow When a user enters a variable from the bottom by using the CTRL+SHIFT+Up Arrow key the selected range will start at the original position and include the entire variable. • Page Up CTRL+Page Up When the selection insertion point lands in a variable the entire variable will be selected. • Page Down CTRL+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 in addition to other standard Word selection • SHIFT+Page Down When the selection insertion point lands in a variable the entire variable will be selected in addition to other standard Word selection • BACKSPACE The entire variable will be selected. • CTRL+BACKSPACE The entire variable will be deleted and any content preceding the variable until a space is encountered. • CTRL+SHIFT+BACKSPACE 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 Arrow CTRL+Left Arrow When a user enters a variable from the right by using the Left Arrow key, alone or in the noted combinations, the entire range of the variable will be selected. • Right Arrow CTRL+Right Arrow When a user enters a variable from the left by using the Right Arrow key, alone or in the noted combinations, the entire range of the variable will be selected. 222 Preface • Down Arrow CTRL+Down Arrow When a user enters a variable from the top by using the Down Arrow key or CTRL+Down Arrow the entire range of the variable will be selected. • Up Arrow CTRL+Up Arrow When a user enters a variable from the bottom by using the Up Arrow key or CTRL+Up Arrow the 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 range of 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 range of 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 range of 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 range of 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 the selected range will start at the original position and include the entire variable plus any content preceding 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 the selected range will start at the original position and include the entire variable plus any content following 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 the selected 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 the selected range will start at the original position and include the entire variable. • Page Up CTRL+Page Up When the Selection IP lands in a variable the entire variable will be selected and the former selection will be collapsed. 223 Preface • Page Down CTRL+Page Down When the Selection IP lands in a variable the entire variable will be selected and the former selection will be collapsed. • SHIFT+Page Up When the selection insertion point lands in a variable the entire variable will be selected in addition to other standard Word selection • SHIFT+Page Down When the selection insertion point lands in a variable the entire variable will be selected in addition to other standard Word selection • 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 any content preceding the variable until a space is encountered. • CTRL+SHIFT+BACKSPACE No effect. • DELETE The entire variable will be deleted. • CTRL+DELETE Collapses the selection range to the start and then the entire variable will be deleted • CTRL+SHIFT+DELETE No effect. Editing Variables Variable values can be changed, and variable instances can be deleted, unless the variable is protected or the primary key for the table. See Protection and Variables for more information on how protection affects editing variables. Variable instances can be deleted as any other content; select the variable instance 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 was deleted and by whom. Refer to the xRevise User Guide for details on the xRevise reporting feature. Only one variable instance can be selected at a time, and only the entire variable instance can be selected. Variable instances can be placed directly next to one another. It is possible to insert text between adjacent variables without impacting either of the variables. Note: Since selecting the entire variable is forced, selecting surrounding characters can be difficult under certain circumstances. If the variable contains a space and there is a character to the immediate 224 Preface right of the variable, and you try to select the character to the right of the variable with a mouse action moving from right to left, the variable will also be selected. It is possible to select the character by placing the cursor between the variable and the following character and using a mouse action from left to right, but this can be difficult. To select the consecutive character to the right of a variable it is recommended 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 are changed using the Date Picker. To begin editing a variable other than a date variable, double-click the variable or select the variable and press CTRL+SEMICOLON. The cursor is moved to the variable’s edit field in the Task Pane where the desired changes can be made as required. When complete, press ENTER or click anywhere in the edit window and the cursor is returned to the document. To exit the Variable grid and abandon any changes, press ESC. If a variable is selected without choosing to edit the 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, when editing in the body of a document, double-clicking in the header or footer will switch to edit the header/footer. But if a variable is selected while editing the body of the document, double-clicking in the 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. But if a variable is selected while editing in the header or footer, double-clicking outside the header or footer will activate variable editing in the grid. Most variables are changed by typing in the edit field of the Variables Grid, but date variables provide a date picker. Date variables cannot be edited directly; the only way to edit a date variable is with the 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 more information on how xEditor handles variable formats. The Toggle Variable Editing button toggles Edit mode off and on in the Variables grid. When in Variable Edit mode the edit fields for the variables in the Task Pane are clear and the variable type icons are bold, when not in edit mode the edit fields are shaded and the variable type icons are dimmed. Some variables, such as primary key variables for the table, cannot be edited at all and are indicated with a lock icon. The xPression administrator can configure xEditor so that variables can never be edited, always be edited, or to honor the protection status established by the document designer. Note: To apply changes to a variable value press the ENTER key. Navigating away from the variable’s edit field with a mouse action will discard any changes to the variable. When navigating away from a variable with a mouse action the value indicated in the variable’s edit field will return to the original value 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 the Task 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 if the variable change is local to an RU. The current value applied to the variable is displayed, even if not 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. Variables in form fields behave more like static text in xEditor. Variable values that were used to populate form fields are edited directly in the form field rather than the variable grid. Changing these instances does not change the value in the grid or in any other instances of the variable. Likewise, changes to the value of a variable used to populate form fields made in the grid do not change the value in the form fields. So, if a variable is used to populate both a form field and an instance outside of the form field, these 225 Preface values can initially be the same but changed independently of one another. Note that variables in form fields are not displayed in red as is the case with variables outside of form fields, and the fact that the same variable was used both inside and outside of a form field is not necessarily obvious in xEditor. Date variables (See Variable Formats, page 226 for details on variable formats) can be modified either directly or with the Date Picker. Click the Date icon to open the Date Picker and select the desired date from the calendar-formatted Date Picker. The Date Picker is a standard Microsoft user interface device; simply select the desired date and it is applied to the selected variable. Direct changes to the date 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, from the Day element to the Month element rather than the end of the day element to the middle as may be expected. • Pressing ENTER or ESC while manually editing have no effect. Click outside the grid to apply changes and remove focus from the Variable grid. Copy and Paste Variables can be copied and pasted, either alone or along with surrounding text. However, when pasted the variable is converted to static text and will not be updated if the variable value is subsequently changed. Drag and Drop Drag and drop cannot be used with variables or DCPI fields, such as subtotals or indexes. Drag and drop is not allowed when the current selection contains a variable or DCPI field. Dropping data into a variable 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 format in that it can contain virtually any character. By contrast, date variables can contain only dates and numeric variable types can contain only numeric values. xEditor strictly enforces variable formats, so it will not allow a variable to be changed in a manner not supported by the variable’s format. For example, placing letters of the alphabet into a numeric variable is not allowed. Some variable types have 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 date variable. The document designer can use the same date variable throughout the document, but apply different date formats in different places. xEditor will honor the variety of formats and display the date in the specified format for each instance. The document designer can also specify the number of 226 Preface decimal places for numeric variables, and this is honored as well. So if the xEditor changes a numeric value 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 value that is not supported by the variable, the xEditor user has no choice but to delete the variable and replace it with static text. Note: xEditor generally imposes no restrictions on variable types and honors restrictions imposed by 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. The following 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 most cases where document protection is to be used. When this setting is selected and the document contains a variable with instances in both protected and unprotected regions, the variable is considered 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 is configured for xRevise to allow all variables to be edited, then all variables in all xRevise documents in that xPression environment can be edited by any xEditor user, except primary key variables that can never be edited. However, in that same xPression environment, there can be a custom application created in the xPression DevKit 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 variable is used in the work item (global variables) or revision unit (local variables). Saved changes to variable revisions are recorded in the revision history. Each change is assigned a version number, which is incremented with each saved change. The value used in a previous version can be restored from the Variable Navigator by selecting the desired value and clicking Set. This does not revert to the selected version. Rather, it creates a new version with a new version number that is a copy of the selected version. In no case does the actual value in the data source change. You can also apply changes to the selected variable, subject to the same limitations as apply to making changes in the Variables grid. Variable scope is clearly indicated in the Variable Navigator. If the variable is global, then any changes made are applied to all instances of the variable. If the variable is local then instances of 227 Preface the 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 Cancel discards any changes and closes the Variable Navigator, and Reset discards changes without closing the Variable Navigator. Subtotals, Index Headings, and Table Headings and Footers The document designer can use xPublish commands to create table headings and footers and index headings. These elements are not automatically protected in xEditor, but can be protected using supported Word protection features. Note that Filling In Forms protection is required if the document includes 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 value of these functions is resolved when the document is published. Therefore they are shown as placeholders in xEditor. They cannot be modified in xEditor, but can be deleted. Variables in Optional Content If an optional content is selected that includes any variables, and the variables exist elsewhere in the RU, the variable instances will remain editable variables as long as all instances of the variable have the same value throughout the RU. If the variable has different values within the RU, all instances will be converted to static text. In this case the static text will be editable, but will no longer be treated as a variable. See Optional Content, page 200 for more information on working with optional content. Note: Variables in work items that were created in earlier version of xPression and upgraded to xPresson 4.0 will be converted to static text in most cases, regardless of value. Purging WIP Work Items The xPression administrator can purge work items from the xPression database. Refer to the xAdmin User Guide for details on using the Workitem Utilities. Carry Forward The xEditor Carry Forward utility enables you to compare your current table of contents to any other version (earlier or later) of the same customer’s document stored in the Completed Work queue, or other documents of the same type. You can copy items or sections from archived versions to the current table of contents. The Carry Forward Utility is part of xEditor. You can open the Carry Forward utility from the Work in Progress page or from an open work item. Regardless of how Carry Forward is opened, the options are the same. 228 Preface Three documents are involved in any Carry Forward action; Baseline, Compare, and an Active document. When a document is opened in Carry Forward the Baseline document is compared to the Compare document. As many conflicts as possible are resolved automatically. In most cases all conflicts are resolved automatically, and any resolutions can be changed if necessary. If Carry Forward encounters a revision unit with a name that conflicts with another revision unit, it is handled as a new RU. Note: Automatic resolution has limitations. If revision units have been moved, for example, it is possible that Carry Forward will not be able to correctly identify which revision units in the baseline document correspond to which revision units in the compare document. When working in Carry Forward the only document subject to change is the active document. The compare and baseline documents can be displayed for reference, but cannot be modified. Opening Carry Forward Access the Carry Forward utility from an open work item in xEditor by right-clicking the document (top-level) node in the Document Actions pane and selecting either Compare to file or Compare to Work Item. The Compare to File option opens a dialog box where the desired file can be selected. The Compare to Work Item opens the Compare pane where the desired work item can be selected. Review Helper Regardless of which method to start the carry forward operation is used, when the baseline and compare documents have been assessed the Review Helper dialog box opens. This dialog box enables the user to scroll through all instances where a change was identified. The user can choose to accept the automatic resolution or switch to the other option. The name of the RU, the Current State of the RU and the state indicator icon (see The Document Structure Tree for a description of the icons), and the reason for the automatic selection. If the user has chosen to override the automatic selection, this is indicated in the Current State field. The Show Carry Forward details button toggles displaying the Carry Forward Data and Content Compatibility sections. 229 Preface The following options are available on the Review Helper dialog box. • Show/hide side-by-side compare documents — Toggles the side-by-side compare view. In this view all three documents involved in the carry forward operation are displayed: Active, Baseline, and Compare. The Review Helper dialog box remains open. This view can also be opened from the Carry Forward Review Toolbar. • Show Carry Forward details — Toggles the expanded Review Helper dialog box. When expanded the dialog box shows Carry Forward Data and Content Compatibility. • Navigation Buttons — Use the navigation buttons to scroll through the identified changes in the document. • Confirm — Confirms the current selection. When a decision is confirmed the only option available for the RU is to undo the confirmation. Options can also be confirmed from the right-click menu for each RU. • Use Compare — This option is available if Use Baseline is the current state, or the RU has been removed. Click this button to use the RU from the Compare document. • Use Baseline — This option is available if Use Compare is the current state, or the RU has been removed. Click this button to use the RU from the Baseline document. • Remove — This option is available unless the RU has been removed. Click this button to remove the RU. The Review Helper closes when the Close button in the upper-right corner of the dialog box is clicked. It can be reopened by clicking the Review Helper button in the Carry Forward Review toolbar. The Carry Forward Review Pane The Carry Forward Review Pane is the main interface for working with documents in Carry Forward. It consists of a toolbar, a document tree for the working document, a Properties section, and information sections for the Baseline and Compare documents. The Carry Forward Review Toolbar The Carry Forward Review toolbar is located at the top of the pane. Use these buttons to perform actions in the Carry Forward Review pane. • Logs — Opens a menu from which the Editor log or the Auto Carry Forward log can be opened. • Show Variable Values or Variable Names — Toggles the working document to display either variable names or values. Baseline and Compare documents always show the variable values. • Show/Hide Compare and Baseline Side-by-side — Carry Forward can display Baseline and Compare documents in frames below the working document. Click this button to toggle displaying the other documents. They are for reference only; they cannot be edited in Carry Forward. Always use this button to close the comparison documents; do not close the extra windows using the window’s Close button. The comparison windows may adversely affect overall performance when open. 230 Preface • View Filter — Determines what is displayed in the working document and the document tree. Click the down arrow, to the right of the funnel icon, to display a list of the available options: — Show Conflict Only — Show Auto-Resolved Only — Show All Differences — Show All • Finish — Saves changes and finishes the comparison. This action is not available if the work item contains a conflict. • Cancel — Discards all changes and closes the comparison. The Document Structure Tree The Document Structure Tree displays the document structure and enables a variety of actions. The highest-level node in the tree represents the document. Under the document node are any RUs that should be displayed based on the selection made with the View Filter on the toolbar. By default only RUs with differences between baseline and compare documents are displayed. The following icons may appear in the Document Structure Tree. • Document Node — The highest level node in the tree; represents the entire active work item. • RU Using Baseline — The Revision Unit differed in the baseline and compare documents. Revisions in the baseline version is being used. The green arrow in the icon points to the left, indicating that baseline is used. • RU Using Compare — The Revision Unit differed in the baseline and compare documents. Revisions in the compare version is being used. The green arrow in the icon points to the right, indicating that compare is used. • RU Identical — The Revision Unit was identical in both baseline and compare documents. • Change from Baseline — There is a tracked change and the baseline version is being used. • Change from Compare — There is a tracked change and the compare version is being used. • Inserted — The Inserted icon indicates that the item exists in a completed work item, but not the active work item, or exists in the active work item but not a completed work item. • Conflict — There is a conflict that cannot be resolved automatically, so it must be resolved manually. The document cannot be finished until the conflict is resolved. The specific conflict will be indicated in the tree as tracked changes. Whenever any node is selected in the tree the corresponding content is highlighted in the working document and appropriate information is displayed in the Information section near the bottom of the pane. Each node except the document node provides a context, or “right-click”, menu for working with the corresponding content. The options depend on the selected node and its current status. 231 Preface The following options are available on Revision Unit nodes. • Confirm — Confirms changes to the revision unit. When confirmed all other options become unavailable except Undo Confirm, which reverses the confirmation. • Remove — Removes the revision unit. This action can be reversed by Revert. • Use Baseline — This action is available if the Compare version is currently being used. It changes the revision unit to the Baseline version. • Use Compare — This action is available if the Baseline version is currently being used. It changes the revision unit to the Compare version. • Use Both — This action is available when revisions exist in both baseline and compare work items that do not overlap or result in a conflict. When selected both revisions are used. • Edit — Allows editing in the active document. Only unprotected text can be edited. Variables cannot be edited, either in Name or Value display mode. When selected the Carry Forward toolbar is replaced with the Finish Edit button. Click Finish Edit to restore the toolbar. See Editing Content in Carry Forward. • Revert — Discards all changes, restoring the document to its starting condition. • Choose Variables — Replaces the Carry Forward Review pane with the Variables pane and the Carry Forward Review toolbar with the Choose Command Bar. See Working with Variables in Carry Forward. • Undo Confirm — This action is available if the Confirm action has been applied. It reverses the Confirm action and restores the remaining options when opening the context menu. The context menu for tracked changes in the tree provides a single option that enables removing changes or restoring changes that have been removed; the menu toggles between the two actions. When removing a change a Comment dialog box opens that enables adding a comment for the removal. To create a comment for the removal, type the text of the comment in the text field and then click Add Comment. To proceed with the removal without adding a comment, click Dismiss. The comment appears in a comment balloon in the active document. The comment balloon is discarded when the change is re-inserted and cannot be recovered. The Information Panel The Information panel, located below the Document Structure pane, displays information relevant to the selected element. Information in this panel is read-only. The following information is available in the upper section of the information panel when the document node is selected. • Properties — The upper section contains information about the document. • Category Name — The name of the category that contains the document. The following information is available in the Baseline section of the information panel when the document node is selected. • Baseline — This section contains information about the Baseline document. • Name — The name of the baseline document. • Customer Key — The customer key used to produce the document. 232 Preface • Publisher Type — The publisher, either xPublish or CompuSet. • Last Saved Time — The last time the baseline document was saved. • Annotations — Any annotations attached to the baseline document 233 Preface The following information is available in the Compare section of the information panel when the document node is selected. • Compare — This section contains information about the Compare document. • Name — The name of the compare document. • Customer Key — The customer key used to produce the document. • Publisher Type — The publisher, either xPublish or CompuSet. • Last Saved Time — The last time the compare document was saved. • Annotations — Any annotations attached to the compare document The following information is displayed in the upper section of the Information panel when a revision unit is selected. • Properties — The upper section contains information about the revision unit in the active document. • Name — The name of the revision unit. • Current State — The current state of the revision unit. The revision unit can be Using Baseline, Using Compare, Using Both, or Not Used. The following information is displayed in the Baseline section of the Information panel when a revision unit is selected. • Baseline — This section contains information about the revision unit in the Baseline document. • Revision — The revision level of the revision unit. • Create Date — The date the revision unit was created in the baseline document. • Annotations — Any annotations associated with the revision unit in the baseline document. • Deleted — Indicates whether the revision unit has been deleted in the compare document. Can be True or False. The following information is displayed in the Compare section of the Information panel when a revision unit is selected. • Baseline — This section contains information about the revision unit in the Baseline document. • Revision — The revision level of the revision unit. • Create Date — The date the revision unit was created in the baseline document. • Annotations — Any annotations associated with the revision unit in the baseline document. • Deleted — Indicates whether the revision unit has been deleted in the compare document. Can be True or False. Editing Content in Carry Forward The Carry Forward feature is intended as a means of efficiently combining content in different versions of a document, but it does provide the ability to edit content. Editing is performed on a single revision unit at a time. When editing a revision unit no other Carry Forward action can be performed. To edit a revision unit, right-click the revision unit in the tree and then click Edit. The Carry Forward Review toolbar is replaced with a single button, Finish Edit, and all context menu items are disabled. 234 Preface If the document contains form fields then Filling In Forms protection is mandatory for any section that contains a form field. In this case the text can be edited, but variables and form fields are protected from editing. If the document does not contain form fields then the document may have been protected with Read Only protection, in which case only designated text can be edited. Text that can be edited is surrounded with brackets and subtly highlighted. When finished editing, click Finish Edit. The Carry Forward utility may not display expected changes to headers and footers under certain circumstances when removing a section with a header or footer and then replacing the removed section. The expected change may not be displayed in the Carry Forward view when the header or footer uses the Link to Previous property. Inserted data in the header or footer will always be correct in the Carry Forward view. This issue affects sections after inserted data if the section is set to Link to Previous. Since the affected sections may not be visible, and the change may be subtle, this behavior may not be easily apparent. The header or footer will be updated when the user completes the carry forward operation and returns to the normal xEditor view. This behavior is specific to the xEditor-based Carry Forward Utility. It does not occur when publishing or when previewing documents outside of Carry Forward. This behavior also occurs when using Revert. Working with Variables in Carry Forward The Carry Forward Review toolbar enables the option of showing either variable names or variable values. In addition to this there is an option to directly interact with variables in Carry Forward. To work with variables, right-click a revision unit that contains variables and then click Choose Variables. This replaces the Carry Forward Review Toolbar with the Choose Command Bar. The toolbar contains the following options: • Source — Opens a drop-down list where the source of the variable values can be selected. Variables can be sourced from either the Baseline Values or Compare Values. • Reset to the entry variable values — Restores the values of the variables to the values at the beginning of the current action. Values cannot be reset after they have been applied. • Apply the variable values to the Revision Unit and resume Review — Applies any changes to variables, closes the Choose Variables session, and returns to the Carry Forward Review. Once applied variable values cannot be restored automatically, but they can be changed manually in a subsequent Choose Variables session. • Cancel — Discards all changes and returns to the Carry Forward Review. In addition to offering a choice between Baseline and Compare documents for variable values, Carry Forward also allows manual changes to individual values. All variables and their current values are displayed beneath the Choose Command Bar. To manually change a variable value, type the desired value in the value cell for the variable. The variable name cannot be changed. 235 Preface Headers and Footers in Carry Forward The xEditor-based Carry Forward utility may not display expected changes to headers and footers under certain circumstances when removing a section with a header or footer and then replacing the removed section. The expected change may not be displayed in the Carry Forward view when the header or footer uses the Link to Previous property. Inserted data in the header or footer will always be correct in the Carry Forward view. This issue affects sections after inserted data if the section is set to Link to Previous. Since the affected sections may not be visible, and the change may be subtle, this behavior may not be easily apparent. The header or footer will be updated when the user completes the carry forward operation and returns to the normal xEditor view. This behavior is specific to the xEditor-based Carry Forward Utility. It does not occur when publishing or when previewing documents outside of Carry Forward. This behavior also occurs when using Revert. Revision Numbers This section applies to Revision Unit numbering in Carry Forward and elsewhere as indicated. Revision Numbering Outside Carry Forward The revision number for a Revision Unit is applied when a new Revision Unit is created or an existing Revision Unit changes following these rules. • Insert Revision Unit from Search. A Revision Unit that is inserted from a Search is assigned the revision number of the searched Revision Unit. This remains the same after saving if there are no changes to the inserted Revision Unit, but is the searched Revision Unit’s revision number plus 1 if any changes are made to the inserted Revision Unit. • Insert Content from Search. When an xDesign content item is added from a Search it is considered a new RU with a revision number of 0, and it remains 0 after saving even if edited before the save. • Edit Existing Revision Unit. An Existing Revision Unit is one that was created when the work item was created or one that was inserted and previously saved. After saving any changes the revision number is the current revision number plus 1. 236 Preface Revision Numbering in Carry Forward Revision numbering is applied when performing a carry forward operation according to the following logic. • Use Baseline. The baseline number is applied before saving and is retained after saving, unless edited. If the RU was edited then 1 is added to the revision number. • Use Compare. The compare revision number is applied before saving and is retained after saving, unless edited. If the RU was edited then 1 is added to the revision number. • Edit any result Revision Unit. The current revision number is applied before saving the change, the revision number is increased by 1 after saving the change. The Editor Log xEditor creates a log file that records the configuration setting used to start xEditor, the elapsed time for all web service calls, and errors with stack traces. When a failure occurs, a message opens with a link that opens the file in a text editor. The Editor log can be accessed from the Logs menu on The Carry Forward Review Toolbar, from the xEditor menu if Carry Forward is not open, or by opening the file in a text editor. The log file is located in C:\Documents and Settings\[USER]\Application Data\EMC Document Sciences\[xEditor]\[server]\xEditor.log. The Auto Carry Forward Log An Auto Carry Forward log is generated during the compare process detailing the decisions made by the carry forward engine. The Carry Forward log can be deleted at any time and a new one will be created if necessary. New actions are appended to the existing log if one is available. The Carry Forward log can be accessed from the Logs menu on The Carry Forward Review Toolbar or by opening the file in a text editor. The log file is located in C:\Documents and Settings\[USER]\Application Data\EMC Document Sciences\[xEditor]\[server]\CF.log. The Carry Forward log provides the following for each revision unit: • Revision unit Name • Which revision unit was selected (baseline/compare) • Reason the revision unit was selected • If the revision unit preceding and/or following the revision unit are not the same in the compare and baseline work item, the names of the adjacent revision units are detailed (this can happen in the case of a move or an inserted revision unit). For example: Revision Unit Name: xPub2 Baseline was auto selected because: 237 Preface The Baseline revision unit is the default when both the Compare and the Baseline revision units are identical ** Reference siblings have changed ** Baseline previous revision unit: xPub1 Baseline next revision unit: RU4 Compare previous revision unit: xPub1 Compare next revision unit: xPub3 238 Chapter 12 The xCatalog Component xCatalog is a Web-based administration interface used for the management of templates, forms, and documents. xCatalog enables you to apply any type of metadata to documents in the form of tags. The tags are then used to enable search functionality so that documents can be located more easily. Documents imported into xCatalog are automatically added to the xPression database. You can also import documents into xCatalog from the xPression database. Forms contained in the xPressForms systems are also available in the xCatalog interface. xCatalog comes with a complete set of APIs to create interfaces that enable an end-user to browse xCatalog and locate documents. Currently, there is no end-user interface for that purpose provided with xCatalog. Access Rights The ability to perform actions in xCatalog is determined by the user access rights setting in xAdmin for your client application (xDesign or an xPresso client). For xDesign users, both Read and Write (Content and Rule) access will allow you to Login and Browse for documents. You need both Write:Content and Write:Rule access to perform the following tasks (you can also use the SharedAdmin or Approve access rights which include both Write:Content and Write:Rule): • Import documents • Import documents to new category • Import documents from the xPression Repository • Add or Copy tags from the Tag tree • Update Name in the Information tab • Update Word template in the Properties tab • Update the description in the Information tab • Delete documents or packages in xCatalog • Add/Remove tags from Custom Fields 239 The xCatalog Component For xPresso client users, both Read and Write access will allow you to Login and Browse for documents. You need Write access to perform the following tasks: • Import documents • Import documents to new category • Import documents from the xPression Repository • Add or Copy tags from the Tag tree • Update the description in the Information tab • Delete documents or packages in xCatalog • Add/Remove tags from Custom Fields The xCatalog Interface Once you log on to xCatalog you will see the main screen. From the main screen you can accomplish all xCatalog tasks. The xCatalog main interface contains the following areas: • Menu Bar, page 240 • Browse and Search Pane, page 242 • Document List, page 248 • Document Detail Area, page 248 Menu Bar The xCatalog menus contain commands for commonly used functions: • The File Menu, page 240 • The Edit Menu, page 241 • The Help Menu, page 241 The File Menu The File menu provides access to several general document functions. You can view the menu options by clicking the menu. The File menu contains the following options. Select this option To Delete Delete the selected documents. For more information, see Deleting Documents, page 254. 240 The xCatalog Component Select this option To Import Import existing documents that were exported from another xCatalog system. For more information, see Importing Documents, page 252. Export Export the selected documents and all of the applied metadata so they can be used on another xPression Server running xCatalog. For more information, see Exporting Documents, page 253. Report Generate a report for selected documents that contains information about each document. For more information, see Creating Document Reports, page 257. Logout Log out of the xCatalog application. For more information, see Logging Out, page 258. The Edit Menu The Edit menu provides access to functions that enable you to work with the documents in the system. You can view the menu options by clicking the menu. The Edit menu contains the following options. Select this option To Add Tag Add a tag to a document. For more information, see Adding Tags to Documents, page 253. Manage Custom Fields Open the Custom Fields window where you can see all the existing custom fields, create new fields, delete fields, rename fields, and define default values for fields. For more information, see Managing Custom Fields, page 255. Change Status Change the status of the selected documents. Available default options are: Staging, Development, QA, Production, and Withdrawn. For more information, see Changing Document Status, page 254. The Help Menu The Help menu provides access to the online Help file for xCatalog, as well as the About dialog box. The Help menu contains the following options. Select this option To Contents Opens the xCatalog online Help file where you can find information about using xCatalog. About Opens the About dialog box where you can find information about the specific version of xCatalog currently installed. 241 The xCatalog Component Browse and Search Pane The pane that appears on the left side of the xCatalog interface contains three different sections that enable you to work with the documents in the system. Each section has a specific purpose: • Browse Pane, page 242 • Search Pane, page 244 • Staging Area Pane, page 247 Browse Pane The Browse area of the pane enables you to view a list of the documents based on the tags (metadata) associated with them. A document can be associated with multiple tags in the Browse list, and can be added or removed from the list. The tag group name appears at the folder level of the list. Clicking a folder displays or hides the tag entries under the group. If you also have a license for the xPressForms application, you will see the default tag groups of Line of Business, Jurisdiction, and Bureau in the Browse area. Along with those groups, there is also the All group. If you don’t have xPressForms, you will only see the All group. The All group is a special folder that contains all the documents in the system, regardless of tags that maybe associated with them. This includes any documents with no tags, and any documents associated with custom tags created by other users. You can add folders (groups) to the Browse pane. For more information, see Adding a Tag or Folder, page 242. You can also expand all the folders in the Browse pane by clicking the Expand All button at the top of the pane; or collapse all the folders by clicking Collapse All. When you click on a tag in the Browse pane, the documents associated with the tag are listed in the Document list. You can select multiple tags in the pane; however, which documents are displayed in the list depends on where the tags are located. If you select tags that reside in the same top-level folder, then the documents displayed will have an “OR” relationship. If you select tags that reside in different top level folders, the documents will have an “AND” relationship. For example, if you select Commercial Umbrella and Workers Compensation under the Line of Business folder, then the list displays all the documents that are associated with the Commercial Umbrella tag or the Workers Compensation tag. If you select Workers Compensation under Line of Business and the CA tag under State, then the list displays the documents associated with both the Workers Compensation tag and the CA tag. The right-click menu enables you to add, rename, delete, copy, paste, or define properties for tags and folders. See the following sections for more information. Adding a Tag or Folder To add a tag or folder to the list: 1. 242 Select the folder under which you want to add the item, right-click, and select Add. The Add a Tag window appears. The xCatalog Component 2. Type the name for the new tag or folder. 3. Select Tag to add a new tag, or select Folder to add a new folder. 4. Click Click to select Parent if you didn’t select a folder in the first step, or you selected the All folder. If you did select a folder, the name of the folder should appear next to the Create in label. If you want to change the folder where the item will reside, click the folder name. The Select Parent Folder window appears. If you don’t want to change the folder, skip to Step 6. 5. Select the folder that you want the new tag or folder to appear under and click OK. 6. Click OK on the Add a Tag window. The new tag or folder appears in the Browse list, under the folder that you selected. Note: Tags in different groups can have the same name, and will not have any relationship to each other. However, you can’t have two tags in the same group with the same name. Renaming a Tag or Folder To rename a tag or folder: 1. Right-click the item in the list and select Rename. The Rename a Tag window appears. 2. Type the new name and click OK. The item’s new name appears in the list. Note: Tags in different groups can have the same name, and will not have any relationship to each other. However, you can’t have two tags in the same group with the same name. Deleting a Tag or Folder You can delete tags or folders that appear in the Browse pane. If you delete a folder, all the tags contained in the folder will also be deleted. To delete a tag or folder: 1. Select the tag or folder in the Browse pane. 2. Right-click and select Delete. A confirmation message appears. 3. Click OK. The item is removed from the pane, and any document references to the item are also removed. If the folder contained tags, those tags and their references are also removed. Copying and Pasting a Tag or Folder You can copy and paste tags and folders in the Browse pane. When you copy a tag, any variables associated with the tag are also copied. Once copied, the new set of variables are independent of the original variable set. To copy and paste a tag or folder: 1. Select the tag or folder in the Browse pane. 2. Right-click and select Copy. 243 The xCatalog Component 3. Select the folder into which you want to paste the copied tag or folder, right-click, and select Paste. Note: Tags in different groups can have the same name, and will not have any relationship to each other. However, you can’t have two tags in the same group with the same name. Marking a Folder as Required Folders can be specified as “required”. If a folder is required, a default tag must be identified. The All folder cannot be set as required. Required folders cannot be deleted, tags with associated documents cannot be deleted if they are in a required folder, and a tag in a required folder cannot be deleted if there are no other tags remaining in the folder. To make a folder required: 1. Select the tag or folder in the Browse pane. 2. Right-click and select Properties. The Tag Folder Properties window appears. 3. Select Tag Required. 4. Select a default tag from the drop-down list. 5. Click OK. Search Pane The Search area of the pane enables you to search the collection of documents for specific template, documents, or forms that meet your criteria. You can perform a basic search for documents based on the following: name, description, status, date, or custom fields and tags associated with the document. You can also search for a piece of content within a document. The content option works in conjunction with the other search items so you can search for a specific phrase used in a document in CA, for example. Search criteria are case insensitive. You can add multiple filter criteria to your basic search to further refine the resulting list. Multiple occurrences of the same filter type are treated with an OR condition, different filter types are treated with an AND condition. Tag top-level folders are each treated as a different filter type. Therefore, if you select two tags in the same folder, they will be treated with an OR condition; if you select two tags in different folders, they will be treated with an AND condition. For example, if you select Commercial Umbrella and Workers Compensation under the Line of Business folder, the search will display all the documents that are associated with the Commercial Umbrella tag or the Workers Compensation tag. If you select Workers Compensation under Line of Business and the CA tag under State, then the search displays the documents associated with both the Workers Compensation tag and the CA tag. If you need to refine your search even more, xCatalog also provides the ability to perform a more advanced search using the same criteria types supported in the basic search, but with more operator options. For more information, see Advanced Search, page 246. 244 The xCatalog Component To define your basic search criteria: 1. Type the criteria in the appropriate field: Name, Description, Date, or Content. You can also select the status from the Status drop-down list. There is a date picker for the Date that facilitates setting the date. 2. Click the plus (+) sign button. The item appears in the Applied Filter Criteria list. As you add items to the criteria list, the document list updates to represent the search criteria. 245 The xCatalog Component 3. Click Custom Field Search to open the Custom Field Search dialog box, where you can select a custom field, select an operator, and define a value to search for. Click OK. You can both select a field and define a value, or you can only select a field, or only define a value. 4. Click Filter Search to select a tag to further refine your search. The Select a Tag window appears listing all the tags currently defined. Select a tag and click OK. The tag name appears in the Applied Filter Criteria list, and the document list is updated. 5. (Optional) Click the red X next to an item in the Applied Filter Criteria list to remove it from the list and from the search criteria. The document list updates when you remove criteria. Advanced Search The Search pane Advanced Search option enables you to create more specific search criteria, using the same categories as the basic search. You can search with AND or OR logic within each category, and different categories are separated by AND logic. Searches within a category can be broken down by using brackets. This enables you to be more specific in your criteria, to refine your search down even more. To define advanced search options: 1. Click Advanced Search at the top of the Search pane. The Advanced Search window appears. 2. Build your search criteria by doing the following: • Type a search word or phrase in the appropriate field, click Choose a value to select a tag, or select a custom field from the drop-down list. • Select an operator, bracket, or operator and bracket combination from the drop down list. • Type another search word or phrase in the corresponding field, click Choose a value to select a tag, or select a custom field from the drop-down list. • Select an operator, bracket, or operator and bracket combination from the drop-down list. If you choose an operator, a new line appears, where you can continue your criteria expression using the previous steps. 3. Define a date range by clicking the calender button and selecting the first date in the From field (the effective date), and then selecting the second date in the To field (the withdraw date). The document does not have to be effective for the entire search period to be selected. If a document is effective any time during the date range, it will appear in the results. 4. Click Search when you are done building your criteria expression. 246 The xCatalog Component Example For an example of the Advanced Search option, take the following criteria: Description [Homeowner OR Business AND Landlord] Date Range FROM 05/31/2009 TO 7/31/2009 Documents that have the word “Landlord”, and “Homeowner” or “Business” in the description, and are effective any time between 05/31/2009 and 07/31/2009, are returned by this search. The document does not have to be effective for the entire search period to be selected. If a document is effective any time during the date range, it will appear in the results. The following document are returned as the result of this search: • BO 01 02 06 09 Landlord Business Form Effective: 06/01/2009 Withdrawn: 09/01/2009 This document was returned because it contains “Landlord” and “Business” in the description and the effective date is within the date range. • HO 02 03 07 09 Homeowner Form for Landlords Effective: 07/01/2009 Withdrawn: 08/01/2009 This document was returned because it contains “Homeowner” and Landlord” in the description, and the effective date is within the date range. The following documents are NOT returned as the result of this search: • BO 01 02 08 09 Landlord Business Form 2 Effective: 08/01/2009 Withdrawn: 11/01/2009 This document was not returned because it was not effective during the date range. • HO 02 44 07 09 Homeowner Policy Effective: 07/01/2009 Withdrawn: 07/31/2009 This document was not returned because it does not contain the word “Landlord” in the description. • CA 05 88 09 08 Commercial Landlord Effective: 09/01/08 Withdrawn: 06/31/2009 This document was not returned because it does not contain either the word “Homeowner” or “Business” in the description. Staging Area Pane When documents are imported into xCatalog, they are automatically placed in the Staging Area. When documents are in the Staging Area, you can’t edit the document’s metadata. You can promote documents in the Staging Area to a new status. 247 The xCatalog Component You can expand all the folders in the Staging Area pane by clicking the Expand All button at the top of the pane; you can also collapse all the folders by clicking Collapse All. To change the status of a document in the Staging Area: 1. Select the tag in the panel that is associated with the document you want to change. Or select the All folder. The document list updates to show the documents for your selection. 2. Select the document, or documents in the document list. 3. From the Edit menu, select Change Status. The Change Document Status window appears. 4. Select the new status for the document: Development, QA, Production, or Withdrawn and click OK. For more information, see Changing Document Status, page 254. Document List The documents listed in the document list vary depending on your selection: • If you select a tag in the Browse pane or the Staging Area pane, the document list contains all the documents associated with the tag. For more information, see Browse Pane, page 242 or Staging Area Pane, page 247. • If you define search criteria on the Search pane, the document list contains all the documents that satisfy the criteria. For more information, see Search Pane, page 244. For each document in the list, you can view the document name, description, status within the xCatalog system, and xPression category. Select a document in the list to view more detailed information in the document details area. For more information, see Document Detail Area, page 248. Document Detail Area When you select a document in the document list, the document details appear at the bottom of the interface in the document detail tabs section. Each tab displays specific information about the selected document: • Information Tab, page 249 • Tags Tab, page 249 • Notes Tab, page 249 • Custom Fields Tab, page 250 • Properties Tab, page 250 Note: You must have Write access for your client application (xDesign or an xPresso client) in the document’s category to modify any information in the document detail tabs section. For more information, see Access Rights, page 239. 248 The xCatalog Component Information Tab The Information tab displays the name and description for the selected document. A thumbnail image of the document appears on the right side of the tab, if one if available. Only documents that have been previously published in xDesign will display a thumbnail image. You can double-click the name or the description to display an edit box where you can change the information. Tags Tab The Tags tab displays the tags associated with the document. If you have the correct Access Rights, page 239 for your client application (xDesign or an xPresso client) in the document’s category, you can modify the tags from this tab. If you do not have the correct access rights, this function will be unavailable. To modify the tags displayed on the tab, you can: • Click Add to open the Select Tags window where you can select a new tag to add to the document. Select the tag, and then click OK. • Select a tag in the list and click Delete to remove the tag from the document. • Click Collapse All to close all the folders on the tab and hide their tags, or click Expand All to open all the folders and display their tags. Note: If the Add and Delete buttons do not appear on the tab, you do not have write access for your client application (xDesign or an xPresso client) in the document’s category. Tip: To add tags to multiple documents at one time, select the documents in the document list and use the Add Tag function on the Edit menu. For more information, see Adding Tags to Documents, page 253. Notes Tab The Notes tab serves as a scratch pad area for free-form notes. You must have write access for your client application (xDesign or an xPresso client) in the document’s category to add notes. To add notes to a document, type the text in the edit box, and then click Save Notes. Notes can consist of up to 255 characters. Note: If the Save Notes button does not appear on the tab, you do not have write access for your client application (xDesign or an xPresso client) in the document’s category. 249 The xCatalog Component Custom Fields Tab The Custom Fields tab displays any custom fields that have been associated with the selected document. You can also add or remove fields from the tab. The tab displays the name, value, and last modified date and time for each field. A custom field is metadata that enables you to assign name or key and value pairs to your document. Using custom fields, you can apply any type of metadata that isn’t already available through the xCatalog interface. Custom fields are created using the Manage Custom Fields function. For more information, see Managing Custom Fields, page 255. To add custom fields: 1. Click Add. The Add Custom Fields window appears, listing all the currently defined custom fields that are not associated with the document. 2. Click in the Add? column to select or clear the check box. A green check mark in the add column means the custom field will be added to the document. No check mark means that the field will not be added. You can click Select All or Deselect All (located at the bottom of the window) to select or clear the selection of all the fields in the list. 3. Click in the Value column and type the value for the field for this document. 4. Click OK. To remove a custom field from the document, select the field on the tab and click Remove. Properties Tab The Properties tab displays information about the selected document. All the information on the tab is read-only; you can’t make any changes to it. The tab contains the following information: • Type. The type of the document. • Version. The version of the software the document was created with. • xPression Design Client. The design client the document was created for use with. • xPression Category. The xAdmin category that the document belongs to. • xPression Attribute Set. The attribute set associated with the document. • Microsoft Word Template. The Word template associated with the document. Double-click this entry to edit it. • Publisher. The xPression publishing engine the document was designed for. Currently, only xPublish is supported. • Last Modified User. The last user to modify the document. • Last Modified Time. The date and time the document was last modified. 250 The xCatalog Component Using xCatalog The Web-based application structure of xCatalog makes it an easy-to-use interface for maintaining the documents you use with your xPression environment: • Login, page 251 • Importing and Exporting Documents, page 251 • Working with Documents, page 253 • Managing Custom Fields, page 255 • Creating Document Reports, page 257 • Logging Out, page 258 Login You must log in to xCatalog to use the application. To access xCatalog: 1. Open a browser window. 2. Type the xCatalog URL. For example: http://localhost:8080/xCatalog The xCatalog Login page appears. 3. Type a user name and password and click Login. If you session expires, or “times out”, when you try to access the server (by performing any action in the xCatalog interface), the Session Expired dialog box appears. Type your password and click Log in to return to the application without any interruption. Importing and Exporting Documents The import/export function enables you to move documents from one xPression Server running xCatalog to another xPression Server also running xCatalog. xCatalog documents can be imported and exported through three methods: • Import and Export through the xCatalog application. See Importing Documents, page 252 and Exporting Documents, page 253 for more information. • Use the xAdmin Migration Utilities to import or export your xCatalog documents. xCatalog and xPressForms metadata is automatically migrated (if available) when the document is migrated. See the xAdmin User Guide for more information. • Use the xPression Server command line migration functions to import or export your xCatalog documents. xCatalog and xPressForms metadata is automatically migrated (if available) when the document is migrated. See the xAdmin Integration Guide for more information. 251 The xCatalog Component The document package includes the following: • A PDP for each document selected in the export. • All of the metadata defined in the xCatalog interface, which includes tags, data elements, descriptions, and notes. Importing Documents You can import document packages that were exported from another xPression Server running xCatalog. You can also use the xPression Content Repository option on the Import window to import documents stored in the xPression database that you have access to. If your system contains required folders, the incoming documents are checked during the import process to see if they have the required tags. If a document doesn’t have a required tag, the default tag is automatically added to the imported document. For more information, see Marking a Folder as Required, page 244. Note: When importing documents that contain metadata, xCatalog will migrate the metadata for the package, and not metadata specific to individual version. To import a document package: 1. From the File menu, select Import. The Import window appears. 2. Select the location of the file: On my machine, On the server, or xPression Content Repository. 3. Click Browse to locate and select the file on your machine, or type the path to the file on the server. 4. Click Import. If you selected On my machine, or On the server, the xCatalog package is inspected and a list of documents included in the package appears. If you selected xPression Content Repository, the Import Documents dialog box appears and displays a list of categories and documents that you have access to, but that are not currently in the xCatalog system. Select the documents you want to import, and click Add to move them into the import list. When you are finished adding documents to the import list, skip to Step 6. 5. (Machine and server imports only) Select Override Existing Documents to replace any existing documents in the xPression database that have the same name as ones being imported. The import process will abort with an error message if this option is left unchecked, and a document already exists in the xPression database. 6. Click Import to complete the import process. A message appears to tell you if your import was successful. 7. Click OK. The new documents appear in the Staging Area with a status of Staging. For information on changing the documents’ status, see Changing Document Status, page 254. Troubleshooting - Importing Large Files If you attempt to import a large file, xCatalog may generate an error. If this occurs, you can split the large file into smaller files, or you can increase the PDP file maximum size setting in the Migration.properties file located in the xPression_Home directory. Be aware that this setting can’t be larger than 2GB. 252 The xCatalog Component Exporting Documents You can export documents into a document package that can then be imported into an xCatalog application running on another xPression Server. Note: When exporting documents that contain metadata, xCatalog will migrate the metadata for the package, and not metadata specific to individual version. To export document: 1. Select the documents that you want to export. If you want to export all the document, skip to the next step. 2. From the File menu, select Export. If you selected a single document, the Current document option is selected, and the document name appears in the Document Name list. If you selected multiple documents, the Selected documents option is selected, and the documents appear in the Document Name list. To export all the documents currently in the documents list, select All documents in list. 3. Specify the server path and file name of the export file and click Export. A message appears to tell you if your export was successful. 4. Click OK. Working with Documents Once a document is in the system, there are several tasks you can perform with the documents to further enhance them: • Adding Tags to Documents, page 253 • Changing Document Status, page 254 • Deleting Documents, page 254 Adding Tags to Documents You can add tags (metadata) to a single document on the Tags tab, or you can add tags to multiple documents at one time. For more information on adding tags to a single document, see Tags Tab, page 249. Note: You must have Write access for your client application (xDesign or an xPresso client) in the document’s category to add a tag to a document. For more information, see Access Rights, page 239. To add tags to multiple documents: 1. Select the documents in the document list. 2. From the Edit menu, select Add Tag. The Add Tag windows appears. You can add tags to the selected documents, or you can select all the documents in the documents list. 253 The xCatalog Component 3. If you selected a single document, the Current document option is selected, and the document name appears in the Document Name list. If you selected multiple documents, the Selected documents option is selected, and the documents appear in the Document Name list. To add tags to all the documents currently in the documents list, select All documents in list. 4. Select the tags that you want to add to the documents in the bottom pane of the window. Multi-select tags by holding the CTRL key while clicking the tag names. You can collapse or expand the folders in the pane by using the buttons at the top of the pane. 5. Click OK. A message appears confirming that the tags were added successfully. 6. Click OK. Changing Document Status xCatalog enables you to define a status for each document. The status label is independent of any other xPression workflow setting, and is used for document maintenance. This status is a visual grouping indicator that enables you to organize documents, manage the import/staging process, and control migration processes. The status levels provided in xCatalog are Staging, Development, QA, Production, and Withdrawn. Note: You must have Write access for your client application (xDesign or an xPresso client) in the document’s category to change the status of a document. For more information, see Access Rights, page 239. To change the status: 1. Select the document or documents that you want to define the status for. If you want to apply the status change to all the documents, skip to the next step. 2. From the Edit menu, select Change Status. 3. If you selected a single document, the Current document option is selected, and the document name appears in the Document Name list. If you selected multiple documents, the Selected documents option is selected, and the documents appear in the Document Name list. To change the status on all the documents currently in the documents list, select All documents in list. 4. Select the new status you want to apply from the Status drop-down list: Staging, Development, QA, Production, or Withdrawn. 5. Click OK. The status for each of the selected documents is updated in the system and a message appears confirming that the status was updated successfully. 6. Click OK. Deleting Documents When you delete a document from the xCatalog list, xPression only removes the document from xCatalog. The document will still reside on the xPression Server and can be re-imported into xCatalog. Note: You must have Write access for your client application (xDesign or an xPresso client) in the document’s category to delete a document. For more information, see Access Rights, page 239. 254 The xCatalog Component To delete a document: 1. Select the documents that you want to delete in the document list. 2. From the File menu, select Delete. 3. If you selected a single document, the Current document option is selected, and the document name appears in the Document Name list. If you selected multiple documents, the Selected documents option is selected, and the documents appear in the Document Name list. To delete all the documents currently in the documents list, select All documents in list. 4. Click Delete. A message appears confirming that the documents were deleted successfully. 5. Click OK. Managing Custom Fields A custom field is metadata that enables you to assign name or key and value pairs to your documents. Using custom fields, you can apply any type of metadata that isn’t already available through the xCatalog interface. The Manage Custom Fields function enables you to manage all the custom fields associated with documents in your system. You can add, delete, or rename fields through the Custom Fields window. You can also define or change the default value associated with a field. Custom fields are added to documents through the Custom Fields tab in the Document Details area. For more information, see Custom Fields Tab, page 250. Adding Fields You can add custom fields to your system though the Custom Fields window. To add custom fields: 1. From the Edit menu, select Manage Custom Fields. The Custom Fields window appears. 2. Click Add. The Add New Custom Field window appears. 3. Type the name for the custom field. 4. (Optional) Type the default value for the field. 5. Click OK. The new field appears in the list in the Custom Fields window. The field will also appear on the Custom Fields tab in the Document Details area so you can add the field to a document. 255 The xCatalog Component Renaming a Field You can rename a field in two different ways. You can use the Rename button at the top of the Custom Fields window, or you can rename the field directly in the list. To rename a field using the Rename button: 1. From the Edit menu, select Manage Custom Fields. The Custom Fields window appears. 2. Select the field in the list. 3. Click Rename. The Rename Custom Field window appears. 4. Type the new name in the box. 5. Click OK. The field name changes in the list to reflect the new name. To rename a field directly in the list: 1. From the Edit menu, select Manage Custom Fields. The Custom Fields window appears. 2. Double-click the name in the list. Editable fields appear. 3. Type the new name in the editable field that appears in the Name column. 4. Click elsewhere in the list. Defining or Changing a Field’s Default Value You can define or change a fields default value directly in the list of fields on the Custom Fields window. To define or change a default value: 1. From the Edit menu, select Manage Custom Fields. The Custom Fields window appears. 2. Double-click the name of the field you want to edit in the list. Editable fields appear. 3. Type the value in the editable field that appears in the Default Value column. 4. Click elsewhere in the list. Deleting a Custom Field You can delete custom fields defined in your system through the Custom Fields window, as long as they are not currently being used by a document. If you attempt to delete a field being used by a document, xCatalog generates an error message. To delete a field: 1. From the Edit menu, select Manage Custom Fields. The Custom Fields window appears. 2. Select the field in the list. 256 The xCatalog Component 3. Click Remove. A confirmation window appears. 4. Click OK. Creating Document Reports You can create a report for selected documents that contains the detailed information about each document. When you generate a report, the file is saved in the temp directory defined in Catalog.properties, and a preview of the file is automatically opened in a new browser window. The report can be an XML file, or a comma delimited file, and can contain any combination of the following information: • Document name • Description of the document • Status of the document • Type of the document • Software version of the document • Design client used with the document • Category that contains the document • Attribute Set used with the document • Microsoft Word template used with the document • Publisher used with the document • Notes associated with the document • Tags assigned to the document (XML format reports only) • Custom fields used on the document (XML format reports only) The following is an example of an XML document report: - - WC 00 00 01 A INFORMATION PAGE Development xDesign - xPressForms 3.0 xDesign xPressForms xPressForms C:\xPressFormsTemplate\ xPressFormsWordTemplate.dot xPression Publish Ed. 5-88 - 257 The xCatalog Component - To create a document report: 1. Select the document or documents that you want to create a report on. 2. From the File menu, select Report. The Generate report window appears. 3. If you selected a single document, the Current document option is selected, and the document name appears in the Document Name list. If you selected multiple documents, the Selected documents option is selected, and the documents appear in the Document Name list. To include all the documents currently in the document list, select All documents in list. 4. Select the output format of the report: XML File or Comma Delimited File. 5. Type a name for the output file, or leave the default. When the file is generated, a random number between 1 and 1000 is appended to the end of the file name you specify here. This is to avoid multiple users from overwriting files. 6. (Optional) Click Select Fields to select the fields that you want to appear in the report. The Select Report Fields window appears. The fields listed in this window differ depending on the output format of the report. If you select Comma Delimited File, the Tags and Custom Fields fields are not listed. All the other fields are the same. To remove a field from the report, select the field line, then clear the check box in the Add Field column. To add a field, select the check box. You can also click Select All Fields to select all the fields in the list, or click Deselect All Fields to clear the selection of all the fields in the list. 7. Click Generate Report to create the file. The report is saved in the temp directory defined in the Catalog.properties file, and the report opens in a separate browser window. 8. Review the report and close the report browser. Close the Generate Report window. Logging Out Once you are done working in xCatalog, you must log out of the system. To log out, from the File menu, select Logout. You will be log out of the application and redirected to the logon page. 258 Chapter 13 System Architecture This section provides a high-level introduction of the system architecture. xFramework covers all of the information an intermediate or high-level developer will need when using the xPression Web services, the high-level xPression Java API, or the xPression EAI Adapter. xPression is a suite of applications that provide universal content processing for your enterprise. The system was designed with an open, component-based architecture based on standards like J2EE, Web Services, JMS, MS .NET, and XML. xPression integrates with enterprise information systems, data, and distribution channels. The xPRS Server utilizes industry leading J2EE application servers and the standards-based architecture they leverage. This provides for: • Extensible component based design • Worldwide compatibility with Unicode • Enterprise scalability with J2EE • Integration flexibility with databases, XML, Web Services, HTTP and APIs • Multi-channel distribution (print, web, email, archive) xFramework exposes xPRS Server capabilities to systems utilizing Java or Microsoft technologies. xPression Server Components The xPression Server is the core of the xPression suite. It consists of the components required for assembling, formatting, and distributing personalized documents. These components are written in Java and are hosted on your application server. The use of Java in both the xPression components and the application server allows xPression to deliver a multiplatform compatible application that runs on several different operating systems, including: Windows, UNIX, and Linux systems. For a full list of supported operating systems and servers, see your installation documentation. 259 System Architecture Figure 2. The following graphic shows the xPRS Server engine simplified data flow. The xPRS server engines are: • The xPression assembly engine • The xPression publishers engine • The xPression controllers • xPression Batch The xPression Assembly Engine The xPression assembly engine “assembles” a document by combining a BDT (Business Document Template), customer data, and content. The BDT is the result of the “Generate XML” function in xDesign. Output of a document assembly is a set of assembled content appropriate for your composition engine of choice. The xPression Publishers Engine The xPression publishers engine is a wrapper for the two Document Sciences Composition Engines. The publishers engine looks at the composition engine setting in the BDT/ASL and forwards the document publication request to the appropriate composition engine. The publishers engine outputs PDL (Page Description Language) documents according to your xAdmin settings. 260 System Architecture The xPublish Engine The xPublish is an easy to use composition engine that performs many of the formatting functions available from Microsoft Word. It enables you to create dynamic charts based on your customer data, and to import printer PDL files to access print device functions. xPublish also performs output processing functions such as sorting and recipient processing, and supports PCL output. Metacode output is not supported. xPublish provides almost effortless configuration. Figure 3. The following graphic shows the xPublish engine simplified data flow. Components: • Instantiater - Assembly Engine which feeds the Composer Styled Documents • Composer - Transforms Styled Documents into composed pages of content in DIF (Device Independent Format) streams • Streamer - Applies necessary output processing logic to a DIF stream and sends to Emitter • Local or Remote Emitter – The emitter generates a PDL by transforming a DIF stream to a specified PDL format and invoking the Controller to send the desired document to the distribution channel. 261 System Architecture Distribution Controller Engine The distribution controller engine processes requests from the composition engines and distributes personalized documents to print, archive, and e-mail distribution channels. Execution Architecture The distribution controller engine runs as a background thread in each xPRS Server node. It wakes up every 30 seconds (a configurable option) and looks for work to do in xPression database distribution tables. When there is work to do, it sends e-mails, archive packages, and executes print scripts according to distribution definitions configured in xAdmin. Distribution Types The distribution controller engine supports both online and offline distribution. In online distribution, the distribution controller’s background process relays published documents directly to the target distribution channel, which can be Email (through SMTP), Print (through print script), or Documentum Archive (through DFC APIs). In offline distribution, the distribution controller writes documents and indexes (information about the documents published) to the file system. Supports very high volumes and specialized archival systems: • FileNet Capture • FileNet HPII • DocFinity • IBM Content Manager OnDemand xPression Batch Engine The xPression batch engine process large volumes of personalized documents, taking advantage of all xPression output management features. The batch engine requires xPRS Server installation files and connectivity to xPRS Server EJBs. It may be invoked through a command shell batch file, Java class main method call, or the xDashboard user interface. 262 System Architecture Figure 4. The following graphic shows the batch engine execution architecture. The batch engine returns standard batch architecture error codes (zero for successful run, non-zero for warnings or failure). xPression batch jobs can be called and monitored by enterprise-class job management software. Several xBatch functions execute in parallel and can be tuned for optimal job execution. xFramework Components xFramework is the Application Programming Interface (API) for xPression. It enables you to build a custom interface to xPression assembly and distribution related services. The xFramework components are: the Web services API, the JAVA API, and the EAI Adapter. WebServices API xPression ships two Web services: a document requester and a document composer. The document requester enables you to retrieve an assembled document from the content repository, and the document composer enables you to distribute a document stored in the content repository. In order to utilize a Web Service, you must obtain a description of the Web Service interface via the WSDL. The Web services API is a platform independent API callable by Java code and .NET Visual Studio. Java API The Java API is available for Java client code only. In order to use the xPression Java API, you must precisely match the Java client program you write with the xPression Server you will connect to by copying the Java Archive (JAR) files. xPression supports near-time messaging through the JMS standard. EAI Adapter Used for enhanced integration scenarios, for example, JMS and file loading. xPression Web Services Web services enable you develop an integrated xPression solution quickly and easily. Web services are a recent technology that enable you to run programs on remote computers over the Web. However, unlike traditional distributed applications, Web services can be invoked across different 263 System Architecture hardware and software platforms. Practically speaking, this means a Web service written in Java and stored on a UNIX computer can be invoked from a Windows application written in Visual Basic, Visual C++, or C#. For more information about the xPression Web Services, see Chapter 14, Deprecated xPression Web Services. The technology that makes invoking remote components possible is called Simple Object Access Protocol (SOAP). The client application constructs a SOAP “message” in XML format that includes the name of the service, the method the client is invoking, and all required parameters. It then sends the message over the Web to the remote computer. The remote computer processes the request and sends back a SOAP “response,” indicating whether the call completed successfully and including attachments, if necessary. xPression Java API The xPression Java API chapter helps you write xPression applications using the xPression high-level Java API. The purpose of this chapter is to provide you with complete documentation for developing and implementing an xPression application solution. This chapter includes sample Java code, implementation and deployment instructions, and a complete command reference. xPression Integration Strategies Figure 5. There are three main xPression integration strategies: Real-Time (Request/Reply), Near-Time, and Batch. This diagram shows how xFramework integrates with the xPRS server. 264 System Architecture Real-Time Interaction Real-Time interaction is done with APIs and Portals. It is the least efficient method, but it is required when you want to serve immediate needs of end users waiting on documents to be published. Real-Time Interaction - APIs xFramework offers two APIs for real-time integration. All APIs are request/reply in nature. • High Level Java API - Only applicable if calling application technology is Java-based. For more information, see Chapter 15, The Deprecated xPression Java API. • Web Services API - Can be used by either Java or non-Java calling applications. Chapter 14, Deprecated xPression Web Services. Real-Time Interaction - Portals xResponse and xRevise support a “FastPath” method of integrating these products into your web-based portals. FastPath is an HTTP Post to a xResponse or xRevise JSP page. There are a variety of HTTP parameters available to customize the behavior of xResponse or xRevise. For example: • Bypass user name/password login • Customer data to compose a new document • Initial screen to display in the browser • Work In Progress document to work with For more information, see the xResponse and xRevise FastPath chapters. Near-Time Interaction Near-time interaction is accomplished through JMS. It guarantees more efficient messaging because processing concurrency can be restricted to the maximum amount the hardware can support. Messages in excess of processing concurrency are queued and processed when resources become available. The xPression EAI Adapter supports the JMS (Java Message Service) specification. Vendor products like IBM WebSphere MQ support JMS for guaranteed delivery of messages between systems. The EAI Adapter provides Message-Driven EJBs (MDBs) to process 3 types of messages: • Publish Document • Preview PDF • Post For Batch 265 System Architecture MDBs are configured to pull messages off an input queue, process messages, and put results on an output queue. Multiple MDBs can work in parallel on the same input queue if supported by the Application Server vendor. Batch Interaction Batch is the most efficient method for producing high volumes of documents. This strategy requires large batches of data to be accumulated for bulk processing before you start the interaction. The xPression EAI Adapter can watch for XML files and accumulate them for submission to a larger batch job. These XML files can be directly placed in a watched file directory or relayed via web services or JMS messages. At intervals defined by a batch job scheduler, the EAI Adapter gathers XML files for processing a particular batch job and optionally transforms them to xPression “streamlined” XML. The XML files are merged into one large XML file and submitted to xBatch for high throughput processing. xPression Integration Decision Tree The xPression decision tree helps you decide which type of integration is best for your needs. 266 Chapter 14 Deprecated xPression Web Services This section covers the deprecated Web Services model. With version 4.0, xPression introduces a new Web Service API that conforms to the WS-I Basic Profile. The old xFramework Web Service API, Java API, and xAdapter have been deprecated. Although these items will be supported for backward compatibility in the current version, EMC Document Sciences encourages you to use the new Web Service API as it offers better performance, greater flexibility, and better security. Web services are a recent technology that enable you to run programs on remote computers over the Web. However, unlike traditional distributed applications, Web services can be invoked across different hardware and software platforms. Practically speaking, this means a Web service written in Java and stored on a UNIX computer can be invoked from a Windows application written in Visual Basic, Visual C++, or C#. The technology that makes invoking remote components possible is called Simple Object Access Protocol (SOAP). The client application constructs a SOAP “message” in XML format that includes the name of the service, the method the client is invoking, and all required parameters. It then sends the message over the Web to the remote computer. The remote computer processes the request and sends back a SOAP “response,” indicating whether the call completed successfully and including attachments, if necessary. Before You Begin Before you can develop and deploy custom xPression applications, you must first configure your environment. You do this by adding your application definition to AppList.xml and configuring it using xAdmin. Additionally, you must ensure your environment is configured to work with Axis version 1.3. In this section, we’ll show you how to get everything set up. Caution: We strongly urge you not to make changes to AppList.xml on a production xPression server until you’re sure your application works as intended in a test environment. 267 Deprecated xPression Web Services Initial Questions There are several options involved in setting up applications in xPression, so you should answer the following questions while planning your application: • What type of application are you developing? Is it a design tool or a production application? • Will your application support workflow (approval)? If so, do you know what actions your application will have? • What access rights will your application require? Are they hierarchical? • Will your application have any required attributes? • Will you use your applicaton to populate the xRevise Work in Progress page with content items? If so, you must set STATUS of the content items to APPROVED. Adding Your Application Definition To add the application definition to AppList.xml: 1. Locate AppList.xml on your xPression server. You should find it in C:\xPression. 2. Open the file in a text editor. 3. Type the application element between the tags. Your application name must not contain apostrophes (’). For example: 4. If your application supports workflow, type the workflow element. For example: 5. Type the access rights your application supports, including whether or not they’re hierarchical. For example: 6. Type the required attributes, if any. For example: 268 Deprecated xPression Web Services 7. Type the closing element at the bottom of your application definition. 8. Save AppList.xml and exit your text editor. Once complete, your application definition should appear similar to the following: This sample application definition has workflow and access rights, but no required attributes. Configuring Your Application with xAdmin Now that you’ve added your application definition to AppList.xml, it’s time to configure it with xAdmin. To configure your application in xAdmin, complete the following steps: 1. Associating Attribute Sets with Your Application, page 269 2. Assigning Data Sources to Your Application, page 270 3. Setting Up Access Rights for Your Application, page 270 4. Configuring Workflow for Your Application, page 270 (optional) Associating Attribute Sets with Your Application Before you can configure categories, data sources, access rights, and workflow for your application, you must first associate one or more attribute sets with your application. 269 Deprecated xPression Web Services To associate attributes with your application: 1. Start xAdmin. 2. Click Category Management, then Attribute Sets. 3. Click an attribute set that you want to associate with your application. When you click the attribute set name, the Attribute Set page appears. Alternatively, you can also create a new attribute set. For more information about creating attribute sets, see the xAdmin User Guide. 4. Select your application from the list and click Save. 5. To assign more categories to your application, repeat steps 1 - 4. Assigning Data Sources to Your Application To assign data sources to your application: 1. Select a category you’ve already assigned to your application. 2. Click the Data Sources tab. 3. Select a data source group from the list and click Set Application. 4. Select your application from the drop-down list. 5. A page appears that enables you to associate your available data sources with your application. Select the data sources you want to assign to your application and click Add. 6. In the Default Data Source list, select a default data source for your application and click Save. 7. To assign additional data sources to your application, repeat steps 2 - 7. Setting Up Access Rights for Your Application To set up access rights for your application: 1. Click the Access Rights tab for a category you’ve assigned to your application. 2. Click view/change for your application, then click Add. 3. Select users from the list of available users and click Add. The users will appear in the Selected Users list. 4. Click Save. The selected users for the category now have access to your application. 5. When the list of users reappears, select the access levels for each user and click Save. 6. To add additional users, repeat steps 1 through 5. Configuring Workflow for Your Application If your application supports workflow, you can configure your application to assign users as submitters and approvers. Please consult the xAdmin User Guide to assist you in setting up workflow for your application. 270 Deprecated xPression Web Services Authentication and Access Control When a user invokes either the document requester or document composer Web services, xPression authenticates the user on the server and checks the user’s access to the document. Both Web services use the existing xPression security mechanism to perform authentication and access control. Let’s take a closer look at what authentication and access control mean in xPression. Authentication The network user name and password are passed to the Web service, which in turn calls the authenticate method of the DSCSecuritySL object. If the method returns a string array containing the user name and groups, the user is authenticated on the server. However, if an empty string array is returned, the user is not authorized to retrieve documents from the xPression server. Access Control After the user is authenticated on the server, xPression determines if the user has at least “READ” access to the category where the requested document resides. If the user does not have access to the document, an error is returned to the user. Logging The document requester and document composer Web services use the existing xPression logging system. All xPression activity is stored in log files on the xPression server. Licensing The xPression Web services use the existing xPression licensing system. Licensing is handled on the xPression server from which the user is requesting documents. If you’re an existing xPression customer, you’ll need a separate license to enable Web services on your server. If you’re a new xPression customer, you’ll need to explicitly request the Web service feature when purchasing your xPression software. For more information, see the xAdmin User Guide. Using WebServices with xPresso Packages The xPressionRequest web service is the only web service that supports xPresso packages. The Document Requester, Revise Request and xResponse web services cannot retrieve xPresso packages. 271 Deprecated xPression Web Services Web Services Processing Diagram To understand how xPression processes Web service requests, the following functional diagram illustrates the flow of the document requester service. Figure 6. The following image shows the document requester functional flow. 1. SOAP Request The document requester client generates a SOAP request and sends the request by means of an HTTP POST. The client request specifies the DocumentRequester service and the requestDocuments method. The request also includes parameters such as documentName. 2. Request Routed to Servlet The application server receives the incoming request and forwards it to the Apache rpcrouter servlet. 3. Servlet Looks Up DocumentRequester The rpcrouter looks up the DocumentRequester, instantiates a DocumentRequester object and invokes the requestDocuments method. 272 Deprecated xPression Web Services 4. requestDocuments Calls EJBs The requestDocuments method calls the AssemblyEngine Enterprise Java Bean (EJB) and other Java Beans to assemble the requested document and return an array of streams. 5. Rpcrouter Returns SOAP Response The rpcrouter captures the results, packages them into a SOAP response, and returns the response to the client. The Document Requester Web Service The document requester Web service enables you to retrieve an assembled xPression document in the format you specify by passing an output profile name. If successful, the xPression server passes back an array containing the document (or stream) name, the output format name, and the assembled document stored in a byte array. The format of the returned byte array depends on the output profile you provide. There are two methods you can invoke to retrieve a document using the document requester: requestDocuments and requestDocumentsWithData. The first method requires you to pass the customer key values. The second accepts an XML stream containing a customer record. We’ll discuss both methods. This web service does not support xPresso packages. The wsdl description for DocumentRequester can be viewed at following location: http://localhost:8080/xPressionWebService/services/DocumentRequester?wsdl Substitute the server name and server port number where web services is installed. The document requester contains the following methods: Requesting a Document by Customer Key, Requesting a Document by XML Customer Data, and Request Document by Output Profile. Requesting a Document by Customer Key The requestDocuments method enables you to retrieve a document from the xPression database by passing the customer data key values. Use this method only if the category your document is associated with has an RDB data source. This method returns an object that contains the stream name, format, and a byte array containing the returned document. It is up to the calling program to save the byte array as a file. Note: All input parameters are case sensitive. For example, if your output profile is “PDF to File,” but you pass “PDF to file,” the SOAP request will fail. Syntax OPStream[] = requestDocuments(documentName, customerKey, outputProfileName, userName, passWord[], appName) 273 Deprecated xPression Web Services Parameters documentName : String Specifies the name of the document you’re retrieving from the content repository. customerKey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: 1 -or 1 English outputProfileName : String Specifies the name of the output profile you’re using to retrieve a document. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. passWord[] : Byte An encrypted byte array specifying the password for the user who has been granted access rights to the category and application in xAdmin. Use the webtool.jar utility to convert a text password to an encrypted byte array. appName : String A string specifying the application name defined in AppList.xml. You must associate the application with a category accessed by the Web service. For example, if you defined “xPression WebService” in AppList.xml, be sure to associate it with the category that contains the document you’re retrieving from the content repository. Requesting a Document by XML Customer Data The requestDocumentsWithData method enables you to retrieve a document from the xPression database by passing an XML string containing a single customer record. When invoking this method, xPression overrides the primary data source with the supplied XML string. Use this method only if the category your document is associated with has an XML data source. This method returns an object that contains the stream name, format, and a byte array containing the returned document. It is up to the calling program to save the byte array as a file. 274 Deprecated xPression Web Services Note: Note: All input parameters are case sensitive. For example, if your output profile is “PDF to File,” but you pass “PDF to file,” the SOAP request will fail. Syntax OPStream[] = requestDocumentsWithData(documentName, customerKey, customerData, dataSourceName, outputProfileName, userName, passWord, appName) Parameters documentName : String Specifies the name of the document you’re retrieving from the content repository. customerKey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: 1 -or 1 English customerData : String A string containing a customer record in XML format. The XML stream can contain a single record from the primary table and, optionally, additional related records from secondary tables in your data source. For example, if you were requesting the Withdrawal Notice Letter document, your XML stream would contain a single record from the primary table. 1 Sara Jones 6732 River Run University City, CA 22445 August 5, 2002 Flexible Premium Variable Life Insurance Policy 2.5% 2.5% 275 Deprecated xPression Web Services 78889567 English CA 2005-12-31 The value of the key for the customerKey parameter must be the same value referenced in the customerData parameter. For example, if the customerKey parameter has a value of 1 but the customerData references a different value, the call to request DocumentsWithData will fail. dataSourceName : String A string specifying an XML data source you associated with a category in xAdmin. To invoke requestDocumentsWithData, you must provide an XML data source here. Otherwise, the method will return a SOAP Fault. outputProfileName : String Specifies the name of the output profile you’re using to retrieve a document. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. passWord : Byte[] An encrypted byte array specifying the password for the user who has been granted access rights to the category and application in xAdmin. Use the webtool.jar utility to convert a text password to an encrypted byte array. appName : String A string specifying the application name defined in AppList.xml. You must associate the application with a category accessed by the Web service. For example, if you defined “xPression WebService” in AppList.xml, be sure to associate it with the category that contains the document you’re retrieving from the content repository. Request Document by Output Profile This method publishes a document to an output profile given as input. If For all return to caller streams in the output profile the Stream Name, Stream format and Stream Output will be returned. The return parameter will be null if no return to calling application output streams are found. This method is a new method to the Document Requester web service. It is a hybrid of the Document Requester requestDocumentsWithData method and the xPressionRequest publishAndReturnDocument Method. The methods used to return the datasource in xPressionRequest should be used similarly in this method. Also please note there is not a need for an encrypted password in this method. It is very important that the returned data includes not only the output but the stream name and format so the client can differentiate between the different streams and operate on them properly based on the format. Should the method fail, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. 276 Deprecated xPression Web Services Syntax OPStream [] streamArray = requestDocumentsByOutputProfile(documentName, userName, password, outputProfile, customerData, applicationName) Parameters documentName : String The name of the document to publish. userName : String The user name that the method will use to validate that the user has permission to publish the document requested. If the user does not have permission to read the document according to its category and application name given as input, the request will be rejected. password : String The password that corresponds to the userName, authenticated by xPression platform security. outputProfile : String The output profile the document will be published to. customerData : String An XML document containing data required to assemble the document given as input. This data must match an XML data source defined in xAdmin as the default data source for the document category and application name given as input. applicationName : String The xPression Application Name defined and configured in xAdmin for the category the document belongs to. The Document Composer Web Service The document composer service enables you to distribute a previously assembled document, using any output profile defined in xAdmin. You can use this service in tandem with the document requester by invoking either requestDocuments or requestDocumentsWithData to retrieve a document. Then you’d pass the returned document to the document composer service. The wsdl description for the document Composer can be viewed at following location: http://localhost:8080/xPressionWebService/services/Composer?wsdl Substitute the server name and server port number where web services is installed. 277 Deprecated xPression Web Services The Compose Document Method The method returns a 0 if the service successfully processes the request. Otherwise, the method returns a SOAP Fault, indicating the reason for the failure. For more information, see Errors, page 300. Note: All input parameters are case sensitive. For example, if your output profile is “PDF to File,” but you pass “PDF to file,” the SOAP request will fail. Syntax returnVal = Compose(msoHtmlDoc, documentName, outputProfileName, userName, passWord) Parameters msoHtmlDoc: Byte[] A byte array containing an assembled document. documentName : String Specifies the name of the document you’re distributing. outputProfileName : String Specifies the name of the output profile you’re using to distribute the supplied document. For more information, see the Administering the xPression Server guide. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. passWord : Byte[] An encrypted byte array specifying the password for the user who has been granted access rights to the category and application in xAdmin. Use the webtool.jar utility to convert a text password to an encrypted byte array. The xPression Request Web Service The xPression Request web service contains methods to conveniently access some of the most common xPression services. The wsdl description for xPressionRequest can be viewed at following location: http://localhost:8080/xPressionWebService/services/xPressionRequest?wsdl Substitute the server name and server port number where web services is installed. 278 Deprecated xPression Web Services xPression Request contains the following methods: Publish Document, Preview PDF, View Categories for User, View Documents in Category, View Output Profiles for Document, Get BDT, Get Assembled Document, Publish MSOHTML Document, and Publish and Return Document. Note: This Web Service will generate an error message if no output stream generates output during publishing. The Publish Document Method The Publish Document web service method allows you to input an XML document as a customer data source override. The XML document must match the default data source group assigned to the document’s category. The web service method will override the customer data source with the provided XML document and publish that document to the output profile specified. “Return to calling application” output streams will not be returned. The method returns a String as an output parameter if the method completes successfully. The output string will have the following format: Message was successfully published to output profile where is the primary key of the primary table in the data source and is the name of the output profile specified in the method. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors, page 300. This method supports xDesign documents and all xPresso packages with one exception. If you are producing HTML output, xPresso for InDesign packages are not supported. Syntax publishDocument(DocumentName, UserName, Password, OutputProfile, CustomerData, AppName) 279 Deprecated xPression Web Services Parameters documentName: String Specifies the name of the document you are retrieving from the xPression database. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. passWord : String A string specifying the password for the corresponding user name. outputProfile : String Specifies the name of the output profile you’re using to distribute the supplied document. customerData : String The XML phrase that contains the data defined by XML data source. appName : String Specifies the name of the xPression application. The Preview HTML Method The preview HTML service enables you to publish an xPresso for Dreamweaver package in HTML format and return the file back to the adapter as an HTML Return to Application stream. The method returns a published HTML document as a Byte array. The array is serialized with BASE64 encoding/decoding according to the SOAP standard. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors, page 300. xDesign documents and other xPresso packages are not supported with this web service. Syntax previewHTML(DocumentName, UserName, Password, CustomerData, AppName) 280 Deprecated xPression Web Services Parameters documentName: String Specifies the name of the document you are retrieving from the xPression database. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. passWord : String A string specifying the password for the corresponding user name. customerData : String The XML phrase that contains the data defined by XML data source. appName : String Specifies the name of the xPression application. The Preview PDF Method The preview PDF service enables you to publish an xDesign document or xPresso for Adobe InDesign package in PDF format and return the file back to the adapter as a PDF Return to Application stream. The method returns a published PDF document as a Byte array. The array is serialized with BASE64 encoding/decoding according to the SOAP standard. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors, page 300. xPresso for Dreamweaver packages are not supported with this web service. When Used with xPublish Documents When this method is called for an xPublish document, the Web Service uses the default PDF output definition. Username and Password Filter Prior to xPression 3 build 30, it was possible to pass incorrect information for the username and password. Under certain circumstances, such as passing a data source for username, it was possible to cause the native code authentication software to abort and so shut down the server. To prevent this, username and password are now filtered as part of authentication and will not be passed if they do not meet these minimum standards: • Maximum string length 256 characters • No embedded EOL characters • No leading or trailing blanks 281 Deprecated xPression Web Services Syntax previewPDF(DocumentName, UserName, Password, CustomerData, AppName) Parameters documentName: String Specifies the name of the document you are retrieving from the xPression database. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. passWord : String A string specifying the password for the corresponding user name. customerData : String The XML phrase that contains the data defined by XML data source. appName : String Specifies the name of the xPression application. The View Categories for User Method The view categories for user service returns a list of categories available to the defined user. The method can complete successfully without returning any category names. This indicates that the user has not been given access rights to any xPression categories. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors, page 300. Syntax categoryForUser(UserName, Password, AppName) Parameters userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. passWord : String A string specifying the password for the corresponding user name. 282 Deprecated xPression Web Services appName : String Specifies the name of the xPression application. The View Documents in Category Method The view documents in category service returns a list of all xDesign documents and xPresso packages contained in the defined category. This list is returned as a String array that contains one document name for every document that resides in the defined category. This method can complete successfully without returning any document names, indicating that the category is empty. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors, page 300. Syntax documentsForCategory(UserName, Password, AppName) Parameters documentCategory : String A string specifying the name of the category whose contents you want to view. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. passWord : String A string specifying the password for the corresponding user name. appName : String Specifies the name of the xPression application. The View Output Profiles for Document Method The view output profiles for document service returns a list of output profiles assigned to the document from xDesign. This list is returned as a String array that contains one output profile name for every output profile assigned to the defined document. This method can complete successfully without returning any output profiles, indicating that no output profiles are assigned to the document. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors, page 300. This web service can only be used with xDesign documents. xPresso packages are not supported with this function. 283 Deprecated xPression Web Services Syntax outputProfilesForDocument(DocumentName, UserName, Password, AppName) 284 Deprecated xPression Web Services Parameters documentName : String A string specifying the name of the document whose output profiles you want to view. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. passWord : String A string specifying the password for the corresponding user name. appName : String Specifies the name of the xPression application. The Get BDT Method The get BDT web service returns a string that is an assembled list using the xDesign document name and customer data. The assembled list is the xDesign BDT that has already been updated with variables. This web service can only be used with xDesign documents. xPresso packages are not supported with this function. Syntax getBDT (documentName, customerData, userName, password, appName) Parameters documentName: String Specifies the name of the document you are retrieving from the xPression database. customerData: String The XML phrase that contains the data defined by XML data source. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. password : String A string specifying the password for the corresponding user name. appName: String Specifies the name of the xPression application. 285 Deprecated xPression Web Services The Get Assembled Document Method The get assembled document web service returns a byte array that is an assembled xDesign document in MSOHTML format. This web service can only be used with xDesign documents. xPresso packages are not supported with this function. Syntax getAssembledDocument (documentName, customerData, userName, password, appName) Parameters documentName: String Specifies the name of the document you are retrieving from the xPression database. customerData: String The XML phrase that contains the data defined by XML data source. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. password : String A string specifying the password for the corresponding user name. appName: String Specifies the name of the xPression application. The Publish MSOHTML Document Method The publish MSOHTML document web service returns a string array that is an assembled xDesign document in MSOHTML format. If the distribution defintion is “return to caller”, the return value will include the output format. If the distribution definitions is not return to caller, the return value will be empty. This web service does not support xPresso packages. Syntax publishMSOHTMLDocument (documentName, customerData, msohtml, outputProfileName, userName, password, appName) 286 Deprecated xPression Web Services Parameters documentName: String Specifies the name of the document you are retrieving from the xPression database. customerData: String The XML phrase that contains the data defined by XML data source. msohtml: byte[] A byte array containing an assembled document. outputProfileName: String Specifies the name of the output profile you’re using to retrieve a document. userName : String A string specifying the user who has been granted access rights to the category and application in xAdmin. password : String A string specifying the password for the corresponding user name. appName: String Specifies the name of the xPression application. The Publish And Return Document Method This method publishes a document to an output profile given as input. If the output profile has a single return to calling application distribution definition defined in the output profile, that stream will be returned to the caller. The return parameter will be null if no return to calling application output streams are found. If more than one return to caller output stream is found, the method will return the first stream found (order not guaranteed) so you should be certain that if you expect a document to be returned of a particular format, you only call an output profile which has one and only one output stream returned. Should the method fail, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. Syntax byte[] publishedDocument = publishAndReturnDocument(documentName, userName, password, outputProfile, customerData, applicationName) 287 Deprecated xPression Web Services Parameters documentName : String The name of the document to publish. userName : String The user name that the method will use to validate that the user has permission to publish the document requested. If the user does not have permission to read the document according to its category and application name given as input, the request will be rejected. passwoetrd : String The password that corresponds to the userName, authenticated by xPression platform security. outputProfile : String The output profile the document will be published to. customerData : String An XML document containing data required to assemble the document given as input. This data must match an XML data source defined in xAdmin as the default data source for the document category and application name given as input. applicationName : String The xPression Application Name defined and configured in xAdmin for the category the document belongs to. The xResponse Web Service The xResponse Web Service contains the following methods: Assign Document to User, Retrieve Work in Progress IDs Assigned to a User, and Reassign Work Item. This web service does not support xPresso packages. The Assign Document to User Method This method creates a work in progress ID (WIP ID) for the document and assigns the WIP ID to the xResponse user’s Work in Progress queue. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The method returns the WIP ID as a string if the method completes successfully. 288 Deprecated xPression Web Services Caution: If you use the Assign Document to User method you will not be able to use optional paragraphs. To use optional paragraphs, you must either use one of the following methods: • FastPath to xResponse passing customer data in the FastPath call • Create the work item directly in the xResponse web application • Use xEditor and the createWorkItem web service method The caller can call the “assignDocumentToUser” web service method with the following URL: http:///xPressionWebService/services/xResponseRequest?method= assignDocumentToUser Syntax assignDocumentToUser(DocumentName, AdminUserName, AdminPassword, AssignToUserName, CustomerData) Parameters DocumentName : String The name of the xPression document you want to assign. AdminUserName : String The username that the method will use to log in as the xResponse work administrator. This user must have Write_Document permission for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected. AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xPression platform security. AssignToUserName: String The user name to whom you are assigning the document. The document will be listed as a work in progress item when the user logs into xResponse. CustomerData : String The assignDocumentToUser web service locates the primary data source defined for the category that contains the document you want to assign. The web service then locates the default data source for the primary data source definition. Both the primary data source and the default data source must be in XML format. The input for this parameter is the XML document for the default data source. This data source must be a valid XML document according to the xPression data source definition. 289 Deprecated xPression Web Services The Retrieve Work In Progress IDs Assigned to a User Method This method returns a String array of WIP IDs assigned to the xResponse user’s work in progress queue. Note: This method does not authenticate the WIPUserName parameter. If you provide a bad user name as input, the method will simply return an empty string array of WIP IDs. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The caller can call the “wipIdsForUser” web service method with the following URL: http:///xPressionWebService/services/xResponseRequest?method= wipIdsForUser Syntax wipIdsForUser(AdminUserName, AdminPassword, WIPUserName) Parameters AdminUserName : String The username that the method will use to log in as the xResponse work administrator. This user must have permission to approve documents in xResponse. AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xPression platform security. WIPUserName : String The user name for whom the method should look up WIP IDs. The Reassign Work Item Method If this method completes successfully, it returns the following String as an output parameter: Work item ID '' was successfully reassigned to the work in progress queue for user '' where WorkItemID is the WIP ID of the work item you want to reassign, and AssignToUserName is the user name to whom you are assigning the work item. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. 290 Deprecated xPression Web Services The caller can call the “reassignWorkItem” web service method with the following URL: http:///xPressionWebService/services/xResponseRequest?method= reassignWorkItem Syntax reassignWorkItem(AdminUserName, AdminPassword, AssignToUserName, WIPID) Parameters AdminUserName : String The username that the method will use to log in as the xResponse work administrator. This user must have Write_Document permission for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected. AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xPression platform security. AssignToUserName : String The user name to whom you are assigning the document. The document will be listed as a work in progress item when the user logs into xResponse. WIPID : String The WIP ID that you want to reassign. This work item will be reassigned to the AssignToUserName specified above. The Create Work Item Method This method is designed for use with xEditor. This method creates a work in progress ID (WIP ID) for the document and assigns the WIP ID to the xResponse user’s Work in Progress queue. This method enables optional paragraphs and automatically selects all default optional paragraphs set in xDesign. The method returns the WIP ID as a string if the method completes successfully. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The caller can call the "createWorkItem" web service method with the following URL: http:///xPressionWebService/services/xResponseRequest?method= Syntax createWorkItem(documentName, adminUserName, adminPassword, assignToUserName, 291 Deprecated xPression Web Services customerData) Parameters documentName : String The name of the xPression document you want to assign. adminUserName : String The username that the method will use to log in as the xResponse work administrator. This user must have Write_Document permission for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected. adminPassword : String The password that corresponds to the AdminUserName, authenticated by xPression platform security. assignToUserName : String The user name to whom you are assigning the document. The document will be listed as a work in progress item when the user logs into xResponse. customerData : String The createWorkItem web service locates the primary data source defined for the category that contains the document you want to assign. The web service then locates the default data source for the primary data source definition. Both the primary data source and the default data source must be in XML format. The input for this parameter is the XML document for the default data source. This data source must be a valid XML document according to the xPression data source definition. Publish and Return Document The Publish and Return Document Web Service method provides return to caller support for DOCX output. This method returns a byte array of the document content. Note that there is a method with the same name in the xPression Request web service. There are significant differences between the two methods. Syntax publishAndReturnDocument (String wipID, String username, String password, String outputProfileName) Parameters This web service employs the following parameters. 292 Deprecated xPression Web Services wipID : String The ID of the work in progress. username : String The username that the method will use to log in to xResponse. Password : String The password that corresponds to the username. outputProfileName: String The name of the output profile. The Revise Request Web Service Caution: This web service has been deprecated since xPression 4.5. Users should instead use the IDocumentItem web service. The Revise request web service contains the following methods: Assign Document to User, Retrieve Work in Progress IDs Assigned to a User, Reassign Work Item, Query Work Item Status, Complete Item, Preview Work Item In PDF, Update Work Item Primary Data, Delete Work Item, and Publish and Return Work Item. This web service does not support xPresso packages. The Assign Document To User Method This method creates a work in progress ID (WIP ID) for the document and assigns the WIP ID to the xRevise user’s Work in Progress queue. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The method returns the WIP ID as a string if the method completes successfully. The caller can call the “assignDocumentToUser” web service method with the following URL: http:///xPressionWebService/services/xReviseRequest?method= assignDocumentToUser Syntax assignDocumentToUser(DocumentName, AdminUserName, AdminPassword, AssignToUserName, CustomerData) Parameters DocumentName : String 293 Deprecated xPression Web Services The name of the xPression document you want to assign. AdminUserName : String The username that the method will use to log in as the xRevise work administrator. This user must have xRevise “Admin” privilege for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected. AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xPression platform security. AssignToUserName : String The user name to whom you are assigning the document. The document will be listed as a work in progress item when the user logs into xRevise. CustomerData : String The assignDocumentToUser web service locates the primary data source defined for the category that contains the document you want to assign. The web service then locates the default data source for the primary data source definition. Both the primary data source and the default data source must be in XML format. The input for this parameter is the XML document for the default data source. This data source must be a valid XML document according to the xPression data source definition. The Retrieve Work In Progress IDs Assigned to a User Method This method returns a String array of WIP IDs assigned to the xRevise user’s work in progress queue. Note: This method does not authenticate the WIPUserName parameter. If you provide a bad user name as input, the method will simply return an empty string array of WIP IDs. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The caller can call the “wipIdsForUser” web service method with the following URL: http:///xPressionWebService/services/xReviseRequest?method= wipIdsForUser Syntax wipIdsForUser(AdminUserName, AdminPassword, WIPUserName) Parameters AdminUserName : 294 String Deprecated xPression Web Services The username that the method will use to log in as the xRevise work administrator. This user must have permission to approve documents in xRevise. AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xPression platform security. WIPUserName : String The user name for whom the method should look up WIP IDs. The Reassign Work Item Method If this method completes successfully, it returns the following String as an output parameter: Work item ID '' was successfully reassigned to the work in progress queue for user '' where WorkItemID is the WIP ID of the work item you want to reassign. and AssignToUserName is the user name to whom you are assigning the work item. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The caller can call the “reassignWorkItem” web service method with the following URL: http:///xPressionWebService/services/xReviseRequest?method= reassignWorkItem Syntax reassignWorkItem(AdminUserName, AdminPassword, AssignToUserName, WorkItemID) Parameters AdminUserName : String The username that the method will use to log in as the xResponse work administrator. This user must have the xRevise “Admin” priviliege for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected. AdminPassword: String The password that corresponds to the AdminUserName, authenticated by xPression platform security. AssignToUserName The user name to whom you are assigning the document. The document will be listed as a work in progress item when the user logs into xRevise. 295 Deprecated xPression Web Services WorkItemID The WIP ID that you want to reassign. This work item will be reassigned to the AssignToUserName specified above. The Query Work ItemStatus Method The output of this web service is “Pending”, “Approved”, or “Rejected” if work item is not completed. If the work item is completed, the output is “Completed”. Syntax String queryWorkItemStatus(String wipId, String username, String password) Parameters wipId : String The ID of the work item. username : String The current username. The user must have access to perform the required function. password : String The user’s password. The Complete Item Method The output of this web service is “Work item (name) has been completed.” This web service moves work item to completed item’s queue, and delete unused RU revisions. Syntax String completeItem(String wipId, String username, String password) Parameters wipId : String The ID of the work item. 296 Deprecated xPression Web Services username : String The current username. The user must be the work item owner to use this web service. password : String The user’s password. The Preview Work Item In PDF Method This method overrides data when previewing a WIP work item. Syntax String previewWorkItemInPDF(String wipId, String customerData, String username, String password) Parameters wipId : String The work in progress work item ID. customerData : String The data source must use the same schema as the primary data source. If customerData is set as null, this web service works just as previewing the work item as PDF. username : String The name of the user. The user must have at least “read” premission to perform the required function. password : String The user’s password. The Update Work Item Primary Data Method This method provides the ability to edit an xRevise work item once, but publish it many times. Syntax String statusMessage = updateWorkItemPrimaryData(AdminUserName, AdminPassword, WorkItemID, CustomerData) 297 Deprecated xPression Web Services Parameters This Web service includes the following parameters. AdminUserName : String This user must have the xRevise “Admin” privilege for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected. AdminPassword: String The password that corresponds to the AdminUserName, authenticated by xPression security platform. WorkItemID The xRevise WIP ID that you want to update. CustomerData: String XML proper for the primary data source defined for the category belonging to the WorkItemID as input. The web service then locates the default data source for the primary data source definition and extracts only the primary table variables from the XML and only those variables that are not key fields. Both the primary data source and the default data source must be in XML format. The input for this parameter is the XML document for the default data source. This data source must be a well formed XML document. Returns Status message stating the WorkItemID was updated. Notes • The ’admin’ user is not necessarily the owner of the WIP item. • For XML tags with no data in them, the original variable value will be replaced to empty. • If no tag is passed in the XML, the original variable value will not be replaced. • If the user changes any variable value in xEditor, then this changed value will be retained throughout and will not be replaced. • Enables use of subdocuments. • Updates OP variables. • Simple variable replacement throughout document and ASL for fields in primary table. The Delete Work Item Method This method delete xRevise work items including completed work items. 298 Deprecated xPression Web Services Syntax deleteWorkItem(AdminUserName, AdminPassword, WorkItemID) Parameters This Web service includes the following parameters: AdminUserName : String The user name that the method uses to log in as the xRevise work administrator. This user must have the xRevise “Admin” privilege for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected AdminPassword: String The password that corresponds to the AdminUserName, authenticated by xPression security platform. WorkItemID The xRevise WIP ID of the work item that you want to delete. Returns Status message stating that the work item was successfully deleted . The Publish and Return Work Item Method This method publishes an xRevise work item with the specified output profile. Syntax publishAndReturnWorkItem(AdminUserName, AdminPassword, WorkItemID, OutputProfileName) Parameters This Web service includes the following parameters: AdminUserName : String The user name that the method uses to log in as the xRevise work administrator. This user must have the xRevise “Admin” privilege for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected 299 Deprecated xPression Web Services AdminPassword: String The password that corresponds to the AdminUserName, authenticated by xPression security platform. WorkItemID The xRevise WIP ID of the work item that you want to publish. OutputProfileName The name of the output profile that you want to use. Returns A byte array of the document content. Errors If an error occurs while either the document requester or document composer Web services are processing a request, the method returns a SOAP Fault to the client, indicating the reason for the error. The following is an example of a SOAP Fault: 9005 Document not found /soap/servlet/rpcrouter To display the fault string to the user, you need to parse the XML response using an XML parser. XML parsers are widely available from a number of vendors, including Microsoft and Sun Microsystems. For COM or .NET applications, the SOAP Toolkit provides methods for displaying fault codes and strings. To see a list of all error codes produced by the xPression Web Services, see the resource_webservice_error.properties file located in your xPressionHome directory. 300 Chapter 15 The Deprecated xPression Java API This section covers the deprecated Web Services model. With version 4.0, xPression introduces a new Web Service API that conforms to the WS-I Basic Profile. The old xFramework Web Service API, Java API, and xAdapter have been deprecated. Although these items will be supported for backward compatibility in the current version, EMC Document Sciences encourages you to use the new Web Service API as it offers better performance, greater flexibility, and better security. In this chapter, we’ll show you how to write Java classes that encapsulates the most common methods in the high-level xPression Java API. We’ll also show you how to create an application that generates instant auto and homeowners insurance quotes and discuss various approaches to packaging and deploying your J2EE xPression application. Writing an XPression Facade Java Class In this section, we’ll show you how to connect to an xPression server, retrieve categories, retrieve documents associated with a specific category, and assemble and retrieve a PDF document stored in the content repository. The complete application we’re going to create is an automatic insurance quote generator. In the next chapter, we’ll show you how to create the thin client piece of the application that calls the Java class we’re writing in this chapter. Objectives In this chapter, we’ll cover the following: • Dependencies, page 302 • Creating a Simple Properties File, page 302 • Connecting to xPression, page 302 • Retrieving Categories, page 304 • Retrieving Document Names, page 305 • Retrieving a Document, page 305 301 The Deprecated xPression Java API Dependencies To complete the sample Java class in this chapter, you’ll need to include the xPressionJavaAPI.jar library in the classpath for your development environment. We’re now ready to create our Java class and add several methods to it. Creating a Simple Properties File In your Quote Generator application, you’ll need to have a readable and writable path where xPression will store PDF documents. To avoid hard coding a path in the Java class, let’s create a simple properties file called XDK.properties in a text editor. Add the following line to the file: tempPath=C:\\WebSphere\\AppServer\\installedApps\\xPression.ear\\Quote_Gen.war\\ xPressionDocs\\ In the above example, we’re assuming you’re using WebSphere and that it’s installed on the C drive. Also, we’re assuming you’re deploying the application to the xPression.ear enterprise application. Both these assumptions may not reflect your actual environment. For example, you may use BEA WebLogic as your application server and you may deploy the Quote Generator application to a different enterprise application than xPression. Therefore, your tempPath setting would be different from the above example. Keep in mind that the required section of the path is \\Quote_Gen.war\\xPressionDocs\\. Connecting to xPression Launch your Java development environment and create a new class called quote_gen.java. Add the following code to the top of the class: package quote_gen; import java.util.*; import java.io.*; import com.docscience.xpression.framework.XPressionFacade; public class quote_gen { private XPressionFacade facade = null; private String tempPath = ""; private byte[] bDoc = null; } You can change the package statement if you intend to nest your Java classes at a deeper directory level. Now add the connect method below the variable declarations: public void connect(String url, String context, String userName, String password, String appName) { try { 302 The Deprecated xPression Java API //init the xPression server facade = new XPressionFacade(); 303 The Deprecated xPression Java API facade.initServerConnection(url, context); //start session facade.getStartSession(userName, password, appName); //set the temp path for docs tempPath = getTempPath(); } catch (Exception e) { e.printStackTrace(); } } The initServerConnection method requires a URL that consists of a server name and port number. Be sure to supply a URL that’s valid for your own environment. Look at the servers.xml file in your xPression home directory for valid entries. You’ll also notice we’re calling a method to retrieve the tempPath from XDK.properties. Add the getTempPath method below the connect method: private String getTempPath() { String path = ""; try { InputStream fileInputStream = this.getClass().getClassLoader().getResourceAsStream("XDK.properties"); Properties xdkProperties = new Properties(); xdkProperties.load(fileInputStream); path = xdkProperties.getProperty("tempPath"); } catch (Exception e) { e.printStackTrace(); } return path; } Retrieving Categories We’ll now add the method to retrieve all the category names stored in the xPression database. Add the getCategories method: public String[] getCategories() { String[] returnVals = null; try { 304 The Deprecated xPression Java API returnVals = facade.getCategories(); } catch (Exception e) { e.printStackTrace(); } return returnVals; } Retrieving Document Names Let’s now add the method to retrieve documents that "live" in a specific category. Add the getDocumentNames method: public String[] getDocumentNames(String categoryName) { String[] returnVals = null; try { returnVals = facade.getBusinessDocuments(categoryName); } catch (Exception e) { e.printStackTrace(); } return returnVals; } Retrieving a Document Now we’re going to write some code to retrieve a document in PDF format. Add the getDocument method: public String getDocument(String docName, String xmlData, String xmlDataSource) { String fileName = null; try { bDoc = facade.getDocumentPDF(docName, xmlData, xmlDataSource); fileName = saveDoc(); } catch (Exception e) { e.printStackTrace(); } return fileName; } 305 The Deprecated xPression Java API Notice that this method requires that we pass both the XML data source name and the XML data stream in order to assemble the document with the data you’ll pass from your own application. Finally, we need to add the saveDoc method: private String saveDoc() { String returnValue = null; File file = null; try { // create the file name String fileName=String.valueOf(System.currentTimeMillis()); file=new File(tempPath+fileName+".pdf"); FileOutputStream out = new FileOutputStream(file); out.write(bDoc); out.close(); returnValue=fileName; } catch (Exception e) { e.printStackTrace(); } return returnValue; } In the saveDoc method, we’re saving the byte array returned by the getDocumentPDF method to a file on the server. That’s all there is to the Java class. Compile and test it on your own if you want. Writing a Quote Generator Application In this section, we’ll show you how to create an application that generates instant auto and homeowners insurance quotes. The application will consist of several JSP pages that call the quote_gen class we wrote in the last chapter. Specifically, the application will present the user a list of insurance types, either auto or homeowner. The user will select an insurance type, select a quote document, enter several values required to generate the quote, and receive an instant quote document in PDF format. Objectives In this chapter, we’ll cover the following: • Dependencies, page 302 • Initial Setup, page 307 • Creating Standard Header and Footer Pages, page 308 • Presenting a List of Categories, page 309 • Presenting a List of Documents, page 311 • Presenting Input Fields, page 313 306 The Deprecated xPression Java API • Generating a PDF Quote, page 315 • Summary, page 320 Dependencies To complete the Quote Generator application, you’ll need to include quote_gen.class in the classpath for your development environment. Additionally, the application uses two documents you’ll need to import into the xPression database you’re using for development, as well as sample data for each document. You’ll find the PDP on the eBooks CD in \\xPression Framework\XDK\Documents\. You’ll find the XML data files for each document in \\xPression Framework\XDK\Documents\ CustomerData. Initial Setup In this chapter, we’re creating a Java Web application (WAR) that you can deploy on any computer with either WebSphere or WebLogic client. Figure 7. On your development machine create a folder structure that resembles the following image, which shows the Quote_Gen.war folder structure. Be sure to copy the XDK.properties file you created in the last chapter to \Quote_Gen.war\WEB -INF\classes. 307 The Deprecated xPression Java API Let’s take a closer look at what goes in each folder. Folder name Contents Quote_Gen.war Contains all the JSP pages that comprise that Quote Generator application. Quote_Gen.war\css Contains the css.css stylesheet we’ll use for minor formatting of the JSP pages. You’ll find the stylesheet on the eBooks CD in \\xPression Framework\XDK\source\css. Quote_Gen.war\images Contains the image files we’ll use for minor formatting of the JSP pages. You’ll find the images on the eBooks CD in \\xPression Framework\XDK\source\images. Quote_Gen.war\META-INF Contains the MANIFEST.MF file that is generated when you create a WAR with a J2EE development tool like WebSphere Studio. For more information, see Deploying an xPression Application, page 320. Quote_Gen.war\WEB-INF Contains files describing your application. For more information, see Deploying an xPression Application, page 320. Quote_Gen.war\WEB-INF \classes Contains the XDK.properties file we created in chapter 2. Quote_Gen.war\WEB-INF \classes\quote_gen Contains the Java class file we created in chapter 2. Quote_Gen.war\WEB-INF\lib Contains all the Java libraries (JAR files) your application needs. For this application, we’re only using xPressionJavaAPI.jar. You’ll find this file in your xRevise and xResponse EAR files. Quote_Gen.war\xPression -Docs Contains the PDF documents your application generates when a user requests an instant quote. Creating Standard Header and Footer Pages To avoid creating the same headers and footers on each page in our application, we’ll create a couple standard JSP pages we can include in all our main JSPs. Open your JSP editor and create three new JSP pages. Name them hdr.jsp, ftr.jsp, and preview_top.jsp. 1. Add the following code to hdr.jsp: 308 The Deprecated xPression Java API

xPression Quote Generator

2. Now add the code for preview_top.jsp: <%@ include file="hdr.jsp" %>

[Start Over]

3. Finally, add the code for ftr.jsp:

© Document Sciences Corporation 2004. All rights reserved.

Presenting a List of Categories We’ll now create a JSP page that displays the policy types the user will choose from to generate a quote. In your JSP editor, create a new page called index.jsp. Add the following code to index.jsp: <%@ include file="hdr.jsp" %> 309 The Deprecated xPression Java API <% //replace with appropriate values depending on environment String url = "iiop://localhost:9081"; String context = "com.ibm.websphere.naming.WsnInitialContextFactory"; String userName = "xpression"; //for security purposes, use an encrypted password that you //decrypt here String password = "xpression"; String appName = "xPression Response"; //connect to xPression quote_gen.connect(url,context,userName,password,appName); //get categories String categories[] = quote_gen.getCategories(); %>

Select a policy type: <% for (int i=0;i <%=categories[i]%> <% } %>

<%@ include file="ftr.jsp" %> Let’s take a look at the code is doing: • We’re including a reference to our Java class at the top of the page. • We’re adding an include statement to insert the code in hdr.jsp into index.jsp. 310 The Deprecated xPression Java API • In the script block, we’re initializing the variables we need to start the xPression session. Observe that we’re making certain assumptions about the xPression environment. You’ll need to modify these variables in your own environment. For example, the context factory value will be different if you’re using BEA WebLogic as your application server. • We’re also getting a list of categories the current user has access to. • In the bottom block of HTML code, we’re populating an option list with all the category names retrieved from the getCategories method. Note: Do you want to test the Quote Generator application? We suggest you grant read access to a "test" user for the two categories you created when you imported the quote documents. Figure 8. The resulting page should look like this when launched in your browser. Presenting a List of Documents On the index.jsp page, we indicated that the form action launched a page called getDocuments.jsp. Let’s now create that new page. Add the following code to the getDocuments page: <%@ include file="hdr.jsp" %> <% String categoryName = request.getParameter("categoryName"); String docs[] = quote_gen.getDocumentNames(categoryName); session.setAttribute("categoryName",categoryName); %>

Select a quote: <% for (int i=0;i <%=docs[i]%> <% } %>

<%@ include file="ftr.jsp" %> This page should look similar to index.jsp, with a few differences: • We’re retrieving the category name from the form field on the index.jsp page. • We’re retrieving all the associated document names for the selected category by calling the getDocumentNames method in the quote_gen Java class. 311 The Deprecated xPression Java API • We’re setting a session variable for the category. In subsequent pages, we’ll need to know which category the user has selected. • Finally, we’re populating a drop-down list with all the document names returned by the getDocumentNames method. 312 The Deprecated xPression Java API Figure 9. The resulting GetDocuments.jsp page should look like this when launched in your browser. Presenting Input Fields If you imported PolicyQuotePDP.zip, you’ll see that the two new documents each have their own data sources. Therefore, our quote application will present different input fields based on the category the user selects. Let’s now add the code for getInputs.jsp: <%@ include file="hdr.jsp" %> <% String categoryName = session.getAttribute("categoryName").toString(); String docName = request.getParameter("docName"); session.setAttribute("docName",docName); %>

Please provide values in the following fields: <% if (categoryName.equals("Auto")) { %> First Name: Middle Initial: Last Name: Address: City: State: Zip: Make: Model: Model Year: Deductible: Auto Coverage Limit: Personal Property Coverage Limit: Loss of Use Limit: Liability Protection (each occurrence): Medical Payments to Others (each person): <%} else {%> 313 The Deprecated xPression Java API First Name: Middle Initial: Last Name: Address: City: State: Zip: Deductible: Dwelling Coverage Limit: Other Structures Coverage Limit: Personal Property Coverage Limit: Loss of Use Limit: Liability Protection (each occurrence): Medical Payments to Others (each person): <%}%>

<%@ include file="ftr.jsp" %> This page is lengthy, but simple: • We’re retrieving the category name from a session variable. • We’re retrieving the document name from the previous page. • We’re storing the document name in a session variable for later use. • Finally, we’re adding input fields to the page based on the category the user selected. 314 The Deprecated xPression Java API Figure 10. The resulting GetInputs.jsp page should look like this when launched in your browser. This graphic only shows a sampling of the user input fields displayed on getInputs.jsp. Generating a PDF Quote After the user has entered values for all the input fields and clicks the Get Instant Quote button, the getQuote.jsp page is executed. Let’s now add the code for getQuote.jsp: <%! public static String markup(String text) { if (text == null) { return null; } StringBuffer buffer = new StringBuffer(); for (int i = 0; i < text.length(); i++) { char c = text.charAt(i); switch (c) { case '<': buffer.append("<"); break; case '&': buffer.append("&"); break; case '>': buffer.append(">"); break; case '"': buffer.append("""); break; default: buffer.append(c); break; } } return buffer.toString(); } %> <% String fileName=""; try{ // get session values String categoryName=session.getAttribute("categoryName").toString(); String docName = session.getAttribute("docName").toString(); //init String String String vars xmlDataSource = ""; xmlData = ""; extension = ".pdf"; //this is an arbitrary number - obviously some calculation is necessary String annualPremium = "1150.00"; 315 The Deprecated xPression Java API String fName = ""; String mInit = ""; String lName = ""; String address = ""; String city = ""; String state = ""; String zip = ""; String clientNum = ""; String make = ""; String model = ""; String modelYear = ""; String deductible = ""; String liabProtLimit = ""; String medPayLimit = ""; String autoCvgLimit = ""; String persPropCvgLimit = ""; String lossUseCvgLimit = ""; String dwelCvgLimit = ""; String othStrCvgLimit = ""; //get form values and create XML string if (categoryName.equals("Auto")) { xmlDataSource = "AutoQuoteDS"; fName = request.getParameter("F_NAME"); mInit = request.getParameter("M_INIT"); lName = request.getParameter("L_NAME"); address = request.getParameter("PROP_ADDR_1"); city = request.getParameter("PROP_CITY"); state = request.getParameter("PROP_STATE"); zip = request.getParameter("PROP_ZIP"); make = request.getParameter("MAKE"); model = request.getParameter("MODEL"); modelYear = request.getParameter("YEAR"); deductible = request.getParameter("DEDUCTIBLE"); liabProtLimit = request.getParameter("LIAB_PROT_LIMIT"); medPayLimit = request.getParameter("MED_PAY_LIMIT"); autoCvgLimit = request.getParameter("AUTO_CVG_LIMIT"); persPropCvgLimit = request.getParameter("PERS_PROP_CVG_LIMIT"); lossUseCvgLimit = request.getParameter("LOSS_USE_CVG_LIMIT"); //create XML string xmlData = "" + zip + fName + ""; xmlData += "" + fName + ""; xmlData += "" + mInit + ""; xmlData += "" + lName + ""; xmlData += "" + state + ""; xmlData += "" + zip + ""; xmlData += "" + zip + fName + ""; xmlData += "" + address + ""; xmlData += "" + city + ""; xmlData += "" + state + ""; xmlData += "" + zip + ""; xmlData += "" + make + ""; xmlData += "" + model + ""; xmlData += "" + modelYear + ""; xmlData += "" + deductible + ""; xmlData += "" + liabProtLimit + ""; xmlData += "" + medPayLimit + "" xmlData += "" + autoCvgLimit + ""; xmlData += "" + persPropCvgLimit + ""; xmlData += "" + lossUseCvgLimit + ""; xmlData += "" + annualPremium + ""; xmlData += ""; 316 The Deprecated xPression Java API } else { xmlDataSource = "HomeownerQuoteDS"; fName = request.getParameter("F_NAME"); mInit = request.getParameter("M_INIT"); lName = request.getParameter("L_NAME"); address = request.getParameter("PROP_ADDR_1"); city = request.getParameter("PROP_CITY"); state = request.getParameter("PROP_STATE"); zip = request.getParameter("PROP_ZIP"); deductible = request.getParameter("DEDUCTIBLE"); liabProtLimit = request.getParameter("LIAB_PROT_LIMIT"); medPayLimit = request.getParameter("MED_PAY_LIMIT"); dwelCvgLimit = request.getParameter("DWEL_CVG_LIMIT"); persPropCvgLimit = request.getParameter("PERS_PROP_CVG_LIMIT"); lossUseCvgLimit = request.getParameter("LOSS_USE_CVG_LIMIT"); othStrCvgLimit = request.getParameter("OTH_STR_CVG_LIMIT"); //create XML string xmlData = "" + zip + fName + ""; xmlData += "" + fName + ""; xmlData += "" + mInit + ""; xmlData += "" + lName + ""; xmlData += "" + state + ""; xmlData += "" + zip + ""; xmlData += "" + zip + fName + ""; xmlData += "" + address + ""; xmlData += "" + city + ""; xmlData += "" + state + ""; xmlData += "" + zip + ""; xmlData += "" + deductible + ""; xmlData += "" + liabProtLimit + ""; xmlData += "" + medPayLimit + "" xmlData += "" + dwelCvgLimit + ""; xmlData += "" + othStrCvgLimit + ""; xmlData += "" + persPropCvgLimit + ""; xmlData += "" + lossUseCvgLimit + ""; xmlData += "" + annualPremium + ""; xmlData += ""; } //replace reserved characters in XML data String xmlDataMarkup = markup(xmlData); fileName = quote_gen.getDocument(docName, xmlData, xmlDataSource); //redirect to preview page if (fileName!=null) { session.setAttribute("fileName",fileName); //set path session.setAttribute("filePath","./xPressionDocs/"+fileName+extension); //go to preview page response.sendRedirect("preview.jsp"); } else { response.sendRedirect("index.jsp"); } } catch(Exception e){ e.printStackTrace(); } %> 317 The Deprecated xPression Java API Let’s look at what the code is doing: • We’re creating a method to strip reserved HTML characters from a string of data and replace them with valid characters. • We’re retrieving the category and document names stored in session variables. We need the category name to determine how to assign values to the variables declared on this page. We’ll pass the document name to the Java class method that returns a PDF document. • Next, we’re initializing several variables, including annualPremium. Here we’re using a hard coded value. In your own applications, you’d want to calculate the annual premium. • We then check which category the user selected and assign values to the variables. • Then we create an XML data string. This is the how xPression generates an instant quote using data the user has entered. While we’re using a simple approach to generating XML, we strongly recommend you use a formal XML parsing engine to generate your data streams. • Next we call the markup method and the getDocument method, passing the document name, the XML data, and the XML data source name. • Finally, if the quote document is successfully created, we redirect the browser to the preview.jsp page. 318 The Deprecated xPression Java API Let’s now create the final page in the Quote Generator application: preview.jsp. Add the following code: <% String pageName = "Preview"; //get path String filePath=session.getAttribute("filePath").toString(); %> <body bgcolor="#FFFFFF"> </body> You’ll notice that the page only needs a bit of script to set the page name and the path for the PDF document. The remaining code creates three frames, which consist of: • A header frame that includes a Start Over link to return the user to the main page in the application. • A middle frame that displays the instant quote in PDF format. • A footer frame that shows the HTML we’ve used to format all the pages in the application. 319 The Deprecated xPression Java API Figure 11. The resulting Preview.jsp page should look like this when launched in your browser. Summary Now that we’ve finished writing the code for our Quote Generator application, you’ll want to deploy it on your client workstation or server. In the next chapter, we’ll show you how to generate a WAR file for your application so you can deploy it either on a client workstation or a server. Deploying an xPression Application In this chapter, we’ll discuss various approaches to packaging and deploying your J2EE xPression application. While we’re suggesting you package the Quote Generator application in a WAR file, you might prefer packaging a pure Java application in a JAR file, or an enterprise application in an EAR file. This chapter discusses the following topics: • J2EE Application Assembly, page 320 • J2EE Web Application Overview, page 321 • J2EE Enterprise JavaBeans Overview, page 321 • J2EE Utility Classes Overview, page 321 • Web Application Archive Construction, page 322 J2EE Application Assembly Before we begin packaging the Quote Generator, let’s discuss the various approaches to J2EE application assembly. There are three different types of J2EE applications: • J2EE Web Applications • J2EE Enterprise JavaBeans (EJBs) • J2EE Utility Class Archives You can combine one or more of these applications into a single J2EE Enterprise Archive, as seen in J2EE Application Assembly, page 320. We’ll discuss each of the applications at a high level before we get into the details of assembling the Quote Generator application. Figure 12. The following image shows the J2EE application assembly. 320 The Deprecated xPression Java API J2EE Web Application Overview J2EE Web Applications are the easiest to understand and work with if you know how to construct Web-enabled applications. J2EE Web Applications contain HTML, GIF, JPEG, and other files appropriate for building Web-enabled applications. Web browsers serve up these files through a Web server like Microsoft’s Internet Information or Apache’s Apache Web Server. J2EE application servers typically integrate with these external Web servers. They may also have their own Web server capabilities. External Web servers cannot easily serve up dynamic content, so J2EE Web applications that use Servlets and JSP pages require a link between an external Web server and an application server. J2EE application servers use these technologies in a Web application to serve dynamic content in addition to any static content in the Web application. J2EE Web Applications are packaged into WAR (Web application archive) files for easier deployment to an application server. WAR files must also have an XML-based deployment descriptor file (web.xml) to describe their contents. J2EE Enterprise JavaBeans Overview The Enterprise JavaBeans (EJB) technology provides the ability to rapidly code and deploy specialized components inside the application server. EJBs come in several different types according to the routine tasks a J2EE application developer needs to perform. For example, EJB Entity Beans are designed to help a developer work with persistent data in a transactional database, and EJB Message-Driven Beans are designed to help a developer work with message queues. EJB components are packaged into JAR (Java ARchive) files for easier deployment to an application server. A single JAR file may contain one or many EJBs, with each EJB composed of an XML-based deployment descriptor, an EJB Home Interface class, an EJB Remote Interface class, and an EJB Implementation class. J2EE Utility Classes Overview J2EE Utility Class archives are collections of Java classes and associated resources you can use in Web applications and EJBs. This mechanism provides an easy way to use third-party utility libraries. For example, xPression makes use of the popular Apache open source log4j utility library, and adding the library once to the J2EE Enterprise Archive makes its capabilities available for use by xPression’s various Web applications and EJBs. J2EE Utility Classes are packaged into JAR (Java ARchive) files for easier deployment to an application server. They can contain any file loaded through a Java CLASSPATH, most notably, Java class files, properties files, and locale-specific resource files. 321 The Deprecated xPression Java API Web Application Archive Construction Let’s now use our Quote Generator application to demonstrate how to assemble a Web application archive. The application uses the following files and folder structure for a WAR file: • ftr.jsp • getDocuments.jsp • getInputs.jsp • getQuote.jsp • hdr.jsp • index.jsp • preview.jsp • preview_top.jsp • css\css.css • images\global_clear.gif • images\pixel-blue.gif • WEB-INF\web.xml • WEB-INF\classes\XDK.properties • WEB-INF\classes\quote_gen\quote_gen.class • WEB-INF\lib\xPressionJavaAPI.jar Let’s look at what these files do. • The first eight files are JSPs at the root of the Web application. • The next file is a cascading style sheet, something familiar to Web site designers. In the overview of a WAR, we discussed that a Web application can contain any type of file normally present in a good Web site. • The next two files are images, which are also customary for a good Web application. An images folder is commonly used to enable Web applications to share image files across multiple Web pages. The Web application could contain any number of other files and directories, nested as deeply as you want for good Web site design. • In J2EE Web applications, the WEB-INF folder is reserved for a web.xml file. The web.xml document must be in the WEB-INF directory so the J2EE server can recognize the WAR properly. The web.xml file is called a web application deployment descriptor, that is, an XML document that describes the contents and configuration of the web application. J2EE specifications dictate the structure and contents of this file. The most common use of this file is to register servlets you’ve written so the container knows what URL calls which Java servlet class. • Next is the XDK.properties file, which contains a path where xFramework stores PDF documents. • The next file is the quote_gen.class file required for the Quote Generator application to operate properly. You may recall from a beginning Java course that each class should be part of a package 322 The Deprecated xPression Java API so classes can be organized into folders and quickly found in the CLASSPATH. WEB-INF\classes is a sort of CLASSPATH storage area for classes only your Web application uses. • Finally, we must place the xPressionJavaAPI.jar file in a lib folder inside WEB-INF so your Web application can gain access to the xPression API. After you’ve completed the folder structure according to the above rules, you can easily create a WAR file by using the Java "jar" utility, which comes with the Java JDK. From a command prompt, change to the root folder of the Quote_Gen application structure (where the JSP files are) and execute: jar cvf ..\Quote_Gen.war *.* This command will create a proper WAR file in the parent folder of the application structure. That way, you’ll avoid including the WAR file in subsequent executions of the command. Now that you’ve created a WAR file for your application, feel free to deploy the Web application on your client workstation or server. Command Reference The xFramework Command Reference documents the two public classes and their methods in the high-level JFramework API. There are a few conventions we follow throughout this chapter. Each class has an introductory paragraph explaining its general purpose. All members of each class are explained fully, including the proper syntax, parameters, and code examples. All code examples are written in Java. This chapter is intended as a glossary for the high-level JFramework API. For complete instructions on how to use the API, see Writing an XPression Facade Java Class, page 301. Each method is formatted as follows: Method Name Descriptive paragraph. Syntax Object.methodName parm1, parm2 Parameters Parm1 : Data Type Descriptive text. parm2 : Data Type Descriptive text. 323 The Deprecated xPression Java API Sample public class CodeSample { public void sampleMethod() { try { //sample code here } catch { //sample error code here } } } 324 The Deprecated xPression Java API The XPressionFacade Class The XPressionFacade class contains the all the methods you’ll need for your xFramework applications. For information about exceptions that each method generates, see xPression Facade Exceptions, page 345. This section includes these methods: getAppName, getBusinessDocuments, getCategories, getDocumentPackedMSOHTML, getDocmentPackedMSOHTML (overloaded), getDocumentPDF, getDocumentPDF (overloaded), getHaveStartSession, getOutputProfiles, getSchema, getStartSession, initServerConnnection, setStatus, publishDocument, and publishDocument (overloaded). getAppName This method, which returns a string, enables you to retrieve the xPression application name you’re using for your Framework session. The application name is set when you initialize a server connection. For more information, see initServerConnection, page 337. Syntax appName = XPressionFacade.getAppName(); Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public String getAppName() { String returnVal = ""; facade = new XPressionFacade(); try { returnVal = facade.getAppName(); } catch { System.out.println("An error occurred getting the app name."); } return returnVal; } } getBusinessDocuments This method, which returns a string array, enables you to retrieve all business document names for the supplied category. 325 The Deprecated xPression Java API Syntax docs[] = XPressionFacade.getBusinessDocuments(categoryName); Parameters categoryName : String An input parameter containing the category name whose documents you’re retrieving. Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public String[] getBusinessDocuments(String categoryName) { String[] returnVals = null; facade = new XPressionFacade(); try { returnVals = facade.getBusinessDocuments(categoryName); } catch { System.out.println("An error occurred getting the document names."); } return returnVals; } } getCategories This method, which returns a string array, enables you to retrieve all the categories the signed on user has access to. Syntax categories[] = XPressionFacade.getCategories(); Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public String[] getCategories() { String[] returnVals = null; facade = new XPressionFacade(); try { 326 The Deprecated xPression Java API returnVals = facade.getCategories(); } catch { System.out.println("An error occurred getting the categories."); } return returnVals; } } 327 The Deprecated xPression Java API getDocumentPackedMSOHTML This method, which returns a byte array, enables you to retrieve an assembled document from the xPression database in packed (or compressed) MSOHTML format. For more information on unpacking MSOHTML, see Appendix A, The Webtool Utility. You must then convert the byte array to a logical file and unpack (decompress) the file. Syntax document[] = XPressionFacade.getDocumentPackedMSOHTML(documentName, customerKey); Parameters documentName : String An input parameter containing the document name you’re assembling. customerKey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: 1 -or 1 English Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public byte[] getMSOHTMLDoc(String documentName, String customerKey) { byte[] returnVals = null; facade = new XPressionFacade(); try { returnVals = facade.getDocumentPackedMSOHTML(documentName, customerKey); } catch { System.out.println("An error occurred getting the document."); } return returnVals; } } 328 The Deprecated xPression Java API When the document you specify contains a sub-document, the sub-document will use customer data from the default data source instead of the customerData you provide. The customer data you specify only works for the master document, not the subdocument. getDocumentPackedMSOHTML (overloaded) This method, which returns a byte array, enables you to retrieve an assembled document from the xPression database in packed (or compressed) MSOHTML format. For more information on unpacking MSOHTML, see Appendix A, The Webtool Utility. Calling this overloaded method is perfect when you want to pass XML customer data that you generate on the fly in transactional applications. You must then convert the byte array to a logical file and unpack (decompress) the file. Syntax document[] = XPressionFacade.getDocumentPackedMSOHTML(documentName, customerData, xmlDataSourceName); Parameters documentName : String An input parameter containing the document name you’re assembling. customerData : String A string containing a customer record in XML format. The XML stream can contain a single record from the primary table and, optionally, additional related records from secondary tables in your data source. In the following example, the customer data is a single record from the primary table. 1 Sara Jones 6732 River Run University City, CA 22445 August 5, 2002 Flexible Premium Variable Life Insurance Policy 2.5% 2.5% 78889567 English CA 2005-12-31 329 The Deprecated xPression Java API xmlDataSourceName : String An input parameter containing the name of an XML data source you’re using to assemble the document. Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public byte[] getMSOHTMLDoc(String documentName, String customerData, String xmlDataSourceName) { byte[] returnVals = null; facade = new XPressionFacade(); try { returnVals = facade.getDocumentPackedMSOHTML(documentName, customerData, xmlDataSourceName); } catch { System.out.println("An error occurred getting the document."); } return returnVals; } } 330 The Deprecated xPression Java API getDocumentPDF This method, which returns a byte array, enables you to retrieve an assembled document from the xPression database in PDF format. You must then convert the byte array to a logical file on your own. Syntax document[] = XPressionFacade.getDocumentPDF(documentName, customerKey); Parameters documentName : String An input parameter containing the document name you’re assembling. customerKey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: 1 -or 1 English Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public byte[] getPDFDoc(String documentName, String customerKey) { byte[] returnVals = null; facade = new XPressionFacade(); try { returnVals = facade.getDocumentPDF(documentName, customerKey); } catch { System.out.println("An error occurred getting the document."); } return returnVals; } } 331 The Deprecated xPression Java API When the document you specify contains a sub-document, the sub-document will use customer data from the default data source instead of the customerData you provide. The customer data you specify only works for the master document, not the subdocument. getDocumentPDF (overloaded) This method, which returns a byte array, enables you to retrieve an assembled document from the xPression database in PDF format. Calling this overloaded method is perfect when you want to pass XML customer data that you generate on the fly in transactional applications. You must then convert the byte array to a logical file on your own. Syntax document[] = XPressionFacade.getDocumentPDF(documentName, customerData, xmlDataSourceName); Parameters documentName : String An input parameter containing the document name you’re assembling. customerData : String A string containing a customer record in XML format. The XML stream can contain a single record from the primary table and, optionally, additional related records from secondary tables in your data source. In the following example, the customer data is a single record from the primary table. 1 Sara Jones 6732 River Run University City, CA 22445 August 5, 2002 Flexible Premium Variable Life Insurance Policy 2.5% 2.5% 78889567 English CA 2005-12-31 xmlDataSourceName : String 332 The Deprecated xPression Java API An input parameter containing the name of an XML data source you’re using to assemble the document. 333 The Deprecated xPression Java API Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public byte[] getPDFDoc(String documentName, String customerData, String xmlDataSourceName) { byte[] returnVals = null; facade = new XPressionFacade(); try { returnVals = facade.getDocumentPDF(documentName, customerData, xmlDataSourceName); } catch { System.out.println("An error occurred getting the document."); } return returnVals; } } getHaveStartSession The method, which returns a true or false value, determines if your xPression session is started. Syntax isStarted = XPressionFacade.getHaveStartSession(); Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public boolean isSessionStarted() { boolean returnVal = null; facade = new XPressionFacade(); try { returnVal = facade.getHaveStartSession(); } catch { System.out.println("An error occurred determining if your xPression session is started."); } return returnVal;}} 334 The Deprecated xPression Java API getOutputProfiles This method, which returns a two-dimensional string array, enables you to retrieve output profile names and IDs from the content repository. The following table illustrates the values contained in the returned array. Column Sample Value 0 (ID) 1234 1 (name) PDF to File Syntax outputProfiles[][] = XPressionFacade.getOutputProfiles(); Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public String[][] getOutputProfiles() { String[][] returnVals = null; facade = new XPressionFacade(); try { returnVals = facade.getOutputProfiles(); } catch { System.out.println("An error occurred getting output profiles."); } return returnVals;} } 335 The Deprecated xPression Java API getSchema This method, which returns a byte array, enables you to retrieve the primary data source group schema in XML format for the category you supply. Syntax schema[] = XPressionFacade.getSchema(categoryName); Parameters categoryName : String An input parameter containing the category name. Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public byte[] getSchema(String categoryName) { byte[] returnVals = null; facade = new XPressionFacade(); try { returnVals = facade.getSchema(categoryName); } catch { System.out.println("An error occurred getting the schema."); } return returnVals; } } getStartSession This method enables you to start an xPression session for a specific user and application, such as xResponse or a custom application of your own. Syntax XPressionFacade.getStartSession(userName, password, appName); 336 The Deprecated xPression Java API Parameters userName : String An input parameter containing the user name. password : String An input parameter containing the user password. appName : String An input parameter containing the application name. Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public void startSession(String userName, String password, String appName) { facade = new XPressionFacade(); try { facade.getStartSession(userName, password, appName); } catch { System.out.println("An error starting your xPression session."); } } } initServerConnection This method enables you to establish a connection with your xPression server. One of the parameters you supply for this method is the "contextFactory," which refers to the context object path for the application server you’re using, either IBM WebSphere or BEA WebLogic. Syntax XPressionFacade.initServerConnection(serverProtocolURL, contextFactory); Parameters serverProtocolURL : String An input parameter containing the URL for your xPression server. contextFactory : String An input parameter containing the context object path for your application server. 337 The Deprecated xPression Java API Sample import com.docscience.xpression.framework.XPressionFacade; public class FacadeTest { public void initServer() { facade = new XPressionFacade(); String url = "iiop://localhost:2809"; String context = "com.ibm.websphere.naming.WsnInitialContextFactory"; try { facade.initServerConnection(url, context); } catch { System.out.println("An error occurred initializing the xPression server."); } } } setStatus The setStatus API parameter was added to the XPressionFacade class to enable users to specify which document status is eligible for publishing. Valid values are ANY and APPROVED. The default value is approved. Because the default status is APPROVED, you do not need to use this API if your document is approved. Syntax setStatus (stringValue) Parameters stringValue You can set this value to either ANY or APPROVED. public class FacadeTest{ public void testPublishDocument(){ XPressionFacade facade = new XPressionFacade(); String documentName = ""; String customerKey = ""; String outputProfileName = ""; facade.setStatus(XPressionFacade.STATUS_ANY); facade.publishDocument(documentName, customerKey, outputProfileName); } } 338 The Deprecated xPression Java API publishDocument This method, which returns an XPressionDocument object, enables you to assemble and publish a document from the xPression database using an output profile you supply. Syntax XPressionDocument[] = XPressionFacade.publishDocument(documentName, customerKey, outputProfileName); Parameters documentName : String An input parameter containing the document name you’re publishing. customerKey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: 1 -or 1 English outputProfileName : String An input parameter containing the output profile name. To retrieve output profiles, use the getOutputProfiles, page 335 method. Sample import import import import com.docscience.xpression.framework.XPressionFacade; com.docscience.xpression.framework.XPressionDocument; java.io.FileOutputStream; java.io.FileInputStream; public class FacadeTest { public void publishDocument(String documentName, String customerKey, String outputProfile) { XPressionDocument[] documents = null; facade = new XPressionFacade(); try { 339 The Deprecated xPression Java API documents = facade.publishDocument(documentName, customerKey, outputProfile); for (int i=0;i 1 Sara Jones 6732 River Run 340 The Deprecated xPression Java API University City, CA 22445 August 5, 2002 Flexible Premium Variable Life Insurance Policy 2.5% 2.5% 78889567 English CA 2005-12-31 xmlDataSourceName : String An input parameter containing the name of an XML data source you’re using to publish the document. outputProfileName : String An input parameter containing the output profile name. To retrieve output profiles, use the getOutputProfiles, page 335 method. Sample import import import import com.docscience.xpression.framework.XPressionFacade; com.docscience.xpression.framework.XPressionDocument; java.io.FileOutputStream; java.io.FileInputStream; public class FacadeTest { public void publishDocument(String documentName, String customerData, String xmlDataSourceName, String outputProfile) { XPressionDocument[] documents = null; facade = new XPressionFacade(); try { documents = facade.publishDocument(documentName, customerData, xmlDataSourceName, outputProfile); for (int i=0;i/xPressionAdapter/webServices/xPressionRequest.jws?wsdl Publish Document Web Service Method To call the Publish Document Web service method, type: http:///xPressionAdapter/webServices/xPressionRequest.jws?method= publishDocument This Web service method accepts the following input parameters. Parameter Description Type DocumentName The name of the xPression document to publish. String UserName The name of an xPression user with permission to publish the selected document. String Password The password for the xPression user. String OutputProfile The xPression output profile used to publish the document. The publish process will fail if incorrectly defined. String Transformation Specifies whether a named transformation should be String applied by the transformation engine. If null or empty string, a default transformation for the document or document category will be applied. CustomerData The XML document for the xPression XML format data source. 352 String The Deprecated xPression EAI Adapter The Web service method will return a String as an output parameter should the method complete successfully. The output String will have the following format: Message '' was successfully published to output profile ''. MessageId is the primary key of the primary table involved in the xPression XML data source. OutputProfile is the output profile specified in the call to the Web service. The Web service method returns a SOAP fault should the method fail. The error text of the SOAP fault returns a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. Preview PDF Web Service Method To call the Preview PDF Web service method, type: http:///xPressionAdapter/webServices/xPressionRequest.jws?method= previewPDF This Web service method accepts the following parameters. Parameter Description Type DocumentName The name of the xPression document to publish. String UserName The name of the user logging on to xPression. This user must have permission to publish the document selected or the request will fail. String Password The password that corresponds to the UserName, authenticated by xPression platform security. String OutputProfile The xPression output profile to publish the document to. This output profile must be a valid option for the DocumentName to be published to. String Transformation Specifies whether a named transformation should be applied by the transformation engine. If this parameter is null or an empty string a default transformation for the document or document category will be applied if configured. String CustomerData The XML document for the xPression XML format data source. String The Web service returns a byte array (which in accordance with SOAP standards is serialized with BASE64 encoding/decoding) should the request be successfully processed. This byte array is the published document in PDF format. The Web service method returns a SOAP fault should the method fail. The error text of the SOAP fault returns a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. 353 The Deprecated xPression EAI Adapter Post For Batch Web Service Method To call the Post For Batch Web service method, type: http:///xPressionAdapter/webServices/xPressionRequest.jws?method= postForBatch This Web service method accepts the following input parameters. Parameter Description Type BatchDocumentType The type of batch document to be processed by the adapter, configured in the adapter’s configuration properties file. String UserName The name of the user to log into xPression. String Password The password that corresponds to the UserName, authenticated by xPression platform security. String CustomerData The XML document for the xPression XML format data source. String The Web service method returns a String as an output parameter should the method complete successfully. The output String has the following format: Customer data records for xPression batch document type '' was successfully written to input XML file directory '' BatchDocumentType corresponds to the input parameter given in the request. The Web service method returns a SOAP fault should the method fail. The error text of the SOAP fault returns a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. Categories For User Web Service Method To call the Categories For User Web service method, type: http:///xPressionAdapter/webServices/xPressionRequest.jws?method= categoriesForUser 354 The Deprecated xPression EAI Adapter This Web service method accepts the following input parameters. Parameter Description Type UserName The name of the user to log into xPression. String Password The password that corresponds to the UserName, authenticated by xPression platform security. String The Web service method returns a String array as an output parameter should the method complete successfully. There will be one document category in the String array for every document category the user is eligible to publish documents to. It’s possible that the request complete successfully with no entries returned (which means there are no categories to which the user is eligible to publish). The Web service method returns a SOAP fault should the method fail. The error text of the SOAP fault includes a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. Documents For Category Web Service Method To call the Documents For Category Web service method, type: http:///xPressionAdapter/webServices/xPressionRequest.jws?method= documentsForCategory This Web service method accepts the following parameters. Parameter Description Type DocumentCategory The xPression category that contains the document to publish. String UserName The name of the user to log on to xPression. This user must have permission to publish documents in the DocumentCategory selected or the request will fail. String Password The password that corresponds to the UserName, authenticated by xPression platform security. String The Web service method returns a String array as an output parameter when the method completes successfully. There will be one document name in the String array for every document in xPression contained within the DocumentCategory given as input. It is possible for the request to complete successfully with no entries returned (which means there are no documents registered in the category given). The Web service method returns a SOAP fault if the method fails. The error text of the SOAP fault includes a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. 355 The Deprecated xPression EAI Adapter Output Profiles For Document Web Service Method To call the Variables for Document web service method, type: http:///xPressionAdapter/webServices/xPressionRequest.jws?method= outputProfilesForDocument This Web service method accepts the following parameters. Parameter Description Type DocumentName The name of the xPression document to retrieve assigned output profiles. String UserName The name of the user to log on to xPression. This user must have permission to publish documents in the document category that the document belongs to or the request will fail. String Password The password that corresponds to the UserName, authenticated by xPression platform security. String The web service method returns a String array as an output parameter when the method completes successfully. There will be one xPression Output Profile in the String array for every output profile assigned to the document in xDesign. It is possible for the request to complete successfully with no entries returned (which means there are no output profiles assigned to the document). The web service method returns a SOAP fault if the method fails. The error text of the SOAP fault includes a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. Variables for Document Web Service Method To call the Variables for Document web service method, type: http:///xPressionAdapter/webServices/xPressionRequest.jws?method= variablesForDocument This Web service method accepts the following parameters. Parameter Description Type DocumentName The name of the xPression document to retrieve assigned output profiles. String UserName The name of the user to log on to xPression. This user must have permission to publish documents in the document category that the document belongs to or the request will fail. String Password The password that corresponds to the UserName, authenticated by xPression platform security. String The web service method will return a String array as an output parameter should the method complete successfully. There will be one xPression document variable in the String array for every document variable defined in xAdmin for the document specified. The adapter looks for the default data source group assigned to the document’s category and returns all variables for that default data 356 The Deprecated xPression EAI Adapter source group. It is possible that the request complete successfully with no entries returned (which means there are no variables used in the document). Each variable will be in the format: TABLE.FIELD where TABLE is the xPression Data Source Group table and FIELD is a field defined within that table. The web service method returns a SOAP fault if the method fails. The error text of the SOAP fault includes a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. JMS-Based Messaging Mechanism For adapters equipped with JMS messaging support, the adapter’s JMS-Based messaging mechanism utilizes the J2EE standardized Message-Driven EJB technology. This technology provides the ability to pull messages off a JMS supported message queuing technology (for example, IBM MQ Series/WebSphere MQ) using application server facilities for pooling EJBs and parallel processing. However, message-driven EJBs only support pulling messages off one queue and don’t natively support pushing output messages to an output queue. To minimize these limitations and achieve your requirements, the adapter is designed as follows: • One message-driven EJB class can be configured by any number of named message-driven EJBs in the ejb-jar.xml file deployment. So Document Sciences can write only one Java class implementing the message-driven EJB and it can be named any number of times in the EJB descriptor files. In WebSphere, there is an additional XMI descriptor file that relates a named EJB instance to a JMS adapter listener port, which ties a named EJB instance to an input JMS queue. • Each message-driven EJB named instance defines a custom property, the JNDI reference to the JMS output queue, in the ejb-jar.xml file. In this manner, each named EJB instance will not only be configured to pull off a different input queue but will also push output messages to a different output queue. • Each named EJB instance can be configured by WebSphere-specific properties in XMI descriptor files for container support of pooling and concurrency. All named EJB instances support the following types of XML-based input messages: • Publish a document to an output profile (request type = Publish Document) • Preview a document in PDF format (request type = Preview PDF) • Submit a document to be published in batch (request type = Post for Batch) For the Publish Document and Post For Batch request types, there is an optional parameter in the XML header that may declare the caller does not want an output message to be queued to the output JMS queue (this parameter doesn’t make sense for Preview PDF request where the output queue is always sent a binary document message upon successful completion). 357 The Deprecated xPression EAI Adapter Publish Document Message The Publish Document input message requires the following XML request parameters. Parameter Description Required? RequestType The type of request this XML message represents. The value for this message must be Publish Document. Y DocumentName The name of the xPression document to publish. Y UserName The name of the user to log into xPression. This user must have permission to publish the document selected or the request will fail. Y Password The password that corresponds to the UserName, authenticated by xPression platform security. Y OutputProfile The xPression Output Profile to publish the document to. This Output Profile must be a valid option for the DocumentName to be published to. Y ReturnStatusMessage A flag which tells the adapter message listener whether to place a message on the output queue telling whether the request was completed or not. This parameter is not required and if not given, the default is “Y” (yes, a status message will be placed on the output queue). Valid values for this parameter are “Y” and “N” (no, a status message will not be placed on the output queue, even if the request cannot be processed). N Transformation Specifies whether a named transformation should be applied by the transformation engine. If this parameter is not given, a default transformation for the document or document category will be applied if configured. N CustomerData The XML document for the xPression XML format data source. Y An example XML input file for the Publish Document message is shown below. Publish Document Automatic Payment Letter xpression xpression Combined Print Archive Email 1 358 The Deprecated xPression EAI Adapter Mary K. Jackson 9573 Main Street San Diego CA, 92108 1/1/2002 50 Wells Fargo 10000 John Doe 760-222-1574 English CA 2005-12-12 [email protected] 1 1 1001 JMS Flexible Premium Variable Life 67-2301-810 $934.00 Monthly 4/8/2002 2 1 1002 JMS Portfolio Annuity 5573-135-4361 $360.00 Monthly 10/24/2002 If the ReturnStatusMessage flag is set to return a status message, the xAdapter will compose an XML document and send it to the output queue. The return status message will have the following output fields. Output Field Name Description Output Conditions RequestType The type of request this XML message represents. The value for this message must be Publish Document. This field is present in all output messages as long as the input message is properly formed. DocumentName The name of the xPression Document to publish. This field is present in all output messages as long as the input message is properly formed 359 The Deprecated xPression EAI Adapter Output Field Name Description Output Conditions UserName The name of the user to log into xPression. This user must have permission to publish the document selected or the request will fail. This field is present in all output messages as long as the input message is properly formed OutputProfile The xPression Output Profile to publish the document to. This Output Profile must be a valid option for the DocumentName to be published to. This field is present in all output messages as long as the input message is properly formed. RequestSuccess-ful Flag telling if the request was successfully processed. Valid values are “Y” (yes, the request was processed successfully), and “N” (no, the request had an error in the course of processing). This field is present in all output messages MessageId The primary key of the first customer data record, if the information can be found in the request to be processed. This field is present in all output messages as long as the customer data record can be properly processed to obtain this information. OutputMessage A message telling what request was processed. Example: This field is only present when the request is successfully processed Message ’’ was successfully published to output profile’’. ErrorCode The unique error code from the adapter for any error encountered processing the request. The field is only present when the request cannot be processed ErrorMessage An error message explaining the error code and any pertinent data involved in the error. The field is only present when the request cannot be processed If the Publish Document request is completed successfully, an example XML output message would look like this: Publish Document Automatic Payment Letter xpression Combined Print Archive Email Y 1 Message '1' was successfully published to output profile 'Combined Print Archive Email'. 360 The Deprecated xPression EAI Adapter If the Publish Document request is not completed successfully, an example XML output message would look like this: Publish Document Automatic Payment Letter xpression Combined Print Archive Email N 1 10101 An error occurred while starting a FrameWork service. Preview PDF Message The Preview PDF input message requires the following XML request parameters. Parameter Description Required? RequestType The type of request this XML message represents. The value for this message must be Preview PDF. Y DocumentName The name of the xPression document to publish. Y UserName Y The name of the user to log into xPression. This user must have permission to publish the document selected or the request will fail. Password The password that corresponds to the UserName, authenticated by xPression platform security. Transformation Specifies whether a named transformation should N be applied by the transformation engine. If this parameter is not given, a default transformation for the document or document category will be applied if configured. CustomerData The XML document for the xPression XML format data source. Y Y An example XML input file for the Publish Document message is shown here. Preview PDF Automatic Payment Letter xpression xpression 361 The Deprecated xPression EAI Adapter 1 Mary K. Jackson 9573 Main Street San Diego CA, 92108 1/1/2002 50 Wells Fargo 10000 John Doe 760-222-1574 English CA 2005-12-12 [email protected] 1 1 1001 JMS Flexible Premium Variable Life 67-2301-810 $934.00 Monthly 4/8/2002 2 1 1002 JMS Portfolio Annuity 5573-135-4361 $360.00 Monthly 10/24/2002 If this request is completed successfully, the output message will be a binary message consisting of the PDF format document output from the request. If this request is not completed successfully, the output message will be an XML message with these output fields. Output Field Name Description Output Conditions RequestType The type of request this XML message represents. The value for this message must be Publish Document. This field is present in all output messages as long as the input message is properly formed. DocumentName The name of the xPression Document to publish. This field is present in all output messages as long as the input message is properly formed. 362 The Deprecated xPression EAI Adapter Output Field Name Description Output Conditions UserName The name of the user to log into xPression. This user must have permission to publish the document selected or the request will fail. This field is present in all output messages as long as the input message is properly formed RequestSuccess-ful Flag telling if the request was successfully processed. Valid values are “Y” (yes, the request was processed successfully), and “N” (no, the request had an error in the course of processing). This field is present in all output messages MessageId The primary key of the first customer data record, if the information can be found in the request to be processed. This field is present in all output messages as long as the customer data record can be properly processed to obtain this information. ErrorCode The unique error code from the adapter for any error encountered processing the request. The field is only present when the request cannot be processed ErrorMessage An error message explaining the error code and any pertinent data involved. The field is only present when the request cannot be processed If the Preview PDF request is not completed successfully, an example XML output message would look like this: Preview PDF Automatic Payment Letter xpression N 1 10101 An error occurred while starting a FrameWork service. Post For Batch Message The Post For Batch input message requires the following XML request parameters. Parameter Description Required? RequestType The type of request this XML message represents. The value for this message must be Post for Batch. Y BatchDocument-Type The type of batch document to be processed by the adapter, configured in the adapter’s configuration properties file. Y 363 The Deprecated xPression EAI Adapter Parameter Description Required? UserName The name of the user to log into xPression. Y Password The password that corresponds to the UserName, authenticated by xPression platform security. Y ReturnStatusMessage A flag which tells the adapter message listener whether to place a message on the output queue telling whether the request was completed or not. This parameter is not required and if not given, the default is “Y” (yes, a status message will be placed on the output queue). Valid values for this parameter are “Y” and “N” (no, a status message will not be placed on the output queue, even if the request cannot be processed). N CustomerData The XML document for the xPression XML format data source. Y An example XML input file for the Post for Batch message is shown here. Post For Batch Policy xpression xpression 1 Mary K. Jackson 9573 Main Street San Diego CA, 92108 1/1/2002 50 Wells Fargo 10000 John Doe 760-222-1574 English CA 2005-12-12 [email protected] 1 1 1001 JMS Flexible Premium Variable Life 67-2301-810 $934.00 Monthly 4/8/2002 2 364 The Deprecated xPression EAI Adapter 1 1002 JMS Portfolio Annuity 5573-135-4361 $360.00 Monthly 10/24/2002 If the ReturnStatusMessage flag is set to return a status message, the xAdapter will compose an XML document and send it to the output queue. The return status message will have the following output fields. Output Field Name Description Output Conditions RequestType The type of request this XML message represents. The value for this message must be Publish Document. This field is present in all output messages as long as the input message is properly formed. BatchDocument-Type The type of batch document to be processed by the adapter, configured in the adapter’s configuration properties file. This field is present in all output messages as long as the input message is properly formed. UserName The name of the user to log into xPression. This field is present in all output messages as long as the input message is properly formed. RequestSuccessful Flag telling if the request was successfully processed. Valid values are “Y” (yes, the request was processed successfully), and “N” (no, the request had an error in the course of processing). This field is present in all output messages. MessageId The primary key of the first customer data record, if the information can be found in the request to be processed. This field is present in all output messages as long as the customer data record can be properly processed to obtain this information. OutputMessage A message telling which request was processed. Example: This field is only present when the request is successfully processed. Customer data records for xPression batch document type ’Policy’ was successfully written to input XML file directory ’c:\\xPressionAdapter\ \PolicyXMLInputDir\\’. 365 The Deprecated xPression EAI Adapter Output Field Name Description Output Conditions ErrorCode The unique error code from the adapter for any error encountered processing the request. The field is only present when the request cannot be processed. ErrorMessage An error message explaining the error code and any pertinent data involved in the error. The field is only present when the request cannot be processed If the Post For Batch request is completed successfully, an example XML output message would look something like this: Post For Batch Policy xpression Y 1 Customer data records for xPression batch document type 'Policy' was successfully written to input XML file directory 'c:\\xPressionAdapter\\ PolicyXMLInputDir\\'. 366 The Deprecated xPression EAI Adapter If the Post For Batch request is not completed successfully, an example XML output message would look as follows: Post For Batch Policy xpression N 1 10321 Error writing the customer data file to the file system. XML Message Error Handling Should an XML Message input into a message-driven EJB not conform to the requirements above, the adapter will detect the following situations and always return an XML message to the output queue with error information. Malformed XML Should the XML Message input into the adapter not be well-formed XML, the adapter will return an error message as follows: N 10322 The XML message input into the adapter could not be parsed as it was not well-formed. 367 The Deprecated xPression EAI Adapter Request Type Not Supported Should the XML Message input into the adapter provide an invalid RequestType, the adapter will return an error message as follows: N 10323 RequestType "Preview PDF" is not supported. XML Missing a Required Parameter Should the XML Message input into the adapter fail to include a required parameter, the adapter will return an error message as follows: N 10324 Required parameter "OutputProfile" was not provided. Transformation Engine The transformation engine provides a framework for transforming XML Customer Data before it is submitted to xPression. This “streamlines” the XML so it can be processed more efficiently in xPression, and so that the xPression data schema and corresponding document design can be much simpler. Extensible Stylesheet Language Transformation (XSLT) is the industry standard technology for transforming XML. Since XSLT has some limitations, the transformation engine in the adapter is flexible enough to allow 3rd party transformations to be plugged into the adapter and invoked on demand. As long as that transformation can be called by a local Java class extended from a transformation engine base class named com.docscience.xpression.adapter.transform. AbstractTransformationEngine the adapter engine will implement a subclass of this base class, com.docscience.xpression.adapter.transform. JAXPTransformationEngine, to utilize the free Apache Xalan XSLT engine through the JAX Java XML standard. 368 The Deprecated xPression EAI Adapter Each transformation defined in the adapter has a transformation name, a transformation engine (the default being the JAXPTransformationEngine), and a set of one or more properties associated with the transformation (for example, in the JAXPTransformationEngine, it is the XSLT file to apply to the input XML). Example property file settings follow for a transformation named PolicyTransformation, using the default XSLT/JAXP transformation implementation: Transform.PolicyTransformation.transformationClass= com.docscience.xpression.adapter.transform.JAXPTransformationEngine Transform.PolicyTransformation.xsltFile=C:\\xPressionAdapter\\ transformations\\Policy.xslt Because the default transformation is the JAXPTransformationEngine, the first property file setting can and should be omitted. The transformation engine can also set up default named transformations for documents and categories, should a request into the adapter publish or preview a document (that is, the “Publish Document” or “Preview PDF” request types only). The adapter will implement a maximum of one transformation per request, and the transformation will be found with the following algorithm: 1. If a transformation name is specified on the adapter request, that transformation is applied and any defaults are ignored. 2. If no transformation name is specified on the request, the transformation engine looks for a default transformation for the document name. 3. If no default transformation is specified for the document name, the transformation engine looks for a default transformation for the document’s category. 4. If no default category transformation is configured, no transformation at all will be applied. Example property file settings DocumentTransform.PolicyTransformation.documentName=NB Policy DocumentTransform.PolicyTransformation.transformName= PolicyTransformation CategoryTransform.BillingTransformation.categoryName= Billing Documents CategoryTransform.BillingTransformation.transformName= BillingTransformation The properties above define one default document transformation and one default category transformation. All documents with a name of “NB Policy” will execute the “PolicyTransformation” definition by default. All documents in the “Billing Documents” category will execute the “BillingTransformation” definition by default. The first time the Transformation Engine is loaded into the JVM, all properties in the xPressionAdapter.properties file with a prefix of Transform., DocumentTransform., and CategoryTransform., are loaded into 3 different HashMap tables respectively so transformations can be found and executed quickly. The Transform HashMap is keyed by the transformName, 369 The Deprecated xPression EAI Adapter the DocumentTransform HashMap is keyed by the document name, and the CategoryTransform HashMap is keyed by the category name. Should a generic XSLT transformation engine not suffice, you can create your own transformation engine by plugging in Java code you create into the adapter. To do so, you must extend the com.docscience.xpression. adapter.transform.AbstractTransformationEngine class and override the public Result transform(Source xmlSource) method. A template for doing so is provided below: package com.mycompany.xpression.adapter.transform; import javax.xml.transform.TransformerFactory; import javax.xml.transform.Transformer; import javax.xml.transform.Source; import javax.xml.transform.Result; import javax.xml.transform.stream.StreamSource; import javax.xml.transform.stream.StreamResult; import javax.xml.transform.TransformerConfigurationException; import javax.xml.transform.TransformerException; import com.docscience.xpression.adapter.transform.AbstractTransformationEngine; public class MyTransformationEngine extends AbstractTransformationEngine { /** * To process the source tree to the output result. * * @param xmlSource The input for the source tree. * @return Result */ public Result transform(Source xmlSource) { // insert code here to perform the transformation } } Should you complete the code for this class, named com.mycompany.xpression.adapter .transform.MyTransformationEngine, you would enable the class in a transformation named MyTransform with an xPressionAdapter.properties entry such as: Transform.MyTransform.transformationClass=com.mycompany.xpression.adapter. transform.MyTransformationEngine Using UTF–8 Format for Adapter Properties The Adapter service does not support UTF-8 format if the document includes the BOM (Byte Order Marker). The BOM is added by Notepad, so do not use Notepad to save the properties file in UTF-8 format. Instead, use an editor that does not add the BOM such as Notepad++. If the properties file includes a multi-byte character it must be converted after saving as UTF-8 (without BOM). Use the native2ascii command to update the file, for example: native2ascii -encoding UTF-8 inputfile outputfile The native2ascii.bat file can be found in the $JAVA_HOME$\bin folder. 370 The Deprecated xPression EAI Adapter XML File Export for Batch Execution The adapter supports a convenient way of executing the xPression Batch standardized component of the xPression product suite. xPression Batch is designed to publish large volumes of documents efficiently, and is the most efficient way to utilize the xPression publishing engine. However, xPression Batch supports the execution of only one XML input file per step. xPression Batch does not provide any XML transformation capabilities. The xAdapter accumulates smaller individual XML documents queued for batch execution throughout the day. The Adapter then provides a batch runner wrapper Java class, which optionally transforms and then merges the XML files in a format that can be used as input into one xPression Batch run, execute xPression Batch, and perform file cleanup activities. Note: xPression Batch 2.0 and above provides the ability to define multiple job steps in one batch job, and each job step can have a different XML data source override file. xAdapter supports only one job step, and that job step must have the same name as the batch job defined in xAdmin and configured in the xPressionAdapter.properties configuration file. XML files containing customer/document data can come from direct XML export to a file system accessible by the adapter. XML files may also come from the Web Services and JMS mechanisms above from the Post For Batch request type. For more information, see Post For Batch Web Service Method, page 354. Each batch job executed is identified by the type of documents published in the batch run. A batch job execution program calls the batch process from the command line according to any interval desired and defined in the batch job execution program. Caution: The Adapter batch runner wrapper must not, for the same batch document type, be called in parallel. Doing so would result in any number of issues as two adapter batch runners compete for the same file resources in the same input and temporary XML file holding areas. The Adapter batch runner wrapper accumulates any files not previously processed in a batch run of that document type and calls xPression Batch, using this command line: java com.docscience.xpression.adapter.batch.AdapterBatchRunner Policy In this case, “Policy” is the type of document to execute. The adapter would read all settings in the xPressionAdapter.properties property file with a prefix of Policy. 371 The Deprecated xPression EAI Adapter Here’s a sample property file: Policy.inputXmlFileDirectory=C:\\xPressionAdapter\\PolicyBatchXMLExport\\ Policy.inputXmlFileNamePattern=*.xml Policy.temporaryXmlFileDirectory=c:\\xPressionAdapter\\PolicyTempXML\\ Policy.errorXmlFileDirectory=c:\\xPressionAdapter\\PolicyErrorXML\\ Policy.mergedXmlFileDirectory=C:\\xPressionAdapter\\PolicyMergedXML\\ Policy.xPressionBatchJobName=PolicyBatchJob Policy.transformationName=PolicyTransformation Policy.customerDataMergeDelimiter = /dataroot/Transaction Policy.xmlErrorThreshold=100 The Adapter Batch Runner wrapper works as follows: 1. Check to see if the marker file C:\xPressionAdapter\PolicyTempXML\ BatchNotComplete .MARKER exists on the file system. 2. If the marker file already exists, assume a previous batch run did not complete successfully and perform no cleanup activities. 3. If the marker file doesn’t exist, perform the following: • Delete any files named C:\xPressionAdapter\PolicyTempXML\*.xml as these files may be leftover from a previous batch run and we don’t want to double-process them. If the files cannot be cleaned up, abort with a fatal error message in the log and a negative System.exit() code. • Write a marker file named C:\xPressionAdapter\PolicyTempXML \BatchNotComplete .MARKER to show that the Policy batch process has not yet completed successfully. If the file cannot be written, abort with a fatal error message in the log and a negative System.exit() code. 4. The program looks for all files named C:\xPressionAdapter\ PolicyBatchXMLExport\*.xml. For each file that matches this pattern we loop through and: • Move each file from the export directory to the C:\xPressionAdapter\PolicyTempXML directory (this step is taken for safety and recoverability, because moving the file ensures that the file is completely written to the file system and that the file names aren’t duplicated). • If the file can’t be moved, log as a warning message in the log file and move to the next file in the list (assume the file is locked because it isn’t completely written to the file system). 372 The Deprecated xPression EAI Adapter 5. Next, set the XML error threshold count to zero and look for all files named C:\xPressionAdapter\ PolicyTempXML\*.xml. For each file found, do the following processing: • Call the transformation engine with the XML file and a transformation named “PolicyTransformation”. Note that XML transformation is completely optional and the transformationName property defined about should be omitted if this is not needed. • Aggregate and merge those files into a file named C:\xPressionAdapter\PolicyMergedXML \PolicyBatchJob.xml in a format that can be directly input into xPression BatchRunner. • If a transformation is configured, run the appropriate transformation engine and catch any exceptions thrown. (If a transformation is not configured, proceed to the next bullet point in this step.) If an exception is thrown, consider the XML file to be bad. Move the original XML input file from the temp directory to the directory specified by the error XML file directory (C:\xPressionAdapter\PolicyErrorXML in the example on page 122). If the file already exists in the error directory, or the file cannot be moved for any reason, log a fatal error and abort the batch job with a negative exit code. If the file is moved successfully, increment the error threshold counter by one. Check the XML error threshold and, if it has been exceeded, log a fatal error and exit the batch job with a negative exit code. If a bad transformation is encountered, the original input file can be moved successfully from the temp directory to the error directory, and the error threshold is not exceeded, move on to the next input file at the beginning of step 5. If the transformation was successful or if no transformation was encountered, continue with the next bullet point. • For each XML file resulting from the above process (either successfully transformed or not transformed at all), parse the XML file stream to see if it is well-formed. If the XML is well-formed, then make sure the structure matches the customer data merge delimiter specified. If the XML file is not well-formed or if it is well-formed but cannot be merged because the XML node structure does not match the merge delimiter, move the original XML file from the temp directory to the directory specified by the error XML file directory (C:\xPressionAdapter\PolicyErrorXML in the example on page 122). If the file cannot be moved, log a fatal error and abort the batch job with a negative exit code. If the file is moved successfully, increment the error threshold counter by one. Check the XML error threshold and, if it has been exceeded, log a fatal error and exit the batch job with a negative exit code. If an XML error is encountered, the original file is moved successfully, and the threshold is not exceeded, move on to the next input file identified at the beginning of step 5. If the XML file is well-formed and complies with the customer data merge delimiter structure, proceed with the steps below. • When merging XML input records (after transformation if a transformation is engaged), the adapter needs to understand what XML node to start the merge process. In the example configuration on page 122, a merge delimiter of “/dataroot/Transaction” would tell the adapter to begin the merge process at the node underneath the root node of the XML document. Each input XML document would need to have a root element named “dataroot” and inside that element there must be at least one element named “Transaction”. Everything inside the “Transaction” element would be extracted from the current XML document and merged with other “Transaction” elements inside the current document and from other XML documents. The resulting XML document has the same XML structure as 373 The Deprecated xPression EAI Adapter the input XML documents, starting with a “dataroot” root node and including any number of “Transaction” elements inside the “dataroot” root node. • If the merge process fails, log a fatal error in the log file and return a negative System.exit() code. 6. Start xPression BatchRunner with a job named PolicyBatchJob and C:\xPressionAdapter \PolicyMergedXML\PolicyBatchJob.xml file as input. 7. When the xPression BatchRunner job completes successfully by returning a zero, one, or two exit status, the Adapter Batch Runner job will: • Remove the marker file. • Delete all files named C:\xPressionAdapter\PolicyTempXML\*.xml. • Leave the file C:\xPressionAdapter\PolicyMergedXML\ PolicyBatchJob.xml on the file system for auditing and debugging purposes. 8. Should the xPression BatchRunner job exit with a status of zero, one, or two, the Adapter Batch Runner job considers the run successful and exits with a zero status code. Otherwise, the Adapter Batch Runner job considers the run unsuccessful, does not perform any cleanup activities and exits with a status of negative one. The marker file must stay on the file system to show the process did not complete successfully and the batch process can be rerun from the start. Note: PolicyBatchJob must be a valid xPression Batch job already defined in xAdmin, it must have only one job step named PolicyBatchJob, and the merged XML file produced by the adapter must be appropriate as an XML data source override for that single job step. Adapter Configuration Information The xAdapter needs the following information as part of its configuration to work properly. Parameter Definition xPressionServerURL The URL the xAdapter uses to connect xPression Server through the xFramework Java interface (JFramework). The xPression Java Framework uses the IIOP/RMI protocol to connect to xPression, so this URL must point to the IIOP/RMI port exposed by the application server for the Java Virtual Machine that runs xPression Server. xPressionApplication-Name This is the name of the xAdapter application as listed in the AppList.xml xPression configuration file and accordingly assigned document category Access Rights for users and groups in xAdmin. To view categories, documents in a category, and submit document preview or publish requests, the userName given in the request must have access rights in the appropriate category for this application name. xPressionBatchRunner -ScriptDir The directory where the xPression Batch BatchRunner script is installed into, typically the location of the exploded xPression EAR file after it’s deployed to the application server. For each batch document type, a set of properties will be defined as described in XML File Export for Batch Execution, page 371. 374 The Deprecated xPression EAI Adapter Here’s an example: xPressionServerURL=iiop://localhost:2809 xPressionApplicationName=xPression Adapter PreviewPDFOutputProfile=PDF Return to Application xPressionBatchRunnerScriptDir=C:\\WebSphere\\AppServer\\installedApps\\ xPression.ear\\ Creating the Adapter Application After deploying the xAdapter, you must configure your environment. You do this by adding your application definition to AppList.xml and configuring it using xAdmin. In this chapter, we’ll show you how to get everything set up. Caution: We strongly urge you not to make changes to AppList.xml on a production xPression server until you’re sure your application works as intended in a test environment. Adding Your Application Definition To add the application definition to AppList.xml: 1. Locate AppList.xml on your xPression server and open it in a text editor. The default location is C:\xPression, but may differ on your server. 2. Type the application element between the tags. For example: Your application name must not contain apostrophes (’). 3. Type the access rights your application supports, including whether or not they’re hierarchical. For example: 4. Type the closing element at the bottom of your application definition. 5. Save AppList.xml and exit your text editor. When complete, your application definition should appear similar to the following. 375 The Deprecated xPression EAI Adapter Configuring Your Application with xAdmin Now that you’ve added your application definition to AppList.xml, it’s time to configure it with xAdmin. Associating Attribute Sets with Your Application Before you can configure categories, data sources, access rights, and workflow for your application, you must first associate one or more attribute sets with your application. To associate attributes with your application: 1. Open your browser and point to http://servername:portnum/xAdmin. Replace servername and portnum with your server name and port number. 2. Click Category Management, then Attribute Sets. 3. Click an attribute set that you want to associate with your application. You can also create your own attribute sets. For more information, see Administering the xPression Server. 4. Select your application from the list. 5. Click Next twice, then Save. The attribute set is now associated with your application. 376 The Deprecated xPression EAI Adapter Assigning Categories to Your Application To assign categories to your application: 1. In xAdmin, click Category Management, then Categories. 2. Select a category you want to assign to your application. 3. Select your application from the list. 4. Click Save. The category is now assigned to your application. 5. To assign more categories to your application, repeat this procedure. Assigning Data Sources to Your Application To assign data sources to your application: 1. Select a category you’ve already assigned to your application. 2. Click the Data Sources tab. 3. Select a data source group from the list. 4. Click Set Application. 5. Select your application from the drop-down list. 6. Select the data sources you want to assign to your application and click Add. 7. Select a default data source for your application from the drop-down list and click Save. 8. To assign additional data sources to your application, repeat this procedure. Setting Up Access Rights for Your Application To set up access rights for your application: 1. Click the Access Rights tab for a category you’ve assigned to your application. 2. Click View/change for your application, then click Add. 3. Select users from the list of available users and click Add. 4. Click Save. The users you selected for the category now have access to your application. 5. When the list of users reappears, select the access levels for each user and click Save. Configure Your Batch Scripts To configure xPression Batch Runner: 1. Create a directory to house your xPression Batch scripts. For example: C:\xPressionAdapter \batchScripts. 377 The Deprecated xPression EAI Adapter 2. Copy BatchRunner.bat from the xPression.ear installation directory to the new directory. The xPression.ear directory should be in the installedApps directory of your WebSphere application server. 3. Open BatchRunner.bat in a text editor and remove the pause at the end of the script. The last line of the script must contain a call to the java program. Immediately before the call to the java program, add a command to change the directory to your xPression.ear directory. Figure 15. The following image shows how to edit the batchrunner.bat file. 4. Copy AdapterBatchRunner.bat from the xPressionAdapter.ear installation directory to C:\xPressionAdapter\batchScripts. 5. Open AdapterBatchRunner.bat in a text editor and set the variables at the top of the script as needed. 6. Edit xPressionAdapter.properties file in your Adapter Home directory to set the xPressionBatchRunnerScriptDir parameter properly. For example, if you place your Batch Runner scripts in C:\xPressionAdapter \batchScripts, it would look like this: xPressionBatchRunnerScriptDir=C:\\xPressionAdapter\\batchScripts\\ 7. Configure your Batch Runner program to execute the C:\xPressionAdapter\batchScripts \AdapterBatchRunner script with a parameter of the batch document type you want executed. Note: AdapterBatchRunner supports all parameters except –f, -q, -j and –o. These parameters are not needed for AdapterBatchRunner because the files are generated by xAdapter by default. Verifying Your Installation Open a Web browser and type http:///xPressionAdapter/webServices /xPressionRequest.jws?wsdl to retrieve the WSDL of the Web service. Figure 16. The following image shows how to retrieve the WDSL. JMS For adapters which support JMS capabilities, you will be provided with a small testing application named xPressionAdapterTest.war. This application is provided as a convenience for testing and should never be deployed to a production environment. You are welcome to use your own messaging tools and programs to test the adapter. 378 The Deprecated xPression EAI Adapter Should you decide to use the test application we provide, deploy the xPressionAdapterTest.war file to the same application server as the adapter, with the Context Root xPressionAdapterTest. Follow the testing instructions below to the adapter’s support for Java Messaging Service requests: 1. Open your Web browser and type http://servername:port/xPressionAdapterTest. 2. Add some XML content and click Submit. Figure 17. The following image shows testing the JMS. 379 The Deprecated xPression EAI Adapter 3. The following page appears. Figure 18. The following image shows the WebSphere Embedded Messaging page. Messages are queued in JMS until the adapter has time and resources to process them. Because of this, results may not be available immediately. Refresh the xAdapter Test Utility periodically to look for new messages on the output queue, or examine the xPressionAdapter.log file to see if your request has been completed. XML Files Three XML files are used: • Publish Document, page 380 • Preview with PDF, page 381 • Post for Batch, page 382 Publish Document Publish Document Automatic Payment Letter jpc0999 JoonP123 PDF To File 1 Mary K. Jackson 9573 Main Street San Diego CA, 92108 1/1/2002 50 Wells Fargo 10000 John Doe 760-222-1574 English CA 2005-12-12 [email protected] 380 The Deprecated xPression EAI Adapter 1 1 1001 JMS Flexible Premium Variable Life 67-2301-810 $934.00 Monthly 4/8/2002 2 1 1002 JMS Portfolio Annuity 5573-135-4361 $360.00 Monthly 10/24/2002 Preview with PDF Preview PDF Automatic Payment Letter jpc0999 JoonP123 1 Mary K. Jackson 9573 Main Street San Diego CA, 92108 1/1/2002 50 Wells Fargo 10000 John Doe 760-222-1574 English CA 2005-12-12 [email protected] 381 The Deprecated xPression EAI Adapter 1 1 1001 JMS Flexible Premium Variable Life 67-2301-810 $934.00 Monthly 4/8/2002 2 1 1002 JMS Portfolio Annuity 5573-135-4361 $360.00 Monthly 10/24/2002 Post for Batch Post For Batch AutomaticPaymentLetter jpc0999 JoonP123 1 Mary K. Jackson 9573 Main Street San Diego CA, 92108 1/1/2002 50 Wells Fargo 10000 John Doe 760-222-1574 English CA 2005-12-12 382 The Deprecated xPression EAI Adapter [email protected] 1 1 1001 JMS Flexible Premium Variable Life 67-2301-810 $934.00 Monthly 4/8/2002 2 1 1002 JMS Portfolio Annuity 5573-135-4361 $360.00 Monthly 10/24/2002 Error Messages All errors and all important events will be logged to the Log4J logging framework, a standard practice for all Document Sciences Java software development. Errors are defined as any situation the code encounters which does not promote the proper or efficient processing of a request. Events are defined as any important task the code executes in the normal course of processing a request. The software will be designed so that each error or event logged in the code will have a unique identifier. Any time an error is detected, a utility class specifically designed to capture and log the error will be utilized. Any time an event is executed, a utility class specifically designed to start a timer, execute the event, stop the timer, and record not only the event identifier and details but also the time it took to execute the event. Both errors and events must be written to the Log4J log file in a manner that is easily parsed by a log file monitoring utility such as HP OVI. The xAdapter will utilize standard Log4J logging levels. Brief definitions of those levels are listed below. Level Definition FATAL The system encountered a critical error at this logging level, which affects the overall accuracy, integrity, reliability, or capability of most or all of the system. Someone should be paged to address the error as soon as possible. 383 The Deprecated xPression EAI Adapter Level Definition ERROR The system encountered an unexpected error at this logging level and the processing of a particular request will be affected. This error is not of a critical nature and typically can be recovered from automatically. Future requests into the system should be able to be processed without error. Someone should be e-mailed to resolve the error in the near future to increase the reliability of the system. WARN The system encountered an expected error situation. The system recovered from it but the fact that it happened should be recorded to see how frequently it happens. System performance may be affected because processing did not complete as expected. INFO An important event was executed in the system. This event is so important to system debugging and monitoring that it should always be logged to the log file every time it happens. DEBUG An event was executed in the system but the fact that this event happened is not important enough to always be written to the log file. When the system needs to be debugged, this event needs to be recorded to more quickly debug problem situations. The adapter uses a Java utility class called StopWatch to record each Time to Execute of Important Event. The log contains these elements: • Message ID • Event ID/Text • Time to execute • Severity (INFO, DEBUG) The adapter will report back to the user the following errors if they occur: • Missing XML data file in the folder where the data extract is expected. • Wrong file name format: This error is returned if the XML extract file name doesn’t have the prefix in the proper format. • Non-existing output profile passed to the adapter. • Target document could not be found. • Run-time errors due to misconfiguration of the adapter. 384 The Deprecated xPression EAI Adapter The adapter will use a Java utility class named “LoggedException” to record the error and necessary information to debug the error, including the following elements: • Message ID • Error ID • Error Message • Severity (Fatal, Error, Warn) • Stack Trace (the Java call stack generated inside the exception) In the batch processing mode, any errors in xPression Batch processing will be reported in the xPression.log file. Error Descriptions Error Number Error Description 1000 An error occurred while invoking webservices, find more info in server log. 3001 Receive message is null. 3002 Occur errors in JMS request process. 3003 Can’t find resource for bundle. 3005 Error request type of the customer data. 3006 An error occurred while getting customer data from XML. 3007 Can’t create adapter response statue message. 3008 An error occurred while getting request data. 3009 Can’t find object by JNDI. 3010 An error occurred while sending message. 3012 Can’t close object after sending message. 3013 The Value of requestType is not provided. 3014 The Value of RequestType {0} is not supported. 3015 Required parameter {0} was not provided in XML doc. 3016 An error occurred while pulling off message from input queue. 5000 The input parameter {0} of the API cannot be null. 5001 Can not connect to xPression Server, using serverURL= {0}, appNum= {1}. 5002 Access Denied. The user name= {0} or password specified is invalid for this server, serverURL= {1}. 5003 Parameters for documentType {0} were not correctly set in the configuration file. 5004 Non-existing output profile {0} passed to the adapter. 385 The Deprecated xPression EAI Adapter Error Number Error Description 5005 Category {0} not found. 5006 User can not access the specified category {0}. 5007 Target document {0} could not be found. 5008 No such kind of request type {0}. 5009 Failed to get categories for user {0}. 5010 Failed to get Letters list in the category {0}. 5011 Failed to get categories for User. 5012 User can not access the specified category. 5011 User {0} is not authorized to access document {1}. 5012 User {0} is failed to be authenticated, using serverURL= {1}, appNum= {2}. 5013 Failed to get assigned output profiles for document {0}. 10101 An error occurred while creating a EJB Agent {0}. No such bean or FrameWork service is not started. 10102 An error occurred while stopping a FrameWork service. 10201 An error occurred while initializing the assembler, appNam= {0}. 10202 An error occurred while overriding the data source {0}. 10203 An error occurred while assembling from BDT {0}. 10204 An error occurred while publishing instantiated document using output profile {0}. 10205 An error occurred while getting published instantiated document content using stream {0}. 10209 An error occurred while setting default the internal state of the assembly engine. 10210 An error occurred while removing the EJB. 10211 An error occurred while accessing a method {0} of EJB agent. 10301 An error occurred while processing XML. 10302 Invalid key error, {0}. 10303 An error occurred while parsing customer data by customer reader, data source name= {0}. 10304 Customer key table didn’t contain key name= {0}. 10401 An error occurred while reading or writing an I/O device. 10403 Error at Reading the input customer data. Might be caused by a malformed XML. 10404 Error at Reading the variables from the schema. 10500 The transformation Class {0} does not inherit the AbstractTransformationEngine. 386 The Deprecated xPression EAI Adapter Error Number Error Description 10501 Error at configuring the XSLT transfer for xsltFilePath {0}. 10502 Failed to do XSLT-tranformation, using XSLT file {0}. 10503 No xsltFilePath transformation is configured for the specified transformationName {0}. Event Descriptions Error Number Error Description 1001 xPression Server log on. 1002 xPression Server log off. 1011 Retrieving xPression Acl. 1012 Retrieving xPression BDT. 1013 Retrieving xPression Category. 1014 Retrieving xPression data source. 1015 Retrieving xPression Output Profile. 1016 Retrieving xPression Assembly Engine. 1021 Initializing Assembly Engine. 1022 Overriding data source. 1023 Assembling from BDT. 1024 Publishing instantiated document. 1025 Get published instantiated document data. 1026 Get schema by category. 1027 Get Effective Date by category name. 1031 Writing the customer data to the inputXmlFileDirectory. 1032 Running a JobDef. 3000 Send the return status message. 3001 JMS request process. 387 The Deprecated xPression EAI Adapter 388 Appendix A The Webtool Utility This section covers the a component of the deprecated Web Services model. With version 4.0, xPression introduces a new Web Service API that conforms to the WS-I Basic Profile. The old xFramework Web Service API, Java API, and xAdapter have been deprecated. Although these items will be supported for backward compatibility in the current version, EMC Document Sciences encourages you to use the new Web Service API as it offers better performance, greater flexibility, and better security. Webtool is a small component that enables you to encrypt and decrypt passwords that you pass to xPression as well as pack and unpack MSOHTML documents you retrieve from the content repository. Though it’s not technically part of the xFramework set of public APIs, it is a useful “helper” utility. Webtool is available for both Java (webtool.jar) and COM (webtool.dll) applications. In this appendix, we’ll describe all the methods of the utility component, including sample code in both Java and Visual Basic. You’ll find both webtool.jar and webtool.dll on the eBooks CD in \\xPression Framework\util. If you’re using the COM version, you’ll need to register it on your computer. Registering Webtool.dll Webtool.dll has a dependency on the uamerge.dll file supplied by EMC Document Sciences. When you register Webtool.dll, please ensure that uamerge.dll has been copied to: • /Drivers/ Or • %SystemRoot%/system32/ The Encryption Utility The encryption utility enables you to encrypt and decrypt user passwords you pass to xPression. When using the high- or low-level API, you’re not required to encrypt passwords, but we recommend it for security purposes. However, the Chapter 14, Deprecated xPression Web Services methods do require password encryption. This section includes these methods: encrypt and decrypt. 389 The Webtool Utility encrypt This method, which returns a byte array, enables you to encrypt a user password. Syntax Java: encryptedPwd[] = Encrypter.encrypt(passWord); Visual Basic: encryptedPwd() = WEBTOOLLib.encrypt(passWord) Parameters password : String An input parameter containing the user password you’re encrypting. Java Sample import com.docscience.xpression.webservice.util.encrypt.*; public class EncryptTest { public byte[] encryptPwd(String passWord) { byte returnVal[] = null; try { returnVal = Encrypter.encrypt(passWord); } catch { System.out.println("An error encrypting the password."); } return returnVal; } } Visual Basic Public Function encryptPwd(passWord As String)As Byte() Dim webTool As New WEBTOOLLib.EncryptUtil Dim encryptedPassword As Byte() 'encrypt password encryptedPassword = webTool.encrypt(passWord) 'set return value encryptPwd = encryptedPassword 'destroy object Set webTool = Nothing End Function 390 The Webtool Utility decrypt This method, which returns a string, enables you to decrypt a user password. Syntax Java: decryptedPwd = Encrypter.decrypt(encryptedPassWord); Visual Basic: decryptedPwd = WEBTOOLLib.decrypt(encryptedPassWord) Parameters encryptedPassWord : Byte[] An input parameter containing the encrypted user password you’re decrypting. Java import com.docscience.xpression.webservice.util.encrypt.*; public class EncryptTest { public String decryptPwd(byte[] encryptedPwd) { String returnVal = ""; try { returnVal = Encrypter.decrypt(encryptedPwd); } catch { System.out.println("An error decrypting the password."); } return returnVal; } } Visual Basic Public Function decryptPwd(encryptedPassword() As Byte) As String Dim webTool As New WEBTOOLLib.EncryptUtil Dim decryptedPassword As String 'decrypt password decryptedPassword = webTool.decrypt(encryptedPassword) 'set return value decryptPwd = decryptedPassword 391 The Webtool Utility 'destroy object Set webTool = Nothing End Function The Pack Utility The pack utility enables you to pack and unpack MSOHTML documents retrieved from the content repository. By default, xPression content items are stored in compressed, or packed, MSOHTML format in the content repository. If you want to enable your users to edit xPression documents, you need to first unpack the content, display it in an editor, and pack it again when re-saving the edited content to the content repository. This section includes these methods: pack and unpack. pack Java: MSOPacker.pack(folderName, mainHTMLFileName, packedMSOHTMLFileName); Visual Basic: WEBTOOLLib.pack(folderName, mainHTMLFileName, packedMSOHTMLFileName) Syntax This method compresses, or packs, MSOHTML content, which then enables you to re-save the content to the content repository. Parameters folderName : String An input parameter containing the fully qualified path for the content you’re packing. If you pass an empty string, the pack method assumes you’re passing the path in the two subsequent parameters. mainHTMLFileName : String An input parameter containing the unpacked file name for the content you’re packing. packedMSOHTMLFileName : String An input parameter containing the packed file name. Java import com.docscience.xpression.webservice.util.pack.*; public class PackTest { public void pack(String fileName) { 392 The Webtool Utility String packedFile = fileName + ".pkd"; String unpackedFile = fileName + ".htm"; try { //pack document MSOPacker.pack("",unpackedFile,packedfile); } catch { System.out.println("An error occurred while packing the content."); } } } Visual Basic Public Sub pack(fileName As String) Dim webTool As New WEBTOOLLib.PackUtil Dim packedFile As String Dim unpackedFile As String 'set file names packedFile = App.Path & "\packed\" & Left$(fileName, Len(fileName) - 3) & "pkd" sUnpackedFile = App.Path & "\unpacked\" & fileName 'pack file webTool.Pack "", unpackedFile, packedFile 'destroy object Set webTool = Nothing End Sub unpack This method decompresses, or unpacks, MSOHTML content, which then enables you to display it in an editor like Microsoft Word. Syntax Java: MSOPacker.unpack(folderName, packedMSOHTMLFileName, mainHTMLFileName); Visual Basic: WEBTOOLLib.unpack(folderName, packedMSOHTMLFileName, mainHTMLFileName) 393 The Webtool Utility Parameters folderName : String An input parameter containing the fully qualified path for the content you’re unpacking. If you pass an empty string, the unpack method assumes you’re passing the path in the two subsequent parameters. packedMSOHTMLFileName : String An input parameter containing the packed file name for the content you’re unpacking. mainHTMLFileName : String An input parameter containing the unpacked file name you’re unpacking. Java import com.docscience.xpression.webservice.util.pack.*; public class PackTest { public void unpack(String fileName) { String packedFile = fileName + ".pkd"; String unpackedFile = fileName + ".htm"; try { //pack document MSOPacker.unpack("",packedFile,unpackedfile); } catch { System.out.println("An error occurred while unpacking the content."); } } } Visual Basic Public Sub unpack(fileName As String) Dim webTool As New WEBTOOLLib.PackUtil Dim packedFile As String Dim unpackedFile As String 'set file names packedFile = App.Path & "\packed\" & Left$(fileName, Len(fileName) - 3) & "pkd" sUnpackedFile = App.Path & "\unpacked\" & fileName 'unpack file webTool.Unpack "", packedFile, unpackedFile 'destroy object Set webTool = Nothing 394 The Webtool Utility End Sub 395 The Webtool Utility 396 Appendix B The AppList DTD In this appendix, we’ll define the applist DTD. First, let’s take a minute to discuss DTDs in general. DTDs define the rules and relationships between elements in an XML document. They also validate XML documents to ensure they adhere to those rules. It’s important to note, however, that DTDs won’t tell you whether an XML document is well formed. There are other tools to determine, for example, that your tag names are correct or that each beginning tag has a corresponding ending tag. Think of DTDs as a strict teacher marking you down for misspelled words or incorrect grammar. AppList.xml is a document that stores information about xPression applications. Specifically, it provides the elements that make up an application’s usage and behavior, including the application name, access rights, required attributes (if any), and workflow information. xAdmin uses AppList.xml to configure categories, attribute sets, and data sources for use with xPression applications. For example, you can assign test data sources to xDesign and production data sources to xResponse. Caution: The AppList.xml document that ships with xPression contains information about applications that are part of the standard xPression suite. Therefore, we urge you to exercise caution when adding your own applications. EMC Document Sciences only provides information about AppList.xml in the xFramework Developer’s Guide, it does not supply programs that write to AppList.xml. The Complete AppList.dtd Now let’s look at AppList.dtd. 397 The AppList DTD The AppList and Application Elements AppList is the top level element in AppList.xml. It contains the child element Application. The plus sign (+) after Application indicates that there must be at least one child Application element of AppList. The definition of the Application element comes next. Notice that it contains three child elements: WorkFlow, AccessRights, and RequiredAttributes. The question mark (?) indicates that the child element may appear once or not at all. The asterisk (*) means that a child element can appear any number of times or not at all. The attributes for the Application element come last, including the data type and modifier. The name attribute’s data type is CDATA, or character data, and its modifier is #REQUIRED, which means that the attribute is required. 398 The AppList DTD Let’s look at an XML example to illustrate: Notice that in this example, we omitted both the WorkFlow and RequiredAttributes elements. This is a perfectly valid scenario. The WorkFlow Element Here we’re defining WorkFlow as an empty element, which means that no data will appear between the begin and end tags. We then define the list of attributes for the WorkFlow element. The four attributes have the same data type and all are required. Here we added two more access rights and a workflow. This means the xPression Test user must have an access level of Write to initiate workflow, whose status, once initiated, is SUBMITTED. To promote the status to APPROVED, the user must have an access right of Approve. We’ve also defined an empty element Access, whose single attribute is name. We’ve used the same data type and modifier as in the other element attributes. The AccessRights Element The AccessRights element includes the Access element followed by a plus sign. You’ll recall that this means Access is a child element of AccessRights and that one or more Access elements must be included. The AccessRights element has a single attribute: heirarchical. This attribute determines whether access rights are hierarchical in nature for the application. For example, in xDesign, a user with 399 The AppList DTD Write authority is a level above a user with Read authority. Additionally, users with higher-level access rights automatically have the lower-level access rights. Therefore, an xDesign user with Approve authority also has Write and Read authority. Access rights that aren’t hierarchical operate independently from one another. xResponse is an example of an application without hierarchical access rights. The RequiredAttributes and Attr Elements Now let’s look at the final elements in the DTD. Most of the syntax should look familiar to you by now, but there are a few differences. The condition attribute of the RequiredAttributes element contains the #IMPLIED modifier. This means that the application will determine the value of the attribute. The Attr element has multiple required attributes, but some of them have enumerated data types, which means that one of the values in parentheses must be used. Let’s examine all the attributes to gain a better understanding of their purpose. Attribute Definition name The name of the xPression attribute. type The data type of the attribute. min The minimum value in a range. max The maximum value in a range. 400 The AppList DTD Attribute Definition ValidValueExist Determines whether the attribute has valid values: 0 = no valid values exist 1 = valid values do exist Default_Value The default attribute value. isMappable Determines whether the attribute can be mapped to a column in a customer data source table: 0 = the attribute cannot be mapped 1 = the attribute is mappable stringLength The length of an attribute whose type is string. RangeExist Determines whether a range of values exist for the attribute: 0 = no range exists 1 = a range does exist DefaultExist Determines whether a default value exists for the attribute: 0 = no default value exists 1 = a default value does exist multisingle Determines whether the attribute is single value or multiple value: multi = multiple value attribute single = single value attribute validValue The valid values for the attribute. A Complete AppList.xml Example Let’s now look at a complete application definition in XML that adheres to the rules in the DTD. What’s different in this example? Notice that we provide all the attributes that must be included in the application definition if we want to support approval. 402