Task invocation

A to-do task is a component in an SCA module. Basically, there are three ways to invoke a to-do task:

  1. Invocation from outside the SCA module (export)
  2. Invocation from a component inside the same SCA module (wiring)
  3. Invocation by a custom client application using the task API

The first two ways ways will be discussed shortly. The third way will be illustrated with code snippets.

SCA export

You can make a to-do task available outside the SCA component by exporting the interface. You can choose different bindings like SCA or Web services. To export the interface, add an export to your SCA module. The default preferred interaction style of the to-do task is any. The following diagram shows how the to-do task is exported with an SCA binding:

SCA component

If you want to invoke the to-do task from components inside your SCA module, you can add a wire from these components to the to-do task component. Note that the to-do task has a preferred interaction style of asynchronous and a join transaction qualifier of false. BPEL processes that invoke to-do tasks should be defined as long-running processes. In addition, the asynchronous nature of the to-do tasks should be considered when the BPEL process is modeled. The following diagram shows the wiring from a BPEL process to the to-do task.

The ToDoTask project in the Download section of this sample contains a simple BPEL process that calls the to-do task.

Task API

If you invoke a to-do task through the task API, you do not need to export or wire the task component.

The next sections show the basic API commands that you can include in your application to invoke to-do tasks.

Java libraries

The required Java classes and interfaces can be found in the following package:

com.ibm.task.api.*

HumanTaskManager EJB

The key access point is the HumanTaskManager EJB. The following sample code shows how to create the local HumanTaskManager EJB:

javax.naming.Context context = new javax.naming.InitialContext();
LocalHumanTaskManagerHome taskHome = (LocalHumanTaskManagerHome)context.lookup("java:comp/env/ejb/LocalHumanTaskManagerHome");
LocalHumanTaskManager taskManager = taskHome.create();

Starting tasks

The first step is to create a new task. Provide task name and namespace:

TKIID pTaskID = taskManager.createTask("RequestTask", "http://ToDoTask/bpc/samples");

With the task instance identifier returned by the createTask operation, you can obtain the task instance:

Task task = taskManager.getTask(pTaskID);

Before you can start the task, you have to provide the task input message. The input message is a commonj.sdo.DataObject wrapped in a ClientObjectWrapper. A pre-initialized ClientObjectWrapper can be obtained from the task instance:

ClientObjectWrapper cow = taskManager.createInputMessage(pTaskID);
commonj.sdo.DataObject inner = (DataObject)cow.getObject();
inner.setString("question",request.getParameter("task_question"));

Note: Only the top-level DataObject is created implicitly by the ClientObjectWrapper. If the task input message is of a complex type, you have to explicitly create the nested DataObjects before setting parameters.

After you have composed the task input message, you can start the task. Provide the task instance identifier and the task input message. If you want to use a custom reply handler, you can pass your own implementation as the third parameter:

taskManager.startTask(pTaskID, cow, null);

After the task has finished, you can access the task output message. The task output message is also wrapped in a ClientObjectWrapper:

ClientObjectWrapper resp = taskManager.getOutputMessage(temp);
DataObject inner = (DataObject)resp.getObject();
answer = inner.getString("answer");

Querying tasks

Before you can work with a to-do task, you have to retrieve a particular task instance from the internal task database. To retrieve task instances, the task API offers powerful query capabilities. To obtain the task instances of a particular task template, issue the following query:

String selectClause = "DISTINCT TASK.TKIID";
String whereClause = "TASK_TEMPL.NAME='RequestTask' AND TASK_TEMPL.NAMESPACE="http://ToDoTask/bpc/samples";
QueryResultSet instances = taskManager.query(selectClause, whereClause, null, null, null, null);

The returned QueryResultSet contains the task instance identifiers. You can iterate the QueryResultSet using the following operations:

boolean b = instances.first();
b = instances.next();

To get the task instance, issue the following commands:

TKIID tkiid = (TKIID) instances.getOID(1);
Task task = taskManager.getTask(tkiid);

For a more detailed description of the query capabilities, refer to the Information center.

Deleting tasks

If a task is in one of the states inactive, terminated, expired, finished, or failed, you can delete a task instance:

taskManager.delete(tkiid);

Prepare your Web application

Add to the Web deployment descriptor a reference to the local session bean. The relevant elements of the deployment descriptor are shown in the following XML fragment:

<ejb-local-ref>
  <ejb-ref-name>ejb/LocalHumanTaskManagerHome</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <local-home>com.ibm.task.api.LocalHumanTaskManagerHome</local-home>
  <local>com.ibm.task.api.LocalHumanTaskManager</local>
</ejb-local-ref>

To add an EJB reference binding, complete the following steps:

  1. Switch to the deployment descriptor editor of your Web application.
  2. Click the References tab.
  3. In the JNDI name field of the WebSphere Bindings section, enter the reference binding.

    4. The following screenshot shows the reference binding of the Web deployment descriptor in WebSphere Integration Developer:

If the WebSphere Bindings section is not shown, it is necessary to add two missing project facets. Perform the following steps in order to do so:

  1. In the navigation tree, right-click the project for which you want to add the project facets.
  2. From the context menu, select Properties. The Properties window opens.
  3. Select Project Facets. The included project facets are listed.

    4. Note: Depending on the type of project you are working with, different project facets are included in this list.

  4. Click Add/Remove Project Facets. The Add/Remove Project Facets window opens.
  5. From the list of project facets, select WebSphere Web (Co-existence) and WebSphere Web (Extended).

    6. Note: Depending on the type of project you are working with, different project facets are available for selection.

  6. Click Finish. The Add/Remove Project Facets window closes.

    7. The list of included project facets now contains the two added facets:

  7. Click Finish. The Properties window closes.

    8. Note: If the application's deployment descriptor editor was open while you added the project facets, close it and then open it again. The added project facets will only take effect after this is done.