Service checklists in the API: completing a service may need its answers

What's new

• A service can carry a service checklist. checklistTemplateId on a service names an active checklist of type Service in your organisation. Any other checklist is refused with a 422 (checklist_template.not_service or checklist_template.service_inactive).
• Default service checklists. Equipment and groups take defaultServiceChecklistTemplateId. The equipment's own default comes first, then its group's.
• GET /api/v1/services/checklist-default?equipmentId= tells you a machine's default service checklist, so you can send it as checklistTemplateId.
• The service detail returns checklistTemplate (the checklist and its items) and checklistResponses (the recorded answers).
• POST /api/v1/services/:id/complete takes checklistResponses: one answer per item, each with checklistItemId, response (PASS, FAIL or NA), and an optional value, notes and photoUrls.

What you need to change

A default is never applied for you. A service you create without a checklistTemplateId has no checklist, as before, even when the machine or its group has a default. To use the default, read it from GET /api/v1/services/checklist-default and send it as checklistTemplateId, as the console does.

Completing a service with a checklist needs its answers. On such a service:

• POST /api/v1/services/:id/complete without an answer to every required item returns 422 service.checklist_incomplete. error.details.missingItemIds lists the items still to answer.
• POST /api/v1/services/:id/transition with toStatus: COMPLETED returns the same 422, because it carries no answers. Complete these services through /complete instead.
• An answer for an item that isn't on the service's checklist (service.checklist_item_not_in_checklist), or the same item twice (service.checklist_duplicate_answer), is also a 422.

If your integration completes services, read checklistTemplate on the service first. When it isn't null, send checklistResponses with /complete.

A back-dated service carries no checklist. A service you create directly as COMPLETED can't name one: that is refused with a 422 (service.completed_log_checklist), because no answers can be added to it later. Create the service as UPCOMING with the checklist, then complete it with the answers.

Also changed

• A defect-repair service must be for a defect on the same machine. POST /api/v1/services with trigger: DEFECT_REPAIR and a defectId of another machine is refused with a 422. Completing the service resolves that defect, so the two must match.
• A repair that fails a critical checklist item leaves its defect open. When a DEFECT_REPAIR service is completed and its checklist answers FAIL on a critical item, the service still completes with every answer, but its defect is not resolved: it keeps its status, gets a comment naming the failed items, and takes the machine out of service until it's closed if nothing had already (a technician's lockout stays theirs), and your organisation's managers are notified. A failed critical item the defect isn't about gets a defect of its own, as on any other service (below).
• A critical checklist item that fails on any other service raises a defect. When a service that isn't a defect repair is completed and its checklist answers FAIL on a critical item, the service still completes with every answer, and the item gets a defect: the machine's open defect for that item, or a new CRITICAL one whose description names the service. That defect takes the machine out of service until it's closed, so every pre-start on it fails until then, and your organisation's managers are notified. A new defect sends the defect.reported webhook.
• A hired machine's service history is open to the organisation operating it. The hiring organisation now sees each service's people, completion notes, status changes and checklist answers. The costs, currency, invoice number and the assigned and performing companies stay with the owner, and are null for the hirer.

Unchanged

• Services with no checklist complete exactly as before.
• A service you create without a checklistTemplateId has no checklist, as before.