# Scheduled tasks

This document describes the scheduled tasks service in Fleet Engine. It assumes
you have read [What is Fleet Engine?](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials) 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](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials/vehicles-intro) 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](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1#task) and [REST](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks)
  - `DeliveryVehicle`: [gRPC](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1#maps.fleetengine.delivery.v1.DeliveryVehicle) and [REST](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.deliveryVehicles)
  - 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.

![](https://developers.google.com/static/maps/documentation/mobility/fleet-engine/essentials/images/taskGenericElements.png)

### 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.

> [!WARNING]
> **Experimental:** As an experimental feature, Fleet Engine now supports using a Place ID either alongside or instead of latitude/longitude. If a location has both Place ID and latitude-longitude, Fleet Engine uses latitude-longitude for routing, and Place ID for location feedback.

- **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.

  > [!IMPORTANT]
  > **Important:** Appropriate use of the task outcome ensures correct billing for your transactions.

- **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


![](https://developers.google.com/static/maps/documentation/mobility/fleet-engine/essentials/images/taskModelScheduled.png)

### Vehicle data model


![](https://developers.google.com/static/maps/documentation/mobility/fleet-engine/essentials/images/vehicleModelScheduled.png)

## 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](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials#resource-naming) section in
**Introduction to Fleet Engine**.

> [!TIP]
> **Tip:** You can create task IDs using whichever programmatic mechanism you prefer. Google recommends using a [version 4 UUID](https://tools.ietf.org/html/rfc4122) tool.

| 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](http://www.unicode.org/reports/tr15/). |
[Task ID Requirements]

| 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 ID Examples]

## 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](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials/tasks-intro#task-timing) for details. |
| Planned location | Set the precise geographic coordinate where the task is to be completed. |
[Task properties]

### 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.

> [!WARNING]
> **Experimental:** As an experimental feature, Fleet Engine now supports using a Place ID either alongside or instead of latitude/longitude. If a location has both Place ID and latitude-longitude, Fleet Engine uses latitude-longitude for routing, and Place ID for location feedback.

### 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.

> [!NOTE]
> **Note:** You can only directly close a task if it has never been assigned to a vehicle.

#### 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](https://developers.google.com/maps/documentation/mobility/journey-sharing/scheduled).

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.

> [!NOTE]
> **Note:** As an alternative, you can also implement your own consumer experience on top of the Fleet Engine API.

### 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](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1) 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.
![](https://developers.google.com/static/maps/documentation/mobility/fleet-engine/essentials/images/taskScenarioDelivery.png)

### 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.
![](https://developers.google.com/static/maps/documentation/mobility/fleet-engine/essentials/images/taskScenarioPickup.png)

### 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.
![](https://developers.google.com/static/maps/documentation/mobility/fleet-engine/essentials/images/taskScenarioFeeder.png)

## 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](https://protobuf.dev/reference/protobuf/google.protobuf/#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.

> [!NOTE]
> **Note:** All delivery tasks require a tracking ID field for ETA calculations from Fleet Engine.

## 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

- [Set up Fleet Engine](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet)
- [Create vehicles](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials/vehicles)
- [Create scheduled journeys](https://developers.google.com/maps/documentation/mobility/fleet-engine/journeys/tasks)