Agent Vacation Summary

API Specification

Description Creates a task for Work Manager to execute export Engine for Agent Vacation Summary exporter.
Authentication
Required
yes
URL https://<domain or IP>/SMARTSync/services/rs/exporters/v1/agent-vacation-summary
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 ,XML, 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 then all date fields will be converted into 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: for PIPE, JSON outputFormat.

timeOffGroupList - array of complex Objects. Consists of timeOffGroup (Integer) and timeOffRules (array of Strings)

Required: only 1 of the fields is supported (either timeOffGroupList or allTimeOffGroups).

Notes: is not case sensitive 

allTimeOffGroups - complex object with one optional property includeAllTimeOffRules with type boolean (If not present in this object then it's set to false). 

includeAllTimeOffRules specifies when running the Agent Vacation Summary exporter with the all child, the export includes Time Off Rules with a date range that overlap the start/end date selected.

Required: only 1 of the fields is supported (either timeOffGroupList or allTimeOffGroups).

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.

excludePipeHeader - boolean field.

Required: false.

Notes: This field can be set only if outputFormat is PIPE. By default it is false. If set to true then PIPE output will contain header and sort in results output.

fields - array of Objects. Only supported for outputFormat as JSON or PIPE.

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

Required: false.

Possible values:

Simple fields when outputFormat is PIPE

{"name": "custID"}, {"name": "muID"}, {"name": "tvID"}, {"name": "acdID"}, {"name": "logonID"}, {"name": "ssn"}, {"name": "agentName"}, {"name": "vacGroup"}, {"name": "vacYear"}, {"name": "vacType"}, {"name": "modify"}, {"name": "from"}, {"name": "to"}, {"name": "earned"}, {"name": "debited"}, {"name": "coFrom"}, {"name": "coTo"}, {"name": "selected"}, {"name": "taken"}, {"name": "credited"}, {"name": "minFullWeeks"}, {"name": "maxPartialHours"}, {"name": "externalID"}

Simple fields when outputFormat is JSON

{"name":"custID"}, {"name":"muID"}, {"name":"tvID"}, {"name":"acdID"}, {"name":"logonID"}, {"name":"personalId"}, {"name":"agentName"}, {"name":"timeOffGroup"}, {"name":"timeOffRule"}, {"name":"earningsType"}, {"name":"modify"}, {"name":"from"}, {"name":"to"}, {"name":"earned"}, {"name":"debited"}, {"name":"coFrom"}, {"name":"coTo"}, {"name":"selected"}, {"name":"taken"}, {"name":"credited"}, {"name":"minFullWeeks"}, {"name":"maxPartialHours"}, {"name":"externalID"}

Note: 

  • In the fields array parameter, the output fields ssn,vacGroupID,vacYear and vacType may be used for PIPE output. But these must be replaced with personalID, timeOffGroup,timeOffRule and earningsType respectively 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.

Only supported for outputFormat as JSON or PIPE.

Represents the list of the supported field names, fields with specified value. All field names 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",
"Invalid entity: 'TimeOffGroup 1001'",
"Insufficient permissions to view entities 'TimeOffGroup 1001'",
"Invalid entity: 'TimeOffRule Test Rule1'",
"For Time Off Group [501], Time Off Rule [501_SB_DAYS_Rule] is configured to use "Days" Calculation Unit, which is not supported. Only "HH:MM" Calculation Unit is supported.",
"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-vacation-summary

request body(request for all fields and 1 TimeOffGroup and TimeOffRule):

{
"outputFormat": "XML",
"dateFormat": "DDMMYYYY",
"timeFormat": "12",
"startDate": "2020-01-01",
"endDate": "2023-03-01",
"timeOffGroupList": [
    {"timeOffGroup": 505,
"timeOffRules": [
"Y_TOR"
      ]
    }
  ]
}
Sample Call for JSON outputFormat

https://localhost/SMARTSync/services/rs/exporters/v1/agent-vacation-summary

request body(request for all fields and 1 TimeOffGroup and TimeOffRule with keeping empty json fields):

{
"outputFormat": "JSON",
"dateFormat": "DDMMYYYY",
"timeFormat": "12",
"startDate": "2020-01-01",
"endDate": "2023-03-01",
  "keepEmptyJsonFields": true,
"timeOffGroupList": [
    {"timeOffGroup": 505,
"timeOffRules": [
"Y_TOR"
      ]
    }
  ]
}
request body(request for all fields and ALL TimeOffGroups with their corresponding TimeOffRules):
{
"outputFormat": "JSON",
"dateFormat": "DDMMYYYY",
"timeFormat": "12",
"startDate": "2020-01-01",
"endDate": "2023-03-01",
"allTimeOffGroups": {
"includeAllTimeOffRules": true
  }
}
 
request body(request for specific fields and 1 TimeOffGroup and TimeOffRule):
{
"outputFormat": "JSON",
"dateFormat": "DDMMYYYY",
"timeFormat": "12",
"startDate": "2020-01-01",
"endDate": "2023-03-01",
  "keepEmptyJsonFields": true,
"timeOffGroupList": [
    {"timeOffGroup": 505,
"timeOffRules": [
"Y_TOR"
      ]
    }
  ],
  "fields":[{"name":"custID"}, {"name":"muID"}, {"name":"tvID"}, {"name":"acdID"}, {"name":"logonID"}, {"name":"personalId"}, {"name":"agentName"}, {"name":"timeOffGroup"}, {"name":"timeOffRule"}, {"name":"earningsType"}, {"name":"modify"}, {"name":"from"}, {"name":"to"}, {"name":"earned"}, {"name":"debited"}, {"name":"coFrom"}, {"name":"coTo"}, {"name":"selected"}, {"name":"taken"}, {"name":"credited"}, {"name":"minFullWeeks"}, {"name":"maxPartialHours"}, {"name":"externalID"}, {"name":"agentData","value":"Supervisor"}],
  "sortOrder":[{"name":"custID"}, {"name":"muID"}, {"name":"tvID"}, {"name":"acdID"}, {"name":"logonID"}, {"name":"personalId"}, {"name":"agentName"}, {"name":"timeOffGroup"}, {"name":"timeOffRule"}, {"name":"earningsType"}, {"name":"modify"}, {"name":"from"}, {"name":"to"}, {"name":"earned"}, {"name":"debited"}, {"name":"coFrom"}, {"name":"coTo"}, {"name":"selected"}, {"name":"taken"}, {"name":"credited"}, {"name":"minFullWeeks"}, {"name":"maxPartialHours"}, {"name":"externalID"}, {"name":"agentData","value":"Supervisor"}]
}
Sample Call for PIPE outputFormat https://localhost/SMARTSync/services/rs/exporters/v1/agent-vacation-summary

request body(request for all fields and 1 TimeOffGroup and TimeOffRule with keeping pipe headers):

{
"outputFormat": "PIPE",
"dateFormat": "DDMMYYYY",
"timeFormat": "12",
"startDate": "2020-01-01",
"endDate": "2023-03-01",
  "excludePipeHeader": false,
"timeOffGroupList": [
    {"timeOffGroup": 505,
"timeOffRules": [
"Y_TOR"
      ]
    }
  ]
}
request body(request for all fields and ALL TimeOffGroups with their corresponding TimeOffRules):
{
"outputFormat": "PIPE",
"dateFormat": "DDMMYYYY",
"timeFormat": "12",
"startDate": "2020-01-01",
"endDate": "2023-03-01",
"allTimeOffGroups": {
"includeAllTimeOffRules": true
  }
}
 
request body(request for specific fields and 1 TimeOffGroup and TimeOffRule):
{
"outputFormat": "PIPE",
"dateFormat": "DDMMYYYY",
"timeFormat": "12",
"startDate": "2020-01-01",
"endDate": "2023-03-01",
"timeOffGroupList": [
    {"timeOffGroup": 505,
"timeOffRules": [
"Y_TOR"
      ]
    }
  ],
  "fields":[{"name":"custID"}, {"name":"muID"}, {"name":"tvID"}, {"name":"acdID"}, {"name":"logonID"}, {"name":"ssn"}, {"name":"agentName"}, {"name":"vacGroup"}, {"name":"vacYear"}, {"name":"vacType"}, {"name":"modify"}, {"name":"from"}, {"name":"to"}, {"name":"earned"}, {"name":"debited"}, {"name":"coFrom"}, {"name":"coTo"}, {"name":"selected"}, {"name":"taken"}, {"name":"credited"}, {"name":"minFullWeeks"}, {"name":"maxPartialHours"}, {"name":"externalID"}, {"name":"agentData","value":"Supervisor"}],
  "sortOrder":[{"name":"custID"}, {"name":"muID"}, {"name":"tvID"}, {"name":"acdID"}, {"name":"logonID"}, {"name":"ssn"}, {"name":"agentName"}, {"name":"vacGroup"}, {"name":"vacYear"}, {"name":"vacType"}, {"name":"modify"}, {"name":"from"}, {"name":"to"}, {"name":"earned"}, {"name":"debited"}, {"name":"coFrom"}, {"name":"coTo"}, {"name":"selected"}, {"name":"taken"}, {"name":"credited"}, {"name":"minFullWeeks"}, {"name":"maxPartialHours"}, {"name":"externalID"}, {"name":"agentData","value":"Supervisor"}
}

Output Field Descriptions

  • This export runs for each time off group  and time off rule specified in the timeOffGroupList array.

  • If the export runs for multiple time off groups, all the data is saved in the same output file.

  • For each time off group and time off rule the export runs, data is exported for each agent with at least one record in the Time Off Summary table for that time off group and time off rule.

  • Note: Even if an agent belongs to the time off group for the year being exported, the agent is not included for that year if no time off summary records exist.

  • Data is exported for the Wait List earnings type as it is for all other earnings types.

  • 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 more than one time off code is associated with the same earnings type, the code-level details are not visible in this export.

  • Vacation is named Time Off in the application.

The Agent Vacation Summary output can include these fields if the XML outputFormat value is not specified:

Field

Description

Values

custID

The customer ID.

 

muID

The ID of the MU to which the agent is assigned in his or her latest AgentMap record.

 

tvID

The agent’s WFM ID.

 

acdID

The ID of the agent’s highest-priority ACD according to the agent’s latest Agent ACD definition record. The highest-priority ACD is the one with the lowest priority number.

 

logonID

The agent’s highest-priority ACD logon ID. 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>.

 

vacGroup

The ID of the time off group for which the export is being run.

 

vacYear

The time off rule for which data are being exported.

Note: This must be a time off rule with a calculation unit of HH:MM. This export does not support time off rules with a calculation unit of Days.

 

vacType

The earnings type.

The earnings type name is printed in this field.

Each earnings type for which the agent has Vacation Summary data for the time off rule is included, each in a separate record.

Note: Vacation Summary records whose code is -1 represent the Wait List earnings type.

 

modify

The record’s modify timestamp.

 

from

The earliest date for which the agent may select an activity code; this is the earliest From Date for all the codes associated with the same earnings type.

 

to

The latest date for which the agent may select an activity code; this is the latest To Date for all codes associated with the same earnings type.

 

earned

The amount of time, in minutes, the agent has earned for the earnings type in the time off rule.

 

debited

The amount of time, in minutes, debited for the earnings type.

 

coFrom

The amount of time, in minutes, the agent carried over from the previous year for the earnings type.

 

coTo

The amount of time, in minutes, the agent carried over into the next year for the earnings type.

 

selected

The amount of time, in minutes, the agent has selected for the earnings type within the time off rule.

Only the vacation selections made for dates on and after the time off rule’s Master From Date are included.

If the Master From date is the same as or later than the time off rule's end date, the system considers the rule to be closed out and all days are taken values, including the time off rule’s end date. In this case, the selected time is zero for all days.

The export's startDate and endDate parameters are not used for calculating this value. Vacation selections are stored in the Future Activities table. Only records that exist for the time off rule being exported are included in the selected value. This value is the sum of the selected time for all the codes associated with the same earnings type.

 

taken

The amount of time, in minutes, the agent has taken for the earnings type within the time off rule.

This value is not stored in the database. It is the sum of the time on agent schedules for dates that fall before the Master From date for all the codes associated with the same earnings type.

If the Master From date is the same as or later than the time off rule's end date, the system considers the rule to be closed out and all days are taken values, including the time off rule’s end date. In this case, the selected time is zero for all days.

The export's startDate and endDate parameters are not used for calculating this value.

 

credited

The amount of time, in minutes, added to the agent’s earned amount.

 

minFullWeeks

The number of weeks the agent must take in full week increments.

 

maxPartialHours

The maximum amount of time, in minutes, the agent is allowed to take in partial day increments.

 

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.

XML Output Option for Agent Vacation Summary

If XML is selected in the outputFormat parameter:

  • the output will follow the DTD below.

  • all of the fields listed in the DTD are included.

  • all of an agent’s time off summary records for a time off group and time off rule are grouped together and included in one agentVacation element.

  • the agentID element is the agent’s WFM agent ID.

  • all other fields contain the same values as specified above.

<?xml version="1.0"?>

    <!ELEMENT agentVacationSummary (agentVacation+)>

 

    <!ELEMENT agentVacation (agent, vacation+)>

 

    <!ELEMENT agent (agentID, vacGroup, vacYear)>

    <!ELEMENT vacation (from?, to?, earned?, credited?, debited?, selected?, taken?, minFullWeeks?, maxPartialHours?, coFrom?, coTo?)>

 

    <!ELEMENT agentID #PCDATA>

    <!ELEMENT vacGroup #PCDATA>

    <!ELEMENT vacYear #PCDATA>

 

    <!ELEMENT from (day, month, year)>

    <!ELEMENT to (day, month, year)>

    <!ELEMENT earned #PCDATA>

    <!ELEMENT debited #PCDATA>

    <!ELEMENT credited #PCDATA>

    <!ELEMENT selected #PCDATA>

    <!ELEMENT taken #PCDATA>

    <!ELEMENT minFullWeeks #PCDATA>

    <!ELEMENT maxPartialHours #PCDATA>

    <!ELEMENT coFrom #PCDATA>

    <!ELEMENT coTo #PCDATA>

 

    <!ELEMENT day (#PCDATA)>

    <!ELEMENT month (#PCDATA)>

    <!ELEMENT year (#PCDATA)>

 

    <!ATTLIST vacation type CDATA #REQUIRED>

    <!ATTLIST agentID acdID CDATA #IMPLIED>

 

Supported output formats:

  • Pipe delimited
  • JSON
  • XML

XML with results

XML with empty results

JSON with results for 1 TOG and TOR and empty fields

JSON for all TOG and TOR

JSON with empty results

PIPE results for 1 TOG and TOR with PIPE header

PIPE results all TOG and TOR

PIPE empty results

Agent Vacation Summary DTD

Agent Vacation Summary Advanced Configuration File XML Example