Event Documentation

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
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