The data basis for the Dashboards - the JSON files (1)

We introduced you to some available settings of the babelforce dashboards in previous articles. Now, we will go ahead and have a look at the script basis for these dashboards: the JSON files.

babelforce provides you with some predefined JSON which you can extend and change according to your needs. In this article we will explain the JSON that is used for our KPI dashboard.

The next article will then give insights on how to adjust the JSON. This will enable you to switch around the widgets, change KPIs, add your queues and groups, etc. 

This article will cover the following:

1. Grabbing the dashboard JSON

2. Introduction to the different widgets

3. Putting it all together

Let's dive into the first part:

1. Grabbing the dashboard JSON

Before you start adjusting your dashboard we suggest you get hold of the KPI dashboard's JSON. To follow our explanations in this article, we recommend you take the file and follow along.

You can view the KPI JSON file here: https://pastebin.com/0jduQWHp

If you want to see the JSON of the standard dashboard presented when you open up https://apps.babelforce.com/dashboard/ you can do this by accessing the API:

If you have been around for a while you have most certainly already heard of the babelforce API documentation. You find it here:

Unbenannt.PNG

In the dashboard API you find the endpoint that returns the default configuration of your dashboard. Find it under manager API > dashboards. The endpoint "view default dashboard config" shows the basic JSON file for our dashboard configuration. Next, let's go through the JSON carefully.

2. Understanding the JSON structure

JSON is stands for “JavaScript Object Notation”. It’s used to store and exchange data as an alternative solution for XML. However, JSON files have a standard structure that makes them easy to read and write. Its syntax format is based on two main structures: Objects and Arrays. An Object is a collection of name/value pairs, and Array is an ordered list of values.

If you didn't work with JSONs yet, we recommend you reading the following article which explains it pretty well:

https://medium.com/omarelgabrys-blog/json-in-a-nutshell-7d638dfea7cc

Now that you understand the basic structure of a JSON, let's move on to investigate the JSON for our babelforce default dashboard.

We start by defining the type of our JSON, a "dashboard" and give it the header "Real-time Dashboard":

{
"type": "dashboard",
"label": {
"text": "Real-time Dashboard"
}

Also, we want our dashboard to be structured by rows. Therefore we define an object called "rows". In these rows you find the objects and arrays with which the different modules and widget groups are defined.

As you can see in the script, the first row has a label assigned saying "right now" - check your dashboard - this is this green label you see at the left top.

Next comes the class "row-y100" which defines the height of the row.

 "rows": [
{
"label": "Right now",
"display": true,
"class": "row-y100",
"widgets": [
{

3. Understanding the different widgets

As you may have seen in one of the first two articles, our dashboard is separated into so called widget groups or modules - small containers which show grouped data. babelforce offers a few different widget types which can be put together to form a widget group or module. Also, there are predefined widget groups/modules  which are largely unchangeable.

Let's have a look at these ones first:

Modules:

  • "agent.status": shows the number of agents available, in call or not available at the moment
  • "call.status" type "inbound" : shows current inbound calls (active, in IVR, queued & bridged)
  • "call.status" type "outbound" : shows current outbound calls (active, scheduled, ringing, bridged)

You find these three modules in the first row of our default dashboard: the agent status widget and both an inbound and an outbound call status widget.


mceclip0.png

  {
"module": "agent.status",
"settings": {
"push": false
}
}

mceclip1.png
  {
"module": "call.status",
"settings": {
"type": "inbound",
"push": false
}
}

mceclip2.png
  {
"module": "call.status",
"settings": {
"type": "outbound",
"push": false
}
}
]
}

As written above, these modules are largely unchangeable. However, there is a nice feature available for some of the modules: we can adjust certain modules to only show the data we want to see: the modules can be adjusted to show only the data for a certain tags or groups for instance by applying filters.

For example, you want a dashboard that only shows agents that have the tags "english" and "spanish". That's possible with parameters.

{
"module": "agent.status",
"settings": {
"push": false,
"tags": ["english","spanish"]
}
}

For groups you will have to use the group ID. This would look like this. As you can see in the example below, you can also combine groups and tags.

{
"module": "agent.status",
"settings": {
"push": false,
"label": "Tech agents",
"groups": ["34d25986-6ee7-86das-xxxx"],
"tags": ["english"]
}
}
You can add the following parameters to filter some of the predefined modules:
 Widget name  groups (group ID)  tags  queues (queueID)
 agent.status  yes  yes  no
 call.status - inbound  yes  no  no

If you compare these three widgets with your dashboard you will have noticed that we covered the top row. Now let's have a look at the second row. It consists of three widget group types:

  • a bar chart which shows the inbound calls that are currently offered and bridged
  • "object-table-agents" which shows the available agents right now
  • "object-table-calls" which shows the agents in call

Let's have a closer look at the type "object-table-agents" for instance:

mceclip3.png

{
"type": "widget.group",
"label": {
"text": "Current agent activity"
},
"rows": [
{
"widgets": [
{
"maxDisplayedItems": 10,
"type": "object-table-agents",
"tableData": "queues",
"tableHeader": "header-current-agent-activity",
"tableTemplate": "table-call-by-activity",
"dataUrl": "/agents"
}
]
}
]
}

Similarly to the modules, these widget groups are predefined by babelforce which means that the basic structure is unchangeable. As for the modules, however, you can filter for certain parameters:

For the widget groups this is done by adding objects to the array "dataURL". We can add any parameter available just like adjusting an API request.

For instance, if you would like to filter for a certain group you just have to add the parameter "group" as an object. This would look like this:

"dataUrl": "/agents",
"params": {
"groups": [
"test-group","dev-group"
]
}

 The following table shows the filters which can be applied for the widget groups:

 Widget name  groups  tags  queues (ID)
 object-table-agents  yes  yes  no
 bar-chart  no  no  yes
 object-table-calls  no  no  no

Having covered the predefined babelforce widget groups and modules, let's move on to the most exciting part - the widgets you can define individually to have an overview of the KPIs relevant to you. This part is actually babelforce offers several widget types:

  • widget.msToS: if the API endpoint returns the metric in milliseconds, we have to convert it to Seconds
  • widget.sToMMSS: if the API endpoint returns the metric in seconds, we have to convert it to Minutes and Seconds
  • widget.percentage: you choose that widget type if you want to have shown a percentage
  • widget.number: you choose that widget type if you want to have shown a number

As you saw in the previous articles and in the screenshots above, every widget contains several small boxes showing certain call metrics. We will now show you how to build such a metric box and how to put it in a widget:

Therefore, let's look at the default JSON again. First of all, we have to create a new row, the third row of our dashboard:

{
"class": "row-y300",
"display": true,
"widgets": [
{

Now, let's have a closer look at the second widget in this row. It shows the wait time, the longest waiting call and the abandon rate:

mceclip0.png

The code snippet for this widget looks like this:

  {
"type": "widget.group",
"label": {
"text": "Wait time / Abandon rate"
},
"rows": [
{
"widgets": [
{
"label": {
"text": "Avg. wait time"
},
"type": "widget.msToS",
"metric": "queues.wait-time.avg",
"params": {
"bridgedOnly": false
}
},
{
"label": {
"text": "Longest waiting call"
},
"type": "widget.sToMMSS",
"metric": "queues.calls.waiting.total",

},
{
"label": {
"text": "Abandon rate"
},
"type": "widget.percentage",
"metric": "abandon.value"
}
]
}
]
}

 There are a few small things we have to consider here:

  • adjustment of the row height: we choose y300
  • widget type wait time: in this case we want to convert milliseconds (which is the default value returned when calling the endpoint for the average wait time) to seconds, hence we have to choose widget.msToS
  • widget type longest waiting call: in this case we want to convert seconds (which is the default value returned when calling the endpoint for the longest waiting call) to seconds, hence we have to choose widget.sToMMSS
  • widget type abandon rate: in this case we want to see a percentage on our dashboard, hence we have to choose widget.percentage
  • metric: the "id" (or you may also call it name) of the metric can be found by making the API request for the respective KPI:

mceclip5.png

Similar to the widget groups and modules you can filter for any parameter you might be using when making the API request for that endpoint.

Now that we covered the details, let's have another look at the big picture:

3. Putting it all together

As you learned in this article, you can divide you dashboard into several rows. You can add as many rows as you wish. Just be careful not to overload your dashboard. A recommended approach by babelforce is to design one row for each queue and repeat this for each queue.

We hope we could give you an overview of how to build your babelforce dashboards in JSON. The next article of this section will play around with the options you have in JSON and show different ways to structure your dashboard.

Have more questions? Submit a request