emc documentsciences xpression xframework...emc®documentsciences® xpression®xframework...
TRANSCRIPT
EMC® Document Sciences®
xPression® xFrameworkVersion 4.6 SP1
Development Guide
EMC CorporationCorporate Headquarters
Hopkinton, MA 01748-91031-508-435-1000www.EMC.com
Legal Notice
Copyright © 2003-2017 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
Preface ................................................................................................................................ 17
Chapter 1 About xFramework ...................................................................................... 19xPression Server Components ........................................................................... 19The xPression Assembly Engine .................................................................... 20The xPression Publishers Engine ................................................................... 20The xPublish Engine ................................................................................. 20
Distribution Controller Engine ...................................................................... 20Execution Architecture.............................................................................. 20Distribution Types .................................................................................... 21
xPression Batch Engine ................................................................................. 21xFramework Components ................................................................................. 21Web Services API.......................................................................................... 21Java API....................................................................................................... 22EAI Adapter................................................................................................. 22xPression Web Services ................................................................................. 22
xPression Integration Strategies ......................................................................... 22Real-Time Interaction.................................................................................... 23APIs ........................................................................................................ 23Portals ..................................................................................................... 23
Near-Time Interaction................................................................................... 23Batch Interaction .......................................................................................... 24xPression Integration Decision Tree ............................................................... 24
Chapter 2 xPression Web Service API ......................................................................... 25Overview ......................................................................................................... 25Authentication ................................................................................................. 26The requestContext Parameter....................................................................... 26Using requestContext with Documentum-Based Documents ....................... 27Applying a Publish Compatibility Configuration ........................................ 27Adding a Unique Identifier ....................................................................... 28Specifying Content Status for xDesign Documents...................................... 28requestContext Examples .......................................................................... 29
Setting Up Your Application.............................................................................. 30Adding Your Application Definition .............................................................. 30Configuring Your Application with xAdmin................................................... 31Associating Attribute Sets with Your Application ....................................... 31Assigning Data Sources to Your Application .............................................. 32Setting Up Access Rights for Your Application ........................................... 32Configuring Workflow for Your Application............................................... 32
IQuickDoc Configuration .................................................................................. 33Error Messages................................................................................................. 33CompuSet Bridge ............................................................................................. 34
Chapter 3 IQuickDoc Web Service ............................................................................... 35
3
Table of Contents
xPresso for Word Documents in Workflow-Enabled Categories ........................... 36The categoriesForUser Method .......................................................................... 36Syntax ......................................................................................................... 36Parameters ................................................................................................... 37
The documentsForCategory Method.................................................................. 37Syntax ......................................................................................................... 37Parameters ................................................................................................... 37
The descriptionForDocument Method................................................................ 38Syntax ......................................................................................................... 38Parameters ................................................................................................... 38
The thumbnailForDocument Method ................................................................. 39Syntax ......................................................................................................... 39Parameters ................................................................................................... 39
The designToolForDocument Method ................................................................ 40Syntax ......................................................................................................... 41Parameters ................................................................................................... 41
The outputProfilesForDocument Method ........................................................... 41Syntax ......................................................................................................... 42Parameters ................................................................................................... 42
The versionsForDocumentWithWorkflowStatus Method ..................................... 42Syntax ......................................................................................................... 43Parameters ................................................................................................... 43
The publishDocument Method .......................................................................... 43Syntax ......................................................................................................... 44Parameters ................................................................................................... 44Sample......................................................................................................... 45
The publishDocuments Method......................................................................... 46Syntax ......................................................................................................... 46Parameters ................................................................................................... 46Sample......................................................................................................... 47
The publishAndReturnDocument Method ......................................................... 48Syntax ......................................................................................................... 49Parameters ................................................................................................... 49
The publishDocxAndReturnDocument Method.................................................. 50Syntax ......................................................................................................... 51Parameters ................................................................................................... 51
The publishDocx Method .................................................................................. 51Syntax ......................................................................................................... 51Parameters ................................................................................................... 52
The publishAndReturnDocumentMultipleStream Method .................................. 52Syntax ......................................................................................................... 53Parameters ................................................................................................... 53
The getTemplateFields Method.......................................................................... 54Syntax ......................................................................................................... 54Parameters ................................................................................................... 54Examples ..................................................................................................... 56With NULL customerData Value ............................................................... 56With Supplied customerData..................................................................... 56
The getDataCollectionTemplate Method ............................................................ 57Syntax ......................................................................................................... 57Parameters ................................................................................................... 57Examples ..................................................................................................... 58With NULL customerData Value ............................................................... 58
4
Table of Contents
With Supplied customerData..................................................................... 59
Chapter 4 Workflow Integration Web Services ............................................................. 61WorkflowDocumentBrowsingService................................................................. 61listWorkFlowAvailableCategories .................................................................. 61Syntax ..................................................................................................... 61Parameters ............................................................................................... 62
listWorkFlowAvailableDocuments ................................................................. 62Syntax ..................................................................................................... 62Parameters ............................................................................................... 62
getDocumentType ........................................................................................ 63Syntax ..................................................................................................... 63Parameters ............................................................................................... 63
getDocumentVersions ................................................................................... 63Syntax ..................................................................................................... 64Parameters ............................................................................................... 64
DataBrowsingService........................................................................................ 64getDefaultDS................................................................................................ 64Syntax ..................................................................................................... 65Parameters ............................................................................................... 65
listKeys........................................................................................................ 65Syntax ..................................................................................................... 66Parameters ............................................................................................... 66
getDataRecordXML ...................................................................................... 66Syntax ..................................................................................................... 66Parameters ............................................................................................... 66
WorkflowService .............................................................................................. 67listLifeCycles................................................................................................ 67Syntax ..................................................................................................... 67Parameters ............................................................................................... 68
statusInLifecycle........................................................................................... 68Syntax ..................................................................................................... 68Parameters ............................................................................................... 68
previewPDF ................................................................................................. 68Syntax ..................................................................................................... 69Parameters ............................................................................................... 69
previewHTML ............................................................................................. 69Syntax ..................................................................................................... 70Parameters ............................................................................................... 70
workflowBegins ........................................................................................... 70Syntax ..................................................................................................... 71Parameters ............................................................................................... 71
setLifecycleStatus ......................................................................................... 71Syntax ..................................................................................................... 71Parameters ............................................................................................... 71
workflowEnds.............................................................................................. 72Syntax ..................................................................................................... 72Parameters ............................................................................................... 72
Chapter 5 xPression DevKit Web Services .................................................................. 75The IDocumentItem Web Service ....................................................................... 75searchDocumentItems .................................................................................. 76Syntax ..................................................................................................... 76Parameters ............................................................................................... 76Sample..................................................................................................... 78
The createDocumentItem Method.................................................................. 79Syntax ..................................................................................................... 80
5
Table of Contents
Parameters ............................................................................................... 80The getDocumentItemInfo Method ................................................................ 80Syntax ..................................................................................................... 82Parameters ............................................................................................... 82Examples ................................................................................................. 83
The publishAndReturnDocumentItem Method............................................... 84Syntax ..................................................................................................... 85Parameters ............................................................................................... 85
The publishAndReturnDocumentMultipleStream Method .............................. 85Syntax ..................................................................................................... 86Parameters ............................................................................................... 86
The documentItemsAssignedToUser Method ................................................. 87Syntax ..................................................................................................... 87Parameters ............................................................................................... 87
The reassignDocumentItemToUser Method.................................................... 88Syntax ..................................................................................................... 88Parameters ............................................................................................... 88
The updatePrimaryVariables Method ............................................................ 89Syntax ..................................................................................................... 89Parameters ............................................................................................... 89
The copyDocumentItem Method ................................................................... 90Syntax ..................................................................................................... 90Parameters ............................................................................................... 90
The addExternalContentByLink Method ........................................................ 91Syntax ..................................................................................................... 91Parameters ............................................................................................... 91
addExternalContentByStream ....................................................................... 92Syntax ..................................................................................................... 92Parameters ............................................................................................... 92
The reorderExternalContent Method ............................................................. 93Syntax ..................................................................................................... 94Parameters ............................................................................................... 94
The addAnnotation Method .......................................................................... 94Syntax ..................................................................................................... 95Parameters ............................................................................................... 95
The deleteExternalContent Method................................................................ 95Syntax ..................................................................................................... 96Parameters ............................................................................................... 96
The createAuthenticationToken Method......................................................... 96Syntax ..................................................................................................... 96Parameters ............................................................................................... 96
The complete DocumentItem Method ............................................................ 97Syntax ..................................................................................................... 97Parameters ............................................................................................... 97
The deleteDocumentItem Method.................................................................. 98Syntax ..................................................................................................... 98Parameters ............................................................................................... 98
The publishRevisionUnits Method................................................................. 99Syntax ..................................................................................................... 99Parameters ............................................................................................... 99
The setCarryForwardDocumentItem Method ............................................... 100Syntax ................................................................................................... 100Parameters ............................................................................................. 100
The clearCarryForwardDocumentItem Method ............................................ 100Syntax ................................................................................................... 100Parameters ............................................................................................. 101
The autoCarryForward Method ................................................................... 101Syntax ................................................................................................... 101Parameters ............................................................................................. 101
6
Table of Contents
The updateRUVariables Method .................................................................. 102Syntax ................................................................................................... 102Parameters ............................................................................................. 102
The submitDocumentItem Method .............................................................. 103Syntax ................................................................................................... 103Parameters ............................................................................................. 103
The approveDocumentItem Method ............................................................ 104Syntax ................................................................................................... 104Parameters ............................................................................................. 104
The rejectDocumentItem Method................................................................. 104Syntax ................................................................................................... 105Parameters ............................................................................................. 105
Calling the xEditor StartUp Application ........................................................... 105Syntax ....................................................................................................... 105Parameters ................................................................................................. 105Samples ..................................................................................................... 106Starting xEditor the First Time..................................................................... 106
Chapter 6 Output Statistics Reporting ....................................................................... 109What Types of Output are Counted? ................................................................ 109Output Statistics Report Details ....................................................................... 110Summary Report Content ........................................................................... 111Summary and Detail Report Content ........................................................... 112Batch Details .......................................................................................... 112Transaction Details ................................................................................. 112API and Web Services Details .................................................................. 113Sample Summary and Details Report....................................................... 114
Output Statistics Reporting Web Services ......................................................... 115getSummaryPublishingReport..................................................................... 115Syntax ................................................................................................... 115Parameters ............................................................................................. 116
getDetailedPublishingReport ...................................................................... 116Syntax ................................................................................................... 116Parameters ............................................................................................. 116
getCompressedSummaryPublishingReport .................................................. 117Syntax ................................................................................................... 117Parameters ............................................................................................. 117
getCompressedDetailedPublishingReport .................................................... 118Syntax ................................................................................................... 118Parameters ............................................................................................. 118
clearDetailPublishingReport........................................................................ 119Syntax ................................................................................................... 119Parameters ............................................................................................. 119
Chapter 7 xPressForms Web Services for Reporting ................................................ 121Get Report Method ......................................................................................... 121Syntax ....................................................................................................... 121Parameters ................................................................................................. 121
Get Report For Fields Method ......................................................................... 122Syntax ....................................................................................................... 122Parameters ................................................................................................. 122
Search for Forms Method ................................................................................ 123Simple Search Criteria ................................................................................ 123Advanced Search Criteria............................................................................ 124Syntax ....................................................................................................... 125Parameters ................................................................................................. 125
7
Table of Contents
Search for Forms Customized View Method..................................................... 125Simple Search Criteria ................................................................................ 126Advanced Search Criteria............................................................................ 126Syntax ....................................................................................................... 127Parameters ................................................................................................. 127
Get Search Field List Method........................................................................... 128Syntax ....................................................................................................... 128Parameters ................................................................................................. 128Return Value .............................................................................................. 128
Deprecated xPressForms Web Services............................................................. 128
Chapter 8 xPression RESTful Services for Batch ...................................................... 129RESTful HTTP Body Structure......................................................................... 129The General.security Element .......................................................................... 130Authorization............................................................................................. 131
Starting Batch Jobs.......................................................................................... 131The Job Element ......................................................................................... 131The xPressionPublishJob Element ................................................................ 132The JobOption Element ............................................................................... 132Starting a Batch Job with an Existing Job Definition ...................................... 132Starting a Batch Job with a Job Definition XML File....................................... 133
Prioritizing and Starting Jobs........................................................................... 134Syntax ....................................................................................................... 134Returned Information ................................................................................. 135
Terminating Jobs ............................................................................................ 136Syntax ....................................................................................................... 136Returned Information ................................................................................. 136
Deleting Job History ....................................................................................... 137Syntax ....................................................................................................... 137Returned Information ................................................................................. 137
Querying the Job Status .................................................................................. 138Syntax ....................................................................................................... 138Returning the Status of a Particular Job .................................................... 139
Returned Information ................................................................................. 139Common Data ........................................................................................ 139Statistics with Details Data ...................................................................... 140Statistics with Errors Data ....................................................................... 141
Samples of Returned Information ................................................................ 141Completed Job with “Statistics” Reporting Level ...................................... 141Completed Job with “Statistics with Details” Reporting Level.................... 142Stopped Job with “Statistics with Errors” Reporting Level......................... 143Job That is Not Started ............................................................................ 143Job That is Still Running.......................................................................... 144
Returning Queued Jobs ................................................................................... 144Syntax ....................................................................................................... 144Returning a List of All Queued Jobs ......................................................... 145
Returned Information ................................................................................. 146Returning a List of All Job Names.................................................................... 146Returning a List of All Running Jobs ................................................................ 147Configuring xPression for RESTful Batch Services ............................................ 148Enable xPression for Concurrent Batch Processing ........................................ 148Configure Servers for RESTful Service Batch Processing................................ 149Service Notification .................................................................................... 149
8
Table of Contents
Chapter 9 xDesign Online Editor Web Service ........................................................... 153
Chapter 10 xCatalog .................................................................................................... 155Access Rights ................................................................................................. 155The xCatalog Interface .................................................................................... 156Menu Bar ................................................................................................... 156The File Menu ........................................................................................ 156The Edit Menu ....................................................................................... 157The Help Menu ...................................................................................... 157
Browse and Search Pane.............................................................................. 158Browse Pane........................................................................................... 158Adding a Tag or Folder ....................................................................... 158Renaming a Tag or Folder ................................................................... 159Deleting a Tag or Folder ...................................................................... 159Copying and Pasting a Tag or Folder.................................................... 159Marking a Folder as Required ............................................................. 160
Search Pane ............................................................................................ 160Advanced Search................................................................................ 161Example......................................................................................... 162
Staging Area Pane .................................................................................. 162Document List............................................................................................ 163Document Detail Area ................................................................................ 163Information Tab...................................................................................... 164Tags Tab................................................................................................. 164Notes Tab............................................................................................... 164Custom Fields Tab .................................................................................. 164Properties Tab ........................................................................................ 165
Using xCatalog............................................................................................... 165Login ......................................................................................................... 166Importing and Exporting Documents........................................................... 166Importing Documents............................................................................. 167Troubleshooting - Importing Large Files............................................... 167
Exporting Documents ............................................................................. 167Working with Documents ........................................................................... 168Adding Tags to Documents ..................................................................... 168Changing Document Status ..................................................................... 169Deleting Documents ............................................................................... 169
Managing Custom Fields ............................................................................ 170Adding Fields ........................................................................................ 170Renaming a Field.................................................................................... 170Defining or Changing a Field’s Default Value ........................................... 171Deleting a Custom Field.......................................................................... 171
Creating Document Reports ........................................................................ 171Logging Out............................................................................................... 173
xCatalog Web Service...................................................................................... 173The getCatalogInfo Method......................................................................... 173Syntax ................................................................................................... 174Parameters ............................................................................................. 174Sample Returned Document.................................................................... 174
The searchForDocuments Method ............................................................... 175Simple Search Criteria ............................................................................ 175Advanced Search Criteria........................................................................ 176Syntax ................................................................................................... 177Parameters ............................................................................................. 177
The getDocumentInfo Method..................................................................... 178Syntax ................................................................................................... 178Parameters ............................................................................................. 178
9
Table of Contents
Chapter 11 Deprecated Utilities ................................................................................... 181Deprecated xPression Web Services ................................................................. 181Before You Begin ........................................................................................ 181Initial Questions ..................................................................................... 182Adding Your Application Definition ........................................................ 182Configuring Your Application with xAdmin............................................. 183Associating Attribute Sets with Your Application ................................. 184Assigning Data Sources to Your Application ........................................ 184Setting Up Access Rights for Your Application ..................................... 184Configuring Workflow for Your Application......................................... 185
Authentication and Access Control .......................................................... 185Authentication ................................................................................... 185Access Control ................................................................................... 185
Logging ................................................................................................. 185Licensing ............................................................................................... 185
Using WebServices with xPresso Packages ................................................... 186Web Services Processing Diagram................................................................ 186The Document Requester Web Service ......................................................... 186Requesting a Document by Customer Key................................................ 187Syntax ............................................................................................... 187Parameters ......................................................................................... 187
Requesting a Document by XML Customer Data ...................................... 188Syntax ............................................................................................... 188Parameters ......................................................................................... 188
Request Document by Output Profile....................................................... 190Syntax ............................................................................................... 190Parameters ......................................................................................... 190
The Document Composer Web Service......................................................... 191The Compose Document Method ............................................................ 191Syntax ............................................................................................... 191Parameters ......................................................................................... 191
The xPression Request Web Service ............................................................. 192The Publish Document Method ............................................................... 192Syntax ............................................................................................... 193Parameters ......................................................................................... 193
The Preview HTML Method.................................................................... 193Syntax ............................................................................................... 193Parameters ......................................................................................... 193
The Preview PDF Method ....................................................................... 194When Used with xPublish Documents ................................................. 194Username and Password Filter ............................................................ 194Syntax ............................................................................................... 194Parameters ......................................................................................... 195
The View Categories for User Method...................................................... 195Syntax ............................................................................................... 195Parameters ......................................................................................... 195
The View Documents in Category Method ............................................... 196Syntax ............................................................................................... 196Parameters ......................................................................................... 196
The View Output Profiles for Document Method ...................................... 196Syntax ............................................................................................... 196Parameters ......................................................................................... 197
The Get BDT Method .............................................................................. 197Syntax ............................................................................................... 197Parameters ......................................................................................... 197
The Get Assembled Document Method .................................................... 198Syntax ............................................................................................... 198Parameters ......................................................................................... 198
10
Table of Contents
The Publish MSOHTML Document Method ............................................. 198Syntax ............................................................................................... 198Parameters ......................................................................................... 199
The Publish And Return Document Method............................................. 199Syntax ............................................................................................... 199Parameters ......................................................................................... 199
The xResponse Web Service......................................................................... 200The Assign Document to User Method..................................................... 200Syntax ............................................................................................... 201Parameters ......................................................................................... 201
The Retrieve Work In Progress IDs Assigned to a User Method ................. 201Syntax ............................................................................................... 202Parameters ......................................................................................... 202
The Reassign Work Item Method ............................................................. 202Syntax ............................................................................................... 202Parameters ......................................................................................... 202
The Create Work Item Method ................................................................ 203Syntax ............................................................................................... 203Parameters ......................................................................................... 203
Publish and Return Document ................................................................ 204Syntax ............................................................................................... 204Parameters ......................................................................................... 204
The Revise Request Web Service .................................................................. 205The Assign Document To User Method .................................................... 205Syntax ............................................................................................... 205Parameters ......................................................................................... 205
The Retrieve Work In Progress IDs Assigned to a User Method ................. 206Syntax ............................................................................................... 206Parameters ......................................................................................... 206
The Reassign Work Item Method ............................................................. 206Syntax ............................................................................................... 207Parameters ......................................................................................... 207
The Query Work ItemStatus Method........................................................ 207Syntax ............................................................................................... 207Parameters ......................................................................................... 208
The Complete Item Method..................................................................... 208Syntax ............................................................................................... 208Parameters ......................................................................................... 208
The Preview Work Item In PDF Method................................................... 208Syntax ............................................................................................... 208Parameters ......................................................................................... 209
The Update Work Item Primary Data Method .......................................... 209Syntax ............................................................................................... 209Parameters ......................................................................................... 209Returns .............................................................................................. 210Notes ................................................................................................. 210
The Delete Work Item Method................................................................. 210Syntax ............................................................................................... 210Parameters ......................................................................................... 210Returns .............................................................................................. 211
The Publish and Return Work Item Method ............................................. 211Syntax ............................................................................................... 211Parameters ......................................................................................... 211Returns .............................................................................................. 211
Errors ........................................................................................................ 211xPression Java API.......................................................................................... 212Writing an xPression Facade Java Class ........................................................ 212Objectives .............................................................................................. 212
11
Table of Contents
Dependencies......................................................................................... 213Creating a Simple Properties File ............................................................. 213Connecting to xPression.......................................................................... 213Retrieving Categories.............................................................................. 214Retrieving Document Names................................................................... 215Retrieving a Document ........................................................................... 215
Writing a Quote Generator Application........................................................ 216Objectives .............................................................................................. 216Dependencies......................................................................................... 216Initial Setup ........................................................................................... 217Creating Standard Header and Footer Pages ............................................ 217Presenting a List of Categories................................................................. 218Presenting a List of Documents ............................................................... 220Presenting Input Fields ........................................................................... 220Generating a PDF Quote ......................................................................... 222Summary ............................................................................................... 226
Deploying an xPression Application ............................................................ 226J2EE Application Assembly ..................................................................... 227J2EE Web Application Overview ............................................................. 227J2EE Enterprise JavaBeans Overview ....................................................... 227J2EE Utility Classes Overview ................................................................. 228Web Application Archive Construction .................................................... 228
Command Reference .................................................................................. 229Method Name ........................................................................................ 229Syntax ............................................................................................... 229Parameters ......................................................................................... 230Sample............................................................................................... 230
The XPressionFacade Class ......................................................................... 230Running XPressionFacade with JBoss Server ............................................ 231getAppName ......................................................................................... 232Syntax ............................................................................................... 232Sample............................................................................................... 232
getBusinessDocuments ........................................................................... 232Syntax ............................................................................................... 232Parameters ......................................................................................... 232Sample............................................................................................... 233
getCategories ......................................................................................... 233Syntax ............................................................................................... 233Sample............................................................................................... 233
getDocumentPackedMSOHTML ............................................................. 233Syntax ............................................................................................... 234Parameters ......................................................................................... 234Sample............................................................................................... 234
getDocumentPackedMSOHTML (overloaded).......................................... 235Syntax ............................................................................................... 235Parameters ......................................................................................... 235Sample............................................................................................... 236
getDocumentPDF ................................................................................... 236Syntax ............................................................................................... 236Parameters ......................................................................................... 236Sample............................................................................................... 237
getDocumentPDF (overloaded) ............................................................... 237Syntax ............................................................................................... 237Parameters ......................................................................................... 237Sample............................................................................................... 238
getHaveStartSession ............................................................................... 238Syntax ............................................................................................... 238Sample............................................................................................... 238
getOutputProfiles ................................................................................... 239
12
Table of Contents
Syntax ............................................................................................... 239Sample............................................................................................... 239
getSchema.............................................................................................. 239Syntax ............................................................................................... 240Parameters ......................................................................................... 240Sample............................................................................................... 240
getStartSession ....................................................................................... 240Syntax ............................................................................................... 240Parameters ......................................................................................... 240Sample............................................................................................... 241
initServerConnection .............................................................................. 241Syntax ............................................................................................... 241Parameters ......................................................................................... 241Sample............................................................................................... 241
setStatus ................................................................................................ 242Syntax ............................................................................................... 242Parameters ......................................................................................... 242
publishDocument ................................................................................... 242Syntax ............................................................................................... 242Parameters ......................................................................................... 243Sample............................................................................................... 243
publishDocument (overloaded) ............................................................... 244Syntax ............................................................................................... 244Parameters ......................................................................................... 244Sample............................................................................................... 245
Ending a Session ........................................................................................ 245removeSession() ..................................................................................... 245Syntax ............................................................................................... 245Parameters ......................................................................................... 246
The XPressionDocument Class .................................................................... 246getDocumentData................................................................................... 246Syntax ............................................................................................... 246Sample............................................................................................... 246
getDocumentFormat ............................................................................... 247Syntax ............................................................................................... 247Sample............................................................................................... 247
getDocumentName................................................................................. 247Syntax ............................................................................................... 247Sample............................................................................................... 247
xPression Facade Exceptions ....................................................................... 248XPressionFrameworkException ............................................................... 248NoAuthorizedRightException ............................................................. 249NoStartSessionException .................................................................... 249NoSuchTargetException...................................................................... 249XPressionEJBException ....................................................................... 249XPressionProcessException ................................................................. 250
xPression EAI Adapter.................................................................................... 250xAdapter Architectural Overview................................................................ 251Listener Technology................................................................................ 251Request Processor................................................................................... 251xPression Batch Wrapper ........................................................................ 251Transformation Engine............................................................................ 252
xAdapter Deployment Architecture ............................................................. 252xAdapter Components................................................................................ 252Web Services Integration ......................................................................... 253Publish Document Web Service Method............................................... 253Preview PDF Web Service Method....................................................... 254Post For Batch Web Service Method ..................................................... 255
13
Table of Contents
Categories For User Web Service Method ............................................. 255Documents For Category Web Service Method ..................................... 256Output Profiles For Document Web Service Method ............................. 256Variables for Document Web Service Method ....................................... 257
JMS-Based Messaging Mechanism ........................................................... 257Publish Document Message................................................................. 258Preview PDF Message......................................................................... 261Post For Batch Message ....................................................................... 264
XML Message Error Handling ................................................................. 267Malformed XML................................................................................. 267Request Type Not Supported............................................................... 267XML Missing a Required Parameter..................................................... 268
Transformation Engine............................................................................ 268Example property file settings ............................................................. 269Using UTF–8 Format for Adapter Properties ........................................ 270
XML File Export for Batch Execution ....................................................... 270Adapter Configuration Information ............................................................. 273Creating the Adapter Application................................................................ 274Adding Your Application Definition ........................................................ 274
Configuring Your Application with xAdmin................................................. 275Associating Attribute Sets with Your Application ..................................... 275Assigning Categories to Your Application ................................................ 275Assigning Data Sources to Your Application ............................................ 276Setting Up Access Rights for Your Application ......................................... 276
Configure Your Batch Scripts....................................................................... 276Verifying Your Installation .......................................................................... 277JMS ....................................................................................................... 277
XML Files .................................................................................................. 278Publish Document .................................................................................. 278Preview with PDF .................................................................................. 279Post for Batch ......................................................................................... 280
Error Messages........................................................................................... 281Error Descriptions .................................................................................. 283Event Descriptions.................................................................................. 284
The Webtool Utility ........................................................................................ 285Registering Webtool.dll............................................................................... 286The Encryption Utility ................................................................................ 286encrypt .................................................................................................. 286Syntax ............................................................................................... 286Parameters ......................................................................................... 286Java Sample ....................................................................................... 286Visual Basic........................................................................................ 287
decrypt .................................................................................................. 287Syntax ............................................................................................... 287Parameters ......................................................................................... 287Java ................................................................................................... 287Visual Basic........................................................................................ 288
The Pack Utility .......................................................................................... 288pack ...................................................................................................... 288Syntax ............................................................................................... 288Parameters ......................................................................................... 288Java ................................................................................................... 289Visual Basic........................................................................................ 289
unpack................................................................................................... 289Syntax ............................................................................................... 290Parameters ......................................................................................... 290Java ................................................................................................... 290Visual Basic........................................................................................ 290
14
Table of Contents
Appendix A The AppList DTD ....................................................................................... 293The Complete AppList.dtd.............................................................................. 293The AppList and Application Elements........................................................ 294The WorkFlow Element............................................................................... 295The AccessRights Element........................................................................... 295The RequiredAttributes and Attr Elements................................................... 296
A Complete AppList.xml Example................................................................... 297
15
Table of Contents
List of Figures
Figure 1. The following image shows the document requester functional flow. ..................... 186Figure 2. The resulting page should look like this when launched in your browser. .............. 219Figure 3. The resulting GetDocuments.jsp page should look like this when
launched in your browser................................................................................ 220Figure 4. 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...................................................................... 222
Figure 5. The resulting Preview.jsp page should look like this when launched inyour browser.................................................................................................. 226
Figure 6. The following image shows the J2EE application assembly. ................................... 227Figure 7. These components and their relationships are shown in the diagram and
discussed below. ........................................................................................... 251Figure 8. The xAdapter, deployed on a WebSphere cluster of two Windows
servers, would look like the following image. ................................................... 252Figure 9. The following image shows how to edit the batchrunner.bat file. ........................... 277Figure 10. The following image shows how to retrieve the WDSL.......................................... 277Figure 11. The following image shows testing the JMS. ......................................................... 278Figure 12. The following image shows the WebSphere Embedded Messaging page. ............... 278
16
Preface
Welcome to the xFramework Development Guide, a guide to the interface between the CompuSetcomposition engine and xPression.
Intended AudienceThis guide is intended for users who are planning to use xPression Web Services, RESTFUL Services,or xCatalog.
ConventionsThe following conventions are used in this document:
Font Type Meaning
boldface Graphical user interface elements associated with an action
italic Book titles, emphasis, or placeholder variables for which you supply particularvalues
monospace Commands within a paragraph, URLs, code in examples, text that appears on thescreen, or text that you enter
xPressionHome
The term “xPressionHome” refers to the location where xPression is installed on your server. OnWindows servers, the default location is C:\xPression
Revision HistoryThe following changes have been made to this document.
17
Preface
Revision Date Description
February 2017 Added the new topic Adding a UniqueIdentifier, page 28.
January 2017 Changed all instances of “<configurationName>”to “<ConfigurationName”>.
November 2016 Initial publication
18
Chapter 1About xFramework
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 integrates with enterprise information systems, data, and distribution channels. ThexPression Server utilizes industry leading J2EE application servers and the standards-basedarchitecture they leverage. This provides for:
• Extensible component based design
• Worldwide compatibility with Unicode
• Enterprise scalability with J2EE
• Integration flexibility with databases, XML, Web Services, HTTP and APIs
• Multi-channel distribution
xFramework exposes xPression 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 the xPression Release Notes.
The xPression server engines are:• The xPression assembly engine
• The xPression publishers engine
• The xPression controllers
• xPression Batch
19
About xFramework
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.
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.
The xPublish Engine contains the following 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.
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 xPression Server node. Itwakes up every 30 seconds (a configurable option) and looks for work to do in xPression databasedistribution tables. When there is work to do, it sends e-mails, archive packages, and executes printscripts according to distribution definitions configured in xAdmin.
20
About xFramework
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, and supports 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 xPression Server installation filesand connectivity to xPression Server EJBs. It may be invoked through a command shell batch file,Java class main method call, or the xDashboard user interface.
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.
Some of the xFramework components have been deprecated. See Chapter 2, xPression Web ServiceAPI for detailed information.
Web Services 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.
21
About xFramework
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. This component has been deprecated with xPression.
EAI Adapter
Used for enhanced integration scenarios, for example, JMS and file loading. This component has beendeprecated with xPression.
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 differenthardware 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 DeprecatedxPression Web Services, page 181.
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 Integration StrategiesThere are three main xPression integration strategies: Real-Time (Request/Reply), Near-Time, andBatch. This diagram shows how xFramework integrates with the xPression server.
22
About xFramework
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.
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 xPression Java API, page 212.
• Web Services API - Can be used by either Java or non-Java calling applications. For moreinformation, see Deprecated xPression Web Services, page 181.
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 three types of messages:• Publish Document
• Preview PDF
• Post For Batch
23
About xFramework
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.
24
Chapter 2xPression Web Service API
Since version 4.0, xPression has introduced a new Web Service API that conforms to the WS-I BasicProfile. The old xFramework Web Service API, Java API, and xAdapter have been deprecated.Although these items will be supported for backward compatibility in the current version, EMCDocument Sciences encourages you to use the new Web Service API as it offers better performance,greater flexibility, and better security.
See the following topics:• Overview, page 25
• Authentication, page 26
• Setting Up Your Application, page 30
• IQuickDoc Configuration, page 33
• Error Messages, page 33
• CompuSet Bridge, page 34
OverviewWhen 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.
• Embedded components — xPression DevKit enables you to embed components into yourapplication.
25
xPression Web Service API
• Improved error messages and codes — For more information, see Error Messages, page 33.
• New xPressForms Web Service methods for xPressForms users — For more information, seeChapter 7, 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.
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.
The application name that you use must grant permissions that are appropriate for your request.In general, for core xPression services (client and server functions), you can supply credentialsfor the user under any application for which the user is authenticated. For solution applications(xPressForms, xPression DevKit, xResponse, xRevise), you must supply credentials for the exactapplication 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.
• xPresso for InDesign Documents—xPression chooses Adobe InDesign as the application .
26
xPression Web Service API
• 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>
Applying a Publish Compatibility Configuration
When you use IQuickDoc, xPression DevKit, or xDesign Online Editor Web Services to publishdocuments or create work items, you can optionally apply a publish compatibility configurationthat you defined in xAdmin. Refer to xAdmin User Guide for how to create a publish compatibilityconfiguration.
To apply a publish compatibility configuration, add the <ConfigurationName> element in therequestContext parameter, as shown in the following example:<RequestContext><Credentials method="Trusted UserID and Groups"><UserID>t1</UserID></Credentials><ConfigurationName>pcc1</ConfigurationName><ApplicationName></ApplicationName></RequestContext>
You can define only one publish compatibility configuration for each publish process. If the publishcompatibility configuration that you defined does not exist on the xPression Server, the publishwill fail.
27
xPression Web Service API
Adding a Unique Identifier
You can add a unique identifier that correlates xPression server log messages with the associated webservice request. xPression appends this unique identifier to all log messages related to the specificweb service call, and also adds it to the detailed statistics reports to help track any issues.
To add a unique identifier, add the <UniqueIdentifier> element in the requestContext parameter,as shown in the following example:<RequestContext><Credentials method="UserID and Password"><UserID>xxxx</UserID><Password>xxxx</Passsword></Credentials><ApplicationName>xPression Design</ApplicationName><UniqueIdentifier>c9e65bde-480b-40bf-a60b-c0be4baf187f</UniqueIdentifier></RequestContext>
The following web service APIs support a unique identifier:
• IQuickDoc Web Service
• CAF Web Services
• Workflow Integration Web Services
• Output Statistics Reporting Web Services
• xDesign Online Editor Web Services
• xPression DevKit Web Services
• xCatalog Web Service
• xPression RESTful Web Services for Batch
• xPressForms Web Services for Reporting
Note:• When calling RESTful Web Services to start a batch job, unique identifiers are appended only tolog messages about batch job queue addition, not to messages about batch job execution.
• In xPressForms Web Services, the getCategory, getCategories and isAvailable web services arenot supported.
Specifying Content Status for xDesign Documents
When you use the publishAndReturnDocument, publishAndReturnDocumentMultipleStream, orpublishDocument method of the IQuickDoc Web Service to publish xDesign documents, you canoptionally specify the content status by adding the <ContentStatus> element in the requestContextparameter, as shown in the following example:<RequestContext><Credentials method="Trusted UserID and Groups"><UserID>t1</UserID></Credentials><ApplicationName>xPression Design</ApplicationName><ContentStatus>Approved</ContentStatus></RequestContext>
28
xPression Web Service API
The value of the <ContentStatus> element can be Approved or Any, which is not case-sensitive:• Approved—xPression will only use approved content items when publishing xDesign documents.
• Any—xPression will use all content items when publishing xDesign documents. This setting hasthe same effect as not adding the <ContentStatus> element.
Note: If you specify a random value other than Approved, xPression will treat the value as Any.
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'><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>
29
xPression Web Service API
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 Definition
To add the application definition to AppList.xml, complete the following steps:
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.
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"
30
xPression Web Service API
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>
This sample application definition has workflow and access rights, but no required attributes.
Configuring Your Application with xAdmin
Now that you’ve added your application definition to AppList.xml, it’s time to configure it withxAdmin. To configure your application in xAdmin, complete the following steps:
1. Associating Attribute Sets with Your Application, page 31
2. Assigning Data Sources to Your Application, page 32
3. Setting Up Access Rights for Your Application, page 32
4. Configuring Workflow for Your Application, page 32 (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 Application1. 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.
31
xPression Web Service API
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, complete the following steps:
1. Select a category you’ve already assigned to your application.
2. Click the Data Sources tab.
3. Select a data source group from the list and click Set Application.
4. Select your application from the drop-down list.
5. A page appears that enables you to associate your available data sources with your application.Select the data sources you want to assign to your application and click Add.
6. In the Default Data Source list, select a default data source for your application and click Save.
7. To assign additional data sources to your application, repeat steps 2 - 7.
Setting Up Access Rights for Your Application
To set up access rights for your application, complete the following steps:
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. See xAdmin User Guide to assist you in setting up workflow for yourapplication.
32
xPression Web Service API
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 Update1. 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><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.
33
xPression Web Service API
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.
34
Chapter 3IQuickDoc 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 users.
If you are working with xPresso for Word documents in workflow enabled categories, see xPressofor Word Documents in Workflow-Enabled Categories, page 36.
Note:• DataDirect xQuery APIs are not supported in the IQuickDoc Web Service.
• We recommend to consider the case sensitivity for xPresso documents names intended forpublished using the web service. The document name can be case insensitive if the database forxPression is case insensitive.
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 36
• The documentsForCategory Method, page 37
• The descriptionForDocument Method, page 38
• The thumbnailForDocument Method, page 39
• The designToolForDocument Method, page 40
• The outputProfilesForDocument Method, page 41
• The versionsForDocumentWithWorkflowStatus Method, page 42
• The publishDocument Method, page 43
• The publishDocuments Method, page 46
• The publishAndReturnDocument Method, page 48
• The publishDocxAndReturnDocument Method, page 50
35
IQuickDoc Web Service
• The publishDocx Method, page 51
• The publishAndReturnDocumentMultipleStream Method, page 52
• The getDataCollectionTemplate Method, page 57
Note: We recommend to consider the case sensitivity for xPresso documents names intended forpublished using the web service. The document name can be case insensitive if the database forxPression is case insensitive.
xPresso for Word Documents inWorkflow-Enabled 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)
36
IQuickDoc Web Service
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.
The application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
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
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.
The application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
categoryName: String
A string specifying the name of the category for which you want to list all available documents.
37
IQuickDoc Web Service
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.
SyntaxString description = descriptionForDocument(requestContext, documentName)
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.
The application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
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:
38
IQuickDoc Web Service
/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.
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
requestContext : String
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.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see 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 Documentum
39
IQuickDoc Web Service
repository. In the Documentum repository, the user must be assigned the xpression_dashboard role.For more information, see Using requestContext with Documentum-Based Documents, page 27.
documentName : String
A string specifying the name of a document whose thumbnail you want to retrieve.• To request the latest version of the document, simply supply the document name.
Note: This does not apply to xPresso for Word documents, for which you must supply a 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.
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.
40
IQuickDoc Web Service
SyntaxString designTool = designToolForDocument(requestContext, documentName)
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.
The application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
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 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.
41
IQuickDoc Web Service
SyntaxString[] outputProfiles = outputProfilesForDocument(requestContext, documentName)
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.
The application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
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 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
where path is the folder path on the repository, filename is the name of the file, and version is theversion number.
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.
42
IQuickDoc Web Service
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)
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.
The application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
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. 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.
43
IQuickDoc Web Service
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 anerror message. Besides, InvalidDocumentTypeException will appear in the xPression log.
To use a publish compatibility configuration with this method, add the <ConfigurationName>element in the requestContext parameter. See Applying a Publish Compatibility Configuration, page27 for detailed information.
To specify the content status when publishing xDesign documents, add the <ContentStatus> elementin the requestContext parameter. See Specifying Content Status for xDesign Documents, page 28 fordetailed instructions.
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)
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.
The application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
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.
documentName : String
44
IQuickDoc Web Service
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
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
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
where path is the folder path on the repository, filename is the name of the file, and version is theversion number.
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 with the specified document. Theoutput profile must reside on the xPression Server.
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: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>
45
IQuickDoc Web Service
<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:outputProfileName>PayPilot</web:outputProfileName></web:publishDocument></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.
To use a publish compatibility configuration with this method, add the <ConfigurationName>element in the requestContext parameter. See Applying a Publish Compatibility Configuration, page27 for detailed information.
SyntaxpublishDocuments(String requestContext,String[] documentPackageNames, String outputProfileName, String customerData)
Parameters
requestContext: String
An XML document that passes user credentials for authentication. It also passes the name of theapplication for which the user is authenticated. In xPression, users are given access rights to specific
46
IQuickDoc Web Service
applications 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 application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
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.
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.
For documents that reside in the xPression database, use the following URL for documentName:/filename?version=versionnumber
where /filename is the name of the document and versionnumber is either a version number or thestring “LATEST”. The string “LATEST” selects the highest version number available. For example:/sampledoc?version=2.1
outputProfileName: String
The name of the publish profile to use when publishing the document package. The publish 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><
IQuickDoc Web Service
<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 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 streams contain 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.
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 anerror message. Besides, InvalidDocumentTypeException will appear in the xPression log.
48
IQuickDoc Web Service
To use a publish compatibility configuration with this method, add the <ConfigurationName>element in the requestContext parameter. See Applying a Publish Compatibility Configuration, page27 for detailed information.
To specify the content status when publishing xDesign documents, add the <ContentStatus> elementin the requestContext parameter. See Specifying Content Status for xDesign Documents, page 28 fordetailed instructions.
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>
Syntaxbyte[] document = publishAndReturnDocument(requestContext, documentName,customerData, outputProfileName)
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.
The application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
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.
documentName : String
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
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:
49
IQuickDoc Web Service
/sampledoc?version=2.1
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
where path is the folder path on the repository, filename is the name of the file, and version is theversion number.
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 string containing 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 with the specified document. Theoutput profile must reside on the xPression Server.
The publishDocxAndReturnDocument MethodThe publishDocxAndReturnDocument method enables you to publish an iDOCX output to otherformats and return the output content of the first “Return to Calling Application” stream. See xAdminUser Guide for the iDOCX output.
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 the first “Return to Calling Application” stream.
To use a publish compatibility configuration with this method, add the <ConfigurationName>element in the requestContext parameter. See Applying a Publish Compatibility Configuration, page27 for detailed information.
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.
50
IQuickDoc Web Service
Syntaxbyte[] publishDocxAndReturnDocument(String requestContext,byte[] document, String outputProfileName)
ParametersrequestContext: String
See The requestContext Parameter, page 26 for the requestContext parameter.document: byte[]
A byte array that contains an iDOCX output, which must be published with the iDocx outputdefinition.outputProfileName: String
A string specifying the name of an output profile valid for use with the specified document. Theoutput profile must reside on the xPression Server. The output of the output profile can be PDF, PS,PCL, AFP, or HTML.
The publishDocx MethodThe publishDocx method enables you to publish an iDOCX output to other formats and return thefinal output file to your calling application using multiple streams. See xAdmin User Guide for theiDOCX output.
To return the document to your calling application, the output profile you specify must contain anoutput stream whose distribution definition is defined with the “Return to Calling Application”option. If no output streams are defined with a distribution definition marked as “Return to CallingApplication”, the method will not return any document data 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. Ifyou want to return document metadata with this method, define the metadata in the DistributionDefinition.
To use a publish compatibility configuration with this method, add the <ConfigurationName>element in the requestContext parameter. See Applying a Publish Compatibility Configuration, page27 for detailed information.
Return Value: This method returns an object representing the document that was published andreturned. The format of the document is determined by the output profile. If your distributiondefinition does not use the “Return to calling application” option, this method will return a nullvalue. If the method fails, it returns a SOAP Fault that indicates the reason for the failure.
SyntaxMultiStream publishDocx(String requestContext,byte[] document, String outputProfileName)
51
IQuickDoc Web Service
ParametersrequestContext: String
See The requestContext Parameter, page 26 for the requestContext parameter.document: byte[]
A byte array that contains an iDOCX output, which must be published with the iDocx outputdefinition.outputProfileName: String
A string specifying the name of an output profile valid for use with the specified document. Theoutput profile must reside on the xPression Server. The output of the output profile can be PDF, PS,PCL, AFP, or HTML.
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 “Returnto Calling Application” option. If no output streams are defined with a distribution definitionmarked as “Return to Calling Application”, the method will not return any document data whensuch documents 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, define themetadata in the Distribution Definition.
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.
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 anerror message. Besides, InvalidDocumentTypeException will appear in the xPression log.
To use a publish compatibility configuration with this method, add the <ConfigurationName>element in the requestContext parameter. See Applying a Publish Compatibility Configuration, page27 for detailed information.
52
IQuickDoc Web Service
To specify the content status when publishing xDesign documents, add the <ContentStatus> elementin the requestContext parameter. See Specifying Content Status for xDesign Documents, page 28 fordetailed instructions.
Return Value: This method returns an object 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.
Syntax
MultiStream multistream= publishAndReturnDocumentMultipleStream(requestContext,documentName, customerData, outputProfileName, includeMetaData)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request. Forthis method, the following xPression application names are valid: xPression Design, xPression Revise,xPression Response, xPression DevKit, Word, Dreamweaver, and InDesign. For more information,see The requestContext Parameter, page 26.
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.
documentName : String
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
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
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
where path is the folder path on the repository, filename is the name of the file, and version is theversion number.
53
IQuickDoc Web Service
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 string containing 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 with the specified document. Theoutput profile must reside on the xPression Server.
includeMetaData : Boolean
If set to true, this method will also return the Generic Index metadata file. The metadata file is 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
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.
54
IQuickDoc Web Service
Use “Word” as the application name. This value will grant permissions that are appropriate for yourrequest. For more information, see The requestContext Parameter, page 26.
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.
documentName : String
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
where path is the folder path on the repository, filename is the name of the file, and version is theversion number.
customerData : String
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.
55
IQuickDoc Web Service
Examples
These examples show input for the following two scenarios:• With NULL customerData Value, page 58
• With Supplied customerData, page 59
With NULL customerData Value
Input XML<web:getTemplateFields><!--Optional:--><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password">
<UserID>user</UserID><Password>password</Password>
</Credentials><ApplicationName>Word</ApplicationName>
</RequestContext>]]></web:requestContext><!--Optional:--><web:documentName>/doc?version=1.1</web:documentName><!--Optional:--><web:customerData></web:customerData></web:getTemplateFields>
With Supplied customerData
Input XML<web:getTemplateFields><!--Optional:--><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password">
<UserID>user</UserID><Password>password</Password>
</Credentials><ApplicationName>Word</ApplicationName>
</RequestContext>]]></web:requestContext><!--Optional:--><web:documentName>/doc?version=1.1</web:documentName><!--Optional:--><web:customerData><
IQuickDoc Web Service
</root>]]></web:customerData></web:getTemplateFields>
The getDataCollectionTemplate Method
Caution: This method is deprecated. Use the getTemplateFields method instead.
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
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.
Use “Word” as the application name. This value will grant permissions that are appropriate for yourrequest. For more information, see The requestContext Parameter, page 26.
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.
documentName : String
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:
57
IQuickDoc Web Service
/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
where path is the folder path on the repository, filename is the name of the file, and version is theversion number.
customerData : String
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 58
• With Supplied customerData, page 59
With NULL customerData Value
Input XML<web:getDataCollectionTemplate>
58
IQuickDoc Web Service
<!--Optional:--><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password">
<UserID>user</UserID><Password>password</Password>
</Credentials><ApplicationName>Word</ApplicationName>
</RequestContext>]]></web:requestContext><!--Optional:--><web:documentName>/doc?version=1.1</web:documentName><!--Optional:--><web:customerData></web:customerData></web:getDataCollectionTemplate>
With Supplied customerData
Input XML<web:getDataCollectionTemplate><!--Optional:--><web:requestContext><![CDATA[<RequestContext><Credentials method="UserID and Password">
<UserID>user</UserID><Password>password</Password>
</Credentials><ApplicationName>Word</ApplicationName>
</RequestContext>]]></web:requestContext><!--Optional:--><web:documentName>/doc?version=1.1</web:documentName><!--Optional:--><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>
59
IQuickDoc Web Service
60
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 61
• DataBrowsingService, page 64
• WorkflowService, page 67
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 61
• listWorkFlowAvailableDocuments, page 62
• getDocumentType, page 63
• getDocumentVersions, page 63
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)
61
Workflow Integration Web Services
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.
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext 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 cannot 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
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.
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
cateName : String
The name of the category where the method will search for eligible documents.
62
Workflow Integration Web Services
getDocumentType
This method identifies the publisher type for a specified document.
Return Value: This method returns a String identifying the publisher type of the specified document.The return values can be:• CompuSet— for CompuSet documents
• xPublish— for xDesign xPublish documents
• xPressoInDesign— for xPresso for Adobe InDesign documents
• xWordDesigner— for xPresso for Word documents
• xPressoDreamWeaver— for xPresso for Dreamweaver documents
Syntax
String[] getDocumentType(requestContext, docName)
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.
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
docName : String
The name of the document whose publisher type you want identified by the method.
getDocumentVersions
This method retrieves the version effective date or version number of a specified xPresso document,depending on the type of the document. This method does not return information about documentscreated in xDesign.
63
Workflow Integration Web Services
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
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.
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
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 documentName WSDL can be found here:http://<server>:<port>/xFramework/services/DataBrowsingService?wsdl
This Web Service contains the following methods:• getDefaultDS, page 64
• listKeys, page 65
• getDataRecordXML, page 66
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 you
64
Workflow Integration Web Services
specify 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)
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.
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
docName : String
The name of the document whose default data source you want to identify.
listKeys
This method lists all of the customer data keys in a specified xPublish data source.
65
Workflow Integration Web Services
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
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.
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
dsName : String
The name of the data source for which you want to return a list of customer keys.
getDataRecordXML
This method retrieves the XML for one customer data record.
Return Value: This method returns an XML document containing the data from one customer record.
Syntax
String[] getDataRecordXML(requestContext, dsName, keyValues)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of theapplication for which the user is authenticated. In xPression, users are given access rights to specificapplications because each application has a different set of access rights. By specifying the applicationname, you are requesting the access rights granted to the user for that specific application.
66
Workflow Integration Web Services
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
dsName : String
The name of the data source you want to use.
keyValues : String
The key value that you want to use to retrieve a data record from the data source.
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 67
• statusInLifecycle, page 68
• previewPDF, page 68
• previewHTML, page 69
• workflowBegins, page 70
• setLifecycleStatus, page 71
• workflowEnds, page 72
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.
Syntax
String[] listLifecycles(requestContext)
67
Workflow Integration Web Services
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.
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
statusInLifecycle
This method lists all the available statuses in a given Life Cycle.
Return Value: This method returns zero or more Strings in a String array. Each String in the arrayrepresents a status in a Life Cycle.
Syntax
String[] statusInLifecycle(requestContext, lifecycleName)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
lifecycleName : String
The name of the Life Cycle for which you want to return all available statuses.
previewPDF
This method uses the “PDF to Caller” output profile to preview a document in PDF format.
68
Workflow Integration Web Services
Return Value: This method returns a binary array, which is the preview PDF file.
Syntax
byte[] previewPDF(requestContext, docName, version, dsName, customerData)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
docName : String
The name of the document that you want to preview.
version : String
The version parameter is only used for xPresso documents. This parameter identifies the 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.
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>
previewHTML
This method uses the “HTML to Caller” output profile to preview a document in HTML format.
69
Workflow Integration Web Services
Return Value: This method returns a byte array, which is the resulting preview HTML file.
Syntax
byte[] previewHTML(requestContext, docName, version, dsName, customerData)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
docName : String
The name of the document that you want to preview.
version : String
The version parameter is only used for xPresso documents. This parameter identifies the 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.
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>
workflowBegins
This method enables you to notify xPression that a document is being submitted to a workflow.
70
Workflow Integration Web Services
Syntax
String[] workflowBegins(requestContext, docName, version)
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.
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
docName : String
The name of the document that you want to submit to a workflow.
version : String
The version parameter is only used for xPresso documents. This parameter identifies the 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.
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)
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.
71
Workflow Integration Web Services
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
docName : String
The name of the document for which you want to change the Life Cycle status.
version : String
The version parameter is only used for xPresso documents. This parameter identifies the 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.
status : String
The name of the status that you want to apply to the specified document. Ensure that 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
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.
The application name that you use must grant permissions that are appropriate for your request. Allvalid application names are acceptable, including: xPression Design, xPression Revise, xPressionResponse, xPression DevKit, Word, Dreamweaver, and InDesign. For more information, see TherequestContext Parameter, page 26.
docName : String
The name of the document that you want to exit a workflow.
version : String
The version parameter is only used for xPresso documents. This parameter identifies the versionof the specified document that you want to preview. For both xWord and xInDesign documents,
72
Workflow Integration Web Services
the version is expressed as the major and minor version numbers in the x.x format, for example,1.0, 1.1, 2.0.
successFlag : Boolean
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.
73
Workflow Integration Web Services
74
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 xEditor User Guide.
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:• searchDocumentItems, page 76
• The createDocumentItem Method, page 79
• The getDocumentItemInfo Method, page 80
• The publishAndReturnDocumentItem Method, page 84
• The publishAndReturnDocumentMultipleStream Method, page 85
• The documentItemsAssignedToUser Method, page 87
• The reassignDocumentItemToUser Method, page 88
• The updatePrimaryVariables Method , page 89
• The copyDocumentItem Method, page 90
• The addExternalContentByLink Method, page 91
75
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 97
• The deleteDocumentItem Method, page 98
• The publishRevisionUnits Method, page 99
• The setCarryForwardDocumentItem Method, page 100
• The clearCarryForwardDocumentItem Method, page 100
• The autoCarryForward Method, page 101
• The updateRUVariables Method, page 102
• The submitDocumentItem Method, page 103
• The approveDocumentItem Method, page 104
• The rejectDocumentItem Method, page 104
searchDocumentItems
The searchDocumentItemsmethod enables you to search for a work item based on the selectedcriteria.
The Return Value is a string array of work item IDs. If the method fails, it returns a SOAP Fault thatindicates the failure reason.
Syntax
String[] documentItemIDs = searchDocumentItems(requestContext, searchCriteriaXML)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of theapplication for which the user is authenticated. In xPression, users are given access rights to specificapplications because each application has a different set of access rights. By specifying the applicationname, you are requesting the access rights granted to the user for that specific application.
76
xPression DevKit Web Services
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see 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="External Content">1</KEY_VALUE>
<KEY_VALUE name="AUTOPAY_KEY" category="xEditor_UC">1</KEY_VALUE><OR>
</CUSTOMER_KEYS>
77
xPression DevKit Web Services
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="External Content">1</KEY_VALUE>
<KEY_VALUE name="AUTOPAY_KEY" category="xEditor_UC">1</KEY_VALUE></CUSTOMER_KEYS>
</PHASE><AND />
78
xPression DevKit Web Services
<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.
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.
To use a publish compatibility configuration with the createDocumentItem method, add the<ConfigurationName> element in the requestContext parameter. See Applying a PublishCompatibility Configuration, page 27 for detailed information.
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.
79
xPression DevKit Web Services
Syntax
String documentItemID = createDocumentItem(requestContext, documentName,customerData, assignToUserName)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentName : String
A string specifying the name of the document for which you want to create a work item. Thedocument must reside on the xPression Server.
customerData : String
The value for this parameter depends upon the type of data source assigned to the category thatcontains the document you want to publish. If your data source is an XML document, you mustprovide a single record of XML customer data. If your data source is a relational database, youmust provide keys for the relational database data source. You can provide the primary key forthe customer data using the following format:<Keys><Key name="keyName1">keyValue</Key><Key name="keyName2">keyValue</Key></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 infoToReturn
80
xPression DevKit Web Services
parameter. You can return information about the following items by passing the specified term inthe infoToReturn parameter:• Annotation— For each annotation in the document, the method returns the annotation type, theuser who created the annotation, the timestamp, and the annotation note itself.
• ASL— A description of all objects in the document.
• Document— Basic information about the document, including the document item ID, thedocument name, the document category, the publishing type, and the customer key of the user forwhom the work item was assembled.
• External 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.
81
xPression DevKit Web Services
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 83.
Syntax
String documentItemInfoXML = getDocumentItemInfo (requestContext,documentItemIDs, infoToReturn)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemIDs : String[]
An array of unique identifiers for document items.
infoToReturn : String[]
An optional parameter specifying a subset of the information to return. If this parameter is null or 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”
82
xPression DevKit Web Services
See the description of this method (The getDocumentItemInfo Method, page 80) for details aboutwhat information is returned for each string.
Examples
This section contains an example of the XML returned from this method.<DocumentItems><DocumentItem id="7311" name="Auto Policy"><Annotations><Annotation type="document"><Item user="tester" timestamp="2010-03-29T10:22:32"note="Passed verification."/>
</Annotation></Annotations><ASL BDTid="2202" name="Auto Policy" style1="8652" style2="8653"categoryName="Auto" customerKeys="1" publisherType="xPublish"><Section name="Sect1"/><CRObject name="Introduction" shared="false" version="1.00" originalID="-1"revision="0"crc="2531604323" objID="8803" createDate="2010-03-29"/>
</ASL><Document><Name>Auto Policy</Name><Category>Auto</Category><CustomerKey>1</CustomerKey><PublisherType>xPublish</PublisherType></Document><ExternalContents><ExternalContent><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>
83
xPression DevKit Web Services
<Shared>false</Shared><Selected>false</Selected><Version>1.00</Version></OptionalParagraph>/OptionalParagraphGroup></OptionalParagraphs><RevisionUnits><RevisionUnit id="8803"><Name>Introduction</Name><Revision>0</Revision><Version>1.00</Version><CreateDate>2010-03-29</CreateDate><CRC>2531604323</CRC><OriginalID>-1</OriginalID><Shared>false</Shared></RevisionUnit></RevisionUnits><Variables><Variable name="V_STR_2" value="CA"/><Variable name="V_STR_1" value="StringValue"/></Variables><WorkItemHistory name="StringsOfVariables_xPub" workItemId="7311"createDate="2010-03-29T09:59:21" serverVer="4.0"><GlobalVariables><Variable name="AUTOPAY.AUTOPAY_KEY" type="integer" currentVer="0"><Version ver="0"><Value>1</Value></Version></Variable></GlobalVariables><RevisionUnits><RevisionUnit id="8803" name="Introduction"><Variables><Definitions><Variable name="V_STR_2" type="string" currentVer="0"><Version ver="0"><Value>CA<Value></Version></Variable></Definitions></Variables></RevisionUnit></RevisionUnits></WorkItemHistory><DocumentItem><DocumentItems>
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.
84
xPression DevKit Web Services
To use a publish compatibility configuration with this method, add the <ConfigurationName>element in the requestContext parameter. See Applying a Publish Compatibility Configuration, page27 for detailed information.
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
MultiStrea multistream = publishAndReturnDocumentItem(requestContext, documentItemID,outputProfileName)
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.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item.
outputProfileName : String
A string specifying the name of an output profile valid for use with the specified document. Theoutput profile must reside on the xPression Server.
The publishAndReturnDocumentMultipleStreamMethod
The publishAndReturnDocumentMultipleStream web service method enables you to publish adocument work item to an output profile using multiple streams. This method works identically
85
xPression DevKit Web Services
to 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.
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.
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 anerror message. Besides, InvalidDocumentTypeException will appear in the xPression log.
To use a publish compatibility configuration with this method, add the <ConfigurationName>element in the requestContext parameter. See Applying a Publish Compatibility Configuration, page27 for detailed information.
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.
Syntax
MultiStrea multistream = publishAndReturnDocumentMultipleStream(requestContext, workItemId,outputProfileName, includeMetaData)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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.
86
xPression DevKit Web Services
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
workItemID : String
The unique identifier for the document item.
outputProfileName : String
A string specifying the name of an output profile valid for use with the specified document. Theoutput profile must reside on the xPression Server.
includeMetaData : Boolean
If set to true, this method will also return the Generic Index metadata file. The metadata file is 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.
Syntax
String[] documentItemIDs = documentItemsAssignedToUser(requestContext, userName)
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.
87
xPression DevKit Web Services
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
userName : String
The username of the user for whom you want to return a list of assigned document items.
The reassignDocumentItemToUser Method
The reassignDocumentItemToUser method moves the document item from its currently 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
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.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item.
assignToUserName : String
88
xPression DevKit Web Services
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
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.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item.
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"/>
89
xPression DevKit Web Services
<Variable name="AUTOPAY.LAST_NAME" value="Anderson"/></PrimaryVariables></Variables>
The copyDocumentItem Method
The copyDocumentItem method makes a copy of a document work item and assigns it to thespecified user. The most common use of this method is to copy a completed document work itemfrom history to make a new editable document work item. The advantage of using this method is thatit enables you to reuse all the previous customizations of that work item.
Return Value: This method returns a string message that identifies the newly copied document workitem. If the method fails, it returns a SOAP Fault that indicates the reason for the failure.
Syntax
String newDocumentItemId = copyDocumentItem (requestContext, documentItemID,assignToUserName)
Parameters
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.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item that you want to copy.
assignToUserName : String
The username to which you will assign the work item.
90
xPression DevKit Web Services
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
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.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item.
ruName : String
The name for the external content Revision Unit.
externalContentLink : String
The link to the location of the external content. You can supply a path to a location on the server, 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 Syntax
91
xPression DevKit Web Services
http://<machine name>/<path>/<filename>
URL Examplehttp://localhost/UC/A40127.pdf
• ECM Path Syntax (syntax is case sensitive)ecm::<ecmConfigName>?uri=/<path>/<filename>?version=<version>
ECM Path Exampleecm::DCTMServer?uri=/UC/A40127.pdf?version=CURRENT
format : String
The external content file format. Valid values include:• “.pdf”
• “word.doc”— not supported when using a URL link. Only supported for local path and ECM link.
• “.tif”
position : String
When you add external content to the document, you must specify the position in the documentwhere you want the external content to appear. You specify the position by identifying the RevisionUnit ID of the Revision Unit that should follow the external content. The external content will beplaced ahead of the Revision Unit you identify with this parameter. If you want to place the contentat the end of the document, supply a null value.
options : String
This parameter is unused at this time, but is included for future updates.
addExternalContentByStream
This method enables you to add external content to your document as a Revision Unit. This methodadds the byte array of the external content to the specified document item.
Return Value: This method returns a string identifying the revision unit ID of the external content.
Syntax
String RUID = addExternalContentByStream(String requestContext,String documentItemID, String ruName, String externalContent,String format, String position, String options) throws AxisFault;
Parameters
requestContext : String
92
xPression DevKit Web Services
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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item.
ruName : String
The name for the external content Revision Unit.
externalContentLink : String
Supply the byte array for the external content.
format : String
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.
93
xPression DevKit Web Services
Syntax
String message = reorderExternalContent(String requestContext,String documentItemID, String externalContentID, String targetPosition)throws AxisFault;
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item.
externalContentID : String
The ID of the external content item that you want to reorder.
targetPosition : String
When you reorder external content in your document, you must specify the position in the 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.
94
xPression DevKit Web Services
Syntax
String message = addAnnotation (String requestContext,String documentItemID, String annotationInfo) throws AxisFault;
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item.
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.
95
xPression DevKit Web Services
Syntax
String message = deleteExternalContent (String requestContext,String documentItemID, String externalContentID) throws AxisFault;
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item.
externalContentID : String
The ID of the external content that you want to delete.
The createAuthenticationToken Method
This method enables you to create a string authentication token that will be used to log on to thexEditor if the user credentials are valid.
Return Value: Returns a string authentication token. Upon failure, an AxisFault exception is thrown.
Syntax
String tokenID = createAuthenticationToken(String requestContext, long timeout)throws AxisFault;
Parameters
requestContext : String
96
xPression DevKit Web Services
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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
timeout : String
The number of milliseconds that the token should be active.
The complete DocumentItem Method
The completeDocumentItem method changes the state of a document work item from a state where itcan be manipulated into a state where it is locked and can only be referenced for historical purposes.At that point, the document work item is considered “completed”. Should you need to make changesto the document work item, copy it to a new document work item through the copyDocumentItemweb service method.
Return Value: This method returns a string message when the method successfully completes thedocument work item. If the method fails, it returns a SOAP Fault that indicates the reason for thefailure.
Syntax
String successMessage = completeDocumentItem (requestContext, documentItemID)
Parameters
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.
97
xPression DevKit Web Services
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item that you want to move to a “completed” state. Oncethe document work item has been completed, it cannot be edited.
The deleteDocumentItem Method
The deleteDocumentItem method deletes the specified document work item and associated historyfrom the server.
Return Value: This message returns a string message when the method successfully deletes thedocument work item. If the method fails, it returns a SOAP Fault that indicates the reason for thefailure.
Syntax
String successMessage = deleteDocumentItem (requestContext, documentItemID)
Parameters
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.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
For more information, see The requestContext Parameter, page 26.
documentItemID : String
The unique identifier for the document item that you want to delete.
98
xPression DevKit Web Services
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.
To use a publish compatibility configuration with this method, add the <ConfigurationName>element in the requestContext parameter. See Applying a Publish Compatibility Configuration, page27 for detailed information.
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
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.
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.
documentItemID : String
The unique identifier for the document item whose partial content is being requested.
ruNames:String[]
A list of the revision unit names to publish. Note that RU names are required to be unique in 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.
99
xPression DevKit Web Services
The setCarryForwardDocumentItem Method
This Web Service enables you to place a Work in Progress into Carry Forward mode.
Return Value: A 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
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. The useryou provide must have Write or Admin permission for the category/application combination.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
documentItemID : String
The unique identifier for the document item that you want to 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: A 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)
100
xPression DevKit Web Services
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. The useryou provide must have Write or Admin permission for the category/application combination.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
documentItemID : String[]
The unique identifier for the document item that you want to remove from Carry Forward mode.
The autoCarryForward Method
This web service enables you to initiate a Carry Forward between two xRevise/IDDK work items.
Return Value: A success message is returned if the method completes successfully. If the methodfails, it returns a SOAP Fault that indicates the reason for the failure.
The method fails under the following conditions:
• The work item contains multiple revision units with the same name.
• Carry Forward is attempted between documents of different categories.
Note: To ensure successful completion, adjust the Carry Forward configuration settings in theDEFAULT_CONFIG.xml file. For more information, see the xEditor User Guide.
Syntax
String message = autoCarryForward(String requestContext, String documentItemID,String CFCompareID, String xEditorConfigName)
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.
101
xPression DevKit Web Services
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression DevKit
• xPression Revise
• Your custom application name
documentItemID: String
The unique identifier for the document item that you want to place into Auto Carry Forward mode.
CFCompareID: String
The unique identifier for the document item that you want to use for comparison in Auto CarryForward mode.
xEditorConfigName: String
The xEditor Configuration name defined in xEditor Configuration within xAdmin ResourceManagement.
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.
Syntax
updateRUVariables(requestContext, documentItemID, ruVariableInfo)
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. The useryou provide must have Write or Admin permission for the category/application combination.
102
xPression DevKit Web Services
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
documentItemID : String
The unique identifier for the document item.
ruVariableInfo : String
XML code that identifies the variable names and values that you want to update. For example:<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)
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. The useryou provide must have Write or Admin permission for the category/application combination.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
103
xPression DevKit Web Services
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.
documentItemID : String[]
The unique identifier for the document item that you want to submit.
The approveDocumentItem Method
This Web Service enables you to approve a specified document item.
Return Value: If successful, this webservice returns “Document item: [documentitemID] has beenapproved.” If the method fails, it returns a SOAP Fault that indicates the reason for the failure.
Syntax
String approveDocumentItem (requestContext, documentItemID)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of theapplication for which the user is authenticated. In xPression, users are given access rights to specificapplications because each application has a different set of access rights. By specifying the applicationname, you are requesting the access rights granted to the user for that specific application. The useryou provide must have Write or Admin permission for the category/application combination.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
documentItemID : String[]
The unique identifier for the document item that you want to submit.
The rejectDocumentItem Method
This Web Service enables you to reject a specified document item.
Return Value: If successful, this webservice returns “Document item: [documentitemID] has beenrejected.” If the method fails, it returns a SOAP Fault that indicates the reason for the failure.
104
xPression DevKit Web Services
Syntax
String rejectDocumentItem (requestContext, documentItemID)
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. The useryou provide must have Write or Admin permission for the category/application combination.
The application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Revise
• xPression DevKit
• Your custom application name
documentItemID : String[]
The unique identifier for the document item that you want to reject.
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:
105
xPression DevKit Web Services
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 and .
CID
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
106
xPression DevKit Web Services
• 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.
107
xPression DevKit Web Services
108
Chapter 6Output 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 109.
• Output Statistics Report Details, page 110.
• Output Statistics Reporting Web Services, page 115.
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
109
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, page111 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 112 for more information.
110
Output Statistics Reporting
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.
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.
111
Output Statistics Reporting
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 112
• Transaction Details, page 112
• API and Web Services Details, page 113
• Sample Summary and Details Report, page 114
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.
— serverIP — The IP address of the server. If the server has multiple IP addresses, xPression liststhem all and separates them with commas.
— server — The server name and port number.
For example:<Batch pages="8">
<Run pages="8" status="Success" op="PDF" runId="1462009" job="jobname"end="00:48:21" start="00:48:11" serverIP="10.32.224.28,192.168.50.1,192.168.6.1" server="Server1:8080"/>
</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
112
Output Statistics Reporting
“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.
— op — The Output Profile used to publish the document.
— status — The final status of the job. This will indicate success or failure.
— pages — The number of pages published by the transaction.
For example:<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
• xPressionRequest
• xResponseRequest
• xReviseRequest
• xDevKit
• JFramework
113
Output Statistics Reporting
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.
— op — The Output Profile used to publish the document.
— status — The final status of the job. This will indicate success or failure.
— pages — The number of pages published by the API or web service.
For example:<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 pages="2" status="Success" op="PDF" runId="146200" job="jobname"end="00:48:21" start="00:48:11" serverIP="10.32.224.28,192.168.50.1,192.168.6.1" server="Server1:8080"/>
</Batch><Transaction pages="2">
<xResponse pages="0"/><xRevise pages="2">
<Publish time="00:49:35" user="root" doc="docname"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"
114
Output Statistics Reporting
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 115
• getDetailedPublishingReport, page 116
• getCompressedSummaryPublishingReport, page 117
• getCompressedDetailedPublishingReport, page 118
• clearDetailPublishingReport, page 119
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)
115
Output Statistics Reporting
Parameters
requestContext : String
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 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)
Parameters
requestContext : String
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
116
Output Statistics Reporting
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 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.
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
requestContext : String
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 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
117
Output Statistics Reporting
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.
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
requestContext : String
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 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.
118
Output Statistics Reporting
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
requestContext : String
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 The requestContext Parameter, page 26.
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.
119
Output Statistics Reporting
120
Chapter 7xPressForms 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 121
• Get Report For Fields Method, page 122
• Search for Forms Method, page 123
• Search for Forms Customized View Method, page 125
• Get Search Field List Method, page 128
• Deprecated xPressForms Web Services, page 128
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
121
xPressForms Web Services for Reporting
The format of the report. You can choose XML or CSV (comma delimited variable file).
username: String
The name of the xPressForms user.
password: String
The xPressForms user’s password.
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
The name of the xPressForms user.
password: String
The xPressForms user’s password.
122
xPressForms Web Services for Reporting
The following example shows the method creating an XML formatted report for three specificdocuments.
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.
Simple Search Criteria
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>
123
xPressForms Web Services for Reporting
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 “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>
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>
124
xPressForms Web Services for Reporting
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>
SyntaxsearchForForms("String criteria", "String format", "String username","String password")
Parameters
criteria : String
The search criteria in XML format. See Simple Search Criteria , page 123 and .
format : String
The format of the report. You can choose XML or CSV (comma delimited variable file)
username: String
The name of the xPressForms user.
password: String
The xPressForms user’s password.
Search for Forms Customized View 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.
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
125
xPressForms Web Services for Reporting
• Content
• Variable
• Tag
• Operator (Advanced Search only)
• Date, StartDate/EndDate (Advanced Search only)
• Status (Advanced Search only)
Simple Search Criteria
To define simple search criteria, you supply an XML formatted string in the “criteria” parameter 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>
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 “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>
126
xPressForms Web Services for Reporting
<Value>HO</Value><Operator>)</Operator></Name></AdvancedSearch>
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>
SyntaxsearchForForms("String criteria", "String format", "String fields","String username", "String password")
Parameters
criteria : String
The search criteria in XML format. See Simple Search Criteria , page 126 and Advanced SearchCriteria, page 126.
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.
127
xPressForms Web Services for Reporting
username: String
The name of the xPressForms user.
password: String
The password for the xPressForms username.
For example, with the following XML search criteria:
Get Search Field List 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.
Deprecated xPressForms Web ServicesThe getCategory, getCategories, and isAvailable web services have been deprecated.
128
Chapter 8xPression RESTful Services for Batch
xPression provides a set of RESTful services and an embedded daemon process to process your jobrequests. This function enables you to run batch services without the requirement that you installjob 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, deactivate the daemon on that server by followingthe instructions in Configure Servers for RESTful Service Batch Processing, page 149.
Your scheduling application should send requests through the HTTP POST protocol to the providedcalling application RESTful services. The services will query the needed information from thexPression Repository and queue the job for batch processing. When sending requests through theHTTP POST protocol to the provided calling application, you must add the Request.ContentType= "application/xml" command in the C# client.
When queued, xPression sets the job Status to –1, which means the job is “Not Started”. Whenprocessing, xPression selects the job that is queued earlier and with a higher priority. The xPressionServer then “checks out” the job from the queue, ensuring that no other xPression Server can processthe same job. The server that “checks out” the job is the “Owner”. While the job is checked out, thestatus is 0, which means it is “Started”. When the job completes, the Status is 1. xPression sends acompletion event to the owner listener, which reports the event to your batch scheduler application.See more descriptions for job status in Returned Information, page 146.
With xPression RESTful services, jobs can be picked up individually by each thread instead of beingpicked up after the termination of all threads.
The return of the job creation is the RequestID of the job from the T_BATCH_QUEUE table in stringformat. All other returns are in XML format.
Note: The RequestID is also known as the QueueID which refers to the ID of a job in the queue. It isdifferent from the job history ID in 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">
129
xPression RESTful Services for Batch
<UserID>UserID</UserID><Password>Password</Password></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext>
where UserID and Password are your credentials.
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">Job_queueID</Item><ReturnInfo>statistics with details</ReturnInfo></RequestContext></XServicesRequest>
where Job_queueID is the ID of the job in the queue.
Note: The value of ReturnInfomust 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 sample above 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 for the service.
A RequestContext element for General.security contains the following parameters:<RequestContext function="General.security"><Credentials method="UserID and Password"><UserID>UserID</UserID><Password>Password</Password></Credentials><Credentials method="Trusted UserID and Groups"><UserID>UserID</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 the methods are authenticatedby comparing the value you or your xPression administrator supply to the key/values defined inthe BatchRunner.properties file. For xPression Batch web services users, contact your xPressionadministrator if you have problems with authorization. For all the other xPression users, seeAuthorization, page 131 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.
130
xPression RESTful Services for Batch
Authorization
For xPression Batch web services users, contact your xPression administrator if you have problemswith authorization. For all the other xPression users, use the following steps to set up trusted userIDs and groups, and 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.
3. Locate the BatchServiceAuthorizedUsersAndGroups property. If the property does notexist, add the property.
4. Update the property by adding users and groups separated by a colon (;).BatchServiceAuthorizedUsersAndGroups={users};{groups}
5. Save and close the file.
Starting Batch JobsThe Job.start.xml and Job.start elements enable you to start a batch job. The Job.start service(/xFramework/restful/services/job/start) enables you to run a job already defined in xDashboard. TheJob.start.xml service (/xFramework/restful/services/job/start/xml) enables you to create and start anew job by supplying XML inline with the request. Both elements use the same sub-elements andparameters. For examples of these elements in use, see Starting a Batch Job with an Existing JobDefinition, page 132 and Starting a Batch Job with a Job Definition XML File, page 133.
To ensure the service notifies your scheduler when a job is complete, see Service Notification, page 149.
Note: With Job.start.xml and Job.start elements, the priorities of the jobs are set to the default value.See Prioritizing and Starting Jobs, page 134 for how to reset the priorities for your jobs.
The elements contain the following sub-elements:• The Job Element, page 131
• The xPressionPublishJob Element, page 132
• The JobOption Element, page 132
The Job Element
The Job element contains the following 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.
131
xPression RESTful Services for Batch
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.
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. See xPression Batch ProcessingGuide for information about each parameter.
Note: For xPression Batch Web Services Users— xPression web services support all command lineparameters except: -r and -j. Consult your xPression administrator for assistance with setting upand supporting these Job Option parameters.
Starting a Batch Job with an Existing Job Definition
To 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
Service Body:<XServicesRequest><RequestContext function="General.security"><Credentials method="UserID and Password"><UserID>UserID</UserID><Password>Password</Password></Credentials>
<Credentials method="Trusted UserID and Groups"><UserID>UserID</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></Job>
</RequestContext></XServicesRequest>
132
xPression RESTful Services for Batch
Starting a Batch Job with a Job Definition XML File
To create and start a new job by supplying a manually created Job Definition XML file, use thefollowing service URL, supply the user credentials in the General.security element, and supply thejob definition information in Job.start.xml.
For more information about creating a Job Definition file and the parameters in it, see “ManuallyCreating Your Job Definition” in xPression Batch Processing Guide.
Service URL:http://your_server:your_port/xFramework/restful/services/job/start/xml
Service Body:<XServicesRequest><RequestContext function="General.security"><Credentials method="UserID and Password"><UserID>UserID</UserID><Password>Password</Password></Credentials>
<Credentials method="Trusted UserID and Groups"><UserID>UserID</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>
</RequestContext></XServicesRequest>
133
xPression RESTful Services for Batch
Prioritizing and Starting JobsYou can also set priorities for your jobs and start them. xPression uses 1 to 10 as the priority valuesto indicate the job priorities. 1 indicates the highest priority and 10 the lowest. The default priorityvalue of a job is 5.
If multiple jobs have the same priority, xPression processes them in the order that they were queued.The most recent queued job is processed at last.
You can use the following elements when prioritizing and starting your jobs:• Job.priority.reset—You can set the priorities for your queued jobs. This element is used for the
xframework/restful/services/job/priority/reset service.
• Job.priority.start—You can set priorities for your jobs that are already defined in xDashboard andstart the jobs. This element is used for the xframework/restful/services/job/priority/start service.
• Job.priority.start.xml—You can supply a job definition XML file to create or start a job and seta priority for the job. This element is used for the xframework/restful/services/job/priority/start/xml service.
To use the elements, see the following content:• Syntax, page 134
• Returned Information, page 135
Syntax
The Job.priority.start and Job.priority.start.xml elements have the same sub-elements with theJob.start element, except that both Job.priority.start and Job.priority.start.xml have an additionalPriority element to set the priority value.
Supply the user credentials through the General.security element and use the following formats.
To reset the priority values of jobs:<RequestContext function="Job.priority.reset"><Item ref="queueID" newPriority="1">Job_queueID1</Item><Item ref="queueID" newPriority="2">Job_queueID2</Item></RequestContext>
where Job_queueID1,2 are the queueIDs of the jobs. The newPriority parameter specifies thepriority value to override the existing priority. The value of newPrioritymust be 1 to 10.
To start an existing job and set a priority for it:<RequestContext function="Job.priority.start"><Priority>1</Priority><Job version="2.0" name="Job_name"></Job></RequestContext>
where Job_name is the name of the job.
The Priority element is required for the Job.priority.start and Job.priority.start.xml services. Thiselement specifies the priority value to override the existing priority. Its value must be 1 to 10.
134
xPression RESTful Services for Batch
The following code is an example of creating and starting a prioritized job by using a job definitionXML file:<RequestContext function="Job.priority.start.xml"><Priority>1</Priority><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>
</RequestContext>
Returned Information
The returned information for the xframework/restful/services/job/priority/resetservice contains the following data:• returnCode—Indicates the status of the service, including the following values:— –1—The priority is set successfully.
— 0—The job has already started before xPression tries to reset the priority.
— 1—The job has completed before xPression tries to reset the priority.
— 2—The job has completed with failure records before xPression tries to reset the priority.
— 3—The job has failed before xPression tries to reset the priority.
— 5—The job has been terminated before xPression tries to reset the priority.
— 100—The job does not exist.
This data is returned in the following format:<Response service="Job.priority.reset"><item ref="Job_queueID1" returnCode="-1">Job priority reset requestaccepted and processed successfully.</item><item ref="Job_queueID2" returnCode="0">Job priority reset requestcould not be processed - this job has already started.</item><item ref="Job_queueID3" returnCode="1">Job priority reset requestcould not be processed - this job has already completed.</item>
135
xPression RESTful Services for Batch
</Response>
where Job_queueID1,...,3 represent the actual queueIDs of the jobs during your batch processing.
Terminating JobsThe Job.kill element enables you to terminate a job that is running currently. This element is usedfor the xframework/restful/services/job/kill service.
Note: If a pre or post-processing script of a job is running, the job cannot be terminated.
See the following content:• Syntax, page 136
• Returned Information, page 136
Syntax
To terminate a list of jobs, supply the user credentials through the General.security element, and usethe following format:<RequestContext function="Job.kill"><Item ref="queueID">Job_queueID1</item><Item ref="queueID">Job_queueID2</item></RequestContext>
where Job_queueID1,2 are the IDs of the jobs in the queue.
Returned Information
The returned information of this service contains the following data:• returnCode—Indicates the status of the service, including the following values:— 0—The service request is accepted and being processed.
— 1—The job is completed successfully and therefore cannot be terminated.
— 2—The job is completed with failure records and therefore cannot be terminated.
— 3—The job has already failed before the termination.
— 5—The job has been already terminated.
— 100—The job does not exist.
— 101—xPression has removed the job from the queue because the job is not started.
This data is returned in the following format:<Response service="Job.kill"><item ref="Job_queueID1" returnCode="0">Job kill request accepted and processing -check status to confirm kill completion.</item><item ref="Job_queueID2" returnCode="1">Job kill request could not be processed -this job has already completed.</item>
136
xPression RESTful Services for Batch
<item ref="Job_queueID3" returnCode="5">Job kill request could not be processed -this job has already terminated.</item><item ref="Job_queueID4" returnCode="101">Job kill request processed - the job hasbeen removed from the queue.</item>
</Response>
where Job_queueID1,...,4 represent the actual queueIDs of the jobs to be terminated during yourbatch processing.
Deleting Job HistoryThe History.delete element enables you to delete a job from both the queue and Job History inxDashboard. This element is used for the xframework/restful/services/history/deleteservice. See the following content:• Syntax, page 137
• Returned Information, page 137
Syntax
To delete a list of jobs and their history records, supply the user credentials through theGeneral.security element, and use the following format:<RequestContext function="History.delete"><Item ref="queueID">Job_queueID1</item><Item ref="queueID">Job_queueID2</item></RequestContext>
where Job_queueID1,2 are the IDs of the jobs in the queue.
Returned Information
The returned information of this service contains the following data:• result—Indicates the result of the deletion. When the job and its history record are deletedsuccessfully, the value is true. Otherwise, the value is false, which is caused by one of thefollowing reasons:— The job is running and therefore cannot be deleted. You must terminate the job or wait thejob to be completed first.
— The job is not started and therefore cannot be deleted.
— The job does not exist.
This data is returned in the following format:<Response service="History.delete"><item ref="Job_queueID1" result=”true”>Job history delete request processed –the job history has been deleted.</item><item ref="Job_queueID2" result=”false”>Job history delete request could not beprocessed – the job is currently running and must be completed or killed first.</item>
137
xPression RESTful Services for Batch
</Response>
where Job_queueID1,2 represent the actual queueIDs of the jobs to be deleted.
Querying the Job StatusThe job.status element enables you to query the status of a job. See the following topics:• Syntax, page 138
• Returned Information, page 139
• Samples of Returned Information, page 141
Syntax
To query the status of a job, supply the user credentials through the General.security element, and usethe following format<RequestContext function="Job.status"/><Item ref="queueID">Job_queueID</Item><ReturnInfo>statistics with details</ReturnInfo></RequestContext>
where Job_queueID is the ID of the job in the queue. For an example of this element in use, seeReturning the Status of a Particular Job, page 139.
The ReturnInfo element 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.
The ReturnInfo element 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,you will not receive all of the requested information. Ensure the level of information you specify inyour Job Level is greater than or equal to the level you specify in the ReturnInfo element.
When running the Job Status Web Service to return “statistics with errors”, the Web Service does notalways return detailed error information. If the batch process for a customer record fails before thedocument can be assembled, xPression is only able to return the error message, but not the detailsof the error message. In this case, the error occurs before xPression is able to enter the diagnosephase, and therefore no details are returned.
The default value of the ReturnInfo element 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 Samples of Returned Information, page 141.
138
xPression RESTful Services for Batch
Returning the Status of a Particular Job
To 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.
Service URL:http://your_server:your_port/xFramework/restful/services/job/status
Service Body:<XServicesRequest><RequestContext function="General.security"><Credentials method="UserID and Password"><UserID>UserID</UserID><Password>Password</Password></Credentials>
<Credentials method="Trusted UserID and Groups"><UserID>UserID</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext><RequestContext function="Job.status"><Item ref="queueID">4366817659012001047974313115310</Item>
<ReturnInfo>statistics with details</ReturnInfo></RequestContext></XServicesRequest>
Returned Information
Depending on the value of your ReturnInfo element, the Job.status element will return differentlevels of information. All queries will return data in the Common element. If you selected Statisticswith Errors or Statistics with Details in your ReturnInfo element, the Statistics with Details orStatistics with Errors elements will also appear.
Common Data
All queries will return the following information:• JOB—The element for information about the job. There can be one or more JOB elements in 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.
139
xPression RESTful Services for Batch
— queueId—The ID for a job in the queue.
— logPath—When the job is completed, the path and file name of the job log file will be recordedhere.
• 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.
• Priority—The priority of the job.
• State—Identifies the current state of the job.
• ReturnCode—This parameter reports the following values:— -1—The job is not started.
— 0—The job is running.
— 1—The job is completed with success.
— 2—The job is completed with failure records.
— 3—The job has failed.
— 5—The job is terminated.
• Server—The server name and port number.
• ServerIP—The IP address of the server. If the server has multiple IP addresses, xPression liststhem all and separates them with commas.
• 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—The Common element contains the following basic information:
— PublishProfile—The name of the publish profile.
— StartTime—The time/date stamp that identifies when the job started.
— EndTime—The time/date stamp that identifies when the job ended.
— DistributionNumber—The number of records processed through the distribution controllerfor 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 customer recordprocessed by the batch job. Each DATA container element contains the following information:— CustomerKey—The customer key for the record that was processed.
— Bdt—The name of the xPression document that was processed by the job.
140
xPression RESTful Services for Batch
— 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.
— 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.
Samples of Returned Information
This section provides sample responses for job status queries:• Completed Job with “Statistics” Reporting Level, page 141
• Completed Job with “Statistics with Details” Reporting Level, page 142
• Stopped Job with “Statistics with Errors” Reporting Level, page 143
• Job That is Not Started, page 143
• Job That is Still Running, page 144
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><Priority>1</Priority><State>COMPLETED</State><ReturnCode>1</ReturnCode><Server>Server1:8080</Server><ServerIP>10.32.224.99,192.168.50.1,192.168.6.1</ServerIP><Statistics><Common>
141
xPression RESTful Services for Batch
<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>
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><Priority>1</Priority><State>COMPLETED</State><ReturnCode>1</ReturnCode><Server>Server1:8080</Server><ServerIP>10.32.224.99,192.168.50.1,192.168.6.1</ServerIP><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>
142
xPression RESTful Services for Batch
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><Priority>1</Priority><State>STOPPED</State><ReturnCode>3</ReturnCode><Server>Server1:8080</Server><ServerIP>10.32.224.99,192.168.50.1,192.168.6.1</ServerIP><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>
Job That is Not Started
<?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"><Priority>1</Priority><ReturnCode>-1</ReturnCode>
</JOB></Response>
143
xPression RESTful Services for Batch
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="C:\xPression\logs\12122011.log"><Percentage><Step name="1">100.0</Step><Step name="2">100.0</Step>
</Percentage><Priority>1</Priority><State>RUNNING</State><ReturnCode>0</ReturnCode><Server>Server1:8080</Server><ServerIP>10.32.224.99,192.168.50.1,192.168.6.1</ServerIP><Statistics><Common><PublishProfile>PDF to File</PublishProfile><PublishType>2</PublishType><StartTime>1317960478623</StartTime><EndTime /><DistributionNumber /><Error /><ReportingLevel>3</ReportingLevel>
</Common></Statistics>
</JOB></Response>
Returning Queued JobsThe job.queue.all element enables you to filter the results of the query by the status of the job. Thiselement is used for the xFramework/restful/services/jobs/queue/all service. This elementand the General.security element are the only two elements needed for the /jobs/queue/all service.• Syntax, page 144
• Returned Information, page 146
Syntax
To return a list of all queued jobs, use the following format:<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 whichstatus levels you want to return. You can specify multiple status values in this element by separating
144
xPression RESTful Services for Batch
them with only commas. Use the following values for Status to return the correspondinginformation:• -1—Return the jobs that are not started.
• 0—Return the jobs that are “checked out” for processing.
• 1—Return the completed jobs.
• 2—Return the jobs that are completed with failure records.
• 3—Return the failed jobs.
• 5—Return the terminated jobs.
Returning a List of All Queued Jobs
To 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
Service Body:<XServicesRequest><RequestContext function="General.security"><Credentials method="UserID and Password"><UserID>UserID</UserID><Password>Password</Password></Credentials>
<Credentials method="Trusted UserID and Groups"><UserID>UserID</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext><RequestContext function="Job.queue.all"><Filter><Status>-1,0</Status></Filter></RequestContext></XServicesRequest>
145
xPression RESTful Services for Batch
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, including the following values:— –1—The job is not started.
— 0—The job is running.
— 1—The job is completed with success.
— 2—The job is completed with failure records.
— 3—The job has failed.
— 5—The job is terminated.
— RunID—The batch job run ID.
— QueueID—The QueueID is the identifier for a job in the queue.
— Server—The server name and port number.
— ServerIP—The IP address of the server. If the server has multiple IP addresses, xPression liststhem all and separates them with commas.
Note: When the job status is –1, which means the job is “Not Started”, the return values forServer and ServerIP are both null.
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><Server>Server1:8080</Server><ServerIP>10.32.224.99,192.168.50.1,192.168.6.1</ServerIP></JOB><JOB><Name>Job2</Name><Status>-1</Status><RunID>1966463550093566940132071314531</RunID><QueueID>2969915873062562401369071313531</QueueID><Server>null</Server><ServerIP>null</ServerIP></JOB></Response>
Returning 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:
146
xPression RESTful Services for Batch
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>UserID</UserID><Password>Password</Password></Credentials>
<Credentials method="Trusted UserID and Groups"><UserID>UserID</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext></XServicesRequest>
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>
Returning 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
Service Body:<XServicesRequest><RequestContext function="General.security"><Credentials method="UserID and Password"><UserID>UserID</UserID><Password>Password</Password></Credentials>
<Credentials method="Trusted UserID and Groups"><UserID>UserID</UserID></Credentials><ApplicationName>xPression Batch</ApplicationName></RequestContext></XServicesRequest>
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.
147
xPression RESTful Services for Batch
— StartTime—The timestamp identifying when the job started.
— Server—The server name and port number.
— ServerIP—The IP address of the server. If the server has multiple IP addresses, xPression liststhem all and separates them with commas.
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><Server>Server1:8080</Server><ServerIP>10.32.224.99,192.168.50.1,192.168.6.1</ServerIP></JOB></Response>
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 148
• Configure Servers for RESTful Service Batch Processing, page 149
• Service Notification, page 149
Enable xPression for Concurrent Batch Processing
You or your xPression Administrator can configure xPression to support the running of batchjobs concurrently in the batch queue. xPression Batch web services users, 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, add it.
4. Set the value of this parameter to the number of concurrent jobs that you want processed by thiscluster node. For example:ServiceBatchThreadSize=7
5. Save and close the file.
148
xPression RESTful Services for Batch
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, contact your xPression administrator to configure the servers inyour cluster. For all other xPression users, use the following steps. The configuration is accomplishedby setting the EnableBatchServiceProcessor property to “True” or “False”. To activate the scheduleron a particular server, set the value to “True”. To deactivate the scheduler on a particular server, setthe value to “False”. Perform these steps on any server in the cluster that you want enable or disablefor 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.
5. Save and close the file.
Service Notification
If you want this service to notify your batch scheduler when the job is complete, you must 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"/></Resource></Application>
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.
149
xPression RESTful Services for Batch
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.
150
xPression RESTful Services for Batch
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.
151
xPression RESTful Services for Batch
152
Chapter 9xDesign Online Editor Web Service
You can use the methods provided by the xDesign Online Editor Web Service to create, open, and editdocument work items. The WSDL Web Service can be found at:http://server:port/xResponse/services/DocumentRequestService?wsdl
This Web Service contains a list of methods. For detailed information of the methods, refer to xDesignOnline Editor User Guide.
153
xDesign Online Editor Web Service
154
Chapter 10xCatalog
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. There is no end-user interface for that purpose provided withxCatalog.
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
155
xCatalog
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 156
• Browse and Search Pane, page 158
• Document List, page 163
• Document Detail Area, page 163
Menu Bar
The xCatalog menus contain commands for commonly used functions:
• The File Menu, page 156
• The Edit Menu, page 157
• The Help Menu, page 157
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 169.
156
xCatalog
Select this option To
Import Import existing documents that were exported from another xCatalogsystem. For more information, see Importing Documents, page 167.
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 167.
Report Generate a report for selected documents that contains informationabout each document. For more information, see Creating DocumentReports, page 171.
Logout Log out of the xCatalog application. For more information, see LoggingOut, page 173.
The Edit Menu
The Edit menu provides access to functions that enable you to work with the documents in the system.You can view the menu options by clicking the menu. The Edit menu contains the following options.
Select this option To
Add Tag Add a tag to a document. For more information, see Adding Tags toDocuments, page 168.
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 170.
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 169.
The Help Menu
The Help menu provides access to the online Help file for xCatalog, as well as the About dialog box.The Help menu contains the following options.
Select this option To
Contents Opens the xCatalog online Help file where you can find informationabout using xCatalog.
About Opens the About dialog box where you can find information about thespecific version of xCatalog currently installed.
157
xCatalog
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 158
• Search Pane, page 160
• Staging Area Pane, page 162
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 158. 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.
158
xCatalog
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.
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.
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.
159
xCatalog
3. Select the folder into which you want to paste the copied tag or folder, right-click, and select Paste.
Note: Tags in different groups can have the same name, and will not have any relationship to eachother. However, you can’t have two tags in the same group with the same name.
Marking a Folder as Required
Folders can be specified as “required”. If a folder is required, a default tag must be identified. The 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 161.
160
xCatalog
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.
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.
161
xCatalog
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
Effective: 07/01/2009Withdrawn: 08/01/2009
This document was returned because it contains “Homeowner” and Landlord” in the description,and the effective date is within the date range.
The following documents are NOT returned as the result of this search:• BO 01 02 08 09 Landlord Business Form 2
Effective: 08/01/2009Withdrawn: 11/01/2009
This document was not returned because it was not effective during the date range.
• HO 02 44 07 09 Homeowner Policy
Effective: 07/01/2009Withdrawn: 07/31/2009
This document was not returned because it does not contain the word “Landlord” in thedescription.
• CA 05 88 09 08 Commercial Landlord
Effective: 09/01/08Withdrawn: 06/31/2009
This document was not returned because it does not contain either the word “Homeowner” or“Business” in the description.
Staging Area Pane
When documents are imported into xCatalog, they are automatically placed in the Staging Area.When documents are in the Staging Area, you can’t edit the document’s metadata. You can promotedocuments in the Staging Area to a new status.
162
xCatalog
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 169.
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 158 orStaging Area Pane, page 162.
• 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 160.
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 163.
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 164
• Tags Tab, page 164
• Notes Tab, page 164
• Custom Fields Tab, page 164
• Properties Tab, page 165
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 155.
163
xCatalog
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 155 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 168.
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.
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.
164
xCatalog
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 170.
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.
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 166
• Importing and Exporting Documents, page 166
165
xCatalog
• Working with Documents, page 168
• Managing Custom Fields, page 170
• Creating Document Reports, page 171
• Logging Out, page 173
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. You can view the progress and historyrecords of your import and export tasks on the Migration History page in xDashboard. Refer toxDashboard User Guide for more information.
xCatalog documents can be imported and exported through three methods:• Import and Export through the xCatalog application. See Importing Documents, page 167 andExporting Documents, page 167 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.
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.
166
xCatalog
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 160.
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 169.
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.
Exporting Documents
You can export documents into a document package that can then be imported into an xCatalogapplication running on another xPression Server.
167
xCatalog
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 168
• Changing Document Status, page 169
• Deleting Documents, page 169
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 164.
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 155.
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.
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.
168
xCatalog
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 155.
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 155.
To delete a document:1. Select the documents that you want to delete in the document list.
2. From the File menu, select Delete.
169
xCatalog
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 164.
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.
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.
170
xCatalog
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.
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.
171
xCatalog
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" /><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.
172
xCatalog
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.
xCatalog Web ServicexCatalog provides three Web Service methods: getDocumentInfo, searchForDocuments, andgetCatalogInfo. This Web Service is part of the new xPression Web Service API. It conforms to theWS-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 173
• The searchForDocuments Method, page 175
• The getDocumentInfo Method, page 178
The getCatalogInfo Method
This method enables you to get a list of metadata tags for the documents in your xCatalog system.
173
xCatalog
Return Value: This method returns an XML document containing all tags and custom fields inthe xCatalog system.
Syntax
public java.lang.String getCatalogInfo(java.lang.String requestContext)
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Catalog
• your customer application name
For more information, see The requestContext Parameter, page 26.
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"/>
174
xCatalog
</CustomFields></CatalogInfo>
The searchForDocuments Method
This 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
• 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>
175
xCatalog
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></Name></AdvancedSearch>
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>
176
xCatalog
Syntax
public java.lang.String searchForDocuments(java.lang.String requestContext,java.lang.String searchCriteria, java.lang.String format,java.lang.String[] infoToReturn)throws org.apache.axis.AxisFault
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Catalog
• your customer application name
For more information, see The requestContext Parameter, page 26.
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”
177
xCatalog
• “Notes”
• “Custom_Fields”
The getDocumentInfo Method
This 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.
Syntax
public java.lang.String getDocumentInfo(java.lang.String requestContext,java.lang.String[] docNames, java.lang.String format,java.lang.String[] infoToReturn) throws org.apache.axis.AxisFault
Parameters
requestContext : String
An XML document that passes user credentials for authentication. It also passes the name of 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 application name that you use must grant permissions that are appropriate for your request.For this method, the following xPression applications are valid:• xPression Catalog
• your customer application name
For more information, see The requestContext Parameter, page 26.
docNames : String
178
xCatalog
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”
• “Notes”
• “Custom_Fields”
179
xCatalog
180
Chapter 11Deprecated Utilities
Since version 4.0, xPression has introduced a new Web Service API that conforms to the WS-I BasicProfile. The old xFramework Web Service API, Java API, and xAdapter have been deprecated.Although these items will be supported for backward compatibility in the current version, EMCDocument Sciences encourages you to use the new Web Service API as it offers better performance,greater flexibility, and better security.
The following utilities are deprecated:• Deprecated xPression Web Services, page 181
• xPression Java API, page 212
• xPression EAI Adapter, page 250
• The Webtool Utility, page 285
Deprecated xPression Web ServicesWeb 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 Begin
Before 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.
181
Deprecated Utilities
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.
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 Definition
To add the application definition to AppList.xml:1. Locate AppList.xml on your xPression server. You should find it in C:\xPression.
2. Open the file in a text editor.
3. Type the application element between the <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" />
182
Deprecated Utilities
</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>
This sample application definition has workflow and access rights, but no required attributes.
Configuring Your Application with xAdmin
Now that you’ve added your application definition to AppList.xml, it’s time toconfigure it with xAdmin. To configure your application in xAdmin, complete thefollowing steps:1. Associating Attribute Sets with Your Application, page 184
2. Assigning Data Sources to Your Application, page 184
3. Setting Up Access Rights for Your Application, page 184
4. Configuring Workflow for Your Application, page 185 (optional)
183
Deprecated Utilities
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.
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.
184
Deprecated Utilities
Configuring Workflow for Your Application
If your application supports workflow, you can configure your application to assign users assubmitters and approvers. See xAdmin User Guide to assist you in setting up workflow for yourapplication.
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.
185
Deprecated Utilities
Using WebServices with xPresso Packages
The xPressionRequest web service is the only web service that supports xPresso packages. TheDocument Requester, Revise Request and xResponse web services cannot retrieve xPresso packages.
Web Services Processing Diagram
To understand how xPression processes Web service requests, the following functional diagramillustrates the flow of the document requester service.
Figure 1. 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.
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 Service
The 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.
186
Deprecated Utilities
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)
Parameters
documentName : String
Specifies the name of the document you’re retrieving from the content repository.
customerKey : String
An XML string containing the key values for a specific customer record. Customer key values 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="AUTOPAY_KEY">1</Key>
<Key name="LANGUAGE">English</Key>
</Keys>
187
Deprecated Utilities
outputProfileName : String
Specifies the name of the output profile you’re using to retrieve a document.
userName : String
A string specifying the user who has been granted access rights to the category and 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.
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
documentName : String
Specifies the name of the document you’re retrieving from the content repository.
customerKey : String
An XML string containing the key values for a specific customer record. Customer key values arealways stored in the primary table of the data source. The following samples show how the XMLshould be formatted:
<Keys>
188
Deprecated Utilities
<Key name="AUTOPAY_KEY">1</Key>
</Keys>
-or-
<Keys>
<Key name="AUTOPAY_KEY">1</Key>
<Key name="LANGUAGE">English</Key>
</Keys>
customerData : String
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><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.
outputProfileName : String
Specifies the name of the output profile you’re using to retrieve a document.
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
passWord : Byte[]
189
Deprecated Utilities
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.
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. An encrypted password in this methodis not necessary. It is very important that the returned data includes not only the output but thestream name and format so the client can differentiate between the different streams and operate onthem 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.
Syntax
OPStream [] streamArray = requestDocumentsByOutputProfile(documentName, userName,password, outputProfile, customerData, applicationName)
Parameters
documentName : String
The name of the document to publish.
userName : String
The user name that the method will use to validate that the user has permission to publish 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
190
Deprecated Utilities
The output profile the document will be published to.
customerData : String
An XML document containing data required to assemble the document given as input. This 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 Service
The 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
Substitute the server name and server port number where web services is installed.
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 211.
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.
documentName : String
Specifies the name of the document you’re distributing.
outputProfileName : String
191
Deprecated Utilities
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
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.
The xPression Request Web Service
The 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
Substitute the server name and server port number where web services is installed.
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 211. This method supports xDesign documents and all xPressopackages with one exception. If you are producing HTML output, xPresso for InDesign packages arenot supported.
192
Deprecated Utilities
Syntax
publishDocument(DocumentName, UserName, Password, OutputProfile, CustomerData,AppName)
Parameters
documentName: String
Specifies the name of the document you are retrieving from the xPression database.
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
passWord : String
A string specifying the password for the corresponding user name.
outputProfile : String
Specifies the name of the output profile you’re using to distribute the supplied document.
customerData : String
The XML phrase that contains the data defined by XML data source.
appName : String
Specifies the name of the xPression application.
The Preview HTML Method
The preview HTML service enables you to publish an xPresso for Dreamweaver package in 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 211. xDesign documentsand other xPresso packages are not supported with this web service.
Syntax
previewHTML(DocumentName, UserName, Password, CustomerData, AppName)
Parameters
documentName: String
Specifies the name of the document you are retrieving from the xPression database.
193
Deprecated Utilities
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
passWord : String
A string specifying the password for the corresponding user name.
customerData : String
The XML phrase that contains the data defined by XML data source.
appName : String
Specifies the name of the xPression application.
The Preview PDF Method
The preview PDF service enables you to publish an xDesign document or xPresso for Adobe 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 211. 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
Syntax
previewPDF(DocumentName, UserName, Password, CustomerData, AppName)
194
Deprecated Utilities
Parameters
documentName: String
Specifies the name of the document you are retrieving from the xPression database.
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
passWord : String
A string specifying the password for the corresponding user name.
customerData : String
The XML phrase that contains the data defined by XML data source.
appName : String
Specifies the name of the xPression application.
The View Categories for User Method
The view categories for user service returns a list of categories available to the defined user. 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 211.
Syntax
categoryForUser(UserName, Password, AppName)
Parameters
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
passWord : String
A string specifying the password for the corresponding user name.
appName : String
Specifies the name of the xPression application.
195
Deprecated Utilities
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 211.
Syntax
documentsForCategory(UserName, Password, AppName)
Parameters
documentCategory : String
A string specifying the name of the category whose contents you want to view.
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
passWord : String
A string specifying the password for the corresponding user name.
appName : String
Specifies the name of the xPression application.
The View Output Profiles for Document Method
The view output profiles for document service returns a list of output profiles assigned to 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 211. This web service can only be used with xDesign documents.xPresso packages are not supported with this function.
Syntax
outputProfilesForDocument(DocumentName, UserName, Password, AppName)
196
Deprecated Utilities
Parameters
documentName : String
A string specifying the name of the document whose output profiles you want to view.
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
passWord : String
A string specifying the password for the corresponding user name.
appName : String
Specifies the name of the xPression application.
The Get BDT Method
The get BDT web service returns a string that is an assembled list using the xDesign document 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
documentName: String
Specifies the name of the document you are retrieving from the xPression database.
customerData: String
The XML phrase that contains the data defined by XML data source.
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
password : String
A string specifying the password for the corresponding user name.
appName: String
Specifies the name of the xPression application.
197
Deprecated Utilities
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
documentName: String
Specifies the name of the document you are retrieving from the xPression database.
customerData: String
The XML phrase that contains the data defined by XML data source.
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
password : String
A string specifying the password for the corresponding user name.
appName: String
Specifies the name of the xPression application.
The Publish MSOHTML Document Method
The publish MSOHTML document web service returns a string array that is an assembled 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)
198
Deprecated Utilities
Parameters
documentName: String
Specifies the name of the document you are retrieving from the xPression database.
customerData: String
The XML phrase that contains the data defined by XML data source.
msohtml: byte[]
A byte array containing an assembled document.
outputProfileName: String
Specifies the name of the output profile you’re using to retrieve a document.
userName : String
A string specifying the user who has been granted access rights to the category and applicationin xAdmin.
password : String
A string specifying the password for the corresponding user name.
appName: String
Specifies the name of the xPression application.
The Publish And Return Document Method
This method publishes a document to an output profile given as input. If the output profile has 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)
Parameters
documentName : String
199
Deprecated Utilities
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.
outputProfile : String
The output profile the document will be published to.
customerData : String
An XML document containing data required to assemble the document given as input. This 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 Service
The 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.
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
200
Deprecated Utilities
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.
The Retrieve Work In Progress IDs Assigned to a User Method
This method returns a String array of WIP IDs assigned to the xResponse user’s work in 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.
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.
201
Deprecated Utilities
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
AdminUserName : String
The username that the method will use to log in as the xResponse work administrator. This user musthave permission to approve documents in xResponse.
AdminPassword : String
The password that corresponds to the AdminUserName, authenticated by xPression platformsecurity.
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.
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 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
AdminUserName : String
202
Deprecated Utilities
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.
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.
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 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,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
203
Deprecated Utilities
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 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.
wipID : String
The ID of the work in progress.
username : String
The username that the method will use to log in to xResponse.
Password : String
The password that corresponds to the username.
outputProfileName: String
The name of the output profile.
204
Deprecated Utilities
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
The name of the xPression document you want to assign.
AdminUserName : String
The username that the method will use to log in as the xRevise work administrator. This user 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.
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 xRevise.
CustomerData : String
205
Deprecated Utilities
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 User Method
This method returns a String array of WIP IDs assigned to the xRevise user’s work in progress queue.
Note: This method does not authenticate the WIPUserName parameter. If you provide a bad username as input, the method will simply return an empty string array of WIP IDs.
If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAPfault contains a unique identifier error code and accompanying error message with details anddata related to the error.
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
AdminUserName : String
The username that the method will use to log in as the xRevise work administrator. This user musthave permission to approve documents in xRevise.
AdminPassword : String
The password that corresponds to the AdminUserName, authenticated by xPression platformsecurity.
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.
206
Deprecated Utilities
and AssignToUserName is the user name to whom you are assigning the work item.
If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAPfault contains a unique identifier error code and accompanying error message with details anddata related to the error.
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
AdminUserName : String
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
The password that corresponds to the AdminUserName, authenticated by xPression platformsecurity.
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.
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)
207
Deprecated Utilities
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.
username : String
The current username. The user must be the work item owner to use this web service.
password : String
The user’s password.
The Preview Work Item In PDF Method
This method overrides data when previewing a WIP work item.
Syntax
String previewWorkItemInPDF(String wipId, String customerData, String username,String password)
208
Deprecated Utilities
Parameters
wipId : String
The work in progress work item ID.
customerData : String
The data source must use the same schema as the primary data source. If customerData is set as null,this web service works just as previewing the work item as PDF.
username : String
The name of the user. The user must have at least “read” premission to perform the required function.
password : String
The user’s password.
The Update Work Item Primary Data Method
This method provides the ability to edit an xRevise work item once, but publish it many times.
Syntax
String statusMessage = updateWorkItemPrimaryData(AdminUserName, AdminPassword,WorkItemID, CustomerData)
Parameters
This Web service includes the following parameters.
AdminUserName : String
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.
AdminPassword: String
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.
209
Deprecated Utilities
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.
Syntax
deleteWorkItem(AdminUserName, AdminPassword, WorkItemID)
Parameters
This Web service includes the following parameters:
AdminUserName : String
The user name that the method uses to log in as the xRevise work administrator. This user must 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
AdminPassword: String
The password that corresponds to the AdminUserName, authenticated by xPression securityplatform.
WorkItemID
The xRevise WIP ID of the work item that you want to delete.
210
Deprecated Utilities
Returns
Status message stating that the work item was successfully deleted .
The Publish and Return Work Item Method
This method publishes an xRevise work item with the specified output profile.
Syntax
publishAndReturnWorkItem(AdminUserName, AdminPassword, WorkItemID, OutputProfileName)
Parameters
This Web service includes the following parameters:
AdminUserName : String
The user name that the method uses to log in as the xRevise work administrator. This user must 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
AdminPassword: String
The password that corresponds to the AdminUserName, authenticated by xPression securityplatform.
WorkItemID
The xRevise WIP ID of the work item that you want to publish.
OutputProfileName
The name of the output profile that you want to use.
Returns
A byte array of the document content.
Errors
If an error occurs while either the document requester or document composer Web services 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/"
211
Deprecated Utilities
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.
xPression Java APIThis section describes how to write Java classes that encapsulates the most common methods in thehigh-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 Class
In 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
See the following topics:• Dependencies, page 213
• Creating a Simple Properties File, page 213
• Connecting to xPression, page 213
• Retrieving Categories, page 214
• Retrieving Document Names, page 215
• Retrieving a Document, page 215
212
Deprecated Utilities
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. Add the connect method below the variable declarations:
public void connect(String url, String context, String userName, String password,String appName) {
try {
213
Deprecated Utilities
//init the xPression server
facade = new XPressionFacade();
facade.initServerConnection(url, context);//start session
facade.getStartSession(userName, password, appName);//set the temp path for docs
tempPath = getTempPath();}catch (Exception e) {e.printStackTrace();
}}
For JBoss servers, remove the facade.initServerConnection(url, context); line in thecode above.
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 {returnVals = facade.getCategories();
}catch (Exception e) {e.printStackTrace();
}
214
Deprecated Utilities
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;}
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();
215
Deprecated Utilities
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 Application
In 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 213
• Initial Setup, page 217
• Creating Standard Header and Footer Pages, page 217
• Presenting a List of Categories, page 218
• Presenting a List of Documents, page 220
• Presenting Input Fields, page 220
• Generating a PDF Quote, page 222
• Summary, page 226
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.
216
Deprecated Utilities
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.
On your development machine, create a folder structure that resembles the following image, whichshows 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.
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 226.
Quote_Gen.war\WEB-INF Contains files describing your application. For more information, seeDeploying an xPression Application, page 226.
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.
217
Deprecated Utilities
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><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" %><%
218
Deprecated Utilities
//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.
• 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 2. The resulting page should look like this when launched in your browser.
219
Deprecated Utilities
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.
• 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.
Figure 3. 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" %><%
220
Deprecated Utilities
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 {%>
<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>
221
Deprecated Utilities
<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.
Figure 4. 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(">");
222
Deprecated Utilities
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";
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");
223
Deprecated Utilities
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>";}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>";
224
Deprecated Utilities
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();}%>
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.
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>
225
Deprecated Utilities
<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.
Figure 5. 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 Application
In 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 227
• J2EE Web Application Overview, page 227
• J2EE Enterprise JavaBeans Overview, page 227
• J2EE Utility Classes Overview, page 228
• Web Application Archive Construction, page 228
226
Deprecated Utilities
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 227. We’ll discuss each of the applications at a high level before weget into the details of assembling the Quote Generator application.
Figure 6. The following image shows the J2EE application assembly.
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.
227
Deprecated Utilities
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.
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.
228
Deprecated Utilities
• 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 packageso 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 Reference
The 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 212. Each method isformatted as follows:
Method Name
Descriptive paragraph.
Syntax
Object.methodName parm1, parm2
229
Deprecated Utilities
Parameters
Parm1 : Data Type
Descriptive text.
parm2 : Data Type
Descriptive text.
Sample
public class CodeSample {public void sampleMethod() {try {//sample code here}catch {//sample error code here}}}
The XPressionFacade Class
The XPressionFacade class contains the all the methods you’ll need for your xFramework applications.For information about exceptions that each method generates, see xPression Facade Exceptions, page248. This section includes these methods: getAppName, getBusinessDocuments, getCategories,getDocumentPackedMSOHTML, getDocmentPackedMSOHTML (overloaded), getDocumentPDF,getDocumentPDF (overloaded), getHaveStartSession, getOutputProfiles, getSchema, getStartSession,initServerConnnection, setStatus, publishDocument, and publishDocument (overloaded).
For WebSphere and WebLogic servers, do the following steps:
To ensure that XPressionFacade works properly:1. Create a folder named xPression on the computer where XPressionFacade is running.
2. Copy the contentRepository.properties and xPressionHome.properties files fromthe xPression Server that xPressionFacade is connected to, and paste them to the \xPressionfolder that you created in Step 1.
3. Open the xPressionHome.properties in your local \xPression folder, and set thexPressionHome property to the path of the \xPression folder. For example:xPressionHome=C:\xPression
230
Deprecated Utilities
4. Use either of the following ways to add the xPressionHome property to the class path onthe client computer:• Create an environment variable named xPressionHome on the system whereXPressionFacade is running.
• Add the xPressionHome system property by using the -D option when running theXPressionFacade application. For example:java -DxPressionHome="c:\xPression"
Running XPressionFacade with JBoss Server
If you use JBoss as your xPression server, to run XPressionFacade from a client, do the following steps:
1. Copy the JBossHome\bin\client\jboss-ejb-client.properties file on your xPressionserver.
2. Paste the jboss-ejb-client.properties file to Quote_Gen.war\WEB-INF\classes onyour client computer. See Initial Setup, page 217 for the location of this folder.
3. Open the jboss-ejb-client.properties file for editing, and update theremote.connection.default.host and remote.connection.default.port propertiesto your xPression server name or IP address and port number.
4. Add the following system properties to JVM when running the client to call XPressionFacade:• xPRSApplicationName—Set the same value as in xPressionHome\contentRepositories
.properties
• APPSERVER_VERSION—Set the value to JBoss 7.x
To add the properties, use one of the following ways:• If you are running the client via executing a class file, you can add system properties using the“–D” JVM argument. For example:java -DxPRSApplicationName=xPression -D"APPSERVER_VERSION=JBoss 7.x"
• If you are running the client via a web application on a JBoss 7.x or EAP 6.x server, you canadd the properties to your standalone configuration, for example, standalone.xml. Addthe following lines in the <system-properties> element:<system-proerties>...<property name="xPRSApplicationName" value="xPression"/><property name="APPSERVER_VERSION" value="JBoss 7.x"/>...</system-proerties>
• If you are running the client via a web application on a non-JBoss server, contact your serveradministrator for how to add system properties to JVM.
5. If you are running the client via executing a class file, ensure that you add thejboss-client.jar to the class path.
231
Deprecated Utilities
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 241.
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.
Syntax
docs[] = XPressionFacade.getBusinessDocuments(categoryName);
Parameters
categoryName : String
An input parameter containing the category name whose documents you’re retrieving.
232
Deprecated Utilities
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 {returnVals = facade.getCategories();}catch {System.out.println("An error occurred getting the categories.");}return returnVals;}}
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 on
233
Deprecated Utilities
unpacking MSOHTML, see The Webtool Utility, page 285. You must then convert the byte array to alogical file and unpack (decompress) the file.
Syntax
document[] = XPressionFacade.getDocumentPackedMSOHTML(documentName, customerKey);
Parameters
documentName : String
An input parameter containing the document name you’re assembling.
customerKey : String
An XML string containing the key values for a specific customer record. Customer key values 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;}}
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.
234
Deprecated Utilities
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 The Webtool Utility, page 285. Calling this overloaded method is perfectwhen you want to pass XML customer data that you generate on the fly in transactional applications.You must then convert the byte array to a logical file and unpack (decompress) the file.
Syntax
document[] = XPressionFacade.getDocumentPackedMSOHTML(documentName, customerData,xmlDataSourceName);
Parameters
documentName : String
An input parameter containing the document name you’re assembling.
customerData : String
A string containing a customer record in XML format. The XML stream can contain a single 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>
xmlDataSourceName : String
An input parameter containing the name of an XML data source you’re using to assemble thedocument.
235
Deprecated Utilities
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;}}
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
documentName : String
An input parameter containing the document name you’re assembling.
customerKey : String
An XML string containing the key values for a specific customer record. Customer key values 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="AUTOPAY_KEY">1</Key><Key name="LANGUAGE">English</Key></Keys>
236
Deprecated Utilities
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;}}
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.
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
documentName : String
An input parameter containing the document name you’re assembling.
customerData : String
A string containing a customer record in XML format. The XML stream can contain a single 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
237
Deprecated Utilities
</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>
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[] 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();
238
Deprecated Utilities
try {returnVal = facade.getHaveStartSession();}catch {System.out.println("An error occurred determining if your xPression session isstarted.");}return returnVal;}}
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;}}
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.
239
Deprecated Utilities
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);
Parameters
userName : String
An input parameter containing the user name.
password : String
An input parameter containing the user password.
appName : String
240
Deprecated Utilities
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.
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 {
241
Deprecated Utilities
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);}}
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);
242
Deprecated Utilities
Parameters
documentName : String
An input parameter containing the document name you’re publishing.
customerKey : String
An XML string containing the key values for a specific customer record. Customer key values 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="AUTOPAY_KEY">1</Key><Key name="LANGUAGE">English</Key></Keys>
outputProfileName : String
An input parameter containing the output profile name. To retrieve output profiles, use thegetOutputProfiles, page 239 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 {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.");}}}
243
Deprecated Utilities
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.
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
documentName : String
An input parameter containing the document name you’re publishing.
customerData : String
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>
xmlDataSourceName : String
An input parameter containing the name of an XML data source you’re using to publish the document.
244
Deprecated Utilities
outputProfileName : String
An input parameter containing the output profile name. To retrieve output profiles, use thegetOutputProfiles, page 239 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.write(documents[i].getDocumentData());
fos.close();
}}catch {System.out.println("An error occurred publishing the document.");}}
Ending a Session
Once 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()
245
Deprecated Utilities
Parameters
This method takes no parameters.
The XPressionDocument Class
When 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();
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.write(documents[i].getDocumentData());
fos.close();
}}catch {System.out.println("An error occurred publishing the document.");}}}
246
Deprecated Utilities
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\\" +documents[i].getDocumentName() + "." + documents[i].getDocumentFormat());
fos.write(documents[i].getDocumentData());fos.close();
}}catch {System.out.println("An error occurred publishing the document.");}}}
getDocumentName
This method returns the published document name.
Syntax
documentName = XPressionDocument.getDocumentName();
Sample
import com.docscience.xpression.framework.XPressionFacade;
247
Deprecated Utilities
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.write(documents[i].getDocumentData());
fos.close();
}}catch {System.out.println("An error occurred publishing the document.");}}}
xPression Facade Exceptions
When 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.
248
Deprecated Utilities
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.
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.
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.
249
Deprecated Utilities
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.
xPression EAI AdapterThis section covers a component of the deprecated Web Services model.
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.
250
Deprecated Utilities
xAdapter Architectural Overview
The xAdapter is organized around three core components: Listener Technology, Request Processor,and xPression Batch Wrapper.
Figure 7. 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).
251
Deprecated Utilities
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 Architecture
The 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 8. The xAdapter, deployed on a WebSphere cluster of two Windows servers, would look like thefollowing image.
xAdapter Components
The xAdapter supports these seven processing requests:• Publish a document to an output profile. For more information, see Publish Document WebService Method, page 253.
• Preview a document in PDF format. For more information, see Preview PDFWeb Service Method,page 254.
• Submit a document to be published in batch. For more information, see Post For Batch WebService Method, page 255.
• Find the document categories to which the user is eligible to publish. For more information, seeCategories For User Web Service Method, page 255.
• Find documents within a document category. For more information, see Documents For CategoryWeb Service Method, page 256.
• Find output profiles configured for use for a particular document. For more information, seeOutput Profiles For Document Web Service Method, page 256.
• Find variables used in a document. For more information, see Variables for Document WebService Method, page 257.
252
Deprecated Utilities
The xAdapter supports three methods of system-to-system integration with XML documents asthe data transfer medium:• Web Services Integration, page 253
• JMS-Based Messaging Mechanism, page 257
• XML File Export for Batch Execution, page 270
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
253
Deprecated Utilities
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.
Parameter Description Type
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.
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.
254
Deprecated Utilities
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
This Web service method accepts the following input parameters.
Parameter Description Type
BatchDocumentType The type of batch document to be processed by the adapter,configured in the adapter’s configuration properties file.
String
UserName The name of the user to log into xPression. String
Password The password that corresponds to the UserName,authenticated by xPression platform security.
String
CustomerData The XML document for the xPression XML format 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.
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.
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
This Web service method accepts the following input parameters.
Parameter Description Type
UserName The name of the user to log into xPression. String
Password The password that corresponds to the UserName,authenticated by xPression platform security.
String
The Web service method returns a String array as an output parameter should the method 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.
255
Deprecated Utilities
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
This Web service method accepts the following parameters.
Parameter Description Type
DocumentCategory The xPression category that contains the document to publish. String
UserName The name of the user to log on to xPression. This usermust have permission to publish documents in theDocumentCategory selected or the request will fail.
String
Password The password that corresponds to the UserName,authenticated by xPression platform security.
String
The Web service method returns a String array as an output parameter when the method 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.
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
This Web service method accepts the following parameters.
Parameter Description Type
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).
256
Deprecated Utilities
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
This Web service method accepts the following parameters.
Parameter Description Type
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 datasource 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. In
257
Deprecated Utilities
WebSphere, 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).
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
258
Deprecated Utilities
Parameter Description Required?
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><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>
259
Deprecated Utilities
<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
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.
260
Deprecated Utilities
Output Field Name Description Output Conditions
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.
The field is only present when therequest cannot be processed
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>
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.
261
Deprecated Utilities
Parameter Description Required?
RequestType The type of request this XML message represents.The value for this message must be Preview PDF.
Y
DocumentName The name of the xPression document to publish. Y
UserName The name of the user to log into xPression. Thisuser must have permission to publish the documentselected or the request will fail.
Y
Password The password that corresponds to the UserName,authenticated by xPression platform security.
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
CustomerData The XML document for the xPression XML formatdata source.
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><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>
262
Deprecated Utilities
</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.
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.
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
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 customerdata record can be properlyprocessed to obtain this information.
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.
The field is only present when therequest cannot be processed
If the Preview PDF request is not completed successfully, an example XML output message wouldlook like this:
263
Deprecated Utilities
<?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.
Parameter Description Required?
RequestType The type of request this XML message represents.The value for this message must be Post for Batch.
Y
BatchDocument-Type The type of batch document to be processed by theadapter, configured in the adapter’s configurationproperties file.
Y
UserName The name of the user to log into xPression. Y
Password The password that corresponds to the UserName,authenticated by xPression platform security.
Y
ReturnStatusMessage A flag which tells the adapter message 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
CustomerData The XML document for the xPression XML formatdata source.
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>
264
Deprecated Utilities
<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><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.
Output Field Name Description Output Conditions
RequestType The type of request this XML messagerepresents. The value for this message mustbe Publish Document.
This field is present in all outputmessages as long as the inputmessage is properly formed.
BatchDocument-Type The type of batch document to be processedby the adapter, configured in the adapter’sconfiguration properties file.
This field is present in all outputmessages as long as the inputmessage is properly formed.
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.
265
Deprecated Utilities
Output Field Name Description Output Conditions
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.
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 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.
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 error codeand any pertinent data involved in the error.
The field is only present when therequest cannot be processed
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>
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>
266
Deprecated Utilities
<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>
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>
267
Deprecated Utilities
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.
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.
268
Deprecated Utilities
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,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;
269
Deprecated Utilities
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.
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.
270
Deprecated Utilities
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 255.
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.
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.
271
Deprecated Utilities
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).
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
272
Deprecated Utilities
“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 asthe 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 Information
The xAdapter needs the following information as part of its configuration to work properly.
Parameter Definition
xPressionServerURL The URL the xAdapter uses to connect xPression Server through the 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.
273
Deprecated Utilities
Parameter Definition
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 270.
Here’s an example:xPressionServerURL=iiop://localhost:2809xPressionApplicationName=xPression AdapterPreviewPDFOutputProfile=PDF Return to ApplicationxPressionBatchRunnerScriptDir=C:\\WebSphere\\AppServer\\installedApps\\xPression.ear\\
Creating the Adapter Application
After 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 Definition
To add the application definition to AppList.xml:1. Locate AppList.xml on your xPression server and open it in a text editor. The default location is
C:\xPression, but may differ on your server.
2. Type the application element between the <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">
274
Deprecated Utilities
<Access name="Read" /><Access name="Write" /><Access name="Approve" /></AccessRights>
4. Type the closing </Application> element at the bottom of your application definition.
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></Application></AppList>
Configuring Your Application with xAdmin
Now that you’ve added your application definition to AppList.xml, it’s time to configure it withxAdmin.
Associating Attribute Sets with Your Application
Before you can configure categories, data sources, access rights, and workflow for your application,you must first associate one or more attribute sets with your application.
To associate attributes with your application:1. Open your browser and point to http://servername:portnum/xAdmin. Replace servername and
portnum with your server name and port number.
2. Click Category Management, then Attribute Sets.
3. Click an attribute set that you want to associate with your application. You can also create 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.
Assigning Categories to Your Application
To assign categories to your application:1. In xAdmin, click Category Management, then Categories.
2. Select a category you want to assign to your application.
275
Deprecated Utilities
3. Select your application from the list.
4. Click Save. The category is now assigned to your application.
5. To assign more categories to your application, repeat this procedure.
Assigning Data Sources to Your Application
To assign data sources to your application:1. Select a category you’ve already assigned to your application.
2. Click the Data Sources tab.
3. Select a data source group from the list.
4. Click Set Application.
5. Select your application from the drop-down list.
6. Select the data sources you want to assign to your application and click Add.
7. Select a default data source for your application from the drop-down list and click Save.
8. To assign additional data sources to your application, repeat this procedure.
Setting Up Access Rights for Your Application
To set up access rights for your application:1. Click the Access Rights tab for a category you’ve assigned to your application.
2. Click View/change for your application, then click Add.
3. Select users from the list of available users and click Add.
4. Click Save. The users you selected for the category now have access to your application.
5. When the list of users reappears, select the access levels for each user and click Save.
Configure Your Batch ScriptsTo configure xPression Batch Runner:1. Create a directory to house your xPression Batch scripts. For example: C:\xPressionAdapter
\batchScripts.
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.
276
Deprecated Utilities
Figure 9. 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 Installation
Open a Web browser and type http://<server:port>/xPressionAdapter/webServices/xPressionRequest.jws?wsdl to retrieve the WSDL of the Web service.
Figure 10. 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.
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.
277
Deprecated Utilities
Figure 11. The following image shows testing the JMS.
3. The following page appears.
Figure 12. 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 Files
Three XML files are used:• Publish Document, page 278
• Preview with PDF, page 279
• Post for Batch, page 280
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>
278
Deprecated Utilities
<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>
Preview with PDF
<?xml version="1.0" encoding="UTF-8" ?><AdapterRequest>
<RequestType>Preview PDF</RequestType><DocumentName>Automatic Payment Letter</DocumentName>
<UserName>jpc0999</UserName>
<Password>JoonP123</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>
279
Deprecated Utilities
<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>
Post for Batch
<?xml version="1.0" encoding="UTF-8" ?><AdapterRequest>
<RequestType>Post For Batch</RequestType>
<BatchDocumentType>AutomaticPaymentLetter</BatchDocumentType>
<UserName>jpc0999</UserName>
<Password>JoonP123</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>
280
Deprecated Utilities
<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>
Error Messages
All 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.
281
Deprecated Utilities
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.
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.
282
Deprecated Utilities
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 cannot 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.
5005 Category {0} not found.
5006 User cannot 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 cannot access the specified category.
5011 User {0} is not authorized to access document {1}.
283
Deprecated Utilities
Error Number Error Description
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.
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
Error Number Error Description
1001 xPression Server log on.
284
Deprecated Utilities
Error Number Error Description
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.
The Webtool UtilityThis section covers the a component of the deprecated Web Services model.
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.
285
Deprecated Utilities
Registering Webtool.dll
Webtool.dll has a dependency on the uamerge.dll file supplied by EMC Document Sciences. Whenyou register Webtool.dll, ensure that uamerge.dll has been copied to:• <xPressionHome>/Drivers/
Or• %SystemRoot%/system32/
The Encryption Utility
The encryption utility enables you to encrypt and decrypt user passwords you pass to xPression.When using the high- or low-level API, you’re not required to encrypt passwords, but we recommendit for security purposes. However, the Deprecated xPression Web Services, page 181 methods dorequire password encryption. This section includes these methods: encrypt and decrypt.
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;}
286
Deprecated Utilities
}
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
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;
287
Deprecated Utilities
}}
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
'destroy objectSet webTool = Nothing
End Function
The Pack Utility
The 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.
pack
Java: MSOPacker.pack(folderName, mainHTMLFileName, packedMSOHTMLFileName);Visual Basic: WEBTOOLLib.pack(folderName, mainHTMLFileName, packedMSOHTMLFileName)
Syntax
This method compresses, or packs, MSOHTML content, which then enables you to re-save 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.
288
Deprecated Utilities
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) {
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
'destroy objectSet webTool = Nothing
End Sub
unpack
This method decompresses, or unpacks, MSOHTML content, which then enables you to displayit in an editor like Microsoft Word.
289
Deprecated Utilities
Syntax
Java: MSOPacker.unpack(folderName, packedMSOHTMLFileName, mainHTMLFileName);Visual Basic: WEBTOOLLib.unpack(folderName, packedMSOHTMLFileName, mainHTMLFileName)
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
290
Deprecated Utilities
'unpack filewebTool.Unpack "", packedFile, unpackedFile
'destroy objectSet webTool = Nothing
End Sub
291
Deprecated Utilities
292
Appendix A
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>
293
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.
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.
294
The AppList DTD
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 withWrite 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>
295
The AppList DTD
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.
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
296
The AppList DTD
Attribute Definition
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"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=""/>
297
The AppList DTD
</RequiredAttributes></Application></AppList>
298