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.

gRPC

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

REST

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>

<id> is a unique identifier for the task.
<taskId> is the ID of the task to look up.
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 be empty.
If the lookup is successful, the response body contains a task entity.

Example curl command:

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

gRPC

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

REST

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>

<tracking_id> is the tracking ID associated with the task.
The request header must contain a field Authorization with the value Bearer <token>, where <token> bears the correct service account role. See Service account roles.
If the lookup is successful, the response body contains a taskTrackingInfo entity.

Example curl command:

# 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:

Field Type	Format	Example
Timestamp	RFC-3339	`task_outcome_time = 2022-03-01T11:30:00-08:00`
Duration	Number of seconds followed by an `s`	`task_duration = 120s`
Enum	String	`state = CLOSED AND type = PICKUP`
Location	`point.latitude` and `point.longitude`	`planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0`

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:

Task properties for filtering lists
`type` `attributes` `tracking_id` `delivery_vehicle_id` `state` `planned_location`	`task_duration` `task_duration_outcome` `task_outcome` `task_outcome_location` `task_outcome_time`

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.

gRPC

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

REST

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks

To apply a filter to the listed tasks, include a "filter" URL parameter with a URL-escaped filter query as its value.

The request header must contain a field Authorization with the value Bearer <token>, where <token> bears the correct service account role. See Service account roles.

A successful lookup provides a response body with the following structure:

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

Example curl command:

 # 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