Chapter 2. 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.

[Warning]

The pipe symbol “|” currently is not behaving as intended and should be encoded with “%7c”.

Older version of Tomcat allow it to stand as it is. Our proxies instead are more aggressive, and reject it correctly with an error 400, because they cannot decode the request.

Example of working URL:

https://localhost/QmRealtime/jsonStatsApi.do?queues=0002%7c5000

Not working URL:

https://localhost/QmRealtime/jsonStatsApi.do?queues=0002|5000

2.1. 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 complex 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.

2.2. Should I use JSON or XML-RPC?

QueueMetrics ships with both an (older) XML-RPC API and a JSON API. The JSON API includes more fuctionality (system configuration) and wraps the existing XML-RPC calls. We plan to primarily support the JSON API and keep the XML-RPC one only for compatibility with legacy software. So if you are creating a new piece of software, go for the JSON API.

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

[Tip]

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

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