MU Results

API Specification

Description Creates a task for workmanager to execute exportEngine for MU-Results exporter.
Authentication
Required
Yes
URL
https://<domain or IP>/SMARTSync/services/rs/exporters/v1/mu-results
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. 

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 be set to true only if outputFormat is set to PIPE. By default it is set to false.

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":"saGroupID"}, {"name":"saGroupName"}, {"name":"ssGroupID"}, {"name":"ssGroupName"}, {"name":"buID"}, {"name":"buName"}, {"name":"ctID"}, {"name":"ctName"}, {"name":"muID"}, {"name":"muName"}, {"name":"modify"}, {"name":"estStaff"}, {"name":"actRec"}, {"name":"actContactsHandled"}, {"name":"actOutContacts"}, {"name":"actIntContacts"}, {"name":"actLogin"}, {"name":"actTalk"}, {"name":"actWork"}, {"name":"actOut"}, {"name":"actReady"}, {"name":"actBusy"}, {"name":"actIn"}

Simple fields when outputFormat is JSON

{"name":"date"}, {"name":"period"}, {"name":"TZ"}, {"name":"custID"}, {"name":"saGroupID"}, {"name":"saGroupName"}, {"name":"ctID"}, {"name":"ctName"}, {"name":"muID"}, {"name":"muName"}, {"name":"modify"}, {"name":"estStaff"}, {"name":"actRec"}, {"name":"actContactsHandled"}, {"name":"actOutContacts"}, {"name":"actIntContacts"}, {"name":"actLogin"}, {"name":"actTalk"}, {"name":"actWork"}, {"name":"actOut"}, {"name":"actReady"}, {"name":"actBusy"}, {"name":"actIn"}

Note: 

  • In the fields array parameter, the output fields ssGroupID, ssGroupName, buID and buName may be used for PIPE output.
  • Fields ssGroupID, ssGroupName, buID and buName may not be used for JSON output.
  • Only one field with the same name can be present in the fields array.

Field with attribute and value: 

{"name":"id","attribute":"idType","value":"personalId"}, {"name":"id","attribute":"idType","value":"acdlogon"}, {"name":"id","attribute":"idType","value":"tvid"}, {"name": "id"}

Note: Only one 'id' field can be present in the fields. idType represents attribute (with possible values: tvID, ssn, acdLogon). 

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: 'pipe'",
"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",
"Invalid values within fields element: wrongField",
"Invalid id attribute value within fields: 'wrong'",
"Invalid values within sortOrder element: wrongField",
"Insufficient permissions to view entities 'MU 8888'",
"Invalid entity: 'MU 1234567'",
"Invalid agentData value within sortOrder element: wrongAgentData"
    ]
}
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 XML outputFormat

https://localhost/SMARTSync/services/rs/exporters/v1/mu-results

request body(request for all fields):

{
"startDate":"2021-01-01",
"endDate":"2022-01-01",
"outputFormat":"PIPE",
"dateFormat":"ddmmyyyy",
"timeFormat":"12",
"muIds":[
500
  ]
}


request body(request for specific fields):

{
"startDate":"2021-01-01",
"endDate":"2022-01-01",
"outputFormat":"PIPE",
"dateFormat":"ddmmyyyy",
"timeFormat":"12",
"muIds":[
500
  ]
"fields":[{"name":"date"}, {"name":"period"}],
"sortOrder":[{"name":"date"}, {"name":"period"}]
}
Sample Call for JSON outputFormat

https://localhost/SMARTSync/services/rs/exporters/v1/mu-results

request body(request for all fields):

{
"startDate":"2021-01-01",
"endDate":"2022-01-01",
"outputFormat":"JSON",
"dateFormat":"ddmmyyyy",
"timeFormat":"12",
"muIds":[
500
  ]
}


request body(request for specific fields):

{
"startDate":"2021-01-01",
"endDate":"2022-01-01",
"outputFormat":"JSON",
"dateFormat":"ddmmyyyy",
"timeFormat":"12",
"muIds":[
500
  ]
"fields":[{"name":"date"}, {"name":"period"}],
"sortOrder":[{"name":"date"}, {"name":"period"}]
}

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.

  • The output file contains a record for each MU and each period in the specified date range. MU hours are not taken into account. Data is only included for past dates. If none of the dates in the specified range is in the past, the output file is empty.

This export uses the CT 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 MU Results output can contain 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 statistics period.

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.

 

saGroupID

The ID of the EG to which the MU belongs on the date being processed.

This field is blank if the MU does not belong to an EG.

saGroupName

The EG name.

 

This field is blank if the MU does not belong to an EG.

ssGroupID

The ID of the skill scheduling group to which the MU belongs on the date being processed.

This field is blank.

ssGroupName

The skill scheduling group name.

This field is blank.

buID

The ID of the BU to which the MU belongs on the date being processed.

If the MU belongs to a CT assigned to a BU on the date being processed, this is the BU to which the CT is assigned.

This field is blank.

buName

The name of the BU.

This field is blank.

ctID

The CT to which the MU belongs on the date being processed.

 

ctName

The name of the CT.

 

muID

The ID of the MU being processed.

 

muName

The name of the MU.

 

modify

Formatted as a UNIX timestamp, this is the time, using the server’s time zone, the record was exported.

Note: Some data items in this record are not stored in the database. Using a last modified field from a database record is not feasible because the contributing database tables and fields used for calculating the data items may all have different last modified timestamps. Therefore, the current date/time of the export is used as the modify field.

 

estStaff

The number of agents in the MU that were logged in for the time period. This value depends on the estimated staff calculation selected for the MU.

This value is rounded to 2 decimal places.

actReq

The MU’s total actual requirement for the period, rounded to 2 decimal places.

The value represents the requirements which meet or exceed all three forecast objectives, service level, ASA, and maximum occupancy, and includes adjustments for:

  • BU efficiency, for CTs that belong to a BU

  • Multi-skill efficiency

For skills based MUs, the requirements for all CTs allocated to the MU are added together and shown in this field.

If data are missing for a period, this field is blank.

This field is blank for workload CTs.

actContactsHandled

The MU’s actual number of contacts handled in the period.

 

actOutContacts

The MU’s actual number of outgoing contacts for the period.

Each record in the MU Results export is the sum of the individual agent records for all agents that belong to the MU on the date being exported. System level data such as actOutContacts is included in only one queue ID per agent, which is the queueID mapped within NICE WFM to each agents’ primary skill. Therefore, at an MU level the system level data may appear under multiple records with different queueIDs, if the agents have different primary skills.

 

actIntContacts

The MU’s actual number of internal contacts for the period.

Each record in the MU Results export is the sum of the individual agent records for all agents that belong to the MU on the date being exported. System level data such as actIntContacts is included in only one queue ID per agent, which is the queueID mapped within NICE WFM to each agents’ primary skill. Therefore, at an MU level the system level data may appear under multiple records with different queueIDs, if the agents have different primary skills.

 

actLogin

The MU’s actual login time, in seconds, for the period.

Each record in the MU Results export is the sum of the individual agent records for all agents that belong to the MU on the date being exported. System level data such as actLogin is included in only one queue ID per agent, which is the queueID mapped within NICE WFM to each agents’ primary skill. Therefore, at an MU level the system level data may appear under multiple records with different queueIDs, if the agents have different primary skills.

 

actTalk

The MU’s actual talk time, in seconds, for the period.

 

actWork

The MU’s actual work time, in seconds, for the period.

 

actOut

The MU’s actual outbound time, in seconds, for the period.

Each record in the MU Results export is the sum of the individual agent records for all agents that belong to the MU on the date being exported. System level data such as actOut is included in only one queue ID per agent, which is the queueID mapped within NICE WFM to each agents’ primary skill. Therefore, at an MU level the system level data may appear under multiple records with different queueIDs, if the agents have different primary skills.

 

actReady

The MU’s actual ready time, in seconds, for the period.

Each record in the MU Results export is the sum of the individual agent records for all agents that belong to the MU on the date being exported. System level data such as actReady is included in only one queue ID per agent, which is the queueID mapped within NICE WFM to each agents’ primary skill. Therefore, at an MU level the system level data may appear under multiple records with different queueIDs, if the agents have different primary skills.

 

actNotReadyTime

The MU’s actual busy time, in seconds, for the period.

This field is the agents’ idle, AUX or not ready time, in seconds, for the date. Each record in the MU Results export is the sum of the individual agent records for all agents that belong to the MU on the date being exported. System level data such as actNotReadyTime is included in only one queue ID per agent, which is the queueID mapped within NICE WFM to each agents’ primary skill. Therefore, at an MU level the system level data may appear under multiple records with different queueIDs, if the agents have different primary skills.

 

actInt

The MU’s actual internal time, in seconds, for the period.

Each record in the MU Results export is the sum of the individual agent records for all agents that belong to the MU on the date being exported. System level data such as actInt is included in only one queue ID per agent, which is the queueID mapped within NICE WFM to each agents’ primary skill. Therefore, at an MU level the system level data may appear under multiple records with different queueIDs, if the agents have different primary skills.

 

 

Supported output formats:

  • Pipe delimited
  • JSON

PIPE results

JSON results with empty fields

JSON results without empty fields

MU results DTD