Breadcrumbs

API Guide

/*<![CDATA[*/ div.rbtoc1769167609505 {padding: 0px;} div.rbtoc1769167609505 ul {list-style: disc;margin-left: 0px;} div.rbtoc1769167609505 li {margin-left: 0px;padding-left: 0px;} /*]]>*/ Data service REST APIs 1. Get available attributes Responses Example HTTP request Request path Example HTTP response Response 200 2. Get filter values Responses Example HTTP request Request path Example HTTP response Response 200 3. Get Service Status Responses Example HTTP request Request path Example HTTP response Response 200 Schema GraphQL schema Queries Real-time data Aggregated real-time data Historical data Line Chart Query (Historical) Bar Chart Query (Historical)


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.

API Guide | id (13.7)APIGuide 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

<API Guide | id (13.7)APIGuide 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}]

<API Guide | id (13.7)APIGuide 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:

  1. aggregateType: Must be one of the “SUM”, “AVERAGE” or “COUNT”. This aggregation type will be used to aggregate all the selected attribute/s

  2. attributes: List of selected attributes

  3. filterAttributes: A list of attributes on which the data will be filtered. This list would contain the names of the attributes 

  4. 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:

  1. 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.

  2. aggregateType: Must be one of the “SUM”, “AVERAGE” or “COUNT”. This aggregation type will be used to aggregate all the selected attribute/s

  3. attributes: List of selected attributes

  4. 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. 

  5. filterAttributes: A list of attributes on which the data will be filtered. This list would contain the names of the attributes 

  6. 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.

  7. 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 } ]

}]