IBM BPM - Business Objects and Variables in IBM Process Designer

Introduction

In Process Designer, variables capture the business data that is used by activities in a business process definition or by steps in services such as integration services or human services. Each variable has its own type and scope. All variables you create must be declared before you can start using them.

Variable types in Process Designer

You can use the variable types provided by the system toolkits, such as the System Data toolkit, or you can create custom business objects, depending on the requirements of the business data included in your process.

During Process Designer installation, the system toolkits are imported into the Process Center repository so that each process application and toolkit that you create has access to a common system data. The system toolkits provide the following categories of variables:

Base Types

Base types allow you to create custom variable types called business object. A list of all the base types is provided further in this topic.

System Types

System types are provided variable types that cannot be modified. A list of all the system types is provided in the JavaScript API reference guide.

Table 1. Provided base types
Base types	Description
String	Allows alpha-numeric characters to be entered into the variable.
Integer	Accepts digits without a decimal place, such as 45 or 20.
Decimal	Accepts digits with up to two decimal places, such as 45.3 or 20.13.
Date	Allows date and time formats to be entered into the variable.
Time	Allows date formats to be entered into the variable as times. The user enters a time, and before the variable is entered into the symbol table, it is converted to and behaves like a date.
Selection	Allows you to provide a list of possible entries to a user, of which the user can select only one. A selection is a list of different values; each value is typed as a string. A selection variable appears at run time on a Coach form as a drop-down list or as radio buttons.
Boolean	Accepts either true or false as values. It appears at run time on a Coach form as a check box.
Structure	To use a structure type, you need to create a custom structure type and define its properties. A structure regroups business data that is related to the same subject. For example, a Customer structure might contain elements such as lastName, firstName, homeNumber, streetAddress.

Custom Variable Types

Custom variable types are defined using business objects. If the predefined business objects provided in the system toolkits do not represent your needs, you can create your own business objects.

Variable Scope in Process Designer

In IBM® BPM, all variables declared for a business process definition (BPD) or service are local variables.

Local variables are only accessible to the currently executing process instance or service. Because variables are unique to an individual BPD or service, you can use a variable of the same name in a nested BPD or service and there are no conflicts at run time.

Table 1. Available namespaces
Namespace	Description
tw	Top-level Process Designer namespace
tw.object	Access Process Designer JavaScript objects and business objects (variable types)
tw.local	Access and update BPD and service-level variables
tw.system	Access system features and functionality
tw.system.org	Access security functionality
tw.epv	Access exposed process values (EPVs)
tw.env	Access environment variables

Initializing Complex Variables and Lists

Before using a complex variable, initialize it by using a script like the following:

If the variable is a complex object

tw.local.<variableName>=new tw.object.<businessObject>();

Example:

tw.local.customer=new tw.object.CustomerBO ();

If the variable is a list, use: tw.local.<listName>=new tw.object.listOf.<businessObject>();

Example:

tw.local.customerList= new tw.object.listOf. CustomerBO ();

Assigning Data to Object

tw.local.customer.id = “C123”

tw.local.customer.name = “BlueMix”

Conclusion

In IBM Process Designer, we can create a custom business object by using a base business object or by defining a new complex structure. When you create a business object in a process application, that object is available for all business processes, case types, and services in the process application. If you want to share a custom business object across process applications, create or store the custom object in a toolkit. Then, create a dependency on that toolkit from the process applications that require the variable. We have learnt how to create Business Object and Initialization of Business Object.

continue reading

Java Integration with IBM Business Process Manager

Introduction:

This article walks you through the steps to integrate external services into IBM® Business Process Manager applications using Process Designer. It covers integration with Java and describes best practices for achieving the integration.

Overview

There are two ways for Business Process Manager to integrate with external services, one is the component bindings way, the other is the out-of-box connectors way. The component binding’s method enables the system to invoke external systems with various bindings such as SCA bindings, EJB bindings, HTTP bindings, JMS bindings, and so on. This is the most powerful method, but it is only possible with Business Process Manager Advanced. The out-of-box connector’s method provides basic integration capabilities with external systems. It's simpler than the binding’s way and can be used for all Business Process Manager Editions. This article will focus on how to use the out-of-box connector’s method to integrate with external systems.

The IBM Process Designer is the authoring tool used to enable integration with out-of-box connectors. It provides capabilities for lifecycle management of business processes, and also provides a set of out-of-box connectors to integrate with external systems. There are four different ways to integrate with external systems using Process Designer:

v Java integration.

v Web service integration.

v ILOG integration.

v Enterprise Content Management (ECM) integration.

In his article we are describing Java Integration with IBM BPM.

Java Integration

Java integration calls methods from a Java class and interfaces with most third-party Java APIs, thus supporting a variety of integration scenarios and giving you access to Java features, including published Java libraries and APIs. You should build a Java integration service when you want to integrate with an external system to retrieve, update, or insert data in order to complete a task.

In this section, we'll use a sample to illustrate how to use Java integration to call a method from a Java class. For the purposes of our sample, let's assume we have a JAR file containing a Java method that can output Country Names based on Input of country code. We'll import that file into Process Designer, then use the Java Integration component to invoke the Java method, as described in detail in this section.

Import external files

External files are images, style sheets, JAR files, or other assets that are part of Business Process Manager Implementation, but developed outside of Business Process Manager. You can add these external files to your process application or toolkit in the Designer view so that all project assets are included in the Process Center repository. Adding these files to your process application ensures that all required assets are available and installed when your project is ready for testing or production.

Before adding managed files, be aware of the following requirements:

ü  You must have write access to the current process application or toolkit to add external files as assets.

ü  The files that you add cannot be larger than 100MB.

You can add Hello CountryDetails.jar to the process application by doing the following:

From the project tree, select the + icon next to Files and select Server File, as shown in below.

In the Server File window, click Browse and select CountryDetails.jar in your file system. CountryDetails.jar is now part of your process application. When you deploy this process application, this server file will be deployed as part of the application.

Save the server file.

Create an integration service and add a Java Integration component

To create an integration service, do the following:

From the project tree, select Implementation, click the + icon, then click Integration Service.

Specify the name as Java Integration Service as shown in below, and click Finish.

To diagram the integration, click the Diagram tab and drag the Java Integration component onto the canvas, then change its name to Invoke Country Details Service, drag a Server script name to Log and wire the components together, as shown in below.

To configure the Java Integration component to invoke a Java method, click Hello World - JIC.

Under Properties, click the Definition tab, and under Discovery, set the Java Class by doing the following, as shown in Figure:

a)      Click Select and select the class.

b)      Select CountryDetails java class.

c)      Select the method String getCountryName(String) from the list.

To set up the service variables, click the Variables tab, and add an input variable CountryCode of type string, and set the default value to “IN”, as shown in Figure. Add an output variable CountryName of type string.

Define the data mapping for CountryDetails. Click Invoke CountryDetails Service. Under Properties, click the Data Mapping tab. To set the Input Mapping, select the variable tw.local.CountryCode, as shown in Figure. Do the same to set the Return Value.

To test the integration, click the debug icon in Process Designer, click Step, as shown in Figure, several times until you see a message saying "The service has finished."

Conclusion

In this article, you've learned about Java Integration with external systems in Process Designer. You learned some best practices for using the integration components to communicate with external systems. These integration components exist as services, so they can be reused in toolkits shared across process applications, making Business Process Manager Systems easier and more efficient for business process designers.

continue reading

Programming IBM BPM - Developing using the JavaScript API

Introduction

You can find programming guides and examples for programming various aspects of the IBM® Business Process Manager system, in this article.

In Process Designer all variables are JavaScript variables so you can use JavaScript code snippets inside your components to improve the behavior of your model.

Variable availability

You can only use certain JavaScript objects inside a specific context. In some contexts, certain objects are automatically instantiated.

Table 1. Object availability
Object	Context Allowed	Context Instantiated	Context Denied
TWLogger	All	None	None
TW	Process	Process	ScoreBoard
TWScoreboard	ScoreBoard	ScoreBoard	Process, Service
Chart	ScoreBoard	Filter Layout, Datasource	None
TWDate	All	None	None
TWMap	All	None	None
String	All	None	None
XMLDocument	All	None	None
XMLElement	All	None	None
XMLNodelist	All	None	None
listOf	All	None	None
ic	All	None	None
Alert	All	None	None
Event	All	None	None

External JavaScript libraries

Process Designer provides a number of JavaScript libraries. You can also import or create your own libraries.

Using JSON

 JSON is a string representation of a JavaScript object that can be transmitted over the network. You can use it to pass parameters inside IBM® BPM.

An Open Source JavaScript implementation is available to both parse and construct JSON strings. Part of this package is a JavaScript source file called json2.js.

Add this file to your toolkit or process application as a server managed file to provide new global methods and objects.

Example

This example illustrates how to taking a List of Complex data structure and building a JSON representation:

var newArray = new Array();

for (var j=0; j<tw.local.myPurchase.listLength; j++)

{

  var newObj = new Object();

  for (var property in tw.local.myPurchase[j].propertyNames)

  {

    var name = tw.local.myPurchase[j].propertyNames[property];

    newObj[name] = tw.local.myPurchase[j][name];

  }

  newArray.push(newObj);

}

var jsonText = JSON.stringify(newArray);

log.error("jsonText = " + jsonText);

Within a browser or the coach, you can use the Dojo classes to work with JSON:

• dojo.fromJson(string) parses a JSON string to return a JavaScript object.
• dojo.toJson(Object) returns a JSON string given a JavaScript object.

Using the Dojo Toolkit

Dojo is an open source set of JavaScript libraries that enhance the capabilities of native JavaScript. The Dojo Toolkit is supplied and loaded by Coach Pages.

Commonly, Dojo is thought as a visual language for building rich web pages. Although this is an important component of the Dojo Toolkit, it is not its only function.

If you are developing complex Coach Views using Dojo or another JavaScript library and need advanced features for JavaScript development, debugging, and testing, consider using an IDE tool, such as Rational® Application Developer, to initially create the JavaScript. You can then use the JavaScript that you develop as part of your Coach views in Process Designer.

Procedure

1. Open a Coach component.
2. Use Dojo calls. For example, use var x = dojo.byId("name of control"); to return the DOM node of the control by name.

JavaScript reference examples

This section provides JavaScript examples.

Starting a new process

A new instance of a process can be started by using the tw.system.startProcessByName() function.

The method tw.system.startProcessByName() returns a TWProcessInstance object and takes 2 parameters:

name (String)

Name of the process.

inputValues (Map)

Map containing the input parameters for the process.

var inputs = new tw.object.Map();

inputs.put("parm1", "parm1 value");

inputs.put("parm2", "parm2 value");

tw.system.startProcessByName("StartProcess2", inputs);

Thread hung exceptions

Under certain circumstances, an attempt to start a process instance using the tw.system.startProcessByName() function might be blocked, and in the system out log you might see a thread hung exception for a thread holding a database connection. This might happen in the following circumstance:

• You have defined an undercover agent (UCA) message event with an attached service.
• In the attached service you are starting a new process instance using the tw.system.startProcessByName() function.
• The process you are starting has variables defined that are exposed to Business Data Search, and the process creation hangs.

The recommended solution is to use the BPMN (Business Process Model and Notation) best practice, and model the process with a start message event.

Getting the current process instance

The current process instance can be retrieved through the TWProcessInstance variable called tw.system.currentProcessInstance.

Getting the current userid

The current user ID can be retrieved through the TWUser variable in tw.system.user.

Starting an external application

You can start an external application such as a batch file or a shell script by performing that task using the JavaScript LiveScript mechanism.

This sample illustrates how to run a batch file on a Windows system.

var runtime = java.lang.Runtime.getRuntime();

runtime.exec("C:\\RunMe.bat");

Returning the owner of a task

You can know the identity of a user who has completed a given task.

You can do this by defining an output parameter for the human service to store the name of the user that completed the task.

Within the human service, before its termination, use the following code to declare the output parameter:var user = tw.system.currentTask.assignedTo;

It returns a TWUser object.

The name property can be used to determine the userid of the user that claimed the task.

Returning a list of reference links

You can return a list of all reference links of the current process application or toolkit on a server by running the tw.system.model.processApp.getLinks() method.

This tw.system.model.processApp.getLinks() method allows for returning reference links in the toolkits referenced by the process application, and results can be filtered. The tw.system.model.processApp.getLinks() link property returns only the reference links for the current process application (not its children), and the results are not filtered.

Parameters

The method tw.system.model.processApp.getLinks() returns an array of TWLink and takes two parameters:includeReferencedToolkitsThis is a boolean flag that indicates if the links should be collected recursively on all library item elements contained in the process application and dependent toolkits. linkFilterThis is a JavaScript function that takes TWLink as parameter and returns a boolean value that indicates whether the link should be excluded from the result.

The signature of the linkFilter argument function is boolean linkFilterFunction(TWLink twlink), and that the filter function is called for each reference link result. The filter function returns true if the TWLink value in question is filtered out (excluded), or false if it is not filtered out.

You can collect the names and URLs of the links using the assetType Change Request from your process application and its children, and then assign them to local variables in your process.

This example assumes that the following two private variables have been defined: requestLinksName of type String List, and requestLinksURL of type String List. Make sure to select Has Default for both. The requestLinksName variable is an array that contain the names of all the links, and the requestLinksURL variable is an array that contain the URLs of all the links obtained by getLinks() that were not filtered out by the linkFilter function.

The following example is an specific example of how to narrow down the list of returned links to be only those of the Change Request asset type for that process application (and child projects). However, getLinks() can be used to return all reference links.

var linkFilter = function (twlink) {

            if (twlink != null && TWLink.AssetTypes.CHANGE_REQUEST == twlink.assetTypeNamespace){

                        return false;

            }else{

                        return true;

            }

}

var requestLinks = tw.system.model.processApp.getLinks(true, linkFilter);

if(requestLinks != null){

    for(var i=0; i<requestLinks.length; i++){

        tw.local.requestLinksName[i] = requestLinks[i].name;

        tw.local.requestLinksURL[i] = requestLinks[i].url;

    }

}

Attention: If the call is done from the context of another process application, only the links of the process application can be obtained. The filtered list will not include any children.

Extracting a managed file

If a process application or a toolkit contains a managed file, you can extract it from the runtime to evaluate its content.

This example illustrates how to extract a managed file by writing its content to a local file.

var managedFile = tw.system.model.findManagedFileByPath("lsw-services.jar",

TWManagedFile.Types.Server);

log.error("Got the managed file!: " + managedFile);

managedFile.writeDataToFile("C:\\lsw-services.jar");

Note: The first parameter of the tw.system.model.findManagedFileByPath API is managedFilePath, which does not support '!' notation to reference the contents of an archive.

Searching processes and tasks

You can search a specific task in a current process.

The JavaScript object of type TWSearch can be used to perform a search. It has three primary methods:

Ø  execute()

Ø  executeForProcessInstances()

Ø  executeForTasks()

The TWSearch object has a number of properties that are used to govern the data queried for and returned.TWSearch.columnsThe columns of data to be returned.TWSearch.conditionsThe queries to be executed (of type TWSearchCondition).A call to TWSearch using the execute() method can return a TWSearchResults object.

log.error("Starting to find other tasks ....");

log.error("This process: " + tw.system.currentProcessInstance.id);

var col1 = new TWSearchColumn();

col1.name = TWSearchColumn.ProcessInstanceColumns.ID;

col1.type = TWSearchColumn.Types.ProcessInstance;

var search = new TWSearch();

search.columns = new Array(col1);

var condition = new TWSearchCondition();

condition.column = new TWSearchColumn();

condition.column.name = TWSearchColumn.ProcessInstanceColumns.ID;

condition.column.type = TWSearchColumn.Types.ProcessInstance;

condition.operator = TWSearchCondition.Operations.Equals;

condition.value = "270";

search.conditions = new Array(condition);

var order1 = new TWSearchOrdering();

order1.column = col1;

order1.order = TWSearchOrdering.Orders.Descending;

search.orderBy = new Array(order1);

search.organizedBy = TWSearch.OrganizeByTypes.ProcessInstance;

var results = search.execute();

log.error("Result.rows.length = " + results.rows.length);

for (var i=0; i<results.rows.length; i++)

{

  ...

}

Calling Java through JavaScript

JavaScript inside IBM® BPM can invoke Java through the Live Connect technology.

LiveConnect is the name of an application programming interface that provides JavaScript with the ability to call methods of Java classes and vice-versa using the existing Java infrastructure.

Working with document attachments

 Document attachments can be associated with process instances. These can be added through coach controls or through programmatic additions.

The relevant JavaScript components are:

TWDocument

The description of a document.

tw.system.findDocumentByID()

Finds a document from its ID.

TWProcessInstance.documents

An array of TWDocument objects associated with an instance of a process.

TWProcessInstance.addDocument()

Adds a document to a process instance.

TWProcessInstance.findDocuments()

Locates documents associated with the current instance.

Note: The addDocument() function will not work when called from JavaScript locally coded in a BPD activity but works fine when coded in a general service.

Using the addDocuments() method

The addDocuments() method has the following parameters:type (String)Either TWDocument.Types.URL or TWDocument.Types.File.name (String)Name of the document.fileLocation (String)The path to the file on the server or URI.hideInPortal (Boolean)A flag which describes whether or not the document is to be visible in the process portal.createdBy (TWUser)properties (Map)

The following code sample illustrates how to use the addDocuments() method.

var myMap = new tw.object.Map();

var hide = false;

var user = tw.system.user;

tw.system.currentProcessInstance.addDocument(

  TWDocument.Types.File,

  "name",

  "C:\\Projects\\WLE\\Images\\ibm.jpg",

  hide,

  user,

  myMap);

Retrieving data from XML

The following examples show you how to pull data out from an XMLDocument (or any XML type) using the following XML.

Generally speaking, walking the XML as shown below is more efficient that using XPath because it does not call the parser.

The XML example here is the resultSet from an Integration Component. For the purposes of the example, assume that the XML below is stored in a variable called myXML.

<resultSet recordCount="2" columnCount="2">

  <record>

    <column name="FIRST_NAME">Daniel</column>

    <column name="ZIP">78703</column>

  </record>

  <record>

    <column name="FIRST_NAME">Helen</column>

    <column name="ZIP">15228</column>

  </record>

</resultSet>

The following examples illustrate how to retrieve specific values from the XML variable.

tw.local.myXML.resultSet

Returns a node list of records.

tw.local.myXML.resultSet.record[1]

Returns a node list of columns. In the previous example, the values "Helen" and "15228".

tw.local.myXML.resultSet.record[1].column[0].getAttribute( "name")

Returns "FIRST_NAME".

tw.local.myXML.resultSet.record[1].column[1].getAttribute("name")

Returns "ZIP".

tw.local.myXML.resultSet.record[1].column[1].getText()

Returns 15228.

continue reading