Skip to main content

Device & Room Insights

Background

The charts query enables you to extract Device and Room Utilization Data & Insights from Poly Lens. This query gives you the ability to dig into the data at various levels of granularity to make informed decisions about your collaboration spaces and infrastructure. This query is incredibly flexible as it uses the same arguments and fields regardless of what you're targeting. This means you'll pass specific values to pull back Insights data for your use case and can expect the response structure to remain consistent. We'll break down the data structure and fields below and then provide example queries to help you test and explore the possibilities.

Arguments

The charts query contains the following required arguments. Values passed in are case-sensitive.

ArgumentDescriptionType
tenantIdUnique identifier of your Poly Lens TenantString!
idUnique identifier of the component you're analyzing. For example, a siteId, roomId, or deviceId. Must align with the locationScope's value (granularity level)ID!
locationScopeDefines the query scope (granularity level). Most commonly used: DEVICE, ROOM, SITE, TENANT. Also available, but less commonly used, VERSION, MODEL, MODEL_VERSION, DEVICE_TYPE, FAMILY, and ROOM_MEETINGEnum!
timeScopeSpecifies the time interval to analyze. Available values: DAY, WEEK, MONTH, QUARTER, YEAREnum!
timeStartThe start time of the analyzation interval. Must align with the start of the timeScope in ISO 8601 standardScalar!
topicThe Insight Topic (value) you're analyzing. Must align with the locationScope's available topicsID!

When using the charts query, the id, locationScope, and topic must align with each other. For example, if you're targeting a device's Insights, id = deviceId, locationScope = DEVICE, topic = available Device Insights topic.

Fields

There are three charts fields you can utilize to return specific data sets: invocationId, meta and series.

InvocationId Field

This serves as a trace ID for debugging queries and can be valuable in troubleshooting potential issues.

{
"data": {
"charts": {
"invocationId": "a2267878-t9a3-6eb7-89ff-a49vfe8pl24w"
}
}
}

Meta Fields

Meta Fields provide metadata for the specific chart you're querying. While there are three possible types, the InsightChartMeta array provides the most prevalent metadata for most charts queries. Within the InsightChartMeta type you have access to:

FieldDescriptionType
aggTypeIndicates the aggregation type used for the chart - AVERAGE, COUNT, PERCENTAGE, TOTALEnum!
childCountRepresents the number of entities, such as devices or rooms, that have contributed to a specific topic.Float!
incrementSpecifies the time interval used to retrieve data - HOUR, DAY, WEEK, MONTH, YEAREnum!
otherCountRepresents the number of additional entities, such as devices or rooms, that have contributed to a specific topic beyond the top 3, or 0 if the count is 3 or lessFloat!
timeScopeThe temporal range for which the data is expected - DAY, WEEK, MONTH, QUARTER, YEAREnum!
topicSpecifies the topic or value the chart represents (the value passed into the query topic argument)String!

When you add meta fields to your query you'll notice three ellipses inside the meta object. This syntax is similar to the JavaScript spread operator and tells GraphQL to assign the fields from the fragment to the current selection set. This convention is one of the benefits of GraphQL's relational structure - it allows us to pull specific metadata into the chart for the id we're targeting.

meta {
... on InsightSeriesMeta {
locationScope
object {
... on Device {
name
id
}
}
}
}

Series Fields

The series fields contain data, meta, and name fields. The data array is what you'll leverage to build a chart or table.

When used in a query, the data response object returns an array of objects (a point in the series) you can use to plot the data. Each object (point) is based on the timeScope and timeStart. This structure provides flexibility in utilizing the data in a UI chart, table, or other ways relevant to your use case. The example below shows a single object (point) within the series data array for a room charts query with a timeScope of "YEAR" and timeStart of "2023-01-01T00:00:00.000Z"


"data": {
"charts": {
"series": [
{
"name": "Room 12a3bc4d-56ef-78gh-9102-ij3kl4lm67891",
"data": [
{
"count": 5360.85882761,
"total": 2884,
"x": "2023-01-01T00:00:00.000Z",
"y": 1.85882761,
"z": null
}
]
}
]
}
}

The series meta field allows you to target specific fields on the chartsId object without running a subsequent query. I.E., name, id, location etc. This data is useful when building UIs focused on charts data.

{
"data": {
"charts": {
"__typename": "Chart",
"series": [
{
"data": [
{
"x": "2023-05-28T00:00:00.000Z",
"y": 1.00166003,
"z": null,
"count": 18102,
"total": 18072
}
],
"meta": {
"locationScope": "ROOM",
"object": {
"name": "Small Room - Studio x30",
"capacity": 3
}
}
}
]
}
}
}

To give you a visual example, this is how we display the series data in a chart in the Poly Lens Portal.

Poly Lens Portal Charts UI Example

Device Insights

Device Insights provide data for Device Adoption and Health Insights. When using the charts query to target device data, change locationScope to DEVICE, chartsId to the deviceId, and topic to the Insight Topic (value) you're targeting. Reference the tables below for available Device Insights Topics.

Device Adoption

InsightDescriptionTopic (value)
Call UseThe average time the device was in calls each dayCall Usage
Devices UsedPercent of days this device made at least one callDevices Used
Devices UnusedPercent of days the device was online but made no callsDevices unused

Device Health

InsightDescriptionTopic (value)
Devices OfflinePercent of days the device experienced an offline stateOffline devices
Devices Out-of-servicePercent of days the device was continuously offlineDevices out of service

Charts Query - Device's Call Use

We'll walk through an example query for a common use case - targeting the average time a device was in calls. In this example, we'll target the timeScope of "WEEK".

Test this query in the GraphQL Playground

query deviceCharts(
$tenantId: [String!]!
$chartsId: ID!
$locationScope: LocationScope!
$timeScope: TimeScope!
$timeStart: Date!
$topic: ID!
) {
charts(
tenantId: $tenantId
id: $chartsId
locationScope: $locationScope
timeScope: $timeScope
timeStart: $timeStart
topic: $topic
) {
series {
name
data {
count
total
x
y
z
}
}
meta {
... on InsightChartMeta {
topic
aggType
timeScope
increment
childCount
otherCount
}
}
}
}

Variables

{
"tenantId": "695xxx-bxxx-4xxx-axxx-1xxxxx", //tenantId
"chartsId": "00xxxxxxxad4", //Studio x50 device ID
"locationScope": "DEVICE", //level at which data is queried. set to "DEVICE" for this room charts query
"timeScope": "WEEK", //time range for which data is expected
"timeStart": "2023-01-22T00:00:00.000Z", //needs to align with the timeScope you define. Since we've chosen "YEAR" above, our "timeStart" is the first day of the Year
"topic": "Call Usage" //Value is case-sensitive
}

Response

{
"data": {
"charts": {
"series": [
{
"name": "Device 00e0db506ad4",
"data": [
{
"count": 0,
"total": null,
"x": "2023-01-22T00:00:00.000Z",
"y": 0,
"z": null
},
{
"count": 106,
"total": null,
"x": "2023-01-23T00:00:00.000Z",
"y": 106,
"z": null
},
{
"count": 0,
"total": null,
"x": "2023-01-24T00:00:00.000Z",
"y": 0,
"z": null
},
{
"count": 74,
"total": null,
"x": "2023-01-25T00:00:00.000Z",
"y": 74,
"z": null
},
{
"count": 23,
"total": null,
"x": "2023-01-26T00:00:00.000Z",
"y": 23,
"z": null
},
{
"count": 38,
"total": null,
"x": "2023-01-27T00:00:00.000Z",
"y": 38,
"z": null
},
{
"count": 0,
"total": null,
"x": "2023-01-28T00:00:00.000Z",
"y": 0,
"z": null
}
],
"meta": {
"locationScope": "DEVICE",
"object": {
"name": "DFR Studio x50",
"id": "00e0db506ad4"
}
}
}
],
"meta": {
"topic": "Call Usage",
"aggType": "COUNT",
"timeScope": "WEEK",
"increment": "DAY",
"childCount": 0,
"otherCount": 0
}
}
}
}

In the example response above, you'll notice the response returned a data object with an array of seven objects (a point in the series) - one for each day of the week. Within each object, count and y represent the total number of minutes the device was in a call and x represents the date. The meta object returned shows us the specific values for this chart query.

Room Insights

Room Insights provide data for Room Utilization or Meeting Behavior. When using the charts query to target room data, change locationScope to ROOM, chartsId to the roomId, and topic to the value of the Insights Topic you're targeting. Reference the tables below for available Room Insights Topics.

Room Utilization

InsightDescriptionTopic (value)
Room OccupancyThe average number of people in the room when occupiedAverage meeting size
Room UseThe average time the room was used each dayRoom usage

Meeting Behaviors

InsightDescriptionTopic (value)
Room Scheduled, but UnusedRoom was scheduled for a meeting but was not used.Rooms scheduled but not used
Room Scheduled in a Series, but UnusedRoom is scheduled for recurring meetings but was not usedRecurring meetings with no participants
Meetings That Were UnscheduledRoom was used for an unscheduled meetingUnscheduled room usage
Meetings That Ran LongRoom was used for a meeting that ran longer than plannedMeetings that run long
Meetings That Started LateRoom was used for a meeting that started lateMeetings that start late

The use of Meeting Behaviors Topics requires O365 Calendar integration for the room. Without this integration, the query will return a null response object.

Charts Query - Average meeting size

Let's walk through a common use case for a room charts query - targeting "people count" in the room. We'll use the Average meeting size topic value and the timeScope of "WEEK" to target this data.

Test this query in the GraphQL Playground

query roomCharts(
$tenantId: [String!]!
$chartsId: ID!
$locationScope: LocationScope!
$timeScope: TimeScope!
$timeStart: Date!
$topic: ID!
) {
charts(
tenantId: $tenantId
id: $chartsId
locationScope: $locationScope
timeScope: $timeScope
timeStart: $timeStart
topic: $topic
) {
__typename
series {
data {
x
y
z
count
total
}
meta {
... on InsightSeriesMeta {
locationScope
object {
... on Room {
name
}
}
}
}
}
meta {
... on InsightChartMeta {
topic
aggType
timeScope
increment
childCount
otherCount
}
}
}
}

Variables

{
"tenantId": "12xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxc89", //tenantId
"chartsId": "68xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx503", //roomId - the unique identifier of location scope
"locationScope": "ROOM", //level at which data is queried. set to "ROOM" for this room charts query
"timeScope": "YEAR", //time range for which data is expected
"timeStart": "2023-01-01T00:00:00.000Z", //starting point for data retrieval. should match the start of the `timeScope`
"topic": "Offline devices" //metric to analyze. topic value available for chart type
}

Response

{
"data": {
"charts": {
"__typename": "Chart",
"series": [
{
"data": [
{
"x": "2023-05-28T00:00:00.000Z",
"y": 1.00166003,
"z": null,
"count": 18102,
"total": 18072
},
{
"x": "2023-05-29T00:00:00.000Z",
"y": 1.00134607,
"z": null,
"count": 46122,
"total": 46060
},
{
"x": "2023-05-30T00:00:00.000Z",
"y": 1.44985817,
"z": null,
"count": 78201,
"total": 53937
},
{
"x": "2023-05-31T00:00:00.000Z",
"y": 1.45103225,
"z": null,
"count": 70777,
"total": 48777
},
{
"x": "2023-06-01T00:00:00.000Z",
"y": 1.33629163,
"z": null,
"count": 68660,
"total": 51381
},
{
"x": "2023-06-02T00:00:00.000Z",
"y": 1.34407777,
"z": null,
"count": 72861.11187839,
"total": 54209
},
{
"x": "2023-06-03T00:00:00.000Z",
"y": 1.02478134,
"z": null,
"count": 2109,
"total": 2058
}
],
"meta": {
"locationScope": "ROOM",
"object": {
"name": "Small Room - Studio x30"
}
}
}
],
"meta": {
"topic": "Average meeting size",
"aggType": "AVERAGE",
"timeScope": "WEEK",
"increment": "DAY",
"childCount": 0,
"otherCount": 0
}
}
}
}

You'll notice the response returned a data object with an array of seven objects (a point in the series) - one for each day of the week. Within each object:

  • x is the date
  • y is the average (count/total)
  • z will remain null in most cases (small people count number and/or for a future timeframe)
  • count is the total number of people-seconds within the timeframe
  • total is the number of meeting-seconds within the timeframe

The series meta object shows us the specific values for this chart and allows us to target specific fields on the object, like the name.

The other meta object returned shows us the specific values for this chart query.


The queries above are just a small subset of the power of the Device and Room Insights APIs. We'll be updating this article with more examples over time. Please reach out if you have specific content requests or questions.