This document assumes you understand how to create and use tasks. It provides
specific examples for how to configure shipment tasks in the following ways:

- **Set the target time window for a shipment task**: Set the window of time
  for the task to be completed.

- **Customize task visibility**: Customize visibility of task activities for
  display to customers or fleet operators.

See [Create shipment tasks](https://developers.google.com/maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks.md.txt) for details about fields for shipment tasks.
When you update additional information about existing tasks, you must also
include the relevant identifier for the task, in addition to the fields you
update for the tasks.

## Set the target time window

The target time window is the [TimeWindow](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.md.txt#timewindow) during which the task should be
completed. For example, if you communicate a delivery time window to delivery
recipients, you can use the task target time window to capture this time window
and generate alerts, or you can use this to analyze past trip performance.

The target time window consists of a start time and an end time and can be set
on any task type. The target time window does not affect routing
behavior.

The following examples shows how to set the time window using the [Java gRPC
library](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks#java) or how to make an HTTP REST request to [`UpdateTask`](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/patch.md.txt). You can
also set this field at the time of task creation.

### gRPC

```java
  static final String PROJECT_ID = "my-delivery-co-gcp-project";
  static final String TASK_ID = "task-8241890";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
  Task task = Task.newBuilder()
    .setName(taskName)
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .build();

  // Task request
  UpdateTaskRequest updateTaskRequest =
    UpdateTaskRequest.newBuilder()  // No need for the header
        .setTask(task)
        .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
        .build();

  try {
    Task updatedTask = deliveryService.updateTask(updateTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case NOT_FOUND:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }
```

### REST

To set a task time window using HTTP, call `PATCH` and
use `updateMask` to update the `targetTimeWindow` parameter:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`

Here *\<id\>* is a unique identifier for the task. The request header
must contain a field *Authorization* with the value *Bearer \<token\>* ,
where *\<token\>* is issued by your server according to the guidelines
described in [Service account roles](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts.md.txt) and [JSON Web tokens](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt.md.txt).

```bash
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
  curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
    -H "Content-type: application/json" \
    -H "Authorization: Bearer ${JWT}" \
    --data-binary @- << EOM
  {
    "targetTimeWindow": {
      "startTime": "2023-03-29T21:00:00Z",
      "endTime": "2023-03-29T23:00:00Z"
    }
  }
  EOM
```

## Customize task visibility

By default, Fleet Engine provides visibility into task activities that can then
be displayed to both customers receiving a shipment and to fleet operators
tracking shipments. This includes such information as indicating the number of
stops before sending a customer a notification about their package delivery
status. You can customize this information on a per-task basis to better suit
your business model.

This section describes the visibility rules for tracked objects on the map.
These rules apply to two categories of objects:

- Location marker visibility
- Task data visibility for active vehicle tasks, such as polylines and ETA

> [!NOTE]
> **Note:** You can also customize the default visibility configuration for your project by [contacting the support team](https://console.cloud.google.com/google/maps-apis/support).

### Location marker visibility rules

Fleet Engine displays location markers for the shipment delivery location
shown on the map, regardless of the state of the delivery.

### Task data visibility rules

This section describes the default visibility rules that apply to task data.
You can only customize *active vehicle tasks*, which means that only
pickup and drop-off tasks can apply customized visibility rules.

The following tasks may not be customized:

- Scheduled stops
- Unavailability tasks
- Inactive vehicle tasks

#### Unavailability tasks visibility rules

By default, the vehicle does not appear on the map if at least one
unavailability task is assigned to task being tracked. For example, if the
driver is taking a break or the vehicle is being refueled on the route to the
tracked shipment. The estimated arrival time and estimated task completion time
are still available. Again, you may not customize this rule.

#### Active vehicle tasks visibility

The [`TaskTrackingInfo`](https://developers.google.com/maps/documentation/javascript/reference/journey-sharing-fleet-engine-entities.md.txt#TaskTrackingInfo) object provides a number of data elements that you
can make visible using the Shipment Tracking Library. By default, these fields
are visible when the task is assigned to the vehicle and when the vehicle is
within 5 stops of the task. The visibility ends when the task is completed or
canceled.

You can customize the visibility configuration on a per-task basis by setting
the [`TaskTrackingViewConfig`](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.md.txt#tasktrackingviewconfig) on a task when creating or updating the task
within Fleet Engine. This creates rules for individual data elements to be
available.

The following table shows the fields you can apply visibility rules to.

| Vehicle task fields for visibility rules |
|---|
| - Route polylines - Estimated time to arrival - Estimated task completion time - Remaining driving distance to the task - Remaining stop count - Vehicle location |

This table shows the visibility options available for the fields listed above.

| Visibility options |
|---|
| - Remaining stop count - Duration until estimated arrival time - Remaining driving distance - Always visible - Never visible |

> [!NOTE]
> **Note:** Each data element can only be associated with one visibility option. You cannot combine criteria using OR or AND.

### Route polylines and vehicle location visibility rules

For a tracked route, the visibility of route polylines is subject to the
visibility of the vehicle. If a route polyline is visible on an active route
where the vehicle **isn't visible**, the vehicle location can still be
inferred by the end of the visible polyline. Therefore, route polyline
visibility must be as restrictive or more restrictive than vehicle visibility.

Follow these rules to provide a valid route polylines / vehicle location
visibility combination.

#### Route polylines and vehicle location specify the **same** visibility options

In this scenario, both the polyline and the vehicle location set the same
options, which include:

- remaining stop count
- duration until ETA
- remaining driving distance

To adhere to the rules, the value for route polylines visibility must be **less
than or equal to** the value set for the vehicle visibility. In this example,
the remaining stop threshold for the polyline is set to 3, which is less than
the value of 5 specified for the vehicle. This means that, when the tracked
journey reaches 5 stops away from the task location, the vehicle appears, but
the route for that vehicle does not appear until the journey is 3 stops away.

    ```js
    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingStopCountThreshold": 5
      },
    }
    ```

#### Route polylines and vehicle location specify the **different** visibility options

When route polylines and vehicle location have **different** visibility options,
vehicle location is only visible when **both** of their visibility options are
satisfied. Again, the polyline visibility is subject to the visibility rules
of the vehicle:

- **Always visible** : A route polyline must use the *always visible* visibility option when the vehicle location also provides that same *always
  visible* visibility option.
- **Never visible** : A route polyline must use a *never visible* visibility option when the vehicle location uses a *never visible* visibility option.

An example follows:

```javascript
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "vehicleLocationVisibility": {
      "remainingDrivingDistanceMetersThreshold": 3000
    },
  }
```

In this example, the vehicle location is only visible if the remaining stop
count is at least 3 **AND** the remaining driving distance is at least 3000
meters.

### Example task visibility customization

The following examples show how to set a task with the following
visibility rules:

- Show the route polylines if the vehicle is within 3 stops.
- Show the ETA if the remaining driving distance is shorter than 5000 meters.
- Never show the remaining stop count.
- Each other field retains the default visibility of being shown when the vehicle is within 5 stops of the task.

See `TaskTrackingViewConfig` for [gRPC](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.md.txt#tasktrackingviewconfig) or [REST](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks.md.txt#tasktrackingviewconfig).

### gRPC

```java
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
  }
  return;
}
```

### REST

To set the task tracking view config window using HTTP, call `PATCH` and
use `updateMask` to update the `taskTrackingViewConfig` parameter:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`

For example:

```bash
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM
```

## What's next

- [Delete Task](https://developers.google.com/maps/documentation/mobility/fleet-engine/journeys/tasks/delete-task.md.txt)