MU Forecast

API Specification

Description Creates a task for workmanager to execute exportEngine for MU-forecast exporter.
Authentication
Required 		Yes
URL https://<domain or IP>/SMARTSync/services/rs/exporters/v1/mu-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 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, JSON output will contain empty values ({},[],"") for fields.

excludePipeHeader - Boolean field.

Required: false.

Notes: This field can only be set if outputFormat is set to PIPE. By default it is set to false. If it is set to true, PIPE output will contain header and sort in results 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":"muID"}, {"name":"muName"}, {"name":"modify"}, {"name":"revPlanReq"}, {"name":"commitPlanReq"}, {"name":"open"}, {"name":"planOpen"}

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":"revPlanReq"}, {"name":"commitPlanReq"}, {"name":"open"}, {"name":"planOpen"}

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.

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: 'dataFormat'",
"Invalid dateFormat value: 'wrong'",
"Invalid timeFormat value: 'wrong'",
"startDate must match the provided yyyy-MM-dd format",
"endDate must match the provided yyyy-MM-dd format",
"Insufficient permissions to view entities 'MU -4'",
        "Invalid entity: 'MU 1234567'"
    ]
}
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/mu-forecast

request body(request for all fields):


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


request body(request for specific fields):

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

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

request body(request for all fields):


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


request body(request for specific fields):

{
"outputFormat": "JSON",
"startDate": "2022-01-01",
"endDate": "2023-12-20",
"dateFormat": "ddmmyyyy",
"timeFormat": "12",
"muIds": [
500
    ],
"fields": [{"name":"TZ"}],
"sortOrder": [{"name":"TZ"}]
}

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.

  • For each MU and each period in the specified date range, the output file contains a record for each CT for which the MU has data. That is, a record prints for each CT for which the MU has allocations from a CT.

This export uses the MU 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 Forecast output can contain these fields:

Field

Description

Values

date

The date, based on the MU’s time zone.

 

period

The start time of the statistics period.

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.

 

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

This is a CT for which the MU has requirements allocated on the date being processed.

Records are printed for each CT for which the MU has requirements 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 represents 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.

 

revPlanReq

The MU’s revised plan requirement for the CT for the period.

This value is rounded to two decimal places. If no data is found for the MU or the CT in any of the plan/forecast allocation tables, this field is blank.

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.

 

This value is rounded to two decimal places.

If no data is found for the MU or its CT in any of the plan/forecast allocation tables, this field is blank.
open

The MU’s number of scheduled open minutes for the CT. This is the sum of the opens value for the period and CT in the MU schedule open and MU external open tables.

Since data is always stored in the MU schedule open in 15-minute periods, the data for the two 15-minute periods that make up a 30-minute period is averaged together and printed in this field, if the customer’s statistics period length is 30 minutes.

Formatted to 2 decimal places.

planOpen

The MU’s planned number of open minutes stored by the system each night for the following date.

 

 

Supported output formats:

  • PIPE
  • JSON

PIPE result with pipe header

var(--codeSnippetCopyLabel) 
#fields:date|period|TZ|custID|saGroupID|saGroupName|ssGroupID|ssGroupName|buID|buName|ctID|ctName|muID|muName|modify|revPlanReq|commitPlanReq|open|planOpen
#sort:date,period,TZ,custID,saGroupID,saGroupName,ssGroupID,ssGroupName,buID,buName,ctID,ctName,muID,muName,modify,revPlanReq,commitPlanReq,open,planOpen
 
05042022|12:00AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|12:15AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|12:30AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|12:45AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|01:00AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|01:15AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|01:30AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|01:45AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|02:00AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|02:15AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|02:30AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|02:45AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|03:00AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00

PIPE result without pipe header

var(--codeSnippetCopyLabel) 
05042022|12:00AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|12:15AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|12:30AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|12:45AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|01:00AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|01:15AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|01:30AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|01:45AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|02:00AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|02:15AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|02:30AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|02:45AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00
05042022|03:00AM|US/Central|1|500|EG_500|||500|BU_500|500|CT_500|500|MU_500|1649176169|0.00|0.00|0.00|0.00

JSON result empty

var(--codeSnippetCopyLabel) 
[]

JSON result with empty fields

var(--codeSnippetCopyLabel) 
[
    {
        "date": "05042022",
        "period": "12:00AM",
        "TZ": "US/Central",
        "custID": "1",
        "saGroupID": "500",
        "saGroupName": "EG_500",
        "ctID": "",
        "ctName": "",
        "muID": "500",
        "muName": "MU_500",
        "modify": "2022-04-05T16:29:29Z",
        "revPlanReq": "0.00",
        "commitPlanReq": "0.00",
        "open": "0.00",
        "planOpen": "0.00"
    },
    {
        "date": "05042022",
        "period": "12:15AM",
        "TZ": "US/Central",
        "custID": "1",
        "saGroupID": "",
        "saGroupName": "",
        "ctID": "500",
        "ctName": "CT_500",
        "muID": "500",
        "muName": "MU_500",
        "modify": "2022-04-05T16:29:29Z",
        "revPlanReq": "0.00",
        "commitPlanReq": "0.00",
        "open": "0.00",
        "planOpen": "0.00"
    }
]

JSON result without empty fields

var(--codeSnippetCopyLabel) 
[
    {
        "date": "05042022",
        "period": "12:00AM",
        "TZ": "US/Central",
        "custID": "1",
        "saGroupID": "500",
        "saGroupName": "EG_500",
        "ctID": "500",
        "ctName": "CT_500",
        "muID": "500",
        "muName": "MU_500",
        "modify": "2022-04-05T16:29:29Z",
        "revPlanReq": "0.00",
        "commitPlanReq": "0.00",
        "open": "0.00",
        "planOpen": "0.00"
    },
    {
        "date": "05042022",
        "period": "12:15AM",
        "TZ": "US/Central",
        "custID": "1",
        "saGroupID": "500",
        "saGroupName": "EG_500",
        "ctID": "500",
        "ctName": "CT_500",
        "muID": "500",
        "muName": "MU_500",
        "modify": "2022-04-05T16:29:29Z",
        "revPlanReq": "0.00",
        "commitPlanReq": "0.00",
        "open": "0.00",
        "planOpen": "0.00"
    }
]

MU forecast DTD

var(--codeSnippetCopyLabel) 
<?xml version="1.0"?>
<!ELEMENT muForecast ((allFields | fieldList), sortOrder?)>
<!ELEMENT fieldList (fields)>
<!ELEMENT sortOrder (fields)>
<!ELEMENT fields (date | period | TZ | custID | saGroupID | saGroupName | ssGroupID |
ssGroupName | buID| buName | ctID | ctName | muID | muName | modify | revPlanReq |
commitPlanReq | open | planOpen)+>
<!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 muID EMPTY>
<!ELEMENT muName EMPTY>
<!ELEMENT modify EMPTY>
<!ELEMENT revPlanReq EMPTY>
<!ELEMENT commitPlanReq EMPTY>
<!ELEMENT open EMPTY>
<!ELEMENT planOpen EMPTY>