Update planning

Synchronize your TMS with Smartlane's optimization

In order have a 1:1 relation between the planning that results from the optimization process and manual changes that take place after the first and any succeeding optimization sent to the Smartlane API, we want to update each planning with the TMS changes. This will also enable you to add new shipments (deliveries and pickups) to the initial planning and let Smartlane find the best solution for adding these to a previous planning. In the future it will also help us to automate changes that follow recognizable patterns (e.g. this ad-hoc pickup will always be assigned to this vehicle and so forth).

We distinguish two ways of updating a previous planning:

  1. The dispatcher sends a previous planning and additional assigned shipment, i.e. each new shipment has a vehicle assigned and all shipments have a fixed order per route.
  2. The dispatcher sends a previous planning and a number of unassigned shipments. The Smartlane solver will do the assignment to the vehicles and run a re-optimization of all affected routes.

We don't allow a mixture of both use cases, so you either provide assignment and order of all shipments or you send unassigned shipments.

📘

Keep in mind that

we rely on the decision made by the dispatcher! In the first case we will not consider constraints (e.g. time windows for delivery, working hours of the drivers, requirements like tail lift etc.)

We will provide the following features that build on the initial and subsequent plannings. The first changes will consider new orders and manual optimizations by the dispatcher. After the trucks left the depot (dotted line) we will manage ad-hoc pickups. Only pickups that are in the future can be considered! Only deliveries that are on a non started route can be considered (if the multi-shift features is enabled).

We will describe the process step by step.

  1. Fixed order changes: New shipments, removed shipments, moved shipments
  2. New shipments, removed shipments, moved shipments with re-optimization

❗️

An important prerequisite for the update planning

is that all vehicles have a vehicle_custom_id and all shipments (delivery or pickup) have a delivery_custom_id. These are the reference that enables Smartlane to compare the initial planning with the update planning.
The id set by your TMS is the leading id for reference

Fixed order changes

These are the actions and the expected result after the update planning. We expect you to set the order_on_tour field for each shipment.

Action in TMS

Expected result after update planning

No changes

Everything will stay the same

A new shipment (delivery or pickup) has been added to a vehicle in the TMS

The new delivery is added at the exact position to the assigned vehicle (referred by the vehicle_custom_id

A shipment (delivery or pickup) that initially has been planned has been removed from a vehicle in the TMS

It is removed from the vehicle in the update planning.

A shipment hat has been moved from one vehicle to another vehicle is treated as a combination of the above

The shipment is removed from one vehicle and added to the other vehicle

These are the operations that we support.

After all changes have been applied, we will recalculate the ETA, DDT and els of each route.

For the update planning you send the same data structure that you sent in the initial planning. Make sure you add the properties delivery_custom_id and vehicle_custom_id. These are the references that link the planned shipments. Also make sure, all shipments have the order_on_tour field set. Keep the query parameter reoptimize with the default value false

import requests
import json

url = "https://<your company>.prd.smartlane.io/api/calcroute/update/dd6df03e-2135-11ec-839b-b64e025d2436?reoptimized=false"

payload = json.dumps({
  "deliverydata": [
    {
      "custom_id": "44041959",
      "customercompany": "ACME LTD",
      "street": "Some street",
      "postalcode": "33397",
      "city": "SOME CITY",
      "pdt_to": "2028-09-11T14:00:00+02:00",
      "vehicletype_name": "MAN_201",
      "load": 1000,
      "load_2": 0,
      "load_3": 2,
      "deliverprio": "high",
      "order_in_tour": 3
    }
  ],
  "departure_time_from": "2028-09-11T06:30:00+02:00",
  "departure_time_to": "2028-09-11T09:00:00+02:00",
  "return_time_to": "2028-09-11T17:00:00+02:00",
  "vehicles": [
    {
      "custom_id": "Vehicle_1",
      "name": "MAN 201",
      "vehicletype": {
        "vehicletypename": "MAN_201",
        "load_class": "LNV"
      },
      "capacity_1": 2500,
      "capacity_2": 999999,
      "capacity_3": 200,
      "traveltime_factor": 1.6,
      "daily_rate": 250,
      "km_rate": 0.35,
      "max_tour_duration": 645,
      "return_time_to": "2028-09-11T17:00:00+02:00",
      "fixed_els_seconds": 480,
      "variable_els_seconds_per_load": [
        0,
        0,
        12
      ],
      "depot_location": {
        "city": "Some other city",
        "postalcode": "33106",
        "street": "some other street",
        "housenumber": "1",
        "country": "DE"
      }
    }
  ]
})
headers = {
  'Authorization': 'JWT <your token>',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

Add unassigned shipments, make changes and re-optimize the route

Now you enable the re-optimization by setting the order_on_tour parameter to True. Be aware that we re-optimize the routes after we applied all changes. The order of the shipments for routes that had changes can differ from the initial planning.

This time the result after the update planning will consider the order defined by the TMS

Action in TMS

Expected result after update planning

No changes

Everything will stay the same

A new shipment (delivery or pickup) has been added to a vehicle in the TMS

The new shipment is added to the vehicle that fits best the constraints

A shipment (delivery or pickup) that initially has been planned has been removed from a vehicle in the TMS

It is removed from the vehicle in the update planning

A shipment hat has been moved from one vehicle to another vehicle is treated as a combination of the above

The shipment is removed from one vehicle and added to the other vehicle

After all changes have been applied, the routes will be re-optimized and the time windows will be re-calculated.

import requests

url = "https://customer_id.prd.smartlane.io/api/calcroute/update/process_id"

querystring = {"reoptimize":True}

payload = {"deliverydata": {
        "liftgate_needed": False,
        "trailer_needed": False,
        "adr_needed": False
    }}
headers = {d
    "Accept": "application/json",
    "Content-Type": "application/json"
}

response = requests.request("PUT", url, json=payload, headers=headers, params=querystring)

print(response.text)