Scheduled tasks

This document describes the scheduled tasks service in Fleet Engine. It assumes you have read What is Fleet Engine? and are aware of the specific Fleet Engine service capability that you need.

As you read this documentation, keep in mind the following:

  • You create tasks and associate them with a vehicle stop as a way to model the real-world association between the task and the location where the vehicle is expected to stop so that the driver can complete the task. Read Introduction to vehicles to better understand how vehicles work in Fleet Engine.
  • Fleet Engine for scheduled tasks uses the following resources: a Task and a DeliveryVehicle. Fleet Engine provides both a gRPC service and REST interfaces:
    • Task: gRPC and REST
    • DeliveryVehicle: gRPC and REST
    • For simplicity, this manual uses gRPC examples.

What is a scheduled task?

A scheduled task in Fleet Engine represents an individual action to be completed by a driver using a vehicle within the broader context of a transportation operation. It defines the specific objective for the driver. For example:

  • to deliver a good to a residence
  • to pick up a package for return to the shipment depot
  • to stop at a location to provide an on-site service for a customer
  • to make a scheduled stop for fueling the vehicle

Task elements

The following image illustrates these task elements in a standard scheduled journey for a vehicle.

Basic task fields

Field Description
Type Defines the type of action associated with the task.
Task ID A string that uniquely identifies the task within the system.
Planned location Specifies the intended location where the task should be performed. This location is not always the same as the planned location for the vehicle stop.
State Indicates whether the task is open or closed.
Task Outcome Indicates whether the task succeeded or failed.

Data model for tasks

The following diagrams illustrate the data model of the Task resource alongside the diagram for its associated DeliveryVehicle resource. You can review both diagrams to explore the relationships between the two resources, keeping in mind the following:

  • Planned location: Both vehicle stops and tasks have planned locations, distinct from each other.
    • For tasks, a planned location indicates where the driver action should occur. For example, 15 package deliveries to a large residential complex require delivery to different mail room locations within that same complex.
    • For vehicle stops, the planned location indicates the stop for the vehicle while the driver completes the tasks. For example, a vehicle stops at the entrance to an apartment complex, and the driver delivers the packages by hand to separate mail rooms within the complex.
  • State: Both tasks and vehicle stops have a state field, distinct from each other.
    • The state for the vehicle stop reflects the progress of the vehicle in relation to the stop, used for fleet tracking purposes.
    • The state for the task indicates whether or not the task is active. This impacts other operations to be done on tasks, such as setting its outcome or assigning it to a vehicle.
  • Task outcome: The task outcome is an important field in the data model, because it is used to indicate the success or failure of a task, independent of the task state.

  • IDs:

    • When you assign a task to a vehicle, Fleet engine populates the deliveryVehicleId field. This read-only field indicates the vehicle to which the task is assigned.
    • Task IDs are unique identifiers across all tasks in your system.
    • Tracking IDs identify a task for the purpose of shipment tracking.

Tasks data model

Vehicle data model

Task IDs

Similar to vehicle IDs in Fleet Engine, tasks must each contain an ID to distinguish them from other tasks within the system. You reference and manage all tasks in your workflow by their ID. You create these IDs by using the CreateTaskRequest service and by providing an ID string that conforms to the requirements described in this section.

This string then comprises part of the name of the task resource itself, an output-only field on the Task object. This is analogous to how Fleet Engine constructs vehicle name resources. See the Resource naming section in Introduction to Fleet Engine.

Task ID Requirements
Property Description
Uniqueness Each task ID must be unique within your Fleet Engine implementation to avoid confusion and ensure proper identification.
Format
  • No personally-identifiable information (PII) or clear text data.
  • Valid Unicode strings.
  • Maximum of 64 characters.
  • Exclude the following characters: / : \ ? #
  • Normalized according to Unicode Normalization Form C.
Task ID Examples
Good task ID examples
  • 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
  • e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
  • NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk
Disallowed task IDs
  • 8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680
  • JohnDoe-577b484da26f-Cupertino-SantaCruz
  • 4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a

Task types

Fleet Engine supports various task types to represent different actions within a transportation operation. They are described here along with their visibility and billing details.

Task Type Description Shipment Tracking Visibility Billed
Delivery Task Use for dropping off items or completing a task for a customer. Consumers can see and track this. Yes
Pickup Task Use to indicate picking up goods from a customer. You must have a corresponding delivery tasks for any pickup task. Consumers can see and track this. No
Unavailability Task Identifies the vehicle as unavailable for service, such as when the driver takes a break or refuels the vehicle. Not visible to consumers. No
Scheduled Stop Task A non-delivery task requiring a stop at a specific location. Use scheduled stop tasks for daily scheduled collection stops at a specific location, independent of other deliveries or pickups at the same location. You can also create scheduled stop tasks for collections from drop boxes or to model feeder-vehicle transfers or stops at service centers and service points. Consumers cannot track this specific task, but can see it as part of tracking other tasks. No

Task and journey lifecycle

This section provides details about the delivery task lifecycle within Fleet Engine. The task lifecycle is connected to the vehicle journey because the vehicle must travel to a stop in order for a driver to complete a task at its planned location.

1. Task creation

When you first create a task in Fleet Engine, you set the a variety of fields for the task independently from associating them with a stop.

Task properties
Property Description
State Set to OPEN
IDs Set the task and tracking ID if you use shipment tracking for your consumers.
Timing The planned duration for the task and its target time window. See Task timing for details.
Planned location Set the precise geographic coordinate where the task is to be completed.

2. Task assignment

When you assign a task to a vehicle, you do so in conjunction with a vehicle stop. Stops are latitude/longitude coordinates that indicate the location where the vehicle parks while the driver completes the tasks associated with the stop. Stops are typically an access point such as a loading dock, or a road-snapped location.

3. In progress

A state of a task is either OPEN or CLOSED. However, once a task is assigned to a vehicle, you can track its progress through its association to the vehicle and where the vehicle is in relation to the stop where the task is to be completed.

Once the vehicle departs from a stop or begins navigation, the status of the stop should change to ENROUTE. In this way, the consumer shipment tracking can update the recipient for a task with the number of stops remaining and estimated time of arrival. This also supports any real-time visualization for consumer shipment tracking or for fleet tracking.

4. Arrival and task outcome

When the vehicle arrives at a stop, the status of the stop should be set to ARRIVED. As with an ENROUTE stop status, this does not impact the state of the task itself, but supports both consumer notifications and any real-time reporting for fleet tracking used by your fleet operators. It also enables later analytics and reporting on your operation that you'd use for delivery optimizations.

Once the vehicle arrives at a stop, your system can handle the rest of the task journey using one of the following approaches:

  • Close out tasks as they are completed.

    When the driver marks the task complete, your system can remove it from the stop, but leave the stop with other tasks assigned to it.

  • Remove the entire stop from the vehicle.

    Once the driver marks all tasks complete and the vehicle is en route to the next stop, you can remove the entire stop from the vehicle. Fleet Engine automatically closes all tasks associated with a removed stop.

Closing a task does not indicate success or failure

Closing a task only indicates that the task is no longer considered in progress. For tasks in the CLOSED state, you set their outcome to either SUCCEEDED or FAILED. This is necessary both to indicate the actual outcome for shipment tracking and for proper billing. Fleet Engine charges only delivery tasks with a state of SUCCEEDED.

Once you set a task outcome, you cannot change it

When marking the outcome of a task, Fleet Engine automatically fills in the task outcome location with the last known vehicle location. You can, however, modify the task outcome time and task outcome location after they have been set and Fleet Engine won't override these fields.

5. Other task scenarios

Not all tasks you model in Fleet Engine fit into a typical journey flow. For example:

  • Pickup tasks. When you have a pickup task for a package to be returned to the depot for later processing, you should create a corresponding delivery task for that package, with the planned location set to the depot. Otherwise, pickup tasks generally follow the same flow as for delivery tasks.
  • Task reassignment. You cannot directly reassign a task to a different vehicle. Instead, to move a task from one vehicle to another, close the original task and then recreate it before assigning it the new vehicle. If you update the task ordering for a task that is already assigned to a different vehicle, Fleet Engine produces an error.
  • Deleting tasks. As with vehicles, Fleet Engine deletes tasks that have not been updated after seven days. If you try to re-use a task ID for one that has been previously closed, Fleet Engine returns an error if that ID has been used within the past seven days. Conversely, if you want to retain task data longer than seven days, you must implement that capability yourself, such as through a scheduled job to reset the 7-day clock.

Share task progress

In Fleet Engine, you can monitor task progress in real-time and share the driver's journey in two key ways:

  • Consumer experience for consumers to know the status of their shipment orders or requested service order.
  • Fleet tracking for your fleet operators to track and analyze the status of vehicles in the fleet.

Consumer experience

To share task progress, you set up the consumer experience using the JavaScript Consumer SDK. With the SDK, you can enhance a visual web or mobile app experience so consumers can monitor the status of their shipment along with estimated times of arrival and real-time location updates for the delivery vehicle. See Consumer SDK scheduled tasks overview.

The Consumer SDK contains a JavaScript map and data components components to connect with Fleet Engine. The map is a drop-in replacement for a standard google.maps.Map object. Your client should authenticate your end users and use the Delivery consumer role from your Google Cloud project to return only customer-specific information. Fleet Engine filters and redacts all other information in the responses. For example, during an unavailability task, no location information is shared with an end user.

In Fleet Engine, you enable the following settings to share task progress with the consumer:

  • Tasks use the TaskTrackingViewConfig property. Optional.
  • Tasks use a tracking ID, which the library needs to identify relevant tasks for a consumer.

Fleet Tracking

The JavaScript Fleet Tracking Library lets you visualize the locations of vehicles in their fleets in near real time. The library uses the Fleet Engine API to provide visualization of delivery vehicles as well as their assigned tasks. Like the JavaScript consumer SDK, it contains a JavaScript map component that is a drop-in replacement for a standard google.maps.Map entity with data components you use to connect with Fleet Engine.

This library shows the visibility of delivery vehicles as soon as they are created in Fleet Engine. For this implementation, you use the Fleet Engine Service Super User Cloud IAM role and you provide Java Web Token claim for access to the delivery vehicles and their associated tasks.

Scheduled task scenarios

This section shows a variety of task scenarios that summarize the information provided at this point in the guide. It's meant to help you understand the variety of ways you can model your transportation operations in Fleet Engine, depending on your business.

Delivery with tracking

This delivery scenario shows a scheduled stop task assigned to the depot both at departure from the depot at the beginning of the journey and arrival to the depot at the end of the journey. It also shows two delivery tasks for a stop, one of which failed. Use this assignment to enable tracking from and to the depot and as a way to model start and stop times for the day. No billing happens with scheduled stop tasks.

Pickup with depot delivery

This scenario shows how to model a pickup with its required corresponding delivery task. You set the return to the depot as a delivery for billing purposes.

Feeder vehicle

This scenario shows two deliveries with a scheduled stop in the middle for a feeder vehicle, where the purpose is to enable the delivery vehicle to return to the depot with a number of packages to be shipped out. You could also model the feeder vehicle with a scheduled stop.

Task Timing

Modeling the task times helps with effective route planning, ETAs, and managing delivery expectations. Fleet Engine offers two key functionalities to model and anticipate task timing, as described in this section.

Task duration

Task duration is set with the task_duration field, a required field that models the anticipated time that the driver spends completing tasks on a stop or for taking a break. For stops, this encompasses all necessary activities after arriving at a stop, such as unloading packages and interacting with the recipient. The more specific this information is, the better Fleet Engine can provide realistic arrival times and ETAs for subsequent stops in the journey. For field details, see Duration in the Protocol Buffers Documentation.

Target time window

Target time defines a proposed time range for a task, typically used for communicating to customers or for internal planning purposes. You set this with the target_time_window field, which consists of a start time and an end time. This doesn't directly influence any route calculations, but could be used for situation such as alerting a consumer about a time window for a package delivery, or when to expect a scheduled service worker to arrive.

Task Attributes

Task attributes in Fleet Engine provide a convenient way to filter tasks based on specific characteristics when using the ListTasks request. You can also use custom task attributes for analytics with Cloud Logging, along with communicating information to consumers or for fleet tracking. The purpose is similar to that for vehicle attributes: use this to craft a more focused perspective of your delivery operations.

Limitations and Restrictions

  • Custom attribute creation: Fleet Engine limits the number of custom attributes you can define per task. Contact your sales representative to request an increase to those limits.
  • Filtering capabilities: While offering filtering flexibility, task attributes don't replace core task data fields. Use them for additional filtering based on your specific needs.
  • Each attribute must have a unique key.
  • Don't include personally-identifiable information or other sensitive information in the attribute value, as these might be visible to the user.
  • Data validation: Ensure the data types and formats of your custom attributes are compatible with Fleet Engine's requirements.

What's next