User Status Aggregate query

User Status Aggregate queries show a high-level summary of user activity. The query data reflects the user's Genesys Cloud presence as well as their ACD routing status.

Before diving too deep into the numbers, take a moment to make yourself familiar with the subtleties and distinctions between primary and secondary presence as well as ACD routing status.

A user aggregate query summarizes overall user activity during a given interval. This is where you get a higher-level view of one or more users and not the individual punch-in/punch-out style details.

The syntax of this query conforms to the general template for aggregate queries.

The user aggregate query displays multiple status metrics, including:

• Genesys Cloud "primary" presence (tSystemPresence) - A user's Genesys Cloud status (such as available or busy).
• User-defined "secondary" presence (tOrganizationPresence) - User-defined status settings, such as "lunch at desk" or "writing emails." In this example, both statuses map to the Genesys Cloud primary presence of available.
• Agent routing status (tAgentRoutingStatus) -The ACD routing status for an agent. These exist within the scope of ACD/queue-related work and have values such as interacting, idle, and not responding.

Note: The query response includes a dictionary that shows the mapping between organization and system presences as a convenience.

Note: As this query is about users (specifically status) and not conversations, metrics such as talk time and handle time do not apply here. If that is what you're looking for, please check out the conversation aggregate metric query.

Filtering and group-by is limited to the userId dimension only. A single query may contain no more than 100 userId predicates. To retrieve data for more than 100 users simply break it up into multiple queries. Metrics are limited to tSystemPresence, tOrganizationPresence, and tAgentRoutingStatus. Granularity must be evenly divisible by thirty minutes. The maximum allowed ratio of interval size to granularity is 1000. For example querying for 1 day of data with half hour granularity would produce 48 points of measurement. That's well within range as 48 < 1000. Querying 1 day of data with second level granularity would produce 86,400 points of measurement and is not allowed as 84,000 > 1000. Query predicates only support equality checks, such as

"predicates": [
      {
        "dimension": "userId",
        "operator: "equals",
        "value": "fc2b4fa6-e082-414b-9cb8-ff8a6fa1b666"
      }
    ]

Most types of metrics (such as conversation metrics) are point-in-time metrics. These count to the time bucket that they happened in, e.g. a call was answered at 9:15 with an answer duration of 2 minutes. User status metrics are different as they track the time in status for the user with analytics only storing complete statuses. This impacts results when there is no activity for a user within the query interval or there is only activity for part of the interval. We attempt to account for the full duration of the statuses in the query interval by looking beyond the interval. This is best illustrated by an example:

A user entered status ON_QUEUE at 9:59. A query is issued for the user's status from 10:00 to 10:30. There is no status change in the query interval. In this case, we cannot determine the result of the query by just looking at the query interval, we need to also expand to the next status change outside the interval:

• If the user's status changes again at 10:31, we'll have a metric with a duration of 32 minutes for the ON_QUEUE status, the result of the query is then the fraction of that status that falls into the query interval (30 minutes).
• If the user's status does not change again (i.e. the user is still in the ON_QUEUE status), we don't have any information stored that allows us to accurately determine the duration in status (because we only store complete metrics). In this scenario, we will attempt to fill in the current user status based on data from external services that manage the current routing status and presence status.

This query is asking for all of the organization-defined/secondary presence and ACD routing status metrics for one user (whose ID is "fc2b4fa6-e082-414b-9cb8-ff8a6fa1b666") on November 1, 2015 partitioned into 12 hour sized buckets.

{
  "interval": "2015-11-01T00:00:00.000Z/2015-11-02T00:00:00.000Z",
  "granularity": "PT12H",
  "groupBy": [
    "userId"
  ],
  "metrics": [
    "tOrganizationPresence",
    "tAgentRoutingStatus"
  ],
  "filter": {
    "type": "or",
    "predicates": [
      {
        "dimension": "userId",
        "value": "fc2b4fa6-e082-414b-9cb8-ff8a6fa1b666"
      }
    ]
  }
}

The response to the above query includes a dictionary mapping primary-to-secondary presence so we know that a secondary presence with ID="e08eaf1b-ee47-4fa9-a231-1200e284798f" corresponds to a primary presence of "ON_QUEUE".

In addition, for a specific user, a list of metrics is returned for each interval queried for. Since the original query asked for a full day broken into 12 hour partitions, we see two intervals returned below. Within each, we see metrics about each acd routing status and organization (secondary) presence. Each of these metrics are composed of stats which show how many milliseconds were spent in that status.

{
  "systemToOrganizationMappings": {
    "ON_QUEUE": [
      "e08eaf1b-ee47-4fa9-a231-1200e284798f"
    ],
    "OFFLINE": [
      "ccf3c10a-aa2c-4845-8e8d-f59fa48c58e5"
    ],
    "AVAILABLE": [
      "6a3af858-942f-489d-9700-5f9bcdcdae9b"
    ]
  },
  "results": [
    {
      "group": {
        "userId": "fc2b4fa6-e082-414b-9cb8-ff8a6fa1b666"
      },
      "data": [
        {
          "interval": "2015-11-01T00:00:00.000Z/2015-11-01T12:00:00.000Z",
          "metrics": [
            {
              "metric": "tAgentRoutingStatus",
              "qualifier": "INTERACTING",
              "stats": {
                "sum": 54358
              }
            },
            {
              "metric": "tAgentRoutingStatus",
              "qualifier": "IDLE",
              "stats": {
                "sum": 230687
              }
            },
            {
              "metric": "tOrganizationPresence",
              "qualifier": "ccf3c10a-aa2c-4845-8e8d-f59fa48c58e5",
              "stats": {
                "sum": 42909373
              }
            },
            {
              "metric": "tOrganizationPresence",
              "qualifier": "e08eaf1b-ee47-4fa9-a231-1200e284798f",
              "stats": {
                "sum": 285094
              }
            },
            {
              "metric": "tOrganizationPresence",
              "qualifier": "6a3af858-942f-489d-9700-5f9bcdcdae9b",
              "stats": {
                "sum": 5533
              }
            }
          ]
        },
        {
          "interval": "2015-11-01T12:00:00.000Z/2015-11-02T00:00:00.000Z",
          "metrics": [
            {
              "metric": "tOrganizationPresence",
              "qualifier": "ccf3c10a-aa2c-4845-8e8d-f59fa48c58e5",
              "stats": {
                "sum": 43200000
              }
            }
          ]
        }
      ]
    }
  ]
}