Building a Task Worklist with the BPM API

Use

The Business Process Management (BPM) application programming interfaces (APIs) allow you to customize and enhance the way you use business processes and execute tasks.

This document describes how to use the BPM APIs to build your own task worklist while still using the Web Dynpro task execution UI to work on tasks.

For a detailed description of the BPM public APIs, see http://help.sap.com/javadocs.

Prerequisites

You have added the necessary dependencies to development component tc/bpem/facade/ear (public part api) in software component BPEM-FACADE and to tc/je/sdo21/api in software component ENGFACADE .

Displaying Tasks in the Worklist

The following steps explain how to query the tasks.

Define the fetch criteria.
When retrieving the task items, the caller can specify certain criteria that need to be satisfied. In this example, the tasks will only be returned if the following criteria are fulfilled:
- The task is ready to be worked on.
- The current user is a potential owner or the actual owner, or the user has claimed the task.
- The priority of the task is very high or high.
```
TaskAbstractOwnerCriteria ownerCriteria = new TaskAbstractOwnerCriteria();
TaskAbstractFetchCriteria statusCriteria = new TaskAbstractFilterCriteria(TaskAbstractFilterProperty.STATUS, Status.READY, Status.RESERVED, Status.IN_PROGRESS);
TaskAbstractFetchCriteria priorityCriteria = new TaskAbstractFilterCriteria(TaskAbstractFilterProperty.PRIORITY, Priority.VERY_HIGH, Priority.HIGH);
```
Define the fetch criteria based on custom attributes (optional step).
Custom attributes for tasks can be defined in the process composer. For more information, see Defining Custom Attributes for Tasks.

When retrieving the task items, the caller can specify certain criteria based on existing custom attributes that need to be fulfilled in addition to the aforementioned criteria.
In this example, tasks will only be retured if the following criteria are fulfilled in addition to the criteria, as defined in step 1:
- The value of the custom attribute 'orderID' of the type String should be "4711" or "4712".
- The value of the custom attribute 'deliveryDate' of type Date should be before December 31, 2014.
```
TaskAbstractCustomAttributesFilterCriteria orderIdCriteria = new 
TaskAbstractCustomAttributesValueFilterCriteria("orderId", "4711", "4712");
```
```
TaskAbstractCustomAttributesFilterCriteria deliveryDateCriteria = new
TaskAbstractCustomAttributesRangeFilterCriteria("deliveryDate",
TaskAbstractCustomAttributeDateFilterType.DATE, null, new Date(2014, 11, 31));
```
While different filter criteria on the same custom attribute are connected with ‘or’, filter criteria on different custom attributes are connected by default with ‘and’. There is a way to explicitly override the default behavior with ‘or’ when having specified different custom attribute filter criteria. The example above could be modified in its semantic accordingly as follows:
- The value of the custom attribute 'orderID' of the type String should be "4711" or "4712".
- The value of the custom attribute 'deliveryDate' of type Date should be before December 31, 2014.
```
TaskAbstractCustomAttributesOrFilterCriteria orderIdOrCustomerId = new
TaskAbstractCustomAttributesOrFilterCriteria(orderIdCriteria, deliveryDateCriteria);
```
If you use the 'orderIDOrCustomerId' variable instead of the 'orderIdCriteria' and 'deliveryDateCriteria' variables in the resulting query (see step 3), the two criteria will be connected with 'or' instead of 'and'.
Retrieve the tasks.
The TaskInstanceManager is the central entity of the BPM public API that you need to manage task instances. To access the TaskInstanceManager, you can ask the BPMFactory to return a reference to it. You can then use the TaskInstanceManager to retrieve the matching TaskAbstracts, which represent the tasks.
```
TaskInstanceManager taskInstanceManager = BPMFactory.getTaskInstanceManager();
List<TaskAbstract> tasks = taskInstanceManager.getTaskAbstracts(null, ownerCriteria, statusCriteria, priorityCriteria, orderIdCriteria, deliveryDateCriteria);
```

Displaying Custom Attributes in the Task Worklist

Custom attributes help users to take appropriate steps and decisions on tasks by providing relevant business context information. These custom attributes for tasks are defined in the process composer. For more information, see Defining Custom Attributes for Tasks .

To make these custom attributes visible in the user's task worklist, perform the following steps:

Retrieve the TaskDefinitionManager.
```
TaskDefinitionManager taskDefinitionManager = BPMFactory.getTaskDefinitionManager();
```
TaskDefinition is a basic representation of a task definition. One task definition of a task model is active; this means that tasks are instantiated from this definition.
Get the list of task custom attribute definitions for the TaskDefinition.
```
TaskDefinition . getCustomAttributeDefinitions()
```
Retrieve the TaskModelManager.
```
TaskModelManager taskModelManager = BPMFactory.getTaskModelManager();
```
The task model is an abstract representation of a task instance. Every task model has one or more task definitions.
Descriptor to specify query criteria for getting TaskAbstract(s):
```
TaskAbstractQueryCriteria
```
Marker descriptor to get custom attribute values of TaskAbstract while querying using TaskInstanceManager, TaskDefinitionManager, or TaskModelManager:
```
TaskAbstractCustomAttributesCriteria
```

To get the custom attribute values, use the following TaskAbstract method:

public java.util.Map<java.lang.String,java.lang.Object> getCustomAttributeValues()

To get the task definition ID, use the following TaskAbstract method:
```
public java.net.URI getDefinitionId()
```
To get the task model ID, use the following TaskAbstract method:
```
public java.net.URI getModelId()
```
To get custom attribute definitions, use the following methods of CustomAttributeDefinition:
- getName
  
  Returns the name of the custom attribute.
- getType
  
  Returns the type of the custom attribute.
- getLabel
  
  Returns the label of the custom attribute, which is translated based on the logged-in user's java.util.Locale.

Displaying the Task Initiator in the Task Worklist

The BPM public API provides a method that retrieves the task initiator. You can use this method to display the task initiator in the task worklist. Users can then already see in their task list who initiated their tasks without having to open the tasks.

Use the following method of the TaskAbstract interface to get the task initiator:

public IUser getTaskInitiator();

This method returns the task initiator of type IUser, if it has been mapped in the process composer. Otherwise this method returns “null”. This includes cases in which the mapped initiator cannot be found or a group or role has been mapped instead of a user.

Example

 IAuthentication auth = UMFactory.getAuthenticator();
IUser user = auth.forceLoggedInUser(request,response); 

TaskInstanceManager taskInstanceManager = null; 

try {
   taskInstanceManager = BPMFactory.getTaskInstanceManager();    

   //Task statuses we are interested in
   Set<Status> statuses = new HashSet<Status>();
   statuses.add(Status.READY);
   statuses.add(Status.CREATED);
   statuses.add(Status.IN_PROGRESS);
   statuses.add(Status.RESERVED);

   Set<TaskAbstract> taskAbstracts = taskInstanceManager.getMyTaskAbstracts(statuses);
   for(TaskAbstract ta : taskAbstracts) {
      IUser taskInitiator = ta.getTaskInitiator();
   }

 }catch (BPMException e) {
   // handle exception
}

Providing Actions on Tasks

In a task worklist, a user requires a set of actions to manage tasks. Depending on the type of task worklist, a dedicated set of actions from the following list can be provided. Actions on tasks are performed using the TaskInstanceManager. Each action requires a task instance identifier, which is a URI. This URI can be retrieved from a TaskAbstract, for example, as returned by the taskInstanceManager.getTaskAbstracts() call. See the following example.

TaskAbstract task = tasks.get(0)
URI taskInstanceID = task.getID();

Open the task.
Use the ID of a task instance to generate the URL of the task execution UI. This can then be opened as an action, for example, when the user clicks the task.
```
URL taskExecutionURL = taskInstanceManager.generateTaskExecutionUrl(taskInstanceId);
```
Claim the task.
To complete a task, the current active user must have claimed the task. Claiming the task also prevents other potential owners of the task from completing it.
Typically, a task is claimed before it is opened (pessimistic locking).
```
taskInstanceManager.claim(taskInstanceID);
```
Release the task.
If a task has been claimed by or is being processed by a user, this user (the current owner) can release the task. After the task has been released, it is available for all potential owners again.
```
taskInstanceManager.release(taskInstanceID);
```
Delegate the task.
If a user needs to delegate a task to another user, you can provide this function in the task worklist as follows:
```
IUser newOwner = ...;
taskInstanceManager.delegate(taskInstanceID, newOwner);
```
Generate a URL for the process instance visualization.
In the task worklist, you can provide a link to a graphical representation of the process instance that triggered the task. To provide such a process instance visualization, you use the TaskInstanceManager.
An absolute URL to the process instance visualization is returned for the given process instance ID.
```
ProcessInstanceManager processInstanceManager = BPMFactory.getProcessInstanceManager();
ProcessInstance processInstance = processInstanceManager.getProcessInstanceForTaskInstanceId(taskInstanceID);
URI processInstanceID = processInstance.getID();
URL visualizationUI = processInstanceManager.generateProcessInstanceVisualizationURL(processInstanceID);
```
Set the priority of a task.
You can enable the worklist user to change the priority of a task using the TaskInstanceManager as in the following example:
```
Priority priority = Priority.VERY_HIGH;
taskInstanceManager.setPriority(taskInstanceID, priority);
```

Fetching Custom Action Definitions

The BPM Public API provides a complete method accepting a custom action as a parameter. Using the following method, you can complete a task with one of the defined custom actions for this task definition.
```
public void complete(URI taskInstanceId, DataObject taskOutputData) throws BPMException
```
Use the following method of the TaskDefinition interface to get all custom action definitions for a given task definition:
```
public List<CustomActionDefinition> getCustomActionDefinitions();
```
To fetch the custom action details, use the following methods of the CustomActionDefinition class:
- getName()
  
  Returns the name of the custom action.
- getLabel()
  
  Returns the label of the custom action, which is translated based on the logged-in user's java.util.Locale.
- getDescription()
  
  Returns the detailed description of the custom action, which is translated based on the logged-in user's java.util.Locale.