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.
General usage
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 http://127.0.0.1:8084/queuemetrics/agent/jsonEditorApi.do
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 http://127.0.0.1:8084/queuemetrics/agent/71/jsonEditorApi.do
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.
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 http://127.0.0.1:8084/queuemetrics/agent/71/jsonEditorApi.do
> 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
http://127.0.0.1:8084/queuemetrics/agent/71/jsonEditorApi.do
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. |
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
http://127.0.0.1:8084/queuemetrics/agent/-/jsonEditorApi.do
After saving, QueueMetrics returns the new record you just saved, so you can obtain its current PK_ID.
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 http://127.0.0.1:8084/queuemetrics/agent/71/jsonEditorApi.do
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.
Hierarchical records
Some editors are hierarchical, because they depend on other editors. For example, in order to get the AMO lists for a campaign, you need to pass the campaign-id when listing.
You do this by adding the parameter parent to your request, as below:
curl --user robot:robot -i -H "Content-Type: application/json"
-X GET
http://127.0.0.1:8080/queuemetrics/amoList/jsonEditorApi.do?parent=4
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.
Available editors
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. |
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.
perftrackRule
Display Performance Tracker rules.
| This transaction is read-only; commits will not work. |
cfgProp
Reads and edits the configuration.properties 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.
client
Reads and updates the list of clients. Like in the GUI, on the deatails of a client you can see a list of cases they are linked to.
case
Reads and updates the list of cases. Linke in the GUI, on the details of a case you can see all its transactions.