This document assumes you have read the introductory guide to
\[Scheduled tasks\]\[1\] in the **Introduction to Fleet Engine** section as well
as \[What is a scheduled task?\]\[2\] 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](https://developers.google.com/maps/documentation/mobility/fleet-engine/journeys/tasks/create-other-tasks.md.txt).

## 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](https://developers.google.com/maps/documentation/mobility/fleet-engine/journeys/tasks/update-tasks.md.txt).

<br />

| Field | Value |
|---|---|
| `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](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials/tasks-intro.md.txt#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. |
| `planned_location` | **`PICKUP`, `DELIVERY`, or `SCHEDULED_STOP` tasks only** : The location where the task is to be completed. Not required for `UNAVAILABLE` tasks. |
| `task_duration` | The expected time to add to complete the task. For example, to look for parking, or walk to the handoff location. |

<br />

### Optional shipment task fields

<br />

| Field | Value |
|---|---|
| `target_time_window` | 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. |

<br />

## 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\]\[4\] or how to make an HTTP REST request to
\[`CreateTask`\]\[5\].

### gRPC

```java
  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`:

```bash
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\]\[6\] and \[JSON Web
tokens\]\[7\].

The request body must contain a `Task` entity with the appropriate fields
described in \[Shipment task fields\]\[8\].

Example `curl` command:

```bash
 # 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
```

> [!WARNING]
> **Experimental:** As an experimental feature, the `LocationInfo` ([gRPC](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.md.txt#locationinfo) or [REST](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.md.txt)) field now supports using `place` ([gRPC](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.md.txt#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place) or [REST](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.md.txt#FIELDS.place)), either alongside or instead of `LatLng`.

## 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\]\[4\] or how to make an HTTP REST request to
\[`CreateTask`\]\[5\].

### gRPC

```java
  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`:

```bash
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\]\[6\] and \[JSON Web
tokens\]\[7\].

The request body must contain a `Task` entity:

Example `curl` command:

````bash
 # 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
 ```
````

> [!WARNING]
> **Experimental:** As an experimental feature, the `LocationInfo` ([gRPC](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.md.txt#locationinfo) or [REST](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.md.txt)) field now supports using `place` ([gRPC](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.md.txt#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place) or [REST](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.md.txt#FIELDS.place)), either alongside or instead of `LatLng`.

[placeidtrips1](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.md.txt#locationinfo): /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo
[placeidtrips2](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.md.txt): /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html
[placeidtrips3](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.md.txt#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place): /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place
[placeidtrips4](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.md.txt#FIELDS.place): /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

## What's next

- \[Create other task types\]\[13\]
- \[Update tasks\]\[3\]

\[1\]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro
\[2\]: /maps/documentation/mobility/fleet-engine/journeys/tasks
\[3\]: update-tasks
\[4\]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks#java
\[5\]: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/create
\[6\]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts
\[7\]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt
\[8\]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks#shipment_task_fields
\[13\]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-other-tasks