Programmers Reference Part1 6.2.8 RevA

Agile Business Process
Platform (ABPP) 3
Programmer’s Reference - Part 1
Revision A
Version 6.2.8
Copyright Information
One i2 Place
11701 Luna Rd.
Dallas, TX 75234 USA
i2® Agile Business Process Platform (ABPP) 3

Programmer’s Reference - Part 1Revision A
Version 6.2.8, January 2008
Copyright © 2000-2008 i2 Technologies US, Inc. All Rights Reserved.
This notice is intended as a precaution against inadvertent publication and does not imply any waiver of
confidentiality. Information in this document is subject to change without notice. No part of this document may be
reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying,
recording, or information storage or retrieval systems, for any purpose without the express written permission of i2
Technologies US, Inc.
The software and/or database described in this document are furnished under a license agreement or nondisclosure
agreement. It is against the law to copy the software onto any medium except as specifically allowed in the license or
nondisclosure agreement. If software or documentation is to be used by the federal government, the following
statement is applicable: In accordance with FAR 52.227-19 Commercial Computer Software -- Restricted
Rights, the following applies: This software is Unpublished--rights reserved under the copyright laws of the
United States.
The text and drawings set forth in this document are the exclusive property of i2 Technologies US, Inc. Unless
otherwise noted, all names of companies, products, street addresses, and persons contained in the scenarios are
designed solely to document the use of i2 Technologies US, Inc. products.
The brand names and product names used in this document are the trademarks, registered trademarks, service marks,
or trade names of their respective owners. i2 Technologies US, Inc. is not associated with any product or vendor
mentioned in this publication unless otherwise noted.
The following registered trademarks are the property of i2 Technologies US, Inc. and its authorized affiliates: i2; i2
& Design; i2 User Group & Design; Planet; and Freightmatrix.
This product may be protected by one or more of the following patents:

Europe Patent No. 0861474 (E) Taiwan Patent No. 140308 Taiwan Patent No. 182974
German Patent No. 10195871 Taiwan Patent No. 146038 Taiwan Patent No. 191262
German Patent No. 69508931.5 Taiwan Patent No. 154327 Taiwan Patent No. 196235
Taiwan Patent No. 80326 Taiwan Patent No. 158220 Taiwan Patent No. 222584
01/16/08
Taiwan Patent No. 241800 U. S. Patent No. 6,374,249 U. S. Patent No. 6,988,104
Taiwan Patent No. 258090 U. S. Patent No. 6,442,528 U .S. Patent No. 7,024,265
U. S. Patent No. 5,630,123 U. S. Patent No. 6,490,566 U. S. Patent No. 7,039,602
U. S. Patent No. 6,374,227 U. S. Patent No. 6,983,421
Contents
Preface........................................................................................................ xvii
1 Introduction.................................................................................................... 1
Overview ...................................................................................................................................................1
Elements of ABPP Framework .................................................................................................................3
X-Server .............................................................................................................................................4
X-Service............................................................................................................................................4
X-Documents .....................................................................................................................................5
X-Rules...............................................................................................................................................5
X-Workflow .......................................................................................................................................6
How to Use This Guide .............................................................................................................................6
2 Modeling Concepts ....................................................................................... 7

Definitions .................................................................................................................................................7
Document ...........................................................................................................................................7
Property .......................................................................................................................................8
Key ..............................................................................................................................................8
Link .............................................................................................................................................9
Facets ........................................................................................................................................11
Dictionary.........................................................................................................................................17
Model Sets & Model Instances ........................................................................................................18
Model Extension and Inheritance............................................................................................................19
Model Dependancy and Composite View...............................................................................................21
Model Data Types vs Database Data Types............................................................................................23
3 X-Documents................................................................................................ 25
Introduction .............................................................................................................................................26
Document Identifiers ...............................................................................................................................27
Surrogate Key ..........................................................................................................................................28
Document Index ......................................................................................................................................28
Document Properties ...............................................................................................................................29
Agile Business Process Platform 3 Programmers Reference Revision A v

Contents
boolean............................................................................................................................................. 29
string ................................................................................................................................................ 30
encryptedString................................................................................................................................ 30
int ..................................................................................................................................................... 30
float .................................................................................................................................................. 30
double .............................................................................................................................................. 31
BigDecimal ...................................................................................................................................... 31
date................................................................................................................................................... 31
datetime............................................................................................................................................ 31
time .................................................................................................................................................. 31
timestamp......................................................................................................................................... 31
Default Values ........................................................................................................................................ 32
Document Constraints............................................................................................................................. 32
Document Links...................................................................................................................................... 33
Referential Integrity Constraints............................................................................................................. 35
Overlay Documents ................................................................................................................................ 36
Flex Properties ........................................................................................................................................ 37
Pre-defined Flex Properties ............................................................................................................. 37
Dynamic Flex Properties ................................................................................................................. 38
4 X-Commands ................................................................................................41
System Commands ................................................................................................................................. 42
GET_RESOURCE_STATS ............................................................................................................ 43
GET_BUILD_INFO ........................................................................................................................ 44
ENABLE/DISABLE/SET_LOG_LEVELS .................................................................................... 44
GET_LOG_LEVELS ...................................................................................................................... 46
CLEAR_ALL_LOGS ...................................................................................................................... 47
DROP_CACHE ............................................................................................................................... 47
BROADCAST ................................................................................................................................. 48
SHUT_DOWN ................................................................................................................................ 49
SET_XSERVICE_PARAM ............................................................................................................ 50
User Commands...................................................................................................................................... 50
Definition......................................................................................................................................... 50
request_descriptor..................................................................................................................... 51
Implementation ................................................................................................................................ 53
Inline the implementation along with the command definition................................................ 54
Provide the implementation separate from the definition ........................................................ 54
Invoking Commands............................................................................................................................... 55
Command Envelope......................................................................................................................... 56
REQUESTS.............................................................................................................................. 56
Utilities for Posting Commands ...................................................................................................... 59
................................................................................................................................................................ 64
5 X-Rules ..........................................................................................................65
Introduction............................................................................................................................................. 65
Variables and Expressions ...................................................................................................................... 67
vi Agile Business Process Platform 3 Programmers Reference Revision A

Contents
LhsExpression ..................................................................................................................................67
RhsExpression ..................................................................................................................................68
Variable Types.........................................................................................................................................69
Local Variables ................................................................................................................................69
Service Variables..............................................................................................................................69
X-Rule Types...........................................................................................................................................69
DEFINE_METHOD.........................................................................................................................69
DEFINE_LISTENER.......................................................................................................................74
DEFINE_IMPLEMENTATION......................................................................................................75
DEFINE_PRE_CREATE.................................................................................................................77
DEFINE_POST_CREATE ..............................................................................................................79
DEFINE_PRE_MODIFY.................................................................................................................80
DEFINE_POST_MODIFY ..............................................................................................................81
DEFINE_INIT ................................................................................................................................81
DEFINE_PRE_SHUTDOWN .........................................................................................................82
DEFINE_POST_SHUTDOWN .......................................................................................................83
X-Rule Components ................................................................................................................................84
Exceptions thrown by Components within X-rules .........................................................................84
X-Rule Components Syntax Notations ............................................................................................85
Condition X-Rule Components ...............................................................................................................87
Simple Condition..............................................................................................................................87
Compound Condition .......................................................................................................................88
Action X-Rule Components ....................................................................................................................88
Core Components.............................................................................................................................89
SET............................................................................................................................................89
PRINT/PRINTLN .....................................................................................................................90
LOG ..........................................................................................................................................91
IF_TEST-THEN-ELSE.............................................................................................................91
IF-THEN-ELSE ........................................................................................................................92
CHOOSE-WHEN-OTHERWISE .............................................................................................94
FOR_EACH-BREAK-CONTINUE .........................................................................................95
REPEAT....................................................................................................................................96
WHILE......................................................................................................................................98
EXIT..........................................................................................................................................99
EXCEPTION ............................................................................................................................99
TRY-CATCH-THROW..........................................................................................................101
HANDLE_SYSTEM_EXCEPTION ......................................................................................103
Command Components ..................................................................................................................104
Data Access Components...............................................................................................................106
CREATE_DOCUMENT_ID ..................................................................................................106
ADD_DOCUMENT ...............................................................................................................106
Query Condition......................................................................................................................109
REMOVE_DOCUMENT .......................................................................................................110
MODIFY_DOCUMENT ........................................................................................................111
SAVE ......................................................................................................................................112
GET_DOCUMENT ................................................................................................................113
Agile Business Process Platform 3 Programmers Reference Revision A vii

Contents
Expression .............................................................................................................................. 116

ORDER_BY ........................................................................................................................... 118
GROUP_BY ........................................................................................................................... 119
QUERY_DOCUMENT_LINK .............................................................................................. 120
NOT_EXISTS_QDL .............................................................................................................. 121
SELECT + QUERY_DOCUMENT_LINK ........................................................................... 123
FETCH_DOCUMENT_LINK ............................................................................................... 124
SQL_FN ................................................................................................................................. 125
Scalar Functions ..................................................................................................................... 128
GET_DOC_CHUNKED ........................................................................................................ 129
PROCESS_GET_DOCUMENT ............................................................................................ 130
EXEC_SQL_QUERY ............................................................................................................ 133
EXEC_LOGICAL_SQL_QUERY......................................................................................... 135
EXEC_SQL_DML ................................................................................................................. 138
EXEC_LOGICAL_SQL_DML.............................................................................................. 139
EXEC_BATCH_SQL_DML.................................................................................................. 140
EXEC_SQL_DDL.................................................................................................................. 141
EXEC_PROC ......................................................................................................................... 141
PROCESS_EXECUTE_SQL_QUERY ................................................................................. 142
XML-Manipulation Components .................................................................................................. 144
SET_PROPS........................................................................................................................... 144
REMOVE_ATTRIBUTE ....................................................................................................... 144
TO_DOCVAR........................................................................................................................ 145
TO_XML................................................................................................................................ 148
APPEND_TO_XML .............................................................................................................. 149
MAKE_INSTANCE_DOCUMENT...................................................................................... 151
SET_NAME ........................................................................................................................... 152
SET_TEXT............................................................................................................................. 152
GET_TEXT ............................................................................................................................ 153
SET_CHILD........................................................................................................................... 153
ADD_CHILDREN ................................................................................................................. 154
APPEND_CHILDREN .......................................................................................................... 157
REMOVE_CHILDREN ......................................................................................................... 158
REMOVE_NODES................................................................................................................ 159
DELETE_ALL_CHILDREN ................................................................................................. 160
COLLATE_XML ................................................................................................................... 161
MAP_CREATE...................................................................................................................... 163
MAP_PUT_ALL .................................................................................................................... 165
MAP_REMOVE..................................................................................................................... 166
MAP_CLEAR ........................................................................................................................ 166
GROUP_DOCS...................................................................................................................... 167
MERGE_DOC........................................................................................................................ 169
MERGE_ERRORS_DOC ...................................................................................................... 171
STRING_TO_XML ............................................................................................................... 173
XML_TO_STRING ............................................................................................................... 173
CLONE_XML........................................................................................................................ 174
viii Agile Business Process Platform 3 Programmers Reference Revision A

Contents
SORT_DOCS..........................................................................................................................174
SORT ......................................................................................................................................178
SET_NAMESPACE ...............................................................................................................179
REMOVE_NAMESPACES ...................................................................................................180
User-Interface Related Components ..............................................................................................181
SET_SESSION .......................................................................................................................181
GET_SESSION.......................................................................................................................181
FORM_SEARCH_FILTER ....................................................................................................181
FORM_GET............................................................................................................................184
FORM_REMOVE ..................................................................................................................185
FORM_UPDATE....................................................................................................................187
PAGINATE_LINES ...............................................................................................................189
TAG_ERRORS .......................................................................................................................190
DROP_DOWN_OPTIONS.....................................................................................................192
CREATE_URL .......................................................................................................................193
SET_REDIRECT_URL ..........................................................................................................194
Utility Components ........................................................................................................................194
EXECUTE_SHELL_COMMAND.........................................................................................194
EXEC_INFORMATICA ........................................................................................................196
LOAD_XML_FILE ................................................................................................................197
STORE_XML_FILE...............................................................................................................197
PRINT_TO_FILE ...................................................................................................................198
GET_CURRENT_TIME ........................................................................................................199
SET_LOGICAL_DATE .........................................................................................................199
DO_TRANSACTION.............................................................................................................199
REFRESH_FROM_CACHE ..................................................................................................200
NATIVE_FUNCTION............................................................................................................201
INSTANCE_METHOD..........................................................................................................201
POST .......................................................................................................................................202
POST_STRING ......................................................................................................................202
SLEEP.....................................................................................................................................202
TIMING_MARKER ...............................................................................................................203
Framework Specification Components ..........................................................................................204
6 X-Path ......................................................................................................... 205

Introduction ...........................................................................................................................................205
X-Path Basics ........................................................................................................................................206
Selecting a node .............................................................................................................................207
Selecting the value of a node..........................................................................................................207
Selecting a list of nodes..................................................................................................................207
Selecting a list of nodes based on a condition................................................................................209
Support for xml with namespaces ..................................................................................................210
Boolean X-Path Expressions .................................................................................................................211
Mathematical X-Path Expressions ........................................................................................................213
Node-Set Functions ...............................................................................................................................214
position ...........................................................................................................................................215
Agile Business Process Platform 3 Programmers Reference Revision A ix

Contents
count .............................................................................................................................................. 215

name............................................................................................................................................... 216
String Functions .................................................................................................................................... 216
string .............................................................................................................................................. 217
concat............................................................................................................................................. 218
strlen .............................................................................................................................................. 218
starts-with ...................................................................................................................................... 219
subString ........................................................................................................................................ 219
substringBefore.............................................................................................................................. 219
substringAfter ................................................................................................................................ 220
normalize-space ............................................................................................................................. 220
trim................................................................................................................................................. 220
upperCase ...................................................................................................................................... 221
lowerCase ...................................................................................................................................... 221
contains .......................................................................................................................................... 221
containsToken................................................................................................................................ 222
stringTokenToXml ........................................................................................................................ 222
Boolean Functions ................................................................................................................................ 223
true() .............................................................................................................................................. 223
false() ............................................................................................................................................. 223
boolean........................................................................................................................................... 223
Number Functions................................................................................................................................. 224
int ................................................................................................................................................... 225
float ................................................................................................................................................ 225
double ............................................................................................................................................ 225
absolute .......................................................................................................................................... 226
minDouble ..................................................................................................................................... 226
maxDouble..................................................................................................................................... 226
sum................................................................................................................................................. 227
Arithmetic Functions ............................................................................................................................ 227
+ ..................................................................................................................................................... 227
- ...................................................................................................................................................... 228
mul ................................................................................................................................................. 228
div .................................................................................................................................................. 228
mod ................................................................................................................................................ 229
ceiling ............................................................................................................................................ 229
floor................................................................................................................................................ 229
power ............................................................................................................................................. 229
roundWithPrecision ....................................................................................................................... 230
Comparison Functions .......................................................................................................................... 230
< ..................................................................................................................................................... 230
> ..................................................................................................................................................... 231
<=................................................................................................................................................... 231
>=................................................................................................................................................... 232
= ..................................................................................................................................................... 232
!=.................................................................................................................................................... 233
x Agile Business Process Platform 3 Programmers Reference Revision A

Contents
and ..................................................................................................................................................233
or.....................................................................................................................................................233
stateCompare..................................................................................................................................234
XMLform & Core Functions.................................................................................................................234
text..................................................................................................................................................235
getId................................................................................................................................................235
sort..................................................................................................................................................235
collate .............................................................................................................................................236
clone ...............................................................................................................................................237
transform ........................................................................................................................................237
docMinus........................................................................................................................................238
docDiff ...........................................................................................................................................239
ifElse...............................................................................................................................................240
stringToXml ...................................................................................................................................240
listGet .............................................................................................................................................241
listUnion .........................................................................................................................................241
findProp..........................................................................................................................................241
key ..................................................................................................................................................242
mapGet ...........................................................................................................................................242
mapContainsKey ............................................................................................................................244
Time Functions......................................................................................................................................244
date .................................................................................................................................................245
date() .......................................................................................................................................245
date(‘string’)............................................................................................................................245
date(year,month,day) ..............................................................................................................246
date(year, month, day, hour, minute, second) .........................................................................247
getYear ...........................................................................................................................................247
getYear() .................................................................................................................................247
getYear(date-string) ................................................................................................................248
getYear(date-object)................................................................................................................248
getMonth ........................................................................................................................................248
getMonth() ..............................................................................................................................248
getMonth(date-string) .............................................................................................................249
getMonth(date-object).............................................................................................................249
getDay ............................................................................................................................................249
getDay() ..................................................................................................................................249
getDay(date-string) .................................................................................................................250
getDay(date-object).................................................................................................................250
getHour...........................................................................................................................................250
getHour() .................................................................................................................................250
getHour(date-string)................................................................................................................251
getHour(date-object) ...............................................................................................................251
getMinute .......................................................................................................................................251
getMinute()..............................................................................................................................252
getMinute(date-string) ............................................................................................................252
getMinute(date-object)............................................................................................................252
Agile Business Process Platform 3 Programmers Reference Revision A xi

Contents
getSecond....................................................................................................................................... 252
getSecond()............................................................................................................................. 253
getSecond(date-string)............................................................................................................ 253
getSecond(date-object) ........................................................................................................... 253
duration .......................................................................................................................................... 253
dstDuration .................................................................................................................................... 254
incrDate.......................................................................................................................................... 255
datediff........................................................................................................................................... 256
minDate.......................................................................................................................................... 256
maxDate......................................................................................................................................... 256
stripTime........................................................................................................................................ 257
incrDateByDays............................................................................................................................. 259
parseDate ....................................................................................................................................... 259
Java's SimpleDateFormat...................................................................................................................... 259
Miscellaneous Functions....................................................................................................................... 262
getFirstDoc .................................................................................................................................... 263
getDocument.................................................................................................................................. 264
request............................................................................................................................................ 265
isEmpty .......................................................................................................................................... 266
isDataType..................................................................................................................................... 266
isValidValue .................................................................................................................................. 267
getDBInfo ...................................................................................................................................... 268
getWorkingDirectory..................................................................................................................... 268
system-property ............................................................................................................................. 268
buildSqlParamStr........................................................................................................................... 269
convertToDBType ......................................................................................................................... 269
Java Functions....................................................................................................................................... 270
nativeFunction ............................................................................................................................... 270
instanceFunction ............................................................................................................................ 271
instanceMethod.............................................................................................................................. 272
7 X-Config.......................................................................................................275
Topics: .................................................................................................................................................. 275
Introduction........................................................................................................................................... 275
Service Configuration ........................................................................................................................... 276
Service Config ............................................................................................................................... 276
Register Handlers........................................................................................................................... 277
Extension Files .............................................................................................................................. 278
X-Path Functions ........................................................................................................................... 279
Document Definition Files ............................................................................................................ 279
Rule Definition Files ..................................................................................................................... 280
Event Definition Files.................................................................................................................... 280
Validation Spec Files..................................................................................................................... 280
Workflow....................................................................................................................................... 281
Export Definition Files .................................................................................................................. 282
Purge Definition Files.................................................................................................................... 282
xii Agile Business Process Platform 3 Programmers Reference Revision A

Contents
DBLock Specification Files ..........................................................................................................282

State Model Files...........................................................................................................................283
Search Definition Files..................................................................................................................283
Audit Trail Definition Files............................................................................................................284
IdGen Configuration ......................................................................................................................284
Service Parameters .........................................................................................................................285
Logger ............................................................................................................................................287
CisTagNameMapping ....................................................................................................................290
SqlScriptFiles .................................................................................................................................290
SemanticValidation ........................................................................................................................290
Server Configuration .............................................................................................................................292
Locator Configuration ....................................................................................................................292
Protocols.........................................................................................................................................293
Client Configuration.......................................................................................................................293
App Server Configuration ..............................................................................................................294
Database Configuration..................................................................................................................294
JMS Configuration .........................................................................................................................296
Server Configuration ......................................................................................................................298
Schema Generation ........................................................................................................................299
Encryption Configuration...............................................................................................................300
Command Line Input .....................................................................................................................301
Enable JMS ....................................................................................................................................301
Logical Date ...................................................................................................................................301
WSDL Generation..........................................................................................................................301
WSDL Client Configuration ..........................................................................................................302
Cis Client Config............................................................................................................................303
CIS Generation...............................................................................................................................304
X-Server Parameters ......................................................................................................................304
Services Override Configuration....................................................................................................305
8 Workflow Concepts ................................................................................... 307

Generic Event Node ..............................................................................................................................308
Workflow Execution .............................................................................................................................308
Variables................................................................................................................................................308
Node Input & Output variables: .....................................................................................................308
Implicit Variables...........................................................................................................................309
Pipeline Variables ..........................................................................................................................309
Workflow Properties .............................................................................................................................310
Workflow Nodes ...................................................................................................................................313
Start Node ....................................................................................................................................313
Task Node ..................................................................................................................................315
Event Node ...................................................................................................................................316
Decision Node ..............................................................................................................................320
Branch Node ..................................................................................................................................322
Subworkflow Node .......................................................................................................................323
Timer Node .................................................................................................................................326
Agile Business Process Platform 3 Programmers Reference Revision A xiii

Contents
OR Node ...................................................................................................................................... 328

AND Node .................................................................................................................................... 328
Asynch Task Node......................................................................................................................... 329
Wsdl Node .................................................................................................................................. 332
UI Node ........................................................................................................................................ 338
Search Node .................................................................................................................................. 344
Serial/Parallel/Multi-Line Approval Nodes................................................................................... 352
Wait/Launch Process, Load SQL File, Execute SQL Procedure, FTP Files, Notification Nodes 352
Table Editor Component .............................................................................................................. 352
Adding a Record..................................................................................................................... 355
Copying a Record ................................................................................................................... 356
Editing a Record ..................................................................................................................... 356
Deleting a Record ................................................................................................................... 356
Select and Return.................................................................................................................... 357
Mass Update ........................................................................................................................... 357
Clearing changes made........................................................................................................... 357
Cancel ..................................................................................................................................... 357
Export to Excel ....................................................................................................................... 357
Configure Table...................................................................................................................... 358
Where Used ............................................................................................................................ 358
Advanced Filters..................................................................................................................... 358
Add to Favorite....................................................................................................................... 358
Close and Refresh Node ............................................................................................................... 358
Master Details Node Configuration............................................................................................... 359
Pivot Node Configuration.............................................................................................................. 364
Workflow Commands........................................................................................................................... 369
START_WORKFLOW ................................................................................................................. 370
KILL_WORKFLOWS .................................................................................................................. 371
CANCEL_EVENT ........................................................................................................................ 373
CANCEL_NODE .......................................................................................................................... 373
Workflow Logging ............................................................................................................................... 374
Workflow Monitoring UI (Reference Implementation):........................................................ 375
A Guide for Gathering Information on Hangs & Crashes...........................379

Server Hangs......................................................................................................................................... 379
Basic information........................................................................................................................... 379
Memory & CPU Information......................................................................................................... 379
Windows................................................................................................................................. 380
Unix ........................................................................................................................................ 380
Solaris ..................................................................................................................................... 380
HP ........................................................................................................................................... 380
AIX ......................................................................................................................................... 381
Log files ......................................................................................................................................... 382
Xserver Logs .......................................................................................................................... 382
Weblogic logs......................................................................................................................... 383
Resource Stats of the Xserver........................................................................................................ 384
xiv Agile Business Process Platform 3 Programmers Reference Revision A

Contents
Thread Dumps ................................................................................................................................384

Windows .................................................................................................................................384
Unix.........................................................................................................................................385
Solaris......................................................................................................................................385
HP............................................................................................................................................386
AIX..........................................................................................................................................386
System backup................................................................................................................................388
Steps to Replicate ...........................................................................................................................389
Server Crashes .......................................................................................................................................389
Basic information ...........................................................................................................................389
Log files..........................................................................................................................................389
System backup................................................................................................................................389
Steps to Replicate ...........................................................................................................................389
The Core file...................................................................................................................................389
Windows .................................................................................................................................390
Unix.........................................................................................................................................390
Solaris......................................................................................................................................390
HP............................................................................................................................................390
AIX..........................................................................................................................................390
B System Tables............................................................................................ 393

Maintenance of System Tables..............................................................................................................393
Details on System Tables ......................................................................................................................393
Encryption ......................................................................................................................................393
Export .............................................................................................................................................393
ID Generation.................................................................................................................................394
DB Locking ....................................................................................................................................394
Purge...............................................................................................................................................394
Workflow .......................................................................................................................................394
Index ........................................................................................................... 397
Agile Business Process Platform 3 Programmers Reference Revision A xv

Contents
xvi Agile Business Process Platform 3 Programmers Reference Revision A

Preface
Welcome to i2 Agile Business Process Platform 3 Programmers Reference. It provides

the transactional framework for building business workflows by defining the
documents in the workflow using X-Docs, and expressing the logic that operates on
these documents using X-Rules. This framework enables the definition of workflows
in a configurable manner with very little programming effort.
About i2 Agile Business Process Platform 3

Programmers Reference
Current businesses more so than ever before, are experiencing tremendous
competitive pressures and changes. Business processes are being outsourced rapidly
and new alliances, partnerships and mergers are happening at a tremendous pace. In
this highly volatile environment the IT and data management systems are being
stretched to their limit. Most of them have been built with a fixed business process in
mind and are inflexible to the kind of change that they are being subject to in today’s
economy. Under these circumstances companies are looking for a solution that would
have the following capabilities:
z An architecture that would allow leveraging existing legacy systems till the time
when they can be replaced or enhanced
z An architecture that would allow rapid prototyping of business ideas to see the
end result in days and months rather than years
z An architecture that allows a business user to be able to define and adjust process
flows more rapidly rather than having to depend on tech savvy people
z An architecture that can string multiple disparate applications to provide a
business process flow rather than having to rewrite all the individual applications
on a single technology or with a single vendor.
z An architecture that provides for data synchronization and data harmonization
across the myriad of systems that are in place
i2’s Agile Business Process Platform (ABPP) has been built with the above mentioned
objectives in mind. It enables a business user to interact with the system at a business
abstraction through a graphical integrated development environment and an intuitive
Agile Business Process Platform 3 Programmers Reference Revision A xvii

Preface
scripting language to express business rules. It provides several pre-built constructs

(such as Approval nodes, Data Upload, Data Profiling, etc) that allow a user to
quickly prototype a business process without having to worry about the nitty-gritty
associated with generic application building software. It also allows a user to define
all aspects of an application in one single environment starting from data model
definition, process workflows, business rules and validations all the way to user
interface design and integration design.
For information on other i2 solutions, contact your i2 sales representative.
xviii Agile Business Process Platform 3 Programmers Reference Revision A

Preface
About this Book

This book is intended to serve as a detailed reference guide on Agile Business Process
Platform (ABPP).
Target Audience
This book is intended for SCOS i2 Application users.
What You Should Know

You must also have basic knowledge about business scenarios.
What This Book Contains

This book has the following chapters.
z Chapter 1 “Introduction” on page 1. It gives an introduction to the ABPP
framework.
z Chapter 3 “X-Documents” on page 25. Explains the various properties of an X-
Doc and its relational structure.
z Chapter 4 “X-Commands” on page 41. It discusses the input and output XML
documents commands.
z Chapter 5 “X-Rules” on page 65. It discusses how business workflows can be
written in ABPP using sets of conditions and the corresponding actions (called X-
Rules).
z Chapter 6 “X-Path” on page 205. It discusses how X-Rules are expressed
uniformly using an XML specification called X-Path.
z Chapter 7 “X-Config” on page 275. This section explains the various parameters
that can be configured which define the behavior of an X-Service.
z Chapter 8 “Workflow Concepts” on page 307. Explains the business process
workflows that enables to model a business process in ABPP.
Conventions
Table 1 lists examples of the typographic conventions used to display different types
of information in this document.
Agile Business Process Platform 3 Programmers Reference Revision A xix

Preface
Table 1 Typographic conventions used in this document
Item Example Explanation
Code Call NotifyPending; File names, executable code,

commands, and configuration
statements are shown in monospaced
font.
Class Names Make the Class Configurations Class names appear in bold.
pointer in the Module
Configuration class a primary
key.
Interface element Click Organization Management Button names, field names, window
in the toolbar. names are shown in a san-serif font.
Pathname C:\i261\webdriver Windows pathnames are shown in

or monospaced font, with backslash path
separators.
/i261/webdriver
Unix pathnames are shown with
forward-slash path separators.
Meta-variable i2_Home\webdriver Portions of code that you replace with

or specific values are shown in italic
monospaced font.
i2_Home/webdriver
Documentation or SCOS Installation Guide Document or book names referenced

book names. in this book are shown in italics.
Any of the following types of notes may appear in this book:
Note: This kind of note contains information that is useful or interesting but not
essential to an understanding of the main text.
CAUTION: This kind of note contains instructions that are especially important to
follow for proper functioning of the product.
WARNING! This kind of note contains instructions that must be followed to avoid
potential crashes or loss of data.
xx Agile Business Process Platform 3 Programmers Reference Revision A

Preface
Related Documentation
For more information about i2 ABPP, refer to the following in the documentation set:
z Agile Business Process Platform (ABPP) 3 Release Notes
| [ABPP3_RelNotes_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Studio User Guide
| [ABPP3_Studio_UserGuide_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Manufacturing User Guide
| [ABPP3_Manufacturing_UserGuide_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Programmers Reference
| [ABPP3_Programmer_Reference_Part2_6.2.8.pdf]
| [ABPP3_Programmer_Reference_Part3_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Best Practices
| [ABPP3_BestPractices_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Install Guide
| [ABPP3_Install_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Deployment Guide
| [ABPP3_DeploymentGuide_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 How To Guide
| [ABPP3_HowTo_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Manufacturing Admin Guide
| [ABPP3_Manufacturing_AdminGuide_6.2.8.pdf[
z Agile Business Process Platform (ABPP) 3 Performance Tuning Guide
| [ABPP3_PerformanceTuning_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Authentication and Authorization
Guide
| [ABPP3_Authentication_Authorization_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Frequently Asked Questions
| [ABPP3_FAQs_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 Monitoring Guide
| [ABPP3_Monitoring_Guide_6.2.8.pdf]
z Agile Business Process Platform (ABPP) 3 PGL Internationalization Guide
| [ABPP3_PGL_Internationalization_6.2.8.pdf]
To Read Documentation
To read the .pdf files, you must have Adobe Acrobat Reader, version 4.0 or higher.
If you do not have Acrobat Reader on your machine, you can download it from
Adobe’s Web site at http://www.adobe.com.
Agile Business Process Platform 3 Programmers Reference Revision A xxi

Preface
To read the Help files, you must have one of the following browsers:
z Internet Explorer, version 5.0 or higher. You can download this software from the
Microsoft Web site at http://www.microsoft.com/.
z Netscape, version 4.0 or higher. You can download this software from the
Netscape Web site at http://home.netscape.com/.
If You Need Assistance

Customer support is available at the i2 Customer Support Web site (http://
support.i2.com), where you can:
z Request shipment of software.
z Request product license keys.
z Download software documentation.
z Submit new issues or cases.
z Track the status of current issues or cases.
To Obtain Licenses
To obtain licenses for i2 and third-party products, go to http://support.i2.com, and log
on. On the Contents list, expand Cases Menu, and then click Request LicenseKey.
Alternatively, you can request licenses by email, but the Web site provides priority
service.
To Contact Customer Support

To contact Customer Support, use one of the following options
Internet Web site: http://support.i2.com
Email: support@i2.com
Phone: US and Canada: 1.469.357.3456

EMEA: 32.2.717.66.77
APAC: +91.80.30288888
Japan: 81.3.6409.1212
Australia: 61.3.9832.7654
Give Us Feedback
We value your comments and suggestions about our documentation. If you have
comments about this book or the online Help, please enter them in the Comments and
Feedback section of the i2 Customer Support Web page. We will use your feedback in
our plans to improve i2 documentation.
xxii Agile Business Process Platform 3 Programmers Reference Revision A

Preface
For the Latest Documentation

For the latest versions of any documentation, go to the i2 Customer Support Web page
(http://support.i2.com). From the Documentation link under Quick Menu, you can
download the most recent version of the product documentation.
Agile Business Process Platform 3 Programmers Reference Revision A xxiii

Preface
xxiv Agile Business Process Platform 3 Programmers Reference Revision A

Chapter 1
Introduction
This chapter gives you an introduction to Agile Business Process Platform 3

Programmers Reference. It includes the following topics.
Topics:
z Overview
z Elements of ABPP Framework
z How to Use This Guide
Overview
Current businesses more so than ever before, are experiencing tremendous
competitive pressures and changes. Business processes are being outsourced rapidly
and new alliances, partnerships and mergers are happening at a tremendous pace. In
this highly volatile environment the IT and data management systems are being
stretched to their limit. Most of them have been built with a fixed business process in
mind and are inflexible to the kind of change that they are being subject to in today’s
economy. Under these circumstances companies are looking for a solution that would
have the following capabilities:
z An architecture that would allow leveraging existing legacy systems till the time
when they can be replaced or enhanced
z An architecture that would allow rapid prototyping of business ideas to see the
end result in days and months rather than years
z An architecture that allows a business user to be able to define and adjust process
flows more rapidly rather than having to depend on tech savvy people
z An architecture that can string multiple disparate applications to provide a
business process flow rather than having to rewrite all the individual applications
on a single technology or with a single vendor.
z An architecture that provides for data synchronization and data harmonization
across the myriad of systems that are in place
Agile Business Process Platform 3 Programmers Reference Revision A 1

Chapter 1 Introduction
i2’s Agile Business Process Platform (ABPP) has been built with the above mentioned
objectives in mind. It enables a business user to interact with the system at a business
abstraction through a graphical integrated development environment and an intuitive
scripting language to express business rules. It provides several pre-built constructs
(such as Approval nodes, Data Upload, Data Profiling, etc) that allow a user to
quickly prototype a business process without having to worry about the nitty-gritty
associated with generic application building software. It also allows a user to define
all aspects of an application in one single environment starting from data model
definition, process workflows, business rules and validations all the way to user
interface design and integration design.
ABPP can be sub divided into two main components: Infrastructure and
Manufacturing Application. The infrastructure provides the capabilities to develop
and maintain any application where as the Manufacturing application provides a
reference data model for the Supply Chain Industry and data management workflows
that allow an end user to maintain data based on the reference model. The i2 planning
engines such as SCP, FP run off of this reference data model.
The infrastructure itself can be further sub-divided into 2 main components: Runtime
and Studio.
z Runtime/Server: The Runtime provides the workflow execution layer that runs
workflows on the data models and also provides the presentation layer. In most
deployments the runtime is housed within an application server such as Weblogic
or Websphere. There are several native services that are included in the runtime
that provide several key capabilities that are necessary in running any application.
Examples of these services include: Timer, Data Upload, Approval, Messaging,
Data Service etc.
z Studio: Studio is the visual design environment that allows the user to create and
modify workflows, user interfaces and data models in one environment. It
provides several built in business abstraction components such as search nodes,
approval nodes, UI components that hide the internal complexity of the system
from the business user during his/her design and development. It also provides a
rich intelli-sense, semantic validation and a debugging tool that is essential in
rapid development and customization of applications.
ABPP
2 Agile Business Process Platform 3 Programmers Reference Revision A

Elements of ABPP Framework
This document is focused on the infrastructure and is intended to provide the

architectural concepts and details of the built-in services, utilities and the scripting
language and its usage for different processes. This document is to be used in
conjunction with the ABPP3_Studio_UserGuide, the PGL_Reference html guide and
the pre packaged samples that illustrate the usage of these concepts through several
business examples.
The material presented in this document is organized into 3 main sections – Reference
Guide, Utilities Guide and Services Guide.
z Reference Guide: This section focuses on providing the syntax and usage of
several of the basic constructs. The essential constructs include:
| X-Documents/Models: These are XML representations of a data model. The
modeling capability in ABPP enables a user to describe a database table
definition which includes the data type, field length, constraints, relationships
etc.
| X-Commands: A command in ABPP enables one to interact with the server.
Usage of a command includes extraction of data from the database as a
request or to start, stop workflows, and set/obtain the system properties for the
services running on the server such as log levels, resource statistics etc.
| X-Rules: X-Rules in ABPP are the java equivalent of a function. They enable
one to express business logic in the XML syntax that the server can execute
| X-Workflows: A workflow in ABPP is a representation of a business process.
Most workflows built on ABPP involve the movement of documents through
a work process a few involve performing a set of actions (such as initiating
some external processes) in a sequence of steps. A workflow in ABPP
consists of a series of nodes (steps) connected through actions/ events.
z Specifications/Utilities Guide: This section focuses on providing details on the
syntax for using the pre-built utilities in ABPP that enable a user to perform a set
of actions such as validations, export documents, enable audit trail etc.
z Services: ABPP is built on service oriented architecture that enables one to model
several business functions as modules that run independent of one another rather
than one monolithic application. A service in ABPP (different from a web service)
is a logical grouping of a set of workflows, rules and documents that address a
business function. For example in the supply chain context all actions pertaining
to forecast analysis could be grouped into one service that constitutes of
workflows and rules that enable forecast loading, forecast validation, forecast
analysis calculations etc. In ABPP certain pre-built services are provided to help
in commonly used business functions. Examples include: data upload, timer and
approval.

The main components of the ABPP framework that are used in any application are:
z X-Server: A single JVM (Java Virtual Machine) instance that implements one or
more X-Services. It constitutes the Run-Time environment for ABPP.

z X-Services: Collection of APIs and processes (workflows) that make up a logical

unit.
z X-Documents: Describes the data model or documents in the system.
z X-Commands: Describes how APIs (Application Programming Interface) can be
invoked on ABPP and provides reference to the built-in APIs available.
z X-Rules: Describes the scripting environment and the built in components
available to create new API.
z X-Workflows: Model the business processes (document flows through the system
together with rules, events, timers etc.).
X-Server
The X-Server is an instance of the ABPP application, running in a single JVM (Java
Virtual Machine). It is the Run-Time deployment of the application that was designed
using the i2 Studio.
The main features of X-Server are:
1. Multiple X-Services can be deployed within an X-Server VM (configurable at
design time).
2. Multiple X-Servers can be deployed in a cluster to guarantee high scalability and
reliability.
3. Communicates with other X-Servers and clients through a variety of protocols -
XRMP, TCPA, HTTP.
4. One X-Server connects to only one RDBMS.
5. X-Server can be deployed as a library within an Application Server or in a stand
alone mode.
X-Service
An X-Service is identified by its name and has a set of APIs and processes that
satisfies a business function.
The main features of X-Service are:
1. The service APIs can be published using WSDL.
2. Each service contains a set of data models, rules and workflows. These are used
by the service to satisfy the business function.
3. Typically all the services that make up an application would be deployed in a
single X-Server.
4. All the X-Services can be configured to register with the Locator service. Clients
can discover the deployed services by querying the Locator service.
The locator Service is a core ABPP framework service that maintains a registry of the
all the X-Service names and the X-Server URLs which form the ABPP application.
The main features of Locator Service are:
1. Provides API for registering and un-registering services.

2. Allows clients to discover the location of the services by querying the locator for a
service and getting the URL of the server on which it is deployed.
3. If a service is deployed by more than one server, then it performs load balancing
by giving out the server URL's in a round-robin scheme.
4. The client communication libraries hide the nuances of finding the service
through the locator and have the built-in intelligence to switch over to another
server (by contacting the locator) in case of a failure.
Xserver instances can be deployed as a library with in the Application server. In this
setup, if you want to use the services to exclusively satisfy the requests posted on the
application server, then it is not necessary to register the services with the locator.
X-Documents
An XML specification to model the business document in the ABPP framework;
consists of document name, properties, and data types, which provides the basis for
database table definitions.
The main features of X-Documents are:
1. Impart transparency to underlying RDBMS since the XML specification is not
database-specific.
2. Contain relationships to other X-Documents, which provide the basis for database
schema referential and integrity constraints.
3. Supports 1-1, 1-n, n-n relationships with other X-Documents.
4. Extensible at deployment time to include additional properties and relationships.
5. Audit Trail and Dynamic Attributes can be turned on at deployment.
6. Provides querying and persistent business document instances - XML based data
manipulation statements that are translated to database dependent SQL
statements.
X-Rules
X-Rules are an XML specification for implementing APIs using ABPP scripting
environment.
The main features of X-Rules are:
1. Built-in primitives for all common tasks.
2. Designed for building database centric applications. Provides components easily
create, search and modify data in a database.
3. X-Path semantics can be applied to traverse and manipulate X-document
instances within X-Rules. X-Path expression functions are extensible and
customizable.
4. Hooks to perform complex logic processing in Java.
5. Extensible framework for adding new rule components not available in the core
product.

X-Workflow
X-Workflows are an XML based specification to model business processes and embed
execution logic.
The main features of X-Workflow are:
1. ABPP provides built-in workflow nodes for:
| Marking the start and end of workflows (Start, Done nodes)
| Performing actions (Task node)
| Creating user-interfaces (UI node)
| Wait for events (Event node)
| Controlling the execution (Decision, And, Or, Branch, and Subworkflow
nodes)
| Invoking other i2 engines through CIS or Web-Services (WSDL node)
| Wait for a specified time (Timer node)
| Specialized actions like document validation, messaging, and so on.
2. Design allows for creation of new workflow nodes to perform specialized tasks.
3. Can be re-used by modeling them as subworkflows. The subworkflows can then
be composed to create complete complex process flows.
4. Can be instantiated explicitly or through an event.
How to Use This Guide

The intention of this guide is to provide the user with a ready reference for
understanding:
z Reference on X-Documents. X-Documents are the run time data models created
from the visual data models in i2 Studio.
z Understanding how APIs are invoked on ABPP and a reference to the built in
APIs
z Grammar used in defining X-Rules. Reference to the built-in rule components and
X-Path functions.
z Grammar for creating validation, search, export, purge, WSDL and other
specifications.
z Reference to server and service configurations
z Core framework services like Timer, Data Upload, Approval etc.
The user will be switching back and forth between this document and the i2 Studio
User Guide as the two go hand-in-hand. The ABPP Studio User Guide covers all the
elements of defining a ABPP application, while the ABPP Reference Guide focuses
on the part dealing with the syntax and grammar for all the elements used by the
ABPP run time engine.

Chapter 2
Modeling Concepts
Most software applications leverage a relational database for storing and retrieving
structured data. The database provides a mechanism to store logical groupings of data
with clear relationships across different entities. While the database is useful in
maintaining information there are still certain types of data that is better suited for
applications to maintain outside of the strict constructs that the relational modeling of
the database provides. For example one could model attributes/properties that
determine how the user interface ought to be rendered while displaying data from a
particular table. These properties/attributes may not necessarily be part of the
physical model in a database that represents the business entities. In order to be able to
maintain this kind of information one would ideally separate the physical model from
the logical representation of the model. The logical representation of the model is used
by the application at design and run time while the physical model in the database is
used just as a mechanism of storing, retrieving and to a certain extent validating data.
ABPP provides a mechanism to create and maintain the logical models through a
visual mechanism. This chapter explains the key concepts and entities involved in
data modeling in ABPP. The topics discussed in this chapter are:
z Definitions
z Model Extension and Inheritance
z Model Dependancy and Composite View
Definitions
Document
A document is the logical equivalent of a SQL table. A document represents an ABPP
application's data model. It contains properties, keys, links and facets.

Chapter 2 Modeling Concepts
Property
A property is an attribute of the document described above. It is the logical equivalent
of a SQL table column along with other elements that provide details about the
column. A property contains the following attributes as shown in the figure below:
z Active: Determines if this data type is active

z Name: The name of the property. This is the logical name of the property. This is
the name used by the ABPP application during run time.
z Data Type: The name of the data type (more on this topic later).
z Physical Name: The physical name of the property. This is the name one would
find in the database once the document is instantiated.
z Required: Whether the property is required. If this is checked then a document
instance cannot be created without providing a value for this property.
z SQL Type: The SQL type of property for example, String_40, Integer, etc.
z Default: The default value of this property. This is the value that the application
will set if a value is not specified in the input data.
z Enumeration: If this property is one of a set of values. The enumeration could be
of three types: Constant or Fixed List, Lookup and Code Master.
| Constant: The enumerated values are a list of constants specified at design
time through Studio
| Lookup: The enumerated values are "looked-up" from a table specified at
design time. What ever properties are specified in the look up table will be
used as the list of valid values during run time.
| Code Master: ABPP provides a standard set of lookup tables that are called
Code Master. At design time the user is expected to specify the Code Master
type for example CURRENCY, STATE and COUNTRY etc. ABPP will
automatically validate against the valid values specified in the Code Master.
z Constraints: If this property has any constraints (for example, value < 30).
z Documentation: The comment associated with this property
Key
A Key in ABPP is equivalent to the Key for a database table. A key is an attribute
utilized to sort and/or identify data in some manner. Each document in ABPP should

Definitions
ideally have a primary key which uniquely identifies it, however this is not mandatory.
The attributes of a key are shown in Figure below and the details of each attribute are
explained below the figure.
z Active: Determines if the key is active

z Name: Name of the key
z Kind: One of primary key, index key, unique key or unique index key
z Physical Name: Physical name of the key
z Properties: The properties that are part of the document key are edited through
the Document Key Properties editor shown below.
Link
A link in ABPP is conceptually similar to a hyperlink in a HTML document. The
primary motivation of a document link is to navigate the additional information
associated with the document. In some ways links are also similar to Foreign Keys in
the database except that they are not necessarily propagated to the database when the
model is instantiated in the database. Links are maintained in the document relations
within ABPP. The attributes of links are shown in below and the details of each
attribute are explained further below.
z Active: Determines if link is active

z Name: Name of the link. This is the logical name of the link used by the ABPP
application

z Physical Name: Physical name of the link. This is what one would find in the
database.
z Key Maps: From (current document) and To (linked document) key mappings
that are part of the link can be edited through interface shown the Figure below.
In the example below the OrderID property on the LineItem document is mapped
to the ID property on the CustomerOrder document. The ID field on the
CustomerOrder also happens to be CustomerOrder document's Primary Key.
Another important point to note is Delete Rule. The list of valid values in the Delete
rule are RESTRICT, CASCADE, SETNULL and blank (empty). If any value other
than blank is chosen then the link is propagated to the database as a foreign key (FK).
If it is left blank then the link is assumed to be only at the application layer and will
not be propagated to the database (there is an exception to this - please see the Note
below).
There are several instances where one may want to establish a link but not propagate it
to the database. For example consider the case where a table called NOTES is defined
to store the notes that are associated with the different documents/tables such as
Purchase Order, Customer Order and Activity Order etc. Given that we wish to store
notes from all these documents in a single Notes table establishing a foreign key
relation is not possible. The same property of a table cannot be linked to three
different tables through a foreign key. In such situations one would create three links
between the three tables and for all three leave the Delete rule blank. One can argue
that ideal modeling practice would be to have a single Order object with PO, AO and
CO as types of that order etc. But in real life one would find several such examples as
mentioned above.
Another situation where a link would serve better than an FK is the case where it is
used only to navigate. For example a Customer Order is related to a Line Item
through an FK that is defined only on the Line Item table. However in most cases one
would like to retrieve Line Items for a given Customer Order and a logical link from
the Customer Order to the Line Item table would help in this navigation. Another case
could be an instance where one would like to allow corrupt/bad data to be loaded into
the system even if it violates the ideal FK relationships so that it can be processed
through user driven error correction workflows. Links come in handy in these kinds
of use cases.

Definitions
Note: Up to and including the 627 release if the To Key in the Key Map was chosen
to be the Primary Key of the To Document the system would default set the
Delete Rule to RESTRICT and create an FK in the database even if the user
did not select any Delete Rule (left it blank).
Facets
ABPP provides several constructs that enable a model driven architecture. Essentially
several attributes can be defined along with a data model that will enable the
generation of other entities dynamically at run time. The way to do this in ABPP is
through a construct called facets. Facets are provided for dynamically extending the
grammar of the models that are used by various frameworks/applications built on top
of the ABPP infrastructure. ABPP Studio provides a separation between data model
definition and these application specific attributes. These attributes could be related to
presentation or data authorization in ABPP application and will be defined as different
facets of the base data model definition. This section describes each of the default
facets that are packaged with ABPP. The presentation related facets are currently used
by the Table editor component of ABPP. Future enhancements are directed towards
making more of the ABPP components use these facets (for example: Search Node,
Pivot Node, Header Detail node etc)
Facets are grouped into two broad sets - Table facets and Property facets. Table facets
define attributes at the table/document level and property facets define attributes for
the individual property of the document.
Table Facets.
The Table Facets contain several sub groups of facets such as Miscellaneous Facets,
Data Service Sys Table Map Facets, Data Service Config Facets and Data Service
Authorization Facets. The entries in each of these groups is explained below
Miscellaneous Facet.
z Active: This facet determines if this document is active in the service and
ultimately included in the DB schema. By default, this box is checked.
z PhysicalName: Represents the physical name of the table in the database
z Display Name: Specifies the Display Name of the table on all screens that display
the table as-is.
z TableEditorRowsPerPage: Specifies the number of records shown per page for a
Table Editor node that uses this document
z Cached: This facet determines whether data in this table is cached during server
startup
z Surrogate Key: This facet determines if the primary key of this table is system
generated

z IdPrefix: This facet is used when the ID of the document is auto-generated. The
text specified in the IdPrefix is added as a prefix to the auto-generated document
Id. For example while creating a customer order one may want to add CO as the
prefix to auto-generated Id.
z ReadOnly: ABPP provides basic APIs called GET_DOCUMENT and
ADD_DOCUMENT to get data and add data to a table. This facet controls
whether ADD or MODIFY_DOCUMENT APIs should be enabled for this
document or not. If the ReadOnly facet is set to true then the ADD and
MODIFY_DOCUMENT for this model are disabled.
Data Service Sys Table Map Facet.

ABPP provides the capability to create data management related workflows. This
essentially involves data being received from external systems into an "INPUT"
staging tables where data is validated and cleansed followed by moving them to the
MASTER tables. This data can be subscribed by other external systems via OUTPUT
staging tables that are a snapshot of the MASTER tables. The Data service Sys Table
Map facets control the data staging aspects of the ABPP Manufacturing application.
z TableClass: This facet determines whether input and output staging tables are
created for this document.
| MASTER: MASTER kind of documents represent master data entities which
are stored in the master repository. These entities also can go through an
elaborate E2E batch loading process wherein they are loaded through the
application and centralized validations and processes are applied. Also the
data for these kinds of entities is always retained by the master repository,
unless explicitly deleted by a delete transaction. E.g. of these documents is
Item, ItemLocation etc. Master Tables are constrained and maintain
referential integrity with other master data tables. For tables marked as
MASTER, Studio creates tables for inbound and master services.
Additionally, tables for net change service might be created depending on
Source Facet described later in this section.
| TRANSACTION: Represents transaction data such as sales orders or in-
transit shipments that are sourced from external systems. The tables whose
TableClass facet is set to TRANSACTION are expected to contain transaction
data that is transient in nature and data in these tables is expected to be deleted
completely before each load of fresh data. The data in these tables therefore
does not go through a net change process; instead it goes through the dynamic
load process. The data however is checked for integrity with the master
repository. Tables are constrained and maintain referential integrity with
other master and transaction data tables. INPUT and OUTPUT staging tables
are not created for TRANSACTION documents.
| PLAN: Tables that are marked with a facet of "PLAN" represent entities that
are not validated in any manner in ABPP. They are just housed in the ABPP
master repository. Typically PLAN tables are used to store output sourced

Definitions
from planning applications. Since such data is programmatically created,

these tables are defined as unconstrained.
z Source - This facet represents the source of the data to be stored in this table.
System Behavior in terms of how the staging area gets created and how the net-
change gets applied is dependent on what the value for the Source property is.
Hence it is critical that this property be set appropriately based on the
requirements of the solution deployment. The values that this facet can be set to
are MASTER, BACKEND or BOTH.
| MASTER represents that this document data is going to be created/managed
in ABPP.
| BACKEND implies that the data for this entity is going to be created, updated
and managed in a backend system and ABPP is going to house it as reference
data.
| A Source of BOTH implies that for this document, data for some of the
properties comes from a backend system while for other properties ABPP is
the system of record and data can be entered from the UI.

The flowchart shown below depicts the factors that decide how the source property
should be set.
Model Business Entities

(Keys, Properties, Relationships)
What is the Master Source of Entity

BackEnd System owns this data ABPP Data Service owns this data
Data?
Mark the Source Facet in Data Service Some Properties of the Entity are owned Mark the Source Facet in Data Service Sys
Sys Table Map By BackEnd and some by the Data Service Table Map
As As
BACKEND MASTER
Mark the Source Facet in Data Service Sys

Table Map
As
BOTH
This also means we need to explicitly

classify which of the properties are
MASTER and which are BACKEND
Go to the Property Tab of Facets

If the properties are defined in a parent
Model Instance – click on Composite View
and override the Properties that are owned
by BACKEND and set their Source to
BACKEND(The default for a property is
MASTER)
z InputTable: Specifies the name of the Physical table in the input staging area.
The default for an InputTable is a prefix of IN_ to the physical name of the entity.
Hence a document with Physical Table Name of ITEM will have by default
(unless overridden here) an Input Table called IN_ITEM.
z ErrorTable: Specifies the physical name of the Error table in the input staging
area. The default for an ErrorTable is a prefix of ERR_ to the physical name of the
entity. Hence a document with Physical Table Name of ITEM will by default have
an ErrorTable called ERR_ITEM
z ErrorDocument: Specifies the document name to be used for the error document
that is generated in the input staging service. ErrorDocument is the logical name

Definitions
of the entity that captures staging/load errors while the ErrorTable described
above is the physical table name of this entity.
z MasterTable: Specifies the name of the master table. The default value for this is
to have a prefix of MST_ on the physical name of the entity. Hence a document
with Physical Table Name of ITEM will by default have a MasterTable called
MST_ITEM
z OutputTable: Specifies the name of the corresponding output staging table. The
default value for this is to have a prefix of OUT_ on the physical name of the
entity. Hence a document with Physical Table Name of ITEM will by default have
an OutputTable name of OUT_ITEM.
z NetChangeTable: Specifies the name of the corresponding net change table. The
default value for this is to have a prefix of NC_ on the physical name of the entity.
Hence a document with Physical Table Name of ITEM will by default have a
NetChangeTable name of NC_ITEM.
Configuration Facets.
z isNative - This implies that this is a native document for the master service and
does not participate in the data staging workflow.
z SchemaGen - If turned on a table gets created for this document during schema
generation. If this facet is set to false (check box unchecked) then the document
will remain as a logical document and will not be instantiated in the database.
z ScenarioEnabled - If turned on scenarios are supported for this document. The
valid values for this facet are "null" (blank), true and false.
| true - This implies that Scenarios are enabled for this document. A
SCENARIO_ID column is added to the table and is included in the Primary
Key of the table. This value will override the setting at the Service level
| false - This implies that Scenarios are not enabled for this document.
SCENARIO_ID is not included in the table definition
| null (blank)- This implies that this document will take the value specified at
the service level and accordingly include/exclude SCENARIO_ID in the table
definition.
z SnapShotDeletedInactive - This specifies if Deleted and Inactive states need to
be snapshotted.
z HardDelete - This is a flag which if checked causes all requests of
REMOVE_DOC_LOGICAL to do hard deletes instead of the usual soft deletes.
The valid values for this facet are true, false and null
| true - This implies that the document is hard deleted from the database when
the REMOVE_DOC_LOGICAL command is issued on the document. The
delete still respects the database constraints (CASCADE, RESTRICT etc)
| false - This implies that the document is soft deleted from the database when
the REMOVE_DOC_LOGICAL command is issued on the document.

| null (blank) - This implies that the facet is inherited from the service
parameters.
z NotesEnabled - If turned on a Notes field is implicitly added as a property of the
document
Authorization Facets.
DefaultAuthorization - This facet is used only by a Data Service (refer to Chapter 13

for more information on a Data Service). This facet determines whether access to data
in this document ought to be restricted on the basis of the user's access privileges.
ABPP comes packaged with a default User Security service that maintains the users
and their access privileges to data. The access to data is controlled through a property
called the SYS_AUTH_ID. This property is added by default to any document that is
instantiated in a Data Service. When using the default User Security Service
packaged with ABPP, each user modeled in the system can be associated with one or
more SYS_AUTH_ID. When the Default Authorization facet is set to true on a
document then a user is allowed to view data in this table only if he has a
SYS_AUTH_ID that matches the SYS_AUTH_ID entry for that record in this table.
The Default Authorization facet can be controlled at the Service level as well as the
document level. The valid values for this facet are "null" (blank), true and false.
| true - This implies that Data Authorization is enabled for this document. A
Foreign Key is added to the table linking it to the Authorization Master table
in the User Security service. This value will override the setting at the Service
level. So for example if the service level authorization setting is false then
this facet will force authorization only for this document therefore overriding
the entry at the service level.
| false - This implies that Data Authorization is NOT enabled for this
document. A Foreign Key is therefore NOT added to the table linking it to the
Authorization Master table in the User Security service. This value will
override the setting at the Service level. So for example if the service level
authorization setting is true then this facet will force authorization NOT to be
performed for this document therefore overriding the entry at the service
level.
| null (blank)- This implies that this document will take the value specified at
the service level and accordingly include/exclude a Foreign Key to User
Security service in the table definition and enforce data authorization on this
document.

Definitions
Field Facets.
The Property facets dictate how the properties of the table are used in E2E and by the
Table Editor UI. The usage of these property facets will be extended to other
components in the future.
z Name: This is the logical name of the property.
z Source: This attribute is used by the E2E service during data staging only when
the Source at the document level is set to BOTH (refer to the previous section for
an explanation). Select the Source for the field from one of the following values:
| BACKEND: Data is sourced from external systems. Studio will create this
field in the netchange table.
| MASTER: Data is created in ABPP. This field will not be created in the
netchange table.
z DisplayName: Specifies the name to be displayed in the table editor for the
property. This could be different from the logical name of the property.
z Editable: Specifies whether this field should be editable in the table editor.
z Hidden: Specifies whether this field should be hidden in the table editor.
z Sortable: Specifies whether this field should be sortable in the table editor.
z Searchable: Specifies whether this field should be searchable in the table editor.
z No Wrap: Specifies whether this field should be wrapped to fit into a cell in the
table editor.
z i18nize: Specifies the field to be i18nized
z Decimals: This specifies the number of decimals that are to be displayed for a
number field.
Dictionary
ABPP provides functionality to extend the native data types (string, boolean, int, float
etc) to create your own logical data types. This feature is very helpful in making
changes to your model easily.
Example:
z Book, Customer Order and Line Item models have an ID column which uniquely
identifies the records. If you want the ID columns in these models to have a
maximum of 50 characters then you would create your own data type (say IdType)
and assign it the value of string (50). You would then set the data type of each of
the ID columns as IdType data type in all the models. Later on if you want to
change the ID columns to have a maximum of 64 characters, then you just need to

change to IdType to string (64). This will ensure that all the above models will
have their ID columns changed to maximum of 64 characters.
z Each Book has a price. Similarly a Customer Order has a total price. You might
want both these price fields to always have the same precision. This can be done
by creating a PriceType data type with the required precision and assigning the
corresponding columns with this data type.
It is considered good data modeling practice to assign columns of similar nature
(example: all ID columns) to the same logical data type.
In ABPP, the user defined data types are grouped in to a data dictionary. A model set
or model instance can contain many data dictionaries. The name of the data dictionary
is unique within the model set or model instance.
Each data type defines what attributes a collection of columns in SQL table should
have. The attributes of data type are as shown in Figure below and the description of
the attributes is presented below the figure.
z Active: Determines if this data type is active

z Data Type: The name of the data type
z Extends: A data type can also extend other data types. This feature lets modeler
create data types such as, SHIP_TO_ID etc. extend from LOCATION_ID which
in turn can extend from the data type ID. In an extension relationship like this,
modeler can change the attributes of LOCATION_ID and also attributes of
SHIP_TO_ID as he/she sees it fit. However the attributes that are not changed by
the modeler in the derived data types are inherited from the parent data type.
z Physical Name: The physical name of the data type
z Required: Whether the data type is required
z SQL Type: The SQL type of data type for example, String_40, Integer, etc.
z Default: The default value of this data type
z Enumeration: If this data type is one of a set of values
z Constraints: If this data type has any constraints (for example, value < 30)
z Description: The comment associated with this data type
Model Sets & Model Instances

ABPP is service oriented architecture. You can perform any meaningful action
(example: creating table, inserting records of a model etc) on any ABPP construct
(model) only if it is part of a service. So the end goal is to create (or deploy) the
models within services.

Model Extension and Inheritance
ABPP allows you to accomplish this by:

1. Creating and managing models globally and deploying them across multiple
services.
2. Creating and managing models directly within the services that consume them.
In the globally managed models approach, you create the models globally and deploy
them across various services. This approach requires the extra step of deploying the
models. Here are the key benefits of this approach:
z Allows you to reuse common data dictionaries across services and prevent
proliferation of models which represent the same thing
z You can potentially build multiple services that share the same model. This can
be done by deploying the same model in to multiple services. Example: A factory
planning service and a master planning service may use the same item, location,
bill-of-materials, resources and routing models.
z Allows you to easily create the dependencies across models which will be
potentially deployed in different services. Example: Forecast model in
forecasting service might have foreign key references to customer and supplier
models in the enterprise service. It will also be easier to visualize the constraints
on Forecast model if the models are created globally.
z You can still create models that are deemed local to a service within the service. It
also allows extending the global models within a service to meet any specific
needs. The model extensions are stored within the service as over-rides.
The group of globally managed models is called a model set. Each model set has a
name and a root folder name. Any models part of the model set is created directly
under the root folder or in a sub folder of the root folder. The models deployed within
a service or directly created within a service are called model instances.
Model Extension and Inheritance

ABPP provides advanced features such as model extension where in one model can
extend the data elements defined in another model. This feature enables one to create
modular model sets that are reused at a solution level. This feature also enables one to
create global model sets that leverage work done in the context of another model. For
example imagine a scenario where in two data models were to be created one for a
retail customer and another for manufacturing customers. In the process of creating
these models one may realize that there are certain common elements such as user
security, code master, items, buffers, transaction models (customer order, shipments
and so on) and more. It would be a good idea to have these entities defined as a
common model called Toolkit. The Retail and the Manufacturing models can then
extend from this common model. They can add data elements that are not present in
the base model as extensions in their specific incarnations.
If a model-2 extends from other model-1, then documents and dictionaries in model-2
having same package (directory) structure and name as in model-1 extend
corresponding documents and dictionaries of model-1

For example as shown in figure below:
Retail Model "extends" Toolkit model:

z Buffer document in Retail model extends Buffer document of Toolkit model,
since the packages (directory structures) of both the Buffer documents are the
same.
z Similar concepts are applicable for the dictionary, "common-dict" in Retail model
extends "common-dict" in the Toolkit model.
z The inheritance is implied because of same file name and same package structure.
z If file names match for documents and dictionaries but package (directory)
structure does not, then there is no inheritance.
z This implied inheritance structure lets users create multiple Item.mtt definitions in
the same model. Given that there are no pointers/references defining the
"extension" relationship between documents, mix and match, promotion and
demotion of the documents between models and packages is easier.

Model Dependancy and Composite View
The model directory contains a manifest file named cfg.xml which contains
information about the name of the model and any information about the model that it
extends.
Model Dependancy and Composite View

If a document extends another document, then it implicitly also gets all the properties,
keys, links and facets defined in base document and in turn properties, keys, links and
facets get the missing attributes from corresponding base model artifacts. Such a
combined view of properties, keys, links or facets is called a composite view.
The composite view is color coded as shown in the figure above.

z Pink color signifies that the attribute value is completely derived from the parent
document.
z Green color signifies the attribute value is overriding the corresponding artifact in
the base model and will reflect all changes done to base model artifact, except
ordering.
z White color signifies that the attribute has been added to the model instance/
model extension and is not present in the parent.

Notes:
1. When a data type or document extends from a base data type or
document, the parent's properties are inherited by the child. If the Extends
link is disconnected, then these properties are removed from the child
unless they are already applied as overrides to the child.
2. Studio provides the capability to create and override a data dictionary at
the model instance level. However when you override a data type at the
model instance, the properties in the model instance that were referring to
the parent data type continue to refer to the parent data type unless they
are manually re-assigned to the override data type.
Consider the case where the base model set has a data type called ID
which is a String32 and a document with a property called OrderId that
refers to this data type. When you generate a service, a model instance is
created and the document in the service refers to the data type defined at
the base model set. If one were to override the Id data type at the model
instance level to say String16, the SQL type of the OrderId property in the
service will continue to refer to Id at the base model level until one
manually points it to the new overridden data type. In general, it is best to
not generate/override a data dictionary at the model instance level.
Caution: The default name of a new property is “Property1”. If the base model
contains a property named “Property1” and you add a new property to the model
instance, by default this new property will be named “Property1”. If this new property
is named the same as the property in the base model, it will override the property in
the base model and will be color-coded accordingly.
Solution: Change the property name from the default “Property1” value to the desired
name.

Model Data Types vs Database Data Types
Model Data Types vs Database Data Types

ABPP data types abstract out the differences between the different databases on which
the schema is instantiated. The table provided below has a mapping of the data types
in the model and corresponding data types in Oracle and DB2 data bases.
Model Data Type Oracle Data Type DB2 Data Type
BinaryData BLOB BLOB
Boolean CHAR_1 CHARACTER_1
Clob CLOB CLOB
Date DATE DATE
Datetime DATE TIMESTAMP
Double NUMBER_38_4 DECIMAL_31_4
Double_31_4 NUMBER_31_4 DECIMAL_31_4
EncryptedString_31 VARCHAR2_52 VARCHAR_52
EncryptedString VARCHAR2_80 VARCHAR_80
Float NUMBER_38_4 DECIMAL_31_4
Float_31_4 NUMBER_31_4 DECIMAL_31_4
Integer NUMBER_11_0 INTEGER
* Integer_31 NUMBER_31_0 INTEGER
Long NUMBER_20_0 INTEGER
LongString CLOB CLOB
* Long_31 NUMBER_31_0 INTEGER
String VARCHAR2_50 VARCHAR_50
StringList VARCHAR2_50 VARCHAR_50
* StringList_99 VARCHAR2_50 VARCHAR_50
String_99 VARCHAR2_99 VARCHAR_99
Time DATE TIME
Timestamp TIMESTAMP(6) TIMESTAMP
Xml CLOB CLOB
Big Decimal NUMBER_38_4 DECIMAL_31_4


Chapter 3
X-Documents
X-Document is the internal format used by the ABPP run-time to represent the
application’s data models. This chapter provides information on the X-Document
structure and explains the underlying constructs.
The studio presents a complete WYSIWYG environment for building models. Please
refer to the model studio section of the studio user guide for details on building data
models in studio. The studio saves out the data models in .mtt format.
The ABPP run-time only understands the X-Document format. This format is
different than the .mtt format saved out by the studio. So the studio provides a "build"
utility to convert the .mtt files in to X-Document format.
It is not required for ABPP application programmers to understand the structure of X-
Document. They just need to know how to invoke the build utility in the studio to
recreate their X-Documents whenever they change the models in the studio.
This chapter is primarily meant for
z ABPP core development team responsible for the .mtt to X-Document conversion
utility.
z ABPP application teams which have not yet migrated to using the model studio.
Topics:
z Introduction
z Document Identifiers
z Document Index
z Document Properties
z Document Links
z Overlay Documents
z Flex Properties

Chapter 3 X-Documents
Introduction
X-Document is a XML specification to model application data and their relationships.
An X-Document has the following constructs:
z Name (Required): Name of the document.
z Properties (Required): Attributes that the document can contain and the related
data types.
z Identifiers (Optional): These are a set of property values which enable unique
identification of an X-Document instance
z Index (Optional) : These are constructs for efficiently retrieving a set of X-
Document instances which match a query criteria.
z Constraints (Optional): These are conditions which the property values of the X-
Document instances have to adhere to.
z Links (Optional):The links (or relationships), the X-Document has with other X-
Documents.
z Overlay Documents (Optional): These are constructs for extending the X-
Document definition at deployment time.
z Flex Properties (Optional): These are constructs to extend the X-Document
instance dynamically with properties which have not been specified at the time of
X-Document definition.
The following is an example of an X-Document.
<DOCUMENT Name=”CustomerOrder” TableName="MST_CUSTOMER_ORDER"
SurrogateKey="true">
<PROPERTY Name="CreatedBy" Type="string(50)"
ColumnName="CREATED_BY" Required="true"/>
<PROPERTY Name="CreatedDate" Type="date"
ColumnName="CREATED_DATE" Required="true"/>
<PROPERTY Name="ID" Type="string(50)"
Required="true"/>
<PROPERTY Name="TotalPrice" Type="float"
ColumnName="TOTAL_PRICE" Required="true"/>
<UNIQUE PrimaryKey="true|false[optional]"
Name="myPK[optional]">
<KEY Property="ID"/>
</UNIQUE>
<DOCUMENTLINK Name="CO_CREATED_BY" LinkedDocument="User">
<MAP_PROPERTY From="CreatedBy" To="ID"/>
</DOCUMENTLINK>
</DOCUMENT>
In the above example,
| CUSTOMER_ORDER is the name of the document.
| CreatedBy, CreatedDate, ID and TotalPrice are the
properties of the document.
| The CUSTOMER_ORDER document has a relationship with USER document
through the link CO_CREATED_BY.
The following is an example of an instance of a CUSTOMER_ORDER document.

Document Identifiers
<CUSTOMER_ORDER>
<ID Value ="CO_1490" />
<CreatedDate Value ="04/20/2004"/>
<CreatedBy Value ="John Doe"/>
<TotalPrice Value =" 7000.0 "/>
</CUSTOMER_ORDER>
The fields, whose values are NULL, are not contained in the document instance.
Note: An X-Document is similar to a table definition in a RDBMS and the

X-Document instance is like a row in the RDBMS table.
The following sections of this chapter provide details on each of the X-Document constructs
introduced in this section.
Document Identifiers
A document can have more than one set of properties that make it unique. You can
specify each of the property sets by using the UNIQUE tags.
A UNIQUE tag definition consists of the following:
| Set of properties
| Name (Optional)
| PrimaryKey attribute (Optional, Valid Values are true|false)
Note: Only one of the UNIQUE tags can be marked as a Primary Key by setting the
PrimaryKey attribute to true. All properties which are part of the UNIQUE tag
must be marked as required.
The following is an example of a X-Document with more than one unique identifier.
<DOCUMENT Name="PROFILE">
<PROPERTY Name="ID" Type ="string(40)" />
<PROPERTY Name="FIRST_NAME" Type ="string(40)" Required
="true"/>
<PROPERTY Name="LAST_NAME" Type ="string(40)"
Required="true"/>
<PROPERTY Name="DESIGNATION" Type ="string"/>
<PROPERTY Name="PHONE" Type ="string"/>
<PROPERTY Name="SSN" Type ="string" Required="true"/>
<PROPERTY Name="JOB_LEVEL " Type ="int"/>
<UNIQUE>
<KEY Property="FIRST_NAME"/>
<KEY Property="LAST_NAME"/>
</UNIQUE>
<UNIQUE>
<KEY Property="SSN"/>
</UNIQUE>
<UNIQUE PrimaryKey="true">
</UNIQUE>
</DOCUMENT>

In the above example, the sets {ID}, {FIRST_NAME, LAST_NAME}, and {SSN}
uniquely identify the PROFILE documents.
Surrogate Key
Documents with only one Primary Key can specify SurrogateKey as true. When this is
specified, ABPP takes care of generating the value for the Primary Key column for
any new rows added using the ADD_DOCUMENT call. Users can also optionally specify
an IdPrefix attribute which can be used in conjunction to generate surrogate keys.
For example:
<DOCUMENT Name="PARENT" SurrogateKey="true" IdPrefix="PT-">
<PROPERTY Name="ID" Type="string(32)" Required="true"/>
<PROPERTY Name="NAME" Type="string(32)" Required="true"/>
<PROPERTY Name="DATA" Type="LongString"/>
</UNIQUE>
</DOCUMENT>
Upon an ADD_DOCUMENT invocation, ABPP will generate a value for the Primary Key
column ID if one hasn't been specified already. IdPrefix will be used as the prefix for
the generated value. In this case, the ID value could be something like PT-73258.
Please refer document on id generation to configure the id generation scheme for any
document.
Document Index
You can set up indexes on the properties that are frequently used in the query criteria.
You can speed up querying the documents from the database using indexes. You can
set up multiple indexes on a document. An index can have more than one property as
its key.
You can specify an index by using the INDEX tag. INDEX tag definition consists of
the following:
| Name (Optional)
| Set of properties
| Unique attribute (Optional, Valid Values="true|false", Default is false)
You can also specify if the index is unique by specifying Unique="true" attribute on
the INDEX tag.
However, note that using indexes will slow down inserting new rows to the table
because the database re-computes indexes whenever a new row has to be inserted.
The following is an X-Document with indexes.
<DOCUMENT Name="LINE_ITEM">
<PROPERTY Name="ITEM_ID" Type="string(40)" Required="true"/>
<PROPERTY Name="PO_ID" Type = "string(40)" Required="true"/>
<PROPERTY Name="CREATION_DATE" Type="date"/>
<PROPERTY Name="STATE" Type="string"/>
<PROPERTY Name="QUANTITY" Type="int"/>

Document Properties
<PROPERTY Name="INVOICE" Type="float"/>

<PROPERTY Name="SELLER " Type="string"/>
<PROPERTY Name="EXT_ID " Type="string"/>
<PROPERTY Name="ORDER_TYPE" Type="string"/>
<DOCUMENTLINK Name="PO_INFO" LinkedDocument=
"PURCHASE_ORDER">
<MAP_PROPERTY To="ID" From="PO_ID"/>
</DOCUMENTLINK>
<DOCUMENTLINK Name="SELLER_INFO" LinkedDocument="PROFILE">
<MAP_PROPERTY To="ID" From="SELLER_ID"/>
</DOCUMENTLINK>
<INDEX>
<KEY Property="PO_ID"/>
</INDEX>
<INDEX Unique="true">
<KEY Property="EXT_ID"/>
<KEY Property="ORDER_TYPE"/>
</INDEX>
<KEY Property="ITEM_ID"/>
<KEY Property="PO_ID"/>
</UNIQUE>
</DOCUMENT>
In the above example, queries providing values for {EXT_ID, ORDER_TYPE} or
{PO_ID} will be faster because of the indexes that have been set up.
Document Properties
The following are the valid data types for a document property:
| boolean
| string
| encryptedString
| int
| float
| double
| BigDecimal
| date
| datetime
| time
| timestamp
boolean
Syntax:
<PROPERTY Name="IS_TAXABLE" Type="boolean"/>
The valid values of a boolean property is always true or false.

string
Syntax:
Description:
| If you do not specify the length of the string, then a default value of 32 is
assigned by X-Core framework.
| If you need a string size greater than the default, then you should explicitly
specify the size.
Example 1:
In this example the property is assigned a string data type whose maximum size can be
32
Example 2:
<PROPERTY Name="STATE" Type="string(40)"/>
In this example the property is assigned a string data type whose maximum size can be
40.
encryptedString
Syntax:
<PROPERTY Name="PASSWORD" Type="encryptedString(16)"/>
Description:
The encryptedString property is used to represent sensitive information like password,
credit card numbers etc that needs to be stored in the database. The field value is
automatically encrypted prior to storing it in the database and decrypted after retrieval.
For the application code it is equivalent to simple string since X-Core takes care of
encryption or decryption automatically. Please refer to Encryption Configuration
section of X-Config chapter for details on enabling and configuring the encryption
support. If encryption support is not enabled this field behaves as a normal string field.
Example 1:
<PROPERTY Name="PASSWORD" Type="encryptedString(16)"/>
int
Syntax:
<PROPERTY Name="PIN" Type="int"/>
float
Syntax:

Document Properties
double
Syntax:
<PROPERTY Name="INVOICE" Type="double"/>
BigDecimal
Syntax:
<PROPERTY Name="PRICE" Type="BigDecimal"/>
Description:
The BigDecimal property is used to represent a fixed point number. Using this data
type helps avoid precision/rounding problems associated with floating-point
operations using float/double data type.
date
Syntax:
datetime
Syntax:
<PROPERTY Name="PROMISED_DELIVERY_TIME" Type="datetime"/>
Description:
The value of the datetime property is always output as mm/dd/yyyy hh:MM:ss.
For example, 04/23/2001 15:30:45 is the same as the April 23, 2001 3:30 PM and 45
seconds format.
time
Syntax:
<PROPERTY Name="PICK_UP_TIME" Type="time"/>
Description:
The value of the time property is always output as hh:MM:ss. The time type does not
have date component.
timestamp
Syntax:
<PROPERTY Name="LAST_MODIFIED" Type="timestamp"/>
Description:
The value of the timestamp property is always output as mm/dd/yyyy hh:MM:ss SSS.
For example, 04/23/2001 15:30:45 345 is the same as April 23, 2001 3:30 PM and 45
seconds and 345 milliseconds format.

The date, datetime and timestamp differ only in the precision.
Default Values
Default values can be specified in the properties of a document and can be specified in
the X-Document definition.
Here is an example of an x-doc with default values specified on properties:
<DOCUMENT Name="DEFAULTS_TEST" TableName="DEF_TEST">
<PROPERTY Name="ID" Type="string(64)" Default="NONE" />
<PROPERTY Name="DBL_COL1" Type="double" Default="10.0" />
<PROPERTY Name="FLOAT_COL2" Type="float" Default="5.0" />
<PROPERTY Name="INT_COL3" Type="int" Default="0" />
<PROPERTY Name="BOOL_COL4" Type="boolean" Default="true"/>
<PROPERTY Name="DATE_COL5" Type="date" Default="03/31/2006"
/>
<PROPERTY Name="DTM_COL6" Type="datetime"
Default="SYSTEM_DATE" />
<PROPERTY Name="DTM_COL7" Type="datetime" Default="01/01/
2000 10:00:00" />
<PROPERTY Name="TS_COL8" Type="timestamp"
Default="SYSTEM_TIMESTAMP" />
<PROPERTY Name="TIME_COL9" Type="time" Default="22:00:00"/>
</DOCUMENT>
SYSTEM_DATE is a reserved default for assigning the current date time to a
document property.
SYSTEM_TIMESTAMP is a reserved default for assigning the current time stamp to
a document property.
Document Constraints
Constraints on properties of a document can be specified in the X-Document
definition. These constraints will be translated into schema based constraints during
schema generation. ABPP will NOT use the constraints specified during its execution;
it will simply delegate the evaluation of the constraints to the database.
The supported constraints are:
z Valid value constraints
z Constraints involving logical operations and operators (incl. range constraints),
and
z Literal constraints.
Example 1: Valid value constraints
The property is defined in the xdoc document definition as:
<PROPERTY Name="STATUS" Type="string(32)" Default="ACTIVE">
<VALID_VALUES>
<OPTION Value="ACTIVE"/>
<OPTION Value="DORMANT"/>
<OPTION Value="INACTIVE"/>

Document Links
</VALID_VALUES>
</PROPERTY>
Example 2: Constraints with operators
The property is defined in the xdoc document definition as
<PROPERTY Name="WIDTH" Type="int" ColumnName="WIDTH">
<CONSTRAINT>
<AND>
<GREATER_EQUAL Value="300"/>
<LESS_EQUAL Value="700"/>
</AND>
</CONSTRAINT>
</PROPERTY>
Example 3: Literal constraints
The property is defined in the xdoc document definition as
<PROPERTY Name="QUANTITY" Type="double" ColumnName="QTY"
Default="30.0">
<CONSTRAINT>
<OR>
<LITERAL Value="2 * #QUANTITY + #BOH <= 10000"/>
<AND>
<GREATER_EQUAL Value="30"/>
<LESS_EQUAL Value="5000"/>
</AND>
</OR>
</CONSTRAINT>
</PROPERTY>
<PROPERTY Name="PRICE" Type="float" Default="2.0">
<CONSTRAINT>
<LITERAL Value="#PRICE * #QUANTITY >= 60.0"/>
</CONSTRAINT>
</PROPERTY>
Document Links
A document link is conceptually similar to a hyperlink in a HTML document. The
primary motivation of a document link is to navigate the additional information
associated with the document.
The following is a scenario for defining the link to the PURCHASE_ORDER
document:
When you are displaying the details of a LINE_ITEM in a UI, you might want to
provide some information on the PURCHASE_ORDER. It is desirable to have the
PURCHASE_ORDER details served up when you are querying for the LINE_ITEM.
A document link specifies the following:
| The name of the document that is being linked.
| The properties of the current document (From) that are mapped on to the
linked document (To).
| A logical name for the document link.

Example 1:
<DOCUMENT Name="LINE_ITEM ">
..................
..................
<DOCUMENTLINK Name="PO_INFO" LinkedDocument=
"PURCHASE_ORDER" >
</DOCUMENTLINK>
<DOCUMENTLINK Name="ITEM_INFO" LinkedDocument="//CATALOG/
ITEM">
<MAP_PROPERTY To="ID" From="ITEM_ID" />
</DOCUMENTLINK>
</DOCUMENT>
In the above example, a document link called PO_INFO is created. PO_INFO
represents a link between the current document that is LINE_ITEM and the linked
document that is PURCHASE_ORDER. The PO_ID property of the current document
(LINE_ITEM) is mapped on to the ID property of linked document
(PURCHASE_ORDER).
You can also specify a document link with the linked document in another service. In
the above example, a document link called ITEM_INFO is created. ITEM_INFO
represents a link between the current document that is LINE_ITEM and the linked
document that is ITEM. The ITEM document is in a different service (CATALOG)
than the LINE_ITEM. So we provided the fully qualified name for the linked
document.
Example 2:
The following is an example of a document link with more than one property
<DOCUMENT Name="SHIPMENT">
<PROPERTY Name="ITEM_ID" Type="string(40)" Required="true"/>
<PROPERTY Name="PURCHASE_ORDER_ID" Type="string(40)"
Required="true"/>
<PROPERTY Name="PROMISED_DATE" Type="string(40)" />
<PROPERTY Name="PROMISED_QTY" Type="string(40)" />
..................
..................
<DOCUMENTLINK Name="LINE_ITEM_INFO"
LinkedDocument="LINE_ITEM">
<MAP_PROPERTY To="ITEM_ID" From="ITEM_ID"/>
<MAP_PROPERTY To="PO_ID" From="PURCHASE_ORDER_ID"/>
</DOCUMENTLINK>
</UNIQUE>
</DOCUMENT>
Example 3:

Referential Integrity Constraints
The following is an example of multiple link documents attached to the same linked
document
<DOCUMENT Name="ALERT ">
<PROPERTY Name="ID" Type="string"/>
<PROPERTY Name="FROM_USER" Type="string"/>
<PROPERTY Name="TO_USER" Type="string"/>
<PROPERTY Name="MESSAGE" Type="string(255)"/>
<DOCUMENTLINK Name="FROM_USER_INFO"
LinkedDocument="PROFILE">
<MAP_PROPERTY To="ID" From="FROM_USER"/>
</DOCUMENTLINK>
<DOCUMENTLINK Name="TO_USER_INFO" LinkedDocument="PROFILE">
<MAP_PROPERTY To="ID" From="TO_USER"/>
</DOCUMENTLINK>
</DOCUMENT>
In the above example, FROM_USER_INFO and TO_USER_INFO are links to the
same linked document, PROFILE.
Referential Integrity Constraints

Referential integrity constraints ensures that there are no dangling references in your
data. For example, LINE_ITEM document cannot exist without a
PURCHASE_ORDER document. Therefore, every LINE ITEM document instance
must refer to a valid PURCHASE_ORDER instance. This type of constraint is called a
referential integrity constraint and is specified on the document link of the referring
(LINE_ITEM) document.
The referential integrity constraint is defined by specifying FkDeleteRule attribute
on the document link.
The valid values for FkDeleteRule are: RESTRICT, CASCADE and SET_NULL.
z If FkDeleteRule is RESTRICT, any instance of the referred
(PURCHASE_ORDER) document cannot be deleted as long as there exists a
corresponding instance of the referring document.
z If FkDeleteRule is CASCADE, if an instance of the referred
(PURCHASE_ORDER) document is deleted then the corresponding instances of
the referring document will also be deleted.
z If FkDeleteRule is SET_NULL, if an instance of the referred
(PURCHASE_ORDER) document is deleted then the linked properties on
corresponding instances of the referring document will be set to NULL.
To specify a delete rule on a document link, all the "To" properties in MAP_PROPERTY
of the document link must correspond to a primary key or unique key on the referred
document.
The following is an example of a LINE ITEM document with referential integrity
constraints.
<DOCUMENT Name="LINE ITEM">
..................
..................

<DOCUMENTLINK Name="ORDER INFO" LinkedDocument="PURCHASE

ORDER" FkDeleteRule="CASCADE">
<DOCUMENTLINK>
..................
..................
</DOCUMENT>
In the above example document link, ORDER INFO, is flagged with FkDeleteRule as
CASCADE. Whenever a PURCHASE_ORDER instance is deleted, all LINE_ITEM
instances related to the PURCHASE_ORDER instance through the document link are
automatically deleted.
Specifying the FkDeleteRule attribute flag results creates a referential integrity
CONSTRAINT on the LINE_ITEM table in the database. PO_ID property in the
LINE_ITEM table references the ID property of the PURCHASE_ORDER table.
Overlay Documents
Overlay Document enables you to extend an existing document definition to suit the
needs of a specific implementation. Overlay documents allows you to define
additional inline properties and document links to the existing document definition.
The system will apply the additions specified in the overlay document to the existing
document definition. Overlay documents cannot re-define any of the properties or
document links already specified in the existing document.
Please note that you cannot remove any existing properties or document links using
the Overlay document mechanism.
z Important: Inline properties specified in the Overlay document definition are
mapped on as additional columns in the table created for the main document. So you
have to regenerate the schema whenever you change the Overlay document definition.
Example 1:
The following is the example of defining Overlay Document to PURCHASE_ORDER
document.
<OVERLAY_DOCUMENT Name="PURCHASE_ORDER">
<PROPERTY Name="EXTERNAL_ID" Type="string(40)"/>
<PROPERTY Name="ORDER_POINT_ID" Type="string(40)"/>
<PROPERTY Name="ORDER_ORIGIN" Type="string(40)"/>
<DOCUMENTLINK Name="ORDER_POINT_INFO"
LinkedDocument="PROFILE">
<MAP_PROPERTY To="ID" From="ORDER_POINT_ID"/>
</DOCUMENTLINK>
<PROPERTY Name="EXTERNAL_ID" Type="string(40)">
<UNIQUE>
<KEY Property="EXTERNAL_ID" Type="string(40)"/>
<KEY Property="ORDER_ORIGIN" Type="string(40)"/>
</UNIQUE>
</PROPERTY>
</OVERLAY_DOCUMENT>

Flex Properties
In the above example, the PURCHASE_ORDER document will now have 3 additional
inline properties, have a new document link in addition to the ones defined in the
previous example and have a new set of document identifiers
Flex Properties
z Pre-defined Flex Properties
z Dynamic Flex Properties
Flex properties are properties that can be added to the document instance without
regenerating the schema. They are stored in a backup table as name-value pairs.
Retrieving the flex property values is very expensive because it involves a join with
the backup table. Consider using inline properties (using overlay documents) instead
of flex properties wherever possible. Flex properties are recommended only for very
sparsely populated properties.
Pre-defined Flex Properties

Flex properties can be pre-defined by specifying them in the document definition. Pre-
defined flex properties can be of the following Types: string (max size: 255), int, float,
double and datetime.
Example of Pre-defined Flex Properties:
<DOCUMENT Name=" CAR">
<PROPERTY Name="MODEL" Type="string(40)" Required="true" />
<PROPERTY Name="MAKE" Type="string(40)" Required="true"/>
<PROPERTY Name="YEAR" Type="date" Required="true"/>
<PROPERTY Name="HORSE_POWER" Type="float"/>
<FLEX_PROPERTIES>
<PROPERTY Name="PRICE" Type="float"/>
<PROPERTY Name="INT_COLOR" Type="string"/>
<PROPERTY Name="EXT_COLOR" Type="string"/>
<PROPERTY Name="INTRO_DATE" Type="date">
<PROPERTY Name="SEATING" Type="int"/>
<PROPERTY Name="AXLE_RATIO" Type="float"/>
<PROPERTY Name="CRASH_RATING" Type="int"/>
<PROPERTY Name="TIRE_WIDTH" Type="float"/>
<PROPERTY Name="NUM_VALVES" Type="int"/>
<PROPERTY Name="DISPLACEMENT" Type="float"/>
</FLEX_PROPERTIES>
<KEY Property="MODEL"/>
<KEY Property="MAKE"/>
<KEY Property="YEAR"/>
</UNIQUE>
</DOCUMENT>
You can use the pre-defined flex properties in queries just like the other regular
properties. In the above example, a CAR_UA table is created along with the CAR
table to hold the pre-defined flex properties of the CAR document instances.
A typical CAR instance could be:
<CAR>

<MODEL Value="INTEGRA"/>
<MAKE Value="Acura"/>
<YEAR Value="04/20/2000"/>
<HORSE_POWER Value="2.5"/>
<PRICE Value="19000"/>
<INT_COLOR Value="black"/>
<EXT_COLOR Value="red"/>
<NUM_VALVES Value="16"/>
</CAR>
Note: INT_COLOR, EXT_COLOR and NUM_VALVES are pre-defined flex fields.
Dynamic Flex Properties

You can enable a document instance to add any flex property on the fly by specifying
UserAttributes="true" in the document definition. Dynamic flex properties can only
be of string data Type of maximum length 255. This is a key limitation as compared to
pre-defined flex properties. A document can have dynamic flex properties in addition
to having pre-defined flex properties.
Example of a PURCHASE_ORDER Document Definition:
The following is a PURCHASE_ORDER document definition of a typical X-
Document, that has been extended to support dynamic flex properties.
<DOCUMENT Name="PURCHASE_ORDER" UserAttributes="true" >
<PROPERTY Name="BUYER_ID" Type="string(40)"/>
<PROPERTY Name="LAST_MODIFIED" Type="timestamp"/>
<PROPERTY Name="PROMISED_DELIVERY_TIME" Type="datetime"/>
<PROPERTY Name="PIN" Type="int"/>
<PROPERTY Name="COMMENT" Type="LongString"/>
<DOCUMENTLINK Name="LINE_ITEMS"
LinkedDocument="LINE_ITEM" > <MAP_PROPERTY
To="PO_ID" From="ID"/>
</DOCUMENTLINK>
<DOCUMENTLINK Name="BUYER_INFO" LinkedDocument="PROFILE">
<MAP_PROPERTY To="ID" From="BUYER_ID"/>
</DOCUMENTLINK>
</UNIQUE>
</DOCUMENT>
PURCHASE_ORDER document is defined with UserAttributes="true" attribute. This
enables the PURCHASE_ORDER document to add dynamic flex properties on the
fly. In the above dynamic flex properties example, the PURCHASE_ORDER_UA
table will be created along with the PURCHASE_ORDER table to hold the flex
properties of the PURCHASE_ORDER document instances.
PURCHASE_ORDER instances can now contain properties that were not specified in
the document definition.

Flex Properties
Example of a PURCHASE_ORDER Instance with Properties:

A typical PURCHASE_ORDER instance could be:
<PURCHASE_ORDER>
<ID Value="PO_01">
<BUYER_ID Value="buyer01"/>
</ID>
<CREATION_DATE Value="04/20/2000"/>
<LAST_MODIFIED Value="09/17/2000 15:30:42 750"/>
<PROMISED_DELIVERY_TIME Value="09/17/2000 15:30:42"/>
<STATE Value="open"/>
<PIN Value="1"/>
<INVOICE Value="7000.0"/>
<MY_ATTRIBUTE_A Value="This is a dynamic attribute"/>
<MY_ATTRIBUTE_B Value="Another dynamic attribute"/>
</PURCHASE_ORDER>
Note: MY_ATTRIBUTE_A and MY_ATTRIBUTE_B properties were not part of

the PURCHASE_ORDER document definition. The MY_ATTRIBUTE_A
and MY_ATTRIBUTE_B properties are defaulted to data type string.
ABPP provides a number of built-in operations for manipulating X-Documents. For

details, refer chapter on “Data Access Components”.


Chapter 4
X-Commands
ABPP enables building service oriented applications. Every application is a collection

of services. Each service in turn is a named container for implementing a set of related
business functionality. It is possible for a service to be part of multiple applications.
Example 1:
A sales order management application built on ABPP is composed of the following
services:
z Alerting: This service provides the functionality of notifying users when things of
interest (Order Shipped Late etc.) happen in the application.
z EnterpriseModeling: Represents the business entities like organization, locations,
products and items which are used by the application
z OrderExecution: Manages the life cycle of orders from creation through
fulfillment.
z Invoicing: Creates and tracks the invoices issued against orders
Typically each service exposes its functionality by exposing a set of public APIs (or
functions) which can be invoked by external systems or by other services deployed
within the application. Each API exposed by a service is uniquely identified by its
name. It should also have a well defined input and output signature.
Example 2:
The OrderExecution service of Example 1 will typically expose the following public
APIs (or functions) to external applications:
z createOrder: External applications can invoke this API to create new orders in the
application
z getOrderStatus: External applications can invoke this API to get the status of
existing orders in the application

Chapter 4 X-Commands
Note: In ABPP we refer to an API as command. As such this guide uses command
to refer to an API or function.
There are 2 types of commands in ABPP:

z User Commands: These are commands created by users (consultants or
development teams building their products on ABPP) to define & implement the
APIs of the services created by them.
z System Commands: These are built in commands provided by the system.
In this chapter, we will:

z Provide information on built-in system commands
z Describe how to define and implement user commands.
z Describe how to invoke system and user commands
All commands accepts an input XML document and returns an output XML
document. The general structure of the input and output XML document for user and
system commands are described in the respective sections.
System Commands
ABPP provides a lot of built in commands to perform server management tasks like:
shutting down the server, changing log levels, monitoring resource statistics, killing
workflows etc. Most of the built in commands (example, shut down command) can
have a potentially disruptive impact and hence should be exercised only by the users
administering the ABPP server.
There are 2 types of system commands:
z General commands: Commands not specific to any ABPP construct. These are
described in detail in this section.
z Specific Commands: Commands specific to an ABPP construct. These are
described in the chapter pertaining to the construct. Here are some examples:
| Commands for managing workflow instances are described in the Workflow
Commands section of Workflow Concepts chapter.
| Commands related to purge specification are described in the Invoking/
Triggering Purge section, located in the Programmer’s Reference Guide, Part
Two, in the Purge chapter.
General structure of the command input/output XML documents:
z The root tag name of input XML document should be the same as the command
name. The body of the input XML contains any parameters
required by the command. Here is an example of the input:
<SET_LOG_LEVELS>
<LOG_LEVEL Value="Error" />
<LOG_LEVEL Value="Exception" />

System Commands
<LOG_LEVEL Value="Warning" />

</SET_LOG_LEVELS>
In this example, SET_LOG_LEVELS is the name of the command.
z The root tag of the output XML document should be <RESPONSE>. The body of
the output XML is specific to the command. Here is an example of the output:
<RESPONSE Status="Success"/>
The rest of this section provides information on the generic system commands
provided by ABPP.
GET_RESOURCE_STATS
Description:
This tag is used to get statistics on the resources (DB Connections, Memory etc.) used
by the process. This can also be used as a ping to monitor if the server is alive. This
provides valuable information for diagnosing server hangs or if the server is out of
resources (jdbc connections, memory etc.).
Input Syntax:
<GET_RESOURCE_STATS />
Example 1:
Sample Input:
<GET_RESOURCE_STATS />
Sample Output: (Comments have been added on each of the resource information
being returned to make it easy to comprehend)
<RESPONSE Status="Success">

<DBConnectionStats TotalConnectionsMade="3"
ConnectionsInPool="3" />

<MemoryStats TotalMemory="3629056" FreeMemory="1239344"
UsedMemory="2389712" />

<ThreadGroups NumThreads="12">
<ThreadGroup Name="system" NumThreads="3">
<Thread Name="Reference Handler" />
<Thread Name="Finalizer" />
<Thread Name="Signal Dispatcher" />

</ThreadGroup>
<ThreadGroup Name="main" ParentGroup="system"
NumThreads="3">
<Thread Name="Thread-5" />
<Thread Name="XServer" />
<Thread Name="DestroyJavaVM" />

</ThreadGroup>

<ThreadGroup Name="Task Thread Group" ParentGroup="main"

NumThreads="4">
<Thread Name="Asynch Thread-0" />
<Thread Name="Asynch Thread-1" />
<Thread Name="WorkerThread-0" />
<Thread Name="WorkerThread-1" />
</ThreadGroup>
<ThreadGroup Name="Pooled Thread Group"
ParentGroup="main" NumThreads="2">
<Thread Name="PooledThread-1">
<PooledThreadInfo UsedByRunnable="None" />
</Thread>
<Thread Name="PooledThread-2">
<PooledThreadInfo UsedByRunnable="None" />
</Thread>
</ThreadGroup>
</ThreadGroups>

<AsynchTasks QueueSize="0" />
</RESPONSE>
GET_BUILD_INFO
Description:
This tag is used to get the build and version information of the running Xserver.
Input Syntax:
<GET_BUILD_INFO/>
Example:
Sample Input:
<GET_BUILD_INFO/>
Sample Output:
<Implementation-Title Value="ABPP Server" />
<Implementation-Version Value="6.2.x" />
<Implementation-Vendor Value="i2 Technologies, Inc." />
<Build-Date Value="Nov-16-2005 11:28 AM" />
<Build-Number Value="0612" />
</RESPONSE>
ENABLE/DISABLE/SET_LOG_LEVELS
Description:
These commands are used to dynamically change log levels on the services deployed
on the server. Enable/Disable log levels command will only enable/disable log levels
explicitly specified in the command for the service. Set log levels request will enable
log levels explicitly specified in the command and disable all other log levels for the
service.

System Commands
Changing log levels is very useful in collecting valuable debugging information in

production environments. Typically production environments run the server in back-
ground with Error, Exception and Warning log levels turned on to optimize
performance. To diagnose any functional errors noticed on the server, it is necessary to
enable/set the log levels to the desired levels and collect the information. Once the
information is collected the server can be reset to the levels prior to this exercise by
disabling/resetting the log levels.
Typically this command is posted on to the server URL using poster class.
Input Syntax:
<ENABLE_LOG_LEVELS
ServiceName="service-name [Optional=true]">
<LOG_LEVEL Value="log level" Repeatable="true"/>
</ENABLE_LOG_LEVELS>
<DISABLE_LOG_LEVELS
</DISABLE_LOG_LEVELS>
<SET_LOG_LEVELS
</SET_LOG_LEVELS>
Attributes:
ServiceName: Name of the service. If null then it is applied to the xserver.
LOG_LEVEL.Value: The valid log level values are:
| All
| Debug
| EnterTrace
| Error
| Exception
| ExitTrace
| Info
| InterServiceCallTrace
| IntraServiceCallTrace
| SqlCallTrace
| Warning
| XPathFnTrace
Example 1:
Sample Input:
<SET_LOG_LEVELS ServiceName="myService">
<LOG_LEVEL Value="Info" />
<LOG_LEVEL Value="SqlCallTrace" />

<LOG_LEVEL Value="ExitTrace" />

</SET_LOG_LEVELS>
Sample Output:
The above command sets Error, Exception, Info, SqlCallTrace and ExitTracelog levels
on the service, myService. All other log levels on myService are disabled.
Example 2:
Sample Input:
<DISABLE_LOG_LEVELS ServiceName="myService">
<LOG_LEVEL Value="SqlCallTrace" />
<LOG_LEVEL Value="Debug" />
</DISABLE_LOG_LEVELS>
Sample Output:
The above command disables SqlCallTrace and Debug log levels on myService. All
other log levels on myService are not affected by this request.
GET_LOG_LEVELS
Description:
This command will retrieve the log levels for a set of services or all services deployed
in the server VM.
Input Syntax:
<GET_LOG_LEVELS>
<CHOICE_OF>
<CHOOSE>
<LOG_LEVEL ServiceName="ALL[Type=Constant]"/>
</CHOOSE>
<CHOOSE>
<LOG_LEVEL ServiceName="serviceName"
Repeatable="true"/>
</CHOOSE>
</CHOICE_OF>
</GET_LOG_LEVELS>
Attributes:
LOGLEVEL.ServiceName: If ServiceName is ALL then the log levels for all the
services is returned. Otherwise the log levels for the service names in the command
will be returned.
Output Syntax:
<RESPONSE>
<LOG_LEVELS ServiceName="service-name" Repeatable="true">
<LOG_LEVEL Name="logLevelName" State="Yes|No"
Repeatable="true"/>
</LOG_LEVELS>
</RESPONSE>
Attributes:

System Commands
LOG_LEVELS.ServiceName: Service name for which log levels are retrieved.

LOG_LEVEL.Name: Name of the log level
LOG_LEVEL.State: If yes, log level is enabled. Otherwise it is disabled.
Example:
Sample Input:
<GET_LOG_LEVELS>
<LOG_LEVEL ServiceName="EM" />
<LOG_LEVEL ServiceName="CATALOG" />
</GET_LOG_LEVELS>
Sample Output:
<LOG_LEVELS ServiceName="EM">
<LOG_LEVEL Name="Error" State="Yes" />
<LOG_LEVEL Name="Exception" State="Yes" />
<LOG_LEVEL Name="Info" State="No" />

</LOG_LEVELS>
<LOG_LEVELS ServiceName="CATALOG">
<LOG_LEVEL Name="Error" State="Yes" />
<LOG_LEVEL Name="Exception" State="Yes" />
<LOG_LEVEL Name="Info" State="No" />

</LOG_LEVELS>
</RESPONSE>
CLEAR_ALL_LOGS
Description:
This command will truncate log files for all the services deployed in the VM. This
utility can be used in doing periodic log file back ups without bouncing the server in
production environments. Here is one way to do log file backup:
1. Copy the existing logs in to archive folder
2. Truncate the log files using this command.
Input Syntax:
<CLEAR_ALL_LOGS />
Example:
Sample Input:
<CLEAR_ALL_LOGS />
Sample Output:
DROP_CACHE
Description:

This command will drop global cache of X-Document instances for all the services
deployed in the VM. This command is applicable only if any of the X-Documents
have global cache turned on. If data is changed on the database directly then you will
need to drop cache to avoid accessing stale cache.
Input Syntax:
<DROP_CACHE />
Example:
Sample Input:
<DROP_CACHE />
Sample Output:
BROADCAST
Description:
This command will execute the embedded command on the locally deployed service
and also broadcast it to the remote servers, registered with the same locator, on which
this service is deployed.
Input Syntax:
<BROADCAST>
<EmbeddedCommand ServiceName="abc">
<ANY />
</EmbeddedCommand>
</BROADCAST>
Example 1:
Sample Input:
<BROADCAST>
<DROP_CACHE ServiceName="EM" />
</BROADCAST>
Executing the above requests on a server VM will:
1. Drop cache on the server process if EM service is locally deployed
2. Broadcast drop cache to all remote server processes where EM is deployed.
This command will result in drop cache executed on all server VMs where EM is
deployed.
Sample Output:
Example 2:
Sample Input:
<BROADCAST>
<SET_LOG_LEVELS ServiceName="EM">
<LOG_LEVEL Value="Warning" />
</SET_LOG_LEVELS>
</BROADCAST>

System Commands
The above request can be used to set the log levels for EM services on all server VMs
where EM is deployed.
Sample Output:
SHUT_DOWN
Description:
This command will shut down the server gracefully. The server will execute the
following steps as part of the shut down:
1. Un-register all the services and stop accepting incoming requests through the
listener port
2. Invoke pre shut down actions registered with each of the deployed services. An
example of a pre shut down action is disconnecting from any in-bound message
queues subscribed by that service. Here is an example of a pre shut down rule:
Example of a Pre Shut Down Rule
<DEFINE_PRE_SHUTDOWN>
<RULE>
<ACTION>
<PRINTLN Value="Pre-Shutdown rule invoked" />
</ACTION>
</RULE>
</DEFINE_PRE_SHUTDOWN>
3. Wait for all the (queued up + currently executing) requests in the JVM to
complete.
4. Invoke post shut down actions registered with each of the deployed services. An
example of a post shut down action is cleaning up any resources acquired by that
service. Here is an example of a post shut down rule:
Example of a Post Shut Down Rule
<DEFINE_POST_SHUTDOWN>
<RULE>
<ACTION>
<PRINTLN Value="Post-Shutdown rule invoked" />
</ACTION>
</RULE>
</DEFINE_POST_SHUTDOWN>
5. Clean up all the database connections.
Input Syntax:
<SHUT_DOWN />
Example:
Sample Input:
<SHUT_DOWN />
Sample Output:

SET_XSERVICE_PARAM
Description:
This command will dynamically change the service param of a service. The change is
valid only till the server is bounced. So this command is primarily useful for
debugging without having to bounce the server.
Input Syntax:
<SET_XSERVICE_PARAM Name="param-name" Value="param-value" />
Note: The service name on which this command should be executed is specified in
the command envelope. Please see the Command Envelope section for
details.
Example:
Sample Input:
<SET_XSERVICE_PARAM Name="dummyDFSplitSchedule" Value="true" />
This command will set the dummyDFSplitSchedule service
parameter to true on the service identified by the command
envelope.
Sample Output:
User Commands
This section describes the essential elements of a user command. The implementation
sub-section discusses the various options for creating user command.
Definition
The command definition describes the information that is required by any one (client)
who wants to invoke the command.
General structure of the command input/output XML documents:
The general structure of the input/output XML documents (defined as part of the
signature) of a user command should conform to the following:
z The root tag of command input xml document should be <REQUEST>. The
Name attribute on the root tag should be the command name. Here is an example
of the input XML document:
<REQUEST Name="receiveApproveEvent">
<FCST_LINE_ID Value="F-123" />
</REQUEST>
z The root tag of command output xml document should be <RESPONSE>. Here is
an example of the output XML document:
<RESPONSE>
<_RESULT Value="SUCCESS" />
</RESPONSE>

User Commands
ABPP provides a special construct, request_descriptor, for providing the definition.

This construct provides the signature (name, input & output XML structure) of the
command.
Here are the details of the request_descriptor construct along with an example:
request_descriptor
Description
This construct is used for providing the command definition separately from the
implementation.
Syntax:
<request_descriptor Name="name-of-command"
Access="Public|Protected|Private[Default=Protected]"
Category="Fcst Analysis[Optional=true]"
DefaultHandler="name-of-default-command"
Externalize="true|false[Default=false]"
JMSConnection="connection-name[Optional=true]"
ValidateSignature="true|false|default[Optional=true]">
<API_DOC>
<INPUT>
<REQUEST Name="name-of-command">
<ANY/>
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<ANY/>
</ON_SUCCESS>
<ON_EXCEPTION Optional="true">
<ANY/>
</ON_EXCEPTION>
</OUTPUT>
</API_DOC>
<keys Optional="true">
<key Repeatable="true" Value="x-path-referencing-
command-input-attributes/text" />
</keys>
</request_descriptor>
Note: The most important elements/attributes of the construct are shown in bold.
Attributes:
z Name (Required): Name of the command. This will be used as an unique
identifier for the command within the service.
z Access (Optional): Privilege required for invoking the command. The valid access
levels are Public, Protected and Private. The Default is Protected. Here is the
description of each of these levels:
| Public: Can be invoked by all clients.

| Protected: Can only be invoked by the owning X-Service and other co-located
X-Services. This is the default access level.
| Private: Can be invoked only by the owning X-Service.
z Category (Optional): This is mainly for grouping related set of commands
together for visualization within the studio.
z Externalize (Optional): Default=false. If true then this command can be invoked
through JMS. Externalizing a command binds the command to a JMS queue. The
command can then be executed by publishing a JMS message on the queue.
Please refer JMS Support, located in the Programmer’s Reference Guide, Part
Two, for further details.
z JMSConnection(Optional): Name of the JMSConnection. This attribute is
mandatory if Externalize is true. The JMSConnection encapsulates the JMS
queues to be used for reading the command input and writing the command
output. Please refer JMS Support, located in the Programmer’s Reference Guide,
Part Two, for further details.
z DefaultHandler(Optional): This is the name of the command in case there is no
concrete implementation is associated with this definition. Typically the default
handler will be used to output a nicely formatted error message. Any output
provided by the default handler should conform to the output signature provided
by the API_DOC.
z keys.key.value (Required): This identifies attributes/text on the input XML
document using X-Path expressions. The input XML document can be referenced
in the X-Path expressions using the implicit variable, thisParam. You can provide
multiple of these key values. These key values are concatenated to generate an
identifier from the command input. This identifier is then used to locate the event
node of the workflow instance which provides the implementation for this
command. Please see the Event Node section for more details.
z ValidateSignature (Optional): This attribute can be used to enable/disable API
signature validation for this command. If the attribute is set to true or false, it will
override the API signature validation set at service level. If the attribute is not
specified or set to default then it will use the API signature validation set at
service level. Refer ValidateApiSignature attribute in Service Config section for
details on setting API signature validation on the service. If the API signature
validation is enabled for example, attribute is true) then the input & output of this
command is validated to ensure conformance with the corresponding signature
(structure, required elements & attributes, data types etc) defined in the
API_DOC.
Elements:
z API_DOC (Optional): The API_DOC describes the structure of the input and
output XML documents of the command. Defining the API_DOC is analogous to
creating an XSD (xml schema definition) for the input & output XML documents
of the command. Please refer to the API_DOC Language Extensions sction,
located in the Programmer’s Reference Guide, Part Two, in the Web Service
Definitions for details on specifying the API_DOC.

User Commands
Note: It is strongly recommended to provide the API_DOC as part of the command

definition. In future releases, this will be made mandatory.
Example:
<request_descriptor Name="receiveApproveEvent" Access="Public"
Category="Fcst Analysis"
DefaultHandler="fcstApprovalErrorHandler" Externalize="true"
JMSConnection="TestConnection">
<API_DOC>
<INPUT>
<REQUEST Name="receiveApproveEvent">
<FCST_LINE_ID Value="xxx[Type=string]" />
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE>
<RESULT Value="SUCCESS[Type=Constant]" />
</RESPONSE>
</ON_SUCCESS>
<ON_EXCEPTION>
<RESPONSE>
<RESULT Value="ERROR[Type=Constant]">
<ERROR_CODE Value="xxx" Optional="true"
/>
</RESULT>
</RESPONSE>
</ON_EXCEPTION>
</OUTPUT>
</API_DOC>
<keys>
<key Value="$thisParam/FCST_LINE_ID/@Value" />
</keys>
Here is an example of the default handler command:

<DEFINE_METHOD Name="fcstApprovalErrorHandler"
Access="Private">
<ACTION>
<APPEND_TO_XML DocVar="thisReturn">
<RESULT Value="ERROR">
<ERROR_CODE Value="NO_IMPL_PROVIDED" />
</RESULT>
</APPEND_TO_XML>
</ACTION>
</DEFINE_METHOD>
Implementation
The command implementation encapsulates the logic to be performed when the
command is invoked. This logic should produce the output XML document which

conforms to the output structure specified in the API_DOC section of the command
definition. The implementation logic is expressed using the ABPP programming
language, X-Rules. So it is necessary for you to have an understanding of X-Rules to
implement commands.
There are 2 options for implementing your commands in ABPP. Both of these are
described below:
Inline the implementation along with the command definition

Typically any changes in the command definition will also require a change in its
implementation. So having the implementation inline with the definition will make it
more convenient to keep them in sync. DEFINE_METHOD X-Rule construct.allows
you to provide the command definition and also inline the implementation. The
DEFINE_METHOD construct includes all the key elements/attributes (Name,
API_DOC & Access) required for command definition. So there is no need to create
the request_descriptor in this approach.
Provide the implementation separate from the definition

There are a few situations where providing the implementation separately from the
definition might have its advantages. Here are some examples:
Example 1:
Assume that you are creating an Alerting service. The Alerting service embeds the
logic to identify the users for the various alerts configured in this service. Typically
the notification preferences (email, on-line alerts etc.) of users are managed as part of
the “user-security” service which manages the user profile. In order to send
notifications, the Alerting service would have to explicitly invoke some API on the
user-security service to get the notification details. This creates a dependency of
Alerting service on the user-security service.
If the Alerting service were to work with different types of user-security service then
the dependency is not desirable. One way to resolve the issue is to just provide the
definition of the “notification details” command within the Alerting service. Any
application which wants to use the Alerting service can provide the implementation
for the command separately (using DEFINE_IMPLEMENTATION construct) in
another service. Whenever the Alerting service invokes the command, it is
transparently re-directed to the implementation associated with the command.
Example 2:
Assume that you are trying to implement a command, createSalesOrder, for creating
sales orders. The command logic is complex and involves the following sequential
steps:
z Validating the command input. This step should ensure that the new order is
validated against all the business rules.
z Computing the order value. This step might involve several sub-steps to
determine the state and county taxes.

Invoking Commands
z Performing credit check for the order value on the customer issuing the order.
z Generating the order fulfillment plan.
z Posting the order details to the ware-house identified by the fulfillment plan
Expressing the sequential steps as a workflow will help you visualize and organize
your logic better than just expressing them as X-Rule code. So you might want to
create a workflow and associate it’s start node with the command definition. When the
command is invoked, the workflow will be executed transparently. The framework
will provide command input as input to the workflow. The workflow output will be
sent out as the command output.
To create commands using this option:

z Create the command definition through the request_descriptor construct.
z After creating the request descriptor, associate an implementation with it using
one of the following approaches:
| Associate the request_descriptor with a specialized X-Rule type called
DEFINE_IMPLEMENTATION.
| Associate the request_descriptor with either the Start Node or Event Node of
the workflow. In this case, the command implementation is provided by the
workflow.
Invoking Commands
The user & system commands of a service are invoked by:
z External clients
| Posting to ABPP Server URL
| Posting to Web Server URL
z Commands of a services issuing other commands defined within the same service
or other services deployed within the server. Example: The order creation
command of ORDER_ADMIN service might issue a command on the
ORDER_PROMISING service to get the order fulfillment plan. Typically the
internal command execution is performed through X-Rules. Please refer to
Command Components section of X-Rules chapter for details.
External clients can invoke commands of an ABPP service by posting HTTP requests
on to the server URL where this service is deployed.
It is also possible for external clients to invoke commands of an ABPP service by
posting HTTP requests via the Web Server Servlet provided by ABPP. The URL to
use would be of the form, https://your-webserver-url/abppcommand where
abppcommand is the name of the ABPP command servlet. The advantages of using
this mechanism include authentication of invocations using the Active User Security
service of ABPP, encryption of authentication parameters by using https, web session
maintenance, and posting to different URLs participating in an SSO session.

A single HTTP request can contain multiple commands of a service enclosed within
an envelope. There are certain semantic associated with executing the commands
within an envelope.
In this section, we will discuss:
z Structure of the command envelope. We will also describe the semantics
associated with it.
z Different utilities provided by ABPP for posting the HTTP request externally on
to the server URL.
Command Envelope
ABPP has a special construct, REQUESTS, for specifying the command envelope.
This construct is explained in detail below with examples.
REQUESTS
Description:
Any command input issued externally on ABPP must be enclosed within REQUESTS
tag. You can have multiple command input xml documents within a REQUESTS tag.
The input xml documents are executed sequentially in the order they occur within the
REQUESTS tag.
Commands can invoke database operations and request the execution of other
commands asynchronously as part of their execution. All database operations issued
when executing commands contained within REQUESTS tag is part of a single
transaction.
If the execution of any command within a REQUESTS tag results in an exception:
1. All database operations issued as part of executing the commands, contained
within the REQUESTS tag, will be rolled back.
2. All input xml commands that occur after the current command within the
REQUESTS tag will not be executed.
3. All asynchronous commands requested for execution as part of executing the
commands, contained within the REQUESTS tag, will be discarded.
If all commands contained within a REQUESTS tag execute successfully:
1. All database operations issued as part of executing the commands will be
committed
2. All asynchronous commands requested for execution as part of executing the
commands will be submitted for execution.
Input Syntax:
<REQUESTS ServiceName="name-of-service" UserName="abpp-login-
id[Optional=true]" Password="abpp-password[Optional=true]"
TimingStats="0|1|2[Optional=true]" UserId="xxx[Optional=true]">
<CHOICE_OF Repeatable="true">
<CHOOSE>
<REQUEST Name="user-command-name" Repeatable="true"
Any="true">

Invoking Commands



</REQUEST>
</CHOOSE>
<CHOOSE>
<system-command-name Repeatable="true" Any="true">


</system-command-name>
</CHOOSE>
</CHOICE_OF>
</REQUESTS>
Attributes:
z ServiceName (Optional): This is the service on which the commands will be
executed. If a ServiceName is provided, then this service should be deployed on
the server on which this command is posted. If no service name is provided then it
will be executed on the server.
z UserId (Optional): Id of the user issuing the commands. Note: This attribute is not
required if calling the command through authenticating servlet. The servlet will
populate this attribute based on the session.
z UserName (Required only if calling to authenticate with servlet): The ABPP
Active Security Service login id. Note: This is same as the login id you would
enter in the web browser based UI. The UserId attribute above is the ID of the user
corresponding to this login id.
z Password (Required only if calling to authenticate with servlet): The ABPP
Active User Security Service password corresponding to the UserName.
z TimingStats (Optional): This attribute provides timing information on command
execution and can be useful for performance tuning. Here is the details provided
for each of the timing levels:
| TimingStats=0: the output will contain the start time, end time and total
elapsed time on the server.
| TimingStats=1: In addition to the details provided by TimingStats=0, the
output will contain elapsed time for each of the database and remote
invocations issued.
| TimingStats=2: In addition to the details provided by TimingStats=1, the
output will contain elapsed time for each of the commands invoked.
Output Syntax:
<RESPONSES Status="Success|Error" Comment="Error indicates
failure" Description="contains description of the error">
<RESPONSE Status="Success|Error" Repeatable="true">

</RESPONSE>
</RESPONSES>
Example 1:
Input:

<REQUESTS ServiceName="myService">
<REQUEST Name="echoTest1">
<echoText>HelloWorld</echoText>
</REQUEST>
<REQUEST Name="fetchItems" />
<REQUEST Name="doSomething" />
</REQUESTS>
Successful Response:
<RESPONSES Status="Success">

</RESPONSE>

<Item>
<ID Value="I5" />
<UnitPrice Value="20" />
<Name Value="Optical Instrument" />
<OrgId Value="Velocity" />
</Item>
</RESPONSE>

<RESULT Value="SUCCESS" />
</RESPONSE>
</RESPONSES>
Example 2:
Assume that fetchItems command in Example 1 threw an exception while fetching
Item information from database.
Exception Response:
<RESPONSES Status="Error">

<ID Value="I1" />
</RESPONSE>
<RESPONSE Status="Error" Description="Failed to connect to
database">

</RESPONSE>
</RESPONSES>
In this example, execution of fetchItems resulted in an exception. So the command,

doSomething, did not get executed. The RESPONSES tag contains the output of all
commands executed up to the point where the exception is thrown. All database
operations issued prior to the exception are rolled back.
Example 3:

Invoking Commands
This example response shows the result of sending invalid user name/password, or if
for some reason the request could not be authenticated by the Active User Security
Service of ABPP.
<REQUESTS ServiceName="myService" UserName=”seller1”
Password=”seller1pwd”>
<REQUEST Name="echoTest1">
</REQUEST>
<REQUEST Name="fetchItems" />
<REQUEST Name="doSomething" />
</REQUESTS>
Exception Response:
<RESPONSE Status="Error" Description="NOT_LOGGED_IN">
</RESPONSE>
</RESPONSES>
In this example, the call to execute a command through ABPP Command Servlet
failed the authentication process. If the authentication had succeeded, the response
would have been same as in Example 1.
Utilities for Posting Commands

Description:
Commands can be posted on to the server by one of the following methods:
1. Using a standard HTTP client, post the XML, containing the commands enclosed
within the REQUESTS tag, directly on the server URL. Ensure that the
ServiceName specified on the REQUESTS tag is deployed on the server. ABPP
packages a utility java class, com.i2.xcore.net.Poster, to post requests to the server
URL.
2. Using the same XML as above, post to the ABPP Command Servlet. The URL
would be of the form: https://your-web-server/abppcommand where
“abppcommand” is the name of the servlet deployed in ABPP as part of your
webserver.
z If you use this mechanism to invoke ABPP commands, you must include
the UserName and Password xml attributes in the REQUESTS tag the
first time (or when starting a new session) you invoke the servlet. The
authentication will be done using the ABPP Active Security Service.
z Once authenticated, the requests xml would be passed on to the ABPP
server for processing. The response from ABPP API would be passed
back to the caller of the servlet.
z In case authentication fails for any reason, the servlet will return an error
NOT_LOGGED_IN.
z Note that once a call is made which has authenticated the UserName and
Password, you can use the same session (by passing back the cookies) to
make additional command calls without sending the UserName and

Password. In other words, if you pass back the cookies of the session, the
UserName and Password attributes would not be expected by the servlet
(and be ignored) if the session related to the cookies is still active.
z Both http and https may be used, but it is recommended to use https in
order to secure the connection having messages with UserName and
Password.
3. In the studio development environment, You can post commands to the server
using the Studio’s poster dialog. Refer to Studio user guide for details on this.
Example 1:
This example shows how to post the commands saved in a file on to the server and
save the server response on to a file using the com.i2.xcore.net.Poster java class
provided by ABPP.
For this example, assume that:
1. ABPP run-time is installed in C:\i2\ABPP\6.2.7 folder. You should find a bre
folder under the folder mentioned above. The bre folder is installed as part of your
ABPP installation
2. The input xml document, containing the commands enclosed by REQUESTS tag.
is saved on to a file myInput.xml in C:\i2\ABPP\6.2.7\bre\bin folder. The contents
of this file should be similar in structure to the example provided as part of
REQUESTS construct.
3. You have a server running on URL: http://someMachineName:4444/.
Open a DOS command prompt. Issue the following commands:
a. cmd> cd C:\i2\ABPP\6.2.7\bre\bin
b. cmd> plenv.cmd
c. cmd> java com.i2.xcore.net.Poster http://someMachineName:4444/
myInput.xml myOutput.xml
Executing (a)-(c) will result in the commands contained in myInput.xml to be
executed. The output of the commands will be saved as an xml document in
myOutput.xml in the current directory.
Poster class provides you a variety of options on posting the xml file on to the server.
You can see the options by following through the following steps:
a. cmd> cd C:\i2\ABPP\6.2.7 \bre\bin
b. cmd> plenv.cmd
c. cmd> java com.i2.xcore.net.Poster
Executing (a)-(c) will result in options displayed on the DOS prompt.
You can also use the Poster class to programmatically post the requests on to a server
URL.
Example 2:
This example shows how to post the commands saved in a file on to the ABPP
Command Servlet. In addition to the assumptions mentioned in previous example

Invoking Commands
assume you have the web server setup with ABPP command servlet at URL: https://
someMachineName:7002/base/abppcommand
Using HttpClient software utility, one could make a call to the above URL in the
following manner. Note: Copy paste the information below in to an editor for easy
viewing of the code.
MyClientClass.java:
package ABPPClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.ByteArrayRequestEntity;
import org.apache.commons.httpclient.HttpClient;
import java.net.URL;
import java.io.*;
public class MyClientClass

{
public static void main(String[] args) throws Exception
{
HttpClient httpclient_a = new HttpClient();
// abppcommand is the servlet name

URL requestUrl = new URL("https://myhostname:7002/base/abppcommand");
// Following method gets the xml from file

// into a string. The xml should include UserName and Password
// attributes at the REQUESTS level
String xmlStr_1 = getRequestFromFile("c:/test/testrequest1.xml");
String response1Str = postToUrl(httpclient_a, requestUrl, xmlStr_1);
System.out.println(response1Str);
// Make a second call using the same session

// (httpclient_a object), and no need to include the

// UserName and Password as long as the session is active.
// The REQUESTS need not include UserName and
// Password attributes
String xmlStr_2 = getRequestFromFile("c:/test/testrequest2.xml");
String response2Str = postToUrl(httpclient_a, requestUrl, xmlStr_2);
System.out.println(response2Str);
}
// Method to post a request to a given url, using the given http session
private static String postToUrl(HttpClient httpclient, URL url, String request)
{
String response = "";
try {
PostMethod post = new PostMethod(url.toString());
post.getParams().setSoTimeout(600000);
ByteArrayRequestEntity entity = new

ByteArrayRequestEntity(request.getBytes("UTF-8"));
post.setRequestEntity(entity);
post.setRequestHeader("User-Agent", "my-user-agent-name");
post.setRequestHeader("Content-Type", "text/xml; charset=UTF-8");
httpclient.executeMethod(post);
byte[] responseBytes = post.getResponseBody();

response = new String(responseBytes, "UTF-8");
post.releaseConnection();
}
catch(Exception e)

Invoking Commands
{
System.out.println("Exception posting: " + e);
e.printStackTrace();
}
return response;
}
private static ByteArrayOutputStream readStream(InputStream bf) throws

IOException
{
ByteArrayOutputStream bis = new ByteArrayOutputStream(4096);
boolean done = false;
byte[] bytes = new byte[4096];
while (!done)
{
int numRead = bf.read(bytes, 0, 4096);
if (numRead <= 0)
done = true;
if (!done)
bis.write(bytes, 0, numRead);
}
bf.close();
return bis;
}
private static String getRequestFromFile(String fileName) throws

FileNotFoundException, IOException
{
String reqStr = "";
ByteArrayOutputStream bos = null;
try {
FileInputStream fstream = new FileInputStream(fileName);
bos = readStream(fstream);
reqStr = new String(bos.toByteArray(), "UTF-8");

}
finally
{
if (bos != null)
bos.close();
}
return reqStr;
}
Sample first request:

<REQUESTS ServiceName="bookstore" UserName="seller1"
Password="pwd">
<REQUEST Name="getBook">
<AuthorName Value="AuthorAa"/>
<BookName Value="BookBb"/>
</REQUEST>
</REQUESTS>
Sample 2nd request. Note the absence of UserName and Password attributes:
<REQUESTS ServiceName="bookstore">
<REQUEST Name="getBook">
<AuthorName Value="AuthorAa"/>
<BookName Value="BookBb"/>
</REQUEST>
</REQUESTS>

Chapter 5
X-Rules
This chapter delves into the subject of X-Rules and discusses in details the definition,
different types, and examples of X-Rules. It includes the following topics.
Topics:
z Introduction
z Variables and Expressions
z Variable Types
z X-Rule Types
z X-Rule Components
z Condition X-Rule Components
z Action X-Rule Components
z Core Components
z Command Components
z Data Access Components
z Query Condition
z Scalar Functions
z XML-Manipulation Components
z User-Interface Related Components
z Utility Components
z Framework Specification Components
Introduction
X-Rule is an XML specification for expressing business logic. This is analogous to a
function in Java programming language. There are different types of X-Rules to cater
to different needs. These will be described in detail in a different section.

Chapter 5 X-Rules
This section will focus on the concepts which are common to any X-Rule. All X-
Rules share the same structure.
Syntax of the Structure:
<RULE>
<COND> 
{condition component1}
............
{condition componentN}
</COND>
<ACTION>
{action component1}
{action component2}
............
{action componentN}
</ACTION>
</RULE>
An X-Rule contains one or more RULE components. A RULE component contains a
set of condition components and action components.
Condition components evaluate to a boolean value (true or false). Action components
perform tasks (example, looping through a list, assigning variables etc) and do not
return any value.
ABPP contains a number of built-in components that are used to perform the common
tasks with in an X-Rule. To perform tasks that are not available in the ABPP
framework or to re-use external functions, you can:
1. Define custom rule tags, easily using the framework extension mechanism.
2. Use Java to define parts of the business logic and/or leverage existing class
libraries, and integrate it seamlessly within the X-Rule using components such as
NATIVE_FUNCTION and INSTANCE_FUNCTION.
Executing an X-Rule will execute all the RULE components within the X-Rule. When
an RULE component is executed, the action components are executed if ALL the
condition components evaluate to true.
The following example illustrates a simple X-Rule 'helloWorld' that prints the text
'Hello World!' to the console as well returns it to the calling function as an XML
value:
<DEFINE_METHOD Name="helloWorld" Access="Public">
<API_DOC>
<INPUT>
<REQUEST Name="helloWorld"/>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE Ststus="Success[Type=Constant]">
<TEXT Value="xxx[Type=string]"/>
</RESPONSE>
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
<RULE>

Variables and Expressions
<ACTION>
<SET Var="myVar" FromValue="Hello World!"/>
<PRINTLN Value="{$myVar}"/>
<TO_DOCVAR AssignToVar="thisReturn">
<RETURN>
<TEXT Value="{$myVar}"/>
</RETURN>
</TO_DOCVAR>
</ACTION>
</RULE>
</DEFINE_METHOD>
The above rule is invoked using the REQUEST tag as follows:
<REQUEST Name="helloWorld" />
</REQUESTS>
The response will be:
<RESPONSES Status="Success">
<TEXT Value="Hello World!"/>
</RESPONSE>
</RESPONSES>
Variables and Expressions

Most of the components operate on variables. So it is necessary to understand
variables.
X-Rules support the following variable types:
| Var: An un-typed variable
| DocVar: A variable of type XML Document
| Value: An un-typed constant
| Property: The property-name of an X-Document
| Attribute: The attribute-name of an XML Document
There are a number of variables that have specific connotation when writing X-Rules.
For example, thisParam , thisReturn , thisDoc , and so on. These variables
will be covered in later sections, in context with the type of X-Rule that uses them.
Using the above mentioned variable types, you can form complex expressions of the
following form:
<ActionTag LhsExpression RhsExpression/>
OR
<ConditionTag LhsExpression RhsExpression/>
LhsExpression
A LhsExpression is formed using one of the following:
| Value: String literal. X-Path expression can be embedded
by using {}.

Chapter 5 X-Rules
| Var: Name of untyped variable.

| Select: X-Path expression that refers to a single untyped
object (xml element, string etc). If the expression
evaluates to a list then only the first entry in the list
will be returned. This is equivalent to using FromValue
with X-Path expression.
| SelectList: X-Path expression that refers to a list. If
the expression evaluates to a single object then a list
with just that single object will be returned.
| DocVar and Property: The ’Property’ attribute refers to
element of the document represented by ’DocVar’. Value of
’Property’ can be made dynamic by specifying an X-Path
expression inside {}. The ’DocVar’ & ’Property’
combination should be used only for cases where the
property name is dynamic. For all other cases use of
’Value’ with X-Path expression is recommended.
| DocVar and Attribute: The ’Attribute’ attribute refers to
attribute of the document represented by ’DocVar’. Value
of ’Attribute’ can be made dynamic by specifying an X-
Path expression inside {}. The ’DocVar’ & ’Attribute’
combination should be used only for cases where the
attribute name is dynamic. For all other cases use of
’Value’ with X-Path expression is recommended.
RhsExpression
A RhsExpression is a LhsExpression with a From prefix:
| FromValue
| FromSelectList
| FromVar
| FromDocVar and FromProperty
| FromDocVar and FromAttribute
The following examples illustrate how Lhs and Rhs expressions are used with the help
of the SET action statement.
Example 1
The following statement creates an un-typed variable called myQuantity and assigns it
the string "50".
<SET Var="myQuantity" FromValue="50"/>
LhsExpression : Var="myQuantity"
RhsExpression : FromValue="50"
Example 2
The following statement creates an un-typed variable msg and assigns it the string
"Order number PO-1 has been received" assuming the orderId variable value is ’PO-
1’.
<SET Var="msg" FromValue="Order number {$orderId} has been
received"/>

Variable Types
Variable Types
Local Variables
Description:
These variables are defined within a X-Rule. They are only visible from the point they
are defined to the end of the X-Rule. See SET component in the ABPP component
reference to know more about how local variables are assigned.
Service Variables
Description:
In an X-Service, when a variable is defined as a service parameter, it is available
anywhere within that X-Service (workflows, rules, validations etc.). It can be
referenced by simply using the variable name in the RhsExpression as with any other
variable (FromVar, FromValue etc.). However, the value of the service variable can
only be a constant value and cannot be changed or re-assigned in the workflow run
time.
X-Rule Types
There are nine different types of X-Rules that can be defined in the ABPP framework:
DEFINE_METHOD
Description:
This is the most common type of X-Rule. It can be explicitly invoked by a user using
the REQUEST command. Please see X-Commands chapter for more information on
commands.
Syntax:
<DEFINE_METHOD Name="methodName"
Access="Public|Protected|Private" Category="abc[Optional=true]"
Externalize="true|false[Optional=true]"
JMSConnection="connectionName[Optional=true]"
SemanticVal="true|false[Optional=true]"
ValidateSignature="true|false|default[Optional=true]">
<API_DOC>
<INPUT>
{input xml definition}
</INPUT>
<OUTPUT>
<ON_SUCCESS>
{success output xml definition}
</ON_SUCCESS>
<ON_EXCEPTION>
<exception output xml definition}

Chapter 5 X-Rules
</ON_EXCEPTION>
</OUTPUT>
</API_DOC>
<RULE>
<COND> <!- COND tag is optional à
............
</COND>
<ACTION>
{action component1}
...............
{action componentN}
</ACTION>
</RULE>
<RULE>
...............
...............
</RULE>
...............
</DEFINE_METHOD>
Attributes:
z Name (Required): Method name.
z Access (Optional): Sets the access level of the request to one of three possible
values:
| Public: Can be invoked by all clients.
| Protected: Can only be invoked by the owning X-Service and other co-located
Xservices. This is the default access level.
| Private: Can be invoked only by the owning X-Service.
z Category (Optional): Used to classify the business request.
z Externalize (Optional): Indicates if the rule is exposed to external clients through
JMS. Default is false.
z JMSConnection (Optional): Name of the JMS Connection to be used for
externalizing the X-Rule.
z SemanticVal (Optional): This attribute can be used to enable/disable semantic
validation just for this method. This will override the semantic validation set at
service level.
z ValidateSignature (Optional): This attribute can be used to enable/disable API
signature validation for this X-Rule. If the attribute is set to true or false, it will
override the API signature validation set at service level. If the attribute is not
specified or set to default then it will use the API signature validation set at
service level. Refer ValidateApiSignature attribute in Service Config section for
details on setting API signature validation on the service. If the API signature
validation is enabled (For example, attribute is true) then the input & output of
this X-Rule is validated to ensure conformance with the corresponding signature
(structure, required elements & attributes, data types etc) defined in the
API_DOC.

X-Rule Types
DEFINE_METHOD accepts xml document as input and returns an xml document as

output. The input/output xml documents must be defined using the API_DOC tags.
For more information on defining API_DOC, please refer to Web Service Definitions
section of the ABPP reference guide.
The following pre-defined variables can be referenced in a DEFINE_METHOD:
z thisParam: This variable references the input xml document passed to this X-Rule
tag (is of type document variable or DocVar).
z thisReturn: This variable is used to set xml content of the output from the
DEFINE_METHOD (also of type DocVar).
z thisContext: This variable is an instance of the Java class com.i2.X-
Core.tool.OmxContext. It provides methods to access the database connections
and documents in the system.
Scope of variables: All variables (including the pre-defined ones) have the scope from
the point at which they are defined to the end of the DEFINE_METHOD block.
A DEFINE_METHOD is invoked using the REQUEST command. In order to invoke,
the REQUEST command must identify the DEFINE_METHOD by providing:
a. Service Name and
b. Name attributes
The REQUEST command should also contain the Input Xml document expected by
the DEFINE_METHOD.
Example 1:
<DEFINE_METHOD Name="isEnterpriseRegistered" Access="Public"
Category="abc">
<API_DOC>
<INPUT>
<REQUEST Name="isEnterpriseRegistered">
<ENTERPRISE_ID Value="xxx[Type=string]"/>
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE Status="Success[Type=Constant]">
<IS_REGISTERED Value="true|false"/>
</RESPONSE>
</ON_SUCCESS>
<ON_EXCEPTION>
<RESPONSE Status="Error[Type=Constant]">
<ERROR_CODE Value="xxx[Type=string]"/>
<ARGS OrderIndicator="true">
<ARG Value="xxx[Type=string]"/>
</ARGS>
</RESPONSE>
</ON_EXCEPTION>
</OUTPUT>
</API_DOC>
<RULE>
<COND>

Chapter 5 X-Rules
<IS_TRUE Value="{$thisParam/ENTERPRISE_ID/
@Value=null}"/>
</COND>
<ACTION>
<EXCEPTION ForceRollBack="true">
<ERROR_CODE Value=" MISSING_MANDATORY_INPUT"/>
<ARGS>
<ARG Value="ID"/>
</ARGS>
</EXCEPTION>
</ACTION>
</RULE>
<RULE>
<ACTION>

<COND>
<OR>
<IS_TRUE Value="{$thisDoc/SELLER_ID/
@Value=null}"/>
<IS_TRUE Value="{$thisDoc/ITEM_ID/
@Value=null}"/>
<IS_TRUE Value="{$thisDoc/PO_ID/@Value=null}"/>
<IS_TRUE Value="{$thisDoc/BUYER_ID/
@Value=null}"/>
</OR>
</COND>
<ACTION>
<EXCEPTION Value="MISSING_MANDATORY_FIELDS"/>
</ACTION>
</RULE>
<RULE>

<COND>
<IS_TRUE Value="{$thisDoc/ID/@Value=null}"/>
</COND>
<ACTION>


X-Rule Types
<CREATE_DOCUMENT_ID Name="LINE_ITEM"
AssignToVar="uid"/>
<SET DocVar="thisDoc" Property="ID" FromVar="uid"/>
</ACTION>
</RULE>
</DEFINE_PRE_CREATE>
DEFINE_POST_CREATE
Description:
invoked just after a new instance of the X-Document is added to the Database.
DEFINE_POST_CREATE is useful for performing actions like sending out an alert,
setting up a timer, create another document, etc. It does not take any parameters and
does not return anything. This rule is automatically called by the system using the
OnPostCreate handler, and does not accept an explicit invocation by a user.
The following pre-defined variables can be referenced in DEFINE_POST_CREATE:
z thisDoc. This variable references the document for which the
DEFINE_POST_CREATE is called (is of type DocVar).
z thisParentDoc. This variable is available only if the document is being added as a
nested document, and points to the enclosing (or parent) document (is of type
DocVar).
the point at which they are defined to the end of the DEFINE_POST_CREATE block.
Syntax:
<DEFINE_POST_CREATE Document="docName">
<RULE>
...............
</COND>
<ACTION>
...............
</ACTION>
</RULE>
<RULE>
...............
</RULE>
............
</DEFINE_POST_CREATE>
Attributes :

Chapter 5 X-Rules
Example
The following post-create rule is used for generating an alert whenever a new
SALES_ORDER document is added to the database.
<DEFINE_POST_CREATE Document="SALES_ORDER">
<RULE>
<ACTION>

<ADD_DOCUMENT Name="ALERT">
<TO_USER Value="{$thisDoc/SELLER_ID/@Value}"/>
<FROM_USER Value="{$thisDoc/BUYER_ID/@Value}"/>
<ALRT_LEVEL Value="SALES_ORDER"/>
<SO_ID Value="{$thisDoc/ID/@Value}"/>
<MSG Value="New Sales Order created by the
system"/>
</ADD_DOCUMENT>
</ACTION>
</RULE>
</DEFINE_POST_CREATE>
DEFINE_PRE_MODIFY
Description:
invoked just before a MODIFY_DOCUMENT command on an X-Document, is executed
on the Database. DEFINE_PRE_MODIFY is useful for performing actions like
automatically updating last-modified-date, last-modified-by-user or setting some
property values before updating the document on the database. It does not take any
parameters and does not return anything. This rule is automatically called by the
system using the OnPersist handler, and does not accept an explicit invocation by a
user.
The following pre-defined variables can be referenced in DEFINE_PRE_MODIFY:
z thisDoc. This variable references the modify document xml for which the
DEFINE_PRE_MODIFY is called (is of type DocVar).
the point at which they are defined to the end of the DEFINE_PRE_MODIFY block.
Syntax:
<DEFINE_PRE_MODIFY Document="docName">
<RULE>
...............
</COND>
<ACTION>
...............

X-Rule Types
</ACTION>
</RULE>
<RULE>
............
</RULE>
............
</DEFINE_PRE_MODIFY>
Attributes:
Example
The following pre-modify rule is used for updating LAST_MODIFIED_DATE and
LAST_MODIFIED_BY_ID columns whenever a MODIFY_DOCUMENT command is
issued on RECEIPT_LINE X-Doc.
<DEFINE_PRE_MODIFY Document="RECEIPT_LINE">
<RULE>
<ACTION>
<SET Var="updateProps" FromValue="{$thisDoc/
UPDATE_PROPERTIES}"/>
<SET DocVar="updateProps"
Property="LAST_MODIFIED_DATE" FromValue="{date()}"/>
<SET DocVar="updateProps"
Property="LAST_MODIFIED_BY_ID" FromValue="{$thisUser}"/>
</ACTION>
</RULE>
</DEFINE_PRE_MODIFY>
DEFINE_POST_MODIFY
Description:
invoked just after a MODIFY_DOCUMENT command on an X-Document, is executed
on the Database. It does not take any parameters and does not return anything. This
rule is automatically called by the system using the OnPersist handler, and does not
accept an explicit invocation by a user.
The syntax and the pre-defined variables available are identical to the
DEFINE_PRE_MODIFY statement. The only difference is the tag name.
DEFINE_INIT
Description:
This is a special X-Rule which can be defined ONLY ONCE for each X-Service and
is used by the system to perform initialization tasks when the X-Service is deployed. It
does not take any parameters and does not return anything. This rule is automatically
called by the system using the OnPostCreate handler, and does not accept an explicit
invocation by a user.
The following pre-defined variables can be referenced in DEFINE_INIT:

Chapter 5 X-Rules

the point at which they are defined to the end of the DEFINE_POST_CREATE block.
Syntax:
<DEFINE_INIT>
<RULE>
<COND>
................
</COND>
<ACTION>
................
</ACTION>
</RULE>
<RULE>
..................
</RULE>
............
</DEFINE_INIT>
Attributes :
None
Example
The following init rule prints a status message to the log whenever the X-Service is
started.
<DEFINE_INIT>
<RULE>
<ACTION>
<PRINTLN Value="Starting Service"/>
</ACTION>
</RULE>
</DEFINE_INIT>
DEFINE_PRE_SHUTDOWN
can be used by the service to perform any custom tasks before the server starts the shut
down actions. Typically this X-Rule can be used to clean up any custom resources that
have been acquired by the service.
It does not take any parameters and does not return anything. This rule is
automatically called by the system as part of shut down, and does not accept an
explicit invocation by a user.
The following pre-defined variables can be referenced in
DEFINE_PRE_SHUTDOWN

X-Rule Types

the point at which they are defined to the end of the DEFINE_PRE_SHUTDOWN
block.
Syntax:
<RULE>
............
</COND>
<ACTION>
................
</ACTION>
</RULE>
<RULE>
...............
</RULE>
...............
Attributes:
None
Example
The following X-Rule prints a status message to the log before the server starts the
shut down.
<RULE>
<ACTION>
<PRINTLN Value="Pre-Shutdown rule invoked"/>
</ACTION>
</RULE>
DEFINE_POST_SHUTDOWN
can be used by the service to perform any custom tasks after the server finishes the
shut down actions. It does not take any parameters and does not return anything. This
rule is automatically called by the system as part of shut down, and does not accept an
explicit invocation by a user.
The following pre-defined variables can be referenced in
DEFINE_POST_SHUTDOWN

Chapter 5 X-Rules

the point at which they are defined to the end of the DEFINE_POST_SHUTDOWN
block.
Syntax:
<RULE>
............
</COND>
<ACTION>
................
</ACTION>
</RULE>
<RULE>
...............
</RULE>
...............
Attributes:
None
Example:
The following X-Rule prints a status message to the log after the server finishes the
shut down tasks.
<RULE>
<ACTION>
<PRINTLN Value="Post-Shutdown rule invoked"/>
</ACTION>
</RULE>
X-Rule Components
Exceptions thrown by Components within X-rules

Description:
Any exception thrown by a rule component will result in rollback of the current
database transaction. The external caller who posted the REQUESTS on the server
will receive a formatted error response.
Example:

X-Rule Components
Assume that the following REQUESTS are posted on the server:

<REQUEST Name="externalRequest"/>
</REQUESTS>
Here is the implementation of externalRequest. API_DOC tags are not shown for
clarity.
<DEFINE_METHOD Name="externalRequest" Access="Public">
<RULE>
<ACTION>
<PRINTLN Value="before invoking myExceptionReq"/>
<REQUEST Name="myExceptionRequest"
AssignToVar="myOutput"/>
<PRINTLN Value="After invoking myExceptionReq"/>
</ACTION>
</RULE>
</DEFINE_METHOD>
<DEFINE_METHOD Name="myExceptionRequest" Access="Public">

<RULE>
<ACTION>
<PRINTLN Value="before Exception"/>
<ADD_DOCUMENT Name="BadDocument"
AssignToVar="myResponse"/>
<PRINTLN Value="after Exception"/>
<TO_XML SelectList="$myResponse/*"/>
</APPEND_TO_XML>
</ACTION>
</RULE>
</DEFINE_METHOD>
The output of REQUESTS invocation:
<RESPONSES Status="Error" >
<RESPONSE Status="Error" Description="BadDocument not found
in myService"/>
</RESPONSES>
In this execution,
The following components in myExceptionRequest X-Rule will not be executed:
<PRINTLN Value="after Exception"/>
<TO_XML SelectList="$myResponse/*"/>
</APPEND_TO_XML>
The following components in externalRequest X-Rule will not be executed:
<PRINTLN Value="After invoking myExceptionReq"/>
X-Rule Components Syntax Notations

Description:

Chapter 5 X-Rules
The syntax snippets in the X-Rule component reference use some reserved attributes
and conventions to convey the syntax. This chapter explains the notations with an
example.
Attribute Notations:
1. AttrName="attrValue [Optional=true]": AttrName is Optional within the xml tag.
2. AttrName="attrValue [default=xx]": AttrName is Optional within the xml tag and
if it is not present then the default value of xx is assumed.
3. AttrName="a|b|c": Valid values for the attribute are a, b or c
4. AttrName="a|b|c [default=b]": Valid values for the attribute are a, b and c. default
value = b.
Tag name Notations:
1. <propertyN Value="abc" Repeatable="true"/>: Specifying Repeatable="true"
indicates that there can be multiple tags with given tag name. If a tag name ends
with N, the exact tag names can be different but the pattern is repeating.
Otherwise the exact tag name can repeat.
CHOICE_OF Notations:
This is used to depict choices. The structure is as follows:
<CHOICE_OF>
<CHOOSE Repeatable="true">
[ grammar of this choice]
</CHOOSE>
</CHOICE_OF>
Example:
<GET_DOCUMENT Name="documentName"
RowName="rowTagName[Optional=true"
AssignToVar="variableName[Optional=true]"
ServiceName="serviceName[Optional=true]"
StartAtRow="number[Optional=true, default=0]"
MaxRows="number[Optional=true]"
ReturnRowCount="true|false[default=false]"
OraHint="xxx[Optional=true]"
Distinct="true|false[Optional=true]">
<CHOICE_OF>
<CHOOSE>
{Compound query condition}
</CHOOSE>
<CHOOSE>
<propertyN MatchBy="match-by-
operator[Optional=true]" Value="value[Optional=true]"/>
</CHOOSE>
</CHOICE_OF>
<SELECT>
<propertyN Repeatable="true"/>
</SELECT>
</GET_DOCUMENT>

Condition X-Rule Components
Condition X-Rule Components

This section provides an introduction to the condition X-Rule components available in
the ABPP framework.
A condition component evaluates to a true or false. A conditional component could be
a simple condition or a compound condition. The following are the different types of
condition components.
z Simple Condition
z Compound Condition
Simple Condition
The basic form of the condition component is:
<IS_TRUE LhsExpression />
OR
<IS_FALSE LhsExpression />
Where LhsExpression is an X-Path expression that contains one of the following
comparison operators:
z EQUAL . '='
z NOT_EQUAL . '!='
z AND . 'and'
z OR . 'or'
In addition, to the above the following operators could also be defined when working
with numbers:
z GREATER . '>'
z GREATER_EQUAL . '>='
z LESS . '<'
z LESS_EQUAL . '<='
Example 1 :
<IS_TRUE Value="{int($myDoc/PROMISED_TOTAL_QTY/@Value)=100}"/>
The above component evaluates to true if the value of
PROMISED_TOTAL_QUANTITY property of a LINE_ITEM document (where is
this document), represented by the variable ` myDoc ', equals ` 100 '. Otherwise, it
returns false .
Example 2 :
<IS_TRUE Value="{int($myVar/@Value)<int($myDoc/
PROMISED_TOTAL_QTY/@Value)}"/>
The above component evaluates to true if the value of ` myVar ' is less than the value
of PROMISED_TOTAL_QUANTITY property of a LINE_ITEM document,
represented by the variable ` myDoc '. Otherwise, it returns false .
Example 3 :

Chapter 5 X-Rules
<IS_TRUE Value="{int($myDoc/PROMISED_TOTAL_QTY/
@Value)<=int($myDoc/REQUESTED_TOTAL_QTY/@Value)}"/>
The above component will evaluate to true if the value of
PROMISED_TOTAL_QUANTITY property of a LINE_ITEM document,
represented by the variable ` myDoc ' is less than or equal to the value of
REQUESTED_TOTAL_QUANTITY property of the same LINE_ITEM document.
Otherwise, it returns false .
Compound Condition
A compound condition can be formed by logically grouping AND/OR condition
components.
Example 1:
<OR>
<IS_TRUE Value="{$lineItemDoc/STATUS/@Value='Ack'}"/>
<AND>
<IS_TRUE Value="{$lineItemDoc/STATUS/@Value='Open'}"/>
<IS_TRUE Value="{$lineItemDoc/PROMISED_TOTAL_QTY/
@Value=$lineItemDoc/REQUESTED_TOTAL_QTY/@Value}"/>
</AND>
</OR>
The above condition is equivalent to,
(lineItemDoc.STATUS == Ack)
OR
(
(lineItemDoc.STATUS == Open)
AND
(lineItemDoc.PROMISED_TOTAL_QTY ==
lineItemDoc.REQUESTED_TOTAL_QTY)
)
Action X-Rule Components

Action components are used to perform the tasks inside a workflow or X-Rules in
ABPP.
As you will recall, the flow logic of a workflow is represented using nodes such as
Start, Task, Event, Branch, UI, Done etc. Within each node, action components are
used to execute specific tasks. The tasks within an X-Rule are also written using
action components.
Based on the type of action performed, Action components are classified into:
1. X-Document
2. SQL
3. XML Manipulation
4. Logic

5. User-Interface
6. Utility
7. Framework Specification
Core Components
SET
Description:
SET assigns the value of the RhsExpression to the LhsExpression.
Syntax :
<SET LhsExpression RhsExpression/>
Attributes :
z Var: Untyped variable which SET operates upon.
z DocVar: Document variable which SET operates upon.
z Property: Any element of the document represented by DocVar.
z Attribute: Any attribute of the document represented by DocVar.
z FromVar: Untyped variable that SET refers to.
z FromValue: X-Path expression (within {}) or String value.
z FromSelect: X-Path expression that refers to a single untyped object (xml
element, string etc). If the expression evaluates to a list then only the first entry in
the list will be returned. This is equivalent to using FromValue with X-Path
expression.
z FromSelectList: X-Path expression that refers to a list. If the expression evaluates
to a single object then a list with just that single object will be returned.
z FromDocVar: Document that SET refers to. This attribute should be used only for
cases where FromProperty or FromAttribute are used. For all other cases use of
FromValue with X-Path expression or FromVar is recommened.
z FromProperty: Refers to element of the document represented by FromDocVar.
Value of this attribute can be made dynamic by specifying an X-Path expression
inside {}. The FromDocVar & FromProperty combination should be used only for
cases where the property name is dynamic. For all other cases use of FromValue
with X-Path expression is recommended.
z FromAttribute: Refers to attribute of the document represented by FromDocVar.
Value of this attribute can be made dynamic by specifying an X-Path expression
inside {}. The FromDocVar & FromAttribute combination should be used only
for cases where the attribute name is dynamic. For all other cases use of
FromValue with X-Path expression is recommended.
When you are using SET, combinations of these attributes can be used to form the Lhs
or Rhs Expressions, depending on the context of the SET component.
Example 1

Chapter 5 X-Rules
The following component creates an un-typed variable called "myQuantity" and

assigns it the value of '50'.
LhsExpression: Var="myQuantity"
RhsExpression: FromValue="50"
Example 2
The following component sets the PROMISED_TOTAL_QTY property of the
LINE_ITEM instance referenced by the variable myDoc to the value of the variable
myQuantity. If the property already exists then its value will be overwritten.
<SET DocVar="myDoc" Property="PROMISED_TOTAL_QTY"
FromValue="{$myQuantity}"/>
LhsExpression: DocVar="myDoc" Property="PROMISED_TOTAL_QTY"
RhsExpression: FromValue="{$myQuantity}
Example 3
The following component sets the variable liQty with the value of ORDERED_QTY
property of the LINE_ITEM instance referenced by the variable liDoc .
<SET Var="liQty" FromValue="{$liDoc/ORDERED_QTY/@Value}"/>
LhsExpression: Var="liQty"
RhsExpression: FromValue="{$liDoc/ORDERED_QTY/@Value}"
Note: The DocVar/Property, DocVar/Attribute combinations during SET operation

cannot be replaced by equivalent X-Path value semantics.
Example 4
The following component assigns an attribute on a existing document instance.
<SET DocVar="myDoc" Attribute="Comment" FromValue="Test"/>
LhsExpression: DocVar="myDoc" Attribute="Comment"
RhsExpression: FromValue="Test"
PRINT/PRINTLN
Description:
The PRINT , PRINTLN statements are very useful for debugging X-Rules. By
default, PRINT publishes the value of the LhsExpression on to the console (or a log
file, if it is specified) when the log level is set to Debug. PRINTLN has the same effect
as PRINT except that it also prints a new line.
Syntax:
<PRINT LhsExpression />
<PRINTLN LhsExpression />
Attributes
z LhsExpression: Refer to LhsExpression section
Example 1
Input:


<PRINT Value="The Value of My Quantity is:{$myQuantity} "/>
Output:
The Value of My Quantity is: 50
Example 2
Input:
<PRINTLN SelectList="$co/ORDER_LINE_ITEMS/ORDER_LINE_ITEM"/>
Output:
This will write a list of line items to the log if Debug log level is enabled.
LOG
Description:
The LOG operation is used to write to the log file. It is similar to the PRINT/
PRINTLN operations but with the advantage that you can control the log level.
Syntax:
<LOG Loglevel= "level" Value="Log Statement"/>
Attributes:
z Loglevel (Required): One of - Error, Exception, Debug, Info, Warning, Audit,
EnterTrace, ExitTrace, IntraServiceCallTrace, InterServiceCallTrace,
SqlCallTrace, XPathFnTrace
z Value (Required): Text to be written to the log file
Example 1:
<LOG Loglevel="Info" Value="Write this in log file. Document is
{$doc}"/>
IF_TEST-THEN-ELSE
Description:
The IF_TEST-THEN-ELSE component forms an execution-control-block in ABPP
and is used to test whether a condition, expressed as a Boolean X-Path expression,
evaluates to true or false. If the condition evaluates to "true", then the action
components associated with THEN is executed. Otherwise, the action components
associated with the "ELSE" component are executed.
Use of X-Path expressions more than 80 characters should be avoided for readability.
IF_TEST is generally preferred over IF-THEN-ELSE component (explained below)
whenever the test condition can be expressed as a compact expression.
Syntax:
<IF_TEST Test="xpath Expression that evaluates to Boolean">
<THEN Optional="true">
[action components]
</THEN>
<ELSE Optional="true">
[action components]
</ELSE>

Chapter 5 X-Rules
</IF_TEST>
Attributes:
Test (Required): The test condition expressed as a Boolean X-Path Expression
Example:
Assuming that 'coDoc' points to the following document instance:
<CUSTOMER_ORDER>
<ID Value="CO-01"/>
<ORDER_TYPE_ID Value="STANDARD"/>
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ID Value="LI-01"/>
<ITEM_ID Value="CPU"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-02"/>
<ITEM_ID Value="MONITOR"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
Example 1: IF_TEST Condition that Evaluates to True
Input:
<IF_TEST Test="$coDoc/ID/@Value = 'CO-01'">
<THEN>
<PRINT Value="Found CO"/>
</THEN>
<ELSE>
<PRINT Value="CO not found"/>
</ELSE>
</IF_TEST>
Output:
Found CO.
Example 2: IF_TEST Condition that Evaluates to False
Input:
<IF_TEST Test="$coDoc/CUSTOMER_TYPE = null">
<THEN>
<PRINTLN Value="Exception. Missing CUSTOMER_TYPE in
CUSTOMER_ORDER."/>
<EXIT/>
</THEN>
</IF_TEST>
Output:
Exception. Missing CUSTOMER_TYPE in CUSTOMER_ORDER.
IF-THEN-ELSE
Description:

The IF-THEN-ELSE component forms an execution-control-block in ABPP and is

used to test a condition and perform actions based on the output of the condition. The
condition component can be a simple condition or a compound condition. If there is
more than one condition component, the components are combined into a single
compound condition component using "AND" and "OR" operators. If the condition
evaluates to "true", then the action components associated with THEN is executed.
Otherwise, the action components associated with the "ELSE" component are
executed.
The use of IF_TEST is generally preferred to that of IF whenever the Test condition
can be expressed as a compact expression. But if the X-Path condition is complex,
then writing it out as IF will make it more comprehensible.
Syntax:
<IF>
<COND>
{condition component N}
................
{condition component N}
</COND>
<THEN>
{action component1}
................
{action component N}
</THEN>
<ELSE> 
{action component1}
................
</ELSE>
</IF>
Attributes:
None
Example 1:
Input:
<IF>
<COND>
<IS_TRUE Value="{$lineItemDoc/TOTAL_PROMISED_QTY/
@Value=$lineItemDoc/TOTAL_REQUIRED_QTY/@Value}"/>
<IS_TRUE Value="{$lineItemDoc/STATUS/@Value !=
'CANCEL'}"/>
<IS_TRUE Value="{isValidValue($lineItemDoc/TYPE/@Value,
'STANDARD', 'SAMPLE','TRANSFER','CONSIGNMENT')}"/>
</COND>
<THEN>
<PRINTLN Value="The total promised qty == required
quantity"/>
</THEN>
<ELSE>
<PRINTLN Value="The condition failed"/>
</ELSE>

Chapter 5 X-Rules
</IF>
Output (assuming the condition is true):
The total promised qty == required qty
Example 2:
The previous example written out as an IF_TEST (see below) looks more complex
than writing it out as IF, and hence should be avoided.
Input:
<IF_TEST Test="(($lineItemDoc/TOTAL_PROMISED_QTY/
@Value=$lineItemDoc/TOTAL_REQUIRED_QTY/@Value) and
($lineItemDoc/STATUS/@Value != 'CANCEL')) and
isValidValue($lineItemDoc/TYPE/@Value, 'STANDARD',
'SAMPLE','TRANSFER', 'CONSIGNMENT')">
<THEN>
<PRINTLN Value="The total promised qty == required
quantity"/>
</THEN>
<ELSE>
<PRINTLN Value="The condition failed"/>
</ELSE>
</IF_TEST>
Output:
The total promised qty == required qty
CHOOSE-WHEN-OTHERWISE
Description:
The CHOOSE-WHEN-OTHERWISE component forms an execution-control-block in
ABPP and can be used to avoid long list of IF_TEST-THEN components when used
for multiple mutually-exclusive conditions.
There can be multiple WHEN tags within the CHOOSE tag. Each WHEN tag should
have a Test attribute that specifies an X-Path expression. The OTHERWISE tag is
optional.
When this component is executed the WHEN tags Test expressions are evaluated
sequentially. If the expression evaluates to true for a WHEN tag, the action
components inside that WHEN tag are executed and then the execution continues after
the CHOOSE component. If none of the WHEN tags Test expression evaluates to true,
the action components inside the OTHERWISE tag are executed.
Syntax:
<CHOOSE>
<WHEN Test="xpath Expression that evaluates to Boolean"
Repeatable="true">
[action components]
</WHEN>
<OTHERWISE Optional="true">
[action components]
</OTHERWISE>
</CHOOSE>

Attributes:
Test (Required): The test condition expressed as a Boolean X-Path Expression
Example:
Assuming that 'coDoc' points to the following document instance:
<CUSTOMER_ORDER>
<ID Value="CO-01"/>
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ID Value="LI-01"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-02"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
Example 1:
Input:
<CHOOSE>
<WHEN Test="$coDoc/ORDER_TYPE_ID/@Value = 'STANDARD'">
<PRINT Value="Found STANDARD order"/>
</WHEN>
<WHEN Test="$coDoc/ORDER_TYPE_ID/@Value = 'TRANSFER'">
<PRINT Value="Found TRANSFER order"/>
</WHEN>
<OTHERWISE>
<PRINT Value="Unknown type"/>
</OTHERWISE>
</CHOOSE>
Output:
Found STANDARD order
FOR_EACH-BREAK-CONTINUE
Description:
The FOR_EACH-BREAK-CONTINUE component forms an execution-control-block
in ABPP and is used to perform iterations. The action components are executed for
each element of the list SelectList, and the current element is referred by the
'CurrentElement' attribute.
CONTINUE component will skip executing any following action components for the
current element, increment the current element and transfer the execution to the first
component after the start of the FOR_EACH tag.
BREAK component will skip executing any following action components for the
current element and transfer the execution to the first component after the end of the
FOR_EACH tag.

Chapter 5 X-Rules
Syntax:
<FOR_EACH SelectList="xpathExpr" CurrentElement="elemVar"
CurrentIndex="indexVar[Optional=true]">
{action component1 }
................
{action component N }
</FOR_EACH>
Attributes:
z SelectList (Required): X-Path expression that evaluates to list of elements to
perform actions on
z CurrentElement (Required): List element under inspection
z CurrentIndex (Optional): Variable that will hold index of the element under
inspection. The index values will be begin with 0.
Example:
First, a list of Purchase Order docs is assigned to the variable 'poDocs'. Then a
FOR_EACH block iterates through these docs and count all the docs in
'COMPLETED' state. Finally, the number of docs in 'COMPLETED' state is printed
out.
<GET_DOCUMENT Name="PURCHASE_ORDER" AssignToVar="poDocs">
<BUYER_ID Value="CISCO"/>
</GET_DOCUMENT>
<FOR_EACH SelectList="$poDocs/PURCHASE_ORDER"
CurrentElement="poDocVar">
<IF_TEST Test="$poDocVar/STATUS/@Value='COMPLETED'">
<THEN>
<SET Var="poCount" FromValue="{int(poCount)+1}"/>
</THEN>
<ELSE>
<CONTINUE/>
</ELSE>
</IF_TEST>
</FOR_EACH>
<PRINTLN Value="#POs in COMPLETED state:{$poCount}"/>
Output:
#POs in COMPLETED state: 43
REPEAT
Description:
The REPEAT component is used within an X-Rule to perform a set of action
components repeatedly. The 'Count' attribute specifies the number of times the
actions are repeated and the current index is referred by the 'IndexVar' attribute.
Syntax:
<REPEAT Count="xpathExpr" IndexVar="currentIndex">
{action component1}
..............
</REPEAT>

Attributes:
z Count (Requred): Number of times to repeat the actions
z IndexVar (Required): The current index value
Example:
An X-Rule 'createOrderXml' builds a customer order with a variable number of lines.
Method:
<DEFINE_METHOD Name="createOrderXml">
<RULE>
<ACTION>
<RESPONSE>
<CUSTOMER_ORDER>
<ID Value="2"/>
<REPEAT Count="int($thisParam/
NUM_LINES/@Value)" IndexVar="currIndex">
<SET Var="liId"
FromValue="{concat('LI_', $currIndex)}"/>
<TO_DOCVAR AssignToVar="liDoc">
<ORDER_LINE_ITEM>
<ID
Value="{string($liId)}"/>
</ORDER_LINE_ITEM>
</TO_DOCVAR>
<TO_XML DocVar="liDoc"/>
</REPEAT>
</CUSTOMER_ORDER>
</RESPONSE>
</TO_DOCVAR>
</ACTION>
</RULE>
</DEFINE_METHOD>
Input:
<REQUEST Name="createOrderXml">
<NUM_LINES Value="5"/>
</REQUEST>
Output:
<RESPONSE>
<CUSTOMER_ORDER>
<ID Value="2"/>
<ORDER_LINE_ITEM>
<ID Value="LI_0"/>
</ORDER_LINE_ITEM>
..............
..............
<ORDER_LINE_ITEM>
<ID Value="LI_4"/>
</ORDER_LINE_ITEM>
</CUSTOMER_ORDER>
</RESPONSE>

Chapter 5 X-Rules
WHILE
Description:
The WHILE component performs a set of actions repeatedly as long as the specified
condition is true.
Syntax:
<WHILE Condition="$condition=true()">
{action component1}
..............
</WHILE>
Attributes:
z Condition (Required): Condition to evaluate
Example:
Input:
<SET Var="index" FromValue="1"/>
<RESPONSE>
<CUSTOMER_ORDER>
<ID Value="CO_1"/>
<WHILE Condition="$index <= 3">
<SET Var="liId" FromValue="{concat('LI_',
$index)}"/>
<ORDER_LINE_ITEM>
<ID Value="{string($liId)}"/>
</ORDER_LINE_ITEM>
</TO_DOCVAR>
<SET Var="index" FromValue="{int($index + 1)}"/
>
</WHILE>
</CUSTOMER_ORDER>
</RESPONSE>
</TO_DOCVAR>
On Successful execution, contents of the variable, thisReturn:
<RESPONSE>
<CUSTOMER_ORDER>
<ID Value="CO_1"/>
<ORDER_LINE_ITEM>
<ID Value="LI_1"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI_2"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI_3"/>
</ORDER_LINE_ITEM>
</CUSTOMER_ORDER>
</RESPONSE>

EXIT
Description:
This component is used to exit the X-Rule module successfully.
Syntax:
<EXIT/>
Attributes
None
Example:
<IF_TEST Test="$thisParam/ID/@Value=null">
<THEN>
<EXIT/>
</THEN>
<ELSE>
<PRINTLN Value="This is a valid profile"/>
</ELSE>
</IF_TEST>
EXCEPTION
Description:
Exceptions are way to communicate to the caller that an abnormal condition has been
encountered. Raising an exception in X-Rule that is finally handled by the system
results in a rollback of the transaction and a well-structured XML response to the
external caller.
When the ABPP engine encounters an Exception component, it stops executing the
current x-rule and propagates the Exception to the caller. If the caller is another X-
Rule then that X-Rule can catch the exception and act on it. If the parent X-Rule does
not catch the exception then the exception will keep propagating up the call hierarchy
and finally will be handled by ABPP engine and it will return a well-structured xml to
the external caller.
The exception component allows the user to specify a name for the exception. The
name can be used in TRY-CATCH component to catch exceptions with specific name.
The syntax for EXCEPTION component is shown below. The entire XML contained
inside EXCEPTION tag will be reported as a part of the error message.
Syntax:
<EXCEPTION Value="xxx[Optional=true]" Name="xxx[Optional=true]"
OrigExceptionVar="e[Optional=true]"
ForceRollback="true[Optional=true]">
<Any XML Structure>
</EXCEPTION>
Attributes
z Value (Optional): Error message
z Name (Optional): Name of the exception. This can be any user defined value.

Chapter 5 X-Rules
z OrigExceptionVar (Optional): If this exception is being thrown from inside a

CATCH block then the exception that was caught by the CATCH block, can be
passed as OrigExceptionVar to link it as parent of this new exception that is being
thrown. Creating a chain in this fashion will help in identifying the original source
of the problem.
z ForceRollback (Optional): Default is false. When an exception is raised it can be
caught by the user-defined rule code (along the call hierarchy) and the caller can
decide to ignore the exception and continue. If the exception is ignored by user-
defined rule code then the active database transaction will end up being
committed successfully. The ForceRollback attribute should be set to ’true’ if the
rule code that is raising the exception wants to enforce that the database
transaction be rolled back even if the exception is caught and ignored by the
caller. When this flag is set to true the database transaction will be marked for
rollback irrespective of the actions taken by the caller. It is strongly recommended
that rule code should never catch and ignore exceptions and so there should be no
need for using this attribute.
Example 1:
The following component exits the rule module by throwing an exception. This
exception is an instance com.i2.X-Core.util.X-CoreException.
<DEFINE_METHOD Name="exceptionTest">
<RULE>
<ACTION>
<IF_TEST Test="$thisParam/ID/@Value=null">
<THEN>
<EXCEPTION Value="MISSING_MANDATORY_FIELD">
<ARG0 Value="ID" />
</EXCEPTION>
</THEN>
<ELSE>
<SET DocVar="thisReturn"
Property="IS_VALID" FromValue="TRUE"/>
</ELSE>
</IF_TEST>
</ACTION>
</RULE>
</DEFINE_METHOD>
If the input request is:

<REQUESTS ServiceName="XXXX">
<REQUEST Name="exceptionTest"/>
</REQUESTS>
Then the response will be:
<RESPONSE Description="MISSING_MANDATORY_FIELD"
Status="Error">
<ARG0 Value="ID"/>
</RESPONSE>
</RESPONSES>
Example 2:
<DEFINE_METHOD Name="exceptionTest">

<RULE>
<ACTION>
<TRY>
<BODY>

</BODY>
<CATCH AssignToVar="e">

<EXCEPTION OrigExceptionVar="e">

</EXCEPTION>
</CATCH>
</TRY>
</ACTION>
</RULE>
</DEFINE_METHOD>
TRY-CATCH-THROW
Description:
The TRY-CATCH-THROW statement can be used within rules to catch exceptions
and then act on them. Once the exception has been caught the user can decide to
ignore it and continue execution or re-throw it as-is or throw a new exception.
The TRY statement needs to have one child BODY statement and one or more child
CATCH statements. The actions inside BODY are executed and if there is an
exception during this execution then the matching CATCH statement is executed.
The CATCH statement can have a Name attribute that gives the name of the exception
that should be matched to this CATCH statement. Or it can have a Type attribute that
specified the type of the exception that should be matched to this CATCH statement.
A CATCH statement that does not have Name or Type attribute is called the default
CATCH statement and can be matched against any exception. The default CATCH
statement is executed only if a matching named/typed CATCH statement is not
defined.
When an exception is thrown within the BODY statement, if it has a name the system
will try to execute a CATCH statement with same name. If no matching named
CATCH statement is found or if the exception thrown does not have a name, the
system will try to execute a CATCH statement that has same type as the type of
exception thrown. If no matching CATCH for given exception type is found, the
system will try to execute the default CATCH statement. If the default CATCH
statement is also not defined the exception will be propagated to the caller.
The CATCH statement can use the AssignToVar attribute to get a handle to the
exception xml. The structure of the variable will be:
<EXCEPTION Name="UserDefinedName[Optional=true]"
Description="description of the exception[Optional=true]"
Type="User|System" Class="java.lang.NullPointerException"
Handle="exception java object">

Chapter 5 X-Rules
... xml body passed within EXCEPTION action used to throw this
exception. For other exceptions there will be no details here
...
</EXCEPTION>
The Name attribute will have some user defined value.
The Description attribute is present for System exceptions and for those User
exceptions where the user does not provide xml body for the exception.
The Type attribute will be 'User' for exceptions that are thrown in x-rules using
EXCEPTION command and will be 'System' for all other cases. To be more specific
all exceptions of type com.i2.xcore.xrules.lang.UserRuleException will have ‘User’
as the Type and all other exceptions will have ‘System’ as the Type.
The Class attributes gives the class name of the exception. e.g.
java.lang.NullPointerException, com.i2.xcore.dblib.XcoreSQLException
The Handle attributes value is the exception java object. It is used for internal
processing.
The body of the variable will have the original xml thrown as part of the exception.
After the matching CATCH statement has been executed the execution will continue
from the statement following the TRY statement unless the CATCH statement re-
throws the exception or a new exception in encountered during the CATCH execution.
To re-throw the original exception within CATCH statement the THROW statement
can be used. The THROW statement will stop execution of the rule and the original
exception will be propagated to the caller.
Syntax:
<TRY>
<BODY>

</BODY>
<CATCH Name="SomeName[Optional=true]"
Type="User|System[Optional=true]"
AssignToVar="e[Optional=true]" Repeatable="true">


<THROW ExceptionVar="e"/>
</CATCH>
</TRY>
Attributes
Refer to Description
Example 1:
<TRY>
<BODY>
<EXCEPTION Name="ValidationFailure>
<_RESULT Value="INVALID_ORDER_ID"/>
<ORDER>
<ID Value="32432"/>
</ORDER>

</EXCEPTION>
</BODY>
<CATCH Name="ValidationFailure" AssignToVar="e">

<PRINTLN Value="Name: {$e/@Name}"/>
<PRINTLN Value="Type: {$e/@Type}"/>
<PRINTLN Value="Exception xml: {$e}"/>
<THROW ExceptionVar="e"/>
</CATCH>
<CATCH AssignToVar="e">

<PRINTLN Value="{$e}"/>
</CATCH>
</TRY>
Example 2:
The ADD_DOCUMENT specifies a document name that does not exist and that
results in an exception whose type is 'System'. The catch statement uses Type
attribute to catch all exception of type 'System'.
Input:
<TRY>
<BODY>
<ADD_DOCUMENT Name="UndefinedDocument"/>
</BODY>
<CATCH Type="System" AssignToVar="e">
<PRINTLN Value="System exception {$e}"/>
</CATCH>
</TRY>
Output:
System exception <EXCEPTION Description="Unable to locate
Document for:UndefinedDocument" Type="System"
Class="com.i2.xcore.util.XcoreException"
Handle="com.i2.xcore.util.XcoreException: Unable to locate
Document for:UndefinedDocument"/>
HANDLE_SYSTEM_EXCEPTION
Description:
This component is used within DEFINE_METHOD tags to catch exceptions related to
ABPP/Database/Remote/Java. This component will not catch user exceptions thrown
(by using EXCEPTION action) within the body of DEFINE_METHOD. Any action
component can be provided within this tag. There is full access to thisParam,
thisReturn and other variables created before the exception was encountered.
This tag is provided only for doing cleanup and throwing a well-formatted exception.
If no exception is thrown within HANDLE_SYSTEM_EXCEPTION, then the
original exception will be thrown back. There is no real way to suppress this
exception. Also, there can be only one HANDLE_SYSTEM_EXCEPTION within a

Chapter 5 X-Rules
method definition that will handle all exceptions. This should be a direct child of
DEFINE_METHOD.
Note: The preferred way to handle exceptions is to use the TRY-CATCH statement
instead of using HANDLE_SYSTEM_EXCEPTION.
Syntax:
<DEFINE_METHOD> <!-other attributes not shown à
<ANY/>
<HANDLE_SYSTEM_EXCEPTION>
[action component1]
...
[action componentN]
</HANDLE_SYSTEM_EXCEPTION>
<DEFINE_METHOD>
Attributes
None
Example:
<DEFINE_METHOD Name="exceptionTest" >
<RULE>
<ACTION>
<REQUEST Name="remoteProcess" AssignToVar="result"/
>
</ACTION>
</RULE>
<HANDLE_SYSTEM_EXCEPTION>
<ACTION>
<EXCEPTION>
<_RESULT Value="SEVERE_ERROR"/>
<_ERROR Value="Exception in Remote Process"/>
</EXCEPTION>
</ACTION>
</HANDLE_SYSTEM_EXCEPTION>
</DEFINE_METHOD>
Command Components
Description:
Any command can be invoked within X-Rules. For general details on commands,
refer to the X-Commands chapter. System Commands section provides information
on generic system commands. It also provides pointers on where you can find specific
system commands. The ABPP framework provides various specification like
validation, purge etc that provide utility services. These specifications also provide
commands to utilize their services. For information on these commands please refer to
appropriate specification chapters.
Note: You should not enclose the command within the "REQUESTS" Command
Envelope when invoking within X-Rules.

When invoking commands within X-Rules, You can use X-Path expressions to form
the body of the command. You can also provide the following additional attributes on
the command.
Additional Attributes:
z AssignToVar: This variable will contain the output of the command. So the
AssignToVar variable will point to the "RESPONSE" XML tag after the
command execution.
z ServiceName: The service on which the command has to be executed. If not
provided, then it defaults to the service in which X-Rule is defined.
z Synchronous: true|false. Default=true.
| If Synchronous is true, the command executes in the same transaction as the
current transactuion. After the command execution, AssignToVar variable
will contain the command output.
| If synchronous is false then the command will be executed asynchronously
after the current transaction is committed. If synchronous is false then
AssignToVar variable is ignored.
Example:
This example illustrate the usage of invoking both system command (RAISE_EVENT)
and user command (isExistingItem) within X-Rules. Things of interest are marked in
bold.
<DEFINE_METHOD Name="addNewItem" Access="Public">


<RULE>
<ACTION>
<SET Var="status" FromValue="SUCCESS" />
<REQUEST Name="isExistingItem" ServiceName="Catalog"
AssignToVar="response">
<Id Value="{$thisParam/Id/@Value}" />
</REQUEST>
<IF_TEST Test="$response/IsExistingItem/
@Value=false()">
<THEN>
<ADD_DOCUMENT Name="Item"
ServiceName="Catalog">
<Id Value="{$thisParam/Id/@Value}" />
<Name Value="{$thisParam/Name/@Value}" />
<UnitPrice Value="{$thisParam/UnitPrice/
@Value}" />
</ADD_DOCUMENT>
<RAISE_EVENT Name="newItemCreated"
ServiceName="Catalog">
<ItemId Value="{$thisParam/Id/@Value}" />
</RAISE_EVENT>
</THEN>
<ELSE>
<SET Var="status" FromValue="ERROR" />
</ELSE>

Chapter 5 X-Rules
</IF_TEST>
<STATUS Value="{$status}" />
</APPEND_TO_XML>
</ACTION>
</RULE>
</DEFINE_METHOD>
Data Access Components
CREATE_DOCUMENT_ID
Description:
The CREATE_DOCUMENT_ID component creates an ID for the specified
document. It is used in conjunction with a pre-defined ID generation scheme and the
idgen tags. See the chapter on ID Generation for more details.
Syntax:
<CREATE_DOCUMENT_ID Name="docName"
Type="typeName[Optional=true] AssignToVar="varName"/>
Attributes:
Name (Required): Document for which ID is generated.
AssignToVar (Required): Variable to which the generated ID is assigned.
Type (Optional): You can use the type name to generate different prefixes and suffixes
for the same document. Refer ID Generation document on how to configure different
prefixes and suffixes for various types of a document. An example of this is: There are
2 types of Activity Orders - PURCHASE_ORDER and TRANSFER_ORDER. The
PURCHASE_ORDER ids have a prefix ’P’ (example, P1, P2 etc). The
TRANSFER_ORDER ids have a prefix ’T’ (example, T1, T2 etc). However
PURCHASE_ORDER and TRANSFER_ORDER share the same sequence since they
both are Activity Orders.
Example 1:
<CREATE_DOCUMENT_ID Name="ORDER_SCHEDULE" AssignToVar="newID"/>
Example 2:
<CREATE_DOCUMENT_ID Name="ACTIVITY_ORDER" Type="PURCHASE_ORDER"
AssignToVar="newID"/>
ADD_DOCUMENT
Description:
The ADD_DOCUMENT component allows creation of new x-document instances in
the system. The Name attribute on the component identifies the x-document instance
to be created. The body of ADD_DOCUMENT will contain values for the properties

of the x-document instance. The response contains the primary key values (document
identifiers) of the x-document instance created.
The xml document for this component can be a nested structure. The enclosed xml
document tag name should match a document link name on the x-document
corresponding to the enclosing xml document. The enclosed xml document derives
the values of mapped property values from the enclosing xml document using the
document link definition. In case of nested structure, the response will contain the
primary key values of the x-document instance corresponding to the top level tag.
ADD_DOCUMENT can result in ABPP caching the newly added x-document
instance in memory and persisting it when the transaction ends. To avoid caching and
to persist the document as soon as the add document component is executed, users can
specified an attribute on ADD_DOCUMENT called CacheHint="2". When this hint is
specified, ABPP will immediately make a database insert upon the
ADD_DOCUMENT call.
Syntax
<ADD_DOCUMENT Name="MyXdoc" CacheHint="0|1|2[default=0]"
Synchronous="true|false[default=true]"> 
<propertyNameN Value="xxxx" Repeatable="true"/> 
<documentLinkName1 Optional="true" Repeatable="true"> 
<linkedDocumentName1 Repeatable="true"> 
<lnPropertyNameN Value="xxxx" Repeatable="true"/>

</linkedDocumentName1>
</documentLinkName1>
</ADD_DOCUMENT>
Attributes
z Name (Required): Name of the X-Document that you want to add.
z ServiceName (Optional): Name of the service which contains the X-Doc.
z CacheHint (Optional): A value of '2' guarantees that the document is inserted into
the database immediately. A value of 0 or 1 results in the default behavior which
is to defer the database operation if possible.
z AssignToVar (Optional): Variable to assign the component output.
z Synchronous (Optional): true|false. If false, the component is executed
asynchronously.
Output Syntax:
<pkPropertyNameN Value="xxxx" Repeatable="true"/> 
</RESPONSE>

Chapter 5 X-Rules
Example 1
<ADD_DOCUMENT Name="PURCHASE_ORDER"
AssignToVar="myResponse">
<ID Value="PO_123"/>
<PIN Value="1"/>
<MY Value="7000.0"/>
<MY_ATTRIBUTE_A Value="This is a user attribute"/>
<MY_ATTRIBUTE_B Value="Another user attribute"/>
</ADD_DOCUMENT>
On successful execution of component:
Variable, myResponse, will have the following contents:
<RESPONSE Status="Success" Description="Add Document
Successful">
<ID Value="PO_123"/>
</RESPONSE>
Example 2
This is a modified example of the previous example and inserts LINE_ITEM
instances related to PURCHASE_ORDER in the same call.
<ADD_DOCUMENT Name="PURCHASE_ORDER" AssignToVar="myResponse">

<PIN Value="1"/>
<MY Value="7000.0"/>
<LINE_ITEMS>
<LINE_ITEM>
<ITEM_ID Value="item1-1-2"/>
<SELLER_ID Value="seller01"/>
<PROMISED_TOTAL_QTY Value="50"/>
<STATE Value="Open"/>
</LINE_ITEM>
<LINE_ITEM>
<ITEM_ID Value="item9-6-2"/>
<SELLER_ID Value="seller02"/>
<STATE Value="Open"/>
</LINE_ITEM>
</LINE_ITEMS>
</ADD_DOCUMENT>


<RESPONSE Status="Success" Description="Add Document
Successful">
<ID Value="PO-7854347890"/>
</RESPONSE>
In the above example, the LINE_ITEM is related to the PURCHASE_ORDER
through LINE_ITEMS document link defined on the PURCHASE_ORDER. The
LINE_ITEM instances derive the value of their PO_ID property (mapped property)
from the enclosing PURCHASE_ORDER document (ID property).
Query Condition
A query condition is a condition that is used to identify a specific set of x-documents
instances in the database. You can use it while fetching the x-document instances from
database. A simple condition has the following format:
<{propertyName} Value="{value}" MatchBy="{Match By Operator}">
This condition compares the value of the Property against the value provided, using
the MatchBy operator. The following is a list of valid MatchBy operators with
examples.
z Starts with (for Partial match)
<ITEM_NAME Value ="Muff" MatchBy="STARTS_WITH"/>. The value string
is interpreted as a literal. The value string will escape the following wild card
characters: %, _
z Ends With (for Partial Match)
<ITEM_NAME Value ="ffler" MatchBy="ENDS_WITH"/>. The value string is
interpreted as a literal. The value string will escape the following wild card
characters: %, _
z Contains (for Partial Match)
<ITEM_NAME Value ="ffl" MatchBy="CONTAINS"/>. The value string is
interpreted as a literal. The value string will escape the following wild card
characters: %, _
z Less Than Or Equal To (<=)
<TOTAL_QTY Value ="50" MatchBy="LESS_EQUAL"/>
z Greater Than or Equal To (>=)
<TOTAL_QTY Value ="50" MatchBy="GREATER_EQUAL"/>
z Less Than (<)
<CREATION_DATE Value="05/30/2000" MatchBy="LESS"/>
z Greater Than (>)
<CREATION_DATE Value="05/30/2000" MatchBy="GREATER"/>
z Exact Match (=)
<ITEM_ID Value ="Muffler" MatchBy="EQUAL"/>
z Not Equals (!=)

Chapter 5 X-Rules
<ITEM_ID Value ="Muffler" MatchBy="NOT_EQUAL"/>

z Like (LIKE)
<ITEM_ID Value ="Muf%fler" MatchBy="LIKE"/>. The Value must contain
wild card characters when using LIKE.
You can compare one property against the other using the following format:
<{propertyName} CompareProperty="{another property name}"
MatchBy="{Match By Operator}">
For example:
<PROMISED_TOTAL_QTY CompareProperty="DELIVERED_TOTAL_QTY"
MatchBy="GREATER">
Represents:
PROMISED_TOTAL_QTY > DELIVERED_TOTAL_QTY
The logical AND/OR operators can be used to combine simple condition to create
compound conditions.
For example:
<AND>
<ITEM_ID Value="Muffler" MatchBy="EQUAL"/>
<OR>
<SUPPLIER_ID Value="VIP DRAM" MatchBy="EQUAL"/>
<SUPPLIER_ID Value="Synekdo" MatchBy="EQUAL"/>
</OR>
</AND>
The compound condition represents:
ITEM_ID == "Muffler" AND (SUPPLIER_ID == "VIP DRAM" OR
SUPPLIER_ID == "Synekdo")
REMOVE_DOCUMENT
Description:
The REMOVE_DOCUMENT component deletes x-document instances that match
the query condition. All the document instances which refer to the deleted instances
with delete rule of CASCADE will also be deleted.
Syntax
<REMOVE_DOCUMENT Name="doc-name"
Synchronous="true|false[default=true]">
{A simple or compound query condition}
</REMOVE_DOCUMENT>
Attributes
z Name (Required): Document to be deleted.
z ServiceName (Optional): Name of the service which contains the X-Doc.


asynchronously.
Output Syntax:
<RESPONSE Status="success" RowCount="number" />
Output Attributes:
RowCount: returns the number of deleted instances.
Example 1
<REMOVE_DOCUMENT Name="PURCHASE_ORDER"
<BUYER_ID Value="buyer01" MatchBy="EQUAL"/>
</REMOVE_DOCUMENT>
<RESPONSE Status="success" RowCount="3" Description="Remove
Document Successful"/>
MODIFY_DOCUMENT
Description:
This operation allows one or more document instances that match the query
conditions to be modified.
All document instances matching the query condition are modified with the values of
the PropertyName tags specified in UPDATE_PROPERTIES. The property names
referenced in UPDATE_PROPERTIES should belong to the x-document specified.
There should be atleast one PropertyName tag under UPDATE_PROPERTIES. If
nothing is present, an exception may be raised.
The value of RowCount attribute in the response XML is the number of document
instances modified by this component.
Bypassing ABPP cache
MODIFY_DOCUMENT can result in ABPP caching the modified document instance
in memory and persisting it only when the transaction ends. To avoid caching and to
persist the document as soon as the modify document operation is executed, users can
specified an attribute on MODIFY_DOCUMENT called CacheHint="2". When this
hint is specified, MODIFY_DOCUMENT call will result in immediate update of the
database.
Syntax
<MODIFY_DOCUMENT Name="documentName"
Synchronous="true|false[default=true]"
CacheHint="0|1|2[default=0]">
<DOCUMENT_CONTEXT>
{A Simple or Compound query condition}
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>

Chapter 5 X-Rules
<propertyNameN Value="valueN" Repeatable="true"/>

</UPDATE_PROPERTIES>
</MODIFY_DOCUMENT>
Attributes
z Name (Required): Document to be modified.
z CacheHint (Optional): When set to '2', ABPP is guaranteed to perform a database
update at the end of the MODIFY_DOCUMENT operation. A value of 0 or 1
results in the default behavior which is to defer the database operation if possible.
asynchronously.
Example 1
The following request changes the state of PURCHASE_ORDER instances of
buyer01 to "hold":
<MODIFY_DOCUMENT Name="PURCHASE_ORDER"
<DOCUMENT_CONTEXT>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<STATE Value="hold"/>
</MODIFY_DOCUMENT>
<RESPONSE Status="success" RowCount="3" Description="Modify
Document Successful"/>
Example 2
You can also use expressions in the document context and update properties section of
modify document. Refer to the section on Expression before reading this example.
<MODIFY_DOCUMENT Name="ORG_RELN" AssignToVar="myResponse">
<DOCUMENT_CONTEXT>
<RELN_VAL Expression="#|RELN_VAL|#*2 - 10"/>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<RELN_VAL Expression="#|RELN_VAL|#*2">
</MODIFY_DOCUMENT>
SAVE
Description:
The SAVE operation can be used to insert or update a document instance to the
database. This operation will issue an update if the document instance already exists in
the database or issue an insert otherwise. It can be used only for documents that have a

primary key defined. This operation is equivalent to a GET_DOCUMENT operation

followed by MODIFY_DOCUMENT or ADD_DOCUMENT.
Syntax
<SAVE DocVar="myVar" ServiceName="service"
Type="Diff|Delta[default=Diff]"/>
Attributes
z DocVar (Required): Variable referencing the X-Doc instance that is to be saved to
the database.
z ServiceName (Optional): Service that owns the document instance; if not
specified, then the current service is taken as default.
z Synchronous (Optional): yes/no. If 'yes', then the save is performed right away,
otherwise it is done asynchronously. The default value is 'yes'.
z Type (Optional): Diff/Delta. This attribute is used only if the document instance
already exists in the database. If Type=Diff then any property value that exists in
the db copy but not present in the document instance will be set to null. If
Type=Delta then any property value that exists in the db copy but not present in
the document instance will be ignored.
Example 1

<TO_DOCVAR AssignToVar="myPODoc">
<PURCHASE_ORDER>
<ID Value="{$thisParam/ID/@Value}"/>
<BUYER_IDValue="buyer01"/>
<CREATION_DATE Value="{date()}"/>
<STATUS Value="Created"/>
</PURCHASE_ORDER>
</TO_DOCVAR>
<SAVE DocVar="myPODoc"/>
Example 2

<GET_DOCUMENT Name="PURCHASE_ORDER" AssignToVar="myPODocs">
<ID Value="PO-123" MatchBy="EQUAL"/>
</GET_DOCUMENT>
<SET Var="myPODoc" FromValue="{$myPODocs/PURCHASE_ORDER}"/>

<SET DocVar="myPODoc" Property="STATUS" FromValue="Hold"/>

<SAVE DocVar="myPODoc"/>
GET_DOCUMENT
Description:
The GET_DOCUMENT component allows document instances to be retrieved from
the database based upon query conditions.

Chapter 5 X-Rules
You can perform pagination by restricting the number of document instances returned
by a GET_DOCUMENT query; use the StartAtRow and MaxRows attributes to
specify this.
Syntax:
<GET_DOCUMENT Name="documentName"
RowName="rowTagName[Optional=true"
StartAtRow="number[optional=true, default=0]"
MaxRows="number[optional=true]"
ReturnRowCount="true|false[default=false]"
OraHint="xxx[Optional=true]"
Distinct="true|false[Optional=true]"
Mode="Write[Optional=true]">
{A Simple or Compound query condition [Optional=true]}
<SELECT>
<propertyN Repeatable="true"/>
</SELECT>
</GET_DOCUMENT>
Query conditions are specified to ensure that only document instances that satisfy the
conditions are retrieved from the database. If not specified, then all the documents are
retrieved from the database.
The properties in the SELECT tags, property1-propertyN etc. are used to specify
which properties should be retrieved by the component. If not specified, then all the
properties of the X-Doc instance are retrieved from the database.
Attributes:
Name (Required): The name of the X-Document to be retrieved
RowName (Optional): The tag in which the property tags of the X-Doc instances will
be enclosed. If not specified, then the name of the X-Document is used.
ServiceName (Optional): Service from which the document is retrieved. If not
specified, then owner service is taken as default.
AssignToVar (Optional): Variable to which the response is assigned.
StartAtRow (Optional): Starting row number from which records should be retrieved
MaxRows (Optional): Maximum number of records to be retrieved from database. If
this is not provided then it is defaulted to the Default MaxRows param. Currently this
is 1000 rows. You can also override the default max rows param for a service by
defining the service param, DEFAULT_MAX_ROWS_FETCH.
For Example,
The following lines in service-config file will set the default max rows for that service
to 20000
<service-params>
<param Name="DEFAULT_MAX_ROWS_FETCH" Value="20000"/>
</service-params>

ReturnRowCount - true/false (Optional): If true, the number of X-Doc instances in the

database which match the query condition is returned as TotalRowCount attribute in
the output.
OraHint (Optional): String containing a hint to oracle. This is needed maily for
optimizing the queries. This hint will be ignored for other DBs.
Distinct (Optional): true/false. If true, the generated SQL will have DISTINCT
keyword. If false, the generated SQL will not have DISTINCT keyword. If this
attribute is not specified then system will insert the DISTINCT keyword if it infers
that the query will result in duplicate rows without the keyword.
Mode (Optional): By default GET_DOCUMENT uses a read only database
connection for executing the query. Setting Mode attribute to "Write" will make it use
a read-write connection and issue a "select for update" query.
Example 1:
The basic GET_DOCUMENT operation has the following format:
<GET_DOCUMENT Name="LINE_ITEM" AssignToVar="myResponse">
</GET_DOCUMENT>
If no MatchBy operator is explicitly specified, then 'EQUAL' is taken as default.
Hence, the above operation can be simply written as:
<ITEM_ID Value="Muffler"/>
</GET_DOCUMENT>
<RESPONSE Status="success" Description="Get Document
Successful">
<LINE_ITEM>
<ID Value="LI-1254347890"/>
<SUPPLIER_ID Value="VIP DRAM"/>
<CREATION_DATE Value="09/17/2000 15:30:42"/>
<STATUS Value="open"/>
</LINE_ITEM>
<LINE_ITEM>
<ID Value="LI-1254347890"/>
<SUPPLIER_ID Value="Synekdo"/>
</LINE_ITEM>
</RESPONSE>
Example 2:
If more than one compound or simple query condition is used in a
GET_DOCUMENT, then the condition is combined into a single compound condition
using AND operator.

Chapter 5 X-Rules
The following is an example of a GET_DOCUMENT with two simple and one

compound query condition.
<OR>
</OR>
<STATUS Value="Open" MatchBy="EQUAL"/>
</GET_DOCUMENT>
The following GET_DOCUMENT is equivalent to the one described above,
<AND>
<OR>
</OR>
<STATUS Value="Open" MatchBy="EQUAL"/>
</AND>
</GET_DOCUMENT>
Example 3:
The following example shows a paginating query:
<GET_DOCUMENT Name="PURCHASE_ORDER" StartAtRow="0"
MaxRows="100" ReturnRowCount="true" AssignToVar="myResponse">
<CREATION_DATE MatchBy="GREATER" Value="01/01/2001"/>
</GET_DOCUMENT>
The above query will return the first 100 rows matching the condition.
<RESPONSE TotalRowCount="160">
<PURCHASE_ORDER>
...
</PURCHASE_ORDER>
...
</RESPONSE>
If the number of rows matching the query is less than 100, then it will return the actual
number of rows matching the query. If the query returns 100 rows, then you can
retrieve the next 100 rows (starting from row 100) by issuing the query:
<GET_DOCUMENT Name="PURCHASE_ORDER" StartAtRow="100"
MaxRows="100" AssignToVar="myResponse">
<CREATION_DATE MatchBy="GREATER" Value="01/01/2001"/>
</GET_DOCUMENT>
Expression
Description:
You can also use Expression attribute to specify a query. It is required when the SQL
expressions are fairly complex to be expressed in the standard GET_DOCUMENT

syntax. This is half way between using a standard GET_DOCUMENT and

EXECUTE_SQL_QUERY.
The expressions are in-lined in the generated SQL. You have to ensure that the
expressions provided actually make sense for the data base on which the query is
issued.
Any property tokens escaped using (#|, |#) in the expression will be replaced with the
actual database column names. The property tokens can be optionally prefixed with
the table name prefixes that will appear in the general SQL. For this purpose, you can
assign a prefix to the GET_DOCUMENT tag and each of the
QUERY_DOCUMENT_LINK tags appearing in the GET_DOCUMENT tag.
Example 1:
X-Docs for this example:
<DOCUMENT Name="ORG">
<PROPERTY Name="ID" PrimaryKey="true" Type="string(32)"/>
<PROPERTY Name="NAME" Type="string(32)"/>
<PROPERTY Name="OVAL" ColumnName="ORG_VAL" Type="float"/>
<DOCUMENTLINK Name="SELL_ORG_LINK"
LinkedDocument="ORG_RELN">
<MAP_PROPERTY To="SELL_ORG" From="ID"/>
</DOCUMENTLINK>
</DOCUMENT>
<DOCUMENT Name="ORG_RELN">
<PROPERTY Name="CUST_ORG" PrimaryKey="true"
Type="string(32)"/>
<PROPERTY Name="SELL_ORG" PrimaryKey="true"
Type="string(32)"/>
<PROPERTY Name="RELN_VAL" Type="float"/>
<DOCUMENTLINK Name="CUST_ORG_LINK" LinkedDocument="ORG">
<MAP_PROPERTY From="CUST_ORG" To="ID"/>
</DOCUMENTLINK>
<DOCUMENTLINK Name="SELL_ORG_LINK" LinkedDocument="ORG">
<MAP_PROPERTY From="SELL_ORG" To="ID"/>
</DOCUMENTLINK>
</DOCUMENT>
Example of Expression attribute:
<GET_DOCUMENT Name="ORG_RELN" Expression="#|p1.OVAL|# +

#|p2.OVAL|# = #|RELN_VAL|#">
<QUERY_DOCUMENT_LINK Name="CUST_ORG_LINK" Prefix="p1">
<OVAL Expression="2*#|OVAL|# - 10"/>
</QUERY_DOCUMENT_LINK>
<QUERY_DOCUMENT_LINK Name="SELL_ORG_LINK" Prefix="p2">
<OVAL Expression="2*#|OVAL|# - 10"/>
</GET_DOCUMENT>

Chapter 5 X-Rules
ORDER_BY
Description:
When using the GET_DOCUMENT operation to retrieve records, you can sort the
results of the query using the ORDER_BY tag.
Syntax:
<GET_DOCUMENT> <!-other required attributes not shown à
<ANY/>
<ORDER_BY>
<propertyNameN
Sort="Ascending|Descending[default=Ascending]"
Repeatable="true">
</ORDER_BY>
</GET_DOCUMENT>
Attributes
Sort (Optional): Ascending/Descending. Default=Ascending
Example 1:
The following is an example of a sorting query that returns a list of LINE_ITEM
instances, sorted by descending order of their creation date:
<ORDER_BY>
<CREATION_DATE Sort="Descending"/>
</ORDER_BY>
</GET_DOCUMENT>
Successful">
<LINE_ITEM>
<ID Value="LI-1254347890"/>
</LINE_ITEM>
<LINE_ITEM>
<ID Value="LI-7778889"/>
<SUPPLIER_ID Value="dram co."/>
</LINE_ITEM>
</RESPONSE>

GROUP_BY
Description:
You can use the GROUP_BY tag within a GET_DOCUMENT operation to sort and
select documents based on its properties. The query also returns the count of each
aggregated result.
Syntax:
<GET_DOCUMENT> <!-other attributes not shown à
<ANY/>
<GROUP_BY>
<propertyNameN Repeatable="true" />
</GROUP_BY>
</GET_DOCUMENT>
Attributes
None.
Example 1:
The following is an example of a sorting query that returns a list of
ORDER_POINT_SHIP_TO_MAP instances, grouped and sorted by the ORG_ID
property.
<GET_DOCUMENT Name="ORDER_POINT_SHIP_TO_MAP"
ReturnRowCount="true" MaxRows="5" AssignToVar="myResponse">
<SELECT>
<ORG_ID/>
<SHIP_TO_ID/>
<ORDER_POINT_ID/>
</SELECT>
<GROUP_BY>
<ORG_ID Value="Organization"/>
</GROUP_BY>
<ORDER_BY>
<ORG_ID/>
</ORDER_BY>
</GET_DOCUMENT>
<RESPONSE TotalRowCount="10" Status="Success">
<ORDER_POINT_SHIP_TO_MAP ExistingDocument="yes" Count="2">
<Organization Value="ORG_1"/>
</ORDER_POINT_SHIP_TO_MAP>

Chapter 5 X-Rules
</RESPONSE>
QUERY_DOCUMENT_LINK
Description:
The QUERY_DOCUMENT_LINK tag can be used within a GET_DOCUMENT
component to create a table-join between linked documents (declared using the
DOCUMENTLINK tag - refer to the X-Documents chapter for more details).
Syntax:
<ANY/>
<QUERY_DOCUMENT_LINK Name= "documentLinkName">
<PropertyN Value="value" Repeatable="true"/>
</GET_DOCUMENT>
Attributes
Name (Required): Document link name.
Example 1:
To retrieve purchase orders and the corresponding LINE_ITEMS, of a particular
buyer where at least one of the line items is in closed state, you can issue the following
query:
<GET_DOCUMENT Name="PURCHASE_ORDER" AssignToVar="myResponse">
<QUERY_DOCUMENT_LINK Name="LINE_ITEMS">
<STATUS Value="Closed"/>
<ORDER_BY>
<CREATION_DATE/>
</ORDER_BY>
<FETCH_DOCUMENT_LINK Name="LINE_ITEMS"/>
</GET_DOCUMENT>

Successful">
<PURCHASE_ORDER>
<ID Value=" PO-9854347890"/>
<PIN Value="1"/>
<MY Value="7000.0"/>

<LINE_ITEMS>
<LINE_ITEM>
<ID Value="LI-1254347890"/>
</LINE_ITEM>
<LINE_ITEM>
<ID Value="LI-7778889"/>
<ITEM_ID Value="mem_chip_123"/>
<SUPPLIER_ID Value="dram co."/>
<STATUS Value="closed"/>
</LINE_ITEM>
</LINE_ITEMS>
</PURCHASE_ORDER>
</RESPONSE>
Note that the 2nd LINE_ITEM instance has a "closed" status.
NOT_EXISTS_QDL
Description:
The NOT_EXISTS_QDL tag is used within a GET_DOCUMENT operation to create
a table-join such that only those documents are selected that do not have associated
instances in the linked document.
Syntax:
<NOT_EXISTS_QDL Name="documentLinkName"/>
</GET_DOCUMENT>
Attributes
Name (Required): Document link name.
Example 1:
The following query will retrieve all order point records that do not have entries in the
Bill To and Ship To link tables.
<GET_DOCUMENT Name="ORDER_POINT" AssignToVar="myResponse">
<STATUS Value="ACTIVE"/>
<OR>
<NOT_EXISTS_QDL Name="SHIP_TO_LIST_LINK"/>
<NOT_EXISTS_QDL Name="BILL_TO_LIST_LINK">
<BT_STATUS Value="ACTIVE"/>
</NOT_EXISTS_QDL>
</OR>
</GET_DOCUMENT>

Chapter 5 X-Rules
<ORDER_POINT ExistingDocument="yes">
<ID Value="OP06"/>
<ADDRESS_ID Value="addr-771063910853479"/>
<ALLOWS_BACKORDERS Value="false"/>
<CURRENCY_CODE Value="USD"/>
<CUSTOMER_ORG_ID Value="ORG_15"/>
<CUSTOMER_STATUS Value="ACTIVE"/>
<CUST_ORG_FNAME Value="i2 Technologies"/>
<CUST_ORG_NAME Value="i2"/>
<DEFAULT_BILL_TO_ID Value="BT03"/>
<DEFAULT_SHIP_TO_ID Value="SP06"/>
<NAME Value="Royal i2"/>
<REQUIRES_ORDER_NUMBER Value="false"/>
<STATUS Value="ACTIVE"/>
</ORDER_POINT>
</RESPONSE>
Example 2:
The following query will retrieve all organization records that have an associated
order point but the order point in turn does not have ship to association:
<GET_DOCUMENT Name="ORGANIZATION" AssignToVar="myResponse">
<QUERY_DOCUMENT_LINK Name="ORDER_POINT_LIST_LINK">
<NOT_EXISTS_QDL Name="SHIP_TO_LIST_LINK">
<QUERY_DOCUMENT_LINK Name="SHIP_TO_INFO_LINK">
<ORG_ID Value="ORG_71"/>
</NOT_EXISTS_QDL>
</GET_DOCUMENT>
<ORGANIZATION ExistingDocument="yes">
<ID Value="ORG_1"/>
<ADDRESS_ID Value="addr-11063910768266"/>
<ALLOWS_BACKORDERS Value="true"/>
<CURRENCY_CODE Value="USD"/>
<CUSTOMER_STATUS Value="ACTIVE"/>
<DEFAULT_FC_ID Value="FC_2"/>
<FULL_NAME Value="GE Worldwide"/>
<GENERATE_INVOICES Value="true"/>
<IS_REPAIR_VENDOR Value="true"/>
<IS_SINGLE_CORPORATE Value="false"/>
<IS_VRMA_REQUIRED Value="false"/>
<NAME Value="GE"/>
<SELLER_STATUS Value="ACTIVE"/>
<TAX_CODE Value="FEIN"/>
<TAX_ID Value="234T34T23TG45Y2Y"/>
<TRANSFER_ORDERS_BILLABLE Value="false"/>
<URL Value="www.ge.com"/>
</ORGANIZATION>

</RESPONSE>
SELECT + QUERY_DOCUMENT_LINK
Description:
The properties of a linked document can be retrieved alongside the property elements
of the parent document by using the QUERY_DOCUMENT_LINK and SELECT tags
together. An alias can be specified for each selected property in the Query document
link and it will be used as the property name in the parent document.
Syntax:
<QUERY_DOCUMENT_LINK Name= "documentLinkName">
<SELECT>
<propertyNameN Alias="abc[Optional=true]"
Repeatable="true"/>
</SELECT>
{query condition for linked document}
</GET_DOCUMENT>
Example 1:
The following query returns the ITEM_ID (as ITEM) and ORDERED_QTY (as
LINE_QTY) fields from the ORDER_LINE_ITEM document and
DELIVERY_DATE (as REQ_DELIVERY_DATE) from the ORDER_REQUEST
document into the parent, CUSTOMER_ORDER, document.
<GET_DOCUMENT Name="CUSTOMER_ORDER" Distinct="true"
<SELECT>
<ID/>
<ORDER_POINT_ID/>
</SELECT>
<QUERY_DOCUMENT_LINK Name="ORDER_LINE_ITEMS">
<SELECT>
<ITEM_ID Alias="ITEM"/>
<ORDERED_QTY Alias="LINE_QTY"/>
</SELECT>
<QUERY_DOCUMENT_LINK Name="ORDER_REQUESTS">
<SELECT>
<DELIVERY_DATE Alias="REQ_DELIVERY_DATE"/>
</SELECT>
<ORDER_BY>
<ID/>
</ORDER_BY>
</GET_DOCUMENT>
<CUSTOMER_ORDER ExistingDocument="yes">
<ID Value="CO-1"/>

Chapter 5 X-Rules
<ORDER_POINT_ID Value="OP01"/>
<ITEM Value="151-S"/>
<LINE_QTY Value="6.0"/>
<REQ_DELIVERY_DATE Value="09/23/2003 00:00:00:000"/>
</CUSTOMER_ORDER>
</RESPONSE>
FETCH_DOCUMENT_LINK
Description:
The FETCH_DOCUMENT_LINK tag can be used within the GET_DOCUMENT
operation to retrieve linked document instances. In addition, you could specify query
condition to restrict the documents fetched, use ORDER_BY tag to sort the linked
documents and nest FETCH_DOCUMENT_LINK tags to retrieve nested documents.
Syntax:
The format of FETCH_DOCUMENT_LINK tag is as follows
<GET_DOCUMENT Name="myDoc"> <!-other attributes not shown à
<FETCH_DOCUMENT_LINK Name="documentLinkName">
{ query condition }[Optional=true]
<ORDER_BY Optional="true">
<propertyNameN />
</ORDER_BY>
</FETCH_DOCUMENT_LINK>
</GET_DOCUMENT>
Attributes
z Name (Required): Document to be deleted.
Example 1:
The following is an example of fetching document that returns LINE_ITEMS and
PROMISED SCHEDULE Instances along with the PURCHASE_ORDER.
<GET_DOCUMENT Name="PURCHASE_ORDER" AssignToVar="myResponse">
<ID Value="PO-7854347890" MatchBy="EQUAL"/>
<FETCH_DOCUMENT_LINK Name="LINE_ITEMS">

<FETCH_DOCUMENT_LINK Name="SCHEDULES">



<ORDER_BY Sort="Ascending">
<PROMISED_TOTAL_QTY/>
</ORDER_BY>

</GET_DOCUMENT>
<RESPONSE Status="success">
<PURCHASE_ORDER>
<ID Value=" PO-7854347890"/>
<PIN Value="1"/>
<MY Value="7000.0"/>
<LINE_ITEMS>
<LINE_ITEM>
<ID Value="LI-1254347890"/>
<SCHEDULES>
<PROMISED_SCHEDULE>
<ID Value="PS-994347890"/>
<PROMISED_DATE Value="11/12/2000
11:45:30"/>
<PROMISED_QUANTITY Value="50"/>
</PROMISED_SCHEDULE>
<PROMISED_SCHEDULE>
<ID Value="PS-784347890"/>
<PROMISED_DATE Value="11/15/2000
11:45:30"/>
<PROMISED_QUANTITY Value="25"/>
</PROMISED_SCHEDULE>
</SCHEDULES>
</LINE_ITEM>
</LINE_ITEMS>
</PURCHASE_ORDER>
</RESPONSE>
The LINE_ITEM instances are in ascending order of PROMISED_TOTAL_QTY.
SQL_FN
Description:
The SQL_FN tag can be used within the select clause of a GET_DOCUMENT query
to perform selected mathematical functions on a document property. The supported
functions are:
z SUM (Summation of property values)

Chapter 5 X-Rules
z COUNT (Count of all the records that match a certain criteria. Note that it is
different from the ReturnRowCount and RowCount attributes)
z MIN (Minimum among all the property values)
z MAX (Maximum among all the property values)
SQL functions can take as arguments document properties, a constant value and other
SQL functions. Compound arguments containing document properties or constant
values can be constructed using the following operators: ADD, MINUS, MULT and
DIV operators.
Arithmetic operators can also be specified to compute the result of the SQL function.
Syntax:
<SQL_FN Name="Function" Alias="Query-Result-Name">
<CHOICE_OF Optional="true">
<CHOOSE>
<PROP Name="Property Name" Repeatable="true"/>
</CHOOSE>
<CHOOSE>
[Compound expressions]
</CHOOSE>
</CHOICE_OF>
</SQL_FN>
Attributes
z Name (Required): SUM/COUNT/MIN/MAX
z Alias (Required): Property to which the query result is assigned.
Example 1:
The following example shows how the SUM function can be used in multiple ways:
<GET_DOCUMENT Name="INVENTORY" AssignToVar="myResponse">
<SELECT>
<ITEM_ID/>
<LOCATION_ID/>
<SQL_FN Name="SUM" Alias="SUM_IN_TRANSIT">
<PROP Name="IN_TRANSIT"/>
</SQL_FN>

<SQL_FN Name="SUM" Alias="EXPECT_SUM">
`<MINUS>
<ADD>
<PROP Name="ON_ORDER"/>
</ADD>
<PROP Name="DAMAGED"/>
</MINUS>
</SQL_FN>

<SQL_FN Name="SUM" Alias="COMPLEX_SUM">
<MINUS>
<ADD>
<DIV>
<MULT>

<CONSTANT Value="2"/>
</MULT>
<CONSTANT Value="2"/>
</DIV>
<PROP Name="ON_ORDER"/>
</ADD>
<PROP Name="DAMAGED"/>
</MINUS>
</SQL_FN>
</SELECT>
<ITEM_ID Value="151-S"/>
<OR>
<LOCATION_ID Value="FC_1"/>
<LOCATION_ID Value="DC_1"/>
</OR>
<GROUP_BY>
<ITEM_ID/>
<LOCATION_ID/>
</GROUP_BY>
<ORDER_BY>
<ALIAS Name="COMPLEX_SUM" Sort="Descending"/>
</ORDER_BY>
</GET_DOCUMENT>
<INVENTORY ExistingDocument="yes" Count="1">
<SUM_IN_TRANSIT Value="5000.0"/>
<EXPECT_SUM Value="6900.0"/>
<COMPLEX_SUM Value="6900.0"/>
<LOCATION_ID Value="DC_1"/>
</INVENTORY>
<SUM_IN_TRANSIT Value="5000.0"/>
<EXPECT_SUM Value="6800.0"/>
<COMPLEX_SUM Value="6800.0"/>
</INVENTORY>
</RESPONSE>
Example 2:
The following example shows how the SUM and MAX functions can be used:
<GET_DOCUMENT Name="INVENTORY" StartAtRow="0" MaxRows="2"
ReturnRowCount="yes" AssignToVar="myResponse">
<SELECT>
<ITEM_ID/>
<LOCATION_ID/>
<SQL_FN Name="SUM" Alias="QTY">

Chapter 5 X-Rules
<PROP Name="UNRESTRICTED"/>
</SQL_FN>
<SQL_FN Name="MAX" Alias="LAST_UPDATE_TIME">
<PROP Name="LAST_UPDATE_TIME"/>
</SQL_FN>
</SELECT>
<ITEM_ID Value="1" MatchBy="STARTS_WITH"/>
<GROUP_BY>
<ITEM_ID/>
<LOCATION_ID/>
</GROUP_BY>
</GET_DOCUMENT>
<RESPONSE TotalRowCount="4" Status="Success">
<QTY Value="200.0"/>
<LAST_UPDATE_TIME Value="01/19/2004 20:51:08:000"/>
</INVENTORY>
<LAST_UPDATE_TIME Value="01/16/2004 09:34:55:000"/>
<ITEM_ID Value="1C6936G05"/>
</INVENTORY>
</RESPONSE>
Example 3:
The following example shows how the COUNT function is used:
<GET_DOCUMENT Name="INVENTORY" AssignToVar="myResponse">
<SELECT>
<SQL_FN Name="COUNT" Alias="TOTAL_COUNT"/>
</SELECT>
<ITEM_ID Value="1" MatchBy="STARTS_WITH"/>
</GET_DOCUMENT>
The response from the above query is:
<INVENTORY ExistingDocument="yes" Count="3"/>
</RESPONSE>
Scalar Functions
For performing column operations in the where clause of a SQL query, the 'ScalarFn'
attribute can be used on a property name in a GET_DOCUMENT operation. The
attribute operates on a single column and supports the following functions:
z upperCase: To enable upper case conversion of a column

z lowerCase: To enable lower case conversion of a column

z char: To convert a column to char
z float: To convert column to numeric value
z double: To convert column to numeric value
Syntax
<GET_DOCUMENT Name="CAR"> <!-other attributes not shown à
<ANY/>
<propertyN Value="Value" MatchBy="Operator[Optional=true]"
ScalarFn="function[Optional=true]" Repeatable="true"/>
</GET_DOCUMENT>
Example 1
<GET_DOCUMENT Name="PARENT" AssignToVar="myResponse">
<NAME Value="Computer%" MatchBy="LIKE"
ScalarFn="upperCase"/>
</GET_DOCUMENT>
Will result in query with upper(NAME) LIKE 'Computer%' in SQL.
Example 2
<GET_DOCUMENT Name="CAR" AssignToVar="myResponse">
<MODEL Value="TT"/>
<MSRP CompareProperty="PRICE" MatchBy="NOT_EQUAL"
ScalarFn="char"/>
</GET_DOCUMENT>
Example 3
<MODEL Value="TT"/>
<MSRP CompareProperty="PRICE" MatchBy="GREATER_EQUAL"
ScalarFn="float"/>
</GET_DOCUMENT>
Example 4
<MODEL Value="TT"/>
<PRICE CompareProperty="MSRP" MatchBy="GREATER"
ScalarFn="double"/>
</GET_DOCUMENT>
GET_DOC_CHUNKED
Description:
Most databases have limitation on the size of the SQL statement that can be issued. If
you have a lot of OR conditions in your GET_DOCUMENT request, you can exceed
the database size limits on the generated SQL.
GET_DOC_CHUNKED component can be used instead of GET_DOCUMENT to
over come the size limitation for cases where there is an <OR> tag just under
GET_DOCUMENT containing a large number of child tags.
This component will break the <OR> tag in chunks and execute GET_DOCUMENT
component for each of the chunks and then combine their responses to return the final
response.

Chapter 5 X-Rules
The GET_DOC_CHUNKED component cannot be used with StartAtRow and

ReturnRowCount attributes. The MaxRows attribute specified on
GET_DOC_CHUNKED will be passed on to the individual GET_DOCUMENTs but
the final result will not honor the MaxRows.
The Distinct attribute specified on GET_DOC_CHUNKED will be passed on to the
individual GET_DOCUMENTs but the uniqueness in final result is controlled by the
attribute InMemoryDistinct that is explained below.
Syntax:
<GET_DOC_CHUNKED Name="docName"
ServiceName="name[Optional=true]"
InMemoryDistinct="true|false[default=true]"
ChunkSize="10[Type=positive-number, default=100]"
AssignToVar="varName" Distinct="true|false">
<OR>
<ANY Repeatable="true" Comment="potentially a big list
"/>
</OR>
<ANY Comment="any other tags that normal GET_DOCUMENT
supports"/> ...
</GET_DOC_CHUNKED>
InMemoryDistinct: Since this component is merging response from multiple
GET_DOCUMENTs there is a possibility that there can be duplicate records. The
component can remove these duplicates only if the individual GET_DOCUMENT
response has values for all the primary keys for this document. If this
'InMemoryDistinct' attribute is true and the GET_DOCUMENT response has all the
primary keys of the document then duplicate records will be removed from final
response. Otherwise there can be duplicates in the the response even if you have used
'Distinct' attribute. This is especially true if you have <SELECT> tag that does not
select primary keys or selects partial primary keys. Default value for this attribute is
true.
ChunkSize: This attribute defines the chunk size used for breaking up the input <OR>
in smaller chunks. Default for this is 100.
Example:
<GET_DOC_CHUNKED Name="ORDER_SCHEDULE" InMemoryDistinct="false"
ChunkSize="10" AssignToVar="myResponse">
<OR>
<ID Value="1"/>
<ID Value="2"/>

<ID Value="101"/>
</OR>
<CUST_ORG_ID Value="Velocity"/>
</GET_DOC_CHUNKED>
PROCESS_GET_DOCUMENT
Description:
The PROCESS_GET_DOCUMENT component retrieves a set of document instances
based on query conditions identical to that of the GET_DOCUMENT component

(Please see details on the GET_DOCUMENT component for further information).

However PROCESS_GET_DOCUMENT retrieves documents in batches with the
batch size specified as an attribute. On each batch of records retrieved, a set of actions
can be executed conditionally.
This operation is useful for:
a. Processing high-volume data without running into memory issues.
b. Conditional processing of a batch of records.
Syntax
<PROCESS_GET_DOCUMENT Name="documentName" BatchSize="noOfRows">
<GET_DOCUMENT_BODY Mode="Write[Optional=true]">
<ANY/> 
</GET_DOCUMENT_BODY>
<ON_EACH_BATCH List="ListVariable"
ContinueExpr="expr[Optional=true]">
<ANY/>

</ON_EACH_BATCH>
</PROCESS_GET_DOCUMENT>
Attributes
z Name (Required): The name of the X-Document to be retrieved
z BatchSize (Required): The batch size is indicated here.
z ServiceName (Deprecated): This attribute has been deprecated. This action
component should be only used for documents in the current service.
z Mode (Optional): By default PROCESS_GET_DOCUMENT uses a read only
database connection for executing the query. Setting Mode attribute to "Write"
will make it use a read-write connection and issue a "select for update" query.
z List (Required): Variable to which the retrieved batch of records are assigned
z ContinueExpr (Optional): X-Path expression. This expression should evaluate to
true for the actions within the ON_EACH_BATCH to be executed for a particular
batch of data being processed. The default value is true.
Example 1
The following updates the price incrementally for each batch on the LineItem
document instances.
<SET Var="newPrice" FromValue="8"/>

<PROCESS_GET_DOCUMENT Name="LineItem1" BatchSize="2">
<GET_DOCUMENT_BODY>
<Price Value="8" MatchBy="EQUAL"/>
<ON_EACH_BATCH List="lines">
<SET Var="newPrice" FromValue="{$newPrice + 1}"/>
<FOR_EACH SelectList="$lines" CurrentElement="item">
<MODIFY_DOCUMENT Name="LineItem"
AssignToVar="result">
<DOCUMENT_CONTEXT>

Chapter 5 X-Rules
<ID Value="{$item/ID/@Value}"/>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<Price Value="{$newPrice}"/>
</MODIFY_DOCUMENT>
</FOR_EACH>
</ON_EACH_BATCH>
On successful execution of the component:

The price on the first 2 records is set to 9. The price on the next 2 records will be set to
10 and so-on.
Example 2
Assume that there is a document ORDER_SCHEDULE that has ID as the primary key
and other columns like DELIVERY_DATE, QTY and ALLOC_QTY. Lets say that the
requirement is to take user defined quantity and allocate it across
ORDER_SCHEDULEs with a particular delivery date (say 01/01/2006) such that the
allocated quantity (ALLOC_QTY) does not exceed the QTY of
ORDER_SCHEDULE. The number of matching entries in ORDER_SCHEDULE can
be large. The PROCESS_GET_DOCUMENT action component can be used as
follows:
<SET Var="qtyToAllocate" FromValue="245"/>

<PROCESS_GET_DOCUMENT Name="ORDER_SCHEDULE" BatchSize="2">
<GET_DOCUMENT_BODY>
<DELIVERY_DATE Value="1/1/2006"/>
<OR>
<ALLOC_QTY/>
<ALLOC_QTY CompareProperty="QTY" MatchBy="LESS"/>
</OR>

<ON_EACH_BATCH List="schs" ContinueExpr="$qtyToAllocate >
0">
<FOR_EACH SelectList="$schs" CurrentElement="sch">

<IF_TEST Test="$qtyToAllocate = 0">
<THEN>
<BREAK/>
</THEN>
</IF_TEST>

<SET Var="schQty" FromValue="{$sch/QTY/@Value}"/>

<SET Var="allocQty" FromValue="{$sch/ALLOC_QTY/
@Value}"/>

<SET Var="allocQty" FromValue="{ifElse($allocQty =

null, 0, $allocQty)}"/>

<SET Var="maxAllocation" FromValue="{$schQty -
$allocQty}"/>
<IF_TEST Test="$qtyToAllocate >= $maxAllocation">
<THEN>
<SET Var="newAllocQty"
FromValue="{$schQty}"/>
<SET Var="qtyToAllocate"
FromValue="{$qtyToAllocate - $maxAllocation}"/>
</THEN>
<ELSE>
<SET Var="newAllocQty"
FromValue="{$allocQty + $qtyToAllocate}"/>
<SET Var="qtyToAllocate" FromValue="0"/>
</ELSE>
</IF_TEST>
<MODIFY_DOCUMENT Name="ORDER_SCHEDULE"
AssignToVar="result">
<DOCUMENT_CONTEXT>
<ID Value="{$sch/ID/@Value}"/>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<ALLOC_QTY Value="{$newAllocQty}"/>
</MODIFY_DOCUMENT>
</FOR_EACH>
</ON_EACH_BATCH>
EXEC_SQL_QUERY
Description:
You can perform a raw SQL query on the database and get the results of the query in a
XML format. The calling application is responsible for issuing syntactically correct
SQL statement. You can also issue paginated raw sql queries.
Syntax
<EXEC_SQL_QUERY RowName="rowTagName"
StartAtRow="number[default=0]"
ReturnRowCount="true|false[default=false, Optional=true]"
MaxRows="number[Optional=true]",
GetNullTags="true|false[default=false, Optional=true]",
Mode="Write[Optional=true]" FetchSize="100[Optional=true]">
<SQL>sql-string</SQL>
<PARAM Value="paramVal" Type="paramType[Optional=true,
default=string]" Repeatable="true"/>
</EXEC_SQL_QUERY >
Attributes

Chapter 5 X-Rules
z StartAtRow (Optional): Beginning row number.

z MaxRows (Optional): Maximum number of rows to be returned.
z ReturnRowCount (Optional): true|false. If true, then the response will contain
another attribute TotalRowCount specifying the total number of records that
qualified the query string. Default is false.
z RowName (Optional): The tag in which the results will be enclosed. If not
specified, then SQL_RESULT is used.
z GetNullTags (Optional):true|false. If true, then empty tags are returned for null
values; default is false.
z AssignToVar (Optional): Variable to which the query result is assigned.
z Mode (Optional): By default EXEC_SQL_QUERY uses a read only database
connection for executing the sql. Setting Mode attribute to "Write" will make it
use a read-write connection. This is needed for "select for update" kind of queries.
z FetchSize (Optional): The FetchSize specified is provided as a hint to the JDBC
driver for fetching specified number of rows when more rows are to be fetched
from the database.
Param Tag Element (Optional)
Parameter Values need to be given in the order they are specified in the SQL Query.
Additionally, they need to match the number of parameters given in the SQL Query.
PARAM.Value: The value of the parameter.
PARAM.Type (Optional): The datatype of the column. If not specified the default type
used is string. Valid values for this attribute are the datatypes supported by ABPP X-
Documents (refer to the X-Document chapter). Example: string, boolean, int, long,
float, double, date, datetime, timestamp etc.
Example 1
<EXEC_SQL_QUERY AssignToVar="myResponse">
<SQL>Select count(*) As COUNT from PURCHASE_ORDER</SQL>
</EXEC_SQL_QUERY>
<SQL_RESULT>
<COUNT Value="45"/>
</SQL_RESULT>
</RESPONSE>
Example 2
<EXEC_SQL_QUERY RowName="CustomerOrder" GetNullTags="yes"
MaxRows="1" AssignToVar="myResponse">
<SQL>Select * FROM CUSTOMERORDER where CREATEDDATE > ?</
SQL>
<PARAM Value="{$date}" Type="datetime"/>
</EXEC_SQL_QUERY>


<RESPONSE Status="success" >
<CustomerOrder>
<ORDERID Value="CO1"/>
<CREATEDATE Value="04/23/2005 15:12:36:983"/>
<CUSTID Value="jdoe"/>
<ID Value="1"/>
</CustomerOrder>
</RESPONSE>
Example 3
Here is an example of using EXEC_SQL_QUERY with variable number of
parameters.
<DEFINE_METHOD Name="testSqlQueryWithStringList">
<RULE>
<ACTION>
<TO_DOCVAR AssignToVar="inputXml">
<ORDERS>
<ID Value="1"/>
<ID Value="2"/>
<ID Value="3"/>
<ID Value="4"/>
</ORDERS>
</TO_DOCVAR>
<EXEC_SQL_QUERY AssignToVar="sqlResponse">
<SQL>select * from CUSTOMER_ORDER where ID in
({buildSqlParamStr(count($inputXml/ID))})</SQL>
<FOR_EACH SelectList="$inputXml/ID"
CurrentElement="id">
<APPEND_TO_XML>
<PARAM Value="{$id/@Value}"
Type="string"/>
</APPEND_TO_XML>
</FOR_EACH>
</EXEC_SQL_QUERY>
<PRINTLN Value="The sql response is:
{$sqlResponse}"/>
</ACTION>
</RULE>
</DEFINE_METHOD>
Here buildSqlParamStr(int) function is used to build a comma separated string of
question marks as: "?,?,?". The parameter to this function is the number of question
marks needed.
EXEC_LOGICAL_SQL_QUERY
Description
You can perform a raw SQL query on the database and get the results of the query in a
XML format. However the key difference in this command as compared to
EXEC_SQL_QUERY is that you can refer to the tables and columns by their logical
names (the logical names are the ones defined in X-document files). The main

Chapter 5 X-Rules
advantage of that is that you no longer need to change your code if the physical names
in the schema change.
All logical references in the SQL quey need to be enclosed in markers in order to
differentiate them for the physical names. The marker for a table is T (<xdoc-name>)
and that for a column is C (<property-name>). You can also have a mix of logical and
physical references in your query, as long as you mark all the logical references. In
case you want to access tables other than those in the calling service, you can prefix
the xdoc name by service name such as T(<service-name>.<xdoc-name>). The use of
aliases for logical references is mandatory.
The command will internally convert all logical references to corresponding physical
names before issuing the raw query to the database. Also, the conversion back to
logical names will also be handled automatically. The calling application is
responsible for issuing syntactically correct SQL statement. You can also issue
paginated sql queries.
Syntax
<EXEC_LOGICAL_SQL_QUERY RowName=”rowTagName[Optional=true]”
StartAtRow="number[default=0]" MaxRows="number[Optional=true]",
ReturnRowCount="true|false[default=false, Optional=true]"
GetNullTags="true|false[default=false], [Optional=true]",
AssignToVar=”variableName[Optional=true]”
Mode="Write[Optional=true]" FetchSize="100[Optional=true]">
<SQL>logical-sql-string</SQL>
<PARAM Value="paramVal" Type="paramType[Optional=true,
default=string]" Repeatable=”true”/>
</EXEC_LOGICAL_SQL_QUERY >
Attributes
z RowName (Optional): The tag in which the results will be enclosed. If not
specified, then SQL_RESULT is used.
z StartAtRow (Optional): Beginning row number.
z MaxRows (Optional): Maximum number of rows to be returned.
z ReturnRowCount (Optional): true|false. If true, then the response will contain
another attribute TotalRowCount specifying the total number of records that
qualified the query string. Default is false.
z GetNullTags (Optional):true|false. If true, then empty tags are returned for null
values; default is false.
z Mode (Optional): By default this action component uses a read only database
connection for executing the sql. Setting Mode attribute to "Write" will make it
use a read-write connection. This is needed for "select for update" kind of queries.

z FetchSize (Optional): The FetchSize specified is provided as a hint to the JDBC

driver for fetching specified number of rows when more rows are to be fetched
from the database.
Example 1
<EXEC_LOGICAL_SQL_QUERY AssignToVar=”myResponse”>
<SQL> select C(t1.ID), C(t1.NAME) AS CITY_NAME, t1.C_AREA,
C(t2.NAME) from T(PM.CITY t1), T(PM.COUNTRY t2) where
C(t1.COUNTRY) = t2.CY_NAME</SQL>
</EXEC_LOGICAL_SQL_QUERY>
Points to note in this example:

1. As shown use of alias with logical references is mandatory
2. Tables in other service (e.g. PM) are accessed by prefixing the table names with
“PM.”
3. Mixed use of physical and logical names is allowed
Example 2
The following example shows use of multiple nested queries:
<EXEC_LOGICAL_SQL_QUERY GetNullTags="yes" MaxRows="10"

AssignToVar=”myResponse”>
<SQL>select C(t1.ID), C(t1.NAME), t1.C_AREA AS MY_AREA from
T(PM.CITY t1) where C(t1.COUNTRY) in (select C(t1.NAME) from
T(COUNTRY t1) where C(t1.AREA) > (select min(t2.C_AREA) from
T(CITY t2))) and C(t1.POPULATION) = (select
max(C(z.POPULATION)) from T(PM.COUNTRY z)) order by C(t1.ID)</
SQL>
Example 3
The following example show use of aggregate functions:
<SQL> select sum(C(t1.AREA)) AS MYSUM from T(PM.CITY t1)</
SQL>

Chapter 5 X-Rules
Example 4
The following example shows use of logical column marker when selecting all
columns. Below the return XML will have physical names for columns of t2 but
logical names for columns of table t1 as t1.* has been enclosed in a logical column
marker and t2.* has not been.
<SQL> select C(t1.*), t2.* from T(CITY t1), T(COUNTRY t2)
where t1.C_country = C(t2.NAME)</SQL>
EXEC_SQL_DML
Description:
You can execute a raw SQL data manipulation language (DML) statement on the
database and get the results of the query in a XML format. The calling application is
responsible for issuing syntactically correct SQL statement.
The response contains an 'UpdateRowCount' attribute that is assigned the number of
rows updated by the SQL query.
Syntax
<EXEC_SQL_DML AssignToVar="myVar[Optional=true]">
<PARAM Value="paramValue" Type="paramType[Optional=true,
default=string]" Repeatable="true"/>
</EXEC_SQL_DML>
Attributes
Example 1
<EXEC_SQL_DML AssignToVar="myResponse">
<SQL>DELETE FROM WFL_ATV_EVENTS WHERE TEMPLATE = ?</SQL>
<PARAM Value="Test"/>
</EXEC_SQL_DML>

<RESPONSE Status="success" UpdateRowCount="1000"/>
EXEC_LOGICAL_SQL_DML
Description
You can execute a raw SQL data manipulation language (DML) statement on the
database and get the results of the query in a XML format. However the key difference
in this command as compared to other similar commands is that you can refer to the
tables and columns by their logical names (the logical names are the ones defined in
X-document files). The main advantage of that is that you no longer need to change
your code if the physical names in the schema change.
All logical references in the SQL query need to be enclosed in markers in order to
differentiate them for the physical names. The marker for a table is T (<xdoc-name>)
and that for a column is C (<property-name>). You can also have a mix of logical and
physical references in your query, as long as you mark all the logical references. In
case you want to access tables other than those in the calling service, you can prefix
the xdoc name by service name such as T(<service-name>.<xdoc-name>). Also, the
use of aliases for the logical references is mandatory in the current implementation.
The calling application is responsible for issuing syntactically correct SQL statement.
The response contains an ‘UpdateRowCount’ attribute that is assigned the number of

Syntax
<EXEC_LOGICAL_SQL_DML AssignToVar="myVar[Optional=true]">
<SQL>logical-sql-string</SQL>
<PARAM Value="paramValue" Type="paramType[Optional=true,
default=string]" Repeatable=”true”/>
</EXEC_LOGICAL_SQL_DML>
Attributes
Example 1
<EXEC_LOGICAL_SQL_DML AssignToVar="myResponse">
<SQL>DELETE FROM T(PM.CITY t) WHERE C(t.NAME) = ?</SQL>

Chapter 5 X-Rules
<PARAM Value="Test"/>

<RESPONSE Status="success" UpdateRowCount="1000"/>
Example 2
<SQL> INSERT INTO T(PURCHASE_ORDER t1) (C(t1.ID),
C(t1.SELLING_ORG_ID)) values ('P02','S01')</SQL>
Example 3
<SQL> INSERT INTO T(PURCHASE_ORDER t1) (C(t1.ID),
C(t1.SELLING_ORG_ID)) (SELECT C(t2.ID), 'S01' from T(OLD_PO
t2)) </SQL>
EXEC_BATCH_SQL_DML
Description:
This command will execute a batch of DML statements as a single jdbc batch update
statement. All the DML statements in the batch execute the same sql statement with
different set of parameter values. The number of statements executed in the batch is
inferred by the number of occurrence of PARAMS tag. The output returns the number
of rows updated for each of the statements in the batch.
Syntax
<EXEC_BATCH_SQL_DML AssignToVar="myVar[Optional=true]">
<SQL> sql-statement </SQL>
<PARAMS Repeatable="true"
Comment="each occurrence corresponds to a statement in the
batch">
<PARAM Type="data-type[optional=true, default=string]"
Value="value-of-param[Optional=true]" Repeatable="true"/>
</PARAMS>
</EXEC_BATCH_SQL_DML>
The number of occurrences of the PARAMS tag is the batch size. Each PARAMS tag
lists the arguments to be used for that DML statement execution. This command will
execute a batch of DML statements.
Attributes:
AssignToVar (Optional): Variable to which the DML result is assigned
PARAM.Type (Optional): The Type attribute can be used to specify the datatype of
the column. If not specified the default type used is string. Valid values for this
attribute are the datatypes supported by ABPP X-Documents (refer to the X-

Document chapter). Example: string, boolean, int, long, float, double, date, datetime,
timestamp etc.
PARAM.Value (Optional): The value of the parameter. If not provided then the
parameter is set to NULL.
Output Syntax:
<UPDATE_ROW_COUNT Status="Success [Type=Constant]"
Value="number[Type=int]" Repeatable="true"
Comment="as many occurrences as the batch size" />
</RESPONSE>
Output Attributes:
UPDATE_ROW_COUNT.Value: This is the number of the rows updated by the DML
statement.
There will be as many UPDATE_ROW_COUNT tags in the output as the batch size.
EXEC_SQL_DDL
Description:
You can execute a raw SQL data definition language (DDL) statement on the database
and get the results of the query in a XML format. The calling application is
responsible for issuing syntactically correct SQL statement.
The response contains an 'UpdateRowCount' attribute that is assigned the number of
Syntax
<EXEC_SQL_DDL AssignToVar="myVar[Optional=true]">
</EXEC_SQL_DDL>
Attributes
Example 1
<EXEC_SQL_DDL AssignToVar="response">
<SQL>ALTER TABLE ECS.WFL_ATV_EVENTS ADD (TEST
VARCHAR2(32))</SQL>
</EXEC_SQL_DDL>
The response from the above query is:
<RESPONSE Status="success" UpdateRowCount="0">
</RESPONSE>
EXEC_PROC
Description:
Using the EXEC_PROC operation, you can execute a database procedure and get the
results of the query in a XML format. The calling application is responsible for issuing
syntactically correct SQL statement.

Chapter 5 X-Rules
Syntax
<EXEC_PROC Name="procName" AssignToVar="myVar[Optional=true]">
<ARGUMENT Type="IN/OUT/IN_OUT" Value="value"
DataType="string"/>
...
</EXEC_PROC >
Attributes
z Name (Required): Procedure name.
Child Tags/Attributes
You have the option to pass one or more arguments to the procedure, each having the
following attributes:
z Type (Required): IN indicates that the argument is an input to the procedure; OUT
indicates that the procedure returns this argument; IN_OUT indicates that this
argument is both an input to and an output from the procedure
z Value (Optional): The value of the argument (not required if it is an OUT type). If
IN/IN_OUT type, do not provide value if you want to set to NULL
z DataType (Optional): Data type of the argument; this is set to string if not
provided. Valid values for this attribute are the datatypes supported by ABPP X-
Documents (refer to the X-Document chapter). Example: string, boolean, int,
long, float, double, date, datetime, timestamp etc.
Example 1
In the following example, a procedure 'FIND_CALENDAR_WO_ENTRY' is
executed and the output value is used to raise an event:
<EXEC_PROC Name="FIND_CALENDAR_WO_ENTRY"
AssignToVar="response">
<STATUS Type="OUT" DataType="string"/>
</EXEC_PROC>
<RAISE_EVENT Name="CalendarValidationFinished">
<STATUS Value="{$response/STATUS/@Value}"/>
</RAISE_EVENT>
PROCESS_EXECUTE_SQL_QUERY
Description:
The PROCESS_EXECUTE_SQL_QUERY operation retrieves result of a SQL
statement in batches and then conditionally executes a set of actions on each batch of
records retrieved.
This operation is useful for:
a. Processing high-volume data without running into memory issues.
b. Conditional processing of a batch of records.
Syntax
<PROCESS_EXECUTE_SQL_QUERY BatchSize="noOfRows">
<EXECUTE_SQL_QUERY_BODY Mode="Write[Optional=true]">

<PARAM Value="{$paramVal}"
Type="paramType[Optional=true, default=string]"
Repeatable="true"/>
</EXECUTE_SQL_QUERY_BODY>
<ON_EACH_BATCH List="ListVariable"
ContinueExpr="expr[Optional=true]">

</ON_EACH_BATCH>
</PROCESS_EXECUTE_SQL_QUERY>
Attributes
z BatchSize (Required): The batch size is indicated here.
z Mode (Optional): By default PROCESS_EXECUTE_SQL_QUERY uses a read
only database connection for executing the sql. Setting Mode attribute to "Write"
will make it use a read-write connection. This is needed for "select for update"
kind of sql queries.
z Type (Optional): The Type attribute can be used to specify the datatype of the
column. If not specified the default type used is string. Valid values for this
attribute are the datatypes supported by ABPP X-Documents (refer to the X-
Document chapter). Example: string, boolean, int, long, float, double, date,
datetime, timestamp etc.
z Value: The value of the parameter.
z List (Required): Variable to which the retrieved batch of records are assigned
z ContinueExpr (Optional): X-Path expression. This expression should evaluate to
true for the actions within the ON_EACH_BATCH to be executed. The default
value is true. This is similar to the ContinueExpr attribute of
PROCESS_GET_DOCUMENT action component. Refer to Example 2 of
PROCESS_GET_DOCUMENT action component to see a usecase where this
attribute is useful.
Example 1
The following updates the price incrementally for each batch on the LINEITEM table
rows.
<PROCESS_EXECUTE_SQL_QUERY BatchSize="2">
<EXECUTE_SQL_QUERY_BODY>
<SQL>Select * from LINE_ITEM Where Price > 8</SQL>
</EXECUTE_SQL_QUERY_BODY>
<ON_EACH_BATCH List="lines">
<SET Var="newPrice" FromValue="{$newPrice + 1}"/>
<FOR_EACH SelectList="$lines" CurrentElement="item">
<EXEC_SQL_QUERY>
<SQL>UPDATE LINEITEM SET PRICE = {$newPrice}
WHERE ID = ?</SQL>
<PARAM Value="{$item/ID/@Value}"/>
</EXEC_SQL_QUERY>
</FOR_EACH>
</ON_EACH_BATCH>
</PROCESS_EXECUTE_SQL_QUERY>

Chapter 5 X-Rules
On successful execution of the component:

The price on the first 2 records is set to 9. The price on the next 2 records will be set to
10 and so-on.
XML-Manipulation Components
SET_PROPS
Description:
SET_PROPS sets the child XML elements on a DocVar object or on each DocVar
object present in a list. This is functionally same as SET component with DocVar and
Property attributes.
SET PROPS should be used when more than one property needs to be set on the same
parent element. Also, while setting each property, the optional attribute Òverwrite'
can be used to specify whether that property should be overwritten or not (by default,
it is true).
Syntax:
<SET_PROPS Select="$myVar">
<Property1 Value="value"
Overwrite="true|false[Optional=true, default=true]"/>
<Property2 Value="value"
...............
<Propertyn Value="value"
</SET_PROPS>
Attributes:
z Select: Variable on which action is performed.
z SelectList: List of XML form objects on which the action is performed.
Example 1:
The following component will update only the PRICE and LAST_UPDATED
properties of a BOOK document (represented by the variable myBook).
<SET_PROPS Select="$myBook">
<AUTHOR Value="John Doe" Overwrite="false"/>
<PRICE Value="15.00"/>
<LAST_UPDATED Value="{date()}" Overwrite="yes"/>
</SET_PROPS>
REMOVE_ATTRIBUTE
Description:
This component is used to remove attributes from XML elements, which may be set
by the SET action component.
Syntax:
<REMOVE_ATTRIBUTE Name="attribName" DocVar="docVariable"/>
Attributes:

z DocVar (Required): Document variable on which action is performed.

z Name (Required): Name of the attribute that should be removed from DocVar.
Example 1:
The following component will remove the Comment attribute on the document
instance represented by myDoc :
<REMOVE_ATTRIBUTE DocVar="myDoc" Name="Comment"/>
TO_DOCVAR
Description:
TO_DOCVAR component is used to build an XML document in memory.
TO_DOCVAR tags can embed other action components while forming XML to build
complex XMLs in memory; the action components will be executed while building
the XML DocVar .
Syntax
<TO_DOCVAR AssignToVar="varName"
IsLiteral="true|false[Optional=true, default=false]">
<XML Document>
</TO_DOCVAR>
Attributes
z AssignToVar : Variable that will store the XML built by the component.
z IsLiteral: Specifying IsLiteral as true will suppress execution of action
components inside TO_DOCVAR. The dynamic values in attributes and text will
still be converted to their runtime values.
Example 1:
This example shows how to build a simple XML document (bookDoc) and print it on
the console.
Input:
<TO_DOCVAR AssignToVar="bookDoc">
<BOOK>
<ID Value="BK-01"/>
<AUTHOR Value="J R R Tolkein"/>
<TITLE Value="Fellowship of the Ring"/>
</BOOK>
</TO_DOCVAR>
<PRINTLN Value="Printing bookDoc:"/>
<PRINTLN Value="{$bookDoc}"/>
Output:
Printing bookDoc:
<BOOK>
<ID Value="BK-01"/>
<AUTHOR Value="J R R Tolkein"/>
<TITLE Value="Fellowship of the Ring"/>
</BOOK>
Example 2

Chapter 5 X-Rules
This example shows how TO_XML action component (See the next section for details
on TO_XML ) is used within TO_DOCVAR to build a complex XML - DocVar
messageDoc :
Input:
<TO_DOCVAR AssignToVar="messageDoc">
<MESSAGE_DATA>
<CO_ID Value="{$reqDoc/CUSTOMER_ORDER/ID/@Value}"/>
<HEADER>
<FROM Value="abc"/>
<TO Value="xyz"/>
</HEADER>
<BODY>
<TO_XML SelectList="$reqDoc/CUSTOMER_ORDER/
ORDER_LINE_ITEMS/ORDER_LINE_ITEM"/>
</BODY>
</MESSAGE_DATA>
</TO_DOCVAR>
<PRINTLN Value="Printing messageDoc document:"/>
<PRINTLN Value="{$messageDoc}"/>
Output:
Printing messageDoc document:
<MESSAGE_DATA>
<CO_ID Value="CO-01"/>
<HEADER>
<FROM Value="abc"/>
<TO Value="xyz"/>
</HEADER>
<BODY>
<ORDER_LINE_ITEM>
<ID Value="LI-01"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-02"/>
</ORDER_LINE_ITEM>
</BODY>
</MESSAGE_DATA>
Example 3
This example shows an X-Rule that creates a complex XML using TO_DOCVAR tags
with multiple action components embedded inside.
<DEFINE_METHOD Name="createOrderXml">
<RULE>
<ACTION>
<RESPONSE>
<CUSTOMER_ORDER>
<ID Value="2"/>

<REPEAT Count="int($thisParam/
NUM_LINES/@Value)" IndexVar="currIndex">
<SET Var="liId"
FromValue="{concat(`LI_',string(currIndex))}"/>
<ORDER_LINE_ITEM>
<ID Value="{$liId}"/>
</ORDER_LINE_ITEM>
</TO_DOCVAR>
</REPEAT>
</CUSTOMER_ORDER>
</RESPONSE>
</TO_DOCVAR>
</ACTION>
</RULE>
</DEFINE_METHOD>
Output:
<RESPONSE>
<CUSTOMER_ORDER>
<ID Value="2"/>
<ORDER_LINE_ITEM>
<ID Value="LI_0"/>
</ORDER_LINE_ITEM>
........
<ORDER_LINE_ITEM>
<ID Value="LI_4"/>
</ORDER_LINE_ITEM>
</CUSTOMER_ORDER>
</RESPONSE>
Example 4
By default all action component inside TO_DOCVAR are executed e.g. REPEAT
action in above example. To prevent the action component(s) from executing inside
TO_DOCVAR, the optional attribute 'IsLiteral' should be set to 'true' (default is false).
Even if IsLiteral is set to true the attributes that are part of LhsExpression or those that
use {} to indicate dynamic values will be evaluated.
Input:
<SET Var="max" FromValue="1000" />
<TO_DOCVAR AssignToVar="req" IsLiteral="true">
<REQUEST Name="test" MaxRows="{$max}">
<FOR_EACH SelectList="$thisParam/LINE"
CurrentElement="line">
<PRINTLN Value="{$line}"/>
</FOR_EACH>
</REQUEST>
</TO_DOCVAR>
Output:
The variable 'req' will be:
<REQUEST Name="test" MaxRows="1000">
<FOR_EACH CurrentElement="line">

Chapter 5 X-Rules
<PRINTLN/>
</FOR_EACH>
</REQUEST>
TO_XML
Description:
TO_XML is an action component that can be used either by the TO_DOCVAR tag or
independently to create the dynamic content for a command (REQUEST,
ADD_DOCUMENT etc). TO_XML only operates on existing document variables or
lists, and its output is always added as a child to the enclosing tag.
Syntax
<TO_XML DocVar="docvarName"/>
OR
<TO_XML SelectList="X-Path expression"/>
OR
<TO_XML Select="X-Path expression"/>
Attributes
z DocVar: The document variable used to build the dynamic content
z SelectList: The document list used to build the dynamic content
z Select: The document used to build the dynamic content
Example 1
Assume that the DocVar `reqDoc' points to the document instance:
<CUSTOMER_ORDER>
<ID Value="CO-01"/>
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ID Value="LI-01"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-02"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
The following components show how to use TO_XML to pass the reqDoc variable to
the processCustomerOrder command:
<REQUEST Name="processCustomerOrder">
<TO_XML DocVar="reqDoc"/>
</REQUEST>
This is equivalent to:
<REQUEST Name="processCustomerOrder">
<CUSTOMER_ORDER>
<ID Value="CO-01"/>
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>

<ID Value="LI-01"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-02"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
</REQUEST>
Example 2
The following components demonstrate the use TO_XML with SelectList attribute
(the variable reqDoc is the same as for Example 1).
<REQUEST Name="processLineItems">
<TO_XML SelectList="$reqDoc/CUSTOMER_ORDER/
ORDER_LINE_ITEMS/ORDER_LINE_ITEM"/>
</REQUEST>
This is equivalent to:
<REQUEST Name="processLineItems">
<ORDER_LINE_ITEM>
<ID Value="LI-01"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-02"/>
</ORDER_LINE_ITEM>
</REQUEST>
APPEND_TO_XML
Description:
This action will append new XML elements to a parent element. The parent element
can be specified by using LhsExpression attributes or by including
APPEND_TO_XML inside another xml building component like TO_DOCVAR or
another APPEND_TO_XML.
Syntax
<APPEND_TO_XML LhsExpression/>
<CHILD_A/>
<CHILD_B/>
........
</APPEND_TO_XML>
Attributes
z LhsExpression (Optional): The document variable to append child XML elements
to. This attribute is not needed when this action component is included within
another xml building component like TO_DOCVAR or APPEND_TO_XML
Example 1
Input:

Chapter 5 X-Rules
$thisReturn initially refers to:

<RESPONSE/>
$otherTags referred to:
<OTHER_TAGS/>
<CHILD_A/>
<CHILD_B/>
<TO_XML Select="$OtherTags"/>
</APPEND_TO_XML>
Output:
After the APPEND_TO_XML operation, thisReturn would be:
<RESPONSE>
<CHILD_A/>
<CHILD_B/>
<OTHER_TAGS/>
</RESPONSE>
Example 2
<DEFINE_METHOD Name="testXRule">
<RULE>
<ACTION>

<TO_DOCVAR AssignToVar="order">
<PURCHASE_ORDER/>
</TO_DOCVAR>
<TO_DOCVAR AssignToVar="lines">
<LINES>
<LINE>
<ID Value="1"/>
<ITEM_ID Value="I1"/>
</LINE>
<LINE>
<ID Value="2"/>
<ITEM_ID Value="I2"/>
</LINE>
</LINES>
</TO_DOCVAR>

<APPEND_TO_XML Select="$order">
<ORDER_LINES>
<FOR_EACH SelectList="$lines/LINE"
CurrentElement="line">


<APPEND_TO_XML>
<ORDER_LINE Item="{$line/ITEM_ID/
@Value}" Price="{$line/PRICE/@Value}"/>
</APPEND_TO_XML>
</FOR_EACH>
</ORDER_LINES>
</APPEND_TO_XML>
<PRINTLN Value="order"/>
</ACTION>
</RULE>
</DEFINE_METHOD>
Output:
Structure of $order at the end will be:
<PURCHASE_ORDER>
<ORDER_LINES>
<ORDER_LINE Item="I1" Price="100"/>
<ORDER_LINE Item="I2" Price="200"/>
</ORDER_LINES>
</PURCHASE_ORDER>
MAKE_INSTANCE_DOCUMENT
Description
MAKE_INSTANCE_DOCUMENT component is used for creating an xml tag on the
fly with name provided from a variable. This component is primarily used when we
need to create an xml tag whose name is dynamic.
Syntax
<MAKE_INSTANCE_DOCUMENT Name="{$sortBy}"
AssignToVar="sortByTag" />
Attributes
z Name : Variable that provides the name for the xml tag to be created
z AssignToVar : Variable that will store the XML built by the component.
Example 1
This example shows how to create an xml tag dynamically using
MAKE_INSTANCE_DOCUMENT component.
Input:
<SET Var="sortBy" FromValue="'BookName'" />

<SET Var="sortOrder" FromValue="'Ascending'" />
<MAKE_INSTANCE_DOCUMENT Name="{$sortBy}"
AssignToVar="sortByTag" />

Chapter 5 X-Rules
<SET DocVar="sortByTag" Attribute="Sort"

FromValue="{$sortOrder}" />
<PRINTLN Value="{$sortByTag}"/>
Output:
Printing $sortByTag:
<BookName Sort=”Ascending”/>
SET_NAME
Description:
The SET_NAME action tag changes the name of the root xml tag referred to by a
given variable to a different name.
Syntax
<SET_NAME LhsExpression RhsExpression/>
Attributes
z LhsExpression (Required): LhsExpression that evaluates to an xml tag or a list of
xml tags (using SelectList). The name of these xml tag(s) will be changed.
z RhsExpression (Required): RhsExpression that evaluates to a string value. This is
the name that the root xml tag(s) should be changed to.
Example 1
Input:
<TO_DOCVAR AssignToVar="myDoc">
<OLD_NAME>
<CHILDREN/>
</OLD_NAME>
</TO_DOCVAR>
<SET_NAME Value="{$myDoc}" FromValue="NEW_NAME"/>
<PRINTLN Value="{$myDoc}"/>
Output:
<NEW_NAME>
<CHILDREN/>
</NEW_NAME>
SET_TEXT
Description:
The SET_TEXT action sets the text content for a given xml tag.
Syntax
<SET_TEXT LhsExpression RhsExpression/>
Attributes
z LhsExpression (Required): LhsExpression that evaluates to an xml tag or a list of
xml tag(s) (using SelectList). The text content of these xml tag(s) will be changed.

z RhsExpression (Required): RhsExpression that evaluates to a string value. This is

the new text content.
Example 1
Input:
<DOC_ROOT/>
</TO_DOCVAR>
<SET_TEXT Value="{$myDoc}" FromValue="This is the text
content."/>
Output:
<DOC_ROOT>This is the text content.</DOC_ROOT>
GET_TEXT
Description:
The GET_TEXT action retrieves the text content for a given tag.
Syntax
<GET_TEXT FromValue="{value}" AssignToVar="var"/>
Attributes
z FromValue: Document variable for which the text content is retrieved.
z AssignToVar: Variable to which the text content is assigned.
Example 1
Input:
<DOC_ROOT>This is the text content.</DOC_ROOT>
</TO_DOCVAR>
<GET_TEXT FromValue="{$myDoc}" AssignToVar="myVar"/>
<PRINTLN Value="{$myVar}"/>
Output:
This is the text content.
SET_CHILD
Description:
The SET_CHILD action removes existing children of the same name and adds the
new child.
Syntax
<SET_CHILD Value="{$docVar}" FromValue="{$childVar}"/>
Attributes
z Value: Document variable on which action is performed.
z FromValue: Variable that references the child document.
Example 1

Chapter 5 X-Rules
Input:
$doc refers to:
<DOC_ROOT>
<A_CHILD/>
<B_CHILD>
<EXISTING_B_CHILD1/>
</B_CHILD>
<B_CHILD>
<EXISTING_B_CHILD2/>
</B_CHILD>
</DOC_ROOT>
$child refers to:
<B_CHILD>
<NEW_B_CHILD/>
</B_CHILD>
<SET_CHILD Value="{$doc}" FromValue="{$child}"/>

Output:
$doc referes to:
<DOC_ROOT>
<A_CHILD/>
<B_CHILD>
<NEW_B_CHILD/>
</B_CHILD>
</DOC_ROOT>
ADD_CHILDREN
Description :
The ADD_CHILDREN component is used to add one or more documents specified
by the RhsExpression, to the document Variable `parentDoc'. The child documents are
added by reference.
Syntax
<ADD_CHILDREN DocVar="parentDoc" RhsExpression
Position="0[Optional=true]"
AfterChildDocVar="childDoc1[Optional=true]"
BeforeChildDocVar="childDoc2[Optional=true]"/>
Attributes
z DocVar (Required): Variable name referring to the parent document.
z RhsExpression (Required): RhsExpression that evaluates to an xml document or a
list of xml documents (using SelectList). These document(s) are added as children
of the parent document.
z Position (Optional): Number literal or X-Path expression that evaluates to an
integer value. This identifies the position at which the new children should be
inserted under the parent document. The position values start from 0.

z AfterChildDocVar (Optional): Variable name referring to a child of the parent

document after which the new children should be inserted under the parent
document.
z BeforeChildDocVar (Optional): Variable name referring to a child of the parent
document before which the new children should be inserted under the parent
document.
Example 1
Assuming that the document variable `myDoc' points to the following document
instance:
<MY_DOCUMENT Comment="Printing my document">
<MY_CHILD1 Name="First Child" Value="1"/>
<MY_CHILD2 Name="Second Child" Value="2">
<MY_CHILD21 Name="Second-one Child" Value="2-1"/>
</MY_CHILD2>
<MY_CHILD3 Name="Third Child1" Value="30"/>
</MY_DOCUMENT>
The following component will add the first child of `myDoc' with the name
`MY_CHILD2' to the DocVar `thisReturn'.
<ADD_CHILDREN DocVar="thisReturn" FromValue="{$myDoc/
MY_CHILD2}"/>
The DocVar can be printed to the log to check whether the operation was successful:
Input:
<PRINTLN Value="{$thisReturn}" />
Output:
<RESPONSE>
</MY_CHILD2>
</RESPONSE>
Example 2
This is a variation of Example 1. The following component will add all children of
`myDoc' with the name MY_CHILD3 to the variable `thisReturn'.
<ADD_CHILDREN DocVar="thisReturn" FromSelectList="$myDoc/
MY_CHILD3"/>
The DocVar can be printed to the log to check whether the operation was successful:
Input:
<PRINTLN Value="{$thisReturn}"/>
Output:
<RESPONSE>
</RESPONSE>
Example 3
Input:

Chapter 5 X-Rules
<TO_DOCVAR AssignToVar="parentDoc">
<DOC_ROOT>
<A_CHILD/>
<B_CHILD>
<EXISTING_B_CHILD/>
</B_CHILD>
</DOC_ROOT>
</TO_DOCVAR>
<TO_DOCVAR AssignToVar="childDoc">
<B_CHILD>
<NEW_B1_CHILD/>
<NEW_B2_CHILD/>
</B_CHILD>
</TO_DOCVAR>
<ADD_CHILDREN DocVar="parentDoc" FromDocVar="childDoc"/>

<PRINTLN Value="{$parentDoc}"/>
Output:
<DOC_ROOT>
<A_CHILD/>
<B_CHILD>
<EXISTING_B_CHILD/>
</B_CHILD>
<B_CHILD>
<NEW_B1_CHILD/>
<NEW_B2_CHILD/>
</B_CHILD>
</DOC_ROOT>
Example 4
Input:
<DOC_ROOT>
<A_CHILD/>
<D_CHILD/>
</DOC_ROOT>
</TO_DOCVAR>
<TO_DOCVAR AssignToVar="childDocs">
<CHILDREN>
<B_CHILD/>
<C_CHILD/>
</CHILDREN>
</TO_DOCVAR>
<ADD_CHILDREN DocVar="parentDoc" FromSelectList="$childDocs/*"

Position="1"/>
Output:
<DOC_ROOT>
<A_CHILD/>

<B_CHILD/>
<C_CHILD/>
<D_CHILD/>
</DOC_ROOT>
Example 5
This is a variant of example 4. This example inserts new children after the child
A_CHILD.
Input:
Assume parentDoc and childDocs as same as those defined in example 4.
<SET Var="afterChild" FromValue="{$parentDoc/A_CHILD}"/>
<ADD_CHILDREN DocVar="parentDoc" FromSelectList="$childDocs/*"
AfterChildDocVar="afterChild"/>
Output:
Same as example 4.
APPEND_CHILDREN
Description :
The APPEND_CHILDREN component is used to add one or more child documents of
the document specified by the document variable 'childDoc', to the document Variable
'parentDoc', It differs from the ADD_CHILDREN action in the fact that only the child
tags from the document 'childDoc' are added, without the enclosing parent tags.
Syntax
<APPEND_CHILDREN DocVar="parentDoc" FromDocVar ="childDoc"/>
Attributes
z DocVar (Required): Parent document name.
z FromDocVar (Required): Child document name.
Example 1
Input:
<DOC_ROOT>
<A_CHILD/>
<B_CHILD>
<EXISTING_B_CHILD/>
</B_CHILD>
</DOC_ROOT>
</TO_DOCVAR>
<TO_DOCVAR AssignToVar="childDoc">
<B_CHILD>
<NEW_B1_CHILD/>
<NEW_B2_CHILD/>
</B_CHILD>
</TO_DOCVAR>

Chapter 5 X-Rules
<APPEND_CHILDREN DocVar="parentDoc" FromDocVar="childDoc"/>

Output:
<DOC_ROOT>
<A_CHILD/>
<B_CHILD>
<EXISTING_B_CHILD/>
</B_CHILD>
<NEW_B1_CHILD/>
<NEW_B2_CHILD/>
</DOC_ROOT>
REMOVE_CHILDREN
Description:
The REMOVE_CHILDREN component is used to remove either all or a specific
immediate child element from the parent document, represented by `parentDoc'
variable. Either all immediate child element or immediate child elements of one name
can be removed at a time. If the AssignToVar attribute is specified, then the list of the
removed child elements is assigned to the mentioned variable.
Syntax
<REMOVE_CHILDREN LhsExpression
ChildName="ChildName[Optional=true]"
AssignToVar="varName[Optional=true]"/>
Attributes
z LhsExpression (Required): LhsExpression that evaluates to an xml document or a
list of xml documents. This is the parent xml document(s) whose children will be
removed.
z ChildName (Optional): If specified, only the child elements with this name will be
removed. If not specified, all children of the parent document will be removed.
z AssignToVar (Optional): The list of removed child elements is assigned to this
variable. If no children are removed then this will be an empty list.
Example 1
Assuming the DocVar `myDoc' points to the following document instance:
<MY_DOCUMENT Comment="This is my document">
</MY_CHILD2 >
</MY_DOCUMENT>
The following component will remove all the children of myDoc:
<REMOVE_CHILDREN DocVar="myDoc"/>
To verify, print the variable:

Input:
Output:
<MY_DOCUMENT Comment="This is my document">
Example 2
For the same document instance `myDoc' from Example 1, the following component
will remove all children with the name `MY_CHILD3':
<REMOVE_CHILDREN DocVar="myDoc" ChildName ="MY_CHILD3"/>
Input:
<PRINTLN Value="{$myDoc}" />
Output:
Printing my document:
</MY_CHILD2>
</MY_DOCUMENT>
REMOVE_NODES
Description:
The REMOVE_NODES component is used to remove specified immediate child
element(s) from the parent document. The child element(s) to remove are specified as
XMLform objects and not as child element name as was the case for
REMOVE_CHILDREN above.
Syntax
<REMOVE_NODES FromSelect="X-Path expression for Parent"
LhsExpression AssignToVar="varName[Optional=true]"/>
Attributes
z FromSelect (Required): X-Path expression that evaluates to the parent document
whose immediate children specified by LhsExpression need to removed.
z LhsExpression (Required): LhsExpression that evaluates to an child element or a
list of child elements that need to be removed from the parent document.
z AssignToVar (Optional): The list of removed child elements is assigned to this
variable. If no children are removed then this will be an empty list.
Example 1
Assuming the DocVar 'myDoc' points to the following document:
<PARENT>
<CHILD1 Value="1"/>
<CHILD1 Value="2"/>
<CHILD1 Value="2"/>
<CHILD1 Value="3"/>

Chapter 5 X-Rules
<CHILD2 Value="100"/>
</PARENT>
The following component will remove those children of myDoc whose name is
'CHILD1' and whose Value attribute has value '2':
<REMOVE_NODES FromSelect="$myDoc" SelectList="$myDoc/

CHILD1[@Value='2']"/>
Output:
The content of 'myDoc' after executing the component will be:
<PARENT>
<CHILD1 Value="1"/>
<CHILD1 Value="3"/>
</PARENT>
DELETE_ALL_CHILDREN
Description:
This component will recursively remove all child elements with specified names from
the parent xml document. If the AssignToVar variable is specified, all the removed
children are returned in a List structure.
Syntax
<DELETE_ALL_CHILDREN LhsExpression
AssignToVar="delNodes[Optional=true]">
<ChildToRemove1/>
<ChildToRemove2/>
...
<ChildToRemoveN/>
</DELETE_ALL_CHILDREN>
Attributes
z LhsExpression (Required): LhsExpression that evaluates to an xml document or a
list of xml documents. This is the parent xml document(s) whose children will be
removed.
z AssignToVar (Optional): Variable which gets assigned all the removed child
elements.
Example 1
If you give the following input:
<TO_DOCVAR AssignToVar="myXML">
<COUNTRY Value="India">
<STATE Value="Maharashtra">
<CAPITAL Value="Bombay"/>
</STATE>
<STATE Value="Karnataka">
<CAPITAL Value="Bangalore"/>
</STATE>
<POPULATION Value="80C"/>

</COUNTRY>
</TO_DOCVAR>
<DELETE_ALL_CHILDREN Select="$myXML">
<CAPITAL/>
<POPULATION/>
</DELETE_ALL_CHILDREN>
<PRINTLN Value="{$myXML}"/>
The output would be:
<STATE Value="Maharashtra"/>
<STATE Value="Karnataka"/>
</COUNTRY>
COLLATE_XML
Description :
This component collates the input XML according to the collate list specified by the
COLLATE_LIST tags in the input XML.
Syntax
<COLLATE_XML LhsExpression AssignToVar="res"/>
Syntax of Input XML:
<MY_DOCUMENT Comment="...[Optional=true]">
<INPUT>
<TAG_A Value="A1"/>
<TAG_A Value="A2"/>
......................
<TAG_A Value="An"/>
<TAG_B Value="B1"/>
<TAG_B Value="B2"/>
......................
<TAG_B Value="Bn"/>
.....................
.....................
<TAG_X Value="X1"/>
<TAG_X Value="X2"/>
......................
<TAG_X Value="Xn"/>
</INPUT>
<COLLATE_LIST Value="OUTPUT">
<TAG_A/>
<TAG_B/>
............
<TAG_X/>
</COLLATE_LIST>
</MY_DOCUMENT>
Syntax of Output XML:
<OUTPUT_LISTS>
<OUTPUT>
<TAG_A Value="A1"/>

Chapter 5 X-Rules
<TAG_B Value="B1"/>
............
<TAG_X Value="X1"/>
</OUTPUT>
<OUTPUT>
<TAG_A Value="A2"/>
<TAG_B Value="B2"/>
............
<TAG_X Value="X2"/>
</OUTPUT>
........
<OUTPUT>
<TAG_A Value="An"/>
<TAG_B Value="Bn"/>
............
<TAG_X Value="Xn"/>
</OUTPUT>
</OUTPUT_LISTS>
Attributes
z LhsExpression (Required): LhsExpression that evaluates to an xml element that
will be collated.
z AssignToVar: Document variable that contains the output of the collation.
Example 1
Assuming that myDoc points to the following document instance:
<INPUT>
<AO_ID Value="PO-128"/>
<ITEM_ID Value="136D8710G01-B"/>
<ID Value="SCH-128"/>
</INPUT>
<COLLATE_LIST Value="LI_DETAILS">
<ID/>
<AO_ID/>
<ITEM_ID/>
</COLLATE_LIST>
</MY_DOCUMENT>
The following components will execute the collate component print the results:
<COLLATE_XML Var="myDoc" AssignToVar="collateDoc"/>
<PRINTLN Value="{$collateDoc }" />
Output on the console:
<LI_DETAILS_LIST>

<LI_DETAILS>
</LI_DETAILS>
<LI_DETAILS>
</LI_DETAILS>
<LI_DETAILS>
</LI_DETAILS>
<LI_DETAILS>
</LI_DETAILS>
</LI_DETAILS_LIST>
MAP_CREATE
Description:
This action component is used to create a Map. Map is a special construct that can be
used to group xml data elements based on their properties that form the key of the
element. Map is a also useful for quick look up of the xml data elements based on their
key. Each key entry can refer to a list of xml data elements.
Syntax:
<MAP_CREATE AssignToVar="mapVariable"/>
or
<MAP_CREATE LhsExpression CurrentElement="varName" Key="key
based on current element" AssignToVar="mapVariable"/>
Attributes:
z AssignToVar (Required): Variable that will refer to the map after it has been
created.
z LhsExpression (Required): LhsExpression that evaluates to one or more xml data
elements that need to be added to the map.
z CurrentElement (Required): The CurrentElement and Key attribute together are
used to specify the logic needed to calculate the key of the data elements that are
being added to the map. CurrentElement is used to specify the variable name that
will refer to each data element as it is added to the map.
z Key (Required): The Key attribute specifies the X-Path expression used to
calculate the key of the data elements being added to the map. It uses the key X-
Path function to calculate the key. For each element specified by LhsExpression
the Key attribute is evaluated to calculate the key and then the data element is
added to the map under its key. The Key expression can access the data element
being added by using the variable name specified by CurrentElement attribute.

Chapter 5 X-Rules
Example 1:
Create an empty map and assign it to variable "myMap":
<MAP_CREATE AssignToVar="myMap"/>
Example 2:
Assume that $data refers to:
<DATA>
<CARS>
<CAR>
<VIN Value="1"/>
<MAKE Value="Toyota"/>
<YEAR Value="2006"/>
<COLOR Value="RED"/>
</CAR>
<CAR>
<VIN Value="2"/>
<COLOR Value="BLACK"/>
</CAR>
<CAR>
<VIN Value="3"/>
<MAKE Value="Lexus"/>
<COLOR Value="BLUE"/>
</CAR>
</CARS>
</DATA>
The MAP_CREATE component can be used to create a map of CAR elements based
on combination of MAKE and YEAR properties as follows:
<MAP_CREATE SelectList="$data/CARS/CAR" CurrentElement="e"

Key="key($e/MAKE/@Value, $e/YEAR/@Value)" AssignToVar="carMap"/
>
Example 3
Once the map has been created it can be queried upon by using X-Path functions
mapGet and mapContainsKey. It is also possible to loop over all the keys and
elements of the map as shown below:
<FOR_EACH SelectList="$carMap/KEY" CurrentElement="currentKey">

<PRINTLN Var="currentKey"/>


<PRINTLN Value="Key Value = {$currentKey/@Value}"/>


<PRINTLN Value="First part of the key = {$currentKey/
PART[1]/@Value}"/>
<PRINTLN Value="Second part of the key = {$currentKey/
PART[2]/@Value}"/>

<FOR_EACH SelectList="$keyDataElements/CAR"
CurrentElement="dataElement">
<PRINTLN Var="dataElement"/>
</FOR_EACH>
</FOR_EACH>
MAP_PUT_ALL
Description:
This action component can be used to add one or more xml data elements to an
existing map that was created by using MAP_CREATE action component.
Syntax:
<MAP_PUT_ALL Map="X-Path expression referring to existing map"
LhsExpression CurrentElement="varName" Key="key based on
current element"/>
Attributes:
z Map (Required): X-Path expression that identifies the map to add to.
z LhsExpression (Required): LhsExpression that evaluates to one or more xml data
element that need to be added to the map.
z CurrentElement (Required): The CurrentElement and Key attribute together are
used to specify the logic needed to calculate the key of the data elements that are
being added to the map. CurrentElement is used to specify the variable name that
will refer to each data element as it is added to the map.
z Key (Required): The Key attribute specifies the X-Path expression used to
calculate the key of the data elements being added to the map. It uses the key X-
Path function to calculate the key. For each element specified by LhsExpression
the Key attribute is evaluated to calculate the key and then the data element is

Chapter 5 X-Rules
added to the map under its key. The Key expression can access the data element
being added by using the variable name specified by CurrentElement attribute.
Example:
Assume that $car refers to:
<CAR>
<VIN Value="4"/>
<MAKE Value="Honda"/>
<COLOR Value="WHITE"/>
</CAR>
Also assume that there is a variable "carMap" that refers to a map that was already
created. To add more elements to this map the MAP_PUT_ALL action component can
be used as:
<MAP_PUT_ALL Map="$carMap" Select="$car" CurrentElement="e"

Key="key($e/MAKE/@Value, $e/YEAR/@Value)"/>
MAP_REMOVE
Description:
This action component can be used to remove a key and its related xml data element
list from the map specified.
Syntax:
<MAP_REMOVE Map="X-Path expression referring to existing map" Key="Key to
remove from the map"/>
Attributes:
z Map (Required): X-Path expression that identifies the map to operate on.
z Key (Required): This defines the key that needs to be removed from the map. The
"key" X-Path function is used to specify the key.
Example
Assume that there is a map referred to be variable "carMap" and the data in it is as
shown in example 2 of MAP_CREATE. To remove the key: MAKE = "Toyota" and
YEAR = "2006" the call will be:
<MAP_REMOVE Map="$carMap" Key="key('Toyota','2006')"/>
This will remove the specified key and its two xml data elements identified by VIN
values of "1" and "2".
MAP_CLEAR
Description:
This action component will remove all entries of the specified map.

Syntax:
<MAP_CLEAR Map="X-Path expression referring to existing map"/>
Attributes:
z Map (Required): X-Path expression that identifies the map to operate on.
Example:
<MAP_CLEAR Map="$carMap"/>
GROUP_DOCS
Description:
This action will group a given list of document instances based on the specified
criteria. This action tag can be used wherever grouping is required.
If the list size is not too large, using this tag will give better performance over using
MAP action tags.
Syntax
<GROUP_DOCS SelectList="list" AssignToVar="myVar">
<PROPERTIES>
<Property1/>
<Property2/>
.........
</PROPERTIES>
<GROUP_NAME Value="groupName"/>
<DOCS_NAME Value="docName"/>
<ROOT_NAME Value="rootName"/>
</GROUP_DOCS>
Attributes
z SelectList (Required): List of XML documents for grouping
z AssignToVar (Required): Grouping result is assigned to this variable
Note: You can also provide "dynamic" properties for grouping criteria using
TO_XML component. Please see Example 2 for details.
Example 1:
<GROUP_DOCS SelectList="$thisParam/ORDER_SCHEDULE"
AssignToVar="thisReturn">
<PROPERTIES>
<SHIP_FROM_NAME/>
<SHIP_TO_NAME/>
</PROPERTIES>
<GROUP_NAME Value="SHIPMENT"/>
<DOCS_NAME Value="ORDER_SCHEDULES"/>
<ROOT_NAME Value="RESPONSE"/>
</GROUP_DOCS>
If the request is like the following, after applying GROUP_DOCS, the response will
be as mentioned under the RESPONSE:

Chapter 5 X-Rules
<REQUEST Name="groupDocs">
<ORDER_SCHEDULE>
<ID Value="SCH-1"/>
<SHIP_TO_NAME Value="i2-Dallas"/>
<SHIP_FROM_NAME Value="i2-MtView"/>
</ORDER_SCHEDULE>
<ORDER_SCHEDULE>
<ID Value="SCH-2"/>
<SHIP_FROM_NAME Value="i2-Atl"/>
</ORDER_SCHEDULE>
<ORDER_SCHEDULE>
<ID Value="SCH-3"/>
</ORDER_SCHEDULE>
<ORDER_SCHEDULE>
<ID Value="SCH-4"/>
</ORDER_SCHEDULE>
</REQUEST>
Response after grouping:
<SHIPMENT>
<ORDER_SCHEDULES>
<ORDER_SCHEDULE>
<ID Value="SCH-2"/>
</ORDER_SCHEDULE>
</ORDER_SCHEDULES>
</SHIPMENT>
<SHIPMENT>
<ORDER_SCHEDULES>
<ORDER_SCHEDULE>
<ID Value="SCH-1"/>
</ORDER_SCHEDULE>
<ORDER_SCHEDULE>
<ID Value="SCH-3"/>
</ORDER_SCHEDULE>
<ORDER_SCHEDULE>
<ID Value="SCH-4"/>

</ORDER_SCHEDULE>
</ORDER_SCHEDULES>
</SHIPMENT>
</RESPONSE>
Example 2:
You can also provide the grouping criteria (properties) dynamically. The below code
snippet re-writes the GROUP_DOC in the previous example using dynamic
properties.
<TO_DOCVAR AssignToVar="dynProps">
<DYNAMIC_PROPS>
<SHIP_FROM_NAME />
<SHIP_TO_NAME />
</DYNAMIC_PROPS>
</TO_DOCVAR>
<PROPERTIES>
<TO_XML SelectList="$dynProps/*" />
</PROPERTIES>
<GROUP_NAME Value="SHIPMENT" />
<DOCS_NAME Value="ORDER_SCHEDULES" />
<ROOT_NAME Value="RESPONSE" />
</GROUP_DOCS>
You can provide static properties along with the dynamic properties for grouping
criteria. Here is a code snippet:
<PROPERTIES>
<TO_XML SelectList="$dynProps/*" />
<CUST_ORG_ID/>
</PROPERTIES>
<GROUP_NAME Value="SHIPMENT" />
<DOCS_NAME Value="ORDER_SCHEDULES" />
<ROOT_NAME Value="RESPONSE" />
</GROUP_DOCS>
MERGE_DOC
Description:
The MERGE_DOC operation compares two document instances (referred to as new
and old instances) and then changes the new document instance to indicate the
differences between the two.
The root tag names of the xml document specified for new and old document
instances needs to correspond to a Document defined in the service. If the root tag
name does not correspond to a Document, then a DocName attribute needs to be
specified to indicate what Document metadata to use. This action component takes
the datatypes of the document properties into consideration and recognizes that
Syntax

Chapter 5 X-Rules
<MERGE_DOC Value="newDoc" FromValue="oldDoc" DocName="X-Doc

name[Optional=true]"/>
Attributes
z Value (Required): New document
z FromValue (Required): Old document
z DocName (Optional): Used when root tag names are different than the X-
Document that they represent.
Example 1
Assume that ORDER_SCHEDULE is a valid X-Document and the variable "newSch"
refers to:
<ORDER_SCHEDULE>
<ID Value="SCHED-1"/>
<QTY Value="10"/>
<DAYS_LATE Value="10"/>
<DELIVERY_DATE Value="10/20/2005 00:10:20"/>
<REASON_CODE Value="NB"/>
<CITY_TAX/>
</ORDER_SCHEDULE>
and variable "oldSch" refers to:
<ORDER_SCHEDULE Value="2">
<CITY_TAX Value="92.4"/>
<REASON_CODE Value="NB"/>
<DAYS_EARLY Value="1"/>
<VERSION_NO Value="72"/>
</ORDER_SCHEDULE>
The MERGE_DOC action component can be used as:

<MERGE_DOC Value="{$newSch}" FromValue="{$oldSch}"/>
The "newSch" variable will get changed to:

<ORDER_SCHEDULE>
<ID Value="SCHED-1" ChangeType="Change" OldValue="SCH-101"/
>
<QTY Value="10" ChangeType="Change" OldValue="900.0"/>
<DAYS_LATE Value="10" ChangeType="New"/>
<DELIVERY_DATE Value="10/20/2005 00:10:20"
ChangeType="Change" OldValue="09/20/2001 00:10:20:000"/>
<REASON_CODE Value="NB" ChangeType="None" OldValue="NB"/>
<CITY_TAX ChangeType="Change" OldValue="92.4"/>
<DAYS_EARLY Value="1" ChangeType="None" OldValue="1"/>
<VERSION_NO Value="72" ChangeType="None" OldValue="72"/>
</ORDER_SCHEDULE>

MERGE_ERRORS_DOC
Description:
This action tag helps in merging error tags from one xml document to another xml
document. The error tags to be copied should follow the format used by validation
specification i.e.
<_ERRORS Value="ERROR|SEVERE_ERROR">
...
</_ERRORS>
Syntax:
<MERGE_ERRORS_DOC FromValue="{$source}" Value="{$target}"
RootTagName="Root tag name[Optional=true]" Key="Comma separated
list of key tag names[Optional=true, default=ID]"/>
Attributes:
z FromValue (Required): Source xml document
z Value (Required): Target xml document
z RootTagName (Optional): root tag name in the target xml form from where the
merging operation has to start
z Key (Optional): Comma separated string containing the keys. This is used for
matching the children in target and source forms. Default value is ID
Example:
Assume variable "source" refers to:
<PURCHASE_ORDER>
<ID Value="10"/>
<SUPPLIER_ID Value="Sup1">
<_ERRORS Value="ERROR">
<_ERROR Value="INVALID_SUPPLIER" Severity="ERROR"/>
</_ERRORS>
</SUPPLIER_ID>
<CREATED_BY Value="user1"/>
<LINES>
<LINE>
<ID Value="1"/>
<ITEM_ID Value="Item1"/>
<QTY Value="10">
<_ERROR Value="MIN_QUANITY_VIOLATION"
Severity="ERROR"/>
<_ERROR Value="QUANTITY_MULTIPLE_VIOLATION"
Severity="ERROR"/>
</_ERRORS>
</QTY>
</LINE>
<LINE>
<ID Value="2"/>

Chapter 5 X-Rules
<QTY Value="40"/>
<PRICE Value="15.34">
<_ERROR Value="INVALID_PRICE"
Severity="ERROR"/>
</_ERRORS>
</PRICE>
</LINE>
</LINES>
</PURCHASE_ORDER>
and variable "target" refers to:

<PURCHASE_ORDER>
<ID Value="10"/>
<SUPPLIER_ID Value="Sup1"/>
<LINES>
<LINE>
<ID Value="2"/>
<QTY Value="40"/>
</LINE>
<LINE>
<ID Value="1"/>
<QTY Value="10"/>
</LINE>
</LINES>
</PURCHASE_ORDER>
As shown above the source xml has the errors marked by using _ERRORS tag at
appropriate places (generally by a call to validation framework). The target document
as shown should be similar in structure to the source document. The
MERGE_ERROR_DOC action component can be used to copy all errors from the
source xml to the target xml as shown below:
<MERGE_ERRORS_DOC FromValue="{$source}" Value="{$target}"/>
The "target" variable after the merge will look like:
<PURCHASE_ORDER>
<ID Value="10"/>
<SUPPLIER_ID Value="Sup1">
<_ERROR Value="INVALID_SUPPLIER" Severity="ERROR"/>
</_ERRORS>

</SUPPLIER_ID>
<LINES>
<LINE>
<ID Value="2"/>
<QTY Value="40"/>
<_ERROR Value="INVALID_PRICE"
Severity="ERROR"/>
</_ERRORS>
</PRICE>
</LINE>
<LINE>
<ID Value="1"/>
<QTY Value="10">
<_ERROR Value="MIN_QUANITY_VIOLATION"
Severity="ERROR"/>
<_ERROR Value="QUANTITY_MULTIPLE_VIOLATION"
Severity="ERROR"/>
</_ERRORS>
</QTY>
</LINE>
</LINES>
</PURCHASE_ORDER>
STRING_TO_XML
Description:
This action tag will convert a string representing XML into an XML form instance.
Syntax
<STRING_TO_XML RhsExpression DocVar="xmlFormInstance"/>
Attributes
z DocVar (Required): Variable to assign the XML form object to
z RhsExpression (Required): RhsExpression that evaluates to a string object that
needs to be converted into an XML form instance.
Example 1
<STRING_TO_XML FromSelect="$xmlString" DocVar="data"/>
XML_TO_STRING
Description:

Chapter 5 X-Rules
This action tag will convert an XML form instance into a string.
Syntax
<XML_TO_STRING RhsExpression Var="xmlString"/>
Attributes
z Var (Required): Variable to assign the string to
z RhsExpression (Required): RhsExpression that evaluates to an xml object that
needs to be converted to its string representation
Example 1
<XML_TO_STRING FromSelect="$xml" Var="xmlString"/>
CLONE_XML
Description:
The CLONE_XML operation returns a clone of the XML form instance.
Syntax:
<CLONE_XML DocVar="XMLformObject" AssignToVar="myVar"/>
Attributes:
z DocVar (Required): XML form object to clone
z AssignToVar (Required): Variable to assign the cloned XML to
Example 1:
Input:
<TO_DOCVAR AssignToVar="myXML">
</STATE>
</COUNTRY>
</TO_DOCVAR>
<CLONE_XML DocVar="myXML" AssignToVar="clonedXML"/>
<PRINTLN Value="{$clonedXML}"/>
Output:
</STATE>
</COUNTRY>
SORT_DOCS
Description:
The SORT_DOCS action tag will sort a given list of document instances based on the
specified criteria. This action tag can be used wherever sorting is required.
Syntax

<SORT_DOCS SelectList="list" AssignToVar="myVar">

<Property1 Type="data-type" Sort="Ascending|Descending"
EnumList="comma-seperated-list for enum"/>
<Property2 Type=="data-type"
Sort="Ascending|Descending" EnumList="comma-seperated-list for
enum"/>
.........
</SORT_DOCS>
Note: You can also provide "dynamic" properties for sorting criteria using
TO_XML component. Please see Example 2 for details.
Attributes
z SelectList (Required): List of XML documents for sorting.
z AssignToVar (Required): Sorted result is assigned to this variable.
z Type (Optional): Should be a valid xcore data type or enum. The xcore data types
are int, string, date, double, float, timestamp, datetime, and boolean.
z EnumList (Optional): This is a comma separated list of enum values. This is
needed if Type=enum
Example 1:
<DEFINE_METHOD Name="sortTest">
<RULE>
<ACTION>
<SORT_DOCS SelectList="$thisParam/A"
AssignToVar="myList">
<STATE Sort="Descending" Type="enum"
EnumList="B,D,C,A,E"/>
<PROP1 Sort="Ascending" Type="int"/>
<PROP3 Sort="Ascending" Type="date"/>
</SORT_DOCS>
<TO_XML SelectList="$myList"/>
</APPEND_TO_XML>
</ACTION>
</RULE>
</DEFINE_METHOD>
If the request is like the following, after applying SORT_DOCS, the response will be
as mentioned under the RESPONSE:
<REQUEST Name="sortTest">
<A>
<PROP1 Value="10"/>
<PROP2 Value="M"/>
<PROP3 Value="01/01/2010"/>
<STATE Value="A"/>
</A>
<A>
<PROP1 Value="5"/>
<PROP2 Value="B"/>
<PROP3 Value="01/01/2007"/>

Chapter 5 X-Rules
<STATE Value="B"/>
</A>
<A>
<PROP1 Value="7"/>
<PROP2 Value="M"/>
<PROP3 Value="01/01/2010"/>
<STATE Value="B"/>
</A>
<A>
<PROP1 Value="7"/>
<PROP2 Value="I"/>
<PROP3 Value="01/01/2003"/>
<STATE Value="C"/>
</A>
<A>
<PROP1 Value="1"/>
<PROP2 Value="C"/>
<PROP3 Value="01/01/2005"/>
<STATE Value="A"/>
</A>
<A>
<PROP1 Value="7"/>
<PROP2 Value="X"/>
<PROP3 Value="01/01/2001"/>
<STATE Value="D"/>
</A>
<A>
<PROP1 Value="5"/>
<PROP2 Value="B"/>
<PROP3 Value="01/01/2015"/>
<STATE Value="E"/>
</A>
</REQUEST>
Response after sorting:
<A>
<PROP1 Value="5"/>
<PROP2 Value="B"/>
<PROP3 Value="01/01/2015"/>
<STATE Value="E"/>
</A>
<A>
<PROP1 Value="1"/>
<PROP2 Value="C"/>
<PROP3 Value="01/01/2005"/>
<STATE Value="A"/>
</A>
<A>
<PROP1 Value="10"/>
<PROP2 Value="M"/>
<PROP3 Value="01/01/2010"/>
<STATE Value="A"/>
</A>

<A>
<PROP1 Value="7"/>
<PROP2 Value="I"/>
<PROP3 Value="01/01/2003"/>
<STATE Value="C"/>
</A>
<A>
<PROP1 Value="7"/>
<PROP2 Value="X"/>
<PROP3 Value="01/01/2001"/>
<STATE Value="D"/>
</A>
<A>
<PROP1 Value="5"/>
<PROP2 Value="B"/>
<PROP3 Value="01/01/2007"/>
<STATE Value="B"/>
</A>
<A>
<PROP1 Value="7"/>
<PROP2 Value="M"/>
<PROP3 Value="01/01/2010"/>
<STATE Value="B"/>
</A>
</RESPONSE>
Example 2:
The sorting criteria can also be specified dynamically by using TO_XML component.
Here the previous example has been re-written using both dynamic and static
properties. The input and output for this code snippet is same as previous example.
<DEFINE_METHOD Name="sortTest">
<RULE>
<ACTION>
<TO_DOCVAR AssignToVar="fewDynamicSortProps">
<PROPS>
<STATE Sort="Descending" Type="enum"
EnumList="B,D,C,A,E"/>
<PROP1 Sort="Ascending" Type="int"/>
</PROPS>
</TO_DOCVAR>
<SORT_DOCS SelectList="$thisParam/A"
AssignToVar="myList">
<TO_XML SelectList="$fewDynamicSortProps/*"/>
<PROP3 Sort="Ascending" Type="date"/>
</SORT_DOCS>
<TO_XML SelectList="$myList"/>
</APPEND_TO_XML>
</ACTION>
</RULE>
</DEFINE_METHOD>

Chapter 5 X-Rules
SORT
Description:
The SORT action tag does an in place sort of a list of XMLform instances based on the
specified property.
Syntax:
<SORT SelectList="XMLformList" Key="X-path expression"
DataType="Type" SortOrder="ascending/descending"/>
Attributes:
z SelectList (Required): XML form list
z Key (Required): X-path expression. This expression is specified relative to the
XMLform’s retrieved by the Select List. The expression is applied on each of the
XMLform’s in SelectList to get the key value to sort on.
z DataType (Optional): Type of data being sorted. Valid values are 'number', 'date'
and 'text'. The default is 'text'. An X-Path expression can be specified by enclosing
it in {}.
z SortOrder (Optional): ascending/descending; ascending by default. An X-Path
expression can be specified by enclosing it in {}.
Example 1:
Assume variable "myXml" refers to following xml. The list of <COUNTRY> tags is
to be sorted in descending order using NAME property as the key:
<PARAMS>
<COUNTRY>
<NAME Value="France"/>
<CAPITAL Value="Paris"/>
</COUNTRY>
<COUNTRY>
<NAME Value="Spain"/>
<CAPITAL Value="Madrid"/>
</COUNTRY>
<COUNTRY>
<NAME Value="UK"/>
<CAPITAL Value="London"/>
</COUNTRY>
<COUNTRY>
<NAME Value="Germany"/>
<CAPITAL Value="Berlin"/>
</COUNTRY>
</PARAMS>
This is the input command:
<SORT SelectList="$myXml/COUNTRY" DataType="text" Key="NAME/
@Value" SortOrder="descending"/>
The variable myXml after this call will be:
<PARAMS>
<COUNTRY>
<NAME Value="UK"/>
<CAPITAL Value="London"/>

</COUNTRY>
<COUNTRY>
<NAME Value="Spain"/>
<CAPITAL Value="Madrid"/>
</COUNTRY>
<COUNTRY>
<NAME Value="Germany"/>
<CAPITAL Value="Berlin"/>
</COUNTRY>
<COUNTRY>
<NAME Value="France"/>
<CAPITAL Value="Paris"/>
</COUNTRY>
</PARAMS>
SET_NAMESPACE
Description
The SET_NAMESPACE action tag will recursively set namespace (i.e. prefix and uri)
on given XML element
Syntax
<SET_NAMESPACE LhsExpression Prefix="order" Uri="http://
order.i2.com" ModifyAttributes="true|false"
Recursive=”true|false”/>
Attributes
z LhsExpression (Required): LhsExpression that evaluates to an XML document or
list of xml documents that need to be changed.
z Prefix (Required): X-path value expression that evaluates to prefix string.
z Uri (Required): X-path value expression that evaluates to uri string.
z ModifyAttributes (Optional): true|false; false by default. If set to true then the
attributes will also be modifed to have the prefix.
z Recursive (Optional): true|false; true by default.
Example1
Input:
Assume you have following xml refered by variable myXml:
<EBO>
<Header>
<EnvironmentName firstAttr="abc" secondAttr="xyz">Dev</
EnvironmentName>
</Header>
</EBO>

Chapter 5 X-Rules
To set namespace the command is:

<SET_NAMESPACE DocVar="myXml" Prefix="ebo" Uri="http://
i2.service.com/schemas/PartyEBO" ModifyAttributes="true"/>
Output:
Changed myXml after execution of SET_NAMESPACE will be:
<ebo:EBO xmlns:ebo="http://i2.service.com/schemas/PartyEBO">
<ebo:Header>
<ebo:EnvironmentName ebo:firstAttr="abc"
ebo:secondAttr="xyz">Dev</ebo:EnvironmentName>
</ebo:Header>
</ebo:EBO>
REMOVE_NAMESPACES
Description
The REMOVE_NAMESPACES action tag will recursively remove all namespaces on
given XML element
Syntax
<REMOVE_NAMESPACES LhsExpression Recursive=”true|false”/>
Attributes
z LhsExpression (Required): LhsExpression that evaluates to an XML document or
list of xml documents that need to be changed.
z Recursive (Optional): true|false; true by default.
Example1
Input:
Assume you have following xml refered by variable myXml:
<ebo:EBO xmlns:ebo="http://i2.service.com/schemas/PartyEBO">
<ebo:Header>
<ebo:EnvironmentName ebo:firstAttr="abc"
ebo:secondAttr="xyz">Dev</ebo:EnvironmentName>
</ebo:Header>
</ebo:EBO>
To remove namespaces the command is:

<REMOVE_NAMESPACES DocVar="myXml"/>

Output:
Changed myXml after execution of REMOVE_NAMESPACES:
<EBO>
<Header>
<EnvironmentName firstAttr="abc" secondAttr="xyz">Dev</
EnvironmentName>
</Header>
</EBO>
User-Interface Related Components
SET_SESSION
Description:
This tag is used to set session variables. The session is created when the user is logged
in and it expires when the user session times out or when he/she log outs.
Syntax:
<SET_SESSION Name="varName" RhsExpression/>
Attributes
z Name (Required): Session variable name.
z RhsExpression (Required): Value to store in session variable.
Example 1
<SET_SESSION Name="mySessionVar" FromValue="3"/>
GET_SESSION
Description:
This tag is used to retrieve the session variables. The session is created when the user
is logged in and it expires when the user session times out or when he/she log outs.
Syntax:
<GET_SESSION Name="value" AssignToVar="var"/>
Attributes
z Name (Required): Session variable name.
z AssignToVar (Required): Variable to assign value from the session variable.
Example 1
<GET_SESSION Name="mySessionVar" AssignToVar="returnVar"/>
FORM_SEARCH_FILTER
Description:
The FORM_SEARCH_FILTER tag is primarily used in the UI workflows to help
formulate the search filters to query documents in the database based on the
parameters specified in the PGL screen. The input to this action tag is the XML data

Chapter 5 X-Rules
returned from a search PGL screen (outXML). The criteria to formulate the filters are
described as attributes of child elements.
Syntax:
<FORM_SEARCH_FILTER Value="{xpath expression}"
AssignToVar="varName">
<ChildTagN MultiValued="true[optional=true]"
Range="true[optional=true]"
IsToInclusive="true|false[default=true]" Operator="match-by-
operator[Optional=true]" InputName=”tagname-
input[optional=true]" IsFilter=”true|false[default=false]”
AddOn="true|false[default=false]"
AddNullIfZero="true|false[optional=true, default=false]"
Repeatable="true"/>
</FORM_SEARCH_FILTER>
Attributes
z Value (Required): X-Path expression to specify the XML output from the PGL
z AssignToVar (Required): Variable to assign the filter expression to
z WildCardCharacter: When this attribute is set, it overrides the default '*' as
wild card character. A global service level param with name
'wildCardCharacter' can also be set to override the default '*' as wild card
character for all FORM_SEARCH_FILTER components in that service. In
absence of both the attribute and service parameter, the wild card character
for FORM_SEARCH_FILTER is set to default value, '*'.
Child Tag Attributes
z MultiValued (Optional): "true" indicates that the search filter for the tag must be
formulated with all the values present in request data
z Range (Optional): Used to specify a between condition filter. This is applicable
only to date-range fields.
z IsToInclusive (Optional): This attribute is used in conjunction with the Range
attribute above. Valid values for this attribute are true and false. By default the
value of this attribute is true. This attribute determines whether to use LESS or
LESS_EQUAL in the condition for the to-value. If the value is false, LESS is
used, else LESS_EQUAL is used.
z Operator (Optional): Indicates that the filter builder must copy over the MatchBy
criteria specified in the incoming data
z InputName (Optional): This attribute is used when the filter tag name is different
from the input tag name.
z IsFilter (Optional): This attribute is normally used for forming the search criteria
from a pgl filter table input. The filter table inputs are always prefixed with
FILTER_. So Valid values for this attribute are true and false. By default the value
of this attribute is false. When set to true, the input tag name is formed by adding
FILTER_ prefix to the tag name. InputName attribute is ignored when this
attribute is set to true.

| Used with Range attribute: This attribute is used when a filter row has date
range column. If this attribute is set to true, then filter is formed based on
FILTER_FROM_ and FILTER_TO_ tags in the input.
| Used with Operator attribute: This attribute is used when a filter row has
numeric operator column. If this attribute is set to true, then filter is formed
based on FILTER_name-of-filter FILTER_name-of-filter_MATCH_BY
z AddOn (Optional): Indicates that the tag must simply be copied over as a filter
criteria even if it not present in the incoming XML data
z AddNullIfZero (Optional): For numeric fields the AddNullIfZero attribute can be
set to true to form a FILTER tag that compares the field to either 0 or NULL. This
is useful when the numeric fields can be NULL in database and these rows should
be returned when the user searches for 0.
Example 1
This is the raw XML as returned from a PGL of a search screen:
<TO_DOCVAR AssignToVar="outXml">
<PARAMETERS>
<RECORD_COUNT Value="NaN"/>
<SYS_ID Value="C:/temp/SearchSchedule.pgl"/>
<MAX_ROWS Value="10"/>
<FROM_DELIVERY_DATE Value="03/24/2004"/>
<SORT_ORDER Value="Ascending"/>
<ORDER_POINT_ID Value=""/>
<PAGE Value="studio_ui"/>
<PAGE_NAME Value="studio_ui"/>
<STATE_ID Value=""/>
<DO_SEARCH Value="false"/>
<VISIBILITY Value="Simple"/>
<pagenum Value=""/>
<NO_OF_ROWS Value="0"/>
<TO_DELIVERY_DATE Value="03/24/2005"/>
<BUTTON_ID Value="search"/>
<SHIP_TO_NAME Value="*"/>
<SORT_BY Value="ID"/>
<START_COUNT Value="0"/>
<ITEM_ID Value=""/>
<SHIP_FROM_NAME Value="G*,P*"/>
<SHIP_FROM_NAME Value="*H*"/>
<SUBMIT_AS_XML Value="false"/>
<NUMBER Value="7800"/>
<NUMBER_MATCH_BY Value="GREATER_EQUAL"/>
</PARAMETERS>
</TO_DOCVAR>
This is the request to formulate the search filters from the XML data above:
<FORM_SEARCH_FILTER Value="{$outXml}" AssignToVar="filters">
<SHIP_TO_NAME/>
<SHIP_FROM_NAME MultiValued="true"/>
<STATE_ID MultiValued="true"/>
<ITEM_ID/>
<DELIVERY_DATE Range="true"/>
<NUMBER Operator="true"/>

Chapter 5 X-Rules
<STATUS Value="ACTIVE" AddOn="true"/>

</FORM_SEARCH_FILTER>
This is the response:
<FILTERS>
<FILTER Name="SHIP_TO_NAME">
<SHIP_TO_NAME Value="%" MatchBy="LIKE"/>
</FILTER>
<FILTER Name="SHIP_FROM_NAME">
<OR>
<SHIP_FROM_NAME Value="G%" MatchBy="LIKE"/>
<SHIP_FROM_NAME Value="P%" MatchBy="LIKE"/>
<SHIP_FROM_NAME Value="%H%" MatchBy="LIKE"/>
</OR>
</FILTER>
<FILTER Name="DELIVERY_DATE">
<DELIVERY_DATE Value="03/24/2004"
MatchBy="GREATER_EQUAL"/>
<DELIVERY_DATE Value="03/24/2005"
MatchBy="LESS_EQUAL"/>
</FILTER>
<FILTER Name="NUMBER">
<NUMBER Value="7800" MatchBy="GREATER_EQUAL"/>
</FILTER>
<FILTER Name="STATUS">
<STATUS Value="ACTIVE" AddOn="true"/>
</FILTER>
</FILTERS>
</RESPONSE>
FORM_GET
Description:
The FORM_GET tag helps in getting a list of nodes from another list based on a set of
conditions. It can be used to select a set of nodes from a huge list using a filter.
Syntax:
<FORM_GET AssignToVar="var">
<FORM Value="{xpath expression}" ChildName="name"
KeyProp="property"/>
<FILTER SelectList="{xpath expression}"/>
</FORM_GET>
Attributes
z AssignToVar (Required): Variable to assign the output to.
z FORM Value (Required): Parent node of the list from where the nodes have to be
selected.
z FORM ChildName (Required): Child element name under the parent specified
above.
z FORM KeyProp (Required): Key with which the filtering values would be
matched.

z FILTER SelectList (Required): Item to be selected.

Example 1
This is the list which needs to be filtered:
<WORLD>
<COUNTRIES>
<COUNTRY>
<NAME Value="India"/>
<CAPITAL Value="New Delhi"/>
<LANGUAGE Value="Hindi"/>
</COUNTRY>
<COUNTRY>
<NAME Value="USA"/>
<CAPITAL Value="Washington"/>
<LANGUAGE Value="English"/>
</COUNTRY>
<COUNTRY>
<NAME Value="Russia"/>
<CAPITAL Value="Moscow"/>
<LANGUAGE Value="Russian"/>
</COUNTRY>
</COUNTRIES>
</WORLD>
This is the filter condition:
<PARAMETERS>
<SELECTED Value="New Delhi"/>
<SELECTED Value="Moscow"/>
</PARAMETERS>
This is the input:
<FORM_GET AssignToVar="outVar">
<FORM Value="{$myXml/COUNTRIES}" ChildName="COUNTRY"
KeyProp="CAPITAL"/>
<FILTER SelectList="$filter/SELECTED/@Value"/>
</FORM_GET>
<PRINTLN Value="{$outVar}"/>
This is the output:
<COUNTRY>
</COUNTRY>
<COUNTRY>
</COUNTRY>
FORM_REMOVE
Description:

Chapter 5 X-Rules
The FORM_REMOVE tag helps in removing specific nodes from a list depending on
a criterion. This tag can be used whenever you want to remove some node(s) from
pipeline list depending on the set of user selections in a PGL UI table.
Syntax:
<FORM_REMOVE AssignToVar="var[Optional=true]">
<FORM Value="{xpath expression}" ChildName="child"
<FILTER SelectList="filter"/>
</FORM_REMOVE>
Attributes:
z AssignToVar (Optional): Variable to assign the output to. The output is a list of
removed child elements.
z FORM Value (Required): Parent element where the removal operation has to be
done.
z FORM ChildName (Required): Children to search for under the parent element.
z FORM KeyProp (Required): Key with respect to the xml list for child elements.
z FILTER SelectList (Required): List of nodes to be removed.
Example 1
Assume following is the node list (myXml):
<TOTAL_STATES Value="27"/>
</STATE>
</STATE>
<STATE Value="TamilNadu">
<CAPITAL Value="Chennai"/>
</STATE>
</COUNTRY>
This is the filter:
<PARAMETERS>
<CAP Value="Bombay"/>
<CAP Value="Chennai"/>
</PARAMETERS>
This is the input:
<FORM_REMOVE>
<FORM Value="{$myXml}" ChildName="STATE" KeyProp="CAPITAL"/
>
<FILTER SelectList="$filter/CAP/@Value"/>
</FORM_REMOVE>
<PRINTLN Value="{$myXml}"/>
This is the output (myXml):

<TOTAL_STATES Value="27"/>
</STATE>
</COUNTRY>
FORM_UPDATE
Description:
The FORM_UPDATE action tag helps updating an xml variable from a flat xml
structure. This tag can be used whenever you want to update a list based on the output
from a PGL UI table. It does the collation of data and updating in one step.
Syntax:
<FORM_UPDATE>
<FILTER SelectList="list"/>
<FORM Value="{xpath expression}" ChildName="child"
<PROPS Source="{xpath expression}">
<Property1/>
<Property2/>
........
</PROPS>
</FORM_UPDATE>
Attributes
z FILTER SelectList(Required): List of values to be filtered from; it acts as keys to
be searched in the xml to be updated.
z FORM KeyProp (Required): Key to use for filtering with respect to the tree xml
list.
z FORM Value (Required): Parent element variable which needs to be updated
z FORM ChildName (Required): Children to search for under the parent specified
by FORM Value attribute.
z PROPS Source (Required): The source xml which contains the new property
values (say data from a UI table).
FORM_UPDATE first matches all the rows with the respective node in the list using
FORM SelectList and FORM KeyProp attributes. After matching it updates the tags
specified within PROPS tag from PROPS Source to the corresponding nodes in
FORM ChildName.
Example 1
Assume following is the raw XML as returned from PGL to the workflow and is
referred to by variable 'formXml' (contains correct values for the capital city and
primary language):
<PARAMETERS>
<NAME Value="USA"/>
<CAPITAL Value="Washinton DC"/>

Chapter 5 X-Rules
</PARAMETERS>
The xml to be updated (referred to by variable 'oldXml' and contains incorrect values):
<WORLD>
<COUNTRIES>
<COUNTRY>
<CAPITAL Value="Delhi"/>
<LANGUAGE Value="German"/>
</COUNTRY>
<COUNTRY>
<NAME Value="USA"/>
<CAPITAL Value="New York"/>
<LANGUAGE Value="Spanish"/>
</COUNTRY>
<COUNTRY>
</COUNTRY>
</COUNTRIES>
</WORLD>
The form update operation:
<FORM_UPDATE>
<FILTER SelectList="$formXml/NAME/@Value"/>
<FORM Value="{$oldXml/COUNTRIES}" ChildName="COUNTRY"
KeyProp="NAME"/>
<PROPS Source="{$formXml}">
<LANGUAGE/>
<NAME/>
<CAPITAL/>
</PROPS>
</FORM_UPDATE>
The updated xml is:
<WORLD>
<COUNTRIES>
<COUNTRY>
</COUNTRY>
<COUNTRY>
<NAME Value="USA"/>
<CAPITAL Value="Washinton DC"/>
</COUNTRY>
<COUNTRY>
</COUNTRY>
</COUNTRIES>

</WORLD>
PAGINATE_LINES
Description:
This tag is used for in-memory pagination. It will return as many elements of the input
list as specified by the MaxRows attribute starting from index specified by StartCount
attribute.
Syntax:
<PAGINATE_LINES SelectList="X-Path expression" StartCount="X-
Path expression" MaxRows="X-Path Expression"
AssignToVar="var[Optional=true]"/>
Attributes
z SelectList (Required): X-Path expression that will evaluate to a list that needs to
be paginated.
z StartCount (Required): Start count. This should be an X-Path expression that
evaluates to an integer value. Lowest value allowed is 0.
z MaxRows (Required): Max rows count. This should be an X-Path expression that
evaluates to an integer value.
z AssignToVar (Optional): The variable that the output should be assigned to. If this
attribute is not specified then the output is added as a child to the parent tag. As
such this action component can be used for building dynamic xml inside
TO_DOCVAR and APPEND_TO_XML and inside commands that allow
dynamic content as REQUEST, ADD_DOCUMENT etc.
Example 1
Assume variable ‘changedLines’ refers to:
<LINES>
<LI>
<ID Value="1"/>
</LI>
<LI>
<ID Value="2"/>
</LI>
<LI>
<ID Value="3"/>
</LI>
<LI>
<ID Value="4"/>
</LI>
<LI>
<ID Value="5"/>
</LI>
</LINES>
Input:
<TO_DOCVAR AssignToVar="pLines">
<LINES>

Chapter 5 X-Rules
<PAGINATE_LINES SelectList="$changedLines/LI"
StartCount="{0}" MaxRows="{2}"/>
</LINES>
</TO_DOCVAR>
Output:
<LINES>
<ITEMS_LIST TotalRowCount="5">
<LI>
<ID Value="1"/>
</LI>
<LI>
<ID Value="2"/>
</LI>
</ITEMS_LIST>
</LINES>
TAG_ERRORS
Description:
TAG_ERRORS operation is primarily used in the UI workflows for copying errors
from one or more elements to a target element (or tag). This action component is very
useful when the requirement is to show an error icon beside a field and the errors
returned by the business API are on some other element(s). As PGL shows an error
icon beside a field whenever it finds an _ERRORS tag under that field element, this
component can be used to copy errors so that they are shown for appropriate fields on
the UI.
Syntax:
<TAG_ERRORS SelectList="list" Name="property-name">
<Property1/>
<Property2/>
..........
</TAG_ERRORS>
Attributes
z SelectList (Required): List of parent elements whose children need to be searched
for collecting errors.
z Name (Required): Element under which all errors found are collected. If this
element does not exist under the parent element then it will be created and errors
will be added under it.
The child elements from which error tags need to be collected are specified within the
component body by specifying the child element names.
Example 1
This is the XML from which a set of errors is to be grouped under one element:
<BPO>
<SELLING_ORG_ID Value="Saturn"/>
<SELLING_ORG_NAME Value="Saturn"/>

<ORDER_POINT_ID Value="Velocity-Dallas"/>
<ORDER_POINT_NAME Value="Velocity-Dallas"/>
<BUYER_ORG_ID Value="Velocity"/>
<TYPE_ID Value="QUANTITY"/>
<NOTES/>
<BPO_LINES>
<BPO_LINE>
<ID Value="bpoli-3311102557060272"/>
<ITEM_ID Value="C-136D8710G01"/>
<ITEM_DESC Value="Borescope Set - S"/>
<SUPPLIER_PART_NUMBER/>
<UOM Value="EA"/>
<QTY_LIMIT Value="0">
<_ERROR Value="INVALID_VALUE"
Severity="ERROR"/>
</_ERRORS>
</QTY_LIMIT>
<QTY_USED Value="1">
<_ERROR
Value="QTY_LIMIT_LESS_THAN_QTY_USED" Severity="ERROR"/>
</_ERRORS>
</QTY_USED>
<MIN_RELEASE_QTY Value="0"/>
<MAX_RELEASE_QTY Value="0"/>
<NOTIFY_QUANTITY_PERCENTAGE Value=""/>
</BPO_LINE>
</BPO_LINES>
</BPO>
This is the input operation:
<TAG_ERRORS SelectList="$currentBPO/BPO_LINES/BPO_LINE"
Name="QUANTITY_ERRORS">
<QTY_LIMIT/>
<QTY_USED/>
<MIN_RELEASE_QTY/>
<MAX_RELEASE_QTY/>
</TAG_ERRORS>
This is the output (you can see a new tag named QUATITY_ERRORS under
BPO_LINE which has all the errors found under QTY_LIMIT, QTY_USED,
MIN_RELEASE_QTY and MAX_RELEASE_QTY):
<BPO>
<SELLING_ORG_ID Value="Saturn"/>
<SELLING_ORG_NAME Value="Saturn"/>
<ORDER_POINT_ID Value="Velocity-Dallas"/>
<ORDER_POINT_NAME Value="Velocity-Dallas"/>
<BUYER_ORG_ID Value="Velocity"/>
<NOTES/>
<BPO_LINES>
<BPO_LINE>

Chapter 5 X-Rules
<ID Value="bpoli-3311102557060272"/>
<ITEM_ID Value="C-136D8710G01"/>
<ITEM_DESC Value="Borescope Set - S"/>
<SUPPLIER_PART_NUMBER/>
<UOM Value="EA"/>
<QTY_LIMIT Value="0">
Severity="ERROR"/>
</_ERRORS>
</QTY_LIMIT>
<QTY_USED Value="1">
<_ERROR
</_ERRORS>
</QTY_USED>
<MIN_RELEASE_QTY Value="0"/>
<MAX_RELEASE_QTY Value="0"/>
<NOTIFY_QUANTITY_PERCENTAGE Value=""/>
<QUANTITY_ERRORS>
<_ERRORS>
Severity="ERROR"/>
<_ERROR
</_ERRORS>
</QUANTITY_ERRORS>
</BPO_LINE>
</BPO_LINES>
</BPO>
DROP_DOWN_OPTIONS
Description:
This action tag is primarily used in the UI workflows for generating options in the
format that the PGL ui:dropdown tag requires. It is mostly used in preprocessing stage
of a UI node in a workflow.
Syntax:
<DROP_DOWN_OPTIONS SelectList="$orderPointInfo/SHIP_TO_LIST/
SHIP_TO" Id="ID" Value="NAME" FirstId="{$orderPointInfo/
SHIP_TO/ID/@Value}"/>
Attributes
z SelectList (Required): List of values that needs to displayed in the UI dropdown
box.
z Id (Required): Tag that corresponds to your dropdown box IDs.
z Value (Required): Tag that corresponds to your dropdown box values.
z FirstId (Optional): The value which becomes the first option in the output options.

Example 1
This is the XML from which the drop down options has to be generated:
<ORDER_POINT_INFO Status="Success">
<SHIP_TO_LIST>
<SHIP_TO>
<ID Value="Velocity-Warren"/>
<NAME Value="Velocity-Warren"/>
</SHIP_TO>
<SHIP_TO ExistingDocument="yes">
<ID Value="Velocity-DC1"/>
<NAME Value="Velocity-DC1"/>
</SHIP_TO>
<SHIP_TO ExistingDocument="yes">
<ID Value="Velocity-DC2"/>
<NAME Value="Velocity-DC2"/>
</SHIP_TO>
</SHIP_TO_LIST>
</ORDER_POINT_INFO>
This is the input command:
<DROP_DOWN_OPTIONS SelectList="$myXml/SHIP_TO_LIST/SHIP_TO"
Id="ID" Value="NAME" FirstId="{$myXml/SHIP_TO/ID/@Value}"/>
The options list output below can be used as the input to the PGL UI dropdown tag
optionSrc attribute:
<OPTION Value="Velocity-Warren" Id="Velocity-Warren"/>
<OPTION Value="Velocity-DC1" Id="Velocity-DC1"/>
<OPTION Value="Velocity-DC2" Id="Velocity-DC2"/>
CREATE_URL
Description:
This action tag is used for creating URLs by appending parameters (Name-Value
pairs) to it.
Syntax:
<CREATE_URL Name="literal or {X-Path expression}"
AssignToVar="variable name">
<ParamN Value="value" Repeatable="true"/>
</CREATE_URL>
Param1…ParamN tag contains the names of the parameters and their parameters
which need to be appended to the URL. Each child tag corresponds to a parameter.
The name of the child tag is the name of the parameter. The value attribute contains
the value of the parameter.
Attributes
z Name(Required): The base url to which the values need to be appended.
z AssignToVar(Required): Variable to which the resultant url string is assigned.
Example 1
Following is example of how the tag can be used inside an X-Rule:

Chapter 5 X-Rules
<CREATE_URL Name="{$webuiContextPath}/cpm/planning/tabs/
showCurrentForecastByEventType.cmd?" AssignToVar="myUrl">
<SUPPLIER_ID Value="{$thisParam/SUPPLIER_ID/@Value}"/>
<ITEM_ID Value="{$thisParam/ITEM_ID/@Value}"/>
<CUSTOMER_ID Value="{$thisParam/CUSTOMER_ID/@Value}"/>
</CREATE_URL>
When passed a thisParam input as follows:
<REQUEST Name="foo">
<SUPPLIER_ID Value="sup1"/>
<ITEM_ID Value="item1"/>
<CUSTOMER_ID Value="cust1"/>
</REQUEST>
The following output is produced:
//localhost:7001/omxclient/cpm/planning/
showCurrentForecastByEventType.cmd?SUPPLIER_ID=sup1&ITEM_ID=ite
m1&CUSTOMER_ID=cust1
SET_REDIRECT_URL
Description:
This action tag is used for setting the re-direct URL. Typically this is set in the done
node of a UI workflow. Once the workflow is done, the screen flow will be redirected
to this URL. A common candidate for SET_REDIRECT_URL is the home page of the
application.
Syntax:
<SET_REDIRECT_URL Value="literal or {X-Path expression}"/>
Attributes
z Value (Required): The url to which the screen needs to be redirected.
Example 1
Following is example of how the tag can be used:
<CREATE_URL Name="{$webuiContextPath}/cpm/planning/tabs/
showCurrentForecastByEventType.cmd?" AssignToVar="myUrl">
<SUPPLIER_ID Value="{$thisParam/SUPPLIER_ID/@Value}"/>
<ITEM_ID Value="{$thisParam/ITEM_ID/@Value}"/>
<CUSTOMER_ID Value="{$thisParam/CUSTOMER_ID/@Value}"/>
</CREATE_URL>
<SET_REDIRECT_URL Value="{$myUrl}"/>
Example 2
<SET_REDIRECT_URL Value="//localhost:7001/omxclient/base/cse/
home.cmd"/>
Utility Components
EXECUTE_SHELL_COMMAND
Description:

This action component can be used to perform OS Shell Commands and get the results
in a XML format. The calling application is responsible for issuing platform
dependent command statement. There is no restriction on what command can be
issued, and hence you should take care to not use a command that can hang the X-
Server. Caution: Although the system does not enforce setting of TimeOut attribute
for backward compatibility reasons, the user must always specify a TimeOut.
Syntax:
<EXECUTE_SHELL_COMMAND Value="literal or {X-Path expression}"
TimeOut="integer[Optional=true]"
WorkingDirectory="path[Optional=true]"
CaptureStdOut="true|false[Optional=true,default=true]"
CaptureErrOut="true|false[Optional=true,default=true]"
AssignToVar="var"/>
Attributes
Value (Required): The shell command to execute.
TimeOut (Optional): Timeout in milli-seconds. Dynamic values can be specified by
using {}.
Note: TimeOut can be assigned the value of "-1", which will make the command
non blocking, as in the process will be started but the
EXECUTE_SHELL_COMMAND will not wait for the process to finish. A
exit code of 0 is always returned when TimeOut="-1" is used.
WorkingDirectory (Optional): The value of this attribute sets up the working directory
of the command being launched. Default working directory is set to the same working
directory as the ABPP application.
CaptureStdOut (Optional): This attribute can be set to ‘false’ to turn off capturing of
the standard output of the launched shell command.
CaptureErrOut (Optional): This attribute can be set to ‘false’ to turn off capturing of
the standard error of the launched shell command.
AssignToVar (Optional): The variable that the output should be assigned to.
Example 1:
The following command will return the Java help for the system:
<EXECUTE_SHELL_COMMAND Value="java -help" TimeOut="1000"
AssignToVar="response"/>
The following response is returned for the above operation:
<RESPONSE Status="Success" ShellReturnValue="0">
<STD_OUT>
<LINE Value="Usage: java [-options] class [args...]"/>
<LINE Value=" (to execute a class)"/>
<LINE Value=" or java [-options] -jar jarfile
[args...]"/>
<LINE Value=" (to execute a jar file)"/>
<LINE Value="where options include:"/>
...
</STD_OUT>

Chapter 5 X-Rules
<STD_ERR/>
</RESPONSE>
The ShellReturnValue attribute in the response provides the exit code of the shell
process. The output of the shell command to its standard ouput stream is available
under STD_OUT tag and to its standard error stream is available under STD_ERR tag.
EXEC_INFORMATICA
Description:
The EXEC_INFORMATICA tag can be used to invoke an Informatica transform
directly from ABPP. The assumption is that Informatica client is installed on the same
machine where the ABPP server is installed.
Note: To use this tag, ensure that your Xserver config file has the service parameters
needed to connect to Informatica The following xml snippet shows the
required service parameters with sample values.
<service-params>
<param Value="C:\Informatica\PowerCenter Server\bin\PmCmd"
Name="pmCmdPath"/>
<param Value="Administrator" Name="repUserName"/>
<param Value="Administrator" Name="repPassword"/>
<param Value="blrqa01" Name="hostName"/>
<param Value="4001" Name="portNo"/>
</service-params>
Where 'pmCmdPath' parameter points to the bin folder of Informatica's PowerCenter.
Syntax:
<EXEC_INFORMATICA AssignToVar="response">
<FOLDER Value="informatica-folder-name"/>
<WORKFLOW Value= "informatica-workflow-name"/>
<BATCH Value="informatica-batch-name "/>
<SESSION Value="informatica-session-name"/>
<WAIT_FLAG Value="0/1"/>
</EXEC_INFORMATICA>
Attributes:
z AssignToVar (Optional): Variable to which the response is assigned
Child Tags:
z FOLDER (Required): Folder where the workflow/batch/session file is located
z WORKFLOW (Optional): Informatica Workflow name
z BATCH (Optional): Informatica Batch name
z SESSION (Optional): Informatica Session name
z WAIT_FLAG (Required): "0/1"
Note: Exactly one of the three - WORKFLOW, BATCH, and SESSION - should be
provided.

Example 1:
<EXEC_INFORMATICA AssignToVar="response">
<FOLDER Value="custdb_input"/>
<BATCH Value="b_all"/>
<WAIT_FLAG Value="1"/>
</EXEC_INFORMATICA>
LOAD_XML_FILE
Description:
This action tag will read an XML file and assign the contents to a variable.
Syntax
<LOAD_XML_FILE Var="variable-name" FromValue="file-name" />
Attributes
z Var (Required): Variable to which the file contents are to be assigned.
z FromValue (Required): Name of the xml file. You can use an expression to
specify the file name by wrapping the expression with {}. If the file name is not
an absolute path, the system will try to find it in the class path.
Example 1
<LOAD_XML_FILE Var="myVar" FromValue="myFile1.xml" />
<LOAD_XML_FILE Var="myVar2" FromValue="{$thisParam/FILENAME/
@Value}" />
STORE_XML_FILE
Description:
This action tag can be used to write an XML document to the specified file on the
local file system.
Note: This has been deprecated. Use PRINT_TO_FILE instead of this action
component.
Syntax
<STORE_XML_FILE Value="fileName" FromSelect="$xml"
Beautify="true|false"/>
Attributes
z FromSelect (Required): X-Path expression that evaluates to XML document that
needs to be written to the file.
z Value (Required): File name where the xml needs to be written to. This can be a
literal value or an X-Path expression enclosed within {}. If the path specified is
relative path then it will be resolved against the working directory.
z Beautify(Optional): true/false. When the attribute exists and the value is true the
xml written out will be formatted. Default value of the attribute(when it is not
explicitly specified) is false.
Example 1

Chapter 5 X-Rules
<STORE_XML_FILE FromSelect="$xml" Value="myFile1.xml"

Beautify="true"/>
PRINT_TO_FILE
Description:
This action tag will write the string representation of any object onto a file on the local
file system. It can also be used to append text to an existing file.
Syntax
<PRINT_TO_FILE File="filename" NewFile="true|false"
StartOnNewLine="true|false" Value="text" Beautify="true|false"/
>
Attributes
z File (Required): A file in a valid directory of the file system. Directories would
NOT be created. "No directory", would imply current directory. If such a file by
that name does not exist, then a file would be created.
z NewFile (Optional): Valid values are "true" or "false". For backward
compatibility "yes" or "no" are also supported. A "true" would imply that a new
file needs to be created with the name. If there is a file already existing with the
name, then the file would be cleaned up and writing would start at the Top. A
"false" would imply that writing would continue at the bottom of the File; a new
File will be created if there is no such File present in the given directory. Default
value is "false".
z StartOnNewLine (Optional): Valid values are "true" or "false". A "true" would
imply that the new text to be printed should start on a new line. A "false" would
imply that the new text to be printed should be on the same Line. Default value is
"false". Note that it is illegal to specify NewFile="true" and
StartOnNewLine="false" as a new file output will always start on a new line.
z Value (Required): An X-Path expression to represent the content for the file.
z Beautify(Optional): Valid values are "true" or "false". When the attribute exists
and the value is "true" the output will be formatted if the entire content of string
written out is valid xml content. Default value of the attribute(when it is not
explicitly specified) is "false". Note that it is illegal to specify
StartOnNewLine="false" and Beautify="true" as Beautify="true" makes sense
only if the output is going to be on a new line.
Example 1
<DEFINE_METHOD Name="printToFileTest">
<RULE>
<ACTION>
<PRINT_TO_FILE File="C:/Temp/myFile.txt"
NewFile="true" StartOnNewLine="true" Value="1Test Line"/>
NewFile="false" StartOnNewLine="false" Value="2TestLine"/>
NewFile="false" StartOnNewLine="true" Value="3TestLine"/>
<TO_DOCVAR AssignToVar="x">
<A>
<B Value="1"/>

</A>
</TO_DOCVAR>
NewFile="false" StartOnNewLine="false" Value="{$x}"/>
NewFile="false" StartOnNewLine="true" Beautify="true"
Value="{$x}"/>
</ACTION>
</RULE>
</DEFINE_METHOD>
GET_CURRENT_TIME
Description:
This action tag return the current time. If a logical date is set, then current time is as
per the logical date.
Syntax:
<GET_CURRENT_TIME AssignToVar="myTime"/>
Attributes:
z AssignToVar (Required): Variable to assign the current time to
Example 1:
<GET_CURRENT_TIME AssignToVar="CurrentTime"/>
SET_LOGICAL_DATE
Description:
This action tag is used to set the logical date of the application server.
Syntax:
<SET_LOGICAL_DATE Value="literal or {X-Path expression}"/>
Attributes:
z Value (Required): X-Path expression or date string specifying the new datetime to
be set as the logical date.
Example 1:
<SET_LOGICAL_DATE Value="{incrDate(date(), duration(0,(-
1),0,0))}"/>
DO_TRANSACTION
Description:
This action is used when the user wants to execute a new transaction in the same
thread. This means that all action tags defined as children of DO_TRANSACTION
will be executed in a different context by the same java thread invoking the
DO_TRANSACTION action. The new database transaction used by
DO_TRANSACTION will be committed at end of the DO_TRANSACTION action
and rolled back if there is any exception inside the action. This action component
needs a new database connection and so care should be taken to make sure that

Chapter 5 X-Rules
sufficient number of database connections have been specified in the server config file
so that the application does not run out of active database connections and deadlock.
Syntax:
<DO_TRANSACTION>
{One or more Operations}
</DO_TRANSACTION>
Attributes:
None
Example 1:
<DO_TRANSACTION>
<REQUEST Name="updateOrder">
<CUSTOMER_ORDER_ID Value="87"/>
<MODIFIED_DATE Value="2/23/2004"/>
</REQUEST>
</DO_TRANSACTION>
REFRESH_FROM_CACHE
Description:
If you know that a document instance is in cache and you have the instance reference
in X-Rules, you can boost system performance by refreshing the value of properties of
your instance by invoking the REFRESH_FROM_CACHE operation that accesses
the ABPP cache directly and updates the values of the instance in the X-Rules.
The document instance is accessed using the root tag name which maps to document
name and the primary keys that are available in the instance specified. If the instance
is not available in ABPP cache, then it will be fetched from the database.
Syntax:
<REFRESH_FROM_CACHE LhsExpression>
<PROP Name="Property1" Repeatable="true"/>
</REFRESH_FROM_CACHE>
Attributes:
z LhsExpression (Required): LhsExpression that evaluate to one or more XML
document instances.
z PROP Name (Required): This specifies the property of the document instance that
needs to be updated from cache.
Example 1:
In the example below, the specified property values will be obtained from cache and
updated on the XML referred to by variable mySched:
<REFRESH_FROM_CACHE Select="$mySched">
<PROP Name="SHIP_FROM_ID"/>
<PROP Name="SHIP_DATE"/>
<PROP Name="QTY"/>
<PROP Name="NON_EXISTING_PROP"/>
<PROP Name="CITY_TAX"/>
</REFRESH_FROM_CACHE>

NATIVE_FUNCTION
Description:
The NATIVE_FUNCTION component can be used to invoke static Java functions
from X-Rules.
Syntax:
<NATIVE_FUNCTION ClassName="myClassName"
MethodName="myMethodName" AssignToVar="rtnVar[Optional=true]">
<PARAM LhsExpression Repeatable="true"/>
</NATIVE_FUNCTION >
Attributes:
z ClassName (Required): Class Name whose static method is to be invoked
z MethodName (Required): Method to invoke
z AssignToVar (Optional): Variable to store the return value
z PARAM LhsExpression (Optional): LhsExpression that is evaluated to calculate a
parameter value. The first PARAM LhsExpression will be map to first parameter
of the method, the second one to second parameter and so on.
Example:
<NATIVE_FUNCTION
ClassName="com.i2.xcore.idgen.UniqueIdGenerator"
MethodName="getUniqueId" AssignToVar="myId">
<PARAM Value="PO"/>
</NATIVE_FUNCTION>
INSTANCE_METHOD
Description:
The INSTANCE_METHOD component can be used to invoke Java class methods of
an object from X-Rules.
Syntax:
<INSTANCE_METHOD MethodName="myMethodName" ObjVar="myObjVar"
AssignToVar="rtnVar[Optional=true]">
<PARAM LhsExpression Repeatable="true"/>
</INSTANCE_METHOD>
Attributes:
z MethodName (Required): Method Name
z ObjVar (Required): Object to invoke the method on.
z AssignToVar (Optional): Variable to store the return value
z PARAM LhsExpression (Optional): LhsExpression that is evaluated to calculate a
parameter value. The first PARAM LhsExpression will be map to first parameter
of the method, the second one to second parameter and so on.
Example:
<INSTANCE_METHOD MethodName="getTotalEstimatedInvoiceValue"
ObjVar="coObj" AssignToVar="invoiceValue"/>

Chapter 5 X-Rules
POST
Description:
This component will post an xml document on to a URL and return the response. The
response xml document can be assigned to a variable.
Syntax:
<POST Url="url-string" DocVar="xmlDocVariable"
AssignToVar="variableName [Optional=true]"/>
Attributes
z Url (Required): A fixed URL or an X-Path expression enclosed by {} which will
evaluate to a URL
z DocVar(Required): XML document to be posted
z AssignToVar (Optional): Variable which will contain the xml response.
Example
<POST Url="http://localhost:2000" DocVar="myDoc"
POST_STRING
Description:
This component will post a string on to a URL and return the response. The response
string can be assigned to a variable.
Syntax:
<POST_STRING Url="url-string" Var="stringVariable"
AssignToVar="variableName [Optional=true]"/>
Attributes
z Url (Required): A fixed URL or an X-Path expression enclosed by {} which will
evaluate to a URL
z Var(Required): Variable containing the string to be posted
z AssignToVar (Optional): Variable which will contain the string response.
Example
<SET Var="myStringVar" FromValue="{text($thisParam/BODY)}"/>
<POST_STRING Url="http://localhost:2000" Var="myStringVar"
SLEEP
Description:
This action will cause the currently executing thread to sleep (temporarily cease
execution) for the specified number of seconds.
Syntax:
<SLEEP Value="10"/>
Attributes:

Value (Required): The number of seconds to sleep. Dynamic value can be specified by
using {X-Path expression}.
Example:
<SLEEP Value="10"/>
TIMING_MARKER
Description:
This action can be used to measure execution time for any rule code block when the
timing stats have been enabled. (To enable timing stats refer to use of TimingStats
attribute on the REQUESTS call).
Syntax:
<TIMING_MARKER Name="markerName">
{One or more X-Rule action components}
</TIMING_MARKER>
Attributes:
Name (Required): The name of the marker can be any valid string. Using meaningful
name will help in identifying the marker in the response xml that has timing details.
Example 1:
<DEFINE_METHOD Name="test">
<RULE>
<ACTION>
<TIMING_MARKER Name="m1">
<GET_DOCUMENT Name="LineItem"
AssignToVar="lines">
<OrderID Value="{$thisParam/CO_ID/@Value}"/
>
</GET_DOCUMENT>
<FOR_EACH SelectList="$lines/*"
CurrentElement="li">

</FOR_EACH>
</TIMING_MARKER>
</ACTION>
</RULE>
</DEFINE_METHOD>
The response of this rule when called with TimingStats="2" will be:
<RESPONSES>
<RESPONSE>
<TIMING_STATS StartTime="1164135001162"
EndTime="1164135001202" ElapsedTime="40">
<REQUEST_OPERATION ElapsedTime="40" Description="//
bookstore/test">
<MARKER_OPERATION ElapsedTime="40"
Description="m1">
<REQUEST_OPERATION ElapsedTime="20"
Description="//bookstore/GET_DOCUMENT">
...
</REQUEST_OPERATION>

Chapter 5 X-Rules
</MARKER_OPERATION>
</REQUEST_OPERATION>
...
<MARKER_OPERATIONS TotalTime="40">
<MARKER_OPERATION ElapsedTime="40"
Description="m1"/>
</MARKER_OPERATIONS>
</TIMING_STATS>
</RESPONSE>
</RESPONSES>
In this example the MARKER_OPERATION tag inside REQUEST_OPERATION

tag indicates the time taken for all action components inside the TIMING_MARKER
identified by "m1". The MARKER_OPERATIONS tag under TIMING_STATS gives
a summary of all the TIMING_MARKER actions executed.
Framework Specification Components

The ABPP framework provides various specification like validation, purge etc that
provide utility services. These specifications provide action components to utilize
their services. For information on these commands please refer to appropriate
specification chapters.
Example:
Action components specific to Validation can be found in Invoke Validation
Framework to Validate XML Document and Other Utility action Components sections
located in the Validations chapter of the Programmer’s Reference Guide, Part Two.

Chapter 6
X-Path
This chapter gives you information on X-Path semantics used in the ABPP
framework.It includes the following topics.
Topics:
z Introduction
z X-Path Basics
z Boolean X-Path Expressions
z Node-Set Functions
z String Functions
z Boolean Functions
z Number Functions
z Arithmetic Functions
z Comparison Functions
z XMLform & Core Functions
z Time Functions
z Java's SimpleDateFormat
z Miscellaneous Functions
z Java Functions
Introduction
The primary purpose of X-Path is to provide a means to address parts of an XML
document. In addition, it makes available a number of functions for manipulating
strings, numbers and Booleans. It contains a compact, non-XML syntax to facilitate
use within URIs and XML attribute values. X-Path operates on the abstract, logical
structure of an XML document, rather than its surface syntax. X-Path gets its name
from its use of a path notation as in URLs for navigating through the hierarchical
structure of an XML document.

Chapter 6 X-Path
In the ABPP framework, X-Path is used as a concise way to express X-Rules. The
main syntactic paradigm in X-Path is the expression. An expression is evaluated to
yield an object, which has one of the following four basic types:
z Node-set (an unordered collection of nodes without duplicates)
z Boolean (true or false)
z Number (a floating-point number)
z String (a sequence of characters)
Note: The X-Path functions in ABPP are similar in syntax and usages to those
provided under the W3C standards, but were developed to suit the needs of
ABPP framework and do not necessarily conform to the standards.
The X-Path functions for ABPP are classified into six categories based on the type of
operation:
| Node-set
| String
| Number
| Boolean
| Arithmetic
| Comparison
| Time
| Miscellaneous
| Java
Each of these classes of function is discussed in detail in the later sections of the
chapter.
X-Path Basics
The following is the general form of X-Path expression:
"$variableName/childNodeName[where expression]/childNodeName"
'$' is essential to refer variables when X-Path is used.
The following are a few examples to understand how X-Path works.

Example 1:
Assume that the variable 'coDoc' points to the following XML document:
<CUSTOMER_ORDER>
<ID Value="CO-1"/>
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>

X-Path Basics
<GRP_MEMBER Value="no"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-3"/>
<ITEM_ID Value="KEYBOARD"/>
<QTY Value="100"/>
<GRP_MEMBER Value="yes"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
Each of the following sub-sections contains an example of how X-Path can be used to
address different parts of coDoc.
Selecting a node
To select the ID node in coDoc,
Input:
<SET Var="res2" FromValue="{$coDoc/ID}"/>
<PRINT Value="{$res2}"/>
Output:
<ID Value="CO-1" />
Selecting the value of a node

To select the value of the ÌD' node in coDoc -
Input:
<SET Var="res3" FromValue="{$coDoc/ID/@Value}"/>
Output:
CO-1
Selecting a list of nodes

To select the list of line item nodes (ORDER_LINE_ITEM )
Input:

Chapter 6 X-Path
<SET Var="res4" FromSelectList="$coDoc/ORDER_LINE_ITEMS/

ORDER_LINE_ITEM"/>
Output:
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-3"/>
<QTY Value="100"/>
</ORDER_LINE_ITEM>
If the X-Path expression in "FromValue" evaluates to a List then the first object in the
List is returned.
Input:
<SET Var="res4" FromValue="{$coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM}"/>
Output:
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>

X-Path Basics
<QTY Value="350"/>
</ORDER_LINE_ITEM>
Selecting a list of nodes based on a condition

The following examples illustrates how you can select the list of
ORDER_LINE_ITEM nodes where value of GRP_MEMBER is `no'.
Example 1:
Input:
<SET Var="result" FromSelectList ="$coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM[GRP_MEMBER/@Value ='no']"/>
<PRINT Value="{$result}"/>
Output:
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
Example 2:
The following is an example to select ORDER_LINE_ITEM nodes where value of
ITEM_ID is ` MONITOR '
Input:
<SET Var="res6" FromValue="{$coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM[ITEM_ID/@Value ='MONITOR']}"/>

Chapter 6 X-Path
Output:
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
Support for xml with namespaces

The ABPP framework allows the user to receive, construct and return namespaced
xml. When manipulating such namespaced xml using rules the framework does not
use the namespace prefix or uri to query the xml tags. But the prefix is used for
quering xml tag attributes.
Assume that the variable èboDoc' points to the following XML document
<ebo:EBO xmlns:ebo="http://service.i2.com/schemas/PartyEBO">
<ebo:ESBHeader>
<ebo:EnvironmentName ebo:firstAttr="abc" ebo:secondAttr="xyz"/>
</ebo:ESBHeader>
</ebo:EBO>
To select the EnvironmentNode node in eboDoc:

Input:
<SET Var="res2" FromValue="{$eboDoc/ESBHeader/
EnvironmentName}"/>
Output:
<ebo:EnvironmentName ebo:firstAttr="abc" ebo:secondAttr="xyz"/>
Note that to find ESBHeader tag in $eboDoc you did not have to use ebo:ESBHeader.
Similarly you did not have to write ebo:EnvironmentName. Do not use prefix for xml
tags in the xpath expressions.
To select the firstAttr attribute of EnvironmentName tag:

Input:

Boolean X-Path Expressions
<SET Var=”res2” FromValue=”{$eboDoc/ESBHeader/EnvironmentName/

@ebo.firstAttr}”/>
<PRINT Value=”{$res2}”/>
Output:
abc
Note that to search for firstAttr attribute you have to use @ebo.firstAttr because the
xml has ‘ebo’ prefix for the attribute.
Boolean X-Path Expressions

A Boolean X-Path Expressions is a concise way to express a condition within
statement in XRules. It should be used within the test clause of an IF_TEST statement.
The following is the format of an X-Path expression that evaluates to Boolean:
LHS Operator RHS
Here, LHS and RHS are operands or X-Path expressions
The Valid Operand values are:
z Null
z Number Literal, for example:10, 23.5
z String Literal, for example: 'True', 'CO-1'
Valid Operators are:
z EQUAL: '='
z NOT_EQUAL: '!='
z AND: 'and'
z OR: 'or'
The following operators work only on numbers and dates:
z GREATER: '>'
z GREATER_EQUAL: '>='
z LESS: '<'
z LESS_EQUAL: '<='
Valid X-Path Expressions are of the form:
"$variableName/childNodeName[where expression]/childNodeName/
@Value"
For example, $thisParam/RESULT/@Value
Assume that the variable 'coDoc' points to the following XML document:
<CUSTOMER_ORDER>
<ID Value="CO-1"/>

Chapter 6 X-Path
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-3"/>
<QTY Value="100"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
Example 1:
The following example illustrates that, when a variable is assigned a boolean
expression that evaluates to true, the value of the variable is also set to true.
Input:
<SET Var="res1" FromValue="{$coDoc/ID/@Value = 'CO-1'}"/>
Output:
true
Example 2:
The following example illustrates that, when a Boolean condition in a if-test evaluates
to true, the conditional statements are executed.
Input:
<IF_TEST Test="$coDoc/ID/@Value = 'CO-1'">
<THEN>
<PRINT Value="Found CO"/>
</THEN>
</IF_TEST>
Output:

Mathematical X-Path Expressions
Found CO
Mathematical X-Path Expressions

The mathematical X-Path expressions provide a concise way of performing
mathematical operations like addition, subtraction etc. The result of a mathematical
X-Path expression is a numeric value. The format of these expressions are:
LHS Operator RHS
Here, LHS and RHS are operands or X-Path expressions
The Valid Operand values are:
z Number Literal, for example:10, 23.5
Valid Operators are:
z ADD: '+'
z SUB: '-'
z MUL: 'mul'
z DIV: 'div'
z MOD: 'mod'
Valid X-Path Expressions are of the form:
"$variableName/childNodeName[where expression]/childNodeName/
@Value"
For example, $thisParam/RESULT/@Value.
The X-Path expressions used here should evaluate to a numeric
value or a String that can be parsed as a number.
Example 1:
The following example illustrates use of ‘+’:
Input:
<SET Var="x" FromValue="120.4"/>
<SET Var="y" FromValue="{$x + 10.5}"/>
Output:
Value of variable 'y' will be:
130.9
Example 2:
The following example illustrates use of ‘mul’:
Input:
<SET Var="x" FromValue="10"/>
<PRINTLN Value="{int($x mul 12)}"/>

Chapter 6 X-Path
Output:
120
Example 3:
The following example illustrates use of ‘mod’:
Input:
<PRINTLN Value="{15 mod 2}"/>
Output:
1
Node-Set Functions
This section deals with the following Node-Set functions.
z position
z count
z name
For all the examples given for the various functions, assume the variable `coDoc'
points to the following sample document:
Sample Document:
<CUSTOMER_ORDER>
<ID Value="CO-1"/>
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-3"/>
<QTY Value="100"/>

Node-Set Functions
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
position
Syntax: position()
Return Type: number
Description: The position function can be used within where expression (enclosed in
[]) of an X-Path expression. It returns the position of the current element being
evaluated. This function will return 1 for the first element and so on.
Example :
Input:
<PRINTLN Value="{$coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM[position() > 1]}"/>
Output:
[<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>, <ORDER_LINE_ITEM>
<ID Value="LI-3"/>
<QTY Value="100"/>
</ORDER_LINE_ITEM>]
count
Syntax: count(X-path expression)
Return Type: number
Description: The count function is a node-set function that returns the number of
nodes (or tags) in the argument.
Example :
Input:
<PRINTLN Value="{count($coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM)}"/>
Output:
3

Chapter 6 X-Path
name
Syntax: name(X-path expression)
Return Type: string
Description: The name function is a node set function that returns the name of the root
tag of a document. In case the argument X-path expression refers to a node-set, the
function returns a string that represents the expanded-name of the node, in the
argument node-set, that is first in the document order.
Example :
Input:
<PRINTLN Value="{name($coDoc)}"/>
Output:
CUSTOMER_ORDER
String Functions
This section contains the following String functions.
z string
z concat
z strlen
z starts-with
z subString
z substringBefore
z substringAfter
z normalize-space
z trim
z upperCase
z lowerCase
z contains
z containsToken
z stringTokenToXml
Sample Document:
<CUSTOMER_ORDER>
<ID Value="CO-1"/>
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>

String Functions
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-3"/>
<QTY Value="100"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
<CUSTOMER_ORDER>
string
Syntax: string(X-Path expression)
Return Type: string
Description: The string function converts an object to a string as follows:
A node-set is converted to a string by returning the string-value of the node in the
node-set that is first in document order. If the node-set is empty, an empty string is
returned.
A number is converted to a string as follows:
z NaN is converted to the string NaN
z Positive zero is converted to the string 0
z Negative zero is converted to the string 0

Chapter 6 X-Path
z Positive infinity is converted to the string Infinity

z Negative infinity is converted to the string -Infinity
z Integer - Represented in decimal form as a number with no decimal point and no
leading zeros; preceded by a minus sign (-) if the number is negative.
z Decimal - Represented in decimal form as a number including a decimal point
with at least one digit before the decimal point and at least one digit after the
decimal point; preceded by a minus sign (-) if the number is negative.
z The boolean false value is converted to the string false . The boolean true value is
converted to the string true .
z An object of a type other than the four basic types (node-set, string, number,
boolean) is converted to a string in a way that is dependent on that type.
Example :
Input:
<PRINTLN Value="{string($coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM[ID/@Value = 'LI-1']/ PRICE/@Value)}"/>
Output:
103.58
concat
Syntax: concat(X-Path expression, X-Path expression)
Return Type: string
Description: The concat function is a string function that returns the concatenation of
its arguments.
Example :
Input:
<PRINTLN Value="{concat('Variable coDoc is ', name($coDoc) ,'
with ID: ',$coDoc/ID/@Value)}"/>
Output:
Variable coDoc is CUSTOMER_ORDER with ID: CO-1
strlen
Syntax: strlen(X-Path expression)
Return Type: number
Description: The strlen function is a string function that returns the number of
characters in the string. If the argument is omitted, it defaults to the context node
converted to a string, in other words the string-value of the context node.
Example :
Input:
<PRINTLN Value="{strlen('abcde')}"/>

String Functions
Output:
5
starts-with
Syntax: starts-with(contains string, substring)
Return Type: boolean
Description: The starts-with function is a string function that returns true if the first
argument string starts with the second argument string, otherwise returns false.
Example :
Input:
<PRINTLN Value="{starts-with(name($coDoc),'CO')}" />
Output:
false
subString
Syntax: subString(sourceString, beginIndex, endIndex)
Return Type: string
Description: The subString function is a string function that returns a portion of the
source string which is a subset of the sourceString. The substring begins at index
=beginIndex and extends to the character at index =endIndex -1. The indexs are zero
based, i.e. first character is index 0. The endIndex is optional argument; if not
specified, then a substring beginning at beginIndex is returned.
Example :
Input:
<PRINTLN Value="{subString('12345',0,3)}"/>
Output:
123
substringBefore
Syntax: substringBefore(sourceString, delimiter)
Return Type: string
Description: The substringBefore function is a string function that returns a portion of
the source string which occurs before the delimiter.
Example :
Input:
<PRINTLN Value="{substringBefore('12/15/2002 12:00:00:000', '
')}" />
Output:

Chapter 6 X-Path
12/15/2002
substringAfter
Syntax: substringAfter(sourceString, delimiter)
Return Type: string
Description: The substringAfter function is a string function that returns a portion of
the sourceString which occurs after the delimiter.
Example :
Input:
<PRINTLN Value="{substringAfter('12/15/2002 12:00:00:000', '
')}" />
Output:
12:00:00:000
normalize-space
Syntax: normalize-space(sourceString)
Return Type: string
Description: The normalize-space function is a string function that returns a string
with leading and trailing whitespace removed. Any sequence of whitespace characters
is replaced with a single space.
Example :
Input:
<PRINTLN Value="{normalize-space(' The quick brown fox
')}" />
Output:
'The quick brown fox'
trim
Syntax: trim(sourceString)
Return Type: string
Description: The trim function is a string function that returns a string which is
trimmed for whitespaces on the left as well as right only. The whitespaces occurring
between characters are left untouched.
Example :
Input:
<PRINTLN Value="{trim(' The quick brown fox ')}" />
Output:
'The quick brown fox'

String Functions
upperCase
Syntax: upperCase(X-Path expression)
Description: The upperCase function is a string function that changes the case of the
string value passed as argument to upper case; it is most useful when performing case
insensitive search.
Example1:
Input:
<PRINTLN Value="Upper Case: {upperCase('abc')}"/>
Output:
Upper Case: ABC
Example2:
Input:
<SET Var="temp" FromValue="hello World"/>
<PRINTLN Value="Upper Case: {upperCase($temp)}"/>
Output:
Upper Case: HELLO WORLD
lowerCase
Syntax:lowerCase(X-Path expression)
Description: The lowerCase function is a string function that changes the case of the
string value passed as argument to lower case; it is most useful when performing case
insensitive search.
Example:
Input:
<PRINTLN Value="Lower Case: {lowerCase('ABCDEFGH')}"/>
Output:
Lower Case: abcdefgh
Example:
Input:
<SET Var="temp" FromValue="HELLO WORLD"/>
<PRINTLN Value="Lower Case: {lowerCase($temp)}"/>
Output:
Upper Case: hello world
contains
Syntax:contains(containingString, subString)

Chapter 6 X-Path
Description: The contains function is a string function that returns true if the
containingString contains substring, else it returns false.
Example:
Input:
<PRINTLN Value="{contains('ORDER_ADMIN','ORDER')}"/>
Output:
True
containsToken
Syntax:containsToken(containingString, substring, token)
Description: The containsToken function is a string function that returns true if the
containingString contains a token that equals substring, else it returns false.
Example:
Input:
<PRINTLN Value="
{containsToken('ORDER_ADMIN|FMX|CPM|IMX','ORDER_ADMIN', '|')}"/
>
Output:
True
stringTokenToXml
Syntax:stringTokenToXml(someString, delimiters)
Description: The stringTokenToXml function is a string function that returns an XML
of all the tokens in a string. The characters in delimiters argument are the delimiters
for separating tokens.
Example:
Input:
<PRINTLN Value=" {stringTokenToXml('ORDER_ADMIN|FMX|CPM|IMX',
'|')}"/>
Output:
<TOKENS>
<TOKEN Value="ORDER_ADMIN"/>
<TOKEN Value="FMX"/>
<TOKEN Value="CPM"/>
<TOKEN Value="IMX"/>
</TOKENS>

Boolean Functions
Boolean Functions
This section illustrates the following Boolean functions.
z true()
z false()
true()
Syntax: true()
Description: The true() function is a boolean function that returns the string true .
Example :
Input:
<PRINTLN Value="{true()}" />
Output:
true
false()
Syntax: false()
Description: The false() function is a boolean function that returns the string false .
Example :
Input:
<PRINTLN Value="{false()}" />
Output:
false
boolean
Syntax: boolean(X-Path expression1, X-Path expression2)
Description: This function returns the boolean equivalent of the value evaluated to by
the first argument. If the first argument evaluates to null, the value of X-Path
expression2 is returned.
Example :
Assuming someVar='true'
Input:
<PRINTLN Value="{boolean($someVar, true())}" />
Output:

Chapter 6 X-Path
true
Number Functions
This section illustrates the following Number functions.
z int
z float
z double
z absolute
z minDouble
z maxDouble
z sum
Sample Document:
<CUSTOMER_ORDER>
<ID Value="CO-1"/>
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-3"/>

Number Functions
<QTY Value="100"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
<CUSTOMER_ORDER>
int
Syntax: int(X-Path expression)
Return Type: number
Description: The int function is a number function that returns the integer value of the
argument.
Example :
Input:
<PRINTLN Value="{int($coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM[ID/@Value = 'LI-1']/PRICE/@Value)}" />
Output:
103
float
Syntax: float(X-Path expression)
Return Type: number
Description: The float function is a number function that returns the floating-point
value of the argument.
Example :
Input:
<PRINTLN Value="{float($coDoc/ORDER_LINE_ITEMS/
Output:
103.58
double
Syntax: double(X-Path expression)
Return Type: number
Description: The double function is a number function that returns the double value of
the argument.
Example :

Chapter 6 X-Path
Input:
<PRINTLN Value="{double($coDoc/ORDER_LINE_ITEMS/
Output:
103.58
absolute
Syntax: absolute(X-Path expression)
Return Type: number
Description: The absolute function is a number function that returns the absolute
value of the number evaluated by the X-Path expression. The data types supported for
the argument of this function are Integer, Float and Double.
Example :
Assume someNumber = -11.0
Input:
<PRINTLN Value="{absolute($someNumber)}"/>
Output:
11.0
minDouble
Syntax: minDouble(X-Path expression1, X-Path expression2…)
Return Type: double
Description: The minDouble function is a number function that returns the minimum
of all the doubles that are passed to the function. All the arguments need to evaluate to
double value, or an exception is thrown.
Example :
Assuming a=1.0, b=2.0, c=3.0
Input:
<PRINTLN Value="{minDouble($a, $b, $c)}"/>
Output:
1.0
maxDouble
Syntax: maxDouble(X-Path expression1, X-Path expression2…)
Return Type: double
Description: The maxDouble function is a number function that returns the maximum
of all the doubles that are passed to the function. All the arguments need to evaluate to
double value, or an exception is thrown.

Arithmetic Functions
Example :
Assuming a=1.0, b=2.0, c=3.0
Input:
<PRINTLN Value="{maxDouble($a, $b, $c)}"/>
Output:
3.0
sum
Syntax: sum(X-Path expression)
Return Type: number
Description: The sum function is a number function that returns the sum for each
node in the argument X-Path expression (node-set). If the argument contains string
values, then these are converted to numbers first.
Example :
Input:
<PRINTLN Value="{sum($coDoc/ORDER_LINE_ITEMS/ORDER_LINE_ITEM/
QTY/@Value)}"/>
Output:
650.0
This section illustrates the following Arithmetic functions.
z +
z -
z mul
z div
z mod
z ceiling
z floor
z power
z roundWithPrecision
ABPP uses the BODMAS rule for evaluating expressions containing more than one
arithmetic operator.
+
Syntax: X-Path expression1 + X-Path expression2
Description: This function performs the arithmetic addition operation.

Chapter 6 X-Path
Example :
Assuming variables: myLhs = 13, and myRhs = 3
Input:
<Print Value="{$myLhs + $myRhs}"/>
Output:
16
-
Syntax: X-Path expression1 - X-Path expression2
Description: This function performs the arithmetic subtraction operation.
Example :
Input:
<Print Value="{$myLhs - $myRhs}"/>
Output:
10
mul
Syntax: X-Path expression1 mul X-Path expression2
Description: This function performs the arithmetic multiplication operation.
Example :
Input:
<Print Value="{$myLhs mul $myRhs}"/>
Output:
39
div
Syntax: X-Path expression1 div X-Path expression2
Description: This function performs the arithmetic division operation.
Example :
Input:
<Print Value="{$myLhs div $myRhs}"/>
Output:
4.3333335

mod
Syntax: X-Path expression1 mod X-Path expression2
Description: This function performs the arithmetic modulus operation.
Example:
Input:
<Print Value="{$myLhs mod $myRhs}"/>
Output:
1
ceiling
Syntax: ceiling(X-Path expression)
Description: This function returns the ceiling of the value evaluated to by the X-Path
expression.
Example:
Assuming variables: num = 13.4
Input:
<Print Value="{ceiling($num)}"/>
Output:
14.0
floor
Syntax: floor(X-Path expression)
Description: This function returns the floor of the value evaluated to by the X-Path
expression.
Example:
Assuming variables: num = 13.4
Input:
<Print Value="{floor($num)}"/>
Output:
13.0
power
Syntax: power(X-Path expression1, X-Path expression2)
Description: This function returns value of X-Path expression1 to the power of X-
Path expression2.

Chapter 6 X-Path
Example:
Assuming variables: a = 2, b=3
Input:
<PRINTLN Value="{power($a, $b)}"/>
Output:
8
roundWithPrecision
Syntax: roundWithPrecision(X-Path expression1, X-Path
expression2)
Description: This function returns value of X-Path expression1 rounded to number of
digits (right of decimal point) specified by X-Path expression 2. The response will be
of type ‘double’.
Example:
Assuming variables: a = 10.6158, b=2
Input:
<PRINTLN Value="{roundWithPrecision($a, $b)}"/>
Output:
10.62
Comparison Functions
This section illustrates the following comparison functions.
z <
z >
z <=
z >=
z =
z !=
z and
z or
z stateCompare
<
Syntax: X-Path expression1 < X-Path expression2

Description: This function performs the arithmetic lesser-than operation. It can be

used in a comparison statement.
Example:
Assuming variables: a = 3, and b = 13
Input:
<IF_TEST Test="$a < $b">
<THEN>
<Print Value="lesser than works!"/>
</THEN>
</IF_TEST>
Output:
lesser than works!
>
Syntax: X-Path expression1 > X-Path expression2
Description: This function performs the arithmetic greater-than operation. It can be
Example:
Input:
<IF_TEST Test="$b > $a">
<THEN>
<Print Value="greater than works!"/>
</THEN>
</IF_TEST>
Output:
greater than works!
<=
Syntax: X-Path expression1 <= X-Path expression2
Description: This function performs the arithmetic lesser-than-or-equal-to operation.
It can be used in a comparison statement.
Example:
Assuming variables: a = 5, c = 2, and d = 3
Input:
<IF_TEST Test="($d + $c) <= $a">

Chapter 6 X-Path
<THEN>
<PRINT Value="lesser than or equal to works!"/>
</THEN>
</IF_TEST>
Output:
Lesser than or equal to works!
>=
Syntax: X-Path expression1 >= X-Path expression2
Description: This function performs the arithmetic greater-than-or-equal-to operation.
It can be used in a comparison statement.
Example:
Assuming variables: a = 5, b = 11
Input:
<IF_TEST Test="$b >= ($a mul 2)">
<THEN>
<PRINT Value="greater than or equal to works!"/>
</THEN>
</IF_TEST>
Output:
greater than or equal to works!
=
Syntax: X-Path expression1 = X-Path expression2
Description: This function performs the arithmetic equals operation. It can be used in
a comparison statement.
Example:
Input:
<IF_TEST Test="$a = $b">
<THEN>
<Print Value="equal works!"/>
</THEN>
</IF_TEST>
Output:
Equal works!

!=
Syntax: X-Path expression1 != X-Path expression2
Description: This function performs the arithmetic not-equals operation. It can be
Example:
Input:
<IF_TEST Test="$a != $b">
<THEN>
<Print Value="not-equal works!"/>
</THEN>
</IF_TEST>
Output:
Not-equal works!
and
Syntax: X-Path expression1 and X-Path expression2
Description: This function performs the 'and' operation. It can be used in a
comparison statement.
Example:
Assuming variables: a = 5, b = 11, c = 2, d = 8
Input:
<IF_TEST Test="$a < $b and $d > $c">
<THEN>
<PRINT Value="And works!"/>
</THEN>
</IF_TEST>
Output:
And works!
or
Syntax: X-Path expression1 != X-Path expression2
Description: This function performs the 'or' operation. It can be used in a comparison
statement.
Example:
Assuming variables: a = 5, b = 11, c = 2, d = 8
Input:

Chapter 6 X-Path
<IF_TEST Test="$b < $a or $d > $c">

<THEN>
<PRINT Value="Or works!"/>
</THEN>
</IF_TEST>
Output:
Or works!
stateCompare
Syntax: stateCompare(Name of state document, state 1, state 2)
Description: This function compares two states of a state document and return-1 if
state1 is less than state2, 0 if the two states are equal and 1 if state1 is greater than
state2.
Example:
Input:
<IF_TEST Test="stateCompare('ORDER_LINE_ITEM', 'ACCEPTED',
'DRAFT')">
<THEN>
<PRINT Value="ACCEPTED is greater than DRAFT"/>
</THEN>
</IF_TEST>
Output:
ACCEPTED is greater than DRAFT
XMLform & Core Functions

This section illustrates the following XMLform functions.
z text
z getId
z sort
z collate
z clone
z transform
z docMinus
z docDiff
z ifElse
z stringToXml
z listGet

z listUnion
z findProp
text
Syntax: text(X-Path expression)
Description: This function returns the text value of the XMLform that the X-Path
expression evaluates to, else it returns null.
Example:
Assuming variables: a referred to
<SOME_XML>some text</SOME_XML>
Input:
<PRINTLN Value="{text($a)}"/>
Output:
Some text
getId
Syntax: getId(documentNameExpr, subTypeExpr)
Description: This function returns the unique id given a document and subtype. The
second parameter, subType, is optional.
Example:
Input:
<PRINTLN Value="Purchase Order - {getId('ACTIVITY_ORDER',
'PURCHASE_ORDER')}"/>
<PRINTLN Value=" Transfer Order - {getId('ACTIVITY_ORDER',
'TRANSFER_ORDER')}"/>
Output:
Purchase Order - P1
Transfer Order - T2
sort
Syntax: sort(someXmlForm list, prop1, Ascending1|Descending1,
prop2,Ascending2|Descending2,..)
Description: This function sorts the list of XMLform objects based on the values of
the properties, in the order specified, passed to the function.
Example:
Input:
<SET Var="sortedList" FromValue="{sort($coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM, 'QTY','Ascending')}"/>

Chapter 6 X-Path
Output:
The above statement results in a list with the order line items sorted by QTY in
ascending order.
collate
Syntax: collate(X-PathExpression evaluating to a XMLform)
Description: This function gathers data from the input that is passed to it and returns a
structured XMLform. In the example below, INPUT and COLLATE_LIST children
are required. The name of the return element (ITEM in the example below) is also
required.
Example:
<TO_DOCVAR AssignToVar="collateVar">
<ROOT>
<INPUT>
<TO_XML SelectList="$pglFormOutput/*"/>
</INPUT>
<COLLATE_LIST Value="ITEM">
<ID/>
<ITEM_ID/>
<ITEM_DESCRIPTION/>
</COLLATE_LIST>
</ROOT>
</TO_DOCVAR>
<SET Var="items" FromValue="{collate($collateVar)}"/>
Output:
<ITEM_LIST>
<ITEM>
<ID Value="1"/>
<ITEM_ID Value="Item1">
<ITEM_DESCRIPTION Value="Item-1">
</ITEM>
<ITEM>
<ID Value="2"/>
<ITEM_ID Value="Item2">
<ITEM_DESCRIPTION Value="Item-2">
</ITEM>
……

</ITEM_LIST>
clone
Syntax: clone(X-PathExpression evaluating to a XMLform)
Description: This function clones the XMLform passed to it and returns it. Only
XMLform data type is supported today.
Example:
Input:
<SET Var="cloneXML" FromValue="{clone($originalXML)}"/>
Output:
cloneXML is set to the cloned XMLform.
transform
Syntax: transform(X-Path expression1 evaluating to a String, X-Path expression2
evaluating to a list)
Description: This function performs a shallow clone of the XMLform objects in the
list passed as the second argument and changes their name to the string evaluated to
by the first argument. A shallow clone does not clone the children of the XMLform.
Example:
Assume originalXML to be
<ROOT>
<CHILD Attr1="x1">
<PROP1 Value="y1"/>
</CHILD>
<CHILD Attr1="x2">
<PROP1 Value="y2"/>
</CHILD>
<CHILD Attr1="x3">
<PROP1 Value="y3"/>
</CHILD>
</ROOT>
Input:
<SET Var="transformedXML" FromValue="transform('NEW_CHILD',
$originalXML/CHILD)"/>
Output:
A list containing the following XMLform objects
<NEW_CHILD Attr1="x1">
<PROP1 Value="y1"/>

Chapter 6 X-Path
</NEW_CHILD>
<PROP1 Value="y2"/>
</NEW_CHILD>
<PROP1 Value="y3"/>
</NEW_CHILD>
docMinus
Syntax: docMinus(X-Path Expression1, X-Path Expression2)
Description: This function performs diff between both the documents that X-Path
expressions evaluate to. Both the documents need to be defined as XCore documents
in the service this function is being executed. It returns an xml document with the
differences.
Example 1:
Assuming variables: doc1=
<ORDER_SCHEDULE ExistingDocument="yes">
<ID Value="207"/>
<AO_ID Value="P202"/>
<ASSEMBLY_LINE Value="asem-line1"/>
<AVAILABLE_DATE Value="05/05/2004 00:00:00:000"/>
<BILL_TO_ID Value="Velocity-BT1"/>
<BILL_TO_NAME Value="Velocity-BT1NAME"/>
</ORDER_SCHEDULE>
doc2=
<ID Value="207"/>
</ORDER_SCHEDULE>
Input:
<SET Var="updateProps" FromValue="{docMinus($doc2, $doc1)}"/>
Output:
updateProps variable would contain
<UPDATE_PROPERTIES>
<ASSEMBLY_LINE value="assem-line2"/>
Example 2:

In this example, the variable doc2 does not have the BILL_TO_ID child, and yet the
result is the same.
<ID Value="207"/>
</ORDER_SCHEDULE>
doc2=
<ID Value="207"/>
</ORDER_SCHEDULE>
Input:
<SET Var="updateProps" FromValue="{docMinus($doc2, $doc1)}"/>
Output:
updateProps would contain
<UPDATE_PROPERTIES>
As seen in this example docMinus() returns all properties of $doc2 (that have Value
attribute defined) that are different than those given in $doc1.
docDiff
Syntax: docDiff(X-Path Expression1, X-Path Expression2)
Description: This function performs diff between both the documents that X-Path
expressions evaluate to. Both the documents need to be defined as XCore documents
in the service this function is being executed. It returns an xml document with the
differences. This function is slightly different from the one above since it considers all
changes as shown below.
Example:
In this example, the variable doc2 does not have a value for BILL_TO_ID.
<ID Value="207"/>

Chapter 6 X-Path
</ORDER_SCHEDULE>
doc2=
<ID Value="207"/>
<BILL_TO_ID/>
</ORDER_SCHEDULE>
Input:
<SET Var="updateProps" FromValue="{docDiff($doc2, $doc1)}"/>
Output:
updateProps would contain
<UPDATE_PROPERTIES>
<BILL_TO_ID/>
As seen in this example docDiff() returns all properties of $doc2 (with or without
Value attribute defined) that are different than those given in $doc1.
ifElse
Syntax: ifElse(X-Path Condition expression, X-Path true expression, X-Path false
expression)
Description: This function id similar to a if-then-else statement. If the first X-Path
condition expression evaluates to true X-Path true expression is returned, else X-Path
false expression is returned.
Example:
Assuming variables: a = 5
Input:
<PRINTLN Value="{ifElse($a=5,1,0)"/>
Output:
1
stringToXml
Syntax: stringToXml(X-Path Expression evaluating to a string)
Description: This function transforms a valid xml string into a xml document. It
returns an XMLform.

Example:
Assuming variable str=<SOME_TAG><SOME_CHILD Value="test"/></
SOME_TAG>
Input:
<PRINT Value="{stringToXml($str)}"/>
OutPut:
<SOME_TAG>
<SOME_CHILD Value="test"/>
</SOME_TAG>
listGet
Syntax: listGet(X-Path Expression evaluating to an XMLList, X-Path Expression
evaluating to an integer)
Description: This function returns the nth (where n is the value that the second
parameter evaluates to) element from the list that the first parameter in the function
call evaluates to.
Example:
Input:
<PRINT Value="{listGet($orderLineItems, 1)}"/>
OutPut:
Prints the first element from the list orderLineItems.
listUnion
Syntax: listUnion(X-Path Expression1, X-Path Expression2, X-Path Expression3, X-
Path Expression4….)
Description: This function returns a list of all the elements passed to it. If any if the
parameters passed to it is a list, all the elements of the list get added to the list that is
returned.
Example:
Input:
<SET VAr="list" Value="{listUnion($oli1, $oli2, $oli3)}"/>
Output:
List containing oli1, oli2, and oli3
findProp
Syntax: findProp(X-PathExpression evaluating to an XMLform, X-Path Expression
evaluating to a string)

Chapter 6 X-Path
Description: This function returns the first matching property of the XMLform. It
expects the XMLform as the first parameter and the property name as the second one.
Example:
Input:
<TO_DOCVAR AssignToVar="root">
<ROOT>
<CHILD1 Value="c1"/>
<CHILD2 Value="c2"/>
</ROOT>
</TO_DOCVAR>
<SET Var="x" FromValue="{findProp($root,'CHILD2')}"/>
<SET Var="x1" FromValue="{findProp($root,'CHILD1')}"/>
<SET Var="x2" FromValue="{findProp($root,name($x))}"/>
<PRINTLN Value="x1: {$x1}"/>

<PRINTLN Value="x2: {$x2}"/>
Output:
x1: <CHILD1 Value="c1"/>
x2: <CHILD2 Value="c2"/>
key
Syntax: key(X-Path Expression1, X-Path Expression2, X-Path Expression3, X-Path
Expression4….)
Description: This function is used in conjunction with the map related action
components. It is used to calculate key of an xml data element based on properties of
the element. The parameters to this function are the properties of the element that form
its key. This function returns a special java object that maintains individual parts of the
key and can be used in map related action components.
Example:
Refer to MAP_CREATE rule action component for an example.
mapGet
Syntax: mapGet(X-Path expression referring to a map object created by using
MAP_CREATE, X-Path expression that evaluates to a map key by using the key fn)

Description: This function return a list of xml data elements from the specified map
whose key matches the specified key.
Example:
Assuming variables:
data:
<DATA>
<CARS>
<CAR>
<VIN Value="1"/>
</CAR>
<CAR>
<VIN Value="2"/>
</CAR>
<CAR>
<VIN Value="3"/>
</CAR>
</CARS>
</DATA>
Input:
>
<SET Var="toyota2006" FromValue="{mapGet($carMap,
key('Toyota','2006'))}"/>
<PRINTLN Value="{$toyota2006}"/>
Output:
<LIST>
<CAR>
<VIN Value="1"/>
</CAR>
<CAR>
<VIN Value="2"/>
</CAR>
</LIST>

Chapter 6 X-Path
mapContainsKey
Syntax: mapContainsKey(X-Path expression referring to a map object created by
using MAP_CREATE, X-Path expression that evaluates to a map key by using the key
fn)
Description: This function return true if the specified key is present in the given map
object, otherwise returns false.
Example:
Assuming variables:
data:
<DATA>
<CARS>
<CAR>
<VIN Value="1"/>
</CAR>
<CAR>
<VIN Value="2"/>
</CAR>
<CAR>
<VIN Value="3"/>
</CAR>
</CARS>
</DATA>
Input:
>
<PRINTLN Value="{mapContainsKey($carMap,
key('Toyota','2006'))}"/>
<PRINTLN Value="{mapContainsKey($carMap,
key('Toyota','2000'))}"/>
Output:
true
false
Time Functions
The following time related functions are available in ABPP:
z date

Time Functions
z getYear
z getMonth
z getDay
z getHour
z getMinute
z getSecond
z duration
z dstDuration
z incrDate
z datediff
z minDate
z maxDate
z stripTime
z incrDateByDays
z parseDate
date
The following functions are used for date related operations:
z See date()
z see date(‘string’)
z See date(year,month,day)
z See date(year, month, day, hour, minute, second)
date()
Syntax: date()
Return Type: date object
Description: The date() function is a date function that returns the current date with
current time stamp.
Example 1:
Input:
<PRINTLN Value="{date()}"/>
Output:
04/23/2002 15:12:36:983
date(‘string’)
Syntax: date(string in MM/dd/yyyy or MM/dd/yyyy HH:mm:ss format or

Chapter 6 X-Path
MM/dd/yyyy HH:mm:ss:SSS)
Description: The date() function converts the string argument in to a date object.The
valid date formats are: MM/dd/yyyy, MM/dd/yyyy HH:mm:ss and MM/dd/yyyy
HH:mm:ss:SSS.
Example 1:
Input:
<PRINTLN Value="{date('01/01/1970')}"/>
Output:
01/01/1970 00:00:00:000
Example 2:
Input:
<PRINTLN Value="{date('01/01/1970 10:30:52'))}"/>
Output:
01/01/1970 10:30:52:000
Example 3:
Input:
<PRINTLN Value="{date('01/01/1970 10:30:52:145'))}"/>
Output:
01/01/1970 10:30:52:145
date(year,month,day)
Syntax: date(year, month, day)
Description: This function returns the date for the given year, month and day. The
year. month and day values are specified as numbers. The system will try to convert
any non-number arguments (like string) in to numbers.
The year is typically a 4 digit number.
Valid values for Month are 0-11. Month value is 0-based. e.g., 0 for January.
Valid values for day are 1-31.
Example 1:
Input:
<PRINTLN Value="{date(2000, 2, 1)}" />
Output:

Time Functions
03/01/2000 00:00:00:000
Example 2:
In this example, the system will convert string arguments in to numbers.
Input:
<PRINTLN Value="{date('2000', '02', '01')}" />
Output:
03/01/2000 00:00:00:000
date(year, month, day, hour, minute, second)

Syntax: date(year, month, day, hour, minute, second)
Description: This function returns the date for the given year, month, day, hour,
minute and second. All the arguments are specified as numbers. The system will try to
convert any non-number arguments (like string) in to numbers.
The year is typically a 4 digit number. Here are the valid values for the other
arguments:
z month : 0-11. Month value is 0-based. e.g., 0 for January.
z day: 1-31.
z hour:0-23
z minute:0-59
z second:0-59
Example 1:
Input:
<PRINTLN Value="{date(2000, 02, 01, 12, 30, 5)}" />
Output:
03/01/2000 12:30:05:000
getYear
The following functions are used for year related operations:
z getYear()
z getYear(date-string)
z getYear(date-object)
getYear()
Syntax: getYear()
Return Type: string
Description: The getYear() function is a getYear function that returns the current year.

Chapter 6 X-Path
Example 1:
Input:
<PRINTLN Value="{getYear()}"/>
Output:
2002
getYear(date-string)
Syntax: getYear(date-string)
Return Type: string
Description: The getYear(date-string) function is a getYear function that returns the
year of the date string.
Example 1:
Input:
<PRINTLN Value="{getYear('12/12/2008')}" />
Output:
2008
getYear(date-object)
Syntax: getYear(date-object)
Return Type: string
Description: The getYear(date-object) function is a getYear function that returns the
year of the date object.
Example :
Input:
<PRINTLN Value="{getYear($dateVariable)}" />
Output:
2008
getMonth
The following functions are used for month related operations:
z getMonth()
z getMonth(date-string)
z getMonth(date-object)
getMonth()
Syntax: getMonth()
Return Type: string

Time Functions
Description: The getMonth() function is a getMonth function that returns the current
month.
Example :
Input:
<PRINTLN Value="{getMonth()}"/>
Output:
3
getMonth(date-string)
Syntax: getMonth(date-string)
Return Type: string
Description: The getMonth(date-string) function is a getMonth function that returns
the month of the date string.
Example :
Input:
<PRINTLN Value="{getMonth(`12/12/2008')}" />
Output:
12
getMonth(date-object)
Syntax: getMonth (date-object)
Return Type: string
Description: The getMonth(date-object) function is a getMonth function that returns
the month of the date object.
Example :
Input:
<PRINTLN Value="{getMonth($dateVariable)}" />
Output:
7
getDay
The following functions are used for day related operations:
z getDay()
z getDay(date-string)
z getDay(date-object)
getDay()
Syntax: getDay()

Chapter 6 X-Path
Return Type: string

Description: The getDay() function is a getDay function that returns the current day.
Example :
Input:
<PRINTLN Value="{getDay()}"/>
Output:
16
getDay(date-string)
Syntax: getDay(date-string)
Return Type: string
Description: The getDay(date-string) function is a getDay function that returns the
day of the date string.
Example :
Input:
<PRINTLN Value="{getDay(`12/23/2008')}" />
Output:
23
getDay(date-object)
Syntax: getDay (date-object)
Return Type: string
Description: The getDay(date-object) function is a getDay function that returns the
day of the date object.
Example :
Input:
<PRINTLN Value="{getDay($dateVariable)}" />
Output:
18
getHour
The following functions are used for hour related operations:
z getHour()
z getHour(date-string)
z getHour(date-object)
getHour()
Syntax: getHour()

Time Functions
Return Type: string

Description: The getHour() function is a getHour function that returns the current
hour
Example :
Input:
<PRINTLN Value="{getHour()}"/>
Output:
10
getHour(date-string)
Syntax: getHour(date-string)
Return Type: string
Description: The getHour(date-string) function is a getHour function that returns the
hour of the date string.
Example :
Input:
<PRINTLN Value="{getHour(`12/12/2008 3:26:05:02')}" />
Output:
3
getHour(date-object)
Syntax: getHour (date-object)
Return Type: string
Description: The getHour(date-object) function is a getHour function that returns the
hour of the date object.
Example :
Input:
<PRINTLN Value="{getHour($dateVariable)}" />
Output:
3
getMinute
The following functions are used for minute related operations:
z getMinute()
z getMinute(date-string)
z getMinute(date-object)

Chapter 6 X-Path
getMinute()
Syntax: getMinute()
Return Type: string
Description: The getMinute() function is a getMinute function that returns the current
minute.
Example :
Input:
<PRINTLN Value="{getMinute()}"/>
Output:
10
getMinute(date-string)
Syntax: getMinute (date-string)
Return Type: string
Description: The getMinute(date-string) function is a getMinute function that returns
the Minute of the date string.
Example :
Input:
<PRINTLN Value="{getMinute('12/12/2008 3:26:05:02')}" />
Output:
05
getMinute(date-object)
Syntax: getMinute (date-object)
Return Type: string
Description: The getMinute(date-object) function is a getMinute function that returns
the Minute of the date object.
Example :
Input:
<PRINTLN Value="{getMinute($dateVariable)}" />
Output:
05
getSecond
The following functions are used for second related operations:
z getSecond()
z getSecond(date-string)

Time Functions
z getSecond(date-object)
getSecond()
Syntax: getSecond()
Return Type: string
Description: The getSecond() function is a getSecond function that returns the current
second.
Example :
Input:
<PRINTLN Value="{getSecond()}"/>
Output:
10
getSecond(date-string)
Syntax: getSecond(date-string)
Return Type: string
Description: The getSecond(date-string) function is a getSecond function that returns
the second of the date string.
Example :
Input:
<PRINTLN Value="{getSecond(`12/12/2008 3:26:05:02')}" />
Output:
02
getSecond(date-object)
Syntax: getSecond (date-object)
Return Type: number
Description: The getSecond(date-object) function is a getSecond function that returns
the second of the date object.
Example :
Input:
<PRINTLN Value="{getSecond($dateVariable)}" />
Output:
03
duration
Syntax: duration(days, hours, minutes, seconds)
Return Type: number

Chapter 6 X-Path
Description: The duration function returns the number of seconds for the given
number of days, hours, minutes and seconds. This uses the fomula : total number of
seconds = days * 24 *3600 + hours * 3600 + minutes * 60 + seconds.
It assumes that a day is made of 24 hours. Hence it does not account for any DST
(Daylight Savings Time) corrections. The dstDuration function explained below can
be used to account for daylight saving time corrections.
Example:
Input:
<PRINTLN Value="{duration(0, 0, 1, 3)}" />
Output:
63
dstDuration
Syntax: dstDuration(days, hours, minutes, seconds)
Return Type: DstDuration object
Description: The dstDuration function returns a DstDuration object corresponding to
the given number of days, hours, minutes and seconds.The dstDuration object can be
used in other X-Path functions like incrDate to increment the date-time. Using the
dstDuration object will ensure that any applicable day light savings time (DST)
correction is applied while incrementing days component of the dstDuration object.
This function will convert all the args (days, hours, minutes and seconds) in to integers
before creating the dstDuration object. So any fractions will be ignored.
Example 1:
Input:
<SET Var="myDuration" FromValue="{dstDuration(2, 0, 0, 0)}" />
<PRINTLN Value="{incrDate(date('03/10/2007'), $myDuration)}"/>
Output:
03/12/2007 00:00:00:000
In the example above, We are adding 2 days to March 10th 2007. Let us assume that
the local time zone pertains to a region of US where Day Light Saving (DST) is used.
For 2007, the DST beings on March 11th. On March 11th the clocks advance from
1.59 AM directly to 3 AM. So effectively the day of March 11th will only have 23
hours.
Since dstDuration function accounts for DST, it will automatically increment only 23
hours for March 11th. It will increment 24 hours for March 10th since this time period
does not fall under DST. So in total the 2 days corresponded to an increment of 47
hours.
If we had used the duration function then it would have blindly incremented by 48
hours and the final output would have been, 03/12/2007 01:00:00:000.

Time Functions
The dstDuration function will yield a different result than duration function when the
date moves from a DST to a non-DST period or vice-versa because of the days
increment.
Example 2:
Input:
<SET Var="myDuration" FromValue="{dstDuration(2, 1, 0, 0)}" />
<PRINTLN Value="{incrDate(date('01/01/2007'), $myDuration)}"/>
Output:
01/03/2007 01:00:00:000
The days increment ( 2 days) considered in this example does not move the date from
a DST to non-DST period or vice-versa. So in this example, using dstDuration or
duration function will yield the same output.
incrDate
Syntax: incrDate(date, duration)
Description: The incrDate function returns a date, incrementing the given date by the
given duration. If a negative duration is given, then the date is decremented by that
value. The duration can be directly provided in seconds or a DstDuration object
created from dstDuration(...) X-Path function.
Example 1:
Input:
<PRINTLNValue="{incrDate('12/12/2002 12:00:00:000', duration(0,
0, 1, 3))}"/>
Output:
12/12/2002 12:01:03:000
Example 2:
Input:
<PRINTLN Value="{incrDate('12/12/2002 12:00:00:000',
duration(0, 0, 0, (-3)))}"/>
Output:
12/12/2002 11:59:57:000
Example 3:
Input:
<PRINTLN Value="{incrDate('12/12/2002 12:00:00:000',
dstDuration(1, 0, 0, 1))}"/>
Output:
12/13/2002 12:00:00:000

Chapter 6 X-Path
datediff
Syntax: datediff(date1, date2)
Return Type: number
Description: The datediff function returns the duration in seconds by taking the
difference: date1 - date2.
Example :
Input:
<PRINTLN Value="{dateDiff(`12/15/2002 12:00:00:000', `12/12/
2002')}" />
Output:
302400
minDate
Syntax: minDate(date1, date2, date3, …)
Return Type: date
Description: The minDate function returns the minmum of all the dates that are
passed to it. All the arguments that are passed to the function must evaluate to a date,
or an exception is thrown.
Example :
Assuming d1='01/01/2004', d2='01/01/2005', d3='01/01/2003'
Input:
<PRINTLN Value="{minDate($d1,$d2,$d3)}" />
Output:
01/01/2003
maxDate
Syntax: maxDate(date1, date2, date3, …)
Return Type: date
Description: The maxDate function returns the maximum of all the dates that are
passed to it. All the arguments that are passed to the function must evaluate to a date,
or an exception is thrown.
Example :
Assuming d1='01/01/2004', d2='01/01/2005', d3='01/01/2003'
Input:
<PRINTLN Value="{maxDate($d1,$d2,$d3)}" />
Output:

Time Functions
01/01/2005
stripTime
Syntax: stripTime(date1)
Return Type: date
Description: The stripTime function returns the date after removing any time portion
of it.
Example:
Input:
<PRINTLN Value="{stripTime(`12/15/2002 12:00:00')}" />
Output:
12/15/2002
formatDate
Syntax: formatDate(date1)
Return Type: string
Description: The formatDate function returns the date as string after formatting the
date in the format 'mm/dd/yyyy', removing any time portion of it. If no arguments are
passed, it returns the current date. It takes either a date or string as a parameter.
Example :
Input:
<PRINTLN Value="{formatDate(`12/30/2002 12:12:12')}" />
Output:
12/30/2002
formatNumber
Syntax: formatNumber(number, pattern)
Return Type: string
Parameters:
number: The number object (integer, long, float or double) that needs to be converted
to its string representation
pattern (Optional): The pattern to use for formatting. Following symbols can be used
to form the pattern.

Chapter 6 X-Path
Symbol Meaning
0 Digit
# Digit, zero shows as absent
. Decimal separator
, Grouping separator
E Separates mantissa and

exponent in scientific
notation
The default pattern will convert the number as is.

Description: The formatNumber function converts the specified number to its
corresponding string representation using the pattern specified.
Example:
Input:
<PRINTLN Value="Non-formatted number:
{double('123456789.1234')}"/>
<PRINTLN Value="Default formatted number:
{formatNumber(double('123456789.1234'))}"/>
<PRINTLN Value="Custom formatted number:
{formatNumber(double('123456789.1234'), '######,##0.##')}"/>
<PRINTLN Value="Custom formatted number:
{formatNumber(double('12.3'), '000.##')}"/>
Output:
Non-formatted number: 1.234567891234E8
Default formatted number: 123456789.1234
Custom formatted number: 123,456,789.12
Custom formatted number: 012.3
xsdDateStr
Syntax: xsdDateStr(date1)
Return Type: string
Description: This function returns the date as string in the Java simple date format
“yyyy-MM-dd'T'HH:mm:ss”. It takes a date as the input parameter.
Example :
Input:
<PRINTLN Value="{xsdDateStr(date())}" />
Output:

Java's SimpleDateFormat
2006-06-29T19:20:13
incrDateByDays
Syntax: incrDateByDays(date1, <expr>)
Return Type: date
Description: The incrDateByDays function returns the date after adding a certain
number of days (identified by the second parameter to the function).
Example:
Input:
<PRINTLN Value="{incrDateByDays('12/15/2002 12:00:00', '1')}" />
Output:
12/16/2002
parseDate
Syntax: parseDate(date1, format)
Return Type: string
Description: The parseDate function parses a string using a specified format and
returns a datetype in the standard date format.
Currently this will support date formats as supported by java's SimpleDateFormat
(See the section below for further information)
Example:
Input:
<SET Var="myDate" FromValue="01-Apr-2005"/>
<PRINTLN Value="Parse date using format dd-MMM-yyyy:
{parseDate($myDate,'dd-MMM-yyyy')}" />
Output:
04/01/2005 00:00:00:000
Date and Time Patterns
Date and time formats are specified by date and time pattern strings. Within date and
time pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted as
pattern letters representing the components of a date or time string. Text can be quoted
using single quotes (') to avoid interpretation. "''" represents a single quote. All other
characters are not interpreted; they're simply copied into the output string during
formatting or matched against the input string during parsing.

Chapter 6 X-Path
The following pattern letters are defined (all other characters from 'A' to 'Z' and from
'a' to 'z' are reserved):
Letter Date or Time Component Presentation Examples
G Era designator Text AD
y Year Year 1996; 96
M Month in year Month July; Jul; 07
w Week in year Number 27
W Week in month Number 2
D Day in year Number 189
d Day in month Number 10
F Day of week in month Number 2
E Day in week Text Tuesday; Tue
a Am/pm marker Text PM
H Hour in day (0-23) Number 0
k Hour in day (1-24) Number 24
K Hour in am/pm (0-11) Number 0
h Hour in am/pm (1-12) Number 12
m Minute in hour Number 30
s Second in minute Number 55
S Millisecond Number 978
z Time zone General time zone Pacific Standard Time; PST; GMT-08:00
Z Time zone RFC 822 time zone -0800
Pattern letters are usually repeated, as their number determines the exact presentation:
z Text: For formatting, if the number of pattern letters is 4 or more, the full form is
used; otherwise a short or abbreviated form is used if available. For parsing, both
forms are accepted, independent of the number of pattern letters.
z Number: For formatting, the number of pattern letters is the minimum number of
digits, and shorter numbers are zero-padded to this amount. For parsing, the
number of pattern letters is ignored unless it's needed to separate two adjacent
fields.
z Year: For formatting, if the number of pattern letters is 2, the year is truncated to
2 digits; otherwise it is interpreted as a number.
For parsing, if the number of pattern letters is more than 2, the year is interpreted
literally, regardless of the number of digits. So using the pattern "MM/dd/yyyy",
"01/11/12" parses to Jan 11, 12 A.D.

For parsing with the abbreviated year pattern ("y" or "yy"), SimpleDateFormat
must interpret the abbreviated year relative to some century. It does this by
adjusting dates to be within 80 years before and 20 years after the time the
SimpleDateFormat instance is created. For example, using a pattern of "MM/dd/
yy" and a SimpleDateFormat instance created on Jan 1, 1997, the string "01/11/
12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be
interpreted as May 4, 1964. During parsing, only strings consisting of exactly two
digits, as defined by Character.isDigit(char), will be parsed into the default
century. Any other numeric string, such as a one digit string, a three or more digit
string, or a two digit string that isn't all digits (for example, "-1"), is interpreted
literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2,
3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC.
z Month: If the number of pattern letters is 3 or more, the month is interpreted as
text; otherwise, it is interpreted as a number.
z General time zone: Time zones are interpreted as text if they have names. For
time zones representing a GMT offset value, the following syntax is used:
GMTOffsetTimeZone:
GMT Sign Hours : Minutes
Sign: one of
+ -
Hours:
Digit
Digit Digit
Minutes:
Digit Digit
Digit: one of
0 1 2 3 4 5 6 7 8 9
Hours must be between 0 and 23, and Minutes must be between 00 and 59. The format
is locale independent and digits must be taken from the Basic Latin block of the
Unicode standard.
For parsing, RFC 822 time zones are also accepted.
z RFC 822 time zone: For formatting, the RFC 822 4-digit time zone format is
used:
RFC822TimeZone:
Sign TwoDigitHours Minutes
TwoDigitHours:
Digit Digit
TwoDigitHours must be between 00 and 23. Other definitions are as for general time
zones.
For parsing, general time zones are also accepted.
SimpleDateFormat also supports localized date and time pattern strings. In these
strings, the pattern letters described above may be replaced with other, locale

Chapter 6 X-Path
dependent, pattern letters. SimpleDateFormat does not deal with the localization of
text other than the pattern letters; that's up to the client of the class.
Examples:
The following examples show how date and time patterns are interpreted in the U.S.
locale. The given date and time are 2001-07-04 12:08:56 local time in the U.S. Pacific
Time time zone.
Date and Time Pattern Result
"yyyy.MM.dd G 'at' HH:mm:ss z" 2001.07.04 AD at 12:08:56 PDT
"EEE, MMM d, ''yy" Wed, Jul 4, '01
"h:mm a" 2:08 PM
"hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time
"K:mm a, z" 0:08 PM, PDT
"yyyyy.MMMMM.dd GGG hh:mm aaa" 02001.July.04 AD 12:08 PM
"EEE, d MMM yyyy HH:mm:ss Z" Wed, 4 Jul 2001 12:08:56 -0700
"yyMMddHHmmssZ" 010704120856-0700
Miscellaneous Functions
This section illustrates the following miscellaneous functions.
z getFirstDoc
z getDocument
z isValidValue
z getDBInfo
z getWorkingDirectory
z system-property
z buildSqlParamStr
z convertToDBType
Sample Document:
<CUSTOMER_ORDER>
<ID Value="CO-1"/>

<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-3"/>
<QTY Value="100"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
getFirstDoc
Syntax: getFirstDoc(//ServiceName/TableName, col1, <expr1>, col2, <expr2>.....)
Return Type: XML
Description: The getFirstDoc function will fetch the first document matching the
criteria from database for the specified Xservice. In the absence of the ServiceName,
default service (i.e. the one from which the function is being called) will be used.
Example 1:
Input:

Chapter 6 X-Path
<PRINTLN Value="{getFirstDoc('//TEST/ORDER_LINE_ITEM', 'CO_ID',

'CO-1')}" />
Output:
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
getDocument
Syntax: getDocument(//ServiceName/TableName, col1, <expr1>, col2, <expr2>.....)
Return Type: XML
Description: The getDocument function will fetch all the documents matching the
criteria from database for the specified Xservice. In the absence of the ServiceName,
default service (i.e. the one from which the function is being called) will be used.
Example 1:
Input:
<PRINTLN Value="{getDocument('ORDER_LINE_ITEM', 'CO_ID', 'CO-
1')}" />
Output:
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>

<ID Value="LI-3"/>
<QTY Value="100"/>
</ORDER_LINE_ITEM>
request
Syntax: request(//ServiceName/RequestName, param1, <expr1>, param2,
<expr2>.....)
Return Type: XML
Description: The request function will execute the request specified in the first
parameter to the function on the specified Xservice and return an XML document
back. In the absence of the ServiceName, default service (i.e. the one from which the
function is being called) will be used.
Example:
Input:
<PRINTLN Value="{request('//ORDER_ADMIN/getPO', 'AO_ID', 'PO-1')}" />
Output:
<ACTIVITY_ORDER>
<ID Value="PO-1"/>
<ORDER_LINE_ITEM>
<ID Value="LI-1"/>
<QTY Value="350"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-2"/>
<QTY Value="200"/>

Chapter 6 X-Path
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ID Value="LI-3"/>
<QTY Value="100"/>
</ORDER_LINE_ITEM>
</ACTIVITY_ORDER>
isEmpty
Syntax: isEmpty(X-Path expression)
Return Type: Boolean
Description: The isEmpty function takes a String, XMLform or a list as a parameter.
will return true if the the value of the parameter is empty. Empty is defined as shown
below for each data type
String: Empty string “”
List: no contents
XMLform: no children
Example 1:
Input:
<IF_TEST Test=" isEmpty($param)">
<THEN>
<PRINTLN Value="Empty parameter"/>
</THEN>
<ELSE>
<PRINTLN Value="Non-Empty parameter"/>
</ELSE>
</IF_TEST>
Output:
Empty parameter
isDataType
Syntax: isDataType(X-Path expression, <dataType>)


Description: The isDataType function will return true if the the value of the first
parameter is of type <dataType>, as specified in the second parameter; otherwise
returns false. The valid data types that are supported are int, float, double, Boolean,
date, datetime, time and timestamp.
Example 1:
Input:
<IF_TEST Test=" isDataType ($coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM[ID/@Value='LI-1']/SEQ_NO/@Value, 'int')">
<THEN>
<PRINTLN Value="Integer Sequence"/>
</THEN>
<ELSE>
<PRINTLN Value="Non-Integer Sequence"/>
</ELSE>
</IF_TEST>
Output:
Integer Sequence
isValidValue
Syntax: isValidValue(X-Path expression, <val1>, <val2>.....)
Description: The isValidValue function will return true if the node-list from the X-
Path expression contains one of the listed values - val1, val2, and so on; otherwise
returns false.
Example 1:
Input:
<IF_TEST Test=" isValidValue ($coDoc/ORDER_LINE_ITEMS/
ORDER_LINE_ITEM[ID/@Value='LI-1']/GRP_MEMBER/@Value, 'yes',
`maybe')">
<THEN>
<PRINTLN Value="Group Member"/>
</THEN>
<ELSE>
<PRINTLN Value="Invalid Group Member"/>
</ELSE>
</IF_TEST>
Output:
Invalid Group Member

Chapter 6 X-Path
getDBInfo
Syntax: getDBInfo()
Return Type: XML
Description: The getDBInfo function will return the database connection information.
Example 1:
Input:
<PRINTLN Value="{getDBInfo()}"/>
Output:
<DATA_BASE_META_INFO>
<PRODUCT_NAME Value="Oracle"/>
<PRODUCT_VERSION Value="Oracle9i Enterprise Edition Release
..."/>
<USER_ID Value=" SCOS"/>
</DATA_BASE_META_INFO>
Note: SCOS is the older term for i2 Agile Business Platform (ABP).
getWorkingDirectory
Syntax: getWorkingDirectory ()
Return Type: String
Description: The getWorkingDirectory function will return the server's root directory.
Example 1:
Input:
<PRINTLN Value="{ getWorkingDirectory()}"/>
Output:
C:/i2/ABPP/bin
system-property
Syntax: system-property(X-Path Expression1, X-Path Expression2)
Return Type: String
Description: The system-property function will return the system property identified
by the value evaluated by the first argument, if it does not find one it will return the
value evaluated to by the second argument. The second argument is optional.
Example 1:
Assuming there is a system property defined for someProperty=someValue
Input:

<PRINTLN Value="{system-property('someProperty')}"/>
Output:
someValue
buildSqlParamStr
Syntax: buildSqlParamStr (X-Path Expression)
Return Type: String
Description: This function returns a comma separated string for the number of
arguments specified in the argument that is passed to it.
Example 1:
Assuming the varibale numParams=3
Input:
<PRINTLN Value="{buildSqlParamStr($numParams)}"/>
Output:
?,?,?
convertToDBType
Syntax: convertToDBType(value, datatype)
Return Type: DB Specific String
Description: The convertToDBType function will return the database specific
conversion of the value as specific to the data type.
Example 1:
Input:
select * from BOOK where bk_rel_date > {convertToDBType(date(),
'date')}
Output (for Oracle):
select * from BOOK where bk_rel_date > TO_DATE('2005-12-16',
'yyyy-mm-dd')
Example 2:
Input:
select * from BOOK where bk_id = {convertToDBType(10,
'string')}
Output (for Oracle):
select * from BOOK where bk_id = '10.0'

Chapter 6 X-Path
Java Functions
ABPP supports embedding Java functions within X-Rules to handle complex
processing tasks. The following X-Path functions are used to invoke Java functions:
z nativeFunction
z instanceFunction
z instanceMethod
nativeFunction
Syntax:
nativeFunction('myClassName', 'myMethodName', 'param1',...,
'paramN')
Where
Parameters param1,..., paramN can use X-Paths expressions.
Syntax of the Class:
public Class myClassName
{
..................
..................
Static public DataType myMethodName (DataType1 param1 ...
DataTypeN paramN)
{
..................
..................
}
}
Description:
A Native Function is used to perform complex tasks in Java. It is a static method of a
class and does not require instantiating the class. Native Function can be used only
when the method is a not override-able; if the method is such that it may need to be
overridden in specific implementations, it is better to use an Instance Function (see
next section).
Example 1:
Input:
<SET Var="myId" FromValue="{nativeFunction('com.i2.X-
Core.utils.UniqueIdGenerator', 'getUniqueId', 'PO')}"/>
<PRINT Value="{$myId}" />
Output:
PO-78691

Java Functions
instanceFunction
Syntax:
instanceFunction('myClassName', 'myMethodName', 'param1',...,
'paramN')
Where Parameters param1,..., paramN can use X-Paths
expressions.
Syntax of the Class:
public class myClassName
{
// A public no-argument default constructor is required
public myClassName()
{
}
....................................................
....................................................
public DataType myMethodName ( DataType1 param1,..., DataTypeN
paramN )
....................................................
....................................................
}
}
Description:
An Instance function is used to perform complex tasks in Java. Instance function is
similar to Native function except that the function is not 'static' and (hence) the
mechanism used to make the invocation is different. ABPP instantiates an object of
the specified class name the first time a method is invoked on it in the transaction. The
instantiation happens using a public no-argument default constructor the class is
required to provide. It then invokes the function. The object is re-used for all the later
invocations during the transaction.
There are 2 added benefits of instance functions not available in native functions.
1. Instance functions allow the functions to update some state (instance) variables
and re-use the state across method invocations within a single transaction.
2. There is a class mapping facility. To understand this feature, consider that some
rules use instance functions on say class À'. In a customer deployment, some of
the methods in class À' are needed to behave differently. Another class `B' can be
written extending class À' that overrides these methods. In the class mapping
setup, A may be mapped to `B'. During execution, class `B' will be instantiated
wherever À' is mentioned and the methods are invoked on `B'. If some methods
don't need to change, class `B' will automatically inherit them.
Example 1:

Chapter 6 X-Path
Input:
<SET Var="myId" FromValue="{instanceFunction('com.i2.X-
Core.utils.UniqueIdGenerator', 'getUniqueId', 'PO')}"/>
<PRINT Value="{$myId}"/>
Output:
PO-78654389
Example 2:
Setting up Class-Mapping
Add the following tag to the service's .xml configuration file:
<class-mapper File="myclassmapping.xml"/>
The file classmapping.xml will have content similar to the following:
<class-mappings>
<class Name="com.i2.xservice.origpackage.OrignalClass"
MapTo="com.i2.xservice.newpackage.NewClass"/>
</class-mappings>
This mapping will cause the class com.i2.xser.newpackage.NewClass to be used in the
X-Rules wherever class com.i2.xservice.origpackage.OriginalClass is referred to in an
INSTANCE_FUNCTION statement.
instanceMethod
Syntax:
instanceMethod($myObjVar, 'myMethodName', 'param1',...,
'paramN')
Where:
z myMethodName - Method to invoke,
z myObjVar - Object to invoke the method on (can use X-Path expression)
z param1,..., paramN - Parameters (can use X-Paths expressions)
Description:
Instance method statement is yet another way to invoke a method on a Java object.
The difference between instance method and instance function is that instance method
allows invocation of a method on a Java object whose reference is already available
within the context of a rule.
Example1:
First, get a handle to the customer order instance using the ID:
<SET Var="coObj"
FromValue="{nativeFunction('com.i2.xservice.orderadmin.sce.orde
r.reg.OrderEntityFactory', 'getOrderEntity', '{$thisParam/ID/
@Value}',' CUSTOMER_ORDER',' {$thisContext}')}"/>
Now, to invoke a method on the customer object instance:

Java Functions
Input:
<SET Var="invoiceValue" FromValue="{instanceMethod($coObj,
'getTotalEstimatedInvoiceValue')}"/>
<PRINTLN Value="The estimated total invoice value is:
{$invoiceValue} "/>
Output:
The estimated total invoice value is 993.45

Chapter 6 X-Path

Chapter 7
X-Config
Topics:
z Service Configuration
z Server Configuration
Introduction
The configuration parameters for the ABPP server and services are specified in
configuration files.
Typical examples of server configuration are:
z Database Connection Parameters - User, Password, Jdbc URL etc
z Number of worker threads
z Cryption parameters for encrypting and decrypting strings.
z Log levels for the server
z Schema generation settings to control if the schema should be directly written to
database or to a sql file or both.
z The directory where WSDL files should be written out.
Typical examples of service configuration are:

z Name of the service and values for other service settings to enable transaction
cache, security access permission for APIs etc.
z The workflow & rule file names that are part of the service.
z Definitions for the id generation sequences used in the service.
The server and service configurations are described in xml files. The tags within the
xml files provide the details on each of the configurations. An ABPP application will
have:

Chapter 7 X-Config
z 1 server configuration file and

z 1 or more service configuration files for each of the services that are part of the
application. Whenever a service is customized, all customizations to the service
configuration are saved in a separate file. Typically for customized services, there
will 1 configuration file for the base service configuration and another to store the
customized configurations.
Note: It is recommended to use the ABPP studio to edit the server and service
configuration files. ABPP studio provides an intuitive visual interface for
creating/editing these configurations. So ABPP users will not typically
require the information contained with this chapter. This chapter is mainly
intended as a reference for the ABPP development team.
Service Configuration
This section explains the configurations which define the behavior of an ABPP
Service.
Service Config
Description:
The service-config element is the root tag enclosing the service configurations.
Syntax:
<service-config Name="name-of-the-service"
SecurityCheck="true|false[default=false]"
Transaction Cache="true|false[default=true]"
ValidateApiSignatures="true|false[default=false]"
Register="true|false[default=true]">
<register-handlers /> (refer Register Handlers)
<extensionFiles /> (refer Extension Files)
<xpathFunctions /> (refer X-Path Functions)
<docDefnFiles /> (refer Document Definition Files)
<ruleDefnFiles /> (refer Rule Definition Files)
<eventDefnFiles /> (refer Event Definition Files)
<validationSpecFiles /> (refer Validation Spec Files)
<workflow /> (refer Workflow)
<exportDefnFiles /> (refer Export Definition Files)
<purgeDefnFiles /> (refer Purge Definition Files)
<dbLockSpecFiles /> (refer DBLock Specification Files)
<stateModelFiles /> (refer State Model Files)
<searchDefnFiles /> (refer Search Definition Files)
<auditTrailDefnFiles /> (refer Audit Trail Definition
Files)
<idgen /> (refer IDGen Configuration)
<service-params /> (refer Service Parameters
<logger /> (refer Logger)
<cisTagNameMapping /> (refer CisTagNameMapping )
<sqlScriptFiles /> (refer SqlScriptFiles)
<semanticVal /> (refer SemanticValidation)
</service-config>

Attributes
z Name (Required): Name of the service
z SecurityCheck (Optional): true/false. Default is false. If true then it will enforce
the access levels (Public|Private|Protected) specified on the rules (i.e., through the
Access attribute on DEFINE_METHOD tags).
z TransactionCache (Optional): true/false. Default is false. If true, then the system
will attempt to cache query results issued during the transaction. It will try to first
serve the query from the cache and if not in cache it will serve it from the
database. This setting also will result in the system deferring insert & update
operations and issuing them on the database as a batch insert & update operation.
Batch inserts & updates are very essential for improving the performance of the
system.
z ValidateApiSignatures (Optional): true/false. Default is false. If true, the system
will validate Public & Protected commands invoked on the service to ensure
conformance to the input/output signatures provided in the API_DOC. This
service flag can be overridden for a specific command by specifying
ValidateSignature attribute on the command. Example: If a public command has
ValidateSignature=false specified on it then it’s input & output will be not
validated regardless of the ValidateApiSignature setting on the service. Similarly
a public command with ValidateSignature=true will have it’s input & output
validated regardless of this service flag.
z Register (Optional): true/false. Default is true. If true, then the system will register
the service with the locator.
Register Handlers
Description:
This tag identifies handlers for all the custom tags that are introduced in this config
file that are not part of the standard set of supported tags.
Syntax:
<register-handlers>
<handler TagName="tagName[Type=string]"
ClassName="className [Type=string]" Repeatable="true">
<dependencies Optional="true">
<dependsOn TagName="tagName[Type=string]"
Repeatable="true" />
</dependencies>
</handler>
</register-handlers>
The handler class should extend from com.i2.xcore.init.core.config.IDyamicRegister.
Please contact ABPP Dev for more information on registering your custom handlers.
Example:
<register-handlers>
<handler TagName="mytag"
ClassName="com.i2.xservice.myService.handler.MyTagHandler">
<dependencies>
<dependsOn TagName="extensionFiles" />

Chapter 7 X-Config
</dependencies>
</handler>
</register-handlers>
For example: TagName = "mtag" is a custom xml tag that is introduced in this file
which is not part of the standard set of supported tags. Whenever the "mytag" tag is
encountered in the service-config file the "mytag" element is passed to the
MyTagHandler, which processes the XML element. If "mytag" element requires other
tags to be processed before it can be processed, you can specify those dependencies as
shown above. This dependency feature is provided so that the content of the service-
config file is order independent.
Extension Files
Description:
This tag lists all the files that contain extensions made to the ABPP language .
Syntax:
<extensionFiles>
<extensionFile Name="file-name" Repeatable="true" />
</extensionFiles>
Example:
<extensionFiles>
<extensionFile Name="xservice/myService/extension/
myExtension.xml" />
</extensionFiles>
The extension file, myExtension.xml, will typically contain the

following structure:.
<XCORE_EXTENSION>
<COMMAND_EXTENSION>
<transformTextToValueAttribute
ClassName="com.i2.xservice.myService.command.TransformTextToVal
ueAttribute" />
</COMMAND_EXTENSION>
<RULE_EXTENSION>GET_DESCENDANT
ClassName="com.i2.xservice.myService.rule.GetDescendantParser"
/></RULE_EXTENSION>
<XPATH_EXTENSION>
<myXpathFunc
ClassName="com.i2.xservice.myService.xpath.MyXpathFunc" />
</XPATH_EXTENSION>
<DOCGEN_EXTENSION>
<MY_SEARCH_FILTERS
ClassName="com.i2.xservice.myService.docgen.ReferSearchFiltersH
andler" />
</DOCGEN_EXTENSION>
<SEARCH_FILTER_EXTENSION>
<my-domain-filter-defs
ClassName="com.i2.xservice.myService.search.DomainFiltersDef" /
>
</SEARCH_FILTER_EXTENSION>
</XCORE_EXTENSION>

Please contact ABPP dev team for more details on creating your custom extension
classes.
In this example, the GET_DESCENDANT tag is an extension to the X-Rule grammar
and whenever ABPP encounters this tag it basically invokes the GetDescendantParser
to handle it.
The above extension file provides extensions to command, X-Rule, X-Path, API doc
generation and search filters.
X-Path Functions
Description:
You can create X-Path short-cuts for the most commonly used requests. This usually
makes the code more concise and readable.
Syntax:
<xpathFunctions>
<function Name="[Type=string]"
Cache="true|false[default=false]" MapTo="any-xpath-function-
expression with arg0,arg1,argn" Repeatable="true" />
</xpathFunctions>
Cache attribute is optional. If Cache attribute is not provided, then it defaults to false.
If Cache attribute is false, output of the X-Path function is not cached.
If Cache attribute is true, output of the X-Path function is cached within the
transaction scope. Invoking the X-Path function again with the same parameters
within the transaction will result in the output served from cache.
Example:
<xpathFunctions>
<function Name="buyGetShipTo" Cache="true"
MapTo="request('buyGetShipTo', 'ID', $arg0)/SHIP_TO" />
<function Name="buyGetBillTo" Cache="true"
MapTo="request('buyGetBillTo', 'ID', $arg0)/BILL_TO" />
</xpathFunctions>
Using the short cuts, You can replace the following code:
<REQUEST Name="buyGetShipTo" AssignToVar="emResponse">
<ID Value="{$arg0}" />
</REQUEST>
<SET Var="shipTo" FromValue="{$emResponse/SHIP_TO/@Value}"/>
With this line of code:
<SET Var="shipTo" FromValue="{buyGetShipTo($arg0)}"/>
Document Definition Files

Description:
This tag lists the names of all the X-Doc files that are used by the Service.
Syntax:
<docDefnFiles>
<docDefnFile Name="xdoc-file-name" Repeatable="true" />

Chapter 7 X-Config
</docDefnFiles>
Example:
<docDefnFiles>
<docDefnFile Name="xservice/orderadmin/xml/sce/xdoc/
oaDocs.xml"/>
<docDefnFile Name="xservice/orderadmin/xml/sce/xdoc/
oaReturnsDoc.xml"/>
</docDefnFiles>
Rule Definition Files

Description:
This tag lists the names of all the X-Rule files that are used by the Service.
Syntax:
<ruleDefnFiles>
<ruleDefnFile Name="xrule-file-name" Repeatable="true" />
</ruleDefnFiles>
Example:
<ruleDefnFiles>
<ruleDefnFile Name="xservice/orderadmin/xml/sce/xrule/task/
oaInit.xml" />
<ruleDefnFile Name="xservice/orderadmin/xml/sce/xrule/task/
oaAPICreation.xml" />
</ruleDefnFiles>.
Event Definition Files

Description:
This tag lists the names of all the event definition files that are used by the Service.
Syntax:
<eventDefnFiles>
<eventDefnFile Name="event-definition-file-name"
</eventDefnFiles>
Example:
<eventDefnFiles>
<eventDefnFile Name="xservice/orderadmin/xml/pce/xrule/
order/orderInterfaces.xml" />
<eventDefnFile Name="xservice/orderadmin/xml/pce/xevent/
oaEvtDescInit.xml" />
</eventDefnFiles>
Validation Spec Files

Description:
This tag lists the names of all the validation spec files that are used by the Service.
Syntax:

<validationSpecFiles>
<validationSpecFile Name="validation-spec-file-name"
</validationSpecFiles>
Example:
<validationSpecFiles>
<validationSpecFile Name="xservice/orderadmin/validation/
asnCreateValidation.xml" />
<validationSpecFile Name="xservice/orderadmin/validation/
asnChangeValidation.xml" />
</validationSpecFiles>.
For more information on validation spec, Refer to the section on Validation
Framework Guide.
Workflow
Description:
This tag lists the names of all the workflow files that are used by the Service. It also
registers any custom workflow nodes used by the service.
Syntax:
<workflow>
<workflowDefnFiles>
<workflowDefnFile Name="workflow-file-name"
Repeatable="true"/>
</workflowDefnFiles>
<nodeHandlers>
<nodeHandler Name="abc" ClassName="abc-class"
Repeatable="true"/>
</nodeHandlers>
</workflow>
A service can implement custom workflow nodes by providing node name and the
implementing class through the nodeHandler tag.
Example:
<workflow>
<workflowDefnFiles>
<workflowDefnFile Name="xservice/approval/xml/workflow/
Wf_SubWf.xml" />
ManagerApprovalOnAmount.xml" />
RoleDomainBasedApproval.xml" />
</workflowDefnFiles>
<nodeHandlers>
<nodeHandler Name="serial_approval_node"
ClassName="com.i2.xservice.approval.handlers.SerialApprovalNode
Handler" />
</nodeHandlers>
</workflow>

Chapter 7 X-Config
Export Definition Files

Description:
This tag lists the names of all the export definition files that are used by the Service.
Syntax:
<exportDefnFiles>
<exportDefnFile Name="export-defn-file-name"
</exportDefnFiles>
Example:
<exportDefnFiles>
<exportDefnFile Name="xservice/orderadmin/xml/pce/export/
asnExportDef.xml" />
openLineExportDef.xml" />
rcptExportDef.xml" />
</exportDefnFiles>
For more information on export definition files, Refer to the section on Export
Framework.
Purge Definition Files

Description:
This tag lists the names of all the purge definition files that are used by the Service.
Syntax:
<purgeDefnFiles>
<purgeDefnFile Name="purge-defn-file-name"
</purgeDefnFiles>
Example:
<purgeDefnFiles>
<purgeDefnFile Name="xservice/orderadmin/purge/
schPurgeDef.xml" />
</purgeDefnFiles>
For more information on purge definition files, Refer to the section on Purge
Framework.
DBLock Specification Files

Description:
This tag lists the names of all the dblock specification files that are used by the
Service.
Syntax:
<dbLockSpecFiles>

<dbLockSpecFile Name="dblock-spec-file-name"
</dbLockSpecFiles>
Example:
<dbLockSpecFiles>
<dbLockSpecFile Name="xservice/orderadmin/dblock/
lockDefinition.xml" />
</dbLockSpecFiles>
For more information on dblock specification files, Refer to the section on DB based
locking utility
State Model Files

Description:
This tag lists the names of all the state model specification files that are used by the
Service.
Syntax:
<stateModelFiles>
<stateModelFile Name="dblock-spec-file-name"
</stateModelFiles>
Example:
<stateModelFiles>
<stateModelFile Name="xservice/orderadmin/xml/pce/state/
oaBuyOrderSM.xml" />
</stateModelFiles>
For more information on state model specification files, Refer to the section on State
Machine
Search Definition Files

Description:
This tag lists the names of all the search definition files that are used by the Service.
Syntax:
<searchDefnFiles>
<searchDefnFile Name="search-defn-file-name"
</searchDefnFiles>
Example:
<searchDefnFiles>
<searchDefnFile Name="xservice/orderadmin/search/
poSearchDef.xml" />
<searchDefnFile Name="xservice/orderadmin/search/
toSearchDef.xml" />
</searchDefnFiles>

Chapter 7 X-Config
For more information on search definition files, Refer to the section on Search
Framework
Audit Trail Definition Files

Description:
This tag lists the names of all the audit trail definition files that are used by the
Service.
Syntax:
<auditTrailDefnFiles>
<auditTrailDefnFile Name="audittrail-defn-file-name"
</auditTrailDefnFiles>
Example:
<auditTrailDefnFiles>
<auditTrailDefnFile Name="xservice/orderadmin/audittrails/
OrderScheduleAuditTrail.xml" />
</auditTrailDefnFiles>
For more information on audit trail definition files, Refer to the section on Audit Trail
Framework
IdGen Configuration
Description:
For generating unique ids for x-document instances, you have to first configure the X-
Service file by setting the 'idgen' tag with details of the document, prefix, delimiter,
sequenceName, block size (if applicable) and the handler to use.
You have to specify the idgen settings for each document for which ID generation is
automated ( See Surrogate Key in X-Document Reference ).
Syntax:
<idgen>
<document Name="xdoc-name[Type=string]"
prefix="[Type=string, optional=true]" delimiter="[Type=string,
Optional=true]" sequenceName="seq-name[Type=string]"
handler="java-class-name[Type=string]"
blockSize="100[Type=positive-int]" startNum="1[Type=positive-
int, default=1]" Repeatable="true">
<Type Name="abc[Type=string]" Prefix="[Type=string]"
Optional="true" Repeatable="true" />
</document>
</idgen>
The following attributes apply to all ID generation schemes:

z document: Name of document for which sequence is generated.
z name: It is the name of the document. The user has to configure the ID generation
scheme for each Document which are defined in the Service.

z prefix: It identifies the prefix to be used in ID. For example, CO for

CUSTOMER_ORDER Document.
z delimiter: It specifies the character to be used after prefix.
z handler: The handler attribute specifies the ID geneation scheme to be used for a
Document. The following are the valid values of the handler:
| com.i2.xcore.idgen.TimeIdGenerator
| com.i2.xcore.idgen.BlockTableIdGenerator
| com.i2.xcore.idgen.OracleIdGenerator (To be used only for Oracle Database)
| com.i2.xcore.idgen.DB2IdGenerator (To be used only for DB2 Database)
The following attributes applies to sequence based id generators:
z sequenceName: It identifies the SEQUENCE Object in the Database to be used
for ID Generation.
z blockSize : It identifies the INCREMENT size of the Sequence in the Database.
z startNum: specifies the starting number for the sequence
Example 1:
<idgen>
<document Name="ACTIVITY_ORDER" prefix="A"
sequenceName="AO_SEQ"
handler="com.i2.xcore.idgen.BlockTableIdGenerator"
blockSize="100">
<Type Name="PURCHASE_ORDER" prefix="P" />
<Type Name="TRANSFER_ORDER" prefix="T" />
<Type Name="FULFILLMENT_ORDER" prefix="FO" />
</document>
<document Name="ORDER_SCHEDULE" prefix="S" delimiter="-"
sequenceName="SCH_SEQ"
blockSize="100" />
</idgen>
The "prefix" attribute identifies the Prefix to be used in ID. In the example, S is the
prefix for ORDER_SCHEDULE Document.
In this example, the prefix is 'S' and the delimiter is '-'for ORDER_SCHEDULE. So
the ID for ORDER_SCHEDULE will be of the form: S-123.
For a document we can optionally have different prefix depending on some types. In
the above example, PURCHASE_ORDER and TRANSFER_ORDER are types of
ACTIVITY_ORDER. For PURCHASE_ORDER type the id prefix is 'P' and for
TRANSFER_ORDER the prefix is 'T'.
Refer to the section on Id Generation for more information.
Service Parameters
Description:

Chapter 7 X-Config
This tag contains all the Service Properties ( Name-Value pairs) that are used by the
service for processing.
Syntax:
<service-params>
<param Name="name[Type=string]" Value="[Type=string]"
</service-params>
Example:
<service-params>
<param Name="AutoSendOrderAfterCreate" Value="false" />
<param Name="AutoSendConsumptionPlanAfterCreate"
Value="false" />
<param Name="BuyExcessiveOverDueDuration" Value="4" />
<param Name="ShipmentDelayToleranceInDays" Value="2" />
<param Name="IMxIntegrationEnabled" Value="true" />
<param Name="DefaultExpediteLeadTime" Value="2" />
</service-params>
The following predefined service parameters are available for all ABPP services:
z WSDL_ACCESS_LEVEL: This parameter overrides the API access level filter
for this service. If this parameter is not specified, WSDL generation will use the
access level filter specified as part of WSDLGenerate tag in xserver
configuration. Please see WSDLGenerate tag in xserver configuration section to
understand how access level filter affects the WSDL generation.
Example:
<param Name="WSDLAccessLevel" Value="Public,Protected"/>
z WSDLGenerate: This parameter can be used to disable WSDL generation of APIs
for this service. By default this is true.
Example:
<param Name="WSDLGenerate" Value="false"/>
z PGL_CACHE_EXPIRY_MINUTES: This is the time interval from the last check
for which the system will not check if a pgl file has been modified on disk.
In a development environment, you will want to reload the pgl file as soon as it
has been modified and hence the parameter should be set to 0.
In a production environment, the pgl file will not be modified. You can avoid the
overhead of checking for file modifications by setting the parameter to -1.
You can enable the check hourly by setting the parameter to 60.
Example:
<param Name="PGL_CACHE_EXPIRY_MINUTES" Value="-1"/>
z PGL_DEBUG_INFO: This parameter is useful in debug environments. If this
parameter is true, the system prints out hidden fields providing the following:
Workflow name, ui-node name, workflow file name and line-number of the node
in the workflow file.

Full path of the pgl file on the disk and the last modified time stamp.
This parameter is true by default. In a production environment, this debug
information is an unnecessary over-head and can be turned off.
<param Name="PGL_DEBUG_INFO" Value="false"/>
z DEFAULT_MAX_XDOC_TXN_CACHE_SIZE: Maximum number of instances
of an X-Doc that can be held in transaction cache for this service. This defaults to
100. This setting is useful to prevent the transaction cache system from running
the system out of memory.
z DEFAULT_MAX_ROWS_FETCH: Default maximum number of records that
can be fetched by a database query on this service. The default is used when
MaxRows attribute is not provided on the query (GET_DOCUMENT,
EXEC_SQL_QUERY etc). If this parameter is not provided, it defaults to 1000.
This setting is useful to prevent inadvertent fetcing of a lot of data leading to the
system running out of memory.
Each of the services have configuration parameters specific to their needs. Please see
service specific documentation for these.
Logger
Description:
The Logger tag specifies the file name to which a particular service's log messages
should be written. If no file name is mentioned, the log messages would appear on
server console.
Syntax:
<logger>
<file Name="service-log-file-name"
Overwrite="true|false[Optional=true, Default=true]"
MaxSize="file-size[default=100MB]" NumBackups="number-of-
backups[Default=2]" />
<logLevels>
<logLevel Value="Exception" Optional="true" />
<logLevel Value="Error" Optional="true" />
<logLevel Value="Info" Optional="true" />
<logLevel Value="EnterTrace" Optional="true" />
<logLevel Value="ExitTrace" Optional="true" />
<logLevel Value="Debug" Optional="true" />
<logLevel Value="Warning" Optional="true" />
<logLevel Value="InterServiceCallTrace" Optional="true"
/>
<logLevel Value="IntraServiceCallTrace" Optional="true"
/>
<logLevel Value="SqlCallTrace" Optional="true" />
<logLevel Value="XPathFnTrace" Optional="true" />
</logLevels>
<brief-console Value="true|false" />
<format Name="text|xml[default=xml]" />
</logger>

Chapter 7 X-Config
Name Attribute:
If no file name is mentioned, then the output would be piped to the console. Same is
the case if a non existent directory is mentioned.
Overwrite Attribute:
The attribute “Overwrite” on the file property can be used to specify whether to
overwrite the log file or append to it.
If Overwrite attribute is not specified on the file property, then it defaults to “true”.
MaxSize and NumBackups Attributes:

Assume File is the is the file name to which the output is set to happen. MaxSize
attribute determines the max size to which this log file can grow to. If NumBackups is
positive, then, each time File grows to MaxSize files {File.1, ...,
File.MaxBackupIndex -1} are renamed to {File.2, ..., File.MaxBackupIndex}.
Moreover, File is renamed File.1 and closed. A new File is created to receive further
log output.
The MaxSize option takes an long integer in the range 0 - 2^63. One can specify the
value with the suffixes "KB", "MB" or "GB" so that the integer is interpreted being
expressed respectively in kilobytes, megabytes or gigabytes. For example, the value
"10KB" will be interpreted as 10240. Please note that when the user specifies the size
as 10KB, it may not be exact 10KB before the backups start being created. Because
the check for size happens after each log, so typically, the size would be a few bytes
more than 10KB before the backups come into play. This neither a bug nor a cause of
concern.
In ABPP, the default value for MaxSize is 100MB and the default value for
NumBackups is 2.
<logLevels> tag
The following log levels provide very important information. Any log messages
pertaining to this level must be investigated to ensure that the system is functioning
correctly. These logLevel should always be turned on.
z Exception: All unhandled exceptions are logged if Exception level is turned on.
z Error: All errors are logged if Error level is turned on.
z Warning: All errors are logged if Warning level is turned on.
The following log levels are useful in trouble shooting in development and production
environment. Turning on these levels can slow down the system because of the
amount of data logged. Hence it is recommended to turn off these log levels in
production environment by default. They can be turned on dynamically for trouble
shooting.
z Info: This log level will capture info messages. Turning info log level on xserver
will log the request-response xml for every request being issued externally on the

server. Look at LOG X-Rule component for details on logging using this log level
within X-Rules.
z EnterTrace: This log level can be used to log the entry in to a code block. You can
use this log level to know if a X-Rule code block has been entered. Look at LOG
X-Rule component for details.
z ExitTrace: This log level can be used to log the exit from a code block. You can
use this log level to know if a X-Rule code block has been exited. Look at LOG
X-Rule component for details. Turning this log level on xserver will log the name
of the first request and elapsed time after processing a REQUESTS tag. The
elapsed time can be of use for identifying the requests that need to be tuned.
z Debug: This log level can be used to log debug messages. PRINTLN rule
component logs it messages using this log level. Also look at LOG X-Rule
component.
z InterServiceCallTrace: This log level will log the REQUEST-RESPONSE for all
invocations across services deployed in the VM.
Example: A request issued in the X-Rule code of service A which calls out a request
on Service B will get logged by this log level.
IntraServiceCallTrace: This log level will log the REQUEST-RESPONSE for all
invocations within the same.
Example: A request issued in the X-Rule code of service A which calls out a request
on the same service will get logged by this log level.
SqlCallTrace: This log level will log all the sql statements issued by the service.
XPathFnTrace: This logs the entry and exit out of a X-Path function.
<brief-console> tag
brief-console is applicable only to the logger setting in xserver. Enabling brief-console
will print the request name of every request issued on the server from outside on to the
console (System.out). This can be enabled by setting Value attribute of this tag to true
<format> tag
This name attribute of this tag controls the format of the log file. If not provided, it
defaults to xml.
Example:
<logger>
<file Name="../log/orderadmin.log" MaxSize="20MB"
NumBackups="4" />
<logLevels>
<logLevel Value="Exception" />
<logLevel Value="Error" />
</logLevels>
<brief-console Value="false" />
</logger>

Chapter 7 X-Config
CisTagNameMapping
Description:
This tag allows you to specify mapping files which translate the native API_DOC tag
and attribute names to CIS compliant names.
CIS compliance requires that all member names be defined in Lower Camel Case (e.g.
orderedQty). Also underscores, dots, dashes are not allowed. If the native API_DOC
has tags defined using Upper Case with underscores, dashes etc., they have to be
converted to CIS compliant tag/attribute names.
Syntax:
<cisTagNameMapping>
<mappingFile Name="mapping-file-name" Repeatable="true" />
</cisTagNameMapping>
Example:
<cisTagNameMapping>
<mappingFile Name="xservice/orderadmin/cis/mapping.xml" />
</cisTagNameMapping>
SqlScriptFiles
Description:
This tag allows you to load sql script files in to the database as part of schemagen.
It is recommended that the sql script files do a DROP before CREATING any
database objects. This will ensure that sqlScriptFiles can be re-executed as part of
schema gen without the need for drop scripts.
Syntax:
<sqlScriptFiles>
<database Name="oracle|db2" Repeatable="true">
<sqlScriptFile Name="script-file-name" />
</database>
</sqlScriptFiles>
Example:
<sqlScriptFiles>
<database Name="oracle">
<sqlScriptFile Name="execproc/procedures/myproc.sql" />
</database>
</sqlScriptFiles>
SemanticValidation
Description:
This tag allows you to turn on semantic validation for the service. Semantic validation
will validate the semantics of the rule code, similar to what a compiler does for
languages like Java, C and C++. For example it will validate if the variable name
being used is valid, check if the document used for GET_DOCUMENT is valid, check

if the REQUEST name given is a valid rule, check if the XPath expression specified is
accessing valid child tags and so on.
The semantic validation if enabled is performed when the server starts up and when a
rule/workflow file is reloaded. Any semantic errors found are printed either on server
console or log file. The semantic errors displayed are warnings only. Here is an
example of a semantic error printed:
Semantic Error: Mentioned variable $orderId not found
at SET[C:\workspace\SemanticValidation\cfg\xservice\
test\rules\creation.xml:37-37]
at ACTION[C:\workspace\SemanticValidation\cfg\xservice\
at RULE[C:\workspace\SemanticValidation\cfg\xservice\
at DEFINE_METHOD-testSemantic[C:\workspace\
SemanticValidation\cfg\xservice\test\rules\creation.xml:2-161]
For the semantic validation to find meaningful errors it needs to know the type
information for each variable. For xml variables it needs to know the structure of the
xml. For variables that are created in rule code the system will figure out the type
information. The type definition for input of a X-Rule (i.e. type information for
thisParam) should be provided by specifying an API_DOC for the rule.
The service level semantic validation settings will override the xserver level semantic
validation settings.
If the application is running in i2 Studio then in Debug mode the user can press F4 key
in the rule or workflow source editor to debug the type definition for variables built till
that point in the code. This is useful in trying to figure out why some semantic error is
happening. Note: The key only works on start and end lines of the rule action
components.
Level Attribute: Valid values are 1 or 2. The Level attributes defines the level of
validation to perform. Level 1 validation will only perform existential checks e.g.
valid variable name, valid document name, valid rule name etc. Level 2 validation will
do all the validations for level 1 and also check the X-Path expression to validate the
tags being traversed.
Output Attribute: Valid values are LOG or CONSOLE. The output of semantic
validation can be directed either to the log file or to server console. Setting the output
to LOG will direct the semantic errors to the service log files. The service should have
Debug log level turned on to see the errors.
Syntax:
<semanticVal Level="1|2" Output="LOG|CONSOLE" />
Example:
<semanticVal Level="2" Output="CONSOLE" />

Chapter 7 X-Config
Server Configuration
This section explains the various configurations which define the behavior of the
ABPP Server.
The server configuration file can also be used for defaulting some of the service
configurations for the services deployed within the server.
Example: If logger configuration ( refer <logger> tag) is not provided for a service
then it defaults to the one specified within the server configuration.
Some configurations common to all the services deployed within the server can be
specified within the server configuration file .This avoids repeating them in each of
the service configuration files. Each of the service configuration files can then contain
only the add-ons/over-rides required by that service.
Example: Any X-Document files or X-Rule files common to all services can be
provided in the server configuration file.
The service configuration tags must be enclosed within the appserver-config tag of the
server configuration file.
Syntax:
<dom-config>
<locator-config …/> (Refer Locator Configuration )
<client-config …/> ( Refer Client Configuration )
<appserver-config …/> (Refer App Server Configuration )
<services-override …/> (Refer Services Override
Configuration)
</dom-config>
Locator Configuration
Description:
This configuration enables the server to register its services with the locator and also
discover the location of remote services.
Syntax:
<locator-config Value="X-Core">
<property Key="locatorURL" Value="locator-url" />
</locator-config>
Example:
<locator-config Value="X-Core">
<property Key="locatorURL" Value="http://m42usklcw:2000"/>
</locator-config>

Protocols
Description:
The server/client can communicate in the protocols mentioned below.
Protocol Name Description
XRMP X-Core remote messaging protocol (XRMP) is symmetrical, asynchronous, multiplexing

communication protocol, which serializes the internal XML data structure. With this protocol
only few open sockets are needed for client to communicate with server. There is no frequent
opening and closing of sockets. Since the internal XML data structure is serialized, no XML
parsing is need. This protocol gives 30 % more throughput than HTTP protocol.
TCPA TCP asynchronous, is similar to XRMP except, it does not serialize XML, instead passes XML
as raw string. Clients who do not have class definitions of internal XML data structure could
use this protocol.
HTTP Standard protocol used when talking across firewalls or for decoupling desperate systems
while integrating.
Client Configuration
Description:
The client config section captures the configuration info for the X-Server client that is
used for communicating with other remote services deployed in other X-Server VMs.
Syntax:.
<client-config>
<protocol-preferences>
<protocol Value="xrmp|tcpa|http" Repeatable="true" />
</protocol-preferences>
<max-conn Value="number[default=2]" />
<timingStats Value="true|false[default=false]" />
<create-soc-timeout Value="time-in-minutes[default=2]" />
<service-refresh-rate Value="time-in-minutes[default=60]" /
>
</client-config>
Here is a brief description of the various protocols supported by ABPP:
If multiple protocol preferences are specified then the preference is in the order it is
specified in the list. The client will choose the protocol to communicate with the
server based on the following criteria:
1. Supported by the server
2. Is of the highest preference.
max-conn: This applies only for xrmp and tcpa protocols. This is the maximum
number of persistent tcp socket stream allowed to connect to server
timingStats: If true then the network timing info is also returned as part of every
invocation.

Chapter 7 X-Config
create-soc-timeout: This is the time out period in minutes for creating a new client
socket. If the time out period expires then the client throws an exception. The default
is 2 minutes.
service-refresh-rate: The client caches a look up table of remotely located service
names Vs their URLs. The cache is expired after the time period specified by Service
refresh rate. The service refresh rate is specified in minutes. The default is 60 minutes.
App Server Configuration

Description:
This section briefly describes the various configuration options and parameters
needed for the Appserver.
Syntax:
<appserver-config Name="Appserver1">
<database-config /> ( refer Database Configuration )
<jms-config /> ( refer JMS Configuration )
<server-config /> ( refer Server Configuration )
<schemaGenerate /> (refer Schema Generation )
<cryption /> (refer Encryption Configuration )
<cmdLineInput /> (refer Command Line Input )
<enableJMS /> (refer Enable JMS )
<logicalDate /> (refer Logical Date )
<WSDLGenerate /> (refer WSDL Generation)
<WSDL-client-config /> (refer WSDL Client Configuration )
<cis-client-config /> (refer Cis Client Config )
<cisGenerate /> ( refer Cis Generation)
<service-params /> (refer X-Server Parameters)
<semanticVal /> (refer SemanticValidation)
+ any service configuration tags
</appserver-config>
Note: All the service configuration tags specified in the Service Configuration
section can also be used within appserver-config tag.
Database Configuration
Description:
Database configuration section captures the parameters required to establish
connections to the database.
Syntax:.
<database-config Name="conn1">
<userid Value="user-id" />
<password Value="password" />
<db-url Value="jdbc-url " />
<db-driver Value="driver-class-name" />
<db-meta-info-file Value="meta-info-file" />
<initial-pool-size Value="number[default=1]" />
<max-pool-size Value="number[default=5]" />
<isJdbc2Driver Value="true|false[default=true]" />

<client-info-enabled Value="true|false[default=false]" />

<service-user-map>
<service-user ServiceName="service-name" UserId="user-
id" Repeatable="true" />
</service-user-map>
</database-config>
userid password fields are read to access the database instance
db-driver/db-url specify the database driver and the url of the database instance.
db-meta-info-file property identifies the mappings between logical datatypes used by
the application to the physical datatypes supported by the database. Here are the driver
class names and mapping files to be used for the 62 stack supported db.
Oracle 10g:
<db-driver Value="oracle.jdbc.driver.OracleDriver"/>
<db-meta-info-file Value="com/i2/xcore/dblib/oracle.xml"/>
Make sure ojdbc14.jar compatible with oracle 10g is in the class path.
DB2:
<db-driver Value="com.ibm.db2.jcc.DB2Driver" />
<db-meta-info-file Value="com/i2/xcore/dblib/db2.xml" />
Make sure db2jcc.jar and db2jcc_license_cu.jar are in class path.
isJdbc2Driver : Set it to false if the driver does not support JDBC 2.0 specification.
initial-pool-size: specifies the initial number of database connections that would be
opened
max-pool-size: specifies the maximum number of open database connections. It is
recommended to have the max-pool-size > worker-thread-size + asynch-thread-size to
avoid deadlocks due to connection starvation. Please see server-config tag for details
on worker and asynch threads.
client-info-enabled: This attribute is only applicable to Oracle. Enabling this will set
the client info on the dbms connection to that of the user id who issued the request on
the server.
service-user-map: The service-user-map tag can be used to specify different database
users for specific services. It should be used only for services whose database user is
different than the connection database userid specified under database-config tag.
The service-user tag inside service-user-map tag defines the database UserId for
service specified by ServiceName attribute. Even when you have the service-user-map
setup the database connections are still created with the userid specified under
database-config. Setting up the map results in the affected service generating SQL that
has fully qualified schema entity names e.g. user01.PURCHASE_ORDER. Using this
feature requires that the userid specified under database-config should have complete
(insert/update/delete/select) access to database entities of the mapped database users
specified in service-user-map.
Example:
<database-config Name="conn1">
<userid Value="system" />
<password Value="manager" />

Chapter 7 X-Config
<db-url Value="jdbc:oracle:thin:@corpdev02:1521:omx9idb" />

<db-driver Value="oracle.jdbc.driver.OracleDriver" />
<db-meta-info-file Value="com/i2/xcore/dblib/
oracle_10g.xml" />
<initial-pool-size Value="5" />
<max-pool-size Value="10" />
<isJdbc2Driver Value="true" />
<service-user-map>
<service-user ServiceName="OA" UserId="user01" />
<service-user ServiceName="EM" UserId="user02" />
</service-user-map>
</database-config>
JMS Configuration
Description:
JMS configuration section captures the parameters required to establish logical JMS
connections.
Syntax:
<jms-config Name="connection name">
<destination-type Value="Queue|Topic" />
<dedicated Value="true|false[default=false]" />
<jndi-context-factory Value="jndi context factory" />
<jndi-provider-url Value="jndi provider url" />
<jndi-user-name Value="user name[optional]" />
<jndi-password Value="password[optional]" />
<connection-factory Value="connection factory" />
<authenticate-jms-user
Value="true|false[default=false]" />
<jms-user-name Value="user name[optional]" />
<jms-password Value="password[optional]" />
<inbound-queue Value="inbound queue JNDI name" />
<response-type Value="Blocking|Ignore|# seconds" />
<outbound-queue Value="outbound queue JNDI name" />
<error-queue Value="error queue JNDI name" />
<heartbeat Value="heartbeat target JNDI name[optional]" />
<topic-name Value="topic JNDI name" />
<durable-subscription Value="true|false[default=false]" />
<envelope Value="xyz[default=i2Document]" />
</jms-config>
destination-type indicates whether the logical connection will use physical queues or
topic as the actual destination.
dedicated: Set it to true if the logical JMS connection and the underlying queues/topic
is dedicated to a single receiver(X-Rule or Event).
jndi-context-factory and jndi-provider-url are required to connect to the the JNDI
provider. If JNDI authentication is enabled, provide the jndi-user-name and jndi-
password.
connection-factory is the administrative resouce required to create JMS connections.

authenticate-jms-user: Set it to true if JMS authentication is enabled. If authentication

is enabled, provide jms-user-name and jms-password.
inbound-queue is the JNDI name of the JMS queue in which incoming messages into
ABPP are published by clients.
response-type is the response type for the JMS connection. Following are the valid
values
a. Ignore - indicates that the caller does not require a response . Request is
processed on receiving the message, but response is not sent to the caller.
b. Blocking - indicates that the caller synchronously waits for the response till
response is received or a system time out is reached.
c. #seconds - indicates that the caller synchronously waits for a response till the
response is received or #seconds time out is reached.
outbound-queue is the JNDI name of the JMS queue in which messages flowing out of
ABPP applications are published.
error-queue is the JNDI name of the JMS queue in which incoming messages that
could not be processed for various reasons are published by ABPP.
heartbeat is the JNDI name of a queue or topic depending on the destination type.
When creating a queue connection the heartbeat target should be a queue and for a
topic connection heartbeat target should be a topic. Heartbeat helps to detect JMS
provider availability and reconnects to the provider if required.
topic-name is the JNDI name of the JMS Topic in which incoming and outgoing
messages are published for consumption by ABPP applications as well as external
clients.
durable-subscription: Set it to true if durable subscription has to be enabled for the
topic. Default is false.
Envelope is the the wrapper tag (or root xml tag) for JMS messages sent out of ABPP
application. Root tag of incoming messages is ignored.
Example:
<jms-config Name="TestQueueConnection">
<destination-type Value="Queue" />
<dedicated Value="true" />
<jndi-context-factory
Value="com.tibco.tibjms.naming.TibjmsInitialContextFactory" />
<jndi-provider-url Value="tcp://localhost:7222" />
<jndi-user-name Value="" />
<jndi-password Value="" />
<connection-factory Value="TestQueueConnectionFactory" />
<authenticate-jms-user Value="false" />
<jms-user-name Value="" />
<jms-password Value="" />
<inbound-queue Value="TestInboundQueue" />
<response-type Value="Blocking" />
<outbound-queue Value="TestOutboundQueue" />
<error-queue Value="TestErrorQueue" />

Chapter 7 X-Config
<heartbeat Value="TestHeartbeatQueue" />

<envelope Value="TestEnvelope" />
</jms-config>
Description:
This section contains configuration options that are useful for performance
optimization and also for determining the protocol support that the server would
provide.
Syntax:
<server-config Name="XServer">
<workerThreads Value="number[default=10]" />
<asynchThreads Value="number[default=1]" />
<asynchMaxQueueSize Value="number[default=25]" />
<threadCreateIncrement Value="number[default=10]" />
<threadIdleLimit Value="number[default=25]" />
<listenerPort Value="4444" />
<schedulingPolicy Value="inline|queuing[default=queuing]" /
>
<protocols>
<protocol Value="http|xrmp|tcpa" Repeatable="true" />
<client-soc-timeout Value="timeout-in-
minutes[default=0]" />
<server-soc-backlog Value="number[default=200]" />
</protocols>
</server-config>
WorkerThreads: Number of threads processing the client requests. This setting is
applicable only if :
1. Server is NOT co-located within weblogic and
2. SchedulingPolicy is queuing
In co-located deployments the worker threads are determined by the number of
worker threads configured in web-logic.
AsynchThreads: Number of threads processing asynchronous requests
AsynchQueueSize: Max length of queued up asynchronous requests. The queue size
should be chosen based on the usage of asynchronous tasks by your application.
If queue size is very small, asynchronous requests are persisted in db and executed at a
later time. The persistence and reading from db is an over-head can affect the
performance.
If your application generates a large volume of asynch requests and you have provided
a large queue size then it is possible for your application to run out of memory.
threadCreateIncrement: This property specifies the number of additional threads to be
created and added to the thread pool whenever the pool is empty.

threadIdleLimit: This specifies the max number of threads that can be idle in the
thread pool. All additional thread would be destroyed.
listenerPort: Port the server is listening on.
protocol: A list of the protocols supported by the server. This will be registered with
the locator.
client-soc-timeout: When the server is reading a request from the client on the socket
input stream, the socket read will time out after the specified time out period. This
time out period is in minutes. if client-soc-timeout =0 then is interpreted as an infinite
timeout.
server-soc-backlog: The maximum queue length for incoming connection indications
(a request to connect) is set to this parameter. If a connection indication arrives when
the queue is full, the connection is refused. The backlog parameter must be a positive
value greater than 0. The defaut is 200
schedulingPolicy: if set to inline, a new thread will be created to service each request
which is received. If scheduling policy is set to queuing, requests will be queued. The
queued requests will be serviced by the worker threads.
Example:
<server-config Name="XServer">
<workerThreads Value="5" />
<asynchThreads Value="5" />
<asynchMaxQueueSize Value="10" />
<threadCreateIncrement Value="3" />
<threadIdleLimit Value="12" />
<listenerPort Value="4444" />
<protocols>
<protocol Value="http" />
<protocol Value="xrmp" />
<protocol Value="tcpa" />
<client-soc-timeout Value="0" />
<server-soc-backlog Value="200" />
</protocols>
</server-config>
Schema Generation
Description:
The SchemaGenerate tag contains data configuration information related to database
schema generation for the server. Server will generate schema for all the services
deployed in the server.
Syntax:
<schemaGenerate>
<file Value="schema-output-file" />
<generateTables Value="true|false[default=false]" />
<maxTableNameLength Value="number[default=30]" />
<maxColumnNameLength Value="number[default=30]" />
<schemaContraintPrefix Value="C" Optional="true" />
<schemaIndexPrefix Value="I" Optional="true" />
<databaseSchemaDefinitionFile Value="schema-config-file" />

Chapter 7 X-Config
</schemaGenerate>
file: This file will contain the SQL files generated as part of database schema
generation.
generateTables: If the value of this property is "true" then the server will create the
physical tables in the database. If false then only the DDL sql scripts are generated.
databaseSchemaDefinitionFile: Physical schema configuration file used to configure
table spaces. Here is the structure of a sample Physical Schema Configuration xml
file.
<?xml version="1.0" encoding="UTF-8"?>
<PHYSICAL_SCHEMA_DEFINITION>
<DEFAULT_TABLE_SPACE Name="I2_DOM_TABLE_SPACE" />
<DEFAULT_INDEX_SPACE Name="I2_DOM_INDEX_SPACE" />
<TABLE_SPACE Name="I2_DOM_OA_TXN_TABLE_SPACE1">
<TABLE_NAME Name="CUSTOMER_ORDER" />
<TABLE_NAME Name="ORDER_LINE_ITEM" />
</TABLE_SPACE>
<INDEX_SPACE Name="I2_DOM_OA_TXN_TABLE_SPACE1">
<INDEX_NAME Name="LINE_ITEM_CUSTOMER_ORDER_INDEX" />
</INDEX_SPACE>
</PHYSICAL_SCHEMA_DEFINITION>
Encryption Configuration
Description:
ABPP provides the ability to encrypt any fields on the database. This is performed by
providing the following configuration information.
Syntax:
<cryption>
<securityProvider Value="provider-class-name" />
<securityTransformation Value="algorithm/mode/padding" />
<securityPersistHandler Value="class-for-persisting-
security-key">
<ANY /> 
</securityPersistHandler>
</cryption>
securityProvider: specifies the implementation of the JCE1.2.1 framework.
securityTransformation: specifies the algorithm, mode and padding used for
encryption. Algorithms values can be: DES, DESede, Blowfish[ These are symmetric
algorithms]. Mode values can be: CBC, CFB. Padding values supported is
PKCS5Padding
securityPersistHandler: Specifies the class name which will persist the secret key.
ABPP framework supports the following handlers:
1. com.i2.xcore.serverutil.CryptoIODBImpl: This persists the key in DB.
2. com.i2.xcore.util.CryptoIOFileImpl: This persists the key in a file. You can
optionally provide the <securityKeyLocation Value="any-location"/> as a child
tag. If not provided then it creates SecretKey.ser in the current working directory.

Example:
<cryption>
<securityProvider Value="com.sun.crypto.provider.SunJCE" />
<securityTransformation Value="DES/CBC/PKCS5Padding" />
<securityPersistHandler
Value="com.i2.xcore.serverutil.CryptoIODBImpl" />
</cryption>
Command Line Input

Description:
To enable command line input on the server console (to reload files/to load requests
etc.), use the configuration shown below.
Syntax:
<cmdLineInput Value="true|false[default=false]"/>
Enable JMS
Description:
To enable ABPP rules and events to be exposed through JMS use the configuration
shown below.
Syntax:
<enableJMS Value="true|false[default=false]"/>
Logical Date
Description:
This command re-sets the server's clock to the date-time specified by this tag. This tag
enables the use of data-sets which are set up for a particular date to be run daily in QA
environments.
Syntax:
<logicalDate Value="date-time in mm/dd/yyyy hh:mm:ss format
[default=current-date]"/>
Example:
<logicalDate Value="04/26/2004 00:00:00"/>
WSDL Generation
Description:
The WSDLGenerate tag contains configuration information for generating WSDL
spec files from API signatures. Please refer section on "API_DOC and Web Service
Definitions" for details on specifying API signatures.
Syntax:
<WSDLGenerate>
<apiFilterFile Value="api-filter-file" Optional="true" />
<SOAPAddr Value="SOAP-url" />
<outputDir Value="output-folder-path" />

Chapter 7 X-Config
<accessLevel Value="comma separated access level strings

[default=Public]" />
</WSDLGenerate>
apiFilter can be used to selectively generate WSDL signatures for only a sub-set of
apis defined in the deployed services.
Syntax of the apiFilterFile:
<apiFilter>
<service Name="service-name" Repeatable="true">
<api Name="apiName" Repeatable="true" />
</service>
</apiFilter>
Example:
<apiFilter>
<service Name="ORDER_ADMIN">
<api Name="createPo" />
<api Name="changeLines" />
</service>
<service Name="FMX">
<api Name="uploadExecutionForecast" />
<api Name="uploadPlanningForecast" />
</service>
</apiFilter>
This specifies that for ORDER_ADMIN service only "createPo" and "changeLines"
APIs should be included in the WSDL. Similarly for FMX service only
"uploadExecutionForecast" and "uploadPlanningForecast" APIs should be included.
For other services not mentioned in this file all eligible (default is Public) APIs are
included.
accessLevel: Only apis with access level mentioned in the accessLevel tag value will
be included in the WSDL spec generation. You can specify multiple access levels by
providing the access level strings (Public, Protected, Private) separated by commas.
outputDir: This is the directory in to which the WSDL specs will be written out.
For each deployed Xservice, the WSDL generator will create a folder with the same
name as the service name. Each service folder will contain the WSDL file, <<service-
name>>.WSDL , for the service.
For each Xservice API included in the WSDL spec, the WSDL generator will also
generate the following files in the service folder:
1. XML file containing the 'expanded' form of the API_DOC,
2. XSD file based on the expanded API_DOC XML,
3. VFS file based on the expanded API_DOC XML.
WSDL Client Configuration

Description:
This tag contains configuration information for invoking operations on external
WSDL services.

Syntax:
<wsdl-client-config>
<bindings Optional="true">
<register-types>
<type Name="binding-name"
ExtensilityReaderClass="class-name" RunTimeInvokerClass="class-
name" Repeatable="true" />
</register-types>
<defaultBinding Name="binding-name" />
</bindings>
<wsdlLocations>
<wsdlLocation Value="wsdl-url" Repeatable="true" />
</wsdlLocations>
</wsdl-client-config>
bindings: register-types tag is needed only if you want to register a custom binding.
The system supports SOAP and CIS bindings out of the box. Please contact i2 ABPP
development if you need to add custom binding protocols. defaultBinding is the
binding protocol to choose when invoking operations on a WSDL which supports
multiple bindings.
If no defaultBinding is specified, system will choose SOAP over CIS.
wsdlLocation: Provide the URL of the external WSDL files
Example:
<wsdl-client-config>
<bindings>
<defaultBinding Name="CIS" />
</bindings>
<wsdlLocations>
<wsdlLocation Value=".\wsdl\TM\TMService.wsdl" />
<wsdlLocation Value=".\wsdl\Yahoo\
CurrencyExchangeService.wsdl" />
</wsdlLocations>
</wsdl-client-config>
In the above example, CIS binding will be used for all invocations on
CurrencyExchangeService and TMService.
Cis Client Config

Description:
The Cis client config tag contains additional properties required for invoking web
services using CIS binding .
Syntax:
<cis-client-config>
<property Key="key-name" Value="value" Repeatable="true" />
</cis-client-config>
Here are some of the predefined cis client properties used by the system:
(1) port type.instance.USER, port type.instance.PASSWORD: These are optional
properties. If specified they are used for creating CIS connection for each of the CIS

Chapter 7 X-Config
port type-instance combination. The port-type and instance should match the ones
specified in the CIS binding section of the WSDL.
Example:
<cisClientConfig>
<property Key="TMPort.TMInstance1.USER" Value="admin" />
<property Key="TMPort.TMInstance1.PASSWORD" Value="admin" /
>
</cisClientConfig>
CIS Generation
Description:
The cisGenerate tag contains configuration information for generating cis meta-data
files from API signatures. Please refer section on ABPP CIS support for details on
generating CIS meta data definitions. ABPP CIS support section provides the
instructions to expose all or some of the public APIs of ABPP services through CIS.
Syntax:
<cisGenerate>
<configFile Value="config-file-name" />
<outputDir Value="output-directory-for-metadata and
bindings" />
</cisGenerate>
Please refer section on ABPP CIS support for the format of the the config file and
details on the output.
Example:
<cisGenerate>
<configFile Value="cseCisCfg.xml" />
<outputDir Value="cis" />
</cisGenerate>
X-Server Parameters
Description:
This section lists x-server parameters that are of interest.
activeNavigationService: This is the service in which the navigation workflow is
deployed.
activeUserSecurityService: This is the service that handles user authentication and
authorization.
maxRows: This property controls the number of records that are displayed in all
pagination screens ( typically search screens).
PARALLEL_EXECUTION_OF_ASYNCH_TASKS: true/false. Default is false. If
true then the asynch tasks generated by a transaction are executed in parallel.
Otherwise they are executed sequentially.

SESSION_TIMEOUT: Timeout for the user session in minutes. This is an optional

parameter and the default value is 120 minutes. This parameter should be in-synch or
atleast greater than the web session timeout.
Example:
<service-params>
<param Name="activeNavigationService" Value="BUY_OMX" />
<param Name="activeUserSecurityService" Value="BUY_OMX" />
<param Name="maxRows" Value="10" />
<param Name=" PARALLEL_EXECUTION_OF_ASYNCH_TASKS"
Value="true" />
<param Name="SESSION_TIMEOUT" Value="30" Comment="In
minutes" />
</service-params>
Services Override Configuration

Description:
This configuration enables the user to override few service level configurations like
Logger, Service Parameters and IDGen. This is especially useful when the service is
an archived service and it is not possible to change the service configuration file. The
configuration values defined under <service-override> take precedence irrespective of
service customizations.
Syntax:
<services-override>
<service-override Name="name-of-the-service-to-override"
Repeatable="true">
<logger Optional="true">

</logger>
<service-params Optional="true">

</service-params>
<idgen Optional="true">

</idgen>
</service-override>
</services-override>
Example:
<services-override>
<service-override Name="bookstore">
<service-params>
<param Name="testParam1" Value="val2"/>
</service-params>
<idgen>
<document Name="CustomerOrder" prefix="CO"
delimiter="-" sequenceName="CO"

Chapter 7 X-Config
blockSize="10"/>
</idgen>
<logger>
<file Name="../log/bookstore1.log" Overwrite="true"
NumBackups="3" MaxSize="101MB"/>
<brief-console Value="true"/>
<logLevels>
<logLevel Value="Exception"/>
<logLevel Value="Error"/>
</logLevels>
</logger>
</service-override>
</services-override>

Chapter 8
Workflow Concepts
Business process workflows are an integral part of ABPP service development.

Workflow enables you to model a business process as a set of nodes which are to be
executed in a sequence. You can also use conditional logic to specify the sequence.
The workflow is similar to a UML activity diagram where the activities are executed
within the workflow nodes.
Every workflow is part of a service and contains the following attributes:
1. Name : The workflow name should be unique within the service defining the
workflow
2. One or more start nodes. Every workflow starts its execution from one of the
start nodes and continues to execute its next nodes.
3. A set of nodes: Each node specifies the next nodes to execute after it is executed.
4. One or more done nodes: Workflow is terminated as soon as it reaches a done
node by executing through the next nodes.
5. Set of variables called pipe-line variables: Pipe-line variables are global to the
workflow. They can be mutated by actions in various nodes of the workflow. The
variable types are limited to the data-types natively supported by ABPP: boolean,
string, int, long, float, double, date, datetime, time and xml.
The following are example node types:
z Start node: used as the starting point of the workflow
z Done node: used to signify the end of the workflow
z Task node: used for processing business logic
z Branch node: used for providing branching behavior, moving the workflow in a
number of directions based upon condition.
z UI node: used for displaying a web page in order to obtain user input.
z Subworkflow node: used to call another workflow as a part of the current
workflow
z WSDL node: like a task node, but used to call out to a web service.

Chapter 8 Workflow Concepts
Workflow nodes are connected with connectors. Connectors can either be conditional
(that is, with a condition attached to them), or simple (always followed).
Some workflow nodes have actions. Actions are the means by which a node executes
business logic. A workflow developer will implement workflow action logic using
ABPP business process language (X-Rule).
You can create many instances of the same workflow with different input parameters.
For example, you can create an order create workflow which validates and saves the
order in the correct state. An instance of this workflow will be created to process each
order created in the application. In our discussion, the workflow is referred to as
“workflow template”. Any instance of the workflow is referred to as “workflow
instance”.
This document explains the workflow concepts. For mechanics of creating the
workflow, please refer to the studio user guide.
Generic Event Node

Some of the workflow nodes execute pre actions and then wait for an external signal
to continue their processing. Upon receiving the external signal, the node continues
executing the post actions and then the next nodes of that node. Examples of these
nodes are: Event, Timer, UI node, Subworkflow node etc. These nodes will be
referred to in this document as “generic event nodes”.
Workflow Execution
A workflow is kicked off through a start node and it continues execution until it
reaches a wait state. A wait state is one where all the workflow paths reach a generic
event node or done node. Once the workflow reaches done node through any path,
then it ceases to exist. The workflow resumes execution when one of the generic event
nodes, on which the workflow is waiting, is triggered. Again the workflow continues
execution of the next nodes until it reaches a wait state. The workflow execution, until
it reaches a wait state, is performed in a single transaction. The transaction is same as
the thread that initiated the workflow by explicit instantiation or by triggering the
generic event node.
Variables
Workflow actions employ the use of variables.
Node Input & Output variables:

Most nodes have input or output variables or both.
These variables are only available, or “in scope”, during the execution of that
workflow node.
The node input can be accessed by referring to the input variable name in the sections
where it is accessible.

Variables
Implicit Variables
Here is a list of implicit workflow variables and their descriptions:
z thisReturn: All of the workflow nodes have access to this implicit return
variable. Once the workflow reaches a wait state, the value of thisReturn is
returned to the caller as the workflow return.
z thisParam: Nodes also have access to the implicit input parameter variable,
thisParam. If the node is executed as part of the workflow start node execution,
then the thisParam will contain the parameters passed to the workflow start node.
If the node is executed as part of an external signal issued to a “Generic Event
Node” then the thisParam will contain the signal payload.
z workflowId: Id of the workflow instance
z workflowName: Name of the workflow template
z thisStartDate: date-time when the workflow was created.
Pipeline Variables
Workflows also have pipeline variables. Pipeline variables are in scope during the life
of that workflow. (Note: pipeline variables for a workflow are not available in any
subworkflows called that workflow.)
The following pipe-line variables are reserved. You will still need to create them
manually in the pipe-line editor:
z thisStartedBy: This variable should be assigned the value of the user id creating
the workflow instance.
z thisPrimaryDocId: This is the id of the primary document on which the
workflow is being executed. Example, if you have a workflow to model the life
cycle of a Sales Order, then the primary document of the workflow is Sales Order.
The id of the sales order instance should be assigned to this pipe line variable.
It is recommended to assign the values to these reserved variables in the start node.
You can search the workflow instances using the value of these reserved variables.
You cannot search for workflow instances using the values of the other pipe-line
variables. Hence the reserved pipe-line variables are useful in identifying workflow
instances to monitor their state of execution and cancel them if needed.
The following screen show the editors for creating pipe line variables:

Figure 1 Pipeline variable dialog
Workflow Properties
The following screen shot shows the work flow properties editor page in the ABPP
studio.

Workflow Properties
Here is a description of the workflow properties:

z Name (Required): This is the name of the workflow. The workflow name must be
unique within the service in which it is deployed.
z Description (Optional): This is for documenting the intent of the workflow
z Type (Optional): Type of the workflow. You can use this field to logically group a
set of related workflows.
| Example, In an Order Management Application, You can logically group
workflows as Order, Shipment and Receipt workflows.
This is a searchable field. So you can search the active workflow instances of a
particular type.
z Primary Document (Optional): This is primary document on which the workflow
is being executed. This field is also used to logically group a set of related
workflows. This field can be used to further classify workflows of the same type
based on the document on which they operate.
| Example, Workflow type can be used to classify workflows as Order,
Shipment and Receipt workflows. The order workflows can be further

classified as Purchase Order, Replenishment Order, and Transfer Order based

on the document on which they operate.
Alternately you can use this to classify workflows in a different dimension than
the workflow type.
| Example, Workflow type can be used to classify workflows as Creation,
Change and Cancel workflows. The primary document can be used to
independently classify workflows as Purchase Order, Replenishment Order,
and Transfer Order based on the document on which they operate.
This is a searchable field. So you can search the active workflow instances of a
particular type.
z IsExtenalStartAllowed (Optional): true/false, Default=true. This is used to
indicate if this workflow can be explicitly instantiated by an external application.
If this is false, the workflow cannot be instantiated.
z Log Workflow(Optional): true/false/default. This is used to indicate if the
workflow should be logged. This is useful if the user has to monitor the workflow.
If false or empty then the workflow is not logged, if set to true the workflow is
logged in the database. If the value is set to default, then value for
NodeEventListener variable defined at the service level is used. For more details
refer to the “Workflow Logging”section
z Shutdown Handler (Optional): The handler for workflow cancellation. Some
times it is necessary to cancel a long running workflow. So ABPP provides
commands for cancelling a workflow. However depending on the state of the
workflow, you might want to do one of the following:
| Disallow cancellation.
| Allow Cancellation after performing some clean up tasks.
Shut down handler allows you to conditionally allow or disallow cancellation.
Here are the properties of the shutdown handler
z Check Condition: X-path expression that evaluates to a boolean. If true,
then cancellation is allowed. This expression has access to the variables
defined in the pre-actions of the shut down handler, pipe-line variables
and workflow implicit variables.
z Pre-actions: Actions executed before the check condition is evaluated
z Post-actions: Action executed if check condition evaluates to true.
Here is how the shut down handler works on receiving a cancellation request for
the workflow
| Executes the X-Rules specified in pre-actions
| Evaluates the X-Path expression specified in check condition text box. If it
evaluates to false, the cancellation is disallowed.
| If the check condition evaluates to true, execute the post actions. The post
actions are meant for performing any clean up tasks before the cancellation.
| If shut down condition is not provided, it defaults to true.
If shut down handler is not provided for a workflow, then the instances of the
workflow can be cancelled unconditionally.

Workflow Nodes
Workflow Nodes
This section describes the built in work flow nodes in detail.
Start Node
As the name implies this is the starting node for workflow execution. The following
screen shows the start node property editor:
Figure 2 Start node property editor
Here is a description of the start node properties:

z Name (Required): This is the name of the start node. The node name must be
unique within the workflow.
z Description (Optional): This is for documenting the node description
z Node Output (Optional): The output variable of the start node and the type of the
variable
z Actions (Optional): X-Rule actions to be executed
z Event Descriptors (Optional): Event or Request descriptors attached to the start
node. Please see “Events and Requests”chapter in Part Two of the Programmer’s

Reference Guide for more details on event and request descriptors. When the
corresponding event is raised or the request is invoked, a new workflow instance
will be created by the system. The workflow instance will start executing from the
start node.
z IsDefault (Optional): true/false. For start node not attached to an event/request
descriptor, the system implicitly assigns this property to true. So this property
setting is applicable only for start nodes attached to an event/request descriptor.
There can be many start nodes in a workflow. But only one of them can be a
default node.
The following properties editor shows the selection of Event/Request descriptor.
A workflow can be instantiated in two ways:

1. By Explicit instantiation using START_WORKFLOW Command. The
workflow will start executing from the default start node. Here is an example of
explicit instantiation of a workflow:
<START_WORKFLOW>
<TEMPLATE Value="orderCreateWfl" />
<ADDITIONAL_PARAMETERS>
<ORDER_ID Value="ddd" />
<MERCHANT_ID Value="mmm" />
</ADDITIONAL_PARAMETERS>
</START_WORKFLOW>
In the above snippet, orderCreateWfl is the name of the workflow.

Workflow Nodes
The user interface node (UINodes) requires solution parameters (example, web
context path, home page URL etc) and user session parameters (session id) for
execution. Hence the UI workflows (i.e., workflows containing UINodes) cannot
be instantiated using the START_WORKFLOW command. The UI workflows are
launched from the left navigation using the ui:pad-item PGL component. The
PGL component instantiates the UI workflows through a special command,
UI_START_WORKFLOW, and will transparently pass the solution and session
specific parameters required to execute the UINodes. The
UI_START_WORKFLOW command is not described here since the invocation is
transparent to the user developing the UI workflows.
2. By raising an event or invoking a request. A workflow can be instantiated by
raising an event or invoking a request if the start node is attached to the
corresponding event/request descriptor. The workflow will start executing from
the start node attached to the event/request descriptor.
Here is an example:
Assume that start node (S1) of workflow template (myWorkflow) is associated
with the event descriptor, foo. Whenever the event foo is raised, an instance of
myWorkflow is created and will start executing from the node S1.
Here is a sample showing how to raise the event, foo
<RAISE_EVENT Name=”foo”>
<!-- body specific to foo. In our example, it is empty -
->
</RAISE_EVENT>
Task Node
A task node is a simple node for performing an action. The following screen shows the
property editor for a task node:

Figure 3 Task node property editor
Here is a description of task node properties:

z Name (Required): name of the task node
z Description (Optional) : brief description
z Node input / Type (Optional): name and type of input variable
z Node output / Type (Optional): name and type of output variable
z Actions (Optional): X-Rule code for performing the tasks
Event Node
An event node allows the workflow to wait for an incoming signal (event or
command) before continuing the workflow. The incoming signal on which the event
node should wait is specified by associating the event node with an event/request
descriptor.
Here is a screen shot of event node properties:

Workflow Nodes
Figure 4 Event node property editor
The available fields:

z Name (Required): name of the event node
z Description (Optional): brief description
z Expiration Date (Optional): This is the date until which the node will wait for
the event to occur. If the event occurs within this time, the execution will continue
with the next nodes specified as “default”. If the event does not occur within this
time, the execution will continue with the next nodes specified as “on-expiry”.
The expiration date can be an X-Path expression or a literal date in mm/dd/YYYY
format. If expiration date is not specified then the event node will fait for infinite
time for the event to occur.
z Node Input/Type (Optional): name and type of input variable
z Node Output/Type (default) (Optional): name and type of output variable for
the next nodes of default condition. The default condition corresponds to the case
when the event occurs before the expiration date.

z Node Output/Type (on-expiry) (Optional): name and type of output variable for
the next nodes of on-expiry condition. The on-expiry condition corresponds to the
case when the event does not occur before the expiration date.
z Event Handling Tab (Required): for specifying the event descriptor which
triggers this event node and also provide the matching keys for filtering the event
based on keys specified.
z Pre-Actions Tab (Optional): for editing the node pre-action
z Post-Actions Tab (Optional): for editing the node post-action
z Expiration Actions Tab (Optional): for editing the actions to be performed
when the event does not occur before the expiration date specified.
There are 2 exit conditions for the event node:

z default: This condition corresponds to the case when the event occurs before the
expiration date.
z on-expiry: This condition corresponds to the case when the event does not occur
before the expiration date.
Each of the next nodes of the event node must be associated with one of these
conditions. Here is an example showing an event node with next nodes wired for both
the conditions:
Every event descriptor can optionally define one or more keys. The intent of the keys
to allow the event node to filter the events based on the values specified in the event
body. Each event descriptor key is an X-Path expression that identifies the values of
interest on the event body. The event node defines X-Path expressions for matching
key values for each of the key values defined in the event descriptor.
If the event node can also be associated with a request descriptor, the matching keys
are applied to filter the commands in the same way as it is used to filter events.
Note: The X-Path expressions for the keys (defined within the event node) have
access to variables defined in the pre-actions, pipe-line variables and
workflow implicit variables.

Workflow Nodes
When the workflow initially reaches the event node,

1. The node’s pre-action will be executed.
2. The matching key values are computed by evaluating the corresponding X-Path
expression.
3. Now the node is in a wait state for the incoming signal.
The node resumes execution when:
1. The system receives an incoming signal (event or request) with the same name as
the event/request descriptor associated with the event node
2. The key values evaluated on the event/request are same as the “matching” key
values computed for the event node before it went to the wait state. The event
node is activated with the default condition
OR
1. The incomming signal (event or request ) is not received before the expiration
date specified on the node. The event node is activated with the on-expiry
condition.
Once an event node is activated with “default” condition:

1. The post-action will be executed.
2. Then the execution will move on to the next nodes of the event node which are
associated with the default condition.
Once an event node is activated with “on-expiry” condition:

1. The expiration-actions will be executed.
2. Then the execution will move on to the next nodes of the event node which are
associated with the on-expiry condition.
Example:
Consider the following event:
<event_descriptor Name="newForecastArrived"
Category="FORECAST">
<EVENT_DOC>
<RAISE_EVENT Name="newForecastArrived">
<FCST_LINE_ID Value="xxx"/>
<RAISE_EVENT/>
</EVENT_DOC>
<keys>
<key Value="$thisParam/FCST_LINE_ID/@Value"/>
</keys>
</event_descriptor>
Assume that an event node (Name = myEventNode) is part of a workflow,
myWorkflow, with:
a. Event descriptor of newForecastArrived.

b. Matching key X-Path expression that identifies a forecast line ($fcLineId)

using a pipe line variable.
Assume that the following set of actions were performed:
1. myWorkflow is instantiated ( instance id = wf-1)
2. Pipe-line variable, $fcLineId, is assigned a value of ‘FC_LINE_101’ as part of
start node actions.
3. As part of workflow execution, the event node is executed.
Now we have a workflow instance (wf-1) whose event node (myEventNode) is
waiting on newForecastArrived event whose forecast line id is FC_LINE_101.
The event node will wake up and resume execution if the newForecastArrived event is
raised with the following body:
<RAISE_EVENT Name="newForecastArrived">
<FCST_LINE_ID Value=" FC_LINE_101"/>
<RAISE_EVENT/>
Decision Node
A decision node is a basic branch node, which allows for branching on a single
condition. The property editor is the following:

Workflow Nodes
Figure 5 Decision node property editor

z Name (Required): name of the decision node
z Condition Expression (Required): X-Path expression for decision
condition.This should evaluate to true or false.
Note: Condition expression has access only to variables defined in actions, pipe-line
variables and workflow implicit variables.
z Node Output / Type (true) (Optional): name and type of output variable, should
the condition evaluate to true.
z Node Output / Type (false) (Optional): name and type of output variable, should
the condition evaluate to false
z Actions Tab (Optional): for editing the node action
When the workflow executes the decision node:
1. The node’s pre-action will be executed.

2. The condition expression is evaluated.

3. If condition is true, the next nodes that are attached to true outcome will be
executed.
4. If condition is false, the next nodes that are attached to false outcome will be
executed.
Branch Node
A branch node is a node for more complex workflow branching behavior. Whereas a
decision node branches on one condition, the number of conditions for a branch node
is unbounded.
Figure 6 Branch Node property editor

z Name (Required): name of the node

Workflow Nodes
z Node output / Type: This is not used and will be removed in future releases.
z Actions Tab (Optional): for editing the node action
z Condition Settings Tab (Required): specifies the set of conditions on which to
branch. You can associate each of the connectors from the branch node with these
conditions.
Note: The condition expression can only access variables defined in node actions,
pipe-line variables and workflow implicit variables.
When the workflow reaches the branch node:

1. The node’s actions will be executed.
2. The expressions in the condition settings are evaluated in the order they were
specified.
3. If any expression evaluates to true, then the next nodes associated with that
condition is executed.
4. Other expressions in the condition settings will not be evaluated.
It is important to specify the order in which the Condition Expressions should be
executed.
Subworkflow Node
A subworkflow node is used to call another workflow. When the called workflow
completes, the calling workflow continues. Pre-actions are called prior to calling the
subworkflow. Post-actions are called when control flow returns from the
subworkflow. The property editor is the following:

Figure 7 Subworkflow property editor

z Service (Required): the ABPP service that contains the subworkflow to call
z Workflow (Required): the name of the workflow to call.
z Input Tab (Optional): for specifying an XML element which will be the input
data for the called subworkflow
z Pre-Actions (Optional): for specifying the pre-action script
z Post-Actions (Optional): for specifying the post-action script
z Assign Output (Optional): variable that contains the subworkflow output.
When the workflow reaches the subworkflow node,
1. The node’s pre-actions will be executed.

Workflow Nodes
2. The subworkflow input xml is evaluated.

3. The subworkflow is launched.
4. The workflow enters in to a wait state and will resume execution once the
subworkflow completes.
Once the subworkflow completes,
1. the output of the subworkflow (thisReturn variable in the subworkflow done
node) is assigned to the variable specified in the assign output setting.
2. Then the post-actions are executed. The workflow continues executing the next
nodes.
There are 2 exit conditions for the subworkflow node:

z default: This condition corresponds to the case when the subworkflow execution
completes successfully.
z exception: This condition corresponds to the case where there is an exception
during subworkflow execution. This allows the parent workflow to handle
exceptions from a child subworkflow.
The exit condition can be selected by right clicking on the link and selecting the
‘Select Condition’ menu option. Each of the next nodes of the subworkflow node must
be associated with one of these conditions. By default they are associated with the
default condition. It is not mandatory to have the exception condition next nodes. Here
is an example showing a subworkflow node with next nodes wired for both the
conditions:
The output from subworkflow node in case of exception is of type ‘exception’. The
exception next nodes (i.e. those connected by the exception link) can get access to the
exception by defining an input variable of type ‘exception’ as shown below:

The structure of this exception variable (‘e’ shown above) is same as the exception
variable available inside CATCH statement as defined in “TRY-CATCH-THROW”
component. The user can re-throw this exception by using the THROW statement or
can continue normal execution.
If a subworkflow node does not have any exception next nodes and the subworkflow
execution results in an exception, then that exception will keep propagating up the call
hierarchy until it is handled. If it is never handled an error response is returned to the
external caller.
Timer Node
A timer node halts the workflow execution until the expiration date time specified.
The property editor is the following:

Workflow Nodes
Figure 8 Timer node property editor

z Name (Required): name of the timer node
z Expiration Datetime expression (Required): an X-Path expression to get the
date/time when the workflow should resume execution.
Note: The date time expression has access only to variables defined in pre-actions,
pipe-line variables and workflow implicit variables.
When the workflow reaches the timer node,

1. The node’s pre-actions will be executed.
2. The expiration date time expression is evaluated to compute the expiration date
time.
3. The node registers a call back with the timer-sink service using the expiration date
time as the call back date time.
4. The workflow enters in to a wait state and will resume execution once the timer
service invokes the call back.
Once the timer-sink service invokes the call-back,
1. The post-actions will be executed.
2. The workflow continues executing the next nodes.

Note: The timer node requires the timer-sink service. Make sure you deploy this
service in the process if you are using timer node in any of your services. For
details on timer sink service, refer to “Timer Service” chapter in Part Three of
the PRogrammer’s Reference Guide.
OR Node
A OR node allows execution of the workflow through its next nodes when the
workflow reaches the OR node initially through one of the input connectors. After the
initial execution, it will block execution of next nodes when it is reached through the
other input connectors.
The next nodes of the OR node will be executed only once. This happens when the OR
node is reached for the first time through one of the input connectors.
A typical use of an OR node would be in situations where you want at least one among
a set of tasks to finish before continuing with the workflow. For example, consider an
item introduction workflow where the item needs to be approved by at least one of the
plants in the organization. You can model this with an OR node whose input
connectors are the success outputs of each of the plant approval subworkflows. The
output of the OR node would connect to the task that marks the item as introduced.
Figure 9 OR node property editor

z Name (Required) : name of the node
AND Node
AND node blocks execution of the workflow through its next nodes until all the
workflow paths represented by its input connectors have been executed.
So the next nodes of the AND node will be executed only once. This happens after the
AND node is reached by all of its input connectors.
A typical use of an AND node would be in situations where you want a set of tasks to
finish before continuing with the workflow. For example, you might want the
invoicing and delivery subworkflows of an order fulfillment workflow to be complete
before you mark the order as fulfilled. However the invoicing and delivery
subworkflows can execute in parallel after the shipping subworkflow is complete. You
can model this with an AND node whose input connectors are the outputs of invoicing

Workflow Nodes
and delivery workflows. The output of the AND node would connect to the task that
marks the order as fulfilled.
Figure 10 AND node property editor

Asynch Task Node

The workflow engine enforces the following transaction behavior: “Any database
operation performed, from the point a workflow execution kicks off (either through
workflow instantiation or triggering of an event on which the workflow is waiting) to
the point it reaches a wait state, will be treated as part of the same database transaction
that initiated the workflow kick off. Any changes to the workflow state (changes to
pipeline variable and workflow history) are also persisted in to the database as part of
the same database transaction.”
In order to provide the above mentioned transaction behavior, it is necessary that the
entire workflow execution from kick off to wait state is performed sequentially in a
single thread. As such even if a node has multiple next nodes, these next nodes are
executed sequentially in some arbitrary order. In some situations, we might want to
the next nodes of a node to be executed in parallel to get higher workflow throughput
at the expense of violating the transaction behavior.
The workflow engine relies on the underlying database transaction to manage its state.
Database locking is used to ensure that the execution of a workflow instance is
serialized to ensure that its state is consistent. Executing the nodes of a workflow
instance in parallel poses problems with respect to managing the workflow state.
Examples,
z How do we resolve if the parallel executing nodes mutilate the same pipe-line
variable?
z How do we ensure that each of the parallel executing nodes have access to a
consistent snap shot of pipe-line variables?
The Asynch Task Node executes the actions contained within it in parallel with any
other workflow execution. The node actions are executed in a separate transaction
than that of the workflow. Also these actions are provided a read-only access to pipe-
line variables. As such the node actions cannot alter the workflow state. As soon as the

node actions are executed, the workflow instance resumes the execution of its next
nodes in a new transaction. This new transaction will first acquire a database lock on
the workflow instance to ensure consistency of workflow state. Any execution
performed from this point on will follow the workflow transaction behavior. The
benefit of using Asynch Task node (as compared to a task node) is that the node
actions are executed in parallel with any other workflow execution.
Example:
This examples illustrates a situation where asynch task nodes can be used to improve
workflow throughput.
Consider a workflow with the following steps:
1. Move sales data from source (A) in to the current database using informatica
transform. Assume that this transform takes 3 hours to run.
2. Move sales data from source (B) in to the current database using informatica
transform. Assume that this transform takes 4 hours to run.
3. After (1) and (2) are complete, run a stored procedure on the current database to
generate an aggregate sales report. Assume this step takes 2 hours.
The above workflow can be modeled using task nodes as follows:
This workflow will take 9 (= 3 + 4 + 2) hours to complete. The task nodes

move_data_from_sourceA and move_data_from_sourceB are executed sequentially
because of the transaction policy.
The informatica transform executed within nodes, move_data_from_sourceA and
move_data_from_sourceA, runs as a separate process. So the nodes do not execute
any database operations in the database transaction that instantiated the workflow.
This provides us an opportunity to increase the throughput of the workflow by
replacing the task nodes, move_data_from_sourceA and move_data_from_sourceA,
with Asynch task nodes. With this change the asynch task nodes will execute in
parallel and hence the workflow will only take 6 (= Max(3,4) + 2) hours to complete.
Here is the workflow with the modification:

Workflow Nodes
In general, replacing set of parallel Task nodes with Asynch Task nodes can improve
performance when:
z Each of the task actions are taking a long time to complete
AND
z The task actions can be executed in a different transaction than that of the
workflow.
Here is a screen shot of the Asynch Task node properties:
The node properties are identical to that of Task node. Here is the description of the
properties:
z Name (Required): name of the task node


z Actions (Optional): X-Rule code for performing the tasks
Note: This node has read-only access to pipe-line variables. Any changes made to
pipe-line variables within the actions code will be discarded after the node is
exited.
Wsdl Node
A WSDL node is used to invoke a web service. These web services are typically
hosted remotely. Web services must be configured prior to adding a WSDL node to
the workflow. (Note: see “Web Service Configuration” of Studio User Guide for more
information on configuring web services.).
The property editor for a WSDL node is the following:

Workflow Nodes
Figure 11 WSDL node property editor

z Timeout (Optional): The time out in milliseconds for establishing the HTTP
connection. This is applicable only for HTTP/SOAP binding. The default is 0
which results in no time out.

z Binding URL (Optional): This URL overrides the URL specified in the WSDL
file for the web-service. You can provide a literal URL or an X-Path expression
enclosed by {}.
Note: The binding URL expression can access only variables defined in
WsdlTransformInput actions, pipe-line variables, workflow implicit variables
and service parameters.
z Binding Type (Optional): This binding type overrides the default value specified
in the Xserver configuration. If left as ‘DEFAULT’, the chosen binding type will
be that specified in the Xserver. If a default binding is not set in the xserver, the
binding type will default to SOAP.
z Wsdl Transform Input (Required): Contains transformation actions for creating
the WSDL input
z Wsdl Transform Output (Required): Contains actions to be performed that act
on the web-service output.
z Wsdl Authentication (Optional): If the web service host needs authentication
information then this tab allows the user to override authentication information
specified at the WSDL level (Refer to Web Service Configuration chapter of the
Studio User Guide). This is only applicable for SOAP binding.
When the workflow reaches the WSDL node,
1. The actions specified in Wsdl Transform Input will be executed. The actions will
result in creating the variable (Wsdl + input-part-name + In) containing the input
xml to the web service. The input-part-name is the name of the input message part
of this WSDL operation in the WSDL spec.
2. It will compute the binding URL if an X-Path expression is provided.
3. The call is made to the web service. The type of binding used for web service
invocation depends on the chosen binding Type.
4. The output from the web-service call is assigned to a variable (Wsdl + output-
part-name + Out for a success response and WsdlFaultOut for a fault response)
and is now accessible to the actions specified in the WSDL Transform Output tab.
The output-part-name is the name of the output message part of this WSDL
operation in the WSDL spec.
Note: Only one of Wsdl+output-part-name+Out or WsdlFaultOut will be available.

The structure of the WsdlFaultOut will be as defined by SOAP 1.1:
<SOAP-ENV:Fault xmlns:SOAP-ENV="http://
schemas.xmlsoap.org/soap/envelope/">
<faultcode>...</faultcode>
<faultstring>...</faultstring>
<detail>...</detail>
</SOAP-ENV:Fault>
5. The actions specified in the WSDL Transform Output tab are executed.
6. The workflow continues executing the next nodes.

Workflow Nodes
The Wsdl Authentication tab as shown below allows the user to override
authentication information specified at the web service level.
Various fields on this tab are:

override: Enables the username/password text boxes and allows the user to override
the values specified at web service level.
username: User name to be used for the authentication type specified for the web
service. The value specified can be a string value or an X-Path expression without
using {}.
password: Password to be used for the authentication type specified for the web
service. The value specified can be a string value or an X-Path expression without
using {}.
expression: This checkbox applies only to the password text field. If the password
specified is an X-Path expression then this flag should be selected.

encrypted: This checkbox applies only to the password field. If the password is not an
X-Path expression then this checkbox can be selected to encrypt the password before
it is saved to the workflow file.
There are 2 exit conditions for the WSDL node:

z default: This condition corresponds to the case when the web service call
completes with a success or a fault response.
z exception: This condition corresponds to the case when there is a system
exception during the web service call. Examples of system exception are invalid
web service URL, unavailable target server.
The exit condition can be selected by right clicking on the link and selecting the
condition under ‘Select Condition’ menu option. Each of the next nodes of the WSDL
node must be associated with one of these conditions. By default they are associated
with the default condition. It is not mandatory to have the exception condition next
nodes.
Here is an example showing a WSDL node with next nodes wired for both the
conditions:
The output from WSDL node in case of exception is of type ‘exception’. The
exception next nodes (i.e. those connected by the exception link) can get access to the
exception by defining an input variable of type ‘exception’ as shown below:

Workflow Nodes
The structure of this exception variable (‘e’ shown above) is same as the exception
variable available inside CATCH statement as defined in “TRY-CATCH-THROW”
component. The user can re-throw this exception by using the THROW statement or
can continue normal execution.
If a WSDL node does not have any exception next nodes and there is a system
exception, then that exception will keep propagating up the call hierarchy until it is
handled. If it is never handled an error response is returned to the external caller.
Before invoking WSDL nodes, the corresponding WSDL spec must be loaded by the
ABPP run-time engine. When you activate a WSDL spec in the studio, it makes the
necessary entries for registering the spec in the process configuration (xserver.xml)
file. If you are interested in how the WSDL specs are registered with run-time, refer to
“WSDL Client Configuration” section of this guide.
It is also possible to configure the WSDL invocations to use CIS binding instead of
SOAP/HTTP binding. For more information on using this option, refer to”Making

Operations and Notifications of Existing CIS Applications available in ABPP” section

of Part Three of the Programmer’s Reference Guide..
You can also expose the public APIs of your service as web-services. For more details
on this, refer to “Web Services Definitions” chapter in Part Three of the Programmer’s
Reference Guide.
UI Node
The UI Node is intended for building UI workflows. Each UI node corresponds to a

web page.
Here are the properties of a UI node:
z Name (Required): Name of the node
z Description (Optional): Brief description
z Show breadcrumbs (Optional): true/false (Default=false). Shows or Hides the
display of bread crumbs in the web page rendered by this node.
z Include node in bread crumbs (Optional): true/false (Default=false). If true, the
node should show up in the bread crumb. The bread crumb text will be the same
as the node name.
The following section discusses the tabs of the UI Node:
Layout: This defines how the page should be rendered on the web browser. The
layout is defined using the PGL (Page Layout specification) and stored in a separate
file with .pgl extension in the same folder as the workflow. The UI node stores the
reference to the pgl file.

Workflow Nodes
Pre-Processing: Pre-processing is for creating the input for the PGL layout. This
input is assigned to the variable, pglFormInput.

Post-Processing: This is for performing any actions after the user executes a web
page action – such as a link, a button, etc on the web page. Any data entered/modified
and the actions performed by the user on the web page are available as pglFormOutput
variable.

Workflow Nodes
Next Nodes: This tab contains a list of web page actions that can be performed by the
user on the web page of this UI Node. This list is automatically populated by
inspecting action-enabled components (such as a button, link, etc.) in the PGL layout
referenced by the node. You can associate the outbound connectors (next nodes) of a
UI node with web page actions listed in this tab. After completing the post-processing,
the workflow will start executing the next nodes associated with the web page action
performed by the user. If the user action does not match the ones defined in the next
nodes tab, it will execute the nodes associated with the default condition, true ().

Over-view of UI Node:
In a typical post-deployment scenario, access to a User Interface activates a UI
Workflow through the invocation of a start node (/start.x2ps). The data-binding, pre-
processing, post-processing and presentation logic are controlled through the UI
workflow services. This workflow service interacts with other application framework
services and brings the PGL UI live with data on the web.
Step 1. Initial data for UI Node

The initial data for a UI Node consists of the node input variable and the $thisParam.
The node input variable is a single parameter specified as part of the pre-action step.
Currently, it can be any valid name and be of any of the following types: string, int,
float, double, data or XML. It is recommended that the node input variable be named
nodeInputXml with a type of XML. This will aid in UI workflow maintenance and
provide flexibility in passing additional data as the need arises.
The $thisParam is akin to the request parameters for a servlet-based page. The data is
stored as an XML structure based on the query parameters and posted data of the

Workflow Nodes
request. For example, the URL http://localhost:7001/core/

view.x2ps?ID=123&TYPE=PO would be stored as the following:
<PARAMETERS>
<ID Value=”123”/>
<TYPE Value=”PO”/>
</ PARAMETERS >
Step 2. Pre-processing of data
The Pre-Processing step of a UI Node is primarily used to construct the input data for
the PGL rendering. Using the node input variable and the $thisParam variable, the
logic can make various web service or X-core rule calls to create the $pglFormInput
data. The $pglFormInput data represents the raw XML data sent to the PGL rendering
engine for processing.
Step 3. Data into page rendering
The PGL page uses two data input sources, $root and $this. The $root variable holds
a handle to the $pglFormInput variable that is created in the Pre-Action step. The
$this variable is the PGL representation of the $thisParam from the Pre-Action step.
Some of the PGL components have a select attribute that can be used to narrow the
data processed by its child components. In this scenario, $root does not need to be
directly referenced.
Step 4. Generate HTML data
The PGL Look and Feel (LAF) rendering engine processes the input data with the
PGL page’s object tree to create a complete HTML page. The generated HTML is
sent to the browser and the workflow waits for user interaction.
Step 5. Submitted data
The user interacts with the generated HTML page by modifying its data and selecting
a button action. This action is stored as a string in the $userAction variable. This
value typically relates to the selected button id. The submitted data and the query
parameters are converted to XML and stored in the $pglFormOutput variable. For
backwards compatibility, the data is also available in $thisParam but this practice
should be avoided where possible.
Step 6. Post-processing of data
The Post-Action step of the UI Node is used for doing logic from multiple button
actions before returning control to the workflow. All logic can be done across all
actions instead of in workflow task nodes but this is considered bad practice.
Step 7. Data result from UI Node
After post processing, the next nodes corresponding to the web action performed by
the user are executed. The node output variable to be used is determined by the
output variable specified for the corresponding user action in the Next Nodes table. If
the user action does not match the ones defined in the next nodes tab, it will execute
the next nodes associated with the default condition, true () with the output variable
specified for this condition. The node output variable can be of type string, int, float,
double, date or XML. In a self loop on the UI Node, the node output variable becomes
the node input variable for the UI node’s Pre-Processing step.

Search Node
The Search Node component is intended to ease the building of Search pages. A
search page has a search container (Search Form) where the user can enter the filter
criteria for the search and a result container (Result Form) where all the search results
are displayed.The Search node allows the user to select filter properties, result
properties, add custom buttons and preview the search User Interface at studio design
time. The component takes care of most of the search features like pagination, max
rows, row selector etc and relieves the user of writing most of the X-rules code.
Here are the properties of a Search node component:
z Name (Required): Name of the node
z Description (Optional): Brief description
z Node input / Type (Default): The name of the node input variable is fixed (i.e.,
the user cannot change it to a different name) as “nodeInput” and the type of the
node input variable is fixed as “xml”. The search node requires this input for the
following reasons:
| ABPP Server internally sends the input to the search node for Save Search,
functionality.
So the search node mandates an node input. For most practical purposes, the user
will send a empty node input variable. However you can take advantage of the
nodeInput xml to provide many of the search node properties dynamically using
X-Path expressions. Here are a few examples:
| service name, primary document can be X-Path expressions referencing the
the node input variable
| search and result field properties like activity, display condition etc can also
be X-Path expressions referencing the node input variable
| You can also default the values of the search inputs by sending the necessary
tags in the nodeInput variable.
| You can provide an X-Path expression for the default filter which references
the nodeInput variable.
z Service (Required): ABPP service that contains the primary document to perform
the search. This attribute can be an expression or a constant value.
z Primary Document (Required): The primary document on which search will be
performed. This attribute can be an expression or a constant value.
z Default Filter (Optional): Any implicit filter that needs to be appended as part of
the search criteria. This attribute has to be an expression. The default filter should
be enclosed within a root tag. All elements inside this root tag will be appended as
an AND condition to the query that gets generated for the search.
When the workflow reaches the search node,
a. All the variables referenced in search node properties, search panel, result
panel and buttons panel will be evaluated.

Workflow Nodes
b. The node will perform the search and display the results. Now the user can do
one of the following:
z The user can refine the search criteria and do the search by clicking on the
search button.
z The user can select one of more rows of the results and click on a button.
z The user can click on any of the links on the result rows
c. When the user clicks the search button, then the screen will be refreshed with
the search results.
d. If the user clicks on a button or a link in the search results, the workflow
execution will continue to the next-nodes corresponding to the button or link.
The node input variable of the node where the useraction is linked, will have
the data in the following format:
When Link field is clicked:
<REQUEST>
row data
<REQUEST>
When button is clicked and the multiple rows are selected:

<REQUEST>
<ROOT>
<row data 1>
row data 1
<row data1>
<row data 2>
row data 2
<row data 2>
...</ROOT>
</REQUEST>...
Figure 12 Search Node Preview Tab

The following section discusses the tabs of the Search Node component:
Preview: This tab (Figure 12) shows the preview of the search user interface that the
user is building. This tab gets updated when the user clicks on the Apply button. This
helps the user to visualize the UI. This functionality is similar to preview panel in the
UI node. The sample data is pre-populated.

Workflow Nodes
Search Node Search Form Tab
Search Form: This tab (Figure above) deals with setting up the search form fields.
The fields that are to be shown in the search form have to be added to the Search Form
panel by clicking the Add button. The Add button brings up the Document Tree Editor
shown below. The user will be able to multi-select the properties either from the
primary document or from any of the link documents to be part of the search form.
Search Table Props:The Search Table Props deals with setting up the look and
feel of the search form UI.
| The Num Columns text field is used to determine the number of columns of
search fields that need to be shown in the Search Form page.
| The Export Search check box is used to determine the visibility of the button
in the Search form UI. The export search button provides the user the ability
to export to MS Excel the results of the search.
| The Save Search check box is used to determine the visibility of the button in
the Search form UI. The save search button provides the ability for the user to
store their search criteria as favorites.

Field Props:Once the user selects the fields in the search form, the user needs to
provide the field properties on the Field Props panel.
| Name represents the name of the field
| Display Name is the name that is shown in the Web User Interface
| Activity is used to determine if the user has the permission to view this
property while the Display Condition is a user condition to either show or
hide the property. The activity and display condition attributes can be an
expression or value.
| The type of search form field in the Field Props panel is auto populated from
the corresponding document model.
| Required attribute is used to specify whether this field property is required
and if so the search node will generate the required field validation.
| Case Insensitive attribute determines if the search should be case insensitive.
| ImageLink checkbox is used to determine if the search field is a text field with
an image link next to it. Selecting the Image Link checkbox will ask the user
if its a popup (select the Popup checkbox).
| The type of the Image Link can be either a look up through a foreign key
relationship from the model or based on button id. If the user selects the
button id checkbox, then the user needs to specify the button id.
| If the field is a dropdown, then the dropdown values can be populated by any
of the following methods
z valid values that are available from the model
z local values that the user can enter by clicking on the Add button
z Select Expr -- this expression can be based on any local variables created
in pre-actions or node input variable or pipe-line variables.
| If the field is a dropdown and multi selection is selected, then the drop down
will be a multi-selection box with 3 rows visible by default.

Workflow Nodes
Figure 13 Document Tree Editor
Result Form: This tab deals with setting up the result form fields. The fields that are
to be shown in the search results have to be added Result Form panel by clicking the
Add button. The Add button brings up the same Document Tree Editor as explained
above.

Figure 14 Result Form Tab
Row Selector: The Row Selector panel deals with row selector properties where
the user determines if the search results will have a radio button, check box or
none. The Id field must be one or more properties of the main document. This
property value will be used for the row selector value.
Note: The Id field property cannot be added as a hidden field in the Result
Form. This will cause the node input of the next node to not have data.

Workflow Nodes
Result Table Props:The Result Table Props panel deals with the properties of the
search result table.
| Selecting the checkboxes for Multi-Sort, Export to Excel, Customize table
will enable the corresponding icons to be available in the result form table.
z Multi-Sort: Allows three level sort on the result properties.
z Export to Excel: Allows the entire search results to be exported to MS
Excel.
z Customize table: Provides the ability to customize the search results
(configure the columns to be shown in the search results)
| The filter row checkbox will enable a filter row in the result form. If the user
gives filter criteria in the search form and in the filter row in the result form,
then the final filter will be a AND of both the filter criteria.
| The freeze option expects the user to enter a numeric value. This specifies the
number of columns that will not scroll and will be permanently available.
| The max row attribute allows the user to enter the maximum number of rows
that will be shown in the search results table.
Result Field Props: Once the user selects the fields in the result form panel, then
the user needs to provide the field properties on the Field Props panel.
| The activity and display condition attributes can be an expression or value.
| The type of result form field in the Field Props panel is auto populated from
the corresponding document model.
| Selecting the Hidden checkbox will make the result field property as a hidden
field.
| Sortable checkbox is to determine if this particular column is sortable
| Filter checkbox will enable/disable the filter row filter
| If the field is a link/image link field, then the user must provide the button id
associated with that field.
Buttons: This tab provides a mechanism for the users to manage custom buttons in
the result form.
| The user needs to enter the button properties in the Button Props panel for all
the buttons in this tab.
| Button Id is used to associate the next node web page action
| The Button Id and Display Text are default populated to the Id of the button.
| The activity and display condition attributes can be an expression or value.
| Emphasized checkbox will determine if this particular button is emphasized
in the web UI.
| Enabled By Selection checkbox will determine if a results row data needs to
be selected to enable this button

Figure 15 Buttons Tab
Serial/Parallel/Multi-Line Approval Nodes

These nodes are described in Part 3 ABPP Services Guide, Approval Service of
ABPP Reference Guide.
Wait/Launch Process, Load SQL File, Execute SQL Procedure,

FTP Files, Notification Nodes
These nodes are described in Part 3 ABPP Services Guide, Please look for further
explaination in the chapter for Task Scheduler Service.
Table Editor Component

Table editor node will enable the user to build data management workflows. A Table
Editor can be defined as a replica of the corresponding database table.Each row in a
table editor represents an equivalent row in the corresponding ABPP data table.
A user can have access to a table editor and buttons on the table editor screen based on
their role.Table editor allows the user to create/modify/delete records for a table that
belongs to a ABPP service. The page layout (PGL) for the UI and Xrules to create/
modify/delete records are in-built, so the user need not provide these as in the case of
a UI node.
The node allows the user to add custom button actions through the buttons tab. The
node also provides a mechanism to enforce user role activities on the button actions
(whether a user can have these buttons: Add, Copy, Mass Update and Delete), by
checking the enforce activities checkbox. By default this checkbox is not enabled, so

Workflow Nodes
all the buttons will be visible for all the users. There are three different modes in
which the table editor node can be invoked. They are given below:
a. Manage - Create/Modify/Delete records
b. Select - Select records and pass the selected records back to the caller
c. View - Ability to search and view records
For example, in a data management workflow for creating and setting properties on an
item-location, you can use the table editor for the steps to select the item and location.
The property editor for a table editor node is the following:
Table Editor node property editor

z Service (Required): service in which document is available
z Table Name (Required): Name of the document
z Mode (Required): MANAGE/SELECT/VIEW

z Enforce Activites (Default UnChecked): Flag to enforce activities on Add/

Copy, Mass Update or Delete buttons. If this checkbox is checked, then the user
should have the following activites for the corresponding buttons to be visible:
| ServiceName:TableName:Add - Add, Copy and Submit
| ServiceName:TableName:Update - Mass Update and Submit
| ServiceName:TableName:Remove - Delete
The following mandatory properties are enabled only for SELECT mode:
z Select Property: set only for SELECT Mode. The values of this property for the
selected rows will be returned in the assign output variable.
z IsMultiSelect? – Yes/No (drop down) is set only for Select Mode. This property
is used to determine if it’s a radio button or checkbox in the Select workflow
z Assign Selection – This variable contains the selection results from the Table
Editor when invoked in the Select Mode. Here is an example of the selection
result format
If Assign Selection = myOutput and Select Property = ItemId
myOutput contents will be:
<RESPONSE>
<ItemId Value=”ITEM-1”/>
<ItemId Value=”ITEM-2”/>
</ RESPONSE >
In the case where a row in the table editor is identified by a compound primary key,
the Select Property can still be only one property. For example, if the primary key is a
combination of ItemId and LocationId, and the Select Property is LocationId, then
myOutput contents will be:
<RESPONSE>
<LocationId Value=”LOC-1”/>
<LocationId Value=”LOC-2”/>
</ RESPONSE >
The buttons on the Table Editor are enabled/disabled based on the mode.
z For SELECT mode, only “Select And Return”, Clear & Search buttons are visible
z For MANAGE mode, all buttons except the “Select And Return” button are
visible
z For View mode, only Clear & Search buttons are visible
You can define presentation facets for each model in the model studio. The
presentation facets can be used to manage editability, visibility, word-wrap, number of
decimals to display, whether to i18nize etc of the model properties. The table editor
will use the presentation facets defined for data-services in rendering the pages.

Workflow Nodes
Custom Buttons: This tab provides a mechanism for the users to manage custom buttons in
the Table Editor.The custom buttons can be added to the table editor irrespective of the Mode
in which the table editor is invoked. The output that needs to be passed to a button action is
defined in the next nodes tab. This tab contains a list of button actions that can be performed
by the user on the web page of the table editor node. This list is automatically populated when
the user adds a custom button. You can associate the outbound connectors (next nodes) of a
table editor node with web page actions listed in this tab. After completing the post-
processing, the table editor will start executing the next nodes associated with the button
action performed by the user. If the user action does not match the ones defined in the next
nodes tab, it will execute the nodes associated with the default condition, true ().
The user needs to enter the button properties in the Button Props panel for all the buttons in
this tab.
z Button Id is used to associate the next node web page action
z The Button Id and Display Text are default populated to the Id of the button
z The activity and display condition attributes can be an expression or value
z Emphasized checkbox will determine if this particular button is emphasized in the web UI
z Enabled By Selection checkbox will determine if a results row data needs to be selected to
enable this button
Note: In this release, the user does not have access to the table editor row
selections for custom button actions.
A sample table editor browser UI is shown below. This section will briefly describe all the
functions of the table editor.
Adding a Record
If you have the privilege to add a record to the table you are viewing you should see an
Add button.
z If you wish to add a new record to the table click the Add button. This adds an
empty row to the table. Enter appropriate values in the fields.

z Fields marked with an asterisk (*) are mandatory.

z Click Submit
z The entered information is validated and if there are no errors your record is added
to the database and a confirmation message is displayed at the top of the screen.
z If there are errors an error icon along with an error message is displayed at the top
of the screen.
Copying a Record
If you have the privilege to add a record to the table you are viewing you should see an
Copy button.
z If you wish to add a new record to the table from an existing row, then
select an existing record and click the Copy button.
z The selected record is copied and highlighted in yellow.
z Modify any information in this new record.
z Click Submit
z The entered information is validated and if there are no errors your record
is added to the database and a confirmation message is displayed at the top
of the screen.
z If there are errors an error icon along with an error message is displayed at the top
of the screen.
Editing a Record
z If you wish to edit a record in the table, modify any information of the record in the table
and click Submit
z If you have the privilege to make edits and the changes are valid then the changes are
stored in the database and a confirmation message is displayed at the top of the screen
z If there are any errors with the modifications you made, an error message is displayed at
the top of the screen
Deleting a Record
If you have the privilege to delete a record to the table you are viewing you should see a Delete
button.
z If you wish to delete a record in the table select the record you wish to delete and click
Delete
z If the record can be deleted (i.e there are no constraints violated) the record is deleted from
the table
z If there are dependencies due to which the record cannot be deleted then you will see an
error message at the top of the screen

Workflow Nodes
Select and Return

You would see this button on a Table Editor screen if you clicked an icon to access data from a
related table.
z Select the records that you wish to populate in the parent table's search/entry field
z Click Select and Return button
z The selected records will be populated in the parent table's search/entry field
Mass Update
If you have the privilege to edit data in the table then you should be able to see a Mass Update
button.
In order to change values of the same property in multiple records in the table with a single
value perform the following steps:
z Enter the desired value in the entry field in the Mass update row
z Select the records whose property you wish to update to the desired value by clicking on
the check boxes next to the records
z Click the Mass Update icon next to the value you entered
z The value is copied over to the selected records
z Click Submit. The change is persisted in the databaseIn order to change values of the same
property in multiple records in the table with a single value perform the following steps:
In order to change values of the same property in the table with a single value to all records in
all the pages of the table editor UI, perform the following steps::
z Enter the desired value in the entry field in the Mass update row
z Click Mass Update button. The change is persisted in the database
Clearing changes made

If you have the privilege to add or edit data in the table then you should be able to see a Clear
button. By clicking on the clear button any rows that you might have added but not submitted
to the database will be deleted.
Cancel
If you have the privilege to add or edit data in the table then you should be able to see a Cancel
button. By clicking on the Cancel button the screen is refreshed and the table will show the
last saved data in the table. Any changes that you might have made but not submitted to the
database will be lost.
Export to Excel
You can export the records in the table by clicking on the Export to Excel icon at the top of the
results container.
z All the records in the search results across all pages will be exported
z The exported file will be in .csv format

Configure Table
z You can configure what columns are visible and the order of the columns by clicking on
the Configure Table icon at the top of the results container.
Where Used
Entries in each table are referred in other tables through foreign key relationships. You can
find out what other tables refer to data in a given table by following the steps mentioned
below.
z Select the row for which you wish to see the other tables in which records refer to this
record
z Click the Where Used button
z You should see a screen displaying the linked documents and the properties that link that
table to the table from where you clicked the Where used icon
Advanced Filters
The Filter row enables you to search for data by simply matching the value entered in the
search field with the value for the property in the database. For performing more advanced
searches click on the advanced filter icon at the top of the results container. The advanced
search functionality allows you to write more complex SQL expressions through a graphical
editor to retrieve data from the database.
Add to Favorite
You can add a particular table to your favorite by clicking on the favorites icon at the
top of the results container. Along with saving the table it also saves the filter criteria
entered on the screen.
Close and Refresh Node

Close and refresh node is primarily used when we want to close a pop up window and
refresh the parent window (or the opener).
Here are the properties of the node::
z Name: The name of the close and refresh node

Workflow Nodes
z Description: Optional text to describe the node

z Refresh Parent Window: Property to specify whether to refresh the parent
window or not.
This node is often used when the workflow control needs to comes back from a pop up
window to the main parent window. One example would be the user control coming
back to order worksheet screen after selecting items from a catalog popup. In this
example the system will add all the selected catalog items to the order worksheet and
close the catalog popup window.
In the figure below we have tried to depict the common usage pattern of a close and
refresh node. In this case when the control comes to close and refresh node from
popup window UI node, it closes the popup window UI node screen and refreshes the
main window UI node screen. The refresh will cause the pre-actions of the main
window UI node to be executed..
Master Details Node Configuration

Master details workflow node (similar to search node) helps in generating header
details review page. This node helps in displaying data from a set of database models
in a master details screen. This section will cover the use of this master details
workflow node.
Master details node can be accessed by clicking master details node icon from
workflow nodes toolbar in studio. After adding a master details node to the workflow,
double-clicking the node or selecting "Properties…" from the node context menu
brings up the master details node dialog.

At the top of the property dialog are the basic master details node settings as shown
below. These are:
z Name: The name of the master details node

z Service: Name of the service where the model resides
z Primary Document: Name of the model which consists of the master detail
screen's header fields
z Secondary Document: Name of the model which consists of the master detail
screen's detail fields
For example, the Master document could be a Forecast header which contains
information about the supplier, item and location while the Detail document
contains the forecast value for each of the supplier, item, location combinations
and a date.
z Prerequisites
| The primary document specified must have a link to the secondary document
| Also the secondary document specified must have a link to the primary
document
| The input to this screen must have all the primary document's primary key
fields value in order for the node to be able to display the selected document
details
For example, if the selected primary document has ORDER_ID and
ORDER_TYPE has the primary key, the xml input to this node should as
shown below
<INPUT_PARAMETERS>
<ORDER_ID Value="Order1" />
< ORDER_TYPE Value="Standard"/>
</INPUT_PARAMETERS>
Where INPUT_PARAMETERS is the root tag (please note that the input tag
name can be anything) and 'Order1' & 'Standard' are the primary keys value of
the document for which the details would be displayed.
The master details node design dialog primarily consists of three tabs as shown below.
z Preview: Like the layout tab in UI node dialog, this tab facilitates the previewing
of the master details screen.

Workflow Nodes
z Header: In this tab the user selects and defines all the properties related to the
header container fields.
z Details: In this tab the user selects and defines all the properties related to the
details table fields.
Header tab
After selecting the service name and the document/model names, the user would be
able to pick the header fields by selecting from a list of properties of the primary
document table.
Click 'Add…' button below the 'header fields' box to select the header fields from list
of properties of the primary document table as shown below.
After selecting the properties to be displayed in the header container, the user can
specify the order in which these header fields appear on the end user screen by using
the up and down arrows next to the entry field. For each of the header field, the
properties can be specified as part of 'header fields' properties section.
Header Field Properties
z Name: The logical name of the property being displayed.
z Display Text: The display text to be displayed on the end user UI.
z Activity: The activity that controls the visibility of the property in the end user UI.
z Show as Hyperlink: If checked, the property is displayed as a clickable link on
the UI

z Button Id: Enabled only if Show as Hyperlink is checked. This specifies the
button Id to be used in the Next Nodes (output Xml).
z Open as a pop up: Enabled only if Show as Hyperlink is checked. If checked the
hyperlinked URL is displayed as a pop up.
The properties under header props section are used for specifying the display text and
the number of columns in the header container as shown below. .
The buttons to be displayed on the header container footer can be specified under the
Buttons tab.
Details Tab
The details fields can be specified under 'Details' tab as shown below. The buttons to
be displayed on the details table footer can be specified under the Buttons tab. The
Field level properties are similar to the header tab and therefore not explained in
detail.
Detail Properties

Workflow Nodes
z Selectable: This property determines if the rows in the details container are
selectable or not. If the value is set to Single then a radio button is placed next to
the row in the end user UI. If the value is set to 'Multiple' then a check box is
placed. If the value is set to None then the row is not selectable.
z Id: This property is enable only if the value of Selectable is not set to None. This
value is used in the Next nodes (output XML).
z Display Text: This is the display text shown at the details container header.
z Max Rows: This attribute sets the Maximum number of rows to be displayed per
page.
z Customize Table: If checked, the end user can configure the table to set the
column ordering or what columns in the end UI are hidden. An icon ( ) is
addedat the top of the Details container.
z Multi-Sort: If checked the end user will be able to sort data in the Details
container on upto 3 columns simultaneously.
z Freeze: You can enter the column number at which a freeze pane is to be applied.
Data to the left and right of this column will then scroll independently.
z Filter Row: If checked the system will add a row at the top of the details data
table for the user to filter data on.
z Export to Excel: If checked the export to excel icon ( )is added to the Details
container and the user will be able to export the data that is displayed in the
Details container.
After specifying the header and detail field properties, the user can click 'Apply'
button to preview the master details screen under the 'Preview' tab as shown below.

Pivot Node Configuration

Pivot workflow node (similar to search node) helps in generating pivot based search
results. This node helps in displaying data from a set of database models in the form of
a pivot table. It also provides a search container with dimension fields using which the
user can filter the pivot table results.
The pivot table that is ultimately generated by this component would look similar to
the example shown below.
ITEM LOCATION SUPPLIER MEASURES 1/1/2008 1/8/2008
V-102-1 Tonawanda JUPITER FORECAST 100 50
SUPPLY 90 60
V-102-1 Tonawanda MERCURY FORECAST 120 70
SUPPLY 120 60
As an introduction to the terminology for the rest of this section, the columns Items,
Locations and Supplier in the example above have been termed as Row Dimensions or
just Dimensions for short. The entities Forecast and Supply are termed as Data
Measures or Measures for short and the dates are termed as the Column Dimension or
horizon parameter.
This section will cover the use of this pivot workflow node.
Pivot node can be accessed by clicking pivot node icon from workflow nodes toolbar
in studio. After adding a pivot node to the workflow, double-clicking the node or
selecting "Properties…" from the node context menu brings up the pivot node dialog.
At the top of the property dialog are the basic pivot node settings as shown below.
These are:
z Name: The name of the pivot node

z Node Input: The input to pivot node is always of type 'xml'. If required, search
criteria can be sent as part of this input xml. If the pivot search node screens needs
to be invoked with a particular search filter, this input parameter would come in
handy.
Currently the search parameters for a pivot node are set based on the selected row
level dimensions. In the example below we have 'ItemID', 'LocationID' &
'SupplierID' as the row level dimensions. So in this example if you want to set the
'LocationID' search filter as 'L*' on pivot node invocation, pass input as shown
below:
<INPUT_PARAMETERS>
<LocationID Value="L*" />

Workflow Nodes
</INPUT_PARAMETERS>
Where INPUT_PARAMETERS is the root tag (please note that the input tag
name can be anything) and 'L*' is the filter criteria for LocationID dimension.
z Service: Name of the service where the model resides. Note, this can be different
from the service in which the workflow is being written.
z Primary Document: Name of the model which consists of the pivot table's row
level dimension fields.
z Secondary Document: Name of the model which consists of the pivot table's
column level dimension (This is represented by the Date in the above table
example.) fields and the data measures values. In the above, example the data
would therefore have to be in two tables as shown below.
It is possible to have a surrogate key in the first table that is used as the FK link to
the second table. For example you could introduce a surrogate key called
BUFFER ID in the DIMENSIONS table and then in the DATAMEASURE
VALUES table you could use that property instead of again having to specify
ITEM, LOCATION and SUPPLIER all over again.
z Prerequisites
| The primary document specified must have a link to the secondary document
| The secondary document must have date type field. Only date type field can
be used as a column level dimension.
The pivot node design dialog primarily consists of four tabs as shown below.
z Preview: Like the layout tab in UI node dialog, this tab facilitates the previewing
of the pivot table.
z Dimensions: In this tab the user selects and defines all the properties related to the
row and column level dimensions of the pivot table.
z Measures: In this tab the user selects and defines all the properties related to the
data measures/KPIs to be displayed on the data side of the pivot table.
z Buttons: This tab helps in adding buttons to the pivot table.

After selecting the service name and the document/model names, the user would be
able to pick the dimensions by selecting from a list of properties of the primary
document table.
Click 'Add…' button below the row dimensions box to select the row level dimensions
from list of properties of the primary document table as shown below.
After selecting, the user can specify the order in which these dimensions appear on the
end user screen by using the up/down arrows to right of the entry box. For each of the
selected dimension, the properties can be specified as part of row dimension
properties section.
Row Dimension Properties
z Name: The Logical name of the Property. This is non-editable and is derived from
the logical name of the property in the model.
z Display Text: The text to be displayed on the end user's UI when displaying the
pivot table.
z Activity: The user activity that controls the visibility of this property. For
example, In the example above, for a supplier user you may want to disable
visibility to the Supplier column. This can be done through activities. For more
information please refer to the ABPP Beginner's Tutorial.
z Lookup: The dropdown would show the list of tables this particular row
dimension field is linked. The table specified here is used as a lookup search for
the dimension search entry fields. Once specified an icon shows up beside the
search entry field which when clicked would show up a table editor screen
facilitating the search.
For example if a lookup table is selected for 'LocationID" field then in the search
section beside the location id entry field an icon shows up which when clicked
would display a table editor screen showing all the available locations from the
lookup table.

Workflow Nodes
Next the column dimension/horizon parameter can be specified by clicking '…' button
and selecting a date field from the 'Select Column Dimension' dialog as shown below.
The selectable properties can be set using the selection settings sections as shown
below. This is basically for displaying checkboxes/radio buttons beside the row/
column level dimensions of the pivot table.
Similarly, the data measure fields for the pivot table can be specified under the
Measures tab as shown below.
Measure Properties

z Name: The logical name of the measure. This is non-editable and is derived from
the logical name specified in the model.
pivot table.
z Activity: The user activity that controls the visibility of this measure. For
example, you may not want certain users to view some of the measures in the
pivot table. This can be controlled through activities. For more information refer
to the ABPP Beginner's Tutorial.
z Show as Hyperlink: If checked, the property is displayed as a clickable link on
the UI
z Button Id: Enabled only if Show as Hyperlink is checked. This specifies the
button Id to be used in the Next Nodes (output Xml).
z Open as a pop up: Enabled only if Show as Hyperlink is checked. If checked the
hyperlinked URL is displayed as a pop up.
Finally, the buttons to be displayed on the pivot table footer can be specified under the
Buttons tab as shown below.
Button Properties
z Button Id: The id of the button that is used internally for specifying actions
associated with the button
pivot table
z Activity: The user activity that controls the visibility of this button. For example,
you may want to visibility of certain buttons on the UI.
z Emphasized: This attribute controls whether or not the button is emphasized
(shown in bold) on the UI.

Workflow Commands
After specifying all the above mentioned properties, click 'Apply' button to preview
the pivot table screen under the 'Preview" tab as shown below. Notice that the preview
screen is pre-populated with some sample data. You can change it by using the
'Sample Data' dialog.
The row dimension fields selected under dimensions tab will show on the left side of
the table (shown below circled in red). The column dimension shows up as the header
on the right side of the pivot table (circled in black). And finally the data measures/
KPIs selected as part of Measures tab will show in the center (circled in blue) and its
data on the right side..
As you can see in the preview shown above, certain buttons and icons are added by
default to the screen.
Search: This button is used to perform the search based on the search criteria entered
in the search container.
Save Search: This button is used to save the search criteria as a 'Favorite' for the user.
The enables the user to configure the layout of the table
The enables the user to export the results in the Data container to a .csv file.
Workflow Commands
ABPP provides built-in commands for workflow management (example: start/kill
workflows). These commands can either be invoked directly on the server ( embedded
within REQUESTS tag) or issued from within X-Rules.

START_WORKFLOW
Description:
This is a system command to start a ABPP workflow explicitly.
Syntax:
<START_WORKFLOW>
<TEMPLATE Value="workflowName"/>
<ANY/>
</START_WORKFLOW>
z TEMPLATE, Value (Required): Name of the workflow to be run.
z ADDITIONAL_PARAMETERS (Optional): Use this tag to pass additional
parameters to the workflow. These parameters will be available in the service
variable 'thisParam' in the Start node of the new workflow.
Example 1
This example shows how to start a workflow from within X-Rules
<DEFINE_METHOD Name="startNewPartRequest">
<API_DOC>
<INPUT>
<REQUEST Name="startNewPartRequest">
<ItemID Value="R-123" />
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE />
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
<RULE>
<ACTION>
<START_WORKFLOW>
<TEMPLATE Value="newPartRequest" />
<ItemID Value="{$thisParam/ItemID/@Value}" />
</START_WORKFLOW>
</ACTION>
</RULE>
</DEFINE_METHOD>
Example 2
This example shows the REQUESTS payload for starting a workflow by posting it
directly onto ABPP server.
<REQUESTS ServiceName="ItemMaster">
<START_WORKFLOW>

Workflow Commands

<ItemID Value="RE-10391" />
</START_WORKFLOW>
</REQUESTS>
In this example, ItemMaster is the ABPP service which contains
the workflow.
KILL_WORKFLOWS
Description:
Some of the workflows:
a. may not finish in a long time
OR
b. may not be executing as expected
So there is a need to identify and kill these workflow instances.
This command can be used to kill all the workflow instances (that are persisted in the
database, as well those in memory) matching the criteria and all of their child
workflow instances. If a workflow is currently executing, this command:
a. Tries to interrupt the thread executing the workflow.
b. Marks the workflow for kill.
It is possible for a thread not to respond to the interrupt. (Example: When the thread is
waiting on a database call ). So there are check points (example, at start and end of
node execution ) where the thread will check and exit if it is marked for kill.
The criteria supported today for killing the workflows are TEMPLATE, SERVICE,
PRIMARY_DOC and PRIMARY_DOC_ID.
Syntax:
<KILL_WORKFLOWS>
<TEMPLATE Value="workflow-name"/>
<SERVICE Value="workflow service"/>
<PRIMARY_DOC Value="primary document name"/>
<PRIMARY_DOC_ID Value="primary document id"/>
</KILL_WORKFLOWS>
z TEMPLATE, Value (Required): Name of the workflow to be killed.
z SERVICE, Value: Name of the service the workflow belongs to.The command
does not automatically use the service name from the invoking context ( example
ServiceName attribute on REQUESTS tag or the service name of the X-Rule
which invokes this command ). So it is essential to provide the value for this tag
for filtering based on service name.
z PRIMARY_DOC Value: Name of the Primary document name as defined in the
workflow.

z PRIMARY_DOC_ID Value: Value of the primary document id as set in the

workflow.
Example 1
This example shows the REQUESTS payload for killing workflow instances by
posting it directly onto ABPP server.
<REQUESTS ServiceName="ItemMaster">
<KILL_WORKFLOWS>
<SERVICE Name="ItemMaster"/>
<PRIMARY_DOC Value="Item" />
<PRIMARY_DOC_ID Value="V-102-1" />
</KILL_WORKFLOWS>
</REQUESTS>
The KILL_WORKFLOWS command does not use the service name
specified on the REQUESTS tag. So we had to explicitly provide
the service name through the SERVICE tag.
The above invocation will kill all the newPartRequest workflow

instances, contained in Item service, created for Item whose
ID= V-102-1.
Example 2
This example shows a X-Rule code snippet for killing workflows within X-Rules.
<DEFINE_METHOD Name="killNewPartRequest">
<API_DOC>
<INPUT>
<REQUEST Name="killNewPartRequest">
<ItemID Value="V-102-1" />
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE />
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
<RULE>
<ACTION>
<KILL_WORKFLOWS>
<SERVICE Name="ItemMaster" />
<PRIMARY_DOC Value="Item" />
<PRIMARY_DOC_ID Value="{$thisParam/ItemID/
@Value}" />
</KILL_WORKFLOWS>
</ACTION>
</RULE>
</DEFINE_METHOD>

Workflow Commands
CANCEL_EVENT
Description:
This command can be used to cancel all active event nodes of a workflow instance
associated the given event or request descriptor.
The criteria supported for this command are INSTANCE_ID and
EVENT_DESCRIPTOR.
Syntax:
<CANCEL_EVENT>
<INSTANCE_ID Value="workflow-instance-id"/>
<EVENT_DESCRIPTOR Value="event-descriptor"/>
</CANCEL_EVENT >
z INSTANCE_ID, Value (Required): Workflow Instance Id.
z EVENT_DESCRIPTOR, Value (Required): Name of the event or request
descriptor.
Example 1
<CANCEL_EVENT>
<INSTANCE_ID Value="test-workflow"/>
<EVENT_DESCRIPTOR Value="shipmentReceivedEvent"/>
</CANCEL_EVENT>
CANCEL_NODE
Description:
This command can be used to cancel an active event node of a workflow instance. The
criteria supported for this command are INSTANCE_ID, NODE and TEMPLATE.
Syntax:
<CANCEL_NODE>
<INSTANCE_ID Value="workflow-instance-id"/>
<TEMPLATE Value="workflow-template-name"/>
<NODE Value="node-name"/>
</CANCEL_NODE >
z INSTANCE_ID, Value (Required): Workflow Instance Id.
z TEMPLATE, Value (Required): Name of the workflow.
z NODE, Value (Required): Name of the event node that is being cancelled.
Example 1
<CANCEL_NODE>
<INSTANCE_ID Value="test-workflow"/>
<TEMPLATE Value="my-workflow"/>
<NODE Value="my-event"/>
</CANCEL_NODE>

Workflow Logging
Logging is a feature of the workflow which captures time at which each node started
and ended execution in a workflow instance. The captured data can be used to monitor
execution of the workflow. Workflow logging can be controlled by setting an optional
NodeEventListener attribute on the workflow node to either “true”,”false” or
“default”. If NodeEventListener attribute is set to “true” then the log will be captured
for the workflow, if set to “false” then the log will not be captured. An empty value for
the attribute is interpreted as “false”. If the value is set to “default” then the system
assumes that a Service Level variable with the name NodeEventListener is defined in
the xservice file, this service variable can only be set to “true” or “false”. The reason
for such an implementation is to be able to turn on or off logging at the service level.
For example in a given service all the workflow’s could have NodeEventListener
attribute (Log Workflow in studio) set to “default” and at a service level variable
NodeEventListener could be set to “true”. This will enable logging of all the
workflows, but if the service level variable is set to “false” all logging will stop on the
workflows from that point onwards. This gives the user better control on logging
workflows at a service level.
Logging information is saved in the following two tables (Only important fields have
been listed):
Table: WORKFLOW_LOG (Physical Name: WFL_LOG): Workflow header level
details are stored in this table.
Fields:
INSTANCE_ID: Capture the instance ID of the workflow instance.
TEMPLATE: Name of the workflow.
WFL_SVC: Service Name of the workflow.
PARENT_ID: ID of the parent workflow, in case the current workflow is a
subworkflow.
PARENT_NODE: Node name of the subworkflow node, in case the current workflow
is a subworkflow
START_DATE: Time stamp field to capture as to when the workflow started.
END_DATE: Time stamp field to capture as to when the workflow ended.
STATUS: Status of the workflow, if the workflow is ACTIVE or COMPLETED.
Table: WORKFLOW_TASK_LOG (Physical Name: WFL_TASK_LOG): An entry

for each node thats executed in a workflow is stored in this table.
Fields:
ID: Unique Identifier
INSTANCE_ID: Workflow instance id.
NODE_NAME: Name of the node as defined in the workflow.

Workflow Logging
NODE_TYPE: Type of node, ex: Start, Done, Task etc.

START_TIME: Time at which the node started executing.
END_TIME: Time at which the node finished executing.
STATUS: Status of node execution, ACTIVE or COMPLETED
Workflow Monitoring UI (Reference Implementation):

There are two screens that are shipped with the standard PGL service which display
the current state of execution of any workflow that is currently active. Both the
screens are packaged with SearchWorkflow workflow.
Search workflow can be added to the navigation panel as follows:
<ui:pad displayText="Tools" name="tools">

<ui:pad-item displayText="Search Workflows" workflow="//
PGL/SearchWorkflows" />
</ui:pad>
UI Assumptions.
The monitoring UI works with certain assumptions that the user has to take into
consideration when creating a workflow that they intend to monitor. The workflow to
be monitored has to have the Log Workflow (or the NodeEventListener Property on
the workflow element) set to “true” and the Is External Start Allowed property set to
Yes as follows:
The user also needs to have a pipeline variable called "thisPrimaryDocId" which
should ideally be set to some value in the Start node as follows.

Note that the workflows are only available for monitoring while they are waiting on
an Event, Timer or on a Subworkflow to complete.
Search Workflows Screen:

Search Screen is the first screen of the SearchWorkflows workflow. This screen
allows the user to filter by the following set of parameters:
z Services: This dropdown lists all the services available in the current application.
z Templates: This dropdown lists all the templates available in the selected Service
(previous parameter).
z Workflow Type: This dropdown lists the Type parameter, Type is a property of
Workflow.
z Document Type: This is the Primary Document specified in the property of the
workflows.
z Node Type: This is the type of node that the user is trying to search these could
be, Event, Timer or Subworkflow nodes.
z Show Subworkflow: This checkbox specifies if the search should include
subworkflows.
z Primary Doc Id: This parameter searches for workflows which have the
appropriate Primary Document Id.
Note: The above screen is a snapshot of the SearchWorkflow’s search screen. Please
note that the user can also select a workflow and click “Cancel Workflow” to
kill the selected workflow.

Workflow Logging
Details Screen:
In the Search Screen the Primary Doc ID is a hyperlink which will take the user to the
Details Screen which shows the following columns:
z Node Name: Name of the node as specified in the workflow.
z Start Time: Time when the node started executing.
z End Time: Time when the node stopped executing.
z Status: Completed or Active.
z Node Type: Type of node.
Note: In the above screenshot of the detailed screen note that the Subworkflow is a
hyperlink which can be clicked to get to the details of the Subworkflow.
Note: The above sceen displays the current activity in the appropriate Subworkflow.
Please note that the SearchWorkflows workflow is for reference only, they can be
customized based on actual requirements of the end customer.


Appendix A
Guide for Gathering Information on Hangs &

Crashes
This chapter explains what information to obtain in case of crash or hang of the
xserver. It also tries to detail out the steps that one should follow to get the
information.
Topics
| Server Hangs
| Server Crashes
Server Hangs
In case of Server hangs, the following information would be required.
Basic information
The following pieces of basic information would be required for tracking down any
hang.
z OS Version ( please check with the system administrator and note down the same)
z Java version ( This can be obtained by doing a "java - version" from the dir where
java is installed
z Database vendor and version ( This should be the stack version. However, do
check with the DBA and get this information
z Memory settings for starting the Xserver. This can be obtained from the .sh or the
.bat file that was used to start the server
Memory & CPU Information

As a first step, try and get the memory and CPU usage of the process. Note down the
usage for about 60 mins ( once every 5 mins). All the information that is captured
shoud be placed in files and the same should be sent over. Below section details how
the same can be obtained for each OS.

Appendix A Guide for Gathering Information on Hangs & Crashes
Windows
Please look at the task manager to find out the memory & CPU usage of the process. A
screen shot of the task manager details could be placed in a file and the same could be
sent.
Unix
For any unix command, the first step is to identify the process. This can be done by
using : ps -ef comand.
As a suggestion, it might be better to grep for com.i2.xcore.xserver.Xserver in case of
non co-located deployments where the xserver VM is hung.
>>ps -ef| grep com.i2.xcore.xserver.Xserver > process.txt
In case of co-located deployments grep for weblogic.Server.
>>ps -ef| grep weblogic.Server> process.txt
Once that is done the below command may help you in identifying the mem and CPU
usages on various versions of Unix.
Solaris
On Solaris, one can use the "top" command. This gives the CPU and memory
utilization. The output would be displayed as
Figure 16 Load average for Solaris
That way the details by process id can be understood. You should issue the command
to pipe the output to a file
>>top > stats.txt
HP
On HP, "top" command would work and output would be something like

Server Hangs
Figure 17 Load average for HP
>> top > stats.txt
AIX
On Aix, "top" may not work, and you would need to use "topas" command. Output
would be something like this.

Figure 18 Load average for AIX
>>topas > stats.txt
Log files
Xserver Logs
If you are running non-colocated xserver in back ground mode then it is recommended
that you redirect the console output to a log file. Provide the xserver console log file if
you are using this setup.
The server log files would all be typically there in the log folder within the product
installation. A good idea would be to tar up the directory and send it to i2 support.
Please refer to the ABPP guide for information on setting log files, and changing log
files on a production setup.

Server Hangs
Windows.
If it is windows normal ZIP, TAR or WINRAR utilities may be used.
Unix.
A script could be written to backup the log file directory.
A general purpose log file back up script is being pasted here and this can be corrected
and re used, as deemed fit.
Note that the script assumes the following:
The folder: logbackup exists at the same level as log. If this folder does not exist then
create it prior to executing the script.
The script is placed in a folder ( typically bin folder of your product install) which is at
the same level as the log folder. If not replace ../log and ../logbackup to provide the
relative path to the log and logbackup folders from the folder containing the script.
The script is executed from the same folder where it exists.
#! /usr/bin/ksh
#Capture the time stamp
dtvar=`date +%m%d%Y%T`
#Backup the log directory and attach time stamp to the dir
cp -r ../log ../logbackup/log_$dtvar
#Compress the backed up directory and create .tar.gz file
tar cf - ../logbackup/log_$dtvar | gzip -v > ../logbackup/
log_$dtvar.tar.gz
#Remove the backedup directory after compressing the directory
in above step
rm -rf ../logbackup/log_$dtvar
Weblogic logs
You need know the web logic domain in which the i2 application is installed. Each of
the domains in WebLogic Server has its own log files.
As an example, assume that:
(1)WebLogic root folder is C:\bea
(2) The application is installed in domain = i2Proddomain. The files belonging to the
domain are in C:\bea\user_projects\i2Proddomain folder.
In case of a server crash/hang, you will need to turn in the following log files to i2
support.
(1)myserver.log (C:\bea\user_projects\ i2Proddomain \myserver folder)
(2)i2Proddomain.log (C:\bea\user_projects\ i2Proddomain folder). This log file is
rotated, so you will find files like i2Proddomain.log000n in the folder. Make sure you
turn in these files also.
(3)access.log (under mydomain/myserver folder)

if you are running the server ion background, it is recommended that you redirect the
console output to a log file.
If you are running weblogic in background and piping the output to a console log file
then provide the console log file.
Resource Stats of the Xserver

The instructions in this section are applicable only if the Xserver is NOT privately co-
located within weblogic.
Getting the resource stats of the Xserver provides valuable information in diagnosing
a hang. This info can be collected by posting the resource stats request onto the server.
Here are the steps to collect the resource stats:
7. Change your working directory to bre/bin folder of the product installation.
8. This folder will have a setABPPEnv.cmd ( or setABPPEnv.sh for Unix). This env
file will most probably be configured with your JAVA_HOME and class path
settings. If not configure this file by following the comments in the file.
9. This folder will have getResourceStats.cmd ( or getResourceStats.sh for Unix )
file. Ensure that this file exists.
10. Execute getResourceStats.cmd providing server url as the parameter. Send the
resourceStatsOutput.xml file created in the folder to i2.
Example:
cd C:\i2\cse\6.2\bre\bin
getResourceStats.cmd http://localhost:14444/
Thread Dumps
The single most important source of information during a crash is a thread dump. The
key is to take about 12 thread dumps at in 5 min intervals, once a hang is noticed. Note
that the thread dumps should be taken in a non instrusive manner. In other words, the
process should not be killed, rather it should be allowed to be continued while the
system is running. Below subsections detail out ways to take thread dumps on various
operating systems
Windows
On windows one way to take a thread dump is to issue the Ctrl+Break, key strokes
together. This command takes a non intrusive dump. In other words, the process is not
killed. Rather, just the dump is created. Note that this output would not be piped to a
file, by default. Rather, it would be streamed to the console itself. As shown below.
And one can capture that output is by copying the dump from the console into a file
and sending the same. However, if the server was started by piping the output to a file,
then Ctrl+Break would direct the thread dump also to that file. And one can take the
requisite number of dumps. Below is a sample dump which has been thrown onto the
console. Note that the thread dump starts with the statement " Full thread dump…".

Server Hangs
Figure 19 Thread Dump
Unix
In Unix taking of the dumps is different on different versions. Below, the case for
Solaris, HP and AIX is explained.
Solaris
On Solaris, to take a non intrusive thread dump, the following command needs to be
issues with the process id as the input parameter
Kill -3 <process_id>
This command takes a non intrusive dump. In other words, the process is not killed.
Rather, just the dump is created. Note that this output would be streamed to the
console itself. As shown below. And one can capture that output is by copying the
dump from the console into a file and sending the same. However, if the server was
started by piping the output to a file, then this command would direct the thread dump
also to that file. And one can take the requisite number of dumps. Below screenshot
shows a sample scenario where the dumps are taken.

Figure 20 Thread dumps for Solaris
The top most buffer is the buffer which has started the process. It was started by
piping the output to a file named abc.out
The second buffer is showing a way of identifying the process id. In this case, the user
name and the fact that this is a java process, are used to nail down the process id. Once
the process id has been nailed down. The kill -3 command is issued from the same
buffer. The bottom buffer is showing the output of the dump as piped to the file
abc.out. Note that the thread dump starts with the statement " Full thread dump…".
HP
The process of taking dumps on HP is exactly same as that on Solaris. Please refer to
Solaris section.
AIX
On AIX, the method to take a non intrusive thread dump is to issue the following
command needs to be issues with the process id as the input parameter
Kill -3 <process_id>

Server Hangs
This would generate a javacore file (Please note that this java core is different from a
core file. Core file is the feature of the OS and can be produced by any program not
just the JVM. ). The JVM checks each of the following locations for existence and
write-permission, and stores the javacore in the first one available. Note that there
should be enough freespace for the file to be written correctly.
- The location specified by the IBM_JAVACOREDIR environment variable if set
- The current working dir of the JVM processes
- The location specified by the TMPDIR environment variable, if set
- The /tmp directory
The file name would be of the form : javacorePID.TIME.txt
Where
PID = process id
TIME = number of milliseconds since 1/1/1970
Below is a sample dump taken on a process similar to the one show in the Solaris
section.

Figure 21 Thread Dump for AIX
The top buffer is the window which started the process. Here too output was asked to
be piped to a file named abc.out
In the middle buffer, the process id of the process is tracked down, and then the kill-3
command is issued twice ( with a time gap). As you can see, in the top window AIX
has indicated that the dumps have been generated and placed in the folder specified.
The bottom buffer is showing that the files are indeed generated, as can be seen by the
'ls' command. These javacore files are to be sent to i2
System backup
As soon as a hang is observed, it would be wise to backup the entire product
installation and send the same to i2. This would be required in cases where the hang is
not happening within i2 on i2 datasets. Please note that in this case, the following
pieces of information would have to be sent:
Tar / zip of the entire product installation directory
Tar / zip of the web installation

Server Crashes
A database dump of the dataset
Steps to Replicate
This is by far the most importanty piece of information that can help the product team.
This is required for both replicating the problem and also validating the bug fix ( if
any). So as soon as a hang happens, it would be good to ask the users patiently, as to
what they were doing before the hang. The more information that can be provided
here, the better it is for diagnosing the issue. Compile all information available and
turn it over to i2 support.
Server Crashes
In case of Server crashes, the following information would be required.
Basic information
The following pieces of basic information would be required for tracking down any
hang.
z OS Version ( please check with the system administrator and note down the same)
z Java version ( This can be obtained by doing a "java - version" from the dir where
java is installed
z Database vendor and version ( This should be the stack version. However, do
check with the DBA and get this information
z Memory settings for starting the Xserver. This can be obtained from the .sh or the
.bat file that was used to start the server
Log files
The steps for collecting the log files is the same as the ones outlined under server
hangs topic. Please refer to the log files section of server hangs topic for details.
System backup
This section is the same as the steps outlined in server hangs topic. Please refer to the
system backup section of server hangs topic for details.
Steps to Replicate
This section is the same as the steps outlined in server hangs topic. Please refer to the
steps to replicate section of server hangs topic for details.
The Core file

As soon as a crash is encountered, a core file would be encountered. This core file
would provide information, which can be sent to the OS vendor and some diagnostic
hinted can be obtained. So this file must be sent to i2 at the earliest. The following

sub-sections list out where and how these core files would be (likely) available in case
of a crash
Windows
Unix
On Unix, the core files look a different and would be located in the directory from
where the process had been started.
Solaris
On Solaris, 2 files would be generated
-A file by the name "core"
-A file with the name hs_err_pid<process_id>.log
These 2 would need to be sent.
As shown in the screen shot below, both these were generated at 11:08 AM when the
process crashed. The process is in this case was 20887
Figure 22 Core File Solaris
HP
On Solaris, 2 files would be generated
-A file by the name "core"
-A file with the name hs_err_pid<process_id>.log
These 2 would need to be sent.
As shown in the screen shot below, both these were generated at 11:12 AM when the
process crashed. The process id in this case was 23253
Figure 23 Core File HP
AIX
This would generate a javacore file. The JVM checks each of the following locations
for existence and write-permission, and stores the javacore in the first one available.
Note that there should be enough freespace for the file to be written correctly.
The location specified by the IBM_JAVACOREDIR environment variable if set
The current working dir of the JVM processes

Server Crashes
The location specified by the TMPDIR environment variable, if set

The /tmp directory
The file name would be of the form : javacorePID.TIME.txt
Where
PID = process id
TIME = number of milliseconds since 1/1/1970
As an example, the below file was generated when the process 671970 crashed on
AIX.
Core File AIX


Appendix B
System Tables
Maintenance of System Tables

When the ABPP engine generates schema, by default few system tables are created in
the target schema. These system tables are used by the runtime to provide various
features like workflow events, encrypted fields etc. For most of these tables the ABPP
developer/user does not have to deal with these tables or maintain them. Few of these
tables can accumulate data over time and so need to be purged periodically to maintain
proper performance of the system. The following section lists the various system
tables, explains their purpose and suggests strategies for maintaining these tables in a
production system. For some of these tables as the amount of data in them grows the
older data that is no longer needed can be removed. This is referred to as purging. This
purging can be performed by executing appropriate SQL delete statement. Purging of
these system tables is simple enough that it does not warrant use of the purge
framework that ABPP provides.
The ABPP server also provides various archived services like APPROVAL,
TIMER_SINK, DATA_UPLOAD etc. These services may also create their own tables
in the target schema. Refer to respective service documentation in this reference guide
for details on maintenance required for the tables created by these archived services.
Details on System Tables
Encryption
z "CRYPTION_KEY: This table is used to store the encryption key used to encrypt
and decrypt fields of type encryptedString. This table does not need any
maintenance/purging.
Export
z "EXP_LOG: This table is used by the export framework to log all export
invocations. It maintains the start date, end date, progress and additional
information for the exports invoked in the system. This table should be purged

Appendix B System Tables
periodically depending on the amount of export activity expected for a particular

implementation. The END_DATE column can be used for the purge criteria.
z "EXP_TRACKER: This table is used by export framework to support incremental
exports. This table does not need any maintenance/purging.
ID Generation
z "ID_SQR: The ID_SQR table is used for ID generation when the
TableIdGenerator is used (i.e. handler specified is
com.i2.xcore.idgen.BlockTableIdGenerator). Please refer to ID Generation
chapter for more details. This table will be small in size and does not need any
maintenance/purging.
DB Locking
z "LOCK_TABLE: This table is used for the DB Locking feature. This table servers
as a repository of lock units that multiple threads update to obtains exclusive
access to the lock units. Based on usage (type of lock units) this table may grow in
size. E.g. if the lock unit is based on supplier id then there will be fixed number of
suppliers in the system and so this table will not grow extensively. But if the lock
unit is based on say order id then this table will keep growing. The purge strategy
should be defined based on usage for a particular implementation. The
LOCK_TIME column can be used for the purge criteria.
Purge
z PURGE_LOG & PURGE_LOG_LN: These tables are used by the Purge
framework to record all the purge related activities. They provide data about the
purge invocations and related information like number of rows deleted from
various tables. For more details on the Purge framework please refer to the Purge
chapter. These tables will need to be purged periodically based on amount of
purge activity for a particular implementation. The START_DATE and
END_DATE columns can be used for the purge criteria.
Workflow
z "WFL_INSTANCE, WFL_ATV_EVENTS & WFL_ATV_NODES: Any
workflow that reaches a state where it is waiting for an external input is persisted
to these tables. Such a workflow will sleep until the required external input re-
activates it. Once the workflow is no longer waiting for any input, its entries from
these tables are removed. In some cases it is possible that the expected external
input never happens and the workflow continues to wait indefinitely. In such cases
entries in these tables will keep growing. To clean such dead workflows it is
recommended that these tables be purged periodically using START_DATE
column of WFL_INSTANCE table for the purge criteria.
z "WFL_LOG & WFL_TASK_LOG: These tables are used to maintain log
information for workflows that have logging enabled. For details on enabling
logging please refer to Workflow Properties section of Workflow Concepts
chapter. This table will need to be purged periodically. The START_DATE/

Details on System Tables
END_DATE columns can be used for the purge criteria. The END_DATE is the
time when the workflow finished executing its "Done" node.

Appendix B System Tables

Index
A Default Values 32
ADD_CHILDREN 154 DEFINE_INIT 81
ADD_DOCUMENT 106 DEFINE_LISTENER 74
And Node 328 DEFINE_METHOD 69
App Server Configuration 294 DEFINE_POST_CREATE 79
APPEND_CHILDREN 157 DEFINE_POST_MODIFY 81
APPEND_TO_XML 149 DEFINE_POST_SHUTDOWN 83
Audit Trail 37 DEFINE_PRE_CREATE 77
Audit Trail Definition Files 284 DEFINE_PRE_MODIFY 80
DEFINE_PRE_SHUTDOWN 82
B Definitions 7
Boolean Functions 223 DELETE_ALL_CHILDREN 160
Boolean X-Path Expressions 211 Dictionary 17
Branch Node 322 DO_TRANSACTION 199
BROADCAST 48 Document 7
Document Constraints 32
C Document Definition Files 279
CANCEL_NODE 373 Document Identifiers 27
Cis Client Config 303 Document Index 28
CIS Generation 304 Document Links 33
CisTagNameMapping 290 Document Properties 29
CLEAR_ALL_LOGS 47 double 31
Client Configuration 293 DROP_CACHE 47
CLONE_XML 174 DROP_DOWN_OPTIONS 192
COLLATE_XML 161 Dynamic Flex Properties 38
Command Components 104
Command Line Input 301 E
Composite View 21 ENABLE/DISABLE/SET_LOG_LEVELS 44
concat 218 encryptedString 30
contains 221 Encryption Configuration 300
CREATE_DOCUMENT_ID 106 Event Definition Files 280
CREATE_URL 193 Event Node 316
EXCEPTION 99
D EXEC_INFORMATICA 196
Data Access Components 106 EXECUTE_SHELL_COMMAND 194
Database Configuration 294 EXIT 99
datetime 31 Export Definition Files 282
DBLock Specification Files 282 Expression 116
Decision Node 320 Extension Files 278

Index
F MERGE_ERRORS_DOC 171
FETCH_DOCUMENT_LINK 124 Model Dependancy 21
Flex Properties 37 Model Extension 19
FOR_EACH-BREAK-CONTINUE 95 Model Instances 18
FORM_GET 184 Model Sets 18
FORM_REMOVE 185 MODIFY_DOCUMENT 111
FORM_SEARCH_FILTER 181
FORM_UPDATE 187 N
Framework Services Commands 64 NATIVE_FUNCTION 201
Node Input & Output variables 308
G Node-Set Functions 214
GET_BUILD_INFO 44 normalize-space 220
GET_CURRENT_TIME 199 NOT_EXISTS_QDL 121
GET_DOC_CHUNKED 129
GET_DOCUMENT 113 O
GET_LOG_LEVELS 46 Or Node 328
GET_RESOURCE_STATS 43 ORDER_BY 118
GET_SESSION 181 Overlay Documents 36
GET_TEXT 153
GROUP_BY 119 P
GROUP_DOCS 167 PAGINATE_LINES 189
Guide for Gathering Information on Hangs & Pipeline Variables 309
Crashes 379, 393 POST 202
POST_STRING 202
H Pre-defined Flex Properties 37
HANDLE_SYSTEM_EXCEPTION 103 PRINT/PRINTLN 90
PRINT_TO_FILE 198
I PROCESS_GET_DOCUMENT 130
IdGen Configuration 284 Property 8
IF_TEST-THEN-ELSE 91 Protocols 293
IF-THEN-ELSE 92 Purge Definition Files 282
Implicit Variables 309
Inheritance 19 Q
INSTANCE_METHOD 201 QUERY_DOCUMENT_LINK 120
K R
KILL_WORKFLOWS 371 Referential Integrity Constraints 35
REFRESH_FROM_CACHE 200
L Register Handlers 277
LOAD_XML_FILE 197 REMOVE_ATTRIBUTE 144
Locator Configuration 292 REMOVE_CHILDREN 158
LOG 91 REMOVE_DOCUMENT 110
Logger 287 REPEAT 96
Logical Date 301 Resource Stats of the Xserver 384
Rule Definition Files 280
M
Management Commands 64 S
MAP 163 Scalar Functions 128
MERGE_DOC 169 Schema Generation 299

Index
Search Definition Files 283 U

SELECT + UI Node 338
QUERY_DOCUMENT_LINK 123 upperCase 221
Selecting a list of nodes 207 User-Interface Related Components 181
Selecting a list of nodes based on a Utility Components 194
condition 209
Selecting a node 207, 210 V
Serial/Parallel/Multi-Line Approval Validation Spec Files 280
Nodes 352 Variable Types 69
Server Configuration 298 Variables 308
Server Crashes 389 Variables and Expressions 67
Server Hangs 379
Service Configuration 275 W
Service Parameters 285 WHILE 98
SET_CHILD 153 Workflow 281
SET_LOGICAL_DATE 199 Workflow Concepts 307
SET_NAME 152 Workflow Execution 308
SET_REDIRECT_URL 194 Workflow Nodes 313
SET_SESSION 181 Workflow Properties 310
SET_TEXT 152 Wsdl Client Configuration 302
SET_XSERVICE_PARAM 50 Wsdl Generation 301
SHUT_DOWN 49 Wsdl Node 332
SORT 178
SORT_DOCS 174
X
SQL_FN 125
X-Commands 41
Start Node 313
X-Config 275
START_WORKFLOW 370
XML_TO_STRING 173
Starting/Cancelling/ Monitoring Workflow
X-Path Basics 206
Instances 369
X-Rule Components 84
starts-with 219
X-Rule Components Syntax Notations 85
State Model Files 283
X-Rule Types 69
STORE_XML_FILE 197
X-Rules 65
string 217
X-Server 292
String Functions 216
X-server Parameters 304
STRING_TO_XML 173
strlen 218
subString 219
substringAfter 220
substringBefore 219
Sub-Workflow Node 323
T
Table Editor Component 352
TAG_ERRORS 190
Thread Dumps 384
Timer Node 326
TO_XML 148
trim 220

Programmers Reference Part1 6.2.8 RevA

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Programmers Reference Part1 6.2.8 RevA

Enviado por

Direitos autorais:

Formatos disponíveis

Agile Business Process

i2® Agile Business Process Platform (ABPP) 3

Copyright © 2000-2008 i2 Technologies US, Inc. All Rights Reserved.

This product may be protected by one or more of the following patents:

2 Modeling Concepts ....................................................................................... 7

Agile Business Process Platform 3 Programmers Reference Revision A v

vi Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A vii

Expression .............................................................................................................................. 116

viii Agile Business Process Platform 3 Programmers Reference Revision A

6 X-Path ......................................................................................................... 205

Agile Business Process Platform 3 Programmers Reference Revision A ix

count .............................................................................................................................................. 215

x Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A xi

xii Agile Business Process Platform 3 Programmers Reference Revision A

DBLock Specification Files ..........................................................................................................282

8 Workflow Concepts ................................................................................... 307

Agile Business Process Platform 3 Programmers Reference Revision A xiii

OR Node ...................................................................................................................................... 328

A Guide for Gathering Information on Hangs & Crashes...........................379

xiv Agile Business Process Platform 3 Programmers Reference Revision A

Thread Dumps ................................................................................................................................384

B System Tables............................................................................................ 393

Index ........................................................................................................... 397

Agile Business Process Platform 3 Programmers Reference Revision A xv

xvi Agile Business Process Platform 3 Programmers Reference Revision A

Welcome to i2 Agile Business Process Platform 3 Programmers Reference. It provides

About i2 Agile Business Process Platform 3

Agile Business Process Platform 3 Programmers Reference Revision A xvii

scripting language to express business rules. It provides several pre-built constructs

xviii Agile Business Process Platform 3 Programmers Reference Revision A

About this Book

What You Should Know

What This Book Contains

Agile Business Process Platform 3 Programmers Reference Revision A xix

Table 1 Typographic conventions used in this document

Item Example Explanation

Code Call NotifyPending; File names, executable code,

Pathname C:\i261\webdriver Windows pathnames are shown in

Meta-variable i2_Home\webdriver Portions of code that you replace with

Documentation or SCOS Installation Guide Document or book names referenced

Any of the following types of notes may appear in this book:

xx Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A xxi

If You Need Assistance

To Contact Customer Support

Internet Web site: http://support.i2.com

Phone: US and Canada: 1.469.357.3456

xxii Agile Business Process Platform 3 Programmers Reference Revision A

For the Latest Documentation

Agile Business Process Platform 3 Programmers Reference Revision A xxiii

xxiv Agile Business Process Platform 3 Programmers Reference Revision A

This chapter gives you an introduction to Agile Business Process Platform 3

Agile Business Process Platform 3 Programmers Reference Revision A 1

2 Agile Business Process Platform 3 Programmers Reference Revision A

This document is focused on the infrastructure and is intended to provide the

Elements of ABPP Framework

Agile Business Process Platform 3 Programmers Reference Revision A 3

z X-Services: Collection of APIs and processes (workflows) that make up a logical

4 Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A 5

How to Use This Guide

6 Agile Business Process Platform 3 Programmers Reference Revision A