a!queryProcessAnalytics() Function

Executes process reports and returns the resulting data.

See also: Process Reports.

Syntax

a!queryprocessanalytics( report, query, contextgroups, contextprocessids, contextprocessmodels, contextusers )

  • report (Document): .arf document containing the report configuration.
  • query (Query): An optional query object containing paging and extra filters, created with a!query(). If no query is provided, the default paging from the report is used.
  • contextGroups (Group Array): One or more groups to pass to the report context.
  • contextProcessIds (Integer Array): One or more process ids to pass to the report context.
  • contextProcessModels (Process Model Array): One or more process models to pass to the report context.
  • contextUsers (User Array): One or more users to pass to the report context.

Returns

PortalReportDataSubset

Notes

The portalreportdatasubset object returned by this function contains both the unformatted result data and the process report's display configuration. The fields are as follows:

  • name (Text): Configured name of the process report.
  • description (Text): Configured description of the process report.
  • startIndex (Integer): Index of the first returned result.
  • batchSize (Integer): Number of items requested.
  • sort (SortInfo Array): Sort configurations used.
  • totalCount (Integer): Number of total results.
  • columnConfigs (Dictionary Array): Array of dictionaries, one for each column in the returned data. See the Examples section below for an example of the array. Each dictionary has the following fields:
    • label (Text): Column name configured in the process report.
    • field (Text): Unique column identifier used to access the column's data from row Dictionaries and to specify a column in a SortInfo configuration.
    • drilldownField (Text): Unique column drilldown identifier used to access the column's drilldown value from row Dictionaries.
    • configuredFormatting (Text): Formatting configured in the process report. This formatting can be interpreted or ignored as the designer chooses.
    • configuredDrilldown (Text): Drilldown configured in the process report. The drilldown type can be interpreted or ignored as the designer chooses.
  • data (Dictionary Array): Array of dictionaries, one for each returned row, containing the unformatted results of the report's column and drilldown expressions for that row. Use the columnConfigs.field and columnConfigs.drilldownField to get the keys to each column's data. See the Examples section below for an example of this format.
  • identifiers (Any Type): Array of unique row identifiers.
  • errorMessage (Text): The error message encountered executing the report, or null if no error occurred.

When a query is passed, the query's pagingInfo overrides the report's configured sorting and paging. The first valid SortInfo object in the query paging field is used to sort the results; other SortInfo objects are ignored.

If the passed query object has a filter or logical expression, these are applied in addition to the filters configured on the process report. Columns cannot be selected or aggregated via the query parameter but can be configured in the process report.

If any of the context parameters are populated with objects, those objects are provided to the report as its context. At most one context parameter type may be used

contextProcessModels should be given using one or more constants of type Process Model.

If no users are passed to contextUsers and the report expects a user context, the report is provided the context of the user evaluating the expression. If contextUsers is populated, only that user or user array is used for the report context.

The user executing the function must be able to see the report configuration file. The report is executed using the same user security context that is running the expression.

Sorting on hidden columns is supported even though they are not returned.

If called multiple times in the same expression with the same parameters, only one query is made to the data store when the expression is evaluated and the result is reused for each identical call. This caching only applies within a single expression evaluation. Return values are not cached in separate expressions, or in separate evaluations of the same expression.

Examples

Note: Since constants are specific to each system, these examples will not evaluate in your test rules interface. Use them only as a reference.

Example 1

Get the first page of the All Processes report by querying that report without providing any supplemental query configuration:

1
=a!queryprocessanalytics(report: cons!all_processes)

The following expression creates a Dictionary array that is equivalent to the returned columnConfigs for the All Processes report:

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
33
34
35
36
37
38
39
40
41
42
43
44
{
  {
    label: "Name",
    field: "c0",
    drilldownField: "dp0",
    configuredFormatting: "NORMAL_TEXT",
    configuredDrilldown: "PROCESS_DASHBOARD"
  },
  {
    label: "Priority",
    field: "c7",
    drilldownField: "dp7",
    configuredFormatting: "PRIORITY",
    configuredDrilldown: ""
  },
  {
    label: "Status",
    field: "c8",
    drilldownField: "dp8",
    configuredFormatting: "PROCESS_STATUS_ICON",
    configuredDrilldown: ""
  },
  {
    label: "Started by",
    field: "c1",
    drilldownField: "dp1",
    configuredFormatting: "USER_NAME",
    configuredDrilldown: ""
  },
  {
    label: "Start Time",
    field: "c2",
    drilldownField: "dp2",
    configuredFormatting: "DATE_TIME",
    configuredDrilldown: ""
  },
  {
    label: "Active Tasks",
    field: "c9",
    drilldownField: "dp9",
    configuredFormatting: "NUMBER",
    configuredDrilldown: ""
  }
}

The following expression creates a Dictionary array that is equivalent to two example data rows for the All Processes report:

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
{
  {
    c1: fn!touser("initiating.user"),
    c2: fn!datetime(2014, 12, 15, 6, 3, 8, 690),
    c0: "Example Process #1",
    c9: 0,
    c8: 0,
    c7: 1,
    dp0: 268435502,
    dp7: null,
    dp8: null,
    dp1: null,
    dp2: null,
    dp9: null
  },
  {
    c1: fn!touser("intiating.user2"),
    c2: fn!datetime(2014, 12, 15, 6, 2, 49, 960),
    c0: "Example Process #2",
    c9: 0,
    c8: 0,
    c7: 1,
    dp0: 268435497,
    dp7: null,
    dp8: null,
    dp1: null,
    dp2: null,
    dp9: null
  }
}

Get the first page of the All Processes report, but override the default batch size of 25 with the larger value of 50 by passing a query with a paging configuration:

1
2
3
4
5
6
7
8
9
=a!queryProcessAnalytics(
  report: cons!ALL_PROCESSES,
  query: a!query(
    pagingInfo: a!pagingInfo(
      startIndex: 1,
      batchSize: 50
    )
  )
)

Example 2

Get the processes for a process model by passing a process model to the context:

1
2
3
4
a!queryProcessAnalytics(
  report: cons!PROCESSES_FOR_PM,
  contextProcessModels: cons!PURCHASE_REQUEST
)

Example 3

Get the tasks assigned to a specific user by passing a username to the context:

1
a!queryProcessAnalytics(report: cons!MY_TASKS, contextUsers: "user.name")

Example 4

Get the expense approval tasks from a given region, greater than a given amount, and assigned to users in a given group by passing a group as context and a query with a logical expression:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
a!queryProcessAnalytics(
  report: cons!OPEN_REIMBURSEMENT_REQUESTS,
  groupContext: cons!EXPENSE_APPROVERS,
  query: a!query(
    pagingInfo: a!pagingInfo(startIndex: 1, batchSize: 20),
    logicalExpression: a!queryLogicalExpression(
      operator: "AND",
      filters: {
        a!queryFilter(field: "c2", operator: "includes", value: "East"),
        a!queryFilter(field: "c4", operator: ">", value: 10000)
      }
    )
  )
)

See Also

Interface Recipe: Display a User's Tasks in a Grid With Task Links: Renders a task report with a!queryProcessAnalytics()

Interface Recipe: Display Processes by Process Model with Status Icons: Shows process information with a!queryProcessAnalytics()

Process Reports: Create and configure process reports to pass to a!queryProcessAnalytics().

Query: The Query data type defines any paging and extra filters to apply when querying data.

FEEDBACK