Onfleet

Onfleet is a logistics software focused on dispatch and fleet management. You can leverage the power of Nextmv's Cloud API with the Onfleet integration. This integration offers functionality for interacting with the Onfleet API and leveraging Nextmv's extended optimization and routing features. The following entities are fetched and transformed from Onfleet API → Nextmv Cloud API:

• workers → vehicles.
• tasks → stops.

Once the entities have been transformed, the stops are routed and assigned to the vehicles and the final assignments are represented as Onfleet containers.

Endpoints

Authorization: Bearer <YOUR-API-KEY>

For the full specification, please visit the Nextmv Cloud API OpenAPI specification.

Using the integration

1. Create the tasks and workers you want to route. To leverage the full feature set of the Nextmv Cloud API, please check out the following sections:

   • Compatible features. Onfleet's API functionality that is compatible with Nextmv Cloud API.
   • Extensible features. Use Nextmv Cloud API features not supported by the Onfleet API.

2. Get the Nextmv and Onfleet API keys. This only needs to be done once.

3. Set up an Onfleet integration on Nextmv to securely store the Onfleet API key.

4. Create a run profile for using the Onfleet integration when requesting new runs, using the integration id and type obtained in the previous step. This only needs to be done once.

5. Send a request to the /v1/integrations/onfleet/run endpoint with a JSON body that follows the input schema to route and assign the desired tasks and workers, using the run profile id obtained in the previous step with the run_profile key. The API server should return a run_id that you will use to query your results. This means that a Nextmv solver has been spun up to solve the model with the given input. The time it takes to finish execution varies by the size of the input and solver options.

6. Poll the status of your run with the /v0/run/{run_id}/status endpoint, using the run_id. Once the status is succeeded, you can query your results. Please see our section on using the API for more information.

7. Get the result of your run with the /v0/run/{run_id}/result endpoint, using the run_id. The result holds the Onfleet containers that represent the final assignments of tasks to workers and it will follow the structure of the output schema. Please see our section on using the API for more information.

8. Update the container's tasks in the Onfleet API using the results optimized by the Nextmv Cloud routing engine.

9. Manage your configurations using the endpoints.

Set up the integration

The Onfleet integration lets you securely store one or more Onfleet API keys inside of Nextmv Cloud. Send a request to the /v1/routing/profiles/integration/onfleet endpoint with a JSON payload that follows this schema:

The configuration object allows you to securely store your Onfleet API key and optionally set up the compatibility feature explained below.

The compatibility object allows you to fine-tune which task and worker attributes are automatically parsed when supported by compatible functionality. Using the compatibility feature is optional. Any attribute that is not explicitly defined as false will be automatically parsed as true. The object follows this schema:

In the following two tables you will find the schema definition for the tasks and workers object, respectively.

• tasks schema (you can read more about compatible Onfleet task attributes here):

  Key	Description	Required	Sample value	Type
  complete_before_after	Parse the Onfleet task's completeBefore and completeAfter into a Nextmv stop's hard_window.	No	false	boolean
  dependencies	Parse the Onfleet task's dependencies into Nextmv stop's succeeds.	No	false	boolean
  location	Parse the Onfleet task's destination.location into the Nextmv stop's position. NOTE: if you turn this toggle off (false) you should make sure that you are specifying position via task metadata, otherwise your stop will not have a location and will cause an error.	No	false	boolean
  quantity	Parse the Onfleet task's quantity into the Nextmv stop's quantity.	No	false	boolean
  service_time	Parse the Onfleet task's serviceTime into the Nextmv stop's stop_duration.	No	false	boolean

• workers schema (you can read more about compatible Onfleet worker attributes here):

  Key	Description	Required	Sample value	Type
  active_task	Parse the Onfleet worker's activeTask to be part of the Nextmv vehicle's backlog.	No	false	boolean
  capacity	Parse the Onfleet worker's capacity into the Nextmv vehicle's capacity.	No	false	boolean
  location	Parse the Onfleet worker's location into the Nextmv vehicle's start position.	No	false	boolean
  tasks	Parse the Onfleet worker's tasks to be part of the Nextmv vehicle's backlog.	No	false	boolean

A sample schema and response are provided below:

{
  "name": "My Onfleet Configuration",
  "description": "my onfleet configuration for deliveries in LA",
  "id": "my-onfleet-integration",
  "configuration": {
    "api_key": "b4**************************8a7",
    "compatibility": {
      "tasks": {
        "quantity": false
      },
      "workers": {
        "active_task": false,
        "tasks": false,
        "capacity": true
      }
    }
  }
}

Make sure to store the id and type, as you will need them to add the integration to your run profile. Please note that you may set up multiple integration profiles using this method. You only need to do this process once for each API key.

To modify an existing Onfleet integration, you can use the PUT /v1/routing/profiles/integration/onfleet/{profile_id} endpoint with a JSON payload that follows the same schema as when creating a new integration (described in the table above). Note that you may not modify the original id.

Compatible functionality

Onfleet's API offers functionality that is compatible with Nextmv Cloud API. If compatible attributes are defined for tasks and/or workers, they will be parsed to Nextmv features. In the following tables you will find a list of these attributes.

Task compatible attributes

Worker compatible attributes

Extending functionality

To use Nextmv Cloud API features not supported by the Onfleet API, you may extend tasks and workers using Onfleet metadata. Metadata for tasks and workers is defined as an array of metadata objects. The name of each metadata object should follow this pattern:

"nextmv:<version>:<attribute>"

Where version dictates the metadata version used and attribute is the name of the Nextmv attribute used to extend the task or worker. An example of a name is: "nextmv:0.1:unassigned_penalty", used to set an unassigned penalty for a task (stop). You may use all (or none) supported metadata extensions for both tasks and workers. In the following tables you will find a list of these attributes.

Task extended attributes

Worker extended attributes

Input schema

The input schema is a JSON payload that has the following keys:

A sample input is provided as a .json file.

Routing options

The routing options is an object that has the following keys:

A sample routing object is provided as part of the input schema below.

Onfleet specification

The Onfleet specification is an object that has the following keys:

The tasks object is composed of the following keys:

The tasks params object specifies most query parameters used in the Onfleet list tasks endpoint. This endpoint is used in the backend to search for the given task ids. All the query parameters should be specified using snake_case.

The lastId query parameter is not provided, as the pagination is done automatically by the Nextmv Cloud API. Please note that there is a limit to the number of pages that are walked over. If the page limit is reached and there are tasks that haven't been found, an error will be returned in the /v0/run/run_id/status endpoint.

We recommend using the query parameters to fine-tune the search of the desired tasks. The params object is composed of the following keys:

The workers object is composed of the following keys:

The workers params object specifies most query parameters used in the Onfleet list workers endpoint. This endpoint is used in the backend to search for the given worker ids.

We recommend using the query parameters to fine-tune the search of the desired workers. The params object is composed of the following keys:

Output schema

The output schema is a JSON response that has the following keys:

A sample output response obtained after running the sample input is provided as a .json file.