General

The new KPI events subscription methodology is that clients will subscribe to specific KPIs they are interested in.

Whenever a KPI changes, an update will be sent to relevant subscribers.

Clients will get all KPI data via events and will not have to poll, or even get a snapshot via the API.

Any client may subscribe to any counter\s. It means wallboard\supervisors\agents.

We expect clients to subscribe to a long list of KPIs - especially for supervisor and wallboard usages.


Subscription via API

Subscription method

The subscription method is Statistics\SubscribeForCounters

Input parameters

ClientSubscriptionId

This is a GUID, generated by the client. It will be included in the events, and will be used to route the events to the subscribed client.

In practice, the eAgent and eSupervisor are expected to use the Id of themselves for this field (i.e. eAgent will send the agent ID as the clientSubscriptionId)

HandlerCounterPairs

This is a list of specific KPIs the client is interested in getting updates for. 

Each element in the list will have the following properties:

  • HandlerId - GUID of the handler of this KPI. 
    • For agent counters it will be an agent ID (All agent IDs are available via GetConfiguration API method - organizationData.agents)
    • For BP and callback counters it will be a BP ID (All BP IDs are available via GetConfiguration API method - organizationData.businessPRocesses)
    • For campaign counters it will be a campaign ID (All campaign IDs are available via Campaigns API method)
    • For channel counters it will be a channel ID (All channel IDs are available via GetConfiguration API method - organizationData.channels)
    • For organization counters it will be the organization ID
  • CounterTypeId - The counter type GUID (available via GetConfiguration API method, organizationData.counters.counterType)
  • DimensionId - This is dimension GUID, (available via GetConfiguration API method, organizationData.counters.dimensions). This is an optional parameter - if not supplied the subscription is for the primary value of the counter, if supplied the subscription is for this specific dimension.  

Results

The result will have the following properties:

  • Result - 0 indicates a failure, 1 indicates a success
  • ErrorCode - error code
  • ErrorText - detailed error message
  • FailedSubscriptions - list of specific failed subscriptions (only when some KPIs are successfully subscribed). Each item in the list will have:
    • HandlerId - same GUID as was received in the input
    • CounterTypeId - same GUID as was received in the input
    • DimensionId - same GUID as was received in the input
    • Reason - details about the failure (i.e. "Counter Type doesn't exist" etc.)

Special cases

  • A subscription requires a wallboard resource, if there are no more resources we will return HTTP code Forbidden 403 (ErrorCode=NO_MORE_LICENSE, ErrorText="Not enough licenses for additional subscriptions") 
  • If all input KPI failed to subscribe we will return HTTP code BadRequest 400 (ErrorCode=WRONG_PARAMETER, ErrorText=""No valid subscriptions ...") 

Initial KPIs right after subscription

Upon successful subscription the client will get an event with the current value of all the KPIs it subscribed to.


Events

Aside from the initial events that are sent right after a subscription, we will monitor changes in subscribed KPIs and fire an event - COUNTER_UPDATE_EVENT with all changed counters for subscribers.

The event with the updated KPI may be sent up to 2 seconds after the KPI changed.

These properties will exist in each event:

ClientSubscriptionId

This is used by the events server to route the events to the real subscriber

Counters

A list of KPI values. Each item in the list will have:

  • HandlerId - same as the input subscription, identifies the handler
  • CounterTypeId - same as the input subscription, identifies the counter type
  • CounterTypeName - the name of the counter type
  • DimensionId - same as the input subscription, identifies the specific dimension, or empty if the subscription was for the primary value
  • Value - this will contain the value of the specific KPI
  • Alert - the alert status of this KPI (relevant only for subscriptions for the primary value and will be null for specific dimension subscriptions). Values are: None\Warning\Alert
  • SecondaryValue - When not empty, this field indicates that this is a timespan counter that is currently ticking. The value is how long this counter is ticking for.


Example

We'll use a sample subscription request for my local Technical Support BP, total interactions counter main value and telephony\chat dimensions.

It contains clientSubscriptionId=fd7c5b2e-624b-4b99-875a-0b618b0dff11

and HandlerCounterPairs=[{"HandlerId":"a120ae78-1ea0-41ac-9135-e9e907c24e04","CounterTypeId":"45b331c6-e5de-44e5-a16c-d2d73d0ccf4f"},{"HandlerId":"a120ae78-1ea0-41ac-9135-e9e907c24e04","CounterTypeId":"45b331c6-e5de-44e5-a16c-d2d73d0ccf4f","DimensionId":"63680cf3-2864-40d8-83c7-1969770afd0f"},{"HandlerId":"a120ae78-1ea0-41ac-9135-e9e907c24e04","CounterTypeId":"45b331c6-e5de-44e5-a16c-d2d73d0ccf4f","DimensionId":"fd7c5b2e-624b-4b99-875a-0b618b0dffdb"}]

This screenshot is a readable version of the subscription request:



Right after subscribing, we get this event:

{
  "type": "REPORTED_EVENT"
  "eventType": "COUNTER_UPDATE_EVENT",
  "clientSubscriptionId": "fd7c5b2e-624b-4b99-875a-0b618b0dff11",
  "counters": [
    {
      "handlerId": "a120ae78-1ea0-41ac-9135-e9e907c24e04",
      "counterTypeId": "45b331c6-e5de-44e5-a16c-d2d73d0ccf4f",
      "counterTypeName": "BusinessProcessTotalInteractions",
      "dimensionId": null,
      "value": "0",
      "alert": "None",
      "secondaryValue": null
    },
    {
      "handlerId": "a120ae78-1ea0-41ac-9135-e9e907c24e04",
      "counterTypeId": "45b331c6-e5de-44e5-a16c-d2d73d0ccf4f",
      "counterTypeName": "BusinessProcessTotalInteractions",
      "dimensionId": "63680cf3-2864-40d8-83c7-1969770afd0f",
      "value": "0",
      "alert": null,
      "secondaryValue": null
    },
    {
      "handlerId": "a120ae78-1ea0-41ac-9135-e9e907c24e04",
      "counterTypeId": "45b331c6-e5de-44e5-a16c-d2d73d0ccf4f",
      "counterTypeName": "BusinessProcessTotalInteractions",
      "dimensionId": "fd7c5b2e-624b-4b99-875a-0b618b0dffdb",
      "value": "0",
      "alert": null,
      "secondaryValue": null
    }
  ],
  "timestamp": "2024-07-02T12:16:16.033+03:00",
  "organizationId": "f0489a6d-2514-41af-b94b-0984dc213925",
}




  • No labels