Configure tasks

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 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 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 or how to make an HTTP REST request to UpdateTask. You can also set this field at the time of task creation.

  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;
  }

# 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

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

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

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:

  "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 or REST.

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;
}

# 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

• Update tasks
• Finalize a task