path: root/third_party/googleapis/google/maps/fleetengine/delivery/v1/tasks.proto

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package maps.fleetengine.delivery.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/maps/fleetengine/delivery/v1/common.proto";
import "google/maps/fleetengine/delivery/v1/delivery_vehicles.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

option go_package = "google.golang.org/genproto/googleapis/maps/fleetengine/delivery/v1;delivery";
option java_multiple_files = true;
option java_outer_classname = "Tasks";
option java_package = "google.maps.fleetengine.delivery.v1";
option objc_class_prefix = "CFED";

// A Task in the Delivery API represents a single action to track. In general,
// there is a distinction between shipment-related Tasks and break Tasks. A
// shipment can have multiple Tasks associated with it. For example, there could
// be one Task for the pickup, and one for the drop-off or transfer. Also,
// different Tasks for a given shipment can be handled by different vehicles.
// For example, one vehicle could handle the pickup, driving the shipment to the
// hub, while another vehicle drives the same shipment from the hub to the
// drop-off location.
//
// Note: gRPC and REST APIs use different field naming conventions. For example,
// the `Task.journey_sharing_info` field in the gRPC API and the
// `DeliveryVehicle.journeySharingInfo` field in the REST API refer to the same
// field.
message Task {
  option (google.api.resource) = {
    type: "fleetengine.googleapis.com/Task"
    pattern: "providers/{provider}/tasks/{task}"
  };

  // The type of Task.
  enum Type {
    // Default, the Task type is unknown.
    TYPE_UNSPECIFIED = 0;

    // A pickup Task is the action taken for picking up a shipment from a
    // customer. Depot or feeder vehicle pickups should use the `SCHEDULED_STOP`
    // type.
    PICKUP = 1;

    // A delivery Task is the action taken for delivering a shipment to an end
    // customer. Depot or feeder vehicle dropoffs should use the
    // `SCHEDULED_STOP` type.
    DELIVERY = 2;

    // A scheduled stop Task is used for planning purposes. For example, it
    // could represent picking up or dropping off shipments from feeder vehicles
    // or depots. It shouldn't be used for any shipments that are picked up or
    // dropped off from an end customer.
    SCHEDULED_STOP = 3;

    // A Task that means the Vehicle is not available for service. For example,
    // this can happen when the driver takes a break, or when the vehicle
    // is being refueled.
    UNAVAILABLE = 4;
  }

  // The state of a Task. This indicates the Tasks's progress.
  enum State {
    // Default. Used for an unspecified or unrecognized Task state.
    STATE_UNSPECIFIED = 0;

    // Either the Task has not yet been assigned to a delivery vehicle, or the
    // delivery vehicle has not yet passed the Task's assigned vehicle stop.
    OPEN = 1;

    // When the vehicle passes the vehicle stop for this Task.
    CLOSED = 2;
  }

  // The outcome of attempting to execute a Task. When `TaskState` is closed,
  // `TaskOutcome` indicates whether it was completed successfully.
  enum TaskOutcome {
    // The Task outcome before its value is set.
    TASK_OUTCOME_UNSPECIFIED = 0;

    // The Task completed successfully.
    SUCCEEDED = 1;

    // Either the Task couldn't be completed, or it was cancelled.
    FAILED = 2;
  }

  // The identity of the source that populated the `task_outcome_location`.
  enum TaskOutcomeLocationSource {
    // The Task outcome before it is set.
    TASK_OUTCOME_LOCATION_SOURCE_UNSPECIFIED = 0;

    // The provider-specified the `task_outcome_location`.
    PROVIDER = 2;

    // The provider didn't specify the `task_outcome_location`, so Fleet Engine
    // used the last known vehicle location.
    LAST_VEHICLE_LOCATION = 3;
  }

  // Journey sharing specific fields.
  message JourneySharingInfo {
    // Tracking information for the stops that the assigned vehicle will make
    // before it completes this Task. Note that this list can contain stops
    // from other tasks.
    //
    // The first segment,
    // `Task.journey_sharing_info.remaining_vehicle_journey_segments[0]` (gRPC)
    // or `Task.journeySharingInfo.remainingVehicleJourneySegments[0]` (REST),
    // contains route information from the driver's last known location to the
    // upcoming `VehicleStop`. Current route information usually comes from the
    // driver app, except for some cases noted in the documentation for
    // [DeliveryVehicle.current_route_segment][maps.fleetengine.delivery.v1.DeliveryVehicle.current_route_segment]. The other segments in
    // `Task.journey_sharing_info.remaining_vehicle_journey_segments` (gRPC) or
    // `Task.journeySharingInfo.remainingVehicleJourneySegments` (REST) are
    // populated by Fleet Engine. They provide route information between the
    // remaining `VehicleStops`.
    repeated VehicleJourneySegment remaining_vehicle_journey_segments = 1;

    // Indicates the vehicle's last reported location of the assigned vehicle.
    DeliveryVehicleLocation last_location = 2;

    // Indicates whether the vehicle's lastLocation can be snapped to
    // the `current_route_segment`. This value is False if either
    // `last_location` or `current_route_segment` don't exist. This value is
    // computed by Fleet Engine. Updates from clients are ignored.
    bool last_location_snappable = 3;
  }

  // Must be in the format `providers/{provider}/tasks/{task}`.
  string name = 1;

  // Required. Immutable. Defines the type of the Task. For example, a break or shipment.
  Type type = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Required. The current execution state of the Task.
  State state = 3 [(google.api.field_behavior) = REQUIRED];

  // The outcome of the Task.
  TaskOutcome task_outcome = 9;

  // The timestamp that indicates when the Task's outcome was set by the
  // provider.
  google.protobuf.Timestamp task_outcome_time = 10;

  // The location where the Task's outcome was set. This value is updated as
  // part of `UpdateTask`. If this value isn't explicitly updated by the
  // provider, then Fleet Engine populates it by default with the last known
  // vehicle location (the *raw* location).
  LocationInfo task_outcome_location = 11;

  // Indicates where the value of the `task_outcome_location` came from.
  TaskOutcomeLocationSource task_outcome_location_source = 12;

  // Immutable. This field facilitates the storing of an ID so you can avoid using a
  // complicated mapping. You cannot set `tracking_id` for Tasks of type
  // `UNAVAILABLE` and `SCHEDULED_STOP`. These IDs are subject to the
  // following restrictions:
  //
  // * Must be a valid Unicode string.
  // * Limited to a maximum length of 64 characters.
  // * Normalized according to [Unicode Normalization Form C]
  // (http://www.unicode.org/reports/tr15/).
  // * May not contain any of the following ASCII characters: '/', ':', '?',
  // ',', or '#'.
  string tracking_id = 4 [(google.api.field_behavior) = IMMUTABLE];

  // Output only. The ID of the vehicle that is executing this Task. Delivery Vehicle IDs are
  // subject to the following restrictions:
  //
  // * Must be a valid Unicode string.
  // * Limited to a maximum length of 64 characters.
  // * Normalized according to [Unicode Normalization Form C]
  // (http://www.unicode.org/reports/tr15/).
  // * May not contain any of the following ASCII characters: '/', ':', '?',
  // ',', or '#'.
  string delivery_vehicle_id = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Immutable. The location where the Task will be completed.
  // Optional for `UNAVAILABLE` Tasks, but required for all other Tasks.
  LocationInfo planned_location = 6 [(google.api.field_behavior) = IMMUTABLE];

  // Required. Immutable. The time needed to execute a Task at this location.
  google.protobuf.Duration task_duration = 7 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Output only. Journey sharing-specific fields. Not populated when state is `CLOSED`.
  JourneySharingInfo journey_sharing_info = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
}