Programmers Reference Part2 6.2.8 RevA

8/14/2019 Programmers Reference Part2 6.2.8 RevA

1/245

Agile Business Process

Platform (ABPP) 3Programmers Reference - Part 2

Revision A

Version 6.2.8


2/245

i2

Agile Business Process Platform (ABPP) 3Programmers Reference - Part 2 Revision AVersion 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)German Patent No. 10195871German Patent No. 69508931.5German Patent No. 69507020.7German Patent No. 69601151.4German Patent No. 69601152.2German Patent No. 69601207.3German Patent No. 69601208.1Taiwan Patent No. 80326Taiwan Patent No. 93090Taiwan Patent No. 100569Taiwan Patent No. 108409Taiwan Patent No. 110827Taiwan Patent No. 113331Taiwan Patent No. 127358

Taiwan Patent No. 129860Taiwan Patent No. 133048Taiwan Patent No. 134299Taiwan Patent No. 136847Taiwan Patent No. 137376Taiwan Patent No. 139353Taiwan Patent No. 139680

Taiwan Patent No. 140308Taiwan Patent No. 146038Taiwan Patent No. 154327Taiwan Patent No. 154338Taiwan Patent No. 154339Taiwan Patent No. 155489Taiwan Patent No. 155708Taiwan Patent No. 157467Taiwan Patent No. 158220Taiwan Patent No. 159609Taiwan Patent No. 161120Taiwan Patent No. 161181Taiwan Patent No. 161494Taiwan Patent No. 162685Taiwan Patent No. 163816


Taiwan Patent No. 182974Taiwan Patent No. 191262Taiwan Patent No. 196235Taiwan Patent No. 199069Taiwan Patent No. 200370Taiwan Patent No. 205817Taiwan Patent No. 221578Taiwan Patent No. 221978Taiwan Patent No. 222584Taiwan Patent No. 222585Taiwan Patent No. 222586Taiwan Patent No. 222588Taiwan Patent No. 225208Taiwan Patent No. 225209Taiwan Patent No. 225605


01/16/08

One i2 Place

11701 Luna Rd.

Dallas, TX 75234 USA

CopyrightIn formation


3/245

Taiwan Patent No. 241800Taiwan Patent No. 242952Taiwan Patent No. 251760Taiwan Patent No. 251996Taiwan Patent No. 258090Taiwan Patent No. 266251Taiwan Patent No. 271617Taiwan Patent No. 284847Taiwan Patent No. 285339

Taiwan Patent No. 285342U. S. Patent No. 5,630,123U. S. Patent No. 5,742,813U. S. Patent No. 5,764,543U. S. Patent No. 5,778,356U. S. Patent No. 5,832,532U. S. Patent No. 5,835,910U. S. Patent No. 5,838,965U. S. Patent No. 5,845,258U. S. Patent No. 5,930,156U. S. Patent No. 5,931,900U. S. Patent No. 5,937,155U. S. Patent No. 5,943,244U. S. Patent No. 5,974,395U. S. Patent No. 5,983,194U. S. Patent No. 5,995,945U. S. Patent No. 6,031,984U. S. Patent No. 6,047,290U. S. Patent No. 6,055,519U. S. Patent No. 6,055,533U. S. Patent No. 6,076,108U. S. Patent No. 6,085,220U. S. Patent No. 6,119,149U. S. Patent No. 6,167,380U. S. Patent No. 6,169,992U. S. Patent No. 6,188,989U. S. Patent No. 6,222,533U. S. Patent No. 6,233,493U. S. Patent No. 6,233,572U. S. Patent No. 6,266,655U. S. Patent No. 6,289,384U. S. Patent No. 6,289,385U. S. Patent No. 6,321,207U. S. Patent No. 6,321,230U. S. Patent No. 6,332,130U. S. Patent No. 6,332,155U. S. Patent No. 6,334,146

U. S. Patent No. 6,360,249U. S. Patent No. 6,366,922U. S. Patent No. 6,370,509U. S. Patent No. 6,374,227

U. S. Patent No. 6,374,249U. S. Patent No. 6,374,252U. S. Patent No. 6,397,191U. S. Patent No. 6,397,192U. S. Patent No. 6,442,528U. S. Patent No. 6,442,554U. S. Patent No. 6,456,996U. S. Patent No. 6,462,736U. S. Patent No. 6,480,894

U. S. Patent No. 6,486,899U. S. Patent No. 6,490,566U. S. Patent No. 6,560,501U. S. Patent No. 6,560,502U. S. Patent No. 6,567,783U. S. Patent No. 6,574,619U. S. Patent No. 6,577,304U. S. Patent No. 6,631,363U. S. Patent No. 6,658,413U. S. Patent No. 6,708,161U. S. Patent No. 6,708,174U. S. Patent No. 6,731,998U. S. Patent No. 6,778,991U. S. Patent No. 6,785,689U. S. Patent No. 6,789,252U. S. Patent No. 6,826,538U. S. Patent No. 6,828,968U. S. Patent No. 6,836,689U. S. Patent No. 6,839,711U. S. Patent No. 6,845,499U. S. Patent No. 6,857,017U. S. Patent No. 6,868,299U. S. Patent No. 6,873,994U. S. Patent No. 6,874,008U. S. Patent No. 6,895,384U. S. Patent No. 6,895,550U. S. Patent No. 6,898,593U. S. Patent No. 6,920,476U. S. Patent No. 6,922,675U. S. Patent No. 6,934,686U. S. Patent No. 6,944,598U. S. Patent No. 6,947,905U. S. Patent No. 6,947,982U. S. Patent No. 6,957,234U. S. Patent No. 6,963,847U. S. Patent No. 6,963,849U. S. Patent No. 6,973,626

U. S. Patent No. 6,980,885U. S. Patent No. 6,980,966U. S. Patent No. 6,983,276U. S. Patent No. 6,983,421

U. S. Patent No. 6,988,104U. S. Patent No. 6,988,111U. S. Patent No. 7,003,729U. S. Patent No. 7,013,485U .S. Patent No. 7,024,265U. S. Patent No. 7,024,371U. S. Patent No. 7,028,000U. S. Patent No. 7,031,955U. S. Patent No. 7,039,562

U. S. Patent No. 7,039,597U. S. Patent No. 7,039,602U. S. Patent No. 7,039,833U. S. Patent No. 7,043,444U. S. Patent No. 7,050,874U. S. Patent No. 7,054,841U. S. Patent No. 7,055,137U. S. Patent No. 7,062,540U. S. Patent No. 7,062,542U. S. Patent No. 7,065,499U. S. Patent No. 7,073,164U. S. Patent No. 7,085,729U. S. Patent No. 7,086,062U. S. Patent No. 7,089,196U. S. Patent No. 7,089,330U. S. Patent No. 7,093,233U. S. Patent No. 7,117,163U. S. Patent No. 7,117,164U. S. Patent No. 7,127,416U. S. Patent No. 7,127,458U. S. Patent No. 7,130,809U. S. Patent No. 7,139,719U. S. Patent No. 7,149,744U. S. Patent No. 7,162,453U. S. Patent No. 7,177,827U. S. Patent No. 7,197,473U. S. Patent No. 7,210,624U. S. Patent No. 7,213,037U. S. Patent No. 7,213,232U. S. Patent No. 7,216,142U. S. Patent No. 7,225,146U. S. Patent No. 7,248,937U. S. Patent No. 7,249,044U. S. Patent No. 7,251,614U. S. Patent No. 7,257,541U. S. Patent No. 7,260,550U. S. Patent No. 7,263,515

U. S. Patent No. 7,266,549U. S. Patent No. 7,277,862U. S. Patent No. 7,277,863


4/245


5/245

vAgile Business Process Platform 3 Programmers Reference Revision A

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................................................................................ 9Introduction ...............................................................................................................................................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


6/245

vi Agile Business Process Platform 3 Programmers Reference Revision A

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 .................................................................................................................................. 46SequenceIdGeneration............................................................................................................................ 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


7/245

Contents

viiAgile Business Process Platform 3 Programmers Reference Revision A

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 .......................................................................................................................................95Interfaces 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................................................................................................. 105Concept..................................................................................................................................................105

Setup ......................................................................................................................................................106

API Specification...................................................................................................................................107

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

Introduction ...........................................................................................................................................109

Audit Trail Functionality.......................................................................................................................109


8/245

viii Agile Business Process Platform 3 Programmers Reference Revision A

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 .................................................................................................145Configure 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


9/245

Contents

ixAgile Business Process Platform 3 Programmers Reference Revision A

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 .................................................................................................180Action X-Rule Components specific to Data Services ..................................................................182

MDM COMMANDS .............................................................................................................183

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


10/245

x Agile Business Process Platform 3 Programmers Reference Revision A

Contents


11/245


12/245

Preface

xii Agile Business Process Platform 3 Programmers Reference Revision A

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 userinterface design and integration design.

For information on other i2 solutions, contact your i2 sales representative.


13/245


14/245

Preface

xiv Agile Business Process Platform 3 Programmers Reference Revision A

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

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 avoidpotential crashes or loss of data.

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

pointer in the Module

Configuration class a primary

key.

Class names appear in bold.

Interface element ClickOrganization Management

in the toolbar.

Button names, field names, window

names are shown in a san-serif font.

Pathname C:\i261\webdriver

or

/i261/webdriver

Windows pathnames are shown in

monospaced font, with backslash path

separators.

Unix pathnames are shown with

forward-slash path separators.

Meta-variable i2_Home\webdriver

or

i2_Home/webdriver

Portions of code that you replace with

specific values are shown in italic

monospaced font.

Documentation or

book names. SCOS Installation GuideDocument or book names referenced

in this book are shown in italics.
http://-/?-http://-/?-


15/245

Preface

xvAgile Business Process Platform 3 Programmers Reference Revision A

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

Adobes Web site at http://www.adobe.com.
http://www.adobe.com/http://www.adobe.com/http://www.adobe.com/


16/245

Preface

xvi Agile Business Process Platform 3 Programmers Reference Revision A

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 clickRequest 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

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.

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

Email: [email protected]

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
http://www.microsoft.com/http://home.netscape.com/http://support.i2.com/http://support.i2.com/http://support.i2.com/http://support.i2.com/http://support.i2.com/http://support.i2.com/http://support.i2.com/http://support.i2.com/http://home.netscape.com/http://www.microsoft.com/http://support.i2.com/


17/245


18/245

Preface

xviii Agile Business Process Platform 3 Programmers Reference Revision A


19/245

1Agile Business Process Platform 3 Programmers Reference Revision A

Chapter 1

Events

Topics:

z Defining Eventsz 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.


20/245

Chapter 1 Events

2 Agile Business Process Platform 3 Programmers Reference Revision A

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. Itwas 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:


21/245

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 externalABPP 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

Programmers 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 Programmers 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 forfurther 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 (Programmers 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 XMLdocument 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


22/245

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 beRAISE_EVENT as that is command used to raise the event and will always be the

root of the event body.

Example:

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:


23/245

Subscribing Events


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 serviceconfiguration 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:

The fully qualified name of the event is /// . 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:

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:


24/245

Chapter 1 Events


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:

Output Syntax:

Attributes:


25/245

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:

Output:

RAISE_EVENTS

Description:

This command raises multiple events defined within a service. This will help in

performance

Input Syntax:

Output Syntax:

Example:

Input:


26/245

Chapter 1 Events


Output:


27/245


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 onlything 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


28/245

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:


29/245

The API_DOC IDL


[ rule logic]

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 sectionto 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 Programmers 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:

The following example illustrates an attribute declaration with a data type and an

example value for the attribute:

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:

The following example illustrates an attribute declaration for a constant value:

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

VMI|CMI_ER

01/01/2004 10:23:42[Type=datetime]

10[Type=positive-int]


30/245



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.3002006-01-01T03:02:01Z This indicates a UTC dateTime2006-01-01T04:02:01+01:00 This is a dateTime that is

one hour ahead of UTC

xsdDateFormat: CCYY-MM-DDExample:

2006-04-10

xsdTimeFormat: hh:mm:ss[.sss]Example:

13:50:25.30003: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.


31/245


32/245



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

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.

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.


33/245



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

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 usedto 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:


34/245



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.

Referencing a Search SpecAnother 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.

The REFER_SEARCH_FILTER directive takes a Name attribute, which must be setto the name of the search spec being referenced.

Assume that the Xservice contains the following search spec definition:


35/245



During WSDL generation, the example above will be expanded to

the following:


36/245



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.

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:


37/245



During WSDL generation, the example above will be expanded to thefollowing:


38/245



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:

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 APIs documentation.

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.


39/245

Appendix A: Generating Xservice WSDL


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:


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.


40/245



The following code segment illustrates how to assign an access privilege to an API:

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:

/WSDLGenerate>

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 offcall .\omxenv.battitle OMx Serverjava com.i2.xcore.wsdl.WsdlGenerator xserver.xml em.xmlorderadmin.xml pause


41/245



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 : .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 tag under as shown below

2. The apiFilterFile specifies the APIs for which to generate the XSDs and WSDL.

The format of this file is:

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


42/245



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

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:

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


43/245

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


44/245




45/245


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 commandsINVOKE_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:


46/245

Chapter 3 Validation


....

....

Output from validation:

....

....

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.


47/245



Specification Structure

The structure of the validation specification file should be as follows:

... other error_code ...

... variable definition ...

... validation rules for tag ...

... validation rules for field ...

... auto fill for field ...

... post fill for field ...

... other field ...

..variables, fields & validation tags..

.....

... other tag ...

... other user_validation ...

The individual elements used in the above specification are explained below:

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


48/245



: The element lists all the errors that the validation can

generate. The Name attribute of 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 willstop 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.

: The 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 the validation is performed on the 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 . For example in the INPUT

XML presented in the Overview section, CUSTOMER_ORDER or

ORDER_LINE_ITEM elements would be validated using the element of the

validation specification.

Notice that elements can be nested within each other. The nested element

are used for validating the child elements of the current element. The logic used by the

validation framework to identify the 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 element for ORDER_LINE_ITEM defined within the element

for CUSTOMER_ORDER.

If it is defined then

It uses the element to validate the ORDER_LINE_ITEM element.

Else

It looks up to find a element defined for ORDER_LINE_ITEM within the

immediate child s of the element (i.e., a element defined at the

top level for that spec). If a 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 element defined at the top level of the spec(i.e ., immediate child of ) 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:


49/245



The Line element within CancelledLines element has a different structure than the

Line element within AddedLines elements. Hence it is necessary to define nested

for Line element within the different parent s to distinguish between the

different structures. The validation structure will be as follows:

: This can be used to define a set of variables that are accessible while

validating the current tag.

: 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 above. For example

ITEM_ID or ORDERED_QTY etc. in the INPUT XML above would be validated

using the element of the validation specification.

: 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 subsequentsections of this chapter.

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

: 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


50/245



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 validationspecification

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 ////

//. Defines the name depending on the element in which

this "Name" attribute is defined e.g. z Severity: Allowed in . Defines the severity of error. Valid values:

INFO|WARNING|ERROR|SEVERE_ERROR e.g.

z IsFilter: Allowed in . Default is false. If IsFilter="true" then

expression used to compute variable should return boolean value e.g.

z IsNoCache: Allowed in . Default is false. If this is false then the

variable is computed once when it is first time referred and t

Documents

Programmers Reference Part2 6.2.8 RevA