Show TOC

Building an Execution UI with the BPM APILocate this document in the navigation structure

Use

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 execution UI. You can assign this task execution UI as UI component to a task.

The task instance ID is passed to the UI via HTTP parameter taskId .

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

When the task execution UI is opened in the universal worklist (UWL) or in the BPM Inbox, the user is propagated within the session. If the task execution UI is launched directly, user credentials need to be provided. If the user is already authenticated, the same user is used. If the user is not authenticated, the user must be asked to log on.

             com.sap.security.api.IAuthentication auth = com.sap.security.api.UMFactory.getAuthenticator();
            // HTTP Request and Response instance
            com.sap.security.api.IUser user =  auth.forceLoggedInUser(request,response);

  1. Retrieve the TaskInstanceManager

                      TaskInstanceManager taskInstanceManager = BPMFactory.getTaskInstanceManager();

  2. 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.

                      HashSet<Status> statuses = new HashSet<Status>();
                  statuses.add(Status.READY);
                  statuses.add(Status.RESERVED);
                  statuses.add(Status.IN_PROGRESS);

  3. 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.

                      Set<TaskAbstract> myTasks = taskInstanceManager.getMyTaskAbstracts(statuses);

  4. Claim and execute the task.

    Typically, before displaying a start execution UI, the task should be claimed and its execution should be started. The task instance ID could be retrieved as a string from the request parameter.

                      String taskId = request.getParameter("taskId"); // This has to be converted to URI
                  URI taskInstanceId = URI.create("bpm://bpm.sap.com/task-instance/"+taskId);
                  taskInstanceManager.claim(taskInstanceId);
                  taskInstanceManager.start(taskInstanceId);

  5. Get the detailed task information.

    To create a task execution UI, more data is needed than is provided by a TaskAbstract. You need to get the TaskDetail. This can be done by using the ID of a task instance. The TaskDetail contains thorough information about the task.

                      URI taskInstanceId = myTask.getId();
                  TaskDetail taskDetail = taskInstanceManager.getTaskDetail(taskInstanceId);

  6. Get the input data.

    The TaskDetail can be used to obtain the input and output data of the task. The input and output data is represented by a data object.

                      DataObject taskInput = taskDetail.getInputDataObject();
                  DataObject taskOutput = taskDetail.getOutputDataObject();

  7. Create the UI

    The taskInput data object can now be used to read the initial task data and the taskOutput data object to write the result of the task execution. For more information about accessing the data objects, refer to the Service Data Objects (SDO) standard. An arbitrary UI Technology can be used for the task execution UI.

  8. (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).

                      void release(URI taskInstanceId) throws BPMException

  9. (Optional step) Delegate the task.

    Triggers the delegate task action.

                      void delegate(URI taskInstanceId,IUser newOwner)throws BPMException

  10. (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.

                      URL generateProcessInstanceVisualizationURL(URI processInstanceId)throws BPMException

  11. (Optional step) Set Priority.

    Sets the priority of the given task to a new value.

                      void setPriority(URI taskInstanceId,Priority prioriy)throws BPMException

  12. Complete the task.

    After the execution of the task, it can be completed with the (modified) output data.

                      taskInstanceManager.complete(taskInstanceId, taskOutput);
More Information