CT Active Forecast

API Specification

Description	Creates a task for workmanager to execute exportEngine for CT Active Forecast exporter.
Authentication Required	Yes
URL	https://<domain or IP>/SMARTSync/services/rs/exporters/v1/ct-active-forecast
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 defined 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.

buIds - Array of integers.

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

ctIds - Array of integers.

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

Required: at least buIds or ctIds should be present in request.

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 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 only if outputFormat is PIPE. By default it is false. If it is set to true, the 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":"date"}, {"name":"period"}, {"name":"TZ"}, {"name":"custID"}, {"name":"saGroupID"}, {"name":"saGroupName"}, {"name":"ssGroupID"}, {"name":"ssGroupName"}, {"name":"buID"}, {"name":"buName"}, {"name":"ctID"}, {"name":"ctName"}, {"name":"acdID"}, {"name":"modify"}, {"name":"fcstContactsReceived"}, {"name":"fcstContactsHandled"}, {"name":"fcstAHT"}, {"name":"fcstSLPct"}, {"name":"slPctObj"}, {"name":"slTime"}, {"name":"fcstOcc"}, {"name":"maxOcc"}, {"name":"fcstASA"}, {"name":"asaObj"}, {"name":"fcstReq"}, {"name":"revPlanReq"}, {"name":"commitPlanReq"}, {"name":"schedOpen"}

Simple fields when outputFormat is JSON:

{"name":"date"}, {"name":"period"}, {"name":"TZ"}, {"name":"custID"}, {"name":"egID"}, {"name":"egName"}, {"name":"buID"}, {"name":"buName"}, {"name":"ctID"}, {"name":"ctName"}, {"name":"acdID"}, {"name":"modify"}, {"name":"fcstContactsReceived"}, {"name":"fcstContactsHandled"}, {"name":"fcstAHT"}, {"name":"fcstSLPct"}, {"name":"slPctObj"}, {"name":"slTime"}, {"name":"fcstOcc"}, {"name":"maxOcc"}, {"name":"fcstASA"}, {"name":"asaObj"}, {"name":"fcstReq"}, {"name":"revPlanReq"}, {"name":"commitPlanReq"}, {"name":"schedOpen"}

Note:

For JSON output saGroupID must be replaced with egID, and saGroupName with egName
Fields ssGroupID and ssGroupName may not be used for JSON output.
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. Al 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 an 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 'BU -1'", "Insufficient permissions to view entities 'CT -1'", "Invalid entity: 'BU 1234567'", "Invalid entity: 'CT 1234567'", "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/ct-active-forecast request body(request for all fields): { "startDate":"2023-11-10", "endDate":"2024-11-10", "outputFormat":"PIPE", "dateFormat":"ddmmyyyy", "timeFormat":"12", "buIds":[ 500 ], "ctIds":[ 500 ] } request body(request for specific fields): { "startDate":"2022-11-10", "endDate":"2022-11-10", "outputFormat":"PIPE", "dateFormat":"ddmmyyyy", "timeFormat":"12", "buIds":[ 500 ], "ctIds":[ 500 ], "fields":[{"name":"custID"}, {"name":"TZ"}], "sortOrder":[{"name":"custID"}, {"name":"TZ"}]
Sample Call for JSON outputFormat	https://localhost/SMARTSync/services/rs/exporters/v1/ct-active-forecast request body(request for all fields): { "startDate":"2023-11-10", "endDate":"2024-11-10", "outputFormat":"JSON", "dateFormat":"ddmmyyyy", "keepEmptyJsonFields":true, "timeFormat":"12", "buIds":[ 500 ], "ctIds":[ 500 ] } request body(request for specific fields): { "startDate":"2022-11-10", "endDate":"2022-11-10", "outputFormat":"JSON", "dateFormat":"ddmmyyyy", "timeFormat":"12", "keepEmptyJsonFields":true, "buIds":[ 500 ], "ctIds":[ 500 ], "fields":[{"name":"custID"}, {"name":"TZ"}], "sortOrder":[{"name":"custID"}, {"name":"TZ"}] } }

Output Field Descriptions

This export runs for each BU specified in the buIds parameter. When run for a BU, the output includes the data for each CT that belongs to the BU during the specified date range, if you appropriately maintained the entity relationships and forecasts/plans.
In addition, this export runs for each CT specified in the ctIds parameter. If a CT specified in the ctIds element belongs to a BU that is also specified in the buIds element, the data for the CT is only included one time.

If the export runs for multiple CTs or BUs, all data is saved in the same output file.
The output file contains one record for each CT, for each statistics period of each date in the selected date range. CT hours are not taken into account.
For future dates and the current date, data is read from the forecast table. For past dates, the data is read from the result table.
The output file contains active forecast data only.
If data does not exist for a date in the specified range, that date is omitted from the output file.
For the system to calculate forecasted ASA (fcstASA), the service level time must be greater than 0.

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 CT Active Forecast output can contain these fields:

Field	Description	Values
date	The date, based on the CT’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 period, based on the CT’s time zone. The format of this time is specified in the timeFormat attribute. If no timeFormat attribute exists, 24-hour format is used.
TZ	The CT’s time zone.
custID	The customer ID.
saGroupID	The EG ID to which the CT belongs on the date being exported.	If the CT does not belong to an EG, this field is blank.
sagroupName	The EG name.	If the CT does not belong to an EG, this field is blank.
ssGroupID	The ID of the skill scheduling group to which the CT belongs on the date being exported.	This field is blank.
ssGroupName	The skill scheduling group name.	This field is blank.
buID	The ID of the BU to which the CT belongs on the date being exported.	If the CT does not belong to a BU, or if the BU cannot be determined because the user did not appropriately maintain the entity relationships and forecasts/plans, this field is blank.
buName	The BU name.	This field is blank if the CT does not belong to a BU, or if the BU cannot be determined.
ctID	The ID of the CT.
ctName	The name of the CT.
acdID	The ID of the CT’s default ACD.
modify	For future dates and the current date, this is the forecast record’s modify timestamp. For past dates, this is the result record’s modify timestamp.
fcstContactsReceived	The revised number of contacts forecast to be received for the period.	Formatted to 2 decimal places.
fcstContactsHandled	The revised number of contacts forecast to be handled for the period.	Formatted to 2 decimal places. This field is only populated for workload-based (multimedia) CTs.
fcstAHT	The revised forecasted average handle time for the period, in seconds.	Formatted to 2 decimal places.
fcstSLPct	The forecasted service level percentage for the period.	Value range and format: 0 – 100. This field is blank for workload-based CTs.
slPctObj	The service level percent objective for the period.	Value range and format: 0.00 - 100.00.
slTime	The service level time objective for the period, in seconds.
fcstOcc	The forecasted occupancy for the period.	Value range and format: 0 – 100.
maxOcc	The maximum occupancy objective for the period.	Value range and format: 0.00 - 100.00.
fcstASA	The forecasted ASA for the period.	No decimal places are shown for this value. This field is blank for workload-based CTs. If the forecast value exceeds 9999, the exported value is limited to 9999.
asaObj	The ASA objective for the period.	Formatted to 2 decimal places.
fcstReq	The revised forecast requirement for the period.	Formatted 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
revPlanReq	The revised plan requirement for the period. This is the same as fcstReq.	Formatted to 2 decimal places. If the value was not entered by a user, the system generated 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
commitPlanReq	The copied requirements for the period.	Formatted to 2 decimal places.
schedOpen	The number of agents scheduled to be open for the CT for the period. This is the sum of all opens values from MUSchedOpen and MUExternalOpen for the CT and the period being processed. If the statistics period is 30 minutes, the MUSchedOpen values for the two 15- minute periods that make up the 30-minute period are averaged together for each record included in the sum.	This value is rounded to two decimal places.

Supported output formats:

Pipe delimited
JSON

JSON Results with non empty fields

View code

var(--codeSnippetCopyLabel)

[
  {
    "date": "01012023",
    "period": "17:45",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "egID": "500",
    "egName": "EG_500",
    "ctID": "500",
    "ctName": "BU_500",
    "acdID": "1",
    "modify": "2022-10-07T09:45:35Z",
    "fcstContactsReceived": "430.00",
    "fcstAHT": "413.00",
    "slPctObj": "80.00",
    "slTime": "20",
    "fcstReq": "208.19",
    "revPlanReq": "208.19",
    "commitPlanReq": "208.19",
    "schedOpen": "0.00"
  },
  {
    "date": "01012023",
    "period": "17:30",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "egID": "500",
    "egName": "EG_500",
    "ctID": "500",
    "ctName": "BU_500",
    "acdID": "1",
    "modify": "2022-10-07T09:45:35Z",
    "fcstContactsReceived": "431.00",
    "fcstAHT": "489.00",
    "slPctObj": "80.00",
    "slTime": "20",
    "fcstReq": "246.29",
    "revPlanReq": "246.29",
    "commitPlanReq": "246.29",
    "schedOpen": "0.00"
  },
  {
    "date": "01012023",
    "period": "17:15",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "egID": "500",
    "egName": "EG_500",
    "ctID": "500",
    "ctName": "BU_500",
    "acdID": "1",
    "modify": "2022-10-07T09:45:35Z",
    "fcstContactsReceived": "291.00",
    "fcstAHT": "537.00",
    "slPctObj": "80.00",
    "slTime": "20",
    "fcstReq": "184.76",
    "revPlanReq": "184.76",
    "commitPlanReq": "184.76",
    "schedOpen": "0.00"
  },
  {
    "date": "01012023",
    "period": "17:00",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "egID": "500",
    "egName": "EG_500",
    "ctID": "500",
    "ctName": "BU_500",
    "acdID": "1",
    "modify": "2022-10-07T09:45:35Z",
    "fcstContactsReceived": "701.00",
    "fcstAHT": "429.00",
    "slPctObj": "80.00",
    "slTime": "20",
    "fcstReq": "347.24",
    "revPlanReq": "347.24",
    "commitPlanReq": "347.24",
    "schedOpen": "0.00"
  }
]

JSON Results with empty fields

View code

var(--codeSnippetCopyLabel)

[
  {
    "date": "01012023",
    "period": "17:45",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "egID": "500",
    "egName": "EG_500",
    "ctID": "500",
    "ctName": "BU_500",
    "acdID": "1",
    "modify": "2022-10-07T09:45:35Z",
    "fcstContactsReceived": "430.00",
    "fcstContactsHandled": "",
    "fcstAHT": "413.00",
    "fcstSLPct": "",
    "slPctObj": "80.00",
    "slTime": "20",
    "fcstOcc": "",
    "maxOcc": "",
    "fcstASA": "",
    "asaObj": "",
    "fcstReq": "208.19",
    "revPlanReq": "208.19",
    "commitPlanReq": "208.19",
    "schedOpen": "0.00"
  },
  {
    "date": "01012023",
    "period": "17:30",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "egID": "500",
    "egName": "EG_500",
    "ctID": "500",
    "ctName": "BU_500",
    "acdID": "1",
    "modify": "2022-10-07T09:45:35Z",
    "fcstContactsReceived": "431.00",
    "fcstContactsHandled": "",
    "fcstAHT": "489.00",
    "fcstSLPct": "",
    "slPctObj": "80.00",
    "slTime": "20",
    "fcstOcc": "",
    "maxOcc": "",
    "fcstASA": "",
    "asaObj": "",
    "fcstReq": "246.29",
    "revPlanReq": "246.29",
    "commitPlanReq": "246.29",
    "schedOpen": "0.00"
  },
  {
    "date": "01012023",
    "period": "17:15",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "egID": "500",
    "egName": "EG_500",
    "ctID": "500",
    "ctName": "BU_500",
    "acdID": "1",
    "modify": "2022-10-07T09:45:35Z",
    "fcstContactsReceived": "291.00",
    "fcstContactsHandled": "",
    "fcstAHT": "537.00",
    "fcstSLPct": "",
    "slPctObj": "80.00",
    "slTime": "20",
    "fcstOcc": "",
    "maxOcc": "",
    "fcstASA": "",
    "asaObj": "",
    "fcstReq": "184.76",
    "revPlanReq": "184.76",
    "commitPlanReq": "184.76",
    "schedOpen": "0.00"
  },
  {
    "date": "01012023",
    "period": "17:00",
    "TZ": "Europe/Kiev",
    "custID": "1",
    "egID": "500",
    "egName": "EG_500",
    "ctID": "500",
    "ctName": "BU_500",
    "acdID": "1",
    "modify": "2022-10-07T09:45:35Z",
    "fcstContactsReceived": "701.00",
    "fcstContactsHandled": "",
    "fcstAHT": "429.00",
    "fcstSLPct": "",
    "slPctObj": "80.00",
    "slTime": "20",
    "fcstOcc": "",
    "maxOcc": "",
    "fcstASA": "",
    "asaObj": "",
    "fcstReq": "347.24",
    "revPlanReq": "347.24",
    "commitPlanReq": "347.24",
    "schedOpen": "0.00"
  }
]

JSON Empty Result

View code

var(--codeSnippetCopyLabel)

[]

PIPE results with enabled headers

View code

var(--codeSnippetCopyLabel)

#fields:date|period|TZ|custID|saGroupID|saGroupName|ssGroupID|ssGroupName|buID|buName|ctID|ctName|acdID|modify|fcstContactsReceived|fcstContactsHandled|fcstAHT|fcstSLPct|slPctObj|slTime|fcstOcc|maxOcc|fcstASA|asaObj|fcstReq|revPlanReq|commitPlanReq|schedOpen
#sort:date
 
01012023|17:45|Europe/Kiev|1|500|EG_500|||500|BU_500|500|BU_500|1|1665135935|430.00||413.00||80.00|20|||||208.19|208.19|208.19|0.00
01012023|17:30|Europe/Kiev|1|500|EG_500|||500|BU_500|500|BU_500|1|1665135935|431.00||489.00||80.00|20|||||246.29|246.29|246.29|0.00
01012023|17:15|Europe/Kiev|1|500|EG_500|||500|BU_500|500|BU_500|1|1665135935|291.00||537.00||80.00|20|||||184.76|184.76|184.76|0.00
01012023|17:00|Europe/Kiev|1|500|EG_500|||500|BU_500|500|BU_500|1|1665135935|701.00||429.00||80.00|20|||||347.24|347.24|347.24|0.00

PIPE Results with disabled headers

View code

var(--codeSnippetCopyLabel)

01012023|17:45|Europe/Kiev|1|500|EG_500|||500|BU_500|500|BU_500|1|1665135935|430.00||413.00||80.00|20|||||208.19|208.19|208.19|0.00
01012023|17:30|Europe/Kiev|1|500|EG_500|||500|BU_500|500|BU_500|1|1665135935|431.00||489.00||80.00|20|||||246.29|246.29|246.29|0.00
01012023|17:15|Europe/Kiev|1|500|EG_500|||500|BU_500|500|BU_500|1|1665135935|291.00||537.00||80.00|20|||||184.76|184.76|184.76|0.00
01012023|17:00|Europe/Kiev|1|500|EG_500|||500|BU_500|500|BU_500|1|1665135935|701.00||429.00||80.00|20|||||347.24|347.24|347.24|0.00

CT Active Forecast DTD

View code

var(--codeSnippetCopyLabel)

<?xml version="1.0"?>
<!ELEMENT ctActiveForecast ((allFields | fieldList), sortOrder?)>
<!ELEMENT fieldList (fields)>
<!ELEMENT sortOrder (fields)>
<!ELEMENT fields (date | period | TZ | custID | saGroupID | saGroupName | ssGroupID |
ssGroupName | buID | buName | ctID | ctName | acdID | modify | fcstContactsReceived |
fcstContactsHandled | fcstAHT | fcstSLPct | slPctObj | slTime | fcstOcc | maxOcc | fcstASA |
asaObj | fcstReq | revPlanReq | commitPlanReq | schedOpen)+>
<!ELEMENT allFields EMPTY>
<!ELEMENT date EMPTY>
<!ELEMENT period EMPTY>
<!ELEMENT TZ EMPTY>
<!ELEMENT custID EMPTY>
<!ELEMENT saGroupID EMPTY>
<!ELEMENT saGroupName EMPTY>
<!ELEMENT ssGroupID EMPTY>
<!ELEMENT ssGroupName EMPTY>
<!ELEMENT buID EMPTY>
<!ELEMENT buName EMPTY>
<!ELEMENT ctID EMPTY>
<!ELEMENT ctName EMPTY>
<!ELEMENT acdID EMPTY>
<!ELEMENT modify EMPTY>
<!ELEMENT fcstContactsReceived EMPTY>
<!ELEMENT fcstContactsHandled EMPTY>
<!ELEMENT fcstAHT EMPTY>
<!ELEMENT fcstSLPct EMPTY>
<!ELEMENT slPctObj EMPTY>
<!ELEMENT slTime EMPTY>
<!ELEMENT fcstOcc EMPTY>
<!ELEMENT maxOcc EMPTY>
<!ELEMENT fcstASA EMPTY>
<!ELEMENT asaObj EMPTY>
<!ELEMENT fcstReq EMPTY>
<!ELEMENT revPlanReq EMPTY>
<!ELEMENT commitPlanReq EMPTY>
<!ELEMENT schedOpen EMPTY>