POST a Complex Search Request for HPSTRA-enabled Tasks

Edit online

This REST request retrieves tasks that are specified with more complex search criteria. The underlying built-in services are:

  • pub.task.taskclient:searchTasksHPSTRA
  • pub.task.taskclient:searchTasksFieldsHPSTRA
  • pub.task.taskclient:searchTasksIndexedHPSTRA
  • pub.task.taskclient:countTasksIndexedHPSTRA
This request can be used in the following four modes:
  • searchTasksHPSTRA mode. Retrieve tasks that match specified search criteria, when working with HPSTRA-enabled tasks that use standard business data.
  • searchTasksFieldsHPSTRA mode. Return a collection of named fields from HPSTRA-enabled tasks, requested in each service that matches specified search criteria.
  • searchTasksIndexedHPSTRA mode. Return a subset of tasks that match the specified search criteria, when working with business data fields, indexed in an Elasticsearch store by the HPSTRA module in Task Engine.
  • countTasksIndexedHPSTRA mode. Return the total count of tasks that match the specified search criteria. This service applies only to tasks with business data fields, indexed in an Elasticsearch store by the HPSTRA module in Task Engine.

For additional information on these modes, see Usage Notes.

searchTasksHPSTRA Mode

Use this mode to retrieve tasks that match specified search criteria. This request applies only to HPSTRA-enabled tasks that use standard business data.

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

POST /rest/pub/opentasksearchhpstra

Input Parameters

includeTaskData String Optional. Specifies whether the service will return the TaskData document as well as the pub.task:TaskInfo document for each task matching the search criteria. Set to:
  • true to include the TaskData document in the result set.
  • false (default) to include only the TaskInfo document in the result set.
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.
taskSearchQuery or TaskSearchQuery Document Optional. The TaskSearchQuery document, which specifies the search criteria. See pub.task:TaskSearchQuery for a description of the fields in this document. If TaskSearchQuery is null, all tasks for user will be returned.
user String Optional. The user ID of the IBM My webMethods Server user on whose behalf this service will execute. If user is not specified, the user ID associated with the WmTaskClient package is used. For information about configuring this user ID, see IBM webMethods Task Engine User’s Guide.
Note: Only tasks to which user has access are searched.

Output Parameters

Tasks Document list Result set containing the tasks that match the search criteria in pub.task:TaskSearchQuery. Each document in the result set has the following structure:
  • TaskID String The identifier assigned to the task instance.
  • TaskInfo Document TaskInfo document containing standard information about the task. See pub.task:TaskInfo for a description of the fields in this document.
  • TaskData Document The TaskData document containing the business data associated with the task. Returned only if includeTaskData is set to true.

searchTasksFieldsHPSTRA Mode

This mode is used to return a collection of named fields from HPSTRA-enabled tasks, requested in each service that matches specified search criteria.

Note: This request can only return primitive types (strings, numbers, dates, and so on) 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/opentasksearchhpstra/fields

Input Parameters

fields String list Optional. List of task fields to be returned by this service. For information about specifying fields, see the fields and operator elements in pub.task: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}

The service will return values for these fields only.

includeTaskData String Optional. Specifies whether the service will return the TaskData document as well as the pub.task:TaskInfo document for each task matching the search criteria. Set to:
  • true to include the TaskData document in the result set.
  • false (default) to include only the TaskInfo document in the result set.
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.
taskSearchQuery or TaskSearchQuery Document Optional. The TaskSearchQuery document, which specifies the search criteria. See pub.task:TaskSearchQuery for a description of the fields in this document. If TaskSearchQuery is null, all tasks for user will be returned
user String Optional. The user ID of the IBM My webMethods Server user on whose behalf this service will execute. If user is not specified, the user ID associated with the WmTaskClient package is used. For information about configuring this user ID, see IBM webMethods Task Engine User’s Guide.
Note: Only tasks to which user has access are searched.

Output Parameters

TaskFields Document list Result set containing a list of documents whose document type is defined in pub.task:TaskFields.

searchTasksIndexedHPSTRA Mode

Use this mode to return a subset of tasks that match the specified search criteria on the Task Engine connected to the Integration Server.

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 service only when working with tasks with business data fields, indexed in an Elasticsearch store by the HPSTRA module in Task Engine. If you are working with standard business data fields, use searchTasksHPSTRA Mode.

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

POST /rest/pub/opentasksearchhpstra/indexed

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.
  • 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 pub.task.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. If user is not specified, the user ID associated with the WmTaskClient package is used. For information about configuring this user ID, see IBM webMethods Task Engine User’s Guide.
Note: Only tasks to which user has access are searched.

Output Parameters

Tasks Document list Result set containing the tasks that match the search criteria in pub.task.TaskSearchQueryV2. Each document in the result set has the following structure:
  • TaskID String The identifier assigned to the task instance.
  • TaskInfo Document The TaskInfo document containing standard information about the task. See pub.task:TaskInfo for a description of the fields in this document.
  • TaskData Document The TaskData document containing the business data associated with the task. Returned only if includeTaskData is set to true.

countTasksIndexedHPSTRA 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 business data fields, indexed in an Elasticsearch store by the HPSTRA module in Task Engine.

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

POST /rest/pub/opentasksearchhpstra/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 includeTaskData 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 pub.task.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. If user is not specified, the user ID associated with the WmTaskClient package is used. For information about configuring this user ID, see IBM webMethods Task Engine User’s Guide.
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:

  • searchTasksHPSTRA. This mode applies only to HPSTRA-enabled tasks that use standard business data.
  • searchTasksFieldsHPSTRA. Using this mode instead of the searchTasks mode can significantly improve search performance. The searchTasksHPSTRA 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 searchTasksFieldsHPSTRA mode, a very narrow search can be tailored, often requiring only a few TaskInfo fields and some business data fields. Using searchTasksFieldsHPSTRA mode is strongly recommended to prevent problems.
  • searchTasksIndexedHPSTRA. 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.
  • countTasksIndexedHPSTRA. To be used when specifying the toIndex and fromIndex parameters of the searchTasksIndexedHPSTRA mode to avoid requesting an index beyond the size of the search results. These two parameters are available in the input document pub.task.TaskSearchQueryV2.