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](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/trips/rpc/maps.fleetengine.v1.md.txt#maps.fleetengine.v1.TripService) or [REST](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/trips/rest/v1/providers.trips/update.md.txt) - `UpdateTripRequest` message: [gRPC](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/trips/rpc/maps.fleetengine.v1.md.txt#updatetriprequest) only Use the appropriate credentials for the service account of your project as described in [Fleet Engine: Service account roles](https://developers.google.com/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts.md.txt). ## Update trip fields You can update any of the trip fields described in [Trip fields](https://developers.google.com/maps/documentation/mobility/fleet-engine/journeys/trips/create-trip.md.txt#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] > **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](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask) 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. ```java 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`](https://developers.google.com/maps/documentation/mobility/fleet-engine/reference/trips/rpc/maps.fleetengine.v1.md.txt#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. ```java 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](https://developers.google.com/maps/documentation/mobility/journey-sharing/on-demand/android/share-journey.md.txt#handle_consumer_sdk_errors) or [iOS](https://developers.google.com/maps/documentation/mobility/journey-sharing/on-demand/ios/share-journey.md.txt#handle_consumer_sdk_errors). ## What's next - [Find trips](https://developers.google.com/maps/documentation/mobility/fleet-engine/journeys/trips/find-trip.md.txt)