Chapter 6   Working with Applications, Process Instances and Work Items

The Process Manager Application API provides classes and methods that let you find and work with applications, process instances and work items. You would use this API to build Java applications that embed the functionality of the Process Manager engine.

For example, you can create back-end systems that create process instances programmatically rather than through the UI.. After creating a process instance, the back-end system can check its status and interact with work items.

You can also use the Process Manager Application API to write your own front-end user-interface to the Process Manager engine so that your users use the new interface rather than using the Process Express. For example, suppose you want to have a batch delegate UI. The inbuilt delegate feature only allows you to delegate one work item. You could write a web-based UI that allows the user to select multiple work items. Then in the back-end, you would call wi.delegate() repeatedly for each work item.

In every Process Manager installation, a cluster manager bean manages the Process Manager clusters. Given the cluster manager bean, you can get access to individual cluster beans. Given an individual cluster bean, you can access the application bean for the cluster. Given the application bean, you can find and work with individual process instances and work items in the application.

See Chapter 4, "Cluster Management," for information about accessing the cluster manager and individual cluster beans.

The Application API consists of the following interfaces:

• IPMApplication -- has methods for finding work items and process instances, and for testing the state of an application.
• IProcessInstance -- has methods for working with individual process instances, such as getting and setting data field values, getting information such as the creation date and creator, changing the state, and suspending, terminating or resuming the process instance.
• IWorkItem -- has methods for working with individual work items, such as changing assignees, expiring or extending the expiration date, finding which node (activity) it is at,and suspending or resuming it.
• IFinder -- has methods for finding process instances and work items in the application.

You can find all the necessary classes in the pm65classes.jar file. If you have installed the Process Manager Builder, you can find this jar file in the directory builder-root\support\sdk. You may also be able to find it on the CD.

IPMApplication

---

The application bean is the main access point for process instances. It has methods that allow the user to initiate and edit process instances and work items associated with the application. The IPMApplication bean is best thought of as a factory for PIs and WIs.

It also has methods that let you get the application's stage, mode, status and testing state. See the section "Deployment States" for more information about these settings.

To remove an application or to change its state, use the IDeploymentDescriptor interface, as discussed in Chapter 5, "Deployment Manager."

To get a handle to a specific application, mount the application bean. For example:

---

String jndiName = IPMApplication.DEFAULT_JNDI_ROOT + "/" + appName; try {    javax.naming.Context cxt = javax.naming.InitialContext ( ) ;    IPMApplicationHome home = (IPMApplicationHome)          cxt.lookup( jndiName );    IPMApplication myApp = home.create(); } catch( Exception e ) { }

---

All the methods on IPMApplication throw a PMException in case of error. The methods findPI and findWI also throw XProcessInstanceNotFound and XWorkItemNotFound respectively in the event the object cannot be located.

For details of the methods on IPMApplication, consult the javadocs, which are in the support\sdk\docs directory of the Process Manager Builder installation directory.

IProcessInstance

---

The IProcessInstance Interface has methods for getting information about process instances and for performing operations on them such as suspending and resuming them or setting their data field values.

Given an IPMCluster bean (see Chapter 4 "Cluster Management") you can get the Finder bean for the cluster. Given the Finder bean you can call the findMyInstances() method to find all process instances in the cluster.

Given an application bean, you can find a specific process instance by calling its findProcessInstance() method and specifying the process instance's key.

For example:

---

// myApp is a mounted application bean IProcessInstancePK pk = ProcessInstancePKFactory.create( PID); pk.setEditable( true ); // for update IProcessInstance pi = myApp.findProcessInstance( pk );

---

For details of the methods on IProcessInstance, consult the javadocs, which are in the support\sdk\docs directory of the Process Manager Builder installation directory.

IWorkItem

---

The IWorkItem Interface has methods for getting information about work items and for performing operations on them such as changing their assignees, expiring them or extending the expiration date, suspendig them or resuming them and so on.

Given an IPMCluster bean (see Chapter 4 "Cluster Management") you can get the Finder bean for the cluster. Given the Finder bean you can call the findWorkItems() method to find all work items in the cluster. If you know the key for a specific process instance, you can use the Finder bean to find all the work items in a specific process instance.

Given a cluster bean, you can also get an application bean for a specific application. Given the application bean, you can get a specific work item by calling its findWorkItem() method and specifying the work item's key.

For details of the methods on IWorkItem, consult the javadocs, which are in the support\sdk\docs directory of the Process Manager Builder installation directory.

IFinder

---

The Ifinder bean is the access point for getting lists of work items and process instances.

In every Process Manager installation, a cluster manager bean manages the Process Manager clusters. Given the cluster manager bean, you can get access to individual cluster beans. Given an individual cluster bean, you can get the finder bean for the cluster by calling the getFinder() method.

The finder has methods for getting worklists, which are lists of work items. The worklist queries only return IWorkItems currently assigned to the principal in read-only mode; the principal cannot retrieve an IWorkItem that is not assigned to them via this interface.

The finder has methods for getting process instances. The process instance search methods only return IProcessInstances that were created by the principal in read-only mode; the principal cannot gain access to a process instance that they did not initiate.

For details of the IFinder methods, see the javadocs, which can be found in the support\sdk\docs directory of the Process Manager Builder installation.