Building a Task Worklist with the BPM API

With the Business Process Management (BPM) application programming interfaces (APIs), you can customize and enhance the way you use business processes and execute tasks.

This document describes how you 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 tc/je/sdo21/api in software component ENGFACADE.

Procedure

Building a Simple Task Worklist

Retrieve the TaskInstanceManager.

Syntax Syntax

TaskInstanceManager taskInstanceManager = BPMFactory.getTaskInstanceManager();

End of the code.

Build the set of statuses to query.
Typically, you use READY, RESERVED and IN_PROGRESS statuses, which mean that the tasks are ready to work on and the user is a potential or actual owner of the task.
Syntax
1. ```
HashSet<Status> statuses = new HashSet<Status>();
```
2. ```
statuses.add(Status.READY);
```
3. ```
statuses.add(Status.RESERVED);
```
4. ```
statuses.add(Status.IN_PROGRESS);
```
End of the code.
Query those statuses.
The returned set contains TaskAbstracts, which are basic descriptions of a task instance and thus contain the required information to build up the task worklist. The method always executes the query for the user who is currently logged in and returns texts in the locale which is set for the user.
Syntax
1. ```
Set<TaskAbstract> myTasks = taskInstanceManager.getMyTaskAbstracts(statuses);
```
End of the code.
To use paging you can use the following methods:
- getMyTaskCount
- getTaskCountForMySubstitutedUsers
- getTaskCountForAllMySubstitutedUsers
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.
Syntax
1. ```
URI taskInstanceId = myTask.getId();
```
2. ```
URL taskExecutionURL = taskInstanceManager.generateTaskExecutionUrl(taskInstanceId);
```
End of the code.
(Optional step) Release the task.
Triggers the release task action (the task is released by the actual owner and it is now available for all potential owners again).
Syntax
1. ```
void release(URI taskInstanceId) throws BPMException
```
End of the code.
(Optional step) Delegate the task.
Triggers the delegate task action.
Syntax
1. ```
void delegate(URI taskInstanceId,IUser newOwner)throws BPMException
```
End of the code.
(Optional step) Generate Process Instance Visualization URL.
Returns an absolute URL to the Process Visualization for the given process instance ID. Can be used to embed it into a custom UI or to display the hyperlink.
Syntax
1. ```
URL generateProcessInstanceVisualizationURL(URI processInstanceId)throws BPMException
```
End of the code.
(Optional step) Set Priority.
Sets the priority of the given task to a new value.
Syntax
1. ```
void setPriority(URI taskInstanceId,Priority prioriy)throws BPMException
```
End of the code.

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.
Syntax
1. ```
TaskDefinitionManager taskDefinitionManager = BPMFactory.getTaskDefinitionManager();
```
End of the code.
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.
Syntax
1. ```
TaskDefinition . getCustomAttributeDefinitions() 
```
End of the code.
Retrieve the TaskModelManager.
Syntax
1. ```
TaskModelManager taskModelManager = BPMFactory.getTaskModelManager();
```
End of the code.
The task model is an abstract representation of a task instance. For every task model there are one or many task definitions.
Descriptor to specify query criteria for getting TaskAbstract(s):
Syntax
1. ```
TaskAbstractQueryCriteria
```
End of the code.
Marker descriptor to get custom attribute(s) value of TaskAbstract while querying using TaskInstanceManager, TaskDefinitionManager, TaskModelManager:
Syntax
1. ```
TaskAbstractCustomAttributesCriteria
```
End of the code.
To get the custom attributes values, use the following TaskAbstract method:
Syntax
1. ```
public java.util.Map<java.lang.String,java.lang.Object> getCustomAttributeValues()
```
End of the code.
To get the task definition ID, use the following TaskAbstract method:
Syntax
1. ```
public java.net.URI getDefinitionId()
```
End of the code.
To get the task model ID, use the following TaskAbstract method:
Syntax
1. ```
public java.net.URI getModelId()
```
End of the code.
To get custom attributes 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 logged in user's java.util.Locale.

Fetching Custom Action Definitions

The BPM Public API provides a complete method accepting a custom action as a parameter. Using the following method, one can complete a task with one of the already defined custom actions for this task definition.
Syntax
1. ```
public void complete(URI taskInstanceId, DataObject taskOutputData) throws BPMException
```
End of the code.
Use the following method of the TaskDefinition interface to get all custom action definitions for a given task definition:
Syntax
1. ```
public List<CustomActionDefinition> getCustomActionDefinitions();
```
End of the code.
To fetch the custom actions 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 logged in user's java.util.Locale.
- getDescription()
  Returns the detailed description of the custom action, which is translated based on logged in user's java.util.Locale.