Create shipment tasks

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 shipment tasks on your server. For other task types, see Create other task types.

Shipment task fields

This section documents the task fields needed for both pickup and delivery 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 a shipment pickup task

To use Fleet Engine to follow the activity of a driver picking up a shipment, create a shipment pickup task. This involves setting the task type attribute to PICKUP. The following example illustrates a shipment pickup from the Grand Indonesia East Mall.

The following examples show how to create a shipment pickup 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.PICKUP)
    .setState(Task.State.OPEN)
    .setTrackingId("my-tracking-id")
    .setPlannedLocation(               // Grand Indonesia East Mall
      LocationInfo.newBuilder().setPoint(
        LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setTaskDuration(
      Duration.newBuilder().setSeconds(2 * 60))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .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 a 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 shipment pickup 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 Shipment task fields.

Example curl command:

 # Set $JWT, $PROJECT_ID, $TRACKING_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": "PICKUP",
   "state": "OPEN",
   "trackingId": "${TRACKING_ID}",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "90s",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 EOM

Create a shipment delivery task

To use Fleet Engine to follow the activity of a driver delivering a shipment, create a shipment delivery task. This involves setting the task type attribute to DELIVERY. The following example illustrates a shipment delivery to the Grand Indonesia East Mall.

The following examples show how to create a shipment pickup 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.DELIVERY)
    .setState(Task.State.OPEN)
    .setTrackingId("my-tracking-id")
    .setPlannedLocation(               // Grand Indonesia East Mall
      LocationInfo.newBuilder().setPoint(
        LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setTaskDuration(
      Duration.newBuilder().setSeconds(2 * 60))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .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 a shipment pickup 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, $TRACKING_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": "DELIVERY",
   "state": "OPEN",
   "trackingId": "${TRACKING_ID}",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "90s",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 EOM
 ```

What's next