Updating a task instance

Our second category of Task Based Business Service is the one that allows the buyer or seller to perform actions against the workflow task. For the purpose of this section we will look at the implementation of the setShippingDetails operation, though the other operations submitInvoice, notifyPaymentMade, confirmPaymentReceived, notifyItemShipped, and confirmItemReceived all follow the same basic pattern.

setShippingDetails is used to complete the first step in the workflow, namely update the task payload to contain the shipping name and address of the buyer as well as provide any additional shipping instructions. Finally it needs to set the outcome of the current step to COMPLETED so that the task moves on to the next step in the workflow. The following diagram shows the input fields for this operation.

From this we can see it contains the buyer's credentials, required to authenticate with the Workflow Services, the orderNo which we will use to locate the appropriate order fulfillment task, and the actual shipTo details which we will use to update the task.

To implement this operation we are going to make use of the Task Service provided by the Workflow Service; this provides a number of operations which act on a task.

Defining a PartnerLink for the Task Service

The WSDL for the Task Service is defined in the file TaskServiceWSIF.wsdl which can be found in the directory:

<SOA_HOME>\bpel\system\services\schema

The WSDL itself imports a number of other WSDLs and schemas, some of which in turn import additional schemas, all of which can be located in the same directory. In total we need to include the following files in our BPEL project:

• RoutingSlip.xsd
• TaskService.xsd
• TaskServiceInterface.wsdl
• TaskServiceWSIF.wsdl
• WorkflowCommon.xsd
• WorkflowTask.xsd

To include these files within our project, we can copy them into the bpel sub-directory in the same way we described earlier for the Task Query Service and create a corresponding PartnerLink.

An alternative approach is to add a Human Task activity to our BPEL process. In doing so, JDeveloper will automatically add all the required resources to our project. This is because BPEL makes use of the same Task Service to create a workflow task in the first place. We can then remove the actual Human Task activity from our process.

To include these files within our project, we can copy them into the bpel sub-directory in the same way we described earlier for the Task Query Service and create a corresponding PartnerLink.

An alternative approach is to add a Human Task activity to our BPEL process. In doing so, JDeveloper will automatically add all the required resources to our project. This is because BPEL makes use of the same Task Service to create a workflow task in the first place. We can then remove the actual Human Task activity from our process.

Using the updateTask operation

Most of the tasks provided by this service are granular in nature and only update a specific part of a task. Thus they only require the taskId and the corresponding part of the task being updated as input.

However, our operation needs to update multiple parts of a task, that is, the order held in the task payload, the corresponding Flex fields and the task outcome. For this we will use the updateTask operation. The following diagram shows its expected input:

From this we can see that it expects the standard workflowContext as well as the complete updated task element.

The simplest way to achieve this is to use the Task Query Service to get an up-to-date copy of our task. We do this in exactly the same way we did for our getOrderDetails operation, but then modifying it as appropriate and calling the updateTask operation to make the changes.

Updating the task payload

The only area of complexity is updating the order directly within the task payload. This is for the same reason we mentioned earlier when implementing the getOrderDetails operation; as the payload is defined as xsd:any, we can't use the XPath mapping tool to visually map the updates.

The simplest way to work around this is to first extract the order from the task payload into a local variable (which we do in exactly the same way that we did for our getOrderDetails operation).

Once we've done this we can update the shipTo element of the order to hold the shipping details as well as update its status to Awaiting Shipping Costs to reflect the next step in the workflow.

Once we have updated the order, we must insert it into the task payload; this is essentially the reverse of the copy operation we used to extract it.

Updating the task Flex fields

Once we have updated the task payload we then need to update the corresponding Flex fields so that they remain synchronized with the order. We do this using an assign activity in a similar way that we used to set the Flex fields when creating the task in our OrderFulfillment process.

Updating the task outcome

Finally, we need to set the task outcome for the current step (this is effectively the same as specifying a task action through the worklist application). In our case we have defined two potential outcomes: COMPLETED or ABORTED.

For setShippingDetails (as with all of our operations), we want to set the task outcome to COMPLETED. Note that this won't actually complete the task, rather it completes the current assignment, and in our case since all our routing policies are single approver, it will complete the current step in the workflow and move the task on to the next step. Only once the final step is completed will the task complete and control be returned to the OrderFulfillment BPEL process.

To set the task outcome, we only need to set the outcome element (located in the task systemAttributes element) to COMPLETED. However, it isn't quite that straightforward; if you look at the actual task data returned by the getTaskDetailsByNumber operation, the outcome element isn't present.

Thus, if we use a standard copy operation to try to assign a value to this element we will get an XPath exception.

Instead what we need to do is create the outcome element and its associated value and append it to the systemAttributes element. To do this within the assign activity, use an Append Operation as shown in the following diagram:

The simplest way to create the outcome element is to use an XML Fragment and append it to the systemAttributes element as shown in the following screenshot:

Once we've done this we will have a completed task, so that all that remains to do is call updateTask to complete the operation.