Find tasks

This document describes the ways that you can find task information from a server or browser. Fleet Engine supports two ways to find tasks:

• Look up tasks: You can look up tasks by the following IDs:

  • Task ID: used by users like fleet operators who have access to the full view of the task data.
  • Tracking ID: used by your client software to provide limited information to an end user, such as when a package is expected at their house.

  Be sure to understand the difference between the task ID and the task tracking ID. They are not the same. See Basic task fields in the Scheduled task guide.

• List tasks: a broad access to tasks, intended for trusted users only.

Look up tasks

This section describes how to lookup tasks by task ID or tracking ID. It has the following requirements:

• Lookups by tracking ID must adhere to the visibility rules stated in Visibility rules for tracked objects.

• Use the narrowest token possible to limit security risks. For example, if you use a Delivery Consumer Token, any calls return only information relevant to that end user, such as the shipper or the receiver of a shipment. Fleet Engine redacts all other information in the responses. For more information about tokens, see JSON Web tokens.

Lookup task by task ID

You can look up a task by its task ID from a server environment using gRPC or REST. The following examples show how to use the Java gRPC library or a REST request to GetTask.

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

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Task request
 String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
 GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
     .setName(taskName)
     .build();

 try {
   Task task = deliveryService.getTask(getTaskRequest);
 } 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 -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

Lookup tasks by tracking ID

The following examples show how to lookup tasks by their shipment tracking ID using either gRPC or an HTTP REST call to GetTaskTrackingInfo.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setTrackingId(TRACKING_ID)
    .build();

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"

List tasks

Listing tasks requests broad access to tasks. Listing tasks is intended only for trusted users. Use Delivery Fleet Reader or Delivery Admin authentication tokens when making list tasks requests. See Service account roles for more information.

Paginate lists

Task lists are paginated. A page size can be specified in list tasks requests. If a page size is specified, the number of returned tasks is no greater than the specified page size. If no page size is present, a reasonable default is used. If the requested page size exceeds an internal maximum value, then the internal maximum is used.

A task list can include a token for reading the next page of results. To retrieve that next page, re-issue the same request along with the page token. When the returned page token is empty, no more tasks are available for retrieval.

Fields when listing tasks

Fleet Engine redacts the following fields when listing tasks:

• VehicleStop.planned_location
• VehicleStop.state
• VehicleStop.TaskInfo.taskId

Use the following field formats based on Google API Improvement Proposals:

Filter listed tasks

You can filter listed tasks by most task properties. For filter query syntax, see AIP-160. If no filter query is specified, all tasks are listed.

The following table shows valid task properties that you can use for filtering:

See AIP-160 for a full list of filter query operators.

List task examples

The following example shows how to list tasks for a deliveryVehicleId and a task attribute, both with the Java gRPC library and with HTTP REST call to ListTasks.

A successful response can still be empty. An empty response indicates no tasks associated the supplied deliveryVehicleId.

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String TRACKING_ID = "TID-7449w087464x5";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Tasks request
 String parent = "providers/" + PROJECT_ID;
 ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder()  // No need for the header
     .setParent(parent)
     .setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
     .build();

 try {
   ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
 } catch (StatusRuntimeException e) {
   Status s = e.getStatus();
   switch (s.getCode()) {
      case NOT_FOUND:
        break;

      case PERMISSION_DENIED:
        break;
   }
   return;
 }

    // JSON representation
    {
      "tasks": [
        {
          object (Task)
        }
      ],
      "nextPageToken": string,
      "totalSize": integer
    }

 # Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
 curl -H "Authorization: Bearer ${JWT}" \
   "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

What's next

• Manage shipments