Add the driver inspection requests - #60
Merged
Merged
Conversation
fleetbase/fleetops adds a driver-facing inspections API under v1 — the
published forms, filing a DVIR against one, and reading back what was filed.
An Inspections folder documents the six requests, and List Vehicle
Inspections sits with them rather than under Vehicles because it needs an
inspection to have been filed first.
Ordered at 7750, after Vehicles and Drivers, so {{vehicle_id}} and
{{driver_id}} exist when it runs.
Forms are published from the console, not this API, so List Inspection
Forms chains {{inspection_form_id}} from the first published form and the
three requests that address a form or file against one need the contract
run to seed a published form for the CI organisation. Without that seed
those three answer 404 and 422; the listings answer 200 regardless.
fleetops#319 changed what an inspection form is. A form is no longer a flat list of pass/fail items, it is groups of typed fields, and it answers `grouped_fields`. An inspection is that form filled in: the driver's answers arrive as `custom_field_values` and come back the same way, with every photo and signature stored as a file and resolved to something fetchable, beside the `item_results` the server derives from the pass/fail answers. Retrieve an Inspection Form documents the field types and what a `pass-fail` field's `meta` says happens on failure, and chains a pass-fail, a meter and a signature field from the form it read. Submit an Inspection builds its `custom_field_values` from those, and asserts the files came back resolved. A field is named by an id that only exists once the form has been read, and a form that has not been rebuilt from the first cut has no fields to name. So the submit sends both bodies, as the driver app does: `custom_field_values` when the ids resolved, and the flat `item_results` either way. The server prefers the field values and ignores the duplicated results, which means one request is 2xx against either cut — no request is skipped.
Three requests for the tokenised public inspection link, in the
Inspections folder after the driver requests:
- Retrieve a Public Inspection Form (GET) asserts the form and the
identity come back, that the driver no longer carries a phone number,
and chains the form's grouped_fields for the next two requests.
- Upload a Public Inspection Photo (POST, multipart) sends the sample
PNG Files/Upload File already uses, with the token as a form field,
and chains the returned file_ id.
- Submit a Public Inspection (POST) builds custom_field_values in its
pre-request script from the chained form, answering every field with
a passing value, and file-upload and signature fields with the
uploaded file as file:<id>.
All three take {{inspection_link_form_id}} and {{inspection_link_token}},
declared empty on the collection; a contract run seeds a link and passes
both in. The routes are public and ignore Authorization, so the
collection's bearer is left inherited: nothing in this repository shows
a verified request-level way to clear auth in the v3 format.
Links now carry a six-digit PIN, shared separately from the link. The three public requests send it as X-Inspection-Pin from inspection_link_pin, and describe the 403s a missing, wrong or locked PIN answers. The retrieve test also checks the identity names who the link is for.
fleetops#319 now emails or texts the link and its PIN together, so the retrieve description no longer says the PIN is shared separately.
The public inspection-link routes in fleetops#319 have no session, but their only consumer is the console's public inspection page, so they are internal by use and do not belong in a collection documenting the consumable API. Integrations file inspections through Submit an Inspection (POST /v1/inspections). This removes the three requests, their collection variables, and the folder description's paragraph about them.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the driver-facing inspections API that fleetbase/fleetops#319 (
feature/inspections-driver-api, draft) adds underv1, which the Navigator app and other integrations use.Folder Inspections (order 7750, after Vehicles and Drivers so
{{vehicle_id}}and{{driver_id}}exist when it runs). Every request authenticates with the API key./v1/inspection-forms?vehicle=/v1/inspection-forms/:id/v1/inspections(withIdempotency-Key: {{$guid}})/v1/inspections?driver=/v1/inspections/:id/v1/vehicles/:id/inspectionsOnly the consumable API is documented. fleetops#319 also adds public inspection-link routes under
/public/inspections/forms. They take no session, but their only consumer is the console's public inspection page, so by use they are internal and are deliberately left out of this collection. An integration files an inspection through Submit an Inspection.Related Issue
Companion to fleetbase/fleetops#319 (draft, supersedes fleetbase/fleetops#267). The CI seed the requests need, a published form with typed field groups, is fleetbase/fleetbase#652.
Type of Change
Implementation Notes
grouped_fields, and an inspection arrives ascustom_field_values, one per field, with photos and signatures stored as files and resolved on the way back. Retrieve an Inspection Form documents the field types and chains a pass-fail, a meter and a signature field; Submit an Inspection buildscustom_field_valuesfrom them and also sends the flatitem_results, as the driver app does, so one request answers 2xx against either cut.inspection_form_idandinspection_id, declared with empty defaults in the collection definition for documentation; the CLI only substitutes--env-varvalues. The published form they start from comes from fleetbase#652's seed.pm.execution.skipRequest()guards, no request writesdriver_identity,driver_passwordordriver_phone, and there is no DELETE in the folder.Validation
scripts/validate-collections.jspasses (5 collections, 3 environments).postman collection lintwith Postman CLI 1.46.0 reports 0 errors and 0 warnings. Every changed YAML file parses, and the embedded scripts passnode --check.Not run against a live stack: no local stack carries the fleetops branch with the seed.
Documentation Impact
fleetbase/fleetbase.ioAPI Reference Impact
fleetbase/postmanAPI reference notes: six new
v1endpoints under the Fleetbase API collection;fleetbase/fleetbase.ioregeneration needed once merged.Documentation Notes
A driver-app guide for inspections (
fleet-ops/maintenance/inspections/overview, which the maintenance hub already links to) would belong infleetbase/fleetbase.io.Risk
Merge order matters. fleetbase/fleetops#319's contract workflow runs the collection at
postman-ref: main, and the publishedfleetbase-api:latestimage does not carry the inspections API yet.Suggested: land fleetops#319 and fleetbase#652, then this; or verify together by pointing the fleetops workflow at
postman-ref: feat/driver-inspectionsfor one run. Nothing else in the collection changes.Screenshots / Recordings
n/a