EMC DocumentSciences xPression xFramework · •...

EMC® Document Sciences®

xPression® xFrameworkVersion 4.5 SP1

Development Guide

EMC CorporationCorporate Headquarters

Hopkinton, MA 01748-91031-508-435-1000www.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 changewithout notice.

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

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

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

Documentation Feedback

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

Table of Contents

Revision History .................................................................................................................. 21

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

Chapter 2 About xFramework and the xPression DevKit API ...................................... 25What Has Changed? ......................................................................................... 25Authentication ................................................................................................ 26About the requestContext Parameter ............................................................. 26Using requestContext with Documentum-Based Documents ....................... 27requestContext Examples .......................................................................... 27

Setting Up Your Application.............................................................................. 28Adding Your Application Definition .............................................................. 28Configuring Your Application with xAdmin................................................... 30Associating Attribute Sets with Your Application ....................................... 30Assigning Data Sources to Your Application .............................................. 30Setting Up Access Rights for Your Application ........................................... 31Configuring Workflow for Your Application............................................... 31

IQuickDoc Configuration .................................................................................. 31Error Messages................................................................................................. 32The CompuSet Bridge ....................................................................................... 32xPressionHome ................................................................................................ 32

Chapter 3 The IQuickDoc Web Service ........................................................................ 33xPresso for Word Documents in Workflow Enabled Categories............................ 34The categoriesForUser Method .......................................................................... 34Syntax ......................................................................................................... 34Parameters ................................................................................................... 34

The documentsForCategory Method.................................................................. 35Syntax ......................................................................................................... 35Parameters ................................................................................................... 35

The descriptionForDocument Method................................................................ 35Syntax ......................................................................................................... 36Parameters ................................................................................................... 36

The thumbnailForDocument Method ................................................................. 37Syntax ......................................................................................................... 37Parameters ................................................................................................... 37

The designToolForDocument Method ................................................................ 38Syntax ......................................................................................................... 38Parameters ................................................................................................... 38

The outputProfilesForDocument Method ........................................................... 39

3

Table of Contents

Syntax ......................................................................................................... 39Parameters ................................................................................................... 39

The versionsForDocumentWithWorkflowStatus Method ..................................... 40Syntax ......................................................................................................... 40Parameters ................................................................................................... 41

The publishDocument Method .......................................................................... 42Syntax ......................................................................................................... 42Parameters ................................................................................................... 43Sample......................................................................................................... 44

The publishDocuments Method ........................................................................ 44Syntax ......................................................................................................... 45Parameters ................................................................................................... 45Sample......................................................................................................... 46

The publishAndReturnDocument Method ......................................................... 47Syntax ......................................................................................................... 48Parameters ................................................................................................... 48

The publishAndReturnDocumentMultipleStream Method .................................. 49Syntax ......................................................................................................... 50Parameters ................................................................................................... 50

The getTemplateFields Method.......................................................................... 51Syntax ......................................................................................................... 51Parameters ................................................................................................... 51Examples ..................................................................................................... 52With NULL customerData Value ............................................................... 53With Supplied customerData..................................................................... 53

The getDataCollectionTemplate Method ............................................................ 53Syntax ......................................................................................................... 54Parameters ................................................................................................... 54Examples ..................................................................................................... 55With NULL customerData Value ............................................................... 55With Supplied customerData..................................................................... 56

Chapter 4 Workflow Integration Web Services ............................................................. 57WorkflowDocumentBrowsingService................................................................. 57listWorkFlowAvailableCategories .................................................................. 57Syntax ..................................................................................................... 57Parameters ............................................................................................... 58

listWorkFlowAvailableDocuments ................................................................. 58Syntax ..................................................................................................... 58Parameters ............................................................................................... 58

getDocumentType ........................................................................................ 59Syntax ..................................................................................................... 59Parameters ............................................................................................... 60

getDocumentVersions ................................................................................... 60Syntax ..................................................................................................... 60Parameters ............................................................................................... 60

DataBrowsingService........................................................................................ 61getDefaultDS................................................................................................ 61Syntax ..................................................................................................... 61Parameters ............................................................................................... 62

listKeys........................................................................................................ 63Syntax ..................................................................................................... 63Parameters ............................................................................................... 63

getDataRecordXML ...................................................................................... 63Syntax ..................................................................................................... 64

4

Table of Contents

Parameters ............................................................................................... 65WorkflowService .............................................................................................. 65listLifeCycles................................................................................................ 65Syntax ..................................................................................................... 66Parameters ............................................................................................... 66

statusInLifecycle........................................................................................... 66Syntax ..................................................................................................... 66Parameters ............................................................................................... 66

previewPDF ................................................................................................. 67Syntax ..................................................................................................... 67Parameters ............................................................................................... 67

previewHTML ............................................................................................. 68Syntax ..................................................................................................... 68Parameters ............................................................................................... 68

workflowBegins ........................................................................................... 69Syntax ..................................................................................................... 69Parameters ............................................................................................... 69

setLifecycleStatus ......................................................................................... 69Syntax ..................................................................................................... 69Parameters ............................................................................................... 70

workflowEnds.............................................................................................. 71Syntax ..................................................................................................... 71Parameters ............................................................................................... 71

Chapter 5 xPression DevKit Web Services .................................................................. 73The IDocumentItem Web Service ....................................................................... 73searchDocumentItem .................................................................................... 74Syntax ..................................................................................................... 74Parameters ............................................................................................... 74Sample..................................................................................................... 76

The createDocumentItem Method.................................................................. 77Syntax ..................................................................................................... 77Parameters ............................................................................................... 78

The getDocumentItemInfo Method ................................................................ 78Syntax ..................................................................................................... 80Parameters ............................................................................................... 80Examples ................................................................................................. 81

The publishAndReturnDocumentItem Method............................................... 82Syntax ..................................................................................................... 83Parameters ............................................................................................... 83

The publishAndReturnDocumentMultipleStream Method .............................. 84Syntax ..................................................................................................... 85Parameters ............................................................................................... 85

The documentItemsAssignedToUser Method ................................................. 85Syntax ..................................................................................................... 86Parameters ............................................................................................... 87

The reassignDocumentItemToUser Method.................................................... 87Syntax ..................................................................................................... 87Parameters ............................................................................................... 87

The updatePrimaryVariables Method ............................................................ 88Syntax ..................................................................................................... 88Parameters ............................................................................................... 88

The copyDocumentItem Method ................................................................... 89Syntax ..................................................................................................... 89Parameters ............................................................................................... 90

The addExternalContentByLink Method ........................................................ 90Syntax ..................................................................................................... 90Parameters ............................................................................................... 90

5

Table of Contents

addExternalContentByStream ....................................................................... 92Syntax ..................................................................................................... 92Parameters ............................................................................................... 92

The reorderExternalContent Method ............................................................. 93Syntax ..................................................................................................... 93Parameters ............................................................................................... 93

The addAnnotation Method .......................................................................... 94Syntax ..................................................................................................... 94Parameters ............................................................................................... 94

The deleteExternalContent Method................................................................ 95Syntax ..................................................................................................... 95Parameters ............................................................................................... 95

The createAuthenticationToken Method......................................................... 96Syntax ..................................................................................................... 96Parameters ............................................................................................... 96

The complete DocumentItem Method ............................................................ 96Syntax ..................................................................................................... 97Parameters ............................................................................................... 97

The deleteDocumentItem Method.................................................................. 97Syntax ..................................................................................................... 97Parameters ............................................................................................... 98

The publishRevisionUnits Method................................................................. 98Syntax ..................................................................................................... 98Parameters ............................................................................................... 98

The setCarryForwardDocumentItem Method ................................................. 99Syntax ..................................................................................................... 99Parameters ............................................................................................... 99

The clearCarryForwardDocumentItem Method ............................................ 100Syntax ................................................................................................... 100Parameters ............................................................................................. 100

The updateRUVariables Method .................................................................. 100Syntax ................................................................................................... 101Parameters ............................................................................................. 101

The submitDocumentItem Method .............................................................. 101Syntax ................................................................................................... 101Parameters ............................................................................................. 102

The approveDocumentItem Method ............................................................ 102Syntax ................................................................................................... 102Parameters ............................................................................................. 102

The rejectDocumentItem Method................................................................. 103Syntax ................................................................................................... 103Parameters ............................................................................................. 103

Calling the xEditor StartUp Application ........................................................... 104Syntax ....................................................................................................... 104Parameters ................................................................................................. 104Samples ..................................................................................................... 105Starting xEditor the First Time..................................................................... 105

Chapter 6 xCatalog Web Service ............................................................................... 107The getCatalogInfo Method............................................................................. 107Syntax ....................................................................................................... 107Parameters ................................................................................................. 107Sample Returned Document........................................................................ 108

The searchForDocuments Method ................................................................... 108Simple Search Criteria ................................................................................ 109Advanced Search Criteria............................................................................ 109Syntax ....................................................................................................... 111Parameters ................................................................................................. 111

6

Table of Contents

The getDocumentInfo Method......................................................................... 112Syntax ....................................................................................................... 113Parameters ................................................................................................. 113

Chapter 7 Output Statistics Reporting ...................................................................... 115What Types of Output are Counted? ................................................................ 115Output Statistics Report Details ....................................................................... 116Summary Report Content ........................................................................... 117Summary and Detail Report Content ........................................................... 118Batch Details .......................................................................................... 118Transaction Details ................................................................................. 119API and Web Services Details .................................................................. 119Sample Summary and Details Report....................................................... 120

Output Statistics Reporting Web Services ......................................................... 121getSummaryPublishingReport..................................................................... 121Syntax ................................................................................................... 121Parameters ............................................................................................. 122

getDetailedPublishingReport ...................................................................... 122Syntax ................................................................................................... 122Parameters ............................................................................................. 123

getCompressedSummaryPublishingReport .................................................. 123Syntax ................................................................................................... 123Parameters ............................................................................................. 123

getCompressedDetailedPublishingReport .................................................... 125Syntax ................................................................................................... 125Parameters ............................................................................................. 125

clearDetailPublishingReport........................................................................ 126Syntax ................................................................................................... 126Parameters ............................................................................................. 126

Chapter 8 xPressForms Web Services for Reporting ................................................ 127Get Report Method ......................................................................................... 127Syntax ....................................................................................................... 127Parameters ................................................................................................. 127

Get Report For Fields Method ......................................................................... 129Syntax ....................................................................................................... 129Parameters ................................................................................................. 129

Search for Forms Method ................................................................................ 130Simple Search Criteria ................................................................................ 130Advanced Search Criteria............................................................................ 131Syntax ....................................................................................................... 132Parameters ................................................................................................. 132

Search for Forms Customized View Method..................................................... 132Simple Search Criteria ................................................................................ 133Advanced Search Criteria............................................................................ 134Syntax ....................................................................................................... 134Parameters ................................................................................................. 135

Get Search Field List Method........................................................................... 135Syntax ....................................................................................................... 135Parameters ................................................................................................. 135Return Value .............................................................................................. 135

Deprecated xPressForms Web Services............................................................. 136

Chapter 9 xPression RESTful Services for Batch ...................................................... 137RESTful HTTP Body Structure......................................................................... 137

7

Table of Contents

The General.security Element .......................................................................... 139Authorization............................................................................................. 139

The Job.start.xml and Job.start Elements........................................................... 140The Job Element ......................................................................................... 140The xPressionPublishJob Element ................................................................ 140The JobOption Element ............................................................................... 141

The Job.status Element.................................................................................... 141Syntax ....................................................................................................... 141Returned Information ................................................................................. 142Common Data ....................................................................................... 142Statistics with Details Data ...................................................................... 143Statistics with Errors Data ....................................................................... 144

Sample Responses for Job.Status.................................................................. 144Completed Job with “Statistics” Reporting Level ...................................... 144Completed Job with “Statistics with Details” Reporting Level.................... 145Stopped Job with “Statistics with Errors” Reporting Level......................... 146Job That is Not Started ............................................................................ 147Job That is Still Running.......................................................................... 147

The Job Queue All Element ............................................................................. 147Syntax ....................................................................................................... 147Returned Information ................................................................................. 148

Return a List of all Job Names ......................................................................... 149Return a List of all Queued Jobs....................................................................... 150Return a List of all Running Jobs...................................................................... 150Return the Status of a Particular Job ................................................................. 151Start a Batch Job with an Existing Job Definition ............................................... 152Start a Batch Job with a Job Definition XML File................................................ 153Configuring xPression for RESTful Batch Services ............................................ 154Enable xPression for Concurrent Batch Processing ........................................ 154Configure Servers for RESTful Service Batch Processing................................ 155Service Notification .................................................................................... 155

Chapter 10 xDesign Online Editor Web Services ......................................................... 159Web Services .................................................................................................. 159Authentication ........................................................................................... 160About the requestContext Parameter ....................................................... 160requestContext Examples .................................................................... 160

Access Rights for Document Item Web Services ............................................ 161createDocumentItem................................................................................... 162Syntax ................................................................................................... 162Parameters ............................................................................................. 162

createAuthenticationToken.......................................................................... 163Syntax ................................................................................................... 163Parameters ............................................................................................. 163

publishAndReturnDocumentItem ............................................................... 164Syntax ................................................................................................... 164Parameters ............................................................................................. 164

deleteDocumentItem .................................................................................. 165Syntax ................................................................................................... 165Parameters ............................................................................................. 165Example................................................................................................. 165

reassignDocumentItemToUser..................................................................... 166Syntax ................................................................................................... 166Parameters ............................................................................................. 166

documentItemsAssignedToUser .................................................................. 167

8

Table of Contents

Syntax ................................................................................................... 167Parameters ............................................................................................. 167

searchDocumentItems ................................................................................ 167Syntax ................................................................................................... 168Parameters ............................................................................................. 168Example................................................................................................. 169

unlockDocumentItem ................................................................................. 170Syntax ................................................................................................... 170Parameters ............................................................................................. 171

addAnnotation ........................................................................................... 171Syntax ................................................................................................... 171Parameters ............................................................................................. 171Example................................................................................................. 172

getDocumentItemInfo................................................................................. 172Syntax ................................................................................................... 173Parameters ............................................................................................. 173Example................................................................................................. 174

openDocumentItem .................................................................................... 175Syntax ................................................................................................... 176Parameters ............................................................................................. 176Example................................................................................................. 176

submitDocumentItem ................................................................................. 177Syntax ................................................................................................... 178Parameters ............................................................................................. 178

rejectDocumentItem ................................................................................... 178Syntax ................................................................................................... 178Parameters ............................................................................................. 178

approveDocumentItem ............................................................................... 179Syntax ................................................................................................... 180Parameters ............................................................................................. 180

documentItemsAssignedToUserReturnInfo .................................................. 180Syntax ................................................................................................... 181Parameters ............................................................................................. 181

searchDocumentItemReturnInfo.................................................................. 182Syntax ................................................................................................... 182Parameters ............................................................................................. 182

copyDocumentItem .................................................................................... 184Syntax ................................................................................................... 184Parameters ............................................................................................. 184

addExternalContentByStream ..................................................................... 185Syntax ................................................................................................... 186Parameters ............................................................................................. 186

addExternalContentByLink ......................................................................... 186Syntax ................................................................................................... 187Parameters ............................................................................................. 187

deleteExternalContent ................................................................................ 188Syntax ................................................................................................... 188Parameters ............................................................................................. 188

Clean Up xDesign Online Editor Temp Folders............................................. 188

Chapter 11 The xPression DevKit xEditor Component ................................................ 191Before You Begin ............................................................................................ 191Internet Explorer Settings............................................................................ 191User Configuration ..................................................................................... 192

How xEditor Handles Updates ........................................................................ 192Running xEditor the First Time ....................................................................... 192Installing xEditor........................................................................................ 193Pushing the xEditor Installation from the Server ........................................... 193

9

Table of Contents

Opening xEditor After “Failed to start editor. Exception fromHRESULT: 0x8004063B” ................................................................................. 194The xEditor Interface ...................................................................................... 194The Document Actions Pane........................................................................ 194The xEditor Toolbar .................................................................................... 195The Table of Contents Section ...................................................................... 196TOC Icons .............................................................................................. 197

The Information Panel ................................................................................ 198The Command Bar...................................................................................... 199The xEditor Menu....................................................................................... 199

Deleting and Undeleting Revision Units........................................................... 199Optional Content............................................................................................ 200Localization ................................................................................................... 200xEditor Functions ........................................................................................... 200Cache Management ........................................................................................ 201The Log ......................................................................................................... 201Finding Existing Content ................................................................................ 202xEditor’s Find Utility .................................................................................. 202Microsoft Word Find and Replace................................................................ 203

Adding New Content ..................................................................................... 204Using xEditor ................................................................................................. 204Closing xEditor .......................................................................................... 205Track Changes............................................................................................ 205Local Files .................................................................................................. 205Microsoft Word Features and Functions ....................................................... 206Hidden Table Borders ............................................................................. 208Editing Actions in xEditor ....................................................................... 208

Form Fields ................................................................................................ 208Protection .................................................................................................. 210Read Only Protection.................................................................................. 211

Configuring Microsoft Word Ribbons .............................................................. 212Language Specific Configuration Files ......................................................... 213Element Properties ..................................................................................... 213Excluded, Repurposed, and Unsupported Commands .................................. 214

Opening a Work Item in xEditor ...................................................................... 218Table and Paragraph Merge......................................................................... 218Content Separators ..................................................................................... 218Merged Paragraphs and Content Separators............................................. 218

Variables .................................................................................................... 218Variable Scope ........................................................................................ 220Selecting Variables .................................................................................. 220Editing Variables .................................................................................... 224Copy and Paste ...................................................................................... 226Drag and Drop ....................................................................................... 226Variable Formats .................................................................................... 226Protection and Variables ......................................................................... 227Variable Navigator ................................................................................. 227

Subtotals, Index Headings, and Table Headings and Footers ......................... 228Variables in Optional Content...................................................................... 228Purging WIP Work Items ............................................................................ 228

Carry Forward ............................................................................................... 228Opening Carry Forward.............................................................................. 229Review Helper ........................................................................................... 229The Carry Forward Review Pane ................................................................. 230

10

Table of Contents

The Carry Forward Review Toolbar ......................................................... 230The Document Structure Tree .................................................................. 231The Information Panel ............................................................................ 232Editing Content in Carry Forward ........................................................... 234Working with Variables in Carry Forward ................................................ 235Headers and Footers in Carry Forward ................................................... 236

Revision Numbers ...................................................................................... 236Revision Numbering Outside Carry Forward ........................................... 236Revision Numbering in Carry Forward .................................................... 237

The Editor Log ........................................................................................... 237The Auto Carry Forward Log ...................................................................... 237

Chapter 12 The xCatalog Component .......................................................................... 239Access Rights ................................................................................................. 239The xCatalog Interface .................................................................................... 240Menu Bar ................................................................................................... 240The File Menu ........................................................................................ 240The Edit Menu ....................................................................................... 241The Help Menu ...................................................................................... 241

Browse and Search Pane.............................................................................. 242Browse Pane........................................................................................... 242Adding a Tag or Folder ....................................................................... 242Renaming a Tag or Folder ................................................................... 243Deleting a Tag or Folder ...................................................................... 243Copying and Pasting a Tag or Folder.................................................... 243Marking a Folder as Required ............................................................. 244

Search Pane ............................................................................................ 244Advanced Search................................................................................ 246Example......................................................................................... 247

Staging Area Pane .................................................................................. 247Document List............................................................................................ 248Document Detail Area ................................................................................ 248Information Tab...................................................................................... 249Tags Tab................................................................................................. 249Notes Tab............................................................................................... 249Custom Fields Tab .................................................................................. 250Properties Tab ........................................................................................ 250

Using xCatalog............................................................................................... 251Login ......................................................................................................... 251Importing and Exporting Documents........................................................... 251Importing Documents............................................................................. 252Troubleshooting - Importing Large Files............................................... 252

Exporting Documents ............................................................................. 253Working with Documents ........................................................................... 253Adding Tags to Documents ..................................................................... 253Changing Document Status ..................................................................... 254Deleting Documents ............................................................................... 254

Managing Custom Fields ............................................................................ 255Adding Fields ........................................................................................ 255Renaming a Field.................................................................................... 256Defining or Changing a Field’s Default Value ........................................... 256Deleting a Custom Field.......................................................................... 256

Creating Document Reports ........................................................................ 257Logging Out............................................................................................... 258

Chapter 13 System Architecture .................................................................................. 259xPression Server Components ......................................................................... 259

11

Table of Contents

The xPression Assembly Engine .................................................................. 260The xPression Publishers Engine ................................................................. 260The xPublish Engine ............................................................................... 261

Distribution Controller Engine .................................................................... 262Execution Architecture............................................................................ 262Distribution Types .................................................................................. 262

xPression Batch Engine ............................................................................... 262xFramework Components ............................................................................... 263WebServices API ........................................................................................ 263Java API..................................................................................................... 263EAI Adapter............................................................................................... 263xPression Web Services ............................................................................... 263xPression Java API...................................................................................... 264

xPression Integration Strategies ....................................................................... 264Real-Time Interaction.................................................................................. 265Real-Time Interaction - APIs.................................................................... 265Real-Time Interaction - Portals................................................................. 265

Near-Time Interaction................................................................................. 265Batch Interaction ........................................................................................ 266xPression Integration Decision Tree ............................................................. 266

Chapter 14 Deprecated xPression Web Services ......................................................... 267Before You Begin ............................................................................................ 267Initial Questions ......................................................................................... 268Adding Your Application Definition ............................................................ 268Configuring Your Application with xAdmin................................................. 269Associating Attribute Sets with Your Application ..................................... 269Assigning Data Sources to Your Application ............................................ 270Setting Up Access Rights for Your Application ......................................... 270Configuring Workflow for Your Application............................................. 270

Authentication and Access Control .............................................................. 271Authentication ....................................................................................... 271Access Control ....................................................................................... 271

Logging ..................................................................................................... 271Licensing ................................................................................................... 271

Using WebServices with xPresso Packages ....................................................... 271Web Services Processing Diagram.................................................................... 272The Document Requester Web Service ............................................................. 273Requesting a Document by Customer Key.................................................... 273Syntax ................................................................................................... 273Parameters ............................................................................................. 274

Requesting a Document by XML Customer Data .......................................... 274Syntax ................................................................................................... 275Parameters ............................................................................................. 275

Request Document by Output Profile........................................................... 276Syntax ................................................................................................... 277Parameters ............................................................................................. 277

The Document Composer Web Service............................................................. 277The Compose Document Method ................................................................ 278Syntax ................................................................................................... 278Parameters ............................................................................................. 278

The xPression Request Web Service ................................................................. 278The Publish Document Method ................................................................... 279Syntax ................................................................................................... 279Parameters ............................................................................................. 280

The Preview HTML Method........................................................................ 280

12

Table of Contents


The Preview PDF Method ........................................................................... 281When Used with xPublish Documents ..................................................... 281Username and Password Filter ................................................................ 281Syntax ................................................................................................... 282Parameters ............................................................................................. 282

The View Categories for User Method.......................................................... 282Syntax ................................................................................................... 282Parameters ............................................................................................. 282

The View Documents in Category Method ................................................... 283Syntax ................................................................................................... 283Parameters ............................................................................................. 283

The View Output Profiles for Document Method .......................................... 283Syntax ................................................................................................... 284Parameters ............................................................................................. 285

The Get BDT Method .................................................................................. 285Syntax ................................................................................................... 285Parameters ............................................................................................. 285

The Get Assembled Document Method ........................................................ 286Syntax ................................................................................................... 286Parameters ............................................................................................. 286

The Publish MSOHTML Document Method ................................................. 286Syntax ................................................................................................... 286Parameters ............................................................................................. 287

The Publish And Return Document Method................................................. 287Syntax ................................................................................................... 287Parameters ............................................................................................. 288

The xResponse Web Service............................................................................. 288The Assign Document to User Method......................................................... 288Syntax ................................................................................................... 289Parameters ............................................................................................. 289

The Retrieve Work In Progress IDs Assigned to a User Method ..................... 290Syntax ................................................................................................... 290Parameters ............................................................................................. 290

The Reassign Work Item Method ................................................................. 290Syntax ................................................................................................... 291Parameters ............................................................................................. 291

The Create Work Item Method .................................................................... 291Syntax ................................................................................................... 291Parameters ............................................................................................. 292

Publish and Return Document .................................................................... 292Syntax ................................................................................................... 292Parameters ............................................................................................. 292

The Revise Request Web Service ...................................................................... 293The Assign Document To User Method ........................................................ 293Syntax ................................................................................................... 293Parameters ............................................................................................. 293

The Retrieve Work In Progress IDs Assigned to a User Method ..................... 294Syntax ................................................................................................... 294Parameters ............................................................................................. 294

The Reassign Work Item Method ................................................................. 295Syntax ................................................................................................... 295Parameters ............................................................................................. 295

The Query Work ItemStatus Method............................................................ 296Syntax ................................................................................................... 296Parameters ............................................................................................. 296

The Complete Item Method......................................................................... 296

13

Table of Contents


The Preview Work Item In PDF Method....................................................... 297Syntax ................................................................................................... 297Parameters ............................................................................................. 297

The Update Work Item Primary Data Method .............................................. 297Syntax ................................................................................................... 297Parameters ............................................................................................. 298Returns .................................................................................................. 298Notes ..................................................................................................... 298

The Delete Work Item Method..................................................................... 298Syntax ................................................................................................... 299Parameters ............................................................................................. 299Returns .................................................................................................. 299

The Publish and Return Work Item Method ................................................. 299Syntax ................................................................................................... 299Parameters ............................................................................................. 299Returns .................................................................................................. 300

Errors ............................................................................................................ 300

Chapter 15 The Deprecated xPression Java API ......................................................... 301Writing an XPression Facade Java Class ........................................................... 301Objectives .................................................................................................. 301Dependencies............................................................................................. 302Creating a Simple Properties File ................................................................. 302Connecting to xPression.............................................................................. 302Retrieving Categories.................................................................................. 304Retrieving Document Names....................................................................... 305Retrieving a Document ............................................................................... 305

Writing a Quote Generator Application............................................................ 306Objectives .................................................................................................. 306Dependencies............................................................................................. 307Initial Setup ............................................................................................... 307Creating Standard Header and Footer Pages ................................................ 308Presenting a List of Categories..................................................................... 309Presenting a List of Documents ................................................................... 311Presenting Input Fields ............................................................................... 313Generating a PDF Quote ............................................................................. 315Summary ................................................................................................... 320

Deploying an xPression Application ................................................................ 320J2EE Application Assembly ......................................................................... 320J2EE Web Application Overview ................................................................. 321J2EE Enterprise JavaBeans Overview ........................................................... 321J2EE Utility Classes Overview ..................................................................... 321Web Application Archive Construction ........................................................ 322

Command Reference ...................................................................................... 323Method Name ............................................................................................ 323Syntax ................................................................................................... 323Parameters ............................................................................................. 323Sample................................................................................................... 324

The XPressionFacade Class ............................................................................. 325getAppName ............................................................................................. 325Syntax ................................................................................................... 325Sample................................................................................................... 325

getBusinessDocuments ............................................................................... 325Syntax ................................................................................................... 326

14

Table of Contents

Parameters ............................................................................................. 326Sample................................................................................................... 326

getCategories ............................................................................................. 326Syntax ................................................................................................... 326Sample................................................................................................... 326

getDocumentPackedMSOHTML ................................................................. 328Syntax ................................................................................................... 328Parameters ............................................................................................. 328Sample................................................................................................... 328

getDocumentPackedMSOHTML (overloaded).............................................. 329Syntax ................................................................................................... 329Parameters ............................................................................................. 329Sample................................................................................................... 330

getDocumentPDF ....................................................................................... 331Syntax ................................................................................................... 331Parameters ............................................................................................. 331Sample................................................................................................... 331

getDocumentPDF (overloaded) ................................................................... 332Syntax ................................................................................................... 332Parameters ............................................................................................. 332Sample................................................................................................... 334

getHaveStartSession ................................................................................... 334Syntax ................................................................................................... 334Sample................................................................................................... 334

getOutputProfiles ....................................................................................... 335Syntax ................................................................................................... 335Sample................................................................................................... 335

getSchema.................................................................................................. 336Syntax ................................................................................................... 336Parameters ............................................................................................. 336Sample................................................................................................... 336

getStartSession ........................................................................................... 336Syntax ................................................................................................... 336Parameters ............................................................................................. 337Sample................................................................................................... 337

initServerConnection .................................................................................. 337Syntax ................................................................................................... 337Parameters ............................................................................................. 337Sample................................................................................................... 338

setStatus .................................................................................................... 338Syntax ................................................................................................... 338Parameters ............................................................................................. 338

publishDocument ....................................................................................... 339Syntax ................................................................................................... 339Parameters ............................................................................................. 339Sample................................................................................................... 339

publishDocument (overloaded) ................................................................... 340Syntax ................................................................................................... 340Parameters ............................................................................................. 340Sample................................................................................................... 341

Ending a Session ............................................................................................ 342removeSession() ......................................................................................... 342Syntax ................................................................................................... 342Parameters ............................................................................................. 342

The XPressionDocument Class ........................................................................ 342getDocumentData....................................................................................... 342Syntax ................................................................................................... 342Sample................................................................................................... 343

15

Table of Contents

getDocumentFormat ................................................................................... 343Syntax ................................................................................................... 343Sample................................................................................................... 343

getDocumentName..................................................................................... 344Syntax ................................................................................................... 344Sample................................................................................................... 344

xPression Facade Exceptions ........................................................................... 345XPressionFrameworkException ................................................................... 345NoAuthorizedRightException ................................................................. 345NoStartSessionException ........................................................................ 345NoSuchTargetException.......................................................................... 345XPressionEJBException ........................................................................... 347XPressionProcessException ..................................................................... 347

Chapter 16 The Deprecated xPression EAI Adapter .................................................... 349xAdapter Architectural Overview.................................................................... 350Listener Technology.................................................................................... 350Request Processor....................................................................................... 350xPression Batch Wrapper ............................................................................ 350Transformation Engine................................................................................ 351

xAdapter Deployment Architecture ................................................................. 351xAdapter Components.................................................................................... 351Web Services Integration ............................................................................. 352Publish Document Web Service Method................................................... 352Preview PDF Web Service Method........................................................... 353Post For Batch Web Service Method ......................................................... 354Categories For User Web Service Method ................................................. 354Documents For Category Web Service Method ......................................... 355Output Profiles For Document Web Service Method ................................. 356Variables for Document Web Service Method ........................................... 356

JMS-Based Messaging Mechanism ............................................................... 357Publish Document Message..................................................................... 358Preview PDF Message............................................................................. 361Post For Batch Message ........................................................................... 363

XML Message Error Handling ..................................................................... 367Malformed XML..................................................................................... 367Request Type Not Supported................................................................... 368XML Missing a Required Parameter......................................................... 368

Transformation Engine................................................................................ 368Example property file settings ................................................................. 369Using UTF–8 Format for Adapter Properties ............................................ 370

XML File Export for Batch Execution ........................................................... 371Adapter Configuration Information ................................................................. 374Creating the Adapter Application.................................................................... 375Adding Your Application Definition ............................................................ 375

Configuring Your Application with xAdmin..................................................... 376Associating Attribute Sets with Your Application ......................................... 376Assigning Categories to Your Application .................................................... 377Assigning Data Sources to Your Application ................................................ 377Setting Up Access Rights for Your Application ............................................. 377

Configure Your Batch Scripts........................................................................... 377Verifying Your Installation .............................................................................. 378JMS ........................................................................................................... 378

XML Files ...................................................................................................... 380Publish Document ...................................................................................... 380

16

Table of Contents

Preview with PDF ...................................................................................... 381Post for Batch ............................................................................................. 382

Error Messages............................................................................................... 383Error Descriptions ...................................................................................... 385Event Descriptions...................................................................................... 387

Appendix A The Webtool Utility .................................................................................... 389Registering Webtool.dll................................................................................... 389The Encryption Utility .................................................................................... 389encrypt ...................................................................................................... 390Syntax ................................................................................................... 390Parameters ............................................................................................. 390Java Sample ........................................................................................... 390Visual Basic............................................................................................ 390

decrypt ...................................................................................................... 391Syntax ................................................................................................... 391Parameters ............................................................................................. 391Java ....................................................................................................... 391Visual Basic............................................................................................ 391

The Pack Utility .............................................................................................. 392pack .......................................................................................................... 392Syntax ................................................................................................... 392Parameters ............................................................................................. 392Java ....................................................................................................... 392Visual Basic............................................................................................ 393

unpack....................................................................................................... 393Syntax ................................................................................................... 393Parameters ............................................................................................. 394Java ....................................................................................................... 394Visual Basic............................................................................................ 394

Appendix B The AppList DTD ....................................................................................... 397The Complete AppList.dtd.............................................................................. 397The AppList and Application Elements........................................................ 398The WorkFlow Element............................................................................... 399The AccessRights Element........................................................................... 399The RequiredAttributes and Attr Elements................................................... 400

A Complete AppList.xml Example................................................................... 401

17

Table of Contents

List of Figures

Figure 1. xEditor works with Microsoft 2007 (shown) and 2010. The xEditor TaskPane is the same for both versions.................................................................... 194

Figure 2. The following graphic shows the xPRS Server engine simplified data flow. ............ 260Figure 3. The following graphic shows the xPublish engine simplified data flow. ................. 261Figure 4. The following graphic shows the batch engine execution architecture. ................... 263Figure 5. There are three main xPression integration strategies: Real-Time

(Request/Reply), Near-Time, and Batch. This diagram shows howxFramework integrates with the xPRS server. ................................................... 264

Figure 6. The following image shows the document requester functional flow. ..................... 272Figure 7. On your development machine create a folder structure that resembles

the following image, which shows the Quote_Gen.war folder structure.............. 307Figure 8. The resulting page should look like this when launched in your browser. .............. 311Figure 9. The resulting GetDocuments.jsp page should look like this when

launched in your browser................................................................................ 313Figure 10. The resulting GetInputs.jsp page should look like this when launched in

your browser. This graphic only shows a sampling of the user inputfields displayed on getInputs.jsp...................................................................... 315

Figure 11. The resulting Preview.jsp page should look like this when launched inyour browser.................................................................................................. 320

Figure 12. The following image shows the J2EE application assembly. ................................... 320Figure 13. These components and their relationships are shown in the diagram and

discussed below. ........................................................................................... 350Figure 14. The xAdapter, deployed on a WebSphere cluster of two Windows

servers, would look like the following image. ................................................... 351Figure 15. The following image shows how to edit the batchrunner.bat file. ........................... 378Figure 16. The following image shows how to retrieve the WDSL.......................................... 378Figure 17. The following image shows testing the JMS. ......................................................... 379Figure 18. The following image shows the WebSphere Embedded Messaging page. ............... 380

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 1Introduction

Welcome to xFramework. This book is geared towards intermediate or higher level programmers.

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

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

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

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

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

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

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

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

23

https://support.emc.com

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

Introduction

24

Chapter 2About xFramework and the xPressionDevKit API

With version 4.0, xPression introduces a newWeb Service API that conforms to the WS-I Basic Profile.The old xFramework Web Service API, Java API, and xAdapter have been deprecated. Althoughthese items will be supported for backward compatibility in the current version, EMC DocumentSciences encourages you to use the new Web Service API as it offers better performance, greaterflexibility, 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 anupdated 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. TheIQuickDocWeb Service is a set of Web Service methods that provide the simplest and most commonlyused xPression services. They are delivered as part of any xPression installation. IDocumentItem is anxPression DevKit Web Service. xPression DevKit is an extension of iQuickDoc for solutions-specificfunctions. 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. Allcoding 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 yourapplication.

• Improved error messages and codes — For more information, see Error Messages, page 32.

• New xPressForms Web Service methods for xPressForms users — For more information, seeChapter 8, xPressForms Web Services for Reporting.

Note: xPression DevKit is known formally as the Interactive Document Development Kit (IDDK).

AuthenticationxPression uses a new authentication model that enables easier integration with a variety of singlesign-on products and security models. All entry points into xPression will take an XML documentwhich contains user credentials and any other information needed to authenticate and authorize therequest. You can specify these credentials in any compatible format, for example: encrypted, plaintext, and token. The XML document is passed through the requestContext parameter that mustbe defined for all Web Service calls.

This new authentication model eliminates the need to pass hard-coded parameters for everysecurity-sensitive request, and enables you to integrate without having to change the signatureof any xPression entry points. It also enables you to create Java User Exit code to perform moresophisticated integrations.

Note: Single Sign-On (Trusted UserID/Groups) can only be used when the enableTrustedUserparameter in the systemconfig.properties file is set to True. This properties file is located in yourxPressionHome 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 documentcontaining 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 setsof access rights. By specifying the application name, you are requesting the access rights granted tothe user for that specific application.

Please be aware that the application name you use must grant permissions that are appropriate foryour request. In general, for core xPression services (client and server functions), you can supplycredentials for the user under any application for which the user is authenticated. For solutionapplications (xPressForms, xPression DevKit, xResponse, xRevise), you must supply credentials forthe exact application you are using.

The xPression Web Service methods that use the requestContext parameter can determine theapplication name even if you do not supply the name in the parameter. xPression uses the followinglogic, 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


• 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 theapplication.

Using requestContext with Documentum-Based Documents

When attempting to access documents stored on a Documentum repository, ensure that the user inthe requestContext parameter passes both xPression server authentication (usually LDAP or NTauthentication) as well as Documentum authentication. This means that the user name should existon both the server and the Documentum Repository. To publish a document on Documentum, theuser needs to have the Documentum role of xpression_dashboard.

Additionally, do not use the <Group> element when accessing Documentum-based documentsthrough Single Sign-On (Trusted UserID and Groups).

Example:<RequestContext><Credentials method="Trusted UserID and Groups"><UserID>t1</UserID></Credentials><ApplicationName></ApplicationName></RequestContext>

requestContext Examples

The following examples show how to structure your XML document for the requestContextparameter.

Unencrypted userid/password<RequestContext><Credentials method="UserID and Password"><UserID>John</UserID><Password>pass</Password></Credentials><ApplicationName>xPression Framework</ApplicationName></RequestContext>

Weak encrypted userid/password<RequestContext><Credentials method="Weak Encrypted UserID and Password"><UserID><EncryptedData xmlns='http://www.w3.org/2001/04/xmlenc#'Type='http://www.w3.org/2001/04/xmlenc#Content'><CipherData><CipherValue>A23B45C67</CipherValue></CipherData></EncryptedData></UserID><Password><EncryptedData xmlns='http://www.w3.org/2001/04/xmlenc#'Type='http://www.w3.org/2001/04/xmlenc#Content'>

27


<CipherData><CipherValue>A2KS4SLDK6DKOQWI</CipherValue></CipherData></EncryptedData></Password></Credentials><ApplicationName>xPression Response</ApplicationName></RequestContext>

Single Sign-On (Trusted UserID/Groups)<RequestContext><Credentials method="Trusted UserID and Groups"><UserID>John</UserID><Group>Administrator</Group><Group>xPression Design User</Group><Group>xPression Revise User</Group></Credentials><ApplicationName>xPression Revise</ApplicationName></RequestContext>

Setting Up Your ApplicationWhen you create your own application, you must add that application to the applist.xml file storedon 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 applicationsdefined to this file. The xPression installation program generates this file upon installation. Creatinga new application name is optional. For the vast majority of users, one of the existing applicationnames will be sufficient.

Adding Your Application DefinitionTo 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


3. Type the application element between the <AppList></AppList> tags. Your application namemust not contain apostrophes (’). For example:<AppList><Application name="xPression Custom Application"></Application></AppList>

4. If your application supports workflow, type the workflow element. For example:<AppList><Application name="xPression Custom Application"><WorkFlow fromStatus="SUBMITTED" toStatus="APPROVED" enterAction="Write"promoteAction="Approve" /></Application></AppList>

5. Type the access rights your application supports, including whether or not they’re hierarchical.For example:<AccessRights heirarchical="yes"><Access name="Read" /><Access name="Write" /><Access name="Approve" /></AccessRights>

6. Type the required attributes, if any. For example:<RequiredAttributes><Attr name="TEXTCLASS_ID" type="integer" min="0" max="0"ValidValueExist="0" Default_Value="" isMappable="0" stringlength="0"RangeExist="0" DefaultExist="0" multisingle="single" validValue=""/><Attr name="PRODUCT_ID" type="integer" min="0" max="0"ValidValueExist="0" Default_Value="" isMappable="0" stringlength="0"RangeExist="0" DefaultExist="0" multisingle="single" validValue=""/>

</RequiredAttributes><RequiredAttributes condition="SupportApproval"><Attr name="STATUS" type="string" min="0" max="0" ValidValueExist="1"Default_Value="PENDING" isMappable="0" stringlength="255" RangeExist="0"DefaultExist="0" multisingle="multi" validValue="PENDING;SUBMITTED;APPROVED"/><Attr name="EFFECTIVE_DATE" type="DateTime" min="0" max="0"ValidValueExist="0" Default_Value="" isMappable="1" stringlength="0"RangeExist="0" DefaultExist="0" multisingle="multi" validValue=""/><Attr name="WITHDRAW_DATE" type="DateTime" min="0" max="0"ValidValueExist="0" Default_Value="" isMappable="1" stringlength="0"RangeExist="0" DefaultExist="0" multisingle="multi" validValue=""/>

</RequiredAttributes>

7. Type the closing </Application> 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:<Application name="xPression Custom Application"><WorkFlow fromStatus="SUBMITTED" toStatus="APPROVED" enterAction="Write"promoteAction="Approve" /><AccessRights heirarchical="yes"><Access name="Read" /><Access name="Write" /><Access name="Approve" /></AccessRights></Application>

29


This sample application definition has workflow and access rights, but no required attributes.

Configuring Your Application with xAdminNow that you’ve added your application definition to AppList.xml, it’s time toconfigure it with xAdmin. To configure your application in xAdmin, complete thefollowing 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 theattribute set name, the Attribute Set page appears. Alternatively, you can also create a newattribute 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


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 SelectedUsers 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 assubmitters and approvers. Please consult the xAdmin User Guide to assist you in setting up workflowfor your application.

IQuickDoc ConfigurationIQuickDoc Web Services users should correct an Axis2 bug before implementing the IQuickDocWeb Services. Failing to perform this manual update can cause errors if you use HTTP Bindingand 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://<server>:<port>/xFramework/services/QuickDoc?wsdl

2. In the HTTP Binding section of the WSDL, change the value of the part attribute to parametersfor each operation. For example:<wsdl:operation name="publishAndReturnDocument"><http:operation location="QuickDoc/publishAndReturnDocument"/><wsdl:input><mime:content type="text/xml" part="parameters"/></wsdl:input><wsdl:output><mime:content type="text/xml" part="parameters"/></wsdl:output><wsdl:operation>

3. Add the SOAPFaultException element for each operation. For example:<wsdl:operation name="publishAndReturnDocument"><http:operation location="QuickDoc/publishAndReturnDocument"/><wsdl:input><mime:content type="text/xml" part="parameters"/></wsdl:input><wsdl:output>

31


<mime:content type="text/xml" part="parameters"/></wsdl:output><wsdl:fault name="SOAPFaultException"><soap:fault use="literal" name="SOAPFaultException"/></wsdl:fault><wsdl:operation>

4. Save and close the file.

Error MessagesEach Web Service returns error messages in the following format:<error code> - <error message>

For example:3143 - Unable to retrieve the next customer record. Check the connection tothe customer data source.

The CompuSet BridgeThe CompuSet Bridge is an optional feature that enables xPression users with legacy CompuSetapplications to leverage their CompuSet assets with xPression. Several web services have beenprovided for use with this option. Since the CompuSet Bridge requires a license and is intended forimplementation with legacy products, details of these web services are provided with the CompuSetBridge documentation. Refer to the xPression CompuSet User Guide for more information.

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

32

Chapter 3The IQuickDoc Web Service

The IQuickDoc Web Service provides access to the simplest and most commonly used xPressionservices. Because IQuickDoc uses simple signatures, the WSDL can be easily consumed by any SOAPtoolkit implementing the WS-I Basic Profile. As a Web Service with a simple signature, IQuickDocmakes no use of complex types. These Web Service methods are easy to implement and can helpyou get started integrating with xPression very quickly. All xPression customers have access to theIQuickDoc Web Service. This Web Service can be used by Documentum Edition and EnterpriseEdition customers.

If you are working with xPresso for Word documents in workflow enabled categories, please seexPresso 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://<server>:<port>/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 WorkflowEnabled CategoriesIf you are using xPresso for Word documents that reside in workflow enabled categories, be awarethat the web service currently respect only the system level workflow setting on your server. The webservices will not override the system level setting with a user level setting. The system level settingdetermines the lowest level of workflow status that can be published on a given server. This alsoapplies to web services that return information about documents.• pending — The server will publish and web services will return information for any documentthat is pending or higher.

• submitted — The server will publish and web services will return information for only approvedand submitted documents.

• approved — The server will publish and web services will return information for only approveddocuments.

The categoriesForUser MethodThe categoriesForUser web service method returns a list of categories that are available to theuser whose information is passed in the requestContext parameter. This method may completesuccessfully without returning any category names if the user has not been given access rights toany xPression categories. If the method fails, it returns a SOAP Fault that indicates the reason forthe failure.

Return Value : This method returns zero or more Strings in a String array. Each String in the arrayrepresents the name of a category the user is eligible to access.

SyntaxString[] categoryNames = categoriesForUser(requestContext)

Parameters

requestContext : String

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

Please be aware that the application name you use must grant permissions that are appropriate foryour request. For this method, the following xPression application names are valid: xPression Design,xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. Formore information, see About the requestContext Parameter, page 26.

34


The documentsForCategory MethodThe documentsForCategory web service method returns a list of all xDesign and xPresso documentscontained in the defined category. This list is returned as a String array that contains one documentname for every document that resides in the defined category. This method can complete successfullywithout 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 arrayrepresents the name of a document inside the requested category that the user is eligible to access.

SyntaxString[] documentNames = documentsForCategory(requestContext, categoryName)

Parameters




categoryName: String

A string specifying the name of the category for which you want to list all available documents.

The descriptionForDocument MethodThe descriptionForDocument method retrieves a textual description of a document deployed on thexPression Server. If the document does not have defined description, the method will return a zerolength String. You can request the description for a specific version of the document, or for the latestversion (highest version number) of the document. To request the latest version, simply request thedocument using the document name without any including and version information. To request aspecific 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 themethod fails, the method will return a SOAP Exception with an error code and error messageappropriate to the type of error encountered.

35


SyntaxString description = descriptionForDocument(requestContext, documentName)

Parameters




If you are requesting information about an xPresso document stored in the Documentum xPressionRepository, ensure the user name is authenticated on the xPression Server and in the Documentumrepository. 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 specificversion number.

• To request a specific version of the document, supply the document name and version numberas follows:/filename?version=versionnumber

where /filename is the name of the document and versionnumber is either a version number or thestring “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 specificversion number must be supplied.

• If you want to retrieve this information for xPresso documents stored on your DocumentumxPression 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 isthe version number.

36


The thumbnailForDocument MethodThe thumbnailForDocument method retrieves the thumbnail image for a document deployed on thexPression 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 thethumbnail 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 documentname 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 thedocument. If the method fails, the method returns a SOAP Exception with an appropriate errorcode and message.

Syntaxbyte[] thumbnailImage = thumbnailForDocument(requestContext, documentName)

Parameters


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

Please be aware that the application name you use must grant permissions that are appropriate foryour request. For this method, the following xPression applications are valid: xPression Design,xPression Revise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. Formore information, see About the requestContext Parameter, page 26.

If you are requesting thumbnails for an xPresso document stored in the Documentum xPressionRepository, ensure the user name is authenticated on the xPression Server and in the Documentumrepository. 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.


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 specificversion number.

• To request a specific version of the document, supply the document name and version numberas follows:/filename?version=versionnumber

37



Note: For xPresso for Word documents, you cannot just use the string “LATEST”; a specificversion number must be supplied.

• If you want to retrieve this information for xPresso documents stored on your DocumentumxPression 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 isthe version number.

The designToolForDocument MethodThe designToolForDocument web service method returns a description of the design tool that createdthe specified document.

Return Value: A String containing the textual description of the design tool which created thespecified 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 messageappropriate to the type of error encountered.

SyntaxString designTool = designToolForDocument(requestContext, documentName)

Parameters



38





A string specifying the name of a document that resides on the xPression Server. This method returnsthe design tool name of the document specified with this parameter.

If you want to retrieve this information for xPresso documents stored on your DocumentumxPression Repository you must supply a path to the document on the Documentum repository. Thepath 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 theversion number.

The outputProfilesForDocument MethodThe outputProfilesForDocument method returns a list of output profiles that the xPressionadministrator has associated with the specified document. In xAdmin, the administrator can associatea subset of output profiles with a document to identify which output profiles are best suited for theparticular document. This list is then available to users of xResponse, xRevise, and any customcorrespondence application created for use with xPression.

Return Value: This method returns a String array that contains one output profile name for everyoutput profile assigned to the specified document. If no output profiles were associated with thedocument, this method will return all available output profiles. If the method fails, it returns a SOAPFault that indicates the reason for the failure.

SyntaxString[] outputProfiles = outputProfilesForDocument(requestContext, documentName)

Parameters



39





A string specifying the name of a document that resides on the xPression server. This method willreturn 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 DocumentumxPression Repository you must supply a path to the document on the Documentum repository. Thepath should be formatted as follows:ecm::Documentum xPression Repository:/path/filename?version=version


The versionsForDocumentWithWorkflowStatusMethodThe versionsForDocumentWithWorkflowStatus method returns the version number and the workflowstatus for the specified document. Workflow status applies only to xPresso for Word documents thatreside 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 versionof the specified document. If you are using this method with xPresso for Word documents, themethod also reports the workflow status of the document version (when such information exists). Ifthe xPresso for Word document resides on a Documentum repository or your xPression category doesnot have workflow functionality enabled, no workflow status will be reported. The version numberis reported first followed by the workflow status of the version.

Workflow-enabled xPresso for Word example:1.0 Pending1.1 Submitted2.0 Approved

If the method fails, it returns a SOAP Fault that indicates the reason for the failure. If the method isused with an xDesign document, xPression will generate an UnsupportedOperationException.

SyntaxString[] versionWithStatus = versionsForDocumentWithWorkflowStatus(requestContext, documentName)

40


Parameters




41




A string specifying the name of a document. The document must reside on the xPression Server. Thedocument name string contains the following elements:

If you want to access xPresso documents stored on your Documentum xPression Repository youmust supply a path to the document on the Documentum repository. The path should be formattedas follows:ecm::Documentum xPression Repository:/path/filename

The publishDocument MethodThe publishDocument method enables you to publish a document. This method is more efficient thanpublishAndReturnDocument because it does not return any documents back to the caller. This is thebest 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 sourcedefinition assigned to the category that contains your document. This method is only guaranteedto process one document record of data, so ensure that you send only one record of input data. Ifmultiple records are given as input, the method may try (and fail) to determine and use the firstrecord in the XML customer data.

Some types of output profiles are not compatible with some documents. For example, CompuSetdocuments cannot use xPublish profiles and xPublish documents cannot use CompuSet profiles.xPresso for Dreamweaver documents cannot use output profiles that produce formats other thanHTML. xPresso for InDesign documents cannot use output profiles that produce HTML. If youattempt to publish a document through an incompatible output profile, this method will return theerror message:9022-The document with type {Document type}(e.g.xPressoInDesign) can not besupported.

Also, InvaildDocumentTypeException will appear in the xPression log.

Return Value: A String message confirming the document was successfully published. If the methodfails, it returns a SOAP Fault that indicates the reason for the failure.

SyntaxString message = publishDocument(requestContext, documentName, customerData,outputProfileName)

42


Parameters




If you are publishing an xPresso document stored in the Documentum xPression Repository, ensurethe user name is authenticated on the xPression Server and in the Documentum repository. Inthe Documentum repository, the user must be assigned the xpression_dashboard role. For moreinformation, see Using requestContext with Documentum-Based Documents, page 27.


A string specifying the name of a document you wish to publish. The document must reside onthe xPression Server. For documents that reside in the xPression database, use the following URLfor documentName:/filename?version=versionnumber


If you want to publish xPresso documents stored on your Documentum xPression Repository youmust supply a path to the document on the Documentum repository. The path should be formattedas follows:ecm::Documentum xPression Repository:/path/filename?version=version


customerData : String

The value for this parameter depends upon the type of data source assigned to the category thatcontains the document you want to publish. If your data source is an XML document, you mustprovide a single record of XML customer data. If your data source is a relational database, you mustprovide keys for the relational database data source. The following is an example of an XML stringcontaining the key values for a specific customer record:<Keys><Key name="AUTOPAY_KEY">1</Key><Key name="LANGUAGE">ENGLISH</Key></Keys>

outputProfileName : String

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

43


Sample

This sample shows how to use the method with a SOAP web service call.<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:web="http://webservice.framework.xprs.dsc.com”><soapenv:Header/><soapenv:Body><web:publishDocument><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password"><UserID>UserName</UserID><Password>Password</Password></Credentials><ApplicationName>xPression Response</ApplicationName></RequestContext>]]></web:requestContext><web:documentName>Pay Pilot Check Stub</web:documentName><web:outputProfileName>PayPilot</web:outputProfileName><web:customerData><![CDATA[<CheckMergePayments xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><EmailRecipients><EmailRecipientAddress>[email protected]</EmailRecipientAddress></EmailRecipients><Payment><PaymentOrderNumber>3</PaymentOrderNumber><CheckNumber>1</CheckNumber><PolicyNumber>0046668888</PolicyNumber><Source>Refund</Source><ClaimType>Death</ClaimType><ClaimTypeGroup>100<ClaimTypeGroup></Payment><Payment><PaymentOrderNumber>4</PaymentOrderNumber><CheckNumber>2</CheckNumber><PolicyNumber>0046669999</PolicyNumber><Source>Loan</Source><ClaimType>Death</ClaimType><ClaimTypeGroup>200</ClaimTypeGroup></Payment></CheckMergePayments>]]></web:customerData></web:publishDocuments></soapenv:Body></soapenv:Envelope>

The publishDocuments MethodThe publishDocuments method immediately publishes documents according to variable data XMLpassed in as a parameter of the method. The method call will not return until all records in thevariable data are processed, so take care to limit the amount of variable data passed or the webservice 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 documentand the output profile used.

If the method fails it generates an AxisFault.

44


SyntaxpublishDocuments(String requestContext,String[] documentPackageNames, String outputProfileName, String customerData)

Parameters

requestContext: String




documentPackageNames: String

An array of strings that contains the names for the packages you want to publish. These documentpackages must already be deployed on the xPression Server, and they must each use the same schemafile. The package names must not include the file extension.

45


For documents that reside in the xPression database, use the following URL for documentName:/filename?version=versionnumber


outputProfileName: String

The name of the publish profile to use when publishing the document package. The publish profilemust be defined in advance.

customerData: String

An XML document containing variable data which conforms to the XML schema required by thedocument packages selected.

Sample

This sample shows how to use the method with a SOAP web service call.<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:web="http://webservice.framework.xprs.dsc.com”><soapenv:Header/><soapenv:Body><web:publishDocument><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password"><UserID>UserName</UserID><Password>Password</Password></Credentials><ApplicationName>xPression Response</ApplicationName></RequestContext>]]></web:requestContext><web:documentPackageNames>Pay Pilot Check Stub</web:documentPackageNames><web:documentPackageNames>Pay Pilot Statement</web:documentPackageNames><web:documentPackageNames>Pay Pilot Summary</web:documentPackageNames><web:outputProfileName>PayPilot</web:outputProfileName><web:customerData><![CDATA[<CheckMergePayments xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><EmailRecipients><EmailRecipientAddress>[email protected]</EmailRecipientAddress></EmailRecipients><Payment><PaymentOrderNumber>3</PaymentOrderNumber><CheckNumber>1</CheckNumber><PolicyNumber>0046668888</PolicyNumber><Source>Refund</Source><ClaimType>Death</ClaimType><ClaimTypeGroup>100<ClaimTypeGroup></Payment><Payment><PaymentOrderNumber>4</PaymentOrderNumber><CheckNumber>2</CheckNumber><PolicyNumber>0046669999</PolicyNumber><Source>Loan</Source><ClaimType>Death</ClaimType><ClaimTypeGroup>200</ClaimTypeGroup></Payment></CheckMergePayments>]]>

46


</web:customerData></web:publishDocuments></soapenv:Body></soapenv:Envelope>

The publishAndReturnDocument MethodThe publishAndReturnDocument method enables you to publish a document and return it to yourcalling 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 youspecify must contain an output stream whose distribution definition is defined with the “Return toCalling Application” option. If no output streams are defined with a distribution definition markedas “Return to Calling Application”, the method will return a zero length byte array when suchdocuments are successfully published. If more than one output stream contains a distributiondefinition marked as “Return to Calling Application”, this method selects any one of the definedoutput profiles. You cannot control which output profile it selects.When the job completes, thexPression Server will notify the URL defined in the Listener with the following XML structuredmessage

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



Return Value: This method returns a byte array representing the document that was published andreturned. The format of the document is determined by the output profile. If the method fails, itreturns a SOAP Fault that indicates the reason for the failure. If your distribution definition does notuse the “Return to calling application” option, this method will return a null value.

The following code is an example of the SOAP fault code:<faultcode>soapenv:Server</faultcode><faultstring>9550-Unexpected error occurred.Please check log for further information. - caused by : null</faultstring></detail>

47


Syntaxbyte[] document = publishAndReturnDocument(requestContext, documentName,customerData, outputProfileName)

Parameters











The value for this parameter depends upon the type of data source assigned to the category thatcontains the document you want to publish. If your data source is an XML document, you mustprovide a single record of XML customer data. If your data source is a relational database, you mustprovide 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:<Keys><Key name="AUTOPAY_KEY">1</Key><Key name="LANGUAGE">ENGLISH</Key>

48


</Keys>



ThepublishAndReturnDocumentMultipleStreamMethodThe publishAndReturnDocumentMultipleStream method enables you to publish a document andreturn it to your calling application using multiple streams. When calling this method, you supplythe document name, the customer data, and the name of the output profile with which to publish thedocument. This method only works with xPublish documents.

In order to successfully return the document to your calling application, the output profile youspecify must contain an output stream whose distribution definition is defined with the “Return toCalling Application” option. If no output streams are defined with a distribution definition markedas “Return to Calling Application”, the method will return a zero length byte array when suchdocuments are successfully published. If more than one output stream contains a distributiondefinition marked as “Return to Calling Application”, this method returns all the document dataassociated with those streams. If you want to return document metadata with this method, pleasedefine the metadata in the Distribution Definition.





49


Syntax

MultiStream multistream= publishAndReturnDocumentMultipleStream(requestContext,documentName, customerData, outputProfileName, includeMetaData)

Parameters











The value for this parameter depends upon the type of data source assigned to the category thatcontains the document you want to publish. If your data source is an XML document, you mustprovide a single record of XML customer data. If your data source is a relational database, you mustprovide 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:<Keys><Key name="AUTOPAY_KEY">1</Key>

50


<Key name="LANGUAGE">ENGLISH</Key></Keys>



includeMetaData : Boolean

If set to true, this method will also return the Generic Index metadata file. The metadata file is anXML 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 UserGuide for more information about this metadata file. If set to false, no metadata is returned.

The getTemplateFields MethodThis method enables you to extract data from an xPresso for Word package. If you use this methodwithout defining any customer data, the method returns data for all the variables used in the specifiedtemplate. If you supply customer data to the method, the method returns only the data that is notincluded in the customer data you supplied. This method works exclusively with xPresso for Worddocuments created in xPression 4.5 or later. It does not support xPresso for Adobe InDesign, xPressofor Dreamweaver, or xDesign.

Return Value: This method returns a string that contains data for all the variables used in thespecified template. If the method fails, it returns a SOAP Fault that indicates the reason for the failure.

Syntax

getTemplateFields(requestContext, documentName, customerData)

Parameters



Use “Word” as the application name. This value will grant permissions that are appropriate for yourrequest. For more information, see About the requestContext Parameter, page 26.



51


A string specifying the name of a document. The document must reside on the xPression Server. Thedocument 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 versionnumber. 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 youmust supply a path to the document on the Documentum repository. The path should be formattedas follows:ecm::Documentum xPression Repository:/path/filename?version=version



You can supply existing customer data for this parameter in XML format, or supply NULL for thevalue. If you supply customer data, this method does not return data for any of the fields that yousupplied. If you use NULL, this data returns all the data for the package.

For example, if your document contains the following three fields: <Name>, <Address>, <Phone>,and you supply the <Name> field in your customer data, this method only returns information forthe <Address> and <Phone> 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 effectivedate information, this method will generate an error.

• Do not supply a version number with the document name. Doing so could result in selecting adocument that is no longer effective.

If you are requesting a workflow-enable xPresso for Word document, only Approved documentscan 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


With NULL customerData Value

Input XML<web:getTemplateFields><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password">

<UserID>user</UserID><Password>password</Password>

</Credentials><ApplicationName>Word</ApplicationName>

</RequestContext>]]></web:requestContext><web:documentName>/doc?version=1.1</web:documentName><web:customerData></web:customerData></web:getTemplateFields>

With Supplied customerData

Input XML<web:getTemplateFields><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password">



</RequestContext>]]></web:requestContext><web:documentName>/doc?version=1.1</web:documentName><web:customerData><![CDATA[<?xml version="1.0" encoding="UTF-8"?><root><AllTypeField>

<photo/><photo1></photo1><agent>JackJones</agent><address>1400 S. Lane St.</address><city>Omaha</city><date>2004-02-20</date>

</AllTypeField></root>]]></web:customerData></web:getTemplateFields>

The getDataCollectionTemplate Method

Caution: This method is deprecated. Use the getTemplateFields method instead.

53


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 inthe Data Collection Template. If you supply customer data to the method, the method will returnonly the data not included in the customer data you supplied. This method works exclusively withxPresso for Word documents created in xPression 4.5 or later. It does not support xPresso for AdobeInDesign, xPresso for Dreamweaver, or xDesign.

Return Value: This method returns a String that contains the Data Collection Template. If the methodfails, it returns a SOAP Fault that indicates the reason for the failure.

Syntax

getDataCollectionTemplate(requestContext, documentName, customerData)

Parameters



Use “Word” as the application name. This value will grant permissions that are appropriate for yourrequest. For more information, see About the requestContext Parameter, page 26.



A string specifying the name of a document. The document must reside on the xPression Server. Thedocument 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 versionnumber. 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


If you want to access xPresso documents stored on your Documentum xPression Repository youmust supply a path to the document on the Documentum repository. The path should be formattedas follows:ecm::Documentum xPression Repository:/path/filename?version=version



You can supply existing customer data for this parameter in XML format, or supply NULL for thevalue. If you supply customer data, the Data Collection Template will not include data for any ofthe fields that you supplied. If you use NULL, the method will return the entire Data CollectionTemplate for the package.

For example:

If your Data Collection Template contains the following three fields: <Name>, <Address>, <Phone>

And you supply the <Name> field in your customer data

The returned Data Collection Template will only include information for the <Address> and <Phone>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 effectivedate information, this method will generate an error.

• Do not supply a version number with the document name. Doing so could result in selecting adocument 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<web:getDataCollectionTemplate><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password">



</RequestContext>]]></web:requestContext>

55


<web:documentName>/doc?version=1.1</web:documentName><web:customerData></web:customerData></web:getDataCollectionTemplate>

With Supplied customerData

Input XML<web:getDataCollectionTemplate><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password">



</RequestContext>]]></web:requestContext><web:documentName>/doc?version=1.1</web:documentName><web:customerData><![CDATA[<?xml version="1.0" encoding="UTF-8"?><root><AllTypeField>

<photo/><photo1></photo1><agent>JackJones</agent><address>1400 S. Lane St.</address><city>Omaha</city><date>2004-02-20</date>

</AllTypeField></root>]]></web:customerData></web:getDataCollectionTemplate>

56

Chapter 4Workflow Integration Web Services

The following Web Services are available to all xPression Enterprise Edition users. These WebServices 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

WorkflowDocumentBrowsingServiceThis Web Service enables you to select a document version for previewing. TheWorkflowDocumentBrowsingService Web Service WSDL can be found here:http://<server>:<port>/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 Cyclesetting.

Return Value: This method returns zero or more Strings in a String array. Each String in the arrayrepresents 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



Please be aware that the application name you use must grant permissions that are appropriate foryour request. All valid application names are acceptable, including: xPression Design, xPressionRevise, xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For moreinformation, 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. Themethod filters out documents currently in a workflow and documents which can not be edited (forexample, xPresso documents without a source template file).

Return Value: This method returns zero or more Strings in a String array. Each String in the arrayrepresents the name of a document eligible to be submitted to a workflow.

Syntax

String[] listWorkflowAvailableDocuments(requestContext, cateName)

Parameters




cateName : String

The name of the category where the method will search for eligible documents.

58


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


Parameters




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 documentscreated in xDesign.

Return Value: This method returns a string identifying the version date or version number of thespecified 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




60


docName : String

The name of the document whose version you want identified by the method.

DataBrowsingServiceThis Web Service enables you to select customer data The IQuickDoc Web Service WSDL can befound here:http://<server>:<port>/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 onyour server, xPression enables you to set the default data source for any application that publishes adocument from that category. The default data source is not selected by name, it is selected when youspecify an application. xPression will then look at the category settings and determine which datasource was defined as the default data source for that application. When using this method, you cancall the default data source by specifying an application name in the requestContext parameter orletting 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 thedefault data source specified for xPression Design in the category.

• xPublish Documents— xPression chooses xPression Design as the application and selects thedefault data source specified for xPression Design in the category.

• xPresso for InDesign Documents— xPression chooses xPresso for InDesign as the applicationand 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 andselects the default data source specified for xPresso for Word in the category.

• xPresso for Dreamweaver Documents— xPression chooses xPresso for Dreamweaver as theapplication and selects the default data source specified for xPresso for Dreamweaver in thecategory.

Return Value: This method returns a String identifying the default data source name.

Syntax

String[] getDefaultDS(requestContext, docName)

61


Parameters



62



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 arrayrepresents a customer key.

Note: This method does not support xPresso data sources.

Syntax

String[] listKeys(requestContext, dsName)

Parameters




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


Syntax

String[] getDataRecordXML(requestContext, dsName, keyValues)

64


Parameters




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.

WorkflowServiceThis Web Service enables you to preview a document and change the Life Cycle status of a documentin a workflow.

The IQuickDoc Web Service WSDL can be found here:http://<server>:<port>/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 arrayrepresents a Life Cycle definition in xAdmin.

65


Syntax

String[] listLifecycles(requestContext)

Parameters




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 arrayrepresents a status in a Life Cycle.

Syntax

String[] statusInLifecycle(requestContext, lifecycleName)

Parameters




lifecycleName : String

The name of the Life Cycle for which you want to return all available statuses.

66


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




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 versionof 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.



67


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




docName : String

The name of the document that you want to preview.

version : String


dsName : String

The name of the data source that you want to use when previewing the document.



68


workflowBegins

This method enables you to notify xPression that a document is being submitted to a workflow.

Syntax

String[] workflowBegins(requestContext, docName, version)

Parameters




docName : String

The name of the document that you want to submit to a workflow.

version : String


setLifecycleStatus

This method enables you to change the Life Cycle status of a specified document. The workflowBeginsmethod should be called before this method.

Syntax

String[] setLifeCycleStatus(requestContext, docName, version, status)

69


Parameters




70


docName : String

The name of the document for which you want to change the Life Cycle status.

version : String


status : String

The name of the status that you want to apply to the specified document. Please ensure this statusis 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




docName : String

The name of the document that you want to exit a workflow.

version : String


successFlag : Boolean

71


If successFlag=true, then xPression will approve all pending content items (both CompuSet andxPublish). If successFlag=false, then xPression will leave the content items at their current status level.

72

Chapter 5xPression DevKit Web Services

xPression DevKit is a purchasable add-on for Enterprise Edition customers. It serves as an extensionof IQuickDoc for solution-specific capabilities. These Web Services methods add considerablepower 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 withoutaccessing the xPression database. The Web Services methods are more powerful, and therefore morecomplex, using complex types and requiring more sophistication in coding. Although more xPressionDevKit Web Service methods will be released in the future, currently xPression DevKit contains onlythe IDocumentItem and xCatalog Web Services.

xPression DevKit also contains xEditor, a component you can embed in your application. xEditoris a Microsoft Word-based editor that enables you to use Microsoft Word’s powerful editing andcomposition features to edit work items for your correspondence application. For more information,see Chapter 11, The xPression DevKit xEditor Component.

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

This Web Service contains the following methods:• searchDocumentItem, page 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 thatindicates the reason for the failure.

Syntax

String documentItemIDs = searchDocumentItem(requestContext, searchCriteriaXML)

Parameters



74


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

• xPression DevKit

• 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 isCompletedparameter can be set to true or false. If set to true, you are indicating that you want to search acompleted work item.

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

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

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

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

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

• DOC_STATUS — Supply the document status.

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

• CUSTOMERKEY — Enables you to search the customer key for values. This element mustappear inside a PHASE element, and can contain any number of KEY_VALUE elements. EachKEY_VALUE element is implicitly joined by an OR operator. The following two samples returnthe same sets of work items.— Sample 1:

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

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

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

— Sample 2:<CUSTOMER_KEYS>

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


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

</CUSTOMER_KEYS>

75


You can use an AND operator to connect multiple elements. The following sample containsthree KEY_VALUE elements, A, B, and C, which returns the result of the logical conjunction:(A AND B) OR C.<CUSTOMER_KEYS>

<AND><KEY_VALUE name="MYKEY" category="MortgageProtection">7</KEY_VALUE><KEY_VALUE name="CUSTNUM" category="MortgageProtection">2</KEY_VALUE>

</AND><KEY_VALUE name="TITLE" category="MortgageProtection">Ms</KEY_VALUE>

</CUSTOMER_KEYS>

You can also use AND operators in conjunction with OR operators. The following sample containsthree KEY_VALUE elements, A, B, and C, which returns the result of the logical conjunction:A AND (B OR C).<CUSTOMER_KEYS>

<AND><KEY_VALUE name="MYKEY" category="MortgageProtection">7</KEY_VALUE>

<OR><KEY_VALUE name="CUSTNUM" category="MortgageProtection">2</KEY_VALUE><KEY_VALUE name="TITLE" category="MortgageProtection">Ms</KEY_VALUE>

<OR></AND>

</CUSTOMER_KEYS>

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

Sample

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

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

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


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

</PHASE><AND />

76


<PHASE><DOC_NAME><VALUE>*</VALUE>

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

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

</TIMESTAMP></PHASE>

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

</ORDERBY></SEARCHCRITERIA>

The createDocumentItem Method

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

• Selection of optional paragraphs

• Editing of the document

• Adding an annotation

• Updating the primary variables of the document

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


Note: If you create a large number of work items with this Web Service and encounter errors becausetoo 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 wascreated within the application specified in the Request Context. If the method fails, it returns a SOAPFault that indicates the reason for the failure.

Syntax

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

77


Parameters








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


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

assignToUserName : String

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

The getDocumentItemInfo Method

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

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

78


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

• External Contents— A list of all external content in the document. For each piece of externalcontent, this method reports the external content name, the external content type, the URL of thelink to the external content, and the location of the external content. If the external content wasadded 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 currentlyassigned to the work item (owner), the work item user who created the work item (user), thework item category, the customer key used to create the work item, the time and date of thelast modification to the work item, the ASL ID (which is used to retrieve information about thework item), the current status and state of the work item, the publisher type, and an indicationif the work item is locked.

• History— Shows the history of the work item, including when it was created, submitted,approved, and rejected. For each state, it reports the action, the user, the user who is currentlyassigned 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 eachoptional paragraph group, the group type, and whether or not it is configured for handlingin batch. It also lists all the optional paragraphs in the optional paragraph group, listing thename, ID, an indication that the optional paragraph is shared or not, an indicator if the optionalparagraph is selected or not, and the version number.

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

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

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

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

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

79


Syntax

String documentItemInfoXML = getDocumentItemInfo (requestContext,documentItemIDs, infoToReturn)

Parameters







documentItemIDs : String[]

An array of unique identifiers for document items.

infoToReturn : String[]

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

• “ASL”

• “Document”

• “ExternalContents”

• “General”

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

• “OptionalParagraphs”

• “RevisionUnits”

• “Variables”

• “WIPChangeHistory”

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

80


Examples

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

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

</ASL><Document><Name>Auto Policy</Name><Category>Auto</Category><CustomerKey>1</CustomerKey><PublisherType>xPublish</PublisherType></Document><ExternalContents><ExternalContent><Name>externalPDF</Name><Type>PDF</Type><Link>/external/Strat.pdf</Link><From>file</From></ExternalContent></ExternalContents><General><User>tester</User><Owner>tester</Owner><Category>StringsOfVariables</Category><CustomerKeys>1</CustomerKeys><Modified>2010-03-29T09:59:21</Modified><ASL_ID>8912</ASL_ID><Status>Pending</Status><State>Active</State><PublisherType>2</PublisherType><LockingState><Locked>False</Locked></LockingState></General><Audit><Action action="Checked in" user="tester" datetime="2010-03-29T09:59:22"/>Workflow submitter="tester" currentowner="tester" currentstate="Active"datetime="2010-03-29T10:03:46"/>

</Audit><OptionalParagraphs><OptionalParagraphGroup name="StringsofVariables_Multiple" selection="multi"handlingInBatch="none"><OptionalParagraph><Name>Word_Variable_Field/Name><Id>8643</Id><Shared>false</Shared><Selected>false</Selected><Version>1.00</Version></OptionalParagraph>/OptionalParagraphGroup></OptionalParagraphs>

81


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

The publishAndReturnDocumentItem Method

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

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

82


Syntax

MultiStrea multistream = publishAndReturnDocumentItem(requestContext, documentItemID,outputProfileName)

Parameters







83


documentItemID : String

The unique identifier for the document item.



The publishAndReturnDocumentMultipleStreamMethod

The publishAndReturnDocumentMultipleStream web service method enables you to publish adocument work item to an output profile using multiple streams. This method works identicallyto the QuickDoc web service method publishAndReturnDocumentMultipleStream, except thatthe document generated comes from a document work item instead of customer data. In order tosuccessfully return the document to your calling application, the output profile you specify mustcontain an output stream whose distribution definition is defined with the “Return to CallingApplication” option.

If no output streams are defined with a distribution definition marked as “Return to CallingApplication”, the method will return a zero length byte array when such documents are successfullypublished. If more than one output stream contains a distribution definition marked as “Return toCalling Application”, this method returns all the document data associated with those streams.





84


Syntax

MultiStrea multistream = publishAndReturnDocumentMultipleStream(requestContext, workItemId,outputProfileName, includeMetaData)

Parameters







workItemID : String




includeMetaData : Boolean

If set to true, this method will also return the Generic Index metadata file. The metadata file is anXML 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 UserGuide 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 documentitems assigned to a given user. You can return information about these document items through asubsequent Web Service call by using the document item IDs returned from this method as inputinto the documentItemInfo method.

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

85


Syntax

String[] documentItemIDs = documentItemsAssignedToUser(requestContext, userName)

86


Parameters







userName : String

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

The reassignDocumentItemToUser Method

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

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

Syntax

String successMessage = reassignDocumentItemToUser (requestContext,documentItemID, assignToUserName)

Parameters



87









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

The updatePrimaryVariables Method

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

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

Syntax

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

Parameters







88




primaryVariableInfo : String

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

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

The copyDocumentItem Method

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

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

Syntax

String newDocumentItemId = copyDocumentItem (requestContext, documentItemID,assignToUserName)

89


Parameters








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


The username to which you will assign the work item.

The addExternalContentByLink Method

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

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

Syntax

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

Parameters



90








ruName : String

The name for the external content Revision Unit.

externalContentLink : String

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

<drive>\<path>\<filename>

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

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

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

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

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

format : String

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

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

• “.tif”

position : String

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

options : String

91


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

addExternalContentByStream

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

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

Syntax

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

Parameters









ruName : String

The name for the external content Revision Unit.


Supply the byte array for the external content.

format : String

92


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

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

• “.tif”

position : String

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

options : String

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

The reorderExternalContent Method

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

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

Syntax

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

Parameters







93




externalContentID : String

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

targetPosition : String

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

The addAnnotation Method

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

Syntax

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

Parameters









94


annotationInfo : String

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

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

</Annotation></Annotations>

The deleteExternalContent Method

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

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

Syntax

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

Parameters









externalContentID : String

95


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

The createAuthenticationToken Method

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

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

Syntax

String tokenID = createAuthenticationToken(String requestContext, long timeout)throws AxisFault;

Parameters







timeout : String

The number of milliseconds that the token should be active.

The complete DocumentItem Method

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

96


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

Syntax

String successMessage = completeDocumentItem (requestContext, documentItemID)

Parameters








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

The deleteDocumentItem Method

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

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

Syntax

String successMessage = deleteDocumentItem (requestContext, documentItemID)

97


Parameters








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 adocuments. For example, to present relevant portions for review to a specialist for review or topublish different portions of the document to different output channels.

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

Syntax

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

Parameters



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

98



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

ruNames:String[]

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

addTitles:String

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

opName:String

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

The setCarryForwardDocumentItem Method

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

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

Syntax

String setCarryForwardDocumentItem (requestContext, documentItemID, CFCompareID)

Parameters


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





99


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

CFCompareID : String

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

The clearCarryForwardDocumentItem Method

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

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

Syntax

String clearCarryForwardDocumentItem (requestContext, documentItemID)

Parameters






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 specifiedRevision Unit variables. If the method fails, it returns a SOAP Fault that indicates the reason forthe failure.

100


Syntax

updateRUVariables(requestContext, documentItemID, ruVariableInfo)

Parameters








ruVariableInfo : String

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

The submitDocumentItem Method

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

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

Syntax

String submitDocumentItem (requestContext, workflowState, documentItemID)

101


Parameters






workflowState : String[]

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


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

The approveDocumentItem Method

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

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

Syntax

String approveDocumentItem (requestContext, documentItemID)

Parameters



102






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

The rejectDocumentItem Method

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

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

Syntax

String rejectDocumentItem (requestContext, documentItemID)

Parameters







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

103


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

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

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

Parameters

Required Parameters:

TOK

A valid user token generated by calling The createAuthenticationToken Method, page 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 xReviseweb applications. This URL is needed so that xEditor can locate the private web services it uses tocommunicate with the server. The syntax is:http://<server_name>:<port_number>/xRevise

CNF

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

Optional Parameters:

INSTL

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

CID

104


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

Samples

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

Starting xEditor the First Time

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

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

• is ready to use

• is the appropriate version

• presents the correct feature set

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

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

105


106

Chapter 6xCatalog 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 tothe 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 MethodThis 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 inthe xCatalog system.

Syntaxpublic java.lang.String getCatalogInfo(java.lang.String requestContext)

Parameters



107

xCatalog Web Service

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

• your customer application name


Sample Returned Document

The following is a sample of returned XML from this method.<?xml version="1.0" encoding="UTF-8"?><CatalogInfo><Tags><Tag Name="Bureau" IsParent="true" IsRequired="true" IsDefault="false"><Tag Name="Independent" IsParent="false" IsRequired="false"IsDefault="false"/><Tag Name="ISO" IsParent="false" IsRequired="false" IsDefault="true"/></Tag><Tag Name="Line of Business" IsParent="true" IsRequired="false"IsDefault="false"><Tag Name="Boiler & Machinery" IsParent="false" IsRequired="false"IsDefault="false"/><Tag Name="Businessowners" IsParent="false" IsRequired="false"IsDefault="false"/>

</Tag><Tag Name="State" IsParent="true" IsRequired="false" IsDefault="false"><Tag Name="AK" IsParent="false" IsRequired="false" IsDefault="false"/><Tag Name="AL" IsParent="false" IsRequired="false" IsDefault="false"/><Tag Name="AR" IsParent="false" IsRequired="false" IsDefault="false"/><Tag Name="AZ" IsParent="false" IsRequired="false" IsDefault="false"/></Tag></Tags><CustomFields><CustomField Name="Contact" Label="Contact" Default="Charlie"/><CustomField Name="Workflow" Label="Workflow" Default="Approved"/></CustomFields></CatalogInfo>

The searchForDocuments MethodThis method enables you to search for and return information about specified documents. You cansearch for documents based on criteria such as document name, document description, documentstatus and more. You can refine the resulting list of documents by using criteria to further refine yoursearch. There are two types of search criteria: Simple search and Advanced searches. In Simplesearches, multiple occurrences of the same criteria types are treated with an OR condition. InAdvanced searches, the relationships between multiple occurrences of the same criteria types can beeither AND or OR condition. The following list shows all the criteria types:

• Name

• Date

• Unique_ID

108


• Description

• Status

• Custom_Field

• Content

• Tag

Simple Search Criteria

To define simple search criteria, you supply an XML formatted string in the searchCriteria parameterof the Web Service method. In the following XML example, we are searching for forms whose namecontains “WC”, description contains “Declaration”, content contains the string, “liability”, variablename contains “Address”, and that has a tag named “CA” in the “State” tag folder.<Search><Name>WC</Name><Description>Declaration</Descripton><Content>liability</Content><Variable>Address</Variable><Tag>State::CA</Tag></Search>

Multiple occurrences of the same filter type are treated with an OR condition. However, the <Tag>element operates under different rules. Multiple <Tag> elements for the same folder name use the ORcondition, but multiple <Tag> elements using different folders use the AND condition. For example:<Search><Tag>Line of Business::Homeowner</Tag><Tag>Line of Business::Property</Tag><Tag>State::CA</Tag><Tag>State::FL</Tag></Search>

This search is looking for forms with either the “Homeowner” or “Property” tag in the Line ofBusiness folder and either the “CA” or “FL” tags in the State folder. Written as a mathematicalstatement, 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 searchCriteriaparameter of the Web Service method. The XML format for advanced searches is different than theformat for simple searches. In an advanced search, you must explicitly specify the relationshipbetween the search strings. You can do that by using the <Operator> element to apply parenthesis (),AND, and OR. For example:<AdvancedSearch><Name><Operator>(</Operator><Value>WC</Value><Operator>or</Operator><Value>HO</Value><Operator>)</Operator>

109


</Name></AdvancedSearch>

110


If you have only a single value in a search category, you can simplify the XML by excluding theOperator element.<AdvancedSearch><UniqueID><Value>DSC</Value></UniqueID></AdvancedSearch>

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.<AdvancedSearch><Name><Value>WC</Value></Name><UniqueID><Value>DSC</Value></UniqueID></AdvancedSearch>

If you using the Date category for your search, you can use only one <StartDate> and <EndDate>element for each search. For example:<AdvancedSearch><Date><StartDate>2008-11-20</StartDate><EndDate>2008-12-20</EndDate></Date></AdvancedSearch>

Syntaxpublic 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






111


searchCriteria : String

The search criteria in XML format. For example:<Search><Name>WC</Name><Date>2008-11-20</Date><Unique_ID>DSC</Unique_ID><Description>Declaration</Description><Content>liability</Content><Variable>Address</Variable><Tag>My Favorite::NCCI</Tag><Tag>State::CA</Tag></Search>

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 haszero strings then all information will be queried and returned in the XML document. You may giveany of these Strings as input into the method:• “Document”

• “Description”

• “Status”

• “Category”

• “Tags”

• “Notes”

• “Custom_Fields”

The getDocumentInfo MethodThis method enables you to retrieve information about the specified document(s). The methodreturns 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 canbe in XML or CSV format.

112


Syntaxpublic 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






docNames : String

The names of the document(s). This method will create a report with the requested informationfor 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 haszero strings then all information will be queried and returned in the XML document. You may giveany of these Strings as input into the method:• “Document”

• “Description”

• “Status”

• “Category”

• “Tags”

113


• “Notes”

• “Custom_Fields”

114

Chapter 7Output Statistics Reporting

The output statistics reporting web services give you the ability to return page count statistics aboutany documents published within a specified date range. This information is of interest to licenseholders with usage-based licenses. Statistics are specific to the server, so activity on a developmentserver is not considered in the report for the production server. Usage limits apply to productionservers only, but the information is available on non-production servers as well to assist with usageplanning. 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 asone page of output. However, more pages will be counted if the document contains a subdocumentwhich requires conversion to an image in order to be included in the output. In this case, the pages ofthe 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 countedwhen batch processes the document from the batch queue. The act of placing the document inthe queue is not counted.

Output Statistics Report DetailsThe output statistics report is returned in an XML format. There are two types of reports, eachreturning a different level of information:• Summary— This type of report returns information about how many pages were produced oneach date in the date range. The pages are also identified by how they were published, providingnumbers for batch, transactional, and API published pages. See Summary Report Content, page117 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 ReportContent, page 118 for more information.

116


Summary Report Content

A Summary report identifies the number of pages produced during the specified date range. Thepages 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.<OutputStatistics><Summary customerID="cust" customerName="" startDate="2012-06-14"endDate="2012-06-14" totalPageCount="6"/><Report date="2012-06-14">

<Batch pages="2"/><Transaction pages="2"><xResponse pages="0"/><xRevise pages="2"/>

</Transaction><Api pages="2">

<DocumentRequesterService pages="0"/><xResponseDocumentRequestService pages="0"/><xAdapterXPressionRequestService pages="2"/><QuickDocService pages="0"/><xPressionRequest pages="0"/><xResponseRequest pages="0"/><xReviseRequest pages="0"/><xDevKit pages="0"/><JFramework pages="0"/>

</Api></Report>

</OutputStatistics>

A Summary report contains the following elements:

Summary

This element identifies the values you defined for the creation of the report, and also provides thetotal 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


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 Reportelement are three additional elements identifying the pages produced through batch, transactionalapplications, and APIs.• Batch— This element identifies the number of pages produced through batch.

• Transaction— This element identifies the total number of pages produced through xResponseand xRevise. Sub-elements identify the pages produced through each individual application.

• Api — This element identifies the total number of pages produced through xPressionAPIs 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 alsoincludes 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 <Run> element that identify the specificbatch job used. Like a summary report, the Batch element contains a “pages” parameter that showsthe number pages generated through batch. For each batch job returned, the report will includethe following information:• Run — Identifies a batch run. The Batch element can contain one or more of these elements. Thiselement 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:<Batch pages="8">

<Run start="00:48:11" end="00:48:21" job="jobname" runId="1462009" op="PDF"status="Success" pages="8" />

118


</Batch>

Transaction Details

For transactional applications, this report provides additional information about the transaction inthe <xResponse> or <xRevise> elements. Like a summary report, the Transaction element contains a“pages” parameter that shows the number pages generated through transactional applications. Foreach 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 ormore 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 xResponseand xRevise work items contain this information.



— pages — The number of pages published by the transaction.

For example:<Transaction pages="3">

<xResponse pages="0"/><xRevise pages="3">

<Publish time="00:49:35" user="root" doc="docname" docVersion="20010401"op="PDF" status="Success" pages="3" />

</xRevise></Transaction>

API and Web Services Details

For API and web services, this report provides additional information about the API call. Likea summary report, the API element contains a “pages” parameter that shows the number pagesgenerated through the API. For each document published through an API or web service, the reportwill include an element for each of the API and Web Service calls that are monitored. These elementscontain a “pages” parameter which identifies the number of pages generated through that method.The method elements are:• DocumentRequesterService

• xResponseDocumentRequestService

• xAdapterXPressionRequestService

• QuickDocService

119


• 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 morethan 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.



— pages — The number of pages published by the API or web service.

For example:<Api pages="2">

<DocumentRequesterService pages="0"/><xResponseDocumentRequestService pages="0"/><xAdapterXPressionRequestService pages="32">

<Call time="00:16:53" user="test" doc="docname" docVersion="null" op="null"status="Failure" pages="0" /><Call time="00:47:59" user="test" doc="docname" docVersion="20010101"op="PDF" status="Success" pages="2" />

</xAdapterXPressionRequestService><QuickDocService pages="0"/><xPressionRequest pages="0"/><xResponseRequest pages="0"/><xReviseRequest pages="0"/><xDevKit pages="0"/><JFramework pages="0"/>

</Api>

Sample Summary and Details Report

Below you will find a sample Summary and Details report.<OutputStatistics><Summary customerID="cust" customerName="" startDate="2012-06-14"endDate="2012-06-14" totalPageCount="6"/>

<Report date="2012-06-14"><Batch pages="2">

<Run start="00:48:11" end="00:48:21" job="jobname" runId="146200"op="PDF" status="Success" pages="2" />

</Batch><Transaction pages="2">

<xResponse pages="0"/><xRevise pages="2">

<Publish time="00:49:35" user="root" doc="docname"

120


docVersion="20010401" op="PDF" status="Success" pages="2" /></xRevise>

</Transaction><Api pages="2">

<DocumentRequesterService pages="0"/><xResponseDocumentRequestService pages="0"/><xAdapterXPressionRequestService pages="2"><Call time="00:16:53" user="test" doc="RI_MAINT_LETTERS" docVersion="null"op="PDF" status="Success" pages="2" />

</xAdapterXPressionRequestService><QuickDocService pages="0"/><xPressionRequest pages="0"/><xResponseRequest pages="0"/><xReviseRequest pages="0"/><xDevKit pages="0"/><JFramework pages="0"/>

</Api></Report>

</OutputStatistics>

Output Statistics Reporting Web ServicesBefore attempting to generate an output statistic report, ensure that you have configured the reportinglevel of your server in xDashboard. You must specify which level of reporting you want xPressionto capture on this server. The server will not capture output statistics data until this setting isconfigured. Once configured, xPression will capture data for all documents subsequently publishedby xPression. See the xDashboard User Guide for more information. EMC Document Sciences providesthe 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://<xpression_server>:<port>/xFramework/services/PublishingReport?wsdl

getSummaryPublishingReport

Use this method to get a Summary level report. This method returns a byte array representing theXML formatted report. If the method fails, it returns a SOAP Fault that indicates the reason forthe failure.

Syntax

String getSummaryPublishingReport = getSummaryPublishingReport(requestContext,startDate, endDate)

121


Parameters


An XML document that passes user credentials for authentication. In most cases it also passes thename of the application for which the user is authenticated. For this method, you do not needto supply ApplicationName information. Do not include the ApplicationName element in yourrequestContext XML file. The only users authorized to use this Web Service are those who areauthorized to access the xDashboard Server Management page. Access is granted through thexAdmin User Management page. All the credentials types (Unencrypted userid/password, Weakencrypted userid/password and Trusted UserID/Groups) are supported. The xpressionsa superadministrative user cannot be authenticated for this Web Service using Trusted UserID and Groupsauthentication. 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 informationbased on the documents published during this date range. Dates should be supplied in the followingformat: yyyy-mm-dd.

endDate : String

The ending date of the date range used to create the report. The report will provide informationbased on the documents published during this date range. Dates should be supplied in the followingformat: yyyy-mm-dd.

getDetailedPublishingReport

Use this method to get a Summary and Detail level report. This method returns a byte arrayrepresenting the XML formatted report. If the method fails, it returns a SOAP Fault that indicates thereason for the failure.

Syntax

String getDetailedPublishingReport = getDetailedPublishingReport(requestContext,startDate, endDate)

122


Parameters



startDate : String


endDate : String


getCompressedSummaryPublishingReport

Use this method to get a Summary level report compressed in a zip file. This method returns a bytearray representing the XML formatted report in a zip file. If the method fails, it returns a SOAPFault that indicates the reason for the failure.

Syntax

byte[] getCompressedSummaryPublishingReport =getCompressedSummaryPublishingReport(requestContext, startDate, endDate)

Parameters


An XML document that passes user credentials for authentication. In most cases it also passes thename of the application for which the user is authenticated. For this method, you do not needto supply ApplicationName information. Do not include the ApplicationName element in yourrequestContext XML file. The only users authorized to use this Web Service are those who areauthorized to access the xDashboard Server Management page. Access is granted through thexAdmin User Management page. All the credentials types (Unencrypted userid/password, Weak

123


encrypted userid/password and Trusted UserID/Groups) are supported. The xpressionsa superadministrative user cannot be authenticated for this Web Service using Trusted UserID and Groupsauthentication. For more information, see About the requestContext Parameter, page 26.

124


startDate : String


endDate : String


getCompressedDetailedPublishingReport

Use this method to get a Summary and Detail level report compressed in a zip file. This methodreturns a byte array representing the XML formatted report in a zip file. If the method fails, it returnsa SOAP Fault that indicates the reason for the failure.

Syntax

byte[] getCompressedDetailedPublishingReport =getCompressedDetailedPublishingReport(requestContext, startDate, endDate)

Parameters



startDate : String


endDate : String


125


clearDetailPublishingReport

This method enables you to delete data from a defined date range. It deletes only the detailed portionof the captured data. The summary data is never deleted. Additionally, you cannot delete data fromthe current day. Ensure your date range does not contain today’s date.

Syntax

void clearDetailPublishingReport =clearDetailPublishingReport(requestContext, startDate, endDate)

Parameters



startDate : String

The starting date of the date range that you want to delete report details. xPression will clear thedetailed information for all documents published during this date range. Dates should be supplied inthe following format: yyyy-mm-dd.

endDate : String

The ending date of the date range that you want to delete report details. xPression will clear thedetailed information for all documents published during this date range. Dates should be supplied inthe following format: yyyy-mm-dd.

126

Chapter 8xPressForms Web Services forReporting

The xPressForms Web Service for reporting contains the following methods: Get Report, Get Reportfor Fields, Search for Forms, Search for Forms Customized View, and Get Search Field List. TheURL 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 MethodThis method returns a report on the specified documents.

SyntaxgetReport("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 documentname. 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


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 specificdocuments.

getReport(“document1, document2, document3”, “XML”, “username”, “password”)

Get Report For Fields MethodThis method returns a report for certain fields (XML element names) in specified documents. Themethod will only return information about the specified fields in the specified document. You canspecify more than one document name and more than one field. The document names are separatedby a comma and enclosed in quotes. The field names are also separated by a comma and enclosedin quotes.

SyntaxgetReportForFields("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 documentname. 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


password: String


The following example shows the method creating an XML formatted report for three specificdocuments.

129


getReport(“document1, document2, document3”, “XML”, “Form, Description, Status, Object_Type”)

Search for Forms MethodReturns a report on forms that contains an XML report with all requested fields. You can search forforms 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 refinethe resulting list. You can implement either a simple search or an advanced search. The followingare 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 bethrown back to caller.


To define simple search criteria, you supply an XML formatted string in the “criteria” parameter ofthe Web Service method. In the following XML example, we are searching for forms whose namecontains “WC”, description contains “Declaration”, content contains the string, “liability”, variablename contains “Address”, and that has a tag named “CA” in the “State” tag folder.<Search><Name>WC</Name><Description>Declaration</Descripton><Content>liability</Content><Variable>Address</Variable><Tag>State::CA</Tag></Search>

130





To define advanced search criteria, you supply an XML formatted string in the “criteria” parameterof the Web Service method. The XML format for advanced searches is different than the format forsimple searches. In an advanced search, you must explicitly specify the relationship between thesearch strings. You can do that by using the <Operator> element to apply parenthesis (), AND,and OR. For example:<AdvancedSearch><Name><Operator>(</Operator><Value>WC</Value><Operator>or</Operator><Value>HO</Value><Operator>)</Operator></Name></AdvancedSearch>


131




SyntaxsearchForForms("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


username: String


password: String


Search for Forms Customized View MethodReturns a report with specified fields on forms that satisfy the search criteria. The search criteria andformat are same as the searchForForms method. The formats of the parameter fields and the resultingreport are the same as the getReportForFields method.

132


You can search for forms based on form name, form description, pieces of form content, variablescontained in the form, and tags associated with the form. You can add multiple filter criteria to yoursearch to further refine the resulting list. You can implement either a simple search or an advancedsearch. 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)


To define simple search criteria, you supply an XML formatted string in the “criteria” parameter ofthe Web Service method. In the following XML example, we are searching for forms whose namecontains “WC”, description contains “Declaration”, content contains the string, “liability”, variablename contains “Address”, and that has a tag named “CA” in the “State” tag folder.<Search><Name>WC</Name><Description>Declaration</Descripton><Content>liability</Content><Variable>Address</Variable><Tag>State::CA</Tag></Search>



133



To define advanced search criteria, you supply an XML formatted string in the “criteria” parameterof the Web Service method. The XML format for advanced searches is different than the format forsimple searches. In an advanced search, you must explicitly specify the relationship between thesearch strings. You can do that by using the <Operator> element to apply parenthesis (), AND,and OR. For example:<AdvancedSearch><Name><Operator>(</Operator><Value>WC</Value><Operator>or</Operator><Value>HO</Value><Operator>)</Operator></Name></AdvancedSearch>




SyntaxsearchForForms("String criteria", "String format", "String fields","String username", "String password")

134


Parameters

criteria : String

The search criteria in XML format. See Simple Search Criteria , page 133 and Advanced SearchCriteria, page 134.

format : String


fields: String

The XML element names that this report will include. This value is case sensitive.

username: String


password: String

The password for the xPressForms username.

For example, with the following XML search criteria:

Get Search Field List MethodxDesign uses the getSearchFieldList web service to implement the xPressForms connectivity feature.getSearchFieldList returns all searchable fields and tags in the XML form.

SyntaxString 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 fielddescription. Name attribute has field name that will be used when calling searchForForms.

135


Deprecated xPressForms Web ServicesThe getCategory, getCategories, and isAvailable web services have been deprecated.

136

Chapter 9xPression RESTful Services for Batch

xPression provides a set of RESTful services and an embedded daemon process which can be calledand tasked with processing your job requests. This configuration enables you to run batch serviceswithout 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 aparticular 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 theprovided calling application RESTful services. The services will query the needed informationfrom the xPression Repository and queue the job for batch processing. When sending requeststhrough RESTful HTTP POST protocol to the provided calling application, you must add theRequest.ContentType = "application/xml" command in the C# client.

When queued, xPression sets the job Status to –1, which means the job is “Not Started”. WhenxPression selects a queued job for processing, the xPression Server “checks out” the job from thequeue, 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”. Whenthe job completes, the Status is 1. xPression sends a completion event to the owner listener, whichreports 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 upindividually 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 stringformat. All other returns are in XML format.

Note: The request ID is different from the job history ID in the xDashboard.

RESTful HTTP Body StructureFor all HTTP requests, the body root element is XServicesRequest, which is followed by<RequestContext> sub-elements. Each request must include the General.security element at the top toauthenticate the request. The body of the RESTful Web Services uses the following structure:<XServicesRequest><RequestContext function="General.security"><Credentials method="UserID and Password"><UserID> </UserID><Password> </Password></Credentials><ApplicationName>xPression Batch</ApplicationName>

137

xPression RESTful Services for Batch

</RequestContext>

138


The General.security element authenticates your request. It can be followed by additional elementsthat provide information to your service. For example:<RequestContext function="Job.status"/><Item ref="queueID"> </Item><ReturnInfo>statistics with details</ReturnInfo></RequestContext></XServicesRequest>

Note: The value of <ReturnInfo> 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 ElementThe General.security element is required for all RESTful services. This element enables you toprovide user credentials to the service.

A RequestContext element for General.security contains the following parameters:<RequestContext function="General.security"><Credentials method="UserID and Password"><UserID>xpression</UserID><Password>xpression</Password></Credentials><Credentials method="Trusted UserID and Groups"><UserID>xpression</UserID><Group>Administrator</Group></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext>

The <Credentials> element identifies the method of authorization. Valid values are “UserIDand Password” and “Trusted UserID and Groups”. Both of these methods are authenticated bycomparing the value you or your xPression administrator supply to the key/values defined in theBatchRunner.properties file. xPression Batch web services users, please contact your xPressionadministrator if you have problems with authorization. All other xPression users, please seeAuthorization, page 139 for more information about configuring authorization.

The ApplicationName element identifies the application for which the user is authorized. InxPression, users are given access rights to specific applications because each application has a differentset of access rights. By specifying the application name, you are requesting the access rights granted tothe 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 problemswith authorization. For all other xPression users, use the following steps to set up trusted userIDs 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


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}


The Job.start.xml and Job.start ElementsThe Job.start.xml and Job.start RequestContext elements enable you to start a batch job. TheJob.start service (/xFramework/restful/services/job/start) enables you to run a job already defined inxDashboard. The Job.start.xml service (/xFramework/restful/services/job/start/xml) enables you tocreate and start a new job by supplying XML inline with the request. Both elements use the samesub-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, page152 and Start a Batch Job with a Job Definition XML File, page 153. These elements contain thefollowing 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, page155. 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 JobDefinition as it exists in xDashboard. If you are using “Job.start.xml”, the value for this parametershould 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 syntaxof an XML job definition, see “Manually Creating Your Job Definition” in the xPression BatchProcessing Guide.

140


The JobOption Element

This element enables you to implement the job options available through command line batchprocessing parameters in xPression. None of these options are required. Please see the xPression BatchProcessing Guide for information about each parameter.

Note: For xPression Batch Web Services Users— xPression web services support all command lineparameters except: -r and -j. Please see your xPression administrator for assistance with setting upand supporting these Job Option parameters.

The Job.status ElementThis 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:<RequestContext function="Job.status"/><Item ref="queueID">23984759875</Item><ReturnInfo>statistics with details</ReturnInfo></RequestContext>


The queueID is the identifier for a job in the queue. For an example of this element in use, see Returnthe 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 aboutfailed customer documents.

• statistics with details — This level collects all the statistics information and customer documentinformation for all documents.

141


The ReturnInfo parameter does not specify which information the server should record, it simplyidentifies what level of information to return to the user. The Job Level parameter in your XML JobDefinition or xDashboard Job Definition determines what level of information the server records. Ifyou use ReturnInfo to request a greater level of information than the Job Level option specified, youwill not receive all of the requested information. Ensure the level of information you specify in yourJob 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 awarethat the Web Service will not always return detailed error information. If the batch process for acustomer record fails before the document can be assembled, xPression is only able to return the errormessage, but not the details of the error message. In this case, the error occurs before xPression is ableto 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 alllowercase. Values that include uppercase characters are ignored and treated as “statistics” only. To seesamples 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 ofinformation. All queries will return data in the Common element. If you selected Statistics withErrors or Statistics with Details in your ReturnInfo parameter, the Statistics with Details or Statisticswith 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 thereturned 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 berecorded 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


• 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-elementsfor each level of detail you requested through the ReturnInfo parameter. The potentialsub-elements are Common, Statistics with Details, and Statistic with Errors.

— Common — This element The Common container element contains the following basicinformation:

— 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 distributioncontroller 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 theReturnInfo parameter:• StatisticWithDetails — This element contains one DATA container element for each customerrecord processed by the batch job. Each DATA container element contains the followinginformation:— 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 = CustomDocuments.

— PublishType — The document type. 1 = xDesign, 2 = xPresso.

— Category — The name of the category that contains the xPression document being processed.

143


— 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 Detailselement, and also contains an “Error” element. The Error element reports the error messagegenerated 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

<?xml version="1.0" encoding="UTF-8"?><Response service="Job.status"><JOB name="autopay" runId="562927969793375489972281312930"processId="1318227998473" queueId="9188627960857243537972281311930"logPath="C:\xPression\logs\12122011.log"><Percentage><Step name="1">100.0</Step><Step name="2">100.0</Step>

</Percentage><State>COMPLETED</State><ReturnCode>1</ReturnCode><Statistics><Common><PublishProfile>PDF to File</PublishProfile><PublishType>2</PublishType>

<StartTime>1318228001015</StartTime><EndTime>1318228628840</EndTime><DistributionNumber>0</DistributionNumber><Error /><ReportingLevel>3</ReportingLevel>

</Common></Statistics>

</JOB></Response>

144


Completed Job with “Statistics with Details” Reporting Level

<?xml version="1.0" encoding="UTF-8"?><Response service="Job.status"><JOB name="Job_of_service_demo_autopay" runId="27039047316977285731"processId="1318230513773" queueId="142960473149279974994032"logPath="C:\xPression\logs\121220011.log"><Percentage><Step name="1">100.0</Step><Step name="2">100.0</Step>

</Percentage><State>COMPLETED</State><ReturnCode>1</ReturnCode><Statistics><Common><PublishProfile>PDF to File</PublishProfile><PublishType>2</PublishType><StartTime>1318230517569</StartTime><EndTime>1318231110411</EndTime><DistributionNumber>0</DistributionNumber><Error /><ReportingLevel>3</ReportingLevel>

</Common><StatisticsWithDetails><Data><CustomerKey>[AUTOPAY_KEY=1]</CustomerKey><Bdt>Automatic Payment Letter</Bdt><DataSource>AUTOPAY-XML</DataSource><Status>1</Status><StepName>1</StepName><StepType>1</StepType><PublishType>2</PublishType><PublishProfile>PDF to File</PublishProfile><Category>Automatic Payment Letter</Category><DSG>AUTOMATIC PAYMENT LETTER</DSG><FileName>C:/xPression/Publish/output/BatchParam.pdf</FileName><Error />

</Data></StatisticsWithDetails>

</Statistics></JOB>

</Response>

145


Stopped Job with “Statistics with Errors” Reporting Level

<?xml version="1.0" encoding="UTF-8"?><Response service="Job.status"><JOB name="Job_of_service_demo_autopay" runId="4786879064266535324784834"processId="1318087425098" queueId="34036790663478937273780483"logPath="C:\xPression\logs\121220011.log"><Percentage><Step name="1">100.0</Step>

</Percentage><State>STOPPED</State><ReturnCode>3</ReturnCode><Statistics><Common><PublishProfile>PDF to File</PublishProfile><PublishType>2</PublishType><StartTime>1318087490687</StartTime><EndTime>1318087649345</EndTime><DistributionNumber>0</DistributionNumber><Error>Error during read.</Error><ReportingLevel>3</ReportingLevel>

</Common><StatisticsWithErrors><Data><CustomerKey>[AUTOPAY_KEY=1]</CustomerKey><Bdt>Automatic Payment Letter</Bdt><DataSource>AUTOPAY-XML</DataSource><Status>2</Status><StepName>1</StepName><StepType>1</StepType><PublishType>2</PublishType><PublishProfile>PDF to File</PublishProfile><Category>Automatic Payment Letter</Category><DSG>AUTOMATIC PAYMENT LETTER</DSG><FileName /><Error>EJB Exception: ; nested exception is:java.lang.NullPointerException</Error></Data>

</StatisticsWithErrors></Statistics>

</JOB></Response>

146


Job That is Not Started

This sample shows returned data for a job that has not yet started.<?xml version="1.0" encoding="UTF-8"?><Response service="Job.status"><JOB name="autopay" queueId="0746075749651328087006081311431"><ReturnCode>-1</ReturnCode>

</JOB></Response>

Job That is Still Running

<?xml version="1.0" encoding="UTF-8"?><Response service="Job.status"><JOB name="autopay" runId="2043485266181832196406971312621"processId="1317960470123" queueId="3327685261861499956406971311621"logPath=""><Percentage><Step name="1">100.0</Step><Step name="2">100.0</Step>

</Percentage><State>RUNNING</State><ReturnCode>0</ReturnCode><Statistics><Common><PublishProfile>PDF to File</PublishProfile><PublishType>2</PublishType><StartTime>1317960478623</StartTime><EndTime /><DistributionNumber /><Error /><ReportingLevel>3</ReportingLevel>

</Common></Statistics>

</JOB></Response>

The Job Queue All ElementThis element is used for the /jobs/queue/all service: Return a List of all Queued Jobs, page 150. Thiselement enables you to filter the results of the query by the status of the job. This element and theGeneral.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


<RequestContext function="Job.queue.all"><Filter><Status>-1,0</Status></Filter></RequestContext>

The Filter element can only contain one Status element. The Status element defines which statuslevels 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 thereturned 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, thexPression Server “checks out” the job from the queue, ensuring that no other xPression Servercan process the same job. The server that “checks out” the job is the “Owner”. While the job ischecked out, the status is 0, which means it is “Started”. When the job completes, the Status is1. xPression sends a completion event to the owner listener, which reports the event to yourbatch 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


This data is returned in the following format:<Response service="Job.queue.all"><JOB><Name>autopay</Name><Status>1</Status><RunID>3969401362522230860562071312531</RunID><QueueID>2685201361864770579462071311531</QueueID></JOB><JOB><Name>Job2</Name><Status>1</Status><RunID>1966463550093566940132071314531</RunID><QueueID>2969915873062562401369071313531</QueueID></JOB></Response>

Return a List of all Job NamesTo query xPression for a list of all existing Job names, use the following service URL and supply usercredentials through the General.security element in the service body.

Service URL:http://<your_server>:<your_port>/xFramework/restful/services/jobs/all/list/names

Service Body:<XServicesRequest><RequestContext function="General.security"><Credentials method="UserID and Password"><UserID>xpression</UserID><Password>[email protected]</Password></Credentials>

<Credentials method="Trusted UserID and Groups"><UserID>xpression</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext></XServicesRequest>

For specific about the General.security syntax and options, see The General.security Element, page139.

This service will return a list of all job names. The data is returned in the following format:<Response service="Job.list.all"><Item key="JobName">Notices</Item><Item key="JobName">Notices2</Item><Item key="JobName">autopay</Item></Response>

149


Return a List of all Queued JobsTo query xPression for a list of all currently queued jobs, use the following service URL, supplyuser credentials through the General.security element, and optionally filter the results with theJob.queue.all element in the service body.

Service URL:http://<your_server>:<your_port>/xFramework/restful/services/jobs/queue/all


<Credentials method="Trusted UserID and Groups"><UserID>xpression</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext><RequestContext function="Job.queue.all"><Filter><Status>-1,0</Status></Filter></RequestContext></XServicesRequest>

For specific information about the General.security syntax and options, see The General.securityElement, page 139. For specific information about filtering your results with the Job.queue.all, see TheJob Queue All Element, page 147 for more information. To see a sample of the returned informationfor this service, see Returned Information, page 148.

Return a List of all Running JobsTo query xPression for a list of all currently running jobs use the following service URL and supplyuser credentials through the General.security element.

Service URL:http://<your_server>:<your_port>/xFramework/restful/services/jobs/running/list


<Credentials method="Trusted UserID and Groups"><UserID>xpression</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext>

150


</XServicesRequest>

For specific about the General.security syntax and options, see The General.security Element, page139.

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 thereturned 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:<Response service="Job.list.running"><JOB><Name>autopay</Name><RunID>4258863931015641131191138131693</RunID><JobId>20</JobId><StartTime>1318311946941</StartTime><Distribution>null</Distribution></JOB></Response>

Return the Status of a Particular JobTo query xPression for the status of a particular job use the following service URL, supply usercredentials through the General.security element, and define your job status query in the Job.statuselement. Web services supports the return of a single job status only; multiple web service calls arerequired for multiple jobs.

151


Service URL:http://<your_server>:<your_port>/xFramework/restful/services/job/status


<Credentials method="Trusted UserID and Groups"><UserID>xpression</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext><RequestContext function="Job.status"><Item ref="queueID">4366817659012001047974313115310</Item>

<ReturnInfo>statistics with details</ReturnInfo></RequestContext></XServicesRequest>


For specific information about the syntax and options available to the General.security and Job.statuselements, see The General.security Element, page 139 and The Job.status Element, page 141. To viewsample returned data, see Sample Responses for Job.Status, page 144.

Start a Batch Job with an Existing JobDefinitionTo start a batch job with an existing Job Definition use the following service URL, supply usercredentials through the General.security element, and define the job definition in the Job.start element.

Service URL:http://<your_server>:<your_port>/xFramework/restful/services/job/start


<Credentials method="Trusted UserID and Groups"><UserID>xpression</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext><RequestContext function="Job.start"><Job version="2.0" name="BES_Notices"><JobOption>-o C:\CustomerData\BILS.xml</JobOption>

152


</Job></RequestContext></XServicesRequest>

For specific information about the syntax and options available to the General.security and Job.startelements, 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 FileTo create and start a new job by supplying a manually created Job Definition XML file, use thefollowing service URL, supply the user credentials in the General.security element, and supplythe job definition information in the Job.start.xml element. For more information about creating aJob Definition file and the parameters displayed below, please see “Manually Creating Your JobDefinition” in the xPression Batch Processing Guide.

Service URL:http://<your_server>:<your_port>/xFramework/restful/services/job/start/xml


<Credentials method="Trusted UserID and Groups"><UserID>xpression</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext><RequestContext function="Job.start.xml"><Job version="2.0" name="BES_Notices_New1"><xPressionPublishJob outputProfileName="BES_Notices"

deletePreviousJobsFirst="no" threadPoolSize="4"preserveDataInputOrder="true" nextTasksNumber="" jobLevel="3">

<Instantiate invalidCustomerRecordOutputFile="" errorRecordsPath=""errorRecordsFile="" enableErrRecordsOutput="" assembleDataSource="BILS.xml"SQL="SELECT * FROM PRIMARY_TABLE"doAutoCustomization="no" useAs="collection"persistAfterJob="no" name="BES_Notices">

<UseBDT BDTName="BES_Notices" /><Parameters><Parameter name="PRIMARY_POLICY_NUMBER" value="$PRIMARY_POLICY_NUMBER"dtype="string" /><Parameter name="BILL_COUNTER" value="$BILL_COUNTER" dtype="string" /><Parameter name="STATUS" value="Any" dtype="string" /><Parameter name="optionalObjectsMode" value="3" dtype="integer" /></Parameters></Instantiate><JobLog logLevel="INFO" logPath="C:\xPression41"

logFile="Job_BES_Notices{JobRunID}.log"errorThreshold="100"appendToExisting="no" />

</xPressionPublishJob><JobOption>-ignoreDebug</JobOption></Job>

153


</RequestContext></XServicesRequest>

For specific information about the syntax and options available to the General.security and Job.startelements, see The General.security Element, page 139 and The Job.start.xml and Job.start Elements,page 140.

Configuring xPression for RESTful BatchServicesYour can configure the daemon process according to your needs and its capabilities. Youradministrator can also customize the configuration of xPression batch processing. See the followingtopics:• 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 jobsconcurrently in the batch queue. xPression Batch web services users, please contact your xPressionadministrator to configure xPression for concurrent processing. All other xPression users, completethe following steps:

1. On the server where you want to enable concurrent batch processing, navigate to thexPressionHome directory.

2. Open BatchRunner.properties for editing.

3. Locate the ServiceBatchThreadSize property. If this property does not exist, please add it.

154


4. Set the value of this parameter to the number of concurrent jobs that you want processed by thiscluster node. For example:ServiceBatchThreadSize=7


Configure Servers for RESTful Service BatchProcessing

You or your xPression administrator can configure individual servers in your cluster to processonly those batch jobs initiated by the RESTful services. This enables the servers to move interactivebatch 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 theservers in your cluster. For all other xPression users, please use the following steps. The configurationis accomplished by setting the EnableBatchServiceProcessor property to “True” or “False”. Toactivate the scheduler on a particular server, set the value to “True”. To deactivate the scheduler on aparticular server, set the value to “False”. Perform these steps on any server in the cluster that youwant 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 theRESTful 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 theproperty to True. To disenable the processing of batch jobs initiated by the RESTful services,change the value of the property to False.


Service Notification

If you want this service to notify your batch scheduler when the job is complete, you must firstmake a change to the Event.xml file in your xPressionHome directory. Once that is complete, youcan configure the listener in xAdmin.

Note: For xPression Batch Web Service Users—You must request that your xPression administratorconfigure the Event.xml file for you. Once that is complete, you can work with your administrator toconfigure 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:<Application name="xPression_Batch"><Resource name="JobHistory"><Event name="xBatch_Completed"/>

155


</Resource></Application>

156


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 beencompleted.Event Notification for all applications is managed on the Event Notification Management screenof 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 Editdialog 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 editit, click the name of the listener. The Add/Edit Event interface opens. The page consists of twotabs: General and Events.

6. If creating a new listener, type the URL for the listener in Listener URL. The listener URL islimited to 256 characters.

7. The Actions bar in the Applications section of the General tab provides two buttons: AddApplication and Delete Application. When creating a new listener, or adding another applicationfor the listener, click Add Application.

8. Select xPression_Batch from the list. The Events tab becomes available when an application isadded 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 JSONstructured message. With Internet Explorer or Firefox, the message is automatically converted to thefollowing XML structured message:<JSONResponse><returnCode> 0/1 </returnCode><queueID> queueid </queueID><resourceId> jobid </resourceId><event>xBatch Completed</event><resourceType>xPressionBatch</resourceType><message></message><JSONResponse>

The <returnCode> 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


The <queueID> and <resourceId> elements identifies the job and queue IDs for the currently runningbatch job. The <message> element reports error messages when the job fails. If the job succeeds, theelement will contain no value.

158

Chapter 10xDesign Online Editor Web Services

You can use the methods provided by the xDesign Online Editor Web Services to create, open, andedit document work items.

Web ServicesThis web service provides methods that work with editable document work items and the xDesignOnline Editor. The web service WSDL will be found at:

http://<server>:<port>/xResponse/services/DocumentRequestService?wsdl

When you use xPression Web Services to create, open, or edit a work item, xPression createstemporary folders to support the action. These folders are not deleted when your session ends. SeeClean 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 singlesign-on products and security models. All entry points into xPression will take an XML documentwhich contains user credentials and any other information needed to authenticate and authorize therequest. You can specify these credentials in any compatible format, for example: encrypted, plaintext, and token. The XML document is passed through the requestContext parameter that mustbe defined for all Web Service calls.

This new authentication model eliminates the need to pass hard-coded parameters for everysecurity-sensitive request, and enables you to integrate without having to change the signatureof any xPression entry points. It also enables you to create Java User Exit code to perform moresophisticated integrations.

Note: Single Sign-On (Trusted UserID/Groups) can only be used when the enableTrustedUserparameter in the systemconfig.properties file is set to True. This properties file is located in yourxPressionHome 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 documentcontaining 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 setsof access rights. By specifying the application name, you are requesting the access rights granted tothe user for that specific application.

Please be aware that the application name you use must grant permissions that are appropriate foryour request. In general, for core xPression services (client and server functions), you can supplycredentials for the user under any application for which the user is authenticated. For xResponse, youmust 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<RequestContext><Credentials method="UserID and Password">

160


<UserID>John</UserID><Password>pass</Password></Credentials><ApplicationName>xPression Response</ApplicationName></RequestContext>

Weak encrypted userid/password<RequestContext><Credentials method="Weak Encrypted UserID and Password"><UserID><EncryptedData xmlns='http://www.w3.org/2001/04/xmlenc#'Type='http://www.w3.org/2001/04/xmlenc#Content'><CipherData><CipherValue>A23B45C67</CipherValue></CipherData></EncryptedData></UserID><Password><EncryptedData xmlns='http://www.w3.org/2001/04/xmlenc#'Type='http://www.w3.org/2001/04/xmlenc#Content'><CipherData><CipherValue>A2KS4SLDK6DKOQWI</CipherValue></CipherData></EncryptedData></Password></Credentials><ApplicationName>xPression Response</ApplicationName></RequestContext>

Single Sign-On (Trusted UserID/Groups)<RequestContext><Credentials method="Trusted UserID and Groups"><UserID>John</UserID><Group>Administrator</Group><Group>xPression Design User</Group><Group>xPression Response User</Group></Credentials><ApplicationName>xPression Response</ApplicationName></RequestContext>

Access Rights for Document Item Web Services

Web service methods that access document work items use access rights to determine if therequesting user is authorized to execute the method. The user must have the appropriate accessrights 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, orhave xResponse Admin access rights in the document’s category, to execute the web service. For thesemethods, 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 moreinformation, see the xAdmin User Guide.

The specific access rights required for each method (if any) are listed in the method description.

161


createDocumentItem

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

• Editing of the document

• Adding an annotation

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


To execute this method, you must have Read access, or xResponse Admin access for the categorythat contains this document.

Return Value: A String that uniquely identifies the newly-created document work item that wascreated within the application specified in the Request Context. The returned string is the work item’sID, and should be tracked for use in subsequent operations, such as opening, publishing, or deleting adocument. 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



Please be aware that the application name you use must grant permissions that are appropriatefor your request. For this method, only the xPression Response application is valid. For moreinformation, see Authentication, page 160.


162


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


A string specifying a single record of XML customer data. You can provide the primary key forthe customer data using the following format:<Keys><Key name="keyName1">keyValue</Key><Key name="keyName2">keyValue</Key></Keys>


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 willbe used in the openDocumentItem method to launch the xDesign Online Editor and open a documentif 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




timeout : String

The number of milliseconds that the token should be active.

163


publishAndReturnDocumentItem

The publishAndReturnDocumentItem web service method enables you to publish a documentwork item to an output profile. The output profile determines whether the document is returnedor distributed without being returned. In order to successfully return the document to your callingapplication, the output profile you specify must contain an output stream whose distributiondefinition is defined with the "Return to Calling Application" option. If the output stream determinesthat 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 orWrite access to the document category; or you must have xResponse Admin access to the categorythat contains the document.

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

Syntax

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

Parameters





The unique identifier for the document item, which is provided by the createDocumentItem method.



164


deleteDocumentItem

The deleteDocumentItem method deletes the specified document work items and associated historiesfrom the server.


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

For more information on the structure for the deleteDocumentItem method, see Example, page 165 .

Syntax

String successMessage = deleteDocumentItem (requestContext, documentItemID)

Parameters





An array of unique identifiers for the document items that you want to delete. You may providemultiple identifiers to delete multiple documents at one time. Document IDs are provided by thecreateDocumentItem method.

Example

The following example shows how to structure the deleteDocumentItem method.<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ses="http://xml.apache.org/axis/session"><soapenv:Header/><soapenv:Body><ses:deleteDocumentItem><ses:requestContext><![CDATA[

<RequestContext><Credentials method="UserID and Password"><UserID>auser</UserID>

165


<Password>apassword</Password></Credentials><ApplicationName>xPression Response</ApplicationName></RequestContext>]]></ses:requestContext>

<ses:documentItemID>603</ses:documentItemID><ses:documentItemID>604</ses:documentItemID></ses:deleteDocumentItem></soapenv:Body></soapenv:Envelope>

reassignDocumentItemToUser

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


Return Value: This method returns a string message when the method successfully reassigns a workitem. For example: "Work item with id: 605 has been reassigned to a user successfully."

Syntax

String successMessage = reassignDocumentItemToUser (requestContext, documentItemID,assignToUserName)

Parameters







The username to whom you want to assign the work item. The new user must have Read accessin the document category.

166


documentItemsAssignedToUser

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

To execute this method, the work item must currently be assigned to you, and you must have Readaccess to the document category; or you must have xResponse Admin access to the category thatcontains the document.

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

Syntax

String[] documentItemIDs = documentItemsAssignedToUser(requestContext, userName)

Parameters




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 youmust have Read access to the document category; or you must have xResponse Admin access to thecategory that contains the document.

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

167


Syntax

String[] documentItemIds= searchDocumentItems (requestContext, searchCriteriaXML)

Parameters





An XML string representing the search criteria. The AND connector will be used when searchingwith 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>, <OR>, and <PHASE> element are the only subelements allowed ina <SECTION>.

• PHASE. The phase element encapsulates each piece of criteria in the searchCriteria file. PHASEcan 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 formatthat 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 March28, 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. SeeREASSIGNER 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 workitem 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 cancontain any number of KEY_VALUE elements. Each KEY_VALUE element is implicitly joinedby an OR operator.

— EDITOR. Supply the value of "tce" to specify the xDesign Online Editor.

168


— 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 containRELATIVE or ABSOLUTE elements, which can contain OLDER, NEWER, FROM, or TOelements.

• ORDERBY. Enables you to sort the list of returned work items. Placing parameters in this elementwill 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 theCREATED, 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.<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ses="http://xml.apache.org/axis/session">

<soapenv:Header/><soapenv:Body>

<ses:searchDocumentItems><ses:requestContext><![CDATA[

<RequestContext><Credentials method="UserID and Password">

<UserID>test</UserID><Password>Iam@EMC2038</Password>

</Credentials><ApplicationName>xPression Response</ApplicationName>

</RequestContext>]]></ses:requestContext>

<ses:searchCriteria><![CDATA[<?xml version="1.0" encoding="UTF-8"?><SEARCHCRITERIA><SECTION><PHASE><CATEGORY_NAME><VALUE>Automatic Payment Letter</VALUE></CATEGORY_NAME><CUSTOMER_KEYS>

<KEY_VALUE name="AUTOPAY_KEY" category="Automatic Payment Letter">*</KEY_VALUE></CUSTOMER_KEYS><EDITOR><VALUE>tce</VALUE></EDITOR><CREATED><VALUE>03-28-12</VALUE></CREATED><NAME><VALUE>Automatic Payment Letter</VALUE></NAME><STATUS><VALUE>Active</VALUE></STATUS><REQUESTER><VALUE>xpression</VALUE></REQUESTER ></PHASE></SECTION>

169


<AND/><SECTION>

<PHASE><DATERANGE><RELATIVE><OLDER unit="Hour">1</OLDER>

</RELATIVE></DATERANGE>

</PHASE></SECTION>

<ORDERBY><VALUE>NAME</VALUE><VALUE>CATEGORY_NAME</VALUE>

</ORDERBY></SEARCHCRITERIA>]]></ses:searchCriteria>

</ses:searchDocumentItems></soapenv:Body>

</soapenv:Envelope>

The following are additional examples of the DATERANGE element:

<DATERANGE><ABSOLUTE><OLDER>08-16-11</OLDER><NEWER>08-16-11</NEWER><FROM></FROM><TO></TO></ ABSOLUTE >

</DATERANGE>

<DATERANGE><RELATIVE><OLDER unit="Month">2</OLDER> //Month Day Hour Minute<NEWER>08-16-11</NEWER><FROM unit="Month">2</FROM><TO unit="Hour">4</TO></RELATIVE>

</DATERANGE>

unlockDocumentItem

The unlockDocumentItem method enables you to unlock a document item that has been openedand locked.


Return Value: This method returns a string message when the method successfully unlocks a workitem. For example: "Work item with id 605 has been unlocked successfully."

Syntax

String successMessage = unlockDocumentItem (requestContext, documentItemID)

170


Parameters


An XML document that passes user credentials for authentication. It also passes the name of theapplication for which the user is authenticated. In xPression, users are given access rights to specificapplications because each application has a different set of access rights. By specifying the applicationname, you are requesting the access rights granted to the user for that specific application. Pleasebe aware that the application name you use must grant permissions that are appropriate for yourrequest. For this method, only the xPression Response application is valid. For more information,see Authentication, page 160.


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 canbe Client Level type or Document Level type. Client Level notes attach to all documents with thesame document ID and the same first primary key, while Document Level notes attach to a specificwork item.


Return Value: This method returns a string message when the method successfully adds theannotation to the work item. For example: "Annotation has been added to work item with 605successfully."

For more information on the structure for the addAnnotation method, see Example, page 172 .

Syntax

String statusMessage = addAnnotation(requestContext, documentItemID,annotationText)

Parameters



171





annotationInfo : String

The XML formatted string that contains the annotation content.

Example

The following example shows how to structure the addAnnotation method:<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ses="http://xml.apache.org/axis/session">


<ses:addAnnotation><ses:requestContext><![CDATA[

<RequestContext><Credentials method="UserID and Password">

<UserID>auser</UserID><Password>apassword</Password>

</Credentials><ApplicationName>xPression Response</ApplicationName>

</RequestContext>]]></ses:requestContext>

<ses:documentItemID>605</ses:documentItemID><ses:annotationInfo>updated customer address</ses:annotationInfo>

</ses:addAnnotation></soapenv:Body>

</soapenv:Envelope>

getDocumentItemInfo

The getDocumentItemInfo method retrieves information about document items. The information isreturned as an XML document. The amount of data returned for some work items could be quitelarge, resulting in a decrease in performance. To help avoid the potential performance decrease,this method enables you to limit the amount of information returned through the infoToReturnparameter. You can return information about the following items by passing the specified term inthe infoToReturn parameter:• General. Shows general information about the work item, including the user who is currentlyassigned to the work item (owner), the work item user who created the work item (user), thework item category, the customer key used to create the work item, the time and date of thelast modification to the work item, the ASL ID (which is used to retrieve information about the

172


work item), the current status and state of the work item, the publisher type, and an indicationif the work item is locked.

• Document. Basic information about the document, including the document item ID, the documentname, the document category, the publishing type, and the customer key of the user for whom thework item was assembled.

• Annotation. For each annotation in the document, the method returns the annotation type, theuser who created the annotation, the timestamp, and the annotation note itself.

• Optional Paragraphs. Lists all the optional paragraphs in the work item. It displays each optionalparagraph group, the group type, and whether or not it is configured for handling in batch. Italso lists all the optional paragraphs in the optional paragraph group, listing the name, ID, anindication that the optional paragraph is shared or not, an indicator if the optional paragraph isselected or not, and the version number.

• External Contents— A list of all external content in the document. For each piece of externalcontent, this method reports the external content name, the external content type, the URL of thelink to the external content, and the location of the external content. If the external content wasadded by an external content rule in xDesign, the name will be NULL. This information will bereturned as follows:<ExternalContents>

<ExternalContent><Name>aaa</Name><Type>PDF</Type><Link>c:\pdf2htmlEX.pdf</Link><From>file</From>

</ExternalContent></ExternalContents>


Return Value: This method returns an XML document containing the requested information. If themethod fails, it returns a SOAP Fault that indicates the reason for the failure.

For more information on the structure for the getDocumentItemInfo method, and for a sample of thereturn XML, see Example, page 174 .

Syntax

String info = getDocumentItemInfo(requestContext, documentItemID,infoToReturn)

Parameters


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

173


name, you are requesting the access rights granted to the user for that specific application. Pleasebe aware that the application name you use must grant permissions that are appropriate for yourrequest. For this method, only the xPression Response application is valid. For more information,see Authentication, page 160.


An array of unique identifiers for document items. Document IDs are provided by thecreateDocumentItem method.

Information will only be returned for those items that you are allowed to access. If you havexResponse 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.


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

• "Document"

• "Annotations"

• "OptionalParagraphs"

• "ExternalContents"

See the description of this method (The getDocumentItemInfo Method) for details about whatinformation is returned for each string.

Example

The following example shows how to structure the getDocumentItemInfo method, and is followedby a sample of a response:<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ses="http://xml.apache.org/axis/session"><soapenv:Header/><soapenv:Body><ses:getDocumentItemInfo><ses:requestContext><![CDATA[

<RequestContext><Credentials method="UserID and Password"><UserID>auser</UserID><Password>password</Password></Credentials><ApplicationName>xPression Response</ApplicationName></RequestContext>]]></ses:requestContext>

<ses:documentItemId>101</ses:documentItemId><ses:infoToReturn/></ses:getDocumentItemInfo></soapenv:Body></soapenv:Envelope>

174


The following is an example of a response to the above request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Header><ns1:sessionID soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"

soapenv:mustUnderstand="0"xmlns:ns1="http://xml.apache.org/axis/session">8218944010464221449</ns1:sessionID>

</soapenv:Header><soapenv:Body>

<getDocumentItemInfoResponse xmlns="http://xml.apache.org/axis/session"><getDocumentItemInfoReturn><![CDATA[<?xml version="1.0"encoding="UTF-8"?>

<DocumentItems><DocumentItem id="1" name="Automatic Payment Letter"><General><Requester>test</Requester><Reassigner /><Category>Automatic Payment Letter</Category><CustomerKeys /><Status>Active</Status><PublisherType>2</PublisherType><LockingState><Locked>False</Locked>

</LockingState></General><Document><Name>Automatic Payment Letter</Name><Category>Automatic Payment Letter</Category><CustomerKey>1</CustomerKey><PublisherType>xPublish</PublisherType><Workflow /><DateAdded>2012-03-28 14:54:31</DateAdded><LastModifiedTime>2012-03-28 14:54:31</LastModifiedTime>

</Document><Annotations /><OptionalParagraphs />

</DocumentItem></DocumentItems>]]></getDocumentItemInfoReturn>

</getDocumentItemInfoResponse></soapenv:Body>

</soapenv:Envelope>

openDocumentItem

The openDocumentItem method is used to open a document in the xDesign Online Editor withinyour own web application. This method requires the following items:• A token, already generated by the createAuthenticationToken method. The token will be usedto verify user credentials, and then launch the xDesign Online Editor and open the specifieddocument 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 areenabled or disabled.

175


Once a work item is opened, a lock will be added until you unlock it using the unlockDocumentItemmethod.


Return Value: This method returns a URL that can be used to load the xDesign Online Editor intoyour custom application. The URL should be applied to the iframe into which you want to load theeditor, by suppling the URL in the iframe src parameter.

For more information on the structure for the openDocumentItem method, and for a sample of thereturn value, see Example, page 176 .

Syntax

String tceHtml = openDocumentItem(token, documentItemID, configuration)

Parameters

token : String

A valid user token generated by the createAuthenticationToken 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 followedby a sample of a response:<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ses="http://xml.apache.org/axis/session">


<ses:openDocumentItem><ses:token>49354c64-5265-49a5-8afb-1c0f9fdb3500</ses:token><ses:documentItemID>605</ses:documentItemID><ses:configuration><![CDATA[<?xml version="1.0" encoding="UTF-8"?>

<EditorConfig><FeatureConfig>

<Save enabled="true"/><PreviewPDF enabled="true"/><SpellCheck enabled="true">

<AddToDictionary enabled="true"/></SpellCheck>

176


<Bold enabled="false"/><Italic enabled="true"/><Underline enabled="true"/><LeftJustify enabled="true"/><CenterJustify enabled="true"/><RightJustify enabled="true"/><StyleSelection enabled="false"/>

</FeatureConfig><PostMessage>

<LoadingCompleteDomain enabled="true"> http://localhost:8080</LoadingCompleteDomain>

</PostMessage></EditorConfig>]]></ses:configuration>

</ses:openDocumentItem></soapenv:Body>

</soapenv:Envelope>

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:<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Header><ns1:sessionID soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"

soapenv:mustUnderstand="0"xmlns:ns1="http://xml.apache.org/axis/session">1789206527339793453</ns1:sessionID>

</soapenv:Header><soapenv:Body>

<openDocumentItemResponse xmlns="http://xml.apache.org/axis/session"><openDocumentItemReturn>http://10.32.220.82:7001/xResponse/html/Edit?

token=b48cb7a4-f5bf-42bf-af89-ba3818a0876c&filename=1332917665889</openDocumentItemReturn>

</openDocumentItemResponse></soapenv:Body>

</soapenv:Envelope>

submitDocumentItem

The submitDocumentItem method enables you to submit a document item to the next stage in yourworkflow, as defined in the category to which the document belongs. Once the document item hasbeen 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 orWrite access to the document category.

Return Value: This method returns a string message when the method successfully submits thedocument item. For example: "Document item: 100 has been submitted successfully." If the methodfails, it returns a SOAP Fault that indicates the reason for the failure. For example, the methodwill fail if the workflow is not defined.

177


Syntax

String submitMessage = submitDocumentItem(requestContext, documentItemID)

Parameters



workflowState : String[]

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


The unique identifier for document item you want to submit. Document IDs are provided by thecreateDocumentItem method.

rejectDocumentItem

The rejectDocumentItem method enables you to reject a specified document item. You can add a noteincluding 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 haveApprove access to the document category.

Return Value: This method returns a string message when the method successfully rejects thedocument item. For example: "Document item: 102 has been rejected." If the method fails, it returns aSOAP Fault that indicates the reason for the failure. For example, the method will fail if the documentitem is not in the pending approval list.

Syntax

String rejectedMessage = rejectDocumentItem(requestContext, documentItemID)

Parameters


178




The unique identifier for document item you want to reject. Document IDs are provided by thecreateDocumentItem 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 haveApprove access to the document category.

Return Value: This method returns a string message when the method successfully approves thedocument item. For example: "Document item: 100 has been approved." If the method fails, it returnsa SOAP Fault that indicates the reason for the failure. For example, the method will fail if thedocument item is not in the pending approval list.

179


Syntax

String approveMessage = approveDocumentItem(requestContext, documentItemID)

Parameters




The unique identifier for the document item you want to approve. Document IDs are providedby the createDocumentItem method.

documentItemsAssignedToUserReturnInfo

The documentItemsAssignedToUserReturnInfo method retrieves information about all of thedocument items currently assigned to the specified user. The information is returned as an XMLdocument. The amount of data returned for some work items could be quite large, resulting in adecrease in performance. To help avoid the potential performance decrease, this method enables youto limit the amount of information returned through the infoToReturn parameter.

You can return information about the following items by passing the specified term in theinfoToReturn parameter:• General. Shows general information about the work item, including the user who is currentlyassigned to the work item (owner), the work item user who created the work item (user), thework item category, the customer key used to create the work item, the time and date of thelast modification to the work item, the ASL ID (which is used to retrieve information about thework item), the current status and state of the work item, the publisher type, and an indicationif the work item is locked.

• Document. Basic information about the document, including the document item ID, the documentname, the document category, the publishing type, and the customer key of the user for whom thework item was assembled.

• Annotation. For each annotation in the document, the method returns the annotation type, theuser who created the annotation, the timestamp, and the annotation note itself.

• Optional Paragraphs. Lists all the optional paragraphs in the work item. It displays each optionalparagraph group, the group type, and whether or not it is configured for handling in batch. Italso lists all the optional paragraphs in the optional paragraph group, listing the name, ID, an

180


indication that the optional paragraph is shared or not, an indicator if the optional paragraph isselected or not, and the version number.

• External Contents - A list of all external content in the document. For each piece of externalcontent, this method reports the external content name, the external content type, the URL of thelink to the external content, and the location of the external content. If the external content wasadded by an external content rule in xDesign, the name will be NULL. This information will bereturned as follows:<ExternalContents>

<ExternalContent><Name>aaa</Name><Type>PDF</Type><Link>c:\pdf2htmlEX.pdf</Link><From>file</From>

</ExternalContent></ExternalContents>



Syntax

String documentItemInfos = documentItemsAssignedToUserReturnInfo(requestContext, userName,infoToReturn)

Parameters



userName : String

The username of the user for whom you want to return information about assigned document items.


181



• "Document"

• "Annotations"


• "ExternalContents"

See the description of the getDocumentItemInfo method for details about what information isreturned 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 inperformance. To help avoid the potential performance decrease, this method enables you to limit theamount of information returned through the infoToReturn parameter.



Syntax

String documentItemInfos= searchDocumentItemReturnInfo (requestContext, searchCriteriaXML,infoToReturn)

Parameters




182


An XML string representing the search criteria. The AND connector will be used when searchingwith 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>, <OR>, and <PHASE> element are the only subelements allowed ina <SECTION>.

• PHASE. The phase element encapsulates each piece of criteria in the searchCriteria file. PHASEcan 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 formatthat 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 March28, 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. SeeREASSIGNER 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 workitem 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 cancontain any number of KEY_VALUE elements. Each KEY_VALUE element is implicitly joinedby 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 containRELATIVE or ABSOLUTE elements, which can contain OLDER, NEWER, FROM, or TOelements.

• ORDERBY. Enables you to sort the list of returned work items. Placing parameters in this elementwill 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 theCREATED, STATUS, and DATERANGE criteria, although no error will appear in the log.

The full schema for the XML search criteria is located in .


183



• "Document"

• "Annotations"


See the description of the getDocumentItemInfo method for details about what information isreturned for each string.

copyDocumentItem

The copyDocumentItem method makes a copy of a document work item and assigns it to thespecified user. The advantage of using this method is that it enables you to reuse all the previouscustomizations of that work item.


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

Syntax

String newDocumentItemId = copyDocumentItem (requestContext, documentItemID,assignToUserName)

Parameters






184


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 methodadds 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


Syntax

String ret = addExternalContentByStream (requestContext, documentItemID, externalContent,format, name)

Parameters





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 withLocal 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 anddeleteExternalContent methods. The name should be unique, especially if there are multiple externalcontent 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 addsthe byte array of the external content to the end of the specified document.


186


Syntax

String ret = addExternalContentByLink (requestContext, documentItemID, externalContentLink,format, name)

Parameters






A link to the location of the external content. You can supply a local file path on your server, aURL, or an ECM path.• Local File Path Syntax - <drive>\<path>\<filename>. For example:

C:\xPression\externalcontent\sample.pdf

• URL Syntax - http://<machine name or IP address>/path/<filename>. For example:http://10.0.0.0/externalcontent/sample.pdf

• ECM Path Syntax - ecm::<ecmConfigName>?uri=/<path>/<filename>?version=<version>. Forexample: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 withLocal 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 anddeleteExternalContent methods. The name should be unique, especially if there are multiple externalcontent additions that may need to be deleted at a later date.

187


deleteExternalContent

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


Syntax

String ret = deleteExternalContent (requestContext, documentItemID, name)

Parameters





name : String

The name of the external content that you want to delete. This is the name used when adding theexternal content through the addExternalContentByLink and addExternalContentByStream methods.This method can only delete external content that was added through Web Services. This methodcannot 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 createstemporary folders to support the action. These folders are not deleted when your session ends. Whenopening 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, youneed to perform two tasks:

1. On your xPression Server, open ecor.properties for editing. This file is located in yourxPressionHome directory.

2. Locate the following section:#Delete xResponse temporary folders when "last modified" time exceeds

188


threshold.

189


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 wantthe 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 toset as the interval for the feature to scan the temporary folders.


6. Next, you have to activate the feature. You do this in xAdmin. Log in to xAdmin, click the SystemManagement menu, then click Service Management.

7. There will be a item in the list for the "xResponse Temporary Folders Cleanup" service. ClickStart 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 11The xPression DevKit xEditorComponent

xEditor is a Microsoft Word-based editor that enables you to use Microsoft Word’s powerful editingand composition features. xEditor is used for editing by xRevise, xResponse and by customapplications created with the xPression DevKit. Refer to the xAdmin User Guide for details onavailable 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 workwith xPression work items.

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

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

After successfully installing .NET Framework:

1. Log off 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) Settingsshould NOT be selected. Significant performance degradation for xEditor has been noted when thisoption is selected. It will be noted as a Warning in the xEditor log if selected.

191

The xPression DevKit xEditor Component

User Configuration

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

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

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

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

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

Running xEditor the First TimeThe client installation itself is largely automatic. If all required components are present, a messagedisplays.

xEditor uses a Smart Client to open xEditor when you open a work item for editing. The SmartClient 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 onlyonce 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 apre-WIP version of xEditor when the machine starts up. This reduces the amount of time required forxEditor to open a work item. There will be an instance of WINWORD.EXE running, with all requiredsupporting software. This instance appears in Task Manager and can be shut down, but if it is shutdown xEditor will take longer to open work items than would otherwise be the case.

192


Installing xEditor

To install xEditor on the client machine:

1. When the xPression Editor Startup message appears, click Install.

Depending on your Microsoft Word macro security setting, you may receive a Security Warningthat xEditor.dot contains macros. xEditor uses macros to override some Word functions, sochoose Enable Macros if you receive this message.

2. The xEditor Setup Wizard starts. Click Next.

3. In the Select Installation Folder step you can choose where to install xEditor.

A default location for xEditor is offered, but you can choose another location. To install to adifferent location, type the desired path in the Folder field, or click Browse and choose a locationfrom the Browse for Folder dialog box.

Click Disk Cost to see if enough disk space is available.

Click Next to proceed with the installation.

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

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

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

The installation applies to either xRevise, xResponse, or any xPression DevKit application that usesxEditor 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. Thisfile is deleted after use unless running in debug mode. It is strictly for internal, session-specific useand should not be modified by the user.

Pushing the xEditor Installation from the Server

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

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

193


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 thanEnglish. The issue can be avoided with the following procedure. This procedure does not affect thesetting 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 selectWinWord.exe, and then click End Process.

5. Close Task Manager.

6. Click Start and point to Startup.

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

8. Restart the computer.

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

10. Click Start and then click Control Panel.

11. Click Add or Remove Programs.

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

13. Load xEditor from your IDDK application. xEditor will automatically install as first-timeinstallation.

The xEditor InterfacexEditor enables Microsoft Word to act as the editor. The main difference between Word’s interfaceand 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 samefor both versions.

The Document Actions Pane

The Document Actions pane resides in the Task Pane. It opens docked to the right side of thewindow by default, but you can relocate it if desired. You can access all xEditor functions through

194


the Document Actions pane. Word provides a number of functions through the Task pane, such asthe XML Structure pane. You can switch panes by clicking the title bar currently displayed andselecting the desired pane from the list.

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

The Document Actions pane contains task pane controls, a toolbar and 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. SeeDeleting 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 displayit by the xPression administrator. This feature should be enabled and used only as directed byEMC Document Sciences Solution Support.

• Forward Backward —Moves the focus to the next or previous variable in the document.

195


• Save — Saves the document. This increments the revision number for any section that has beenchanged since the last time that the document was saved. This also creates a new xPressiondatabase object. Note that xPression removes unused xPression database objects to preventproblems with search and other issues.

• Search — Opens the Search window in the Task pane. See Finding Existing Content, page 202 fordetails 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 MicrosoftWord’s spell check feature. This button appears if the work item contains form fields and a sectionunder 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 elementthat 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 areestablished 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 anychange is made that affects the assembly, such as adding or moving an RU. You can add new contentitems, which are displayed in the same manner as those created in xDesign.

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

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

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

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

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

196


Some xEditor functions are not available through the toolbar, but can be accessed by right-clickingthe document node or any RU in the TOC. The right-click menu for the document node providesthe following options.• Save As — Opens the Save dialog box and enables you to save the document as a file to anyselected location. Saving the file in this way allows you to open the file without going throughxEditor, but changes will not be available to xEditor.

• Annotation — Displays any annotations associated with the document. Annotations cannot beedited in xEditor. After creating an annotation xEditor will not allow another annotation to beadded until the work item is saved. Annotations can also be attached in xDesign. New annotationscan 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 itemwith either a work item stored in the xEditor history for this item, or a Word document stored onthe 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 changesappropriately with the delete status of the RU. You cannot delete the last RU in the document, sothis option is available only if there is another RU in the document. See Deleting and UndeletingRevision Units.

• Annotation — Displays any annotations for the work item. Annotations cannot be edited ordeleted once created. Annotations can be added to xEditor work items with the New Annotationbutton on the Command Bar in xEditor. Annotations can be as long as desired. Only oneannotation 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 theappropriate 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. Allother nodes in the TOC are below this node.

• Revision Unit — xEditor documents are divided into Revision Units. Each RU is represented withthis icon. Some RUs have further child nodes.

• External Content — The document designer can include external content in the document. Eachpiece of external content is contained in its own RU represented by this icon. Multi-page TIFF andPDF 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 bythis icon under the External Content RU node. If the external content is a multi-page TIFFright-clicking the child node opens a context menu that provides the option of skipping the page.

197


• Multi Select — Multi-select Optional Content Group - Any combination of optional content undera Multiselect Optional Content Group can be selected. Clicking a selected item deselects it. Youare never required to select optional content. See Optional Content, page 200.

• Single Select — Single-select Optional Content Group - Only one optional content item under aSingle-select Optional Content Group can be selected. Selecting an item deselects any currentlyselected item. Clicking a selected item deselects it. You are never required to select optionalcontent. See Optional Content, page 200.

The Information Panel

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

Properties are established when the document or revision unit is created. Once created, they cannotbe changed in xRevise, so this grid is read-only except when creating a new revision unit.

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 MergeParagraphs section. The xEditor user cannot designate content for merge.

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

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

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

198


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

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

The Command Bar

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

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

• Variable Navigator

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

• New Annotation

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

The xEditor Menu

When running xEditor, Word’s menu bar includes an xEditor menu. The main purpose for this menuis to provide a convenient means of opening the Task Pane in the event that it closes. It also providessome functions that are also available in the 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 UnitsTo delete a revision, right-click the revision unit in the TOC and then click Delete/Undelete. DeletedRUs appear in the TOC with a deleted mark. You can toggle between showing and not showingdeleted sections by clicking Hide deleted TextPieces.

199


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 ContentA section can be designated as optional when it is created in xDesign. Optional sections are indicatedin the xEditor TOC by a checkbox. If you clear the checkbox, the section is not included when thedocument is published. You are never required to choose any optional content.

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

If optional content that includes any variables is selected, and the variables exist elsewhere in the RU,the variable instances will remain editable variables as long as all instances of the variable have thesame value throughout the RU. If the variable has different values within the RU, all instances will beconverted to static text. In this case the static text will be editable, but will no longer be treated as avariable. See Variables, page 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 toxPresson 4.0 will be converted to static text in most cases, regardless of value.

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

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

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

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

xEditor FunctionsxEditor supports most Microsoft Word features and it provides additional functionality to supportfunctions needed to work within the xPression environment. Refer to Microsoft Word Features andFunctions 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 xDesigntemplate and made available to xEditor through the xPression server. Character styles should not beused in xEditor.

200


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

The xPression Administrator can configure the system to clear the cache automatically. The primaryreason for automatically clearing the local cache is for security. In cases where xEditor users workwith documents that contain sensitive information, deleting local copies of the document helps toprevent unauthorized access to this information. The administrator can configure the system to deletecached 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 clearedmanually as required to prevent an excessive accumulation of files. You can clear the xRevise cachemanually, 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 Settingsdialog box opens showing the current settings. If the dialog box has not been enabled it will stillopen, 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 openthe associated cache file will not be deleted.

2. On the client machine, locate the cache files. Cache files are stored in [Drive]:\Documentsand Settings\[WINDOWS_LOGIN_NAME]\Application Data\EMC DocumentSciences\<application>. 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 LogxEditor creates a log file that records the configuration setting used to start xEditor, the elapsedtime for all web service calls, and errors with stack traces. When a failure occurs, a message openswith a link that opens the file in a text editor.

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

201


Finding Existing ContentContent that you, or other xEditor users, have created for other work items can be reused. Usethe 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 searchstatement, then click the Search button on the toolbar. Microsoft Word’s Find and Replace feature isalso 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’sSearch 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 usethis feature. Refer to the xPression Installer’s Handbook for instructions on enabling Full TextSearch.

• Search Options: Search For— By default, both standard and custom content for all versions isincluded in the search. You can limit the potential size of the search results by choosing an optionother than the default.— All Content returns content regardless of origin or revision number.

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

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

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

• Search Options: Match— Choose whether you want to return any item that contains a word orphrase, or only exact matches.

• Match These Attributes— Content attributes will vary, and may not be associated with a workitem at all.

Press Start Search when you are ready to start the search. Search results display in a window belowthe TOC. Search results are sorted by last modified date, from latest to earliest. Double-click the itemfor 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 youwill be prompted to rename it. Duplicate names are not allowed.

202


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 cursorlocation.

If the searched item exists in multiple documents each document is listed in the Owner Documentsection of the Search Results. In addition to the customer key, which would identify the work itemwhere the content is used, the Owner Document section shows the following for each work item:Status, Current State, Last Modified time stamp, and whether it is in use. This information is forthe document, not the specific RU.

The xEditor Find utility is limited to 101 return items. In addition, databases have the ability toexclude certain common words. SQL and Oracle provide similar support to exclude noise. Acomplete list of words excluded from SQL full text search is available in the xRevise User Guide. DB2does not support stop word processing. See DB2 Text Search and Net Search Extender Comparisonfor 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 versionsof Microsoft Word. Find and Replace will not find variables, hidden text, or DCPI fields, such assubtotals and indexes. Features that are available in xEditor have the same functionality as providedin 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 soforth are not supported for searching in xEditor.

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

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

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

203

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


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

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

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

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

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

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

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

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

To add a new RU:1. In the TOC, select the element after which the new RU should appear. You will be able to 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 xEditorEditing documents in xEditor is very similar to editing documents in Microsoft Word. Most Wordfunctions 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


You must log off xEditor whenever your user session closes. xEditor will not close automatically. It ispossible 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 yourwork and close xEditor when finished. Instances of Word appear in the Task Manager asMSWORD processes.

If the host application session closes, whether by user action or timeout, and a work item remainsopen in xEditor, the work item will remain locked until the xEditor session is closed. A messagedisplays when the host application session closes with a work item locked reminding the user toclose the editor when finished editing.

It is necessary to lock documents when they are open in xEditor. While a document is locked, youwill not be able to use the Submit, Delete, Carry Forward, or Assign actions. A message will displaywhen 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, thesame user can reopen the document.

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

Closing xEditor

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

Track Changes

xEditor uses Word’s Track Changes feature, so changes made to documents in xEditor will appear inred and underlined by default. Select the Final display option, rather than the default Final ShowingMarkup option, to suppress showing changes in the Edit window. In Microsoft Word 2007 and 2010the display option is located in the Tracking section of the Review ribbon. Refer to your MicrosoftWord 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 toimprove performance. The files stored here are the application files downloaded from theserver, not the assembled document files. The structure is located under C:\Documents and

205


Settings\[user]\Application Data\EMC Document Sciences\[server_port]\[document]. The variableparts 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 eachclient machine must be deleted to apply the changes. It is possible that different documents can havedifferent toolbar configurations in xEditor if this file is not deleted when changes are made on theserver. Smart Client automatically replaces the file on the client machine if the file is necessary.

xEditor saves a Word-format copy of the document in the \[document] folder. This file cannot beopened 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 supportedbecause xEditor provides a similar function for use within the xPression environment. For example,Word’s New function is not supported because work items for xEditor must be created in xDesign;they cannot originate in xEditor. Microsoft Word’s selection logic has been modified to maintainvariable integrity. See Selecting Variables.

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

The following Word functions are either not available with xEditor, or the stock functionality ismodified by xEditor. It may be possible to enable toolbar buttons or menu item for those that arenot supported, but the function is still overridden by xEditor. It is also possible disable others, seeRibbon 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 isdeleted and a message is displayed. xEditor does not support modifying styles. Users should notmodify styles because satisfactory results cannot be guaranteed.

• New Window

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

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

206


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

• CTRL+A

The CTRL+A hotkey combination selects the entire document in Word. CTRL+A behavesdifferently in xEditor, depending on whether the document includes optional paragraphs or not.If the document does not include any optional paragraphs, then the entire RU is selected. If thedocument 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. SeeProtection.

• Drag and Drop

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

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

Word Menu Function xEditor Implementation

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

Edit FindReplace

Go To

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

Tools Spelling andGrammar

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

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

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


Note that Track Changes is used by the application. Unlike other items in this list, it cannot beturned 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 enablefeatures disabled by xEditor.

Hidden Table Borders

If a document that includes a table with a hidden border is created in Microsoft Word 2003 and thedocument is subsequently opened in a later version of Microsoft Word, the table border will not behidden 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 directlythrough the Microsoft Word interface. Headers and footers are accessed either by double-clicking inthe header or footer or from the Header or Footer tools on the Insert ribbon.

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

Spelling and Grammar are available from the Review ribbon. Options for automatic grammar andspelling provided by Microsoft Word are available in xEditor.

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

Form Fields

xPression supports Drop Down, Text, and Check Box form fields in documents. Form fields areadded to the document in xDesign; they cannot be added in xEditor, but they can be modified.Variables are supported in Drop Down and Text form fields. Variables, whether in form fields ornot, return the value of the variable when the document is assembled regardless of the protectedstate of the document. Variables cannot be used to establish the state of Check Boxes. Supportedform fields must be selected from the Legacy Tools list in the Controls section of the Developerribbon when the document is created in xDesign.

208


Documents that include form fields and are intended for use with xEditor must use Filling In Formsprotection in any section that includes a form field. Since Read Only protection is applied to theentire document if it is applied to any part of the document, documents with form fields cannotinclude any section with Read Only protection.

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

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

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

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

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

Some applications may not permit users to specify an output profile for previews, so the preview PDFwill always show form fields as static text. In applications that do, if none is specified the previewwill show form fields as static text.

When the document is published as standard PDF the form field is converted to static text with theselected value. When published as Fill-in PDF the field is published as a form field with the valueselected or specified by the xEditor user presented as the default. If the value of a variable used in aform field is not set the field will publish as empty.

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

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

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

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

• Static Text

• Static Text {Variable}

209


• {Variable} Static Text

• {Variable} Static Text {Variable}

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

• {Variable}{Variable}……

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

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 thedocument is created.

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

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

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

210


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

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

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

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

Read Only Protection

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

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 theProtect Document item has been enabled. Refer to the xAdmin User Guide for information on creatingcustom toolbars and ribbons.

211

Configuring Microsoft Word RibbonsYou can change the Microsoft Word ribbon configuration to enable or suppress the elements on theribbon. While changes that you make through the Word interface are limited to the current session,change made through a configuration file wile last beyond the current session. Changes made in theconfiguration file affect all users of the application on the xPression server where the configurationfile is located. Each server can have a different configuration.

The configuration files are located in the xEditor folder of your xPressionHome directory. This fileused to be located in the EAR directory, please note the new location. EMC Document Sciencesprovides sample configuration files to help you get started:• 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 configurationfile. Once your file is configured, you must specify the configuration file in xAdmin to enable it forthe server.

To make changes to the Microsoft Word ribbon configuration on your server, completethe 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. Forexample:<command idMso="Font" enabled="false"/><command idMso="Bold" enabled="false"/>

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

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

5. Log in to xAdmin.

6. Click Resource Management, then click xEditor Configuration.

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

8. Click theWord tab.

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

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

11. Click Save.

212

Preface

Language Specific Configuration Files

You can create language specific configuration files for non-English implementations if you areusing Microsoft Word 2007 or 2010. Language specific configuration files are not supported forMicrosoft 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 fora specific toolbar. In addition to its properties, the HideControls and DisableControls elementsreside between its opening and closing tags.— Name is the name of the toolbar.

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

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

• HideControls

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

Name is the name of the control to be hidden.

• Disable- Controls

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

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

• Control

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

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

• Menus

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

213

Preface

• Menu

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

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

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

• HideControls

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

Name is the name of the control to be hidden.

• Disable- Controls

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

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

• Control

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

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

Excluded, Repurposed, and Unsupported Commands

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

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

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

• New Window

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

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 wascreated. It always inserts “Created on 6/19/2007 10:14:00 AM.” It is recommended that usersavoid using this option.

• CTRL+A

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

• Protection

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

• Drag and Drop

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

The following Word functions are suppressed, not supported, and cannot be enabled with a customribbon configuration.

From the Office menu:• Send Menu

All items including E-mail, E-mail as PDF Attachment, E-mail as XPS Attachment, and Internet Fax

• Version History

• Properties

• Save As Menu

All items including Save as Word Document, Save as Word Template, Save as Word 97–2003Document, PDF or XPS, and Other Formats

• 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 originalfunction cannot be restored.

From the Office menu:• Save

• Save As

• Application Options

From the Home tab:• Find

• Replace

• GoTo

• Paste

• Paste Special

• Paste Hyperlink

From the Page Layout tab:• Page Setup

From the Review tab:• Spelling and Grammar

• Restrict Formatting

• 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 enablefeatures disabled by xEditor.

217

Preface

Opening a Work Item in xEditorThe specific method for opening a document in xEditor for an xPression DevKit application dependson 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, butnot when assembling for xPublish. If possible it is recommended that paragraphs and tables formerge occupy the same RU to avoid confusion when working in the editor.

Content Separators

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

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

Merged Paragraphs and Content Separators

The Paragraph Insert function in xDesign enables the document designer to indicate to xPressionthat a series of paragraphs, possibly from separate content items, should be merged into a singleparagraph at the time of assembly. xEditor treats merged content items as one object. Only the firstof a set of merged content items will have a separation marker. If you make a change anywhere inthe merged text, xEditor replaces the first content item, and marks all subsequent merged contentitems 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. Thedocument designer can insert variables with the Insert Variable tool in xDesign, or by using a variablerule. When working with the document, the values are displayed and the variables are retained untildeleted. Instances of the same variable with different values in a given RU are converted to plain textwhen the document is assembled for xEditor.

Variables are usually displayed in red to distinguish them from ordinary text, but appear as static textin 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 allvariables 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 mustbe 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 theprimary data source and local variables are either from secondary tables or variable rules. When thevalue of a global variable is changed in xEditor all instances of the variable throughout the documentare updated to reflect the change. When the value of a local variable is changed all instances of thevariable in the selected RU are updated to reflect the change. So, for example, the same local variablemay appear in any number of RUs, and may initially have the same value in each, but the value canbe changed in xEditor so that the value differs from one RU to another, but a global variable willalways have the same variable wherever it is used in the document.

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

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

Selecting Variables

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

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

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

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

• SHIFT+SEMICOLON

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

220

Preface

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

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

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

• Right ArrowSHIFT+Right ArrowCTRL+Right Arrow

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

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

• Down ArrowCTRL+Down Arrow

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

• Up ArrowCTRL+Up Arrow

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

• SHIFT+Down Arrow

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

• SHIFT+Up Arrow

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

• CTRL+SHIFT+Left Arrow

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

• CTRL+SHIFT+Right Arrow

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

• CTRL+SHIFT+Down Arrow

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

221

Preface

• CTRL+SHIFT+Up Arrow

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

• Page UpCTRL+Page Up

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

• Page DownCTRL+Page Down

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

• SHIFT+Page Up

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

• SHIFT+Page Down


• BACKSPACE

The entire variable will be selected.

• CTRL+BACKSPACE

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

• CTRL+SHIFT+BACKSPACE

No effect.

• DELETE

The entire variable will be selected

• CTRL+DELETE

The entire variable will be deleted

• CTRL+SHIFT+DELETE

No effect.

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

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

• Right ArrowCTRL+Right Arrow

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

222

Preface

• Down ArrowCTRL+Down Arrow

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

• Up ArrowCTRL+Up Arrow

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

• SHIFT+Left Arrow

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

• SHIFT+Right Arrow

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

• SHIFT+Down Arrow

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

• SHIFT+Up Arrow

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

• CTRL+SHIFT+Left Arrow

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

• CTRL+SHIFT+Right Arrow

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

• CTRL+SHIFT+Down Arrow

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

• CTRL+SHIFT+Up Arrow

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

• Page UpCTRL+Page Up

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

223

Preface

• Page DownCTRL+Page Down

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

• SHIFT+Page Up


• SHIFT+Page Down


• BACKSPACE

The entire selection range will be deleted.

• CTRL+BACKSPACE

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

• CTRL+SHIFT+BACKSPACE

No effect.

• DELETE

The entire variable will be deleted.

• CTRL+DELETE

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

Note: When a variable instance is deleted it cannot be restored after the document has been saved.However, it will be included in xRevise reports along with its entire history, including when it wasdeleted and by whom. 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 beselected. Variable instances can be placed directly next to one another. It is possible to insert textbetween adjacent variables without impacting either of the variables.

Note: Since selecting the entire variable is forced, selecting surrounding characters can be difficultunder certain circumstances. If the variable contains a space and there is a character to the immediate

224

Preface

right of the variable, and you try to select the character to the right of the variable with a mouse actionmoving from right to left, the variable will also be selected. It is possible to select the character byplacing the cursor between the variable and the following character and using a mouse action fromleft to right, but this can be difficult. To select the consecutive character to the right of a variable it isrecommended to select the variable, press RIGHT ARROW and then press SHIFT+Right Arrow.

Variable values cannot be changed in the same way as other content. All changes to variable values,except date variables, are made in the Variable grid section of the Task Pane. Date variables arechanged using the Date Picker. To begin editing a variable other than a date variable, double-click thevariable or select the variable and press CTRL+SEMICOLON. The cursor is moved to the variable’sedit field in the Task Pane where the desired changes can be made as required. When complete, pressENTER or click anywhere in the edit window and the cursor is returned to the document. To exit theVariable grid and abandon any changes, press ESC. If a variable is selected without choosing to editthe variable, any typing is added as plain text just prior to the variable instance in the edit window.

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

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

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

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

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

Variables can be used to populate Text and Drop-down List form fields. Variables in form fieldsbehave more like static text in xEditor. Variable values that were used to populate form fields areedited directly in the form field rather than the variable grid. Changing these instances does notchange the value in the grid or in any other instances of the variable. Likewise, changes to the valueof 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 formfields are not displayed in red as is the case with variables outside of form fields, and the fact that thesame 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 eitherdirectly or with the Date Picker. Click the Date icon to open the Date Picker and select the desireddate from the calendar-formatted Date Picker. The Date Picker is a standard Microsoft user interfacedevice; simply select the desired date and it is applied to the selected variable. Direct changes to thedate are allowed in the Variables grid as well, but there are some restrictions:• The BACKSPACE key cannot be used to go back one character.

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

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

Copy and Paste

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

Drag and Drop

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

Variable Formats

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

Certain variable types have formatting options that the document designer can define. For example,“12/31/2010” and “December 31, 2010” both refer to the same day and could be expressed in a datevariable. The document designer can use the same date variable throughout the document, but applydifferent date formats in different places. xEditor will honor the variety of formats and display thedate in the specified format for each instance. The document designer can also specify the number of

226

Preface

decimal places for numeric variables, and this is honored as well. So if the xEditor changes a numericvalue to “99.09” and the document designer had limited that variable to a single decimal place,xEditor would display it as “99.1”.

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

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

Protection and Variables

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

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

• All variables are editable

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

• No variables are editable

Does not allow editing any variable.

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

Variable Navigator

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

Subtotals, Index Headings, and Table Headings andFooters

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

The document designer can use a variety of functions to provide subtotals in the document. Thevalue of these functions is resolved when the document is published. Therefore they are shown asplaceholders 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 theRU, the variable instances will remain editable variables as long as all instances of the variable havethe same value throughout the RU. If the variable has different values within the RU, all instanceswill be converted to static text. In this case the static text will be editable, but will no longer be treatedas a variable. See Optional Content, page 200 for more information on working with optional content.

Note: Variables in work items that were created in earlier version of xPression and upgraded toxPresson 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 xAdminUser Guide for details on using the Workitem Utilities.

Carry ForwardThe xEditor Carry Forward utility enables you to compare your current table of contents to any otherversion (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 tothe current table of contents.

The Carry Forward Utility is part of xEditor. You can open the Carry Forward utility from the Workin Progress page or from an open work item. Regardless of how Carry Forward is opened, theoptions are the same.

228

Preface

Three documents are involved in any Carry Forward action; Baseline, Compare, and an Activedocument. When a document is opened in Carry Forward the Baseline document is compared tothe Compare document. As many conflicts as possible are resolved automatically. In most casesall conflicts are resolved automatically, and any resolutions can be changed if necessary. If CarryForward encounters a revision unit with a name that conflicts with another revision unit, it ishandled as a new RU.

Note: Automatic resolution has limitations. If revision units have been moved, for example, it ispossible that Carry Forward will not be able to correctly identify which revision units in the baselinedocument correspond to which revision units in the compare document.

When working in Carry Forward the only document subject to change is the active document. Thecompare 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 toWork 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 andcompare documents have been assessed the Review Helper dialog box opens. This dialog box enablesthe user to scroll through all instances where a change was identified. The user can choose to acceptthe 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 DocumentStructure Tree for a description of the icons), and the reason for the automatic selection. If the userhas chosen to override the automatic selection, this is indicated in the Current State field. The ShowCarry Forward details button toggles displaying the Carry Forward Data and Content Compatibilitysections.

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 thisview 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 fromthe Carry Forward Review Toolbar.

• Show Carry Forward details — Toggles the expanded Review Helper dialog box. When expandedthe dialog box shows Carry Forward Data and Content Compatibility.

• Navigation Buttons — Use the navigation buttons to scroll through the identified changes inthe document.

• Confirm— Confirms the current selection. When a decision is confirmed the only option availablefor the RU is to undo the confirmation. Options can also be confirmed from the right-click menufor each RU.

• Use Compare — This option is available if Use Baseline is the current state, or the RU has beenremoved. 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 beenremoved. 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 removethe 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, andinformation 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 performactions 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 eithervariable 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 andCompare documents in frames below the working document. Click this button to toggledisplaying the other documents. They are for reference only; they cannot be edited in CarryForward.

Always use this button to close the comparison documents; do not close the extra windows usingthe window’s Close button. The comparison windows may adversely affect overall performancewhen 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 workitem 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. Thehighest-level node in the tree represents the document. Under the document node are any RUs thatshould be displayed based on the selection made with the View Filter on the toolbar. By default onlyRUs 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 theactive 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 resolvedmanually. The document cannot be finished until the conflict is resolved. The specific conflict willbe indicated in the tree as tracked changes.

Whenever any node is selected in the tree the corresponding content is highlighted in the workingdocument and appropriate information is displayed in the Information section near the bottom ofthe pane.

Each node except the document node provides a context, or “right-click”, menu for working with thecorresponding 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 becomeunavailable 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 changesthe revision unit to the Baseline version.

• Use Compare — This action is available if the Baseline version is currently being used. It changesthe revision unit to the Compare version.

• Use Both — This action is available when revisions exist in both baseline and compare work itemsthat 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. Variablescannot be edited, either in Name or Value display mode. When selected the Carry Forwardtoolbar is replaced with the Finish Edit button. Click Finish Edit to restore the toolbar. SeeEditing 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 theCarry Forward Review toolbar with the Choose Command Bar. See Working with Variables inCarry Forward.

• Undo Confirm — This action is available if the Confirm action has been applied. It reverses theConfirm 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 removingchanges 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 theremoval. To create a comment for the removal, type the text of the comment in the text field and thenclick Add Comment. To proceed with the removal without adding a comment, click Dismiss. Thecomment appears in a comment balloon in the active document. The comment balloon is discardedwhen the change is re-inserted and cannot be recovered.

The Information Panel

The Information panel, located below the Document Structure pane, displays information relevantto the selected element. Information in this panel is read-only.

The following information is available in the upper section of the information panel when thedocument 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 thedocument 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 thedocument 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 revisionunit is selected.• Properties — The upper section contains information about the revision unit in the activedocument.

• 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 arevision 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. Canbe True or False.

The following information is displayed in the Compare section of the Information panel when arevision 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. Canbe True or False.

Editing Content in Carry Forward

The Carry Forward feature is intended as a means of efficiently combining content in differentversions of a document, but it does provide the ability to edit content. Editing is performed on a singlerevision 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 ForwardReview 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 sectionthat contains a form field. In this case the text can be edited, but variables and form fields areprotected from editing. If the document does not contain form fields then the document may havebeen protected with Read Only protection, in which case only designated text can be edited. Textthat can be edited is surrounded with brackets and subtly highlighted. When finished editing, clickFinish Edit.

The Carry Forward utility may not display expected changes to headers and footers under certaincircumstances when removing a section with a header or footer and then replacing the removedsection. The expected change may not be displayed in the Carry Forward view when the headeror footer uses the Link to Previous property.

Inserted data in the header or footer will always be correct in the Carry Forward view. This issueaffects sections after inserted data if the section is set to Link to Previous. Since the affected sectionsmay 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 andreturns to the normal xEditor view. This behavior is specific to the xEditor-based Carry ForwardUtility. 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 variablevalues. 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 ChooseVariables. 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 thebeginning 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 tovariables, closes the Choose Variables session, and returns to the Carry Forward Review. Onceapplied variable values cannot be restored automatically, but they can be changed manually in asubsequent 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, CarryForward also allows manual changes to individual values. All variables and their current values aredisplayed beneath the Choose Command Bar. To manually change a variable value, type the desiredvalue 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 footersunder certain circumstances when removing a section with a header or footer and then replacing theremoved section. The expected change may not be displayed in the Carry Forward view when theheader 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 issueaffects sections after inserted data if the section is set to Link to Previous. Since the affected sectionsmay 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 andreturns to the normal xEditor view. This behavior is specific to the xEditor-based Carry ForwardUtility. 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 existingRevision Unit changes following these rules.• Insert Revision Unit from Search. A Revision Unit that is inserted from a Search is assigned therevision number of the searched Revision Unit. This remains the same after saving if there are nochanges to the inserted Revision Unit, but is the searched Revision Unit’s revision number plus 1 ifany changes are made to the inserted Revision Unit.

• Insert Content from Search. When an xDesign content item is added from a Search it is considereda 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 itemwas created or one that was inserted and previously saved. After saving any changes the revisionnumber 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 thefollowing logic.• Use Baseline. The baseline number is applied before saving and is retained after saving, unlessedited. 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 elapsedtime for all web service calls, and errors with stack traces. When a failure occurs, a message openswith a link that opens the file in a text editor.

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. Thelog file is located in C:\Documents and Settings\[USER]\Application Data\EMC DocumentSciences\[xEditor]\[server]\xEditor.log.

The Auto Carry Forward Log

An Auto Carry Forward log is generated during the compare process detailing the decisions madeby the carry forward engine.

The Carry Forward log can be deleted at any time and a new one will be created if necessary. Newactions are appended to the existing log if one is available. The Carry Forward log can be accessedfrom 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 DocumentSciences\[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 compareand baseline work item, the names of the adjacent revision units are detailed (this can happen inthe case of a move or an inserted revision unit).

For example:

Revision Unit Name: xPub2Baseline was auto selected because:

237

Preface

The Baseline revision unit is the default when both the Compare and the Baseline revision units areidentical

** Reference siblings have changed **Baseline previous revision unit: xPub1Baseline next revision unit: RU4Compare previous revision unit: xPub1Compare next revision unit: xPub3

238

Chapter 12The xCatalog Component

xCatalog is a Web-based administration interface used for the management of templates, forms, anddocuments. 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 alsoimport documents into xCatalog from the xPression database. Forms contained in the xPressFormssystems are also available in the xCatalog interface.

xCatalog comes with a complete set of APIs to create interfaces that enable an end-user to browsexCatalog and locate documents. Currently, there is no end-user interface for that purpose providedwith xCatalog.

Access RightsThe ability to perform actions in xCatalog is determined by the user access rights setting in xAdminfor your client application (xDesign or an xPresso client).

For xDesign users, both Read and Write (Content and Rule) access will allow you to Login andBrowse for documents. You need bothWrite:Content andWrite:Rule access to perform the followingtasks (you can also use the SharedAdmin or Approve access rights which include both Write:Contentand 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 fordocuments. You needWrite 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 InterfaceOnce you log on to xCatalog you will see the main screen. From the main screen you can accomplishall 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 optionsby clicking the menu. The File menu contains the following options.

Select this option To

Delete Delete the selected documents. For more information, see DeletingDocuments, page 254.

240



Import Import existing documents that were exported from another xCatalogsystem. For more information, see Importing Documents, page 252.

Export Export the selected documents and all of the applied metadata so theycan be used on another xPression Server running xCatalog. For moreinformation, see Exporting Documents, page 253.

Report Generate a report for selected documents that contains informationabout each document. For more information, see Creating DocumentReports, page 257.

Logout Log out of the xCatalog application. For more information, see LoggingOut, 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.


Add Tag Add a tag to a document. For more information, see Adding Tags toDocuments, page 253.

ManageCustomFields Open the Custom Fields window where you can see all the existingcustom fields, create new fields, delete fields, rename fields, and definedefault values for fields. For more information, see Managing CustomFields, page 255.

Change Status Change the status of the selected documents. Available default optionsare: Staging, Development, QA, Production, and Withdrawn. For moreinformation, 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.


Contents Opens the xCatalog online Help file where you can find informationabout using xCatalog.

About Opens the About dialog box where you can find information about thespecific version of xCatalog currently installed.

241


Browse and Search Pane

The pane that appears on the left side of the xCatalog interface contains three different sections thatenable 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 beadded or removed from the list. The tag group name appears at the folder level of the list. Clicking afolder 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 Lineof Business, Jurisdiction, and Bureau in the Browse area. Along with those groups, there is alsothe All group. If you don’t have xPressForms, you will only see the All group. The All group is aspecial folder that contains all the documents in the system, regardless of tags that maybe associatedwith them. This includes any documents with no tags, and any documents associated with customtags 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 atthe 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 theDocument list. You can select multiple tags in the pane; however, which documents are displayed inthe list depends on where the tags are located. If you select tags that reside in the same top-levelfolder, then the documents displayed will have an “OR” relationship. If you select tags that reside indifferent top level folders, the documents will have an “AND” relationship. For example, if you selectCommercial Umbrella and Workers Compensation under the Line of Business folder, then the listdisplays all the documents that are associated with the Commercial Umbrella tag or the WorkersCompensation tag. If you select Workers Compensation under Line of Business and the CA tag underState, then the list displays the documents associated with both the Workers Compensation tagand the CA tag.

The right-click menu enables you to add, rename, delete, copy, paste, or define properties for tags andfolders. See the following sections for more information.

Adding a Tag or Folder

To add a tag or folder to the list:1. Select the folder under which you want to add the item, right-click, and select Add. The Add a

Tag window appears.

242


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 Allfolder. 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 SelectParent 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, underthe folder that you selected.

Note: Tags in different groups can have the same name, and will not have any relationship to eachother. 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.


Deleting a Tag or Folder

You can delete tags or folders that appear in the Browse pane. If you delete a folder, all the tagscontained 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 alsoremoved. 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 variablesassociated with the tag are also copied. Once copied, the new set of variables are independent of theoriginal 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


3. Select the folder into which you want to paste the copied tag or folder, right-click, and select Paste.


Marking a Folder as Required

Folders can be specified as “required”. If a folder is required, a default tag must be identified. The Allfolder cannot be set as required. Required folders cannot be deleted, tags with associated documentscannot be deleted if they are in a required folder, and a tag in a required folder cannot be deleted ifthere 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 contentwithin a document. The content option works in conjunction with the other search items so you cansearch 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. Multipleoccurrences of the same filter type are treated with an OR condition, different filter types are treatedwith 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 selecttwo tags in different folders, they will be treated with an AND condition. For example, if youselect Commercial Umbrella and Workers Compensation under the Line of Business folder, thesearch will display all the documents that are associated with the Commercial Umbrella tag orthe Workers Compensation tag. If you select Workers Compensation under Line of Business andthe CA tag under State, then the search displays the documents associated with both the WorkersCompensation tag and the CA tag.

If you need to refine your search even more, xCatalog also provides the ability to perform a moreadvanced search using the same criteria types supported in the basic search, but with more operatoroptions. For more information, see Advanced Search, page 246.

244


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 facilitatessetting the date.

2. Click the plus (+) sign button. The item appears in the Applied Filter Criteria list. As you additems to the criteria list, the document list updates to represent the search criteria.

245


3. Click Custom Field Search to open the Custom Field Search dialog box, where you can select acustom 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 appearslisting all the tags currently defined. Select a tag and click OK. The tag name appears in theApplied 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 thelist 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, usingthe 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 brokendown by using brackets. This enables you to be more specific in your criteria, to refine your searchdown 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, orselect 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 selecta 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. Ifyou choose an operator, a new line appears, where you can continue your criteria expressionusing 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). Thedocument does not have to be effective for the entire search period to be selected. If a documentis 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


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, andare effective any time between 05/31/2009 and 07/31/2009, are returned by this search. The documentdoes not have to be effective for the entire search period to be selected. If a document is effective anytime 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/2009Withdrawn: 09/01/2009

This document was returned because it contains “Landlord” and “Business” in the descriptionand the effective date is within the date range.

• HO 02 03 07 09 Homeowner Form for Landlords


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


This document was not returned because it was not effective during the date range.

• HO 02 44 07 09 Homeowner Policy


This document was not returned because it does not contain the word “Landlord” in thedescription.

• CA 05 88 09 08 Commercial Landlord


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 promotedocuments in the Staging Area to a new status.

247


You can expand all the folders in the Staging Area pane by clicking the Expand All button at the topof 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 Editmenu, select Change Status. The Change Document Status window appears.

4. Select the new status for the document: Development, QA, Production, orWithdrawn andclick 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 allthe documents associated with the tag. For more information, see Browse Pane, page 242 orStaging Area Pane, page 247.

• If you define search criteria on the Search pane, the document list contains all the documents thatsatisfy 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 thexCatalog system, and xPression category. Select a document in the list to view more detailedinformation 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 ofthe interface in the document detail tabs section. Each tab displays specific information about theselected 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 thedocument’s category to modify any information in the document detail tabs section. For moreinformation, see Access Rights, page 239.

248


Information Tab

The Information tab displays the name and description for the selected document. A thumbnailimage of the document appears on the right side of the tab, if one if available. Only documents thathave 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 changethe 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, youcan modify the tags from this tab. If you do not have the correct access rights, this function willbe 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 Allto 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 yourclient 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 anduse the Add Tag function on the Editmenu. 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 yourclient application (xDesign or an xPresso client) in the document’s category to add notes. To addnotes to a document, type the text in the edit box, and then click Save Notes. Notes can consist ofup to 255 characters.

Note: If the Save Notes button does not appear on the tab, you do not have write access for yourclient application (xDesign or an xPresso client) in the document’s category.

249


Custom Fields Tab

The Custom Fields tab displays any custom fields that have been associated with the selecteddocument. You can also add or remove fields from the tab. The tab displays the name, value, and lastmodified 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 thexCatalog interface. Custom fields are created using the Manage Custom Fields function. For moreinformation, 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 columnmeans the custom field will be added to the document. No check mark means that the field willnot be added. You can click Select All or Deselect All (located at the bottom of the window) toselect 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 tabis 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-clickthis entry to edit it.

• Publisher. The xPression publishing engine the document was designed for. Currently, onlyxPublish 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


Using xCatalogThe Web-based application structure of xCatalog makes it an easy-to-use interface for maintainingthe 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 inthe xCatalog interface), the Session Expired dialog box appears. Type your password and click Log into return to the application without any interruption.

Importing and Exporting Documents

The import/export function enables you to move documents from one xPression Server runningxCatalog 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 andExporting Documents, page 253 for more information.

• Use the xAdmin Migration Utilities to import or export your xCatalog documents. xCatalog andxPressForms 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 xCatalogdocuments. xCatalog and xPressForms metadata is automatically migrated (if available) when thedocument is migrated. See the xAdmin Integration Guide for more information.

251


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 runningxCatalog. You can also use the xPression Content Repository option on the Import window to importdocuments stored in the xPression database that you have access to.

If your system contains required folders, the incoming documents are checked during the importprocess to see if they have the required tags. If a document doesn’t have a required tag, the defaulttag is automatically added to the imported document. For more information, see Marking a Folderas Required, page 244.

Note: When importing documents that contain metadata, xCatalog will migrate the metadata for thepackage, 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 inspectedand a list of documents included in the package appears.If you selected xPression Content Repository, the Import Documents dialog box appears anddisplays a list of categories and documents that you have access to, but that are not currently inthe xCatalog system. Select the documents you want to import, and click Add to move them intothe 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 existingdocuments in the xPression database that have the same name as ones being imported. Theimport process will abort with an error message if this option is left unchecked, and a documentalready exists in the xPression database.

6. Click Import to complete the import process. A message appears to tell you if your importwas successful.

7. Click OK. The new documents appear in the Staging Area with a status of Staging. Forinformation 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 splitthe large file into smaller files, or you can increase the PDP file maximum size setting in theMigration.properties file located in the xPression_Home directory. Be aware that this setting can’t belarger than 2GB.

252


Exporting Documents

You can export documents into a document package that can then be imported into an xCatalogapplication running on another xPression Server.

Note: When exporting documents that contain metadata, xCatalog will migrate the metadata for thepackage, 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 documentoption is selected, and the document name appears in the Document Name list. If you selectedmultiple documents, the Selected documents option is selected, and the documents appear inthe Document Name list. To export all the documents currently in the documents list, selectAll documents in list.

3. Specify the server path and file name of the export file and click Export. A message appears to tellyou 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 tofurther 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 multipledocuments 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 thedocument’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 theselected documents, or you can select all the documents in the documents list.

253


3. If you selected a single document, the Current document option is selected, and the documentname appears in the Document Name list. If you selected multiple documents, the Selecteddocuments option is selected, and the documents appear in the Document Name list. To add tagsto 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 orexpand 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 anyother xPression workflow setting, and is used for document maintenance. This status is a visualgrouping indicator that enables you to organize documents, manage the import/staging process, andcontrol 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 thedocument’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 documentname appears in the Document Name list. If you selected multiple documents, the Selecteddocuments option is selected, and the documents appear in the Document Name list. To changethe 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, orWithdrawn.

5. Click OK. The status for each of the selected documents is updated in the system and a messageappears 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 fromxCatalog. 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 thedocument’s category to delete a document. For more information, see Access Rights, page 239.

254


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 documentname appears in the Document Name list. If you selected multiple documents, the Selecteddocuments option is selected, and the documents appear in the Document Name list. To deleteall 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 thexCatalog interface.

The Manage Custom Fields function enables you to manage all the custom fields associated withdocuments 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 todocuments through the Custom Fields tab in the Document Details area. For more information, seeCustom 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 Editmenu, selectManage 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 alsoappear on the Custom Fields tab in the Document Details area so you can add the field to adocument.

255


Renaming a Field

You can rename a field in two different ways. You can use the Rename button at the top of the CustomFields window, or you can rename the field directly in the list.

To rename a field using the Rename button:1. From the Editmenu, selectManage 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 Editmenu, selectManage 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 Fieldswindow.

To define or change a default value:1. From the Editmenu, selectManage 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 asthey are not currently being used by a document. If you attempt to delete a field being used by adocument, xCatalog generates an error message.

To delete a field:1. From the Editmenu, selectManage Custom Fields. The Custom Fields window appears.

2. Select the field in the list.

256


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 abouteach document. When you generate a report, the file is saved in the temp directory defined inCatalog.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 thefollowing 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:<?xml version="1.0" encoding="UTF-8" ?>- <Documentss>- <Document><Document>WC 00 00 01 A</Document><Description>INFORMATION PAGE</Description><Status>Development</Status><Object_Type>xDesign - xPressForms</Object_Type><Object_Type_Version>3.0</Object_Type_Version><xPression_Design_Client>xDesign</xPression_Design_Client><Category>xPressForms</Category><xPression_Attribute_Set>xPressForms</xPression_Attribute_Set><Microsoft_Word_Template>C:\xPressFormsTemplate\xPressFormsWordTemplate.dot</Microsoft_Word_Template><Publisher>xPression Publish</Publisher><Notes>Ed. 5-88</Notes>- <Tags><Tag name="Line of Business" value="Workers Compensation" /><Tag name="Bureau" value="NCCI" /><Tag name="Bureau" value="ACORD" /><Tag name="State" value="UT" /><Tag name="State" value="GU" /><Tag name="State" value="MD" />

257


<Tag name="State" value="NJ" /></Tags>-</Document>

</Documents>

To create a document report:1. Select the document or documents that you want to create a report on.

2. From the Filemenu, select Report. The Generate report window appears.

3. If you selected a single document, the Current document option is selected, and the documentname appears in the Document Name list. If you selected multiple documents, the Selecteddocuments option is selected, and the documents appear in the Document Name list. To includeall 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 numberbetween 1 and 1000 is appended to the end of the file name you specify here. This is to avoidmultiple users from overwriting files.

6. (Optional) Click Select Fields to select the fields that you want to appear in the report. The SelectReport Fields window appears. The fields listed in this window differ depending on the outputformat of the report. If you select Comma Delimited File, the Tags and Custom Fields fields arenot 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 Fieldcolumn. To add a field, select the check box. You can also click Select All Fields to select all thefields 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 theCatalog.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 Filemenu, select Logout. You will be log out of the application and redirected to the logon page.

258

Chapter 13System 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 whenusing 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. Thesystem was designed with an open, component-based architecture based on standards like J2EE, WebServices, JMS, MS .NET, and XML.

xPression integrates with enterprise information systems, data, and distribution channels. The xPRSServer utilizes industry leading J2EE application servers and the standards-based architecture theyleverage. 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 ComponentsThe xPression Server is the core of the xPression suite. It consists of the components required forassembling, formatting, and distributing personalized documents. These components are written inJava and are hosted on your application server. The use of Java in both the xPression components andthe application server allows xPression to deliver a multiplatform compatible application that runs onseveral different operating systems, including: Windows, UNIX, and Linux systems. For a full list ofsupported 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 DocumentTemplate), customer data, and content. The BDT is the result of the “Generate XML” functionin xDesign. Output of a document assembly is a set of assembled content appropriate for yourcomposition 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 thedocument publication request to the appropriate composition engine. The publishers engine outputsPDL (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 functionsavailable 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 outputprocessing functions such as sorting and recipient processing, and supports PCL output. Metacodeoutput 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 (DeviceIndependent 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 specifiedPDL 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 distributespersonalized 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 upevery 30 seconds (a configurable option) and looks for work to do in xPression database distributiontables. When there is work to do, it sends e-mails, archive packages, and executes print scriptsaccording to distribution definitions configured in xAdmin.

Distribution Types

The distribution controller engine supports both online and offline distribution. In onlinedistribution, the distribution controller’s background process relays published documents directly tothe 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 aboutthe documents published) to the file system. Supports very high volumes and specialized archivalsystems:• 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 allxPression output management features. The batch engine requires xPRS Server installation files andconnectivity to xPRS Server EJBs. It may be invoked through a command shell batch file, Java classmain 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-zerofor warnings or failure). xPression batch jobs can be called and monitored by enterprise-class jobmanagement software. Several xBatch functions execute in parallel and can be tuned for optimal jobexecution.

xFramework ComponentsxFramework is the Application Programming Interface (API) for xPression. It enables you to builda custom interface to xPression assembly and distribution related services. The xFrameworkcomponents 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 documentrequester enables you to retrieve an assembled document from the content repository, and thedocument 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 viathe 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 mustprecisely match the Java client program you write with the xPression Server you will connect to bycopying the Java Archive (JAR) files. xPression supports near-time messaging through the JMSstandard.

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 servicesare 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 Javaand stored on a UNIX computer can be invoked from a Windows application written in VisualBasic, 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 AccessProtocol (SOAP). The client application constructs a SOAP “message” in XML format that includesthe name of the service, the method the client is invoking, and all required parameters. It then sendsthe message over the Web to the remote computer. The remote computer processes the request andsends back a SOAP “response,” indicating whether the call completed successfully and includingattachments, if necessary.

xPression Java API

The xPression Java API chapter helps you write xPression applications using the xPression high-levelJava API. The purpose of this chapter is to provide you with complete documentation for developingand implementing an xPression application solution. This chapter includes sample Java code,implementation and deployment instructions, and a complete command reference.

xPression Integration StrategiesFigure 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 requiredwhen 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 moreinformation, 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 yourweb-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 becauseprocessing concurrency can be restricted to the maximum amount the hardware can support.Messages in excess of processing concurrency are queued and processed when resources becomeavailable.

The xPression EAI Adapter supports the JMS (Java Message Service) specification. Vendor productslike IBM WebSphere MQ support JMS for guaranteed delivery of messages between systems. TheEAI 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 anoutput queue. Multiple MDBs can work in parallel on the same input queue if supported by theApplication Server vendor.

Batch Interaction

Batch is the most efficient method for producing high volumes of documents. This strategy requireslarge batches of data to be accumulated for bulk processing before you start the interaction. ThexPression EAI Adapter can watch for XML files and accumulate them for submission to a larger batchjob. These XML files can be directly placed in a watched file directory or relayed via web services orJMS messages.

At intervals defined by a batch job scheduler, the EAI Adapter gathers XML files for processing aparticular batch job and optionally transforms them to xPression “streamlined” XML. The XML filesare 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 14Deprecated xPression Web Services

This section covers the deprecated Web Services model. With version 4.0, xPression introduces a newWeb Service API that conforms to the WS-I Basic Profile. The old xFramework Web Service API, JavaAPI, and xAdapter have been deprecated. Although these items will be supported for backwardcompatibility in the current version, EMC Document Sciences encourages you to use the new WebService 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 overthe Web. However, unlike traditional distributed applications, Web services can be invoked acrossdifferent hardware and software platforms. Practically speaking, this means a Web service writtenin Java and stored on a UNIX computer can be invoked from a Windows application written inVisual Basic, Visual C++, or C#.

The technology that makes invoking remote components possible is called Simple Object AccessProtocol (SOAP). The client application constructs a SOAP “message” in XML format that includesthe name of the service, the method the client is invoking, and all required parameters. It then sendsthe message over the Web to the remote computer. The remote computer processes the request andsends back a SOAP “response,” indicating whether the call completed successfully and includingattachments, if necessary.

Before You BeginBefore you can develop and deploy custom xPression applications, you must first configure yourenvironment. You do this by adding your application definition to AppList.xml and configuring itusing xAdmin. Additionally, you must ensure your environment is configured to work with Axisversion 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 xPressionserver 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 thefollowing 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 yourapplication 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 DefinitionTo 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 <AppList></AppList> tags. Your application namemust not contain apostrophes (’).For example:<AppList><Application name="xPression Custom Application"></Application></AppList>

4. If your application supports workflow, type the workflow element.For example:<AppList><Application name="xPression Custom Application"><WorkFlow fromStatus="SUBMITTED" toStatus="APPROVED" enterAction="Write"promoteAction="Approve" /></Application></AppList>

5. Type the access rights your application supports, including whether or not they’re hierarchical.For example:<AccessRights heirarchical="yes"><Access name="Read" /><Access name="Write" /><Access name="Approve" /></AccessRights>

6. Type the required attributes, if any.For example:

268


<RequiredAttributes><Attr name="TEXTCLASS_ID" type="integer" min="0" max="0" ValidValueExist="0"Default_Value="" isMappable="0" stringlength="0" RangeExist="0"DefaultExist="0" multisingle="single" validValue=""/>

<Attr name="PRODUCT_ID" type="integer" min="0" max="0" ValidValueExist="0"Default_Value="" isMappable="0" stringlength="0" RangeExist="0"DefaultExist="0" multisingle="single" validValue=""/>

</RequiredAttributes><RequiredAttributes condition="SupportApproval"><Attr name="STATUS" type="string" min="0" max="0" ValidValueExist="1"Default_Value="PENDING" isMappable="0" stringlength="255" RangeExist="0"DefaultExist="0" multisingle="multi" validValue="PENDING;SUBMITTED;APPROVED"/><Attr name="EFFECTIVE_DATE" type="DateTime" min="0" max="0" ValidValueExist="0"Default_Value="" isMappable="1" stringlength="0" RangeExist="0"DefaultExist="0" multisingle="multi" validValue=""/><Attr name="WITHDRAW_DATE" type="DateTime" min="0" max="0" ValidValueExist="0"Default_Value="" isMappable="1" stringlength="0" RangeExist="0"DefaultExist="0" multisingle="multi" validValue=""/>

</RequiredAttributes>


8. Save AppList.xml and exit your text editor.Once complete, your application definition should appear similar to the following:<Application name="xPression Custom Application"><WorkFlow fromStatus="SUBMITTED" toStatus="APPROVED" enterAction="Write"promoteAction="Approve" /><AccessRights heirarchical="yes"><Access name="Read" /><Access name="Write" /><Access name="Approve" /></AccessRights></Application>

This sample application definition has workflow and access rights, but no required attributes.

Configuring Your Application with xAdminNow that you’ve added your application definition to AppList.xml, it’s time toconfigure it with xAdmin. To configure your application in xAdmin, complete thefollowing 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)



269


To associate attributes with your application:1. Start xAdmin.


3. Click an attribute set that you want to associate with your application. When you click theattribute set name, the Attribute Set page appears. Alternatively, you can also create a newattribute 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.


3. Select a data source group from the list and click Set Application.


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 SelectedUsers list.

4. Click Save. The selected users for the category now have access to your application.


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 assubmitters and approvers. Please consult the xAdmin User Guide to assist you in setting up workflowfor your application.

270


Authentication and Access Control

When a user invokes either the document requester or document composer Web services, xPressionauthenticates the user on the server and checks the user’s access to the document. Both Web servicesuse 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 theauthenticate method of the DSCSecuritySL object. If the method returns a string array containing theuser name and groups, the user is authenticated on the server. However, if an empty string array isreturned, 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 tothe document, an error is returned to the user.

Logging

The document requester and document composer Web services use the existing xPression loggingsystem. 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 onthe xPression server from which the user is requesting documents. If you’re an existing xPressioncustomer, you’ll need a separate license to enable Web services on your server. If you’re a newxPression customer, you’ll need to explicitly request the Web service feature when purchasing yourxPression software. For more information, see the xAdmin User Guide.

Using WebServices with xPresso PackagesThe xPressionRequest web service is the only web service that supports xPresso packages. TheDocument Requester, Revise Request and xResponse web services cannot retrieve xPresso packages.

271


Web Services Processing DiagramTo understand how xPression processes Web service requests, the following functional diagramillustrates the flow of the document requester service.

Figure 6. The following image shows the document requester functional flow.

1. SOAP RequestThe document requester client generates a SOAP request and sends the request by meansof an HTTP POST. The client request specifies the DocumentRequester service and therequestDocuments method. The request also includes parameters such as documentName.

2. Request Routed to ServletThe application server receives the incoming request and forwards it to the Apache rpcrouterservlet.

3. Servlet Looks Up DocumentRequesterThe rpcrouter looks up the DocumentRequester, instantiates a DocumentRequester object andinvokes the requestDocuments method.

272


4. requestDocuments Calls EJBsThe requestDocuments method calls the AssemblyEngine Enterprise Java Bean (EJB) and otherJava Beans to assemble the requested document and return an array of streams.

5. Rpcrouter Returns SOAP ResponseThe rpcrouter captures the results, packages them into a SOAP response, and returns the responseto the client.

The Document Requester Web ServiceThe document requester Web service enables you to retrieve an assembled xPression documentin the format you specify by passing an output profile name. If successful, the xPression serverpasses back an array containing the document (or stream) name, the output format name, and theassembled document stored in a byte array. The format of the returned byte array depends on theoutput 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 thecustomer key values. The second accepts an XML stream containing a customer record. We’lldiscuss 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 databaseby passing the customer data key values. Use this method only if the category your documentis associated with has an RDB data source. This method returns an object that contains the streamname, format, and a byte array containing the returned document. It is up to the calling program tosave the byte array as a file.

Note: All input parameters are case sensitive. For example, if your output profile is “PDF to File,” butyou pass “PDF to file,” the SOAP request will fail.

Syntax

OPStream[] = requestDocuments(documentName, customerKey, outputProfileName,userName, passWord[], appName)

273


Parameters


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 arealways stored in the primary table of the data source. The following samples show how the XMLshould be formatted:

<Keys>

<Key name="AUTOPAY_KEY">1</Key>

</Keys>

-or-

<Keys>


<Key name="LANGUAGE">English</Key>

</Keys>


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 applicationin xAdmin.

passWord[] : Byte

An encrypted byte array specifying the password for the user who has been granted access rightsto the category and application in xAdmin. Use the webtool.jar utility to convert a text passwordto an encrypted byte array.

appName : String

A string specifying the application name defined in AppList.xml. You must associate the applicationwith a category accessed by the Web service. For example, if you defined “xPression WebService” inAppList.xml, be sure to associate it with the category that contains the document you’re retrievingfrom the content repository.

Requesting a Document by XML Customer Data

The requestDocumentsWithData method enables you to retrieve a document from the xPressiondatabase 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 onlyif the category your document is associated with has an XML data source. This method returns anobject that contains the stream name, format, and a byte array containing the returned document. It isup to the calling program to save the byte array as a file.

274


Note: Note: All input parameters are case sensitive. For example, if your output profile is “PDF toFile,” but you pass “PDF to file,” the SOAP request will fail.

Syntax

OPStream[] = requestDocumentsWithData(documentName, customerKey, customerData,dataSourceName, outputProfileName, userName, passWord, appName)

Parameters


Specifies the name of the document you’re retrieving from the content repository.


An XML string containing the key values for a specific customer record. Customer key values arealways stored in the primary table of the data source. The following samples show how the XMLshould be formatted:

<Keys>


</Keys>

-or-

<Keys>


<Key name="LANGUAGE">English</Key>

</Keys>


A string containing a customer record in XML format. The XML stream can contain a single recordfrom the primary table and, optionally, additional related records from secondary tables in your datasource. For example, if you were requesting the Withdrawal Notice Letter document, your XMLstream would contain a single record from the primary table.<?xml version="1.0" encoding="UTF-8"?><CustomerData><WITHDRAWAL><KEY>1</KEY><NAME>Sara Jones</NAME><STREET_ADDRESS>6732 River Run</STREET_ADDRESS><CITY_STATE_ZIP>University City, CA 22445</CITY_STATE_ZIP><LETTER_DATE>August 5, 2002</LETTER_DATE><POLICY_PURCHASED>Flexible Premium VariableLife Insurance Policy</POLICY_PURCHASED><SALES_LOAD>2.5%</SALES_LOAD><STATE_PREMIUM_TAX>2.5%</STATE_PREMIUM_TAX>

275


<POLICY_NUMBER>78889567</POLICY_NUMBER><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFDATE>2005-12-31</EFFDATE></WITHDRAWAL></CustomerData>

The value of the key for the customerKey parameter must be the same value referenced in thecustomerData parameter. For example, if the customerKey parameter has a value of 1 but thecustomerData 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 invokerequestDocumentsWithData, you must provide an XML data source here. Otherwise, the methodwill return a SOAP Fault.



userName : String


passWord : Byte[]


appName : String

A string specifying the application name defined in AppList.xml. You must associate the applicationwith a category accessed by the Web service. For example, if you defined “xPression WebService” inAppList.xml, be sure to associate it with the category that contains the document you’re retrievingfrom the content repository.

Request Document by Output Profile

This method publishes a document to an output profile given as input. If For all return tocaller streams in the output profile the Stream Name, Stream format and Stream Output will bereturned. The return parameter will be null if no return to calling application output streamsare found. This method is a new method to the Document Requester web service. It is a hybridof the Document Requester requestDocumentsWithData method and the xPressionRequestpublishAndReturnDocument Method. The methods used to return the datasource inxPressionRequest should be used similarly in this method. Also please note there is not a need for anencrypted password in this method. It is very important that the returned data includes not only theoutput but the stream name and format so the client can differentiate between the different streamsand operate on them properly based on the format.

Should the method fail, it returns a Simple Object Access Protocol (SOAP) fault. The text of theSOAP fault contains a unique identifier error code and accompanying error message with detailsand data related to the error.

276


Syntax

OPStream [] streamArray = requestDocumentsByOutputProfile(documentName, userName,password, outputProfile, customerData, applicationName)

Parameters


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 thedocument requested. If the user does not have permission to read the document according to itscategory 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.


An XML document containing data required to assemble the document given as input. This datamust match an XML data source defined in xAdmin as the default data source for the documentcategory and application name given as input.

applicationName : String

The xPression Application Name defined and configured in xAdmin for the category the documentbelongs to.

The Document Composer Web ServiceThe document composer service enables you to distribute a previously assembled document, usingany output profile defined in xAdmin. You can use this service in tandem with the documentrequester by invoking either requestDocuments or requestDocumentsWithData to retrieve adocument. 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


277


The Compose Document Method

The method returns a 0 if the service successfully processes the request. Otherwise, the methodreturns 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,” butyou 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.


Specifies the name of the document you’re distributing.


Specifies the name of the output profile you’re using to distribute the supplied document. For moreinformation, see the Administering the xPression Server guide.

userName : String


passWord : Byte[]


The xPression Request Web ServiceThe xPression Request web service contains methods to conveniently access some of the mostcommon xPression services.

The wsdl description for xPressionRequest can be viewed at following location:http://localhost:8080/xPressionWebService/services/xPressionRequest?wsdl


278


xPression Request contains the following methods: Publish Document, Preview PDF, View Categoriesfor User, View Documents in Category, View Output Profiles for Document, Get BDT, Get AssembledDocument, Publish MSOHTML Document, and Publish and Return Document.

Note: This Web Service will generate an error message if no output stream generates output duringpublishing.

The Publish Document Method

The Publish Document web service method allows you to input an XML document as a customerdata source override. The XML document must match the default data source group assigned tothe document’s category. The web service method will override the customer data source with theprovided XML document and publish that document to the output profile specified. “Return tocalling application” output streams will not be returned. The method returns a String as an outputparameter if the method completes successfully. The output string will have the following format:Message <messageID> was successfully published to output profile <outputProfile>

where <messageID> is the primary key of the primary table in the data source and <outputProfile> isthe 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 moreinformation, see Errors, page 300. This method supports xDesign documents and all xPressopackages with one exception. If you are producing HTML output, xPresso for InDesign packages arenot supported.

Syntax

publishDocument(DocumentName, UserName, Password, OutputProfile, CustomerData,AppName)

279


Parameters

documentName: String

Specifies the name of the document you are retrieving from the xPression database.

userName : String


passWord : String

A string specifying the password for the corresponding user name.


Specifies the name of the output profile you’re using to distribute the supplied document.


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 HTMLformat and return the file back to the adapter as an HTML Return to Application stream. Themethod returns a published HTML document as a Byte array. The array is serialized with BASE64encoding/decoding according to the SOAP standard. If the method fails, it returns a SOAP Fault thatindicates the reason for the failure. For more information, see Errors, page 300. xDesign documentsand other xPresso packages are not supported with this web service.

Syntax

previewHTML(DocumentName, UserName, Password, CustomerData, AppName)

280


Parameters



userName : String


passWord : String




appName : String


The Preview PDF Method

The preview PDF service enables you to publish an xDesign document or xPresso for Adobe InDesignpackage 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 BASE64encoding/decoding according to the SOAP standard. If the method fails, it returns a SOAP Faultthat indicates the reason for the failure. For more information, see Errors, page 300. xPresso forDreamweaver 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 outputdefinition.

Username and Password Filter

Prior to xPression 3 build 30, it was possible to pass incorrect information for the username andpassword. Under certain circumstances, such as passing a data source for username, it was possibleto cause the native code authentication software to abort and so shut down the server. To preventthis, username and password are now filtered as part of authentication and will not be passed ifthey do not meet these minimum standards:• Maximum string length 256 characters

• No embedded EOL characters

• No leading or trailing blanks

281


Syntax

previewPDF(DocumentName, UserName, Password, CustomerData, AppName)

Parameters



userName : String


passWord : String




appName : String


The View Categories for User Method

The view categories for user service returns a list of categories available to the defined user. Themethod can complete successfully without returning any category names. This indicates that the userhas not been given access rights to any xPression categories. If the method fails, it returns a SOAPFault that indicates the reason for the failure. For more information, see Errors, page 300.

Syntax

categoryForUser(UserName, Password, AppName)

Parameters

userName : String


passWord : String


282


appName : String


The View Documents in Category Method

The view documents in category service returns a list of all xDesign documents and xPresso packagescontained in the defined category. This list is returned as a String array that contains one documentname for every document that resides in the defined category. This method can complete successfullywithout 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


passWord : String


appName : String


The View Output Profiles for Document Method

The view output profiles for document service returns a list of output profiles assigned to thedocument from xDesign. This list is returned as a String array that contains one output profilename for every output profile assigned to the defined document. This method can completesuccessfully without returning any output profiles, indicating that no output profiles are assigned tothe document. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. Formore information, see Errors, page 300. This web service can only be used with xDesign documents.xPresso packages are not supported with this function.

283


Syntax

outputProfilesForDocument(DocumentName, UserName, Password, AppName)

284


Parameters


A string specifying the name of the document whose output profiles you want to view.

userName : String


passWord : String


appName : String


The Get BDT Method

The get BDT web service returns a string that is an assembled list using the xDesign document nameand customer data. The assembled list is the xDesign BDT that has already been updated withvariables. This web service can only be used with xDesign documents. xPresso packages are notsupported with this function.

Syntax

getBDT (documentName, customerData, userName, password, appName)

Parameters





userName : String


password : String


appName: String


285


The Get Assembled Document Method

The get assembled document web service returns a byte array that is an assembled xDesign documentin MSOHTML format. This web service can only be used with xDesign documents. xPresso packagesare not supported with this function.

Syntax

getAssembledDocument (documentName, customerData, userName, password, appName)

Parameters





userName : String


password : String


appName: String


The Publish MSOHTML Document Method

The publish MSOHTML document web service returns a string array that is an assembled xDesigndocument in MSOHTML format. If the distribution defintion is “return to caller”, the return valuewill include the output format. If the distribution definitions is not return to caller, the return valuewill be empty. This web service does not support xPresso packages.

Syntax

publishMSOHTMLDocument (documentName, customerData, msohtml, outputProfileName,userName, password, appName)

286


Parameters





msohtml: byte[]

A byte array containing an assembled document.



userName : String


password : String


appName: String


The Publish And Return Document Method

This method publishes a document to an output profile given as input. If the output profile has asingle return to calling application distribution definition defined in the output profile, that streamwill be returned to the caller. The return parameter will be null if no return to calling applicationoutput streams are found. If more than one return to caller output stream is found, the method willreturn the first stream found (order not guaranteed) so you should be certain that if you expect adocument to be returned of a particular format, you only call an output profile which has one andonly one output stream returned.

Should the method fail, it returns a Simple Object Access Protocol (SOAP) fault. The text of theSOAP fault contains a unique identifier error code and accompanying error message with detailsand data related to the error.

Syntax

byte[] publishedDocument = publishAndReturnDocument(documentName, userName,password, outputProfile, customerData, applicationName)

287


Parameters


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 thedocument requested. If the user does not have permission to read the document according to itscategory 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.


The output profile the document will be published to.


An XML document containing data required to assemble the document given as input. This datamust match an XML data source defined in xAdmin as the default data source for the documentcategory and application name given as input.

applicationName : String

The xPression Application Name defined and configured in xAdmin for the category the documentbelongs to.

The xResponse Web ServiceThe xResponse Web Service contains the following methods: Assign Document to User, RetrieveWork in Progress IDs Assigned to a User, and Reassign Work Item. This web service does notsupport 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 tothe xResponse user’s Work in Progress queue.

If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAPfault contains a unique identifier error code and accompanying error message with details anddata related to the error.

The method returns the WIP ID as a string if the method completes successfully.

288


Caution: If you use the Assign Document to User method you will not be able to use optionalparagraphs. 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 followingURL: http://<server:port>/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 musthaveWrite_Document permission for the category that contains the requested document. If the userdoes not have the correct permissions, the request will be rejected.

AdminPassword : String

The password that corresponds to the AdminUserName, authenticated by xPression platformsecurity.

AssignToUserName: String

The user name to whom you are assigning the document. The document will be listed as a work inprogress item when the user logs into xResponse.

CustomerData : String

The assignDocumentToUser web service locates the primary data source defined for the category thatcontains the document you want to assign. The web service then locates the default data source forthe primary data source definition. Both the primary data source and the default data source must bein XML format. The input for this parameter is the XML document for the default data source. Thisdata source must be a valid XML document according to the xPression data source definition.

289


The Retrieve Work In Progress IDs Assigned to a UserMethod

This method returns a String array of WIP IDs assigned to the xResponse user’s work in progressqueue.

Note: This method does not authenticate the WIPUserName parameter. If you provide a bad username as input, the method will simply return an empty string array of WIP IDs.


The caller can call the “wipIdsForUser” web service method with the following URL:http://<server:port>/xPressionWebService/services/xResponseRequest?method= wipIdsForUser

Syntax

wipIdsForUser(AdminUserName, AdminPassword, WIPUserName)

Parameters


The username that the method will use to log in as the xResponse work administrator. This user musthave permission to approve documents in xResponse.



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 '<WorkItemID>' was successfully reassigned to the work in progressqueue for user '<AssignToUserName>'

where WorkItemID is the WIP ID of the work item you want to reassign, and AssignToUserName isthe user name to whom you are assigning the work item.


290


The caller can call the “reassignWorkItem” web service method with the following URL:http://<server:port>/xPressionWebService/services/xResponseRequest?method= reassignWorkItem

Syntax

reassignWorkItem(AdminUserName, AdminPassword, AssignToUserName, WIPID)

Parameters





AssignToUserName : String


WIPID : String

The WIP ID that you want to reassign. This work item will be reassigned to the AssignToUserNamespecified above.

The Create Work Item Method

This method is designed for use with xEditor. This method creates a work in progress ID (WIP ID) forthe document and assigns the WIP ID to the xResponse user’s Work in Progress queue. This methodenables 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.


The caller can call the "createWorkItem" web service method with the following URL:http://<server:port>/xPressionWebService/services/xResponseRequest?method=

Syntax

createWorkItem(documentName, adminUserName, adminPassword, assignToUserName,

291


customerData)

Parameters



adminUserName : String


adminPassword : String





The createWorkItem web service locates the primary data source defined for the category thatcontains the document you want to assign. The web service then locates the default data source forthe primary data source definition. Both the primary data source and the default data source must bein XML format. The input for this parameter is the XML document for the default data source. Thisdata 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 DOCXoutput. This method returns a byte array of the document content. Note that there is a method withthe same name in the xPression Request web service. There are significant differences betweenthe two methods.

Syntax

publishAndReturnDocument (String wipID, String username,String password, String outputProfileName)

Parameters

This web service employs the following parameters.

292


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.


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 theIDocumentItem web service.

The Revise request web service contains the following methods: Assign Document to User, RetrieveWork in Progress IDs Assigned to a User, Reassign Work Item, Query Work Item Status, CompleteItem, Preview Work Item In PDF, Update Work Item Primary Data, Delete Work Item, and Publishand 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 thexRevise 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 accompanyingerror message with details and data related to the error.

The method returns the WIP ID as a string if the method completes successfully. Thecaller can call the “assignDocumentToUser” web service method with the following URL:http://<server:port>/xPressionWebService/services/xReviseRequest?method= assignDocumentToUser

Syntax

assignDocumentToUser(DocumentName, AdminUserName, AdminPassword, AssignToUserName,CustomerData)

Parameters

DocumentName : String

293




The username that the method will use to log in as the xRevise work administrator. This user musthave xRevise “Admin” privilege for the category that contains the requested document. If the userdoes not have the correct permissions, the request will be rejected.



AssignToUserName : String

The user name to whom you are assigning the document. The document will be listed as a work inprogress item when the user logs into xRevise.

CustomerData : String

The assignDocumentToUser web service locates the primary data source defined for the category thatcontains the document you want to assign. The web service then locates the default data source forthe primary data source definition. Both the primary data source and the default data source must bein XML format. The input for this parameter is the XML document for the default data source. Thisdata source must be a valid XML document according to the xPression data source definition.

The Retrieve Work In Progress IDs Assigned to a UserMethod

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 username as input, the method will simply return an empty string array of WIP IDs.


The caller can call the “wipIdsForUser” web service method with the following URL:http://<server:port>/xPressionWebService/services/xReviseRequest?method= wipIdsForUser

Syntax

wipIdsForUser(AdminUserName, AdminPassword, WIPUserName)

Parameters


294


The username that the method will use to log in as the xRevise work administrator. This user musthave permission to approve documents in xRevise.



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 '<WorkItemID>' was successfully reassigned to the work in progressqueue for user '<AssignToUserName>'

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.


The caller can call the “reassignWorkItem” web service method with the following URL:http://<server:port>/xPressionWebService/services/xReviseRequest?method= reassignWorkItem

Syntax

reassignWorkItem(AdminUserName, AdminPassword, AssignToUserName, WorkItemID)

Parameters


The username that the method will use to log in as the xResponse work administrator. This user musthave the xRevise “Admin” priviliege for the category that contains the requested document. If theuser does not have the correct permissions, the request will be rejected.

AdminPassword: String


AssignToUserName

The user name to whom you are assigning the document. The document will be listed as a work inprogress item when the user logs into xRevise.

295


WorkItemID

The WIP ID that you want to reassign. This work item will be reassigned to the AssignToUserNamespecified 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 moveswork 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


username : String

The current username. The user must be the work item owner to use this web service.

password : String


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.


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 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


Parameters

This Web service includes the following parameters.


This user must have the xRevise “Admin” privilege for the category that contains the requesteddocument. If the user does not have the correct permissions, the request will be rejected.


The password that corresponds to the AdminUserName, authenticated by xPression securityplatform.

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 asinput. The web service then locates the default data source for the primary data source definitionand extracts only the primary table variables from the XML and only those variables that are not keyfields. Both the primary data source and the default data source must be in XML format. The inputfor this parameter is the XML document for the default data source. This data source must be awell 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 retainedthroughout 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


Syntax

deleteWorkItem(AdminUserName, AdminPassword, WorkItemID)

Parameters

This Web service includes the following parameters:


The user name that the method uses to log in as the xRevise work administrator. This user must havethe xRevise “Admin” privilege for the category that contains the requested document. If the userdoes not have the correct permissions, the request will be rejected



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:


The user name that the method uses to log in as the xRevise work administrator. This user must havethe xRevise “Admin” privilege for the category that contains the requested document. If the userdoes not have the correct permissions, the request will be rejected

299




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.

ErrorsIf an error occurs while either the document requester or document composer Web services areprocessing a request, the method returns a SOAP Fault to the client, indicating the reason for theerror. The following is an example of a SOAP Fault:<SOAP-ENV:Envelopexmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"xmlns:xsd="http://www.w3.org/1999/XMLSchema"><SOAP-ENV:Body><SOAP-ENV:Fault><faultcode>9005</faultcode><faultstring>Document not found</faultstring><faultactor>/soap/servlet/rpcrouter</faultactor></SOAP-ENV:Fault></SOAP-ENV:Body></SOAP-ENV:Envelope>

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 SunMicrosystems. For COM or .NET applications, the SOAP Toolkit provides methods for displayingfault codes and strings.

To see a list of all error codes produced by the xPression Web Services, see theresource_webservice_error.properties file located in your xPressionHome directory.

300

Chapter 15The Deprecated xPression Java API

This section covers the deprecated Web Services model. With version 4.0, xPression introduces a newWeb Service API that conforms to the WS-I Basic Profile. The old xFramework Web Service API, JavaAPI, and xAdapter have been deprecated. Although these items will be supported for backwardcompatibility in the current version, EMC Document Sciences encourages you to use the new WebService 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 methodsin the high-level xPression Java API. We’ll also show you how to create an application that generatesinstant auto and homeowners insurance quotes and discuss various approaches to packaging anddeploying your J2EE xPression application.

Writing an XPression Facade Java ClassIn this section, we’ll show you how to connect to an xPression server, retrieve categories, retrievedocuments associated with a specific category, and assemble and retrieve a PDF document stored inthe content repository.

The complete application we’re going to create is an automatic insurance quote generator. In the nextchapter, we’ll show you how to create the thin client piece of the application that calls the Java classwe’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.jarlibrary in the classpath for your development environment. We’re now ready to create our Javaclass 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 wherexPression will store PDF documents. To avoid hard coding a path in the Java class, let’s create asimple 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 Cdrive. Also, we’re assuming you’re deploying the application to the xPression.ear enterpriseapplication. Both these assumptions may not reflect your actual environment. For example, youmay use BEA WebLogic as your application server and you may deploy the Quote Generatorapplication to a different enterprise application than xPression. Therefore, your tempPath settingwould 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 thefollowing 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 directorylevel. Now add the connect method below the variable declarations:

public void connect(String url, String context, String userName, String password,String appName) {

try {

302


//init the xPression server

facade = new XPressionFacade();

303


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 yourxPression home directory for valid entries. You’ll also notice we’re calling a method to retrievethe 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


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 getDocumentmethod: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


Notice that this method requires that we pass both the XML data source name and the XML datastream 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 nameString 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 afile 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 ApplicationIn this section, we’ll show you how to create an application that generates instant auto andhomeowners insurance quotes. The application will consist of several JSP pages that call thequote_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 togenerate 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


• 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 classpathfor your development environment. Additionally, the application uses two documents you’ll need toimport into the xPression database you’re using for development, as well as sample data for eachdocument. 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 computerwith 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


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 Generatorapplication.

Quote_Gen.war\css Contains the css.css stylesheet we’ll use for minor formatting of theJSP pages. You’ll find the stylesheet on the eBooks CD in \\xPressionFramework\XDK\source\css.

Quote_Gen.war\images Contains the image files we’ll use for minor formatting of the JSPpages. You’ll find the images on the eBooks CD in \\xPressionFramework\XDK\source\images.

Quote_Gen.war\META-INF Contains the MANIFEST.MF file that is generated when you create aWAR with a J2EE development tool like WebSphere Studio. For moreinformation, see Deploying an xPression Application, page 320.

Quote_Gen.war\WEB-INF Contains files describing your application. For more information, seeDeploying 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 thisapplication, we’re only using xPressionJavaAPI.jar. You’ll find this file inyour xRevise and xResponse EAR files.

Quote_Gen.war\xPression-Docs

Contains the PDF documents your application generates when a userrequests 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 couplestandard 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:<HTML>

<HEAD><TITLE>xPression Quote Generator</TITLE><LINK rel="stylesheet" href="./css/css.css" type="text/css"></HEAD><BODY BGCOLOR="WHITE" TEXT="BLACK" TOPMARGIN="0" LEFTMARGIN="0"MARGINHEIGHT="0" MARGINWIDTH="0">

<TABLE width="100%" border="0" cellspacing="0" cellpadding="0"><tr><TD class="title1_13" align="center"><BR>xPression Quote Generator</TD></tr><TR>

308


<TD valign="bottom" align="center" width="90%"><IMG src="images/pixel-blue.gif"width="99%" height="1" vspace="4"></TD>

</TR></TABLE>

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

<DIV align="center"><FORM ACTION="index.jsp" METHOD="post" name="postform" target="_top"><A HREF="index.jsp" TARGET="_top"><SPAN class="no_dec">[Start Over]</SPAN></A></FORM></DIV></BODY></HTML>

3. Finally, add the code for ftr.jsp:<LINK rel="stylesheet" href="./css/css.css" type="text/css">

<TABLE width="100%" border="0" cellspacing="0" cellpadding="0"><TR><TD valign="bottom" align="center" width="90%"><IMG src="images/pixel-blue.gif"width="99%" height="1" vspace="4"></TD>

</TR><TR>

<TD colspan=2 align="right" class="c">© Document SciencesCorporation 2004. All rights reserved. </TD>

</TR></TABLE></BODY></HTML>

Presenting a List of Categories

We’ll now create a JSP page that displays the policy types the user will choose from to generate aquote. In your JSP editor, create a new page called index.jsp.

Add the following code to index.jsp:<jsp:useBean class="quote_gen.quote_gen" id="quote_gen" scope="session"/><%@ include file="hdr.jsp" %>

309


<%//replace with appropriate values depending on environmentString url = "iiop://localhost:9081";String context = "com.ibm.websphere.naming.WsnInitialContextFactory";String userName = "xpression";

//for security purposes, use an encrypted password that you//decrypt hereString password = "xpression";String appName = "xPression Response";

//connect to xPressionquote_gen.connect(url,context,userName,password,appName);

//get categoriesString categories[] = quote_gen.getCategories();%>

<FORM name="postform" method="post" action="getDocuments.jsp"><TABLE align="center" border="0" cellspacing="0" cellpadding="0"><TR><TD class="copy"> </TD></TR><TR><TD class="table_copy"><SPAN class="subtitle">Select a policy type:</SPAN><BR><SELECT size="1" name="categoryName"><% for (int i=0;i<categories.length;i++) { %><OPTION value="<%=categories[i]%>"><%=categories[i]%></OPTION><% } %></SELECT><P><input type="submit" NAME="getDoc" value="Next >>" /></TD></tr></TABLE></FORM><%@ 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


• In the script block, we’re initializing the variables we need to start the xPression session. Observethat we’re making certain assumptions about the xPression environment. You’ll need to modifythese variables in your own environment. For example, the context factory value will be differentif 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 namesretrieved 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:<jsp:useBean class="quote_gen.quote_gen" id="quote_gen" scope="session"/><%@ include file="hdr.jsp" %><%String categoryName = request.getParameter("categoryName");String docs[] = quote_gen.getDocumentNames(categoryName);session.setAttribute("categoryName",categoryName);%><FORM name="postform" method="post" action="getInputs.jsp"><TABLE align="center" border="0" cellspacing="0" cellpadding="0"><TR><TD class="copy"> </TD></TR><TR><TD class="table_copy"><SPAN class="subtitle">Select a quote:</SPAN><BR><SELECT size="1" name="docName"><% for (int i=0;i<docs.length;i++) { %><OPTION value="<%=docs[i]%>"><%=docs[i]%></OPTION><% } %></SELECT><P><input type="submit" NAME="getInputs" value="Next >>" /></TD></tr></TABLE></FORM><%@ 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 thegetDocumentNames method in the quote_gen Java class.

311


• We’re setting a session variable for the category. In subsequent pages, we’ll need to know whichcategory the user has selected.

• Finally, we’re populating a drop-down list with all the document names returned by thegetDocumentNames method.

312


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 owndata sources. Therefore, our quote application will present different input fields based on thecategory 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);%>

<FORM name="postform" method="post" action="getQuote.jsp"><TABLE align="center" border="0" cellspacing="0" cellpadding="0"><TR><TD><SPAN class="subtitle">Please provide values in the following fields:</SPAN><BR /><BR /><BR /><% if (categoryName.equals("Auto")) { %>

<SPAN class="subtitle">First Name:</SPAN><BR /><INPUT name="F_NAME" size="50" value=""> <P><SPAN class="subtitle">Middle Initial:</SPAN><BR /><INPUT name="M_INIT" size="50" value=""> <P><SPAN class="subtitle">Last Name:</SPAN><BR /><INPUT name="L_NAME" size="50" value=""> <P><SPAN class="subtitle">Address:</SPAN><BR /><INPUT name="PROP_ADDR_1" size="50" value=""> <P><SPAN class="subtitle">City:</SPAN><BR /><INPUT name="PROP_CITY" size="50" value=""> <P><SPAN class="subtitle">State:</SPAN><BR /><INPUT name="PROP_STATE" size="50" value=""> <P><SPAN class="subtitle">Zip:</SPAN><BR /><INPUT name="PROP_ZIP" size="50" value=""> <P><SPAN class="subtitle">Make:</SPAN><BR /><INPUT name="MAKE" size="50" value=""> <P><SPAN class="subtitle">Model:</SPAN><BR /><INPUT name="MODEL" size="50" value=""> <P><SPAN class="subtitle">Model Year:</SPAN><BR /><INPUT name="YEAR" size="50" value=""> <P><SPAN class="subtitle">Deductible:</SPAN><BR /><INPUT name="DEDUCTIBLE" size="50" value=""> <P><SPAN class="subtitle">Auto Coverage Limit:</SPAN><BR /><INPUT name="AUTO_CVG_LIMIT" size="50" value=""> <P><SPAN class="subtitle">Personal Property Coverage Limit:</SPAN><BR /><INPUT name="PERS_PROP_CVG_LIMIT" size="50" value=""> <P><SPAN class="subtitle">Loss of Use Limit:</SPAN><BR /><INPUT name="LOSS_USE_CVG_LIMIT" size="50" value=""> <P><SPAN class="subtitle">Liability Protection (each occurrence):</SPAN><BR /><INPUT name="LIAB_PROT_LIMIT" size="50" value=""> <P><SPAN class="subtitle">Medical Payments to Others (each person):</SPAN><BR /><INPUT name="MED_PAY_LIMIT" size="50" value=""> <P><%}else {%>

313


<SPAN class="subtitle">First Name:</SPAN><BR /><INPUT name="F_NAME" size="50" value=""> <P><SPAN class="subtitle">Middle Initial:</SPAN><BR /><INPUT name="M_INIT" size="50" value=""> <P><SPAN class="subtitle">Last Name:</SPAN><BR /><INPUT name="L_NAME" size="50" value=""> <P><SPAN class="subtitle">Address:</SPAN><BR /><INPUT name="PROP_ADDR_1" size="50" value=""> <P><SPAN class="subtitle">City:</SPAN><BR /><INPUT name="PROP_CITY" size="50" value=""> <P><SPAN class="subtitle">State:</SPAN><BR /><INPUT name="PROP_STATE" size="50" value=""> <P><SPAN class="subtitle">Zip:</SPAN><BR /><INPUT name="PROP_ZIP" size="50" value=""> <P><SPAN class="subtitle">Deductible:</SPAN><BR /><INPUT name="DEDUCTIBLE" size="50" value=""> <P><SPAN class="subtitle">Dwelling Coverage Limit:</SPAN><BR /><INPUT name="DWEL_CVG_LIMIT" size="50" value=""> <P><SPAN class="subtitle">Other Structures Coverage Limit:</SPAN><BR /><INPUT name="OTH_STR_CVG_LIMIT" size="50" value=""> <P><SPAN class="subtitle">Personal Property Coverage Limit:</SPAN><BR /><INPUT name="PERS_PROP_CVG_LIMIT" size="50" value=""> <P><SPAN class="subtitle">Loss of Use Limit:</SPAN><BR /><INPUT name="LOSS_USE_CVG_LIMIT" size="50" value=""> <P><SPAN class="subtitle">Liability Protection (each occurrence):</SPAN><BR /><INPUT name="LIAB_PROT_LIMIT" size="50" value=""> <P><SPAN class="subtitle">Medical Payments to Others (each person):</SPAN><BR /><INPUT name="MED_PAY_LIMIT" size="50" value=""> <P><%}%><input type="submit" NAME="getQuote" value="Get Instant Quote" /></TD></tr></TABLE></FORM><%@ 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


Figure 10. The resulting GetInputs.jsp page should look like this when launched in your browser. Thisgraphic 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, thegetQuote.jsp page is executed.

Let’s now add the code for getQuote.jsp:<jsp:useBean class="quote_gen.quote_gen" id="quote_gen" scope="session"/>

<%!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 valuesString categoryName=session.getAttribute("categoryName").toString();String docName = session.getAttribute("docName").toString();

//init varsString xmlDataSource = "";String xmlData = "";String extension = ".pdf";

//this is an arbitrary number - obviously some calculation is necessaryString annualPremium = "1150.00";

315


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 stringif (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 stringxmlData = "<dataroot><RECORD><AUTO_CLIENT><CLIENT_NO>" + zip + fName +"</CLIENT_NO>";xmlData += "<F_NAME>" + fName + "</F_NAME>";xmlData += "<M_INIT>" + mInit + "</M_INIT>";xmlData += "<L_NAME>" + lName + "</L_NAME>";xmlData += "<STATE>" + state + "</STATE>";xmlData += "<ZIP>" + zip + "</ZIP></AUTO_CLIENT><AUTO_PROP>";xmlData += "<CLIENT_NO>" + zip + fName + "</CLIENT_NO>";xmlData += "<PROP_ADDR_1>" + address + "</PROP_ADDR_1>";xmlData += "<PROP_CITY>" + city + "</PROP_CITY>";xmlData += "<PROP_STATE>" + state + "</PROP_STATE>";xmlData += "<PROP_ZIP>" + zip + "</PROP_ZIP>";xmlData += "<MAKE>" + make + "</MAKE>";xmlData += "<MODEL>" + model + "</MODEL>";xmlData += "<YEAR>" + modelYear + "</YEAR>";xmlData += "<DEDUCTIBLE>" + deductible + "</DEDUCTIBLE>";xmlData += "<LIAB_PROT_LIMIT>" + liabProtLimit + "</LIAB_PROT_LIMIT>";xmlData += "<MED_PAY_LIMIT>" + medPayLimit + "</MED_PAY_LIMIT>"xmlData += "<AUTO_CVG_LIMIT>" + autoCvgLimit + "</AUTO_CVG_LIMIT>";xmlData += "<PERS_PROP_CVG_LIMIT>" + persPropCvgLimit + "</PERS_PROP_CVG_LIMIT>";xmlData += "<LOSS_USE_CVG_LIMIT>" + lossUseCvgLimit + "</LOSS_USE_CVG_LIMIT>";xmlData += "<IQ_TOT_PREM>" + annualPremium + "</IQ_TOT_PREM>";xmlData += "</AUTO_PROP></RECORD></dataroot>";

316


}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 stringxmlData = "<dataroot><RECORD><HO_CLIENT><CLIENT_NO>" + zip + fName + "</CLIENT_NO>";xmlData += "<F_NAME>" + fName + "</F_NAME>";xmlData += "<M_INIT>" + mInit + "</M_INIT>";xmlData += "<L_NAME>" + lName + "</L_NAME>";xmlData += "<STATE>" + state + "</STATE>";xmlData += "<ZIP>" + zip + "</ZIP></HO_CLIENT><HO_PROP>";xmlData += "<CLIENT_NO>" + zip + fName + "</CLIENT_NO>";xmlData += "<PROP_ADDR_1>" + address + "</PROP_ADDR_1>";xmlData += "<PROP_CITY>" + city + "</PROP_CITY>";xmlData += "<PROP_STATE>" + state + "</PROP_STATE>";xmlData += "<PROP_ZIP>" + zip + "</PROP_ZIP>";xmlData += "<DEDUCTIBLE>" + deductible + "</DEDUCTIBLE>";xmlData += "<LIAB_PROT_LIMIT>" + liabProtLimit + "</LIAB_PROT_LIMIT>";xmlData += "<MED_PAY_LIMIT>" + medPayLimit + "</MED_PAY_LIMIT>"xmlData += "<DWEL_CVG_LIMIT>" + dwelCvgLimit + "</DWEL_CVG_LIMIT>";xmlData += "<OTH_STR_CVG_LIMIT>" + othStrCvgLimit + "</OTH_STR_CVG_LIMIT>";xmlData += "<PERS_PROP_CVG_LIMIT>" + persPropCvgLimit + "</PERS_PROP_CVG_LIMIT>";xmlData += "<LOSS_USE_CVG_LIMIT>" + lossUseCvgLimit + "</LOSS_USE_CVG_LIMIT>";xmlData += "<IQ_TOT_PREM>" + annualPremium + "</IQ_TOT_PREM>";xmlData += "</HO_PROP></RECORD></dataroot>";}//replace reserved characters in XML dataString xmlDataMarkup = markup(xmlData);

fileName = quote_gen.getDocument(docName, xmlData, xmlDataSource);//redirect to preview pageif (fileName!=null) {session.setAttribute("fileName",fileName);//set pathsession.setAttribute("filePath","./xPressionDocs/"+fileName+extension);

//go to preview pageresponse.sendRedirect("preview.jsp");}else {response.sendRedirect("index.jsp");}

}catch(Exception e){e.printStackTrace();}%>

317


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 replacethem with valid characters.

• We’re retrieving the category and document names stored in session variables. We need thecategory name to determine how to assign values to the variables declared on this page. We’llpass 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 hardcoded 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 usingdata the user has entered. While we’re using a simple approach to generating XML, we stronglyrecommend 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, theXML data, and the XML data source name.

• Finally, if the quote document is successfully created, we redirect the browser to the preview.jsppage.

318


Let’s now create the final page in the Quote Generator application: preview.jsp. Add the followingcode:<%String pageName = "Preview";

//get pathString filePath=session.getAttribute("filePath").toString();%><html><head><title><%=pageName%></title><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"></head><frameset rows="220,350*" frameborder="0" border="0" framespacing="0"><frame name="topFrame" scrolling="NO" noresize src="preview_top.jsp"><frameset rows="350,60" frameborder="0" border="0" framespacing="0"><frame name="mainFrame" scrolling="auto" src="<%=filePath%>"><frame name="bottomFrame" scrolling="NO" src="ftr.jsp"></frameset><noframes><body bgcolor="#FFFFFF"></body></noframes></frameset></html>

You’ll notice that the page only needs a bit of script to set the page name and the path for the PDFdocument. 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 theapplication.

• 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


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 deployit on your client workstation or server. In the next chapter, we’ll show you how to generate a WARfile for your application so you can deploy it either on a client workstation or a server.

Deploying an xPression ApplicationIn this chapter, we’ll discuss various approaches to packaging and deploying your J2EE xPressionapplication. 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 applicationin 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 J2EEapplication 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 inJ2EE Application Assembly, page 320. We’ll discuss each of the applications at a high level before weget into the details of assembling the Quote Generator application.

Figure 12. The following image shows the J2EE application assembly.

320


J2EE Web Application Overview

J2EE Web Applications are the easiest to understand and work with if you know how to constructWeb-enabled applications. J2EE Web Applications contain HTML, GIF, JPEG, and other filesappropriate for building Web-enabled applications. Web browsers serve up these files through aWeb server like Microsoft’s Internet Information or Apache’s Apache Web Server. J2EE applicationservers typically integrate with these external Web servers. They may also have their own Webserver capabilities.

External Web servers cannot easily serve up dynamic content, so J2EE Web applications that useServlets and JSP pages require a link between an external Web server and an application server. J2EEapplication servers use these technologies in a Web application to serve dynamic content in additionto any static content in the Web application.

J2EE Web Applications are packaged into WAR (Web application archive) files for easier deploymentto 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 deployspecialized components inside the application server. EJBs come in several different types accordingto the routine tasks a J2EE application developer needs to perform. For example, EJB Entity Beansare designed to help a developer work with persistent data in a transactional database, and EJBMessage-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 applicationserver. A single JAR file may contain one or many EJBs, with each EJB composed of an XML-baseddeployment descriptor, an EJB Home Interface class, an EJB Remote Interface class, and an EJBImplementation class.

J2EE Utility Classes Overview

J2EE Utility Class archives are collections of Java classes and associated resources you can use in Webapplications and EJBs. This mechanism provides an easy way to use third-party utility libraries. Forexample, xPression makes use of the popular Apache open source log4j utility library, and addingthe library once to the J2EE Enterprise Archive makes its capabilities available for use by xPression’svarious Web applications and EJBs.

J2EE Utility Classes are packaged into JAR (Java ARchive) files for easier deployment to anapplication server. They can contain any file loaded through a Java CLASSPATH, most notably, Javaclass files, properties files, and locale-specific resource files.

321


Web Application Archive Construction

Let’s now use our Quote Generator application to demonstrate how to assemble a Web applicationarchive. 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 overviewof a WAR, we discussed that a Web application can contain any type of file normally presentin a good Web site.

• The next two files are images, which are also customary for a good Web application. An imagesfolder is commonly used to enable Web applications to share image files across multiple Webpages. The Web application could contain any number of other files and directories, nested asdeeply 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.xmldocument 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 thatdescribes the contents and configuration of the web application. J2EE specifications dictate thestructure and contents of this file. The most common use of this file is to register servlets you’vewritten 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 operateproperly. You may recall from a beginning Java course that each class should be part of a package

322


so classes can be organized into folders and quickly found in the CLASSPATH. WEB-INF\classesis 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 Webapplication can gain access to the xPression API.

After you’ve completed the folder structure according to the above rules, you can easily create a WARfile by using the Java "jar" utility, which comes with the Java JDK. From a command prompt, changeto 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. Thatway, 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 applicationon your client workstation or server.

Command ReferenceThe xFramework Command Reference documents the two public classes and their methods in thehigh-level JFramework API. There are a few conventions we follow throughout this chapter. Eachclass has an introductory paragraph explaining its general purpose. All members of each class areexplained fully, including the proper syntax, parameters, and code examples. All code examples arewritten in Java.

This chapter is intended as a glossary for the high-level JFramework API. For complete instructionson how to use the API, see Writing an XPression Facade Java Class, page 301. Each method isformatted as follows:

Method Name

Descriptive paragraph.

Syntax

Object.methodName parm1, parm2

Parameters

Parm1 : Data Type

Descriptive text.

parm2 : Data Type

Descriptive text.

323


Sample

public class CodeSample {public void sampleMethod() {try {//sample code here}catch {//sample error code here}}}

324


The XPressionFacade ClassThe 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, page345. 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’reusing for your Framework session. The application name is set when you initialize a serverconnection. 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 forthe supplied category.

325


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 onuser 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


returnVals = facade.getCategories();}catch {System.out.println("An error occurred getting the categories.");}return returnVals;}}

327


getDocumentPackedMSOHTML

This method, which returns a byte array, enables you to retrieve an assembled document fromthe xPression database in packed (or compressed) MSOHTML format. For more information onunpacking MSOHTML, see Appendix A, The Webtool Utility. You must then convert the byte arrayto a logical file and unpack (decompress) the file.

Syntax

document[] = XPressionFacade.getDocumentPackedMSOHTML(documentName, customerKey);

Parameters


An input parameter containing the document name you’re assembling.


An XML string containing the key values for a specific customer record. Customer key values arealways stored in the primary table of the data source.

The following samples show how the XML should be formatted:<Keys><Key name="AUTOPAY_KEY">1</Key></Keys>

-or-<Keys><Key name="AUTOPAY_KEY">1</Key><Key name="LANGUAGE">English</Key></Keys>

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


When the document you specify contains a sub-document, the sub-document will use customer datafrom the default data source instead of the customerData you provide. The customer data you specifyonly works for the master document, not the subdocument.

getDocumentPackedMSOHTML (overloaded)

This method, which returns a byte array, enables you to retrieve an assembled document fromthe xPression database in packed (or compressed) MSOHTML format. For more information onunpacking MSOHTML, see Appendix A, The Webtool Utility. Calling this overloaded method isperfect when you want to pass XML customer data that you generate on the fly in transactionalapplications. You must then convert the byte array to a logical file and unpack (decompress) the file.

Syntax

document[] = XPressionFacade.getDocumentPackedMSOHTML(documentName, customerData,xmlDataSourceName);

Parameters




A string containing a customer record in XML format. The XML stream can contain a single recordfrom the primary table and, optionally, additional related records from secondary tables in your datasource. In the following example, the customer data is a single record from the primary table.<?xml version="1.0" encoding="UTF-8"?><CustomerData><WITHDRAWAL><KEY>1</KEY><NAME>Sara Jones</NAME><STREET_ADDRESS>6732 River Run</STREET_ADDRESS><CITY_STATE_ZIP>University City, CA 22445</CITY_STATE_ZIP><LETTER_DATE>August 5, 2002</LETTER_DATE><POLICY_PURCHASED>Flexible Premium VariableLife Insurance Policy</POLICY_PURCHASED><SALES_LOAD>2.5%</SALES_LOAD><STATE_PREMIUM_TAX>2.5%</STATE_PREMIUM_TAX><POLICY_NUMBER>78889567</POLICY_NUMBER><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFDATE>2005-12-31</EFFDATE></WITHDRAWAL></CustomerData>

329


xmlDataSourceName : String

An input parameter containing the name of an XML data source you’re using to assemble thedocument.

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


getDocumentPDF

This method, which returns a byte array, enables you to retrieve an assembled document from thexPression 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




An XML string containing the key values for a specific customer record. Customer key values arealways stored in the primary table of the data source. The following samples show how the XMLshould be formatted:<Keys><Key name="AUTOPAY_KEY">1</Key></Keys>


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



getDocumentPDF (overloaded)

This method, which returns a byte array, enables you to retrieve an assembled document from thexPression database in PDF format. Calling this overloaded method is perfect when you want topass XML customer data that you generate on the fly in transactional applications. You must thenconvert the byte array to a logical file on your own.

Syntax

document[] = XPressionFacade.getDocumentPDF(documentName, customerData,xmlDataSourceName);

Parameters




A string containing a customer record in XML format. The XML stream can contain a single recordfrom the primary table and, optionally, additional related records from secondary tables in your datasource. In the following example, the customer data is a single record from the primary table.<?xml version="1.0" encoding="UTF-8"?><CustomerData><WITHDRAWAL><KEY>1</KEY><NAME>Sara Jones</NAME><STREET_ADDRESS>6732 River Run</STREET_ADDRESS><CITY_STATE_ZIP>University City, CA 22445</CITY_STATE_ZIP><LETTER_DATE>August 5, 2002</LETTER_DATE><POLICY_PURCHASED>Flexible Premium VariableLife Insurance Policy</POLICY_PURCHASED><SALES_LOAD>2.5%</SALES_LOAD><STATE_PREMIUM_TAX>2.5%</STATE_PREMIUM_TAX><POLICY_NUMBER>78889567</POLICY_NUMBER><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFDATE>2005-12-31</EFFDATE></WITHDRAWAL></CustomerData>


332


An input parameter containing the name of an XML data source you’re using to assemble thedocument.

333


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 isstarted.");}return returnVal;}}

334


getOutputProfiles

This method, which returns a two-dimensional string array, enables you to retrieve output profilenames and IDs from the content repository. The following table illustrates the values containedin 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


getSchema

This method, which returns a byte array, enables you to retrieve the primary data source groupschema 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 asxResponse or a custom application of your own.

Syntax

XPressionFacade.getStartSession(userName, password, appName);

336


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 parametersyou supply for this method is the "contextFactory," which refers to the context object path for theapplication 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


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 specifywhich document status is eligible for publishing. Valid values are ANY and APPROVED. Thedefault value is approved. Because the default status is APPROVED, you do not need to use thisAPI 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


publishDocument

This method, which returns an XPressionDocument object, enables you to assemble and publish adocument from the xPression database using an output profile you supply.

Syntax

XPressionDocument[] = XPressionFacade.publishDocument(documentName, customerKey,outputProfileName);

Parameters


An input parameter containing the document name you’re publishing.


An XML string containing the key values for a specific customer record. Customer key values arealways stored in the primary table of the data source. The following samples show how the XMLshould be formatted:<Keys><Key name="AUTOPAY_KEY">1</Key></Keys>



An input parameter containing the output profile name. To retrieve output profiles, use thegetOutputProfiles, page 335 method.

Sample

import com.docscience.xpression.framework.XPressionFacade;import com.docscience.xpression.framework.XPressionDocument;import java.io.FileOutputStream;import java.io.FileInputStream;

public class FacadeTest {public void publishDocument(String documentName, String customerKey,String outputProfile) {XPressionDocument[] documents = null;facade = new XPressionFacade();try {

339


documents = facade.publishDocument(documentName, customerKey, outputProfile);for (int i=0;i<documents.length;i++) {FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" +documents[i].getDocumentName() + "." + documents[i].getDocumentFormat());

fos.write(documents[i].getDocumentData());

fos.close();

}}catch {System.out.println("An error occurred publishing the document.");}}}


publishDocument (overloaded)

This method, which returns an XPressionDocument object, enables you to assemble and publish adocument from the xPression database using an output profile you supply. Calling this overloadedmethod is perfect when you want to pass XML customer data that you generate on the fly intransactional applications.

Syntax

XPressionDocument[] = XPressionFacade.publishDocument(documentName, customerData,xmlDataSourceName, outputProfileName);

Parameters


An input parameter containing the document name you’re publishing.


A string containing a customer record in XML format. The XML stream can contain a single recordfrom the primary table and, optionally, additional related records from secondary tables in your datasource. In the following example, the customer data is a single record from the primary table.<?xml version="1.0" encoding="UTF-8"?><CustomerData><WITHDRAWAL><KEY>1</KEY><NAME>Sara Jones</NAME><STREET_ADDRESS>6732 River Run

340


</STREET_ADDRESS><CITY_STATE_ZIP>University City, CA 22445</CITY_STATE_ZIP><LETTER_DATE>August 5, 2002</LETTER_DATE><POLICY_PURCHASED>Flexible Premium VariableLife Insurance Policy</POLICY_PURCHASED><SALES_LOAD>2.5%</SALES_LOAD><STATE_PREMIUM_TAX>2.5%</STATE_PREMIUM_TAX><POLICY_NUMBER>78889567</POLICY_NUMBER><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFDATE>2005-12-31</EFFDATE></WITHDRAWAL></CustomerData>


An input parameter containing the name of an XML data source you’re using to publish the document.


An input parameter containing the output profile name. To retrieve output profiles, use thegetOutputProfiles, page 335 method.

Sample

import com.docscience.xpression.framework.XPressionFacade;import com.docscience.xpression.framework.XPressionDocument;import java.io.FileOutputStream;import 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<documents.length;i++) {FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" +documents[i].getDocumentName() + "." + documents[i].getDocumentFormat());


fos.close();

}}catch {System.out.println("An error occurred publishing the document.");}}

341


Ending a SessionOnce you are done with an xPression session, you’ll need to stop the session and terminate yourxPression connection.

removeSession()

The removeSession() method enables you to stop a session in order to release a seat. This methodterminates your xPression connection. Typically, you would call this method at the end of yourxPression session.

Syntax

removeSession()

Parameters

This method takes no parameters.

The XPressionDocument ClassWhen publishing a document using the XPressionFacade class, an XPressionDocument object isreturned to the caller. Each object contains the document name, format, and data in a byte array.To retrieve those values, you must call the three methods documented in this section. This sectionincludes these methods: getDocumentData, getDocumentFormat, and getDocumentName.

getDocumentData

This method returns the published document data in a byte array. It’s up to you to convert the arrayto a logical file if you want to store a copy of the document locally.

Syntax

documentData[] = XPressionDocument.getDocumentData();

342


Sample

import com.docscience.xpression.framework.XPressionFacade;import com.docscience.xpression.framework.XPressionDocument;import java.io.FileOutputStream;import java.io.FileInputStream;public class FacadeTest {public void publishDocument(String documentName, String customerKey,String outputProfile) {XPressionDocument[] documents = null;facade = new XPressionFacade();try {documents = facade.publishDocument(documentName, customerKey, outputProfile);for (int i=0;i<documents.length;i++) {FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" +documents[i].getDocumentName() + "." + documents[i].getDocumentFormat());


fos.close();


getDocumentFormat

This method returns the published document format, such as PDF or HTML.

Syntax

documentFormat = XPressionDocument.getDocumentFormat();

Sample

import com.docscience.xpression.framework.XPressionFacade;import com.docscience.xpression.framework.XPressionDocument;import java.io.FileOutputStream;import java.io.FileInputStream;public class FacadeTest {public void publishDocument(String documentName, String customerKey,String outputProfile) {XPressionDocument[] documents = null;facade = new XPressionFacade();try {documents = facade.publishDocument(documentName, customerKey, outputProfile);for (int i=0;i<documents.length;i++) {FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" +

343


documents[i].getDocumentName() + "." + documents[i].getDocumentFormat());

fos.write(documents[i].getDocumentData());fos.close();


getDocumentName

This method returns the published document name.

Syntax

documentName = XPressionDocument.getDocumentName();

Sample

import com.docscience.xpression.framework.XPressionFacade;import com.docscience.xpression.framework.XPressionDocument;import java.io.FileOutputStream;import java.io.FileInputStream;public class FacadeTest {public void publishDocument(String documentName, String customerKey,String outputProfile) {XPressionDocument[] documents = null;facade = new XPressionFacade();try {documents = facade.publishDocument(documentName, customerKey, outputProfile);for (int i=0;i<documents.length;i++) {FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" +documents[i].getDocumentName() + "." + documents[i].getDocumentFormat());


fos.close();


344


xPression Facade ExceptionsWhen calling the methods of the XPressionFacade class, errors may occur for several reasons: userinput, server connections timing out, or the xPression session wasn’t properly started. In this section,you’ll find all the exceptions the XPressionFacade methods can generate. Each high level exceptionwill also include descriptions of its lower level "child" exceptions.

This section includes the following xFramework exceptions: XPressionFrameworkException,NoAuthorizedRightException, NoStartSessionException, NoSuchTargetException,XPressionEJBException, and XPressionProcessException.

XPressionFrameworkException

This is the top level xFramework exception. All other Framework exceptions are lower in the callstack. The following table describes the methods this exception calls.

Method Description

getErrorCode Returns the error code for the exception.

getErrorContent Returns the error text for the exception.

replaceWithMsg Enables you to replace the error text with a string array. It returns the replacedtext.

NoAuthorizedRightException

This exception occurs when you’re attempting to access a category you don’t have rights to. It callsthe categoryError method, which returns a string containing the error message.

NoStartSessionException

This exception occurs when an xPression session isn’t started and you’re trying to call otherXPressionFacade methods. It can call the following methods.

Method Description

baseError Returns a base message when no other methods can be called.

getSessionError Returns the specific error text when an xPression session can’t be started.

NoSuchTargetException

This exception occurs when xFramework cannot find a remote object. It calls the following methods,depending on the error.

345


Method Description

findAPPPrimaryDataSourceByBDTError Occurs when xFramework cannot find the primarydata source for the business document.

findBDTIdError Occurs when xFramework cannot find the businessdocument (BDT) ID value.

findCategoryByBDTError Occurs when xFramework cannot find the categoryfor the business document.

findEffectiveDateError Occurs when xFramework cannot find the effectivedate for the business document.

outputProfileError Occurs when xFramework cannot retrieve outputprofiles.

346


XPressionEJBException

This exception occurs when xFramework cannot access a remote Enterprise Java Beans (EJB) object. Itcalls the following methods, depending on the error.

Method Description

initialContextError Occurs when xFramework cannot find the initial context for the EJB.

lookupTargetError Occurs when xFramework cannot look up a remote EJB object.

remoteObjectError Occurs when xFramework cannot use the remote EJB object.

XPressionProcessException

This exception occurs when xFramework cannot process an xPression document. It calls thefollowing methods, depending on the error.

Method Description

getCustomKeyWithDataError Occurs when xFramework cannot process thecustomer key data.

getEffectiveDateFromCustomerDataError Occurs when xFramework cannot get the effectivedate from the supplied customer data.

parameterNotAllowEmpty Occurs when xFramework passes an emptyparameter when a value is required.

parseCustomDataError Occurs when xFramework cannot parse customerdata.

347


348

Chapter 16The Deprecated xPression EAI Adapter

This section covers a component of the deprecated Web Services model. With version 4.0, xPressionintroduces a new Web Service API that conforms to the WS-I Basic Profile. The old xFramework WebService API, Java API, and xAdapter have been deprecated. Although these items will be supportedfor backward compatibility in the current version, EMC Document Sciences encourages you to usethe new Web Service API as it offers better performance, greater flexibility, and better security.

The xPression EAI Adapter supports the JMS (Java Message Service) specification. Vendor productslike IBM WebSphere MQ support JMS for guaranteed delivery of messages between systems. TheEAI Adapter provides Message-Driven EJBs (MDBs) to process 3 types of messages:

• Publish Document

• Preview PDF

• Post For Batch

MDBs are configured to pull messages off an input queue, process messages, and put results on anoutput queue Multiple MDBs can work in parallel on the same input queue if supported by theApplication Server vendor The xPression EAI Adapter can watch for XML files and accumulate themfor submission to a larger batch job XML files can be directly placed in a watched file directory

At intervals defined by a batch job scheduler, the EAI Adapter performs the following actions:• Gathers XML files for processing a particular batch job

• Optionally transforms them to xPression “streamlined” XML

• Merges the XML files into one large XML file

• Submits the XML file to xBatch for high throughput processing

Note: When processing customer data, the xAdapter will always assume the element specified in thedelimiter is the first child in the parent element.

349

The Deprecated xPression EAI Adapter

xAdapter Architectural OverviewThe xAdapter is organized around three core components: Listener Technology, Request Processor,and xPression Batch Wrapper.

Figure 13. These components and their relationships are shown in the diagram and discussed below.

Listener Technology

Listeners watch for document processing requests and process them according to the technology theyemploy. Each listener supports a particular integration technology, be it real-time Web services ornear-time JMS messages. Multiple listeners of the same technology can be employed simultaneously,or started in parallel as the xAdapter is initialized (through J2EE standard Servlet or message-drivenEJB initialization).

Request Processor

Listeners support two different mechanisms for accomplishing an xPression Server request:• If the request is flagged for immediate execution, it sends the request to the xPression requestprocessor. This processor connects to the xPression Server through the xPression Framework APIand immediately processes the request and returns the results to the listener plug-in.

• If the request is flagged for batch execution, it creates an XML file in a temporary holdingdirectory. Any number of requests can be queued for batch execution.

xPression Batch Wrapper

Batch execution is driven by a batch runner program that calls the xAdapter’s xPression Batchwrapper Java class. The wrapper program accumulates any XML files queued for batch execution,merges them into one XML file, then calls xPression Batch to process the merged XML file.

The batch wrapper is written in a recoverable manner, such that if the batch job completessuccessfully, the intermediate files are deleted so they will not be processed again on subsequentexecution. If the batch job doesn’t complete successfully, the intermediate files will remain and thebatch job can be run again without manual intervention.

The Adapter batch wrapper program uses standard batch job error codes, where a zero code indicatessuccess (and deletion of processed XML files), and negative code indicates failure (and files willremain for a subsequent call to re-execute the batch run).

350


Transformation Engine

The Transformation Engine is a simple framework for invoking optional transformations of customerdata XML. The adapter supports an open source XML transformation engine (Apache Xalan) for theindustry standard XSLT technology. The Transformation Engine provides configuration hooks sothat third-party XML transformation engines can be used for jobs where the open source solutiondoes not provide adequate performance or throughput. Third-party engines are invoked using alocal Java method call.

xAdapter Deployment ArchitectureThe xAdapter is located on the same physical server as the xPression Server, from which it connectsto one instance of the xPression Server. If multiple instances of xPression Server are in use, oneinstance of an adapter must be installed for each instance of xPression Server. The xAdapter doesnot broker requests across multiple instances of xPression Server.

Figure 14. The xAdapter, deployed on a WebSphere cluster of two Windows servers, would look like thefollowing image.

xAdapter ComponentsThe xAdapter supports these seven processing requests:• Publish a document to an output profile. For more information, see Publish Document WebService Method, page 352.

• Preview a document in PDF format. For more information, see Preview PDFWeb Service Method,page 353.

• Submit a document to be published in batch. For more information, see Post For Batch WebService Method, page 354.

• Find the document categories to which the user is eligible to publish. For more information, seeCategories For User Web Service Method, page 354.

• Find documents within a document category. For more information, see Documents For CategoryWeb Service Method, page 355.

• Find output profiles configured for use for a particular document. For more information, seeOutput Profiles For Document Web Service Method, page 356.

• Find variables used in a document. For more information, see Variables for Document WebService Method, page 356.

351


The xAdapter supports three methods of system-to-system integration with XML documents asthe data transfer medium:• Web Services Integration, page 352

• JMS-Based Messaging Mechanism, page 357

• XML File Export for Batch Execution, page 371

Web Services Integration

The adapter’s Web Services integration mechanism is meant for the real time request-reply systemintegration paradigm. It carries the most processing overhead of the three mechanisms and thereforeshould be used only when an immediate reply is needed to a request into the adapter.

The Web Services mechanism supports all six types of requests using SOAP and WSDL standards.The requests are easily callable by both Java and .NET technologies and each is described below.

The Web Services mechanism utilizes the Apache Axis open source Web services toolkit for Java,version 1.3. It defines one JWS (Java Web Service) file which has six methods, one for each processingrequest type. To retrieve the WSDL for the Web service, type:http://<server:port>/xPressionAdapter/webServices/xPressionRequest.jws?wsdl

Publish Document Web Service Method

To call the Publish Document Web service method, type:http://<server:port>/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 topublish the selected document.

String

Password The password for the xPression user. String

OutputProfile The xPression output profile used to publish thedocument. The publish process will fail if incorrectlydefined.

String

Transformation Specifies whether a named transformation should beapplied by the transformation engine. If null or emptystring, a default transformation for the document ordocument category will be applied.

String

CustomerData The XML document for the xPression XML formatdata source.

String

352


The Web service method will return a String as an output parameter should the method completesuccessfully. The output String will have the following format:Message '<MessageId>' was successfully published to output profile'<OutputProfile>'.

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 SOAPfault returns a unique error identifier code plus an error message explaining the error code and anypertinent data involved in the error.

Preview PDF Web Service Method

To call the Preview PDF Web service method, type:http://<server:port>/xPressionAdapter/webServices/xPressionRequest.jws?method=previewPDF

This Web service method accepts the following parameters.


DocumentName The name of the xPression document to publish. String

UserName The name of the user logging on to xPression. This usermust have permission to publish the document selected orthe 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 documentto. This output profile must be a valid option for theDocumentName to be published to.

String

Transformation Specifies whether a named transformation should beapplied by the transformation engine. If this parameteris null or an empty string a default transformation forthe document or document category will be applied ifconfigured.

String

CustomerData The XML document for the xPression XML format datasource.

String

The Web service returns a byte array (which in accordance with SOAP standards is serialized withBASE64 encoding/decoding) should the request be successfully processed. This byte array is thepublished document in PDF format.


353


Post For Batch Web Service Method

To call the Post For Batch Web service method, type:http://<server:port>/xPressionAdapter/webServices/xPressionRequest.jws?method=postForBatch



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


String

CustomerData The XML document for the xPression XML format datasource.

String

The Web service method returns a String as an output parameter should the method completesuccessfully. The output String has the following format:

Customer data records for xPression batch document type '<BatchDocumentType>' wassuccessfully written to input XML file directory '<inputXmlFileDirectory>'

BatchDocumentType corresponds to the input parameter given in the request.


Categories For User Web Service Method

To call the Categories For User Web service method, type:http://<server:port>/xPressionAdapter/webServices/xPressionRequest.jws?method=categoriesForUser

354




UserName The name of the user to log into xPression. String


String

The Web service method returns a String array as an output parameter should the method completesuccessfully. There will be one document category in the String array for every document categorythe user is eligible to publish documents to. It’s possible that the request complete successfully withno 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 SOAPfault includes a unique error identifier code plus an error message explaining the error code and anypertinent data involved in the error.

Documents For Category Web Service Method

To call the Documents For Category Web service method, type:http://<server:port>/xPressionAdapter/webServices/xPressionRequest.jws?method=documentsForCategory



DocumentCategory The xPression category that contains the document to publish. String

UserName The name of the user to log on to xPression. This usermust have permission to publish documents in theDocumentCategory selected or the request will fail.

String


String

The Web service method returns a String array as an output parameter when the method completessuccessfully. There will be one document name in the String array for every document in xPressioncontained within the DocumentCategory given as input. It is possible for the request to completesuccessfully with no entries returned (which means there are no documents registered in the categorygiven).

The Web service method returns a SOAP fault if the method fails. The error text of the SOAP faultincludes a unique error identifier code plus an error message explaining the error code and anypertinent data involved in the error.

355


Output Profiles For Document Web Service Method

To call the Variables for Document web service method, type:http://<server:port>/xPressionAdapter/webServices/xPressionRequest.jws?method=outputProfilesForDocument



DocumentName The name of the xPression document to retrieve assignedoutput profiles.

String

UserName The name of the user to log on to xPression. This user must havepermission to publish documents in the document category thatthe document belongs to or the request will fail.

String

Password The password that corresponds to the UserName, authenticatedby xPression platform security.

String

The web service method returns a String array as an output parameter when the method completessuccessfully. There will be one xPression Output Profile in the String array for every output profileassigned to the document in xDesign. It is possible for the request to complete successfully with noentries 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 faultincludes a unique error identifier code plus an error message explaining the error code and anypertinent data involved in the error.

Variables for Document Web Service Method

To call the Variables for Document web service method, type:http://<server:port>/xPressionAdapter/webServices/xPressionRequest.jws?method=variablesForDocument



DocumentName The name of the xPression document to retrieve assignedoutput profiles.

String

UserName The name of the user to log on to xPression. This user musthave permission to publish documents in the documentcategory that the document belongs to or the request will fail.

String

Password The password that corresponds to the UserName, authenticatedby xPression platform security.

String

The web service method will return a String array as an output parameter should the methodcomplete successfully. There will be one xPression document variable in the String array for everydocument variable defined in xAdmin for the document specified. The adapter looks for the defaultdata source group assigned to the document’s category and returns all variables for that default data

356


source group. It is possible that the request complete successfully with no entries returned (whichmeans 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 faultincludes a unique error identifier code plus an error message explaining the error code and anypertinent data involved in the error.

JMS-Based Messaging Mechanism

For adapters equipped with JMS messaging support, the adapter’s JMS-Based messaging mechanismutilizes the J2EE standardized Message-Driven EJB technology. This technology provides theability to pull messages off a JMS supported message queuing technology (for example, IBM MQSeries/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 nativelysupport 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 inthe ejb-jar.xml file deployment. So Document Sciences can write only one Java class implementingthe message-driven EJB and it can be named any number of times in the EJB descriptor files. InWebSphere, there is an additional XMI descriptor file that relates a named EJB instance to a JMSadapter 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 JMSoutput queue, in the ejb-jar.xml file. In this manner, each named EJB instance will not only beconfigured to pull off a different input queue but will also push output messages to a differentoutput queue.

• Each named EJB instance can be configured by WebSphere-specific properties in XMI descriptorfiles 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 theXML header that may declare the caller does not want an output message to be queued to the outputJMS queue (this parameter doesn’t make sense for Preview PDF request where the output queue isalways sent a binary document message upon successful completion).

357


Publish Document Message

The Publish Document input message requires the following XML request parameters.

Parameter Description Required?

RequestType The type of request this XML messagerepresents. The value for this message must bePublish 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 thedocument selected or the request will fail.

Y

Password The password that corresponds to theUserName, authenticated by xPression platformsecurity.

Y

OutputProfile The xPression Output Profile to publish thedocument to. This Output Profile must be a validoption for the DocumentName to be publishedto.

Y

ReturnStatusMessage A flag which tells the adapter message listenerwhether to place a message on the output queuetelling whether the request was completed ornot. This parameter is not required and if notgiven, the default is “Y” (yes, a status messagewill be placed on the output queue). Validvalues for this parameter are “Y” and “N” (no, astatus message will not be placed on the outputqueue, even if the request cannot be processed).

N

Transformation Specifies whether a named transformationshould be applied by the transformationengine. If this parameter is not given, a defaulttransformation for the document or documentcategory will be applied if configured.

N

CustomerData The XML document for the xPression XMLformat data source.

Y

An example XML input file for the Publish Document message is shown below.<?xml version="1.0" encoding="UTF-8" ?><AdapterRequest>

<RequestType>Publish Document</RequestType><DocumentName>Automatic Payment Letter</DocumentName><UserName>xpression</UserName><Password>xpression</Password><OutputProfile>Combined Print Archive Email</OutputProfile><CustomerData><CustomerData><Transaction><AUTOPAY><AUTOPAY_KEY>1</AUTOPAY_KEY>

358


<FIRST_NAME>Mary</FIRST_NAME><MIDDLE>K.</MIDDLE><LAST_NAME>Jackson</LAST_NAME><STREET_ADDRESS>9573 Main Street</STREET_ADDRESS><CITY_STATE_ZIP>San Diego CA, 92108</CITY_STATE_ZIP><LETTER_DATE>1/1/2002</LETTER_DATE><CLIENT_NUMBER>50</CLIENT_NUMBER><FIN_INST_NAME>Wells Fargo</FIN_INST_NAME><FIN_INST_ACCT_NUM>10000</FIN_INST_ACCT_NUM><REP_NAME>John Doe</REP_NAME><REP_PHONE>760-222-1574</REP_PHONE><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFECTIVE_DATE>2005-12-12</EFFECTIVE_DATE><EMAIL_ADDRESS>[email protected]</EMAIL_ADDRESS></AUTOPAY><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>1</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1001</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Flexible Premium Variable Life</ACCOUNT_NAME><ACCOUNT_NUMBER>67-2301-810</ACCOUNT_NUMBER><ACCOUNT_AMT>$934.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>4/8/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>2</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1002</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Portfolio Annuity</ACCOUNT_NAME><ACCOUNT_NUMBER>5573-135-4361</ACCOUNT_NUMBER><ACCOUNT_AMT>$360.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>10/24/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS></Transaction></CustomerData></CustomerData>

</AdapterRequest>

If the ReturnStatusMessage flag is set to return a status message, the xAdapter will compose anXML 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 messagerepresents. The value for this messagemust be Publish Document.

This field is present in all outputmessages as long as the inputmessage is properly formed.

DocumentName The name of the xPression Document topublish.

This field is present in all outputmessages as long as the inputmessage is properly formed

359



UserName The name of the user to log into xPression. This user must have permission topublish the document selected or therequest will fail. This field is presentin all output messages as long as theinput message is properly formed

OutputProfile The xPression Output Profile to publishthe document to.

This Output Profile must be a validoption for the DocumentName to bepublished to. This field is present inall output messages as long as theinput message is properly formed.

RequestSuccess-ful Flag telling if the request was successfullyprocessed. Valid values are “Y” (yes, therequest was processed successfully), and“N” (no, the request had an error in thecourse of processing).

This field is present in all outputmessages

MessageId The primary key of the first customer datarecord, if the information can be found inthe request to be processed.

This field is present in all outputmessages as long as the customer datarecord can be properly processed toobtain this information.

OutputMessage A message telling what request wasprocessed. Example:

Message ’<MessageId>’was successfullypublished to outputprofile’<OutputProfile>’.

This field is only present when therequest is successfully processed

ErrorCode The unique error code from the adapterfor any error encountered processing therequest.

The field is only present when therequest cannot be processed

ErrorMessage An error message explaining the errorcode and any pertinent data involved inthe error.


If the Publish Document request is completed successfully, an example XML output message wouldlook like this:

<?xml version="1.0" encoding="UTF-8" ?><AdapterResponse>

<RequestType>Publish Document</RequestType><DocumentName>Automatic Payment Letter</DocumentName><UserName>xpression</UserName><OutputProfile>Combined Print Archive Email</OutputProfile><RequestStatus><RequestSuccessful>Y</RequestSuccessful><MessageId>1</MessageId><OutputMessage>Message '1' was successfully published to outputprofile 'Combined Print Archive Email'.</OutputMessage></RequestStatus></AdapterResponse>

360


If the Publish Document request is not completed successfully, an example XML output messagewould look like this:

<?xml version="1.0" encoding="UTF-8" ?><AdapterResponse><RequestType>Publish Document</RequestType><DocumentName>Automatic Payment Letter</DocumentName><UserName>xpression</UserName><OutputProfile>Combined Print Archive Email</OutputProfile><RequestStatus><RequestSuccessful>N</RequestSuccessful><MessageId>1</MessageId><ErrorCode>10101</ErrorCode><ErrorMessage>An error occurred while starting a FrameWork service.</ErrorMessage></RequestStatus></AdapterResponse>

Preview PDF Message

The Preview PDF input message requires the following XML request parameters.


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 The name of the user to log into xPression. Thisuser must have permission to publish the documentselected or the request will fail.

Y


Y

Transformation Specifies whether a named transformation shouldbe applied by the transformation engine. If thisparameter is not given, a default transformation forthe document or document category will be appliedif configured.

N


Y

An example XML input file for the Publish Document message is shown here.<?xml version="1.0" encoding="UTF-8" ?><AdapterRequest>

<RequestType>Preview PDF</RequestType><DocumentName>Automatic Payment Letter</DocumentName><UserName>xpression</UserName><Password>xpression</Password>

<CustomerData><CustomerData><Transaction>

361


<AUTOPAY><AUTOPAY_KEY>1</AUTOPAY_KEY><FIRST_NAME>Mary</FIRST_NAME><MIDDLE>K.</MIDDLE><LAST_NAME>Jackson</LAST_NAME><STREET_ADDRESS>9573 Main Street</STREET_ADDRESS><CITY_STATE_ZIP>San Diego CA, 92108</CITY_STATE_ZIP><LETTER_DATE>1/1/2002</LETTER_DATE><CLIENT_NUMBER>50</CLIENT_NUMBER><FIN_INST_NAME>Wells Fargo</FIN_INST_NAME><FIN_INST_ACCT_NUM>10000</FIN_INST_ACCT_NUM><REP_NAME>John Doe</REP_NAME><REP_PHONE>760-222-1574</REP_PHONE><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFECTIVE_DATE>2005-12-12</EFFECTIVE_DATE><EMAIL_ADDRESS>[email protected]</EMAIL_ADDRESS></AUTOPAY><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>1</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1001</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Flexible Premium Variable Life</ACCOUNT_NAME><ACCOUNT_NUMBER>67-2301-810</ACCOUNT_NUMBER><ACCOUNT_AMT>$934.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>4/8/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>2</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1002</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Portfolio Annuity</ACCOUNT_NAME><ACCOUNT_NUMBER>5573-135-4361</ACCOUNT_NUMBER><ACCOUNT_AMT>$360.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>10/24/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS></Transaction></CustomerData></CustomerData>

</AdapterRequest>

If this request is completed successfully, the output message will be a binary message consisting ofthe PDF format document output from the request.

If this request is not completed successfully, the output message will be an XML message withthese output fields.


RequestType The type of request this XML messagerepresents. The value for this messagemust be Publish Document.


DocumentName The name of the xPression Document topublish.


362



UserName The name of the user to log into xPression. This user must have permission topublish the document selected or therequest will fail. This field is presentin all output messages as long as theinput message is properly formed

RequestSuccess-ful Flag telling if the request was successfullyprocessed. Valid values are “Y” (yes, therequest was processed successfully), and“N” (no, the request had an error in thecourse of processing).

This field is present in all outputmessages


This field is present in all outputmessages as long as the customerdata record can be properlyprocessed to obtain this information.



ErrorMessage An error message explaining the errorcode and any pertinent data involved.


If the Preview PDF request is not completed successfully, an example XML output message wouldlook like this:

<?xml version="1.0" encoding="UTF-8" ?><AdapterResponse><RequestType>Preview PDF</RequestType><DocumentName>Automatic Payment Letter</DocumentName><UserName>xpression</UserName><RequestStatus><RequestSuccessful>N</RequestSuccessful><MessageId>1</MessageId><ErrorCode>10101</ErrorCode><ErrorMessage>An error occurred while starting a FrameWork service.</ErrorMessage>

</RequestStatus>

</AdapterResponse>

Post For Batch Message

The Post For Batch input message requires the following XML request parameters.


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 theadapter, configured in the adapter’s configurationproperties file.

Y

363



UserName The name of the user to log into xPression. Y


Y

ReturnStatusMessage A flag which tells the adapter message listenerwhether to place a message on the output queuetelling 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 beplaced on the output queue). Valid values for thisparameter are “Y” and “N” (no, a status messagewill not be placed on the output queue, even if therequest cannot be processed).

N


Y

An example XML input file for the Post for Batch message is shown here.<?xml version="1.0" encoding="UTF-8" ?><AdapterRequest>

<RequestType>Post For Batch</RequestType><BatchDocumentType>Policy</BatchDocumentType><UserName>xpression</UserName><Password>xpression</Password>

<CustomerData><CustomerData><Transaction><AUTOPAY><AUTOPAY_KEY>1</AUTOPAY_KEY><FIRST_NAME>Mary</FIRST_NAME><MIDDLE>K.</MIDDLE><LAST_NAME>Jackson</LAST_NAME><STREET_ADDRESS>9573 Main Street</STREET_ADDRESS><CITY_STATE_ZIP>San Diego CA, 92108</CITY_STATE_ZIP><LETTER_DATE>1/1/2002</LETTER_DATE><CLIENT_NUMBER>50</CLIENT_NUMBER><FIN_INST_NAME>Wells Fargo</FIN_INST_NAME><FIN_INST_ACCT_NUM>10000</FIN_INST_ACCT_NUM><REP_NAME>John Doe</REP_NAME><REP_PHONE>760-222-1574</REP_PHONE><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFECTIVE_DATE>2005-12-12</EFFECTIVE_DATE><EMAIL_ADDRESS>[email protected]</EMAIL_ADDRESS></AUTOPAY><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>1</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1001</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Flexible Premium Variable Life</ACCOUNT_NAME><ACCOUNT_NUMBER>67-2301-810</ACCOUNT_NUMBER><ACCOUNT_AMT>$934.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>4/8/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>2</AUTOPAY_ACCTS_KEY>

364


<AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1002</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Portfolio Annuity</ACCOUNT_NAME><ACCOUNT_NUMBER>5573-135-4361</ACCOUNT_NUMBER><ACCOUNT_AMT>$360.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>10/24/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS></Transaction></CustomerData></CustomerData></AdapterRequest>

If the ReturnStatusMessage flag is set to return a status message, the xAdapter will compose anXML document and send it to the output queue. The return status message will have the followingoutput fields.


RequestType The type of request this XML messagerepresents. The value for this message mustbe Publish Document.


BatchDocument-Type The type of batch document to be processedby the adapter, configured in the adapter’sconfiguration properties file.


UserName The name of the user to log into xPression. This field is present in all outputmessages as long as the inputmessage is properly formed.

RequestSuccessful Flag telling if the request was successfullyprocessed. Valid values are “Y” (yes, therequest was processed successfully), and“N” (no, the request had an error in thecourse of processing).

This field is present in all outputmessages.


This field is present in alloutput messages as long asthe customer data record can beproperly processed to obtain thisinformation.

OutputMessage A message telling which request wasprocessed. Example:

Customer data records forxPression batch document type’Policy’ was successfullywritten to input XML filedirectory ’c:\\xPressionAdapter\\PolicyXMLInputDir\\’.

This field is only present when therequest is successfully processed.

365




The field is only present when therequest cannot be processed.

ErrorMessage An error message explaining the error codeand any pertinent data involved in the error.


If the Post For Batch request is completed successfully, an example XML output message wouldlook something like this:

<?xml version="1.0" encoding="UTF-8" ?><AdapterResponse><RequestType>Post For Batch</RequestType><BatchDocumentType>Policy</BatchDocumentType><UserName>xpression</UserName>

<RequestStatus>

<RequestSuccessful>Y</RequestSuccessful><MessageId>1</MessageId><OutputMessage>Customer data records for xPression batch document type 'Policy'was successfully written to input XML file directory 'c:\\xPressionAdapter\\PolicyXMLInputDir\\'.</OutputMessage>

</RequestStatus></AdapterResponse>

366


If the Post For Batch request is not completed successfully, an example XML output message wouldlook as follows:

<?xml version="1.0" encoding="UTF-8" ?><AdapterResponse><RequestType>Post For Batch</RequestType><BatchDocumentType>Policy</BatchDocumentType><UserName>xpression</UserName><RequestStatus><RequestSuccessful>N</RequestSuccessful><MessageId>1</MessageId><ErrorCode>10321</ErrorCode><ErrorMessage>Error writing the customer data file to the filesystem.</ErrorMessage></RequestStatus></AdapterResponse>

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 outputqueue with error information.

Malformed XML

Should the XML Message input into the adapter not be well-formed XML, the adapter will returnan error message as follows:<?xml version="1.0" encoding="UTF-8" ?><AdapterResponse>

<RequestStatus><RequestSuccessful>N</RequestSuccessful><ErrorCode>10322</ErrorCode><ErrorMessage>The XML message input into the adapter could not be parsed

as it was not well-formed.</ErrorMessage></RequestStatus>

</AdapterResponse>

367


Request Type Not Supported

Should the XML Message input into the adapter provide an invalid RequestType, the adapter willreturn an error message as follows:<?xml version="1.0" encoding="UTF-8" ?><AdapterResponse>

<RequestStatus>

<RequestSuccessful>N</RequestSuccessful><ErrorCode>10323</ErrorCode><ErrorMessage>RequestType "Preview PDF" is not supported.</ErrorMessage>

</RequestStatus></AdapterResponse>

XML Missing a Required Parameter

Should the XML Message input into the adapter fail to include a required parameter, the adapter willreturn an error message as follows:<?xml version="1.0" encoding="UTF-8" ?><AdapterResponse>

<RequestStatus>

<RequestSuccessful>N</RequestSuccessful><ErrorCode>10324</ErrorCode><ErrorMessage>Required parameter "OutputProfile" was not provided.</ErrorMessage>

</RequestStatus>

</AdapterResponse>

Transformation Engine

The transformation engine provides a framework for transforming XML Customer Data before itis submitted to xPression. This “streamlines” the XML so it can be processed more efficiently inxPression, and so that the xPression data schema and corresponding document design can be muchsimpler.

Extensible Stylesheet Language Transformation (XSLT) is the industry standard technology fortransforming XML. Since XSLT has some limitations, the transformation engine in the adapter isflexible enough to allow 3rd party transformations to be plugged into the adapter and invokedon demand. As long as that transformation can be called by a local Java class extended from atransformation 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, toutilize the free Apache Xalan XSLT engine through the JAX Java XML standard.

368


Each transformation defined in the adapter has a transformation name, a transformation engine (thedefault being the JAXPTransformationEngine), and a set of one or more properties associated withthe transformation (for example, in the JAXPTransformationEngine, it is the XSLT file to apply tothe input XML).

Example property file settings follow for a transformation named PolicyTransformation, using thedefault 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 settingcan and should be omitted.

The transformation engine can also set up default named transformations fordocuments and categories, should a request into the adapter publish or preview adocument (that is, the “Publish Document” or “Preview PDF” request types only).The adapter will implement a maximum of one transformation per request, and thetransformation 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 adefault transformation for the document name.

3. If no default transformation is specified for the document name, the transformation engine looksfor 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 PolicyDocumentTransform.PolicyTransformation.transformName=PolicyTransformation

CategoryTransform.BillingTransformation.categoryName=Billing DocumentsCategoryTransform.BillingTransformation.transformName=BillingTransformation

The properties above define one default document transformation and one default categorytransformation. 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 thexPressionAdapter.properties file with a prefix of Transform., DocumentTransform., andCategoryTransform., are loaded into 3 different HashMap tables respectively so transformationscan be found and executed quickly. The Transform HashMap is keyed by the transformName,

369


the DocumentTransform HashMap is keyed by the document name, and the CategoryTransformHashMap is keyed by the category name.

Should a generic XSLT transformation engine not suffice, you can create your own transformationengine by plugging in Java code you create into the adapter. To do so, you must extend thecom.docscience.xpression. adapter.transform.AbstractTransformationEngineclass and override the public Result transform(Source xmlSource)method. A templatefor 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 namedMyTransform 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 OrderMarker). The BOM is added by Notepad, so do not use Notepad to save the properties file in UTF-8format. 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

http://notepad-plus.sourceforge.net/uk/site.htm


XML File Export for Batch Execution

The adapter supports a convenient way of executing the xPression Batch standardized componentof the xPression product suite. xPression Batch is designed to publish large volumes of documentsefficiently, 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 notprovide any XML transformation capabilities.

The xAdapter accumulates smaller individual XML documents queued for batch executionthroughout the day. The Adapter then provides a batch runner wrapper Java class, which optionallytransforms and then merges the XML files in a format that can be used as input into one xPressionBatch 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 jobstep, and that job step must have the same name as the batch job defined in xAdmin and configuredin the xPressionAdapter.properties configuration file.

XML files containing customer/document data can come from direct XML export to a file systemaccessible by the adapter. XML files may also come from the Web Services and JMS mechanismsabove from the Post For Batch request type. For more information, see Post For Batch Web ServiceMethod, page 354.

Each batch job executed is identified by the type of documents published in the batch run. A batch jobexecution program calls the batch process from the command line according to any interval desiredand defined in the batch job execution program.

Caution: The Adapter batch runner wrapper must not, for the same batch document type, becalled in parallel. Doing so would result in any number of issues as two adapter batch runnerscompete 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 ofthat 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 thexPressionAdapter.properties property file with a prefix of Policy.

371


Here’s a sample property file:

Policy.inputXmlFileDirectory=C:\\xPressionAdapter\\PolicyBatchXMLExport\\Policy.inputXmlFileNamePattern=*.xmlPolicy.temporaryXmlFileDirectory=c:\\xPressionAdapter\\PolicyTempXML\\Policy.errorXmlFileDirectory=c:\\xPressionAdapter\\PolicyErrorXML\\Policy.mergedXmlFileDirectory=C:\\xPressionAdapter\\PolicyMergedXML\\Policy.xPressionBatchJobName=PolicyBatchJobPolicy.transformationName=PolicyTransformationPolicy.customerDataMergeDelimiter = /dataroot/TransactionPolicy.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 successfullyand 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 beleftover from a previous batch run and we don’t want to double-process them. If the filescannot 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 filecannot 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. Foreach file that matches this pattern we loop through and:• Move each file from the export directory to the C:\xPressionAdapter\PolicyTempXMLdirectory (this step is taken for safety and recoverability, because moving the file ensures thatthe 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 inthe list (assume the file is locked because it isn’t completely written to the file system).

372


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 thetransformationName property defined about should be omitted if this is not needed.

• Aggregate and merge those files into a file named C:\xPressionAdapter\PolicyMergedXML\PolicyBatchJob<timestamp>.xml in a format that can be directly input into xPressionBatchRunner.

• If a transformation is configured, run the appropriate transformation engine and catch anyexceptions thrown. (If a transformation is not configured, proceed to the next bullet point inthis step.) If an exception is thrown, consider the XML file to be bad. Move the original XMLinput 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 existsin the error directory, or the file cannot be moved for any reason, log a fatal error and abortthe batch job with a negative exit code. If the file is moved successfully, increment the errorthreshold counter by one. Check the XML error threshold and, if it has been exceeded, loga fatal error and exit the batch job with a negative exit code. If a bad transformation isencountered, the original input file can be moved successfully from the temp directory tothe error directory, and the error threshold is not exceeded, move on to the next input file atthe beginning of step 5. If the transformation was successful or if no transformation wasencountered, continue with the next bullet point.

• For each XML file resulting from the above process (either successfully transformed ornot transformed at all), parse the XML file stream to see if it is well-formed. If the XMLis well-formed, then make sure the structure matches the customer data merge delimiterspecified. If the XML file is not well-formed or if it is well-formed but cannot be mergedbecause the XML node structure does not match the merge delimiter, move the originalXML 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 bemoved, log a fatal error and abort the batch job with a negative exit code. If the file is movedsuccessfully, increment the error threshold counter by one. Check the XML error thresholdand, 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 thresholdis not exceeded, move on to the next input file identified at the beginning of step 5. If theXML 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), theadapter needs to understand what XML node to start the merge process. In the exampleconfiguration on page 122, a merge delimiter of “/dataroot/Transaction” would tell the adapterto begin the merge process at the <Transaction> node underneath the <dataroot> root node ofthe 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 XMLdocument and merged with other “Transaction” elements inside the current document andfrom other XML documents. The resulting XML document has the same XML structure as

373


the input XML documents, starting with a “dataroot” root node and including any numberof “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<timestamp>.xml file as input.

7. When the xPression BatchRunner job completes successfully by returning a zero, one, or twoexit 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<timestamp>.xml onthe file system for auditing and debugging purposes.

8. Should the xPression BatchRunner job exit with a status of zero, one, or two, the Adapter BatchRunner job considers the run successful and exits with a zero status code. Otherwise, the AdapterBatch Runner job considers the run unsuccessful, does not perform any cleanup activities andexits with a status of negative one. The marker file must stay on the file system to show theprocess 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 haveonly one job step named PolicyBatchJob, and the merged XML file produced by the adapter must beappropriate as an XML data source override for that single job step.

Adapter Configuration InformationThe 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 xFrameworkJava interface (JFramework). The xPression Java Framework uses the IIOP/RMIprotocol to connect to xPression, so this URL must point to the IIOP/RMIport exposed by the application server for the Java Virtual Machine that runsxPression Server.

xPressionApplication-Name This is the name of the xAdapter application as listed in the AppList.xmlxPression configuration file and accordingly assigned document category AccessRights for users and groups in xAdmin. To view categories, documents in acategory, and submit document preview or publish requests, the userNamegiven in the request must have access rights in the appropriate category forthis 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 tothe application server.

For each batch document type, a set of properties will be defined as described in XML File Export forBatch Execution, page 371.

374


Here’s an example:xPressionServerURL=iiop://localhost:2809xPressionApplicationName=xPression AdapterPreviewPDFOutputProfile=PDF Return to ApplicationxPressionBatchRunnerScriptDir=C:\\WebSphere\\AppServer\\installedApps\\xPression.ear\\

Creating the Adapter ApplicationAfter deploying the xAdapter, you must configure your environment. You do this by adding yourapplication definition to AppList.xml and configuring it using xAdmin. In this chapter, we’ll showyou how to get everything set up.

Caution: We strongly urge you not to make changes to AppList.xml on a production xPressionserver until you’re sure your application works as intended in a test environment.

Adding Your Application DefinitionTo 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 <AppList></AppList> tags. For example:<AppList>

<Application name="xPression Adapter"></Application></AppList>

Your application name must not contain apostrophes (’).

3. Type the access rights your application supports, including whether or not they’re hierarchical.For example:

<AccessRights heirarchical="yes"><Access name="Read" /><Access name="Write" /><Access name="Approve" /></AccessRights>


5. Save AppList.xml and exit your text editor. When complete, your application definition shouldappear similar to the following.

<AppList><Application name="xPression Adapter"><AccessRights heirarchical="yes"><Access name="Read" /><Access name="Write" /><Access name="Approve" /></AccessRights>

375


</Application></AppList>

Configuring Your Application with xAdminNow that you’ve added your application definition to AppList.xml, it’s time to configure it withxAdmin.



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.


3. Click an attribute set that you want to associate with your application. You can also create yourown 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


Assigning Categories to Your ApplicationTo 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 ApplicationTo assign data sources to your application:1. Select a category you’ve already assigned to your application.


3. Select a data source group from the list.

4. Click Set Application.


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 ApplicationTo 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.


Configure Your Batch ScriptsTo configure xPression Batch Runner:1. Create a directory to house your xPression Batch scripts. For example: C:\xPressionAdapter

\batchScripts.

377


2. Copy BatchRunner.bat from the xPression.ear installation directory to the new directory. ThexPression.ear directory should be in the installedApps directory of your WebSphere applicationserver.

3. Open BatchRunner.bat in a text editor and remove the pause at the end of the script. The lastline of the script must contain a call to the java program. Immediately before the call to the javaprogram, 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 toC:\xPressionAdapter\batchScripts.

5. Open AdapterBatchRunner.bat in a text editor and set the variables at the top of the scriptas needed.

6. Edit xPressionAdapter.properties file in your Adapter Home directory to set thexPressionBatchRunnerScriptDir parameter properly.For example, if you place your Batch Runner scripts in C:\xPressionAdapter \batchScripts, itwould 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 notneeded for AdapterBatchRunner because the files are generated by xAdapter by default.

Verifying Your InstallationOpen a Web browser and type http://<server:port>/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 applicationnamed xPressionAdapterTest.war. This application is provided as a convenience for testing andshould never be deployed to a production environment. You are welcome to use your own messagingtools and programs to test the adapter.

378


Should you decide to use the test application we provide, deploy thexPressionAdapterTest.war file to the same application server as the adapter, with theContext Root xPressionAdapterTest. Follow the testing instructions below to theadapter’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


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 ofthis, results may not be available immediately. Refresh the xAdapter Test Utility periodically tolook for new messages on the output queue, or examine the xPressionAdapter.log file to see ifyour request has been completed.

XML FilesThree XML files are used:• Publish Document, page 380

• Preview with PDF, page 381

• Post for Batch, page 382

Publish Document<?xml version="1.0" encoding="UTF-8" ?><AdapterRequest>

<RequestType>Publish Document</RequestType>

<DocumentName>Automatic Payment Letter</DocumentName>

<UserName>jpc0999</UserName>

<Password>JoonP123</Password>

<OutputProfile>PDF To File</OutputProfile><CustomerData><CustomerData>

<Transaction><AUTOPAY><AUTOPAY_KEY>1</AUTOPAY_KEY><FIRST_NAME>Mary</FIRST_NAME><MIDDLE>K.</MIDDLE><LAST_NAME>Jackson</LAST_NAME><STREET_ADDRESS>9573 Main Street</STREET_ADDRESS><CITY_STATE_ZIP>San Diego CA, 92108</CITY_STATE_ZIP><LETTER_DATE>1/1/2002</LETTER_DATE><CLIENT_NUMBER>50</CLIENT_NUMBER><FIN_INST_NAME>Wells Fargo</FIN_INST_NAME><FIN_INST_ACCT_NUM>10000</FIN_INST_ACCT_NUM><REP_NAME>John Doe</REP_NAME><REP_PHONE>760-222-1574</REP_PHONE><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFECTIVE_DATE>2005-12-12</EFFECTIVE_DATE><EMAIL_ADDRESS>[email protected]</EMAIL_ADDRESS>

380


</AUTOPAY><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>1</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1001</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Flexible Premium Variable Life</ACCOUNT_NAME><ACCOUNT_NUMBER>67-2301-810</ACCOUNT_NUMBER><ACCOUNT_AMT>$934.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>4/8/2002</ACCOUNT_NEXT_PAY_DATE> </AUTOPAY_ACCTS><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>2</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1002</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Portfolio Annuity</ACCOUNT_NAME><ACCOUNT_NUMBER>5573-135-4361</ACCOUNT_NUMBER><ACCOUNT_AMT>$360.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>10/24/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS>

</Transaction>

</CustomerData></CustomerData></AdapterRequest>

Preview with PDF<?xml version="1.0" encoding="UTF-8" ?><AdapterRequest>

<RequestType>Preview PDF</RequestType><DocumentName>Automatic Payment Letter</DocumentName>



<CustomerData><CustomerData>

<Transaction><AUTOPAY><AUTOPAY_KEY>1</AUTOPAY_KEY><FIRST_NAME>Mary</FIRST_NAME><MIDDLE>K.</MIDDLE><LAST_NAME>Jackson</LAST_NAME><STREET_ADDRESS>9573 Main Street</STREET_ADDRESS><CITY_STATE_ZIP>San Diego CA, 92108</CITY_STATE_ZIP><LETTER_DATE>1/1/2002</LETTER_DATE><CLIENT_NUMBER>50</CLIENT_NUMBER><FIN_INST_NAME>Wells Fargo</FIN_INST_NAME><FIN_INST_ACCT_NUM>10000</FIN_INST_ACCT_NUM><REP_NAME>John Doe</REP_NAME><REP_PHONE>760-222-1574</REP_PHONE><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFECTIVE_DATE>2005-12-12</EFFECTIVE_DATE><EMAIL_ADDRESS>[email protected]</EMAIL_ADDRESS>

381


</AUTOPAY><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>1</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1001</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Flexible Premium Variable Life</ACCOUNT_NAME><ACCOUNT_NUMBER>67-2301-810</ACCOUNT_NUMBER><ACCOUNT_AMT>$934.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>4/8/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>2</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1002</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Portfolio Annuity</ACCOUNT_NAME><ACCOUNT_NUMBER>5573-135-4361</ACCOUNT_NUMBER><ACCOUNT_AMT>$360.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>10/24/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS></Transaction>


Post for Batch<?xml version="1.0" encoding="UTF-8" ?><AdapterRequest>

<RequestType>Post For Batch</RequestType>

<BatchDocumentType>AutomaticPaymentLetter</BatchDocumentType>



<CustomerData><CustomerData>

<Transaction><AUTOPAY><AUTOPAY_KEY>1</AUTOPAY_KEY><FIRST_NAME>Mary</FIRST_NAME><MIDDLE>K.</MIDDLE><LAST_NAME>Jackson</LAST_NAME><STREET_ADDRESS>9573 Main Street</STREET_ADDRESS><CITY_STATE_ZIP>San Diego CA, 92108</CITY_STATE_ZIP><LETTER_DATE>1/1/2002</LETTER_DATE><CLIENT_NUMBER>50</CLIENT_NUMBER><FIN_INST_NAME>Wells Fargo</FIN_INST_NAME><FIN_INST_ACCT_NUM>10000</FIN_INST_ACCT_NUM><REP_NAME>John Doe</REP_NAME><REP_PHONE>760-222-1574</REP_PHONE><LANGUAGE>English</LANGUAGE><JURISDICTION>CA</JURISDICTION><EFFECTIVE_DATE>2005-12-12</EFFECTIVE_DATE>

382


<EMAIL_ADDRESS>[email protected]</EMAIL_ADDRESS></AUTOPAY><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>1</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1001</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Flexible Premium Variable Life</ACCOUNT_NAME><ACCOUNT_NUMBER>67-2301-810</ACCOUNT_NUMBER><ACCOUNT_AMT>$934.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>4/8/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS><AUTOPAY_ACCTS><AUTOPAY_ACCTS_KEY>2</AUTOPAY_ACCTS_KEY><AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID><ACCOUNT_ID_NUM>1002</ACCOUNT_ID_NUM><ACCOUNT_NAME>JMS Portfolio Annuity</ACCOUNT_NAME><ACCOUNT_NUMBER>5573-135-4361</ACCOUNT_NUMBER><ACCOUNT_AMT>$360.00</ACCOUNT_AMT><ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY><ACCOUNT_NEXT_PAY_DATE>10/24/2002</ACCOUNT_NEXT_PAY_DATE></AUTOPAY_ACCTS>

</Transaction>


Error MessagesAll errors and all important events will be logged to the Log4J logging framework, a standard practicefor all Document Sciences Java software development. Errors are defined as any situation the codeencounters which does not promote the proper or efficient processing of a request. Events are definedas 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 uniqueidentifier. Any time an error is detected, a utility class specifically designed to capture and log theerror will be utilized. Any time an event is executed, a utility class specifically designed to start atimer, execute the event, stop the timer, and record not only the event identifier and details but alsothe time it took to execute the event. Both errors and events must be written to the Log4J log file in amanner 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 listedbelow.

Level Definition

FATAL The system encountered a critical error at this logging level, which affects the overallaccuracy, integrity, reliability, or capability of most or all of the system. Someoneshould be paged to address the error as soon as possible.

383


Level Definition

ERROR The system encountered an unexpected error at this logging level and the processingof a particular request will be affected. This error is not of a critical nature andtypically can be recovered from automatically. Future requests into the systemshould be able to be processed without error. Someone should be e-mailed to resolvethe error in the near future to increase the reliability of the system.

WARN The system encountered an expected error situation. The system recovered from itbut the fact that it happened should be recorded to see how frequently it happens.System performance may be affected because processing did not complete asexpected.

INFO An important event was executed in the system. This event is so important to systemdebugging and monitoring that it should always be logged to the log file everytime it happens.

DEBUG An event was executed in the system but the fact that this event happened is notimportant enough to always be written to the log file. When the system needs to bedebugged, 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 ImportantEvent. 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 theprefix 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 adapter will use a Java utility class named “LoggedException” to record the error and necessaryinformation 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 thexPression.log file.

Error Descriptions

Error Number Error Description

1000 An error occurred while invoking webservices, find more info inserver 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 forthis server, serverURL= {1}.

5003 Parameters for documentType {0} were not correctly set in theconfiguration file.

5004 Non-existing output profile {0} passed to the adapter.

385



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 orFrameWork 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 usingoutput profile {0}.

10205 An error occurred while getting published instantiated documentcontent using stream {0}.

10209 An error occurred while setting default the internal state of theassembly 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 amalformed XML.

10404 Error at Reading the variables from the schema.

10500 The transformation Class {0} does not inherit theAbstractTransformationEngine.

386



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 specifiedtransformationName {0}.

Event Descriptions


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


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 oldxFramework Web Service API, Java API, and xAdapter have been deprecated. Although these itemswill be supported for backward compatibility in the current version, EMC Document Sciencesencourages you to use the newWeb Service API as it offers better performance, greater flexibility, andbetter security.

Webtool is a small component that enables you to encrypt and decrypt passwords that you passto xPression as well as pack and unpack MSOHTML documents you retrieve from the contentrepository. 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 inboth Java and Visual Basic.

You’ll find both webtool.jar and webtool.dll on the eBooks CD in \\xPression Framework\util. Ifyou’re using the COM version, you’ll need to register it on your computer.

Registering Webtool.dllWebtool.dll has a dependency on the uamerge.dll file supplied by EMC Document Sciences. Whenyou register Webtool.dll, please ensure that uamerge.dll has been copied to:• <xPressionHome>/Drivers/

Or• %SystemRoot%/system32/

The Encryption UtilityThe 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 recommendit for security purposes. However, the Chapter 14, Deprecated xPression Web Services methods dorequire 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.EncryptUtilDim encryptedPassword As Byte()

'encrypt passwordencryptedPassword = webTool.encrypt(passWord)

'set return valueencryptPwd = encryptedPassword

'destroy objectSet 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.EncryptUtilDim decryptedPassword As String

'decrypt passworddecryptedPassword = webTool.decrypt(encryptedPassword)

'set return valuedecryptPwd = decryptedPassword

391

The Webtool Utility


End Function

The Pack UtilityThe pack utility enables you to pack and unpack MSOHTML documents retrieved from the contentrepository. By default, xPression content items are stored in compressed, or packed, MSOHTMLformat in the content repository. If you want to enable your users to edit xPression documents, youneed to first unpack the content, display it in an editor, and pack it again when re-saving the editedcontent to the content repository. This section includes these methods: pack and unpack.

packJava: 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 thecontent to the content repository.

Parameters

folderName : String

An input parameter containing the fully qualified path for the content you’re packing. If you pass anempty 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.PackUtilDim packedFile As StringDim unpackedFile As String

'set file namespackedFile = App.Path & "\packed\" & Left$(fileName, Len(fileName) - 3) & "pkd"sUnpackedFile = App.Path & "\unpacked\" & fileName

'pack filewebTool.Pack "", unpackedFile, packedFile


End Sub

unpack

This method decompresses, or unpacks, MSOHTML content, which then enables you to displayit 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 youpass an empty string, the unpack method assumes you’re passing the path in the two subsequentparameters.

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.PackUtilDim packedFile As StringDim unpackedFile As String

'set file namespackedFile = App.Path & "\packed\" & Left$(fileName, Len(fileName) - 3) & "pkd"sUnpackedFile = App.Path & "\unpacked\" & fileName

'unpack filewebTool.Unpack "", packedFile, unpackedFile


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 validateXML documents to ensure they adhere to those rules. It’s important to note, however, that DTDswon’t tell you whether an XML document is well formed. There are other tools to determine, forexample, 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, itprovides the elements that make up an application’s usage and behavior, including the applicationname, access rights, required attributes (if any), and workflow information. xAdmin uses AppList.xmlto configure categories, attribute sets, and data sources for use with xPression applications. Forexample, 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 aboutapplications that are part of the standard xPression suite. Therefore, we urge you to exercisecaution when adding your own applications. EMC Document Sciences only providesinformation about AppList.xml in the xFramework Developer’s Guide, it does not supply programsthat write to AppList.xml.

The Complete AppList.dtdNow let’s look at AppList.dtd.<?xml version="1.0" encoding="UTF-8"?><!ELEMENT AppList (Application+)><!ELEMENT Application (WorkFlow?, AccessRights?, RequiredAttributes*)><!ATTLIST Applicationname CDATA #REQUIRED><!ELEMENT WorkFlow EMPTY><!ATTLIST WorkFlowfromStatus CDATA #REQUIREDtoStatus CDATA #REQUIREDenterAction CDATA #REQUIREDpromoteAction CDATA #REQUIRED><!ELEMENT AccessRights (Access+)><!ATTLIST AccessRightsheirarchical (yes|no) #IMPLIED>

397

The AppList DTD

<!ELEMENT Access EMPTY><!ATTLIST Accessname CDATA #REQUIRED><!ELEMENT RequiredAttributes (Attr+)><!ATTLIST RequiredAttributescondition (SupportApproval) #IMPLIED><!ELEMENT Attr EMPTY><!ATTLIST Attrname CDATA #REQUIREDtype CDATA #REQUIREDmin CDATA #REQUIREDmax CDATA #REQUIREDValidValueExist (0 | 1) #REQUIREDDefault_Value CDATA #REQUIREDisMappable (0 | 1) #REQUIREDstringlength CDATA #IMPLIEDRangeExist (0 | 1) #REQUIREDDefaultExist (0 | 1) #REQUIREDmultisingle (multi | single) #REQUIREDvalidValue CDATA #REQUIRED>

The AppList and Application Elements

AppList is the top level element in AppList.xml. It contains the child element Application. Theplus sign (+) after Application indicates that there must be at least one child Application elementof AppList.<!ELEMENT AppList (Application+)><!ELEMENT Application (WorkFlow?, AccessRights?, RequiredAttributes*)><!ATTLIST Applicationname CDATA #REQUIRED>

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 childelement may appear once or not at all. The asterisk (*) means that a child element can appear anynumber of times or not at all.

The attributes for the Application element come last, including the data type and modifier. Thename attribute’s data type is CDATA, or character data, and its modifier is #REQUIRED, whichmeans that the attribute is required.

398

The AppList DTD

Let’s look at an XML example to illustrate:<AppList><Application name="xPression Test"><AccessRights><Access name="Read"/></AccessRights></Application></AppList>

Notice that in this example, we omitted both the WorkFlow and RequiredAttributes elements. Thisis a perfectly valid scenario.

The WorkFlow Element

Here we’re defining WorkFlow as an empty element, which means that no data will appear betweenthe begin and end tags. We then define the list of attributes for the WorkFlow element. The fourattributes have the same data type and all are required.<!ELEMENT WorkFlow EMPTY><!ATTLIST WorkFlowfromStatus CDATA #REQUIREDtoStatus CDATA #REQUIREDenterAction CDATA #REQUIREDpromoteAction CDATA #REQUIRED

Let’s expand on our previous example:<AppList><Application name="xPression Test"><WorkFlow fromStatus="SUBMITTED" toStatus="APPROVED" enterAction="Write"promoteAction="Approve"/><AccessRights heirarchical="yes"><Access name="Read"/><Access name="Write"/><Access name="Approve"/></AccessRights></Application></AppList>

Here we added two more access rights and a workflow. This means the xPression Test user musthave an access level of Write to initiate workflow, whose status, once initiated, is SUBMITTED. Topromote 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 samedata 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 thismeans Access is a child element of AccessRights and that one or more Access elements must beincluded.

The AccessRights element has a single attribute: heirarchical. This attribute determines whetheraccess 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-levelaccess rights automatically have the lower-level access rights. Therefore, an xDesign user withApprove authority also has Write and Read authority. Access rights that aren’t hierarchical operateindependently from one another. xResponse is an example of an application without hierarchicalaccess rights.<!ELEMENT Access EMPTY><!ATTLIST Accessname CDATA #REQUIRED><!ELEMENT AccessRights (Access+)><!ATTLIST AccessRightsheirarchical (yes|no) #IMPLIED>

The RequiredAttributes and Attr Elements

Now let’s look at the final elements in the DTD.<!ELEMENT RequiredAttributes (Attr+)><!ATTLIST RequiredAttributescondition (SupportApproval) #IMPLIED><!ELEMENT Attr EMPTY><!ATTLIST Attrname CDATA #REQUIREDtype CDATA #REQUIREDmin CDATA #REQUIREDmax CDATA #REQUIREDValidValueExist (0 | 1) #REQUIREDDefault_Value CDATA #REQUIREDisMappable (0 | 1) #REQUIREDstringlength CDATA #IMPLIEDRangeExist (0 | 1) #REQUIREDDefaultExist (0 | 1) #REQUIRED

multisingle (multi | single) #REQUIREDvalidValue CDATA #REQUIRED>

Most of the syntax should look familiar to you by now, but there are a few differences. The conditionattribute of the RequiredAttributes element contains the #IMPLIED modifier. This means that theapplication 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 togain 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 customerdata 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 ExampleLet’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 inthe application definition if we want to support approval.<AppList><Application name="xPression Test"><WorkFlow fromStatus="SUBMITTED" toStatus="APPROVED"enterAction="Write" promoteAction="Approve"/><AccessRights><Access name="Read"/><Access name="Write"/><Access name="Approve"/></AccessRights><RequiredAttributes condition="SupportApproval"><Attr name="STATUS" type="string" min="0" max="0"ValidValueExist="1"Default_Value="PENDING" isMappable="0"

401

The AppList DTD

stringlength="255"RangeExist="0" DefaultExist="0" multisingle="multi"validValue="PENDING;SUBMITTED;APPROVED"/><Attr name="EFFECTIVE_DATE" type="DateTime" min="0"max="0"ValidValueExist="0" Default_Value="" isMappable="1"stringlength="0"RangeExist="0" DefaultExist="0" multisingle="multi"validValue=""/><Attr name="WITHDRAW_DATE" type="DateTime" min="0"max="0"ValidValueExist="0"Default_Value="" isMappable="1"stringlength="0"RangeExist="0"DefaultExist="0" multisingle="multi"validValue=""/></RequiredAttributes></Application></AppList>

402

Date post:	08-Nov-2018
Category:	Documents
Upload:	hoangngoc
View:	254 times
Download:	3 times