Retrieve tasks by filter

Learn how you can use the Retrieve Tasks by Filter API to retrieve the tasks.

The API retrieves the details of the tasks by using specific filters.

Operation Endpoint:

POST {workflowPath}/workflow/{tenantId}/tasks/history

Note: Consider the following information while retrieving tasks by filter:

Endpoint retrieves a task only if you had READ access to the objects of the task (entities, change requests, or relations) when the task was created.

To retrieve the task, use the parameters listed in Table 1: Parameters used while Retrieving a Task.

Table 1. Parameters used while retrieving a task
Parameter		Required	Description
Headers	`Authorization`	Yes	Access Token in format `Bearer <access token>` (see details in Authentication API).
	`Content-Type`	Yes	Type of content. It must be `Content-Type: application/json`.
	`EnvironmentURL`	Yes	Reltio Environment URL
Body	`assignee`	No	Task assignee. To retrieve unassigned tasks, use a value of `none`.
	`processInstanceId`	No	Process instance ID
	`processType`	No	Process instance type. Use this field to filter on a single process type.
	`processTypes`	No	Process instance Type. Use this field to filter on multiple process types. For example, `dataChangeRequestReview` and `recommendForDelete`.
	`offset`	No	Start position
	`max`	No	Number of records to be returned
	`suspended`	No	Suspended: true or false.
	`createdBy`	No	Task owner
	`priorityClass`	No	Possible values: Urgent, High, Medium, Low.
	`orderBy`	No	Sort criteria. Possible values: createTime (default), assignee, dueDate, priority.
	`ascending`	No	Is used with `orderBy`. Ascending: true and descending: false (default).
	`taskType`	No	Task type
	`createdAfter`	No	Time in milliseconds
	`createdBefore`	No	Time in milliseconds
	`state`	No	Validation state of a task. The possible values are as follows: valid invalid all The default value is valid.
	`objectURIs`	No	List of Reltio object URIs (entity/relation). You can retrieve the tasks if the filter includes at least one `object URI`.
	`open`	No	Includes open tasks. Can be set to true or false. If the parameter isn’t specified (default behavior), it returns all the tasks. If the parameter is true, it returns the open tasks only. If the parameter is false, it returns the closed tasks only.
	`completedAfter`	No	Time in milliseconds
	`completedBefore`	No	Time in milliseconds
	`completedBy`	No	Username
	`showTaskVariables`	No	Displays task variables. It must be true or false. If true, returns the task variables if the user wants to view the details of the variables. Default is false.
	`showTaskLocalVariables`	No	Displays task local variables. It must be true or false. If true, returns the task local variables if the user wants to view the details of the variables. Default is false.

Response

Response Structure:

offset: start position of records
size: number of records returned
total: total number of records
data: array with results for each element returned. Each result will have the following properties:
- assignee: task assignee
- createTime: task creation time
- createdBy: task creator
- dueDate: due date for the task
- processInstanceComments: comments for the process instance, an array with results for each element returned. Each result will have the following properties:
  - id: comment ID
  - message: comment message
  - author: comment author
  - time: comment time
- taskId: task ID
- displayName: task name
- processInstanceId: process instance ID
- processTypes: process definition types
- processDefinitionDisplayName: process definition display name
- taskType: task definition type (provided during process design time)
- suspended: is suspended (true/false)
- objectURIs: object URIs for the task; the list contains two entities for potential matches or one entity/relation otherwise
- possibleActions: possible user actions on the task
  - action: action name
  - label: display value for the action
- preferredAction: preferred possible user action on the task
  - action: action name
  - label: display value for the action
- priority: task priority
- priorityClass: Urgent/High/Medium/Low based on the priority value
- repeatingTask: indicates whether the task has been repeated or not (true/false). The true value means that a task of the same task type was created earlier in the process. Default is false.
- validationMessage: validation message
- isOpen: true/false to indicate if the task is open/closed
- updateTime: time of the last update on the task
- completedAction: user action on task completion
  - action: action name
  - label: display value for the action
- completeTime: time of the task completion (for closed tasks only)
- completedBy: user that completed this task (for closed tasks only)
- valid: indicates whether the task is valid or not (true/false)
- taskLocalVariables-task local variables
- taskVariables-task variables
error: returned if an error is encountered; contains details of the issue:
- errorCode: 5-digit error code
- errorMessage: error message
- errorData: details of the error:
  - exception: exception message
  - stack: stack trace
- innerError: details of the error from the Reltio API:
  - errorMessage: Reltio API error message
  - errorCode: Reltio API error code
  - innerErrorData: Reltio API inner error data
warning: returned if the operation is completed with some minor issues
status: result of the operation; possible values are "OK" or "failed"

Request

Sample Request JSON:

{
  "assignee": "adminqa",
  "processTypes": ["dataChangeRequestReview"],
  "createdBy": "adminqa",
  "priorityClass": "Medium",
  "taskType": "dcrInternalReview",
  "completedAfter": 1507034164953,
  "completedBefore": 1507034164955,
  "completedBy": "adminqa", 
  "offset": 0,
  "max": 1
}

Response

{
  "status": "OK",
  "data": [
    {
      "assignee": "user1",
      "processInstanceId": "23164186",
      "processType": "dataChangeRequestReview",
      "objectURIs": [
        "changeRequests/AeFAoBPn",
        "entities/16lJbKKs"
      ],
      "createdBy": "user2",
      "priorityClass": "Low",
      "taskType": "dcrReview",
      "createTime": 1606292473723,
      "dueDate": 1606465273724,
      "taskId": "23164197",
      "displayName": "DCR Review",
      "processDefinitionDisplayName": "Data Change Request Review",
      "possibleActions": [
        {
          "action": "Approve",
          "label": "Approve"
        },
        {
          "action": "Reject",
          "label": "Reject"
        }
      ],
      "priority": 1,
      "preferredAction": {
        "action": "Approve",
        "label": "Approve"
      },
      "repeatingTask": false,
      "isOpen": false,
      "completedAction": {
        "action": "Approve",
        "label": "Approve"
      },
      "completeTime": 1607002013680,
      "completedBy": "user1",
      "valid": true
    }
  ],
  "total": 1,
  "offset": 0,
  "size": 1
}

Accelerate the Value of Data

Retrieve tasks by filter

Request

Response

Footer