Clinton Davidson's Blog

Product: AquaLogic BPM Suite Archives

Creating a Process using PAPI-WS

Determining the list of processes where the current user can create an instance

Unfortunately, there is no PAPI-WS call that gives a list of processes where the current user can create an instance. A user can create a process instance if they belong to any role in the process. This is in contrast to Global Applications- the activities used to create a process instance in ALBPM-, which are only in one role. Creating a process using PAPI-WS means executing the Begin activity, which belongs to the automatic handler role and not to a user-created role. Since no user belongs to the automatic handler role, PAPI-WS looks at all roles in the process, and then checks to see if the current user belongs to any of those roles.

Method signature to create a process instance

The method createInstance takes four parameters: a session id, a process id, the argument set name, and an array of arguments. It returns an InstanceInfo Let's look at each of these in turn.
A remote session is required to do anything with PAPI-WS. This is a call that takes a name and password and returns a String sessionId. Creating a session id is documented in PAPI Web Service.
The process id is the programmatic identifier for the process. The simplest way to find the process id is to right-click the process in Studio, click properties, and the id will be listed at the top. A "/" needs to be added to the process id for it to be used as the process id parameter. See the PAPI Web Service document for more details or if you will specifying a version or organizational unit.
To get the argument set name, go to Studio, right-click the Begin activity, and choose "Argument Mapping". The default argument set name is "BeginIn". However, note that it's possible to add additional argument set names. This is valuable when this process could be created through ALBPM (in a global activity) as well as remotely. If the input arguments for the BeginIn argument set contain arguments that can't be expressed remotely, such as FuegoObjects, the alternative is to create another argument set. In this case the arguments coulc be xml, and the Fuego objects could be created from values in the xml documents in the method window of the Begin activity.
The array of arguments parameter in the createInstance method are an array of KeyValuePairs, where each key corresponds to an argument in the ArgumentMapping window of the BeginActivity, and each value corresponds to the String value of the argument. The document PAPI-WS Extensions for Fuego 5.5 also details how the argument sets and argument names can be retrieved via PAPI-WS.

Sample code in Java for creating a process instance

 try
{
	//endpoint defined in include page	
	URL endpoint = new URL(WEB_SERVICE_ENDPOINT);
	//basic auth username and password defined in include page
                //note that this is only required for ALIP, not ALBPM
	ProcessServiceServiceLocator locator = new ProcessServiceServiceLocator(BASIC_AUTH_USERNAME, BASIC_AUTH_PASSWORD);

	//get the process service
	fuego.papi.ws.ProcessService processService =  locator.getProcessService(endpoint);
	System.out.println("Created the process service");

	//get a session id to make further calls
	//credentials defined in include.jsp for this lab.
	//credentials could also provided through a user prompt, or supplied by other means.
	String sessionID = processService.createSessionWithTakeOver(PROCESS_SERVER_USERNAME, PROCESS_SERVER_PASSWORD, true);
	System.out.println("Got the session ID");
	//creates the instance, using the parameters from the previous page.
	//note that the arguments and process name need to be hard-coded
	//this could be simplified using java preferences

	//Get the process ID.
	//Either get the process ID (process name, not project name) in Studio,
	//or get the process name via Process Administator by clicking the link under history,
	//then the link under Processes,
	//and finally viewing the Process Name.
	String processID = "/NewEmployee";

	//create the key value pair array of arguments
	//here we have 4 arguments - ssn, first name, last name, and email
	KeyValuePair[] keyValues = new KeyValuePair[4];
	keyValues[0] = new KeyValuePair();
	keyValues[0].setKey("ssn_arg");
	keyValues[0].setValue(ssn);
	keyValues[1] = new KeyValuePair();
	keyValues[1].setKey("nameFirst_arg");
	keyValues[1].setValue(nameFirst);
	keyValues[2] = new KeyValuePair();
	keyValues[2].setKey("nameLast_arg");
	keyValues[2].setValue(nameLast);
	keyValues[3] = new KeyValuePair();
	keyValues[3].setKey("email_arg");
	keyValues[3].setValue(email);

	//argument set name. Unless you have created another argument set, the default name is "BeginIn"
	String argumentSetName = "BeginIn";

	//create the instance, and get back the instance info
	InstanceInfo instanceInfo = processService.createInstance(sessionID, processID, argumentSetName, keyValues );
	System.out.println("Created new instance");
}
catch (Throwable t)
{
	 t.printStackTrace();
}

Sample code in C# for creating a process instance

try
{
               //get the process service
	ProcessServiceService processService =  new ProcessServiceService();
	Console.WriteLine("Created the process service");

	//get a session id to make further calls
	//credentials are defined in PageBase.cs for this lab.
	//credentials could also provided through a user prompt, or supplied by other means.
	String sessionID = processService.createSession(PROCESS_SERVER_USERNAME, PROCESS_SERVER_PASSWORD);
	Console.WriteLine("Got the session ID");
	//creates the instance, using the parameters from the previous page.
	//note that the arguments and process name need to be hard-coded
	//this could be simplified using java preferences

	//Get the process ID.
	//Either get the process ID (process name, not project name) in Process Designer,
	//or get the process name via Process Administator by clicking the link under history,
	//then the link under Processes,
	//and finally viewing the Process Name.
	String processID = "/NewEmployee";;

	//create the key value pair array of arguments
	//here we have 4 arguments - ssn, first name, last name, and email
	KeyValuePair[] keyValues = new KeyValuePair[4];
	keyValues[0] = new KeyValuePair();
	keyValues[0].key = "ssn_arg";
	keyValues[0].value =  ssn;
	keyValues[1] = new KeyValuePair();
	keyValues[1].key = "nameFirst_arg";
	keyValues[1].value = nameFirst ;
	keyValues [2] = new KeyValuePair();
	keyValues [2].key = "nameLast_arg";
	keyValues [2].value = nameLast;
	keyValues[3] = new KeyValuePair();
	keyValues[3].key =  "email_arg";
	keyValues[3].value =  email ;
	//argument set name. Unless you have created another argument set, the default name is "BeginIn"
	String argumentSetName = "BeginIn";

	//create the instance, and get back the instance info
	InstanceInfo instanceInfo = processService.createInstance(sessionID, processID, argumentSetName, keyValues );
	Console.WriteLine("Created new instance");

}
catch (Exception ex)
{
	Console.WriteLine(ex.ToString());
}

Where to find documentation and post questions for ALBPM/ALIP

Sample listing of useful documents:

• Configuring the Fuego Process Archive Database
• Fuego 5.5 & Apache-Ant Integration
• BPM Process Patterns: Repeatable Designs for BPM Process Models
• APIs for Integrating with FuegoBPM
• Fuego Business Language (FBL) 5 Programming Guide

There is a whole series of newsgroups under this category. Individual newsgroups include using the various apis, email notifications, collaboration, IDK integration, and administration. There are many people subscribed to these newgroups, so response times should be reasonable.

Documenting BPM Studio Processes

Before I get started, I should clarify some terms. ALIP is the product that integrates ALBPM with ALUI. ALBPM is AquaLogic Business Process Management (the former Fuego product) and ALUI is AquaLogic User Interaction, or much of what used to be known as the Plumtree Portal. BPM Studio (the ALBPM name) or Process Designer (the ALIP name) is the desktop application for designing BPM Processes.

One of the difficulties in working with processes in Studio is that it's hard to see everything in one page. The process diagram is under Processes, the Roles are under organization, the activities are listed under specific processes, and the FBL (Fuego Business Language) is listed under the structure tag. Viewing descriptions and properties means a number of additional clicks.

Process Reports
Process Reports let you see all of this information in one html page. To generate a process report, right-click on the Process and select Process Report. You will see a dialog to include Use cases, Include Implementation Source Code (which means FBL) and Include Variables. In this example, I checked everything; play with the options and see what options you need. Click OK and Studio will generate the Process Report, which is a single HTML file with a folder of images. Here's a shot of the process image and summary for a sample process:

Process Image
The process image on top displays the same way that it does in Studio. In other words, take a little time to clean it up, and don’t make it any wider than you have to. Sometimes people add notes to the process image. While these can help to explain a complicated process, they can also make the process image harder to read. Unless this is a simple process, I'd suggest putting detailed documentation in either of two places: the process documentation for end-user html documentation, and the description textbox for plain text developer documentation.

The summary section should be self-explanatory. Roles are defined using File:Organization. Activities are all the Interactive and Automatic activities defined in the process diagram. Variables are instance variables defined in the Variables tab. And Methods are the FBL language methods that generally correspond to an activity. Note that the methods are listed in sorted order but the activities are not. Each of these sections except Variables are described below.

Role Details
Clicking on an individual role gives you role details, which includes the description and the associated activities.

In this case, the description is empty, as I didn't take the time to fill it in. It’s a good idea to include descriptions for all elements that support it, so later developers can determine your intent.

Activity Details
Clicking on any activity in the process image takes you to activity details. Activity Details includes description, a link to the associated role, the activity type, and activity properties.

The properties of Abortable, Assignable, Auto-complete, User selects transition, and suspendable are set in the general category of activity properties. By default, only auto-complete is true. Also included in activity details are the conditional and unconditional transitions to other activities, and the activity tasks.

Method Details
Method details show the return type, whether the method is static, arguments, and FBL source code. Most methods have a void return type and are not static. For the Begin, End, and NotificationWait activities, arguments are defined in argument mappings. For other activities, arguments are defined on the variables tab associated with the method. Click the structure tab, select the method, and then click the variables tab to see the arguments. Source code includes the FBL code as written, including comments.

Summary
Process Reports are a good way to share information about processes- much simpler than starting up Studio and digging through the project. They are also a good way to see that a process has been well-documented.

Future Postings
While I can't commit to scheduled postings, there are a number of topics that I want to cover as they have confused developers. These include argument mapping, displaying the process image in the details portlet, using the IDK within screenflows, accessing ALIP/ALBPM from an external application, and using PAPI.