Programmers Reference Part2 6.2.8 RevA

Agile Business Process
Platform (ABPP) 3
Programmer’s Reference - Part 2
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 2 Revision 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........................................................................................................... xi
1 Events ............................................................................................................. 1
Introduction ...............................................................................................................................................1
Defining Events .........................................................................................................................................2
Subscribing Events ....................................................................................................................................5
Defining a listener in X-Rules............................................................................................................5
Defining a listener in Workflow.........................................................................................................5
Raising Events ...........................................................................................................................................6
RAISE_EVENT ..........................................................................................................................6
RAISE_EVENTS........................................................................................................................7
2 Web Service Definitions................................................................................ 9

Introduction ...............................................................................................................................................9
The API_DOC IDL ...................................................................................................................................9
Specifying the Data Type of an Attribute ........................................................................................11
Specifying that an Attribute is Optional...........................................................................................12
Specifying that a Tag is Optional.....................................................................................................13
Allowing Extra Attributes on a Tag .................................................................................................13
Specifying the Order of Child Tags .................................................................................................13
Allowing Extra Child Tags ..............................................................................................................13
Allowing Repetitions of a Tag .........................................................................................................14
Specifying a Choice of Tags ............................................................................................................14
API_DOC Language Extensions.............................................................................................................14
Referencing Declarations in an X-Document ..................................................................................15
Referencing a Search Spec...............................................................................................................16
Referencing a Validation Spec.........................................................................................................18
Advanced Features ....................................................................................................................20
Referencing other API_DOCs..........................................................................................................20
Appendix A: Generating Xservice WSDL ..............................................................................................21
Appendix B: Validating Xservice APIs at Runtime................................................................................24
Agile Business Process Platform 3 Programmers Reference Revision A v

Contents
Appendix C: Testing the WSDL API ..................................................................................................... 24
3 Validation ......................................................................................................27
Introduction............................................................................................................................................. 27
Validation specification .......................................................................................................................... 27
Overview.......................................................................................................................................... 27
Specification Structure..................................................................................................................... 29
Definition of XML Attributes used in defining validation specification ........................................ 32
Variables .......................................................................................................................................... 33
Types of validations......................................................................................................................... 34
data_type_validation................................................................................................................. 34
mandatory_validation ............................................................................................................... 35
Validation ................................................................................................................................. 35
Validation_group...................................................................................................................... 36
Autofill/Postfill ................................................................................................................................ 37
Steps involved in using validation framework ....................................................................................... 38
Specify the validation specification file in the appropriate service configuration file .................... 38
Invoke validation framework to validate XML document .............................................................. 38
INVOKE_VALIDATION_FRAMEWORK ............................................................................ 38
VALIDATE_DOC ................................................................................................................... 40
Other utility action components....................................................................................................... 42
UPDATE_VALIDATION_RESULT ...................................................................................... 42
4 ID Generation ................................................................................................45
Introduction............................................................................................................................................. 45
TimeIdGeneration ................................................................................................................................... 45
TableIdGeneration .................................................................................................................................. 46
SequenceIdGeneration ............................................................................................................................ 46
BlockIdGeneration.................................................................................................................................. 46
IdGen Configuration ............................................................................................................................... 46
Managing Id Generation configurations in ABPP Studio ...................................................................... 48
Obtaining Unique IDs ............................................................................................................................. 50
5 Purge .............................................................................................................53
Purge Functionality................................................................................................................................. 53
Features of Purge Framework................................................................................................................. 54
Defining Purge Definition ...................................................................................................................... 54
Loading purge definition ........................................................................................................................ 63
Creating purge backup table schema ...................................................................................................... 63
Invoking/Triggering purge...................................................................................................................... 63
Purge framework schema........................................................................................................................ 64
6 Export Framework ........................................................................................65

Export Functionality ............................................................................................................................... 65
Features of Export Framework ............................................................................................................... 66
vi Agile Business Process Platform 3 Programmers Reference Revision A

Contents
Defining Export Definition......................................................................................................................66

Loading Export Definition ......................................................................................................................69
Creating export/staging table schema......................................................................................................69
Invoking/Triggering export .....................................................................................................................70
Export Framework Schema .....................................................................................................................71
Sample Export Spec ................................................................................................................................71
7 Search Framework....................................................................................... 75
Search Functionality................................................................................................................................75
Search Definition.....................................................................................................................................77
Selected Properties ...........................................................................................................................78
Fetch document links .......................................................................................................................78
Query document links ......................................................................................................................79
Normal Filters ..................................................................................................................................79
Specifying additional search criteria ................................................................................................79
Interfaces to Search Framework ..............................................................................................................80
GET_SEARCH_RESULTS......................................................................................................80
GET_SEARCH_FORM............................................................................................................84
Loading the search definition ..................................................................................................................86
8 State Machine............................................................................................... 89
State Model..............................................................................................................................................89
State Model Specification........................................................................................................................90
Mapping condition specification and event mapping ......................................................................92
State Model Association...................................................................................................................93
Exception States ...............................................................................................................................93
State Document .......................................................................................................................................95
Interfaces to State Machine .....................................................................................................................95
RAISE_STATE_EVENT.................................................................................................................96
PREVIOUS_STATE_EVENT.........................................................................................................97
Obtaining event name for a state in a state model............................................................................97
Loading state model files.........................................................................................................................98
Parallel States ..........................................................................................................................................98
Appendix ...............................................................................................................................................100
Example of state model specification.............................................................................................100
FAQ................................................................................................................................................103
9 DB Locking................................................................................................. 105
Concept..................................................................................................................................................105
Setup ......................................................................................................................................................106
API Specification...................................................................................................................................107
10 Audit Trail Framework............................................................................... 109

Introduction ...........................................................................................................................................109
Audit Trail Functionality.......................................................................................................................109
Agile Business Process Platform 3 Programmers Reference Revision A vii

Contents
Features of Audit Trail framework ....................................................................................................... 110

Defining Audit Trail Definition ............................................................................................................ 110
Creating Audit Trail Definitions in ABPP Studio ................................................................................ 111
Turn off/on audit trail ........................................................................................................................... 113
SET_AUDIT_TRAIL_STATUS................................................................................................... 113
Audit Trail User Interface..................................................................................................................... 115
11 CIS Support.................................................................................................117
Making ABPP rules and events available to clients using CIS ............................................................ 117
Generating Metadata types and Bindings ...................................................................................... 118
Define API_DOC and EVENT_DOC for the rules and event descriptor .............................. 118
Define CIS tag in API_DOC/EVENT_DOC ......................................................................... 119
Define config file needed for CIS file generation .................................................................. 120
Specify the config file in server config file ............................................................................ 122
Define name mapping file ...................................................................................................... 122
Specify the mapping file in service config file....................................................................... 123
Override default data type mapping only if needed ............................................................... 124
Generate the CIS metadata types and binding files................................................................ 124
Handling Attributes ................................................................................................................ 125
Handling Text......................................................................................................................... 125
Runtime Setup ............................................................................................................................... 125
Running CIS .................................................................................................................................. 127
Examples of XML Messages......................................................................................................... 127
Making operations and notifications of existing CIS application available in ABPP .......................... 130
ABPP Binding types ...................................................................................................................... 130
SOAP Binding ........................................................................................................................ 130
CIS Binding ............................................................................................................................ 130
Generate WSDL from CIS Adapter............................................................................................... 130
Sample CIS Adapter ............................................................................................................... 130
Generate SOAP WSDL from CIS adapter ............................................................................. 131
Generate CIS WSDL .............................................................................................................. 136
Using SOAP binding to make web service calls to CIS Adapter .................................................. 141
Insert the generated WSDL .................................................................................................... 141
Add workflow with a SOAP binding WSDL node ................................................................ 142
Configure WSDL node properties.......................................................................................... 143
Setup steps to use CIS Binding...................................................................................................... 144
Set project ClassPath .............................................................................................................. 144
Update Service configuration ................................................................................................. 145
Configure Security for CIS client........................................................................................... 146
Using CIS binding to invoke operations on the CIS Adapter........................................................ 150
Insert the generated CIS WSDL. ............................................................................................ 150
Add workflow with a CIS binding WSDL node .................................................................... 151
Update server configuration file............................................................................................. 152
Configure WSDL node properties.......................................................................................... 153
Using CIS binding to receive events from the CIS Adapter.......................................................... 155
Generate ABPP event descriptors .......................................................................................... 155
viii Agile Business Process Platform 3 Programmers Reference Revision A

Contents
Insert Init rule..........................................................................................................................156

Insert event descriptor file.......................................................................................................157
Add event listener ...................................................................................................................158
12 JMS Support............................................................................................... 161

Xserver configuration to enable JMS ....................................................................................................161
Defining JMS Connections....................................................................................................................162
Externalizing Requests, X-Rules and Events ........................................................................................164
Invoke ABPP Request or X-Rule through JMS ....................................................................................166
Raise ABPP Event through JMS ...........................................................................................................167
SEND_MESSAGE ................................................................................................................................168
RECEIVE_MESSAGE..........................................................................................................................170
Concept of Integration Service..............................................................................................................172
Additional considerations in a cluster setup..........................................................................................173
Setting jmsAppCluster Flag ...........................................................................................................173
Setting Client Id .............................................................................................................................173
Advanced Configuration Settings..........................................................................................................174
JMSHeartbeatInterval.....................................................................................................................174
Example ..................................................................................................................................174
JMSRetryCountBeforeReconnect ..................................................................................................174
Example ..................................................................................................................................174
JMSMessageConverter...................................................................................................................174
JMSQueueBrowseInterval .............................................................................................................175
Example ..................................................................................................................................175
JMSMaxPendingMsgCount ...........................................................................................................175
Example ..................................................................................................................................175
JMSMaxDynamicListenersPerAPI ................................................................................................175
Example ..................................................................................................................................176
JMSMinDynamicListenersPerAPI.................................................................................................176
Example ..................................................................................................................................176
JMSMaxListenerIdleTime .............................................................................................................176
Example ..................................................................................................................................176
JMSDynamicListenerSurvivalRatio...............................................................................................177
Example ..................................................................................................................................177
13 Data Service ............................................................................................... 179

Data Service - Basic Concepts ..............................................................................................................179
Service Layering in Data Services .................................................................................................180
Action X-Rule Components specific to Data Services ..................................................................182
MDM COMMANDS .............................................................................................................183
Index ........................................................................................................... 225
Agile Business Process Platform 3 Programmers Reference Revision A ix

Contents
x 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 xi

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.
xii 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 “Events” on page 1. Describes the Event and Request Interfaces used in
ABPP.
z Chapter 2 “Web Service Definitions” on page 9. Explains the Web Services
Description Language (WSDL) to builds the integration of enterprise applications
using XML.
z Chapter 3 “Validation” on page 27. It discusses validation framework and how it
is used to do auto-fills and validations for an input XML document.
z Chapter 4 “ID Generation” on page 45. This chapter gives you information about
generating unique ids in ABPP.
z Chapter 5 “Purge” on page 53. The following chapter describes the purge
specification that is used to specify document which needs to be purged.
z Chapter 6 “Export Framework” on page 65. The chapter describes the export
specification that can be used to specify export filters, document and its properties
that have to be exported.
z Chapter 7 “Search Framework” on page 75. The document details the search filter
specification and its usage to support different filters on a document.
z Chapter 8 “State Machine” on page 89. This chapter discuss state machine and the
states associated with document instances.
z Chapter 9 “DB Locking” on page 105. This chapter describes the API locking
using a common table in database.
z Chapter 10 “Audit Trail Framework” on page 109. The following chapter discuss
audit trail specification.
z Chapter 11 “CIS Support” on page 117.This document explains the CIS front bus
support provided by ABPP server.
z Chapter 12 “JMS Support” on page 161. This chapter delves into JMS framework.
z Chapter 13 “Data Service” on page 179. This chapter gives you information on
Timer Service in ABPP.
Agile Business Process Platform 3 Programmers Reference Revision A xiii

Preface
Conventions
Table 1 lists examples of the typographic conventions used to display different types
of information in this document.
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.
xiv 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_Part1_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 xv

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.
xvi 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 xvii

Preface
xviii Agile Business Process Platform 3 Programmers Reference Revision A

Chapter 1
Events
Topics:
z Defining Events
z Subscribing Events
z Raising Events
Introduction
Event framework is a mechanism for executing any number of configurable business
actions when some “thing of interest” occurs in a service (or an application).
The thing of interest is called an event. Common examples of event are:
z Loading of a new Forecast
z Inventory stock out at an item-location
z Creation of an order
z Delayed Shipment
z Order not completed by due date.
The configured business actions are the subscribers to the event. The subscribers can
be defined at a much later time in a development cycle than the event and plugged in
to receive the event notifications to execute business action. Typically the subscribers
are used to non-intrusively plug-in business actions that could not have been foreseen
when the event was defined.
A service using the event frame work would contain:

z Definition of all the events. An event definition would involve providing the event
name and specifying its payload (xml body).
z Subscription to the events. Each of the subscribers would be notified when the
event occurs. On being notified, each subscriber can perform some business
action.
Agile Business Process Platform 3 Programmers Reference Revision A 1

Chapter 1 Events
z Logic to raise the event when “the thing of interest” occurs. This is called raising
the event.
Example:
Enterprise A uses an Item Catalog service to manage items sold to its customers. It
was felt that other services/applications might be interested in Item property changes
(Example Price and Cost change). So the Item Catalog service defined “Item
Properties Changed” event and raises the event whenever any of the item properties
are changed. The event payload clearly identifies the properties that have changed and
their old values.
At a later point of time, the enterprise created Invoice and Inventory Tracking
services. The new services had to perform the following updates whenever item price
or cost changes to keep their information consistent:
z On a price change of an item, the Invoice service should update the invoices
corresponding to the item.
z On a cost change of an item, the Inventory Tracking service should update the
inventory valuation for all the location where this item is stocked.
These changes were easily accomplished without making any changes to the Item
Catalog service. The Invoice and Inventory Tracking services created business logic
functions to do the necessary updates. These functions subscribed to the “Item
Properties Changed” event. When any Item properties changed, the corresponding
functions in these services were executed to do the necessary updates.
The following sections describe the mechanics of defining, subscribing and raising
events.
Defining Events
Events are defined by specifying event descriptor using the syntax shown below.
Syntax:
<event_descriptor Name="name-of-event"
Category="FORECAST[Optional=true]"
Externalized="true|false[Default=false]" JMSConnection="connection-
name[Optional=true]" Broadcast="true|false[Default=false]"
ValidateSignature="true|false|default[Optional=true]"
IsSynchronous="true|false[Default=false,Optional=true]">
<EVENT_DOC>
<RAISE_EVENT Name="name-of-event">

<RAISE_EVENT/>
</EVENT_DOC>
<keys>
<key Value="x-path-referencing-command-input-attributes/
text" Repeatable="true" Optional="true"/>
</keys>
</event_descriptor>
2 Agile Business Process Platform 3 Programmers Reference Revision A

Defining Events
Attributes:
z Name (Required): Name of the event. This should be unique within the service.
z Category (Optional): This is mainly for grouping related set of events together.
z Externalize (Optional): Default=false. Externalizing an event binds the event to a
JMS topic (or queue). An externalized event can be triggered by an external
ABPP client by publishing an appropriate JMS Message on the associated topic
(or queue). Also any externalized event raised within ABPP is published on the
bound topic (or queue). Please refer JMS Support chapter, 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/topic that this event is bound to. Please refer JMS Support chapter, located
in the Programmer’s Reference Guide, Part Two, for further details.
z Broadcast: The broadcast attribute is applicable only if Externalize is true and the
JMS enabled application is deployed in a cluster scenario. Please refer
"Additional considerations in cluster setup" section of "JMS Support" chapter for
further details.
z ValidateSignature (Optional): This attribute can be used to enable/disable API
signature validation for this event. 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 to the ValidateApiSignature attribute in the Service Config
chapter (Programmer’s Reference - Part 1) 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 to this event is validated to ensure conformance
with the corresponding signature (structure, required elements & attributes, data
types etc) defined in the EVENT_DOC.
z IsSynchronous (Optional): Default is false. By default all the listeners of this
event are invoked asynchronously. Each listener will execute in its own
transaction and failure of one listener will not rollback the original transaction that
raised the event or the other listeners. This attribute can be set to true to have all
the listeners execute synchronously. When the listeners are executed
synchronously they execute in same transaction as the one that has raised the
event and so any failure in the listeners will rollback the transaction that raised the
event.
z keys.key.Value (Optional): The key tag is optional. But if the key tag is specified
then its Value attribute is mandatory. The Value attribute identifies attribute value/
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 event input. This identifier is then
used to locate the event node of the workflow instance that is waiting for this
event.
Elements:
z EVENT_DOC (Optional): The EVENT_DOC describes the structure of the input
XML document of the event. Defining the EVENT_DOC is analogous to creating

Chapter 1 Events
an XSD (xml schema definition) for the input XML document of the event. It is
used to define the event body. The EVENT_DOC is equivalent to the API_DOC
that is specified for user defined commands. All features of API_DOC related to
grammar and API_DOC extensions specified in the API_DOC Language
Extensions section of Web Service Definitions chapter are applicable for
EVENT_DOC also. The tag inside EVENT_DOC will always be
RAISE_EVENT as that is command used to raise the event and will always be the
root of the event body.
Example:
<event_descriptor Name="newForecastArrived" Category="FORECAST"
Externalized="true" JMSConnection="TestConnection" Broadcast="true"
ValidateSignature="true">
<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>
This above example defines an event, newForecastArrived. The EVENT_DOC tag

defines the elements contained in the event body. This event would typically be raised
by the service whenever a new forecast is uploaded in to the system.
You can define one or more events in an event definition file (myevents.xml) as
follows:
<event_descriptors>
<event_descriptor Name="newForecastArrived"
Category="FORECAST">
<EVENT_DOC>
<RAISE_EVENT Name="newForecastArrived">
<FCST_LINE_ID Value="xxx"/>
<RAISE_EVENT/>
</EVENT_DOC>
<keys>
</keys>
</event_descriptor>
<event_descriptor Name="ForecastLineValidationFailed"
IsRequest="false">
<EVENT_DOC>
<RAISE_EVENT Name="ForecastLineValidationFailed">
<EVENT_HEADER>
<DOC_ID Value="xxx"/>
<REF_DOC_ID Value="xxx"/>
<REF_DOC_TYPE
Value="PROBLEM_LINE[Type=Constant]"/>
<SELLING_ORG_ID Value="xxx"/>
<CUSTOMER_ORG_ID Value="xxx"/>
<ITEM_ID Value="xxx"/>
<LOCATION_ID Value="xxx"/>
</EVENT_HEADER>

Subscribing Events
</RAISE_EVENT>
</EVENT_DOC>
</event_descriptor>
</event_descriptors>
Events are part of an X-service. An event name is unique within a service. Events can
be associated with a service by including the event definition file as part of the service
configuration file. Typically event definition is specified in the service that raises the
event.
Example:
The relevant portions of the service configuration file are shown below:
<dom-config>
<service-config Name="FMX" TransactionCache="true"
Register="true" >
<eventDefnFiles>
<eventDefnFile Name="xservice/fmx/xml/eventdef/
myevents.xml"/>
</eventDefnFiles>
</service-config>
</dom-config>
The fully qualified name of the event is //<service-name>/<event-name>. This
name is globally unique.
Example: //FMX/ ForecastLineValidationFailed
Subscribing Events
A subscriber to an event will be notified when the event occurs. On being notified,
each subscriber can perform some business action. An event can have more than one
subscriber. You can subscribe to an event in the following ways:
Defining a listener in X-Rules

Example:
<DEFINE_LISTENER Name="newForecastArrivedListener1"
Descriptor="//FMX/newForecastArrived">
<RULE>
<ACTION>
<PRINTLN Value="The event key = {$thisParam/
FCST_LINE_ID/@Value}"/>
</ACTION>
</RULE>
</DEFINE_LISTENER>
Please refer X-Rules chapter to understand the DEFINE_LISTENER syntax.
Defining a listener in Workflow

You can define a listener through an event node in workflows. Here is an example:
<event Name="WaitForNewForecastArrivedEvent" Description="Wait
for new Forecast Arrival" InputVar="{lineForecast,lineForm}"
Descriptor="//FMX/newForecastArrived">

Chapter 1 Events
<pre_actions/>
<post_actions>
<action Name="Print Info">
<PRINTLN Value="The event key = {$thisParam/
FCST_LINE_ID/@Value}"/>
</action>
</post_actions>
<keys>
<key Value="$fcLineId"/>
</keys>
<next_nodes>
<next_node Name="Done" Description=""/>
</next_nodes>
</event>
Please refer Workflow Concepts chapter to understand the event node syntax.
Raising Events
ABPP provides system commands to raise events. These commands are described in
this sub-section.
RAISE_EVENT
Description:
This command raises a single event. For this command to be successful:
z The event definition must already exist in the service on which this command is
being invoked. Recall that event definition can be provided using the
event_descriptor construct.
z The body of RAISE_EVENT must conform to the EVENT_DOC specified in the
event_descriptor
An event can have multiple listeners. When the command executes:
z All of the listeners are notified of the event. Please refer to the IsSynchronous
attribute of event descriptor for details on execution behavior of the listeners.
The response of the command contains the number of listeners who subscribed to the
event.
Input Syntax:
<RAISE_EVENT Name="event-name">

</RAISE_EVENT>
Output Syntax:
<RESPONSE>
<NUMBER_OF_LISTENERS Value="5{Type=int]" />
</RESPONSE>
Attributes:

Raising Events
z Name (Required): This is the name of the event. There should be an event
descriptor already defined in the service (on which the command is being
executed).
Note: The Service Name for the command is infered from the Command Envelope.
Example:
Input:
<EVENT_HEADER>
<DOC_ID Value="FC-LI-201" />
<REF_DOC_ID Value="REQ-PROB-101" />
<REF_DOC_TYPE Value="PROBLEM_LINE" />
<SELLING_ORG_ID Value="1" />
<CUSTOMER_ORG_ID Value="2" />
<ITEM_ID Value="SUP-MOT-ITEM1" />
<LOCATION_ID Value="SUP-MOT-SHIPTO1" />
</EVENT_HEADER>
</RAISE_EVENT>
Output:
<RESPONSE>
<NUMBER_OF_LISTENERS Value="5" />
</RESPONSE>
RAISE_EVENTS
Description:
This command raises multiple events defined within a service. This will help in
performance
Input Syntax:
<RAISE_EVENTS>
<RAISE_EVENT Name="event-name" Repeatable="true">

</RAISE_EVENT>
</RAISE_EVENTS>
Output Syntax:
<RESPONSE/>
Example:
Input:
<RAISE_EVENTS>
<EVENT_HEADER>

Chapter 1 Events

</EVENT_HEADER>
</RAISE_EVENT>
<EVENT_HEADER>
</EVENT_HEADER>
</RAISE_EVENT>
<RAISE_EVENT Name="MissingFirmQualifier">
<EVENT_HEADER>
</EVENT_HEADER>
</RAISE_EVENT>
</RAISE_EVENTS>
Output:
<RESPONSE/>

Chapter 2
Web Service Definitions
Introduction
The widespread adoption of XML as a flexible and non-proprietary way of describing
data has simplified the integration of enterprise applications. The Web Services
Description Language (WSDL) builds on this success by using XML to convey not
only data but also actions to be carried out on the data.
WSDL is an XML-based language for describing web services and how to access
them. It specifies the location of the service and the operations (or methods) the
service exposes. A web service is a programmatic interface exposed through WSDL.
This interface is described using the XML Schema Definition (XSD) language.
Given that ABPP already passes messages using XML, it is easy to see why ABPP
and WSDL are a natural fit. Any Xservice API can be exposed as a web service
simply by defining its interface in the WSDL description for that Xservice. The only
thing that's missing is the interface description for those public APIs.
However, using the XSD language to describe Xservice APIs presents a number of
problems. For the more complex Xservice APIs, one cannot form an XSD that
correctly specifies the interface. This is mainly due to the inability of XSDs to
conditionally include a tag (or set of tags) based on the value of an attribute. At the
same time, XSDs impose an ordering on the XML which is not required by the
Xservice API and which conflicts with the way APIs are invoked by legacy code.
Add to this the fact that XSDs can be difficult to read and understand, and it becomes
apparent that ABPP programmers need an alternate interface description language to
define the Xservice APIs
The API_DOC IDL

The API_DOC Interface Description Language (IDL) is an XML-based language that
is used to document Xservice APIs. It supplies a description of the interface in an
XML format that is natural for ABPP programmers to read and maintain. It also
serves as an example of the input and outputs of an API and can be used to generate
documentation. It contains hints which are used to generate a best-fit XSD and

Chapter 2 Web Service Definitions
Validation Framework Spec file. It can be used to generate test cases for the API
signature. And it provides a single point of maintenance so that all of these generated
documents can remain synchronized.
Before describing the form and content of the API_DOC IDL, it might be useful to
show an example of its use:
<DEFINE_METHOD Name="createTPA" Access="Public">
<API_DOC>
<INPUT>
<REQUEST Name="createTPA" Any="true" Comment="This API
creates TPA">
<TPA>
<TPA_ID Value="[Type=string(64)]" Optional="true" />
<AUTO_HANDLING Value="[Type=string(32)]"
Optional="true" />
<CMI_ER_TYPE Value="SHIP_TO_FIRM|UNIQUE_IDENTIFIER"
Optional="true" />
<CUST_NAME Value="[Type=string(32)]" Optional="true"
/>
<CUST_ORG_ID Value="[Type=string(64)]" />
<DAILY_PLANNING_WEEKS Value="5[Type=int]"
Optional="true" />
<DESCRIPTION Value="A descriptive string"
Optional="true" />
<END_DATE Value="01/01/2004 10:23:42[Type=datetime]"
Optional="true" />
<FCST_DOC_META_ID Value="[Type=string(64)]"
Optional="true" />
<FIRM_IDENTIFIER_TYPE Value="[Type=string(32)]"
Optional="true" />
<START_DATE Value="01/01/2004
10:23:42[Type=datetime]" Optional="true" />
<STATUS Value="[Type=string(10)]" Optional="true" />
<SUPP_NAME Value="[Type=string(32)]" Optional="true"
/>
<SUPP_ORG_ID Value="[Type=string(32)]" />
<TPA_NAME Value="[Type=string(32)]" />
<TPA_TYPE Value="VMI|CMI_ER" />
</TPA>
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE Status="Success[Type=Constant,
Optional=true]" Any="true" OrderIndicator="true" Comment="Success
response of creates TPA">
<TPA_ID Value="1" />
<ANY />
</RESPONSE>
</ON_SUCCESS>
<ON_EXCEPTION>
<RESPONSE XsdDef="createTPAError" Comment="Validation
error response of create TPA" />
</ON_EXCEPTION>
</OUTPUT>
</API_DOC>
<RULE>
<ACTION>

The API_DOC IDL
[ rule logic]
</ACTION>
</RULE>
</DEFINE_METHOD>
The example shown above defines the interface for the createTPA API. The
API_DOC has an INPUT section to define the API Request and an OUTPUT section
to define the API Response. The Output section has an ON_SUCCESS section to
define the Response of a successful API invocation and an optional ON_EXCEPTION
section to define the Response of an API invocation that returns with Status equal to
'Error'.
Specifying the Data Type of an Attribute

Each attribute specified in the interface definition can include a data type declaration.
If none is specified, the value of the attribute is defaulted to the string data type. The
list of recognized data types are: boolean, string, int, long, float, double, BigDecimal,
date, datetime, timestamp, time and xml. The string data type can be given an optional
length restriction.
For details on the acceptable formats for these data types, refer to Document
Properties located int eh Programmer’s Reference Guide, Part Two.
For the numeric data types (int, long, float, double) you can also specify the following
prefixes : positive-, negative-, non-negative-. For example, you can specify the data
type as positive-int or negative-float.
You can also specify data types on the text elements of the API_DOC. The syntax for
specifying data types on text elements is exactly the same as the one for specifying it
on attributes.
The following example illustrates an attribute declaration with an example value of
Today and with the default string data type:
<START_DATE Value="Today"/>
The following example illustrates an attribute declaration with a data type and an
example value for the attribute:
<START_DATE Value="01/01/2004 10:23:42[Type=datetime]"/>
In addition to specifying one of the defined data types, an attribute can be declared to
have a constant value or to be an enumerated type.
The following example illustrates an attribute declaration for an enumerated type:
<TPA_TYPE Value="VMI|CMI_ER"/>
The following example illustrates an attribute declaration for a constant value:
<RESPONSE Status="Success[Type=Constant]" >
The following example illustrates using a data type on text element:

<TPA>VMI|CMI_ER<TPA/>
<START_DATE> 01/01/2004 10:23:42[Type=datetime] </START_DATE>
<A>10[Type=positive-int]</A>

In addition to the date related data types listed above following date related data types
that follow the XSD date specification can also be used:
xsdDateTime
Format: CCYY-MM-DDThh:mm:ss[.sss][Z|±hh:mm]
Example:
2006-04-10T13:50:25.300
2006-01-01T03:02:01Z – This indicates a UTC dateTime
2006-01-01T04:02:01+01:00 – This is a dateTime that is
one hour ahead of UTC
xsdDate
Format: CCYY-MM-DD
Example:
2006-04-10
xsdTime
Format: hh:mm:ss[.sss]
Example:
13:50:25.300
03:02:15
Using these data types allows the API to receive and return date/time values using the
XSD format. These data types can be used only for Public and Protected APIs and
need the API signature validation feature to be enabled.
When these data types are used in the INPUT section of the API_DOC the engine will
allow the incoming date to be in XSD format or in native format. It will parse the
incoming date and convert it to native date format. The converted value will be in
server timezone for xsdDateTime data type. Within an X-Rule the date value available
is always in the native format.
When these data types are used in the OUTPUT section of the API_DOC of a rule that
is invoked by an external caller the engine will convert the native date format to XSD
format and return it to the external caller. If such an API is called internally by another
rule then this conversion to XSD format is not performed and the native date is
returned as is.
These data types can also be used when specifying the signature of events using
EVENT_DOC tag. For events the engine will do parse the incoming date and convert
it to native date format.
Specifying that an Attribute is Optional

By default, an attribute declared in the interface definition is mandatory. You can
specify that an attribute is optional by providing the Optional modifier in the data type
declaration as shown below.
<CREATION_DATE Value="01/01/2004 10:23:42[Type=datetime,
Optional=true]"/>

The API_DOC IDL
Specifying that a Tag is Optional

By default, a tag declared in the interface definition is mandatory. You can specify
that a tag is optional by providing the Optional attribute in the tag declaration. The
following example illustrates the use of the optional attribute for a tag:
<TPA_ID Value="[Type=string(64)]" Optional="true"/>
Allowing Extra Attributes on a Tag

For XSDs, a tag cannot have attributes other than those that are declared in the
interface definition. To allow additional tags that are not validated by the XSD,
provide the Any attribute in the tag declaration as shown below.
<RESPONSE Status="Success[Type=Constant, Optional=true]"
Any="true" />
Note that by default both the Validation Framework and ABPP ignore extra attributes
on a tag. As such, this directive only applies to XSD generation.
Specifying the Order of Child Tags

For XSDs, the default compositor for grouping tags is xsd:all. This compositor
specifies that the elements are unordered. However, there are restrictions on the cases
where this compositor can be used in an XSD. In the cases where unordered grouping
conflicts with other XSD hints (see the ANY and CHOICE_OF tags and the
Repeatable attribute below), the child tags must be declared as ordered. This is
accomplished by specifying the OrderIndicator attribute on the parent tag declaration
as show below.
OrderIndicator="true">
<TPA_ID Value="12Q345QDW5[Type=string(64)]" />
<TPA_NAME Value="Hitachi-Dell-1[Type=string(32)]" />
</RESPONSE>
Note that by default the Validation Framework and ABPP do not require tags to be in
any order. As such, this directive only applies to XSD generation.
Allowing Extra Child Tags

For XSDs, only tags that are declared in the interface definition are permitted. To
allow additional tags that are not validated by the XSD, insert the ANY tag as shown
below.
OrderIndicator="true">
<ANY />
</RESPONSE>
Note that by default the Validation Framework and ABPP ignore extra tags. As such,
this directive only applies to XSD generation. Also note that if used for XSD
generation, the ANY tag requires that the parent tag (in this case the RESPONSE tag)
has the OrderIndicator hint set to true.

Allowing Repetitions of a Tag

By default, it is assumed that a tag occurs once and only once. It is possible to specify
that a tag can occur many times by setting the Repeatable hint to true in the tag
declaration (as shown below).
<TPAS OrderIndicator="true" TotalRowCount="1[Type=int,
Optional=true]">
<TPA Repeatable="true" Optional="true" Any="true">
<AUTO_HANDLING Value="MANUAL|AUTO" Optional="true" />
<CMI_ER_TYPE Value="[Type=string]" Optional="true" />
<CREATION_DATE Value="01/01/2004 10:23:42[Type=datetime]"
Optional="true" />
<CUST_NAME Value="[Type=string]" Optional="true" />
<CUST_ORG_ID Value="[Type=string]" />
<TPA_NAME Value="[Type=string(64)]" />
<TPA_TYPE Value="someString" />
</TPA>
</TPAS>
Specifying a Choice of Tags

It is possible to specify that one of several groups of tags is acceptable as input. This
can be accomplished by using the CHOICE_OF and CHOOSE tags as shown below.
<FILTER Name="TPA_ID" Repeatable="true" OrderIndicator="true">
<CHOICE_OF>
<CHOOSE>
<TPA_ID Value="someString"
MatchBy="STARTS_WITH[Type=stringCompare]"
Optional="true" Comment="element name() = FILTER/
@Name"/>
</CHOOSE>
<CHOOSE>
<OR OrderIndicator="true">
MatchBy="STARTS_WITH[Type=stringCompare]"
Repeatable="true"
Comment="element name() = FILTER/@Name"/>
</OR>
</CHOOSE>
</CHOICE_OF>
</FILTER>
Note that if used for XSD generation, the CHOICE_OF / CHOOSE tags require that
the parent tag (in this case the FILTER tag) has the OrderIndicator hint set to true.
API_DOC Language Extensions

The API_DOC IDL can be extended using the standard ABPP extension mechanism.
Thus, new constructs can be added to the language simply by registering handlers for
them. Details on adding custom extensions for the API_DOC IDL can be found in
Appendix C.

There are several language extensions that come packaged with API_DOC. Details
on these are given in the following sections.
Referencing Declarations in an X-Document

It is often the case that the tags specified in an API map directly from tags defined in
an X-Document. Instead of declaring these tags separately, it is best to simply
reference the existing definition. The REFER_DOC directive provides the means to
accomplish this, as shown below.
<TPA>
<REFER_DOC Name="TPA" ServiceName="service-name[Optional=true]">
<MANDATORY_PROPS>
<TPA_NAME />
<TPA_TYPE />
<CUST_ORG_ID />
<SUPP_ORG_ID />
</MANDATORY_PROPS>
<EXCLUDE_PROPS>
<CREATION_DATE />
<LAST_MOD_DATE />
</EXCLUDE_PROPS>
<RENAME_PROPS>
<TPA_NAME Alias="NAME" />
<SUPP_NAME Alias="SUPPLIER_NAME" />
</RENAME_PROPS>
</REFER_DOC>
</TPA>
The REFER_DOC directive takes two attributes. The Name attribute must be set to
the name of the X-Document being referenced. The ServiceName attribute is
optional, and specifies the name of the Xservice where the X-Document is defined.
As shown, all tags defined in the X-Document named TPA are included as optional
tags by the REFER_DOC directive. There are two optional child tags that can be used
to modify this default behavior. The MANDATORY_PROPS tag is used to specify
the names of all the X-Document tags which are required tags in the interface
definition. The EXCLUDE_PROPS tag is used to specify the names of all the X-
Document tags which are to be excluded from the interface definition.
The REFER_DOC directive can contain one more optional child tag. There are cases
where a referenced X-Document property is called by another name in the interface
definition. The RENAME_PROPS tag contains a list of X-Document properties and
their 'aliases' in the interface definition. When a property is copied, it is renamed
using the defined alias.
During WSDL generation the REFER_DOC short cut will expand to the following
form:
<TPA>
<TPA_ID Value="someString" Optional="true" />
<AUTO_HANDLING Value="someString" Optional="true" />
<CMI_ER_TYPE Value="someString" Optional="true" />
<CUST_NAME Value="someString" Optional="true" />
<CUST_ORG_ID Value="someString" />
<DAILY_PLANNING_WEEKS Value="5[Type=int]" Optional="true" />
<DESCRIPTION Value="someString" Optional="true" />

<END_DATE Value="01/01/2004 10:23:42[Type=datetime]"

Optional="true" />
<FCST_DOC_META_ID Value="someString" Optional="true" />
<FIRM_IDENTIFIER_TYPE Value="someString" Optional="true" />
<START_DATE Value="01/01/2004 10:23:42[Type=datetime]"
Optional="true" />
<STATUS Value="someString" Optional="true" />
<SUPP_NAME Value="someString" Optional="true" />
<SUPP_ORG_ID Value="someString" />
<TPA_NAME Value="someString" />
<TPA_TYPE Value="someString" />
</TPA>
An alternate form of the REFER_DOC directive is shown below. In this case, only
the tags specified inside INCLUDE_PROPS are copied to the interface definition.
These tags are included as mandatory by default; they are included as optional if the
Optional attribute is given.
<TPA>
<REFER_DOC Name="TPA" ServiceName="service-name[Optional=true]">
<INCLUDE_PROPS>
<TPA_NAME />
<TPA_TYPE Repeatable="true" />
<CUST_ORG_ID />
<SUPP_ORG_ID Optional="true" />
</INCLUDE_PROPS>
<RENAME_PROPS>
<TPA_NAME Alias="NAME" />
</RENAME_PROPS>
</REFER_DOC>
</TPA>
Referencing a Search Spec

Another common case is that an API is defined by a search spec. In this case, the
search spec itself defines the tags and their structure. Instead of expanding the search
spec definition by hand, it is best to simply reference the existing definition. The
REFER_SEARCH_FILTER directive provides the means to accomplish this, as
shown below.
<REQUEST Name="getTPA" OrderIndicator="true"
MaxRows="10[Type=int,Optional=true]"
ReturnRowCount="yes[Type=Constant, Optional=true]"
StartAtRow="0[Type=int, Optional=true]">
<REFER_SEARCH_FILTERS Name="PROGRAM_SEARCH" />
</REQUEST>
The REFER_SEARCH_FILTER directive takes a Name attribute, which must be set

to the name of the search spec being referenced.
Assume that the Xservice contains the following search spec definition:
<search-defs>
<search-def Name="PROGRAM_SEARCH" Document="TPA">
<filter-def Name="TPA_ID" />
<filter-def Name="TPA_NAME" />
<filter-def Name="TPA_TYPE" />
<filter-def Name="DESCRIPTION" />
<filter-def Name="START_DATE" />

<filter-def Name="CUST_ORG_ID" />

<filter-def Name="SUPP_ORG_ID" />
<filter-def Name="STATUS" />
<filter-def Name="END_DATE" />
<filter-def Name="CUST_NAME"
MapTo="CUSTOMER_EM_ORGANIZATION_LINK/NAME" />
<filter-def Name="SUPP_NAME"
MapTo="SELLER_EM_ORGANIZATION_LINK/NAME" />
</search-def>
</search-defs>
During WSDL generation, the example above will be expanded to

the following:
<REQUEST Name="getTPA" OrderIndicator="true"
MaxRows="10[Type=int,Optional=true]"
ReturnRowCount="yes[Type=Constant, Optional=true]"
StartAtRow="0[Type=int, Optional=true]" Any="true">
<FILTER Repeatable="true" OrderIndicator="true"
Name="TPA_ID|TPA_NAME|TPA_TYPE ">
<CHOICE_OF>
<CHOOSE>
MatchBy="STARTS_WITH[Type=stringCompare]" Repeatable="true"
Optional="true" Comment="element name() = FILTER/@Name" />
<OR OrderIndicator="true" Repeatable="true"
Optional="true">
</OR>
</CHOOSE>
<CHOOSE>
<TPA_NAME Value="someString"
Optional="true">
<TPA_NAME Value="someString"
</OR>
</CHOOSE>
<CHOOSE>
<TPA_TYPE Value="someString"
Optional="true">
<TPA_TYPE Value="someString"
</OR>
</CHOOSE>
</CHOICE_OF>
</FILTER>
</REQUEST>

Referencing a Validation Spec

Yet another common case is that the error responses for an API are defined as part of a
Validation Framework Spec (VFS) file. In this case, the tags and their structure are
defined by the output of the Validation Framework. Instead of expanding the error
responses by hand, it is best to simply reference the existing definition. The
REFER_VALIDATION_ERRORS directive provides the means to accomplish this, as
shown below.
<ON_EXCEPTION>
<REFER_VALIDATION_ERRORS Name="createTPA" />
</ON_EXCEPTION>
The REFER_VALIDATION_ERRORS directive takes a Name attribute, which must
be set to the name of the validation spec being referenced. This typically matches the
API name.
Assume that the Xservice contains the following in the validation spec for the
createTPA API:
<user_validations>
<user_validation Name="createTPA" ServiceName="CPM">
<error_codes>
<error_code Name="TPA_MISSING" Severity="ERROR" />
<error_code Name="REQUIRED_FIELD_MISSING" Severity="ERROR"
/>
<error_code Name="DUPLICATE_TPA_NAME" Severity="ERROR" />
<error_code Name="INVALID_TPA_TYPE" Severity="ERROR" />
<error_code Name="INVALID_CUST_ORG_ID" Severity="ERROR" />
<error_code Name="INVALID_SUPP_ORG_ID" Severity="ERROR" />
<error_code Name="INVALID_STATUS" Severity="ERROR" />
<error_code Name="INVALID_VALUE" Severity="ERROR" />
<error_code Name="INVALID_DAILY_PLANNING_WEEKS"
Severity="ERROR" />
</error_codes>
<tags>
<tag Name="TPA">
<fields>
<field Name="TPA_NAME" Type="string">
<validations>
<validation_group>
<mandatory_validation
Error="REQUIRED_FIELD_MISSING" />
<validation Expression="getFirstDoc('/
/CPM/TPA','TPA_NAME',$thisField) = null" Error="DUPLICATE_TPA_NAME" />
</validation_group>
</validations>
</field>
<field Name="TPA_TYPE" Type="string">
<validations>

<validation_group>
<mandatory_validation
Error="REQUIRED_FIELD_MISSING" />
<validation
Expression="isValidValue($thisField,'VMI','CMI-ER')"
Error="INVALID_TPA_TYPE" />
</validation_group>
</validations>
</field>
</fields>
</tag>
</tags>
</user_validation>
</user_validations>
During WSDL generation, the example above will be expanded to the
following:
<ON_EXCEPTION>
<RESPONSE>
<_RESULT Value="ERROR[Type=Constant]"
Details="true[Type=Constant,Optional=true]" OrderIndicator="true">
<_ERROR
Value="TPA_MISSING|REQUIRED_FIELD_MISSING|INVALID_DAILY_PLANNING_WEEKS
|INVALID_STATUS|INVALID_SUPP_ORG_ID|INVALID_TPA_TYPE
|INVALID_CUST_ORG_ID|INVALID_VALUE |DUPLICATE_TPA_NAME"
Optional="true" Repeatable="true" OrderIndicator="true"
Severity="ERROR[Type=Constant]">
<ANY />
</_ERROR>
</_RESULT>
<REQUEST Name="createTPA" Any="true" Comment="This API creates
TPA">
<TPA>
<TPA_ID Value="someString" Optional="true" />
<TPA_NAME Value="someString">
<_ERRORS Value="ERROR[Type=Constant]"
Optional="true" OrderIndicator="true">
<_ERROR
Value="REQUIRED_FIELD_MISSING|DUPLICATE_TPA_NAME" Optional="true"
Repeatable="true" OrderIndicator="true"
<ANY />
</_ERROR>
</_ERRORS>
</TPA_NAME>
<TPA_TYPE Value="someString">
<_ERRORS Value="ERROR[Type=Constant]"
Optional="true" OrderIndicator="true">
<_ERROR
Value="REQUIRED_FIELD_MISSING|INVALID_TPA_TYPE" Optional="true"
Repeatable="true" OrderIndicator="true"
<ANY />
</_ERROR>
</_ERRORS>
</TPA_TYPE>

<_ERRORS Value="ERROR|SEVERE_ERROR" Optional="true" />

</TPA>
<_ERRORS Value="ERROR|SEVERE_ERROR" Optional="true" />
</REQUEST>
</RESPONSE>
</ON_EXCEPTION>
Advanced Features
It is possible to generate a validation error response from multiple validation specs.
This is very useful when you have multiple validation specs exercised on the API.
The following example shows how to use three validation specs to generate the
validation error response for an API:
<ON_EXCEPTION>
<REFER_VALIDATION_ERRORS
Name="orderCreateValidation|poCreateValidation|poItemValidation" />
</ON_EXCEPTION>
It is possible to select a portion of the error response for insertion into the generated
API_DOC. This can be accomplished by using VAL_OUTPUT. The following
example shows how to include only the sub-tree under REQUEST/ORDER as part of
this API’s documentation.
<ON_EXCEPTION>
<RESPONSE Status="Success[Type=Constant]">
<_RESULT Value="ERROR|SEVERE_ERROR" />
<ORDER ValidationResult="ERROR|SEVERE_ERROR">
Name="orderCreateValidation">
<VAL_OUTPUT Path="REQUEST/ORDER" />
</REFER_VALIDATION_ERRORS>
</ORDER>
</RESPONSE>
</ON_EXCEPTION>
Referencing other API_DOCs

Sometimes the tags passed to an API are used to internally invoke another API. In this
case, the definition of these tags and the hints associated with them are actually
already defined. The REFER_API_DOC directive can be used to reference the
definition of another API and inline the definition.
<REQUEST Name="attachBufferSLAsWithMultipleShipTos" Any="true"
Comment="Given a program and item, create multiple buffers with
settings">
<SOURCE Value="someString" />
<BUFFER_SLA>
<TPA_ID Value="someString" />
<ITEM_ID Value="someString" />
<SHIP_TO_IDS OrderIndicator="true">
<SHIP_TO_ID Value="someString" Repeatable="true" />
</SHIP_TO_IDS>
<CATEGORY_ID Value="someString" Optional="true" />

Appendix A: Generating Xservice WSDL
<REFER_API_DOC Name="createCmiErSettings" Path="INPUT/

REQUEST" ServiceName="CPM" />
</BUFFER_SLA>
</REQUEST>
The example above shows how to inline the input request of the createCmiErSettings
API, pulling in everything under (but not including) the REQUEST tag.
During WSDL generation, the example above will be expanded to the following:
<REQUEST Name="attachBufferSLAsWithMultipleShipTos"
Comment="Given a program and item, create multiple buffers with
settings">
<SOURCE Value="someString" />
<BUFFER_SLA>
<TPA_ID Value="someString" />
<ITEM_ID Value="someString" />
<SHIP_TO_IDS OrderIndicator="true">
<SHIP_TO_ID Value="someString" Repeatable="true" />
</SHIP_TO_IDS>
<CATEGORY_ID Value="someString" Optional="true" />
<CMI_ER_SETTINGS>
<ID Value="someString" Optional="true" />
<FIRM_WINDOW Value="5[Type=int]" />
<FROZEN_WINDOW Value="5[Type=int]" />
<IS_CATEGORY Value="someString" Optional="true" />
<NAME Value="someString" Optional="true" />
<CMI_VIOLATIONS OrderIndicator="true">
<CMI_VIOLATION Repeatable="true">
<ID Value="someString" Optional="true" />
<VIOLATION_NAME Value="someString" />
<RESOLUTION Value="someString" />
</CMI_VIOLATION>
</CMI_VIOLATIONS>
</CMI_ER_SETTINGS>
</BUFFER_SLA>
</REQUEST>

ABPP is now packaged with a utility to generate WSDL descriptions for the APIs
exposed by an Xservice. There are two prerequisites to using the utility:
1. Each Xservice API must be assigned an access privilege. There are 3 levels of
access possible:
| Public: Can be invoked by all clients.
| Protected: Can only be invoked by the owning Xservice and other co-located
Xservices. (This is the default access level.)
| Private: Can be invoked only by the owning Xservice.
2. Any Xservice method that is to be exposed as a web service must specify its
interface description using API_DOC.
3. The default setting is the generate XSDs and WSDL only for Public APIs.

The following code segment illustrates how to assign an access privilege to an API:
<DEFINE_METHOD Name="createTPA" Access="Public">
<API_DOC>

</API_DOC>
<RULE>

</RULE>
</DEFINE_METHOD>
Once the Xservice APIs have been assigned access privileges and the interfaces have
been defined using API_DOC, the Xservice WSDL can be generated as follows:
1. Specify the output directory for the generated WSDL files. This is accomplished
by adding the following section to the xserver.xml file:
<dom-config>
…
<WSDLGenerate>
<SOAPAddr Value="http://localhost:4444"/>
<outputDir Value="C:\Temp\WSDL"/>
/WSDLGenerate>
…
</dom-config>
SOAPAddr: Note that the SOAP address is used to define the Xservice WSDL. In
the above example, it is referring to a direct port to the ABPP Server.
It is also possible to make calls through the Web Service servlet of ABPP. The
advantages of sending through the web service servlet are that the SOAP client calls
are authenticated with the Active User Security service of ABPP, and the SOAP
messages can be sent securely by using HTTPS. In this mode, you send the user name
and password information in the SOAP header. If you prefer using this mode for
connecting to ABPP, you may either change the SOAPAddr Value above to “http://
your web url/abppws” where abppws is the name of the Web Service servlet of
ABPP, or you may change the address in the generated WSDL files later when you
deploy for using the servlet based Web Service. Every time you change the
SOAPAddr or outputDir in the xml above, you need to regenerate the wsdl files in
order to effect those changes.
outputDir: The output directory is the root directory for all generated files. The
WSDL generator will create a subdirectory for each Xservice, and store the generated
WSDL files appropriately. Also note that the output directory is cleared each time the
WSDL generator is run.
2. Create a batch file containing the xserver.xml and all desired Xservice config files
(e.g., em.xml, orderadmin.xml, …) as follows:
@echo off
call .\omxenv.bat
title OMx Server
java com.i2.xcore.wsdl.WsdlGenerator xserver.xml em.xml
orderadmin.xml …
pause

3. Run the batch file and check the output directory for the generated files. For each
deployed Xservice, the WSDL generator will create a folder with the same name
as the service name. Each service folder will contain:
a. WSDL file for the service. The file name for this is : <<service-name>>.wsdl
b. For each Xservice API included in the WSDL spec, the WSDL generator will
create:
z XML file containing the 'expanded' form of the API_DOC,
z XSD file based on the expanded API_DOC XML,
z VFS file based on the expanded API_DOC XML.
In your service log files, make sure there are no WSDL generator errors related to the
API_DOC structure. If there are, fix those errors and re-run the WSDL generator.
The generated Xservice WSDL files can now be used to perform validation on the
APIs as explained in Appendix B, generate API documentation and/or test cases, etc.
The steps explained above generate XSDs and WSDL definition for all public APIs of
the service specified. If you don't want to generate WSDL for all public APIs the steps
to follow are explained below
1. Add <apiFilterFile> tag under <WSDLGenerate> as shown below
<WSDLGenerate>
<apiFilterFile Value="WSDLApiFilter.xml"/>
…
</WSDLGenerate>
2. The apiFilterFile specifies the APIs for which to generate the XSDs and WSDL.
The format of this file is:
<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 under ORDER_ADMIN service only "createPo" and
"changeLines" APIs should be included in the WSDL. Also 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. This file serves as a filter on top of access level filter. The default access
level filter is "Public" APIs.
Having this control will help in coming up XSD/WSDL for customer implementations
where only few of the total available APIs are to be published.

Appendix B: Validating Xservice APIs at Runtime

Any command invocation can be validated for conformance with the input & output
signatures defined in the API_DOC of that command. This is accomplished by:
z Setting ValidationApiSignatures attribute to true on the element in the Xservice
config file. This will validate any command with access privilege of Public or
Protected.
OR
z Setting ValidateSignature attribute on the command to true. This will work even
for commands with access privilege of Private.
If signature validation is enabled for a command (by service default or by setting it on
the command ) then the system will throw an error at server start up if API_DOC is
not provided for it.
Signature validation of a command will fail ( and an exception will be raised) if:
1. The command input doesn't conform to the API_DOC definition.
2. The command output doesn't conform to the API_DOC definition.
Some times when the command input/output fails signature validation, it may be not
be very obvious to spot the reason for the failure. In many situations looking at the
validation code that was used to validate can help in identifying the problem with the
input/output. The validation code can be viewed by:
z Enabling the SystemInfo log level on a service. This will log the internally
generated validation code whenever the command is being invoked for the first
time in the server VM.
z Invoking the utility command on the service as shown below:
<GET_APIDOC_VALIDATION_SPEC>
<API_NAME Value="name-of-api"/>
</GET_APIDOC_VALIDATION_SPEC>
The command output will contain the auto-generated validation code.
Appendix C: Testing the WSDL API

Setup Server:
In the i2 Studio,
1. Right-Click on the Web Services link on the left pane,
2. Choose Insert New group…
3. Specify a name that is representative of the xservice that is offering the WSDL
Operations.
4. You will see a child entry under the Web Services link, for the group you just
created.
5. Right-click on that and choose 'Insert'.

Appendix C: Testing the WSDL API
6. In the popup, choose 'File Based' in order to register the WSDL file(s) that were
generated.
7. In the next step, specify the WSDL file name.
8. Now the details in that file will be loaded as children under the group you just
created.
9. Important Step: Right Click on the child of the Group, and choose 'Activate'. This
would put the relevant entry into the xserver.xml file.
Setup Client:
The WSDL Interface generated above can be tested using the XWorkflow's WSDL
Node acting as a client for the WSDL API.
In a test service, using i2 Studio create an XWorkflow and include the WSDL Node in
the workflow.
Double click on the WSDL Node and specify the WSDL Operation (your WSDL
API), and construct the API input body within the Wsdl Transform Input tab, where it
indicates where the code should go. Close and save the XWorkflow.
Note: It would be convenient to include an Event Descriptor in the start node, so that
you could invoke this workflow using the standard REQUEST tag, specifying the
name of the event descriptor.
Invoke the Client:
z Form an XML Request file, to invoke the client XWorkflow that you just created.
z Post the request to the XServer running your WSDL server.
Note: If you get the follow error, then you need to include lib\
httpclientLogging.jar in the classpath for your XServer:
java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory


Chapter 3
Validation
Introduction
The ABPP server allows the user to define rules that take an xml document as input
and execute some business process. The xml document that is received as input may
need to satisfy some restrictions specified by the rule e.g. the input should have a
supplier id and it should be a valid value as per the data in the system.
The validation framework is a utility that can be used by the rule to validate that the
xml document sent to it satisfies its requirements. The validation framework allows
for defining validation rules for elements in the input xml. The framework will
validate the xml passed to it and mark any errors by inserting _ERROR tag at
appropriate places. The framework also provides additional feature of auto-fills where
some missing data can be filled in with default values.
Validation specification
Overview
The validation specification is an xml file that defines the validations using the
grammar of the validation framework. The validation specification file can have
multiple validation definitions in it. Each validation definition has a unique name and
defines the validation rules for various elements of the input xml.
The rule that needs to validate some input xml uses commands
INVOKE_VALIDATION_FRAMEWORK or VALIDATE_DOC to invoke the
validation framework and passes the name of the validation definition to execute and
the input xml that needs to be validated. The validation framework will execute all the
validation rules defined in the validation definition and mark errors under appropriate
elements and return the marked xml as the response. Here is an example of how the
errors are marked in the response (output) xml.
Input Xml:
<CUSTOMER_ORDER>

Chapter 3 Validation
<DOC_TYPE Value="DRAFT1"/>
<CREATED_BY_ID Value="user01"/>
....
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ITEM_ID Value="InvalidItem"/>
<ORDERED_QTY Value="6"/>
<UOM Value="EA"/>
....
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
Output from validation:
<RESPONSE ValidationResult="ERROR">
<_RESULT Value="ERROR" Details="true">
<_ERROR Value="INVALID_DOC_TYPE" Severity="ERROR"/>
<_ERROR Value="INVALID_ITEM" Severity="ERROR"/>
</_RESULT>
<CUSTOMER_ORDER>
<DOC_TYPE Value="DRAFT1">
<_ERRORS Value="ERROR">
<_ERROR Value="INVALID_DOC_TYPE"
Severity="ERROR"/>
</_ERRORS>
</DOC_TYPE>
....
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM>
<ITEM_ID Value="151-S">
<_ERROR Value="INVALID_ITEM"
Severity="ERROR"/>
</_ERRORS>
</ITEM_ID>
<UOM Value="EA"/>
....
<_ERRORS Value="ERROR"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
</RESPONSE>
The format shown above is the preferred format of representing errors in ABPP. The
ABPP UI components (PGL specification) understand this format of errors and can
display the errors to the user on the user interface. Refer to PGL Reference guide for
details on how the error highlight can be turned on.

Specification Structure
The structure of the validation specification file should be as follows:
<user_validations>
<user_validation Name="..">
<error_codes>
<error_code Name=".."
Severity="SEVERE_ERROR|ERROR|WARNING|INFO" />
... other error_code ...
</error_codes>
<tags>
<tag Name="..">
<variables>
... variable definition ...
</variables>
<validations>
... validation rules for tag ...
</validations>
<fields>
<field Name=".." Type="string">
<validations>
... validation rules for field ...
</validations>
<autofills>
... auto fill for field ...
</autofills>
<postfills>
... post fill for field ...
</postfills>
</field>
... other field ...
<tag Name="..">
..variables, fields & validation tags..
<tag>
.....
</tag>
</tag>
</fields>
</tag>
... other tag ...
</tags>
</user_validation>
... other user_validation ...
</user_validations>
The individual elements used in the above specification are explained below:
<user_validation>: This defines a validation with “Name” attribute defining the
name of the validation. The name should be unique within a service. It is
recommended that this name be same as the rule name that is going to call this
validation.

<error_code>: The <error_codes> element lists all the errors that the validation can
generate. The Name attribute of <error_code> gives the error name. The Severity
attribute defines the severity for given error. Valid values are SEVERE_ERROR,
ERROR, WARNING and INFO. The end result of the validation is the highest level
of all errors found. If the validation framework encounters a validation rule that has an
error code with severity level of SEVERE_ERROR then the validation execution will
stop and the response will be sent back immediately. For other severity levels the
execution will continue and the response will be returned after completing all the
validation rules.
<tag>: The <tag> element defines validation rules to be executed on the input xml
element which matches the name of the tag. For example if the tag is <tag Name =
“CO”> the validation is performed on the <CO> element in the input xml. It is
recommended in the usage of the validation specification that elements of the input
xml that have child elements be validated using the <tag>. For example in the INPUT
XML presented in the Overview section, CUSTOMER_ORDER or
ORDER_LINE_ITEM elements would be validated using the <tag> element of the
validation specification.
Notice that <tag> elements can be nested within each other. The nested <tag> element
are used for validating the child elements of the current element. The logic used by the
validation framework to identify the <tag> element to be used for validating an
element ( example, CUSTOMER_ORDER or ORDER_LINE_ITRM) is explained
below using the INPUT XML presented in the Overview section:
When the validation framework encounters ORDER_LINE_ITEM element while
processing the child elements of CUSTOMER_ORDER element, It looks up to see if
there is a <tag> element for ORDER_LINE_ITEM defined within the <tag> element
for CUSTOMER_ORDER.
If it is defined then
It uses the <tag> element to validate the ORDER_LINE_ITEM element.
Else
It looks up to find a <tag> element defined for ORDER_LINE_ITEM within the
immediate child <tag>s of the <tags> element (i.e., a <tag> element defined at the
top level for that spec). If a <tag> element is found then it is used for validating
the ORDER_LINE_ITEM element. Otherwise no validation is performed on the
ORDER_LINE_ITEM element.
Validating the child tags using the <tag> element defined at the top level of the spec
(i.e ., immediate child of <tags>) will be limiting when the input XML contains
elements with the same names but different structures depending on the parent
element enclosing them.
Example:
Consider the following input XML:
<Order>

<Id Value="1" />

<CancelledLines>
<Line Repeatable="true">
<Id Value="1" />
</Line>
</CancelledLines>
<AddedLines>
<Line Repeatable="true">
<Id Value="1" />
<ItemId Value="C-151-S" />
<Qty Value="10" />
<Price Value="100.0" />
</Line>
</AddedLines>
</Order>
The Line element within CancelledLines element has a different structure than the
Line element within AddedLines elements. Hence it is necessary to define nested
<tag> for Line element within the different parent <tag>s to distinguish between the
different structures. The validation structure will be as follows:
<tags>
<tag Name="CancelledLines">
<tag Name="Line">

</tag>
</tag>
<tag Name="AddedLines">
<tag Name="Line">

</tag>
</tag>
</tags>
<variables>: This can be used to define a set of variables that are accessible while
validating the current tag.
<field>: This element of the validation specification is used to validate leaf nodes of
the input xml that belong to a parent that is specified in <tag> above. For example
ITEM_ID or ORDERED_QTY etc. in the INPUT XML above would be validated
using the <field> element of the validation specification.
<validations>: This is used to define the list of validation rules. There are various
types of validation rules. e.g. data type validation, mandatory validation, validation
with expression and validation with x-rules. These are explained in subsequent
sections of this chapter.
<autofills>: This is used to define a list of autofill rules. The autofill rules are
executed before validation only if the input xml is missing the defined field. In such
cases the autofill can be used to fill default values for the field.
<postfills>: For some fields the value needs to be a fixed value based on certain
criteria. In such cases even if the input xml has different value it is fine to over-write
that with the correct value. This is especially useful for cases where some field is not

expected in the input xml and the system should use right value even if the field is
given in input with wrong value. The postfill rules are executed at the end of
validation and can be used to over-write input values.
The following sections will explain the components of validation specification in
more details.
Definition of XML Attributes used in defining validation

specification
The validation specification allows for various attributes on the elements of the
validation specification. Many attributes are shared across several elements and have
the same meaning. The following section summarizes various attributes allowed, their
meaning and where in validation specification they are used.
z Name: Allowed in <user_validation>/<variable>/<validation>/<autofill>/
<postfill>/<field>/<tag>. Defines the name depending on the element in which
this "Name" attribute is defined e.g. <error_code
Name="MISSING_REQUIRED_FIELD" Severity="SEVERE_ERROR"/>
z Severity: Allowed in <error>. Defines the severity of error. Valid values:
INFO|WARNING|ERROR|SEVERE_ERROR e.g. <error_code
Name="MIN_QTY_VIOLATION" Severity="ERROR"/>
z IsFilter: Allowed in <variable>. Default is false. If IsFilter="true" then
expression used to compute variable should return boolean value e.g. <variable
Name="shipModeDetails" ... IsFilter="true"/>
z IsNoCache: Allowed in <variable>. Default is false. If this is false then the
variable is computed once when it is first time referred and then computed value is
used when it is referred afterwards. If this is false then the variable is computed
every time it is referred. e.g. <variable Name="shipModeDetails"...
IsNoCache="true"/>
z Expression: Allowed in <variable>/<autofill>/<postfill>/<validation>. This is
the X-Path expression to compute value of variable/autofill/postfill/validation
depending on the tag in which this attribute is defined e.g. <validation
Name="checkNonEmptyField" Expression="($thisField != null) ..../>
z FilterExp: Allowed in <validation>/data_type_validation>/
<mandatory_validation>/<autofill>/<postfill>. This defines the X-Path
expression to compute filter. If the expression results is true then the
corresponding validation action will be executed. e.g. <validation
Name="validate" FilterExp="$thisField != null" ..../>
z FilterName: Allowed in <validation>/data_type_validation>/
<mandatory_validation>/<autofill>/<postfill>. This defines the variable name of
to use to compute the filter. If the variable is true then the corresponding
validation action will be executed. One of FilterExp or FilterName should be
specified. If both are specified then FilterExp will take precedence. e.g.
<validation Name="validate" FilterName="isValidBillTo" ..../>
z Error: Allowed in <validation>. This defines the error_code to use when
validation fails and should be one of the errors defined under <user_validation>.
e.g. <validation Name="validate" .. Error="INVALID_VALUE"/>

z IsActive: Allowed in <validation>/data_type_validation>/

<mandatory_validation>/<autofill>/<postfill>/<validation_group>. Default is
true. If some validation action is marked false then it will not be evaluated. e.g.
<validation Name="validate" .. IsActive="false" Error="INVALID_VALUE"/>
Variables
While defining the validation rules there are various variables available for use in the
rules. There are two types of variables: implicit variables and user defined variables.
Implicit Variables
z thisDoc refers to current tag .
Example: "count($thisDoc/ORDER_LINE_ITEMS/ORDER_LINE_ITEM) > 0"
z thisField refers to current field value.
Example: "$thisField > 0"
z previousDoc refers to the previous document with the same name
Example: "$previousDoc/ID/@Value
z nextDoc refers to the next document with the same name
Example: "$nextDoc/ID/@Value"
z previousDocList refers to the list of previous documents
Example: "$previousDocList[ORDER_TYPE_ID/@Value='STANDARD']/ID/
@Value"
z nextDocList refers to the list of documents to follow
Example: "$nextDocList[ORDER_TYPE_ID/@Value='STANDARD']/ID/
@Value"
z thisFieldDoc refers to current field .
Example:"$thisFieldDoc/@OldValue != null"
z thisParent refers to current tag's parent tag.
Example 1: "$thisParent/ITEM_ID/@Value"
Example 2:"$thisParent[name() = 'CUSTOMER_ORDER']/ORDER_TYPE_ID/
@Value"
User defined variables

In addition to the above pre-defined variables users can define their own variables.
Variables can be defined under the <tag> element. These variables can be defined in
two ways:
z Using an Expression attribute which is evaluated to get the value of the variable.
<variable Name="myVar" [IsFilter="true|false"]
Expression="some-expr" [IsNoCache="true|false"]/>
IsFilter = false and IsNoCache=false are the default
values.

z Using the x_rule tag in the body of the variable. When you use x_rule to define a
variable, you have to return the variable value using <RETURN
Expression="expr" /> statement. The x_rule has access to all the other validation
variables. Example of a variable defined using x_rule is shown below:
<variable Name="item" [IsFilter="true|false"]
[IsNoCache="true|false"] >
<x_rule>
<IF_TEST Test="$suppItem != null">
<THEN>
<PRINTLN Value=""/>
<RETURN Expression="$suppItem"/>
</THEN>
<ELSE>
<RETURN Expression="$custItem"/>
</ELSE>
</IF_TEST>
</x_rule>
</variable>
IsFilter = false and IsNoCache=false are the default values.
Types of validations
There are three kinds of validation tags to specify the validation you want to perform.
There is one for data type validation, one for mandatory data validation and one for
generic validations using an expression/x-rule (validations based on business rules).
Although you can use generic validations in all cases it is recommended that you use
data type validation and mandatory validation tags instead of writing them as generic
validations for ease of use.
These validations are specified under the <validations> tag. In addition to these three
types the user can also use <validation_group> under the <validations> tag. Usage of
<validation_group> is explained below.
data_type_validation
This validation can be used only for field validation. This validation makes sure that
the value of the field is of the specified data type. The system uses a predefined Error
Code = INVALID_<Type Specified> for this validation. For example if the Type
specified is ‘int’ the error code will be ‘INVALID_int’. Shown below is an example of
the usage of a data_type_validation:
<data_type_validation [FilterExp="some-expression"]
[Severity="SEVERE_ERROR"] Type="positive-int"
[IsActive="true"]/>
Severity:
The severity of the predefined error code is ERROR. The user can optionally provide
a different severity by specifying the Severity attribute.
Type:

This is a mandatory attributes and specifies the data type for the field. In addition to
the standard ABPP data types (int, float, double, string, date, datetime, timestamp,
boolean), following additional data types are supported:
positive-int, positive-float, positive-double
non-negative-int, non-negative-float, non-negative-double
non-positive-int, non-positive-float, non-positive-double
negative-int, negative-float, negative-double
FilterExp: This is optional attribute. If not specified the validation rule will be
evaluated.
IsActive: Defaults to true
mandatory_validation
This validation can be used only for field validation. This validation is to make sure
that there is value for this field. The system uses a predefined Error Code =
MISSING_REQUIRED_FIELD for this validation. Shown below is an example of the
usage of a mandatory_validation:
<mandatory_validation [FilterExp="some-expression"]
[Severity="SEVERE_ERROR"] [IsActive="true"]/>
Severity:
The severity of the predefined error code is ERROR.. The user can optionally provide
a different severity by specifying the Severity attribute.
FilterExp: This is optional attribute. If not specified the validation rule will be
evaluated.
IsActive: Defaults to true
Validation
This validation can be used for field validations as well as tag validations. This kind of
validation can be used to perform any other validation you may require other than the
above two. There are two variations of this validation:
Expression: If the validation condition is simple enough to express as an xpath
expression that evaluates to a boolean value then the Expression attribute can be used.
For example, you may require that a value of the field is always '1'
<validation Name="checkforOne" Expression="$thisField = '1'"
Error="NOT_ONE"/>
Note that ABPP provides a rich library of xpath functions and the user can potentially
invoke rules, get data from database etc.
Embedded x-rule: In some cases instead of invoking a rule through x-path function to
execute the validation logic it may be preferable to embed a small snippet of the rule
code right in the validation specification for the required validation logic. This allows
for better readability but at the expenses of code reuse. The <x_rule> tag can be used
for this purpose. The code inside <x_rule> tag has access to all the validation

variables. The <x-rule> snippet should return the result of the validation through the
<RETURN Expression="<expression>" /> statement. An example of using the x_rule
tag is shown below.
<validation Name="xyz" Error="INVALID_VALUE">
<x_rule>
<SET Var="buckets"
FromValue="{$thisParent[name()='FORECAST']/BUCKETS}"/>
<SET Var="bSpecEndDate"
FromValue="{$thisParent[name()='FORECAST']/END_DATE/@Value}"/>
<SET Var="invalidStartDate" FromValue="false"/>
<IF_TEST Test="date($thisField) <
date($bSpecEndDate)">
<THEN>
<IF_TEST Test="count($buckets/
BUCKET[date(START_DATE/@Value)=date($thisField)]) <= 0">
<THEN>
<RETURN Expression="true()"/>
</THEN>
<ELSE>
<RETURN Expression="false()"/>
</ELSE>
</IF_TEST>
</THEN>
<ELSE>
</ELSE>
</IF_TEST>
</x_rule>
</validation>
Validation_group
The validation_group is not a type of validation by itself but allows for grouping
dependent validations. For example, take the mandatory and data type validations
explained above. If there is no value for the field there is no point in executing the data
type validation for that field. In such a case, you would group mandatory and data type
validations together, with the mandatory validation as the first validation using the
<validation_group> tag. The data type validation will be executed only if the
mandatory validation succeeds. You can group as many validations as you like. The
first failure of a validation stops the execution for that group. Here is an example of
<validation_group> that groups a mandatory validation, data type validation and rule
based generic validation.
<validation_group Name="fromDateValidation">
<mandatory_validation/>
<data_type_validation Type="date"/>
<validation Name="StartDateAlignmentWithBucketSpecCheck"
Error="FROM_DATE_DOES_NOT_ALIGN_WITH_BUCKET_SPEC">
<x_rule>
<SET Var="buckets"
FromValue="{$thisParent[name()='FORECAST']/BUCKETS}"/>
<SET Var="bSpecEndDate"
FromValue="{$thisParent[name()='FORECAST']/BUCKET_DATES/
BUCKET_SPEC_END_DATE/@Value}"/>

<SET Var="invalidStartDate" FromValue="false"/>

<IF_TEST Test="date($thisField) <
date($bSpecEndDate)">
<THEN>
<IF_TEST Test="count($buckets/
BUCKET[date(START_DATE/@Value)=date($thisField)]) <= 0">
<THEN>
<SET Var="invalidStartDate"
FromValue="true"/>
</THEN>
</IF_TEST>
</THEN>
</IF_TEST>
<IF_TEST Test="$invalidStartDate= 'true'">
<THEN>
</THEN>
<ELSE>
<RETURN Expression="true()"/>
</ELSE>
</IF_TEST>
</x_rule>
</validation>
</validation_group>
Autofill/Postfill
Autofills are executed on all the fields before executing validation rules. Autofill logic
is executed on a field if the field does not have any value in the input xml. The result
of the Expression specified for autofill will be set as the value for the field missing in
the input xml. Autofill logic can also be made conditional using FilterName &
FilterExp attributes.
Here is an example of auto fill:
<autofills>
<autofill Name="default" FilterExp="$isCategory"
Expression="'TRUE'" />
<autofill Name="defaultFalse"
FilterExp="$isCategory=false()" Expression="'FALSE'"/>
</autofills>
Postfills are executed on all the fields after the input xml has been validated
successfully. Postfills are not executed if there are any validation errors on the input
xml. Postfill will overwrite the value for the field specified in the input xml. Postfill
logic can also be made conditional using FilterName & FilterExp attributes.
Here is an example of post fill:
<postfills>
<postfill Name="default" Expression="$shipto/LOC_NAME/
@Value" />
</postfills>

Steps involved in using validation framework

This section explains the steps needed to start using the validation specification.
Specify the validation specification file in the appropriate

service configuration file
Include validation specification file in the appropriate service configuration file so
that validation service load the validation specification to do the validation.
Example from orderadmin service:
<dom-config>
<service-config Name="ORDER_ADMIN" TransactionCache="true">
<validationSpecFiles>
<validationSpecFile Name="xservice/orderadmin/xml/
pce/validation/oaCreateOrderValidationBuy.xml"/>
<validationSpecFile Name="xservice/orderadmin/xml/
pce/validation/oaCreateBpoValidationBuy.xml"/>
</validationSpecFiles>
</service-config>
</dom-config>
Note that validation specification file are referred using the relative path and so the
parent directory of the relative path should be in classpath.
Invoke validation framework to validate XML document

ABPP provides following rule action components to invoke validation framework:
INVOKE_VALIDATION_FRAMEWORK
Description:
This component validates the input xml and assigns the validation result to specified
output variable. If ApiName attribute is not provided, it is inferred from the Name
attribute on the root tag of input xml. This component assumes that a validation spec
exists in the service with the same name as the ApiName.
Syntax:
<INVOKE_VALIDATION_FRAMEWORK DocVar="docVarName"
AssignToVar="resultVar"
ServiceName="serviceName[Optional=true]"
ApiName="apiName[Optional=true] Clone="true|false[default=true]
/>
Attributes:
ServiceName (Optional): Name of the service containing the API. If not provided then
the service name is assumed to be the same as the current service which is executing
the component.
DocVar (Required): Variable containing the input xml
ApiName (Optional): This is the validation spec name used for the validation. If not
provided, it is inferred from the Name attribute on the root tag of input xml.

Clone (Optional): true|false. If false then the validation results ( errors, autofills,
postfills) are marked on the input xml. If true the validation results are marked on a
clone of the input xml. The default value is true.
Example:
Here is an example of an X-Rule using this component:
<DEFINE_METHOD Name="validateLogin" Access="Public">
<API_DOC>
<INPUT>
<REQUEST Name="validateLogin">
<LOGIN_NAME Value="velocity-buyer"/>
<PASSWORD Value="pw"/>
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
Optional=true]"/>
</ON_SUCCESS>
<ON_EXCEPTION>
Optional=true]">
Name="validateLogin"/>
</RESPONSE>
</ON_EXCEPTION>
</OUTPUT>
</API_DOC>

<RULE>
<ACTION>
<INVOKE_VALIDATION_FRAMEWORK DocVar="thisParam"
AssignToVar="response"/>
<IF_TEST Test="isValidValue($response/_RESULT/
@Value, 'SEVERE_ERROR', 'ERROR')">
<THEN>
<SET Var="thisReturn" FromVar="response" />
<EXIT />
</THEN>
</IF_TEST>
</ACTION>
</RULE>
</DEFINE_METHOD>
Input to X-Rule (Error Case):

<LOGIN_NAME/>
<PASSWORD Value="def"/>
</REQUEST>
Output of INVOKE_VALIDATION_FRAMEWORK (Error Case):
<RESPONSE ValidationResult="SEVERE_ERROR">
<_RESULT Value="SEVERE_ERROR" Details="true">

<_ERROR Value="REQUIRED_FIELD_MISSING"
Severity="SEVERE_ERROR"/>
</_RESULT>
<LOGIN_NAME>
<_ERRORS Value="SEVERE_ERROR">
<_ERROR Value="REQUIRED_FIELD_MISSING"
Severity="SEVERE_ERROR"/>
</_ERRORS>
</LOGIN_NAME>
<_ERRORS Value="SEVERE_ERROR"/>
</REQUEST>
</RESPONSE>
Input to X-Rule (Success Case):

</REQUEST>
Output of INVOKE_VALIDATION_FRAMEWORK (Success Case):
<RESPONSE ValidationResult="SUCCESS">
<_RESULT Value="SUCCESS"/>
<REQUEST Name="validateLogin" MaxRows="10"
ReturnRowCount="true" StartAtRow="0">
</REQUEST>
</RESPONSE>
VALIDATE_DOC
Description:
This component is used to validate a given XML against one or more validation
specifications. It will stop validating and return upon encountering a severe error. For
other errors and successes, it will continue executing all the specified validation specs
and finally return an aggregated result. This component will work on the input xml's
by reference.
Syntax:
<VALIDATE_DOC Value="{X-Path expression}">
<SPEC Name="validateSpec1" Repeatable="true"/>
</VALIDATE_DOC>
Example:
Here is an example of an X-Rule using this component:
<DEFINE_METHOD Name="validateLogin" Access="Public">
<API_DOC>
<INPUT>

</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
Optional=true]"/>
</ON_SUCCESS>
<ON_EXCEPTION>
Optional=true]">
Name="validateLogin"/>
</RESPONSE>
</ON_EXCEPTION>
</OUTPUT>
</API_DOC>

<RULE>
<ACTION>
<VALIDATE_DOC Value="{$thisParam}">
<SPEC Name="validateLogin"/>
</VALIDATE_DOC>
<IF_TEST Test="isValidValue($thisParam/
@ValidationResult, 'SEVERE_ERROR', 'ERROR')">
<THEN>
<APPEND_TO_XML DocVar="thisReturn">
<_RESULT Value="{$thisParam/
@ValidationResult}" Details="true"/>
<TO_XML DocVar="thisParam"/>
</APPEND_TO_XML>
</THEN>
</IF_TEST>
</ACTION>
</RULE>
</DEFINE_METHOD>
Input to X-Rule (Error Case):

<LOGIN_NAME/>
</REQUEST>
Output ($thisParam after call to VALIDATE_DOC) (Error Case):

<REQUEST Name="validateLogin" ValidationResult="ERROR">
<LOGIN_NAME>
<_ERROR Value="MISSING_REQUIRED_FIELD"
Severity="ERROR"/>
</_ERRORS>
</LOGIN_NAME>
</REQUEST>

The ValidationResult attribute indicates the overall status of validation. In case where
multiple validation specifications are being evaluated this attribute will indicate the
highest level of error encountered among all the mentioned validation specifications.
The valid values possible for ValidationResult attribute are SUCCESS, INFO,
WARNING, ERROR and SEVERE_ERROR.
Note: When using VALIDATE_DOC there is no <RESPONSE> and <_RESULT> tag
available in the output as compared to INVOKE_VALIDATION_FRAMEWORK.
Other utility action components
UPDATE_VALIDATION_RESULT
Description
This component is used in conjunction with the
INVOKE_VALIDATION_FRAMEWORK component. If two documents have been
validated using INVOKE_VALIDATION_FRAMEWORK, then this action
component can be used to aggregate the two results obtained. This component will
compare the value of _RESULT tag of the primary document with the secondary
document and then update _RESULT tag on the primary document to be higher of the
two values.
The order of preference will be SEVERE_ERROR > ERROR > WARNING > INFO >
SUCCESS
Syntax:
<UPDATE_VALIDATION_RESULT Value="{X-Path expression}"
FromValue="{X-Path expression}"/>
Attributes:
Value(Required): X-Path expression that evaluates to the primary document that has a
_RESULT child tag.
FromValue(Required): X-Path expression that evaluates to a String indicating the
value of _RESULT of the secondary document.
Example:
Assume $ship refers to
<SHIP>
<_RESULT Value="SUCCESS"/>
...
</SHIP>
and $shipLine refers to
<SHIP_LINE>
<_RESULT Value="ERROR"/>
...
</SHIP_LINE>
Input:
<UPDATE_VALIDATION_RESULT Value="{$ship}"
FromValue="{$shipLine/_RESULT/@Value}"/>

Output:
The variable $ship after execution will be:
<SHIP>
<_RESULT Value="ERROR"/>
</SHIP>


Chapter 4
ID Generation
This chapter gives you information about generating unique ids in ABPP. It includes
the following topics.
Topics:
z Introduction
z TimeIdGeneration
z TableIdGeneration
z SequenceIdGeneration
z BlockIdGeneration
z IdGen Configuration
z Managing Id Generation configurations in ABPP Studio
z Obtaining Unique IDs
Introduction
An identifier is used to identify an entity in Database. For example, an Order Id is
used to identify an Order from rest of the Orders in the System. ABPP supports a
configurable way to generate ID for the entities in System. This should be configured
in the service configuration file.
ABPP supports the following three methods of ID generation.
z Time ID Generation.
z Table ID Generation.
z Native Database Sequence Id Generation.
TimeIdGeneration
This is the default ID generation used in ABPP. It generates the ID based on current
system time and the entity for which the ID is being generated.

Chapter 4 ID Generation
TableIdGeneration
In this scheme ABPP maintains a table called ID_SQR. The schema for ID_SQR
Table is defined as follows:
<DOCUMENT Name="ID_SEQUENCE" TableName="ID_SQR">
<PROPERTY Name="DOC_NAME" Type="string(64)"
ColumnName="DOC_NAME" PrimaryKey="yes"/>
<PROPERTY Name="SEQUENCE_NUMBER" Type="long"
ColumnName="SEQ_NR"/>
</DOCUMENT>
ID_SQR Table keeps track of the next ID for each of the idgen configurations in this
scheme. The DOC_NAME column contains the name of the idgen configuration and
the SEQUENCE number column contains the next id that can be issued for that
configuration.
This is a system table which is automatically generated by ABPP as part of schema
generation.
SequenceIdGeneration
This scheme utilizes native database sequences to generate unique Id. So it requires
the creation of sequence objects in the database. ABPP will automatically create the
necessary sequence objects as part of schema generation.
Here is a sample sequence creation SQL issued by ABPP for Oracle database as part
of schema generation:
CREATE SEQUENCE CO_SEQ INCREMENT BY 1000 START WITH 1000
NOMINVALUE NOMAXVALUE NOCYCLE CACHE 5.
The above SQL creates a SEQUENCE Object named CO_SEQ. The starting number
for this sample sequence is 1000 and it will be incremented by 1000 every time an
application queries for next sequence number.
The sequence name and other parameters in the above SQL are configured in the
'idgen' section of the service configuration file.
BlockIdGeneration
In the Table and Sequence ID generation schemes, the system has to make a call to the
database for generating IDs. It is expensive to make a call to the database for
generating every ID. To increase performance, ABPP can be configured to fetch
blocks of ID from the Database and keep in memory. When the block is served out it
would go to the Database to fetch next block.
IdGen Configuration
Description:
When using any of the three methods of generating IDs - Table ID, Sequence ID or
Block ID - you have to first configure the X-Service file by setting the 'idgen' block
with details of the document, prefix, delimiter, sequenceName, block size (if

IdGen Configuration
applicable) and handler. You have to specify the idgen settings for each document for
which ID generation is automated.
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 generation java class name 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.DatabaseIdGenerator
| com.i2.xcore.idgen.OracleIdGenerator (To be used only for Oracle Database)
| com.i2.xcore.idgen.DB2IdGenerator (To be used only for DB2 Database)
Note:
1. com.i2.xcore.idgen.DatabaseIdGenerator handler relies on the native
sequence feature of the database to generate unique id. If the target
database does not support native sequences then this handler will default
to com.i2.xcore.idgen.BlockTableIdGenerator
2. The handlers com.i2.xcore.idgen.OracleIdGenerator and

com.i2.xcore.idgen.DB2IdGenerator are deprecated. Replace their usage
with com.i2.xcore.idgen.DatabaseIdGenerator handler.
The following attributes applies only to sequence generators:

z sequenceName: It identifies the SEQUENCE Object in the Database to be used
for ID Generation.his corres
The following attributes applies to sequence and table id generators:

z blockSize : It is the number of ids fetched by the generator in a single call to the
database. The generator will cache these ids and will not make calls to the
database until it has exhausted the ids in the cache. This identifies the
INCREMENT size of the database sequence for sequence generator.
z startNum: specifies the starting number for the id generation.
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"
handler="com.i2.xcore.idgen.BlockTableIdGenerator"
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'.
Note: Tune the 'blockSize' parameter to get better performance. If typical Customer
Order has 10 Line Items each having 10 Requests then the block size of Line
Item should be 10 times the block size of Customer Order and the block size
of the Order Request should be 10 times the block size of the Line Item.
Managing Id Generation configurations in ABPP Studio

The user can manage Id Generation configurations in the service properties panel.
Here is a screen shot:

Managing Id Generation configurations in ABPP Studio
The columns of the Id Generation Parameters table map directly to the attributes on
the <idgen/> tag described in the previous section.
Please note that studio provides a more friendly description of the handler class
names. The following table shows the mapping of the handler description (shown in
studio) to the actual handler class names:
Handler Description Handler Class
Time Based com.i2.xcore.idgen.TimeIdGenerator

Internal Sequence com.i2.xcore.idgen.BlockTableIdGenerator
Database Sequence com.i2.xcore.idgen.DatabaseIdGenerator
Oracle Sequence com.i2.xcore.idgen.OracleIdGenerator
DB2 Sequence com.i2.xcore.idgen.DB2IdGenerator
The Add, Update and Delete buttons on the Id Generation Parameters can be used for
adding, editing and deleting id generation configuration entries respectively. Here is a
screenshot of the id generation configuration add panel :

Obtaining Unique IDs

This section provides a brief description of the ABPP Components which can be used
for obtaining Unique IDs. These components use the configurations (<idgen> tag)
described in this section to determine the format (prefix etc) and the scheme ( time-
based, database sequence etc) for generating the unique IDs.
1. Any X-Document containing only one Primary Key can be configured (by setting
the SurrogateKey attribute to true) to automatically generate & insert a unique ID
whenever an ADD_DOCUMENT component ( see X-RULES chapter, located in
the Programmer’s Reference Guide, Part One for details on the component) is
executed on that X-Document. You will need to provide the ID Generation
configuration ( using <idgen> tag) corresponding to the X-Document name.
Note: I2 studio represents X-Documents as models. You can set the SurrogateKey
attribute on a X-Document using the i2 studio in the Model Set -> ... your
model ... -> Facets Tab -> Document Tab -> Misc Facet -> Surrogate Key
check box.
Refer to Surrogate Key section of X-Document chapter, located in the

Programmer’s Reference Guide, Part One, for more information about setting up a
Surrograte Key.

Obtaining Unique IDs
2. Use CREATE_DOCUMENT_ID X-Rule component to obtain a unique ID and

assign it to a variable. You will need to provide the ID Generation configuration
(using <idgen> tag) corresponding to the Name attribute on the component.


Chapter 5
Purge
The following document gives a detailed description of the purge specification that is
used to specify document which needs to be purged.
Topics:
z Purge Functionality
z Features of Purge Framework
z Defining Purge Definition
z Loading purge definition
z Creating purge backup table schema
z Invoking/Triggering purge
z Purge framework schema
Purge Functionality
Purging old, unwanted document data stored in the database is an important
functionality that the ABPP server supports. Examples of document data that may
need this support are from Purchase Orders, Shipments, Invoices, and Receipts etc.
It is essential to purge unwanted data such as completed/cancelled/rejected orders,
resolved alerts etc., which are no longer needed for daily workflows. Keeping
unwanted data in the database:
1. Increases the space needed to maintain the database
2. Can have an adverse effect on the performance of database operations
When purge API is invoked, purge framework selects the records which satisfy the
purge criteria and purges them. If you want the purged data for reporting purposes,
then the purge framework can backup the purged data in to backup tables defined in
the same DB as the source tables.

Chapter 5 Purge
Features of Purge Framework

The purge framework can selectively purge documents and their related documents by
allowing the user to define the criteria.
Key features of the purge framework:
1. Purge definitions: Ability to specify an XML that defines the properites of a purge
task.
2. Pure Purging: Ability to delete rows from the database without storing this data
elsewhere
3. Purge and Copy: Saving candidate data (those selected for purging) in backup
tables and then deleting that data from the original tables. The backup tables
mimic the schema of the copied tables. These backup tables are not accessible to
the application and for all application purposes this data does not exist. The
customer is responsible for maintaining these backup tables
4. Ability to specify names of documents to be purged along with its related
document names
5. Ability to define purging criteria on the document rows to be purged and define
purging criteria on its related documents as well
6. Ability to specify backup table names when you want to perform "Purge and
Copy"
7. Provide a log for the purge activity which logs the spec name, the time the purge
job started and the time the purge job got completed and the number of records
purged etc
8. Support for locking to prevent accidental concurrent purge out of the same purge
definition.
Steps involved in using purge framework:
1. Define XML based purge definition (also called ‘purge spec’)
2. Load purge spec by specifying in the appropriate service configuration file
3. Create schema for the backup tables which may be needed to backup the purge
data (this is done using schema generation)
4. Invoke the purge API to trigger purge task
Defining Purge Definition

Purge definition is an XML based specification and it captures all the information
needed for the purge framework to do its job. Following are the key capabilities it
provides:
1. Ability to specify names of documents to be purged
2. Ability to define purge criteria on the document to be purged and to define purge
criteria on its related documents, and to define purge criteria in terms of AGE
using the built-in variable "AGE_IN_DAYS" and other conditions using format
similar to GET_DOCUMENT

3. Ability to define purge action such as PURGE or BACKUP_N_PURGE

4. Ability to specify appropriate batch processing size so as to prevent overloading
of the system
5. Ability to define the documents to be backed-up (in addition to purge) and its
related documents
6. Ability to define the backup table names if you want to backup before purging the
data
The structure of a purge specification is speicified below.
<purge_defs>
<purge_def Name=".." Action="PURGE|BACKUP_N_PURGE"
AnchorDocumentName=".." BatchSize="..">
<table_maps Prefix="..">
<table_map NativeName=".." ArchiveName=".."/>
... other table_map(s) ...
</table_maps>
<documents>
<document DocumentName="..">
... filter on the document ...
</document>
... other document(s) ...
</documents>
<dependency_links>
<dependency_link LinkName="..">
... other dependency link(s) ...
</dependency_link>
... other dependency_link(s) ...
</dependency_links>
<traverse_links>
<traverse_link LinkName="..">
... filter on the document if needed ...
... other traverse_link(s) ...
</traverse_link>
... other traverse_link(s) ...
</traverse_links>
</purge_def>
</purge_defs>
The individual elements used in the above specification are explained below. We will
use the following example Documents (and dependent Documents) for explaining the
purge definition structure:

Chapter 5 Purge
ORDER_LINE is the Document whose rows (and its related rows from other tables)
are to be purged. It has ORDER_ID, LINE_ID as Primary Key. It is linked to
CUSTOMER_ORDER, and NOTES.
CUSTOMER_ORDER is a linked document through a link name called “AO_LINK”,
and is linked by ORDER_ID. This document has ID as primary key. It is linked to
ORDER_NOTES via a link named NOTES.
ORDER_NOTES is a linked document of both the above documents. It has ID and
DOC_NAME, and SEQ_NUM as primary key. ID will contain either the
ORDER_LINE’s ID or CUSTOMER_ORDER’s ID. The DOC_NAME field would
contain value of either “ORDER_LINE” or “CUSTOMER_ORDER” depending on
which document the notes row is used for. SEQ_NUM is a running number that allows
multiple Notes to be created for a given Order ID or Line ID.
It would be easier to follow the syntax of a purge definition if we considered the
following purge requirement based on the above three documents:
The sample requirement for this purge definition is that it should backup and then
purge ORDER_LINE(s) (and related documents) which satisfies the following
conditions:
1) STATE_ID field value is COMPLETED or REJECTED or CANCELLED
2) CREATION_DATE field value is older than 180 days
3) INVOICE_STATUS of CUSTOMER_ORDER in which this ORDER_LINE
belongs is in PAID state
4) All the ORDER_LINEs connected with the CUSTOMER_ORDER in which this
ORDER_LINE belongs should satisfy conditions 1 and 2. That is, all of the
ORDER_LINE rows of an customer order should satisfy the
STATE_ID and CREATION_DATE conditions.

Now let us go through various tags and values to be specified in a purge definition:
<purge_def>: This defines a purge definition. The ‘Name’ attribute specifies the
name of the purge definition. The name should be unique within a service. When
invoking purge task, this name would need to be provided.
The ‘Action’ attribute specifies the purge action to take when the purge definition is
executed. Valid values are ‘PURGE’ and ‘BACKUP_N_PURGE’. If the action is
‘PURGE’ then the eligible data will be deleted from the database. If the action is
‘BACKUP_N_PURGE’ then the eligible data will be copied to backup tables and then
deleted from main tables.
The ‘AnchorDocumentName’ attribute specifies the ABPP document that needs to
be purged.
Example:
<purge_def Name="LinePurgeDefinition"
Action="BACKUP_N_PURGE" AnchorDocumentName="ORDER_LINE"
BatchSize="250">
An invocation of purge operation performs purges in several batches as part of its
execution in order to avoid over-usage of the system memory. The ‘BatchSize’
attribute controls how many “anchor documents” are processed in one batch. For
example if the BatchSize is 100 then for every 100 anchor document instances (rows)
the system will load (from database) all the related document instances as specified by
the dependency links. Higher the depth of dependency links and higher the amount of
data being fetched, smaller the BatchSize should be. The default value for BatchSize
is 100.
<table_maps>: The <table_maps> tag is used to define backup tables when the
Action used is BACKUP_N_PURGE. The ‘Prefix’ attribute defines the prefix string
to use for all the tables specified in <table_map> tags. Each <table_map> specifies a
document that needs to be purged and the corresponding backup table. For Example:
<table_maps Prefix="A$_">
<table_map NativeName="CUSTOMER_ORDER"
ArchiveName="AO"/>
<table_map NativeName="ORDER_LINE"
ArchiveName="AO_LINE"/>
</table_maps>
In this example the instances of document ‘CUSTOMER_ORDER’ are backed up to
physical table A$_AO. Specify the table_maps whenever BACKUP_N_PURGE
option is selected so that you are able to control the names of the back-up tables.
<documents>: The <documents> tag is used to define the filter conditions for the
anchor document and for the related documents. The anchor document instances that
satisfy the specified filter conditions are fetched from database (max 100K rows) and
evaluated to check if all their related document instances (specified using
dependency_links which is explained below) also satisfy their corresponding filter
conditions specified. If all the dependent linked instances also satisfy the
corresponding filter conditions (recursively) then the ‘traverse links’ (defined below)
starting from anchor document are used to purge the appropriate document instances.
Thus ‘dependency links’ specify the criteria to apply in other tables for choosing
candidate rows of ‘anchor document’ for purging, while the ‘traverse links’ specify
the related documents whose related rows should be purged when purging the

Chapter 5 Purge
candidate rows from the anchor document. Note: If the number of anchor document
instances that satisfy the filter condition is more than 100K then the purge will have to
be executed again to process the remaining anchor document instances.
The filter conditions are expressed by using standard GET_DOCUMENT format.
Example:
<documents>
<document DocumentName="ORDER_LINE">
<filter>
<AGE_IN_DAYS Value="300"
FieldToBeUsed="CREATION_DATE"/>
<OR>
<STATE_ID Value="COMPLETED"/>
<STATE_ID Value="REJECTED"/>
<STATE_ID Value="CANCELLED"/>
</OR>
</filter>
</document>
<document DocumentName="CUSTOMER_ORDER">
<filter>
<INVOICE_STATUS Value="PAID"/>
</filter>
</document>
</documents>
Note: The <AGE_IN_DAYS> is a special filter that will be converted to expression:
“FieldToBeUsed < (CurrentDate - Value in Days)”. In above example:
CREATION_DATE <(CurrentDate - 300 Days).
<dependency_links>: The <dependency_links> tag is used to define the documents
that the anchor document is dependent on. i.e. The anchor document instance cannot
be purged unless the dependent document instances can also be purged. The
documents that the anchor document depends on can further depend on other
documents, so the <dependency_link> tag can be nested. The ‘LinkName’ attribute
of <dependency_link> tag is the X-Document link name that links to the required
dependent document.
A document instance is eligible for purge only if it satisfies the filter condition and all
its dependent document instances also satisfy respective filter conditions. Same logic
applies to the dependent documents also. This recursive algorithm is applied to find
out the anchor document instances that can be purged. In the example below, for
Anchor Document ORDER_LINE, the dependency link is with
CUSTOMER_ORDER through the AO_LINK. So the filter conditions specified for
CUSTOMER_ORDER above must be satsified in order to select the corresponding
candidate rows from the Anchor Document. From the example XML above, even if
an ORDER_LINE row satisfies the filter conditions, the corresponding
CUSTOMER_ORDER row must have the INVOICE_STATUS field value equal to
“PAID” in order for the ORDER_LINE row to become a candidate for purging.
<dependency_links>
<dependency_link LinkName="AO_LINK">
<dependency_link LinkName="ORDER_LINES"/>
</dependency_link>
</dependency_links>

Note: One restriction placed on the dependency_link(s) is that the leaf node of the
dependency graph should be the same as anchor document. As such the documents
will need bidirectional links defined. This is the reason you see an inner
dependency_link ORDER_LINES in the above example.
Note: The anchor document should be selected such that the depth of the dependency
graph is minimized.
<traverse_links>: The <traverse_links> define the path traversed to purge the data
starting from anchor document. Once the anchor document instances that can be
purged are identified (using AnchorDocument and Dependency Links), the
traverse_link(s) are used to actually delete (or backup and delete) the data from the
anchor document and from documents mentioned in the <traverse_links>. The
<filter> tag can be specified in <traverse_link> tag to further filter down the records
that need to be deleted. The conditions used in the filter tag if any will be passed to the
REMOVE_DOCUMENT operation which is used to purge the documents in the
traverse links. The ‘LinkName’ attribute of <traverse_link> tag is the X-Document
link name. Example:
<traverse_links>
<traverse_link LinkName="NOTES">
<filter>
<DOC_NAME Value="ORDER_LINE"/>
</filter>
</traverse_link>
<traverse_link LinkName="AO_LINK">
<filter>
<DOC_NAME Value="CUSTOMER_ORDER"/>
</filter>
</traverse_link>
</traverse_link>
</traverse_links>
=> Here once the rows of anchor document ORDER_LINE are identified, those
candidate rows, and the rows in ORDER_NOTES document belonging to those
specified ORDER_LINE rows, and the rows in CUSTOMER_ORDER table that are
linked to the candidate ORDER_LINE rows (through AO_LINK), and the rows in
ORDER_NOTES that are linked to the CUSTOMER_ORDER rows (through NOTES
link within the AO_LINK) are deleted.
Thus you specify the criteria for candidate rows of anchor document using the
dependency_link, but you use traverse_link for actually deleting dependent rows.
Notice that the traverse_link helps to delete all dependent rows, even those that did not
participate in criteria specificiation in dependency_links. In the above case, NOTES
was not part of filter conditions in dependency links, so it was not a part of making a
decision for selecting candidate rows of ORDER_LINE anchor document, but when it
comes to actually deleting the candidate rows of ORDER_LINE the corresponding
ORDER_NOTES rows are also deleted as they are specified in the traverse_links.
Example of a simple purge definition (without related documents):

Chapter 5 Purge
Following is a purge spec definition for document STATE_HISTORY

that purges all records that are older than 180 days:
<purge_defs>
<purge_def Name="SHPurgeDefinition" Action="PURGE"
AnchorDocumentName="STATE_HISTORY" BatchSize="1000">
<documents>
<document DocumentName="STATE_HISTORY">
<filter>
</filter>
</document>
</documents>
</purge_def>
</purge_defs>
Explanation:
The above purge specification when executed will purge all rows of
STATE_HISTORY document whose CREATION_DATE column has a value that is
older than 180 days from current date.
Example of a complex purge definition (with related documents):

Here we provide the complete purge definition for the Customer Order example we
used for describing the XML tags of a purge definition.
<purge_defs>

<purge_def Name="LinePurgeDefinition"
Action="BACKUP_N_PURGE" AnchorDocumentName="ORDER_LINE"
BatchSize="250">

<table_maps Prefix="A$_">
<table_map NativeName="CUSTOMER_ORDER"
ArchiveName="AO"/>
<table_map NativeName="ORDER_LINE"
ArchiveName="AO_LINE"/>

<table_map NativeName="ORDER_NOTES"
ArchiveName="NOTE"/>
</table_maps>
<documents>
<document DocumentName="ORDER_LINE">
<filter>
<OR>
</OR>
</filter>
</document>
<document DocumentName="CUSTOMER_ORDER">
<filter>
</filter>
</document>
</documents>

<dependency_links>
<dependency_link LinkName="AO_LINK">
<dependency_link LinkName="ORDER_LINES"/>
</dependency_link>
</dependency_links>

<traverse_links>
<filter>
<DOC_NAME Value="ORDER_LINE"/>
</filter>
</traverse_link>
<traverse_link LinkName="AO_LINK">
<filter>
<DOC_NAME Value="CUSTOMER_ORDER"/>
</filter>
</traverse_link>
</traverse_link>
</traverse_links>
</purge_def>
</purge_defs>
Explanation:

Chapter 5 Purge
This example demonstrates a purge definition with all its features. The data model for
which this purge is defined has 3 documents: CUSTOMER_ORDER, ORDER_LINE
and ORDER_NOTES.
The requirement for this purge definition is that it should backup and then purge
ORDER_LINE(s) (and related documents) which satisfies the following conditions:
1) STATE_ID field value is COMPLETED or REJECTED or CANCELLED
2) CREATION_DATE field value is older than 180 days
3) INVOICE_STATUS of CUSTOMER_ORDER in which this ORDER_LINE
belongs is in PAID state
4) All the ORDER_LINEs connected with the CUSTOMER_ORDER in which this
ORDER_LINE belongs should satisfy conditions 1 and 2. That is, all of the
ORDER_LINE rows of an customer order should satisfy the
STATE_ID and CREATION_DATE conditions.
When the purge specification is executed it will fetch all ORDER_LINE instances that
satisfy the filter condition:
<filter>
<OR>
</OR>
</filter>
Then for every 250 (batch size) such ORDER_LINEs it will evaluate the dependency
links.
The first dependency link is AO_LINK that links to document
CUSTOMER_ORDER. So it will fetch all the CUSTOMER_ORDERs for the current
batch of ORDER_LINEs that satisfy the filter condition defined for
CUSTOMER_ORDER:
<filter>
</filter>
The ORDER_LINEs whose CUSTOMER_ORDER does not satisfy this filter is not
eligible for purge and is marked accordingly.
The next dependency link is ORDER_LINES that links from CUSTOMER_ORDER
to ORDER_LINE. For all the CUSTOMER_ORDER instances fetched in current
batch the corresponding ORDER_LINEs are fetched that satisfy the ORDER_LINE
filter. For an CUSTOMER_ORDER all the related ORDER_LINEs need to satisfy the
ORDER_LINE filter. If they do not i.e. if any ORDER_LINE of the
CUSTOMER_ORDER is not in the right state or is not more than 180 days old then
the CUSTOMER_ORDER is not eligible for purging. If the CUSTOMER_ORDER is
not eligible for purging then the corresponding anchor ORDER_LINE is also not
eligible for purging.

Loading purge definition
Once the final list of ORDER_LINEs that can be purged is calculated the framework
will purge these ORDER_LINEs and use the traverse_links specified to purge the
related documents. The ORDER_NOTES table has a filter specified so that only
appropriate notes entries are purged.
Loading purge definition

The different purge definitions that a service needs should be specified in the service
config file. The purge definition files are defined in tag <purgeDefnFiles> as
shown below.
Service config file
<purgeDefnFiles>
<purgeDefnFile Name="xservice/orderadmin/xml/pce/purge/
linePurgeDef.xml"/>
</purgeDefnFiles>
Note: When using i2 Studio, simply adding the purge definition files to a service
would automatically perform the above operation in the service config file.
Creating purge backup table schema

Purge backup table schema is identical to the source table expect the table name. This
backup table schema would be registered with the ABPP server when purge spec is
loaded by the service. So when you run Schema Generator utility to generate schema,
backup table schema is also generated. If you change the purge spec which will affect
the backup table schema then you need to recreate the schema in order to keep purge
spec to be in sync with the physical schema.
Invoking/Triggering purge
The "EXECUTE_PURGE" rule command can be used to trigger purge execution. In
this command you specify the name of the purge spec.
Invoke purge command
<REQUESTS ServiceName="ORDER_ADMIN">

<EXECUTE_PURGE Name="LinePurgeDefinition"/>
</REQUESTS>
(Of course the EXECUTE_PURGE could be called from inside a rule
or workflow as well if needed.)
Typical response of the above request will look like:
<RESPONSES Status="Success">
<RESPONSE BatchSize="3" AnchorDocumentsFetched="4000"
Status="Success">
<PURGE_ID Value="PURGE-3811099692974285"/>
<END_DATE Value="04/26/2004 00:01:10:000"/>
<NUM_RECORDS Value="7000"/>
<PROGRESS Value="COMPLETED"/>
<SPEC_NAME Value="LinePurgeDefinition"/>

Chapter 5 Purge
<START_DATE Value="04/26/2004 00:00:49:000"/>

<DETAILS>
<ORDER_LINE RowsAffected="4000"/>
<CUSTOMER_ORDER RowsAffected="1500"/>
<ORDER_NOTES RowsAffected="1500"/>
</DETAILS>
</RESPONSE>
</RESPONSES>
NUM_RECORDS indicates the total number of records, including ones deleted

through traverse_links, that were deleted by this purge operation.
Purge framework schema

The purge framework persists its execution log to the database. The tables it will
populate are:
PURGE_LOG table
PURGE_ID Purge ID. System generated unique ID
SPEC_NAME Purge spec name
START_DATE Purge start date and time
END_DATE Purge end date and time
NUM_RECORDS Total Number of records purged including related

documents
PROGRESS Purge progress status (Valid values: INITIATED,

FAILED, and COMPLETED)
PURGE_LOG_LN table
PURGE_ID Purge ID
DOC_NAME Document name. Example: ORDER_LINE,

CUSTOMER_ORDER etc
NUM_RECORDS Total Number of records purged from the

document

Chapter 6
Export Framework
The following document lays out the detailed description of the export specification
that can be used to specify export filters, document and its properties that have to be
exported.
Topics:
z Export Functionality
z Features of Export Framework
z Defining Export Definition
z Loading Export Definition
z Creating export/staging table schema
z Invoking/Triggering export
z Export Framework Schema
z Sample Export Spec
Export Functionality
Exporting various documents/entities is an important functionality that the server
needs to support. Examples of documents that may need this support are Purchase
Orders, Shipments, Invoices, and Receipts etc. It is essential export data to support
various integration workflows and to help generate various reports.
When export API is invoked, export framework selects the records which satisfy the
export filters criteria and export them to the staging table which is defined in the same
DB as the source table. After the data is exported, integration system can pickup the
exported data and use them for their workflow. The exported data should be purged
periodically to restore the space used by it. You can use purge functionality provided
by the purge framework to accomplish this task.

Chapter 6 Export Framework
Features of Export Framework

The export framework makes it easier to define export filters on a document using its
properties as well as the properties which are defined on its related documents. It also
allows you to define fields to be exported from the document and its related
documents. For example, when receipt line is exported, you might also want to export
receipt date field which is defined on the receipt header along with the receipt line
fields.
Key features of the export framework:
1. Ability to define which documents to export along with the attributes on the object
itself as well as the related objects. It provides the ability where the external
system which is triggering the export can specify the query parameters. For
example, schedules in a particular state, schedules for which the shipped qty >=
ordered qty etc.
2. Ability to store the exported document in the DB.
3. Ability to export delta as well as whole. Where delta implies that the export is for
only those objects that meet the selection criteria since the last export.
4. Support for multiple external systems to export data simultaneously.
5. Provide a log for the export activity which records the source system for the
export trigger, the time when the export was performed, the API that was called,
the time the job started and the time the job got completed and the number of
records exported etc.
6. Ability to specify number of export transactions you want to keep in the staging/
export table.
7. Support for locking to prevent concurrent export for the same spec and target
system accidentally.
Steps involved in using export framework:
1. Define XML based export spec.
2. Load export spec by specifying in the appropriate service configuration file.
3. Create schema for the staging table which are needed to export the data.
4. Invoke the export API to trigger exports.
Defining Export Definition

Export definition is a XML based specification and it captures all the data needed for
the export framework to do its job. Please refer search framework to get more details
on properties selection and filter definition etc since export framework is implemented
using search framework libraries. It would be very clear if we define the export spec
for the real problem.
Requirements
Export shipment line which satisfies the following requirements:
1. Fields to be exported from SHIPMENT_LN table are ID, CREATION_DATE,
ITEM_DESCR, ITEM_ID, SHIPMENT_ID, SHIPPED_QTY, UOM

Defining Export Definition
2. Fields to be exported from related table SHIPMENT table are

SELLING_ORG_ID, SHIP_TO_ID, SHIP_FROM_ID, SHIP_MODE,
SHIP_DATE, and DELIVERY_DATE
3. Support DELTA export based on the LAST_MODIFIED_DATE
4. Export Shipment line which has at least one open PO line
5. Export Shipment line for a given seller
6. Export data into export table named EXP_ASN_LN
Defining export spec consist the following steps:
1. Define export spec header
2. Define delta export filter
3. Define fields to be exported
4. Define fields which would be used in export filter
Define export spec header
This step provides helps to define export spec name, document to be exported, and
name of the staging/export where you want to have the exported data.
Example:
<export-defs>
<export-def Name="ASN_EXPORT"
Document="SHIPMENT_LINE"
ExportTableName="EXP_ASN_LN">



</export-def>
</export-defs>
Define delta export filter
This step provides support to define delta export definition where you can specify
filtering condition needed for the delta export using built-in variable
"LAST_EXPORT_DATE" and "CURRENT_DATE". This filter expression would be
converted into X-Path compliant filer expression by the export framework. The delta
export filter is a fixed selection criterion and that can't be changed by the caller. It is
strongly recommended to use "LAST_EXPORT_DATE" and "CURRENT_DATE" to
set upper and lower bound for delta export.
When export happens for the first time, "LAST_EXPORT_DATE" would be null
since there is no earlier export. In this case "January 1, 1970" would be used as a last
export date. Default value for "CurrentDateOffsetInMin" is 0. For subsequent
exports, the system will infer the LAST_EXPORT_DATE from the previous export.
You can specify current date offset (in minutes) to prevent potential error cases due
the transactions which are over lapping with export transaction. By using
"CURRENT_DATE" and current date offset, you can introduce a slack in the delta
export. In the following example, delta filters restrict shipment line export i.e. it

exports shipment lines which are modified since the last export and their modification
date is less than or equal to (CURRENT_DATE - 5 minutes).
Example:
<export-defs>
<export-def Name="ASN_EXPORT" Document="SHIPMENT_LINE"
<delta-export-filter CurrentDateOffsetInMin="5">
<AND>
<LAST_MODIFIED_DATE MatchBy="GREATER"
Value="LAST_EXPORT_DATE" />
<LAST_MODIFIED_DATE MatchBy="LESS_EQUAL"
Value="CURRENT_DATE" />
</AND>
</delta-export-filter>
</export-def>
</export-defs>
Define fields to be exported
This step provides support to define fields to be exported from the document and its
related document. This feature gives you the control to select fields which are
absolutely needed for your workflows.
You can select the properties from the related document which belongs to the same
service as the document for which export spec is defined. Example when export spec
is defined for SHIPMENT_LN which belongs to ORDER_ADMIN service, it is
allowed to define properties from the related document such as SHIPMENT which
also belongs to ORDER_ADMIN service but it is not allowed to use the related
document say LOCATION which is defined in EM service. This limitation is imposed
in order to create schema for the export/staging table dynamically.
Example:
<export-defs>
<select-properties>

<ID />
<CREATION_DATE />
<ITEM_DESCR />
<ITEM_ID />
<SHIPMENT_ID />
<SHIPPED_QTY />
<UOM />

<SELLING_ORG_ID MapTo="SHIPMENT_LINK/
SELLING_ORG_ID" />
<SHIP_TO_ID MapTo="SHIPMENT_LINK/SHIP_TO_ID" />
<SHIP_FROM_ID MapTo="SHIPMENT_LINK/SHIP_FROM_ID"
/>
<SHIP_MODE MapTo="SHIPMENT_LINK/SHIP_MODE" />
<SHIP_DATE MapTo="SHIPMENT_LINK/SHIP_DATE" />

Loading Export Definition
<DELIVERY_DATE MapTo="SHIPMENT_LINK/
DELIVERY_DATE" />
</select-properties>
</export-def>
</export-defs>
Define fields which would be used in export filter
This step provides support to define export filters using fields defined on the
document to be exported and its related documents. The filter values would be
specified by the caller at the run time.
Example:
<export-defs>

<filter-def Name="CREATION_DATE" />

<filter-def Name="SELLING_ORG_ID" MapTo="SHIPMENT_LINK/
SELLING_ORG_ID" />
</export-def>
</export-defs>
Loading Export Definition

The different export definitions that a service needs have to be specified in the service
config xml file. The export definition files are defined in tag <exportDefnFiles>.
Service config file
<exportDefnFiles>
<exportDefnFile Name="xservice/orderadmin/xml/pce/export/
asnExportDef.xml" />
<exportDefnFile Name="xservice/orderadmin/xml/pce/export/
openLineExportDef.xml" />
</exportDefnFiles>
Note: When using i2 Studio, simply adding the export definition files to a service
would automatically perform the above operation in the service config file.
Creating export/staging table schema

Export/Staging table schema is derived from the export spec "<select-properties>"
definition section. Recall that <select-properties> covers fields from the document to
be exported as well as the fields from the related documents. The export/staging table
schema is automatically generated as part of schema generation. So if you change the
<select-properties> section of the export spec then you will need to re-run schema
generation in order to keep the export spec in synch with the physical schema.

Invoking/Triggering export
You can use the command "EXECUTE_EXPORT" to trigger export. In this command
you can pass the export filter condition and can specify whether you need full export
or delta export, target system name etc. Please make sure that you are using only those
fields which are defined in the export spec filter definition section to define your
filters.
The same export spec can be used to export incremental data for various end users.
For example one end user can be a backend ERP system and another end user can be a
planning engine. These two end users may request export at different times and so the
incremental data that is exported for them will be different. The TargetSystem
attribute of ‘EXECUTE_REPORT’ command can be used to specify the end user.
It is assumed that export is not invoked for the same spec and target system with
different export type (FULL, DELTA) i.e. first call export with export type as FULL
and in the next time call export with export type DELTA. If the export type is changed
between calls, you may get the wrong result due to not able to keep track of the
LAST_EXPORTED_DATE.
Example:
<EXECUTE_EXPORT Name="ASN_EXPORT" Type="DELTA"
TargetSystem="MRP" MaxPreviousExportToKeep="1">





<FILTER Name=" SELLING_ORG_ID">
<SELLING_ORG_ID Value="Saturn" MatchBy="EQUAL" />
</FILTER>
<FILTER Name="SCHEDULE_STATE_ID">
<OR>
<SCHEDULE_STATE_ID Value="ACCEPTED"
MatchBy="EQUAL" />
<SCHEDULE_STATE_ID Value="IN_PROCESS"
MatchBy="EQUAL" />
</OR>
</FILTER>
</EXECUTE_EXPORT>

Export Framework Schema
</REQUESTS>
A typical response to the above request would be as follows:

<RESPONSE Status="Success">
<EXP_ID Value="EXPORT-3811099684440111" />
<END_DATE Value="04/26/2004 00:01:36:000" />
<EXP_TYPE Value="DELTA" />
<NUM_RECORDS Value="12" />
<PROGRESS Value="COMPLETED" />
<PURGE_STATUS Value="NOT_PURGED" />
<SPEC_NAME Value="OPEN_LINE_EXPORT" />
<START_DATE Value="04/26/2004 00:01:36:000" />
<TARGET_SYSTEM Value="MRP" />
</RESPONSE>
</RESPONSES>
Since you have the capability to pass filters when you invoke export using
"EXECUTE_EXPORT" command, if you want to export data for a specific period
then you can achieve it by constructing appropriate export date range filter and then
use it when you invoke the export command.
For each export spec and target system combination, last export date is maintained in
EXP_TRACKER table (refer section 7). So when multiple target system requesting
the delta exports using the same spec then export framework computes the delta using
the data from EXP_TRACKER table to figure it out the delta for each target system
independently.
If for some reason the “EXECUTE_EXPORT” command fails it will throw an
exception with appropriate error message.
Export Framework Schema

Export framework persist export log and its details in to the EXP_TRACKER table.
Details are given below.
EXP_TRACKER table
SPEC_NAME Spec name
TARGET_SYSTEM Target system name
LST_EXP_DATE Last export date and time
LST_EXP_ID Last Export Id
This table is automatically created as part of schema generation.
Sample Export Spec

<export-defs>

<delta-export-filter CurrentDateOffsetInMin="5">
<OR>

<AND>
</AND>

<QUERY_DOCUMENT_LINK Name="SHIPMENT_LINK">
<AND>
</AND>
</QUERY_DOCUMENT_LINK>

<QUERY_DOCUMENT_LINK Name="SHIP_LN_TO_SCH_LINK">
<QUERY_DOCUMENT_LINK Name="SCHEDULE_LINK">
<AND>
<LAST_MODIFIED_DATE
MatchBy="LESS_EQUAL" Value="CURRENT_DATE" />
</AND>
</OR>
</delta-export-filter>
<select-properties>

<ITEM_ID />
<ITEM_DESCR />
<REF_TYPE />
<REF_ID />
<UOM />
<SHIPPED_QTY />

<SHIP_FROM_ID MapTo="SHIPMENT_LINK/SHIP_FROM_ID" />
<SHIP_CHARGES MapTo="SHIPMENT_LINK/SHIP_CHARGES" />
<OTHER_CHARGES MapTo="SHIPMENT_LINK/OTHER_CHARGES" /
>
<GROSS_WEIGHT MapTo="SHIPMENT_LINK/GROSS_WEIGHT" />
<GW_UOM MapTo="SHIPMENT_LINK/GROSS_WEIGHT_UOM" />
<SF_CNTRY_CODE MapTo="SHIPMENT_LINK/
SHIP_FROM_COUNTRY" />
<SHIP_TERMS MapTo="SHIPMENT_LINK/SHIP_TERMS" />
<SHIP_VIA MapTo="SHIPMENT_LINK/SHIP_VIA" />
<SHIP_MODE MapTo="SHIPMENT_LINK/SHIP_MODE" />

Sample Export Spec
<NUMBER_PACKAGES MapTo="SHIPMENT_LINK/
NUMBER_PACKAGES" />
<TRACKING_NUMBER MapTo="SHIPMENT_LINK/
TRACKING_NUMBER" />
<DELIVERY_DATE MapTo="SHIPMENT_LINK/DELIVERY_DATE" /
>
<SHIP_DATE MapTo="SHIPMENT_LINK/SHIP_DATE" />

<filter-def Name="STATE_ID" />
<filter-def Name="SHIPPED_QTY" />

<filter-def Name="SHIP_TERMS" MapTo="SHIPMENT_LINK/
SHIP_TERMS" />
<filter-def Name="SELL_ORG_ID" MapTo="SHIPMENT_LINK/
SELLING_ORG_ID" />
<filter-def Name="SCH_STATE_ID"
MapTo="SHIP_LN_TO_SCH_LINK/SCHEDULE_LINK/STATE_ID" />
<filter-def Name="DELIVERY_DATE" MapTo="SHIPMENT_LINK/
DELIVERY_DATE" />
<filter-def Name="SHIP_TO_ID" MapTo="SHIPMENT_LINK/
SHIP_TO_ID" />
<filter-def Name="PLND_SHIP_DATE" MapTo="SHIPMENT_LINK/
PLANNED_SHIP_DATE" />
<filter-def Name="PLND_DEL_DATE" MapTo="SHIPMENT_LINK/
PLANNED_DELIVERY_DATE" />
</export-def>
</export-defs>
Sample export request and response

Sample Request:
<EXECUTE_EXPORT Name="ASN_EXPORT" Type="DELTA"
TargetSystem="LEGACY" MaxPreviousExportToKeep="2">
<FILTER Name="SHIP_TERMS">
<SHIP_TERMS Value="SHIP-01" MatchBy="EQUAL" />
</FILTER>
<FILTER Name="SELL_ORG_ID">
<SELL_ORG_ID Value="Saturn" MatchBy="EQUAL" />
</FILTER>
<FILTER Name="DELIVERY_DATE">
<DELIVERY_DATE Value="03/20/2004" MatchBy="GREATER"
/>
</FILTER>
<FILTER Name="SHIP_TO_ID">
<SHIP_TO_ID Value="Velocity-Tonawanda"
MatchBy="EQUAL" />
</FILTER>
</EXECUTE_EXPORT>
</REQUESTS>

Sample Response:
<EXP_ID Value="EXPORT-5181099960193744" />
<END_DATE Value="04/26/2004 00:15:39:000" />
<EXP_TYPE Value="DELTA" />
<NUM_RECORDS Value="2" />
<PROGRESS Value="COMPLETED" />
<PURGE_STATUS Value="NOT_PURGED" />
<SPEC_NAME Value="ASN_EXPORT" />
<START_DATE Value="04/26/2004 00:15:39:000" />
<TARGET_SYSTEM Value="LEGACY" />
</RESPONSE>
</RESPONSES>

Chapter 7
Search Framework
The following document lays out the detailed description of the search filter
specification that can be used to support different filters on a document.
Topics:
z Search Functionality
z Search Definition
z Interfaces to Search Framework
z Loading the Search Definition
Search Functionality
Searching for different documents/entities is an important functionality that the server
needs to support. The search framework makes is easy to implement search capability
on a document defined in xservices. It allows a document to be searched by properties
that are defined for the document as well as search on properties on linked documents.
E.g. searching Customer Orders by ItemId, which is a property of the lines of the
order.
The following diagram shows various parts of the existing search framework,

Chapter 7 Search Framework
The request and response format for a typical search API is:
<REQUEST Name="getCustomerOrders" StartAtRow="10" MaxRows="20"
ReturnRowCount="yes" UserId="bbabin">
<FILTER Name="ID">
<OR>
<ID Value="CO-1" MatchBy="STARTS_WITH"/>
<ID Value="123" MatchBy="ENDS_WITH"/>
</OR>
</FILTER>
<FILTER Name="CREATION_DATE">
<CREATION_DATE Value="12/12/2001" MatchBy="GREATER"/>
<CREATION_DATE Value="12/15/2001" MatchBy="LESS"/>
</FILTER>
<FILTER Name="ORDER_POINT_ID">
<ORDER_POINT_ID Value="OP-1"/>
</FILTER>
... Other filters as defined in the search definition ...
<ORDER_BY>
<CREATION_DATE Sort="Ascending"/>
<ID Sort="Descending"/>
</ORDER_BY>
</REQUEST>
<RESPONSE>
<CUSTOMER_ORDERS TotalRowCount="12">
<CUSTOMER_ORDER ExistingDocument="yes">
<ID Value="CO-1"/>
<ORDER_ORIGIN_ID Value="CSR"/>
<ORDER_POINT_ID Value="OP-1"/>
... other properties ...
</CUSTOMER_ORDER>
... other customer orders ...

Search Definition
</CUSTOMER_ORDERS>
</RESPONSE>
For the request if the attributes StartAtRow and MaxRows are present then the server
will do pagination on the result. The ReturnRowCount attribute is optional. If this
attribute value is 'yes' then the TotalRowCount is returned as part of the response.
The response will contain the documents that matched given search criteria. The result
may be paginated depending on input request.
The filters that are supported depend on the search definition that is used. Search
definition is where you can specify the filters and how they map to in the query.
Search Definition
Search definition is a specification that tells the search framework how to generate the
database query.
Search Definition Example
<search-defs>
<search-def Name="SIMPLE_CO_SEARCH"
Document="CUSTOMER_ORDER">
<select-properties>
<ID/>
<ORDER_POINT_ID/>
<CREATION_DATE/>
<CREATED_BY_ID/>
<NAME/>
<DOC_TYPE/>
<ORDER_TYPE_ID/>
<STATE_ID/>
<ESTMT_VALUE/>
<CURRENCY_CODE/>
<PRICE MapTo="ORDER_LINE_ITEMS/UNIT_PRICE"/>
<REQUESTE_DATE MapTo="ORDER_LINE_ITEMS/
ORDER_REQUESTS/DELIVERY_DATE"/>
<PROMISE_DATE MapTo="ORDER_LINE_ITEMS/
ORDER_REQUESTS/ORDER_SCHEDULES/DELIVERY_DATE"/>
<ITEM_ID MapTo="ORDER_LINE_ITEMS/ITEM_ID"/>
<fetch-document-link Name="NOTES">
<select-properties>
<NOTE_TYPE_ID/>
</fetch-document-link>
<filter-def Name="ID"/>
<filter-def Name="ORDER_TYPE_ID"/>
<filter-def Name="CREATION_DATE"/>
<filter-def Name="STATE_ID"/>
<filter-def Name="ESTMT_VALUE"/>
<filter-def Name="EXT_ORDER_NUMBER"
MapTo="EXT_ORDER_NUM"/>

<filter-def Name="ITEM_ID" MapTo="ORDER_LINE_ITEMS/

ITEM_ID"/>
</search-def>
</search-defs>
Each search definition is defined for a document and should have a unique name. In
above example the search definition name is 'SIMPLE_CO_SEARCH' and it's defined
for document 'CUSTOMER_ORDER'.
The search definition allows users to define the fields that are to be selected and
retuned in the response as well as other associated documents that are to be fetched.
The search definition also allows the user to define various filters that will be
supported in the search API. The various components are described in the following
sections.
Selected Properties
The <select-properties> tag is used to define the fields that need to be returned
as part of the search response. The fields listed under this tag can belong to the
document for which the search spec is defined as well as other documents linked to
the primary document.
The fields belonging to the document are listed by just the names. The fields of the
linked documents are listed with an alias and a mapping path to access the linked
document field.
In the example above, REQUEST_DATE has a 'MapTo' defined as below.
ORDER_LINE_ITEMS/ORDER_REQUESTS/DELIVERY_DATE
The system will perform a join of the primary document CUSTOMER_ORDER and
the linked documents ORDER_LINE_ITEM and ORDER_REQUEST to get the field
DELIVERY_DATE defined for ORDER_REQUEST document.
Fetch document links

The fetch-document-link tag defines the associated documents that need to be fetched
and returned as part of the response.
Example:
<fetch-document-link Name="ABC">
<select-properties>
<prop1/>
<prop2/>
<fetch-document-link Name="DEF"/>
</fetch-document-link>
In above example ABC must be valid document link on the document on which the
search spec is defined. Similarly DEF should be a valid link from the document that
link ABC refers to. The syntax for select-properties is same as the select-properties tag
that appears under search-def tag.

Search Definition
Query document links

You can use the query-document-link to do an inner join on associated documents.
You can also select properties on these documents. The query-document-link tags can
also be nested.
Example:
<query-document-link Name="ABC">
<select-properties>
<prop1/>
<prop2/>
</query-document-link>
ABC must be valid document link on the document on which the search spec is
defined. The syntax for select-properties is same as the select-properties tag that
appears under search-def tag.
Normal Filters
Example:
<filter-def Name="EXT_ORDER_NUMBER" MapTo="EXT_ORDER_NUM"/>
<filter-def Name="ITEM_ID" MapTo="ORDER_LINE_ITEMS/ITEM_ID"
CaseInsensitive="true" />
The <filter-def> tag defines a normal filter. A normal filter is a filter that does not need
any special processing and is evaluated by converting to a GET_DOCUMENT call.
The 'Name' attribute is a mandatory attribute. This attribute defines what the input
request filter name should be.
The input filter name need not be same as the required document property name. The
'MapTo' attribute can be used to define how the input filter should be mapped to
database. e.g. above the input filter name 'EXT_ORDER_NUMBER' is mapped to
'EXT_ORDER_NUM' in the document definition (i.e. the CUSTOMER_ORDER
document has a property called EXT_ORDER_NUM).
It's also possible that the filter may map to a property on some linked document. E.g.
the 'ITEM_ID' filter is mapped to document 'ORDER_LINE_ITEM' and property
'ITEM_ID' through link 'ORDER_LINE_ITEMS'.
A string search by default is case sensitive. To perform a case insensitive search, users
have to specify the attribute CaseInsensitive="true". If the attribute is set to true, a
case insensitive search will be performed on the filter property.
Specifying additional search criteria

In certain cases, there may be a need to specify additional attributes or XML tags in
the GET_DOCUMENT that search framework generates for a search request. To be
able to add these additional attributes and append XML tags, one can specify a get-
doc-spec in the search spec like below. The specified attributes and XML in the get-
doc-spec will be transferred to the get document XML generated by the search
framework.
Here is an example of a search spec which uses the get-doc-spec.

Using get-doc-spec to specify search rules

<search-def Name="INVENTORY_ITEM_STATUS_SEARCH"
Document="INVENTORY">
<select-properties>
<ITEM_ID/>
<ORG_ID MapTo="INV_LOC_LINK/ORG_ID"/>
<SUPP_ORG_ID MapTo="INVENTORY_ITEM_LINK/
ORGANIZATION_ID"/>
<CUST_NAME MapTo="INV_LOC_LINK/ORG_INFO_LINK/NAME"/>
<filter-def Name="ITEM_ID"/>
<filter-def Name="ITEM_LVL_ONE" MapTo="INVENTORY_ITEM_LINK/
ITEM_LVL_ONE"/>
<filter-def Name="ITEM_LVL_TWO" MapTo="INVENTORY_ITEM_LINK/
ITEM_LVL_TWO"/>
<filter-def Name="ITEM_LVL_THREE"
MapTo="INVENTORY_ITEM_LINK/ITEM_LVL_THREE"/>
<filter-def Name="CUST_NAME" MapTo="INV_LOC_LINK/
ORG_INFO_LINK/NAME"/>
<filter-def Name="SHIP_TO_NAME" MapTo="INV_LOC_LINK/NAME"/>
<filter-def Name="LOCATION_TYPE" MapTo="INV_LOC_LINK/
LOCATION_TYPE"/>
<filter-def Name="LOCATION_CATEGORY" MapTo="INV_LOC_LINK/
LOCATION_CATEGORY"/>
<filter-def Name="LOCATION_STATUS" MapTo="INV_LOC_LINK/
SHIP_TO_INFO_LINK/STATUS"/>
<filter-def Name="STATUS" MapTo="INV_LOC_LINK/
BUFFER_SHIP_TO_LINK/STATUS"/>
<get-doc-spec>
<appendXml>
<QUERY_DOCUMENT_LINK Name="INVENTORY_ITEM_LINK"
Prefix="ITM"/>
<QUERY_DOCUMENT_LINK Name="INV_LOC_LINK"
Prefix="LOC">
<QUERY_DOCUMENT_LINK Name="BUFFER_SHIP_TO_LINK"
Prefix="SLA"/>
</appendXml>
<addAttr Name="Expression"
Value="#|ITM.ORGANIZATION_ID|#=#|SLA.SUPP_ORG_ID|# AND
#|ITEM_ID|#=#|SLA.ITEM_ID|# AND
#|LOC.ORG_ID|#=#|SLA.CUST_ORG_ID|#"/>
</get-doc-spec>
</search-def>
Interfaces to Search Framework

The search specification provides the following commands:
GET_SEARCH_RESULTS
Description

This command will return the results of executing the specified search specification
using the provided search criteria.
Syntax:
<GET_SEARCH_RESULTS ServiceName="name[Optional=true]"
AssignToVar="varName">
<SPEC Value="spec-name"/>
<CRITERIA>
<REQUEST MaxRows="10[Optional=true]"
ReturnRowCount="true|false [default=false]" StartAtRow="number
[default=0]" UserId="user-id">
<FILTER Name="name-of-filter" Repeatable="true">
<ANY/>
</FILTER>
<FETCH_DOCUMENT_LINK Name="link-name"
Optional="true" Repeatable="true">
<ANY/>
</FETCH_DOCUMENT_LINK>
<NOT_EXISTS_QDL Name="link-name" Optional="true"
Repeatable="true">
<ANY/>
<NOT_EXISTS_QDL>
<ORDER_BY Optional="true">
<ANY/>
</ORDER_BY>
</REQUEST>
</CRITERIA>
<ROOT_NAME Value="root-name" Optional="true"/>
</GET_SEARCH_RESULTS>
Attributes:
z SPEC.Value: This is the name of the search spec to be used for constructing the
search query.
z REQUEST.MaxRows: Maximum number of records to be return by this
operation. If not provided then it will return all the rows, up to default maximum
rows configured for the service, which match the query. See Service Params
section in ABPP Config guide for configuring default maximum rows for a
service.
z REQUEST.ReturnRowCount: if true, the output returns the number of rows which
match the search query criteria. This is essential for providing paginated search
pages.
z REQUEST.StartAtRow: if not provided, this defaults to 0. The output returns up
to MaxRows starting from StartAtRow on the result set of the search query.
z REQUEST.UserId: This is user id of the user who is accessing the search page.
This user id can be used to apply data level filters based on the authorization
permissions of the user. For example, a buyer searching for Purchase Orders can
view the Orders assigned to all the suppliers. A supplier viewing the Purchase
Order can view Orders assigned to his organization. Search spec does not provide
built-in support for enforcing data level authorizations. If this is required then
search spec needs to be extended. Please contact i2 ABPP development for details
on extending the search spec.

z FILTER Name: You can specify various named search conditions in your search
spec. Each of these names search conditions is called a filter. Please refer ABPP
Search framework guide for details on the FILTER and how to provide values for
each of the FILTERs. The name of the search filters referenced this command
must be valid search filter name on the search spec in SPEC.Value attribute.
z FETCH_DOCUMENT_LINK.Name: You can optionally include any
FETCH_DOCUMENT_LINK tags in the command. The Name attribute must be
a valid document link on the X-Doc on which the search spec is based. Please
refer FETCH_DOCUMENT_LINK section in X-Document command for details.
z NOT_EXISTS_QDL.Name: The input can optionally have any number of
NOT_EXISTS_QDL tags. Please refer to NOT_EXISTS_QDL section in
GET_DOCUMENT command for details.
z ORDER_BY: You can provide an ORDER_BY condition on the search query.
Please refer ORDER_BY section in X-Document command for details.
z ROOT_NAME .Value: If null, the search result records will be direct children of
the RESPONSE tag in the output. Otherwise the RESPONSE tag will have a child
tag whose name is the value of this attribute. The search result records will be
children of this child tag.
Example 1:
<GET_SEARCH_RESULTS>
<SPEC Value="CUSTOMER_ORDER_SEARCH"/>
<CRITERIA>
<REQUEST MaxRows="10" ReturnRowCount="yes"
StartAtRow="0" UserId="user3">
<FILTER Name="ID">
<ID Value="A" MatchBy="ENDS_WITH"/>
</FILTER>
<FILTER Name="ORDER_TYPE_ID">
<ORDER_TYPE_ID Value="STANDARD"
MatchBy="EQUAL"/>
</FILTER>
<FILTER Name="ITEM_ID">
<ITEM_ID Value="C-151-S"/>
</FILTER>
<ORDER_BY>
</ORDER_BY>
</REQUEST>
</CRITERIA>
<ROOT_NAME Value="CUSTOMER_ORDERS"/>
Sample response to the command:
<CUSTOMER_ORDERS TotalRowCount="121">
<CUSTOMER_ORDER>
<ID Value="C1"/>
<ORDER_POINT_ID Value="OP1"/>
<CREATION_DATE Value="01/01/2000"/>

<STATE_ID Value="SENT"/>
<CURRENCY_CODE Value="USD"/>
<BILL_TO_ID Value="BT1"/>
<SHIP_TO_ID Value="ST1"/>
</CUSTOMER_ORDER>
<CUSTOMER_ORDER>
<ID Value="C2"/>

</CUSTOMER_ORDER>

</CUSTOMER_ORDERS>
</RESPONSE>
Assuming that you have a total row count = 121 and each page can display a
maximum of 10 rows.
To show the results you will have 13 pages.
Page #1 will display records 0-9. To retrieve this page use StartAtRow=0.
Page #2 will display records 10-19. To retrieve this page use StartAtRow=10
Page #13 will display records 120. To retrieve this page use StartAtRow=120
Note that all pages except Page #13 will return max rows of 10. Page #13 will return
only 1 row.
Example 2:
This example is similar as Example 1. However the ROOT_NAME tag is missing in
this example.
<GET_SEARCH_RESULTS>
<CRITERIA>
<FILTER Name="ID">
</FILTER>
MatchBy="EQUAL"/>
</FILTER>
</FILTER>
<ORDER_BY>
</ORDER_BY>
</REQUEST>
</CRITERIA>
Sample response to the command:
<RESPONSE Status="Success" TotalRowCount="121">
<CUSTOMER_ORDER>
<ID Value="C1"/>

<ORDER_POINT_ID Value="OP1"/>
<CREATION_DATE Value="01/01/2000"/>
<STATE_ID Value="SENT"/>
<CURRENCY_CODE Value="USD"/>
<BILL_TO_ID Value="BT1"/>
<SHIP_TO_ID Value="ST1"/>
</CUSTOMER_ORDER>
<CUSTOMER_ORDER>
<ID Value="C2"/>

</CUSTOMER_ORDER>

</RESPONSE>
GET_SEARCH_FORM
Description
This command will return the GET_DOCUMENT query that is constructed by the
search framework. This GET_DOCUMENT query can in turn be augmented by
additional criteria and executed by the caller.
Syntax:
<GET_SEARCH_FORM ServiceName="name[Optional=true]"
AssignToVar="varName">
<SPEC Value="name-of-spec"/>
<CRITERIA>
<ANY_TAG_NAME MaxRows="10[Optional=true]"
ReturnRowCount="true|false [default=false]" StartAtRow="number
[default=0]" UserId="user-id">
<FILTER Name="name-of-filter" Repeatable="true">
<ANY/>
</FILTER>
<FETCH_DOCUMENT_LINK Name="link-name"
Optional="true" Repeatable="true">
<ANY/>
</FETCH_DOCUMENT_LINK>
<NOT_EXISTS_QDL Name="link-name" Optional="true"
Repeatable="true">
<ANY/>
<NOT_EXISTS_QDL>
<ORDER_BY Optional="true">
<ANY/>
</ORDER_BY>
</ANY_TAG_NAME>
</CRITERIA>
</GET_SEARCH_FORM>
Attributes:

z SPEC.Value: This is the name of the search spec to be used for constructing the
search query.
z StartAtRow (Optional): If not provided, this defaults to 0. The
GET_DOCUMENT will return up to MaxRows starting from StartAtRow on the
result set of the search query.
z MaxRows (Optional): Maximum number of records to be return by the
GET_DOCUMENT query. If not provided then it will return all the rows, up to
default maximum rows configured for the service, which match the query. See
Service Params section in ABPP Config guide for configuring default maximum
rows for a service.
z ReturnRowCount (Optional): If true, the GET_DOCUMENT will return number
of rows that match the search query criteria. This is essential for providing
paginated search pages. Default value is false.
z UserId: This is user id of the user who is accessing the search page. This user id
can be used to apply data level filters based on the authorization permissions of
the user. For example, a buyer searching for Purchase Orders can view the Orders
assigned to all the suppliers. A supplier viewing the Purchase Order can view
Orders assigned to his organization. Search spec does not provide built-in support
for enforcing data level authorizations. If this is required then search spec needs to
be extended. Please contact i2 ABPP development for details on extending the
search spec.
z FILTER Name: You can specify various named search conditions in your search
spec. Each of these names search conditions is called a filter. Please refer ABPP
Search framework guide for details on the FILTER and how to provide values for
each of the FILTERs. The name of the search filters referenced this command
must be valid search filter name on the search spec in SPEC.Value attribute.
z FETCH_DOCUMENT_LINK.Name: You can optionally include any
FETCH_DOCUMENT_LINK tags in the command. The Name attribute must be
a valid document link on the X-Doc on which the search spec is based. Please
refer FETCH_DOCUMENT_LINK section in X-Document command for details.
z NOT_EXISTS_QDL.Name: The input can optionally have any number of
NOT_EXISTS_QDL tags. Please refer to NOT_EXISTS_QDL section in
GET_DOCUMENT command for details.
z ORDER_BY: You can provide an ORDER_BY condition on the search query.
Please refer ORDER_BY section in X-Document command for details.
Example:
<GET_SEARCH_FORM AssignToVar="getDocVar">
<CRITERIA>
<FILTER Name="ID">
</FILTER>
MatchBy="EQUAL"/>

</FILTER>
</FILTER>
<ORDER_BY>
</ORDER_BY>
</REQUEST>
</CRITERIA>
</GET_SEARCH_FORM>
After executing this command, the contents of getDocVar will be:
<RESPONSE Name="CUSTOMER_ORDER">
<SELECT>
<ID/>
<ORDER_POINT_ID/>
<CREATION_DATE/>
<CREATED_BY_ID/>
<NAME/>
<DOC_TYPE/>
<ORDER_TYPE_ID/>
<STATE_ID/>
<ESTMT_VALUE/>
<CURRENCY_CODE/>
<BILL_TO_ID/>
<SHIP_TO_ID/>
</SELECT>
<ORDER_TYPE_ID Value="STANDARD" MatchBy="EQUAL"/>
<QUERY_DOCUMENT_LINK Name="LINE_ITEMS">
<ORDER_BY>
</ORDER_BY>
</RESPONSE>
Loading the search definition

The different search definitions that a service has needs to be specified in the service
config xml file. The search definition files are defined in tag <searchDefnFiles>.
Search definition files can also be reloaded at runtime through specifying the file path
at ABPP command line and specifying the owner service name.
Service config file
<searchDefnFiles>
<searchDefnFile Name="xservice/orderadmin/xml/sce/search/
coSearchDef.xml"/>
aoSearchDef.xml"/>
shSearchDef.xml"/>

Loading the search definition
</searchDefnFiles>


Chapter 8
State Machine
The state machine associates, changes and tracks states associated with document
instances. It does this based on a state model specification that is defined for a
document instance. Here document instance refers to a record in the document table.
Topics:
z State Model
z State Model Specification
z State Document
z Interfaces to State Machine
z Loading state model files
z Parallel States
z Example of state model specification
z FAQ
State Model
A state model defines the set of states a document instance can go through in its life
cycle. The set of defined states have an inherent order or rank associated with it. The
model also specifies how an instance reaches a particular state. There can be 2
possible means of reaching a particular state. One is through an event directly received
by the state machine and the other is through mapping which in turn is a result of some
event received by the state machine.
A state event is a command executed to trigger state change. The event is triggered
during or as a result of a business process. Upon this event, the state machine will
change the state of the document instance to the state defined by the event. Note: This
event is a command (e.g. RAISE_STATE_EVENT) that the business process will
execute to notify the state machine of the state change needed and is not related to the
events supported by ABPP.

Chapter 8 State Machine
This state change may require a state change in a related document instance. The state
machine will consider the document instance associations and trigger state change on
the related document instance through mapping.
State Model Specification

A state model specifies the following:
1. State model name
| This name is unique within a given service.
2. Document associated with the state model
| The document is defined in ABPP as an xdoc.
3. States
| An ordered set of states that a document instance goes through.
| The first state has the lowest rank and the last specified state has the highest
rank. These ranks are used in state mapping to decide which state the
document instance has to be in when it satisfies more than state mapping
conditions.
4. State triggers - The trigger can be an event or a mapping or both, but not more
than one of each type.
| Event trigger: Name of the event that causes the document instance to move
to the specified state.
| Mapping trigger: The condition that has to be satisfied for a document
instance to move to a particular state.
5. State model associations or links, if any
| By default, xdoc document links are used to associate state models.
| Alternatively, state model links can be defined explicitly in the state model
definition.
6. Activation actions
| Actions to be executed synchronously when an instance achieves a particular
state.
| Note the syntax of specifying the actions.
7. Events
| Events that ought to be raised when a state condition is satisfied.
Example of a State Model specification
<state_model Name="MerchandiseLineSM"
Document="ORDER_LINE_ITEM">
<state Name="CREATED">
<on_event Name="Created"/>
</state>
<state Name="DELIVERED">
<on_event Name="Delivered"/>

</state>
</state_model>

<state_model Name="InstallLineSM" Document="ORDER_LINE_ITEM">



<on_mapping>

<link StateModel="MerchandiseLineSM">

<all State="CREATED"/>
</link>
</on_mapping>
</state>
<state Name="READY_FOR_INSTALL">
<on_mapping>
<all State="DELIVERED"/>
</link>
</on_mapping>
</state>
<state Name="INSTALL_STARTED">
<on_event Name="InstallStarted"/>

<on_activation>
<actions>
<PRINTLN Value="Executing actions on move to state:
{$thisState}"/>
<PRINTLN Value="State changed for instance: {$thisDoc}"/>
<REQUEST Name="StateEventOnMappingListener">
<ID Value="{$thisDoc/ID/@Value}"/>

<DOCUMENT_NAME Value="INSTALL_ORDER_LINE_ITEM"/>
<STATE_ID Value="{$thisState}"/>
<USER_ID Value="{$thisUser}"/>
<REASON_CODE Select="$thisParam/REASON_CODE/@Value"/>
<REASON_TEXT Select="$thisParam/REASON_TEXT/@Value"/>
</REQUEST>
</actions>
</on_activation>
</state>
<state Name="INSTALL_COMPLETED">
<on_event Name="InstallCompleted"/>
</state>
</state_model>
Mapping condition specification and event mapping

Mapping conditions can involve one or more linked state models. The logical
operations supported are 'and' and 'or'. For a given linked state model, conditions can
be specified on the states of document instances of that state model. Currently, the 2
supported operations are 'any' and 'all' with one of the many operators - EQUAL,
GREATER_EQUAL, GREATER, LESS, LESS_EQUAL and NOT_EQUAL.
Following is an example illustrating these and how an event can be raised as a result
of a mapping condition.
Example of a mapping condition resulting in an event
<event Name="StateEventOnMapping">
<on_mapping>
<or>
<any State="DELIVERED" MatchBy="EQUAL"/>
<all State="DELIVERED" MatchBy="GREATER_EQUAL"/>
</link>
<link StateModel="InstallLineSM">
<any State="READY_FOR_INSTALL" MatchBy="GREATER_EQUAL"/>
<or>
<all State="INSTALL_STARTED" MatchBy="LESS_EQUAL"/>
<all State="INSTALL_COMPLETED" MatchBy="LESS"/>
</or>
</link>
</or>
</on_mapping>

</event>
State Model Association

The state machine figures out the linked state model document instances through state
model links. The following table illustrates how to specify links between state models.
If no such link is explicitly specified between state models, direct document links as
defined in ABPP are used. If no defined document link exists between 2 document
instances, then an exception is thrown at bootstrap time.
In summary, the state machine supports three types of state model links:
1. Direct document link - Default link and does not have to be explicitly specified as
a state model link.
2. Expression link - An X-Path expression is used to associate state models.
3. Multi-path link - A multi-path document link as defined in x-doc is specified to
associate state models. The parts are the document link names from x-doc of one
state model all the way to the final document link name relating x-doc of the other
state model.
State model associations: Expression links
<state_model_links>

<model_link From="MerchandiseLineSM" To="InstallLineSM"
Value="{request('getLinkedLine', $thisDoc)}"/>

<model_link From="InstallLineSM" To="MerchandiseLineSM"
</state_model_links>
State model associations: Multi-path links
<state_model_links>
<model_link From="StandardShipmentLineSM"
To="StandardOrderScheduleSM" Path="SHIP_LN_TO_SCH_LINK/
SCHEDULE_LINK"/>
<model_link From="StandardOrderScheduleSM"
To="StandardShipmentLineSM" Path="SHIP_LN_TO_SCH_LINK/
SHIP_LN_LINK"/>
Exception States
Exception states are those states that will not participate in a mapping condition unless
the defined comparison state is also an exception state.

For example, CANCELLED and REJECTED are two exception states of an order line
item. These states will be discounted in mapping computation of an order having n
number of lines with x (where x < n) lines in CANCELLED state.
An exception state is defined through an attribute of the state definition tag.
Exception states and mapping computation
<state_model>


<on_mapping>
<link StateModel="StandardLineSM">
<all State="DELIVERED" MatchBy="GREATER_EQUAL"/>
</link>
</on_mapping>
</state>

<state Name="CANCELLED" ExceptionState="true">
<on_mapping>

<all State="CANCELLED" MatchBy="GREATER_EQUAL"/>
</link>
</on_mapping>
</state>
<state Name="REJECTED" ExceptionState="true">
<on_mapping>
<all State="REJECTED" MatchBy="EQUAL"/>
</link>
</on_mapping>
</state>
</state_model>

State Document
State Document
A state document is an extended characterization of the ABPP document object
maintained by the State Machine. Any document in xdoc definition can be used in
state machine. If a user wants to associate an x-doc with state models, then the user
has to add 3 document properties. These are: STATE_MODEL, STATE_ID and
STATE_HISTORY.
During state model specification, these three properties are considered default by the
state machine and do not have to be specified explicitly as the state properties for the
state model.
If the user wishes to use different property names in x-doc to store the state related
data, then these properties can be described in the state model. Refer to section on
Parallel States.
The STATE_MODEL property value is specified by the application using the state
machine. The other two properties are maintained by the state machine. STATE_ID
defines the current state of the document instance while STATE_HISTORY is a
concatenated string of all the previous states.
It is good practice to define an index constituting the primary keys and the State model
property in that order. This is because the state machine accesses document instances
using the primary keys and the state model.
The user may choose to specify additional state properties in the x-doc definition if
document has a notion of parallel states.
For purposes of backward compatibility, DOCUMENT defined as
STATE_DOCUMENT in x-doc definition is still supported through specifying
document handler com.i2.xcore.tool.DocumentHandler for STATE_DOCUMENT.
Setting the State Model:
Applications can use xrule action tag SET_STATE_MODEL to set the state model for
a given document instance.
Example of SET_STATE_MODEL
<SET_STATE_MODEL Select="$thisParam/ORDER_LINE_ITEM"
FromValue="{$sm}"/>
OR
<SET_STATE_MODEL Select="$thisParam/ORDER_LINE_ITEM"
FromValue="MerchandiseLineSM"/>
Interfaces to State Machine

There are 2 primary interfaces to the state machine. One of them is to change the state
of a list of document instances through a state change event and the other is to
associate the immediate previous state of a document instance as the current state.
Other interfaces include, obtaining the event name that causes a document instance to
reach a particular state.

RAISE_STATE_EVENT
This is the action tag to be used to change the state of a list of entities. The state to
change to is identified by the event name specified using the Name attribute. The
event name has to be valid for the all state models of the parameter instances and will
be one of those specified in the state model specification.
The instances themselves can have different state models.
By default, the state machine will query the database to obtain a new copy of the
instance data, so that all properties of each document instance are available for the
state machine to work with. This query will use the parameters passed to
RAISE_STATE_EVENT as the context.
If users are sure that they are passing all the relevant data, they can specify an attribute
Refetch="false", to prevent the state machine from making this database query.
If the state of the parameter document instances change, then the states of all mapped
document instances will be reevaluated.
Typical usage of this action tag will be in the business workflow to update state of a
set of document instances that the business workflow is working with.
Example of RAISE_STATE_EVENT

<RAISE_STATE_EVENT Name="{$thisParam/EVENT/@Value}"
Refetch="false"><ORDER_LINE_ITEM>
<ID Value="LI-190"/>
<ORDER_TYPE_ID Value="MERCHANDISE"/>
<STATE_MODEL Value="MerchandiseLineSM"/>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ORDER_TYPE_ID Value="INSTALL"/>
<STATE_MODEL Value="InstallLineSM"/>
</ORDER_LINE_ITEM>
</RAISE_STATE_EVENT>

Interfaces to State Machine
PREVIOUS_STATE_EVENT
This is the action tag to be used to change the state of all the parameter instance
documents to their previous state. After the states of these instances are changed to
their previous state, all mappings that these instances participate in will be
reevaluated.
If no previous state exists for any instance, then an exception will be thrown. Any
mapping that is triggered as a result of this state change, will throw an exception if no
valid state is detected.
Example of PREVIOUS_STATE_EVENT
<PREVIOUS_STATE_EVENT Refetch="false">
<ORDER_LINE_ITEM>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
</ORDER_LINE_ITEM>
<ORDER_LINE_ITEM>
<ORDER_TYPE_ID Value="INSTALL"/>
<STATE_MODEL Value="InstallLineSM"/>
</ORDER_LINE_ITEM>
</PREVIOUS_STATE_EVENT>
Obtaining event name for a state in a state model

This function will return the event that is defined to trigger a state for a given state
model.
If the state or state model is invalid, an exception is thrown. If they are valid and no
event exists for the state, null is returned.
Function: getEventState
<SET Var="event" FromValue="{getStateEvent('StateModelName',
'StateName')}"/>
OR

<SET Var="event" FromValue="{getStateEvent($thisParam/MODEL/

@Value, $thisParam/STATE/@Value)}"/>
Loading state model files

State models file names are specified in the service configuration file of the service
they are to be registered with. All calls to the state machine involving these state
models will have to occur within that service.
Handler for state model files
<register-handlers>
<handler TagName="stateModelFiles"
ClassName="com.i2.xcore.statemachine.StateModelFilesHandler"/>
</register-handlers>
Registration of state model
<stateModelFiles>
<stateModelFile Name="xservice/orderadmin/StateModel-
SellSide.xml"/>
</stateModelFiles>
Parallel States
The state machine can track and support multiple state models on the same x-doc. In
order to do this,
z x-doc definition must contain all the state properties used in its document
definition.
z Each state model specification excepting the one using default state properties
(STATE_ID, STATE_MODEL, STATE_HISTORY) must specify the state
properties to be used to maintain the states associated with that state model.
z If a state event has to be raised on a document instance for a state model other than
the default, then a StateModel attribute must be mentioned while raising the state
event.
z State model links must be specified as done in the default one.
The state machine will then use the state properties associated with the state model to
track and maintain the parallel states.
Example:
A state model defining and using a specific set of state properties
<state_models>
<state_model Name="pceScheduleInvSM" Document="ORDER_SCHEDULE">
<state_properties>
<state_id Name="INVOICE_STATUS"/>
<state_model Name="INV_STATUS_SM"/>

Parallel States
<state_history Name="INV_STATUS_HISTORY"/>
</state_properties>
<state Name="NOT_ELIGIBLE">
<on_event Name="NotEligible"/>
</state>
<state Name="PENDING">
<on_mapping>
<link StateModel="StandardBuyOrderSchSM">
<all State="ACCEPTED" MatchBy="GREATER_EQUAL"/>
<all State="PARTIALLY_INVOICED" MatchBy="LESS"/>
</link>
</on_mapping>
</state>
<state Name="PARTIALLY_INVOICED">
<on_mapping>
<all State="PARTIALLY_INVOICED" MatchBy="EQUAL"/>
</link>
</on_mapping>
</state>
<state Name="INVOICED">
<on_mapping>
<all State="INVOICED" MatchBy="EQUAL"/>
</link>
</on_mapping>
</state>
</state_model>
</state_models>
Example:
Raising state event on a non-default state model. Not the StateModel attribute that is
specified. The same can be specified for PREVIOUS_STATE_EVENT as well.
<RAISE_STATE_EVENT Name="Invoiced"
StateModel="ScheduleInvoiceSM">
<ORDER_SCHEDULE>
<ID Value="SCH-190"/>
</ORDER_SCHEDULE>

</RAISE_STATE_EVENT>
Appendix
Example of state model specification

A combination customer order's states are determined by its constituent merchandise
and install lines. The install line states are in turn determined by the merchandise line
states. This example also shows state model links as defined in the state model.
<state_models>
<state_model Name="CombinationOrderSM"
Document="CUSTOMER_ORDER">
<on_activation_any_state>
<actions>
{$thisState}"/>
</actions>
</on_activation_any_state>
<on_activation>
<actions>
<PRINTLN Value="Customer order is created: {$thisDoc/ID/
@Value}"/>
</actions>
</on_activation>
<on_mapping>
</link>
</link>
</on_mapping>
</state>
<event Name="StateEventOnMapping">
<on_mapping>
<or>

Appendix
<any State="DELIVERED" MatchBy="EQUAL"/>

</link>
<any State="READY_FOR_INSTALL" MatchBy="GREATER_EQUAL"/>
</link>
</or>
</on_mapping>
</event>
<state Name="MERCHANDISE_PARTIALLY_DELIVERED">
<on_mapping>
<any State="DELIVERED"/>
</link>
</on_mapping>
</state>
<state Name="MERCHANDISE_DELIVERED">
<on_mapping>
<link Doc="ORDER_LINE_ITEM" StateModel="MerchandiseLineSM">
</link>
</on_mapping>
</state>
<state Name="INSTALL_IN_PROGRESS">
<on_mapping>
<link Doc="ORDER_LINE_ITEM" StateModel="InstallLineSM">
<any State="INSTALL_STARTED"/>
</link>
</on_mapping>
</state>
<state Name="COMPLETED">
<on_mapping>
<link Doc="ORDER_LINE_ITEM" StateModel="MerchandiseLineSM">
</link>
<link Doc="ORDER_LINE_ITEM" StateModel="InstallLineSM">
<any State="INSTALL_COMPLETED"/>
</link>
</on_mapping>

</state>
<state Name="CANCELLED" ExceptionState="true">
<on_event Name="Cancelled"/>
</state>
</state_model>
<state_model Name="MerchandiseLineSM"
Document="ORDER_LINE_ITEM">
</state>
<on_event Name="Delivered"/>
</state>
</state_model>

<state_model Name="InstallLineSM" Document="ORDER_LINE_ITEM">



<on_mapping>


</link>
</on_mapping>
</state>
<state Name="READY_FOR_INSTALL">
<on_mapping>
</link>
</on_mapping>

Appendix
</state>
<state Name="INSTALL_STARTED">
<on_event Name="InstallStarted"/>
<on_activation>
<actions>
{$thisState}"/>
<REQUEST Name="StateEventOnMappingListener">
<ID Value="{$thisDoc/ID/@Value}"/>
<DOCUMENT_NAME Value="INSTALL_ORDER_LINE_ITEM"/>
<STATE_ID Value="{$thisState}"/>
<USER_ID Value="{$thisUser}"/>
<REASON_CODE Select="$thisParam/REASON_CODE/@Value"/>
<REASON_TEXT Select="$thisParam/REASON_TEXT/@Value"/>
</REQUEST>
</actions>
</on_activation>
</state>
<state Name="INSTALL_COMPLETED">
<on_event Name="InstallCompleted"/>
</state>
</state_model>
<state_model_links>

<model_link From="MerchandiseLineSM" To="InstallLineSM"

<model_link From="InstallLineSM" To="MerchandiseLineSM"
</state_models>
FAQ
1.Does a state model have to be associated with a state document?
Yes, a state model has to be associated with a state document.

2.Can multiple state models be defined for the same state document?
Yes, multiple state models with different names can be associated with the same state
document. Each document instance of that state document will use one state model.
3.If a state in the state model is defined as triggered by both an event and mapping,
which one takes precedence?
If the state can be reached through either one of the mechanisms, the document
instance changes to that state if its current state is less than the new state. The
mechanism does not matter in state transition.
4.How does transition to a lower state occur during state mapping?

If a condition defined at a higher state than current state is satisfied, then transition to
the higher state will occur. When no condition for state higher than current state is
satisfied, then the last valid state of the document instance is computed. The last valid
state is the highest state in the state history of the instance that has an event trigger or
has a mapping condition that holds true. Even if this state was not reached using the
event, this state is still deemed to be valid.
5.What is the outcome of an event mapping?

If the mapping condition associated with an event evaluates to true, then the event is
raised with the document instance as the parameter. This event is by definition
asynchronous. Hence, the event will have to defined and registered in the event
document for the service.
6.Is the interface for RAISE_STATE_EVENT backward compatible with previous

definitions of RAISE_STATE_EVENT?
Yes, it is. One can use FOR_DOCUMENT and DOCUMENT_CONTEXT tags.
However, these will be deprecated. The preferred way is to simply list the document
instances under the RAISE_STATE_EVENT tag.
7.When can I safely set the Refetch attribute of RAISE_STATE_EVENT or

PREVIOUS_STATE_EVENT to false?
The state machine event and mappings work on the document instance. If you are sure
that the instance passed as parameter is current and contains all the information that
the state machine will require for evaluating mappings (incl. document link properties
used in fetching linked instances), then set Refetch to false.

Chapter 9
DB Locking
ABPP server provides utility APIs to perform locking that can be used to avoid
deadlocks and wrong results due to concurrency issues.
This chapter will explain the concept of locking and setup needed to use locking in
ABPP server
Topics:
z Concept
z Setup
z API Specification
Concept
ABPP server is a multi-threaded engine. It can serve multiple client requests
simultaneously. It is possible that these various requests being executed concurrently
can end up modifying same set of rows in the database and cause data consistency
issues. To avoid such database concurrency problems ABPP provides locking support
that will work across various types of databases supported by ABPP.
When one database transaction modifies a row in a table all other database
transactions that want to modify the same row are forced to wait till the first
transaction commits or rollbacks. This database feature is used to implement the
locking feature in ABPP.
The ABPP server does not acquire any locks in the actual transaction tables, instead it
defines a lock table that maintains key resources/data item on which the transactions
acquire lock to resolve the contentions. ABPP provides a rule action
“ACQUIRE_DB_LOCK” that each transaction has to use to request lock on key
resources/data items. When a transaction requests for such a lock ABPP attempts to
create/update entries into the lock table. Given that the database serializes such
updates as mentioned above the contending transactions are also serialized.

Chapter 9 DB Locking
The lock table where all the lock entries are kept is “LOCK_TABLE”. The structure
of this table is:
LOCK_KEY LOCK_VALUE LOCK_TIME
ITEM_ID^SHIP_TO_ID^ V-102-1^Velocity-Tonawanda^ 1091655519497
ITEM_ID^SHIP_TO_ID^ V-102-1^Velocity-Warren^ 1091655519497
ITEM_ID^SHIP_TO_ID^ V-102-1^Velocity-DC1^ 1091666519497
ITEM_ID^SHIP_TO_ID^ V-104-1^Velocity-Warren^ 1091666519497
Here LOCK_KEY and LOCK_VALUES together uniquely identify the data items
that client requests are working with. The LOCK_TIME is the column that is updated
to lock appropriate rows in this table.
Every rule that is invoked from outside and results in a new transaction should
identify the data items that it intends to work with. For example: A rule that modifies
purchase order may need exclusive access to all the item and ship_to combinations
that the purchase order lines refer to. To request necessary lock the rule should call the
locking API with appropriate item-ship_to combinations. The locking API will
internally modify the LOCK_TABLE (or insert rows if not present) to update the
LOCK_TIME for corresponding data items that are passed to it. If two client requests
try to modify the same row of the LOCK_TABLE at same time (i.e. they want to work
on same data items) then only one client request will proceed and the other client
request will be forced to wait till the first client request is done.
Setup
Define a lock specification file
The format of the file is:
<DEFINE_LOCKS>
<DEFINE_LOCK Name="ITEM_LOC_LOCK">
<SELECT>
<PROPERTY Value="ITEM_ID"/>
<PROPERTY Value="SHIP_TO_ID"/>
</SELECT>
</DEFINE_LOCK>
<DEFINE_LOCK Name="ITEM_LOCK">
<SELECT>
<PROPERTY Value="ITEM_ID"/>
</SELECT>
</DEFINE_LOCK>
</DEFINE_LOCKS>

API Specification
Each lock definition has a name that uniquely identifies the lock definition within a
service.
The lock definition defines a list of select properties. This is the list of properties that
will be concatenated together to form the lock key. The lock API will expect these
properties in input and concatenation of those values will form the lock value. The
format of the API is discussed below.
Change service config file
Change the service config file to specify the lock definition file defined above.
<dom-config>
<service-config Name="ORDER_ADMIN" TransactionCache="true"
Register="true">
...
<dbLockSpecFiles>
<dbLockSpecFile Name="xservice/orderadmin/xml/pce/dblock/
lockDefinition.xml"/>
</dbLockSpecFiles>
...
</service-config>
</dom-config>
API Specification
The API for acquiring a lock is shown below:
<ACQUIRE_DB_LOCK>
<LOCKS>
<LOCK Name="ITEM_LOC_LOCK"/>
</LOCKS>
<LOCK_DATA>
<LOCK_UNIT> 
<ITEM_ID Value="V-102-1"/>
<SHIP_TO_ID Value="Velocity-Tonawanda"/>
</LOCK_UNIT>
<LOCK_UNIT> 
<ITEM_ID Value="V-104-1"/>
<SHIP_TO_ID Value="Velocity-Warren"/>
</LOCK_UNIT>
</LOCK_DATA>
</ACQUIRE_DB_LOCK>

Chapter 9 DB Locking
The list of locks that need to be acquired is given under the <LOCKS> tag. Each lock
is identified by the lock definition name that was defined in the lock definition file.
Given the lock definition the API knows what data to look for under the
<LOCK_DATA> tag.
The requested lock (in this case ITEM_LOC_LOCK) can be acquired for multiple
data points (lock units) by specifying multiple <LOCK_UNIT> tags. In above case
the ITEM_LOC_LOCK will be acquired for two lock units: V-102-1^Velocity-
Tonawanda^ and V-104-1^Velocity-Warren^.
In summary this API allows the user to identify the lock units and then lock them
using predefined lock definitions. The call to ACQUIRE_DB_LOCK will block until
the lock is acquired.
The ACQUIRE_DB_LOCK API takes care of sorting all the lock units and inserting/
modifying the LOCK_TABLE in proper sequence so as to avoid any deadlocks. It has
also been optimized to minimize the number of database calls that it does. If the
transaction cache is turned on for the service then the API will batch the updates that it
does.
When designing the locking schema take into consideration all the rules/transactions
in the solution. Find out all the tables that are modified/inserted into by the
transactions. Group the transactions by their dependency on each other (modifying/
inserting same rows). For each such group define the lock definition such that
conflicting transactions will get serialized. Then at start of each transaction use
ACQUIRE_DB_LOCK with right lock name and lock data to acquire the locks.

Chapter 10
Audit Trail Framework
Introduction
The following document lays out the detailed description of the audit trail
specification that can be used to specify document which needs to be audited.
Audit Trail Functionality

Transaction data can be changed frequently, however, the changes have to be recorded
in a fashion that they can be retrieved and viewed at a later date. Thus, it is imperative
that an execution system have an inbuilt mechanism to keep an Audit Trail of data
changes. The motivation for keeping a trail to eventually audit, is driven by changes to
certain data elements in the data model, not all, viz. when a note is added to a order we
may choose not to keep a trail of that, however, if the quantity changes we might want
to visit it at a later date and inspect the intention for changing the element, and
therefore might keep the old quantity and also the state of the object when such a
change occurred.
One of the most important requirements for identifying an entry in the audit trail
would be the context information that's associated with the element. Context
information will be static data associated with the changed element, viz. when the
quantity changes on a line item, recording the associated context information like, line
item id, order id would be imperative for the user to get a context of that change, this
can be called static context, because this data will not change in relation to values that
can change.
The context could also have information from other related documents, for example
while recording changes for quantity on a line item we might also choose to record a
field in a related document like the status field on order, thus giving the user a broader
understanding of changes that took place during the transaction not only on the current
document but also on related documents.

Chapter 10 Audit Trail Framework
Other implicit information like, change time, user who executed the change will have
to be recorded for every change that takes place, these will be more evidential in
nature and will constitute information that will further resolve context of the change,
more like a dynamic context.
On the Auditable Document every write will be recorded with the same rules as
described above, even if it's in the same transaction.
Features of Audit Trail framework

The Audit Trail framework makes it easier to define fields to be audited and related
fields from other documents.
Key features of the Audit trail framework:
1. Allows the user to back up a version of information at a document level when any
of the specified fields change.
2. The Spec also allows the user to snapshot fields from other related documents.
3. The user can turn on/off audit trail(s) using a simple X-Command operation.
Defining Audit Trail Definition

Audit Trail definition is a XML based specification and it captures all the data needed
for the Audit trail framework to do its job. Following are the key capability it
provides:
1. Ability to define the name of the document that is to be audit trailed.
2. Ability to define fields that are to be monitored for changes.
3. Ability to define reference fields which could be fields that could be either from
the same document or from a related document.
Simple Audit Trail definition:
<audit-trail-def Name="…." Document="….">
<audit-fields>
<field1/>
<field2/>
</audit-fields>
<reference-fields>
<field3/>
<field4 MapTo="field5"/>
<field6 MapTo="Link1/field1"/>
<field7 [ColumnName="field8"] MapTo="Link2/field1"/>
</reference-fields>

Creating Audit Trail Definitions in ABPP Studio
</audit-trail-def >
Assumptions:
1. All the Field Names defined will be unique, MapTo with or without a link can be
used to point to a field and the element names have to be kept unique.
2. A backup table will be created for the appropriate table with a suffix of _AT.
3. Linked fields specified should always be through a MANY to ONE or ONE to
ONE link.
4. Field Types are introspected and picked up from the actual fields.
5. Audit and Reference Field Names cannot exceed a length of 30.
6. In an Audit Spec which has more than one MapTo field and two or more of such
fields have the same name like in the above sample (Link1/field1 and Link2/
field1), then the user has to specify an attribute called ColumnName to override
the default physical name of the field and ensure the uniqueness of the field name
in the table, otherwise an exception will be thrown.
Creating Audit Trail Definitions in ABPP Studio

User can right click on a service node and on the pop up menu select Additional
Configurations->Insert Audit Trail

An audit trail node is inserted in the service which will now be able to contain Audit
trail specifications as follows:
On the following dialog box the user can either insert a new or an existing audit trail
specification which should now appear below the Audit Trail node.
If you double click the audit trail specification node the user will get a editor on the
right hand side where he/she can define the spec as follows:

Turn off/on audit trail
Note: The audit trail information is stored in database tables. These database tables
are generated from the audit trail specs as part of schema generation. So you
will need to regenerate the database schema (using full or incremental schema
modes) whenever you create a new audit trail spec or change/delete existing
ones.
Turn off/on audit trail

ABPP provides a built-in command to enable/disable audit trail tracking. This
commands can be posted on to the server externally or can be be invoked within X-
Rules. Here is the command description:
SET_AUDIT_TRAIL_STATUS
Description:
This command is used to turn on/off audit trails for all or a set of specific audit trail
specifications. Sometimes it is necessary to disable audit trails during the back-end
load of data. This can be accomplished by setting the audit trail status to InActive
prior to the load and re-setting the status to Active after the load is complete.
You can enable/disable status of all Audit Trails in the system by setting the Status
attribute on ALL.
Syntax:
<SET_AUDIT_TRAIL_STATUS>
<CHOICE_OF>
<CHOOSE>
<AuditTrailSpecName1 Status="Active|InActive"/>
<AuditTrailSpecName2 Status="Active|InActive"/>
...
<AuditTrailSpecNameN Status="Active|InActive"/>

</CHOOSE>
<CHOOSE>
<ALL Status="Active|InActive"/>
</CHOOSE>
</CHOICE_OF>
</SET_AUDIT_TRAIL_STATUS>
Attributes:
AuditTrailSpecName.Status: Valid values are Active/InActive.
Example 1
This example shows the REQUESTS payload for disabling all audit trails on a service
by posting it directly onto ABPP server.
<REQUESTS ServiceName="OrderTracking">
<ALL Status="InActive" />
</REQUESTS>
The above invocation will disable all audit trails on the

OrderTracking service.
Example 2
This example shows a X-Rule code snippet for enabling audit trails corresponding to
an audit trail spec.
<DEFINE_METHOD Name="enableOrderAuditTrail">
<API_DOC>
<INPUT>
<REQUEST Name="enableOrderAuditTrail" />
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE />
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
<RULE>
<ACTION>
<Order_Audit_Trail Status="Active" />
</ACTION>
</RULE>
</DEFINE_METHOD>
The above X-Rule enables audit trails corresponding to the
spec, Order_Audit_Trail.

Audit Trail User Interface
Audit Trail User Interface

Once an audit trail has been defined for your system, you can view the audit trail
information from the web user interface. (Note: be sure that the ABPP_UI service is
currently running.)
To access the audit trail, add the following URL to your navigation workflow:
start.x2ps?SERVICE_NAME=PGL&START_WORKFLOW=AuditTrail&
AUDIT_TRAIL_NAME=audit_trail_name
For example, if your defined audit trail was named "ShipmentAuditTrail", the
appropriate URL would be:
start.x2ps?SERVICE_NAME=PGL&START_WORKFLOW=AuditTrail&
AUDIT_TRAIL_NAME=ShipmentAuditTrail
The Audit Trail UI looks something like the following:
The audit trail UI follows the standard ABPP UI search page motif. The top container
provides searching capabilities, which are comprised of the audit fields, reference
fields, and "static" fields (transaction time, user, etc.) for this specific audit trail. The
bottom container displays the search results. Highlighted cells show values that
changed in that audit trail record.

This UI is automatically generated by the audit trail framework. As such, it is not

customizable via the i2 Studio. It references a search spec automatically-generated by
the audit trail framework, named <AUDIT_TRAIL_NAME>_SEARCH. For
example, if your audit trail is named "ShipmentAuditTrail", the generated search spec
will be named "ShipmentAuditTrail_SEARCH".

Chapter 11
CIS Support
Infrastructure services (CIS) provides a common integration capability for i2

products. CIS addresses most parts of the system-to-system integration problems,
focussing mainly on Enterprise Application Integration and Extract-Transform-Load
problems. For more details on CIS refer to the Infrastructure Service Reference Guide
that is included with the CIS install.
This chapter provides details on the interactions possible between ABPP and CIS.
Topics:
z Making ABPP rules and events available to clients using CIS
z Making operations and notifications of existing CIS application available in
ABPP
Making ABPP rules and events available to clients using

CIS
This document explains the CIS front bus support provided by ABPP server. Any rule
(defined by using <DEFINE_METHOD>) or event (defined by using
<event_descriptor>) in ABPP can be exposed as a CIS operation.
CIS front bus provides a single integration interface for applications and allows the
clients to invoke these interfaces from variety of sources (e.g. RMI, WebMethods,
MQ). CIS needs the interfaces to be defined a particular format and also needs
additional supporting files (metadata type and binding files). The CIS front bus
exposes the application interfaces as a set of operations. The different types of
operation are:
| Operation10 - Operation taking input but not producing any output
| Operation11 - Operation taking input and producing output
| Operation01 - Operation that only publishes and output
For any rule or event in ABPP that is CIS enabled the interface definition and
additional supporting files needed by CIS can be auto-generated. ABPP server also

Chapter 11 CIS Support
handles any runtime conversions needed (between CIS interface definition and native
ABPP rule/event definition).
Any rule in ABPP can be exposed as an Operation10 or Operation11. This will allow
the client to call the rule using any CIS supported binding.
Any event can be exposed as an Operation01. This will allow ABPP application to
publish messages to clients using any CIS supported binding.
Generating Metadata types and Bindings

The steps needed to generate metadata types and bindings are:
1. Define API_DOC and EVENT_DOC for the rules and event descriptor that need
to be CIS enabled
2. Define CIS tag in API_DOC/EVENT_DOC
3. Define config file needed for CIS file generation
4. Specify the config file in server config file (e.g. xserver.xml)
5. Define name mapping file
6. Specify the mapping file in service config file (e.g. orderadmin.xml)
7. Override default data type mapping only if needed
8. Generate the CIS metadata types and binding files
Define API_DOC and EVENT_DOC for the rules and event descriptor
For details on defining API_DOC and EVENT_DOC refer to sections “Event and
Request Interfaces” and “Web Service Definitions” in this document
Here is a sample definition of the API_DOC and EVENT_DOC:
<DEFINE_METHOD Name="createPO">
<API_DOC>
<INPUT>
<REQUEST Name="createPO" Comment="This API will create a
purchase order and return the ID of the purchase order">
<CUSTOMER_ORDER>
<DOC_TYPE Value="ORDER" Comment="The valid values for this
field are ORDER or DRAFT or TEMPLATE"/>
Comment="The date time when this PO was submitted"/>
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM Type="DELIVERY[Optional=true]">
<ID Value="L1"/>
<UNIT_PRICE Value="25.78[Type=double]" Optional="true"
Comment="This is the item unit price"/>
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>

Making ABPP rules and events available to clients using CIS
<ID Value="P1" Comment="This is the ID of the newly created PO"/
>
<STATE_ID Value="ACK" Comment="The status of newly created PO"/
>
</RESPONSE>
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
<RULE>
<ACTION>
<PRINTLN Value="Incoming cis message is {$thisParam}"/>
<SET DocVar="thisReturn" Property="ID" FromValue="P1"/>
<SET DocVar="thisReturn" Property="STATE_ID" FromValue="ACK"/>
</ACTION>
</RULE>
</DEFINE_METHOD>
<event_descriptor Name="poHasBeenCreated">
<EVENT_DOC>
<RAISE_EVENT Name="poHasBeenCreated" Comment="This event is
generated when a purchase order is created">
<CUSTOMER_ORDER>
<ID Value="C1" Comment="This is the ID of the PO that has been
created"/>
<DOC_TYPE Value="ORDER"/>
<ORDER_TYPE_ID Value="STANDARD"/>
<ORDER_LINE_ITEM Repeatable="true">
<ID Value="L1"/>
<NEEDS_DELIVERY Value="true[Type=boolean]" Optional="true"/>
</ORDER_LINE_ITEM>
</CUSTOMER_ORDER>
</RAISE_EVENT>
<CIS Name="poCreated">
<PORT_TYPE Value="CisTest"/>
</CIS>
</EVENT_DOC>
</event_descriptor>
Define CIS tag in API_DOC/EVENT_DOC

For rule definition the format of the CIS tag is:
<API_DOC>
<INPUT>
...
</INPUT>
<OUTPUT>
...
</OUTPUT>
<CIS Name="createPO">

<REPLY_TYPE Value="PUBLISH"/> <!-Valid Values NONE, PUBLISH,

DELIVER -->
</CIS>
</API_DOC>
<RULE>
<ACTION>
...
</ACTION>
</RULE>
</DEFINE_METHOD>
The 'Name' attribute on <CIS> tag defines the operation name as it will be seen by
CIS. This name should be unique among all rules/events defined with same portType.
CIS has a compliance requirement that all operation names be in Lower Camel Case.
For more details refer to CIS documentation.
The <PORT_TYPE> specifies the CIS <portType> name on which to expose this
operation. Additional portType details are defined in the cis config file specified in
server config file.
The <REPLY_TYPE> specifies how the response needs to be handled:
NONE - No response is generated i.e. the response is discarded
PUBLISH - The response is published back. The caller does not wait for response.
DELIVER - The response is synchronously delivered to the waiting caller.
Note: Response types of PUBLISH/DELIVER make a difference only for
Webmethods binding. For all other bindings it does not change the response behavior.
For event descriptor the format of the CIS tag is:
<event_descriptor Name="poHasBeenCreated">
<EVENT_DOC>
<RAISE_EVENT Name="poHasBeenCreated" Comment="This event is
generated when a purchase order is created">
...
</RAISE_EVENT>
<CIS Name="poCreated">
</CIS>
</EVENT_DOC>
</event_descriptor>
The 'Name' attribute on <CIS> tag defines the operation name as it will be seen by
CIS. Requirement on this are similar to those given above for the rule API_DOC.
The <PORT_TYPE> specifies the CIS <portType> name on which to expose this
operation.
Define config file needed for CIS file generation

A config file needs to be defined to give additional info needed for the CIS file
generation. The format of this file is:
<cisConfig>
<portType Name="CisTest">
<argFiles Value="xserverCis.xml"/>

<classPath>
<path Value="C:\Projects\Oms\6x\release\bin\cis"/>
<path Value="C:\Projects\Oms\6x\release\cfg\properties"/>
<path Value="C:\Projects\ABPP\studio\bre\lib\bpe-util.jar"/>
<path Value="C:\Projects\ABPP\studio\bre\lib\bpe-server.jar"/>
<path Value="C:\Projects\ABPP\studio\bre\lib\bpe-services.jar"/
>
<path Value="C:\Projects\ABPP\studio\bre\lib\3plib\xerces.jar"/
>
<path Value="C:\Projects\ABPP\studio\bre\lib\3plib\xalan.jar"/>
<pathValue="C:\Projects\ABPP\studio\bre\lib\3plib\jdom.jar"/>
<path Value="C:\Projects\ABPP\studio\bre\lib\3plib\i2util.jar"/
>
<path Value="C:\Projects\ABPP\studio\bre\lib\3plib\i2dom.jar"/>
<path Value="C:\Projects\ABPP\studio\bre\lib\3plib\log4j.jar"/>
<path Value="C:\Projects\ABPP\studio\bre\lib\3plib\
httpclient.jar"/>
httpclientLogging.jar"/>
<path Value="C:\Projects\ABPP\studio\bre\lib\3plib\jcert.jar"/>
ojdbc14.jar"/>
</classPath>
<bindings>
<rmi>
<classPath> 
<path Value="."/>
<path Value="someAdditional.jar"/>
</classPath>
</rmi>
<webMethodsEnterprise>
<config broker="pushkarTest" host="comdev4">
<client logicalId="OA"/>
</config>
</webMethodsEnterprise>
<mq>
<config
jndiContextFactory="com.sun.jndi.fscontext.RefFSContextFactory"
jndiProviderURL="file:/C:"/>
<destinationMap type="custom"> 
<map operation="createPO" destination="i2.ptp.OA.OA"/>
</destinationMap>
</mq>
</bindings>
</portType>
</cisConfig>
There can be multiple <portType> tags in this file. Each portType tag here results in a
portType getting created in CIS with the same name. The operations defined in the
CIS portType will be the ABPP rules and events specifying same portType Name.

The <argFiles> tag defines the startup parameters for the ABPP server that runs inside
CIS adapter. The files that are specified here should be available in specified
classpath.
The <classPath> tag defines the classpath for the CIS adapter. The paths defined here
need to be absolute paths. The paths defined here form the base classPath. In addition
to this for a particular binding additional class paths can be defined that get appended
to the base classPath.
The <rmi> tag defines the RMI binding. No additional info is needed for RMI binding
The <webmethodsEnterprise> tag defines the WebMethods Enterprise binding.
The <mq> tag defines the IBM MQSeries binding.
For details on the parameters/attributes needed for each binding refer to the CIS
documentation.
Specify the config file in server config file

The config file created in previous step needed to be specified in the server config file
(e.g. xserver.xml). Here is an example of that:
<dom-config>
<appserver-config Name="Appserver1">
...
<cisGenerate>
<configFile Value="cisConfig.xml"/>
<outputDir Value="cis"/>
</cisGenerate>
</appserver-config>
</dom-config>
The <outputDir> specified above is where all the CIS files will be generated.
Define name mapping file

CIS compliance requires that all member names be defined in Lower Camel Case (e.g.
orderedQty). Also underscores, dots, dashes are not allowed.
ABPP rules and events have no such restriction. To make ABPP APIs CIS compliant
tag/attribute name mapping needs to be done. This is an optional step. If mapping file
is not provided the ABPP tag names will be maintained.
Example:
<CUSTOMER_ORDER>
<DOC_TYPE Value="ORDER"/>
...
</CUSTOMER_ORDER>
Native xml given above will need to be represented as below in
CIS:
<customerOrder>
<docType>ORDER</docType>
...
</customerOrder>
This name mapping to and fro from CIS is achieved by defining a name mapping file
for each ABPP service.

The format of the name mapping file is:

<mapping>
<map NativeName="CUSTOMER_ORDER" CisName="customerOrder"/>
<map NativeName="DOC_TYPE" CisName="docType"/>
...
</mapping>
If there is a conflicting need for mapping i.e. in one API <ORDER_LINE_ITEM> in
OMx maps to <orderLineItem> in CIS and in another API there is a need to map
<ORDER_LINE_ITEM> in OMx to <oli> in CIS then that can be achieved by
defining the mapping as part of the API_DOC/EVENT_DOC.
Here is an example of that:
<API_DOC>
<INPUT>
<REQUEST Name="createPO" Comment="This API will create a
purchase order and return the ID of the purchase order">
<CUSTOMER_ORDER>
...
<ORDER_LINE_ITEMS>
<ORDER_LINE_ITEM Type="DELIVERY[Optional=true, CisName=myType]"
CisName="oli">
...
</ORDER_LINE_ITEM>
</ORDER_LINE_ITEMS>
</CUSTOMER_ORDER>
</REQUEST>
</INPUT>
<OUTPUT>
...
</OUTPUT>
</API_DOC>
<RULE>
<ACTION>
...
</ACTION>
</RULE>
</DEFINE_METHOD>
In the example above tag 'ORDER_LINE_ITEM' is mapped to 'oli' and attribute
'Type' is mapped to 'myType'.
Specify the mapping file in service config file

The name mapping file defined above needs to be specified in the service config file
(e.g. orderadmin.xml). Here is an example of that:
<dom-config>
<service-config Name="ORDER_ADMIN" TransactionCache="true">
...
<cisTagNameMapping>
<mappingFile Name="xservice/orderadmin/xml/sce/cis/
mapping.xml"/>
</cisTagNameMapping>
</service-config>

</dom-config>
Override default data type mapping only if needed

Some of the data types used by CIS are different than those used in ABPP. The ABPP
cis adapter does default data type mapping.
ABPP Data Type Cis Data Type
string xsd:string
LongString xsd:string
constant xsd:string
int xsd:integer
float xsd:decimal
double xsd:decimal
Boolean xsd:boolean
datetime (MM/dd/yyyy hh:mm:ss) xsd:dateTime (yyyy-MM-ddThh:mm:ss)
date (MM/dd/yyyy) xsd:date (yyyy-MM-dd)
time (hh:mm:ss) xsd:time (hh:mm:ss)
timestamp (MM/dd/yyyy hh:mm:ss:SSS) xsd:dateTime (yyyy-MM-ddThh:mm:ss.SSS)
It is possible to override this default data type mapping. To override the default type
mapping the 'CisType' attribute can be specified in API_DOC/EVENT_DOC as
follows:
<AVAILABLE_DATE Value="07/14/2003 09:00:00:000[Type=datetime
CisType=xsd:string]"/>
In this example the Value attribute is of type 'datetime' in ABPP but when in CIS it
will be published as 'xsd:string' type.
Generate the CIS metadata types and binding files

To generate the CIS files create a batch file containing the xserver.xml and all desired
Xservice config files (e.g., em.xml, orderadmin.xml, …) as follows:
@echo off
call .\omxenv.bat
title OMx Server
java com.i2.xcore.cis.CisGenerator xserver.xml em.xml
orderadmin.xml …
pause
Run the batch file and that will create the CIS files in the specified output directory.
The CIS generator will generate following directories under the output directory:
Types - Has all the metadata type files for the operations

Bindings - Has one binding file for every port type defined
Apidocs - For every ABPP service has one file for every API_DOCs/EVENT_DOCs
defining the CIS enabled rules/events
Mappings - For every ABPP service has the name mapping file
Handling Attributes
The CIS xml format does not allow attributes on xml tags. To handle this problem the
ABPP CIS adapter will do runtime conversion to map attributes in ABPP xml as child
tags in cis xml. Here is an example of this mapping:
Following tag in ABPP:
<AVAILABLE_DATE Value="07/14/2003 09:00:00" OldValue="01/16/
2004 09:00:00"/>
Will be mapped to following in CIS:
<AvailableDate>
<attributes>
<Value>2004-03-10T09:30:47</Value>
<OldValue>2004-03-10T09:30:47</OldValue>
</attributes>
</AvailableDate>
For this mapping all ABPP attributes are mapped as child tag of special tag named
'attributes'. As such 'attributes' is a reserved tag name and ABPP xml should not use
this name for tags.
Name mapping can be used to map 'attributes' to some other name if needed.
Handling Text
As the 'Value' attribute in ABPP is mapped to tag text in CIS if the ABPP tag has text
then it gets mapped to child tag in cis xml. Here is an example of this mapping:
Following tag in ABPP:
<AVAILABLE_DATE>07/14/2003 09:00:00</AVAILABLE_DATE>
Defined by using API_DOC:
<AVAILABLE_DATE>07/14/2003 09:00:00[Type=datetime,
Comment=Example of text]</AVAILABLE_DATE>
Will be mapped to following in CIS:
<AvailableDate>
<attributes>
<text>2003-07-14T09:00:00</text>
</attributes>
</AvailableDate>
Runtime Setup
The ABPP services with CIS support can be deployed in two forms:
1. ABPP services run in one JVM and the CIS adapter runs in different JVM.

To run ABPP in this configuration create one server config files for every CIS
portType that is defined. In the server config file select different listenerPort for the
server.
The server config file created here needs to be specified as the startup parameter in the
cis config file e.g. <argFiles Value="xserverCis.xml"/>
2. ABPP services and CIS adapter run in same JVM.
To run ABPP server in this configuration create one server config file for every CIS
portType that is defined. In the server config file select different listenerPort for the
server.
The server config file created here needs to be specified as the startup parameter in the
cis config file. For example if there is only one port then the argFiles can be specified
as:
<argFiles Value=" xserver.xml timersink.xml catalog.xml
credit.xml deployment.xml eai.xml em.xml email.xml invoice.xml
emx.xml orderadmin.xml pricer.xml tax.xml ui.xml messaging.xml

approval.xml df.xml dataupload.xml imx.xml invoice_pce.xml

match.xml tdm.xml custom.xml"/>
Running CIS
Here are some basic steps that can be used to test this functionality:
1. Install CIS 6.2
2. Follow all the steps needed to generate the CIS files. To start with only have RMI
binding.
3. Run CIS\6.2\cis-sdk\bin\launch.bat. This will start the CIS launcher that provides
various scripts needed.
4. Run the processMetadata.py script. Click on 'Usage' to find out the script
parameters. Uncheck the 'Close when Complete' checkbox so that the window
does not disappear after the script execution is done. This script will create
additional files like xsd files etc. Example of parameters: C:\Projects\Oms\6x\
release\bin\cis\bindings\CisTest.xml root-output-dir=C:\Projects\Oms\6x\release\
bin\cis\output
5. Run the runCISAgent.py script. This will start the CIS agent. You can access the
CIS agent using URL http://localhost:8088
6. Run installAdapter.py script to install the ABPP adapter. This script will need the
binding file that was created in step 2. Under the output directory specified the
binding file is created under the 'bindings' directory. Example of parameter: -m C:\
Projects\Oms\6x\release\bin\cis\bindings\CisTest.xml
7. Then go to http://localhost:8088, expand 'Agent Manager' and click on 'Adapters'.
The adapter installed in step 6 should be present in the list of adapters.
8. Start the adapter by clicking on 'Start' button.
9. Click on the adapters 'instanceId' link. This should show all the operations that are
registered for the adapter
10. To test outgoing messages create a sample request to raise some CIS enabled
event and execute it. Then click on the 'View Log' button on the CIS adapter
details screen. The adapter log should register that it received the event and that it
published it out.
11. To test incoming messages run the cisRequestEx.py provided in the CIS launcher.
This will send a message to the adapter. This message will be translated and then
send to the ABPP service. The response (only for Operation11) will be sent back.
Examples of XML Messages

ABPP EVENT_DOC:
<event_descriptor Name="ScheduleWritebackOutbound">
<EVENT_DOC>
<RAISE_EVENT Name="ScheduleWritebackOutbound" Comment="">
<ORDER_SCHEDULE Comment="OldValue attribute won't be sent for
NEW schedule">
Comment="system populated; signal creation date"/>
<ORDER_POINT_ID Value="Sanford"/>

<PLANNER_CODE Value="MP03"/>
<SELLING_ORG_ID Value="H5768U0"/>
<BPO_ID Value="BPO-234" Comment="AN-9"/>
<BPO_LI_SEQ_NUM Value="1[Type=int CisType=xsd:string]"
Comment="NUM-5"/>
<ITEM_ID Value="151-S"/>
<SCHEDULE_TYPE
Value="FIRM|IN_PROCESS|MATERIAL_ACQUISITION|PLANNED"
OldValue="PLANNED"/>
<AVAILABLE_DATE Value="07/14/2003 09:00:00:000[Type=datetime
CisType=xsd:string]" OldValue="01/16/2004
09:00:00:000[Type=datetime]" Comment="DOE-date format"/>
<DELIVERY_DATE Value="07/09/2003 00:00:00:000[Type=datetime]"
OldValue="01/13/2004 09:00:00:000[Type=datetime]" Comment="DOE-
date format"/>
<SHIP_DATE Value="07/02/2003 09:00:00:000[Type=datetime]"
OldValue="01/09/2004 00:00:00:000[Type=datetime]" Comment="DOE-
date format"/>
<QTY Value="120.0[Type=double]" OldValue="100.0[Type=double]"
Comment="NUM-7; Qty would be 0 if schedule is cancelled"/>
</ORDER_SCHEDULE>
</RAISE_EVENT>
<CIS Name="ScheduleWritebackOutbound">
<PORT_TYPE Value="CisInt"/>
</CIS>
</EVENT_DOC>
</event_descriptor>
Sample xml that conforms to the EVENT_DOC:
<RAISE_EVENT Name="ScheduleWritebackOutbound">
<ORDER_SCHEDULE>
<CREATION_DATE Value="03/06/2003 09:17:27"/>
<ORDER_POINT_ID Value="Sanford"/>
<PLANNER_CODE Value="MP03"/>
<SELLING_ORG_ID Value="H5768U0"/>
<BPO_ID Value="BPO-234"/>
<BPO_LI_SEQ_NUM Value="1"/>
<ITEM_ID Value="151-S"/>
<SCHEDULE_TYPE Value="FIRM" OldValue="PLANNED"/>
<AVAILABLE_DATE Value="07/14/2003 09:00:00:000"
OldValue="01/16/2004 09:00:00:000"/>
<DELIVERY_DATE Value="07/09/2003 00:00:00:000"
OldValue="01/13/2004 09:00:00:000"/>
<SHIP_DATE Value="07/02/2003 09:00:00:000"
OldValue="01/09/2004 00:00:00:000"/>
<QTY Value="120.0" OldValue="100.0"/>
</ORDER_SCHEDULE>
</RAISE_EVENT>
</REQUESTS>
CIS xml that will be generated:
<CISDocument>
<OrderSchedule>
<CreationDate>2004-03-10T09:30:47</CreationDate>

<OrderPointID>String</OrderPointID>
<PlannerCode>String</PlannerCode>
<SellingOrgID>String</SellingOrgID>
<BPOID>String</BPOID>
<BPOLiSeqNum>4</BPOLiSeqNum>
<ItemID>String</ItemID>
<ScheduleType> <!-Note that CIS does not allow
attributes on tags. The attributes on OMx tags are converted to
child tags as seen here -->
<Attributes>
<Value>String</Value>
<OldValue>String</OldValue>
</Attributes>
</ScheduleType>
<AvailableDate>
<Attributes>
<Value>2004-03-10T09:30:47</Value>
</Attributes>
</AvailableDate>
<DeliveryDate>
<Attributes>
<Value>2004-03-10T09:30:47</Value>
</Attributes>
</DeliveryDate>
<ShipDate>
<Attributes>
<Value>2004-03-10T09:30:47</Value>
</Attributes>
</ShipDate>
<Qty>
<Attributes>
<Value>3.1415</Value>
<OldValue>3.1415</OldValue>
</Attributes>
</Qty>
</OrderSchedule>
</CISDocument>
Note: If you require the response xml to use the Operation name as the root tag
instead of <CISDocument> add the following section to server config file.
<cisClientConfig>
<property Key="CisRootUseOperName" Value="true"/>
</cisClientConfig>

Making operations and notifications of existing CIS

application available in ABPP
ABPP Binding types

Binding type is the protocol used to invoke web service operations from ABPP.
ABPP has built in support for SOAP binding and CIS binding.
SOAP Binding
When SOAP binding is used, ABPP acts as a SOAP client to access web services.
CIS (Infrastructure Services) provides the facility to expose product adapters as a CIS
web service. SOAP binding can be used with both CIS hosted web services and non
CIS hosted web services.
SOAP binding has the following limitations:
1. Only web service operations can be invoked. It does not provide support for
receiving notifications.
2. It does not support user authentication.
CIS Binding
CIS binding uses CIS APIs instead of SOAP and can be used only on adapters
installed in CIS. Instead of web service calls, CIS client APIs are used to invoke
operations on the installed CIS Adapters.
CIS binding can be used to invoke operations as well as receive notifications. It also
allows user authentication for enhanced security.
Generate WSDL from CIS Adapter

To use either of the above binding types we need to first generate the appropriate
WSDL from the CIS adapter.
Sample CIS Adapter

We will use the following CIS adapter (POmetadata.xml) to demonstrate usage of
CIS and SOAP bindings.
<?xml version="1.0" encoding="utf-8"?>
<definitions xmlns="http://www.i2.com/cis">

<types>
<type javaPrefix="Seg" name="PORequest"
javaPackage="com.i2.fp.tmapi">
<member name="poID" type="xsd:string"
use="required"/>
</type>
<type javaPrefix="Seg" name="PriceInfo"
<member name="price" type="xsd:integer"
use="required"/>

Making operations and notifications of existing CIS application available in ABPP
<member name="currency" type="xsd:string"

use="required"/>
</type>
<type javaPrefix="Seg" name="NotifyInfo"
<member name="date" type="xsd:string" use="required"/>
</type>
</types>

<portType name="Procurement" serviceName="Procurement"
version="6.1">
<operation name="notifyPO">
<documentation>Notification operation.</documentation>
<handler class="com.i2.fp.tmapi.NotifyPOOperation"/>
<output type="NotifyInfo"/>
</operation>
<operation name="oneWayPO">
<handler class="com.i2.fp.tmapi.oneWayPOOperation"/>
<input type="PORequest"/>
</operation>
<operation name="twoWayPO">
<handler class="com.i2.fp.tmapi.twoWayPOOperation"/>
<input type="PORequest"/>
<output type="PriceInfo"/>
</operation>
</portType>
<bindings instanceID="FP-PO">
<RMI type="Procurement">
<config exportPort="1222"/>
<security requireClientAuthentication="true"
requireSenderIdentity="true"/>
<classPath>
<path>.</path>
</classPath>
</RMI>
</bindings>
</definitions>
Note that this adapter defines two operations (oneWayPO, twoWayPO) and one
notification(notifyPO).
The portType name is 'Procurement' and the instanceID is 'FP-PO'.
Generate SOAP WSDL from CIS adapter

Start CIS agent and Install CIS adapter in web service mode.
CIS provides python scripts to generate a WSDL for this web service.
The script processMetadata.py generates a WSDL with SOAP binding.
Following is the command to generate the WSDL file using processMetadata.py.
%CIS_HOME%\bin\launch.bat %CIS_HOME%\bin\ processMetadata.py
<metadatafile path > <create-WSDL=true> <ws-url=end point URL of the
webservice> <root-output-dir>

Here, Metadatafile path is the absolute path to POmetadata.xml (C:\i2\cis\Proc-

FPAdapter\POmetadata.xml).
''ws-url' is required to generate service element in WSDL with the specified endpoint
URL. This URL can be obtained from the CIS manager UI for the installed adapter
under the web services section.
The root-output-dir is the target directory for the generated files(E:\temp\ABPP-CIS).
The output of the above script is the following WSDL(Procurement-FP-PO.wsdl).

Note that this WSDL has SOAP binding and it does not include the notification
operation 'notifyPO'. This is the WSDL required to make web service calls to CIS
Adapter using SOAP binding.
<?xml version="1.0" encoding="utf-8"?>

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http:/
/schemas.xmlsoap.org/wsdl/soap/" xmlns:http="http://
schemas.xmlsoap.org/wsdl/http/" xmlns:soapenc="http://
schemas.xmlsoap.org/soap/encoding/" xmlns:mime="http://
schemas.xmlsoap.org/wsdl/mime/" xmlns:cis="http://www.i2.com/
cis" xmlns:saxon="http://icl.com/saxon" targetNamespace="http:/
/www.i2.com/cis">
<types>
<xsd:schema targetNamespace="http://www.i2.com/cis"
elementFormDefault="qualified">
<xsd:complexType name="PORequest">
<xsd:sequence>
<xsd:element name="PoID" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="PriceInfo">
<xsd:sequence>
<xsd:element name="Price" type="xsd:integer"/>
<xsd:element name="Currency" type="xsd:string"/>
</xsd:sequence>

</xsd:complexType>
<xsd:complexType name="NotifyInfo">
<xsd:sequence>
<xsd:element name="Date" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="notifyPOResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Date" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="oneWayPO">
<xsd:complexType>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="oneWayPOAckOkResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="AckOk" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="twoWayPO">
<xsd:complexType>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="twoWayPOResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Price" type="xsd:integer"/>
<xsd:element name="Currency" type="xsd:string"/
>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="getSessionID">
<xsd:complexType/>
</xsd:element>
<xsd:element name="getSessionIDResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="0" maxOccurs="1"
name="SessionID" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="SessionID" type="xsd:string"/>

<xsd:complexType name="OperationException">
<xsd:sequence>
<xsd:element name="ExceptionClass"
type="xsd:string"/>
<xsd:element name="ExceptionMessage"
type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="OperationException"
type="cis:OperationException"/>
<xsd:element name="closeSession">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="SessionID"
type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="closeSessionAckOkResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="AckOk" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</types>
<message name="oneWayPO">
<part name="parameters" element="cis:oneWayPO"/>
</message>
<message name="oneWayPOAckOkResponse">
<part name="parameters"
element="cis:oneWayPOAckOkResponse"/>
</message>
<message name="twoWayPO">
<part name="parameters" element="cis:twoWayPO"/>
</message>
<message name="twoWayPOResponse">
<part name="parameters" element="cis:twoWayPOResponse"/>
</message>
<message name="closeSessionAckOkResponse">
element="cis:closeSessionAckOkResponse"/>
</message>
<message name="OperationException">
<part name="parameters" element="cis:OperationException"/
>
</message>
<message name="getSessionID">
<part name="parameters" element="cis:getSessionID"/>
</message>
<message name="getSessionIDResponse">

element="cis:getSessionIDResponse"/>
</message>
<message name="closeSession">
<part name="parameters" element="cis:closeSession"/>
</message>
<message name="soapHeader">
<part name="CISHeader" element="cis:SessionID"/>
</message>
<portType name="ProcurementPortType">
<documentation/>
<input message="cis:oneWayPO"/>
<output message="cis:oneWayPOAckOkResponse"/>
<fault name="CISFault"
message="cis:OperationException"/>
</operation>
<documentation/>
<input message="cis:twoWayPO"/>
<output message="cis:twoWayPOResponse"/>
<fault name="CISFault"
message="cis:OperationException"/>
</operation>
<operation name="getSessionID">
<documentation>Returns a new Session ID from the server
which is used when invoking stateful operations.</
documentation>
<input message="cis:getSessionID"/>
<output message="cis:getSessionIDResponse"/>
</operation>
<operation name="closeSession">
<documentation>Closes server side resources associated
with the specified Session ID.</documentation>
<input message="cis:closeSession"/>
<output message="cis:closeSessionAckOkResponse"/>
</operation>
</portType>
<binding name="ProcurementSoapBinding"
type="cis:ProcurementPortType">
<soap:binding transport="http://schemas.xmlsoap.org/soap/
http" style="document"/>
<soap:operation soapAction=""/>
<input>
<soap:body use="literal"/>
</input>
<output>
</output>
<fault name="CISFault">
<soap:fault name="CISFault" use="literal"/>
</fault>
</operation>

<input>
</input>
<output>
</output>
<soap:fault name="CISFault" use="literal"/>
</fault>
</operation>
<input>
</input>
<output>
</output>
</operation>
<input>
</input>
<output>
</output>
</operation>
</binding>
<service name="ProcurementService">
<port name="ProcurementPort"
binding="cis:ProcurementSoapBinding">
<soap:address location="http://d610ig5qsf1s:8088/
webservices/services/Procurement-FP-PO"/>
</port>
</service>
</definitions>
Generate CIS WSDL

This step is required only if we want to use CIS binding to make calls to the CIS
Adapter. This step adds incremental CIS binding elements to the SOAP WSDL
generated in the previous step and hence the generated WSDL can be used with SOAP
binding also.
The CIS script generateWSDLForBPE.py generates a WSDL with both SOAP and
CIS bindings.
The following command generates the CIS WSDL file.
%CIS_HOME%\bin\launch.bat %CIS_HOME%\bin\
generateWSDLForBPE.py

<metadataFile> <SOAP WSDL generated by processMetadata.py >

<output directory for generated WSDL> <instanceID of the
installed adapter in CIS>
Example:
launch.bat generateWSDLForBPE.py C:\i2\cis\Proc-FPAdapter\
POmetadata.xml E:\temp\ABPP-CIS\Procurement-FP-PO.wsdl E:\temp\
ABPP-CIS\ FP-PO
Where
C:\i2\cis\Proc-FPAdapter\POmetadata.xml is the metadata file.
E:\temp\ABPP-CIS\Procurement-FP-PO.wsdl is the SOAP WSDL
generated by processMetadata.py.
E:\temp\ABPP-CIS\ is the output directory
Note: The output directory for generated WSDL must be specified with an ending
file separator '\' as in the example above.
FP-PO is the instanceID of the installed adapter. Refer to the metadata file in Sample
CIS Adapter.
The output of the above script is the following CIS WSDL (Procurement-BPE.wsdl).
Note that this WSDL has both CIS and SOAP bindings and supports both operations
and notifications. This WSDL can be used to make calls to CIS adapters using either
SOAP or CIS binding. However, irrespective of the WSDL used, the limitations of
SOAP binding still apply.
<?xml version="1.0" encoding="UTF-8"?>

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http:/
/schemas.xmlsoap.org/wsdl/soap/" xmlns:http="http://
schemas.xmlsoap.org/wsdl/http/" xmlns:soapenc="http://
schemas.xmlsoap.org/soap/encoding/" xmlns:mime="http://
schemas.xmlsoap.org/wsdl/mime/" xmlns:cis="http://www.i2.com/
cis" xmlns:saxon="http://icl.com/saxon" xmlns:cisWsdl="http://
www.i2.com/wsdl/cis" targetNamespace="http://www.i2.com/cis">
<types>
<xsd:schema targetNamespace="http://www.i2.com/cis"
elementFormDefault="qualified">
<xsd:complexType name="PORequest">
<xsd:sequence>
<xsd:element name="PoID" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="PriceInfo">
<xsd:sequence>
<xsd:element name="Price" type="xsd:integer" />
<xsd:element name="Currency" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="NotifyInfo">
<xsd:sequence>
<xsd:element name="Date" type="xsd:string" />

</xsd:sequence>
</xsd:complexType>
<xsd:element name="notifyPOResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Date" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="oneWayPO">
<xsd:complexType>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="oneWayPOAckOkResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="AckOk" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="twoWayPO">
<xsd:complexType>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="twoWayPOResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Price" type="xsd:integer" />
<xsd:element name="Currency" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="getSessionID">
<xsd:complexType />
</xsd:element>
<xsd:element name="getSessionIDResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element minOccurs="0" maxOccurs="1"
name="SessionID" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="SessionID" type="xsd:string" />
<xsd:complexType name="OperationException">
<xsd:sequence>
<xsd:element name="ExceptionClass" type="xsd:string" />
<xsd:element name="ExceptionMessage" type="xsd:string" />

</xsd:sequence>
</xsd:complexType>
<xsd:element name="OperationException"
type="cis:OperationException" />
<xsd:element name="closeSession">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="SessionID" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="closeSessionAckOkResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="AckOk" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</types>
<message name="oneWayPO">
<part name="parameters" element="cis:oneWayPO" />
</message>
<message name="oneWayPOAckOkResponse">
<part name="parameters" element="cis:oneWayPOAckOkResponse" />
</message>
<message name="twoWayPO">
<part name="parameters" element="cis:twoWayPO" />
</message>
<message name="twoWayPOResponse">
<part name="parameters" element="cis:twoWayPOResponse" />
</message>
<message name="closeSessionAckOkResponse">
element="cis:closeSessionAckOkResponse" />
</message>
<message name="OperationException">
<part name="parameters" element="cis:OperationException" />
</message>
<message name="getSessionID">
<part name="parameters" element="cis:getSessionID" />
</message>
<message name="getSessionIDResponse">
<part name="parameters" element="cis:getSessionIDResponse" />
</message>
<message name="closeSession">
<part name="parameters" element="cis:closeSession" />
</message>
<message name="soapHeader">
<part name="CISHeader" element="cis:SessionID" />
</message>
<message name="notifyPOResponse">
<part name="parameters" element="cis:notifyPOResponse" />
</message>

<portType name="ProcurementPortType">
<operation name="notifyPO">
<documentation>Notification operation.</documentation>
<output message="cis:notifyPOResponse" />
<fault name="CISFault" message="cis:OperationException" />
</operation>
<documentation />
<input message="cis:oneWayPO" />
<output message="cis:oneWayPOAckOkResponse" />
</operation>
<documentation />
<input message="cis:twoWayPO" />
<output message="cis:twoWayPOResponse" />
</operation>
<documentation>Returns a new Session ID from the server
which is used when invoking stateful operations.</
documentation>
<input message="cis:getSessionID" />
<output message="cis:getSessionIDResponse" />
</operation>
<documentation>Closes server side resources associated
with the specified Session ID.</documentation>
<input message="cis:closeSession" />
<output message="cis:closeSessionAckOkResponse" />
</operation>
</portType>
<binding name="ProcurementSoapBinding"
<soap:binding transport="http://schemas.xmlsoap.org/soap/
http" style="document" />
<soap:operation soapAction="" />
<input>
<soap:body use="literal" />
</input>
<output>
</output>
<soap:fault name="CISFault" use="literal" />
</fault>
</operation>
<input>
</input>
<output>


</output>
<soap:fault name="CISFault" use="literal" />
</fault>
</operation>
<input>
</input>
<output>
</output>
</operation>
<input>
</input>
<output>
</output>
</operation>
</binding>
<binding name="ProcurementCISBinding"
<cisWsdl:binding transport="www.i2.com/cis/cci"
style="document" />
</binding>
<service name="ProcurementService">
<port name="ProcurementPort"
binding="cis:ProcurementSoapBinding">
<soap:address location="http://d610ig5qsf1s:8088/
webservices/services/Procurement-FP-PO" />
</port>
<port name="ProcurementCISPort"
binding="cis:ProcurementCISBinding">
<cisWsdl:address instance="FP-PO" portType="Procurement" />
</port>
</service>
</definitions>
Using SOAP binding to make web service calls to CIS Adapter

Following are the steps needed to invoke webservice hosted by CIS Adapter using
SOAP binding.
Insert the generated WSDL

In the studio project, create a new group ('Demo') under Web Service Set and click
'Insert' on the newly created group.

Select "File Based" Loading mechanism.
For SOAP binding, we could use either the SOAP WSDL or the CIS WSDL as both
contain the SOAP binding element.
Navigate to the location of the generated SOAP WSDL.
In our example, navigate to E:\temp\ABPP-CIS and select Procurement-FP-PO.wsdl.
In ABPP, a web service must be activated in order to be able to invoke its operations.
Navigate to the inserted web service, right-click and select "Activate" popup menu
item.
Add workflow with a SOAP binding WSDL node

Create a workflow (Example: InvokeWebServiceOperation.xml) having a WSDL
node (Example: InvokeWebServiceOperation) that refers to the imported WSDL
(Example: ProcurementService).

Configure WSDL node properties

Click on the WSDL node to configure node properties.
Configure Operation.
Select any operation (here, selected operation is 'twoWayPO') and fill-in the body
of the request in the bottom half of "parameters" window.

Configure Binding Type.
Select DEFAULT or SOAP from the dropdown for the binding type. The Option
'DEFAULT' is explained in further detail in section Update server configuration file.
With the above steps, the WSDL node is configured to use SOAP binding.
Setup steps to use CIS Binding

This section explains the steps needed to use CIS Binding to invoke operations and/or
to receive notifications from the CIS Adapter.
Set project ClassPath

Add CIS jar files to the studio project.

Click menu item Tools->Classpath…

Click "Add..." and add the following jar files to the classpath.
-cis.jar (in <CIS_HOME>\lib),
-cis-util.jar (in <CIS_HOME>\lib),
-connector.jar (in <CIS_HOME>\lib),
-jmxri.jar (in <CIS_HOME>\lib),
-log4j.jar (in <CIS_HOME>\lib).
Add <CIS_HOME>/properties directory to the classpath.
Update Service configuration

Add the following service parameters to your xservice.
z CIS_PORT_TYPE
z CIS_INSTANCE
The value for these parameters should be same as that in the CIS Adapter and the
generated CIS WSDL.
Example:
<service-params>
<param Name="CIS_PORT_TYPE" Value="Procurement" />
<param Name="CIS_INSTANCE" Value="FP-PO" />
</service-params>
The CIS_PORT_TYPE and CIS_INSTANCE service parameters are required for our
service to be able to connect to CIS.

Configure Security for CIS client

If CIS is configured with security then ABPP client must connect to CIS with the
appropriate username and password.
Using Predefined user name and password.
Username and password can be predefined in ABPP xserver in the section <cis-client-
config> as shown below.
<cis-client-config>
<property Key="Procurement.FP-PO.USER" Value="admin"/>
<property Key="Procurement.FP-PO.PASSWORD" Value="pw"/>
</cis-client-config>
Where 'Procurement' is CIS port type and 'FP-PO' is CIS instance. The port type and
instance should match the ones specified in the CIS binding section of the WSDL.
If CIS is configured with security, this configuration can be used to receive CIS
notifications as well as invoke CIS operations. For receiving CIS notifications this is
the only way to supply authentication information and the following section on user
profile based authentication does not apply.

Using user profile based authentication.
When authentication information is configured in the xserver, the same username and
password will be used to authenticate all users. This may not be suitable if the product
functionality depends on user profile. In such cases the user profile based
authentication can be used.
This mode of providing authentication information works only for invoking CIS
operations and cannot be used to receive CIS notifications.
To ensure user profile based authentication, use 'INITIALIZE_CIS_CONNECTIONS'
and 'CLEAR_CIS_CONNECTIONS' commands.
The syntax of 'INITIALIZE_CIS_CONNECTIONS' is as below:
<INITIALIZE_CIS_CONNECTIONS>
<AUTHORIZATION_CONTEXT>
<USER_ID Value="user name" />
<PASSWORD Value="password" />
<AUTHORIZATION_ID Value="SSO Token"/>
</AUTHORIZATION_CONTEXT>
<PORTTYPES>
<PORTTYPE name="Porttype name" instance="Instance Id" />
…
</PORTTYPES>
</INITIALIZE_CIS_CONNECTIONS>
This command creates a new CIS client and CIS connection for each of the listed port
types and caches them in the studio session.
Here AUTHORIZATION_ID is the SSO Token. Either one of PASSWORD or
AUTHORIZATION_ID is adequate to create a CIS connection. If both are available,
AUTHORIZATION_ID takes precedence over PASSWORD.
For any later invocations to CIS, the cached connection and client would be used.
If SSO is enabled in ABPP, user name and SSO Token are available at runtime from
the context and CIS connections can be created with user specific authentication
information. Therefore, INITIALIZE_CIS_CONNECTIONS is not required.
However, if SSO is not enabled, user specific CIS connections cannot be created at
runtime for lack of authentication information. INITIALIZE_CIS_CONNECTIONS
is required to workaround this problem.
This command should be called from where a handle to the user's password/SSO
token is available after successful login.
In the new user security framework in ABPP, an active user security service can be
specified in the xserver configuration. A user security service has to implement the
following APIs:
z validateLogin
z onValidatedLogin (Optional)
z getUserInfo
z changePasswordForUser

The API signature for these can be found in rule file uiUserSecurity.xml in PGL
service.
If ABPP is not configured to use SSO, 'validateLogin' rule is called with
LOGIN_NAME and PASSWORD when a user attempts to login. If 'validateLogin'
returns success then 'onValidatedLogin' is called with LOGIN_NAME and
PASSWORD.
If ABPP is configured to use SSO and if 'validateLogin' returns success,
'onValidatedLogin' is called with LOGIN_NAME and SSO_TOKEN.
In both the above scenarios, 'onValidatedLogin' rule has the necessary inputs for user
authentication. INITIALIZE_CIS_CONNECTIONS command can be executed from
here.
Example:
<DEFINE_METHOD Name="onValidatedLogin">
<API_DOC>
<INPUT>
<REQUEST Name="onValidatedLogin">
<LOGIN_NAME Value="..." />
<PASSWORD Value="..." Optional="true"/>
<SSO_TOKEN Value="..." Optional="true"/>
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE>
</RESPONSE>
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
<RULE>
<ACTION>
<INITIALIZE_CIS_CONNECTIONS>
<AUTHORIZATION_CONTEXT>
<USER_ID Value="{$thisParam/LOGIN_NAME/@Value}" />
<PASSWORD Value="{$thisParam/PASSWORD/@Value}" />
<AUTHORIZATION_ID Value="{$thisParam/SSO_TOKEN/@Value}"/>
<PORTTYPES>
<PORTTYPE name="Procurement" instance="FP-PO" />
</PORTTYPES>
</INITIALIZE_CIS_CONNECTIONS>
</ACTION>
</RULE>
</DEFINE_METHOD>
The command <CLEAR_CIS_CONNECTIONS/> clears the CIS connections cached
in the user's studio session.
<CLEAR_CIS_CONNECTIONS/> can be in called in the reserved 'onLogout' rule.

Custom Authentication.
If the above discussed options are not suitable for your security needs then you can
create your own class for providing user/password combination for CIS binding. You
need to extend class com.i2.xcore.net.cis.CisSecurity and register new class as shown
below.
<cis-client-config>
<property Key="CIS_SECURITY_CLASS"
Value="com.xxx.yyy.MyCisSecurity"/>
…
</cis-client-config>
You may put ant properties to this class in <cis-client-config> section. When ABPP
requires user/password combination for authentication it uses the following method.
/**
* Calculates security context like username and password.
*
* @param context ABPP context
* @param cisConfig CIS client configuration parameters
* @param cisPortType CIS server port type
* @param cisInstance CIS server instance
* @return security context.
*/

public CisSecurityContext getSecurityContext(OmxContext context, Map cisConfig,

String cisPortType, String cisInstance);
Using CIS binding to invoke operations on the CIS Adapter

Refer to Setup steps to use CIS Binding as prerequisite for this section.
Insert the generated CIS WSDL.

In the studio project, Create a new group (Example: 'Demo') under Web Service Set
and click 'Insert' on the newly created group.
Select "File Based" Loading mechanism.
Navigate to the location of the generated CIS WSDL. In our example, navigate to E:\
temp\ABPP-CIS and select Procurement-BPE.wsdl.

In ABPP, a web service must be activated in order to be able to invoke its operations.
Navigate to the inserted web service, right-click and select "Activate" popup menu
item.
Add workflow with a CIS binding WSDL node

Create a workflow (Example: InvokeCISOperation.xml) having a WSDL node
(Example: InvokeCISOperation) that refers to the imported WSDL (Example:
ProcurementService).

Update server configuration file

Binding Type is the protocol used for web service invocation. The default binding
type to use for web service invocations from ABPP can be configured in the server
configuration file. The default binding type configured in server configuration file can
be overridden at the WSDL node level. Following section gives details on these two
ways of setting the binding protocol.
If SOAP binding is used, ABPP acts as SOAP client to the web service. If CIS binding
is used, ABPP acts as a CIS client making API calls to the CIS adapter.
Setting the default binding in the xserver configuration.
Open the server configuration file and locate the <wsdl-client-config> section.
<wsdl-client-config>
<wsdlLocations>
<wsdlLocation Value=".\CIStoABPP\WSDL\Demo\
ProcurementService.wsdl" Group="Demo" Version="2" />
</wsdlLocations>
</wsdl-client-config>
Add the following binding information to <wsdl-client-config> so that it looks like the
snippet shown below

<wsdl-client-config>
<bindings>
<defaultBinding Name="CIS" />
</bindings>
<wsdlLocations>
<wsdlLocation Value=".\CIStoABPP\WSDL\Demo\
ProcurementService.wsdl" Group="Demo" Version="2" />
</wsdlLocations>
</wsdl-client-config>
Here, defaultBinding is the binding protocol to be used to interact with the imported
web service. This setting applies to all the WSDL nodes in all the workflows.
Setting the binding type in the WSDL node.
The property editor of the WSDL node has a Binding type dropdown. The default
selection in this dropdown is 'DEFAULT'.
If a <defaultBinding/> is configured in the xserver as explained in the previous
section, then choosing 'DEFAULT' in the dropdown sets the binding type to the
protocol configured in the xserver. In the above example the configured protocol is
CIS.
The <defaultBinding/> set in the xserver can be overridden at the WSDL node by
choosing a different binding type than that configured in the xserver. Binding type set
in a WSDL node is applicable only for that particular node.
In ALL cases where the user's binding preference is ambiguous, SOAP will be used
as the default binding.
Example: If <defaultBinding/> is not configured in the xsever, then choosing
'DEFAULT' in the dropdown sets the binding type to 'SOAP'.
Configure WSDL node properties

Click on the WSDL node to configure node properties.
Configure Operation.
Select operation (Here the selected operation is 'twoWayPO') and fill-in the body of
the request in the bottom half of "parameters" window. Top half shows XML schema
for the request body.


Configure Binding Type.
Refer to section “Update server configuration file” on page 152 for details on how to
configure binding type.
With these steps WSDL node is configured to use CIS binding to invoke operations on
the CIS adapter.
Using CIS binding to receive events from the CIS Adapter
Generate ABPP event descriptors

ABPP cannot use CIS events directly from the generated WSDL. These events must
be converted into ABPP events.
The utility CisBpeConvertor is used to create definition of ABPP events
corresponding to CIS events.
Run the following command to generate ABPP artifacts from CIS WSDL.
>set CLASSPATH=%ABPP_HOME%\bre\lib\3plib\jdom.jar;%ABPP_HOME%\
bre\lib\bpe-server.jar
java com.i2.xcore.cis.CisBpeConverter <CIS WSDL-file> <target-
dir> <service-name>
Example:
java com.i2.xcore.cis.CisBpeConverter E:\temp\ABPP-CIS\
Procurement-BPE.wsdl E:\temp\ABPP-CIS
Where,
Procurement -BPE.wsdl is the generated CIS WSDL file.
E:\temp\ABPP-CIS is target directory where ABPP artifacts are to be generated
This utility generates the following files:
E:\temp\ABPP-CIS
|-- properties
| |-- Procurement.xml
|
|-- xservice
|-- procurement
|-- event-descriptors
| |-- ProcurementEvents.xml
|
|-- rules
|-- InitService.xml
ABPP events must belong to some ABPP service, so this utility also generates a
service configuration. CIS port type value will be used as the name of the generated
service if it is not given as part of command line parameters.
In our example, 'Procurement' is the name of the generated service.

Insert Init rule

Insert rule file InitService.xml.
Add the DEFINE_INIT rule from the generated rule file(E:\temp\ABPP-CIS\xservice\

procurement\rules\InitService.xml) to InitService.xml.
<DOCUMENTS>
<DEFINE_INIT>
<RULE>
<ACTION>
<NATIVE_FUNCTION
ClassName="com.i2.xcore.cis.net.CisRunTime" MethodName="init">
<PARAM Var="thisContext" />
</NATIVE_FUNCTION>
</ACTION>
</RULE>
</DEFINE_INIT>
</DOCUMENTS>
Note: There can be only one DEFINE_INIT for a service. If a DEFINE_INIT rule
already exists for your service just add the NATIVE_FUNCTION call shown
above to existing DEFINE_INIT.

Insert event descriptor file

Insert an event descriptor file (Example: DemoEvents.xml).
Edit this file in source mode and copy contents from the event file generated above.
(Example: E:\temp\ABPP-CIS\xservice\procurement\event-descriptors\
ProcurementEvents.xml).
Reload the studio project.

In our example, the event definition file looks like the following.
<event_descriptors>
<event_descriptor Name="notifyPO" Category="Procurement" />
</event_descriptors>
Note that the event names in ABPP are same as that of the notification operation
(output-only operation) in the WSDL and CIS metadata file.
Add event listener

The DEFINE_INIT rule we added previously subscribes to CIS at run-time. Only
those web service notifications that have listeners in ABPP are subscribed to.
Insert another rule file for example DemoRules.xml.
Add the following rule to create a listener for 'notifyPO' event.

<DEFINE_LISTENER Name="notifyPOListener" Descriptor="//

DemoService/notifyPO">
<RULE>
<ACTION>
<PRINTLN Value="++++++ Received web service event
++++++!"></PRINTLN>
<PRINTLN Value="{$thisParam}"></PRINTLN>
</ACTION>
</RULE>
</DEFINE_LISTENER>
Since a listener is defined for 'notifyPO', the INIT rule subscribes to the corresponding
CIS notification. The event listener in ABPP is notified as and when events are raised
in CIS.


Chapter 12
JMS Support
ABPP X-Rules can be executed from an external application using Poster or web
service options. However, both these are synchronous calls. That is, caller waits for
the execution to be completed.
JMS framework provides another powerful alternative to invoke X-Rules. Using JMS
framework, an X-Rule can be executed synchronously or asynchronously. ABPP
Events can be triggered by external applications and can also be published to external
applications.
An Event or an X-Rule that is exposed to the external world through JMS framework
is said to be 'externalized'.
This chapter delves into JMS framework. It includes the following topics.
Topics:
z Xserver configuration to enable JMS
z Defining JMS Connections
z Externalizing Requests, X-Rules and Events
z Invoke ABPP Request or X-Rule through JMS
z Raise ABPP Event through JMS
z SEND_MESSAGE
z Concept of Integration Service
z Additional considerations in a cluster setup
z Advanced Configuration Settings
Xserver configuration to enable JMS

The first step to expose rules and events to JMS is to enable the 'enableJMS' flag in the
xserver configuration. This defines whether JMS framework is enabled for the server
instance.

Chapter 12 JMS Support
Figure 1 Server Configuration
Defining JMS Connections

The next step is to define logical JMS connections. JMS connections can be created in
the studio as explained in the ABPP Studio User Guide.
Figure 2 Queue connection editor

Defining JMS Connections
Above screenshot shows a Queue Connection. A Topic connection is similar with few
different configuration fields as explained in the Studio user guide. For convenience,
configuration fields for both Queue connection and Topic connection are explained
below:
z destination-type indicates whether the logical connection will use queues or a
topic.
z dedicated flag is set to true if the logical JMS connection and the underlying
queues/topic is dedicated to a single receiver(X-Rule or Event).
z jndi-context-factory and jndi-provider-url are required to connect to the JNDI
provider. If JNDI authentication is enabled, provide the jndi-user-name and jndi-
password.
z connection-factory is the administrative resource required to create JMS
connections.
z authenticate-jms-user is set to true if JMS authentication is enabled. If
authentication is enabled, provide jms-user-name and jms-password.
z inbound-queue is the JNDI name of the queue where incoming messages are
received.
z response-type indicates whether response is expected when a rule is invoked
through JMS framework. Following are the valid values
| Ignore - indicates that the caller does not need a response. Request is
processed on receiving the message, but response is not sent to the caller.
| Blocking - indicates that the caller synchronously waits for the response till
response is received or a system time out is reached.
| #seconds - indicates that the caller synchronously waits for a response till the
response is received or #seconds time out is reached.
z outbound-queue is the JNDI name of the queue where outgoing messages are
published.
z error-queue is the JNDI name of the queue where messages that failed to process
are published.
z 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 pings JMS
provider at regular intervals to check availability. This enables JMS framework to
re-establish connections in case of temporary provider unavailability.
z topic-name is the JNDI name of the Topic in which event messages are published
z durable-subscription is set to true if durable subscription is needed for the topic.
Default is false.
z max-subscriber-count is the maximum number of listeners that can be created
dynamically for the inbound queue. Dynamic listeners are created when message
load is high. By default, messages are consumed sequentially by a single listener.
High load results in large number of pending messages in the queue and thus long
response time to process the same. Creating multiple listeners would enable
consuming messages quickly. However, sequence of message consumption is not

guaranteed when dynamic listeners are used. Default value for this property is
zero indicating not to use dynamic listeners.
z message-converter is the name of the message converter class that implements
com.i2.xcore.jms.JMSMessageConverter interface. The methods in this class will
be invoked for inbound and outbound conversion of JMS messages. ABPP can
only handle xml messages. When external system sends message in non-xml
format, same has to be converted to an xml format for use in ABPP. Use message
converter class when message has to be converted from xml to non-xml formats.
Converter can handle only inbound message, only outbound message or both.
z Envelope is the wrapper tag (or root xml tag) for messages sent out of ABPP
application.
Note that the JMS connections defined in the studio are just logical entities and the
actual physical queues, topics and connection factories have to be administratively
created in the JMS provider.
Externalizing Requests, X-Rules and Events

A Request, X-Rule or Event can be externalized using JMS framework. When
externalized, same can be invoked by external application by placing a message on
inbound-queue or topic. Requests and X-Rules are externalized to queue connections
while Events can be externalized to both queue and topic connections.
Two additional attributes, Externalize and JMSConnection, are added to Event, X-
Rule and Request definitions.
Example 1:
<DEFINE_METHOD Name="Bid" Access="Private" Externalize="true"
JMSConnection="ExchangeBids">
<API_DOC>
<INPUT>
<REQUEST Name="Bid">
<InvestorID Value="1" />
<StockCode Value="ABC" />
<Qty Value="10" />
<LimitPrice Value="100" />
</REQUEST>
</INPUT>
</API_DOC>
<RULE>
<ACTION>
<REQUEST Name="Bid" ServiceName="ExchangeCore"
AssignToVar="thisReturn">
<TO_XML SelectList="$thisParam/*" />
</REQUEST>
</ACTION>
</RULE>
</DEFINE_METHOD>

Externalizing Requests, X-Rules and Events
X-Rule must be externalized using Queue connection only. A queue connection

defines the inbound, outbound and error queues for processing messages and returning
response.
Example 2:
<event_descriptor Name="StockTicker" Externalize="true"
JMSConnection="ExchangeStockTicker" Description="Stock Ticker">
<keys />
<EVENT_DOC>
<RAISE_EVENT>
</RAISE_EVENT>
</EVENT_DOC>
</event_descriptor>
Event can be externalized using Queue connection or a topic connection. A queue is
primarily used for point-to-point messaging whereas a topic is used for publish-
subscribe messaging.
Example 3:
<request_descriptor Name="receiveApproveEvent" Access="Public"
Category="Fcst Analysis" DefaultHandler="fcstApprovalErrorHandler"
Externalize="true" JMSConnection=" FcstConnection">
<API_DOC>
<INPUT>
<REQUEST Name="receiveApproveEvent">
<FCST_LINE_ID Value="xxx[Type=string]"/>
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE>
<_RESULT Value="SUCCESS|ERROR">
<ERROR_CODE Value="xxx" Optional="true"/>
</_RESULT>
</RESPONSE>
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
<keys>
</keys>
</request_descriptor>
Similar to X-Rules, Request must be externalized using Queue connection only.

Invoke ABPP Request or X-Rule through JMS

To invoke an externalized Request or X-Rule through JMS the following header
properties should be available in the incoming JMS message.
z Operation_Name: Name of the Request or X-Rule to execute
z Service_Name: Service to which the Request or X-Rule belongs
If the JMS connection is dedicated, then the connection is bound to a single Request or
X-Rule only. In this scenario, the 'Operation_Name' and 'Service_Name' header
properties need not be specified in the incoming message.
When a message is received on the inbound queue, appropriate X-Rule is executed
and the response is published on the outbound queue.
If the incoming message is invalid or the Request or X-Rule could not be executed
successfully, an error document containing the input message and error text is
published to the error queue. These error messages can be examined by system
administrators for corrective action.
Example 1:
Consider the following externalized X-Rule:
<DEFINE_METHOD Name="Bid" Access="Private" Externalize="true"
JMSConnection="ExchangeBids">
<RULE>
<ACTION>
…
</ACTION>
</RULE>
</DEFINE_METHOD>
To invoke this X-Rule, incoming message must have following header properties:
z "Service_Name ="ExchangePortal"
z "Operation_Name ="Bid"
The JMS message body must contain a valid XML as shown below which is passed as
input to the Request or X-Rule.
<i2Document>
<Qty Value="10" />
<LimitPrice Value="99.95" />
</ i2Document >

Raise ABPP Event through JMS
This is similar to invoking the X-Rule internally as below.

<REQUEST Name="Bid" JMSCorrelationID="11e1e67:11399a769bf:-7ffc"
JMSMessageID="ID:EMS-SERVER.1DE8469DD2E113A:1" JMSTimestamp="1184764072229"
JMSRedelivered="false" JMSType="null" JMSExpiration="0" JMSPriority="4"
JMSDeliveryMode="2">
<Qty Value="10" />
<LimitPrice Value="99.95" />
</REQUEST>
Note: Note that the root tag Note:

- The root tag <i2Document> is not passed to the X-Rule.
- The predefined JMS header properties of the received message are passed to
the X-Rule as attributes on the REQUEST tag.
In our example, the X-Rule returns the following response:

<RESPONSE>
<ID Value="BID007"/>
</RESPONSE>
This response is wrapped with the envelope tag (defined in the JMS Connection
configuration) and the following message is placed on the outbound-queue:
<i2Document>
<ID Value="BID007"/>
</ i2Document >
Raise ABPP Event through JMS

To raise an event through JMS the following header property should be available in
the incoming JMS message.
z Event_Name: Name of the Event.
If the JMS connection is dedicated, then the connection is bound to a single Event
only. In this scenario, the 'Event_Name' header property need not be specified in the
incoming message.
Note that unlike X-Rule invocation, Service_Name property is not required in the
JMS message header to trigger events. This is because, events with the same name
across multiple services is considered to be the same Event by the JMS framework.
This enables services potentially on different VMs, to share and collaborate on a
single Event. However, care must be taken to ensure that all these events have same
specifications and represent the same business event. This design time validation is a
pre-requisite to externalizing an ABPP event.
When a message is received on the inbound-queue or topic all listeners for the event
are notified. This enables external applications to trigger an ABPP Event.
Also when the same event is raised within ABPP, the event document is published on
the outbound-queue or topic of the associated JMS connection. This enables external
consumers to receive the event published by ABPP.
Example 1:

Consider the following externalized Event:

<event_descriptor Name="StockTicker" Externalize="true"
JMSConnection="ExchangeStockTicker" Description="Stock Ticker">
<keys />
<EVENT_DOC>
<RAISE_EVENT>
</RAISE_EVENT>
</EVENT_DOC>
</event_descriptor>
To trigger this Event, incoming message must have following header property:
z Event_Name ="StockTicker"
The JMS message body must contain a valid XML as shown below. This xml is
passed as the Event document.
<i2Document>
</ i2Document >
This is similar to triggering the Event internally as below:
<RAISE_EVENT>
</RAISE_EVENT>
Note that the root tag <i2Document> is not part of the Event document.
SEND_MESSAGE
Description:
This component is used to post a message on the outbound-queue or topic of a logical
JMS connection and optionally fetch the response message from the inbound-queue or
topic.
JMS connection definition has a response-type property. Following are the valid
values for response-type:
a. Ignore - If the response-type is ignore it implies that the caller does not need a
response. Request is processed on receiving the message, but response is not
sent to the caller.
b. Blocking - If the response-type is blocking it indicates that the caller
synchronously waits for the response till response is received or a system time
out is reached. The default system time out value is 15 seconds.
c. #seconds - If response-type is number of seconds it implies that the caller
synchronously waits for a response till the response is received or #seconds
time out is reached.

SEND_MESSAGE
Depending on the response-type configured in the JMS connection definition,

SEND_MESSAGE command can be used to synchronously fetch the response or
ignore the same.
Syntax:
Attributes:
<SEND_MESSAGE JMSConnection="connectionName">
<JMS_HEADER_PROPERTIES>
<Property Name Value="xyz"
Type="String|Boolean|Short|Integer|Long|Float|Double[Default =String]"/>
</JMS_HEADER_PROPERTIES>
<!- - xml message body - >
<SEND_MESSAGE/>
JMSConnection (Required): The name of the JMS Connection to be used for sending
the message.
Child Tags:
JMS_HEADER_PROPERTIES (Optional): If property name and value are set within
this tag, they will be added as header properties to the JMS message.
Example:
<SEND_MESSAGE JMSConnection="TestConnection"
AssignToVar="queryResponse">
<Operation_Name Value="GetPOAmount" Type="String"/>
<Service_Name Value="ProcurementService" Type="String"/>
<JMSCorrelationID Value="1234567"/>
<PO>
<POId Value="PO123" />
<Requestor Value="abc" />
</PO>
</SEND_MESSAGE>
This command publishes the following message on the outbound-queue:

<i2Document>
<PO>
<POId Value="PO123" />
<Requestor Value="abc" />
</PO>
</ i2Document>
Note: The response xml is wrapped within 'i2Document' tags. 'i2Document' is the
default envelope for JMS connections. That is, if no envelope is defined, the
xml placed in the outbound-queue or topic will be wrapped within
'i2Document' tag.
The correlation Id, which should be set on the outbound message, can also be
specified in the JMS_HEADER_PROPERTIES section as in the above

example. This is optional and ABPP will auto generate a correlation id if not
specified.
The published message contains below user defined header roperties:

| Operation_Name="GetPOAmount "
| Service_Name=="ProcurementService"
Output Syntax:
The contents of the variable, queryResponse will be:
<RESPONSE Status="Success" JMSCorrelationID="1234567" >
<PO>
<POAmount Value="10000"/>
<Currency Value="USD"/>
</PO>
</RESPONSE>
If there is no response to receive before the timeout elapses or if the response-type is
ignore, the queryResponse variable would have the following contents:
<RESPONSE Status="Success" JMSCorrelationID="1234567" />
</RESPONSES>
Note: The correlation Id with which the message was published on the outbound
queue is returned as an attribute on the RESPONSE tag.
RECEIVE_MESSAGE
This component is used to receive a message from the inbound-queue or topic of a
logical JMS connection and optionally fetch the message properties of the message.
Syntax:
<RECEIVE_MESSAGE JMSConnection="TestConnection"
Timeout="100000" AssignToVar ="message">
<JMS_MSG_FILTER Value="xyz='abc'"/>
<Property
Type="String|Boolean|Short|Integer|Long|Float|Double[Default
=String]"/>
</RECEIVE_MESSAGE>
Attributes:
JMSConnection (Required): The name of the JMS Connection to be used for sending
the message.
Timeout (Optional): Number of seconds to wait for the message.
RECEIVE_MESSAGE call returns when a message is received or the timeout is
reached. If timeout is not specified the default system timeout of 15 seconds will be
assumed.
Child Tags:

RECEIVE_MESSAGE
JMS_HEADER_PROPERTIES (Optional): If property name is set within this tag, the

value of this property (if available in the received message) would be retrieved from
JMS message and returned as part of the command response.
The type of the property should be specified as an attribute as shown in the syntax.
Type need not be set for the predefined JMS header properties like JMSCorrelationID.
JMS_MSG_FILTER (Optional): If a message filter is specified, this expression would
be used to filter the JMS messages and receive only messages with matching message
properties.
Example:
<RECEIVE_MESSAGE JMSConnection="TestConnection"
AssignToVar="queryResponse" "Timeout="100000">
<JMS_MSG_FILTER Value="Operation_Name='getOrderStatus' AND
Order_Type='PO'"/>
<Operation_Name Type="String"/>
<Service_Name Type="String"/>
<Order_Type Type="String"/>
<JMSCorrelationID/>
<JMSRedelivered/>
</RECEIVE_MESSAGE>
This command receives the following message from the inbound-queue:
Output Syntax:
The contents of the variable, queryResponse will be:
<Operation_Name="getOrderStatus"/>
<Service_Name="ORDER_ADMIN"/>
<Order_Type Value="PO"/>
<JMSCorrelationID Value=" 10f11b8:10f194a18e7"/>
<JMSRedelivered Value="false"/>
<Activity_Order>
<Id Value="PO123"/>
<Status Value="ACCEPTED"/>
</Activity_Order>
</RESPONSE>
</RESPONSES>
Note: Besides the actual message, the queryResponse variable contains the values of
the requested JMS message properties within the
JMS_HEADER_PROPERTIES tag.
The message properties match the JMS_MSG_FILTER criteria of the

RECEIVE_MESSAGE command. i.e In the incoming message,
Operation_Name is 'getOrderStatus' and 'Order_Type' is 'PO' as specified in
the message filter.

If the incoming message did not satisfy the message filter criteria or if there is no
message to receive before the timeout elapses, the queryResponse variable would
have the following contents:
<RESPONSE Status="Success"/>
</RESPONSES>
Concept of Integration Service

Requests, X-Rules or Events can be externalized using JMS framework. While any
rule or event in any service can be exposed using JMS, it is recommended that an
integration service be defined which is solely responsible for integration layer.
Integration service should have wrapper rules and events, that are externalized, which
may in turn call one or more rules. Integration service may be defined by the product
or during implementation.
Following are the advantages of using an Integration Service:
z Core product services are insulated from direct external access.
z Integration service may perform additional validations before invoking the core
product rules.
z Externalization may be turned on/off by changing only the integration service.
z JMS Connections to which rules or events are externalized can be customized by
changing the Integration Service only. This limits customizations to a single
service as opposed to many services.

Additional considerations in a cluster setup
Additional considerations in a cluster setup
Setting jmsAppCluster Flag

When a JMS enabled application is deployed in a cluster setup, the xserver flag
'jmsAppCluster' should be set to 'true'.
Figure: Setting JMS Application cluster flag to true in the xserver

An ABPP Event may be externalized using a JMS topic. Broadcast flag on the event
descriptor is set to 'false' by default. In this case, message is published to only one
node in the cluster.
If Broadcast flag on the event descriptor is set to 'true', all nodes in the cluster will
receive the message published on the related topic.
Note: Event should be associated with a queue connection only when Broadcast is
not required.
Setting Client Id
This section is applicable if:
1. Durable topic subscriptions are used
2. Application is co-deployed with application server and
3. Application cluster consists of multiple instances on the same host
Client Id parameter is required for durable topic subscriptions. If above scenario, set a
unique client id for each instance of the server using system property i2.jms.clientId.

Example:
For an instance of the application deployed in weblogic, meeting all the above
criteria,the unique client id could be configured as follows:
%JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS%
-Di2.jms.clientId=xserver1
-Dweblogic.Name=%SERVER_NAME%
-Dweblogic.ProductionModeEnabled=%PRODUCTION_MODE%
-Djava.security.policy="%WL_HOME%\server\lib\weblogic.policy"
weblogic.Server
Advanced Configuration Settings

Following section lists some of the advanced configuration settings available in the
JMS framework. When these parameters are not defined, system assumes default
configurations. Default configuration is recommended for all implementations. The
parameters explained below should be changed only after careful thought on design
and performance implications.
JMSHeartbeatInterval
This parameter is relevant only if heartbeat is enabled.
A heartbeat message is published to the heartbeat Queue/Topic after every
JMSHeartbeatInterval.
Default is 30 seconds. This value should be a multiple of 10.
Example
If JMSHeartbeatInterval is set to 60 in the xserver configuration, a heatbeat message
is published to the heartbeat Queue/Topic every 60 seconds.
JMSRetryCountBeforeReconnect
This parameter is relevant only if heartbeat is enabled.
JMSRetryCountBeforeReconnect is the number of retries that will be attempted after
a heartbeat failure before the existing JMS connections are closed and reconnected to
the JMS provider. Default is 2 retries.
Example
If JMSRetryCountBeforeReconnect is set to 5 in the xserver configuration, ABPP
will reconnect to the provider only if 5 successive heartbeat messages could not be
published successfully.
The following parameters are relevant only if dynamic subscribers are enabled for
one or more Queue connections.
JMSMessageConverter
JMSMessageConverter is the name of the message converter class that implements
com.i2.xcore.jms.JMSMessageConverter interface. The methods in this class will be

invoked for inbound and outbound conversion of JMS messages. ABPP can only
handle xml messages. When external system sends message in non-xml format, same
has to be converted to an xml format for use in ABPP. Converter can handle only
inbound message, only outbound message or both. Message converter can be
configured for individual JMS connections in the connection definition. If the
application uses a single message converter class for all connections, it can be
configured globally using this xserver parameter. If a message converter is specified in
the connection configuration, same will override the converter specified in the
xserver.
JMSQueueBrowseInterval
This parameter is relevant only if dynamic subscribers are enabled for one or more
Queue connections.
This is the interval at which ABPP will attempt to increase or descrease number of
subscribers based on number of pending messages in the queue.
This value should be a multiple of 10.
Default is 30 seconds.
Example
If JMSQueueBrowseInterval is set to 60 seconds in the xserver configuration, ABPP
attempts to purge existing subscribers and create new subscribers after every 60
seconds.
JMSMaxPendingMsgCount
Queue connections.
This is the minimum number of messages that must be pending in the Inbound queue
to trigger creation of new dynamic subscribers.
Default is 5 messages.
Example
If JMSMaxPendingMsgCount is set to 10 in the xserver configuration, then a
minimum of 10 messages must be present in the Inbound queue before new dynamic
subscribers can be created.
JMSMaxDynamicListenersPerAPI
Queue connections.
During system startup, one listener is created for every externalized rule or event.
Dynamic subscribers can be created for any rule or event associated with the
connection that specifies max-subcriber-count greater than zero. However, some
implementation might want to restrict maximum parallel processing of same type
(rule or event). In such case, this parameter can be used.

JMSMaxDynamicListenersPerAPI is the maximum number of dynamic subscribers

that could be created per rule/event/request externalized on a JMS connection.
Default value is equal to the number of dynamic subscribers defined for the JMS
connection.
Example
If max-subscriber-count is set to 10 for a JMS connection and
JMSMaxDynamicListenersPerAPI is set to 5 in the xserver configuration then a
maximum of 5 dynamic subscribers will be created for every rule/event/request
externalized on the connection provided the total dynamic subscriber count is less
than 10.
JMSMinDynamicListenersPerAPI
Queue connections.
This is the minimum number of dynamic subscribers that should remain alive after
creation per rule/event/request externalized on a JMS connection even when there are
no pending messages Note that there will be no dynamic listeners at start. Dynamic
listeners are created when there are pending messages in the queue as described
earlier.
Default value is 0.
Example
If JMSMinDynamicListenersPerAPI is set to 2 in the xserver configuration then a
minimum of 2 dynamic subscribers will be retained for every rule/event/request
externalized on the connection.
JMSMaxListenerIdleTime
Queue connections.
A dynamic listener will be purged during a purge cycle if it is idle for more than
JMSMaxListenerIdleTime. However a minimum number of dynamic listeners as
defined by JMSMinDynamicListenersPerAPI will be retained even if the listeners are
idle.
Default is 5 minutes.
Example
If JMSMaxListenerIdleTime, is set to 60 in the xserver configuration, then a dynamic
listener will be purged during a purge cycle if it has been idle for more than 60
seconds.

JMSDynamicListenerSurvivalRatio
Queue connections.
JMSDynamicListenerSurvivalRatio is the ratio of dynamic listeners that will survive a
purge cycle. This helps in gradual reduction of listeners, there by eliminating spikes in
creation or destruction of listeners. This value should be a fraction between 0 and 1.
Default is 0.5
Example
If JMSDynamicListenerSurvivalRatio, is set to 0.25 in the xserver configuration, then
only one fourth of the dynamic listeners will be alive after every purge cycle. If the
dynamic listener count is 16, 12 listeners are purged in cycle 1 and 3 listeners are
purged in cycle 2.
The above parameters can be set in the xserver configuration as follows:
<service-params>
<param Name="activeNavigationService" Value="" />
<param Name="maxRows" Value="10" />
<param Name="activeUserSecurityService" Value="" />
<param Name="JMSHeartbeatInterval" Value="20" />
<param Name="JMSQueueBrowseInterval" Value="20" />
<param Name="JMSDynamicListenerSurvivalRatio" Value="0.2" />
<param Name="JMSMaxDynamicListenersPerAPI" Value="6" />
<param Name="JMSMinDynamicListenersPerAPI" Value="2" />
<param Name="JMSMessageConverter" Value="GlobalMsgConverter" />
<param Name="JMSMaxPendingMsgCount" Value="7" />
<param Name="JMSMaxListenerIdleTime" Value="60" />
<param Name="JMSRetryCountBeforeReconnect " Value="5" />
</service-params>


Chapter 13
Data Service
Data Service - Basic Concepts

This section provides an overview of some basic concepts associated with data
services. The pictorial below shows an architectural view of a Data Service.

Chapter 13 Data Service
Data Services are services that are enabled with capabilities for data consolidation,
data validation, data management, data access and data integration. These kinds of
services lend themselves well for solving problems related to Master Data
Management, Data Staging for running the Planning Engines and creating Operational
Data Stores which drive analytic, planning and reporting engines. As illustrated above
in the picture they have an associated Input Staging, Master Repository and an Output
Staging area respectively for enabling batch inbound integration and batch outbound
integration.
As also shown above in the figure, data services enable data integration into the
master repository via various channels and technologies using ABPP core services.
This provides the ability to enable both real time and batch integrations into the master
repository.
In cases where the data from multiple source systems needs to be consolidated and
cleansed as a whole before moving it to the master, it is staged in Input Staging where
it can be validated and cleansed in batch mode. From the input staging the data is
moved to the master via the application layer using the E2E workflow which ensures
that the centralized process, validation and business rules are applied to the data. Data
services provide services to consolidate data from various source systems in an input
staging area. This is to enable scenarios where the data services acts as system of
reference for this data. To illustrate this further in i2 SCM deployments - some master
data is owned by legacy systems - e.g. the Produced Items, the Producing and
Distributing Locations of those items could be owned by an ERP system. The
Resources and their raw capacities could be owned by another MRP system. This data
needs to be passed to the i2 Data Service and it will house it as a system of reference
to build more data on top of it and pass it on to the i2 Planning engines. This data will
be staged in the input staging area of the i2 Platform Data Service.
The data service can be the system of record for other data that depends on this
reference data. This is quite often the case in deployments where i2 Planning engines
get lot of data from backend ERP systems but may also need some other data that
needs to be managed and maintained in i2 solution. This is enabled by creating data
services which can house the data that comes from back-end systems and create/
manage/provide access to other data which is authored by workflows in the data
service.
Service Layering in Data Services

The Services that are part of any Data Service Solution are illustrated below in the
Service Layer Diagram below. The diagram shows the various core services that are
part of the ABPP core layer and the Domain Services layer. The layers represent the

layering in terms of a higher level service utilizing the services of lower level services.
This is illustrated in the figure below.
The above pictorial demonstrates the various core services that are provided as a part
of ABPP and which are utilized by the Data Services to enable various data
capabilities as described previously. The domain data services will have the data
models, business logic and processes associated with data management related to
domain data. The core services of persistence, presenting, raising messages, uploading
and loading and data security are provided by the ABPP core services.
Described below are the core ABPP services and how they play into providing the
data service capabilities to the platform.
z META: This service provides the metadata services to the run-time by servicing
the document model and the facets associated with the data services in the
solution. This capability is used by the run-time command handlers to drive the
appropriate behavior. This service also provides the Business Rules capability to
the ABPP based solution. Business Rules can be defined to design batch
validations which are executed as SQL.
z PGL: This service provides core UI capabilities that are needed by any ABPP
based UI e.g. navigation, favorites, delegation to user security authentication/
authorization, generic audit trail and workflow monitoring UI capabilities.
z MESSAGING: This service provides messaging capabilities to data services
wherein messaging events can be raised which cause messages to be sent to the UI
as alerts or to other users as emails etc.

z DATAUPLOAD: This service provides asynchronous data file upload capabilities

to the platform. These files can be of various formats - e.g. csv, xml, xls or
delimited text files.
z TASKSCHEDULER: This service provides task scheduling capabilities to the
platform where tasks like batch files, sql procedures, data load workflows etc can
be called in sequence or based on scheduled times.
z E2E: This service provides processes for data loading, data validation, data error
management and net change detection and application routing of data capabilities
on data that is loaded in batch mode into the input staging area.
z USER_SECURITY: This service provides the user management and the
associated roles based access along with data level authorization to the ABPP data
services based solution.
Domain Services consist of the services that define the models, rules, workflows,
validations, UI etc to manage data that is relevant to the solution. In a data service
based solution the corresponding input staging, net-change, master and output staging
services are created by the ABPP infrastructure when you create a data service. The
input staging represents the staging area where the batch data from multiple sources is
consolidated, validated and cleansed. The net change area stages the data that
represents the incremental data from a data load perspective. The Master Service
serves the master repository where the clean data resides and where more data
enrichment can happen to be served up to the consumers. The output staging area
represents a snapshot of the master for data that is ready to be published.
The pictorial below demonstrates for a particular entity how the batch data flows
through and the key tables involved in the E2E Data Load Workflow. More details on
the data flow process can be found in the ABPP Manufacturing Admin guide.
Action X-Rule Components specific to Data Services

In earlier sections of the Programmer's Reference Guide we had discussed the Action
X-Rule components that are used to add, update and delete data into the database. The
data service extends some of those constructs so as to enforce default data
authorization. The Action X-Rule components that are used by the data service are
explained in below.

MDM COMMANDS
GET_TABLE
GET_TABLES
GET_LINKS
GET_FOLDERS
GET_DOC_PROPERTIES
ADD_DOC_SMART
GET_DOC_SMART
MODIFY_DOC_SMART
ADD_FORM
UPDATE_FORM
DELETE_FORM
GET_FORMS
GET_FORM_DATA
UPDATE_FORM_DATA
GET_DOCUMENT_NAME
REMOVE_DOC_LOGICAL
GET_VALID_VALUES
MODIFY_DOC_SET_NULL
GET_DOC_WITH_NULL
DO_PERSIST
ADD_DOCUMENT
GET_DOCUMENT
REMOVE_DOCUMENT
MODIFY_DOCUMENT
GET_SCENARIO_ID
SET_SCENARIO_ID
GET_SUPPORTED_DATA_TYPES

GET_TABLE.
Description
This component returns the Meta data for the queried document.
The Metadata included the facet information and the document properties.
If the document name ends with '_AT', then AuditTrail MetaData would be returned
else Regular Table Meta Table would be returned.
Syntax
<GET_TABLE AssignToVar="MyVariableName [Optional=true]">
<TABLE_NAME Value="documentName"/>
</GET_TABLE>
Attributes:
z AssignToVar (Optional): Variable to which the response is assigned.
Property:
z TABLE_NAME (Required): Name of the X-Document for which MetaData is to
be retrieved.
Example:
<GET_TABLE AssignToVar="MyVariableName">
<TABLE_NAME Value="CalendarMaster"/>
</GET_TABLE>

Output Syntax
<RESPONSES>
<RESPONSE Status="Success" DbgCmd_="GET_TABLE">
<DOCUMENT Name="CalendarMaster" TableName="MST_CALENDARMASTER">
<PROPERTY Name="SCENARIO_ID" Type="int" PrimaryKey="yes"
DefaultValue="0" ColumnName="SCENARIO_ID" Refers="EnterpriseMaster"
RefersServiceName="BCM_MASTER" ToProperty="SCENARIO_ID"
DisplayName"SCENARIO_ID">
<PRESENTATION Name="SCENARIO_ID">
<EDITABLE Value="no"/>
<HIDDEN Value="yes"/>
<DISPLAY_NAME Value="SCENARIO_ID"/>
<SORTABLE Value="yes"/>
<NO_WRAP Value="yes"/>
<SEARCHABLE Value="yes"/>
<I18NIZE Value="no"/>
</PRESENTATION>
</PROPERTY>
<PROPERTY Name="audit_key" Type="int" ColumnName="AUDIT_KEY"
DisplayName="audit_key">
<PRESENTATION Name="audit_key">
<NO_WRAP Value="no"/>
<DISPLAY_NAME Value="audit_key"/>
<SEQUENCE Value="0"/>
<EDITABLE Value="yes"/>
<HIDDEN Value="no"/>
<SORTABLE Value="yes"/>
<SEARCHABLE Value="yes"/>
<I18NIZE Value="no"/>
</PRESENTATION>
</PROPERTY>
<PROPERTY>
….
</PROPERTY>
<PROPERTY>
</PROPERTY>
</DOCUMENT>
</RESPONSE

GET_TABLES.
Description:
This component returns a list of all the documents and their Meta Data, for a service.
If audit trail exists then that is also added to the response.
Syntax:
<GET_TABLES AssignToVar="MyVariableName [Optional=true]"/>
Attributes:
Example:
<GET_TABLES AssignToVar="response"/>
Output Syntax
<RESPONSE Status="Success" DbgCmd_="GET_TABLES">
<DOCUMENTS>
<DOCUMENT Name="SalesAppropriation_NC" TableName="SALESAPPR_NC"
<PROPERTY Name="SCENARIO_ID" Type="int" DefaultValue="0"
ColumnName="SCENARIO_ID" DisplayName="SCENARIO_ID">
<PRESENTATION>
<DISPLAY_NAME Value="SCENARIO_ID"/>
<SEQUENCE Value="0"/>
…………………….
</PRESENTATION>
</PROPERTY>
<PROPERTY Name="APPRSALESLEVEL" Type="string" MaxLength="40"
Required="yes" ColumnName="APPRSALESLEVEL"
DisplayName="APPRSALESLEVEL">
…..
</PROPERTY>
………..
<DOCUMENT>
……
</DOCUMENT>
</DOCUMENTS>
</RESPONSE>

GET_LINKS.
Description:
This component returns all the documents linked to the queried document.
The result contains the documents linked along with the mapped properties.
Syntax:
<GET_LINKS OnlyDownward="true"[Optional=”true”] AssignToVar="
MyVariableName [Optional=true]">
<TABLE_NAME Value="documentName"/>
</GET_LINKS>
Attributes:
z OnlyDownward: If this attribute is set to 'true' then only the child documents are
retrieved.
Property:
z TABLE_NAME (Required): The Name of the X-Document whose linked
documents are to be retrieved.
Example:
<GET_LINKS OnlyDownward="true" AssignToVar=”response”>
<TABLE_NAME Value="ItemSiteMaster"/>
</GET_LINKS>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_LINKS">
<DOCUMENTLINK Name="ItemBOMRouting">
<MAP_PROPERTY To="SK_ITEMSITEMASTER1" From="SK_ITEMSITEMASTER"/>
<MAP_PROPERTY To="ITEM" From="ITEM"/>
<MAP_PROPERTY To="SITEID" From="SITEID"/>
<MAP_PROPERTY To="SCENARIO_ID" From="SCENARIO_ID"/>
</DOCUMENTLINK>
<DOCUMENTLINK Name="SalesProductItemSiteMapping">
…
</DOCUMENTLINK>
………….
</RESPONSE>

GET_FOLDERS.
Description:
This component returns the list of document along with their displayName, for a
service.
Syntax:
<GET_FOLDERS AssignToVar="MyVariableName [Optional=true]"
IsErrorDocRequired=”true” >
<FOLDER_TREE_NAME Value="documentName"/>
<ALL_FOLDERS_REQ Value=”true”/>
</GET_FOLDERS>
Attributes:
z IsErrorDocRequired (Optional): True if error documents are also needed. Default
is False.
Property:
z FOLDER_TREE_NAME: Folder name from which the document list will be
retrieved.
z ALL_FOLDERS_REQ (Optional): True if the structure of the folders needs to be
same as it is defined during data modeling. False if only leaf level folder is
needed. Default is false.
Example:
<GET_FOLDERS AssignToVar=”response”>
<FOLDER_TREE_NAME Value="ods"/>
<ALL_FOLDERS_REQ Value=”true”/>
</GET_FOLDERS>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_FOLDERS">
<ALL_FOLDERS>
<FOLDER Name="models">
<DOCUMENTS>
<DOCUMENT Name="ASNDelivery" DisplayName="ASNDelivery"/>
<DOCUMENT Name="ASNDelivery_NC" DisplayName="ASNDelivery_NC"/>
……..
</DOCUMENTS>
</FOLDER>
</ALL_FOLDERS>

GET_ALL_DOC_NAMES.
Description:
This component returns Documents details for a given Service, limited to its
LogicalName, PhysicalName and Audit Trail flag.
Syntax:
<GET_ALL_DOC_NAMES AssignToVar="MyVariableName [Optional=true]"/>
Attributes:
Example:
z <GET_ALL_DOC_NAMES AssignToVar="response"/>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_ALL_DOC_NAMES">
<DOCUMENTS>
<DOCUMENT Name="TransLocationSchedule"
TableName="MST_TRANSLOCSCHEDULE"/>
<DOCUMENT Name="ApprovedSupplierPriceBreak"
TableName="MST_APPRSUPPRICEBRK"/>
<DOCUMENT Name="BucketCalendar_NC" TableName="BUCKETCALENDAR_NC"/>
… </DOCUMENTS>
</RESPONSE

GET_DOC_PROPERTIES.
Description:
This component returns all Document Properties for a given document along with data
type of attribute.
Syntax:
<GET_DOC_PROPERTIES TableName="myTableName"
AssignToVar="MyVariableName [Optional=true]"/>
Attributes:
z TableName: Name of the document whose properties are to be retrieved.
Example:
<GET_DOC_PROPERTIES TableName=" Item" AssignToVar="response"/>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_DOC_PROPERTIES">
<DOCUMENT Name="ItemMaster" TableName="MST_ITEMMASTER">
<PROPERTY Name="STORAGECLASS" ColumnName="STORAGECLASS" Type="string"/>
<PROPERTY Name="CONDEMNCOST" ColumnName="CONDEMNCOST" Type="float"/>
</DOCUMENT>
</RESPONSE>

ADD_DOC_SMART.
Description:
This component is a wrapper around the ADD_DOCUMENT component.
Please refer to the ADD_DOCUMENT component for more details.
Apart from creating the x-document instances in the system with the properties
specified as input ,it adds extra property
z 'SYS_ENT_STATE ' and its value is set as 'ACTIVE".
z CREATION_DATE
z LAST_MODIFIED_DATE
This component is also enabled for authorization and it check the authorization
context and stamps the authorization context in authorized column. This will also
work on the tables where there are no SYS_* columns
Syntax:
Without Authorization Context:
<ADD_DOC_SMART Name="documentName" AssignToVar="MyVariableName
[Optional=true]" Synchronous="true|false [default=true]"
CacheHint="0|1|2 [default=0]">
<ITEM Value=""/>
<ENTERPRISE Value=""/>
</ADD_DOC_SMART>
With Authorization Context.

<REQUESTS>
<ADD_DOC_SMART Name="documentName" AssignToVar="MyVariableName
[Optional=true]" Synchronous="true|false [default=true]"
CacheHint="0|1|2 [default=0]">
<ITEM Value=””/>
<ENTERPRISE Value=””/>
</ADD_DOC_SMART>
<REQUEST_HEADER>
<AUTHORIZATION_CONTEXT Enabled="true">
<DOCELEMENT Name="AuthDocName">
<AuthID Value=" "/>
</DOCELEMENT>
</REQUEST_HEADER>
</REQUESTS>
Attributes:
z Name (Required): Name of the X-Document for which document instance has to
be added.
z AssignToVar (Optional): For storing the response of ADD_DOC_SMART.
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 Synchronous (Optional): true|false. If false, the component is executed
synchronously.
Example 1:

<ADD_DOC_SMART Name="ItemMaster" AssignToVar="response">

<ITEM Value="Item1"/>
<ENTERPRISE Value="ENTERPRISE"/>
</ADD_DOC_SMART>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="ADD_DOC_SMART"
DbgNameAttr_="ItemMaster">
<SCENARIO_ID Value="0"/>
</RESPONSE>
Example 2:
<REQUESTS>
<ADD_DOC_SMART Name="ItemMaster" AssignToVar="response">
</ADD_DOC_SMART>
<REQUEST_HEADER>
<DOCELEMENT Name="AuthorizationMaster">
<AuthID Value="Auth1"/>
</DOCELEMENT>
</REQUEST_HEADER>
</REQUESTS>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="ADD_DOC_SMART"
</RESPONSE>

GET_DOC_SMART.
Description:
This component is a wrapper around the GET_DOCUMENT component.
It is scenario enabled and it fetches only those document instances whose
ENTITY_STATE is 'ACTIVE'. This command has logic to apply the authorization
while selecting the records. This will also work on the tables where there is no
SYS_ENT_STATE column.
Please refer to the GET_DOCUMENT component for more details.
Syntax:
<GET_DOC_SMART Name="documentName"
RowName="rowTagName[Optional=true"]
AssignToVar="variableName[Optional=true]"
StartAtRow="number[optional=true, default=0]"
MaxRows="number[optional=true]"
ReturnRowCount="true|false[default=Optional]"
OraHint="xxx[Optional=true]"
Distinct="true|false[Optional=true]">
{A Simple or Compound query condition [Optional=true]}
<SELECT>
<propertyN Repeatable="true"/>
</SELECT>
</GET_DOC_SMART>
With Authorization Context.
<REQUESTS>
<GET_DOC_SMART Name="documentName"
ReturnRowCount="true|false[default=false]"
<SELECT>
</SELECT>
</GET_DOC_SMART>
<REQUEST_HEADER>
<DOCELEMENT Name="AuthDocName">
<AuthID Value=" "/>
</DOCELEMENT>
</REQUEST_HEADER>
</REQUESTS>
Attributes:
z Name (Required): The name of the X-Document to be retrieved
z 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.

z ServiceName (Optional): Service from which the document is retrieved. If not

specified, then owner service is taken as default.
z StartAtRow (Optional): Starting row number from which records should be
retrieved
z 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.
z ReturnRowCount (Optional): Same as GET_DOCUMENT.
z OraHint (Optional): Same as GET_DOCUMENT.
Example 1:
<GET_DOC_SMART Name="Item" AssignToVar="response">
<itemID Value="LEG_ANGULAR"/>
</GET_DOC_SMART>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_DOCUMENT" DbgNameAttr_="Item">
<Item ExistingDocument="yes">
<ENTITY_STATE Value="ACTIVE"/>
………….
</RESPONSE>
Example 2:
<REQUESTS>
<GET_DOC_SMART Name="Item" AssignToVar="response">
</GET_DOC_SMART>
<REQUEST_HEADER>
<DOCELEMENT Name="AuthorizationMaster">
<AuthID Value="AUTH1"/>
</DOCELEMENT>
</REQUEST_HEADER>
</REQUESTS>
Output Syntax:
………….
</RESPONSE>

MODIFY_DOC_SMART.
Description:
This component is a wrapper around the MODIFY_DOCUMENT component.
It is scenario enabled and it appends ENTITY_STATE as 'ACTIVE' to the query
condition .And in the properties to be updated it adds an extra property
LAST_MODIFIED_DATE and sets it as the current date.
Syntax:
<MODIFY_DOC_SMART Name="" AssignToVar="MyVariableName [Optional=true]"
Synchronous="true|false [default=true]" CacheHint="0|1|2 [default=0]">
<DOCUMENT_CONTEXT>
<ID Value=""/>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<Property1 Value="newValue"/>
<Property2 Value="newValue"/>
</UPDATE_PROPERTIES>
</MODIFY_DOC_SMART>
Attributes:
be modified.
z AssignToVar (Optional): For storing the response of MODIFY_DOC_SMART.
asynchronously
Property:
Same as MODIFY DOCUMENT -
Example:
<MODIFY_DOC_SMART Name="Item" AssignToVar="response">
<DOCUMENT_CONTEXT>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<name Value="LG"/>
</MODIFY_DOC_SMART>

This tags gets converted to MODIFY_DOCUMENT as shown below:

<MODIFY_DOCUMENT Name="Item">
<DOCUMENT_CONTEXT>
<OR>
<ENTITY_STATE Value="DELETED" MatchBy="NOT_EQUAL"/>
<ENTITY_STATE/>
</OR>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<name Value="LG"/>
<LAST_MODIFIED_DATE Value="03/29/2007 17:29:58:998"/>
</MODIFY_DOCUMENT>
Output Syntax:
<RESPONSE RowCount="1" Status="Success" DbgCmd_="MODIFY_DOCUMENT"
DbgNameAttr_="Item"/>

ADD_FORM.
Description:
This component is used for adding form specification into database and also it
refreshes memory with new Form object
Syntax:
<ADD_FORM AssignToVar="MyVariableName [Optional=true]">
<QUERY_FORM Name=" " Service=" " Type=" ">
< ID Value=””/>
< SEARCH_PROPERTIES>
……………
</ SEARCH_PROPERTIES>
< RESULT_PROPERTIES>
…………..
</RESULT_PROPERTIES>
</ADD_FORM>
Attributes:
Property:
z <QUERY_FORM Name=" " Service=" " Type=" ">
Attribute:
| Name (Required): Name of the Queryform
| Service : Name of the service
| Type : Simple/Complex
z SEARCH_PROPERTIES: Search properties of the QueryForm.
z RESULT_PROPERTIES: Result Properties of the QueryForm
Example:
<ADD_FORM AssignToVar="response">
<QUERY_FORM Name="MST_SC_ITEM_LOC_FORM" Service="BCM_MASTER"
Type="Complex">
<ID Value="MST_SC_ITEM_LOC_FORM"/>
<SEARCH_PROPERTIES>
<SEARCH_PROPERTY Document="Location" Property="locationID"
DisplayName="Loc Id" Type="text"/>
<SEARCH_PROPERTY Document="Item" Property="itemID"
DisplayName="Item Id" Type="text"/>
</SEARCH_PROPERTIES>
<RESULT_PROPERTIES>
<RESULT_PROPERTY Document="Location" Property="name"
DisplayName="Location">
<PRESENTATION>
…………………..
</PRESENTATION>
</RESULT_PROPERTY>
</QUERY_FORM>
</ADD FORM>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="ADD_FORM">

</RESPONSE>

UPDATE_FORM.
Description:
This component is used for updating form specification into database and also it
refreshes memory with new Form object
Syntax:
<UPDATE_FORM AssignToVar="MyVariableName [Optional=true]">
<QUERY_FORM Name=" " Service=" " Type=" ">
< ID Value=””/>
< SEARCH_PROPERTIES>
……………
</ SEARCH_PROPERTIES>
< RESULT_PROPERTIES>
…………..
</UPDATE_FORM>
Attributes:
Property:
z <QUERY_FORM Name=" " Service=" " Type=" ">
Attributes:
| Name: Name of the Queryform
| Service: Name of the service
| Type: Simple/Complex
z SEARCH_PROPERTIES: Search properties of the QueryForm.
z RESULT_PROPERTIES: Result Properties of the QueryForm
Example:
<UPDATE_FORM AssignToVar="response">
Type="Complex">
<SEARCH_PROPERTIES>
<SEARCH_PROPERTY Document="Location"
Property="locationID" DisplayName="Loc Id"
Type="text"/>
<RESULT_PROPERTIES>
<PRESENTATION>
…………………..
</PRESENTATION>
</RESULT_PROPERTY>
</QUERY_FORM>
</ UPDATE_FORM>
Output Syntax:

<RESPONSE Status="Success" DbgCmd_=" UPDATE_FORM">

</RESPONSE>

DELETE_FORM.
Description:
This component is used for deleting form specification from database and also it
refreshes memory of the server.
Syntax:
<DELETE_FORM AssignToVar="MyVariableName [Optional=true]">
<ID Value=" " />
</DELETE_FORM >
Attributes:
Property:
z ID: Id of the query form.
Example:
< DELETE_FORM AssignToVar="response">
<ID Value=" MST_SC_ITEM_LOC_FORM " />
</ DELETE_FORM >
Output Syntax:
<RESPONSE Status="Success" DbgCmd_=" DELETE_FORM ">
</RESPONSE>

GET_FORMS.
Description:
This component is used for retrieving the form specification from the database.
Syntax:
<GET_FORMS AssignToVar="MyVariableName [Optional=true]">
<ID Value=" " />
</ GET_FORMS >
Attributes:
Property:
z ID: Id of the query form
Example:
<GET_FORMS AssignToVar="response">
<ID Value=" MST_SC_ITEM_LOC_FORM " />
</GET_FORMS >
Output Syntax:
<RESPONSE Status="Success" DbgCmd_=" GET_FORMS ">
Type="Complex">
<SEARCH_PROPERTIES>
<SEARCH_PROPERTY Document="Location" Property="locationID"
DisplayName="Loc Id" Type="text"/>
<RESULT_PROPERTIES>
<PRESENTATION>
…………………..
</PRESENTATION>
</RESULT_PROPERTY>
</QUERY_FORM>
</RESPONSE>

GET_FORM_DATA.
Description:
This component returns the data for a queryform.
Syntax:
<GET_FORM_DATA Expression=”” StartAtRow="" MaxRows="" ReturnRowCount=""
AssignToVar="MyVariableName [Optional=true]">
<ID Value=" "/>
<ORDER_BY>
………….
</ORDER_BY>
</GET_FORM_DATA>
Attributes:
retrieved
If it is not provided the default value is picked up from x2-config.cnd
MAX_ROWS parameter.
<query_form_config>
<all_forms>
<parameters>
…………….
<param name="MAX_ROWS" service="*" value="15"/>
</parameters>
</all_forms>
</ query_form_config>
z ReturnRowCount (Optional): true/false, If true, the number of instances in the
which match the query condition is returned as TotalRowCount attribute in the
output.
z Expression (Optional): This is used for specifying expression filters.
This command also considers the Authorization.
Property:
z ORDER_BY: To sort the results of the query.
z ID: Id of the form.
Example:

Output Syntax:…………………………….

UPDATE_FORM_DATA.
Description:
This component updates the data in table(s) using the queryforms.
Syntax:
Attributes:
z Expression (Optional): This is used for specifying expression filters.
This command also considers the Authorization.
Property:
z ID: Id of the form.
z FILTER: Filter criteria
z UPDATE_DOCUMENT: Name of the document which needs to be updated.
Example:
Output Syntax:
<RESPONSE Status="Success" DbgCmd_=" UPDATE_FORM_DATA ">
<RESPONSE Status="Success" />
</RESPONSE>

GET_DOCUMENT_NAME.
Description:
This component is used for getting Document's LogicalName from its Physical Name.
Syntax:
<GET_DOCUMENT_NAME TableName="MST_ITEMMASTER"
AssignToVar="MyVariableName [Optional=true]"/>
Attributes:
z TableName(Required): Physical Name of the Document
Example:
<GET_DOCUMENT_NAME TableName="MST_ITEMMASTER"
AssignToVar="response"/>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_DOCUMENT_NAME">
<DOCUMENT_NAME Value="ItemMaster"/>
</RESPONSE>

REMOVE_DOC_LOGICAL.
Description:
This component is used to soft delete the document instance.
The document is soft deleted by setting the 'SYS_ENT_STATE' column as deleted.
Syntax:
<REMOVE_DOC_LOGICAL Name="MyXDoc" ApplyDeleteRule="yes/no
[Default=no]" AssignToVar="MyVariableName [Optional=true]"
Synchronous="true|false [default=true]">
<propertyID Value="xyz"/>
</REMOVE_DOC_LOGICAL>
Attributes:
z Name (Required): Name of the document.
z ApplyDeleteRule: yes/no. Default is no. If this is yes then it will consider the
delete rule between the specified document and its children.
asynchronously.
Example:
<REMOVE_DOC_LOGICAL Name="ItemMaster" AssignToVar="response">
<ITEM Value="ITEM1"/>
</REMOVE_DOC_LOGICAL>
Output Syntax:
<RESPONSE RowCount="0" Status="Success"
DbgCmd_="REMOVE_DOC_LOGICAL" DbgNameAttr_="ItemMaster"/>

GET_VALID_VALUES.
Description:
This component returns the valid values defined for the properties of a document.
Syntax:
<GET_VALID_VALUES AssignToVar="MyVariableName [Optional=true]"/>
<DOCUMENT ServiceName="xyz" Name="abc" >
</GET_VALID_VALUES>
Attributes:
Property:
z DOCUMENT
Attribute:
| ServiceName: Name of the service.
| Name (Required): Name of the Document.
Example:
<GET_VALID_VALUES AssignToVar="response">
<DOCUMENT ServiceName="BCM_MASTER" Name="ItemMaster"/>
</GET_VALID_VALUES>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_VALID_VALUES">
<PROPERTY Name="SYS_TYPE" Document="Item">
<VALID_VALUE Value="ACTIVATE"/>
<VALID_VALUE Value="DELETE"/>
<VALID_VALUE Value="INSERT"/>
<VALID_VALUE Value="UPDATE"/>
</PROPERTY>
<PROPERTY Name="storageClass" Document="Item">
<VALID_VALUE Value="PALLETS"/>
<VALID_VALUE Value="WAREHOUSE"/>
</PROPERTY>
……………………
</RESPONSE>

MODIFY_DOC_SET_NULL.
Description:
This component is similar to MODIFY_DOCUMENT component , the only
difference being that it will set each property (except primary key) of document to null
which is not part of input update properties
Please refer to the MODIFY_DOCUMENT in the ABPP Programmers Reference
Guide, X-Rule Component Section for further details.
Syntax:
<DOCUMENT_CONTEXT>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<name Value="ppp"/>
<minimumQuantity/>
<width/>
<presp/>
<SYS_FILTER/>
<SYS_ERR_CODE/>
<SYS_TARGET_ID/>
……….
</UPDATE_PROPERTIES
</MODIFY_DOCUMENT>
Attributes:
Same as MODIFY_DOCUMENT -
be modified.
z AssignToVar (Optional): For storing the response of
MODIFY_DOC_SET_NULL.
asynchronously
Example:
<MODIFY_DOC_SET_NULL Name="Item">
<DOCUMENT_CONTEXT>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<name Value="ppp"/>
</MODIFY_DOC_SET_NULL>

This get converted to MODIFY_DOCUMENT

<DOCUMENT_CONTEXT>
</DOCUMENT_CONTEXT>
<UPDATE_PROPERTIES>
<name Value="ppp"/>
<minimumQuantity/>
<width/>
<presp/>
<SYS_FILTER/>
<SYS_ERR_CODE/>
<SYS_TARGET_ID/>
……….
</UPDATE_PROPERTIES
</MODIFY_DOCUMENT>
Output Syntax:
<RESPONSE RowCount="1" Status="Success" DbgCmd_="MODIFY_DOC_SET_NULL"

GET_DOC_WITH_NULL.
Description:
This component is similar to GET_DOCUMENT component, the only difference
being that it returns those properties also whose value is null.
Please refer to the GET_DOCUMENT in the ABPP Programmers Reference Guide ,
X-Rule Component Section for further details
Syntax:
<GET_DOC_WITH_NULL Name="documentName"
ReturnRowCount="true|false[default=false]"
<SELECT>
</SELECT>
</ GET_DOC_WITH_NULL >
Attributes:
z Name (Required): The name of the X-Document to be retrieved
z 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.
z ServiceName (Optional): Service from which the document is retrieved. If not
specified, then owner service is taken as default.
retrieved
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.
Example:
<GET_DOC_WITH_NULL Name="Item" AssignToVar="response">
</GET_DOC_WITH_NULL>

Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_DOC_WITH_NULL"
DbgNameAttr_="Item">
<width/>
<presp/>
<effectiveStartDate/>
<SYS_TYPE/>
…………………..
</RESPONSE>

DO_PERSIST.
Description:
This component does an ADD_DOC_SMART/MODIFY_DOC_SMART/
REMOVE_DOC_LOGICAL by default on the document instance based on the Value
of the action attribute. We can override this behavior by adding dataPersistSpecFile
under dataPersistSpec in the service configuration file.
Entry as shown below can be added in service file:
<dataPersistSpecFile Name="xservice/manufacturing/dataPersist/
do_persist_config_spec.xml" />
Syntax:
<REQUESTS ServiceName=” {VALID-SERVICE-NAME}”>
<DO_PERSIST
Action="INSERT | UPDATE | DELETE |ACTIVATE”
DocumentName="{VALID_DOC_NAME}"
[DoValidateOnly=”TRUE | FALSE [Optional=true]” Optional=”true”]
AssignToVar="response" >
<INPUT_DOC>
</DO_PERSIST>
</REQUESTS>
<Attributes:
z Action -
| Mandatory, specifies the persist action.
| Valid values:
INSERT - add the record
UPDATE - update
DELETE - delete
ACTIVATE - activate the record.
z DocumentName -
| Mandatory, specifies the document name.
z DoValidateOnly (optional)
| TRUE / true - The request is only for validating using the validation API
mentioned in the specs.
| FALSE / false - The request is for both validation and the action. This is a
default value.
We can define the behavior of <DO_PERSIST> for a particular document by
configuring a spec file. If the document name is '_ANY_DOCUMENT_' then it is
referred as default spec.

The 'xserver' service defines the default specs for all the documents for INSERT,
UPDATE, DELETE and ACTIVATE actions. The file containing default specs looks
like:
<data-persistance>

<document name="_ANY_DOCUMENT_">
<create api="addDocSmart"/>
<delete api="removeDocLogical"/>
<edit api="modifyDocSmart"/>
<activate api="modifyDocSmartActivate"/>
</document>
</data-persistance>
This spec can be overridden by the xService by defining the specs for
'_ANY_DOCUMENT_' in addition to the document specific spec. This is done by
adding dataPersistSpecFile under dataPersistSpec in the service configuration file.
The data persist spec file maps the document with its action handler API.
For Example,
Here 'create' refers to INSERT and 'edit' refers to UPDATE action. All other names are
obvious about their actions.
<data-persistance>
<document name="Item”
<create
validation="validateCreateOrEditItem[Optional=true]"
api="editItem[Optional=true]"
onError="onError[Optional=true]"
alertOnSuccess="createDocSuccessEvent[Optional=true]"
alertOnFailure="createDocFailedEvent[Optional=true]"
Optional=”true”/>
<edit
<delete
<activate
</document>
<data-persistance>
Action Handlers:
For every action we can declare up to 5 different handler APIs for different purposes.
All these handlers are optional as in such case the default spec is referred.

All these handlers are invoked in the following sequence.

The handlers are: (The serial number is the order of invocation)
z validation: The name of the validation API to be used to validate the document
record.
Note: This is the name of Validation API and not XRule.
If this Api fails then further execution is terminated and response is sent back.
z api: The name of XRule API for the action. It is invoked ONLY if validation
succeeds.
z onError: The error API ,invoked if 'api' fails
z alertOnSuccess: The XRule that raises the success alert when 'api' succeeds.
z alertOnFailure: The XRule that raises the failure alert when 'api' fails.
Note: The error message is passed to this Api in 'Error' attribute.
Example 1:
<DO_PERSIST> Call with default specs :
Call:
<REQUESTS ServiceName="BCM_MASTER">
<DO_PERSIST Name="doPersist" Action="INSERT” DocumentName
="Item" AssignToVar="response" >
<UOM Value="EA"/>
<description Value="testingdoc"/>
<accUOM Value="EA"/>
<isSellable Value="TRUE"/>
<itemID Value="testing1"/>
<name Value="testing1"/>
<status Value="ACTIVE"/>
<lifeCycleStage Value="saddas"/>
<ownerOrganizationID Value="1"/>
</DO_PERSIST>
</REQUESTS
Response:
<RESPONSE Status="Success" DbgCmd_="DO_PERSIST" >
</RESPONSE>
Example 2:
<DO_PERSIST> call for overridden specs:
Example of an entry made in dataPersistSpecFile:
<data-persistance>
<document name="Item">
<create validation="myTestValidation" api="myTestApi"/>
</document>
</data-persistance>

The overridden behavior is for validation and api handler. For rest handlers default
behavior will get called.
Call:
<REQUESTS ServiceName="BCM_MASTER">
<DO_PERSIST Name="doPersist" Action="INSERT" DocumentName="Item"
AssignToVar="response" >
<UOM Value="EA"/>
<description Value="testingdocument"/>
<accUOM Value="EA"/>
<isSellable Value="TRUE"/>
<name Value="testing2"/>
<status Value="ACTIVE"/>
<lifeCycleStage Value="qwerty"/>
<ownerOrganizationID Value="1"/>
</DO_PERSIST>
</REQUESTS>
Response:
<RESPONSE Status="Success" DbgCmd_="DO_PERSIST" />

ADD_DOCUMENT.
Description:
ADD_DOCUMENT command in MDM is enhanced to be scenario enabled.
Please refer to the ADD_DOCUMENT in the ABPP Programmers Reference Guide ,
X-Rule Component Section for further details.
Syntax:
Same as ABPP ADD _DOCUMENT
Attributes:
Same as ABPP ADD _DOCUMENT
Examples:
<ADD_DOCUMENT Name="ItemMaster" AssignToVar="response">
</ADD_DOCUMENT>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="ADD_DOCUMENT"
</RESPONSE>

GET_DOCUMENT.
Description:
GET_DOCUMENT command in MDM is enhanced to be scenario enabled. It fetches
the current scenario id and that is appended in the query condition for fetching the
document instances.
Please refer to the GET_DOCUMENT in the ABPP Programmers Reference Guide,
X-Rule Component Section for further details.
Syntax:
Same as ABPP GET _DOCUMENT
Attributes:
Same as ABPP GET _DOCUMENT
Examples:
<GET_DOCUMENT Name="Item" AssignToVar="response"> <itemID Value="
LEG_ANGULAR"/> </ GET_DOCUMENT >
Output Syntax:
<CREATION_DATE Value="03/29/2007 10:56:57:000"/>
……….
</Item>
</RESPONSE>

REMOVE_DOCUMENT.
Description:
REMOVE _DOCUMENT command in MDM is enhanced to be scenario enabled. It
fetches the current scenario id and that is appended in the query condition for fetching
the document instances to be deleted.
Please refer to the REMOVE _DOCUMENT in the ABPP Programmers Reference
Syntax:
Same as ABPP REMOVE _DOCUMENT
Attributes:
Same as ABPP REMOVE _DOCUMENT
Examples:
<REMOVE_DOCUMENT Name="Item" AssignToVar="response">
<itemID Value="LISA_DP1"/>
</REMOVE_DOCUMENT>
Output Syntax:
<RESPONSE RowCount="1" Status="Success" DbgCmd_="REMOVE_DOCUMENT"

MODIFY_DOCUMENT.
MODIFY _DOCUMENT command in MDM is enhanced to be scenario enabled. It
fetches the current scenario id and that is appended in the query condition for fetching
the document instances to be modified.
Please refer to the MODIFY _DOCUMENT in the ABPP Programmers Reference
Syntax:
Same as ABPP MODIFY _DOCUMENT
Attributes:
Same as ABPP MODIFY _DOCUMENT
Output Syntax:
<RESPONSE RowCount="1" Status="Success"
DbgCmd_="MODIFY_DOCUMENT" DbgNameAttr_="Item"/>

GET_SCENARIO_ID.
Description:
This component is used to get scenario id from the session.
Syntax:
<GET_SCENARIO_ID AssignToVar="variableName[Optional=true]"/>
Attributes:
Example:
<GET_SCENARIO_ID AssignToVar="response"/>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_SCENARIO_ID">
</RESPONSE>

SET_SCENARIO_ID.
Description:
This component is used to set scenario id in the session.
Syntax:
<SET_SCENARIO_ID ScenarioId=""
AssignToVar="variableName[Optional=true]"/>
Attributes:
z ScenarioId (Required): Value of the scenario id that should be set in the session.
Example:
<SET_SCENARIO_ID ScenarioId="0" AssignToVar="response"/>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="SET_SCENARIO_ID"/>

GET_SUPPORTED_DATA_TYPES.
Description:
This component returns the list of all the supported data types.
Syntax:
<GET_SUPPORTED_DATA_TYPES
AssignToVar="variableName[Optional=true]"/>
Attributes:
Example:
<GET_SUPPORTED_DATA_TYPES AssignToVar="response"/>
Output Syntax:
<RESPONSE Status="Success" DbgCmd_="GET_SUPPORTED_DATA_TYPES">
<datatype Name="stringlist"/>
<datatype Name="BigDecimal"/>
……………………
</RESPONSE>


Index
A Define CIS tag in API_DOC/

ABPP Studio 111 EVENT_DOC 119
ADD_DOC_SMART 191 Define config file needed for CIS file
ADD_DOCUMENT 217 generation 120
ADD_FORM 197 Define name mapping file 122
Advanced Configuration Settings 174 Defining a listener in Workflow 5
Allowing Extra Attributes on a Tag 13 Defining a listener in X-Rules 5
Allowing Extra Child Tags 13 Defining a Request Interface 8
Allowing Repetitions of a Tag 14 Defining Audit Trail Definition 110
API Specification 107 Defining Events 2
API_DOC Language Extensions 14 Defining Export Definition 66
Appendix 100 Defining Purge Definition 54
Appendix A Definition of XML Attributes used in defining
Generating Xservice WSDL 21 validation specification 32
Appendix B DELETE_FORM 201
Validating Xservice APIs at Runtime 24 DO_PERSIST 213
Appendix C
Adding Custom Extensions to E
API_DOC 24 Event and Request Interfaces 1
Appendix D Examples of XML Messages 127
Testing the WSDL API 24 Exception States 93
Audit Trail Framework 109 Export Framework 65
Audit Trail Functionality 109 Export Framework Schema 71
Autofill/Postfill 37 Export Functionality 65
B F
BlockIdGeneration 46 Features of Audit Trail framework 110
Features of Export Framework 66
C Features of Purge Framework 54
CIS Support 117 Fetch document links 78
Concept 105
Creating export/staging table schema 69 G
Creating purge backup table schema 63 Generate the CIS metadata types and binding
files 124
D Generating Metadata types and Bindings 118
DB Locking 105 GET_ALL_DOC_NAMES 189
Define API_DOC and EVENT_DOC for the GET_DOC_PROPERTIES 190
rules and event descriptor 118 GET_DOC_SMART 193
GET_DOC_WITH_NULL 211

Index
GET_DOCUMENT 218 MODIFY_DOCUMENT 220

GET_DOCUMENT_NAME 206
GET_FOLDERS 188 N
GET_FORM_DATA 203 Normal Filters 79
GET_FORMS 202
GET_LINKS 187 O
GET_SCENARIO_ID 221 Obtaining event name for a state in a state
GET_SEARCH_RESULTS 80 model 97
GET_SUPPORTED_DATA_TYPES 223 Override default data type mapping only if
GET_TABLE 184 needed 124
GET_TABLES 186
GET_VALID_VALUES 208
P
PREVIOUS_STATE_EVENT 97
H Purge 53
Handling Attributes 125 Purge framework schema 64
Handling Text 125 Purge Functionality 53
I Q
ID Generation 45 Query document links 79
IdGen Configuration 46
Interfaces to Search Framework 80
R
Interfaces to State Machine 95
RAISE_STATE_EVENT 96
INVOKE_VALIDATION_FRAMEWORK 3
Raising Events 6
8
Referencing a Search Spec 16
Invoking/Triggering export 70
Referencing a Validation Spec 18
Referencing Declarations in an Xdocument 15
J Referencing other API_DOCs 20
JMSDynamicListenerSurvivalRatio 177 REMOVE_DOC_LOGICAL 207
JMSHeartbeatInterval 174 REMOVE_DOCUMENT 219
JMSMaxDynamicListenersPerAPI 175 Running CIS 127
JMSMaxListenerIdleTime 176 Runtime Setup 125
JMSMaxPendingMsgCount 175
JMSMessageConverter 174
S
JMSMinDynamicListenersPerAPI 176
Search Definition 77
JMSQueueBrowseInterval 175
Search Framework 75
JMSRetryCountBeforeReconnect 174
Search Functionality 75
SequenceIdGeneration 46
L SET_AUDIT_TRAIL_STATUS 113
Loading Export Definition 69 SET_SCENARIO_ID 222
Loading purge definition 63 Setup 106
Loading state model files 98 Specify the config file in server config file 122
Specify the mapping file in service config
M file 123
Making ABPP rules and events available to Specifying a Choice of Tags 14
clients using CIS 117 Specifying additional search criteria 79
Mapping condition specification and event Specifying that a Tag is Optional 13
mapping 92 Specifying that an Attribute is Optional 12
MODIFY_DOC_SET_NULL 209 Specifying the Data Type of an Attribute 11
MODIFY_DOC_SMART 195 Specifying the Order of Child Tags 13

Index
State Document 95
State Machine 89
State Model 89
State Model Association 93
State Model Specification 90
Steps involved in using validation
framework 38
Subscribing Events 5
T
TableIdGeneration 46
The API_DOC IDL 9
TimeIdGeneration 45
Turn off audit trail 111
Types of validations 34
U
UPDATE_FORM 199
UPDATE_FORM_DATA 205
UPDATE_VALIDATION_RESULT 42
V
VALIDATE_DOC 40
Validation 27
Variables 33
W
Web Service Definitions 9, 179

Programmers Reference Part2 6.2.8 RevA

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Programmers Reference Part2 6.2.8 RevA

Transféré par

Droits d'auteur :

Formats disponibles

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 Web Service Definitions................................................................................ 9

Agile Business Process Platform 3 Programmers Reference Revision A v

Appendix C: Testing the WSDL API ..................................................................................................... 24

6 Export Framework ........................................................................................65

vi Agile Business Process Platform 3 Programmers Reference Revision A

Defining Export Definition......................................................................................................................66

10 Audit Trail Framework............................................................................... 109

Agile Business Process Platform 3 Programmers Reference Revision A vii

Features of Audit Trail framework ....................................................................................................... 110

viii Agile Business Process Platform 3 Programmers Reference Revision A

Insert Init rule..........................................................................................................................156

12 JMS Support............................................................................................... 161

13 Data Service ............................................................................................... 179

Index ........................................................................................................... 225

Agile Business Process Platform 3 Programmers Reference Revision A ix

x 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 xi

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

xii 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 xiii

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:

xiv Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A xv

If You Need Assistance

To Contact Customer Support

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

Phone: US and Canada: 1.469.357.3456

xvi Agile Business Process Platform 3 Programmers Reference Revision A

For the Latest Documentation

Agile Business Process Platform 3 Programmers Reference Revision A xvii

xviii Agile Business Process Platform 3 Programmers Reference Revision A

A service using the event frame work would contain:

Agile Business Process Platform 3 Programmers Reference Revision A 1

2 Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A 3

This above example defines an event, newForecastArrived. The EVENT_DOC tag

4 Agile Business Process Platform 3 Programmers Reference Revision A

Defining a listener in X-Rules

Defining a listener in Workflow

Agile Business Process Platform 3 Programmers Reference Revision A 5

6 Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A 7

<REF_DOC_ID Value="REQ-PROB-101" />

8 Agile Business Process Platform 3 Programmers Reference Revision A

Web Service Definitions

The API_DOC IDL

Agile Business Process Platform 3 Programmers Reference Revision A 9

10 Agile Business Process Platform 3 Programmers Reference Revision A

Specifying the Data Type of an Attribute

The following example illustrates using a data type on text element: