ABPP3 Programmers Reference Part3 6.2.8 RevA

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

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

Europe Patent No. 0861474 (E) Taiwan Patent No. 140308 Taiwan Patent No. 182974
German Patent No. 10195871 Taiwan Patent No. 146038 Taiwan Patent No. 191262
German Patent No. 69508931.5 Taiwan Patent No. 154327 Taiwan Patent No. 196235
Taiwan Patent No. 80326 Taiwan Patent No. 158220 Taiwan Patent No. 222584
01/16/08
Taiwan Patent No. 241800 U. S. Patent No. 6,374,249 U. S. Patent No. 6,988,104
Taiwan Patent No. 258090 U. S. Patent No. 6,442,528 U .S. Patent No. 7,024,265
U. S. Patent No. 5,630,123 U. S. Patent No. 6,490,566 U. S. Patent No. 7,039,602
U. S. Patent No. 6,374,227 U. S. Patent No. 6,983,421
Contents
Preface........................................................................................................... ix
1 Timer Service ................................................................................................. 1

Introduction ...............................................................................................................................................1
Timer setup and callback...........................................................................................................................2
Deployment ...............................................................................................................................................2
Configuration of timer poll interval ..........................................................................................................2
Timer commands .......................................................................................................................................3
START_TIMER.................................................................................................................................3
STOP_TIMER....................................................................................................................................7
Guaranteed Messaging ..............................................................................................................................8
Success-failure Determination .........................................................................................................11
2 Approval Service ......................................................................................... 13

Introduction .............................................................................................................................................13
Approval Nodes.......................................................................................................................................15
Common Approval Node Properties ................................................................................................15
Serial Approval Node.......................................................................................................................18
Parallel Approval Node....................................................................................................................19
Multi-line Approval node.................................................................................................................20
Approval Node Execution .......................................................................................................................22
Starting the approval .................................................................................................................22
Performing Approver Action ....................................................................................................22
Processing Approver Action .....................................................................................................23
Input/Output to Approval UI workflows.................................................................................................24
Configuring & Managing Approval Alerts .............................................................................................25
Approval Node Activation ........................................................................................................26
Steps for creating an Approval Workflow...............................................................................................26
3 Data Upload.................................................................................................. 29
Introduction .............................................................................................................................................29
Agile Business Process Platform 3 Programmers Reference Revision A v

Contents
Upload Functionality Overview.............................................................................................................. 29

Upload Templates Management ............................................................................................................. 29
Upload Methods...................................................................................................................................... 31
Server Based Method....................................................................................................................... 31
UI Based Method............................................................................................................................. 34
Status Report........................................................................................................................................... 34
Error Correction ...................................................................................................................................... 36
Advanced Customizations ...................................................................................................................... 41
Dataupload Workflow ..................................................................................................................... 41
Guidelines ............................................................................................................................................... 44
Tuning Upload using Get Resource Stats Command ............................................................................. 45
4 Task Scheduler Service ...............................................................................49

Introduction............................................................................................................................................. 49
Task Nodes ............................................................................................................................................. 50
Wait Process Node........................................................................................................................... 50
Wait Process ouputDocVar Signature:..................................................................................... 52
Launch Process Node ...................................................................................................................... 52
Launch Process ouputDocVar Signature:................................................................................. 53
Load SQL File Node........................................................................................................................ 54
Load SQL File ouputDocVar Signature:.................................................................................. 55
Execute SQL Procedure Node ......................................................................................................... 55
Execute SQL Procedure ouputDocVar Signature: ................................................................... 57
FTP Files Node ................................................................................................................................ 58
FTP Files Node ouputDocVar Signature:................................................................................. 59
Notification Node ............................................................................................................................ 59
Task Node Execution.............................................................................................................................. 60
Assumptions and Dependencies ............................................................................................................. 61
Configuring and Managing Notification................................................................................................. 61
Steps for Configuring Notification at an application level:............................................................. 61
Task Event and Task Status Table .......................................................................................................... 65
Scheduling .............................................................................................................................................. 68
UI Log and Monitoring........................................................................................................................... 69
Details of the workflows are as follows: ......................................................................................... 69
tsTaskHistory Workflow: ......................................................................................................... 69
tsDetails Workflow:.................................................................................................................. 72
Suggestions and Best Practices............................................................................................................... 73
Debug External Processes: .............................................................................................................. 73
Subworkflows:................................................................................................................................. 73
Stop Running tasks: ......................................................................................................................... 74
Handler Task Errors:........................................................................................................................ 74
Complex start conditions: ................................................................................................................ 74
Node Input Parameter:..................................................................................................................... 74
Adding tsHistory workflow to an Application ................................................................................ 74
vi Agile Business Process Platform 3 Programmers Reference Revision A

Contents
5 Email Service ............................................................................................... 75

Introduction .............................................................................................................................................75
Setup ........................................................................................................................................................75
Sending Emails........................................................................................................................................76
Example 1: Sending simple text email.............................................................................................78
Example 2: Sending HTML format email using XSL file ...............................................................78
Example 3: Sending HTML format email using X-Rules................................................................80
6 Messaging Service ...................................................................................... 83

Introduction .............................................................................................................................................83
Functionality and Setup...........................................................................................................................83
Define Message Events ....................................................................................................................85
Define Message Template................................................................................................................86
ALERT Template......................................................................................................................87
EMAIL Template......................................................................................................................89
Define Recipient Groups..................................................................................................................90
ENTITY Recipient Type...........................................................................................................92
RULE Recipient Type...............................................................................................................93
CUSTOM Recipient Type ........................................................................................................94
Link Message Event to Message Template and Recipient Groups ..................................................95
Loading messaging specification files .............................................................................................97
Raise message event.........................................................................................................................99
Additional APIs provided by MESSAGING service .....................................................................100
delSelectedAlerts ....................................................................................................................100
Web UI ..................................................................................................................................................100
Configure UI ..................................................................................................................................100
Search Alerts ..................................................................................................................................101
Remove Alerts................................................................................................................................102
Alert Details ...................................................................................................................................102
Index ........................................................................................................... 105
Agile Business Process Platform 3 Programmers Reference Revision A vii

Contents
viii Agile Business Process Platform 3 Programmers Reference Revision A

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

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

z About this Book
z Related Documentation
z If You Need Assistance
z Give Us Feedback
z For the Latest Documentation
About i2 Agile Business Process Platform 3

Programmers Reference
Current businesses more so than ever before, are experiencing tremendous
competitive pressures and changes. Business processes are being outsourced rapidly
and new alliances, partnerships and mergers are happening at a tremendous pace. In
this highly volatile environment the IT and data management systems are being
stretched to their limit. Most of them have been built with a fixed business process in
mind and are inflexible to the kind of change that they are being subject to in today’s
economy. Under these circumstances companies are looking for a solution that would
have the following capabilities:
z An architecture that would allow leveraging existing legacy systems till the time
when they can be replaced or enhanced
z An architecture that would allow rapid prototyping of business ideas to see the
end result in days and months rather than years
Agile Business Process Platform 3 Programmers Reference Revision A ix

Preface
z An architecture that allows a business user to be able to define and adjust process
flows more rapidly rather than having to depend on tech savvy people
z An architecture that can string multiple disparate applications to provide a
business process flow rather than having to rewrite all the individual applications
on a single technology or with a single vendor.
z An architecture that provides for data synchronization and data harmonization
across the myriad of systems that are in place
i2’s Agile Business Process Platform (ABPP) has been built with the above mentioned
objectives in mind. It enables a business user to interact with the system at a business
abstraction through a graphical integrated development environment and an intuitive
scripting language to express business rules. It provides several pre-built constructs
(such as Approval nodes, Data Upload, Data Profiling, etc) that allow a user to
quickly prototype a business process without having to worry about the nitty-gritty
associated with generic application building software. It also allows a user to define
all aspects of an application in one single environment starting from data model
definition, process workflows, business rules and validations all the way to user
interface design and integration design.
For information on other i2 solutions, contact your i2 sales representative.
x Agile Business Process Platform 3 Programmers Reference Revision A

Preface
About this Book

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

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

This book has the following chapters.
z Chapter 1 “Timer Service” on page 1. This chapter gives you information on
Timer Service in ABPP.
z Chapter 2 “Approval Service” on page 13. This chapter gives you information
about the Approval Service.
z Chapter 3 “Data Upload” on page 29.This document details the features of
Dataupload service that is packaged with ABPP.
z Chapter 4 “Task Scheduler Service” on page 49. This chapter gives you an
introduction to The Task scheduler component and how to use.
z Chapter 5 “Email Service” on page 75. This chapter helps you get started using
the email service.
z Chapter 6 “Messaging Service” on page 83. This chapter gives you the messaging
component that is integrated into the application.
Conventions
Table 1 lists examples of the typographic conventions used to display different types
of information in this document.
Table 1 Typographic conventions used in this document
Item Example Explanation
Code Call NotifyPending; File names, executable code,

commands, and configuration
statements are shown in monospaced
font.
Class Names Make the Class Configurations Class names appear in bold.
pointer in the Module
Configuration class a primary
key.
Interface element Click Organization Management Button names, field names, window
in the toolbar. names are shown in a san-serif font.
Agile Business Process Platform 3 Programmers Reference Revision A xi

Preface
Item Example Explanation
Pathname C:\i261\webdriver Windows pathnames are shown in

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

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

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

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

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

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

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

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

Preface
For the Latest Documentation

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

Preface
xvi Agile Business Process Platform 3 Programmers Reference Revision A

Chapter 1
Timer Service
This chapter gives you information on Timer Service in ABPP. It includes the
following topics.
Topics:
z “Introduction”
z “Timer setup and callback”
z “Deployment”
z “Configuration of timer poll interval”
z “Timer commands”
z “Guaranteed Messaging”
Introduction
Timer service allows one to perform specified actions at a specified time. It also
allows one to specify a duration at which the timer should repeat these actions. It
provides a collection of functions and tags to perform the timer related activities.
Using the timer feature is a two step process:
1. Setup a timer in the system with a callback time and specify callback actions that
need to be executed when the callback time is reached. ABPP provides
START_TIMER command for this. This results in ABPP server adding timer
record to the database.
2. The Timer Sink runs as a service (TIMER_SINK) on the ABPP server and takes
care of monitoring the timer entries for expired timers and executing the specified
callback actions. It also takes care of repeating the call after the specified duration
if so specified in START_TIMER.
Agile Business Process Platform 3 Programmers Reference Revision A 1

Chapter 1 Timer Service
Timer setup and callback

Services can define a timer by specifying the timer name, call back time, call back
actions and optionally a document or a duration after which it should repeat the call.
This gets persisted as a timer record in the database with a calculated expiration date.
The timer sink service polls the database periodically to select timer records that have
expired. The interval at which the service polls the database is configurable. For every
selected expired timer record, the timer service marks a claim date. This prevents
another timer sink service of another ABPP server, to act upon the expired records.
For each of these timer records, callback actions are executed.
z For a simple timer callback request, the service attempts callback once and then
removes the timer record from the database.
z For a durational timer, the expiration date is incremented using the duration that is
specified and the timer record in the database updated.
To define timers, delete timers or to get an existing timer details, timer commands are
used.
Deployment
In a typical deployment there can be multiple ABPP Servers. Each of these servers
should be homogeneously deployed with multiple Xservices. Each of the ABPP
Server can have a timer source component and a timer sink component. In such a
scenario there will be multiple timer services running across different ABPP Servers.
When a service in one ABPP Server starts a timer job, the ABPP server will persist the
job as a timer record in the database. Whenever this job is due to be run, any of the
timer sink services across ABPP servers can pick up this job and act on it. So, timer
callback actions can be executed in an ABPP Server instance that is not the one that
initiated it. This design helps achieve high availablity for the timer function.
Configuration of timer poll interval

There are 2 ways to configure a timer poll interval
1. In timersink.xml, the property file for the timer sink service, you can change the
value specified and then bring up the ABPP server.
<service-params>
<param Value="40" Name="TIMER_SLEEP_TIME" Comment="Specify
sleep time in seconds"/>
</service-params>
2. Through command line utility on the ABPP server console at runtime.
xcore>GetTimerFreq
This will return the timer poll that is currently set to the specified interval in
seconds.
xcore>SetTimerFreq 500
This will change the timer poll that is currently set, to the specified interval in
seconds.
2 Agile Business Process Platform 3 Programmers Reference Revision A

Timer commands
Timer commands
START_TIMER
Description :
It adds a timer record to the database. Each timer record contains the following key
elements:
Identifier: This is specified by a set of key-value pairs. The key-value pairs are
enclosed within IDENTIFIED_BY tag. The identifier needs to passed in to Stop
Timer command to remove the timer entry created by this command. This identifier
will be made available (as identifiedByDoc variable) whenever the call back actions
are invoked
Example:
<IDENTIFIED_BY>
<OrderId Value="C-1" />
<Type Value="creditCheckTimer"/>
</IDENTIFIED_BY>
In the above example, the timer entry is identified by the values for the keys - OrderId
and Type
For Document: This encapsulates the context on which the timer is acting.This is a
place-holder to associate any xml document along with the timer entry.
Example: You might want to create a timer to perform credit check on an order at a
future time. The credit check logic (triggered on the timer call back) might require
some information (Customer associated with the order, Order Value etc) on the order
to perform its logic. You can store this information along with the timer entry. This
information will be made available (as thisDoc variable) whenever the call back
actions are invoked.
Example:
<FOR_DOCUMENT>
<Order>
<ID Value="C-1" />
<Customer Value="Velocity" />
<OrderValue Value="100000" />
</Order>
</FOR_DOCUMENT>
Note: The actual information is enclosed within FOR_DOCUMENT tag. This

information does not have any relation to X-Document. It can be any xml you
want to associate with the timer entry.
Call Back Date: This is the date on which the the call back actions should be
executed. This can be specified in one of the 2 ways:
z A date time specified by CALL_BACK_DATE tag. After the current time
exceeds the specified time:

| The call back actions are executed.

| The timer entry is expired.
z A duration with a start and end time. The call back actions will be executed
continuously from the start time until the end time with the frequency specified by
the duration. After the current time exceeds the end time, the timer entry is
expired. In this scenario, the call back actions may be invoked multiple times
before the timer entry is expired. The start time, end time and duration are
specified by tags CALLBACK_START_DATE, CALLBACK_END_DATE and
CALLBACK_DURATION respectively. The duration is specified in seconds. So
it does not account for any DST correction. However you can provide
DstDuration instead of the duration using CALLBACK_DST_DURATION. The
DstDuration will ensure that time increments for days account for any applicable
DST correction. The dstDuration X-Path function can be used for specifying
DstDuration.
Call Back Actions: This is the X-Rule actions to be executed when the timer wakes
up.The X-Rule actions are enclosed within the CALLBACK_ACTIONS tag.
Only the following implicit variables can be referenced within the call back actions:
z thisDoc : This is a reference to the xml document contained within the
<FOR_DOCUMENT> tag of the START_TIMER.
z identifiedByDoc : This is the identifier. This is the reference to the
<IDENTIFIED_BY> xml of the START_TIMER
z callBackDateVar : This is a special variable that contains the current call back date
time.
Example:
<CALL_BACK_ACTIONS>
<PRINTLN Value="Call back date time is {$callBackDateVar}"/>
</CALL_BACK_ACTIONS>
Note: Only the implicit variables specified above are visible within the scope of the
CALLBACK_ACTIONS tag.
Syntax:
<START_TIMER>

<IDENTIFIED_BY>
<key-name Value="value" Repeatable="true"/>
</IDENTIFIED_BY>

<FOR_DOCUMENT>

<CustomerOrder>
<ID Value="CO-1" />
</CustomerOrder>
</FOR_DOCUMENT>
<CHOICE_OF>
<CHOOSE>

Timer commands
<CHOICE_OF>
<CHOOSE>

<CALLBACK_DURATION Value="{duration(0,1,30,0)}" />
</CHOOSE>
<CHOOSE>

<CALLBACK_DST_DURATION
Value="{dstDuration(1,1,30,0)}" />
</CHOOSE>
</CHOICE_OF>

<CALLBACK_START_DATE Value="01/01/2000[Type=datetime,
Optional=true]" />

<CALLBACK_END_DATE Value="01/01/2006[Type=datetime,
Optional=true]" />
</CHOOSE>
<CHOOSE>

<CALLBACK_DATE Value="01/01/2005[Type=datetime]" />
</CHOOSE>
</CHOICE_OF>

<CALLBACK_ACTIONS>

<PRINTLN Value="thisDoc Variable = {$thisDoc}" />
<PRINTLN Value="Identifier Variable = {$identifiedDoc}" />
<PRINTLN Value="Current Expiration Date = {$callBackDateVar}" /
</CALLBACK_ACTIONS>
</START_TIMER>
Example 1:
Description :
The following example defines a timer with name SIMPLE_TIMER . It asks to call
back after six hours. When it calls back it prints the date time and calls doSomething
request.
<DEFINE_METHOD Name="startSimpleTimer">
<RULE>
<ACTION>
<START_TIMER>
<IDENTIFIED_BY>
<NAME Value="SIMPLE_TIMER" />
</IDENTIFIED_BY>
<CALLBACK_DATE Value="{incrDate(date(),duration (0, 6,
0,0))}" />
<CALLBACK_ACTIONS>
<PRINTLN Value="Call back date time is:
{$callBackDateVar}" />

<REQUEST Name="doSomething" />

</CALLBACK_ACTIONS>
</START_TIMER>
</ACTION>
</RULE>
</DEFINE_METHOD>
Example 2:
Description :
The following example starts a timer. The timer call back starts the following day and
repeats every hour until the end of the day. On each call back, the parameters for the
call back are printed and the myRequest X-Rule is executed.
<DEFINE_METHOD Name="startCreditTimer1">
<RULE>
<ACTION>
<START_TIMER>
<IDENTIFIED_BY>
<NAME Value="CreditCheckTimer" />
</IDENTIFIED_BY>
<FOR_DOCUMENT>
<Customer>
<ID Value="{$thisParam/ID/@Value}" />
</Customer>
</FOR_DOCUMENT>
<CALLBACK_START_DATE
Value="{incrDate(stripTime(date()), duration(1,0,0,0)}" />
<CALLBACK_DURATION Value="{duration(0,1,0,0)}" />
<CALLBACK_END_DATE Value="{incrDate(stripTime(date()),
duration(2,0,0,0)}" />
<CALLBACK_ACTIONS>
<PRINTLN Value="{$identifiedDoc}" />
<PRINTLN Value="{$thisDoc}" />
<REQUEST Name="myRequest">
<TO_XML DocVar="thisDoc" />
</REQUEST>
</CALLBACK_ACTIONS>
</START_TIMER>
</ACTION>
</RULE>
</DEFINE_METHOD>
When the callback is invoked,

identifiedDoc will point to the following xml:
<IDENTIFIED_BY>
</IDENTIFIED_BY>
thisDoc will point to the following xml:

<Customer>
<ID Value="Velocity" />
</Customer>
The Value attribute of ID is the same as the ID contained in the input to the
startCreditTimer1 X-Rule.

Timer commands
Note: In this example, we are using the duration function to compute the call back
start and end dates. The duration function assumes the days argument to mean
24 hours. Hence this does not account for DST adjustments. So the call back
may not start at the 00 hrs:00 min:00 secof the following day. Similarly it may
not end at 11 hrs:59 min:59 sec of the following day.
Example 3:
Description :
This example is similar to the previous one. It shows the usage of DstDuration to
account for DST adjustment. The timer call back is invoked at 00:00:000 hrs for the
next 7 days starting from tommorrow.
<DEFINE_METHOD Name="startCreditTimer1">
<RULE>
<ACTION>
<START_TIMER>
<IDENTIFIED_BY>
</IDENTIFIED_BY>
<FOR_DOCUMENT>
<Customer>
<ID Value="{$thisParam/ID/@Value}" />
</Customer>
</FOR_DOCUMENT>
<CALLBACK_START_DATE
Value="{incrDate(stripTime(date()), dstDuration(1,0,0,0)}" />
<CALLBACK_DST_DURATION Value="{dstDuration(1,0,0,0)}" /
>
<CALLBACK_END_DATE Value="{incrDate(stripTime(date()),
dstDuration(7,0,0,0)}" />
<CALLBACK_ACTIONS>
<PRINTLN Value="{$identifiedDoc}" />
<PRINTLN Value="{$thisDoc}" />
<REQUEST Name="myRequest">
<TO_XML DocVar="thisDoc" />
</REQUEST>
</CALLBACK_ACTIONS>
</START_TIMER>
</ACTION>
</RULE>
</DEFINE_METHOD>
STOP_TIMER
Description :
Deletes the timer record identified by the key-value pairs contained within the
IDENTIFIED_BY tag.
Syntax
<STOP_TIMER>
<IDENTIFIED_BY>
<key-name Value="value" Repeatable="true" />

</IDENTIFIED_BY>
</STOP_TIMER>

Example 1:
Description :
The following example will delete the timer entry corresponding to the ones created in
examples 2 and 3 of the START_TIMER command. The timer entry to be deleted is
identified by the key-value pairs: key=NAME and Value=CreditCheckTimer.
<DEFINE_METHOD Name="stopCreditCheckTimer">
<RULE>
<ACTION>
<STOP_TIMER>
<IDENTIFIED_BY>
</IDENTIFIED_BY>
</STOP_TIMER>
</ACTION>
</RULE>
</DEFINE_METHOD>
Guaranteed Messaging
Guaranteed Messaging is an extension of the timer service and provides a way to
make guaranteed call to a rule defined in ABPP. The guaranteed call can be
configured so that if for some reason the call fails the system can retry the call at a
later time.
The guaranteed call will be an asynchronous call (if guarantee level is High) i.e. it will
be invoked using a different transaction only if the current transaction commits. This
is useful when the ABPP server needs to call external systems only if the originating
transaction succeeds. In such situations the call to the external system can be
encapsulated in an ABPP rule and then the ABPP rule invoked using guaranteed
messaging.
A guaranteed message request is defined as follows in the rule. It has the following
components.
z Guaranteed Request invocation (<GUARANTEED_REQUEST>)
| Specifies the request to be of type guaranteed.
| Specifies the API that needs to be invoked.
| Specifies the service that this API is registered with.
z Header (<HEADER>)
| Specifies the parameters that the Timer Service will use.
| Specifies the mandatory message key, which can be any user defined string
(MSG_KEY).
| Specifies the number of retry attempts, default value being one
(NUM_RETRIES).
| Specifies the retry interval, default being zero (RETRY_INTERVAL).
| Specifies the start date when the API is to be called first (START_DATE).
| Specifies the result determining rule (RESULT_DETERMINER).

| Specifies the guarantee level (High or Low. Default is High)

(GUARANTEE_LEVEL).
z Body (<BODY>)
| Content to be sent to the API.
z On Success actions (<ON_SUCCESS>)
| Optional actions to be executed on a successfull delivery.
z On Failure actions (<ON_FAILURE>)
| Optional actions to be executed on failure, after the specified number of retry
attempts.
If guarantee level is set to "Low ", then the message delivery is attempted once before
the guarantee request is persisted as a timer entry. So, the message delivery works in a
semi-guaranteed fashion.
Note: Use semi-guaranteed messaging only if you are certain that you are willing to
take the chance of losing a message.
Example 1:
Description :
Example of setting up a guaranteed message. Once the message has been setup, the
timer sink service will attempt delivery of this message. If the attempt is successful, it
will execute the actions listed under ON_SUCCESS . If the delivery attempts fail,
then the message is re-tried for a maximum of the specified number of retry times. If
all attempts fail, then the ON_FAILURE actions are executed.
<DEFINE_METHOD Name="executeGuaranteedMsg">
<RULE>
<ACTION>
<GUARANTEED_REQUEST Name="callDummyExternalApi"
ServiceName="DUMMY">
<HEADER>
<MSG_KEY Value="{$thisParam/ID/@Value}"/>

<NUM_RETRIES Value="{$thisParam/NUM_RETRIES
/@Value}"/>

<RETRY_INTERVAL Value="{duration(0, 0, 0,
$thisParam/RETRY_SECONDS/@Value)}"/>

<START_DATE Value="{incrDate(date(),
duration(0,0,0,20))}"/>

<RESULT_DETERMINER Rule="resultDeterminer"/>


<GUARANTEE_LEVEL Value="High"/>

</HEADER>
<BODY>
<ORDER Value="1">
<LINE Value="{sum(1, 0)}"/>
</ORDER>
<ORDER Value="2">
</ORDER>
</BODY>
<ON_SUCCESS>
<PRINTLN Value="This is the thisDoc for msg
{$thisDoc/@Name}"/>
<PRINTLN Select="$thisDoc"/>
<REQUEST Name="CallbackGMsgSuccess">
<TO_XML DocVar="thisDoc"/>
<ON Value="Success"/>
</REQUEST>
</ON_SUCCESS>
<ON_FAILURE>
<ADD_DEAD_LETTER>
</ADD_DEAD_LETTER>
<REQUEST Name="CallbackGMsgFailure"
<ON Value="Failure"/>
</REQUEST>
</ON_FAILURE>
</GUARANTEED_REQUEST>
</ACTION>
</RULE>
</DEFINE_METHOD>

Success-failure Determination
When the message delivery is attempted, success is determined by the response from
the invocation. An exception that occurs or an indication of failure is considered a
failure.
Users can optionally specify a result determining rule. If this rule is specified, the rule
is invoked right after an attempted delivery with the guaranteed message request data
as parameter to this rule. The format of this input is in the next section. The rule then
will have to indicate success or failure in the format specified below.

<REQUEST Name="callDummyExternalApi" ServiceName="DUMMY">
<ORDER Value="1">
<LINE Value="1.0"/>
<LINE Value="2.0"/>
</ORDER>
<ORDER Value="2">
<LINE Value="2.0"/>
<LINE Value="3.0"/>
</ORDER>
</REQUEST>

<RESPONSE Status="Success">
<_RESULT Value="SUCCESS"/>
</RESPONSE>

<_RESULT Value="FAILURE"/>
</RESPONSE>
OR
<RESPONSE Status="Error">
<SOME_ EXCEPTION_TRACE/>
</RESPONSE>
The on success and on failure actions will have access to variable thisDoc that will
have the following.
The reply section contains the response from the API invoked.
<GUARANTEED_REQUEST Name="callDummyExternalApi"
<HEADER>
<IDENTIFIED_BY>
<MSG_KEY Value="101010"/>

<REQUEST_NAME Value="callDummyExternalApi"/>
</IDENTIFIED_BY>
<NUM_RETRIES Value="2"/>
<RETRY_INTERVAL Value="65"/>
<START_DATE Value="10/31/2003 16:41:42:143"/>
<MSG_KEY Value="101010"/>
<END_DATE Value="10/31/2003 16:43:52:143"/>
<LAST_ATTEMPTED_DELIVERY_DATE Value="10/31/2003 16:41:48:921"/>
<CURR_RETRY_COUNT Value="1"/>
</HEADER>
<BODY>
<ORDER Value="1">
<LINE Value="1.0"/>
<LINE Value="2.0"/>
</ORDER>
<ORDER Value="2">
<LINE Value="2.0"/>
<LINE Value="3.0"/>
</ORDER>
</BODY>
<REPLY>
<_RESULT Value="SUCCESS"/>
<EXT_API_RESPONSE Value="SOME_DATA"/>
</RESPONSE>
</REPLY>
</GUARANTEED_REQUEST>

Chapter 2
Approval Service
This chapter gives you information about the Approval Service. It includes the
following topics.
Topics:
z Introduction
z Approval Nodes
z Serial Approval Node
z Parallel Approval Node
z Multi-line Approval node
z Approval Node Execution
z Input/Output to Approval UI workflows
z Configuring & Managing Approval Alerts
z Steps for creating an Approval Workflow
Introduction
Approval Workflow framework is used to define and manage approval business
process. Here is an examples of approvals required in a business process:
New Part Introduction:
Typically in a factory, finished products are manufactured from different raw
materials. The raw materials are referred to as parts. Once in a while, an existing part
is replaced with new part to meet objectives such as improved manufacturing
efficiency, lower cost, increased durability of the finished product etc.
Introducing a new part in to the manufacturing process typically requires various
departments within the factory to consider the implications of the change. For
example,
z Engineering department has to decide if the new part will require additional
tooling and changes to the existing manufacturing process.

Chapter 2 Approval Service
z Quality control department has to evaluate if any changes have to be made to the
existing inspection procedures to accomodate this change.
z Purchasing department has to evaluate which suppliers to contract for procuring
the new part.
z Accounting department has to consider the overall cost benefit from this change.
After considering the implication, each department can either approve or reject the
change. The new part can be introduced if all the relevant departments approve this
change. The approval process may require orchestration in a particular sequence.
For example,
z Engineering and Purchasing departments can approve in parallel.
z Quality Control department has to get the inputs from Engineering before it can
provide its recommendation. So it can approve only after the Engineering
department.
z Accounting department requires all other departments to approve before
providing its recommendation.
Approval Framework allows you to model approval business processes similar to the
one descibed above. The approval framework provides special purpose approval
workflow nodes for:
z Notifying approvers through email and on-line alerts when there is an approval
request waiting on their input
z Enabling approvers to provide their input. Typically the input is to either approve
or reject the approval request. Approval framework allows specifying a user
interface workflow for each of the approval nodes. This user interface workflow
will be launched when the approver tries to act on the on-line alert associated with
the approval node. The approver can provide his input by clicking the relevant
buttons ( Approve, Reject etc) on the user interface workflow.
The approval workflow nodes can be used within any standard workflow in ABPP.
The workflow can be used to define the order in which each of the individual
approvals should take place in the overall approval process.
Approval framework publishes its dependency on user security and alerting

infrastructure as interfaces. The approval frame-work can be plugged in with any user
security and alert infrastructure if the interfaces are implemented.
Approval framework is a tool kit and hence can be used to model various types of
approval processes including:
z New Part Introduction - Process for introducing a new part into the Approved
Product Catalog
z New Supplier Introduction - Process for introducing a new Supplier into the
Approved Supplier Catalog
z Suggested Orders - Process for requesting a Purchase

Approval Nodes
z Purchase Order - Process for Draft PO verification

z Purchase Order Change Notice - Process for Change Notices to make
amendments to the PO
z Project Approvals - Process for creating Budget based Projects
z Project Expenditures - Process for validating expenditures on Projects
z Price Variance - Process across Buying and Supplying Organizations on Price
changes for an item or PO
z Quantity Variance - Process across Buying and Supplying Organizations on
Quantity changes for an item or PO
Approval Nodes
Approval framework provides three special nodes for handling approvals- Serial,
Parallel and Multi-line approval nodes.
Common Approval Node Properties

All of the approval nodes share a lot of common characteristics. Here are some of the
important ones:
z All of the nodes work on a document which is identified by an Id and type.
Example: the approval is for a Purchase Order type with an id of P101.
z All Approval nodes allow approvers to perform Approve and Reject actions.
z All of them provide configuration to enable forwarding or consulting the approval
with other users.
z Any Approval node execution will ultimately result in a approval result of either
Approved or Rejected.
z You can wire the next nodes of any approval node conditionally depending on the
approval outcome (Approved or Rejected) of the node.
This section describes the properties common across all the approval nodes. The
following picture is that of serial approval node. However our discussion will be
confined to the common properties.

Serial Approval node property editor

Here is the description of the common properties:
z Name: name of the node
z Description: brief description
z Node input / Type (Optional): name and type of input variable
z Node output (Approved)/ Type (Optional): name and type of output variable for
the next nodes associated with Approved result
z Node output (Rejected)/ Type (Optional): name and type of output variable for
the next nodes associated with Rejected result.
z Settings: This panel contains the approval properties. The approval properties are
described below.
z Approval UI Workflow: The name of the UI workflow to be launched when the
approver wants to view and perform the approval actions. The details on how this
workflow interacts with Alerts and Approval Node is described in a separate
section.
z Approval UI Service: the ABPP service that contains the approval UI workflow

Approval Nodes
z Approver ID List: X-Path expression evaluating to an XML containing the set of

Approver Id’s for this node. The structure of the XML should match the example
shown below for serial and parallel approval nodes.
<root>
<Id Value=”1”/>
<Id Value=”2”/>
</root>
In case of serial approval, the approvers work on the approval in the same order as
they appear in the list. Example: After the first approver in the list approves, the
second approver in the list works on the approval etc.
The format of the xml is different for multi-line approval node. Please see multi-
line approval node properties for details.
z Document Id: The Document Identifier for the document being run through the
Approval Process. Example: The Id of the part in a New Part Request (NPR)
approval process. The Approval Service does not check for the uniqueness of this
Id. This is just for the developer to use. Typically this property will be an X-Path
expression that will evaluate to a string.
z Document Type: This indicates the type of the Document being used in the
Approval Workflow. Example: The document type would be Part in a NPR
approval process. The Approval Service is not aware of and does not define the
types of documents possible. This is just for the developer to use. This property
can be an X-Path expression that will evaluate to a string.
z Alert Object (Optional): If provided, this X-Path expression should evaluate to
an xml. This xml will be passed to the alert events invoked by the Approval
Service. The alert events are described in a later section. Alert Object can be used
as a placeholder for any variables etc. which are defined in the Approval
Workflow but are required when creating the alerts for the approval requests.
z Consult Allowed: This check box indicates if the Approver is allowed to consult
another Approver for the approval assigned to him. For the consulted approver,
only respond action is permitted. The original approver can act on the approval
after the consulted approver responds with his comments.
z Forward Allowed: This checkbox indicates if the Approver is allowed to forward
the approval to another approver. Upon forwarding, the original approver gives
away all rights to the forwarded approver.
z PreActions: X-Rule actions. These actions are executed when the workflow
initially reaches the node. All the property X-Path expressions (Alert Object,
Approver List etc.) are evaluated after the pre-actions are executed. The typical
use of pre-action would be to compute the list of approvers for this node and
assign it to the variable referenced in the X-Path expression for Approver List
property.
z PostActions (Optional): X-Rule actions. These actions are executed after
approvals have been completed for the node. The approval result (Approved or
Rejected) can be accessed through the implicit variable, approvalResult in the
post actions. The node output for Approved/Rejected next nodes will be evaluated
after executing the post actions. The typical use of post actions would be to

perform any post approval tasks. After the post actions, the workflow will
continue executing the next nodes depending on the approval result.
z On Approver Response Actions (Optional): X-Rule actions. These actions are
executed whenever an approver performs an approval action. Examples of
approval actions are: Approve, Reject, Hold etc. performed by an approver. An
implicit variable, approvalContext is also available for use within these actions.
The payload of this variable is the same as that of expediteApprovalAlert event for
Expedite action. For all other actions, the payload is same as that of
modifyApprovalAlert event. Please see the section on Approval events for details
on these events. These actions act as an user exit to execute some X-Rule actions
whenever an approver performs an approval action.
Serial Approval Node

A serial approval node is used when a number of approvals are required “in serial” (or,
“one after another”). For example, perhaps a manager must approve an action first,
then a finance manager, and finally a vice president. If the approvals must happen in a
fixed order, a serial approval node is the mechanism to use.
In this section we only focus on the properties unique to the serial approval node. The
common properties are discussed in the Common Approval Node Properties section.
The property editor for a serial approval node is the following:

Approval Nodes
Serial Approval node property editor

Here is the description of the serial node specific properties:
z Expedite Allowed: This parameter indicates if the approver who comes further in
the approval chain can choose to bypass the requests before him and approve the
the approval request.
z Approver ID List: Please see the Approver ID List property described in
Common Approval Node Properties section. The approvers work on the approval
in the same order as they appear in the list. Example: After the first approver in
the list approves, the second approver in the list works on the approval etc.
Parallel Approval Node

In contrast to a serial approval node, a parallel approval node does not require the
approvals to be done in any particular order. All approvals can be gained “in parallel”
(or, “at the same time”) from the approvers. The node can be configured to require
approval from all the approvers or from any one approver. Once the approvals have
been gained, the workflow continues to the next node(s).
This section focuses only on the properties specific to parallel approval node. The
common properties are described in the Common Approval Node Properties
section.The property editor for a parallel approval node is the following:

Parallel Approval node property editor

Here is the description of the parallel approval node specific properties:
z All Required to Approve: This parameter indicates if all the approvers are
required to approve a request or only one approver in the list is required.
z Hold Allowed: This parameter indicates if the Hold action is allowed by the
Approver on the request. If the request is put on hold, then no further actions are
possible on the node by the other parallel approvers of this node.
z Override Hold Allowed: This parameter indicates if an approver can override the
hold state placed on the approval by another approver.
Multi-line Approval node

A multiline approval node is used when a particular document has multiple portions
that require different approvals. For example, perhaps your workflow is for processing
a customer order. Perhaps the bill-to address must be approved by the bill-to manager,
and each order line item must be approved by the fulfillment center for each item
SKU. If such an approval process is required, a multiline approval node is the
appropriate mechanism to use.
This node is a combination of the serial and parallel approval node. The approval
request goes through parallel paths for each document line (and optionally the header)
which in turn are run serially for the list of different approvers for each line in the
document.
This section focuses only on the properties specific to multiline approval node. The
common properties are described in the Common Approval Node Properties
section.The property editor for a multiline approval node is the following:

Approval Nodes
Multi-line Approval node property editor

Here is the description of the properties:
z Approver ID List: X-Path expression evaluating to an XML containing the set of
Approver Id’s for this node. This variable has to be of type XML. Its structure
should match the examples shown.
<root>
<Line Id="@">
<Id Value="1"/>
<Id Value="2"/>
</Line>
<Line Id="1">
<Id Value="3"/>
<Id Value="4"/>
</Line>
</root>
z Line tag with Id attribute value of “@” is used in the Multiline Node for to specify
that the approval list is for the document header approval. This is needed only if
the document header requires approval. The other line tags represent the lines that
make up the Multiline Node. The approvers for each line work on the approval in
the same order as they appear in the list. Example: After the first approver in the
list for a line approves, the second approver in the list works on the approval line
etc.

z Reject at Line applies to Document: This parameter indicates (in a Multiline

Approval Node) if a reject on a line applies to the document as a whole. If yes,
then document is rejected on any rejection on any line. If no, then after all actions
are completed on all the lines, the developer can query as to which lines were
approved and which were rejected.
z Document Requires Approval: This parameter indicates (in a Multiline
Approval Node) if the document header also requires approval.
z Expedite Allowed: Each of the line approvals in a Multiline Node follows a serial
approval process. This parameter indicates if the approver for a line who comes
further in the approval chain can choose to bypass the approvals before him and
approve the line.
z Hold Allowed: This parameter indicates if the Hold action is allowed by the
Approver on the request. If the request is put on hold, then no further actions are
possible on the node by the current or any other approver
Approval Node Execution

Here is the typical execution of a approval node:
Starting the approval

z When the workflow execution enters the approval node, pre actions will be
executed. Typically the pre actions will compute the approver list.
z All the approval node properties specified in the settings panel will be evaluated.
At this point of time the approval node has access to document id, document type,
list of approvers and node configurations for consult, forward etc.
z The approval node will raise events providing information necessary to create
active alert entries (‘createApprovalAlert’ event) for the approvers in the approval
list. If the approval node allows expedite then the approval node will raise
‘createPendingApprovalAlert’ event for the creation of future alerts. A future
approver can expedite the approval request by acting on the future alert. The alert
events are defined in the APPROVAL service. Look at approval_events.xml in the
APPROVAL service for the payload of all the approval alert events.
z The listeners associated with alert events will create alert entries and notify the
approvers through e-mails. It is responsibility of the application using the alert
infrastructure to implement the listeners for alert events and manage the alerts as
part of the listener implementation.
z Each approver identified in the alert events is associated with a token. The token
allows the approval framework to uniquely identify the approval context when the
approver interacts with the approval infrastructure. So the token should also be
persisted as part of the alert entry.
Performing Approver Action

z The approver logs on to the system and views his alert entries. Typically the user
expresses his intent to act on the approval alert by clicking on a hyper link on the

Approval Node Execution
alert or by selecting the alert and clicking a button. At this point the application
should invoke the “activateApprovalNode” command on the APPROVAL service
passing
| Token associated with the alert
| Approver’s user id.
| Return URL. The approver will be taken to this URL after he has processed
the approval. In most cases the return URL will be the URL of the alert in-box
page from which the user launched the activation.
Please see Approval Node Activation section for the payload of
activateApprovalNode command.
z The approval framework retrieves the approval context (approval workflow
instance and approval node information) from the token. It launches the UI
workflow associated with the approval node. The approval framework provides
the UI workflow with the approval node properties provided in the settings panel
and the list of approval actions that are allowed for that approver. The input/output
to the UI workflow is described in Input/Output to Approval UI workflows
section.
z The UI workflow renders the approval document and the displays the buttons for
performing the approval actions - Approve, Reject etc. It is the responsibility of
the approval workflow author to create the UI workflow and associate it with the
approval node. The same UI workflow can be reused across multiple approval
nodes. The UI workflow should also provide the screens for choosing the consult
and forward users if these features are enabled on the approval node.
z The user performs an approval action by clicking on one of the buttons on the UI
workflow page. At this point, the UI workflow should pass the following
information in its thisReturn variable:
| Token associated with the alert
| Approval action performed
| Approver Comments
| Consult or Forward Approver’s user id in case of consult or forward actions
z Approval framework gets the result of the approver action through the return
variable (thisReturn) of the UI workflow. It will process the approver action.
z The approver will be redirected to the return URL provided as part of the
activateApprovalNode command.
Processing Approver Action

The approval framework will perform the following as part of processing the approver
action:
z Raise recordApprovalHistory event. This event contains the The application using
the alert infrastructure should provide listeners to this event and persist the
approval history. Look at approval_events.xml in the approval service for the
payload of this event.
z Determine the next approver in the node.

z Raise ‘modifyApprovalAlert’ event for all approver actions other than expedite.
The event payload providing information on the current approver, approval status,
the approver action and the next approver (if any).The listener to this event should
perform the necessary actions to manage the alert entries. Typically this will
involve deleting the alert entry for the current user and creating an active alert for
the next approver.
z Raise ‘expediteApprovalAlert’ event for the expedite action. This event contains
information on the expedited users in addition to the information contained by the
payload of the ‘modifyApprovalAlert’ event. The listener to this event should clear
the alert entries for the expedited users in addition to the processing done for a
‘modifyApprovalAlert’ event listener. Note that ‘modifyApprovalEvent’ event is
NOT raised for an expedite event.
z Invoke the “On Approver Response Actions” provided on the approval node. The
approval framework will provide an implicit variable, approvalContext, providing
the approval context. The payload of the approvalContext variable is same as that
of the payload of modifyApprovalAlert event.
z If there are no next approvers in the node then the approval frame-work
determines the result of the approval.
z Raise ‘removeApprovalAlert’ event. The listener to this event should remove all
the alert entries associated with the approval node.
z Invoke the “PostActions” provided on the approval node. The implicit variable,
approvalResult, contains the approval result and is visible in the post actions. The
valid values for approval result are APPROVED and REJECTED.
z If the approval result is APPROVED, the execution passes on to the next nodes of
the approval node associated with this outcome.
z If the approval result is REJECTED, the execution passes on to the next nodes of
the approval node associated with this outcome.
Input/Output to Approval UI workflows

Please refer to Approval Node Execution section to understand how Approval UI’s are
launched in the over all approval flow.
Here is a sample input to the approval UI workflow. The input can be accessed
through thisParam variable in the start node of the UI workflow.
<ADDITIONAL_PARAMETERS>
<CURRENT_PARAMS>
<REQUEST Name="activateApprovalNode">
<TokenId Value="xyz" />
<ActingUserId Value="jwright" />
<REDIRECT_URL Value="http://localhost:7001/base/
start.x2ps?START_WORKFLOW=UI_MyCurrentAlerts&SERVICE_NAME=M
yService" />
</REQUEST>
</CURRENT_PARAMS>
<APPROVAL_NODE_CONTEXT>
<DocumentId Value="5111154358183352" />
<DocumentType Value="NPR" />

Configuring & Managing Approval Alerts
<AlertObject>
<ANY />
</AlertObject>
<ApproverIdList>
<root>
<Id Value="gnorman" />
<Id Value="jwright" />
</root>
</ApproverIdList>
<DocumentLineIdStatusList>
<ANY />
</DocumentLineIdStatusList>
<ApprovalResult Value="PENDING" />
<AllowedActions>
<Approve Value="true|false" />
<Reject Value="true|false" />
<Consult Value="true|false" />
<Respond Value="true|false" />
<Hold Value="true|false" />
<Forward Value="true|false" />
<Expedite Value="true|false" />
</AllowedActions>
</APPROVAL_NODE_CONTEXT>
</ADDITIONAL_PARAMETERS>
The CURRENT_PARAMS tag contains the contents of the activateApprovalNode

command that triggered the launch of the UI Workflow.
The APPROVAL_NODE_CONTEXT tag contains the values of the approval node
properties provided in the settings panel. It also contains AllowedActions tag which
lists the approval action the approver is allowed to perform.
The thisReturn variable of the UI Workflow should have the following contents:
For consult and forward actions,
<RESPONSE>
<ApproverResult Value="CONSULT|FORWARD" />
<ApproverComment Value="abc" />
<ToApproverId Value="hwilson" />
</RESPONSE>
For other actions,
<RESPONSE>
<ApproverResult Value="APPROVED|REJECTED|HOLD|RESPOND" />
<ApproverComment Value="abc" />
</RESPONSE>
Configuring & Managing Approval Alerts

I2 applications use different alert infrastructure for managing their alerts. (For
example, ABPP Manufacturing, CSE, TM etc. use different user models and alert

infrastructure). So the approval framework has been designed to work with any alert
implementations for managing approval alerts.
The approval framework will raise events providing information necessary for
creating, modifying and deleting the approval alert entries. It is the responsibility of
the application to define the listeners to these approval alert events for managing
(create/modify/delete) the alert entries and notifying approvers through email etc. The
payload of all the approval events can be found in approval_events.xml in the
APPROVAL service.
The alert entry persisted by the application should contain the approval token,
approval node name, approval document id and approval document type. These
properties are required for interacting with the approval infrastructure. Implementing
listeners to the approval events can be quite tricky. Please see the ABPP Approval
sample for an example of implementing listeners to the approval events. Note that this
is a one time effort for an application to use the approval framework.
Approval Node Activation

The alert infrastructure of the application is responsible for displaying the on-line
approval alerts to the approvers. It should also provide the plumbing for invoking the
activateApprovalNode command when the approver wishes to act on the approval
alert. Here is the API_DOC of the activateApprovalNode command:
<API_DOC>
<INPUT>
<REQUEST Name="activateApprovalNode">
<TokenId Value="xxxx" />
<REDIRECT_URL Value="yyyy" />
<ActingUserId Value="xxxxx" />
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE />
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
TokenId is the token persisted along with the alert entry. The REDIRECT_URL is the
URL to which the approver should be re-directed after performing the approval action.
Typically this will be the URL of the alert in-box of the approver.
The approval framework also raises recordApprovalHistory event. This event is useful
if the calling application wants to record the approval history.
Steps for creating an Approval Workflow

Please read the Approval Node Execution section to understand how the approval
nodes work. Here are the pre-requisite steps to create any approval workflow:

Steps for creating an Approval Workflow
z Add the APPROVAL service to your project. The APPROVAL service is an

archived services contained within bpe-services.jar. The studio will automatically
add this to your project when you add approval node to any of your workflows.
z The approval service defines events for managing alert entries and recording
approval history. The event definitions can be found in approval_events.xml in the
APPROVAL service. You must define listeners for these events. You should also
implement the necessary plumbing to invoke activateApprovalNode workflows
from your alert pages for the approval alerts. Please see the section on
Configuring & Managing Approval Alerts for more information.
Now you are ready to create your approval workflows. Here are the steps for creating
and running approval workflows:
z Create workflows using approval nodes in your service. (The approval nodes can
be used in workflows of all the services.). You should associate each approval
node with a UI workflow which renders the approval request to the approvers.
Please see the section on Input/Output to Approval UI workflows for more
information.
z Include the APPROVAL service as part of your service set up and the server run.


Chapter 3
Data Upload
Introduction
Dataupload service is a native service which is packaged with ABPP and allows the
user to upload data into various services. This document lays out a detailed description
of what features the service provides.
Upload Functionality Overview

The basic function of the data upload service is to provide a mechanism for the user to
upload data into the system through a service based API. Upload service provides a
couple of ways to upload data using files on disk. The user can upload data files using
the ABPP UI or can also follow a more automated way of uploading (this has been
described in Upload Methods in detail). The service allows creating a batch of
requests during uploads, and also lets the user to correct records which error out
during the upload process.
Upload Templates Management

To execute an API, the upload service needs some Meta data, including the API name
and also the service on which this API has to be invoked. This data and other related
information associated with a particular upload is captured into a model called
Template. The values specified in the template are static in nature and are applicable
to every instance of the upload made for a particular template. A template has to be
loaded for upload service to accept any data.
A Template primarily consists of the following properties:
Name (Required, Unique): The name of a template has to be unique with in an
application and will be referred to during uploads both from the UI as well as the
Server.
ServiceName (Required): The value of this attribute determines as to which service
the target API will belong to.

Chapter 3 Data Upload
ApiName (Required): Name of the REQUEST that has to be invoked for each
document that is encountered in the source document.
DataType (Required): If the source is going to be CSV, XML or XLS.
DisplayName (Required): This is a required attribute for the User Interface to show a
meaningful name for the Template.
BatchSize: The number of batches that are to be run while running the said template.
Each batch will be running on different thread trying to execute requests
simultaneously.
RequestStreamClass: If the user wants to override the standard stream for processing
the records, he can implement a class and register it in this field. The standard streams
support CSV, XML and XLS.
TemplateType: This field is used by the UI for categorizing Templates. If 2 templates
have the same type then they are folded under the same node in the UI. In the
reference implementation there are 2 broad categories, Transaction and static under
which the user can create further categorization by following this convention
Transaction.Category or Static.Category.
UserData: This field can hold data associated with user information, in the reference
implementation this field holds the activity associated with the template. This is
further used by the UI to display only the templates that a user is eligible to view.
MiscData: This field holds any miscellaneous data, that's needed by an application.
When a getTemplate call is made this field along with other fields is returned to the
user. Not used in the reference implementation.
For a CSV type template the upload also needs the order in which the properties will
occur. This is defined in the create template under the template node with the
PROPERTY tag.
Here is an example of a typical request.
<REQUEST Name="addTemplate">
<TEMPLATE Name=""
ServiceName=""
ApiName=""
DisplayName=""
DataType=""
BatchSize=""
RequestStreamClass=""
TemplateType=""
UserData=""
MiscData="">
<PROPERTY Name="" />
:
:
</TEMPLATE>
</REQUEST>
Example Templates:
1. XML Template

Upload Methods
<TEMPLATE Name="Upload Order (XML)"
ServiceName="Order_Processing"
ApiName="createCustomerOrder"
DisplayName="Upload Order (XML)"
DataType="xml"
BatchSize="1"
TemplateType="Transaction.Order"
UserData="upload_customer_order" />
</REQUEST>
2. CSV Template
<TEMPLATE Name="Upload Order (CSV)"
ServiceName="Order_Processing"
ApiName="createCustomerOrderCsv"
DisplayName="Upload Order (CSV)"
DataType="csv" BatchSize="1"
TemplateType="Transaction.Order"
UserData="upload_customer_order">
<PROPERTY Name="UserID" />
<PROPERTY Name="ShipDate" />
<PROPERTY Name="Expedite" />
<PROPERTY Name="BookID" />
<PROPERTY Name="Price" />
<PROPERTY Name="Quantity" />
</TEMPLATE>
</REQUEST>
The user can delete a template in the system by using the deleteTemplate API. The
user can access the Template by calling the getTemplate API, also the
getAllTemplates API can be used to get all the templates available in an application.
Upload Methods
There are a couple of ways in which data can be uploaded through the dataupload
service there is a server based method and then there is a UI based method. Following
is a description of both these mechanisms.
Server Based Method

The server based method is used where no user intervention is required. This is a more
popular mode of implementation as it can be automated fairly easily. After the initial
setup the system can run in a purely unassisted mode.
Configuration:
First the user has to configure the value of the following parameter in the dataupload
service configuration file
<service-params>
<param Name="UPLOAD_FILE_DIR" Value="../data/upload"/>

The UPLOAD_FILE_DIR parameter defines the root folder for dataupload, this is the
folder where the service will maintain a set of other folders for internal management
like source, archive and inprocess. Dataupload uses the source directory to look for
relevant files when a request is posted, once the service picks up a file for processing
the file will be moved to inprocess folder with a time stamp in the folder name, once
the processing of the file is over it will be moved to the archive folder.
After the above configuration is completed and a template is added for the data to be
uploaded, the user can copy the file to be uploaded into a folder under source
directory, (if the source directory does not exist then the user might have to create it).
If the data type is XML then the upload data file must follow a certain convention and
must look like the following:
<DATAUPLOAD Template="">
<BATCH_REQUEST>
...
</BATCH_REQUEST>
<BATCH_REQUEST>
...
</BATCH_REQUEST>
<BATCH_REQUEST>
...
</BATCH_REQUEST>
:
:
</DATAUPLOAD>
Example:
<DATAUPLOAD Template="Upload Order (XML)">
<BATCH_REQUEST>
<CustomerOrder>
<ShipDate Value="5/15/2006" />
<LineItems>
<LineItem>
<BookID Value="1" />
<Price Value="3" />
<Quantity Value="10" />
</LineItem>
</LineItems>
</CustomerOrder>
</BATCH_REQUEST>
<BATCH_REQUEST>
<CustomerOrder>
<ShipDate Value="5/15/2006" />
<LineItems>
<LineItem>
<BookID Value="1" />
<Price Value="3" />
<Quantity Value="10" />
</LineItem>
</LineItems>
</CustomerOrder>
</BATCH_REQUEST>
</DATAUPLOAD>

Upload Methods
For all non xml files the user also has to create another file called source.cfg and
copy it in the same folder as the data file. The source.cfg file should have the
following content:
<UPLD_CFG>
<JOB_PATH ResourceName="" Sequence="true" >
<TEMPLATE Value="for non xml files'/>
</JOB_PATH>
<JOB_PATH ResourceName="" />
</UPLD_CFG>
In the source.cfg file the ResourceName attribute should contain the actual file
name and the sequence attribute defines that the files will be processed in the order
that they are specified in the file.
The user has to now post a request to the server which should be as follows:
<REQUEST Name="uploadBatchRequestsDir" >
<JOB_NAME Value=""/>
</REQUEST>
Where the job name is the name of the folder under source where the data file has
been copied.
Example:
Assume that the UPLOAD_FILE_DIR parameter is set to c:/i2/data/upload folder
then the user can create a folder with a date stamp like templateName-01-01-2006 and
copy the data files under c:/i2/data/upload /source/templateName-01-01-2006 and
execute the following request on dataupload service
<REQUESTS ServiceName=" DATAUPLOAD">
<REQUEST Name="uploadBatchRequestsDir">
<JOB_NAME Value="templateName-01-01-2006"/>
</REQUEST>
</REQUESTS>
Lets further assume that we would like to upload two types of files, the first one is non
xml based template (csv etc) the user will have to create another file called source.cfg
and put it in the same folder as the data file. The relevant source.cfg file for non
XML file:
<UPLD_CFG>
<JOB_PATH ResourceName="myFile-01-01-2006.csv"
Sequence="true">
<TEMPLATE Value="MY_NON_XML_TEMPLATE" />
</JOB_PATH>
<JOB_PATH ResourceName="myFile-01-01-2006.xml" />
</UPLD_CFG>
In the above example we had two resources the first one is a csv and therefore the
template name is specified in the source config file and the second one is an xml file
which would contain the name of the template in the Template attribute of the root
DATAUPLOAD tag as specified earlier. However, if a folder contains only xml file
types with no implied sequence then source.cfg is NOT needed and all files will start
loading almost simultaneously. In all other cases a source.cfg file is needed. If
source.cfg is provided it should list all the files in the folder regardless of their file
types.

A Note about aborted uploads, if the user copies a invalid xml file for upload then the
upload will abort, but the file is copied under the inprocess folder. The user can go to
that directory, correct the xml file and then post the following request.
<REQUEST Name="processAbortedDirs">
<DATE1 Value=".." />
<DATE2 Value=".." />
</REQUEST>
Where DATE1 is start time and DATE2 is end time respectively, this will ensure that
all the uploads processed in the DATE1 to DATE2 time line are reprocessed. Please
note that the user will have to leave the aborted files after correction in the directories
that they were found under the inprocess folder.
UI Based Method
Uploading Data Files
The following are the steps to upload a data file through the UI, Please note that the
screens themselves are a part of the ABPP product, however, the navigation links are
subject to implementation, the navigation links described here are as implemented by
the reference implementation.
1. In the Navigation pad (left-pane), click on the Uploads > Upload File.
The Transaction Templates screen is displayed.
2. Note that the categorization happens when the user creates the upload template
with TemplateType field as follows: Transaction.Order.
3. The user can click the appropriate template name and the upload screen is
displayed.
4. The User can then browse the appropriate data file and click the Upload button.
5. The file is then submitted to the server, and a success or failure message is
displayed to the user.
6. For checking the details of a template the user can click Template Details button
and a screen is displayed with the details of the Template.
Status Report
The status report presents the status of an upload, it shows the details of the various
uploads that happened, the user can filter these by various parameters including
Report ID, Template Name, Upload Status and Data range of when the upload
occurred. The result screen shows all the data related to uploads. The following is a
description of the fields that are displayed in the results:
1. Report ID: This is the id provided by the system to a upload that has been
executed.
2. Template Name: Name of the template that was used for the upload.
3. Report Time: Time when the upload actually started.
4. Progress: Status of the upload the valid status are as follows:

Status Report
| Aborted: This status indicates that upload service was not able to resolve
certain issues, like if an xml upload has invalid xml.
| Completed: All records in the upload file were processed without any records
returning an error message by the API.
| Completed with gaps: All records were processed by the API but some
records returned a error message from the API, the error messages have to be
in the format that ABPP validation service reports it in, more details on how
to generate error messages are in Appendix.
| Initialized: This indicates that the upload has just been initialized; this is a
transitory state which should quickly go away.
| Processing: This status indicates that the dataupload service is still processing
records associated with this upload.
| Processing with gaps: dataupload is still processing the records for this
upload but it has already encountered some valid errors.
| Waiting for start signal: This is a state where this upload is in pre initialized
state, again this is a transitory state.
| Reserve Report: As soon as the upload starts upload reserves a report id
number for the upload, this state indicates that the upload is in the process of
acquiring that id.
5. Total Records: The number of records that were processed in this upload
6. Errors: The number of records that had errors returned by the API.
7. Purged: The number of records that were purged from this report without being
corrected.
The user is also allowed to reprocess or purge the upload information, the user can
select a record in the status report screen and click the appropriate button, Purge for
deleting all data related to the upload or Reprocess to reprocess the upload, for
example in case where the records error out due to a referential constraint and the user
later realizes that the constraint has now been fixed he/she can select the appropriate
upload record in this screen and click the reprocess button, all the records will be
posted again to the server and to the same API/service combination.
The following is a screen shot of the Status report screen which is accessible from the
view status menu in the reference implementation.

Error Correction
The user can look for reports with status Completed with gaps and click the button
report id link on the Status reports screen. Here he will see more details regarding the
upload including a list of records which have errors in them as follows:
The user can then click on the error record number link and inspect the error as well as
execute correction on the error, the following screen displays the error correction UI:
The correction can be made by the user and can be submitted to the server by clicking
the submit button. The system returns with a success or failure error message, in case
of failure the user can correct the error once again and submit.
A Note on how to create Links for the above mentioned screen flows.
The above screens have been written using the x2 technology. For both the screens,
Upload file and Status Report there are page definitions already available in the

Error Correction
system. The user has to refer to these page definitions to create URL links in the
navigation panel.
Here are the steps to include these screens in your Application:
z Open your applications Navigation workflow right click the Navigation UI node
and select Properties.... as shown below.

z Right click on the Solution and select Add..->pad as shown below.
z On the following screen set Display Text and name as Upload and upload
respectively and click the OK button.

Error Correction
z The previous step will create a pad called Upload. Right click on the pad and
select Add...->pad-item as below
z On the resulting dialog box enter Upload File for displayText and click OK.

z Select pad-item created in the previous step, and fill the url property with
{$pages:upload_transaction_templates}. This url internally points to a pre
packaged jsp in the system.
z Right click on the Upload : pad again and select Add...->pad-item, on the resulting
dialog type View Status and click OK button as shown below

Advanced Customizations
z Right click on the newly created pad-item View Status and set the url property to
{$pages:upload_reports} as shown below.
z Hit the apply button and on the right hand side of UI nodes property page you
should see the newly created pad items as follows
Dataupload Workflow
Dataupload goes through the following workflow when a new upload is started. Please
note that UNDERLINED text represents parameters that can be configured in
dataupload service file. Certain parameters can be further over-ridden at a template
level by setting some attributes in the addTemplate API. These parameters are specified
in Bold:
1. when uploadBatchRequestsDir API is invoked, dataupload first ensures that

the job name (the directory name within the $UPLOAD_FILE_DIR/source
folder) is a valid directory. If the directory does not exist dataupload throws an
error and exits the upload. In our discussion, we use the job name and its
corresponding directory synonymously
2. In a single uploadBatchRequestsDir invocation the user can specify various
Job Names, in essence the user can request dataupload to start uploading contents
from more than one directory. However, a service parameter
MAX_JOB_THRESHOLD can be set to control the number of directories that

dataupload will process in parallel. Note that this parameter ensures that only
configured number of directories are processed in parallel at any given point in
time in dataupload.
Consider the following situation:
| User invokes 3 requests for uploadBatchRequestsDir simultaneously
with each one having two job names.
| The MAX_JOB_THRESHOLD is set to 2.
There are totally 6 jobs (i.e. directories) for data upload from the 3 invocations.
Dataupload will start to process only 2 jobs from the first invocation. The other 4
jobs are queued up. The jobs from the queue will be processed as soon as any of
the existing jobs finish. At any point there can only be a maximum of 2 jobs that
are processed simultaneously.
3. The first step in processing a job ( i.e. directory) is to move the files in the
$UPLOAD_FILE_DIR/source/job-name directory in to $UPLOAD_FILE_DIR/
inprocess/job-name +time-stamp directory. If the service parameter
CAN_DELETE_SOURCE_DIR is true then dataupload also deletes the
$UPLOAD_FILE_DIR/source/job-name directory.
4. After moving the files to inprocess directory, dataupload will process as many
files as controlled by service parameter MAX_REQ_STREAM_THRESHOLD. The
above parameter defines how many files are processed in parallel by dataupload
across all the jobs that are currently in execution.
For example consider the following scenario
z Two directories are created containing three files each.
z uploadBatchRequestsDir is called twice on dataupload almost
simultaneously with the above two job names.
z MAX_REQ_STREAM_THRESHOLD is set to four
z MAX_JOB_THRESHOLD is set to two.
In the above scenario, dataupload will start processing all the files under the
first directory (total of 3 files) and one file from the second directory.
Dataupload will wait until it processes at least one file before picking up the
next file from the second directory.
5. Dataupload then creates a Request Queue for each file. The request queue in effect
restricts the number of requests that are maintained in memory by dataupload.
Size of this Queue is determined by reading a service parameter
REQ_QUEUE_SIZE (ReqQueueSize).
6. The Request Queue is not kept filled up all the time because of performance
reasons. The Queue is filled only when it drops below a certain percentage. This
percentage is defined by the REQ_QUEUE_REFILL_PERCENT
(ReqQueueRefillPercent).
For example if the Request Queue size is 200 and the fill percentage is set to 75
then the request queue will be filled only when 150 requests are remaining in the
queue.
7. Eventually dataupload starts filling up the Request Queue with requests read from
a file. A set of threads start pulling data from the Queue and start executing
requests on the appropriate xservice (ServiceName/API are configured when the

template is created). The number of threads that start executing requests

simultaneously is controlled by the service parameter called
UPLOAD_THREAD_COUNT, (UploadThreadCount).
8. In some cases, the performance can be optimized if many requests are executed
within a single transaction scope. The number of requests to be executed in a
transaction is called BatchSize. The size of this batch is determined by service
parameter called BATCH_SIZE (BatchSize).
Note: In most cases, executing more than 1 request within a transaction can result in
dead-locks. This typically happens if the invoked API employs any locking of
the resources it uses. A common example of a resource is the database rows
that are implicitly locked when issuing any write operation. So a safe
guideline is to set this parameter to 1.
9. Even if one of the requests in a batch encounters an exception, the entire

transaction rolls back. In such an event, dataupload will re-execute each of the
requests in the batch one by one in a separate transaction.
10. Dataupload provides an applet error correction to correct errors, one request at a
time, on the web UI.
11. Two parameters REQUEST_TRACE_DIR (RequestTraceDir) and
RESPONSE_TRACE_DIR (ResponseTraceDir) are meant for debugging, if this
directory is set then all the requests and responses are logged to these respective
folders.
12. A service parameter called CAN_ARCHIVE (CanArchive) can be set which
allows the user to specify if dataupload should archive the uploaded files in the
archives folder.
13. As part of processing the files, dataupload service writes out the status of the
upload in to a few database tables. These tables are queried in the view status
screen to display information about the upload operation to the user.
14. User has the option to use interceptors which are invoked before getUploadReport
or uploadBatchRequestsMem APIs are invoked. The interceptor can be a class
that can be registered with dataupload service in the service file. The following
INTERCEPT_getUploadReports, INTERCEPT_uploadBatchRequestsMem
service parameters can be set to point to the appropriate class. The implementing
class has to implement the DataUploadNative.Interceptor interface. This feature is
especially useful in scenarios where a business process requires more granular
control of visibility into uploads.
For example, if the business requirements so state that a user of the system can
only view uploads that were executed by him, then:
| uploadBatchRequestsMem interceptor can be created to save the user id could
into the USER_DATA field in the progress reports table.
| getUploadReports interceptor can then be used to filter the records viewed in
the data upload UI to match the user id with data in the USER_DATA field.
15. There is also scope for the user to control a field's edit ability in the correction UI.
This can be achieved by registering a class in the service file for the parameter

PAGE_BUILDER_CLASS. The page builder class has to override the default

com.i2.xservice.dataupload.jc.builder.PageBuilder class.
Guidelines
1. For dataupload service to capture errors raised by the API, the error response
should be in the standard ABPP validation format as follows:
| response will have a child element called _RESULT
| _RESULT should have a Value attribute with a value of ERROR or
SEVERE_ERROR.
| RESPONSE should have all the fields as they appear on the REQUEST
tagged along with the standard error response (_ERROR).
| Details attribute in the _RESULT should be set to true. If the Details attribute
is not set to true then will assume that the contents of the RESPONSE are not
the same as the REQUEST and will display the REQUEST form as is to the
user (It will not contained the errors marked) for correction.
2. Ensure that the code is completely free of contentions before using BatchSize of
more than 1. When in doubt use BatchSize of 1.
3. If the Server Method is chosen for implementation, please note that all the files
used for upload will be saved to the Archive folder so its recommended that the
user should clean up the files at regular intervals.
4. Upload service also maintains data in several tables, these tables can increase in
size as more and more uploads are executed. ABPP has a built in purge utility that
allows the user to configure purging of data. The following is an example of a
purge spec implemented for cleaning up data upload tables:
<purge_defs>
<purge_def Name="UploadDataPurgeDef" Action="PURGE"
AnchorDocumentName="UPLOAD_RESOURCE_SPEC" BatchSize="150">
<documents>
<document DocumentName="UPLOAD_RESOURCE_SPEC">
<filter>
<AGE_IN_DAYS
Value="{$PURGE_AGE_IN_DAYS}" FieldToBeUsed="CREATION_DATE"/>
</filter>
</document>
</documents>

<traverse_links>
<traverse_link
LinkName="UPLOAD_PROGRESS_RESC_LINK">
<traverse_link
LinkName="UPLOAD_RECORDS_LINK"/>
<traverse_link LinkName="UPLOAD_ERROR_LINK"/
>
</traverse_link>
</traverse_links>
</purge_def>

Tuning Upload using Get Resource Stats Command
</purge_defs>
For more information about the purge utility please refer to Part B of the ABPP
programmers reference. The PURGE_AGE_IN_DAYS (refer to the spec above)
is the number of days of dataupload data that you would want to keep in the
tables. It is recommended to purge the data in the tables by running the purge
utility on a daily basis.
5. There is a lot of over-head incurred per file by the data upload framework to track
the upload status, move the files through directory structure etc. This implies
creating fewer files with large sizes to avoid the over head. On the other hand
reading a huge file may take a long time since this is a serial activity. So there is a
need to strike a balance between the two factors.
The right file size is often determined by running your uploads with different file
sizes and choosing the one that yields the best results. One rule of thumb is to use
file sizes > 5 MB to strike the right balance.
6. On a server with more memory ReqQueueSize can be set to a higher number to
yield better performance. You can find your optimal size by trial and error.
7. On a server with many CPU’s you can increase the UploadThreadCount. Some
trial and error might be required to find the optimal setting for the given server.
8. On a machine with many CPU’s, running multiple instances of data upload server
may yield a better throughput. You can divide the work amongst the servers by
distributing the jobs (directories). This is worth checking it out.

The GET_RESOURCE_STATS command has been enhanced to provide additional
information on the currently executing upload jobs. This information can be used to
identify bottle necks and tune the upload parameters to improve the through put.
Here is a sample output of GET_RESOURCE_STATS command when an upload job

is in progress. Some of the command output details not relevant to this discussion
have been omitted for readability. The attributes of interest are shown in bold.
<DBConnectionStats TotalConnectionsMade="3"
ConnectionsInPool="3" />
<MemoryStats TotalMemory="887033856" FreeMemory="31541272"
UsedMemory="855492584" />
<ThreadGroups NumThreads="44">
<ThreadGroup Name="system" NumThreads="6">

</ThreadGroup>
<ThreadGroup Name="main" ParentGroup="system"
NumThreads="5">

<Thread Name="XServer" />
</ThreadGroup>

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

NumThreads="12">

</ThreadGroup>
<ThreadGroup Name="Pooled Thread Group"
ParentGroup="main" NumThreads="21">

<Thread Name="MasterUploader-15204">
<UploadFileStats ReportId="15204"
QueueSize="9775" MaxQueueSize="10000" NumThreads="2"
UsedByRunnable="com.i2.xservice.dataupload.impl.request.MasterR
equestUploader" />
</Thread>
<Thread Name="DataUploader-0-15204">
<UploadBatchRequestStats
RecentElapsedTime="3828" MovingAvgElapsedTime="3949"
NumOperationsForMovingAvg="10" AvgElapsedTime="4351"
TotalOperations="81"
UsedByRunnable="com.i2.xservice.dataupload.impl.request.Request
Uploader" />
</Thread>
<Thread Name="DataUploader-1-15204">
<UploadBatchRequestStats
RecentElapsedTime="4203" MovingAvgElapsedTime="3820"
NumOperationsForMovingAvg="10" AvgElapsedTime="4180"
TotalOperations="85"
UsedByRunnable="com.i2.xservice.dataupload.impl.request.Request
Uploader" />
</Thread>
</ThreadGroup>
</ThreadGroups>
<AsynchTasks QueueSize="0" />
</RESPONSE>
Here is how you can make sense of the resource stats command output listed above:
Note: Refer to the Dataupload Workflow section for description of any of the upload
parameters mentioned in the discussion below.
z You will see a master thread, MasterUploader-xxxxx, for each of the files that is
currently being uploaded. A master thread controls the upload for a single upload
file. The number of master threads will be less than or equal to (<=)
MAX_REQ_STREAM_THRESHOLD parameter.
| The MaxQueueSize attribute on the MasterUploader thread corresponds to
ReqQueueSize parameter. This parameter determines the number of upload
batches that can be held in memory for a given file upload. If the system is not
memory constrained then increasing ReqQueueSize parameter will improve
the throughput.
| The QueueSize attribute corresponds to the actual number of upload requests
in the queue waiting to be processed. If this number is very high then

increasing the number of threads consuming from the queue

(UploadThreadCount parameter) might help in increasing the throughput.
The actual improvement will depend on the specific hardware, the number of
cpu’s available to the process and other bottle-necks (like database resources)
in the system. If the number is too low then increasing the
ReqQueueRefillPercent parameter might improve the throughput.
| The NumThreads attribute corresponds to the UploadThreadCount
parameter.
z For each master thread, you will see as many upload threads (DataUploader-n-
xxxxx) as the NumThreads attribute specified on the master thread. In the above
example, DataUploader-0-15204 and DataUploader-1-15204 are the
upload threads corresponding to the master thread, MasterUploader-15204.
| The RecentElapsedTime attribute is the time taken to execute the last batch
of upload requests by this thread. This time is mostly spent in executing the
underlying application API to process the upload batch. To reduce this time,
you will need to tune the underlying API.
| The MovingAvgElapsedTime attribute is the moving average time taken to
execute a batch of upload requests averaged over the last number of batches
specified by NumOperationsForMovingAvg attribute. In the above
example, DataUploader-0-15204 thread executed the last 10 batch
uploads at an average time of 3949ms (for each batch). Comparing the
RecentElapsedTime Vs MovingAvgElapsedTime can give you an indication
if the time taken by the underlying API is increasing or decreasing with time.
| The AvgElapsedTime attribute is the average time taken by the upload thread
to process a batch of upload requests. Comparing the AvgElapsedTime Vs
MovingAvgElapsedTime Vs RecentElapsedTime can give you an indication
if the time taken by the underlying API is increasing or decreasing with time.
| The TotalOperations attribute is the total number of upload batches executed
by the upload thread.


Chapter 4
Task Scheduler Service
This chapter gives you information about the Task Scheduler Concepts and Service. It
includes the following topics.
Topics:
z Introduction
z Task Nodes
z Wait Process Node
z Launch Process Node
z Load SQL File Node
z Execute SQL Procedure Node
z FTP Files Node
z Notification Node
z Task Node Execution
z Assumptions and Dependencies
z Configuring and Managing Notification
z Scheduling
z UI Log and Monitoring
z Suggestions and Best Practices
Introduction
Task scheduler framework provides a toolkit which enables the user to create, monitor
and schedule task based workflows. It uses various components already available in
ABPP such as the workflow engine, PGL and the timer service.
The framework also provides a rich set of workflow nodes which can be easily
configured. It also provides a monitoring UI which can be used by the user to check
the status of a Task workflow, these screens could be customized further based on
customer requirements.

Chapter 4 Task Scheduler Service
The task nodes have inbuilt notification mechanism which can be configured to send
emails, or can be hooked up with an alerting system
Task Nodes
Task scheduler framework has five special nodes for the user to create various tasks.
These are Wait Process Node, Launch Process Node, Load SQL File Node, Execute
Procedure Node and FTP Files Node.
Wait Process Node, Load SQL File Node, Execute Procedure and FTP Files Node
have similar characteristics, as mentioned below:
z These nodes have a Pre Action and Post Action components where the user can
execute rules before and after the Task is executed.
z They also have a Notification component, where the user can specify the
condition in which a notification is to be raised, along with email subject and
body, it also allows the user to associate a activity with the notification.
z These nodes also have next nodes component. This enables the user to decide
which next node to execute after the post action has been executed.
z All of the above mentioned nodes are restartable, as in when a notification is
raised the user can look at the state of the workflow and decide if he wants to
restart the workflow from any of the four nodes available in the workflow. If he so
chooses the workflow will restart from the specified task node onwards.
z An implicit variable named outputDocVar is available (This is also available in
Launch Process Node) to the user in the Post Process component which returns
the result of the task. The signature of this variable is defined in the explanation of
each node
z All properties of these nodes can be expressed as xpath expressions except for the
Procedure name in the Execute Procedure node.
z All the task nodes can be used with regular ABPP nodes in a workflow, the other
nodes will not be restartable.
Wait Process Node

The wait process node is a task node which launches a executable or a shell script.
This node waits for the process to finish, before moving to the next node. The user
also has to specify a timeout value for the process, thus ensuring that the process will
either finish or timeout after a finite number of seconds.If the process finishes before
the timeout an exit code is returned in the outputDocVar, otherwise a flag indicating
that the operation timed out is returned. The next nodes component allows the user to
branch into various nodes depending on the branching conditions. This node can be
restarted from the UI when a notification is pending on it.

Task Nodes
The following is a description of the above parameters:

z Command: This is a required parameter for this node. The value of this parameter
should contain the name of the application (with the entire path ex: c:/
mybatch.bat).
z Arguments: Optional parameter, the value of this parameter should point to
arguments that are required by the application in the Command parameter.
Multiple arguments can be passed in with space as a delimiter
z Timeout: This is a required parameter, it should be a number (seconds), if the
application does not finish execution by the number of seconds, then the system
will kill the process and return control back to this nodes post action. If the killing
fails for whatever reason the user has to go to the OS and kill it manually. This
also will return the control back to the post actions on that node.
z Working Directory: The value of this optional parameter sets up the working
directory of the application being launched. Default working directory is set to the
same working directory as the ABPP application.
z Environment: This optional parameter can contain name value pairs separated by
space in the following format: name1=value1 name2=value2.
z Capture StdOut: This optional parameter will configure the node to capture
Standard output of the application configured in the Command parameter, the
result is available only at the end of the process in the outputDocVar. Warning: As
this setting starts capturing standard out buffer of the application till the
application is running it will cause the memory footprint to go up, it is best to
avoid this property and leave it as false.

z Capture Errors: This optional parameter will configure the node to capture
Standard Error of the application configured in the Command parameter, the
result is available only at the end of the process in the outputDocVar. Warning: As
this setting starts capturing standard error buffer of the application till the
application is running it will cause the memory footprint to go up, it is best to
avoid this property and leave it as false.
z Node Input: Input to this node. Warning: It is best not to use Node Input because
this is a restartable node. The values of the node input parameter will not be
remembered when a restart happens.
Wait Process ouputDocVar Signature:

<WAIT_PROCESS_RESPONSE Status=”Success|Error” Description=”..”>
[OPERATION_TIMED_OUT Value=”true”/>]
[EXIT_CODE Value=”..”]
[<STD_OUT>
<LINE Value=””/>
</STD_OUT>]
[<STD_ERR>
<LINE Value=””/>
</STD_ERR>]
</WAIT_PROCESS_RESPONSE>
Note: Description in the root node is inserted only when the status is Error.
Launch Process Node

Launch process node is also used to start an external process, just like wait process,
however, launch process does not wait for the process to finish, and in fact proceeds to
the next node connected, also this node is not restartable from the user interface. No
notifications can be raised on this node as this node doesn’t wait till the completion of
the process. This node also has the action component which is executed after the
process is launched. This node is like a workflow task node. This node is not
restartable from the UI.

Task Nodes
The properties of the above node are described below:

Node Input: Same as a task node the variable in this node is the input to the node. As
this is not a restartable node, its alright to specify the input variable.
Node Output: output of this node.
Command: This is a required parameter for this node. The value of this parameter
should contain the name of the application (with the entire path ex: c:/mybatch.bat).
Arguments: Optional parameter, the value of this parameter should point to
arguments that are required by the application in the Command parameter. Multiple
arguments can be passed in with space as a delimiter
Working Directory: The value of this optional parameter sets up the working
directory of the application being launched. Default working directory is set to the
same working directory as the ABPP application.
Environment: This optional parameter can contain name value pairs separated by
space in the following format: name1=value1 name2=value2.
Launch Process ouputDocVar Signature:

<LAUNCH_PROCESS_RESPONSE Status=”Success|Error”
Description=”..”/>

Note: The above only returns the status of the launch, it does not include the exit
code etc.
Load SQL File Node

The Load SQL File Node is used to run the contents of a SQL file. The node accepts a
SQL file as a parameter and allows the user to run the specified file. The user can
select to run the SQL on any database as supported by i2 Stack, they can also choose
to Load the SQL file on the System database, which will connect to the database that
the ABPP application is running on. A JDBC connection is used to execute the Load
on the configured DB instance. The user has to ensure that appropriate driver classes
are available in the classpath in the ABPP application.This node can be restarted from
the UI when a notification is pending on it.
Here is the description of the above properties:

File Name: This required parameter is the name of the SQL file which can be found in
the system path. The specified file will be loaded into the configured database. All
paths should be relative to the ABPP’s workfing folder.
Use System DB: If this required parameter is set to true, then the above file is loaded
to the same database that the ABPP engine is connected to, if this is set to false then

Task Nodes
the rest of the database properties are used to connect to the database and the SQL file
is loaded into the specified database.
DB Type: Required if Use System DB is set to false. The Database type can be set to
‘ORACLE’ or ‘DB2’ as per the i2 Stack.
Host: Required when Use System DB is set to false. This parameter is to be set to the
Host where the SQL file is to be loaded.
Port: Required when Use System DB is set to false. This parameter is used to specify
the Port to connect to the database.
User Id: Required when Use System DB is set to false. This parameter is used to
specify the User Id to connect to the database.
Password: Required when Use System DB is set to false. This parameter is used to
specify the Password to connect to the database
DB Instance Name: Required when Use System DB is set to false. This property is
used to specify the Instance name to connect to the database.
Load SQL File ouputDocVar Signature:

<LOAD_SQL_RESPONSE Status="Success|Error" Description="..">
[<FILE_PATH Value=".."/>]
[<DB_TYPE Value=".."/>]
</LOAD_SQL_RESPONSE>
Note: Note: Description in the root node is inserted only when the status is Error.
Execute SQL Procedure Node

The Execute SQL Procedure Node allows the user to execute a SQL procedure
available in the specified database. The node can be configured to execute the
procedure on the database that ABPP is connnected to or any other database supported
by i2 Stack. Execute procedure node also lets the user specify a set of parameters to be
consumed by the SQL procedure. These parameters could be of three types, IN
Parameter which means the parameter is used to specify a value as an input to the
execute procedure, OUT Parameter which would mean that the execute procedure
could set the parameter and IN_OUT Parameter where the value of the parameter
going into the procedure could be changed by the procedure. This node can be
restarted from the UI when a notification is pending on it.

Here is a description of the above properties:

Procedure Name: This required parameter is the name of the SQL procedure to be
executed, note that this is not a expression value.
Use System DB: If this required parameter is set to true, then the above procedure is
executed in the same database that the ABPP engine is connected to, if this is set to
false then the rest of the database properties are used to connect to the database and
the SQL file is loaded into the specified database.
DB Type: Required if Use System DB is set to false. The Database type can be set to
‘ORACLE’ or ‘DB2’ as per the i2 Stack.
Host: Required when Use System DB is set to false. This parameter is to be set to the
Host where the SQL file is to be loaded.
Port: Required when Use System DB is set to false. This parameter is used to specify
the Port to connect to the database.
User Id: Required when Use System DB is set to false. This parameter is used to
specify the User Id to connect to the database.
Password: Required when Use System DB is set to false. This parameter is used to
specify the Password to connect to the database
DB Instance Name: Required when Use System DB is set to false. This property is
used to specify the Instance name to connect to the database.

Task Nodes
The above table defines the parameters to be accepted by the SQL procedure. The
table has as many rows as the number of parameters accepted by the SQL procedure.
The following explains the columns in the above table:
z Name: This is a required parameter which will be used to return the value for all
OUT and IN_OUT parameters in the response contained in the outputDocVar. In
the above example outputDocVar will contain the values <PARAM2 Value=””/>
and <PARAM3 Value=””/> PARAM1 will not be available as its an input
parameter.
z Value: This has to be populated to a literal or xpath expression value required for
the IN parameters.
z Type: This is a required parameter, as explained earlier this will indicate if the
parameter is of Type IN, OUT or IN_OUT.
z Data Type: This indicates the type of parameter that the SQL procedure is
expecting, this could be of the following types:boolean, string, int, float, double,
date, datetime,time and timestamp
Execute SQL Procedure ouputDocVar Signature:

<EXEC_PROC_RESPONSE Status="Success|Error" Description=”..”>
<PARAM Value=".."/>
</EXEC_PROC_RESPONSE>
In the above signature PARAM could be one of the OUT or IN_OUT
parameter type.

FTP Files Node

This node is used to FTP files, it can be used to get files from a server and put files on
to a FTP server. The node does not allow the user to recursively copy directories. Note
that user who starts the process will need to have access to the local directory where
the files have to be copied. Either source or destination should be remote. This node
can be restarted from the UI when a notification is pending on it.
Here is an explanation of the properties of this node:

Source: This required parameter specifies the value of the source file or directory that
needs to be copied using FTP.
Source is Remote: This parameter specifies if the source file or directory is on a
remote computer, a true value indicates that the file is on a remote computer otherwise
the file is assumed to be on the local computer.
Destination: This required parameter indicates the location of the destination file or
directory. The file(s) specified in the Source will be copied to this location. It then its
best to specify entire file or directory path ex: c:/dailyload/abc.csv or c:/dailyload
Destination is Remote: This parameter specifies if the destination file or directory is
on a remote computer, a true value indicates that the file is to be copied using FTP to a
remote computer.

Task Nodes
Source is Directory: Optional parameter specifies if the Source is a directory, if this

parameter is set to true, then certain precautions have to be taken:
| Make sure there are no other directories under the source directory.
| Ensure that all files in the source directory are of either Binary or Ascii type.
| Ensure that the destination folder is already available for this node to copy
into.
| Ensure that the user id that started the ABPP server has appropriate privileges
to write files to the local computer or read files.
FTP Type: Required parameter indicating if the file or directory to be copied are
ASCII or BINARY. Warning: If the Source is a directory and is set to true all the files
in the directory are assumed to be of the same type(ASCII or BINARY).
Host Name: Required parameter set to the name of the FTP host.
Port Number: Optional parameter set to the port number on which the FTP server is
listening. If not specified defaults to 21.
FTP User Id: Required parameter the value of which would indicate the user id which
would be used to connect to the FTP server.
FTP Password: Optional parameter the value of which would indicate the password
needed to connect to the FTP server.
Connection Timeout: This optional parameter indicates as to how long in seconds
that the system will wait for the FTP server to establish connection, note that this is
not timeout for file transfer.
FTP Files Node ouputDocVar Signature:

<FTP_RESPONSES Status="Success" Description="..">
<FTP_RESPONSE Value="226 .."/>
</FTP_RESPONSES>
Note: Description in the root node is inserted only when the status is Error.
Note: If all files in a directory are copied and if the FTP fails in between due to a
netowork error the user might have to cleap up the existing file(s). The user
will have access to this information in the Status field of outputDocVar, the
user will get ‘Error’ in the Status attribute, as mentioned earlier outputDocVar
is available in post action.
Notification Node
The Notification node is a task scheduler node which can be used to execute xrules.
However, it has all the charecteristics of Task Scheduler nodes like it allows the user
to execute action, configure notification and branch into next nodes based on multiple
conditions. This node is also restartable from the monitoring UI.

Each of the above tabs of the Notification Node properties window represent the
following:
Actions: The user can execute any xrules, the actions are executed as normal rule
code.
Notification Conditions: The user can specify notification conditions under this tab.
If any of these conditions are evaluated to true then a notification is raised to the
people with appropriate activity.
Condition settings: Next node condtions can be specified here in this tab. This allows
the user to branch into multiple nodes based on various conditions.
Notification nodes are executed as follows:
Actions are executed first, then the notifications are evaluated and finally Next Node
conditions are evaluated.
Task Node Execution

The Wait Process, Load SQL File, Execute Procedure and Copy files nodes execute in
the following order:
1. The pre action code is executed first.

Assumptions and Dependencies
2. The Task is executed.

3. The post action is code is executed where the user has access to outputDocVar.
4. The system checks the notification conditions configured in the node. If any
condition happens to be true then a notification is raised. The workflow waits until a
user acts on the workflow and from the UI chooses either to continue from the next
node (Therefore it would be a good practice to specify all conditions in notification be
available in next nodes, this is useful if the user continues)
5. If no notification conditions match or the user hits continue on the UI then the next
nodes conditions are evaluated and the next node is chosen to execute.
The Launch process has only two execution points:
1. The process is executed.
2. The action code is executed where the user has access to outputDocVar and the
control moves to the next node.
Assumptions and Dependencies

Task Scheduler service depends on the following services, Please read appropriate
documentation to understand the functionality of each service in this list:
1. TIMER_SINK: This service is used for task scheduling and also by the Task
scheduler status table.
2. PGL: The History, Monitoring and Notification UI’s require this service.
3. OMS_MESSAGE_SERVICE: This service is used to email notifications.
4. MESSAGING: This service is used to send web alerts for notification
Configuring and Managing Notification

Notifications are alerts sent out by the Messaging service. A notification can be sent
out by email or as a web alert.
Steps for Configuring Notification at an application level:

1. Ensure that a valid SMTP host is configured in the
OMS_MESSAGING_SERVICE. The host is specified in a service parameter called
om.smtpHost.
2. Ensure that a valid from email address is registered in the
OMS_MESSAGING_SERVICE, this is the email address that the user will be getting
email from. The from email address is configured in a service parameter called
om.systemFromAddress.
3. Appropriately configure the following properties in the service parameters of the
TASK_SCHEDULER service:
a. loginPage: This parameter should be set to ABPP Login
page URL. for example: http://server/platform/core/login.jsp

b. appName: This parameter value should be set to the

ABPP application name as specified in Weblogic/WebSphere.
example: platform
4. The Task Scheduler service contains a request descriptor (Interface) called

getUserListBasedOnActivity, this interface needs to be implemented by the service
which hosts the User models within an application. When a notification condition is
found to be true on a node, the Task scheduler service calls the above method and
expects back a response with all the user id’s and email belonging to the configured
activity. All the emails for the users who are returned by the above function are sent a
notification.
Here is a signature of the input and output of the above function.

<API_DOC>
<INPUT>
<REQUEST Name="getUserListBasedOnActivity" Comment="Given an activity,
returns all the users that have that activity." Any="true">
<ACTIVITY Value="xyz[Type=string]" />
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE>
<USER_PROFILE>
<ID Value="admin[Type=string]" />
<EMAIL_ADDRESS Value="admin@i2.com[Type=string]" />
</USER_PROFILE>
</RESPONSE>
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
Here is an example of how to implement the above interface:

<DEFINE_IMPLEMENTATION Name="getUserListBasedOnActivity"
Descriptor="//TASK_SCHEDULER/getUserListBasedOnActivity">
<RULE>
<ACTION>
<GET_DOCUMENT Name="UserProfile"
AssignToVar="response">
<SELECT>

Configuring and Managing Notification
<UserID/>
<Email/>
</SELECT>
<QUERY_DOCUMENT_LINK Name="UsersToRoleLink">
<QUERY_DOCUMENT_LINK
Name="RoleToRoleActivity">
<ActivityId Value="{$thisParam/ACTIVITY/
@Value}"/>
</QUERY_DOCUMENT_LINK>
</QUERY_DOCUMENT_LINK>
</GET_DOCUMENT>
<FOR_EACH SelectList="$response/UserProfile"
CurrentElement="userProfile">
<APPEND_TO_XML DocVar="thisReturn">
<USER_PROFILE>
<ID Value="{$userProfile/UserID/@Val}"/>
<EMAIL_ADDRESS
Value="{$userProfile/Email/@Value}"/>
</USER_PROFILE>
</APPEND_TO_XML>
</FOR_EACH>
</DEFINE_IMPLEMENTATION>
Steps for Configuring Notification in a Task Node:

The following picture shows a typical configuration for a Notification on a task node:
Here is an explanation of the above properties of the notification component:

z Condition Expression: Expression which will indicate if a notification has to be
raised. The expression has to evaluate to true. Note that a the user could choose to
continue from the notification UI, therefore its imperative that the condition
specified in Condition Expression be available in Next Nodes. When the user
selects Continue from the notification UI then the same condition will be
evaluated in next nodes.
z Subject: This field will be used for the subject of the email.
z Message: This field will show up as the message for the user to comprehend the
issue.
z Activity: The value in this field will be used to get the email address of the users
who have been assigned the activity. When a notification condition is found to be
true then the node will invoke the getUserListBasedOnActivity function (as
described above) with the specified activity, once the users are returned from the
above function the system will create an email and send it to the appropriate
address, the email also contains a URL from which the user can access the details
page of the workflow from where he can decide what to do next.
The following is an example of an email sent out by the notification framework:

Task Event and Task Status Table
The user can click the link and go to the Details page and decide to either restart a
particular node or continue from the notification node. Details UI is explained in more
details in “UI Log and Monitoring” chapter.

Task Scheduler has a mechanism through which an external/internal application can
communicate back to the task workflows, this is possible if the external application
can insert a record into Task Scheduler table called TASK_SCHEDULE_STATUS
(Physical Name TS_STATUS). This table has the following properties:
This table has a insert trigger built in, which invokes a Task Event with the following
signature.

The above raise event derives all its properties from the data inserted into the
TASK_SCHEDULE_STATUS table. This mechanism inherently depends on the timer
server. Therefore its imperative that TIMER_SINK service be co-located with the
TASK_SCHEDULER service.
Here is an example workflow which demonstrates how the TaskEvent could be used:

The above workflow uses Launch Process to start an external process, after launching
the process the control moves to an event node which waits for //
TASK_SCHEDULER/TaskEvent, assuming that the external process after finishing
its operations will insert a record into TS_STATUS table. When the external
application inserts a record in TS_STATUS table, a trigger is used to create a raise
event in the TIMER_SINK service for the TaskEvent, this raise event uses the same
values as in the insert TS_STATUS, therefore the STATUS field is available to the
user in the post action of the Event node. On timer expiration the TIMER_SINK
service will execute a raise event for the TaskEvent, and the workflow will start
executing from the post actions of the Event node. The Events node can decide on
what to do next based on the STATUS received from the external application. Note

that the user has to specify the module name and the instance name as keys which are
evaluated right after pre actions of the event node.
Scheduling
The TIMER_SINK service is to be used for scheduling task workflows. Please read
detailed instructions about how to use timer service in the ABPP Services Guide.
The user can register Timer operations in the DEFINE_INIT of the service in which
the user has the task scheduler workflows. Within the START_TIMER a call back
duration could be setup such that the workflow is repeated based on the duration
specified. The user could also register a callback with rules to check more complex
conditions.
The following is an example of a START_TIMER which Invokes a Task Workflow
only on Weekday and will not be invoked on weekends
<DEFINE_INIT>
<RULE>
<ACTION>
<STOP_TIMER>
<IDENTIFIED_BY>
<NAME Value="SchedulerSample"/>
</IDENTIFIED_BY>
</STOP_TIMER>
<START_TIMER>
<IDENTIFIED_BY>
<NAME Value="SchedulerSample"/>
</IDENTIFIED_BY>
<CALLBACK_DURATION Value="{duration(0,1,0,0)}"/>
<CALLBACK_DATE Value="{date()}"/>
<CALLBACK_ACTIONS>

<IF_TEST Test="((getDayOfWeek() != 7) or (getDayOfWeek() !=

1))">
<THEN>
<START_WORKFLOW ServiceName="TASK_SAMPLE">
<TEMPLATE Value="SchedulerSample"/>
<Command Value="rawprocess.bat"/>
<Arguments Value="3"/>
</START_WORKFLOW>
</THEN>
</IF_TEST>
</CALLBACK_ACTIONS>
</START_TIMER>
</ACTION>
</RULE>
</DEFINE_INIT>

UI Log and Monitoring
In the above define init the user first stops the timer, this is to ensure that we do not
end up calling the same timer entry multiple times. Once the timer is stopped the start
timer is executed which registers the timer. The <CALLBACK_DURATION
Value="{duration(0,1,0,0)}"/> sets the duration of the timer entry in the given
example.
When the above timer expires the code under CALLBACK_ACTIONS is executed, in
the above scenario the system evaluates <IF_TEST Test="((getDayOfWeek() != 7) or
(getDayOfWeek() != 1))"> which checks to see if the current day is a weekday. If the
current day is a weekday only then workflow is executed.
The user could come up with different strategies around specifying the rules for
starting a workflow based on the requirements.

There are two workflows available out of the box in the TASK_SCHEDULER
service. The tsTaskHistory workflow can be used for viewing the log of Completed,
Active or Aborted workflows, the user can also cancel an Active workflow from this
screen as well as view the details of how the workflow has been executed so far is
available, and the tsDetails workflow can be used to view the details of a workflow,
the details include a list of nodes that have been executed so far and also a list of nodes
that need to be executed.
Note: Please note that just like any workflow in ABPP this workflow can be
extended and customized to meet different requirements.
Details of the workflows are as follows:
tsTaskHistory Workflow:
For the user to be able to see their workflow in this monitoring UI the user has to
follow certain steps while creating a TASK_SCHEDULER workflow.
On the workflow node set the following properties
| Set the Type attribute to “TASK_SCHEDULER”.
| Set the IsStartAllowed to “Yes”
| Set the NodeEventListener to “true” or set it to “default”, however, if the
property is set to ‘default’ then the node will look for ‘NodeEventListener’ in
the list of service parameters (these are specified in the service xml file), this
should be set to ‘true’, if it does not find this property set to true the logs may
not show up in the tsTaskHistory results.
Alternatively in the studio right click on a workflow and look up properties of the
workflow and set them as follows:

Note: NodeEventListener property enables a node listener which gets called on

every entry and exit of a workflow node. The current implementation of the
node essentially creates a log in ABPP database with the node name, type and
a timestamp. This log is eventually used by the task scheduler workflow
monitoring UI to display the status of the workflow.
The following picture shows the initial search screen of the tsTaskHistory table:
The above search fields are as follows:

z Services: The first field queries all the services in the Solution and lists them.
z Templates: Selecting the Service populates the Templates field with the available
templates which have the following properties as specified earlier they should be
of Type “TASK_SCHEDULER” and IsStartAllowed=”Yes”.
z Start Date Range: This filter will search for the workflows that started executing
between these dates.
z End Date Ranges: This filter will search for the workflows that finished
executing between these dates.
z Status: Lets the user filter by the status of the workflows, the user can filter by
“Active”, “Completed” and “Aborted“ workflows.

z Started By: The user can also filter by the Started By parameter.
Once the user sets up the above parameters and hits the search button the following
results are displayed:
The results have the following details:

z Selector: The selector shows up only if the workflow is active, the user can select
this and hit the Cancel Workflow button to abort the workflow.
z Details: This image link takes the user to the details page as follows:
| Nodes Executed: These are nodes that were executed in the workflow
z Name: Name of the Node (this is the name that is entered at design time)
z Type: Type of Node
z Start Time: The time at which the node started execution
z End Time: The time at which the node started execution. If the end time is
not found that means the node has not finished execution.
z Status: Completed if the node finished execution, empty otherwise.
| Nodes Not Executed: These are nodes that are not executed so far.
z Field Explanation is same as Nodes Executed except that the Start Time,
End Time and Status are always blank as there is execution that has
happened on these nodes.
z Description: If the Workflow Description is populated that will show up here.
z Start Date: Start time of the workflow
z End Date: End time of the workflow
z Status: Current Status of a workflow.

tsDetails Workflow:
The tsDetails workflow allows the user to directly go to the Details page and look
at the execution path of the workflow. This page is ideal for notifications as it
takes the user directly to the pertinent information page.
The first column is selectable only if there is a notification pending on the relevant
workflow.
Here is a detailed description of the above fields:
z Nodes Executed: These are nodes that were executed in the workflow
| Name: Name of the Node (this is the name that is entered at design time)
| Type: Type of Node
| Start Time: The time at which the node started execution
| End Time: The time at which the node started execution. If the end time is not
found that means the node has not finished execution.
| Status: Completed if the node finished execution, empty otherwise.
z Nodes Not Executed: These are nodes that are not executed so far.
Field Explanation is same as Nodes Executed except that the Start Time, End
Time and Status are always blank as there is execution that has happened on these
nodes.
z Continue Button: The Continue button will be displayed when the workflow is in
a notification state. The press of this button will allow the workflow to go forward
with the next nodes and evaluate conditions on the next node.
z Restart Button: The Restart button will be displayed when the workflow is in a
notification state, the user can select any node of his choice and click the Restart
button to restart the workflow from that point onwards. Note that non Task
Scheduler nodes will not be restartable.
z Important note, if a workflow is either ACTIVE, COMPLETED or ABORTED
Restart and Continue buttons will not appear

Suggestions and Best Practices
Suggestions and Best Practices
Debug External Processes:

While debugging workflows in which there are Wait Process and/or Launch Process
Nodes it’s helpful to see the launched processes System out statements. The toolkit
has a method through which this can be achieved. These steps assume that the user is
using studio to debug Wait / Launch Process workflows:
1. Close the studio if it’s already running.
2. Open the file appSettings.xml which is installed by the studio installer in the
following location: C:\Documents and Settings\<windows userid>\i2\studio
3. Search for the string XCORE_JVM_OPTIONS in appSettings.xml. This property
defines the parameters which are used for launching all processes from studio,
including ABPP server process (ABPP server will be the server where we will be
running our workflows). The existing value for this component will be as follows:
<COMPONENT Name="JavaProcess">
<Property Name="XCORE_JVM_OPTIONS" Value="-Xms128M -
Xmx512M"/>
</COMPONENT>
Change the above component definition to include the vm

system property process.debug.output set to true as follows:
<COMPONENT Name="JavaProcess">
<Property Name="XCORE_JVM_OPTIONS" Value="-Xms128M -
Xmx512M -Dprocess.debug.output=true"/>
</COMPONENT>
4. Start the studio and execute workflow which either has any of the Launch/Wait
process nodes. Now notice that the ABPP process console gets the output from the
launched process.
Note: The external process launched from the Launch/Wait Process Nodes are still
external to studio or ABPP server, it’s just that we register the output stream
to the console of ABPP.
Subworkflows:
Ideally the task workflows will be monitored by the Admin user group, to keep the
monitoring view fairly straight forward its suggested not to use subworkflows.
However, in certain scenarios it might be necessary to use subworkflows, in such
situations it might be best to create a subworkflow which has
Type=”TASK_SCHEDULER” and IsExternalStartAllowed set to “true”. This way
the user could directly search for the subworkflow and monitor it.

Stop Running tasks:

In the wait process node once a process is launched, there is no UI to stop the process.
As mentioned earlier the process either has to return with an exit code or timeout.
Therefore its suggested that the TimeOut value be picked appropriately.
Handler Task Errors:

As explained earlier all the task nodes have a implicit variable called outputDocVar,
this variable has a Status attribute which will be set to either ‘Success’ or ‘Error’. If
the value of this attribute is set to Error usually a Description is returned as to what the
error was. The user can use this value to either notify or change the path of the
workflow execution by creating next nodes as follows: $outputDocVar/
@Status=’Error’. This will allow the user to handle errors occurring in a task node.
Complex start conditions:

The user can setup TIMER_CALLBACK conditions to be as complex as they wish to
make it, refer to Timer service documentation and also XPath functions for Time.
Today there is no UI to configure this, however, at implementation time a customized
UI could be generated to achieve online configuration.
Node Input Parameter:

All task scheduler nodes except for Launch Process node are restartable, they also
have a Node Input parameter which can accept input from the previous node. It is
suggested that this may not be used because when these nodes are restarted in a
workflow the input would have been forgotten
Adding tsHistory workflow to an Application

The user can point to the tsTaskHistory workflow in TASK_SCHEDULER service in
their Navigation.pgl, that will start showing this workflow

Chapter 5
Email Service
Introduction
Email support in ABPP is provided by the OMS_MESSAGE_SERVICE service. This
is an archived service (available in bpe-services.jar) that provides an X-Rule method
that can be called from other services to send out emails.
The name OMS_MESSAGING_SERVICE is misleading and will be renamed to some
thing more meaningful like EMAIL in next major release of ABPP.
For most of the ABPP applications that need dashboard kind of functionality, the
emails will be generated from MESSAGING service. In such cases this service needs
to be setup as explained in next section but there is no need to call this service directly.
Please refer to MESSAGING service chapter for details on features provided by
MESSAGING.
Setup
The service configuration file for this service has following service parameters that
need to be set properly:
z om.smtpHost: This service parameter defines the SMTP host name. The value
can be a host name or host IP address.
z om.systemFromAddress: This service parameter defines the default from
address that will be used when from address is not provided as part of the request.
z isEmailEnabled: This flag can be set to ‘true’ or ‘false’. Default is ‘false’. If set
to ‘false’ no email will be sent from the system.
As this is an archived service, to change these parameters create a custom service
extension and then change these parameters in the custom service configuration file.
When using Studio, the service can be customized by right clicking on this service
node in left navigation and selecting ‘Customize Service…’ menu option.

Chapter 5 Email Service
To change these parameters, open the custom service configuration file and add
following parameters with proper values.
Sending Emails
To send out emails this service provides an X-Rule method “sendEmail. The
API_DOC for this method is:
<API_DOC>
<INPUT>
<REQUEST Name="sendEmail">
<SMTP_HOST Value="i2.com" Optional="true" Comment="Defaults to
om.smtpHost service parameter"/>
<FROM_ADDRESS Value="dummy@i2.com" Optional="true" Com-
ment="Defaults to om.systemFromAddress service parameter"/>
<TO_ADDRS>
<TO_ADDR Value="abc@i2.com" Repeatable="true"/>
</TO_ADDRS>
<CC_ADDRS Optional="true">
<CC_ADDR Value="fdhd@i2.com" Repeatable="true"/>
</CC_ADDRS>
<BCC_ADDRS Optional="true">
<BCC_ADDR Value="fdhd@i2.com" Repeatable="true"/>
</BCC_ADDRS>
<SUBJECT Value="some subject"/>
<FORMAT Value="TEXT|HTML"/>
<MESSAGE>
<DATA Value="some data" Optional="true" Comment="One of DATA or
XML_DATA is required"/>
<XML_DATA XsltFileName="inv.xsl" Optional="true" Comment="One of
DATA or XML_DATA is required">
<ANY/>
</XML_DATA>
</MESSAGE>
<ATTACHMENTS Optional="true">
<ATTACH_FILE_NAME Value="demo.doc" Repeatable="true"/>

Sending Emails
</ATTACHMENTS>
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE Status="Success"/>
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
The various tags expected by this x-rule method are explained below:
SMTP_HOST
This specifies the SMTP host to use to send the email. This is optional and if
not specified the ‘om.smtpHost’ parameter specified in the service
configuration file is used.
FROM_ADDRESS
This specifies the ‘from’ address for the email. Most SMTP servers will force
this to be a valid email address in the server’s domain. This is optional and if
not specified the ‘om.systemFromAddress’ parameter specified in the service
configuration file is used.
TO_ADDR
This specifies email address of a recipient in ‘To’ category. Multiple
TO_ADDR tags can be used to send email to multiple recipients.
CC_ADDR
This specifies email address of a recipient in ‘Cc’ category. Multiple
CC_ADDR tags can be used to send email to multiple recipients.
BCC_ADDR
This specifies email address of a recipient in ‘Bcc’ category. Multiple
BCC_ADDR tags can be used to send email to multiple recipients.
SUBJECT
This specifies subject of the email.
FORMAT
Valid values for this are TEXT or HTML. Using TEXT will result in a plain
text email. The HTML type should be used for emails where the body is a
HTML document so that the client displays it properly.
MESSAGE
This tag is used to define the email body. There are two ways to specify the
email body contents. The DATA tag can be used to specify the content as a
string. The XML_DATA tag can be used to convert XML data to email body
content (either plain text or HTML) using an XSL file specified by the

XsltFileName attribute. The XSL file should be specified using absolute path
or path relative to classpath.
ATTACH_FILE_NAME
This tag is used to send a file as an attachment in the email. The Value
attribute specifies the absolute path or path relative to working directory of
the attachment file.
Example 1: Sending simple text email

This example shows the simplest form of a call to ‘sendEmail’
<REQUEST Name="sendEmail">
<TO_ADDRS>
<TO_ADDR Value="testuser@testcompany.com"/>
</TO_ADDRS>
<SUBJECT Value="Test"/>
<FORMAT Value="TEXT"/>
<MESSAGE>
<DATA Value="This is a test email"/>
</MESSAGE>
</REQUEST>
Example 2: Sending HTML format email using XSL file

In this example an X-Rule method is used to show how dynamic data can be sent as
part of an email. The email format used is HTML and the email body is specified by
using XML_DATA and XSL file (EmailTest.xsl). Using this approach has an
advantage that the email formatting information is kept separately from the x-rules
code and allows use of powerful transformation language like XSL. The drawback is
that the user has to be conversant with XSL.
<DEFINE_METHOD Name="testEmailXmlData">
<RULE>
<ACTION>
<TO_DOCVAR AssignToVar="orderData">
<ORDERS>
<ORDER>
<ID Value="P1"/>
<ITEM Value="Brake Pads"/>
<QUANTITY Value="4"/>
<SHIP_DATE Value="01/10/2007"/>
</ORDER>
<ORDER>
<ID Value="P2"/>
<ITEM Value="Brake Drum"/>

Sending Emails
</ORDER>
</ORDERS>
</TO_DOCVAR>
<REQUEST Name="sendEmail" Service-
Name="OMS_MESSAGE_SERVICE">
<TO_ADDRS>
</TO_ADDRS>
<FORMAT Value="HTML"/>
<MESSAGE>
<XML_DATA XsltFileName="EmailTest.xsl">
<TO_XML SelectList="$orderData/ORDER"/>
</XML_DATA>
</MESSAGE>
</REQUEST>
</ACTION>
</RULE>
</DEFINE_METHOD>
Contents of EmailTest.xsl:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Trans
form">
<xsl:template match="XML_DATA">
<html>
<body>
<b>Summary of Orders</b>
<table border="1">
<tr bgcolor="#9acd32">
<th align="left">Id</th>
<th align="left">Item</th>
<th align="left">Quantity</th>
<th align="left">Ship Date</th>
</tr>
<xsl:for-each select="ORDER">
<tr>
<td>
<xsl:value-of select="ID/@Value"/>
</td>

<td>
<xsl:value-of select="ITEM/@Value"/>
</td>
<td>
<xsl:value-of select="QUANTITY/@Value"/>
</td>
<td>
<xsl:value-of select="SHIP_DATE/@Value"/>
</td>
</tr>
</xsl:for-each>
</table>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
Example 3: Sending HTML format email using X-Rules

This example shows how X-Rules can be used to build the HTML body of an email
without using an XSL file.
<DEFINE_METHOD Name="testEmail">
<RULE>
<ACTION>
<TO_DOCVAR AssignToVar="orderData">
<ORDERS>
<ORDER>
<ID Value="P1"/>
<ITEM Value="Brake Pads"/>
</ORDER>
<ORDER>
<ID Value="P2"/>
<ITEM Value="Brake Drum"/>
</ORDER>
</ORDERS>
</TO_DOCVAR>
<TO_DOCVAR AssignToVar="emailBody">

Sending Emails
<html>
<body>
<b>Summary of Orders</b>
<table border="1">
<tr bgcolor="#9acd32">
<th align="left">Id</th>
<th align="left">Item</th>
<th align="left">Quantity</th>
<th align="left">Ship Date</th>
</tr>
<FOR_EACH SelectList="$orderData/ORDER" Curren-
tElement="order">
<APPEND_TO_XML>
<tr>
<td>{$order/ID/@Value}</td>
<td>{$order/ITEM/@Value}</td>
<td>{$order/QUANTITY/@Value}</td>
<td>{$order/SHIP_DATE/@Value}</td>
</tr>
</APPEND_TO_XML>
</FOR_EACH>
</table>
</body>
</html>
</TO_DOCVAR>
<XML_TO_STRING FromSelect="$emailBody" DocVar="emailBodyS-

tring"/>
<REQUEST Name="sendEmail" Service-

Name="OMS_MESSAGE_SERVICE">
<TO_ADDRS>
</TO_ADDRS>
<FORMAT Value="HTML"/>
<MESSAGE>
<DATA Value="{$emailBodyString}"/>
</MESSAGE>
</REQUEST>
</ACTION>
</RULE>

</DEFINE_METHOD>

Chapter 6
Messaging Service
Introduction
The MESSAGING service is a utility service that can be used to notify a group of
users by email or by alerts on their Web UI about an event that has occurred in the
system. Examples of events are: Order creation, Order needs approval etc. Notifying
the users is referred to as sending a message to the user and the business event that
triggers this notification is referred to as messaging event.
This service can be used by all other services (lets call them client services) to send
messages to different recipients. The client services have to define xml specification
files for each type of messaging event they intend to send. The specification files
include messaging details like: messaging event that will be raised by the client
service, recipients for the event, message format (email or Web UI alert) and message
content.
Then to raise/generate messaging events at appropriate places in the business
workflows the client service invokes a predefined X-Rule action component called
'RAISE_MSG_EVENT'. The parameters to 'RAISE_MSG_EVENT' identify the
messaging event configuration to use and also provide event related details like Order
ID, Items etc. On such an invocation the MESSAGING service uses the messaging
event configuration that has already been loaded and the data provided by
'RAISE_MSG_EVENT' to notify appropriate recipients. Please note that
RAISE_MSG_EVENT action component has no relation to RAISE_EVENT action
component.
Functionality and Setup

The MESSAGING service can send messages in two formats: Alert (using WebUI) or
Email. For actual transmission in Email format the OMS_MESSAGING_SERVICE
service is used. The Alert creation and display/maintenance on Web UI are handled by
the MESSAGING service locally.
The MESSAGING service can be configured to work with any User Security service
(service providing user details) to access the user information like email address, etc.

Chapter 6 Messaging Service
Please refer to MESSAGING/Events/EMRequestDescriptors.xml for the interface to

be implemented by the user security service. The USER_SECURITY service
packaged as part of Studio samples in the userSecurity folder has a reference
implementation of this interface.
The following diagram shows the interactions between MESSAGING service and
other services:
For a client service to use the MESSAGING service the steps to be followed are as
follows:
1. Define Message Event: The first specification that the client service has to define
is the list of message events that it will generate. Each message event has a name
that needs to be unique within the client service.
2. Define Message Template: Based on messaging events the client service needs to
define the message templates that provide the contents of the message in different
protocols (EMAIL and/or ALERT). Each message template has a name that
should be unique within the client service.
3. Define Recipient Groups: Next step is to define the Recipient Groups needed.
Recipient Group is a logical grouping of recipients and maps to one or more
recipient. A recipient is a valid user in the system as identified by the User
Security service. The recipient group specification allows for three types of
recipient groups ENTITY, RULE and CUSTOM. These are explained later. Each
Recipient Group is uniquely identified by its name across all client services in the
system.
4. Link Message Event to Message Template and Recipient Groups: The next
step in setting up messaging is to link each of the message events with appropriate
message template to use and provide a list of recipient groups to be notified as a
result of the message event.
5. Loading messaging specification files: All of the above configurations are done
in xml specification files and these files are specified in the service configuration
file of the client service.

6. Raise message event: Finally to send messages i.e. notify users, the client service
uses 'RAISE_MSG_EVENT' x-rule action component from its workflows/x-rules.
On receiving this invocation the MESSAGING service will use the specifications
defined in previous steps to notify appropriate recipients.
Each of the steps above is explained in more details below.
Define Message Events

The message events that a client service can generate are specified in following
format:
Syntax:
< m e s s a g in g >
< ev e n ts >
< e v e n t N a m e = "E v en t N a m e " S er v ic e N a m e = "C lie n tS e rv ic e "
D oc u m e n t = "X m lD o c u m e n t[O p t io n a l= tr u e] " O n E v en t T y p e C lic k = "U IW ork flo w [O p t io n a l= tr u e] "
C at e g o r y= "O r d er[ O p tio n a l= tru e ]" R e p ea t a b le = "tr u e "/ >
< /e v e n ts >
< /m es s a g in g >
The <event> tag above defines a message event.

Attributes:
z Name (Required): This specifies the message event name. This can be any user-
defined string and has to be unique within the client service.
z ServiceName (Required): This specifies the client service that is publishing the
event.
z Document (Optional): In most cases the message event will be in relation to some
business object e.g. order, forecast, item, user etc. This attribute specifies the
logical name of the input xml document that represents this business object.
Specifying this attribute is optional and just provides a hint to the developer about
the xml input needed for the message event. The actual input xml document is
passed as a parameter to 'RAISE_MSG_EVENT' (explained later). If this attribute
is not specified then it indicates that the messaging event does not need any input
xml to send out the messages. This document name does not have a relation to the
X-Documents defined in ABPP.
z Category (Optional): This attribute specifies the category that the event belongs
to. The Recipients can control the messages that they receive based on Category
of the event. If this attribute is not defined then only those users who have
subscribed to 'All' categories will be notified about the event. Refer to the
Recipient Group section of this document for details on how the recipient
specifies the categories for which they want to receive messages.
z OnEventTypeClick (Optional): This attribute specifies the UI workflow to
execute to show details of the alert. For example if the alert is 'Order created by
buyer' then this screen may show order details. This should be a fully qualified
workflow name i.e. //<serviceName>/<workflowName>. The input passed to this
UI workflow has all the details of the message alert. Refer to Alert Details section
below for more details. If this attribute is not specified then the Web UI would not
provide hyperlink for that specific alert to go to the alert details.

Example:
<messaging>
<events>
<event Name="CoCreditHoldEvent" ServiceName="ORDER_ADMIN"
Document="CUSTOMER_ORDER" Category="Order"/>
<event Name="AoRouteEvent" ServiceName="ORDER_ADMIN" Document="ACTIVITY_OR
OnEventTypeClick="//ORDER_ADMIN/orderReview" Category="ActivityOrder"/>
...
</events>
</messaging>
Define Message Template

A message template defines the contents of the message being sent to the user. The
message can be sent using two protocols ALERT and/or EMAIL. Message content for
either one or both protocols can be defined. Defining the message template using a
separate specification allows for reuse of a message template across various message
events if needed. The syntax for message templates is shown below.
Below wherever the specification allows an X-Path expression the input xml
document passed as input to 'RAISE_MSG_EVENT' is available as variable 'thisDoc'
for use in the X-Path expression.
Syntax:
<messaging>
<message_templates>
<message_template_resource ServiceName="ClientService"
ResourceBundleName="ClientServiceMsgResources" Optional="true"/>
<message_template Name="TemplateName" ServiceName="ClientService"

Document="XmlDocument[Optional=true]" Repeatable="true">
<comm_protocol Type="ALERT" Optional="true">
… contents explained below …
</comm_protocol>
<comm_protocol Type="EMAIL" Optional="true">
</comm_protocol>
</message_template>
</message_templates>
</messaging>
<message_template_resource>: This tag is used for enabling internationalization of

the emails that the message template defines.
Attributes:
z ServiceName (Required): The Client Service that is defining this message
template.
z ResourceBundleName (Required): This defines the base file name to be used for
the language resource bundle. For example if this value is 'messaging' then the
base resource bundle file expected is 'messaging.properties'. A resource bundle is
a text file that defines translations for string resources used in the application. The
contents of this file looks like:
EMAIL_NOTIFICATION_SUB=Email Notification
EMAIL_NOTIFICATION_MSG=This is an email notification for {0}
…

The base resource bundle file defines the default translations. For various
languages supported the appropriate resource bundle file needs to be defined. The
naming convention for the resource bundle file is
'<baseName>_<language>_<country>.properties' and use of <country> is
optional. The list of languages and countries can be found at http://ftp.ics.uci.edu/
pub/ietf/http/related/iso639.txt and http://userpage.chemie.fu-berlin.de/diverse/
doc/ISO_3166.html (use 2 letter codes).
As an example the English bundle for country US should be provided in file

'messaging_en_US.properties'. For German bundle the file name will need to be
'messaging_de.properties'. These resource bundle files should be available in a
directory that is specified in the CLASSPATH set for the solution.
Such a combination of language and country is referred to as 'Locale' of the user.

For message templates these resource bundles are used to internationalize the
email subject and simple email body text (using the <text> tag) based on locale
defined for the recipient.
<messageTemplate>: This tag as shown above defines a message template.
Attributes:
z Name (Required): This defines the template name. The name of the template
Should be unique within the Client Service that is defining the template.
z ServiceName (Required): This is the Client Service that is defining the template.
z Document (Optional): This specifies the logical name of the input xml document
that the template is expecting to send out appropriate message. Specifying this
attribute provides a hint to the developer that this template can only be used for
those message events that are also expecting same input xml document.
<comm_protocol>: This tag provides details for a communication protocol like
EMAIL or ALERT. The Type attribute is required and specifies the communication
protocol type. Valid values are EMAIL or ALERT. The contents of this tag are
different based on Type defined and are explained in sections below.
Example:
<messaging>
<message_templates>
<message_template_resource ServiceName="ORDER_ADMIN"
ResourceBundleName="oaMsgResourceBundle"/>
<message_template Name="CoCreditHoldMT" Document="CUSTOMER_ORDER"
ServiceName="ORDER_ADMIN">
<comm_protocol Type="ALERT">
... See details below ...
</comm_protocol>
<comm_protocol Type="EMAIL">
... See details below ...
</comm_protocol>
</message_template>
</message_templates>
</messaging>
ALERT Template
The syntax for <comm_protocol> of type "ALERT" is:

Syntax:

<priority Value="0|1|2|3" Comment="0 – Fatal, 1 – Severe, 2 – Warning, 3 - Information"/>
<url>
<document_id Select="X-Path expression"/>
<document_name Value="LiteralLogicalDocumentName"/>
</url>
<message Type="TEXT">
<text>Alert text using {n} for arguments</text>
<args Optional="true">
<arg Select="X-Path expression" Repeatable="true"/>
</args>
</message>
</comm_protocol>
<priority>: This tag defines the priority of the alert. Possible values are:
0 for Fatal.
1 for Severe
2 for Warning
3 for Information
The priority of an alert is used by the user to narrow down search results on the Web
UI.
Please note that in message template the priority is defined by numbers (for example
2) but while using the UI, only text equivalent of priority (for example Warning) will
be shown.
<document_id>: The alert being generated may be related to a business object like
order, shipment etc that can be uniquely identified by some ID. This tag is used to
capture this ID. The Select attribute specifies an X-Path expression to be evaluated at
runtime to calculate the document id. The document id captured here is shown on the
Web UI and also passed to the alert details UI workflow that is invoked when the user
clicks on the alert.
<document_name>: This tag can be used to specify a logical name of the business
document who's ID has been captured by the document_id tag. This is also passed to
the UI workflow that is invoked when the user clicks on the alert.
<message>: This tag is used to define the alert message to be shown on the Web UI.
The 'Type' attribute should be set to 'TEXT'.
<text>: This tag provides the alert message to be shown on the Web UI. The alert
message is specified as xml-text element of this tag. The message can be specified
using dynamic arguments by using curly brackets like {0}, {1},…, {n}.
<arg>: This tag is used to define the dynamic arguments specified in <text>. The first
<arg> corresponds to {0}, second to {1} and so on. The Select attribute specifies the
X-Path expression to be evaluated at runtime to get the argument value.

Example:
<com m _protocol Type="ALER T">
<priority Value="5"/>
<url>
<docum ent_id Select="$thisDoc/ID/@ Value"/>
<docum ent_nam e Value="CUSTOM ER_OR DER"/>
</url>
<m essage Type="TEXT">
<text>Credit hold placed on custom er order {0} with BillTo {1}</text>
<args>
<arg Select="$thisDoc/ID/@ Value"/>
<arg Select="$thisDoc/BILL_TO _ID/@ Value"/>
</args>
</m essage>
</com m _protocol>
EMAIL Template
The syntax for specifying <comm_protocol> of type "EMAIL" is shown below.
Syntax:
<subject Value="Email subject using {n} for arguments">
<args Optional="true">
</args>
</subject>
<from_address Select="X-Path expression" Optional="true" Comment="Defaults to om.systemFromAddress
service parameter in OMS_MESSAGE_SERVICE"/>
<format Value="text|html"/>
<message Type="TEXT|XML">
<text Optional="true" Comment="Required for message type TEXT">Email text using {n} for
arguments</text>
<args Optional="true" Comment="Required for message type TEXT">
</args>
<data Select="X-Path expression for xml to be passed to XSL file" Optional="true" Comment="Required for
message type XML"/>
<xsl_file Value="Absolute or relative path of XSL file" Optional="true" Comment="Required for message
type XML"/>
</message>
</comm_protocol>
<subject>: This tag defines the subject of the email. The Value attribute specifies the
email subject. The subject can be specified using dynamic arguments by using curly
brackets like {0}, {1},…, {n} and corresponding <arg> tags inside <subject>. By
specifying the subject value as some string that is specified in the language resource
bundles explained before, the email subject can be internationalized based on locale
defined for the email recipient.
<from_address>: This tag specifies the 'From' address of the Email. If there is no
from_address specified then default 'From' address used will be
om.systemFromAddress service parameter defined in OMS_MESSAGE_SERVICE
service.
<format>: This tag specifies the format of the message. Valid values for this tag are
"text" or "html". Default value is "html". If format specified is "text" then the contents
of the email sent will be treated as plain text by the mail client. The 'text' format is
useful for simple emails. The "html" format is used to send emails where the email
content is an html document.
<message>: This tag is used to specify the email body. To send out simple text emails
the <text> and <args> child tags are used. To send out emails with html content the
<data> and <xsl_file> child tags are used.

<text>: The text of this tag specifies the email body. Dynamic arguments can be
specified by using curly brackets like {0}, {1}, … {n} etc. By specifying the text of
this tag as a string that is specified in the language resource bundles explained before,
the email body can be internationalized based on locale defined for the email
recipient.
<arg>: This is used to define dynamic arguments for email body specified by <text>
tag. The first <arg> corresponds to {0} in email body text, second to {1} and so on.
<data>: The Select attribute of this tag specifies the xml document to use for
generating HTML contents of the email.
<xsl_file>: The Value attribute of this tag specifies the XSL file to apply to the xml
document identified by <data> tag to generate the HTML body of the email. The XSL
file should be specified using absolute path or path relative to classpath.
Internationalization is not supported when an XSL file is used.
Example 1:
<subject Value="Credit hold on customer order"/>
<from_address Select="$thisDoc/EMAIL/@Value"/>
<format Value="text"/>
<message Type="TEXT">
<text>Credit check resulted in credit hold for Customer Order Id: {0}</text>
<args>
<arg Select="$thisDoc/ID/@Value"/>
</args>
</message>
</comm_protocol>
Example 2:
<subject Value="Credit hold on customer order"/>
<from_address Select="$thisDoc/EMAIL/@Value"/>
<format Value="html"/>
<message Type="XML">
<data Select="$thisDoc"/>
<xsl_file Value="CreateHoldEmail.xsl"/>
</message>
</comm_protocol>
Contents of CreateHoldEmail.xsl:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="CUSTOMER_ORDER">
<html>
<body>
<b>Credit check resulted in credit hold for Customer Order Id: <xsl:value-of
select="ID/@Value"/></b>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
Define Recipient Groups

Recipient Group represents a collection of recipients who will be notified when the
message event is raised. Each recipient group can have a list of recipient definitions
(specified by <recipient_def> as shown below). Each recipient definition is evaluated

at run-time to find the recipients that need to be notified. Recipients from each
recipient definition are combined to form the final unique list of recipients.
Defining the recipient groups using a separate specification file allows for reuse of a
recipient group across various message events. The syntax for defining recipient
groups is:
Syntax:
<messaging>
<recipient_groups>
<recipient_group Name="RecipientGroup1" ServiceName="ClientService[Optional=true]"
Document="XmlDocument[Optional=true]" >
<recipient_def Name="RecipientDef1" Type="ENTITY" Optional="true" Repeatable="true">
</recipient_def>
<recipient_def Name="RecipientDef2" Type="RULE" Optional="true" Repeatable="true">
</recipient_def>
<recipient_def Name="RecipientDef3" Type="CUSTOM" Optional="true" Repeatable="true">
</recipient_def>
</recipient_group>
</recipient_groups>
</messaging>
<recipient_group>: This defines a recipient group. The recipient group is uniquely

identified by the 'Name' attribute and is not specific to any service.
Attributes:
z Name (Required): Uniquely identifies the recipient group.
z ServiceName (Optional): This defines the ClientService that is defining the
recipient group. This is for information purpose only.
z DocumentName (Optional): This specifies the logical name of the input xml
document that the recipient group is expecting at runtime to find appropriate
recipients. Specifying this attribute provides a hint to the developer that this
recipient group can only be used for those message events that are also expecting
same input xml document.
<recipient_def>: A recipient group can be formed of multiple <recipient_def> i.e.
recipient definitions. Each recipient definition is evaluated at runtime to find the
recipients. There are three types of recipient definition supported: ENTITY, RULE
and CUSTOM.
Attributes:
z Name (Required): The name of the recipient definition has to be unique within the
recipient group.
z Type (Required): This identifies the type of the recipient definition. Valid values
are ENTITY, RULE and CUSTOM. Each of this type is explained below.

Example:
<messaging>
<recipient_groups>
<recipient_group Name="CoCreatorRG" ServiceName="ORDER_ADMIN"
Document="CUSTOMER_ORDER">
<recipient_def Name="RecipientDef1" Type="ENTITY">
... recipient def of type ENTITY. See details below ...
</recipient_def>
<recipient_def Name="RecipientDef2" Type="RULE">
... recipient def of type RULE. See details below ...
</recipient_def>
<recipient_def Name="RecipientDef3" Type="CUSTOM">
... recipient def of type CUSTOM. See details below ...
</recipient_def>
</recipient_group>
</recipient_groups>
</messaging>
In the above example the recipient group 'CoCreatorRG' is defined for service
'ORDER_ADMIN' and document 'CUSTOMER_ORDER'. That means that the
recipient group needs a CUSTOMER_ORDER document for evaluation and so is
compatible only with those message events that are also defined for the same
document.
The different recipient definition types are explained below.
ENTITY Recipient Type

The syntax for recipient definition of type 'ENTITY' is shown below.
Syntax:
<recipient_def Name="RecipientDef1" Type="ENTITY" Optional="true" Repeatable="true">
<entity_type Value="USER[Type=string]"/>
<entity_id Select="X-Path expression"/>
</recipient_def>
When the recipient definition is of type 'ENTITY', at runtime the recipients are
evaluated by invoking a request descriptor 'getEntityMessagingInfo'. The 'entity_type'
and runtime value of 'entity_id' XPath expression specified above are passed as
parameters to this request descriptor. The request descriptor can be implemented by
any service in the solution and is generally implemented by the User Security service.
The rule implementing the request descriptor is expected to return appropriate
recipients and their contact information. The API_DOC for the request descriptor can
be found in MESSAGING/Events/EMRequestDescriptors.xml in Studio left
navigation. The valid values for <entity_type> will depend on the rule implementing
the request descriptor. The USER_SECURITY service packaged as part of Studio
examples in the userSecurity folder provides basic implementation of the
‘getEntityMessagingInfo’ request descriptor. It supports only 'USER' as a valid value
for <entity_type>. Also it assumes that all users are interested in all categories of
events.
Example of recipient_def of type ENTITY:
<recipient_def Name="Creator" Type="ENTITY">
<entity_type Value="USER"/>
<entity_id Select="$thisDoc/CREATED_BY_ID/@Value"/>
</recipient_def>

RULE Recipient Type

The recipient definition of type RULE can be used to evaluate recipients by calling a
custom rule. The syntax for this type of recipient definition is:
Syntax:
<recipient_def Name="RecipientDef2" Type="RULE" Optional="true" Repeatable="true">
<request Name="customRule" ServiceName="CustomRuleService"/>
</recipient_def>
<request>: This defines the custom rule to be called and its service.
Attributes:
z Name (Required): The name of the custom rule to be invoked to find the
recipients.
z ServiceName (Required): Name of the service that is implementing this custom
rule. The custom rule can be implemented in any service.
This type of recipient definition is used when the logic to figure out the recipients is
complex. Here the MESSAGING service will call the user-defined rule at runtime to
get the recipient information. The input to the rule is the input xml document passed as
a parameter to 'RAISE_MSG_EVENT' (if a document is specified for the recipient
group).
The request to this rule will be like:
<REQUEST Name="customRule" ServiceName="CustomRuleService">

…
</REQUEST>

The output format expected back from the rule is as follows:

<RESPONSE>
<RECIPIENT Repeatable=”true”>

<ENTITY_ID Value=" user1"/>
<ENTITY_TYPE Value="USER"/>
<LOCALE Value="en_US"/> 
<!—The EVENT_CATEGORIES tag lists the event categories that the
recipient is interested in. If EVENT_CATEGORIES tag is not present it will
imply that the recipient is not interested in any events. A special event
category 'All' is allowed to indicate that the recipient is interested in all
categories. At runtime, if the category of the message event that is being
evaluated is not listed in this EVENT_CATEGORIES list then the recipient will
not receive notification for this message event. -->
<EVENT_CATEGORIES>
<EVENT_CATEGORY Value="All"/>
</EVENT_CATEGORIES>

<COMM_PROTOCOLS>
<COMM_PROTOCOL Type="EMAIL">
<ADDR Value="abc@abc.com"/>
</COMM_PROTOCOL>
<COMM_PROTOCOL Type="ALERT">
<USER_ID Value="user1"/>
</COMM_PROTOCOL>
</COMM_PROTOCOLS>
</RECIPIENT>
</RESPONSE>
Example of recipient_def of type RULE:

<recipient_def Name="recipient1" Type="RULE">
<request Name="customRuleForApproverMessagingInfo" ServiceName="APPROVAL"/>
</recipient_def>
In this example the custom rule 'customRuleFormApproverMessagingInfo' on service

'APPROVAL' will be called to get the appropriate recipients.
CUSTOM Recipient Type

The recipient definition of type CUSTOM can be used in cases where the contact
information for the recipient like email address and user_id are fixed and known while
writing the specification. CUSTOM allows you to 'inline' the information about the
recipient.
Syntax:
<recipient_def Name="RecipientDef3" Type="CUSTOM" Optional="true" Repeatable="true">
<event_categories>
<event_category Value="Category1" Repeatable="true"/>
</event_categories>
<comm_protocols>
<USER_ID Value="userId"/>
</comm_protocol>
<ADDR Value="user@abc.com"/>
</comm_protocol>
</comm_protocols>
</recipient_def>

<event_category>: This tag is used to list the event categories that the recipient is
interested in. If no <event_category> tags are listed then it implies that the recipient is
not interested in any events. A special event category 'All' is allowed to indicate that
the recipient is interested in all categories. At runtime, if the category of the message
event that is being raised is not listed in this list then the recipient will not receive
notification for that message event.
<comm_protocol>: This is used to provide the contact information for the recipient.
The 'Type' attribute can be 'ALERT' or 'EMAIL'. Either one or both protocol types can
be specified. The expected children of this tag are shown above.
Example of recipient_def of type CUSTOM:
<recipient_def Name="recipient1" Type="CUSTOM">
<event_categories>
<event_category Value="All"/>
</event_categories>
<comm_protocols>
<comm_protocol Type="ALERT">
<USER_ID Value="admin"/>
</comm_protocol>
<ADDR Value="admin@abc.com"/>
</comm_protocol>
</comm_protocols>
</recipient_def>
Link Message Event to Message Template and Recipient Groups

The previous sections have shown how message events, message templates and
recipient groups are defined. The message events are synonymous with business
events that need to be notified to users. The message templates define the content of
the alert or email that is sent to the users and the recipient groups identify the users
who will be notified.
The last step in completing the messaging specification is to link each message event
with appropriate message template and recipient groups. The syntax of specification
used for doing this is shown below.
Syntax:
<messaging>
<event_defs>
<event_def Name="EventName" ServiceName="ClientService">
<action Name="Action1" Cond="XPath Expression[Optional=true]" Repeatable="true">
<message_template Value="MsgTemplate1"/>
<recipient_groups>
<recipient_group Value="RecipientGroup1" Repeatable="true"/>
</recipient_groups>
</action>
</event_def>
</event_defs>
</messaging>
<event_def>: This tag identifies the message event that is being linked. The 'Name'
and 'ServiceName' specified should match an already defined message event.
<action>: This tag is used to link the message event to message template and recipient
groups. This tag can have one <message_template> and one or more
<recipient_group> as children. When the message event is raised by using

'RAISE_MSG_EVENT' the MESSAGING service will use the message template

referenced here to send alerts/emails to the recipient returned by recipient groups
referenced here. Multiple <action> tags can be used to send different alerts/emails to
different users for the same message event.
Attributes:
z Name (Required): The name of the action tag should be unique within the
message event.
z Cond (Optional): This attribute can be an X-Path expression. At runtime this
condition has to evaluate to true for the action to be executed.
<message_template>: This references an already defined message template.
Attributes:
z Value (Required): The name of the message template mentioned here should
match an already defined message template in the same Client Service as the
message event definition. If the message template referenced here needs a
document then make sure that the document defined for the message event is
compatible.
<recipient_group>: This references an already defined recipient group.
Attributes:
z Value (Required): The name of the recipient group mentioned here should match
an already defined recipient group. If the recipient group referenced here needs a
document then make sure that the document defined for message event is
compatible.
Example:
<messaging>
<event_defs>
<event_def Name="CoCreditHoldEvent" ServiceName="ORDER_ADMIN">
<action Name="CreditHoldMessage" Cond="$thisDoc/ORDER_TYPE_ID/@Value =
'STANDARD'">
<message_template Value="CoCreditHoldMT"/>
<recipient_groups>
<recipient_group Value="CoCreatorRG"/>
<recipient_group Value="CoSalesPersonRG"/>
</recipient_groups>
</action>
</event_def>
<event_def Name="CoPromisedEvent" ServiceName="ORDER_ADMIN">
<action Name="SendMessage1">
<message_template Value="CoPromisedMT"/>
<recipient_groups>
<recipient_group Value="CoOrderPointRG"/>
</recipient_groups>
</action>
</event_def>
</event_defs>
</messaging>

Loading messaging specification files

After defining the messaging specification files as explained in previous sections,
these file names need to be specified in the client service configuration file as shown
below. The path of the files can be absolute or relative to classpath.
.
<msgSpecFiles>
<msgSpecFile Name=" xservice/bookstore/messaging/bkMsgEvents.xml"/>
<msgSpecFile Name=" xservice/bookstore/messaging/bkMsgEventDefs.xml"/>
<msgSpecFile Name=" xservice/bookstore/messaging/bkMsgTemplates.xml"/>
<msgSpecFile Name=" xservice/bookstore/messaging/bkMsgRecipientGrps.xml"/>
</msgSpecFiles>
When using Studio the messaging configuration files can be added to the client service
without having to manually type the xml mentioned above in client service
configuration file.
To do that first right click on the client service node in the studio left navigation and
select the “Insert Messaging Definitions” option under “Additional Configuration”.

This adds a “Messaging Definitions” node under the client service node as seen in the
image below. Then right click on the “Messaging Definitions” node and select “Insert
Messaging Definition File...” option.
This pops up a dialog where you can specify the name of the messaging configuration
file and its path.
Clicking OK in this popup will add the specified messaging configuration file to the
client service (under the “Messaging Definitions” node) as shown below. Double click
this newly added file in studio left navigation to open the editor that provides intelli-
sense support for messaging specification.

Raise message event

To raise a message event the client service uses the X-Rule action component
'RAISE_MSG_EVENT'.
Syntax:
<RAISE_MSG_EVENT Name="messageEventName" Select="XPath
Expression[Optional=true]" Synchronous="yes|no"/>
Attributes:
z Name (Required): This is the name of the message event that has already been
registered with the MESSAGING service by uploading the messaging
specification files.
z Select (Optional): If the message event has been defined with a document then the
document can be sent to the MESSAGING service using the 'Select' attribute. The
value of this attribute should be an X-Path expression that evaluates to an xml
document.
z Synchronous (Optional): The default behavior of RAISE_MSG_EVENT is to
send the message in an asynchronous manner. This attribute can be set to 'yes' to
send the message synchronously. In asynchronous mode the message will be sent
using a different thread and different database transaction and if it fails it will not
affect the parent transaction.

Example:
<RAISE_MSG_EVENT Name="createCoEvent" Select="$coDoc" Synchronous="yes"/>
Additional APIs provided by MESSAGING service
delSelectedAlerts
The 'delSelectedAlerts' API can be used to delete alerts by specifying filters on
properties of the alert document MSG_ALERT. Alert deleted by using this API will be
deleted from all users who received that alert. The API_DOC for this is:
<API_DOC>
<INPUT>
<REQUEST Name="delSelectedAlerts" Any="true" OrderIndicator="true">

<ANY/>
</REQUEST>
</INPUT>
<OUTPUT>
<ON_SUCCESS>
<RESPONSE Status="Success"/>
</ON_SUCCESS>
</OUTPUT>
</API_DOC>
Example 1:
<REQUEST Name="delSelectedAlerts">
<ID Value="ALERT-1011169763975492"/>
</REQUEST>
Example 2:
<OR>
<ID Value="ALERT-1011169763975492"/>
<ID Value="ALERT-1011169763975456"/>
</OR>
</REQUEST>
Example 3:
<EVENT_NAME Value="CoCreditHoldEvent"/>
<DOCUMENT_ID Value="CO-123"/>
<DOCUMENT_NAME Value="CUSTOMER_ORDER"/>
</REQUEST>
Web UI
Configure UI
Based on specifications described in previous sections the messaging service will
generate alerts when messaging events are raised. These alerts can be displayed on the
WebUI. The messaging service provides a UI workflow for searching active alerts. To

Web UI
add a link to this search workflow from the left navigation of the WebUI, append
following line to Navigation.xml at appropriate level like any other link.
<ui:pad-item displayText="Search Alerts" workflow="//MESSAGING/SearchAlerts"
activity=”serch_alerts”/>
Following figure shows an example of adding messaging alert UI.
Search Alerts
The alert search screen enables the user to search with various criteria for the alerts for
which the user is a recipient. Following search filters are provided by the alert
mechanism.
1. Service Name: Every alert belongs with an Xservice. The services of the alerts are
specified while configuring the alert.
2. Event Name: This dropdown lists all the events. User can select "All" or an event
type of interest.
3. Priority: Every event can be assigned a priority according to its importance. Once
configured, priority for a particular event does not change. Alert mechanism
provides following list of priorities.
a. Fatal
b. Severe
c. Warning
d. Information
4. Category: It is a logical grouping of alerts. Category is defined at the time of
configuration.
5. Document Name: This particular search filter can be used when user knows for
which particular entity (Purchase Order or ASN) the alert is created.
6. Document Id: If user is aware of Document ID, then the user can find particular
alert for the ID.
7. Creation Date: User can search alerts based on creation date.
The following screenshot shows various search filters.

On the same page it provides detailed information for the alert. User can use the
pagination functionality for browsing alerts.
Remove Alerts
Apart from searching, users can remove (clear) the alerts in the same search alert
screen. To remove the alert
1. Select the check box for the alert(s).
2. Click on the clear button.
After the above action the selected alerts will be deleted from the system (for all the
recipients of the alert) and will not be available later for any action. (refer the above
figure)
Alert Details
To view the alert details user can click the link given under the description column.
This link will take the user to another page, which can provide further details relevant
to that alert. For different types of alerts this link can take the user to different pages as
per the configuration in the messaging event definition. The UI workflow that is
invoked by clicking on this link will have access to all the details of the alert. The
'thisParam' variable in this UI workflow will refer to following xml:
<ID Value="ALERT-1011169662846851[Type=string]"/>
<CREATION_DATE Value="01/24/2007 12:20:46[Type=datetime]"/>
<DOCUMENT_ID Value="1[Type=string]"/>
<DOCUMENT_NAME Value="CUSTOMER_ORDER[Type=string]"/>
<EVENT_NAME Value="PoCreated[Type=string]"/>
<MESSAGE Value="New Order 1 placed by buyer buyer1. [Type=string]"/>
<MSG_TEMPLATE_NAME Value="PoCreatedMT[Type=string]"/>
<MSG_TEMPLATE_TEXT Value="New Order {0} placed by buyer {1}.[Type=string]"/>
<PRIORITY Value="3[Type=int]"/>
<SERVICE_NAME Value="ORDER_ADMIN[Type=string]"/>
<CATEGORY Value="Order[Type=string]"/>
<ON_CLICK_SERVICE_NAME Value="ORDER_ADMIN_UI[Type=string]"/>
<ON_CLICK_WORKFLOW_NAME Value="orderReviewFromAlert[Type=string]"/>
The various tags are explained below:

Web UI
z ID: Unique identifier for the alert.

z CREATION_DATE: The creation datetime of the alert.
z DOCUMENT_ID: The runtime value of document_id X-Path expression defined
in message template ALERT protocol.
z DOCUMENT_NAME: document_name defined in message template ALERT
protocol.
z EVENT_NAME: The message event that generated this alert.
z MESSAGE: The alert message generated by the message template ALERT
protocol.
z MSG_TEMPLATE_NAME: The message template used to generate this alert.
z MSG_TEMPLATE_TEXT: The raw alert message as it is defined in the message
template ALERT protocol. This can potentially be used for internationalization
along with alert arguments available in MSG_ALERT_ARG table.
z PRIORITY: The priority of the alert as defined in the message template ALERT
protocol.
z SERVICE_NAME: The client service that this message event is registered for.
z CATEGORY: The category of the message event.
z ON_CLICK_SERVICE_NAME: The service that provides the UI workflow to
view alert related details.
z ON_CLICK_WORKFLOW_NAME: The UI workflow to view alert related
details.


Index
A Timer setup and callback 2

Advanced Customizations 41
Approval Nodes 15, 50 U
Approval Service 13, 49 UI Based Method 34
Upload Functionality Overview 29
C Upload Methods 31
Configuration of timer poll interval 2 Upload Templates Management 29
D
Data Upload 29
Deployment 2
E
Error Correction 36
G
Guaranteed Messaging 8
Guidelines 44
M
Multi-line Approval node 20, 52, 54, 55, 58
P
Parallel Approval Node 19
S
Serial Approval Node 18, 50
Server Based Method 31
Service Setup & Configuration 26
START_TIMER 3
Status Report 34
STOP_TIMER 7
Success-failure Determination 11
T
Tabs on Approval Nodes 26
Timer commands 3
Timer Service 1, 75, 83

ABPP3 Programmers Reference Part3 6.2.8 RevA

Diunggah oleh

Informasi Dokumen

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

ABPP3 Programmers Reference Part3 6.2.8 RevA

Diunggah oleh

Hak Cipta:

Format Tersedia

Agile Business Process

i2® Agile Business Process Platform (ABPP) 3

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

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

1 Timer Service ................................................................................................. 1

2 Approval Service ......................................................................................... 13

Agile Business Process Platform 3 Programmers Reference Revision A v

Upload Functionality Overview.............................................................................................................. 29

4 Task Scheduler Service ...............................................................................49

vi Agile Business Process Platform 3 Programmers Reference Revision A

5 Email Service ............................................................................................... 75

6 Messaging Service ...................................................................................... 83

Index ........................................................................................................... 105

Agile Business Process Platform 3 Programmers Reference Revision A vii

viii Agile Business Process Platform 3 Programmers Reference Revision A

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

z About i2 Agile Business Process Platform 3 Programmers Reference

About i2 Agile Business Process Platform 3

Agile Business Process Platform 3 Programmers Reference Revision A ix

x Agile Business Process Platform 3 Programmers Reference Revision A

About this Book

What You Should Know

What This Book Contains

Item Example Explanation

Code Call NotifyPending; File names, executable code,

Agile Business Process Platform 3 Programmers Reference Revision A xi

Item Example Explanation

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

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

Documentation or SCOS Installation Guide Document or book names referenced

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

xii Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A xiii

If You Need Assistance

To Contact Customer Support

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

Phone: US and Canada: 1.469.357.3456

xiv Agile Business Process Platform 3 Programmers Reference Revision A

For the Latest Documentation

Agile Business Process Platform 3 Programmers Reference Revision A xv

xvi Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A 1

Timer setup and callback

Configuration of timer poll interval

2 Agile Business Process Platform 3 Programmers Reference Revision A

Note: The actual information is enclosed within FOR_DOCUMENT tag. This

Agile Business Process Platform 3 Programmers Reference Revision A 3

| The call back actions are executed.

4 Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A 5

<REQUEST Name="doSomething" />

When the callback is invoked,

thisDoc will point to the following xml:

6 Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A 7

8 Agile Business Process Platform 3 Programmers Reference Revision A

| Specifies the guarantee level (High or Low. Default is High)

Agile Business Process Platform 3 Programmers Reference Revision A 9

10 Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A 11

12 Agile Business Process Platform 3 Programmers Reference Revision A

Agile Business Process Platform 3 Programmers Reference Revision A 13

Approval framework publishes its dependency on user security and alerting

14 Agile Business Process Platform 3 Programmers Reference Revision A