Agent Results Detail

API Specification

Description	Creates a task for workmanager to execute exportEngine for Agent Results Detail exporter.
Authentication Required	Yes
URL	https://<domain or IP>/SMARTSync/services/rs/exporters/v1/agent-results-detail
Method	POST
Request Headers	Cookie: JSESSIONID={jsessionId} Content-Type: application/json
Request Params	(See below)

API Specification: Request Params

startDate - String, format: YYYY-MM-YY

Required: true.

Notes: cannot be after the endDate.

endDate - String, format: YYYY-MM-YY

Required: true.

Notes: cannot be before the startDate.

outputFormat - String, supported formats: PIPE, JSON

Required: for PIPE -required, for JSON - optional.

Notes: is not case sensitive.

dateFormat - String, possible values: mmddyy, ddmmyy, mmddyyyy, ddmmyyyy, yyyymmdd, yyyyddmm, yyddmm, yymmdd.

If the fields were not provided and outputFormat is set to JSON, all date fields will be converted to ISO date format.

Required: Only for PIPEoutputFormat.

Notes: is not case sensitive. Determines format of output dates.

timeFormat - String, possible values: 12, 24.

Determines format of output times.

Required: true.

Notes: is not case sensitive.

muIds - Array of integers.

Should be one or more IDs user has permission to use.

Required: true.

Notes: is not case sensitive.

keepEmptyJsonFields - Boolean field.

Required: false.

Notes: This field can only be set if outputFormat is set to JSON. By default it is false. If it is set to true, the JSON output will contain empty values ({},[],"") for fields.

excludePipeHeader - Boolean field.

Required: false.

Notes: This field can only be set if outputFormat is PIPE. By default it is false. If it is set to true, headers will be excluded from PIPE output.

fields - Array of objects.

Represents the list of the supported field names, fields with attribute values, and fields with specified value. All field names, attributes and values are not case sensitive.

Required: false.

Possible values:

Simple fields when outputFormat is PIPE:

{"name":"date"}, {"name":"period"}, {"name":"TZ"}, {"name":"custID"}, {"name":"muID"}, {"name":"tvID"}, {"name":"acdID"}, {"name":"logonID"}, {"name":"ssn"}, {"name":"agentName"}, {"name":"modify"}, {"name":"queueID"}, {"name":"queueName"},

{"name":"contactsHandled"}, {"name":"outContacts"}, {"name":"logonTime"}, {"name":"talkTime"}, {"name":"workTime"}, {"name":"outTime"}, {"name":"externalID"}, {"name":"holdTime"}, {"name":"readyTime"}, {"name":"notReadyTime"}, {"name":"dnContacts"}, {"name":"dnContactTime"}, {"name":"internalContacts"}, {"name":"internalContactTime"}

Simple fields when outputFormat is JSON:

{"name":"date"}, {"name":"period"}, {"name":"TZ"}, {"name":"custID"}, {"name":"muID"}, {"name":"tvID"}, {"name":"acdID"}, {"name":"logonID"}, {"name":"personalID"}, {"name":"agentName"}, {"name":"modify"}, {"name":"queueID"}, {"name":"queueName"},

Note:

In the fields array parameter, the output field ssn may be used for PIPE output.
For JSON output ssn must be replaced with personalID.
Only one field with the same name can be present in the fields array.

sortOrder - Array of objects.

Represents the list of the supported field names, fields with attribute values, and fields with specified value. All field names, attributes, and values are not case sensitive.

Required: false.

Possible values: the same values as for fields.

API Specification (cont)

Response Data	Response has a unique JobId: jobId is a 32 length string. Example { "jobId":"9b2fe7bb8362429fb85a16c9373cf50c" }
Response Headers	Content-Type: application/json
Success Response	Code: 200 OK Content : [Response Data]
Error Response	Code: 401 Unauthorized Error message: { "message":"Unauthorized", "status":401 } Code: 400 Bad Request All fields are invalid: { "message":"One or more request validations failed", "status":400, "details": [ "Invalid field: 'keepEmptyJsonFields'", "Invalid field: 'excludePipeHeader'", "Invalid outputFormat value: 'XML'", "Invalid dateFormat value: 'ddmmcyyyy'", "Invalid timeFormat value: '1c2'", "startDate must match the provided yyyy-MM-dd format", "endDate must match the provided yyyy-MM-dd format", "Insufficient permissions to view entities 'MU -1'", "Invalid entity: 'MU 1234567'", "Invalid values within fields element: wrongField2,wrongField1" ] } Start date>end date { "message":"One or more request validations failed", "status":400, "details": [ "endDate must be either equal to or after the startDate" ] } Code: 500 Internal server error
Sample Call for PIPE outputFormat	https://localhost/SMARTSync/services/rs/exporters/v1/agent-results-detail request body(request for all fields): { "startDate":"2023-11-10", "endDate":"2024-11-10", "outputFormat":"PIPE", "dateFormat":"ddmmyyyy", "timeFormat":"12", "muIds":[ 500 ] } request body(request for specific fields): { "startDate":"2022-11-10", "endDate":"2022-11-10", "outputFormat":"PIPE", "dateFormat":"ddmmyyyy", "timeFormat":"12", "muIds":[ 500 ], "fields":[{"name":"custID"}, {"name":"TZ"}], "sortOrder":[{"name":"custID"}, {"name":"TZ"}]
Sample Call for JSON outputFormat	https://localhost/SMARTSync/services/rs/exporters/v1/agent-results-detail request body(request for all fields): { "startDate":"2023-11-10", "endDate":"2024-11-10", "outputFormat":"JSON", "dateFormat":"ddmmyyyy", "keepEmptyJsonFields":true, "timeFormat":"12", "muIds":[ 500 ] } request body(request for specific fields): { "startDate":"2022-11-10", "endDate":"2022-11-10", "outputFormat":"JSON", "dateFormat":"ddmmyyyy", "timeFormat":"12", "keepEmptyJsonFields":true, "muIds":[ 500 ], "fields":[{"name":"custID"}, {"name":"TZ"}], "sortOrder":[{"name":"custID"}, {"name":"TZ"}] } }

Output Field Descriptions

This export runs for each MU specified in the muIds list.
If the export runs for multiple MUs, all the data is saved in the same output file.
For each date in the range specified, the Activity data is read for each agent that belongs to the MU being processed for the date being processed.
Agent data group values assigned to the agent for the date being processed are exported. Agent data group values are stored by date range and are not dependent on the agent’s MU assignment.

Note: Since R7.x increased the name lengths allowed for some entities, and the agent results data is stored by interval, the memory required to store the agent results detail data increased. Running this exporter for large date ranges may cause the CPU to run out of memory for the storage needed for processing and sorting the agent results detail records. If this happens, you should run the exporter for a shorter date range or fewer MUs.

This export uses the MU time zone setting. The export does not differentiate between the duplicate periods that occur on the Daylight Saving Time (DST) date. It does not show which of the duplicate periods occurred first on a DST date with multiple entries for the same period.

The Agent Results Detail output can include these fields:

Field	Description	Values
date	The date, based on the MU’s time zone. The format of the date is specified in the dateFormat parameter. If no dateFormat is provided, then the format defaults to mmddyyyy if the outputFormat is PIPE. If the outputFormat is JSON, then dates default to ISO 8601 format. If the outputFormat is XML, the format is always a fixed XML structure.
period	The start time of the period, based on the MU’s time zone. The format of this time is specified in the timeFormat attribute. If no timeFormat attribute exists, 24-hour format is used for the times.
TZ	The MU’s time zone.
custID	The customer ID.
muID	The ID of the MU.
tvID	The agent’s WFM ID.
acdID	The ID of the ACD or multimedia server for which data are being exported.
logonID	The agent’s logon ID for the ACD or multimedia server being exported.	It is possible for this field to be blank.
ssn	The agent’s personal ID number. For JSON output, personalId is used instead	This field is blank if no personal ID number is assigned to the agent.
agentData	This multi-value field exports the value(s) assigned to the agent for each agent data group specified in the "value" attribute of the agentData field. You can include as many agentData elements as you want; one agent data group is printed in the output file for each agentData value defined. You can specify the same agent data group more than once. If you do not include an agentData element, this field is omitted.	This field may be blank if the agent is not assigned a value for the specified agent data group for the date being processed.
agentName	The agent’s name, formatted as <last>, <first><suffix>.
modify	The record’s modify timestamp.
queueID	The ID of the queue or skill for which data are being exported. Records are included for each queue or skill for which the agent has data.
queueName	The name of the queue or the skill.
contactsHandled	The total number of contacts the agent handled for the queue or skill on the date being processed.
outContacts	The total number of outbound contacts the agent handled for the queue or skill on the date being processed. System level data such as outContacts are included in only one record per acdID. The queueID associated with the agent, through skill mapping within the WFM system, and with the lowest ID on the acdID is the record whose system-level fields are populated. Records in the output file with other queueIDs have null values for system level data.
logonTime	The total amount of logon time, in seconds, associated with the queue or skill for the date. System level data such as logonTime is included in only one record per acdID. The queueID associated with the agent, through skill mapping within the WFM system, and with the lowest ID on the acdID is the record whose system-level fields are populated. Records in the output file with other queueIDs have null values for system level data.
talkTime	The agent’s total talk time, in seconds, for the queue or skill for the date.
workTime	The agent’s total work time, in seconds, for the queue or skill for the date.
outTime	The agent’s total outbound talk time, in seconds, for the queue or skill for the date. System level data such as outTime is included in only one record per acdID. The queueID associated with the agent, through skill mapping within the WFM system, and with the lowest ID on the acdID is the record whose system-level fields are populated. Records in the output file with other queueIDs have null values for system level data.
externalID	The ID the agent uses to log in to Agent WebStation, if the WebStation is configured to use external IDs.	If the agent’s externalID field is blank, this field is blank.
holdTime	The agent’s hold time, in seconds, for the queue for the date.	The value in this field is an actual value from the ACD or multimedia server database. Note: If the value is not present or appropriate, you may contact NICE WFM Support to determine if your ACD or multimedia server is capable of providing the value directly from the ACD or multimedia server database. Professional service fees may apply to modify the ACD or multimedia server integration and interface.
readyTime	The agent’s ready or available time, in seconds, for the date. System level data such as readyTime is included in only one record per acdID. The queueID associated with the agent, through skill mapping within the WFM system, and with the lowest ID on the acdID is the record whose system-level fields are populated. Records in the output file with other queueIDs have null values for system level data.
notReadyTime	The agent’s idle, AUX or not ready time (in seconds) for the date. System level data such as notReadyTime is included in only one record per acdID. The queueID associated with the agent, through skill mapping within the WFM system, and with the lowest ID on the acdID is the record whose system-level fields are populated. Records in the output file with other queueIDs have null values for system level data.	The value in this field is one of these: a derived value that NICE WFM calculates using information from the ACD or multimedia server interface an actual value from the ACD or multimedia server database Note: If the derived value is not appropriate, you may contact NICE WFM Support to determine if your ACD or multimedia server is capable of providing the value directly from the ACD or multimedia server database. Professional service fees may apply to modify the ACD or multimedia server integration and interface.
dnContacts	The number of direct dialed contacts the agent handled on the date. A direct dialed contact occurs when the caller dials the actual extension of a specific agent and is not queued to a group of agents. System level data such as dnContacts are included in only one record per acdID. The queueID associated with the agent, through skill mapping within the WFM system, and with the lowest ID on the acdID is the record whose system-level fields are populated. Records in the output file with other queueIDs have null values for system level data.	The value in this field is one of these: blank, if the ACD or multimedia server does not store direct dialed contacts an actual value from the ACD or multimedia server database Note: If the blank value is not appropriate, you may contact NICE WFM Support to determine if your ACD or multimedia server is capable of providing the value directly from the ACD or multimedia server database. Professional service fees may apply to modify the ACD or multimedia server integration and interface.
dnContactTime	The agent’s talk time for direct dialed contacts handled on the date. System level data such as dnContactTime is included in only one record per acdID. The queueID associated with the agent, through skill mapping within the WFM system, and with the lowest ID on the acdID is the record whose system-level fields are populated. Records in the output file with other queueIDs have null values for system level data.	The value in this field is one of these: blank, if the ACD or multimedia server does not store direct dialed contact talk time an actual value from the ACD or multimedia server database Note: If the blank value is not appropriate, you may contact NICE WFM Support to determine if your ACD or multimedia server is capable of providing the value directly from the ACD or multimedia server database. Professional service fees may apply to modify the ACD or multimedia server integration and interface.
internalContacts	The number of internal calls handled by the agent for the date. An internal contact occurs when an agent contacts another agent, a supervisor, or some other resource. System level data such as internalContacts is included in only one record per acdID. The queueID associated with the agent, through skill mapping within the WFM system, and with the lowest ID on the acdID is the record whose system-level fields are populated. Records in the output file with other queueIDs have null values for system level data.	The value in this field is one of these: blank, if the ACD or multimedia server does not store internal contacts an actual value from the ACD or multimedia server database Note: If the blank value is not appropriate, you may contact NICE WFM Support to determine if your ACD or multimedia server is capable of providing the value directly from the ACD or multimedia server database. Professional service fees may apply to modify the ACD or multimedia server integration and interface.
internalContactTime	The agent’s talk time for internal contacts handled on the date. System level data such as internalContactTime is included in only one record per acdID. The queueID associated with the agent, through skill mapping within the WFM system, and with the lowest ID on the acdID is the record whose system-level fields are populated. Records in the output file with other queueIDs have null values for system level data.	The value in this field is one of these: blank, if the ACD or multimedia server does not store internal contact talk time an actual value from the ACD or multimedia server database Note: If the blank value is not appropriate, you may contact NICE WFM Support to determine if your ACD or multimedia server is capable of providing the value directly from the ACD or multimedia server database. Professional service fees may apply to modify the ACD or multimedia server integration and interface.

Supported output formats:

Pipe delimited
JSON

JSON results with non-empty fields

View code

var(--codeSnippetCopyLabel)

[
  {
    "date": "01012023",
    "period": "17:45",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "muID": "500",
    "tvID": "500",
    "acdID": "500",
    "personalID": "agent",
    "agentName": "agentName",
    "modify": "2022-10-07T09:45:35Z",
    "dnContactTime": "0",
    "internalContacts": "0"
  }
]

JSON results with empty fields

View code

var(--codeSnippetCopyLabel)

[
  {
    "date": "01012023",
    "period": "17:45",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "muID": "500",
    "tvID": "500",
    "acdID": "500",
    "logonID": "",
    "personalID": "agent",
    "agentName": "agentName",
    "modify": "2022-10-07T09:45:35Z",
    "queueID": "",
    "queueName": "",
    "contactsHandled": "",
    "outContacts": "",
    "logonTime": "",
    "talkTime": "",
    "workTime": "",
    "outTime": "",
    "externalID": "",
    "holdTime": "",
    "readyTime": "",
    "notReadyTime": "",
    "dnContacts": "",
    "dnContactTime": "0",
    "internalContacts": "0"
  }
]

JSON empty results

View code

var(--codeSnippetCopyLabel)

[]

PIPE results with enabled headers

View code

var(--codeSnippetCopyLabel)

#fields:date|period|TZ|custID|muID|tvID|acdID|logonID|ssn|agentName|modify|queueID|queueName|contactsHandled|outContacts|logonTime|talkTime|workTime|outTime|externalID|holdTime|readyTime|notReadyTime|dnContacts|dnContactTime|internalContacts|internalContactTime
#sort:custID,muID,tvID,date
 
01012023|17:45|Europe/Kiev|1|500|500|500||agent|agentName|1665135935||||||||||||||0|0

PIPE results with disabled headers

View code

var(--codeSnippetCopyLabel)

01012023|17:45|Europe/Kiev|1|500|500|500||agent|agentName|1665135935||||||||||||||0|0

DTD example

View code

var(--codeSnippetCopyLabel)

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!ELEMENT agentResultsDetail ((allFields | fieldList), sortOrder?) >
<!ELEMENT fieldList (fields)>
<!ELEMENT sortOrder (fields)>
<!ELEMENT fields (date | period | TZ | custID | muID | tvID | acdID | logonID | ssn |
agentData | agentName | modify | queueID | queueName | contactsHandled | outContacts |
logonTime | talkTime | workTime | outTime | externalID | holdTime |
readyTime | notReadyTime | dnContacts | dnContactTime | internalContacts |
internalContactTime )+>
<!ELEMENT allFields EMPTY>
<!ELEMENT date EMPTY>
<!ELEMENT period EMPTY>
<!ELEMENT TZ EMPTY>
<!ELEMENT custID EMPTY>
<!ELEMENT muID EMPTY>
<!ELEMENT tvID EMPTY>
<!ELEMENT acdID EMPTY>
<!ELEMENT logonID EMPTY>
<!ELEMENT ssn EMPTY>
<!ELEMENT agentData (#PCDATA)>
<!ELEMENT agentName EMPTY>
<!ELEMENT modify EMPTY>
<!ELEMENT queueID EMPTY>
<!ELEMENT queueName EMPTY>
<!ELEMENT contactsHandled EMPTY>
<!ELEMENT outContacts EMPTY>
<!ELEMENT logonTime EMPTY>
<!ELEMENT talkTime EMPTY>
<!ELEMENT workTime EMPTY>
<!ELEMENT outTime EMPTY>
<!ELEMENT externalID EMPTY>
<!ELEMENT holdTime EMPTY>
<!ELEMENT readyTime EMPTY>
<!ELEMENT notReadyTime EMPTY>
<!ELEMENT dnContacts EMPTY>
<!ELEMENT dnContactTime EMPTY>
<!ELEMENT internalContacts EMPTY>
<!ELEMENT internalContactTime EMPTY>