Lockouts and Lodgings

Most moves occur over a single day, but occasionally there will be a move which takes multiple days. There are usually two reasons for this:

• A lockout occurs when unforeseen circumstances (such as delays in court or to the journey) mean a person will not arrive at their planned destination in time to be received that day. In this scenario they are held at a nearby establishment (usually a police custody suite) under a temporary lodging
• A lodging is when a person is temporarily held overnight on the way to their ultimate destination.
  • Temporary lodgings (previously overnight lodgings) are usually unplanned, for example if there is a temporary lack of space at their destination prison or because of a lockout.
  • Overnight lodgings are planned to split up a move before it starts, for example if the move is over a long distance which cannot be completed in one day.

For these kinds of moves, the existing walkthroughs should be followed, but with a few important differences. In any descriptions below, we can assume A refers to the original location, B refers to the final destination and C refers to where the person will be held overnight.

Journeys with dates

For these kinds of moves, the move should be booked from A to B and not redirected at any point to C. This is important is it allows the entire move to be shown to users in the right dashboard in the Book a secure move frontend. The journeys must be recorded with the move accurately as early as possibly known, this is to ensure the move appears in the dashboard for the C location as soon as it's known. Using a redirection would prevent the move from remaining in the dashboard for B for the next day. Crucially, the move should appear in the frontend for all three locations, A, B and C.

When journeys are created, they can be associated with a date, which falls back to the move date if not specified. This should be recorded accurately as early as possibly known (the date can be amended at any point) which helps to ensure the move appears in the right place for users of Book a secure move.

Examples of creating journeys with dates are included in the walkthroughs.

Move lodging events

When a move of this type occurs, the event should be recorded as early as possible so that the move state is updated in the Book a secure move frontend and users are aware of the lodging. See the documentation for the individual events for more information.

• MoveLockout
• MoveLodgingStart
• MoveLodgingEnd

The presence of a MoveLockout or MoveLodgingStart event on a move, will mean the move shows slightly differently on the Book a secure move frontend, specifically a label will be placed near the status of the move. The move remains in transit while the lodge occurs.

Overnight lodging events

For pre-planned overnight lodgings, events will be created to indicate the intended schedule.

• LodgingCreate
• LodgingUpdate
• LodgingCancel

These events will be automatically created when lodgings are created, updated and cancelled via the lodgings controller, typically as a result of user interaction in the frontend. The notifications sent to suppliers will be of the type create_lodging, update_lodging or cancel_lodging.

Event notifications

While a person is held in police custody, certain events can happen which the suppliers will want to be notified of. To support this functionality, the existing webhook mechanism will be used with a Create event notification.

These will only be sent for events created on a move or a PER by a non-supplier user, so suppliers won't receive notifications for events they have created.

Manual testing

Lockouts can only occur when a supplier sends us a lockout event, which can make testing locally difficult. Here are some small bits of code you can run in a Rails console to set up a lockout move. This isn't entirely realistic as it skips a few unnecessary steps, but it's enough for testing.

move = Move.find(...)

In this example we'll use consistent locations, but this isn't strictly necessary.

l1 = Location.find_by(title: 'Haywards Heath County Court')
l2 = Location.find_by(title: 'Tonbridge Custody Suite')
l3 = Location.find_by(title: 'MAIDSTONE (HMP)')

move.update!(from_location: l1, to_location: l3, move_type: :prison_remand)

Once the PER is complete, the supplier usually creates the journeys and starts the move.

j1 = move.journeys.create!(from_location: l1, to_location: l3, client_timestamp: Time.zone.now, supplier: move.supplier, date: move.date)
GenericEvent::JourneyCreate.create!(eventable: j1, occurred_at: Time.zone.now, recorded_at: Time.zone.now, supplier_id: move.supplier.id)

move.accept
move.start
move.save
GenericEvent::MoveStart.create!(eventable: move, occurred_at: Time.zone.now, recorded_at: Time.zone.now)

The handover for the first journey can then be recorded. You can use the code below to fix the location of the event if necessary.

h1 = GenericEvent::PerHandover.find_by(eventable: PersonEscortRecord.find_by(move: move))
h1.details["location_id"] = l1.id
h1.save

Then a lockout occurs.

GenericEvent::MoveLockout.create!(eventable: move, occurred_at: Time.zone.now, recorded_at: Time.zone.now, details: { from_location_id: l3.id })
move.update!(is_lockout: true)

At this point, the journeys will be updated to reflect the new situation.

j1.update!(state: :cancelled)
GenericEvent::JourneyCancel.create(eventable: j1, occurred_at: Time.zone.now, recorded_at: Time.zone.now)

j2 = move.journeys.create!(from_location: l1, to_location: l2, client_timestamp: Time.zone.now, supplier: move.supplier, date: move.date)
GenericEvent::JourneyCreate.create!(eventable: j2, occurred_at: Time.zone.now, recorded_at: Time.zone.now, supplier_id: move.supplier.id)

j3 = move.journeys.create!(from_location: l2, to_location: l3, client_timestamp: Time.zone.now, supplier: move.supplier, date: move.date + 1.day)
GenericEvent::JourneyCreate.create!(eventable: j3, occurred_at: Time.zone.now, recorded_at: Time.zone.now, supplier_id: move.supplier.id)

When the lodging starts, the police user can begin to add lockout events.

GenericEvent::MoveLodgingStart.create!(eventable: move, occurred_at: Time.zone.now, recorded_at: Time.zone.now, details: { location_id: l2.id, reason: 'lockout' })

When the lodging ends, the police users can no longer add lockout events and effectively the move is back with the supplier.

GenericEvent::MoveLodgingEnd.create!(eventable: move, occurred_at: Time.zone.now, recorded_at: Time.zone.now, details: { location_id: l2.id })

The handover for the seconds journey can then be recorded. You can use the code below to fix the location of the event if necessary.

h2 = GenericEvent::PerHandover.find_by(eventable: PersonEscortRecord.find_by(move: move))
h2.details["location_id"] = l2.id
h2.save

Finally, a move can be completed.

j2.update!(state: :completed)
j3.update!(state: :completed)

move.complete
move.save
GenericEvent::MoveComplete.create!(eventable: move, occurred_at: Time.zone.now, recorded_at: Time.zone.now)