The Strategic Movements Application Programming Interface allows a software developer an simple way to move logistics data into Strategic Movements for further processing.
Automation requests are made through a REST interface at www.mystrategicmovements.com/api/v1/automation with a POST message containing an AutomationRequest object in the body of the message.
Interface Classes
Automation requests may be processed synchronously or asynchronously. To specify asynchronous execution, a response URL is specified in the AutomationRequest. When the process is completed, a POST message is sent to that URL with the AutomationResponse object.
These are the objects used to request automation processes and to receive back status on each of the actions taken.
AutomationRequest
An AutomationRequest consists of several headers and a JSON body containing the data to be processed by Strategic Movements.
From C#, you can instantiate an AutomationRequest object, specifying the data that will be send in the headers.
From other languages, in the request being sent, specify the headers and place the JSON for the objects to be sent in the body.
Fields
| Default Name | Field Type | Description |
|---|---|---|
| ApiKey | string | When you create an account at Strategic Movements, you will be assigned an API key. This key is sent with each request. |
| ObjectType | string | The type of object being sent as the body of this request. |
| Action | string | The action to be taken. See the table below for a list of valid actions. |
| CallbackUrl | string | If the action is to be performed asynchronously, the URL to which the response message will be sent. If the action is to be performed synchronously, this should be omitted or set to null. |
ObjectTypes and Actions
| Object Type | Action | Description |
|---|---|---|
| Location | Upload | Upload one or more locations. |
| Plan | CreateSingleDatePlan | Create a new single date plan from the specified template and upload the jobs. |
| Plan | Submit | Submit plan for AI assignment process. |
| Plan | Upload | Upload the jobs to the specified plans. |
Constructor
public AutomationRequest(string apiKey, string objectType, string action, string callbackUrl = “”)
| Parameter | Description |
|---|---|
| apiKey | Sets the ApiKey field in the object. |
| objectType | Sets the ObjectType field in the object. |
| action | Sets the Action field in the object. |
| callbackUrl | Sets the CallbackUrl in the object. |
Request Method
public AutomationResponse Request(string url, string json)
| Parameter | Description |
|---|---|
| url | The URL of the StrategicMovements server. |
| json | The JSON for the data to be sent to the server. |
Request Headers
If the request is not created and sent using the AutomationRequest object, these are the required and optional headers to be sent with the request.
| Header | Description | |
|---|---|---|
| x‑walzik‑apiKey | Required | See ApiKey (above). |
| x‑walzik‑objectType | Required | See ObjectType (above). |
| x‑walzik‑action | Required | See Action (above). |
| x‑walzik‑callbackUrl | Optional | See CallbackUrl (above). |
AutomationResponse
This object is returned when the AutomationRequest is sent to Strategic Movements.
It contains a list of messages detailing the actions taken.
Fields
| Default Name | Field Type | Description |
|---|---|---|
| List | List of AutomationResponseItem objects | List of messages for each upload action taken. |
| Message | string | Status message. |
| RequestId | string | A unique identification that can be used to match requests to asynchronous responses. |
| Severity | string | Request result: Error, Info, Warning. |
AutomationResponseItem
This object contains the status for an action taken on any one item in the JSON object sent to Strategic Movements.
Fields
| Default Name | Field Type | Description |
|---|---|---|
| Message | string | Status message. |
| ObjectType | string | Type of object uploaded. |
| ObjectCode | string | JobCode, LocationCode, or PlanCode. |
| Severity | string | Upload result: Error, Info, Warning. |
JSON Schema
Each field has a default name. You can change the names of fields sent to Strategic Movements by changing the upload format from the Preferences menu.
Location
A Location is the physical place where a product is delivered and/or picked up; a service is performed; or a Trip starts or ends.
Locations are maintained on a tenant basis; that is, for a given API key, all Locations are available for use in all Plans.
Locations are identified by a code that may contain only alphabetic, numeric, and the dash characters. The code is required and may be up to 30 characters long.
If the Location has previously been geocoded; that is, the longitude (X) and latitude (Y) may be specified. If they are not specified, the earth position will be determined from the address given.
If the Location may be visited at only specific times of the day, time windows may be specified.
Time windows may be either soft or hard.
- A soft time window is one where the earliest arrival time must be between the specified start and end times; and the departure may be any time after that.
- A hard time window is one where the earliest arrival time must be between the specified start and end time; and the work must be completed on or before the specified end time.
If a time window is not used, the time window type should either be set to a null value or omitted.
Location Fields
| Default Field Name | Field Type | Description |
|---|---|---|
| addressLine1 | string(50) Required |
First line of address, used for geocoding. |
| addressLine2 | string(50) Nullable |
Second line of address, not used for geocoding. |
| city | string(30) Required |
Location city. |
| firstName | string (20) Nullable |
First name of customer. |
| lastName | string(30) Required |
Last name or company name of customer. |
| locationCode | string(30) Regex: “^[a-zA-Z0-9\-]*$” Either location or locationCode is required |
A unique code within the Tenant. |
| postalCode | string(10) Regex: “^[0-9]{5}(?:-[0-9]{4})?$” Required |
Location ZIP code. |
| state | string(2) Required |
Location state. |
| timeWindow1End | timeOfDay (see below) Nullable |
End of time window 1. |
| timeWindow1Soft | bool Nullable |
Time window 1 type: TRUE = soft time window; FALSE = hard time window; null = time window not used. |
| timeWindow1Start | timeOfDay (see below) Nullable |
Start of time window 1. |
| timeWindow2End | timeOfDay (see below) Nullable |
End of time window 2. |
| timeWindow2Soft | bool Nullable |
Time window 2 type: TRUE = soft time window; FALSE = hard time window; null = time window not used. |
| timeWindow2Start | timeOfDay (see below) Nullable |
Start of time window 2. |
| x | number Nullable |
Location longitude. |
| y | number Nullable |
Location latitude. |
Sample JSON (Required Fields)
{
“locations”:
[
{
“locationCode”: “Location1”,
“lastName”: “Mercaptan”,
“firstName”: “Ethyl”,
“addressLine1”: “79 Field St”,
“city”: “Torrington”,
“state”: “CT”,
“postalCode”: “06790”
},
{
“locationCode”: “Location2”,
“lastName”: “Syrah”,
“firstName”: “Kay”,
“addressLine1”: “152 Winsted Rd”,
“city”: “Torrington”,
“state”: “CT”,
“postalCode”: “06790”
}
]
}
Job
A Job is the work to be done at a Location on a specified date.
Jobs are identified by a code that may contain only alphabetic, numeric, and the dash characters. The code is required and may be up to 30 characters long.
Jobs are always assigned to a specific Plan.
A work time must be specified for each Job.
Jobs may have product with, optionally, two measurements. These measurements are usually weight and cube, but could be any units of measure, such as pallets or gallons.
Arrival times are usually computed from the Location’s time windows, if specified for the Location. When specified for the Job, they override those computed from the time windows.
Job Fields
| Default Field Name | Field Type | Description |
|---|---|---|
| deliveryCube | number Range 0:100000 |
Non-weight measurement of goods to be delivered. |
| deliveryWeight | number Range 0:100000 |
Weight measurement of goods to be delivered. |
| earliestArrivalTime1 | timeOfDay(see below) | The earliest allowed arrival time. If specified, overrides Location time window 1 start value. |
| earliestArrivalTime2 | timeOfDay(see below) | The earliest allowed arrival time. If specified, overrides Location time window 2 start value. |
| earliestDate | date | The earliest date for performing work. |
| jobCode | string(30) Regex: “^[a-zA-Z0-9\-]*$” Required |
A unique code within the Plan. |
| latestArrivalTime1 | timeOfDay(see below) | The latest allowed arrival time. If specified, overrides Location time window 1 end value. |
| latestArrivalTime2 | timeOfDay(see below) | The latest allowed arrival time. If specified, overrides Location time window 2 end value. |
| latestDate | date | The earliest date for performing work. |
| location | Location object | Place where work is to be done. Specify location or locationCode, but not both. |
| locationCode | The code for the location for this job | Place where work is to be done. Specify location or locationCode, but not both. |
| pickupCube | number Range 0:100000 |
Non-weight measurement of goods to be picked up. |
| pickupWeight | number Range 0:100000 |
Weight measurement of goods to be picked up. |
| userData0 | string(100) Nullable |
First user data field. |
| userData1 | string(100) Nullable |
Second user data field. |
| userData2 | string(100) Nullable |
Third user data field. |
| userData3 | string(100) Nullable |
Fourth user data field. |
| workTime | duration (see below) Required |
Estimated work time. |
Sample JSON (Required Fields Using Referenced Location)
{
“jobs”:
[
{
“jobCode”: “Job1”,
“locationCode”: “Location1”,
“workTime”: “00:30”
}
]
}
Sample JSON (Required Fields Using Embedded Location)
{
“jobs”:
[
{
“jobCode”: “MyJob”,
“location”:
{
“locationCode”: “MyLocation”,
“lastName”: “Mercaptan”,
“first”: “Ethyl”,
“addressLine1”: “79 Field St”,
“city”: “Torrington”,
“state”: “CT”,
“postalCode”: “06790”
}
“workTime”: “00:30”
}
]
}
Plan
A Plan is the work to be done and the resources to do that work for a given date.
Plans are identified by a code that may contain only alphabetic, numeric, and the dash characters. The code is required and may be up to 30 characters long.
When a new single date Plan is created, the plan code, template plan code and base date must be specified.
When jobs are added to a Plan, the plan code must be specifed.
When using the AI algorithm to assign Jobs in a single date plan to Trips, the planCode must be specified.
Plan Fields
| Default Field Name | Field Type | Description |
|---|---|---|
| baseDate | date | The date for plan execution. |
| jobs | List of Job objects | The lost of jobs to be included in the plan. |
| planCode | string(30) Regex: “^[a-zA-Z0-9\-]*$” Required |
A unique code. |
| templatePlanCode | string(30) | The name of an existing template plan used when creating a new single date plan. |
Sample JSON
{
“planCode”: “MyPlan”,
“templatePlanCode”: “MyTemplatePlan”,
“baseDate”: “2019-12-01”,
“jobs”:
[
{
“jobCode”: “Job1”,
“locationCode”: “Location1”,
“workTime”: “00:30”
},
{
“jobCode”: “Job2”,
“locationCode”: “Location2”,
“workTime”: “00:30”
},
{
“jobCode”: “Job3”,
“locationCode”: “Location3”,
“workTime”: “00:30”
}
]
}
Data Formats
Times are specified for two reasons: either the duration of an activity or a time of the day.
Fields Formats
| Format | Description |
|---|---|
| duration | Hours and Minutes 4:30 or 04:30 (four hours and thirty minutes).Decimal Hours 8.5 (eight and a half hours). The number must have a decimal point.Integer Minutes 75 (seventy five minutes, one hour and 15 minutes). The number must not have a decimal point. |
| timeOfDay | 24 Hour 8, 8:00, 08:00 or 17:00.12 Hour 8 AM, 8:00 AM, 08:00 AM, 5 PM, 5:00 PM or 05:00 PM. |