Agent Adherence Detail

API Specification

Description	Creates a task for workmanager to execute exportEngine for Agent Adherence Detail.
Authentication Required	Yes
URL	https://<domain or IP>/SMARTSync/services/rs/exporters/v1/agent-adherence-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: true.

Notes: is not case sensitive.

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

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

Required: Only for PIPE outputFormat.

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.

attribute - String.

Represents activity code attribute.

Required: false.

Notes:

If attribute is defined, the attribute value must be present in the database.
If attribute is not defined, "EXC_EXPORT" will be considered as the default value for the attribute and if this attribute value is not present in DB, validation error "Missing default attribute value: 'EXC_EXPORT'" will be returned in the response. Otherwise, the results will be based on the default attribute.

keepEmptyJsonFields - Boolean field.

Required: false.

Notes: This field can only be set if outputFormat is set to JSON. By default it is set to 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 set to 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":"custID"}, {"name":"muID"}, {"name":"tvID"}, {"name":"date"}, {"name":"period"}, {"name":"TZ"}, {"name":"acdID"}, {"name":"logonID"}, {"name":"ssn"}, {"name":"agentName"}, {"name":"modify"}, {"name":"externalID"}," +
{"name":"totalAct"}, {"name":"totalInAdh"}, {"name":"totalOutAdh"}, {"name":"totalSched"}, {"name":"adhPct"}

Simple fields when outputFormat is JSON:

{"name":"custID"}, {"name":"muID"}, {"name":"tvID"}, {"name":"date"}, {"name":"period"}, {"name":"TZ"}, {"name":"acdID"}, {"name":"logonID"}, {"name":"personalID"}, {"name":"agentName"}, {"name":"modify"}, {"name":"externalID"}," +
{"name":"totalAct"}, {"name":"totalInAdh"}, {"name":"totalOutAdh"}, {"name":"totalSched"}, {"name":"adhPct"}

Notes:

In the fields array parameter, the output fields ssn may be used for PIPE output. But it must be replaced with personalId, if JSON output is used.
Only one field with the same name can be present in the fields array.

Field with multi value:

{"name":"agentData","value":"value1"}, {"name":"agentData","value":"value2"}

Note: agentData value should exists in DB.

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 outputFormat value: 'wrongFormat'", "Invalid dateFormat value: 'wrongDateFormat'", "Invalid timeFormat value: 'wrongTimeFormat'", "startDate must match the provided yyyy-MM-dd format", "endDate must match the provided yyyy-MM-dd format", "Insufficient permissions to view entities 'MU 8888'", "Invalid entity: 'MU 1234567'", "Invalid agentData value within fields element: wrongAgent", "Duplicate fields with same attribute value within fields: logonID,acdID" ] } 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-adherence-detail request body(request for all fields): { "outputFormat":"PIPE", "dateFormat":"mmddyy", "timeFormat":"12", "startDate":"2023-11-21", "endDate":"2023-11-21", "muIds": [ 100 ], "excludePipeHeader":true, "attribute" : "Adherence" } request body (request for specific fields): { "outputFormat":"PIPE", "dateFormat":"DDMMYYYY", "timeFormat":"12", "startDate":"2024-01-01", "endDate":"2024-01-01", "attribute" : "Adherence", "muIds": [ 100 ], "excludePipeHeader":false, "fields": [ { "name":"date" }, { "name":"TZ" }, { "name":"custID" }, { "name":"muID" },
	{ "name":"acdID" }, { "name":"logonID" }, { "name":"totalAct" }, { "name":"totalInAdh" }, { "name":"totalOutAdh" }, { "name":"totalSched" }, { "name":"adhPct" }, { "name":"externalID" } ], "sortOrder": [ { "name":"date" }, { "name":"logonID" }, { "name":"totalAct" }, { "name":"totalInAdh" },
	{ "name":"totalOutAdh" }, { "name":"totalSched" }, { "name":"adhPct" }, { "name":"externalID" } ] }
Sample Call for JSON outputFormat	https://localhost/SMARTSync/services/rs/exporters/v1/agent-adherence-detail request body(request for all fields): { "outputFormat":"JSON", "dateFormat":"mmddyy", "timeFormat":"12", "startDate":"2023-11-21", "endDate":"2023-11-21", "muIds": [ 100 ], "keepEmptyJsonFields":true, "attribute" : "Adherence" }
	request body (request for specific fields): { "outputFormat":"JSON", "dateFormat":"DDMMYYYY", "timeFormat":"12", "startDate":"2024-01-01", "endDate":"2024-01-01", "muIds": [ 100 ], "keepEmptyJsonFields":false, "attribute":"Adherence", "fields": [ { "name":"date" }, { "name":"TZ" }, { "name":"custID" }, { "name":"muID" }, { "name":"acdID" }, { "name":"logonID" }, { "name":"totalAct" }, { "name":"totalInAdh" },
	{ "name":"totalOutAdh" }, { "name":"totalSched" }, { "name":"adhPct" }, { "name":"externalID" } ], "sortOrder": [ { "name":"date" }, { "name":"logonID" }, { "name":"totalAct" }, { "name":"totalInAdh" }, { "name":"totalOutAdh" }, { "name":"totalSched" }, { "name":"adhPct" }, { "name":"externalID" } ] }

Output Field Descriptions

This export runs for each MU specified in the muIds list.
If the export is run 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.
If the attribute parameter is defined, the value assigned to each activity code for the specified activity code attribute is used for the output file’s exception field. If the attribute parameter does not exist, the attribute named EXC_EXPORT is used.
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.
Activity records for agents with multiple logon IDs are automatically merged for the calculation of adherence. If an agent has activity for more than one ACD logon for any time, the export uses the activity with the higher priority for the overlapping times. Priority of each activity code is defined on the Activity Code Definition view. The lowest number is the highest priority.
R7.4.3 and later: To use this export with 1-second precision, contact NICE WFM Support to set the customer property for this option. If 1-second precision is enabled, this export shows time data accurate to the second.

You can generate the export for the current date. The data stops at the last completed interval. Future intervals do not impact the adherence calculation output.

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 Adherence Detail output can include these fields:

Field	Description	Values
date	This date is based on the MU’s time zone. 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 agent’s highest-priority ACD for the associated schedule date. The highest-priority ACD is the one with the lowest priority number.
logonID	The agent’s highest-priority ACD logon ID for the associated schedule date. The highest-priority ACD is the one with the lowest priority number.	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	Formatted as a UNIX timestamp, this represents the time, using the server’s time zone, the adherence values were last calculated and the record was exported. Note: Adherence values are not stored in the database. Using a last modified field from a database record is not feasible because: the schedule record may have changed since the last export the activity record may have changed since the last export both the schedule and activity records may have changed since the last export the activity code adherence attribute values may have changed since the last export Adherence exclusions may have been added since the last export Therefore, the current date/time of the export is used as the modify field
totalAct	The total number of seconds the agent was signed on during the period. If the agent was signed on to more than one ACD simultaneously, this is the total from the highest priority activity code in each minute.
totalInAdh	The total number of seconds the agent was in adherence during the period.
totalOutAdh	The total number of seconds the agent was out of adherence during the period.
totalSched	The total number of seconds the agent was scheduled during the period.
adhPct	The agent’s adherence percentage during the period. This value is calculated by dividing the totalInAdh value by the totalSched value.	0.00-100.00
externalID	The ID the agent uses to log in to the Agent WebStation if the WebStation is configured to use external IDs.	If the agent's externalID field is blank, this field is blank.

Supported output formats:

PIPE
JSON

PIPE output with results and headers

View code

var(--codeSnippetCopyLabel)

#fields:date|period|TZ|custID|muID|tvID|acdID|logonID|ssn|agentName|modify|totalAct|totalInAdh|totalOutAdh|totalSched|adhPct|externalID
#sort:date,period,TZ,custID,muID,tvID,acdID,logonID,ssn,agentName,modify,totalAct,totalInAdh,totalOutAdh,totalSched,adhPct,externalID
 
01012024|08:00AM|Asia/Calcutta|1|100|101|1|101||last101,|1704047400|0|0|900|900|0.00|
01012024|08:00AM|Asia/Calcutta|1|100|102|1|102||last102,|1704047400|0|0|900|900|0.00|

PIPE output with results and no headers

View code

var(--codeSnippetCopyLabel)

01012024|08:00AM|Asia/Calcutta|1|100|101|1|101||last101,|1704047400|0|0|900|900|0.00|
01012024|08:00AM|Asia/Calcutta|1|100|102|1|102||last102,|1704047400|0|0|900|900|0.00|

PIPE with empty result and disabled header

View code

var(--codeSnippetCopyLabel)

JSON output with results and empty fields

View code

var(--codeSnippetCopyLabel)

[
  {
    "date": "01012024",
    "period": "08:00",
    "TZ": "Asia/Calcutta",
    "custID": "1",
    "muID": "100",
    "tvID": "101",
    "acdID": "1",
    "logonID": "101",
    "personalID": "",
    "agentName": "last101,",
    "modify": "2023-12-31T18:30:00Z",
    "totalAct": "0",
    "totalInAdh": "0",
    "totalOutAdh": "900",
    "totalSched": "900",
    "adhPct": "0.00",
    "externalID": ""
  },
  {
    "date": "01012024",
    "period": "08:00",
    "TZ": "Asia/Calcutta",
    "custID": "1",
    "muID": "100",
    "tvID": "102",
    "acdID": "1",
    "logonID": "102",
    "personalID": "",
    "agentName": "last102,",
    "modify": "2023-12-31T18:30:00Z",
    "totalAct": "0",
    "totalInAdh": "0",
    "totalOutAdh": "900",
    "totalSched": "900",
    "adhPct": "0.00",
    "externalID": ""
  }
]

JSON output with non-empty fields

View code

var(--codeSnippetCopyLabel)

[
  {
    "date": "01012024",
    "period": "08:00",
    "TZ": "Asia/Calcutta",
    "custID": "1",
    "muID": "100",
    "tvID": "101",
    "acdID": "1",
    "logonID": "101",
    "agentName": "last101,",
    "modify": "2023-12-31T18:30:00Z",
    "totalAct": "0",
    "totalInAdh": "0",
    "totalOutAdh": "900",
    "totalSched": "900",
    "adhPct": "0.00"
  },
  {
    "date": "01012024",
    "period": "08:00",
    "TZ": "Asia/Calcutta",
    "custID": "1",
    "muID": "100",
    "tvID": "102",
    "acdID": "1",
    "logonID": "102",
    "agentName": "last102,",
    "modify": "2023-12-31T18:30:00Z",
    "totalAct": "0",
    "totalInAdh": "0",
    "totalOutAdh": "900",
    "totalSched": "900",
    "adhPct": "0.00"
  }
]

JSON output with empty results

View code

var(--codeSnippetCopyLabel)

[]

Agent adherence detail DTD

View code

var(--codeSnippetCopyLabel)

<?xml version="1.0"?>
<!ELEMENT agentAdherenceDetail ((allFields | fieldList), sortOrder?)>
<!ELEMENT fieldList (fields)>
<!ELEMENT sortOrder (fields)>
<!ELEMENT fields (date | period | TZ | custID | muID | tvID | acdID | logonID | ssn
| agentData | agentName | modify | totalAct | totalInAdh | totalOutAdh | totalSched
| adhPct | externalID)+>
<!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 totalAct EMPTY>
<!ELEMENT totalInAdh EMPTY>
<!ELEMENT totalOutAdh EMPTY>
<!ELEMENT totalSched EMPTY>
<!ELEMENT adhPct EMPTY>
<!ELEMENT externalID EMPTY>