Agent Activity Detail

API Specification

Description Creates a task for workmanager to execute exportEngine for Agent Activity Detail exporter.
Authentication
Required 		Yes
URL https://<domain or IP>/SMARTSync/services/rs/exporters/v1/agent-activity-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: 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 convert to ISO date format.

Required: Only for PIPE outputFormat.

Notes: Not case sensitive. Determines format of output dates.

timeFormat - String, possible values: 12, 24. 

Determines format of output times.

Required: True

Notes: Not case sensitive.

muIds - Array of integers.

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

Required: True

Notes: Not case sensitive 

keepEmptyJsonFields - Boolean field.

Required: False

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

excludePipeHeader - Boolean field.

Required:False

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

attribute - String. Represents activity code attribute.

Required: False

Notes:

  • If attribute field is mentioned in the request, the attribute value must be present in the database.
  • If attribute field is not mentioned in the request, "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.

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":"modify"}, {"name":"stop"}, {"name":"TZ"}, {"name":"custID"}, {"name":"muID"}, {"name":"logonID"}, {"name":"exception"}, {"name":"acdID"}, {"name":"ssn"}, {"name":"agentName"}, {"name":"date"}, {"name":"tvID"}, {"name":"start"}, {"name":"externalID"}

Simple fields when outputFormat is JSON: 

{"name":"modify"}, {"name":"stop"}, {"name":"TZ"}, {"name":"custID"}, {"name":"muID"}, {"name":"logonID"}, {"name":"exception"}, {"name":"acdID"}, {"name":"agentName"}, {"name":"date"}, {"name":"personalID"}, {"name":"tvID"}, {"name":"start"}, {"name":"externalID"}

Note: 

  • For JSON output  ssn must be replaced with  personalID.
  • 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 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 attribute value: 'wrongAttribute'",
"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-activity-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
  ],
 "attribute":"Adherence",
 "fields":[{"name":"custID"}, {"name":"TZ"}],
 "sortOrder":[{"name":"custID"}, {"name":"TZ"}, {"name":"agentData","value":"TEST"}]
}
Sample Call for JSON outputFormat

https://localhost/SMARTSync/services/rs/exporters/v1/agent-activity-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
    ],
"attribute":"Adherence",
 "fields":[{"name":"custID"}, {"name":"TZ"}],
 "sortOrder":[{"name":"custID"}, {"name":"TZ"}, {"name":"agentData","value":"TEST"}]
}
}

Output Field Descriptions

  • This export runs for each MU specified in the muIds list.

  • If the export is run for multiple MUs, 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.

  • Data is exported for all ACDs to which an agent is assigned.

  • 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.

  • If a gap exists in an agent’s activity log, for example, when the agent went to lunch, between a split shift, and so on, gaps are not explicitly stored as a No Code in the database. Therefore, there is nothing to map to an export activity code and the gaps are not explicitly included in the export.

Since the activity record exceptions are stored midnight-to-midnight based on MU time zone, all data is exported between midnight and midnight for each date.

The Agent Activity Detail output can contain these fields:

Field

Description

Values

date

This date is 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.

 

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 assigned ACD or multimedia server. Multiple records may exist for a date if the agent is assigned to more than one ACD or multimedia server.

 

logonID

The agent’s ACD or multimedia server logon ID.

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 is 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 activity record’s modify timestamp.

 

exception

The activity code attribute value assigned to the activity code, as specified in the attribute parameter .

If no value is assigned to the activity code for the activity code attribute, the activity code is not included in the export.

If multiple activity codes with the same activity code attribute value exist contiguously, they are exported as a single exception, with the appropriate start and stop times subject to the cross-midnight note below.

 

start

The start time of the activity code, based on the MU’s time zone.

The format of the start time is specified in the timeFormat attribute. If no timeFormat attribute exists, 24-hour format (HH:MM) is used.

 

stop

The end time of the activity code, based on the MU’s time zone.

The stop is the clock stop time, and therefore excludes the stop minute. For example, if a Lunch activity exists at noon for one hour, the stop time is 1:00pm, not 12:59pm. There are two records: [first record] |LUNCH|1200|1300, [second record]: OPEN|1300|1500. The actual 1300 clock minute is included in the second record.

The format of the stop time is specified in the timeFormat parameter. If no timeFormat parameter exists, 24-hour format (HH:MM) is used.

 

 

Supported output formats:

  • PIPE
  • JSON

JSON with results and non empty fields

var(--codeSnippetCopyLabel) 
[
    {
        "date": "20042023",
        "TZ": "America/Chicago",
        "custID": "1",
        "muID": "12",
        "tvID": "15000",
        "acdID": "2",
        "logonID": "15000",
        "agentName": "Johnson, Hayden",
        "modify": "2023-04-20T18:35:41Z",
        "exception": "test",
        "start": "01:34PM",
        "stop": "01:35PM"    },
    {
        "date": "20042023",
        "TZ": "America/Chicago",
        "custID": "1",
        "muID": "12",
        "tvID": "15000",
        "acdID": "2",
        "logonID": "15000",
        "agentName": "Johnson, Hayden",
        "modify": "2023-04-20T18:40:45Z",
        "exception": "test",
        "start": "01:36PM",
        "stop": "01:37PM"    }
]

JSON with results and empty fields

var(--codeSnippetCopyLabel) 
[
    {
        "date": "20042023",
        "TZ": "America/Chicago",
        "custID": "1",
        "muID": "12",
        "tvID": "15000",
        "acdID": "2",
        "logonID": "15000",
        "personalID": "",
        "agentName": "Johnson, Hayden",
        "modify": "2023-04-20T18:35:41Z",
        "exception": "test",
        "start": "01:34PM",
        "stop": "01:35PM",
        "externalID": ""    },
    {
        "date": "20042023",
        "TZ": "America/Chicago",
        "custID": "1",
        "muID": "12",
        "tvID": "15000",
        "acdID": "2",
        "logonID": "15000",
        "personalID": "",
        "agentName": "Johnson, Hayden",
        "modify": "2023-04-20T18:40:45Z",
        "exception": "test",
        "start": "01:36PM",
        "stop": "01:37PM",
        "externalID": ""    }
]

JSON with empty result

var(--codeSnippetCopyLabel) 
[]

PIPE result with enabled headers

var(--codeSnippetCopyLabel) 
#fields:date|TZ|custID|muID|tvID|acdID|logonID|ssn|agentName|modify|exception|start|stop|externalID
#sort:date,TZ,custID,muID,tvID,acdID,logonID,ssn,agentName,modify,exception,start,stop,externalID

20042023|America/Chicago|1|12|15000|2|15000||Johnson, Hayden|1682015741|test|01:34PM|01:35PM|
20042023|America/Chicago|1|12|15000|2|15000||Johnson, Hayden|1682016045|test|01:36PM|01:37PM|
20042023|America/Chicago|1|12|15000|2|15000||Johnson, Hayden|1682016348|test|01:40PM|01:43PM|

PIPE with disabled headers

var(--codeSnippetCopyLabel) 
20042023|America/Chicago|1|12|15000|2|15000||Johnson, Hayden|1682015741|test|01:34PM|01:35PM|
20042023|America/Chicago|1|12|15000|2|15000||Johnson, Hayden|1682016045|test|01:36PM|01:37PM|
20042023|America/Chicago|1|12|15000|2|15000||Johnson, Hayden|1682016348|test|01:40PM|01:43PM|

PIPE result with empty data

var(--codeSnippetCopyLabel) 
#fields:date|TZ|custID|muID|tvID|acdID|logonID|ssn|agentName|modify|exception|start|stop|externalID
#sort:date,TZ,custID,muID,tvID,acdID,logonID,ssn,agentName,modify,exception,start,stop,externalID

Agent Activity Detail DTD

var(--codeSnippetCopyLabel) 
<?xml version="1.0"?>
<!ELEMENT agentActivityDetail ((allFields | fieldList), sortOrder?)>
<!ELEMENT fieldList (fields)>
<!ELEMENT sortOrder (fields)>
<!ELEMENT fields (date | TZ | custID | muID | tvID | acdID | logonID | ssn |
agentData | agentName | modify | exception | start | stop | externalID)+>
<!ELEMENT allFields EMPTY>
<!ELEMENT date 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 exception EMPTY>
<!ELEMENT start EMPTY>
<!ELEMENT stop EMPTY>
<!ELEMENT externalID EMPTY>