documentation.md

Fleet Routing App

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

Fleet Routing App 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, Fleet Routing App uses a powerful service from Google called the Route Optimization API. Fleet Routing App makes it easy for a Planner to do their daily work without having to know the details of how the Route Optimization API works.

Fleet Routing App 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 Route Optimization 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 Fleet Routing App 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 Google Maps Platform in the top-left corner of the web page to get to the starting page.

3. Select Load, Choose a file, and browse to where you saved the sample-scenario.json file from Step 1. Upon selection, the file will be load and you will be taken into the application automatically.

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

   1. Select the Request Settings > 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. Fleet Routing App just submitted this small scenario representing a vehicle routing problem to Google's Route Optimization API. It got a solution to the problem. The application switched to the Timeline view.

      

6. The map is displayed over the top half of the page. You can see a map of central Paris with the planned vehicle route. There's an icon showing the Depot, and little circular icons showing pickup locations.

   1. Pickups are shown as circles with a caret pointing up, whereas drop-offs have downward-pointing caret.
   2. On the Timeline chart, an upward triangle represents a pickup and a downward triangle represents a drop-off.

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 Route Optimization API is called a visit. So if you see Visit in Fleet Routing App, 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 Route Optimization API? Fleet Routing App has you covered. Let's make some changes:

1. Open Request Settings > 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 Route Optimization 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 Route Optimization 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 Request Planning button on the top left of the application window.

   1. There are plenty of settings to adjust here (Hint: You can grab the divider between this view and to adjust how the space is shared between the two views.). 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, 2019 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 table view to figure out what's happened.

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

   

2. Sure enough, Shipment #2 was skipped.

   

Understanding the solver

back

Fleet Routing App uses the Route Optimization 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 Table 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 Route Optimization 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 Table 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 Route Optimization 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 Route Optimization 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 Fleet Routing App is sending to the Route Optimization 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 Route Optimization API solver will act on a given input VRP scenario.

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 Route Optimization 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 Timeline View.

Vehicle edit view

NOTE: Not all of the capabilities or data supported by the Route Optimization 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

Timeline View

Once a solution has been generated, the default view is the Timeline view. Timeline charts show time windows and dependencies between tasks. In Fleet Routing App, 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.

While on the Timeline 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 Table View filtered to just that route.
• Apply filters to reduce the number of routes you see
• 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

At the top of the view 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.

Table View

The Table 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 Table 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 Fleet Routing App 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 Fleet Routing App 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. Fleet Routing App 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 Request Settings > Shipments window.
5. Select one or more Vehicles in the _Request Settings > Vehicles window.
6. Click Generate
7. Make any adjustments and iteratively use the Request Settings > 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 Fleet Routing App. 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 Route Optimization 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 Request Settings > 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 Request Settings > 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

Fleet Routing App 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 Fleet Routing App user has generated.

From a Planner's perspective, Fleet Routing App 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 the Fleet Routing App 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 the Fleet Routing App storage component.

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

But as a Planner using Fleet Routing App, 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 Fleet Routing App 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 Fleet Routing App 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 Fleet Routing App can solve. It consists of one or more vehicles and one or more shipments.
• Solution. A solution is what the Route Optimization API produces in response to a request to solve a scenario. Solutions are visible in Fleet Routing App via the Timeline chart, on a map, or in the Table 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 Fleet Routing App 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 Route Optimization 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 Table 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 Route Optimization 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 Fleet Routing App 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 resources.

The Open dialog supports an end user opening a valid Route Optimization 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-Fleet Routing App integration. The default integration approach that comes as part of Fleet Routing App 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 Google Cloud project where you deployed Fleet Routing App.

1. Open the Google 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 Fleet Routing App!

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

2. Configure gcloud with access to the necessary Google Cloud 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 Fleet Routing App and use the Open function, you should see something like 2021-01-28/sample-scenario.json ready to work with.