documentation.md

Cloud Fleet Routing

Contents

• Overview
  • Quick tour
    • Get an initial solution
    • Make some adjustments
    • Using metadata
    • Understanding the solver
  • Concepts
    • Overall system and workflow
    • Terminology
• Application components
• How To Guides
  • Planning routes and visits
  • Saving a solution
  • Starting from an empty scenario
• Frequently Asked Questions (FAQ)
• Advanced topics
  • Load scenarios from another system

Overview

back

Cloud Fleet Routing is an end-user web application that planners on transportation or logistics team can use to plan pickups and deliveries to locations using a fleet of vehicles.

Behind the scenes, Cloud Fleet Routing uses a powerful service from Google called the Fleet Routing API. Cloud Fleet Routing makes it easy for a Planner to do their daily work without having to know the details of how the Fleet Routing API works.

Cloud Fleet Routing lets users:

• Plan fleeting routing scenarios from a fresh start.
• Load pre-defined fleet routing scenarios from a local file or from a corporate transportation management system.
• Generate a plan or solution to a scenario by calling the Fleet Routing API behind the scenes.
• Make manual adjustments to the scenario or the solution, such as moving a shipment from one vehicle to another, or changing the time window of a pick-up.
• Save the resulting plan (solution) to the TMS so that vehicles can be dispatched.

Quick tour

back

Learn the basics of using Cloud Fleet Routing by getting a solution to a vehicle routing problem.

Get an initial solution

1. Download the sample scenario. If your browser opens this in a new tab, do Save As to save to your computer in a location you will remember.

2. Click Cloud Optimization AI in the top-left corner of the web page to get to the starting page.

3. Upload existing scenario and browse to where you save the sample-scenario.json file from Step 1 then click OK.

4. Let's find a solution for all of the Shipments and allow the solver to consider all Vehicles.

   1. Select the Planning Scenario > Shipments item on the left hand side of the page.

   2. In the Shipment Click the checkbox in the top row of the Shipments table to include all shipments.

      

   3. Click on Vehicles and select them all by clicking on the checkbox in the top row. Now that you have at least one Shipment and at least one Vehicle selected, the GENERATE button is available.

5. Click Generate.

   1. You will briefly see a Cancel button. If this were a more complex scenario you would have time to click it.

   2. Cloud Fleet Routing just submitted this small scenario representing a vehicle routing problem to Google's Fleet Routing API. It got a solution to the problem. The application switched to the Gantt view.

      

6. Click on the Toggle map tool to show a map of the solution proposed by the Fleet Routing API. You can see a map of central Paris with the planned vehicle route. There's an icon showing the Depot, and little triangular icons showing pickup locations.

   1. Pickups are shown as triangle pointing up, whereas drop-offs look like a downward-pointing triangle.
   2. The icons on the map are the same as the icons on the Gantt chart.

7. Click on one of the shipments on the map.

   1. This reveals the Visit popup. You can see the related Shipment and the Vehicle that will be making the visit.

      

   2. TIP: Shipments are pickups or deliveries. The act of making a pickup or a delivery in the Fleet Routing API is called a visit. So if you see Visit in Cloud Fleet Routing, just know that it's a specific vehicle making a stop at a location to pickup or drop something off.

8. Click the small link on the popup window for the Visit to open the Shipment for this visit to open the Shipment Detail. There's a lot on this screen but for now let's change the label from a simple number to something more helpful.

   

9. Click on the Label field and type a short label, e.g., order-123.

   1. TIP: Pressing the Tab key on your keyboard or clicking outside the field will turn that text into a label. You can also type a comma , to add another label.

10. Press the Save button on that Shipment Detail page.

    1. You can see that your map popup now shows a meaningful label.

Make some adjustments

Having a plan is great, but what if you have new information and want to get a fresh solution from the Google Fleet Management API? Cloud Fleet Routing has you covered. Let's make some changes:

1. Open Planning Scenario > Shipments to see the current VRP definition.

   1. Notice that Shipment #2 has both a pickup and a delivery. In the app a pickup and delivery are treated as a combination.

      

2. Click the Edit icon (little pencil) on the row for Shipment #2 to open the Shipment Detail view. Now that we're looking at the Pickup part of the shipment, we notice a few missing elements that we know should be changed.

   1. Notice that it's possible to provide more than one set of constraints (time windows, penalties) for a single pickup or delivery. Those are called visit request alternatives. But for now, we'll just update the one that has been provided.

   2. Update the Time window (also called the 'hard time window') for 7:00-8:30AM on July 4th, 2019. This is the time window within which the shipment *must be picked up, otherwise the Fleet Routing API solver will consider it a missed shipment.

   3. Update the Soft time window to start at 8:00AM on the same date. This indicates that the Fleet Routing API should try to get that shipment picked up after 8:00AM. That's different than the (hard) time window, which must be picked up during the 7:00-8:30AM window.

   4. You can also tell the solver that there is a penalty for not hitting the soft time window. Change the Earliness penalty to 2 / hour. The units are value-less, but you might assume that this means "2 euros penalty for each hour that the shipment is picked up early". Why Euros? Because it's in Paris, France!

      

   5. Finally, we'll switch to the delivery part of this shipment by clicking the Delivery icon at the top of the Shipment Detail form.

   6. Change Penalty cost to 30.00. This means that the penalty for missing this delivery altogether is 30.00 (following the previous statement about units, we can assume this is 30 Euros, but we don't specify the units).

      

   7. Click the Save button to see the updated information in the Shipment list view.

3. You have updated your Shipment. The action button changes from Generate (first time) to Regenerate. Click the Regenerate button.

   1. Oh no! We have a problem. One of the dates or times cannot be accommodated due to a global setting.

      

4. Click on the Scenario settings button on the top right of the application window.

   1. There are plenty of settings to adjust here. Go to Shipment Model tab. Notice that the Routes begin at Start Date field is July 14, 2019? Compare that with the Time Window column in the Shipment List table: we accidentally entered a shipment date of July 4th. That violates the global time window. We need to either adjust the global time window or adjust the shipment.

      

   2. Reopen the Shipment Detail view for that shipment, adjust the date to July 14th, 20219 on the Pickup screen.

   3. Click the Save button.

5. With our errors fixed, click the Regenerate button again.

Using metadata

back

Looks good...until you see in the key performance indicator (KPI) summary that a shipment was skipped. We'll use the metadata view to figure out what's happened.

1. Switch to the Metadata view then choose Metrics per shipment to see the complete list of shipments.

   

2. Sure enough, Shipment #2 was skipped.

   

Understanding the solver

back

Cloud Fleet Routing uses the Fleet Routing API, which is a solver for vehicle routing problems. The solver can make all kinds of optimizations to accommodate a wide variety constraints and demands, including setting penalty costs on shipments or fixed costs on vehicles.

Looking at the brief description of Skipped Shipments, we would hope to see a helpful Skipped Shipment Reason in the Metadata View. However, while there are some obvious reasons for one or more shipments to be skipped, the complexity of input scenarios can be very high, and that leads to shipments being skipped for reasons that may not be easy to reason about. The Fleet Routing API solver will not provide a Skipped Shipment Reason unless it can be very explicit about the reason. That means the reasons you see in the Metadata View are quite actionable, but when no reasons is given for a skipped shipment it can be hard to know where to start.

TIP: The Google team recommends a simple and iterative approach to handling skipped shipments. Iterative adjustments! Because the Fleet Routing API is relatively fast to generate solutions, you can tweak a value using the Shipment or Vehicle detail views, or the Scenario settings, and Generate a new solution. For example, if a Shipment is skipped and you see that it has a very low Penalty cost, try looking at the average cost of reach vehicle route in the solution, and at least making the penalty for that shipment higher than the average route cost. That will provide a strong hint to the solver that it is really expensive to skip that shipment.

Feel free to tweak, remove, or add additional parameters, shipment, and vehicles to get a sense for how the solver behind the Fleet Routing API works.

Saving your work

Use the Download button to save the solution to your local computer. You can open the result text file to see exactly what Cloud Fleet Routing is sending to the Fleet Routing API.

Application components

back

The main parts of the application are described here. This is not exhaustive, and screenshots might look a little different from the version in your browser as the application evolves.

Home screen

The home screen gives you three choices when you first open the application.

• Upload an existing scenario or solution. You have a JSON file that contains a VRP scenario you want to solve.
• Upload from CSV.
• Open a saved scenario or solution. The application is integrated with your TMS and you want to open a file exported from the TMS, or saved ready for use by the TMS.
• Build a new scenario. Start from an empty scenario and add shipments and vehicles manually.

App actions

Application actions work with scenario and solution files. Download and Upload work with local files from your computer, whereas Open and Save work with files that will integrated with the TMS.

Sidebar

The sidebar gives you a quick overview of the number of shipments and vehicles and uses gray (in progress), green (completed), and orange (warning) colors to indicate where you are in the application workflow. Possible solution actions are shown as buttons, like Generate.

Scenario settings

Scenario settings contains personal application settings like the local time zone. All times in the application are stored as Coordinated Universal Time (UTC). Changing the time zone just adjusts how it is displayed in the application; it does not change the underlying times.

Most other Scenario Settings affect how the Fleet Routing API solver will act on a given input VRP scenario.

Toolbar

The toolbar switches between the major Solution views in the application: the Gantt or 'timeline' view and the Metadata or 'report' view. The map tool toggles the visibility of the Google Map showing routes and shipments. The Undo and Redo buttons enable you to back out of changes or reapply them.

Shipment and vehicle planning views

Whether you create them or load them from an existing file, the Shipment Planning View (and related Vehicle Planning View) give you a list of items in the scenario and a way to select which items will be sent to the solver. Clicking on the checkbox next to the ID column will select or unselect all items. Use the Undo button if you make a mistake. Filters can be applied, and the list can be sorted by clicking on any column heading. Bulk Edit to edit multiple Shipments or Vehicles in one go. Choose which columns are visible using the column picker. Click on the pencil icon to edit any fields in the shipment or vehicle.

Add Item button

The Add Item button is visible on the bottom right of the Shipment and Vehicle planning list views. It's a large plus sign button floating in the lower-right corner. Clicking on the Add Item button will create a new empty Vehicle or Shipment, depending on which list is currently displayed.

Shipment edit view

NOTE: Not all of the capabilities or data supported by the Fleet Routing API are available in this form.

Clicking the pencil icon on any Shipment Planning List row opens the Shipment Edit View form. A Shipment has minimal required information: a single pickup or drop-off request alternative with a location defined. Everything is optional, but in almost all cases you will want to define demands, and likely also time windows and fixed costs and penalties.

Once a solution has been built, an abbreviated version of the form is available, called the Shipment Quick Edit view. The primary purpose of the Quick Edit is to tie a shipment to a subset of vehicles, or to change the pickup or drop-off time window. The Quick Edit form replicates the actions performed by dragging-and-dropping a shipment on the Gantt View.

Vehicle edit view

NOTE: Not all of the capabilities or data supported by the Fleet Routing API are available in this form.

Clicking the pencil icon on any Vehicle Planning List row opens the Vehicle Edit view form. There are zero required fields for Vehicles. So you can just click the Add Item and press Save on the the Vehicle Edit View and get a perfectly valid vehicle. Now typically, there will be a lot more going on: a start and end location; a start and end time; vehicle Capacities (Load Limits) that match shipment demands, etc.

If you are adding a new Vehicle in this way, we recommend at least adding a label so that you can differentiate vehicles in the list view.

back

Gantt View

Once a solution has been generated, the default view is the Gantt view. Gantt charts show time windows and dependencies between tasks. In Cloud Fleet Routing, each row in the chart is one route and it's associated visits. Pickups are shown using a triangle pointing up; drop-offs use a downwards-point triangle. If you drag a pickup and it has a related drop-off, you will see both move. The same is true if you drag a drop-off: the pickup will move.

While on the Gantt view you can:

• Click on the pencil icon on any row to open the vehicle edit view for that route.
• Click on the name of the vehicle servicing a route to open the Metadata View filtered to just that route.
• Apply filters to reduce the number of routes you see
• Drag and drop any visit along the timeline for the current route or drag to a different route entirely.

  TIP: Use filters to reduce the number of routes on the Gantt view before dragging-and-dropping

• Click the < and > icons on the timeline heading to slide backwards and forwards in time.
• Zoom in and out on time slices using the time slice dropdown. For example, choose 24 hours to see an entire day or 1 hour to fine tune a solution.`
• Quickly switch time zones. Remember that this does not change the underlying data; it helps you communicate local time zones to your team.

Map View

Clicking the Toggle Map button in the toolbar will show and hide the Map. This is a Google map that can optionally use your estimated location to center the map in a helpful spot. The map has several useful tools.

• Select routes. Select one or more individual routes.
• Toggle selected. Switches between displaying all routes and shipments, or just the selected routes and associated shipments.
• Satellite view. This is particularly handy when trying to find a precise location for a shipment pickup or drop-off. Enable Satellite view to find exactly where the vehicle must be.

Clicking on a single visit provides shortcuts to associated shipment and vehicle, plus some brief summary information.

Metadata View

The Metadata View lets you focus on the solution and drill down to specific routes and visits so you can understand and tweak them if needed. Use the Metrics per route and Metrics per shipment dropdown to toggle between Route (vehicle) and Visit (shipment) summaries. Filters are very capable to help focus on a subset. You can edit an existing filters by click on them.

The Skipped Shipment button is a quick way to access the Metadata View with the appropriate filter already in place. The button will be highlighted in orange if your solution has skipped shipments.

Any skipped shipments will have similar highlighting:

Warnings and messages

Warnings are presented in the app whenever it can detect that you have a potential cause for error or confusion, or are taking an action that might result in a suboptimal solution. For example, if you set the start or end time for a single shipment outside of the global time window defined in Global Settings you will see this:

Similar messages will show up on edit forms, e.g., if you define a Load Demand in a Shipment, but no Vehicles have a related Load Limit (capacity) you will see a hint.

Getting Started

The basic process in Cloud Fleet Routing is to either Open or Upload a scenario; Generate a solution; optionally adjust the parameters of the problem; then either Save or Download the solution.

back

Unless your organization has set up Cloud Fleet Routing differently, you will need the following before you can:

• A Google account. This will almost certainly not be a personal GMail account but rather a Google Workplace account or Google Cloud Identity associated with your organizational email address.
• A desktop web browser. Cloud Fleet Routing is not designed to work on a mobile web browser. It may work, but will be difficult to use because it has a complex user interface that assumes at least a laptop-size screen.

If your organization has set things up differently, then follow the instructions provided. For example, you may be asked to use single sign-on with your existing corporate login rather than a Google account.

Planning routes and visits

back

1. Open the application.
2. Click on the Open saved scenario or solution
3. Find then select one Scenario from the Open dialog. Click Open.
4. Select one or more Shipments in the Planning Scenario > Shipments window.
5. Select one or more Vehicles in the _Planning Scenario > Vehicles window.
6. Click Generate
7. Make any adjustments and iteratively use the Planning Scenario > Regenerate function.

Save a solution

back

Once you have planned a scenario or started from scratch you want to pass the work on to the TMS for scheduling, or save the file for further use.

1. Either click Save and follow the instructions in the dialog,
2. or click Download to store the scenario and solution on your local machine.

If you Download a file you can subsequently Upload it back into Cloud Fleet Routing. It's a handy way to experiment with scenarios.

TIP: If you save any file that you Download with the file extension *.json, as in my-scenario.json, then you can open it in a web browser or text editor to see what data the Fleet Routing API actually uses. Developers can look at the documentation (password protected) to learn more.

Starting from an empty scenario

back

1. Open the application
2. Click on the Build a new scenario button. This opens the Planning Scenario > Shipments view.
3. Click on the Add shipment button in the lower right corner of the app window.
4. Shipments must have at least one pickup or drop-off. Choose the Pickup or Delivery screen using the toggle button in the top-center of the Shipment Detail window.
5. A pickup or delivery must have at least one Pickup request alternative. Click Add pickup request alternative and enter the required data.
6. Click on the Planning Scenario > Vehicles view in the sidebar.
7. Click on the Add vehicle button in the lower right corner of the app window.
8. Everything in the Vehicle Detail is optional. You can just click Save to continue.
9. Use the checkboxes next to vehicles and shipments to include them in the scenario.
10. Click Generate to solve the VRP.

Concepts

back

Overall system and workflow

Cloud Fleet Routing can be used in a standalone mode: just use the Upload and Download tools to work with solution and scenario files on your computer. But it is designed to be part of a bigger overall fleet dispatching system with both: an upstream system supplying the word to be done, which we term vehicle routing problems or scenarios; and a downstream system that accepts the solutions that Cloud Fleet Routing user has generated.

From a Planner's perspective, Cloud Fleet Routing is just a web application that understands how to find work to be planned in the corporate TMS via the Open tool, and to be saved back to the corporate TMS using the Save tool.

Behind the scenes there is a little more going on. The corporate TMS is actually pushing work to be planned from the TMS and into Cloud Fleet Routing Storage component. And when the Planner hits the Save button, the solution (or routes ready to be run in the real world) are pushed back to that TMS behind the scenes via Cloud Fleet Routing Storage component.

The separate-but-related nature of Cloud Fleet Routing and the underlying data store for the vehicle routing problems to be solved ensures that each organization using Cloud Fleet Routing can integrate with whatever core business system they need to.

But as a Planner using Cloud Fleet Routing, just focus on _Open_ing work, planning it using the App, then Save-ing it back so drivers can start their routes.

Terminology

The API documentation contains much more detail these and additional terms.

• Vehicle routing problem (VRP). Given a set vehicles and locations, a solution to a VRP finds the optimal routes so that each location is visited by a vehicle.
• Shipment. A shipment is either a pickup or a delivery (or both) that must be performed by a vehicle at a location. In addition to vehicles, shipments are the primary input to a VRP that Cloud Fleet Routing handles. Shipments must have at least one potential pickup or delivery window. Shipments may also have Load Demand(capacities) stated in the same units as the capacities of vehicles. For example, if a shipment has a weight of 200 kilograms, that is how much Load Demand (capacity) that shipment will demand of a single vehicle.
• Vehicle. A vehicle performs pickups or dropoffs of shipments. Vehicles have properties called Load Limits (capacities) that are used by Cloud Fleet Routing to find the optimal vehicle to perfrom a pickup or dropoff. For example, a vehicle might have a Load Limit (capacity) of '2 pallets' or '20 cubic meters'. Vehicles may also have a starting and ending location, and various time constraints. The visits that make up a Shipment
• Scenario. A scenario is a vehicle routing problem (VRP) logistics problem that Cloud Fleet Routing can solve. It consists of one or more vehicles and one or more shipments.
• Solution. A solution is what the Fleet Routing API produces in response to a request to solve a scenario. Solutions are visible in Cloud Fleet Routing via the Gantt chart, on a map, or in the Metadata view.
• Transportation management system (TMS). A TMS is a generic term for the system or systems that an organization uses to generate a scenario for the planners using Cloud Fleet Routing to solve. TMSs typically contain order information that becomes a shipment, and information about the fleet of vehicles that will be used to deliver or pick up those shipments.
• Soft time window. Sometimes there is flexibility when a shipment needs to be picked up or dropped off. For example, a customer may say that they must have a delivery.
• Skipped shipment. The Fleet Routing API solver optimizes for minimum cost while considering a list of constraints. Given those inputs, it is possible or even likely that the solver cannot find a solution that has every shipment being picked up or deliver. Sometimes the reason that the solver has skipped a shipment is very clear. In those cases the Metadata view will list that reason. The full list of Reason Codes are in the developer documentation (may be behind a login) but DEMAND_EXCEEDS_VEHICLE_CAPACITY is a representative example.
• Pickup request alternative. It is common for a shipment pickup or shipment delivery to support more than one possible pickup or delivery alternative. For example, a package delivery company may have offered two potential delivery windows for a customer. The Pickup/Delivery Request Alternative is how that is modeled in the app.
• Load Demand. A load demand is what a vehicle will be delivering or picking up to satisfy a shipment. For example, a load demand might be 'One pallet' or '200 kilograms' or '15 refrigerated cases'. A load demand must have a type ('weight') and an amount ('2') and optionally units ('kilograms'). Load Demand types and amounts match up with similarly defined Load Limits (capacities) of vehicles. Matching one or more shipment load demands with one or more vehicle capacities is a key capability of the Fleet Routing API solver.

Frequently Asked Questions

back

Q: What's the difference between a penalty cost of zero (0) and a penalty cost that is not defined (empty)?

A: An undefined penalty cost on a shipment is interepreted as an infinite penalty cost. In the application UI this looks like an empty field:

An infinite penalty cost will cause the solver to attempt to handle that shipment at--almost literally--any cost.

Conversely, a penalty cost field that has defined numeric value is interpreted as a specific penalty cost. For example, if your assumed units of cost are Euros, then a penalty cost of 300 will be interpreted by the solver as: 'the cost of not handling this shipment is 300 Euros'.

As a result, setting a specific penalty cost on one shipment but not others can likely cause a shipment to be skipped.

Q: Why does Cloud Fleet Routing ask for access to my location?

A: This is just a convenience. If you do grant access to Browser Location and you are starting from an empty scenario, the Google Map will automatically be centered on your approximate location. If you are working on an existing scenario, the map will use the locations of the shipments and vehicles instead.

If you do not grant location permission, the app will use a default location specified in the configuration. You cannot override this default location.

Advanced Topics

back

Load scenarios from another system

NOTE: This is an advanced topic for IT and engineering staff. You will need to install the gcloud command-line tool and understand how to work with Google Cloud Platform resources.

The Open dialog supports an end user opening a valid Fleet Routing API scenario. But how do they get into that list in the first place? The application architecture diagram explains the big picture for TMS-to-Cloud Fleet Routing integration. The default integration approach that comes as part of Cloud Fleet Routing from Google Marketplace uses Google Cloud Storage. While most integrations will likely use something more elegant like the Google Cloud client libraries (like the Go client library for Cloud Storage), we can mimic the operation using a few commands.

Configure gcloud

We will use the convention $PROJECT as a placeholder for the name of the GCP project where you deployed Cloud Fleet Routing.

1. Open the GCP Cloud Console Service Accounts page. For example, https://console.cloud.google.com/iam-admin/serviceaccounts?project=$PROJECT.
2. Use the Actions >... > Create key menu for the Compute Engine default service account record.
3. Choose Key Type > JSON and save the resulting *.json file somewhere locally that you can find again, e.g., my_account_key.json.

Load Scenario

Now let's get a scenario loaded into Cloud Fleet Routing!

1. Download the sample scenario and save it as sample-scenario.json.

2. Configure gcloud with access to the necessary Google Cloud Platform resources in your project.

    gcloud config set project $PROJECTID
    gcloud auth activate-service-account --key-file=my_account_key.json

3. Find the GCS bucket that contains scenarios. The bucket name is something you will have configured when you deployed the app from the Google Marketplace, but it's good to validate before trying to copy files there:

    $ gsutil ls
    gs://some-bucket
    gs://dispatcher-solutions-dev/ # This is the one we want!
    gs://another-bucket
    ...

4. Use the gsutil tool to upload the sample scenario.

   TIP: By default the application is configured to look for a folder called scenarios and a subfolder named after a date, e.g., 2020-01-31.

    bucket=gs://dispatcher-solutions-dev
    path="scenarios/$(date +%Y-%m-%d)" # Get the right date-formatted destination
    destination="$bucket/$path/"
    gsutil cp sample-scenario.json $destination
    gsutil ls $bucket

5. Open Cloud Fleet Routing and use the Open function, you should see something like 2021-01-28/sample-scenario.json ready to work with.