Agent Export

API Specification

Description Creates a task for WorkManager to execute exportEngine for Agent-Export exporter.
Authentication
Required
yes
URL https://<domain or IP>/SMARTSync/services/rs/exporters/v1/agent-export
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: XML, JSON

Required: true.

Notes: is not case sensitive

lastModifiedTime -  String, represents date in ISO format yyyy-MM-dd'T'HH:mm:ss'Z'.

If specified, filters out Time Off Rules whose date range does not overlap with the startDate or endDate

Required: false.

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 be set only if outputFormat is set to JSON.

By default it is false. If set to true then JSON output will contain empty values ({},[],"") for fields.

recordType - String, possible values: newAgent, changedAgent

Required: true.

Notes: is not case sensitive. Determines whether

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 XML

{"name":"useAvailability"}, {"name":"availListDateRange"}, {"name":"accrualDate"}, {"name":"minRestPerWeek"}, {"name":"firstName"}, {"name":"rank"}, {"name":"workStatus"}, {"name":"rotationNum"}, {"name":"minCDO"}, {"name":"lastName"}, {"name":"senExt"}, {"name":"tourGroup"}, {"name":"maxMinutes"}, {"name":"UUID"}, {"name":"vacDayLengthList"}, {"name":"minTimeBetweenScheds"}, {"name":"vacationGroup"}, {"name":"emailList"}, {"name":"senDate"}, {"name":"nameSuffix"}, {"name":"allAgentData"}, {"name":"forceWork"}, {"name":"biddingDate"}, {"name":"mu"}, {"name":"supervisor"}, {"name":"maxCDO"}, {"name":"skillSet"}, {"name":"recid"}, {"name":"minCDW"}, {"name":"acdList"}, {"name":"startID"}, {"name":"biddingExt"}, {"name":"name"}, {"name":"ssn"}, {"name":"agentStartDate"}, {"name":"maxCDW"}, {"name":"password"}, {"name":"minMinutes"}, {"name":"availabilityList"}, {"name":"availDateRange"}, {"name":"daysVacWeek"}, {"name":"externalID"}, {"name": "id"}

Simple fields when outputFormat is JSON

{"name":"useAvailability"}, {"name":"availListDateRange"}, {"name":"accrualDate"}, {"name":"minRestPerWeek"}, {"name":"firstName"}, {"name":"rank"}, {"name":"workStatus"}, {"name":"rotationNum"}, {"name":"minCDO"}, {"name":"lastName"}, {"name":"senExt"}, {"name":"tourGroup"}, {"name":"maxMinutes"}, {"name":"UUID"}, {"name":"vacDayLengthList"}, {"name":"minTimeBetweenScheds"}, {"name":"timeOffGroup"}, {"name":"emailList"}, {"name":"senDate"}, {"name":"nameSuffix"}, {"name":"allAgentData"}, {"name":"forceWork"}, {"name":"biddingDate"}, {"name":"mu"}, {"name":"maxCDO"}, {"name":"skillSet"}, {"name":"recid"}, {"name":"minCDW"}, {"name":"acdList"}, {"name":"startID"}, {"name":"biddingExt"}, {"name":"name"}, {"name":"personalID"}, {"name":"agentStartDate"}, {"name":"maxCDW"}, {"name":"minMinutes"}, {"name":"availabilityList"}, {"name":"availDateRange"}, {"name":"daysVacWeek"}, {"name":"externalID"}, {"name": "id"}

Note: 

  • In the fields array parameter, the output fields vacationGroup, supervisor, ssn, and passwordmay be used for XML output.
  • For JSON output vacationGroupmust be replaced with timeOffGroup, and ssn with personalID
  • Fields supervisor and password 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) within Id field in the advanced xml configuration generated for exporter. 

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 recordType value: 'wrongRecordType'",
"Invalid values within fields element: wrongField",
"Invalid agentData value within fields element: wrongAgentData",
"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/agent-export

request body(request for all fields):


{
"startDate":"2023-11-10",
"endDate":"2024-11-10",
"outputFormat":"xml",
"dateFormat":"ddmmyyyy",
"timeFormat":"12",
"muIds":[
500
  ],
"recordType":"newagent"
}


request body(request for specific fields):

{
"startDate":"2022-11-10",
"endDate":"2022-11-10",
"outputFormat":"xml",
"dateFormat":"ddmmyyyy",
"timeFormat":"12",
"muIds":[
500
  ],
"recordType":"newagent",
"fields":[{"name":"availListDateRange"}, {"name":"id"}],
"sortOrder":[{"name":"availListDateRange"}, {"name":"mu"}]
}


Sample Call for JSON outputFormat

https://localhost/SMARTSync/services/rs/exporters/v1/agent-export

request body(request for all fields):


{
"startDate":"2023-11-10",
"endDate":"2024-11-10",
"outputFormat":"JSON",
"dateFormat":"ddmmyyyy",
"keepEmptyJsonFields": true,
"timeFormat":"12",
"muIds":[
500
  ],
"recordType":"changedAgent"
}
request body(request for specific fields):
{
"startDate": "2022-11-10",
"endDate": "2022-11-10",
"outputFormat": "JSON",
"dateFormat": "ddmmyyyy",
"timeFormat": "12",
"keepEmptyJsonFields": true,
"muIds": [
500
    ],
"recordType": "newagent",
"fields":[{"name":"availListDateRange"}, {"name":"id","attribute": "idType","value":"tvid"}, {"name":"agentData","value":"TEST"}],
"sortOrder":[{"name":"availListDateRange"}, {"name":"mu"}]
}

Output Field Descriptions

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

  • Agent information is exported for each agent that belongs to the MU being processed for the date being processed. Data is exported for each date in the range specified by startDate and endDate.

    If you use the lastModifiedTime parameter, the records in the output file are further limited to only include agents whose records from the database have a modify time greater than or equal to the lastModifiedTime.

    • To include an agent in the output file as a newAgent record:

      • All the records from the various tables used to create a newAgent record must have a modify time greater than or equal to the lastModifiedTime +/- 10 seconds

        or

      • The agent’s ACD assignment start date/time is greater than the lastModifiedTime.

    • To include an agent in the output file as a changedAgent record:

      • Any of the records from the various tables used to create a changedAgent record must have a modify time greater than or equal to the lastModifiedTime.

    • 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 an agent has an ampersand (&) anywhere in their definition, the export output truncates the field. It truncates anything after and including the ampersand. This applies to every field, including names, skill names, agent data groups, and so on. For example, when exporting agents assigned a skill named 124 Tamarac English P&T.127.502, the export outputs 124 Tamarac English P.

    • The file format of this export is XML, rather than a delimited field file format.

    • The output file contains either newAgent or changedAgent elements, depending on the value specified in the recordType parameter.

      • If the recordType is newAgent,, newAgent elements are used for all the exported agents.

      • If the recordType is changedAgent, changedAgent elements are used for all agents.

      • If you did not specify recordType, all agents are exported in newAgent elements.

    • The exporter ensures the required output for newAgent and changedAgent elements is produced. For example, muId is a required parameter in a newAgent export. Therefore, if newAgent elements are exported, mu is included even if the fields array did not indicate to include mu. Similarly, agentStartDate is not a valid field in a changedAgent export. Therefore, if exporting changedAgent elements, agentStartDate is not included in the output, even if the fields array indicated it should be.

    • Data is sorted for this export as it is for all other exporters. However, since the acdList, availabilityList, skillSet, agentData and vacDayLengthList elements may contain multiple children, data is not sorted by these elements. If you specify any of these elements in the sortOrder parameter, they are ignored. The allAgentData element is also ignored if specified in the sortOrder element.

    • When exporting agent availability information, for example, Tour Group/Weekly Rule, Availability, and so on, date-specific data is included in the output. The agent’s default record is used if no date-specific record exists for the date being processed.

    • If exporting ACD logon IDs or skill assignments, only the logon IDs and skills assigned to the agent for the date being processed are exported. It is not possible to export the date ranges associated with these data items, due to the way the data items are imported by the NICE WFM Import Agent SmartSync.

The Agent Export output can include these fields:

Field

Description

Values

id

You must include this element if exporting changedAgent elements, and omit it if exporting newAgent elements. The value exported in this field depends on the idType attribute of the id element.

idType:

  • tvIDor [not specified]: this is the agent’s WFM ID.

  • ssn: this is the agent’s personal ID.

  • acdLogon: this is the agent’s priority 1 logon ID. The ID of the ACD is printed in the acdID attribute of this element. The element is blank if the agent is not assigned a Logon ID for the priority 1 ACD.

name

You must include this field for newAgent elements. This is the agent’s name.

The name is exported as three elements of firstName, lastName, and nameSuffix. This field is optional for changedAgent elements. However, if used, you must specify the name or lastName element to output agent names. The firstName and nameSuffix elements are optional when used with the lastName element.

 

UUID

The unified user ID for the agent.

 

mu

You must include this element if exporting newAgent elements. This is the ID of the MU for which the export is being run.

 

acdList

This optional element includes an acdStartDate child and one or more acd children. One acd child is included for each ACD assigned to the agent on the date being processed. If the agent is assigned to multiple ACDs, the acd children are exported in priority order.

 

acdStartDate

The date being processed.

 

acd

This element includes an acdID child, a logon child, and an agentGroup child.

 

acdID

The ID of the ACD or multimedia server to which the agent is assigned.

 

logon

The logon ID assigned to the agent for the ACD or multimedia server.

If the agent is not assigned to an ACD with the specified priority for the date being processed, this field is blank.

If no priority is specified, the agent’s priority 1 ACD is shown in this field.

If a priority is specified, it must be an integer between 1 and 10, otherwise this field is not exported and a warning message is printed in the process report.

The specified priority is printed in the first lines of the output file.

logonType

The type of logon. This element is used for synchronizing agents between NICE products.

 

agentGroup

The ID of the agent group to which the agent is assigned.

 

startID

This element is not exported for changedAgent elements. This element contains the agent’s WFM ID.

 

ssn

The agent’s personal ID number.

For JSON output, personalId is used instead

 

agentStartDate

This element is not included if exporting changedAgent elements. This element contains day, month, and year children. This is the start date of the agent’s earliest active AgentMap record. The earliest record is the record whose s_date is earliest.

 

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.

senDate

The agent’s seniority date. This element contains day, month, and year children.

 

senExt

The agent’s seniority extension.

 

rank

The agent’s rank.

 

supervisor

The logon ID of the agent’s supervisor.

This field is blank.

password

The agent’s password.

The password is blank.

minCDO

The agent’s minimum consecutive days off.

 

maxCDO

The agent’s maximum consecutive days off.

 

minCDW

The agent’s minimum consecutive days to work.

 

maxCDW

The agent’s maximum consecutive days to work.

 

minTimeBetweenScheds

The minimum number of minutes required between schedules for the agent.

 

minRestPerWeek

The agent’s minimum rest period per week.

 

availDateRange

The date range of the agent availability record.

Note: The date range provided in the availDateRange element is the date + weeks or date range for these data items:

  • minCDO

  • maxCDO

  • minCDW

  • maxCDW

  • minTimeBetweenScheds

  • minRestPerWeek

  • availDateRange

  • forceWork

  • workStatus

  • tourGroup

  • rotationNum

  • minMinutes

  • maxMinutes

This element contains day, month, and year children and a weeks child.

If the agent’s default agent availability record is exported, this element is blank.

startDate

The start date of the scheduling parameters.

 

endDate

The end date of the scheduling parameters.

 

default

The default record of scheduling parameters.

 

forceWork

The agent’s force work setting.

Y or N

workStatus

This field indicates whether the agent works full or part time.

F or P

tourGroup

The agent’s weekly rule.

 

rotationNum

The agent’s weekly rule rotation number.

 

minMinutes

The agent’s minimum minutes per week.

 

maxMinutes

The agent’s maximum minutes per week.

 

useAvailability

This field indicates whether the availability matrix is used for the agent.

This field is always Y.

availListDateRange

The date range of each availabilityList. Either an empty <default/> element or a <startDate> and an <endDate> element is exported.

 

availabilityList

This element contains seven availability children. One availability child is included for each day of the week. The availability children are exported in order beginning with Sunday.

 

availability

The day attribute of this element is the day of the week being exported.

The value of this element is a string of A and N values; each A or N indicates availability for each 15-minute period of the day.

availabilityListstatus

This attribute indicates if the availability list has been approved, rejected, or is pending approval.

 

skillSet

This element contains a skillStartDate child, a baseScheduleCode child and zero or more skill children. One skill child is included for each skill assigned to the agent on the date being processed.

 

skillStartDate

The date being processed.

 

baseScheduleCode

The base schedule code for the date being processed. The activity code description is the value exported.

 

skillName

The name of the skill.

 

level

The level assigned to the agent for the skill.

 

rsv

The agent’s reserve flag setting for the skill.

 

agentData

An agentData element is included in the output file if any of these are true:

  • One or more valid agentData elements is included. In this case, only the specified agent data groups are included in the output file.

    • The allAgentData element exists and at least one agent data group is defined. In this case, all agent data groups defined in the system are exported.

    • No agentData parameter exists and at least one agent data group is defined. In this case, all agent data groups defined in the system are exported.

Note: If an allAgentData element is included as well as one or more agentData elements, the agent data groups specified in the agentData elements are exported twice.

If any agent data group values are exported, one agentData element is included in the output file. This element contains a group child for each valid agentData element specified.

If all agent data groups are exported, a group child exists for each agent data group, subject to the group comments below. If no valid agentData elements are specified or if no agent data groups are defined, the agentData element is not included in the output file.

 

group

This element contains a description child, and a value child. If an agentData element exists, but no agent data group exists in the system with the specified description, then no group element is exported for that agent data group.

 

adgStartDate

The start date of the value assigned to the agent for the group. This element contains day, month, and year children.

 

description

This element contains the agent data group description specified in the agentData element.

 

value

This element contains the value assigned to the agent for the agent data group specified in the agentData element.

The value element is blank if the agent is not assigned a value for the specified agent data group for the date being processed.

emailList

This element includes one email child for each record that exists in the email address table.

 

email

This element contains the email address.

 

number

This attribute contains the number of the email address.

1 - 10

type

This attribute contains the type.

N - normal

S - short

language

This attribute contains a 5-character string identifying the language and region of a locale for formatting messages.

 

vacationGroup

This element is not exported for changedAgent elements. This is the ID of the time off group to which the agent is assigned on the date being processed.

 

biddingDate

The agent’s alternate seniority date. This element contains day, month, and year children.

 

biddingExt

The agent’s alternate seniority extension.

 

accrualDate

The agent’s accrual date. This element contains day, month, and year children.

 

daysVacWeek

The number of vacation days that comprise a week of vacation for the agent.

 

vacDayLengthList

This element contains seven vacDayLength children. One child is exported for each day of the week. Days of the week are exported in order, beginning with Sunday.

 

recid

This element contains a counter. The counter begins at 1 and increments for each newAgent or changedAgent element exported.

 

 

Supported output formats:

  • XML
  • JSON

JSON with results [recordType="newagent"]


JSON with empty result

XML with results [recordType="newagent"]

XML with results [recordType="changedAgent"]

XML with empty result

JSON with results [recordType="changedAgent"]

Agent Export DTD