Chapter 3. The JSON Configuration API

This API lets you configure QueueMetrics in a way that is similar to the one used interactively to create and edit records.

3.1. General usage

3.1.1. Reading a record

Each editor has a unique name, as decribed below. Let’s say we want to configure an agent. The first thing we do is to list available agents by issuing a list for editor agent.

curl  --user robot:robot -i -H "Content-Type: application/json"
      -X GET

The result is a set of records, each of which describes one agent configured. 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....

You can see that each record has an ID with a fixed name of PK_ID. This is the identifier for one specific record. The other information is provided to help you locate the record(s) you are looking for. It is also possible to pass along the parameter "q=Agent/101" to filter for "Agent/101".

When you know which record you want to get details about, you issue a:

  curl  --user robot:robot -i -H "Content-Type: application/json"
        -X GET

The result is a full description of a record, as in:

  "aliases" : "",
  "chiave_agente" : "",
  "current_terminal" : "-",
  "default_server" : "0",
  "descr_agente" : "John Doe (101)",
  "group_by" : "1",
  "group_by__DECODED" : "Default",
  "id_agente" : "71",
  "location" : "1",
  "location__DECODED" : "Main",
  "ltCodeAssociate" : [ [ "inbound", "All", "Main" ], [ "inbound", "Q DPS", "Main" ] ],
  "nome_agente" : "agent/101",
  "nomedata_insert" : "demoadmin, 18/06/2007, 22:28",
  "nomedata_update" : "demoadmin, 05/05/2014, 12:56",
  "payroll_code" : "",
  "sip_login" : "",
  "sip_pwd" : "",
  "sip_realm" : "",
  "sip_uri" : "",
  "supervised_by" : "41",
  "supervised_by__DECODED" : "demosupervisor",
  "sys_dt_creazione" : "2007-06-18 22:28:20",
  "sys_dt_modifica" : "2014-05-05 12:56:33",
  "sys_optilock" : "63943",
  "sys_user_creazione" : "32",
  "sys_user_modifica" : "32",
  "vnc_url" : "",
  "xmpp_address" : "agent101@chatserver"

You can notice a few patterns in the data above:

  • the ID is passed along in the URL.
  • some fields may end in DECODED and they contain a string version of a numeric ID. When committing, you can leave the main field blank and pass along the textual DECODED version only. If both the DECODED version and the relevant ID are present, the DECODED version takes precedence.
  • the record may contain structures (lists, hashes or tables); those are read-only and are ignored on commit.
  • any field starting with opt_ or _ is a decorator, and is read-only. It is typically used to convey additional information.
  • the fields named nomedata_insert and nomedata_update are textual representation of the current record creator and last updater.
  • the field called sys_optilock is the current optimistic lock and is needed for updating the record.
  • any other fields staring with sys_ are read-only and can be ignored on commit.
  • boolean values (yes/no) are usually encoded as "1" and "0" respectively.
  • when an updatable field is made up of multiple entries, they are usually separated by the pipe "|" character.

3.1.2. Updating a record - Optimistic locking

In order to perform an update on an existing record, you need to:

  • load the current record,
  • edit it,
  • commit it.

It is of paramount importance that you reload the record before editing and committing it - as QueueMetrics is a multi-user application, it is possible that a record is changed before you save it. In order to detect and abort such changes, QueueMetrics uses the original value from sys_optilock to make sure the record was not modified when you save it. In case the record was modified, subsequent modifications will fail with an OptiLock exception; in this case you need to reload the record and repeat the sequence.

So, for example, you could read record #71 into a file….

  curl  --user robot:robot -H "Content-Type: application/json"
        -X GET
        > agent71.json

You would then edit it and save it again, as in:

  curl  --user robot:robot -i -H "Content-Type: application/json"
        -X POST -d @agent71.json

After saving, QueueMetrics returns the new record you just saved, so you can check that your changes were saved successfully.


Some QueueMetrics editors might perform additional contextual sanity checks before saving the record and might abort if they find a logical inconsistency. For example, you cannot enter two agents with the same agent code. In this case a meaningful error message will be returned.

3.1.3. Creating a new record

In order to create a new record, you POST to a fake record id "-" or "0", as in:

  curl  --user robot:robot -i -H "Content-Type: application/json"
        -X POST -d @new_agent.json

After saving, QueueMetrics returns the new record you just saved, so you can obtain its current PK_ID.

3.1.4. Deleting a record

In order to delete an existing record you perform a DELETE, as in:

  curl  --user robot:robot -i -H "Content-Type: application/json"
        -X DELETE

There is no safety-check on delete, so a deleted record is gone forever. QueueMetrics will return the record you just deleted as it was before being deleted, so you stilll have a chance to save it and restore it.

3.1.5. Hyerarchical records

Some editors are hyerarchical, because they depend on other editors. For example, in order to get the screens in a report, you need to pass the screen editor the report id when listing.

You do this by adding:

  curl  --user robot:robot -i -H "Content-Type: application/json"
        -X GET

The id’s you get out of listing are then permanent, so you do not need to pass this along when updating or inserting. When inserting, you will generally need to fill in a "__DECODED" field with the name of the parent so that QM knows where to attach the new record.

3.2. Available editors

3.2.1. dnis

Edits the DNIS tables.

3.2.2. ivr

Edits the IVR tables.

3.2.3. class

Edits the user class tables.

3.2.4. user

Edits the user list. Any user must belong to a valid class.

3.2.5. queue

Edits the list of queues and the set of agents linked to a sepcific queue.

3.2.6. agent

Edits the agent properties.

3.2.7. agentGroup

Edits agent groups.

3.2.8. location

Edits the list of locations.

3.2.9. outcome

Edits the list of allowed outcomes.

3.2.10. pause

Edits the list of available pause codes.

3.2.11. exportJob

Created and edits export jobs.

3.2.12. cronJob

Created and edits Scheduled Jobs.

3.2.13. exportCall

Lists the set of calls in an export job. Requires the export-job ID as a parent.


This transaction is read-only; commits will not work.

3.2.14. report

Edits availble reports.

3.2.15. reportScreen

Edits the screens for a report. Requires the screen-id as a parent.

3.2.16. reportItem

Edits the items in a screen. Requires the screen-id as a parent.

3.2.17. qaForm

Edits QA forms. It is of paramount importance to make sure that all items exist and that the lengths of each section are correct.

3.2.18. qaItem

Edits QA items.

3.2.19. perftrackRule

Display Performance Tracker rules.


This transaction is read-only; commits will not work.

3.2.20. exportReport

Edits the available export reports.

3.2.21. cfgProps

Reads and edits the file. In order to make changes to the file, the key EDIT_CFG is required. Any changes are appended by the end of the file and the previous entry is commented out.

3.2.22. skills

Reads and updates the set of available skills known to the system.

3.2.23. knownnumbers

Reads and updates the set of known phone numbers present in the system.