a!queryTaskList() Function

Queries tasks from both standard and autoscaled processes, returning unified task data with filtering, sorting, and pagination support.

Parameters

a!queryTaskList( fields, filters, pagingInfo, fetchTotalCount, aggregation, contextGroups, contextUsers )

Returns

PortalReportDataSubset

The return value contains these fields:

• The success field (Boolean) indicates whether the query succeeded.
• The data field (List of Map) contains task data as a list of maps, or aggregated results when the aggregation parameter is specified.
• The startIndex field (Integer) contains the starting position in the result set.
• The batchSize field (Integer) contains the number of results requested.
• The sort field (List of SortInfo) contains the sort configuration applied to the result set.
• The totalCount field (Integer) contains the total number of tasks that match the query, or -1 when fetchTotalCount is false.
• The identifiers field (List of Integer) contains task identifiers in the result set. This list is empty for aggregated queries.
• The errorMessage field (Text) contains error information when the query fails, or null when the query succeeds.

Using the function

The following considerations apply to the a!queryTaskList() function.

Query tasks across process engines

The a!queryTaskList() function queries standard and autoscale processes in one operation. Each engine applies security, context, and filters before returning results. Appian combines the results into a single dataset, then applies sorting and pagination.

If you cannot view any matching tasks, the function returns an empty result with success set to true.

Configure paging and sorting

Use the pagingInfo parameter to configure pagination and sorting. Configure sorting only with the sort parameter of a!pagingInfo().

The paging limits are:

• The batchSize parameter accepts values from 1 through 5000.
• The startIndex parameter accepts values less than 10000.

The fetchTotalCount parameter defaults to false. When it is false, the totalCount field is -1.

Select and filter task fields

Use the fields parameter to select which task fields to return. When fields is null or empty, the query returns all standard task fields. You cannot specify fields and aggregation in the same query.

The following fields can be used with the fields parameter:

• taskId
• taskName
• status
• assignees
• priority
• dueDate
• createdOn
• acceptedOn
• completedOn
• processInstanceId
• processModelName
• processModelUuid
• owner

Use the filters parameter to provide one or more a!queryFilter() or a!queryLogicalExpression() values. Filter fields must be valid task field names, and each operator must be valid for the field's data type.

Filters are always applied after the contextGroups or contextUsers parameter, and you cannot filter on the owner field if either context parameter is included in the query.

Query tasks for users or groups

Use contextUsers to retrieve tasks for one or more users, including tasks assigned through group membership. Use contextGroups to retrieve tasks for one or more groups. Neither function returns completed tasks.

The contextUsers and contextGroups parameters are mutually exclusive. When neither parameter is specified, task filters do not expand group assignments to individual users.

Aggregate task data

Use the aggregation parameter to group task data and calculate metrics. Filters apply before aggregation. The parameter supports the "COUNT", "MIN", and "MAX" aggregation functions. The "MIN" and "MAX" functions apply to numeric and date fields.

Each aggregated row represents a group. Grouping fields without an alias use the field name as the key, and aggregation columns require an alias. To sort aggregated results, use a grouping field name or aggregation alias in pagingInfo.sort. Aggregated queries return an empty identifiers list.

Handle query failures

When querying for standard and autoscaled task data, a failed query for either process type results in a complete query failure (with success set to false). The function does not return a partial result set.

Examples

The following examples demonstrate the a!queryTaskList() function.

To experiment with examples, copy and paste the expression into an interface or expression rule object.

Get a user's open tasks

1
2
3
4
5
6
7
a!queryTaskList(
  pagingInfo: a!pagingInfo(
    startIndex: 1, 
    batchSize: 10
    ),
  contextUsers: loggedInUser()
)

Using the contextUsers parameter, the function queries only open tasks (assigned or accepted) for the specified user, as well as the tasks that are assigned to a group that the user is in.

Get a user's active tasks

1
2
3
4
5
6
7
8
9
10
11
12
a!queryTaskList(
  filters: a!queryFilter(
    field: "status",
    operator: "=",
    value: "Accepted"
  ),
  pagingInfo: a!pagingInfo(
    startIndex: 1,
    batchSize: 10
    ),
  contextUsers: loggedInUser()
)

To query only the tasks that the user has accepted, use a status filter in addition to setting contextUsers.

Get open tasks for a group

1
2
3
4
5
6
7
a!queryTaskList(
  pagingInfo: a!pagingInfo(
    startIndex: 1, 
    batchSize: 10
    ),
  contextGroups: cons!GROUP_CONSTANT
)

Using the contextGroups parameter, the function queries tasks that are assigned to the specified groups but have not been accepted yet. This allows you to see the tasks are assigned to a team that are still waiting to be picked up.

Get overdue tasks

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
a!queryTaskList(
  filters: a!queryLogicalExpression(
    operator: "AND",
    logicalExpressions: {
      a!queryLogicalExpression(
        operator: "OR",
        filters: {
          a!queryFilter(
            field: "status",
            operator: "=",
            value: "Assigned"
          ),
          a!queryFilter(
            field: "status",
            operator: "=",
            value: "Accepted"
          ),
        }
      )
    },
    filters: a!queryFilter(
      field: "dueDate",
      operator: "<",
      value: now()
    )
  ),
  pagingInfo: a!pagingInfo(
    startIndex: 1,
    batchSize: 10,
    sort: a!sortInfo(field: "dueDate", ascending: true)
  )
)

A combination of status filters returns the list of all outstanding tasks that weren't completed by their deadline.

Get outstanding tasks for a process model

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
a!queryTaskList(
  filters: a!queryLogicalExpression(
    operator: "AND",
    logicalExpressions: {
      a!queryLogicalExpression(
        operator: "OR",
        filters: {
          a!queryFilter(
            field: "status",
            operator: "=",
            value: "Assigned"
          ),
          a!queryFilter(
            field: "status",
            operator: "=",
            value: "Accepted"
          ),
        }
      )
    },
    filters: a!queryFilter(
      field: "processModelUuid",
      operator: "=",
      value: "0002d9d6-a691-8000-f92f-7f0000014e7a"
    )
  ),
  pagingInfo: a!pagingInfo(
    startIndex: 1, 
    batchSize: 10
  )
)

A combination of status filters and the process model ID returns the list of all outstanding tasks for a specified process model. If your process model only contains a single task node, this can be used to show you all outstanding tasks of a given type. Note that filtering by process model requires the process model UUID; you cannot use a constant to specify the model. The process model UUID can be found in Appian Designer by opening the object's properties.

Feature compatibility

Feedback