Programming Using BPM APIs

WebLogic Integration provides rich BPM APIs for creating custom configuration, design, and runtime management, and for monitoring clients . The business process engine consists of Session EJBs, Entity EJBs, and message-driven beans (MDBs). The session EJBs provide the primary interface to the business process engine. Both stateful and stateless session EJBs provide various functions. The session EJBs shown in Table 34.1 are available to the BPM API.

Table 34.1. BPM Session EJBs

Name of Session EJB	Stateless/Stateful	Functionality
Admin	Stateful	Serves as a primary interface for design clients such as Studio. One example is an API for defining a template definition.
Audit	Stateless	Provides an interface that encapsulates WebLogic JMS Topic ( wlpsAudit ) to which a process engine sends audit and error messages.
EJBCatalog	Stateful	Collects EJB metadata by scanning the JNDI tree and storing it in a catalog.
Permission	Stateless	Supports getting and setting user and role permissions.
PluginManager	Stateless	Provides runtime management of plug-ins during workflow execution.
PluginManagerCfg	Stateless	Enables management of user-defined plug-ins.
ServerProperties	Stateless	Enables clients to obtain information about properties governing BPM.
WLPIPrincipal	Stateless	Configures, manages , and gets information about roles, users, and organizations.
Worklist	Stateful	Provides a primary interface for runtime management clients.
XMLRepository	Stateless	Provides access to the XML repository.

There are other useful classes in the following packages:

• com.bea.wlpi.client.common This package provides client-side classes used by BPM clients.

• com.bea.wlpi.client.util This package provides two JMS utilities for testing.

• com.bea.wlpi.common This package provides value objects for describing different BPM entities.

• com.bea.wlpi.security This package provides value objects for describing roles and user permissions.

An Example of Using BPM APIs

The second example shows how to start a workflow and then execute a specific task within the workflow by using BPM APIs.

A workflow (called MyWorkFlow ) has been created using Studio. This workflow is designed so that it can be started manually (see the manual option in Start Properties dialog in Figure 34.11). After the workflow is started, a task (called MyTask ) is activated. Refer to Figure 34.11.

Figure 34.11. Example2: The MyWorkflow workflow.

MyTask is designed to send an XML response to the client including the date and time (see Figure 34.12).

Figure 34.12. Example2: Properties for MyTask .

At this point, a command-line Worklist client has been created; it will start this workflow and execute the task named MyTask .

Now you can establish a connection to the running BPM server and obtain a handle on the WorkList Session Bean, as shown in Listing 34.1.

Listing 34.1 Connecting to BPM Server

 private static boolean connect(String url, String userId, String password ) { Object result; try { ctx = getInitialContext(url, userId, password); result = ctx.lookup(WORKLIST_JNDI); WorklistHome wHome = (WorklistHome) PortableRemoteObject.narrow(result,WorklistHome.class); worklist = wHome.create(); return true; } catch(Exception e) { System.err.println("Caught Exception:" + e); } return false; } 

Start the workflow by using Worklist EJB, as shown in Listing 34.2. You can obtain a list of workflows that can be started manually by using the following method:

 public java.util.List getStartableWorkflows(java.lang.String orgID) throws java.rmi.RemoteException, WorkflowException 

From the list of startable workflows, you can choose and instantiate MyWorkFlow by using the following call:

 public java.lang.String instantiateWorkflow(java.lang.String orgID, java.lang.String templateID, java.lang.Object requestID) throws java.rmi.RemoteException, WorkflowException 

Listing 34.2 Starting the Workflow

 /** * Start a workflow */ public static String startWorkflow(String templateName) { String instanceId = null; try { String activeOrgId = worklist.getActiveOrganization(); List templates; templates = worklist.getStartableWorkflows(activeOrgId); for(int i = 0; i < templates.size(); i++) { TemplateInfo templateInfo = (TemplateInfo)templates.get(i); if (templateInfo.getName().equals(templateName) == true) { String response = worklist.instantiateWorkflow(activeOrgId, templateInfo.getId()); System.out.println("response:\n" + response); //parse instance id from response int j = response.indexOf("<instanceid>"); int k = response.indexOf("</instanceid>"); instanceId = response.substring(j + "<instanceid>".length(), k); } } } catch (Exception e) { System.err.println("Caught Exception : " + e.getMessage()); } finally { return instanceId; } } 

The response you will obtain is shown in the following code:

 <wlpiresponse> <instanceid>13001</instanceid> <templatedefinitionid>9001</templatedefinitionid> <root> <actionid>1029650142617</actionid> <DateOfMyWorkFlow>Sun Aug 18 01:16:34 MDT 2002</DateOfMyWorkFlow> </root> </wlpiresponse> 

The response is parsed to get the instanceid . This instanceid is used for executing a task. To execute a task, use the method shown in Listing 34.3.

Listing 34.3 Executing a Task in a Given Workflow

 public TaskInfo getTask(java.lang.String taskName, java.lang.String instanceID) throws java.rmi.RemoteException, WorkflowException /** * Execute task of a given workflow */ public static boolean executeTask(String taskName, String instanceId) { try { TaskInfo taskInfo = worklist.getTask(taskName, instanceId); String response = worklist.taskExecute (taskInfo.getTemplateDefinitionId(), taskInfo.getInstanceId(), taskInfo.getTaskId()); System.out.println("response:\n" + response); return true; } catch (Exception e) { return false; } } 

The following is the response you will obtain:

 <wlpiresponse> <instanceid>15002</instanceid> <templatedefinitionid>9001</templatedefinitionid> </wlpiresponse> 

You can then run Example2 as follows :

1. Start the WLI samples server by running the following script:

     <WL_HOME>\weblogic700\samples\integration\samples\bin\RunSamples.cmd  

2. Open Studio.

3. Log in as admin/security.

4. Use the Import package tool to import the given workflow under chapter34\example2\MyWorkFlow.jar in the ORG1 organization.

5. Run the MyWorkList client written using the BPM APIs. This will start the workflow called MyWorkFlow and then execute a task in the workflow called MyTask :

   1. Copy chapter34\example2 to your local drive.

   2. Use cd to change the directory to example2 .

   3. While in the example2 directory, run the setWLSenv.cmd script from <WL_HOME>\weblogic700\server\bin .

   4. Run ant , which will first compile and then run the sample. Run ant -projecthelp to list all the targets.

   5. The response from starting the workflow and subsequently executing the task is shown earlier in this section.

6. In Studio, right-click the MyWorkFlow template and select Instances.

7. Note the details of the instance that finished execution due to step d within step 5.