Accessing QueueMetrics through its JSON interface
Contents
1. Any missing parameters are read as if they were blank and vice versa The names of the data blocks you need will usually be similar to OKDO A gentsOnQueues You can get those easily from QueueMetrics where you see the Excel CSV export icon copy the link in your browser and inspect it it will contain a parameter like S OkDO AgentsOnQueues 123456789 Just remove the first and last parameters wow For QA methods allowed grader types are unknown agent grader and caller For readability s sake all examples given below that use the curl command are written on multiple lines When testing them O on a real system they must be entered on one single long line instead 4 1 Reports 4 1 1 Obtaining statistics QmStats This API call will start up a session in QueueMetrics check if the user exists and has the privilege to run the report run the analysis prepare the required results and return them At the end of the call the QueueMetrics session is destroyed so no data is kept for further elaboration This means that it s usually the most efficient thing to do to request all needed response information at once but it s wise to limit yourself to the minimum data set you will actually need as each block takes up CPU and memory space to be marshaled between the native Java format the intermediate JSON format and the resulting client format QueueMetrics poses no limits on the size of analyses you may want to run It is2. 010 amp to 2015 01 01 00 00 00 amp queues ql q2 amp form MyForm 17 The JSON Reports API amp block QualAssDO OverallAverageFormReport amp block QualAssDO ScoringItemsFormSummary Parameters queues one or more queues separated by the pipe symbol from the beginning of the reporting period in date time format to the end period agent the agent code to be used as a filter e form the name of the form you want to report on grader the grader type block One or more data blocks that you need to access Parameters marked with an asterisk are mandatory Allowed data blocks QualAssDO Quality Assessment information related to QA Forms Method Description OverallAverageFormReportAggregated information for the overall specified form scoring and not scoring questions included FormSummary Aggregated information for the specified form only scoring questions ScoringltemsFormSummarAggregated information for the specified form only scoring questions same as FormSummary NonScoringltemsFormSummggregated information for the specified form only non scoring questions 4 3 4 Entering a QA form QmQaGrading This method lets you fill a QA form through an API call It replies with the same raw information reported by the QmQaFormReport method and can replace it if QA parameters are empty when calling The report counts the aggregated QA statistics on calls with timestamp included in t
3. 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 The JSON Configuration API 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 exportCall Lists the set of calls in an export job Requires the export job ID as a parent O 3 2 13 report Edits availble reports This transaction is read only commits will not work 3 2 14 reportScreen Edits the screens for a report Requires the screen id as a parent 3 2 15 reportltem Edits the items in a screen Requires the screen id as a parent 3 2 16 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 17 qaltem Edits QA items 3 2 18 perftrackRule Display Performance Tracker rules O 3 2 19 exportReport This transaction is read only commits will not work Edits the available export reports 3 2 20 cfgProps 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 Chapter 4 The JSON Reports API All of Que
4. agent101 chatserver You can notice a few patterns in the data above e 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 e 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 e load the current record e 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
5. 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 e 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 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 to
6. server the server name in a cluster setup or empty for a not cluster setup e id the Asterisk call id filename the recording filename associated to the tag to be inserted e time the time in seconds where the tag will be placed If empty the tag will be placed at the beginning of the file e duration the tag duration in seconds lt can be empty message a text message If empty no tags will be added This is useful for retrieve the list of tags associated to a specific call color a color in RGB format from 000000 to FFFFFF Parameters marked with an asterisk are mandatory Response There is only one response block returned named TagRecords where the caller will retrieve the list of tags associated to the specific server and Uniqueld parameters 4 1 5 Add broadcast messages QmBroadcastMsg This method is used to insert broadcast messages that will be shown in the realtime broadcast message page Method QmBroadcastMsg Auth required Yes user must hold the key ROBOT XML RPC method QM broadcastMessage Available since 14 06 Seas Example CUel user robor robot 1 Se Comeeme lyose apolicairion sont X GET http localhost 8084 queuemetrics QmBroadcastMsg jsonStatsApi do text Hello world severyone 1 Parameters e text the message to be broadcast queue the optional queue name to act as a filter may be empty 11 The JSON Reports API e location the optional location name
7. the authenticating user is used newpass the new password to be changed for the user If left blank the password is not set Parameters marked with an asterisk are mandatory Response There is only one response block returned named output where the caller will retrieve all user data including the live key set for that user The output block has the format sergio ECO CS EN CON ANS E user keys USER AGENT XX YY All computed keys space separated segs A ES CS ES usercommen own EC CC SE agemalases tetas presen supervisor genia ey EC e ESTI EC password changed OK OK if password was changed blank otherwise The following rules apply Column zero contains the attribute Column one contains the value of the attribute we supply a sample in the table above 13 The JSON Reports API Attribute names are not case sensitive e If the user is also an agent that is there is an agent under the same name as the login Agent attributes are passed e Blank attributes may or may not be present in the list of attributes 4 2 3 The set of known queues for an agent QmAgentQueues The same information can also be accessed and edited through the Configuration API Given an agent like Agent 101 let the caller know on which queue s he s supposed to work as per the configuration on the QM interface For each queue we get also back a level that is a penalty level like 0 1 or 2 It wi
8. to be graded and related information e Validity a task can have a validity period that might be current or future A task with a futiure validity will mature when it enters the validity period e The Task Process Field This is an optional identifier defined as ProcessFamily Processld to be associated to the task Either ProcessFamily and or Processld might be empty It is used generally to link tasks to external processes e g the process and ID of an external system that loads tasks for users 4 4 1 Live data AmAddNoteTask Adds a note task for a specific user Method QmAddNoteTask Auth required Yes user must hold the key ROBOT XML RPC method QM tskAddNote Available since 14 06 sea Example curl use r roborsronor i H Comeceme Typer application som X GET http localhost 8084 queuemetrics QmAddNoteTask jsonStatsApi do recipient Agent 101 amp valid_from 2010 01 01 00 00 00 amp message Hello World EaOtLeSsaores Hice Parameters recipient the login of the user receiving the task e valid_from begin of validity in long date format See above e valid_to end of validity e process usually in the form ProcessFamily ProcessiD See above message the message associated with the task notes an optional textual note Parameters marked with an asterisk are mandatory 4 4 2 Live data QmAddTrainingTask Adds a training task for a specific user Method QmAddTrainingTask
9. Accessing QueueMetrics through its JSON interface Loway Accessing QueueMetrics through its JSON interface Loway Table of Contents 1 Document contents coun evap eed neue pde 1 1 1 REVISION history su ceed sevtne A nent Seen sevese A A AA da 1 2 What is JSON x rise ontario Hank the cee ane as Man wh set ans bare deb Lawhead a rae eden toe dedans eds AUTOUR edhe dt GO 2 2 1 Which functions does QueueMetrics export aS JSON us 2 2 2 Should l use JSON of XML RPG aaraa eetan sade dena Eaa aaa DATER aA LD OPA tg pee DARA da bates Prades 2 2 3 Example accessing QueueMetrics from the command line cee eee eet etree eee tiitt ntti rtnn natur ununa tuuu eeeene eee 2 2 4 Example accessing QueueMetrics from Ruby issues 3 3 The JSON Configuration API romt sorei orne aate a e RA RADA aE A 4 E A ON 4 3 2 Available editors 4 44888 oponen ponia pr eaa enta A ACCA AAN AA chung eee AAA RARA a die 6 4 The JSON Reports AP r tapera e nain orita lt e rer anale bn ed iow apia esr iaeiae 8 41 Reports cia non donnes eme ae dh anaedai nee A anne A A A seeomegeta ees 8 4 2 Authentication and agent information cciecesierecesereneceaarenteeserenedstarenedesetenedsbarendeeneremede A eedi aaa dents 12 4 3 Quality Assessment QA mois arcas endettement ae ane ne alerte ren de were red date ere Diada 15 A TASKS AN 20 4 5 SysioM administration 2222282828 ad a AAA a Aa 22 A A shortlistof REST JSON librari S cociococo n
10. AnsCallsLocation AgentsDO AnsCallsSG e AgentsDO PerformanceAcdGroups AgentsDO AgentOccupancy e AgentsDO AgentSessionTimeByHour e AgentsDO AgentPayableTimeByHour e AgentsDO AgentBillableTimeByHour e AgentsDO AgentSessionByQueueTagFeatureReport AgentsDO SessionByQueueTagFeatureReport AreaAnDO Setup e AreaAnDO CallsOK e AreaAnDO CallsKO e CallDistrDO AnsDistrPerDay e CallDistrDO AnsWaitPerDay e CallDistrDO UnansWaitPerDay e CallDistrDO SalesPerDay e CallDistrDO StaffPerDay CallDistrDO QPosPerDay e CallDistrDO InclSlaPerDay e CallDistrDO TrafficAnPerDay e CallDistrDO AnsDistrPerHr e CallDistrDO AnsWaitPerHr e CallDisttDO UnansWaitPerHr e CallDistrDO SalesPerHr e CallDistrDO StaffPerHr e CallDistrDO QPosPerHr e CallDistrDO InclSlaPerHr e CallDistrDO TrafficAnPerHr e CallDistrDO AnsDistrPerDOW e CallDistrDO AnsWaitPerDOW e CallDisttDO UnansWaitPerDOW 24 Appendix Il QueueMetrics data blocks CallDistrDO SalesPerDOW CallDistrDO StaffPerDOW CallDistrDO QPosPerDOW CallDistrDO InclSlaPerDOW CallDistrDO TrafficAnPerDOW DetailsDO AgentSessions DetailsDO AgentPauses DetailsDO AgentSessionsRaw DetailsDO CallsKO DetailsDO AfpCallsKO DetailsDO CallsKoRaw DetailsDO CallsOK DetailsDO AfpCallsOK DetailsDO AfpCallsIVR DetailsDO CallsIVR DetailsDO CallsOkRaw DetailsDO ButtonExportCalls DistrDO ReportAcd DistrDO AcdByQueue DistrDO AcdByTerminals KoDO ReportKoAll KoDO ReportKoFully KoDO DiscCauses
11. Auth required Yes user must hold the key ROBOT XML RPC method QM tskAddTraining 20 The JSON Reports API Available since 14 06 CES AUN Example Quel user roborsronor i H Comeeme Typer applicarion Jeon X GET http localhost 8084 queuemetrics QmAddTrainingTask jsonStatsApi do recipient Agent 101 amp valid_from 2010 01 01 00 00 00 message Hello World amp notes notesther amp training_title OM Website training_url http queuemetrics com Parameters e recipient the login of the user receiving the task e valid_from begin of validity in long date format See above e valid_to end of validity e process usually in the form ProcessFamily ProcessiD See above message the message associated with the task notes an optional note training_title a title for this trainig task e training_url an URL for this training task e training_id an optional ID for this training task Parameters marked with an asterisk are mandatory 4 4 3 Live data QmAddMeetingTask Adds a meeting task for a specific user Method QmAddMeetingTask Auth required Yes user must hold the key ROBOT XML RPC method QM tskAddMeeting Available since 14 06 Se aie S Example Quel user robor robot i H Comeeme Type application Json X GET http localhost 8084 queuemetrics QmAddMeetingTask jsonStatsApi do recipient Agent 101 amp valid_from 2010 01 01 00 00 00 amp ti
12. KoDO UnansByQueue KoDO OutboundKo KoDO UnansByLen KoDO InclusiveSLA KoDO ReportKoKeyPress KoDO StintsKo KoDO StintsOkKo KoDO QPosKo KoDO QPosOkKo KoDO IvrKo KoDO IvrOkKo KoDO DnisKo KoDO DnisOkKo KoDO OverviewOkKo KoDO InclusiveAnswSLA OkDO RiassAllCalls OkDO RiassFullyWithin OkDO AgentsOnQueue 25 Appendix Il QueueMetrics data blocks OkDO ServiceLevelAgreement OkDO DisconnectionCauses OkDO Transfers OkDO AnsweredcallsByQueue OkDO AnsweredcallsByDirection OkDO StintsOk OkDO QPosOk OkDO IvrOk OkDO DnisOk OkDO MOHOk OkDO HDRRpt OutcomesDO GeneralRep OutcomesDO CallResByOutcome OutcomesDO ActivBillable OutcomesDO ActivNotBillable OutcomesDO AgentReportDetailed OutcomesDO AgentOutcomes CallTagDO CallResByTag OutcomesDO CallResByFeature IlvrDO IvrReport IvrDO IvrTiming IvrDO IvrGoals 5 2 Available blocks for QmRealtime RealTimeDO RTRiassunto RealTimeDO RTCallsBeingProc RealTimeDO RTAgentsLoggedin RealTimeDO WallRiassunto RealTimeDO WallCallsBeingProc RealTimeDO VisitorCallsProc RealTimeDO VisitorTodaysOk RealTimeDO VisitorTodaysKo RealTimeDO RtLiveQueues RealTimeDO RtLiveCalls RealTimeDO RtLiveAgents RealTimeDO RiLlveStatus RealTimeDO RtAgentsRaw RealTimeDO RtCallsRaw RealTimeDO QueuesAndTagsView RealTimeDO QueuesAndTimesView RealTimeDO AgentAndOutcomeView 26
13. Masterkey If set to 1 this user has a Masterkey so this user will pass each key ckeck NLogons The number of logons the user has made Each successful QmAuth call counts as a logon 4 2 2 Authentication and password changing QmAuthenticate This method is used to obtain the profile of a user given its login and password The profile is made up of both login and where applicable agent information It is possible to obtain the profile either of the very user you are calling by knowing its login and password or of a deferred separate user if you have a user that would have the admin keys to view that information in the main GUI The deferred username works so that If a deferred username is passed and e Ifthe username login pair are valid and the user has key USRADMIN and ROBOT Then the User output for the deferred user is returned e If the user also holds the key USR_AGENT the Agent output is returned as well The password change function applies only to the user who logs in not to the deferred user Method QmAuthenticate 12 The JSON Reports API Auth required Yes Available since 14 06 Example curl user robots rosa L H Comeeme lype application Json X GET http localhost 8084 queuemetrics QmAuthenticate jsonStatsApi do deferred agent 101 Logs on as robot and obtains information about agent 101 Parameters e deferred the other user you are accessing data for If left out
14. Res4 Section 4 as defined in the form calls by agent report Res4Q Section 4 as defined in the form calls by queue report Res5 Section 5 as defined in the form calls by agent report Res5Q Section 5 as defined in the form calls by queue report Res6 Section 6 as defined in the form calls by agent report Res6Q Section 6 as defined in the form calls by queue report Res7 Section 7 as defined in the form calls by agent report Res7Q Section 7 as defined in the form calls by queue report Res8 Section 8 as defined in the form calls by agent report Res8Q Section 8 as defined in the form calls by queue report Res9 Section 9 as defined in the form calls by agent report Res9Q Section 9 as defined in the form calls by queue report Res10 Section 10 as defined in the form calls by agent report Res10Q Section 10 as defined in the form calls by queue report AgentDetail Tracked calls details for each defined agent Data blocks from QualAssFormDO can be queried as well see below 4 3 2 Raw form data AmQaFormReport Reads a list of filled in QA forms within the requested period 16 The JSON Reports API Auth required Yes user must hold the key ROBOT XML RPC method QM gaformreport Available since 14 06 Example curl user roborsroboc L 4 Comrenec 1y982 apoliceatrion Jeon X GET http localhost 8084 queuemetrics QmQaFormReport jsonStatsApi do Bio 20010 01 011 00 00 00 Svto 20 1301 Oe 00 010 3 00 amp ag
15. T and KEYUPDATE Available since 14 06 seaso Example curl user keyupdater enableme i H Content Type application json X GET http localhost 8084 queuemetrics QmSetActivationKey jsonStatsApi do key 1234 Parameters e key the new activation key Parameters marked with an asterisk are mandatory Response The custom block KeyResults is filled with the following parameters e KEY status NOKEY if no new key is given otherwise OK or ERROR depending on the success of the operation e KEY_plexld The server identifier e KEY_message A message explaining what went wrong e KEY_current_appl The name of the application e KEY _current_user The name of the user that the application is licensed to e KEY_current_exp The expiration date for the current key Please note that when a new key is installed the current user and expiration date are those of the system on which the key is being installed you should get the new ones as soon as the system restarts will usually take between 5 and 20 seconds 22 Appendix A A short list of REST JSON libraries The following list is by no means exhaustive of all available implementations In most cases REST JSON implementation are embedded in the language itself and are logically split between a network library that will take care of the HTTP request and a JSON library that will unmarshal the response Java The excellent Jackson library will help you parse and cr
16. aaa raptor enn mdd 23 5 Appendix Il QueueMetrics data blocks ss sisiiseseseeseeseesee 24 5 1 Available blocks for QmStats resistant Lovie tea caved gee et dde Ian 24 5 2 Available blocks for QmRealtime Chapter 1 Document contents This document details how to access and use the JSON access functionality in Loway QueueMetrics This makes it possible for your programs to leverage the power of QueueMetrics by calling a very simple API with bindings available in nearly every programming language 1 1 Revision history Jan 27 2015 Added auto generated list of methods Oct 15 2014 New configuration methods e May 19 2014 First draft 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 2 1 Which functions does QueueMetrics export as JSON QueueMetrics uses the JSON
17. advisable to run large data set analysis at night time or when nobody is accessing the system as they may take quite a lot of RAM and CPU and this may slow down QueueMetrics for interactive users Method QmStats Auth required Yes user must hold the key ROBOT XML RPC method QM stats Available since 14 06 seeaso AN Example curl user roborsronor 1 H Comeeme lyper applicarion som X GET http localhost 8084 queuemetrics QmStats jsonStatsApi do queues ql amp from 2000 01 01 00 00 00 Seo 2013 01 0 4L OO 00300 amp block OkDO RiassAllCalls amp block OkDO AgentsOnQueues The JSON Reports API Parameters queues the set of queues that must be included in the analysis They must be separated by a symbol if more than one queue is passed The queue name is the internal Asterisk queue name from the begin of the reporting period as a date to the end of the reporting period filter the agent filter an agent s name like Agent 101 that must be the filter for all the relevant activity block the output blocks that have to be exported To specify multiple blocks add multiple times It is advisable to request all blocks you need in a single call as it is way cheaper for QueueMetrics to compute different blocks on a data set in memory than to recompute it from scratch on a different API call Parameters marked with an asterisk are mandatory Where do find data blocks A complet
18. cord 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 Gurl u8semz olowsoloow L al Comes 14988 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_age ww LA nte Heurne Cerimi merlt default server descr_agen Moiola MONA group_by id_agente VOCAL LOMY Wlosewi loja te val T OUR John LA DECO DED AL 71L T DECO DED ltCodeAssociate nome agente nomedata_i MS Saa nomedata_update payroll code Cl agent de de we LA Doe 101 Default Main talon WATLIw Mesa done moadmin 18 06 2007 moadmin 05 05 2014 22828 128 56 iaa O Das MM l The JSON Configuration API SOMO g wwe emo jaa MW Mea iascubas 3 uo SAP S per vis iso A supervised_by__ DECODED demosupervisor SISMO ME SM 3 V2007 06 18 22 28 20 Were Cle mocllrica 2 2014 05 gt 205 12256533 Mae MO O IAS ES sys_user_creazione 32 WNa e S SAMOA Vaz A xmpp_address
19. e list of possible QueueMetrics blocks is maintained in the QueueMetrics User Manual chapter 6 Report Details where each block is described in detail The QueueMetrics User Manual can be obtained from the QueueMetrics website For every possible block there is a name a description a shortcut code for ease of identification and an API code usually referred to as an XML RPC code for historical reasons That is the name of the block that has to be retrieved over JSON For example if we want to access the Disconnection Causes block we will look it up in the manual until we encounter E UNOS Disconnection Causes We see that its XML RPC code is KoDO DiscCauses so that is the name of the block we ll be asking for Block names are case sensitive so make sure you are writing it exactly as it appears on the User Manual For a quick reference data blocks are aso listed in Appendix Il of this manual at Section 5 1 Available blocks for QmStats 4 1 2 Live data QmRealtime Obtains the real time status of a system This method is very similar to QmStats but it is used to retrieve the real time stats The same suggestions that are given for QmStats apply Please note that there is a difference between results produced by the API realtime calls and the realtime statistics produced through the QueueMetrics GUI when the key realtime members_only is equal to true The difference is related to the agents list shown As the list of qu
20. eate JSON see https github com FasterXML jackson while the embedded class java net URLConnection will take care of the connection Perl You can use the JSON module and LWP UserAgent for accessing the remote QM instance Python The json and urllib2 libraries should be immediately available JavaScript NodeJS The http module will take care of the connection while JSON parse will decode the output C Net Can be done natively see example at http msdn microsoft com en us library hh6741 88 aspx PHP You can usually read a remote URL with php_curl and retry the JSON structure with json_decode Here s an example of a GET query with php url http queuemetrics server 8080 queuemetrics agent 73 jsonEditorApi do Sch curl_init curl_setopt ch CURLOPT_CUSTOMREQUEST GET curl_setopt ch CURLOPT_USERPWD username password curl_setopt ch CURLOPT_URL url curl_setopt ch CURLOPT_RETURNTRANSFER true Soutput curl_exec ch curl_close ch print_r json_decode output true Ruby The modules json and open uri are available in the standard library Go Can be done natively leveraging the encoding json and net http packages 23 Chapter 5 Appendix Il QueueMetrics data blocks 5 1 Available blocks for QmStats e AgentsDO ReportAgents AgentsDO SessionPauseDur e AgentsDO AgentAvail e AgentsDO AnsCallsQueues e AgentsDO AnsCallsCG e AgentsDO
21. ent agent 101 amp queues ql q2 amp form MyForm amp block QualAssFormDO FormStructure amp block QualAssFormDO SectionValues amp block QualAssFormDO Comments Parameters queues one or more queues separated by the pipe symbol e from the beginning of the reporting period in date time format to the end period agent the agent code to be used as a filter e form the form you want to report on grader the grader type block One or more data blocks that you need to access Parameters marked with an asterisk are mandatory Allowed data blocks QualAssFormDO Quality Assessment information related to QA Forms Method Description FormStructure The data structure of specified form SectionValues Raw QA values for each section in forms matching the query Comments Comments associated to forms matching the query 4 3 3 QA form summaries QnQaFormSummary This method is very similar to QmStats but it s used to retrieve aggregated information about a specific Quality Assessment Form The report counts the aggregated QA statistics on calls with timestamp included in the date range specified Method QmQaFormSummary Auth required Yes user must hold the key ROBOT XML RPC method QM qaformsummary Available since 14 06 Se aie S Example curl user roborsronbor i H MlConrent lype application sont X GET http localhost 8084 queuemetrics QmOaFormSummary jsonStatsApi do 2000010100 8 010 8
22. eues in use Calls being processed in real time Agents logged in and paused The wallboard top panel The wallboard call list Calls processed Calls taken Call lost Raw agent panel Raw calls panel When exporting blocks it is strongly advisable to use the raw data blocks RtAgentsRaw and RtCallsRaw as they are O easier to parse For a quick reference data blocks are aso listed in Appendix Il of this manual at Section 5 2 Available blocks for QmRealtime 4 1 3 Accessing audio files AmFindAudio This method lets you download audio files and other meta files associated with a call In order to retrieve the file name QM will invoke the currently configured Pluggable Modules to search within the current recording set This can be used by third party software that needs to retrieve audio recordings via HTTP Method QmFindAudio Auth required Yes user must hold the key ROBOT XML RPC method QM findAudio Available since 14 06 CC Example curl user roborsroboc L 4 Comrene 1y98 apoliceatiocn aca X GET http localhost 8084 queuemetrics QmFindAudio jsonStatsApi do id 664745 1 Parameters id the calls UniquelD server mandatory on clustered systems the server id timestamp the time stamp of the call as number of seconds since the epoch agent the agent code queue the queue Parameters marked with an asterisk are mandatory If QM is on a clustered setup the Server parameter mus
23. eues passed through the API does not point to a specific QueueMetrics queue instance it s not possible to correctly tell elementary queues from aggregate queues having the same name In this situation the agent list will always be computed as the union of all agents associated to all elementary queues composing the macro queue even if an existing aggregate queue has a different set of agents assigned to it Method QmRealtime Auth required Yes user must hold the key ROBOT XML RPC method QM realtime Available since 14 06 Example curl user olor solos 1 4 Comeeme UyoSss apalicaitioa Json X GET http localhost 8084 queuemetrics QmRealtime jsonStatsApi do queues ql amp block RealtimeDO RtAgentsRaw amp block RealtimeDO RtCallsRaw Parameters queues one or more queues separated by the pipe symbol e filter the agent filter an agent s name like Agent 101 that must be the filter for all the relevant activity e block the output blocks that have to be exported To specify multiple blocks add multiple times Parameters marked with an asterisk are mandatory Data blocks RealtimeDO Real time information as displayed in the main QM real time page using system defaults The JSON Reports API Method RTRiassunto RTCallsBeingProc RTAgentsLoggedin WallRiassunto WallCallsBeingProc VisitorCallsProc Visitor TodaysOk Visitor TodaysKo RtAgentsRaw RtCallsRaw Description An overview table of the qu
24. he date range specified Method QmQaGrading Auth required Yes user must hold the key ROBOT and the key QA_TRACK XML RPC method QM qaformgrading Available since 14 06 CE AN Example quel user rollos rola H lContent lype application Json X GET http localhost 8084 queuemetrics QmQaGrading jsonStatsApi do calldate 2014 03 30 15 19 00 amp margin 3600 amp id 475263 1 amp form MyForm amp queues ql amp item_CLE 73 amp item_HEL 56 amp comment Comment1 amp comment Comment 2 amp block QualAssFormDO FormStructure amp block QualAssFormDO SectionValues amp block QualAssFormDO Comments Parameters queues the set of queues that must be included in the analysis They must be separated by a symbol if more than one queue is passed The queue name is the internal Asterisk queue name e calldate the beginning of the search period for the call This should be usually a few seconds or minutes before the call was started 18 The JSON Reports API margin This is at least the number of seconds the call was in the waiting status or the complete call time or a suitable number that comfortably contains the call like for example 3600 e form The form name that you need to fill in e id The unique identifier for the call to be graded grader The grader type used to filter out graded forms e item_ The list of QA items score supplied as an hash of item_ prefix see above The l
25. ist should contain all specific form items codes and their relative score In order to specify N A values for not mandatory items an empty string should be specified If the list is left empty no QA score will be filled into the form comment A list of the notes to be filled in the form Each note must be supplied as a String If the list is empty no new comments will be added to the form e block a set of blocks to be returned Possible values are the ones defined in QmQaFormReport Parameters marked with an asterisk are mandatory 4 3 5 Finding calls to grade AmQaCallsToGrade Runs a Grading transaction Method QmQaCallsToGrade Auth required Yes user must hold the key ROBOT XML RPC method QM qacallstograde Available since 14 06 See aso Example curl meeirz roborsronor i H lContent lype application Jeon X GET http localhost 8084 queuemetrics QmOaCallsToGrade jsonStatsApi do rom 20001 One O OOO NID amp to 2014 06 30 00 00 00 amp form MyForm amp queues ql q2 block 0AGradingDO qagExtendedProposals amp k_outcome KN min 100 amp k_outcome_KN_num amp k_agroup_Default_min 1 Parameters queues the set of queues that must be included in the analysis They must be separated by a symbol if more than one queue is passed The queue name is the internal Asterisk queue name from a start date to an end date form the name of the form agent an optional agen
26. ll also return the composite queues the agent is known on and the level he s scheduled on them Method QmAgentQueues Auth required Yes user must hold the key ROBOT XML RPC method QM getQueuesForAgent Available since 14 06 See also Example curl user roborsronoc i H Conmreane Iyses application Json X GET http localhost 8084 queuemetrics QmAgentQueues jsonStatsApi do agent Agent 101 Parameters e agent the agent code we want to retrieve Parameters marked with an asterisk are mandatory Response If the agent code is unknown an exception is raised There is only one response block returned named output where the caller will retrieve all user data including the live key set for that user The output block has the format 2 Explanation as follows Column zero contains the agent code Column one contains the queue or composite queue it is known for These are a set of the queues as they are known in Asterisk They are separated by either a space or a vertical pipe symbol Column two contains the name that such queue s appear in the QM interface Column three contains the agent level as per 0 Main no penalty 1 Wrap some penalty e 2 Spill highest penalty 4 2 4 The available pause codes for an agent QmAgentPCodes Get the current association of agents to queues 14 The JSON Reports API Given an agent e g Agent 101 the caller gets back a se
27. ol 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 kel user solo solo i H Monrentr Ilyoes aplicar ioa Json X GET http qmserver 8080 queuemetrics agent jsonEditorApi do The result is a human readable data structure that describes configured agents For example KY loop meine 3 Deramlr PK TD TARIA AIO catkonr a as a E group_by 9 ye al r descr_agente John Doe 101 chiave_agente Moe mame eM Ame UE LL Q wee A Weoo LEONU E elsa ja real_name Super Visor emperyisesa ly 2 HAINE eur iceSicmaliog lL MU nome_agente agent 101 What is JSON amoo ales NS Ent 101 tcs serys 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 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 Make sure you remember to enable the user robot in QueueMetrics or have an equivalent user you can login as usr bin env ruby require json require open uri Settings edit as needed url http 127 0 0 1 8084 queuemetrics apicall agent js
28. onEditorApi do login roor ass NE CE CIE call the JSON method replyHttp open url apicall http basic authentication gt 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 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 Ciel The result is a set of records each of which describes one agent configured For example 1099 zolo 1 Comes 1908 E application json X GET http 127 0 0 1 8084 queuemetrics agent jsonEditorApi do group_name PK TD 2 Mon AE OCALENIA Moca Jo wa Wi descr_agente chiave_agente MA loc_name OO EL Horou Leom real_name n r supervised_by current_terminal nome agente Samoa alli Default f F Won Das ALOL lelsiauie joing HSE AUS OMS TASEI we vagent ione agent101 chatserver oo mote ecos Eolo gt 45 6 You can see that each re
29. 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 Gurl user robots robot Content Type apjolicacioen json X GET http 127 0 0 1 8084 queuemetrics agent 71 jsonEditorApi do gt agent71 json You would then edit it and save it again as in Quel Mseiz olor soso i H MContent lype application Jeon X POSI CCE CENEMPSIS CIN 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 The JSON Configuration API 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 Gurl usez robor robor i i Comeeme Myoes spplicatrtion json X POST d new_agent json http 127 0 0 1 8084 queuemetrics agen
30. t jsonEditorApi do 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 olor solo i h Comuecne Iyoss aalicar ica eo 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 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 us r rollo solo i h Concent yes applicartion somu X GET http 127 0 0 1 8084 queuemetrics reportScreen 8 jsonEditorApi do parent 7 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
31. t be passed to qualify the Asterisk call id Some PM may optionally require the Call start Agent and Queue parameters those are used for fuzzy matching of calls e g on an external storage Most PMs that do an exact match do not need those parameters Response There is only one response block returned named AudioFiles where the caller will retrieve the filename of each recorded file and a URL to actually download the file The response may include zero or more files it is possible that multiple recordings are present for the same call e g because they are of different media type or because recordings were started and ended multiple times 4 1 4 Inserting and retrieving call tags QminsertTag This method is used to associate a new tag for a specific recording call file This method is used to retrieve the list of tags related to a specific call 10 The JSON Reports API By leaving the message empty no new tag will be added but a list of existing tags for a specific calls can be retrieved Method QminsertTag Auth required Yes user must hold the key ROBOT and CALLMONITOR_ADDTAGS XML RPC method QM insertRecordTag Available since 14 06 Sesso Example curl usger robor robot L i Comrene 1y9es apolicaitnoa aca X GET http localhost 8084 queuemetrics OmInsertTag jsonStatsApi do id 664745 1 amp filename abcd wav amp time 5 amp duration 7 message Thististattag amp color FF0000 Parameters
32. t code to be used as a filter k_ ahash of constrainsts used to find calls see below block one or more response blocks Parameters marked with an asterisk are mandatory Understanding constraints Constraints are a set of key value pairs used by the engine to filter out the calls to be graded The constraint list should be defined with the proper syntax in order to be correctly interpreted by QueueMetrics There are two types of constraints the percentage values and the absolute values They should be respectively specified through the suffixes min or num The constraints are related to different categories e Individual agents specified through the key AXG like for example AGX_min or AGX_num 19 The JSON Reports API e All calls specified through the key AC like for example AC_ min or AC_num Outcome code specified through the key outcome followed by the outcome code and separated by an underscore character like for example outcome_KN_num or outcome_KN_min Agent group specified through the key agroup followed by the agent group name and separated by an underscore character like for example agroup_Default_min or agroup_Default_num Data Blocks QAGradingDO Quality Assessment information related to calls to be graded Method qagExtendedProposals 4 4 Tasks Tasks have two concepts that you have to keep in mind when accessing them through the API Description The set of calls
33. t of pause codes and their description as it would be visible to this agent As QM allows protecting pause codes with security keys so that e g you can have some pauses visible by some users only QM computes the set of allowed pause from the point of view of the agent Method QmAgentPCodes Auth required Yes user must hold the key ROBOT XML RPC method QM getPauseCodesForAgent Available since 14 06 seeaso ON Example curl user zobors robot L 4 Comeeme lyoSee apolication sont X GET http localhost 8084 queuemetrics QmAgentPCodes jsonStatsApi do agent Agent 101 Parameters e agent the agent code we want to retrieve Parameters marked with an asterisk are mandatory Response If the agent code is unknown an exception is raised There is only one response block returned named output where the caller will retrieve all user data The output block has the format Agent 101 Coffee break NPNB Explanation as follows Column 0 contains the agent code Column 1 contains the pause code as should be reported in Asterisk Column 2 is the description Column 3 is the pause type PB pause is payable and billable PNB pause is payable but not billable NPB pause is not payable but billable unlikely NPNB pause is neither payable nor billable 4 3 Quality Assessment QA 4 3 1 Retrieving QA statistics QmQaReport This method is very similar to QM stats but it s used to retrie
34. tle Hello message Hello World amp notes notesther amp date 2014 05 09 10 30 00 amp duration 300 Parameters e recipient the login of the user receiving the task e valid_from begin of validity in long date format See above e valid_to end of validity e process usually in the form ProcessFamily ProcessiD See above message the message associated with the task 21 The JSON Reports API notes an optional note date a date and time for the meeting e duration the duration of the meeting in seconds Parameters marked with an asterisk are mandatory 4 5 System administration 4 5 1 Updating the activation key QmSetActivationKey This method is used to remotely change the license key of the QueueMetrics instance or to query the current license key As this operation is potentially critical the user sending this request must hold the keys ROBOT and KEYUPDATE We ship such a user named keyupdater in the default QM configuration but it has to be manually enabled Make sure you change the password as well As the system must be restarted after setting the new key so that it is picked up this is done automatically the QM server may be unavailable for a few seconds during the restart phase and all current user sessions may be forcibly terminated It is therefore not advisable to run this command on a busy system with many users logged in Auth required Yes user must hold the key ROBO
35. to act as a filter may be empty supervisor a supervisor login to act as a filter may be empty The message will be broadcast to people reporting to that supervisor agent a specific destination agent may be empty The message will be addressed to the specified agent everyone set to 1 to have the message delivered to everyone Parameters marked with an asterisk are mandatory 4 2 Authentication and agent information 4 2 1 Checking logins QmAuth This method is used to authenticate a username password set against the QueueMetrics server This can be used by third party software that does not want to keep its own separate user database but wants to use QueueMetrics instead Method QmAuth XML RPC method QM auth Available since 14 06 Example euel user robor robot 1 Hh Comrecnr 1y982 apollicai 1ion sont X GET http localhost 8084 queuemetrics QmAuth jsonStatsApi do Parameters None You only pass the authentication Response The call will return one single block named auth This block contains the following information e UserName the login name e Status OK if authentication was accepted or ERR if it was refused FullName The user s full name e Email The user s email address e Class The name of the class the user belongs to Keys The active key set of the user that is all keys given to the class plus or minus the keys that have been granted or revoked to this specific user
36. ueMetrics JSON Reports API share a common set of guidelines e All requests must contain a valid QueueMetrics username and password supplied as HTTP Basic auth They will usually require a user holding the key ROBOT and may require additional security keys where appropriate Both GET and POST requests are allowed note that GET requests may have a size limit while there is basically none for POST Whenever multiple parameters are allowed for example when querying for multiple data blocks the same parameter is repeated multiple times In case you need to pass the API an associative array hash all keys within the hash have a common prefix E g an array like A 1 B 2 which common prefix is defined as k_ should be passed as k_A 1 amp k_B 2 All dates are to be written exactly in the format 2000 01 01 00 00 00 Make sure you do not forget the dot between the day and the hour The result of all API Reports is a hash made up of blocks that is an array of rows each of which is an array of strings Usually the first row of each block contains the titles for subsequent rows It is mandatory when reading data to check which column contains the title you are looking for as different versions of QueueMetrics might report columns in a different order e There is always a block called result that specifies whether the operation completed successfully or failed the time it took to complete and a stack trace of the error if any
37. ve Quality Assessment statistics Method QmQaReport Auth required Yes user must hold the key ROBOT XML RPC method QM qareport Available since 14 06 CC AN Example curl user olor solos 1 sa Comren 1y982 apolicarion Json 15 The JSON Reports API X GET http localhost 8084 queuemetrics QmQaReport jsonStatsApi do from 2000 01 01 00 00 00 amp to 2015 01 01 00 00 00 amp queues ql q2 amp form MyForm amp block QualAssDO TrkCalls amp block QualAssDO Res1 Parameters queues one or more queues separated by the pipe symbol e from the beginning of the reporting period in date time format e to the end period agent the agent code to be used as a filter e form the form you want to report on grader the grader type block One or more data blocks that you need to access Parameters marked with an asterisk are mandatory Allowed data blocks QualAssDO Method Description TrkCalls Tracked calls per agent report TrkCallsQ Tracked calls per queue report CallSupervs Supervisors tracking calls report Res1 Section 1 as defined in the form calls by agent report Res1Q Section 1 as defined in the form calls by queue report Res2 Section 2 as defined in the form calls by agent report Res2Q Section 2 as defined in the form calls by queue report Res3 Section 3 as defined in the form calls by agent report Res3Q Section 3 as defined in the form calls by queue report
Download Pdf Manuals
Related Search