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
Taskand aDeliveryVehicle. Fleet Engine provides both a gRPC service and REST interfaces:
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
deliveryVehicleIdfield. 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.
- When you assign a task to a vehicle, Fleet engine populates the
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.
| Property | Description |
|---|---|
| Uniqueness | Each task ID must be unique within your Fleet Engine implementation to avoid confusion and ensure proper identification. |
| Format |
|
| Good task ID examples |
|
|---|---|
| Disallowed task IDs |
|
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.
| 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
TaskTrackingViewConfigproperty. 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.