Instantiating Jobs
The RouteCloud API can be used to instantiate jobs based on recurring schedules. To instantiate jobs, POST an instantiate_request in JSON format to /v1/instantiate, including a start date and the number of days as query parameters. For every schedule in the request, the RouteCloud API generates jobs based on the schedule's recurrence pattern, provided that jobs in the same time range do not already exist for the schedule.
Note that Instantiating Routes can be done in the same request as instantiating jobs.
Note
To run the examples in this tutorial, you will need:
- A RouteCloud API login. Use your Verizon Connect Enterprise username and password to authenticate with the RouteCloud API. To obtain a username and password, contact Verizon Connect sales.
- cURL to run the requests. You can download a cURL binary from here.
You can download a copy of the instantiate_jobs_request.json example instantiate request from here.
Run the request in the command line using cURL:
curl -u "youraccount%3Amain:password" "https://routecloud.telogis.com/v1/instantiate?start_date=2018-01-01&num_days=14" -H "Content-Type: application/json" --data-binary "@instantiate_jobs_request.json" -L
Substitute youraccount%3Amain for your username (replacing the colon with %3A), and password with your password. See the Authentication topic for more information and alternative authentication methods.
The RouteCloud API will generate jobs and should return a response within a few seconds.
Request
{
"schedules": [
{
"id": "schedule0",
"type": "daily",
"interval": 2,
"earliest_date": "2018-01-01",
"base_date": "2018-01-02",
"job_template": {
"location": "39.635928, -105.049219"
},
"jobs": [
"job0",
null,
null,
"job1"
]
},
{
"id": "schedule1",
"type": "weekly",
"interval": 1,
"earliest_date": "2018-01-01",
"base_date": "2018-01-02",
"allowed_variance_before": 2,
"job_template": {
"location": "39.725375, -104.791080"
},
"job_overrides": [
{
"ordinal": 1,
"type": "out_of_range"
}
]
}
],
"jobs": [
{
"id": "job0",
"location": "39.635928, -105.049219"
},
{
"id": "job1",
"location": "39.635928, -105.049219"
}
]
}
The instantiate_jobs_request.json request. Click here to open it in the UI.
The request JSON consists of an array of schedules, and and array of already existing jobs. The schedules will be used to generate new jobs, provided the target jobs do not already exist.
The request defines two schedules, both starting deliveries on January 1, 2018:
- A daily schedule "schedule0" with an interval of
2, meaning it will be delivered every other day:- A base_date of January 2 means that deliveries in January will occur on even-numbered dates,
- Two existing jobs are provided at ordinals 0 and 3, meaning that these ordinals will not be instantiated.
- A weekly schedule "schedule1", with an interval of
1, meaning it will be delivered every week:- A base_date of January 2 (a Tuesday) means that deliveries should occur on Tuesdays each week,
- An allowed_variance_before value of
2means that, while the target day of the week is Tuesday, it may be delivered on Sunday or Monday, - A job_override is provided for ordinal
1, meaning that this ordinal will not be instantiated.
Response
{
"schedules": [
{
"id": "schedule0",
"jobs": [
{ "ordinal": 1, "job": "11f7c913-9955-4f33-9d8b-ac7d5e2f3cc4", "target_date": "2018-01-04", ... },
{ "ordinal": 2, "job": "8b9768fb-917b-4ad9-9995-e6d8ec53e93a", "target_date": "2018-01-06", ... },
{ "ordinal": 4, "job": "4ecab7f5-1c00-46b6-9215-34ce7c38f9d3", "target_date": "2018-01-10", ... },
{ "ordinal": 5, "job": "f4898cd4-4c61-4d7d-9f9f-48034c8e7302", "target_date": "2018-01-12", ... },
{ "ordinal": 6, "job": "86fcdd77-41d4-48d1-8f16-1eacd952b81f", "target_date": "2018-01-14", ... }
]
},
{
"id": "schedule1",
"jobs": [
{
"ordinal": 0,
"job": "1c0949b8-11a5-4d38-901b-351e11e0d276",
"target_date_range": {
"from_date": "2018-01-01",
"num_days": 2
},
"target_date": "2018-01-02"
},
{
"ordinal": 2,
"job": "40b3893c-8df7-4889-bf3f-abb8a4c1b927",
"target_date_range": {
"from_date": "2018-01-14",
"num_days": 3
},
"target_date": "2018-01-16"
}
]
}
],
"jobs": [
{
"id": "11f7c913-9955-4f33-9d8b-ac7d5e2f3cc4",
"name": "schedule0 [1]",
"location": "39.635928,-105.049219"
},
{
"id": "8b9768fb-917b-4ad9-9995-e6d8ec53e93a",
"name": "schedule0 [2]",
"location": "39.635928,-105.049219"
},
{
"id": "4ecab7f5-1c00-46b6-9215-34ce7c38f9d3",
"name": "schedule0 [4]",
"location": "39.635928,-105.049219"
},
{
"id": "f4898cd4-4c61-4d7d-9f9f-48034c8e7302",
"name": "schedule0 [5]",
"location": "39.635928,-105.049219"
},
{
"id": "86fcdd77-41d4-48d1-8f16-1eacd952b81f",
"name": "schedule0 [6]",
"location": "39.635928,-105.049219"
},
{
"id": "1c0949b8-11a5-4d38-901b-351e11e0d276",
"name": "schedule1 [0]",
"location": "39.725375,-104.791080"
},
{
"id": "40b3893c-8df7-4889-bf3f-abb8a4c1b927",
"name": "schedule1 [2]",
"location": "39.725375,-104.791080"
}
]
}
A snipped version of the instantiate_jobs_request.json response. The full response is available here. Click here to open in the UI.
The response object consists of an array of job objects, and an array of schedule_instantiate_response objects detailing the target dates of each created job. Each job has a copy of the details from the job_template, but does not have information about dates as this is calculated from the schedule.
Explanation:
schedule0is configured to be delivered on every even-numbered date.- For this instantiate period, this means that it could be delivered on the following dates in January: 2, 4, 6, 8, 10, 12, and 14.
- Since there are already jobs existing at ordinals 0 and 3, these ordinals are not instantiated and therefore no jobs are created for January 2 or 8.
- Each job has a copy of the location from
schedule0's job_template.
schedule1is configured to be delivered every Tuesday, with up to two days' variance beforehand.- For this instantiate period, this means that it could be delivered on January 2 and 9.
- The first delivery has a target date of January 2, meaning that the allowed variance would put the start of its target range at December 31. The target date range is set shorter to ensure it is not delivered before the earliest_date.
- Since there is a job override for ordinal 1, it is not instantiated and therefore no job is created for January 9.
- The next delivery would be on January 16, which is outside of the instantiate period. However, after taking into account allowed variance the target window begins on January 14, so this is included.
These jobs can then be assigned to routes in an optimal fashion using a build request.
What Next?
- Continue to Building Routes.
- View the /v1/instantiate reference.
- Back to Instantiating Routes.