The statistic and alert APIs provide access to real-time analytics from the Interaction Center server. Both statistic and alert APIs consist of a catalog and corresponding values. The catalogs allow clients to retrieve the statistic/alert definitions defined and accessible to the session user. Statistic values and alert notifications provide real-time data associated with the definitions in their respective catalog.
Jump to a section that describes each area of the statistic and alert API:
The statistic catalog contains statistic categories, statistic definitions, and parameter type definitions. This metadata about the statistics available allows clients to build dynamic user interfaces which put the user in control of which statistics they want to see. As a convenience, the statistics catalog is fully documented in The Statistics Catalog, allowing for browsing of the available statistics.
The statistic catalog can amount to a large amount of data being transferred back to the client. Since the statistic catalog is unlikely to change, there is a caching mechanism clients are encouraged to use. After creating a subscription to the statistic catalog, the corresponding message will have a cache tag (the ellipses represents the rest of the statisticCatalogMessage.):
{
"__type":"urn:inin.com:statistics:statisticCatalogMessage",
"isDelta":false,
"statisticCatalogCacheTag":"fa597edd809a5c0513aaff1d06a34819",
...
}
Clients can use the statisticCatalogCacheTag member to avoid the large statistic catalog payload. In order to do so, a client must cache the data received in the statisticCatalogMessage in a way that it can retrieve it beyond a session. The next time the app requests the statistic catalog, it can check to see if it already has a cache, and if so send
PUT /icws/{sessionId}/messaging/subscriptions/statistics/statistic-catalog
{
"statisticCatalogCacheTag":"fa597edd809a5c0513aaff1d06a34819"
}
The response to the example request above will include a clientStateIsFresh member which indicates whether or not the client can use the cache or should discard it and expect a corresponding message.
{
"clientStateIsFresh":true
}
If the API response has "clientStateIsFresh":true, the client should not expect a corresponding statisticCatalogMessage.
In order to observe statistic values, a client must first form "statistic keys" to represent the wanted statistics. A statistic key consists of an identifier and set of parameter value items.
{
"statisticIdentifier":"inin.workgroup:AgentsLoggedIn",
"parameterValueItems":
[
{
"parameterTypeId":"ININ.People.WorkgroupStats:Workgroup",
"value":"Marketing"
}
]
}
The example above shows the identifier of "inin.workgroup:AgentsLoggedIn" (Number of logged on agents in this workgroup). The parameter value item consists of a parameter type ID and parameter value. AgentsLoggedIn is parameterized by workgroup, so this example shows a statistic key for agents logged on who are part of the "Marketing" workgroup.
In order to form a statistic key, clients must first retrieve the statistic catalog for accessible statistic and parameter type definitions. These definitions provide the statistic identifier and parameter type portions of a statistic key. For values of parameter types, clients use the statistic parameter value API.
For a statistic key to be valid, all of the parameter types for a statistic key must be used, and they must be presented in the same order they are given in the statistic catalog.
An example of a client forming a statistic key might look like this:
{
"statisticIdentifier":"inin.workgroup:AgentsLoggedIn",
"displayString":"Agents logged in on this workgroup",
"description":"Number of agents logged in on this workgroup.",
"unitsDisplayString":"",
"requiredParametersDefinitions":
[
{
"orderedParameterTypeList":
[
"ININ.People.WorkgroupStats:Workgroup"
],
"shouldBeSuppressed":false
}
],
"statisticDefinitionData":
{
"lowerBoundValue":
{
"__type":"urn:inin.com:statistics:statisticIntValue","value":0,
"statisticValueType":0
},
"upperBoundValue":
{
"__type":"urn:inin.com:statistics:statisticIntValue","value":9999,
"statisticValueType":0
},
"precision":0,
"units":0
},
"drillDowns":[],
"statisticDefinitionFlags":[]
}
POST /icws/{sessionID}/statistics/statistic-parameter-values/queries
{
"parameterTypeId":"ININ.People.WorkgroupStats:Workgroup"
}
{
"parameterValues":
[
{
"value":"<**All**>",
"displayString":"All objects",
"description":"All objects"
},
{
"value":"Marketing",
"displayString":"Marketing",
"description":""
},
{
"value":"Support",
"displayString":"Support",
"description":""
}
]
}
{
"statisticIdentifier":"inin.workgroup:AgentsLoggedIn",
"parameterValueItems":
[
{
"parameterTypeId":"ININ.People.WorkgroupStats:Workgroup",
"value":"Support"
}
]
}
Due to a scalability algorithm, null statistic values may be returned initially when creating a subscription to the statistic values . A subsequent message with actual values (assuming they are not truly null) will be sent as soon as possible.
The alert catalog contains "alert sets" accessible to the session user. Alert sets will have an alertSetId, which is used when subscribing to alert notifications. These alert sets contain alert definitions, which define what statistic key an alert is based on and its rules. An alert can have multiple rules which define actions clients should take when the alert is triggered, the condition by which the alert is triggered, and a severity for this condition. Here is an example alert set with one alert definition:
{
"alertSetId":"2370ffba-39f7-4dc2-a5c0-df5ae98f4153",
"subscribedByOther":true,
"subscribedByUser":true,
"owner":"john.doe",
"ownerDisplayName":"John Doe",
"description":"",
"created":"20130911T163034.963Z",
"modified":"20130911T163034.963Z",
"modifiedBy":"john.doe",
"accessMode":1,
"alertDefinitions":
[
{
"alertDefinitionId":"1e63b1aa-83f3-414a-b2b8-6f7b0718e2ba",
"statisticKey":
{
"statisticIdentifier":"inin.agent:InteractionsEntered",
"parameterValueItems":
[
{
"parameterTypeId":"ININ.People.AgentStats:Workgroup",
"value":"Support"
},
{
"parameterTypeId":"ININ.People.AgentStats:User",
"value":"user1"
},
{
"parameterTypeId":"ININ.Queue:Interval",
"value":"CurrentPeriod"
}
]
},
"displayString":"",
"description":"",
"alertRules":
[
{
"alertRuleId":"59b1b3e8-e059-4a1c-bf35-2c6acde18583",
"alertSeverity":1,
"alertCondition":
{
"__type":"urn:inin.com:alerts:numericIntCondition",
"minimum":20,
"maximum":100,
"alertConditionId":"59b1b3e8-e059-4a1c-bf35-2c6acde18583",
"alertConditionComparison":7
},
"alertActions":
[
{
"alertActionId":"9674a936-45ae-4c2f-b695-cd0c75723d4c",
"targetId":"ININ.Supervisor.IconAlertAction",
"namedValues":{}
}
]
}
]
}
]
}
Alert notifications inform clients when alerts have been triggered by their conditions. A "triggered alert" is also known as an "active alert". If the statistic value of a triggered alert exits an alert condition, an alert notification will be sent so clients know it is no longer active.
When creating a subscription to alert notifications, you must form an "alert set key". An alert set key consists only of an alertSetId, which must correspond to an alert set contained in the alert catalog:
PUT http://iosapps.inin.com:8018/icws/431669001/messaging/subscriptions/alerts/alert-notifications HTTP/1.1
{
"alertSetsAdded":
[
{
"alertSetId":"2370ffba-39f7-4dc2-a5c0-df5ae98f4153"
}
]
}