API Guide

Data service

Data service is a REST+GraphQL based microservice following the REST and GraphQL API specifications. A 3rd party application can implement these services to return any kind of real-time and historical data to be displayed on Dashboards and Wallboards. We do not expect the data service to implement any sort of authentication on REST and/or GraphQL APIs for now.

REST APIs

Each data service must support the following endpoints with the following data:

1. Get available attributes

GET /service-name/attribute

Responses

HTTP Code	Description	Schema
200	List of attributes and filters will be returned on success response.	dataContract

Example HTTP request

Request path

/agent-service/attribute

Example HTTP response

Response 200

{
  "attributes" : [{"name": "aht", description: "Average handling time", "group": "voice", "dataType": "FLOAT", historical: true}], 
"filterAttributes" : ["team", "skillGroup"], 
"multipleFilters" : true 
}

2. Get filter values

GET /service-name/<name-of-filter>

Responses

HTTP Code	Description	Schema
200	List of the values of the given filter	<filterValues> array

Example HTTP request

Request path

/agent-service/team

Example HTTP response

Response 200

[{
  "id" : 1
  "name" : "team1"
},
{
  "id" : 2
  "name" : "team2"
}]

3. Get Service Status

GET /service-name/status

Responses

HTTP Code	Description	Schema
200	Service is up and running	string

Example HTTP request

Request path

/agent-service/status

Example HTTP response

Response 200

{"status": "ok"}

Schema

dataContract

Name

Description

Schema

attributes

List of all the attributes that the data service exposes.

Example : [{"name": "currentState", description: "Current state of the Agent", "group": "voice", "dataType": "FLOAT", historical: true}]

<attribute> array

filterAttributes

List of all the filter attributes. The filterValue API will use these names to create the URL path for getting the filter values.

Example : ["team", "skillGroup"]

< string > array

multipleFilters

Should be true if data service supports multiple filter selection.

Example : true

boolean

attribute

Name	Description	Schema
name	Name of the attribute Example : "aht"	string
description	Description of the attribute Example : "Some description"	string
group	Optional – Group of the attribute Example : "voice"	string
dataType	Must be one of the `STRING`, `INT`, `FLOAT,` `BOOL or PERCENT` for corresponding data types of the attribute.	string
historical	Whether this attribute has historical data available or not. Example : true	boolean

filterValues

Name

Description

Schema

name

Name of the attribute

Example : "team1"

string

id

Integer ID of the object. This value will be given in the arguments of the queries where filter values are required. See below for details.

Example : "1"

string

GraphQL schema

Every data service will have to expose the following GraphQL queries. Description of the schema is as follows:

Queries

Real-time data

This query will return a list of given attributes and optionally filter the list based on the provided arguments. Following input arguments must be supported:

filterAttributes: A list of attributes on which the data will be filtered. This list would contain the names of the attributes
filterValues: An array of arrays corresponding to the filter values. The array at first index will have values of the first filter and so on.

Sample Query:

getRealTimeData (filterAttributes: {val:["team", “skillGroup”]}, 
                 filterValues: {val: [[1, 2, 3], [4, 5, 6]]}) 
{
    agentName
    AHT
    answeredEmails
    ...
}

Result:

[{
    agentName: “SomeAgent”
    AHT: “20”,
    answeredEmails: “50”,
    ...
},
{
    agentName: “SomeOtherAgent”
    AHT: “30”,
    answeredEmails: “60”,
    ...
}]

Aggregated real-time data

Each data service should support SUM and AVERAGE data aggregation of any numerical attribute and Row Count of any numerical/non-numerical attributes.

SUM: Sum aggregation will give the sum of the given attribute’s values across all the rows.
AVERAGE: Average aggregation will give the average of the given attribute’s values across all the rows.
COUNT: Count will return the row count of the number of lines which have the same value for the given attribute.

Following input parameters must be supported:

aggregateType: Must be one of the “SUM”, “AVERAGE” or “COUNT”. This aggregation type will be used to aggregate all the selected attribute/s
attributes: List of selected attributes
filterAttributes: A list of attributes on which the data will be filtered. This list would contain the names of the attributes
filterValues: An array of arrays corresponding to the filter values. The array at first index will have values of the first filter and so on.

Sample Query:

getAggregatedData (aggregateType: "count", 
                   attributes: {val: ["currentState"]},
                   filterAttributes: {val:["team", "skillGroup"]}, 
                   filterValues: {val: [[1, 2, 3], [4, 5, 6]]})
{
    name
    value
}

Result:

[{
    name: “Ready”,
    value: “20”
},
{
    name: “Not ready”,
    value: “5”
}]

Historical data

This query will give historical stats of the given attribute/s. It should support the following input arguments:

resolution: Will take one of the values from “hourly” and “daily”. Hourly stats will give hour-wise cumulative stats of the selected attribute/s for last 24 hours; daily stats will accumulate all the stats day-wise for last 7 days.
aggregateType: Must be one of the “SUM”, “AVERAGE” or “COUNT”. This aggregation type will be used to aggregate all the selected attribute/s
attributes: List of selected attributes
comparison: This boolean flag would be true for comparison of the same attribute over this and the last week and would be false for comparison of different attributes over the same time period. The time period will depend on the value of resolution.
filterAttributes: A list of attributes on which the data will be filtered. This list would contain the names of the attributes
filterValues: An array of arrays corresponding to the filter values. The array at first index will have values of the first filter and so on.
chartType: Its value is either "Line Chart" or "Bar Chart". if no value is provided (i.e: empty string) then it sends Line Chart by default.

Line Chart Query (Historical)

Sample Query:

getHistoricalData (resolution: "hourly",
                   aggregateType: "count", 
                   attributes: {val: ["callsAbandoned"]},
                   comparison: "true",
                   filterAttributes: {val:["team", "skillGroup"]}, 
                   filterValues: {val: [[1, 2, 3], [4, 5, 6]],chartType:"Line Chart"})
{
    name
    series
}

Result:

[
  {
    name: "Ready"
    series: [

      {
        "value": 20,
        "name": "2016-09-17T12:47:17.425Z"
      },
      {
        "value": 30,
        "name": "2016-09-19T17:07:51.824Z"
      },
      {
        "value": 22,
        "name": "2016-09-20T10:30:15.408Z"
      },
      {
        "value": 25,
        "name": "2016-09-13T10:41:32.861Z"
      },
      {
        "value": 28,
        "name": "2016-09-21T18:23:16.441Z"
      }],
  },
  { 
    name: "Not Ready"
    series: [

      {
        "value": 5,
        "name": "2016-09-17T12:47:17.425Z"
      },
      {
        "value": 10,
        "name": "2016-09-19T17:07:51.824Z"
      },
      {
        "value": 15,
        "name": "2016-09-20T10:30:15.408Z"
      },
      {
        "value": 10,
        "name": "2016-09-13T10:41:32.861Z"
      },
      {
        "value": 8,
        "name": "2016-09-21T18:23:16.441Z"
      }]
  }
]

Bar Chart Query (Historical)

Bar Chart also support the same input arguments as of line chart, only its output response is different. The sample query and expected result of bar chart query is as follow:

Sample Query:

getHistoricalData (resolution: "hourly",
                   aggregateType: "count", 
                   attributes: {val: ["callsAbandoned","callsReceived","callsAnswered"]},
                   comparison: "true",
                   filterAttributes: {val:["queue","skillGroup"]}, 
                   filterValues: {val: [[1, 2, 3], [4, 5, 6]],chartType:"Bar Chart"})
{
    name
    series
}

Result when comparison is false (i.e comparison of multiple attributes in single week)
Result:

[
  {
    name: "Mon"
    series: [

      {
        "name": "Received",
        "value": 490
      },
      {
        "name": "Answered",
        "value": 490
      },
      {
        "name": "Abandoned",
        "value": 490
      }
    ]
  },
  {

    name: "Tue"
    series: [

      {
        "name": "Received",
        "value": 490
      },
      {
        "name": "Answered",
        "value": 321
      },
      {
        "name": "Abandoned",
        "value": 700
      }
    ]

 },
 {

    name: "Wed"
    series: [

      {
        "name": "Received",
        "value": 490
      },
      {
        "name": "Answered",
        "value": 570
      },
      {
        "name": "Abandoned",
        "value": 220
      }
    ]

}
]

Result when comparison is true (i.e comparison of same attribute for this and previous week)
Result:

[
  {
    name: "Mon"
    series: [

      {
        "name": "This week",
        "value": 490
      },
      {
        "name": "Previous Week",
        "value": 490
      }
    ]
  },
  {

    name: "Tue"
    series: [

      {
        "name": "This Week",
        "value": 490
      },
      {
        "name": "Previous Week",
        "value": 321
      }
    ]

}
]