Update trips and manage their state

This document describes how to update a trip and manage its state, which involves using a field mask to set relevant fields for a trip. It assumes you have set up Fleet Engine as described in this site and are working with a vehicle assigned to a trip.

Trip update basics

Your system uses Fleet Engine to update a trip in the following situations:

• When assigning a vehicle to a trip after it's created.
• When the status of the trip changes; for example, when the vehicle passes through waypoints.
• When you update trip fields, such as the number of passengers and the drop-off point.

To update a trip, send a request using either gRPC and REST.

• UpdateTrip() method: gRPC or REST
• UpdateTripRequest message: gRPC only

Use the appropriate credentials for the service account of your project as described in Fleet Engine: Service account roles.

Update trip fields

You can update any of the trip fields described in Trip fields in Create a single destination trip. For example, after you create a trip, it's a common practice to first find a vehicle and then update the trip vehicle_id field to associate it with the vehicle that will carry out the trip.

Important: You can only set the vehicle_id for a NEW trip. If you want to changes vehicle for a trip, you must set the trip status to NEW and then assign the different vehicle.

Use field masks

Field masks are a way for API callers to list the fields that a request should or update. Using a FieldMask avoids unnecessary works and improves performance. Fleet Engine uses field masks for updating fields across all resources.

Update the trip with the vehicle ID

You must configure a trip with a vehicle ID so that the Fleet Engine can track the vehicle along its route. The following code sample demonstrates how to update the trip with a vehicle ID.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()      // No need for the header.
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(FieldMask.newBuilder().addPaths("vehicle_id"))
        .build();

// Error handling.
// If the Fleet Engine has both a trip and vehicle with IDs, and if the
// credentials validate, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:                    // Neither the trip nor vehicle exist.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Manage trip state for trips

You specify the state of a trip using one of the TripStatus enumeration values. When a trip's state changes; for example from ENROUTE_TO_PICKUP to ARRIVED_AT_PICKUP, you update the trip state in Fleet Engine. The trip lifecycle always begins with a state value of NEW, and ends with a value of either COMPLETE or CANCELED.

Example trip update

The following demonstrates how to update the trip state for a back-to-back trip in Fleet Engine.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to be updated.
Trip trip = Trip.newBuilder()
    .setTripStatus(TripStatus.ARRIVED_AT_PICKUP)
    .build();

// Trip update request
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder().addPaths("trip_status"))
    .build();

// Error handling.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:            // The trip doesn't exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

You can see other examples of how to update trips in the Other trip types section.

Handle trip errors

When updating or finding existing trips, you might encounter a case of a DEADLINE_EXCEEDED error, in which case the state of Fleet Engine is unknown. To investigate this, first call CreateTrip again using the same trip ID you are trying to update or monitor. This should return either a 201 (CREATED) or 409 (CONFLICT). In the latter case, the previous request succeeded before DEADLINE_EXCEEDED.

See the list of network errors in the Consumer SDK, either for Android or iOS.

What's next

• Find trips