POST a Complex Task Search Request

Edit online

This REST request retrieves tasks that match the specified complex search criteria.

This request can be used in the following modes:
  • searchTasksFields mode. Return a collection of named fields requested in each service that matches specified search criteria.
  • searchTasksIndexed mode. Return a subset of tasks that match the specified search criteria, when working with indexed business data fields.
  • countTasksIndexed mode. Return the total count of tasks that match the specified search criteria. This service applies only to tasks with indexed business data.

For additional information on these modes, see Usage Notes.

searchTasksFields Mode

This mode is used to return a list of tasks that match specified field search criteria.

Note: This request can return only primitive types (for example, Strings, Numbers, Dates) or lists (arrays) of primitives. It cannot return complex objects such as all task business data.

Use this HTTP request and include optional parameters in the request body:

POST /rest/pub/opentasksearch/fields

Input Parameters

fields String List of tasks fields that are to be returned by this service. For information about specifying fields, see the fields and operator parameters in TaskSearchQueryTerm. For example, suppose you want to return the following fields as result of the query:
  • taskID
  • The business data field orderID from task data documents.

You would then pass in following field specifications:


#{currentTask.taskInfo.taskID}

#{currentTask.taskData.order.orderID}

This API returns the values for these fields only.

includeTaskData String Optional. Specifies whether the operation returns the TaskData object as well as the TaskInfo object for each task matching the search criteria. Set to:
  • true to include the TaskData in the result set.
  • false (default) to include only the TaskInfo in the result set.
taskSearchQuery TaskSearchQuery The TaskSearchQuery object, which specifies the search criteria. See TaskSearchQuery for a description of the fields in this object.

If TaskSearchQuery is null, all tasks for user are returned.

user String Optional. The user ID of the IBM My webMethods Server user on whose behalf this operation executes.

If user is not specified, the administrative user ID under which your client program logged on is used.

Note: Only tasks to which user has access are searched.
fields String List of tasks fields that are to be returned by this service. For information about specifying fields, see the fields and operator elements in TaskSearchQuery. For example, suppose you want to return the following fields as result of the query:
  • taskID
  • The business data field orderID from task data documents.

You would then pass in following field specifications: 

#{currentTask.taskInfo.taskID}
#{currentTask.taskData.order.orderID}

This API returns the values for these fields only.

Output Parameters

Task Field Document List Result set containing the tasks that match the search criteria in TaskSearchQuery. Each document in the result set has the following structure:
  • name String Name of the task.
  • value Object The value of the field contents for the specified field(s).

That is, the service returns a collection of tasks that match the query. For each task, it returns a collection of specified fields.

The purpose of this API is to ease performance issues of searchTasks. It is quite common that only few taskInfo fields along with some business data fields are returned. searchTasks returns the entire TaskInfo plus TaskData documents. The TaskData could be very large. This could cause the SOAP response size to become an issue, severely limiting the performance of this service. By using searchTaskFields instead, the user can choose to return only a few fields which can help improve performance.

searchTasksIndexed Mode

Use this mode to return a subset of tasks that match the specified search criteria against indexed business data.

The query must contain a search term specifying the taskTypeID when searching for business data fields. The Task Engine uses the taskTypeID to identify the specific index table to use. You can search for multiple task types in a single query by specifying multiple taskTypeID values when you define the search criteria. If you are not searching for business data fields, then a taskTypeID is not required.

Use this HTTP request and include optional parameters in the request body:

POST /rest/pub/opentasksearch/indexed

Input Parameters

businessData Boolean Optional. Indicates whether the search query operation includes indexed business data when processing the search query. Use this property when your search query contains search terms that reference indexed business data fields. Set to:
  • true to include business data in the search query processing.
  • false (default) when your search query does not require processing of business data or when your task type does not use any defined indexed business fields.
taskSearchQuery TaskSearchQueryV2 Specifies the TaskSearchQueryV2 object that provides the search criteria. If taskSearchQueryV2 is null, an error occurs.
user String Optional. Specifies the user ID of the IBM My webMethods Server user for which the operation executes. If user is not specified, the administrative user ID under which your client program logged on as is used. When you use this parameter, the search is limited to tasks that are accessible by the user.
userTasks Boolean Optional. Indicates whether the operation searches all tasks or only the user’s inbox. This parameter is overridden if the user parameter contains a value. Set to:
  • true to execute the search only on the user’s inbox.
  • false (default) to search accessible user tasks.

By default, only active tasks are returned. This can be overridden with the showNonActiveTasks parameter in TaskSearchQuery.

Output Parameters

tasks Task Specifies an array of Task objects representing the tasks that match the search criteria in TaskSearchQueryV2.

If no tasks match the search criteria, an empty array is returned.

countTasksIndexed Mode

This mode is used to return the total count of tasks that match the specified search criteria. This request applies only to tasks with indexed business data.

Use this HTTP request and include optional parameters in the request body:

POST /rest/pub/opentasksearch/count

Input Parameters

includeTaskData String Optional. Indicates whether the search query operation includes indexed business data when processing the search query. Use this property when your search query contains search terms that reference indexed business data fields. Set to:
  • true to include business data in the search query processing. An error occurs if businessData is set to true and the task type does not contain any indexed fields.
  • false (default) when your search query does not require processing of business data or when your task type does not use any defined indexed business fields.
searchUserTasks String Optional. Specifies whether the service searches all tasks or only the user's inbox. Set to:
  • true to search only the inbox for user.
  • false (default) to search all tasks to which user has access.
taskSearchQueryV2 or TaskSearchQueryV2 Document Optional. The TaskSearchQueryV2 document that specifies the search criteria. See TaskSearchQueryV2 for a description of the fields in this document. If TaskSearchQueryV2 is null, an error occurs.
user String Optional. The user ID of the IBM My webMethods Server user on whose behalf this service will execute.
Note: Only tasks to which user has access are searched.

Output Parameters

totalCount String Returns the total number of tasks that match the query.

Usage Notes

The following considerations apply to the available modes:

  • searchTasksFields. Using this mode instead of the searchTasks mode can significantly improve search performance. The searchTasks mode returns all TaskInfo data plus TaskData documents, which can result in a very large amount of data. Because this is a Web service (REST) call, the response size becomes an issue, severely limiting performance of this service. With searchTasksFields mode, a very narrow search can be tailored, often requiring only a few TaskInfo fields and some business data fields. Using searchTasksFields mode is strongly recommended to prevent problems.
  • searchTasksIndexed. If no tasks match the search criteria, an empty TaskData document is returned. The search query must contain a search term specifying the taskTypeID to search business fields and create an index of the results.
  • countTasksIndexed. To be used when specifying the toIndex and fromIndex parameters of the searchTasksIndexed mode to avoid requesting an index beyond the size of the search results. These two parameters are available in the input document TaskSearchQueryV2.