Programmers Reference Part2 6.2.8 RevA
Transcript of 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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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. 164194Taiwan Patent No. 166322Taiwan Patent No. 167148Taiwan Patent No. 167585Taiwan Patent No. 170630Taiwan Patent No. 172458Taiwan Patent No. 182787
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
Taiwan Patent No. 227425Taiwan Patent No. 227427Taiwan Patent No. 231432Taiwan Patent No. 234724Taiwan Patent No. 235318Taiwan Patent No. 238957Taiwan Patent No. 239461
01/16/08
One i2 Place
11701 Luna Rd.
Dallas, TX 75234 USA
CopyrightIn formation
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
4/245
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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/14/2019 Programmers Reference Part2 6.2.8 RevA
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
10/245
x Agile Business Process Platform 3 Programmers Reference Revision A
Contents
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
11/245
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
13/245
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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://-/?- -
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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/ -
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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/ -
8/14/2019 Programmers Reference Part2 6.2.8 RevA
17/245
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
18/245
Preface
xviii Agile Business Process Platform 3 Programmers Reference Revision A
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
21/245
Defining Events
3Agile Business Process Platform 3 Programmers Reference Revision A
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
22/245
Chapter 1 Events
4 Agile Business Process Platform 3 Programmers Reference Revision A
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
23/245
Subscribing Events
5Agile Business Process Platform 3 Programmers Reference Revision A
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
24/245
Chapter 1 Events
6 Agile Business Process Platform 3 Programmers Reference Revision A
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
25/245
Raising Events
7Agile Business Process Platform 3 Programmers Reference Revision A
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
26/245
Chapter 1 Events
8 Agile Business Process Platform 3 Programmers Reference Revision A
Output:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
27/245
9Agile Business Process Platform 3 Programmers Reference Revision A
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
28/245
Chapter 2 Web Service Definitions
10 Agile Business Process Platform 3 Programmers Reference Revision A
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
29/245
The API_DOC IDL
11Agile Business Process Platform 3 Programmers Reference Revision A
[ 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]
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
30/245
Chapter 2 Web Service Definitions
12 Agile Business Process Platform 3 Programmers Reference Revision 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.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.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
31/245
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
32/245
Chapter 2 Web Service Definitions
14 Agile Business Process Platform 3 Programmers Reference Revision A
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.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
33/245
API_DOC Language Extensions
15Agile Business Process Platform 3 Programmers Reference Revision A
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
34/245
Chapter 2 Web Service Definitions
16 Agile Business Process Platform 3 Programmers Reference Revision A
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
35/245
API_DOC Language Extensions
17Agile Business Process Platform 3 Programmers Reference Revision A
During WSDL generation, the example above will be expanded to
the following:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
36/245
Chapter 2 Web Service Definitions
18 Agile Business Process Platform 3 Programmers Reference Revision A
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
37/245
API_DOC Language Extensions
19Agile Business Process Platform 3 Programmers Reference Revision A
During WSDL generation, the example above will be expanded to thefollowing:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
38/245
Chapter 2 Web Service Definitions
20 Agile Business Process Platform 3 Programmers Reference Revision A
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.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
39/245
Appendix A: Generating Xservice WSDL
21Agile Business Process Platform 3 Programmers Reference Revision A
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:
Appendix A: Generating Xservice WSDL
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.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
40/245
Chapter 2 Web Service Definitions
22 Agile Business Process Platform 3 Programmers Reference Revision A
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
41/245
Appendix A: Generating Xservice WSDL
23Agile Business Process Platform 3 Programmers Reference Revision A
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.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
42/245
Chapter 2 Web Service Definitions
24 Agile Business Process Platform 3 Programmers Reference Revision A
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'.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
43/245
Appendix C: Testing the WSDL API
25Agile Business Process Platform 3 Programmers Reference Revision A
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
44/245
Chapter 2 Web Service Definitions
26 Agile Business Process Platform 3 Programmers Reference Revision A
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
45/245
27Agile Business Process Platform 3 Programmers Reference Revision A
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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
46/245
Chapter 3 Validation
28 Agile Business Process Platform 3 Programmers Reference Revision A
....
....
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.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
47/245
Validation specification
29Agile Business Process Platform 3 Programmers Reference Revision A
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.
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
48/245
Chapter 3 Validation
30 Agile Business Process Platform 3 Programmers Reference Revision A
: 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:
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
49/245
Validation specification
31Agile Business Process Platform 3 Programmers Reference Revision A
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
-
8/14/2019 Programmers Reference Part2 6.2.8 RevA
50/245
Chapter 3 Validation
32 Agile Business Process Platform 3 Programmers Reference Revision A
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