Scheduling Response JSON
The response to the scheduling request is the optimized schedule for the specified job identifier, only if the data that has been passed is correct. If there is incorrect data or mismatch, the above scheduling request API returns an error file as a response, which contains the reason for failure.
Endpoint
https://<hostname>:<port>/optimax/scheduling/v2/schedules/<jobInstanceId>
Success Scenario
In the success scenario, the API returns a zip file that contains the following:
Route-wise Files with Schedules
A route corresponds to one day of one resource. For example, if there are three resources each with a horizon of two days, the scheduling response JSON file contains six routes in total.
The response contains route files for only those days where the schedule exists. Empty routes are not present.
The JSON files are typically named in the Route_<Technician name>_<Scheduled Route Date>. For example, Route_John_2020-02-13.
Example
{
"jobInstanceId": 377,
"routes": [
{
"routeId": "0",
"resourceId": "Terri-Test-Tech1",
"startLocationElementId": "Terri-Test-Tech1",
"endLocationElementId": "Terri-Test-Tech1",
"scheduledElements": [
{
"id": "WO-00305986",
"type": "WORK_ORDER",
"booking": {
"resource": "Terri-Test-Tech1",
"startTime": "2020-03-19T09:00:00Z",
"driveDuration": "PT5M45.945S",
"arrivalTime": "2020-03-19T09:05:45.945Z",
"idleDuration": "PT0S",
"serviceDuration": "PT1H",
"endTime": "2020-03-19T10:05:45.945Z"
},
"violations": [
{
},
{
}
]
},
{
"id": "Event-1",
"type": "EVENT",
"booking": {
"resource": "Terri-Test-Tech1",
"startTime": "2020-03-19T10:05:45.945Z",
"driveDuration": "PT0S",
"arrivalTime": "2020-03-19T10:05:45.945Z",
"idleDuration": "PT0S",
"serviceDuration": "PT2H",
"endTime": "2020-03-19T12:05:45.945Z"
}
}
],
"routeSummary": {
"startTime": "2020-03-19T09:00:00Z",
"endTime": "2020-03-19T12:11:31.89Z",
"routeDuration": "PT3H17M17.835S",
"drivingDuration": "PT11M31.89S",
"distance": "15221.587436035494 m",
"serviceDuration": "PT3H",
"idleDuration": "PT0S",
"returnDriveDuration": "PT5M45.945S",
"returnDistance": "7610.793718017747 m"
}
}
]
}
Field Descriptions
The following table lists all the fields and provides descriptions.
|
Element Type
|
Field
|
Description
|
Example
|
|---|---|---|---|
|
jobInstanceId
|
Job reference ID
|
||
|
routeId
|
Route ID
|
||
|
resourceId
|
The ID of the technician who is assigned to the route.
|
JohnSmith
|
|
|
startLocation
|
Element ID of the technician or starting event where the technician begins the route.
|
JohnSmith
|
|
|
endLocation
|
Element ID of the technician or ending event where the technician ends the route.
|
JohnSmith
|
|
|
scheduledElements
|
id
|
The ID of the scheduled element. Can be a work order number or event name.
|
WO-00305986
or
Event-1
|
|
type
|
Type of element. Can be a work order or an event.
|
EVENT
or
WORK_ORDER
|
|
|
booking>resource
|
Resource attached to the scheduled element.
|
JohnSmith
|
|
|
booking>startTime
|
Scheduled resource start time to work on the scheduled element.
Format: UTC.
|
2020-03-19T09:00:00Z
|
|
|
booking>driveDuration
|
Scheduled drive time will be taken to drive to the location of this scheduled element.
Format: PT<h>H<m>M<s>S
Where h is for hours, m for minutes, and s for seconds.
|
PT5M45.945S
|
|
|
booking>arrivalTime
|
The scheduled arrival time for the scheduled element.
Format: UTC.
|
2020-03-19T09:05:45.945Z
|
|
|
booking>idleDuration
|
The scheduled idle time for the scheduled element.
Format: PT<h>H<m>M<s>S
Where h is for hours, m for minutes, and s for seconds.
|
PT0S
|
|
|
booking>serviceDuration
|
The scheduled time that will be taken to service for this scheduled element.
Format: PT<h>H<m>M<s>S
Where h is for hours, m for minutes, and s for seconds.
|
PT1H
|
|
|
booking>endTime
|
Scheduled element end time.
Format: UTC.
|
2020-03-19T10:05:45.945Z
|
|
|
booking>violations
|
Violations for this element, if any.
|
||
|
routeSummary
|
startTime
|
Scheduled route start time.
Format: UTC.
|
2020-03-19T09:00:00Z
|
|
endTime
|
Scheduled route end time.
Format: UTC.
|
2020-03-19T12:11:31.89Z
|
|
|
routeDuration
|
Total time the technician spends in the route.
Format: PT<h>H<m>M<s>S
Where h is for hours, m for minutes, and s for seconds.
|
PT3H17M17.835S
|
|
|
drivingDuration
|
Total time spent in transit in the route.
Format: PT<h>H<m>M<s>S
Where h is for hours, m for minutes, and s for seconds.
|
PT11M31.89S
|
|
|
distance
|
Total distance covered in transit in the route.
Format: <distance<unit>
|
15221.587436035494 m
|
|
|
serviceDuration
|
The sum of service durations for all the work orders and events in the route.
Format: PT<h>H<m>M<s>S
Where h is for hours, m for minutes, and s for seconds.
|
PT3H
|
|
|
idleDuration
|
Total idle time in the route.
Format: PT<h>H<m>M<s>S
Where h is for hours, m for minutes, and s for seconds.
|
PT0S
|
|
|
returnDriveDuration
|
Drive time from the last event in the route to the technician's end location.
Format: PT<h>H<m>M<s>S
Where h is for hours, m for minutes, and s for seconds.
|
PT5M45.945S
|
|
|
returnDistance
|
Drive distance from the last event in the route to the technician's end location.
Format: <distance<unit>
|
7610.793718017747 m
|
Unresourced or Invalid Data
The unresourced data file is generated only if there are unresourced elements. If the input contains work orders that cannot be scheduled because of hard constraints or soft constraints being violated, the file contains those details with the corresponding message.
 |
If there is a large amount of unresourced or invalid data (work orders, events, or resources), the JSON files are batched. The batch size is 20.
|
Example
The following is a sample unresourced work order data JSON file.
{
"jobInstanceId": 880,
"unassignedSchedulingElements": [
{
"id": "a42e3b20-036f-4429-a374-3cdeb6939f1e",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
},
{
"id": "571085e0-1907-4bc7-a74d-6fff398fb8ae",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
},
{
"id": "5e1450a3-d00d-43a6-af2e-3176fec58616",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
},
{
"id": "0250cd4c-5a9b-4ae6-82ee-71d71187d450",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
},
{
"id": "5d06e8e4-2245-47c9-bea2-0e14d13c4fae",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
},
{
"id": "7686c96a-7d5d-4601-ba08-43cfbe2bedab",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
},
{
"id": "43f98ea7-ce00-4d67-b2f8-d1229df6024d",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
},
{
"id": "8232efe3-90da-4a7e-99b4-2acce615889b",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
},
{
"id": "9a45db74-b184-4d25-86ce-7d8cdf35e9a2",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
},
{
"id": "571bf876-751f-40ab-b2c3-4f5c971a6131",
"reason": "Maximum distance of the technician exceeded constraint is violated.",
"unscheduledElementType": "UNASSIGNED_WORK_ORDER"
}
]
}
Field Descriptions
The following table provides field descriptions.
|
Element Type
|
Field
|
Description
|
Example
|
|---|---|---|---|
|
jobInstanceId
|
Job reference ID
|
||
|
unassignedSchedulingElements
|
id
|
Element identifier which was passed in the scheduling input JSON.
|
a42e3b20-036f-4429-a374-3cdeb6939f1e
|
|
reason
|
Reason for unresourcing. This is an error message. For the list of error messages, see Error Codes and Messages.
|
The maximum distance of the technician exceeded constraint is violated.
|
|
|
unscheduledElementType
|
Can be one of the following:
BAD_WORK_ORDER, BAD_RESOURCE, BAD_EVENT, UNASSIGNED_WORK_ORDER, UNASSIGNED_EVENT.
The BAD prefix indicates input data was bad and could not be used for optimization. The UNASSIGNED prefix indicates was considered for optimization and got unassigned with the reason mentioned.
|
Statistics
The statistics file contains information about the schedules, such as the beginning of the earliest scheduled route and the end of the last scheduled route. This is across all the routes.
Failure Scenario
In the failure scenario, a scheduling input validation error file is returned. It means that the optimizer rejects the scheduling input and does not run the job at all.
Example
The following is an example error validation JSON file.
{
"serviceName": "/batch/optimize",
"errors": [
{
"entityName": "WorkOrder1",
"fieldName": "workOrderId",
"message": "workOrderId is empty."
},
{
"entityName": "Resource1",
"fieldName": "maxDistance",
"message": "maxDistance can not be negative."
}
]
}
Error Codes and Messages
For the list of error codes and messages, see Error Codes and Messages.