Create other task types

This document assumes you have read the introductory guide to Scheduled tasks in the Introduction to Fleet Engine section as well as What is a scheduled task? in this section.

Fleet Engine for scheduled tasks provides different broad categories of tasks:

  • Shipment tasks: Use for driving tasks, including pickup and delivery of shipments.
  • Unavailability tasks: Use for times when drivers are unavailable, such as with required breaks.
  • Scheduled stop tasks: Use for non-driving tasks at drop boxes or customer locations, such as time to enter a building or locate a delivery point.

This document covers how to create non-shipment tasks on your server. For shipment task types, see Create shipment tasks.

Task fields for non-driving tasks

This section documents the task fields needed for both both unavailability and scheduled stop tasks.

Required task fields

For every task you create in Fleet Engine, you must provide it with the required fields, and may also provide any of the optional fields. Fleet Engine ignores all other fields, and throws an exception if a task creation request provides an assigned deliveryVehicleId. To assign tasks to a vehicle, use UpdateDeliveryVehicleRequest. For more information, see Update tasks.

FieldValue
type

Set to the type that matches the task type, which is one of:

  • PICKUP
  • DELIVERY
  • SCHEDULED_STOP
  • UNAVAILABLE
state State.OPEN
task_id Unique task ID. This must not be the tracking number for the shipment. If you don't have task IDs in your system, you may generate a universally unique identifier (UUID). For specifics, see Task IDs.
tracking_id PICKUP or DELIVERY tasks only: The number or identifier you are using to track a shipment. Do not provide this field for non-shipment tasks.
plannedLocation PICKUP, DELIVERY, or SCHEDULED_STOP tasks only: The location where the task is to be completed. Not required for UNAVAILABLE tasks.
taskDuration The expected time to add to complete the task. For example, to look for parking, or walk to the handoff location.

Optional shipment task fields

FieldValue
targetTimeWindow The time window during which the task should be completed. This field does not affect routing behavior.
task_tracking_view_config PICKUP or DELIVERY tasks only: The configuration for task tracking that specifies which data elements are visible to the end users under what circumstances.
attributes A list of custom task attributes. Each attribute must have a unique key.

Create an unavailability task

You can create a task indicating unavailability; for example, for driver breaks. To create an unavailability task, use the following guidelines:

  • Set the task type to UNAVAILABLE.
  • Don't include a tracking ID.
  • Although you don't have to provide a location for an unavailability task, doing so provides enhanced ETA calculations throughout the day.

Special visibility rules apply to the vehicle location when it is on an UNAVAILABLE task for journey sharing.

  • Consumer apps integrated with the Shipment Tracking library: When the vehicle is on an unavailability task, users of the consumer app can't see the vehicle location, although they can still see status information for their shipment.
  • Fleet tracking apps integrated with the Fleet Tracking library: When the vehicle is on an unavailability task, fleet managers who use the fleet tracking app will be able to see vehicle location for unavailability tasks.

The following examples show how to create a scheduled unavailability task using the Java gRPC library or how to make an HTTP REST request to CreateTask.

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String parent = "providers/" + PROJECT_ID;
  Task task = Task.newBuilder()
    .setType(Task.Type.UNAVAILABLE)
    .setState(Task.State.OPEN)
    .setTaskDuration(
      Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
    .build();

  // Task request
  CreateTaskRequest createTaskRequest =
    CreateTaskRequest.newBuilder()  // No need for the header
        .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
        .setTaskId("task-8241890")  // Task ID assigned by the Provider
        .setTask(task)              // Initial state
        .build();

  // Error handling
  // If Fleet Engine does not have task with that ID and the credentials of the
  // requestor pass, the service creates the task successfully.

  try {
    Task createdTask = deliveryService.createTask(createTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case ALREADY_EXISTS:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }
  ```

REST

To create an unavailability task from a server environment, make an HTTP REST call to CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<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 and JSON Web tokens.

The request body must contain a Task entity with the appropriate fields described in Task fields for non-driving tasks.

Example curl command:

 # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
 curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "type": "UNAVAILABLE",
   "state": "OPEN",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "300s"
 }
 EOM

Create a scheduled stop task

You can create a task for a scheduled stop; for example, for non-driving tasks at customer locations, for refueling stops, or for when a driver receives shipments from a feeder vehicle. When you create a scheduled stop task, use the following guidelines:

  • Set the task type to
  • Don't include a tracking ID.
  • You may optionally provide a location.

The following examples show how to create a scheduled unavailability task using the Java gRPC library or how to make an HTTP REST request to CreateTask.

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String parent = "providers/" + PROJECT_ID;
  Task task = Task.newBuilder()
    .setType(Task.Type.SCHEDULED_STOP)
    .setState(Task.State.OPEN)
    .setPlannedLocation(               // Grand Indonesia East Mall
      LocationInfo.newBuilder().setPoint(
        LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setTaskDuration(
      Duration.newBuilder().setSeconds(2 * 60))
    .build();

  // Task request
  CreateTaskRequest createTaskRequest =
    CreateTaskRequest.newBuilder()  // No need for the header
        .setParent(parent)
        .setTaskId("task-8241890")  // Task ID assigned by the Provider
        .setTrip(task)              // Initial state
        .build();

  // Error handling
  // If Fleet Engine does not have task with that ID and the credentials of the
  // requestor pass, the service creates the task successfully.

  try {
    Task createdTask = deliveryService.createTask(createTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case ALREADY_EXISTS:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }
  ```

REST

To create a scheduled stop task from a server environment, make an HTTP REST call to CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<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 and JSON Web tokens.

The request body must contain a Task entity:

Example curl command:

# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
 curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "type": "SCHEDULED_STOP",
   "state": "OPEN",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "600s"
 }
 EOM

What's next