What is JSON?

Wikipedia defines JSON as:

JSON, or JavaScript Object Notation, is an open standard format that uses human-readable text to transmit data objects consisting of attribute-value pairs. It is used primarily to transmit data between a server and web application, as an alternative to XML. Although originally derived from the JavaScript scripting language, JSON is a language-independent data format, and code for parsing and generating JSON data is readily available in a large variety of programming languages.

This means that, whatever your programming language of choice, you can surely find a JSON library for it; and once you have the library, connection to QueueMetrics is straightforward.

Which functions does QueueMetrics export as JSON?

QueueMetrics uses the JSON API in order to:

  • read and update the system configuration - e.g. reading, creating and updating agents, queues, DNIS etc.

  • export the results of most analyses in a format that is immediately usable by other software.

  • perform actions programmatically, like e.g. filling in QA forms.

Information is divided into blocks, i.e. sets of data that roughly correspond to the tables QM uses for its own output.

This means that you can build software that sits on top of QueueMetrics and uses its results as a starting point for further elaboration, e.g.:

  • Visualizing results with custom graphs currently not supported by QueueMetrics.

  • Computing period comparison analyses (one period versus another period).

  • Accessing agent presence data for payroll computation.

  • Creating QueueMetrics users based on an external reference system.

Of course there are many possible scenarios where you might want to use such information.

A note on examples

If you use Tomcat 8+ as a servlet container, or a proxy in front like we do for QueueMetrics Loive, then you will get an error code 400 if you do not accurately URL-encode all characters according to RFC 7230 and RFC 3986. This often happens when passing a set of queues or agents that are separated by the pipe symbol - so a|b will not work, but a%7Cb will.

Older version of Tomcat allowed them to stand as they were. Current versions instead are more aggressive, and reject ( correctly) with an error 400, because they cannot decode the request. As the encoded format is not very readable, we left examples in this tutorial with the old format, but you must remember to quote them properly.

To keep the text readable, we also chose to write long command-lines having multiple parameters on multiple lines - it is up to you to enter them on one single line. For example, the URL above could be written as:

https://localhost/queuemetrics/SomeApi/jsonStatsApi.do?
      queues=0002|5000&
      agent=123

But you must enter it as:

https://localhost/queuemetrics/SomeApi/jsonStatsApi.do?queues=0002%7c5000&agent=123

Should I use JSON or XML-RPC?

QueueMetrics used to ship with an old XML-RPC API, but it does not exist in recent QueueMetrics versions. So you should definitely use JSON and, if you are on an older version, migrate any existing integration to run on JSON as well.

Example: accessing QueueMetrics from the command-line

The easiest way to interact with the JSON interface is to do it from the command line using a tool like 'wget' or 'curl'. All QueueMetrics JSON calls require a valid login and password, that must be passed as an HTTP basic auth.

So in order to access the list of configured agents from the command line you would simply type (all in one line):

curl  --user robot:robot -i -H "Content-Type: application/json"
      -X GET http://qmserver:8080/queuemetrics/agent/jsonEditorApi.do

The result is a human-readable data structure that describes configured agents. For example:

[ {
  "group_name" : "Default",
  "PK_ID" : "71",
  "location" : "1",
  "group_by" : "1",
  "descr_agente" : "John Doe (101)",
  "chiave_agente" : "",
  "loc_name" : "Main",
  "vnc_url" : "",
  "group_icon" : "default.png",
  "real_name" : "Super Visor",
  "supervised_by" : "41",
  "current_terminal" : "",
  "nome_agente" : "agent/101",
  "xmpp_address" : "agent101@chatserver"
},
  ...more records follow....
]

As this format is very easy to see and understand, all JSON APIs in this guide are documented by showing an example of a command-line call using 'curl'.

Make sure you remember to enable the user 'robot' in QueueMetrics, or have an equivalent user you can login as.

Example: accessing QueueMetrics from Ruby

In this example we’ll see how easy it is to access QueueMetrics from a scripted language like Ruby.

#! /usr/bin/env ruby

require 'json'
require 'open-uri'

# Settings - edit as needed
url = 'http://127.0.0.1:8084/queuemetrics'
apicall = "agent/jsonEditorApi.do"
login = 'robot'
pass = 'robot'

# call the JSON method
replyHttp = open( "#{url}/#{apicall}", :http_basic_authentication=>[login, pass])
jsonText = replyHttp.read

# decode the JSON response and print it out as a Ruby structure
reply = JSON.parse( jsonText )
puts reply

This very simple script gets the list of agents in QueueMetrics and prints it out as a native Ruby data structure.