Skip to content

Event Documentation

danbenton-mojdt edited this page Aug 19, 2024 · 47 revisions

Events (Version 2)

Summary

Events encapsulate something that happens at a particular time for a given subject (eventable) such as a move, journey or person.

To create them, they are POSTed to the Book a Secure Move API.

Events fall into one of 4 business categories:

  • MI (Management Intelligence)
  • CDI (Contract Delivery Indicator) - subset of MI (includes financial penalties and target levels)
  • Payment
  • Incident

Events must indicate their subject (Eventable), which is one of the following types:

  • Move
  • Journey
  • PersonEscortRecord
  • Person
  • Profile

Common event parameters

In the body of every request to create an event, we support the following attributes:

Explicit fields clients provide:

  • occurred_at - The closest feasible approximation of when the event was expected to have occurred
  • recorded_at - The time the event was first recorded into the system that the event was recorded on before it arrives in our servers
  • notes - Arbitrary and unstructured notes that give human readable additional information that is relevant to stakeholders that might review the current event being created
  • eventable - Always passed as a JSON:API relationship, this is the subject of the event (see above) and event-specific documentation links provided below

Implicit fields we generate:

  • created_at - When was the event resource inserted into our database
  • updated_at - When was the event resource last updated (events are immutable and this should be the same as created_at in theory)
  • supplier_id - We tag events that were created by a supplier with the supplier's id for auditing and security

Specific event parameters

In the body of all event requests you will need to specify the event_type attribute (see specific event documentation - links provided for all events below).

The event_type attribute is important because it affects the kinds of validations and triggers that the generation of the current event leads too. For example, for state-transition events which are used to change the status of a Move resource or state of a Journey resource the event_type field will lead to the relevant transition behaviour for that event.

In addition to the event type, each individually specced event defines a set of parameters that it alone supports. These parameters are all nested flatly under the details attribute.

Event ordering

We always order by and execute triggers according to the occurred_at field. This is to guarantee that (especially for a Journey resource) all events triggers run in the correct order.

For a Journey this means a transition won't take hold until all events are received and created with the correct applied order.

We call this ordered list of events for an eventable internally the eventable's event log.

Events are immutable: this means that once you've created an event, you can't change it. Please contact Book A Secure Move Dev team if you have a need to update an existing event

Journey Events

Type Short Description On V1? Result
JourneyAdmitThroughOuterGate Admitted through outer gate of a Designated location (for pick-up or drop-off) N
JourneyAdmitToReception Admitted to reception of Designated location (for pick-up or drop-off) N
JourneyArriveAtOuterGate Arrival outside the outer gate of a Designated location (for pick-up or drop-off) N
JourneyCancel Journey cancel Y Changes journey state from in_progress to cancelled
JourneyChangeVehicle Change of vehicle mid journey N Changes the journey vehicle in the middle of a journey. Typically during a breakdown
JourneyComplete Journey complete - NB: suppliers must complete Journeys when the person has been handed over to staff at a designated location Y Changes the journey state from in_progress to completed
JourneyExitThroughOuterGate Exit through the outer gate of the Designated location N
JourneyHandoverToDestination Handover to establishment / Authority N
JourneyHandoverToSupplier Handover to supplier N
JourneyLockout DEPRECATED Lockout (deprecated, use MoveLockout) Y DEPRECATED
JourneyLodging DEPRECATED Lodging (deprecated, use MoveLodgingStart and MoveLodgingEnd) Y DEPRECATED
JourneyPersonBoardsVehicle Person boards escort vehicle N
JourneyPersonLeaveVehicle Person leaves escort vehicle N
JourneyReadyToExit Escort vehicle loaded and ready to exit from the Designated location N
JourneyReject Journey reject Y Changes journey state from proposed to rejected
JourneyStart Journey start - Vehicle begins to move. NB: This event occurs after the vehicle has been loaded and is ready to exit but before the vehicle has exited through the outer gate. A Move / Journey should not be started in the case where a vehicle moves to reposition itself at the pick up location. Y Changes the proposed journey state to in_progress
JourneyUncancel Journey uncancel Y Changes journey state from cancelled to in_progress
JourneyUncomplete Journey uncomplete Y Changes the journey state from completed to in progress

Move Events

Type Short Description On V1? Result Details
MoveAccept Supplier accepts the move Y Changes move status from requested to booked
MoveApprove PMU approves a single prison-to-prison transfer move proposed by the OCA Y Changes move status to requested and updates with the provided move date
MoveCancel Cancel an unwanted move Y Changes move status to cancelled
MoveCollectionByEscort Collected by escort crew N
MoveComplete Supplier indicates the move has been completed - NB: Suppliers must complete Moves when the person has been handed over to staff at the final move destination (drop-off) designated location Y Changes move status to completed
MoveLockout Supplier unable to handover person at required desginated location resulting in a lockout (temporarily relocating) Y
MoveLodgingEnd DateTime a person was collected by supplier from lodging N
MoveLodgingStart DateTime person was handed over to temporary lodging location N
MoveNotifyPremisesOfArrivalIn30Mins Notify the destination (drop-off) that the van will arrive in 30 minutes time N
MoveNotifyPremisesOfEta Notify of the expected arrival time at the destination (drop-off) designated location N
MoveNotifyPremisesOfExpectedCollectionTime Notified Of Expected Collection Time at the pick-up designated location N
MoveNotifySupplierOfMoveRequest Supplier notified of move request N
MoveOperationHMCTS Formal arrangement for the utilisation of HMCTS Courthouse cells ("HMCTS Court Cells") to accommodate Prisoners overnight N
MoveOperationSafeguard The procedure the Authority has in place to manage the detention of Prisoners when prison operational capacity is reached. N
MoveOperationTornado The procedure the Authority has in place to decant detained Prisoners where prisons suddenly need to be vacated N
MoveOvernightLodge Used to indicate that a lodging is planned to take place during the move N
MoveRedirect Person is being redirected to another designated location Y Changes move destination (to_location). It does not alter the journeys associated with the move: additional API calls will be necessary to reject, complete or cancel existing journeys and create new journeys
MoveDateChanged Date of the move is being changed to the date specified in the details Y Changes move date only. It does not alter the journeys associated with the move: additional API calls will be necessary to reject, complete or cancel existing journeys and create new journeys as required or the front end will continue to display the journey date(s)
MoveReject PMU reject a single prison-to-prison transfer proposed by OCA Y Changes move status to cancelled, the move cancellation reason to rejected and update with the provided rejection reason
MoveStart Move start - Vehicle begins to move. NB: This event occurs after the vehicle has been loaded and is ready to exit but before the vehicle has exited through the outer gate. A Move / Journey should not be started in the case where a vehicle moves to reposition itself at the pick up location. Y Changes move status from booked to in_transit A move should only be started when the Escort Vehicle is loaded and ready for exit from the Designated Location
PersonMoveBookedIntoReceivingEstablishment DateTime when the Person was booked into the receiving establishment N

Person Escort Record Events

Type Short Description
PerConfirmation Indicates when and who confirmed a PER
PerCourtAllDocumentationProvidedToSupplier All necessary documentation provided to supplier
PerCourtAssignCellInCustody Assign cell in court custody
PerCourtCellShareRiskAssessment Cell share risk assessment at Court
PerCourtExcessiveDelayNotDueToSupplier Excessive delay caused by party other than Supplier
PerCourtHearing Court Hearing
PerCourtPreReleaseChecksCompleted Pre-release checks
PerCourtReadyInCustody Person ready and available within court custody area
PerCourtReleaseOnBail Released on bail
PerCourtRelease Released
PerCourtReturnToCustodyAreaFromDock Person returned to court custody area from court dock
PerCourtReturnToCustodyAreaFromVisitorArea Person returned to court custody area from visitor area
PerCourtTakeFromCustodyToDock Person taken from court custody to court dock
PerCourtTakeToSeeVisitors Person taken to see visitors at court
PerCourtTask Miscellaneous Court Task
PerGeneric Generic PER event
PerMedicalAid Medical aid
PerPrisonerWelfare Prisoner Welfare

Incident events

Type Short Description
PersonMoveAssault Assault
PersonMoveDeathInCustody Death in Custody
PersonMoveMajorIncidentOther Other Major Incidents
PersonMoveMinorIncidentOther Other Minor Incidents
PersonMovePersonEscapedKpi KPI Escape
PersonMovePersonEscaped Non KPI Escape
PersonMoveReleasedError Released in error
PersonMoveRoadTrafficAccident Road traffic accident
PersonMoveSeriousInjury Serious Injury
PersonMoveUsedForce Use of Force
PersonMoveVehicleBrokeDown Vehicle breakdown
PersonMoveVehicleSystemsFailed Failure of vehicle systems

Lodging events

Type Short Description
LodgingCreate Indicates that an overnight lodging is planned to take place during a move
LodgingUpdate Indicates that the details of an overnight lodging have been updated
LodgingCancel Indicates that an overnight lodging has been cancelled for a move
Clone this wiki locally