Using the Task Engine Web Service API

Edit online

Overview

Edit online

The Web service API enables you to add, delete, locate, and update tasks on a IBM webMethods BPM Task Engine from a client program.

The Task Engine hosts two versions of the task Web service, one version for .NET clients and the other for regular Web-service clients. Both versions of the Web service provide the same set of operations, however, the schemas for the underlying data structures differ slightly between the two. The .NET version of the service uses structures that are compatible with .NET clients.

Note: If you want to manipulate tasks from the Integration Server environment, use the built-in Java services described in Using the Task Engine Built-in Services. Do not use the Web service operations described in this chapter with Web services created within Integration Server.

Task Service URLs

Edit online

The task Web service is hosted at the following endpoints on the machine where the Task Engine is installed.

  • For regular Web service clients, the task Web service is hosted at: http://hostName:port/services/bizPolicy/task
  • For .NET clients, the task Web service is hosted at: http://hostName:port/services/bizPolicy/taskDotNet

Where:

hostName specifies the machine where IBM My webMethods Server and the Task Engine are running.

port specifies the port on which IBM My webMethods Server listens for http requests. The default port is 8585, however, this port assignment is configurable. If you do not know which port your server uses, contact your IBM My webMethods Server administrator.

Example: http://server:8585/services/bizPolicy/task

Extracting the WSDL for the Task Web Service

Edit online

About this task

To obtain the task WSDL

Procedure

  1. log on to IBM My webMethods Server as sysadmin.
  2. Navigate to one of the following URLs:
    • For .NET clients: http://server:port/services/bizPolicy/taskDotNet?wsdl
    • For other clients: http://server:port/services/bizPolicy/task?wsdl

Using the Task Web Service Operations

Edit online

To use the task Web service operations described below, your client program must log on to IBM My webMethods Server with a user ID that has appropriate functional and task access privileges on the Task Engine. Operations that your client program performs are executed under this user ID. If the user ID does not have the required function and task access privileges, the operation fails and an exception is generated.

You can specify an alternative user ID for the operation by setting the optional user input parameter, which is available on all operations in the task Web service. This parameter enables a client program to perform an operation under a user ID that is different from the one it used to log on to IBM My webMethods Server.

Important: To use the user parameter, your client program must log on to the IBM My webMethods Server with a user ID that belongs to the "Admin Role" role. If your program does not belong to the "Admin Role" role and it requests an operation using the user parameter, the operation fails and an exception is generated.

When a client requests an operation with the user parameter, the Task Engine executes the operation as though it were requested by the specified user. For example, if your client program logs on as "mrussel," but executes the searchTask operation under the user ID "rkosi," the Task Engine searches only tasks the user "rkosi" can access.

IBM My webMethods Server updates a user's role membership only when the user interactively logs in into IBM My webMethods Server. When impersonating a user with the Task Engine APIs, there is no interactive login of this user to IBM My webMethods Server. Therefore, the Task Engine itself handles role membership changes and updates for these impersonated users.

The Task Engine updates a user's role membership when:

  • A specified time has passed since last time the user ID was impersonated. The default value is 30 minutes.
  • A specified time has passed since the last time the user's role membership was updated. The default value is 24 hours (session total time-to-live).

These default time periods can be modified with the following environment settings: 

-Dtask.remote.session.timeout=<the time period in seconds between updates 
of user role information. The session is not invalidated or expired.>  
-Dtask.remote.session.ttl=<user session time-to-live in seconds>
Important: It is important to understand that the -Dtask.remote.session.timeout setting does not affect the duration of the actual session. The only purpose of the setting is to specify the time interval between updates to the impersonated user’s role membership.
  • For more information about setting these options, and assigning task functional privileges and task access privileges, see the PDF publication IBM webMethods Task Engine User’s Guide.
  • For more information about working with roles and users, see the PDF publication IBM webMethods Integration Server Administrator’s Guide.

Summary of Available Operations

Edit online

The following table lists the operations that the task service provides.

Operation Description
addTagsToTask Adds tags to a task.
addTaskAttachment Adds the specified attachment to a task.
addTaskComment Adds a comment to a task.
countTasksIndexed Returns the total count of tasks that match the specified search criteria in a searchTasksIndexed search.
deleteTagsFromTask Deletes all tags from a task.
deleteTask Deletes an instance of a task from the Task Engine.
deleteTaskAttachment Deletes the specified task attachment.
deleteTaskComment Deletes a comment from a task.
formFlowTaskNotify Service that notifies a waiting step in a task workflow that the workflow is completed.
getTask Returns the TaskInfo object, and optionally the TaskData object, for a specified task.
getTaskAttachments Returns all the attachments in a task.
getTaskAudit Returns the audit log of all of the operations performed on a task.
getTaskComments Returns all the comments in a task.
getTaskExpertList Returns a list of experts associated with the tags.
listTagsByTask Lists all the tags of a task.
queueTask Adds a task instance to the Task Engine.
rollbackTask Enables you to roll back the task to any available audit point in the task's audit history.
searchTasks Returns an array of tasks that match specified search criteria.
searchTaskFields Returns a list of tasks that match specified field search criteria.
searchTasksIndexed Returns a subset of tasks that match the specified search criteria against indexed business data.
updateTask Modifies an existing task instance on the Task Engine. You use this operation to change information in the task's TaskInfo and TaskData objects. This service applies only to tasks with Active, Error, and Suspended status. For information about updating tasks with other statuses, see Usage Notes.
updateTaskAttachment Updates the specified task attachment.
updateTaskComment Updates the specified task comment.
updateTaskTags Updates the tags of a task.