Fetch paginated list of tasks

Method

Up to 9.0.012

GET

From 9.0.013

POST

Important

The new request has exactly the same parameters as the old one and allows you to pass the ql_expression in the request body in JSON format.

Syntax

Up to 9.0.012

GET /gtl/tasks/<solution_dbid>/<page>?entity_dbid=<dbid>&entity_type=department/process/capturePoint/solution>&filter=<filter_name>&order_by=qualified_attribute_name>&order_direction=<ascending/descending>&snapshot_id=snapshot_id>&release_snapshot=<snapshot_id>

From 9.0.013

POST /gtl/tasks/<solution_dbid>/<page>/search?entity_dbid=<dbid>&entity_type=department/process/capturePoint/solution>&filter=<filter_name>&order_by=qualified_attribute_name>&order_direction=<ascending/descending>&snapshot_id=snapshot_id>&release_snapshot=<snapshot_id>

Request Body

The Request body should contain a valid JSON data with array of <ql_items>.

[<ql_item>, <ql_item>, ...]

<ql_item> is a JSON object with the following fields:

Key	Is Mandatory	Comment
attribute	-	Database column name.
operator	+	"LIKE", "IN", "=", ">", "<", ">=", "<=", "OR", "AND", "(", ")"
value	-	String, array of strings or numbers.

Important

1. Any string or date value must be wrapped in single quotes.
2. Operators are case insensitive.
3. Date format is "YYYY-MM-DDTHH:mm:ssZ", for example: 2020-06-18T14:10:12Z

Here is a JSON example of query "Queue IN ( 'iWD_Rejected' , 'iWD_Canceled' ) and 'Business Value' in ( 1, 2, 3) and 'Completed Date' <= 2020-06-16" :

[
    {
        "operator": "IN",
        "value": [
            "'iWD_Rejected'",
            "'iWD_Canceled'"
        ],
        "attribute": "queue"
    },
    {
        "operator": "AND"
    },
    {
        "operator": "IN",
        "value": [
            1,
            2,
            3
        ],
        "attribute": "IWD_businessValue"
    },
    {
        "operator": "AND"
    },
    {
        "operator": "<=",
        "value": "'2020-06-16T23:59:59Z'",
        "attribute": "completed_at"
    }
]

Parameters

Parameter Name	Description	Default Value
entity_dbid	DBID of solution, department, process or capture point	The same value as solution_dbid in the path)
entity_type	solution, department, process or capturePoint; if solution then entity_dbid must be the same as solution_dbid in the path	solution
filter	Filter name	-
order_by	Qualified attribute name used to sort the results (qualified attribute name is a name with core/ext/data prefix and a dot delimiter)	core.createdDateTime
order_direction	ascending or descending	descending
Custom Filter Query
core.{any core task attribute}	attribute value	-
ext.{any extended task attribute}	attribute value	-
data.{any custom task attribute}	attribute value	-
any_id	A value of id or captureId	-
Snapshot Management
snapshot_id	Reuse a previously taken snapshot (Interaction Server's query result) if still valid. Create a new snapshot otherwise.	-
release_snapshot	If present, a new snapshot in Interaction Server is requested. The snapshot with ID given in this parameter is released.	-

• snapshot_id and release_snapshot are optional and mutually exclusive.
• entity_dbid and entity_type must be both present or both omitted.

Response Body

{
  "page": <page number>,
  "tasks_per_page": <number of tasks per page>,
  "total_tasks": <number of tasks>,
  "snapshot_id": "<snapshot ID>",
  "columns":
  [
    {
      "name": "<column name>",
      "label": "<localized column label>",
      "type": "<string/date/int/img>",
      "sortable": <true/false>,
      "sorted": <ascending/descending>,
      "category": "<core/ext/data>"
    },
    ...
  ],
  "tasks":
  [
    {
      "core":
      {
        <attribute definitions>
      },
      "ext":
      {
        <attribute definitions>
      },
      "data":
      {
        <attribute definitions>
      }
    },
    ...
  ]
}

Attribute Definitions

"<attribute name>":
{
  "value": <attribute value>,
  "display_value": <value_to_display>,
  "tooltip": "<tooltip>"
},
...

• Returned tasks contain only attributes selected by the filter plus task ID, which is always present, regardless of whether it is selected by the filter or not.
• "snapshot_id" is not the same as the Interaction Server's snapshot ID. In order to be unique across the application, "snapshot_id" is combined from a connection ID and Interaction Server's snapshot ID.
• If a selected attribute is not set for a task, it is omitted in the returned record.
• If the attribute type is "img", the value is a URL of the image. The URL is relative to the host base address, i.e. it contains the whole path, including the path to the application and the api prefix. For example: "value": "/iwd_manager/api/gtl/icons/102/workitem". Currently there is only one attribute of this type - mediaIcon. "tooltip" for this attribute contains the associated media type.
• The list of tasks may be empty. Pages are numbered starting from 1.
• At most one column is expected to contain the field "sorted".
• "tooltip" and "display_value" are present only if different to the value. "display_value" is currently used only for channel.

HTTP Status Codes

• 404 Not Found—Solution, department, process, capture point or filter does not exist. Page number is 0 (zero) or negative
• Up to release 9.0.012: 302 Found—Requested page is out of range. Location header contains a URL of the last valid page

  From release 9.0.013: 307 Temporary Redirect

• 400 Bad Request—One of the following:

  Wrong value of order_direction

  Both release_snapshot and snapshot_id are present in the request

  The snapshot identified by snapshot_id was taken with different query parameters (solution DBID, filter, order etc.) from those used for the current request

  Any other request error

• 403 Forbidden—The snapshot identified by release_snapshot does not belong to the current user session