Skip to content

Journey Events

Jump to bottom
Adam Sharp edited this page Oct 20, 2021 · 32 revisions

Journey Events

This document describes journey events in the Book A Secure Move Api.

The typical order of journey events during the pick-up process from a designated location is expected to be:

  1. JourneyArriveAtOuterGate (of pick-up location)
  2. JourneyAdmitThroughOuterGate (of pick-up location)
  3. JourneyAdmitToReception (of pick-up location)
  4. JourneyHandoverToSupplier
  5. JourneyPersonBoardsVehicle
  6. JourneyStart
  7. JourneyReadyToExit (pick-up location)
  8. JourneyExitThroughOuterGate (of pick-up location)

The typical order of journey events during the drop-off process at a designated location is expected to be:

  1. JourneyArriveAtOuterGate (of drop-off location)
  2. JourneyAdmitThroughOuterGate (of drop-off location)
  3. JourneyAdmitToReception (of drop-off location)
  4. JourneyPersonLeaveVehicle
  5. JourneyHandoverToDestination
  6. JourneyComplete

JourneyStart

Description

Starting a journey will change the proposed journey state to in_progress. Indicates that the vehicle has begun 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.

Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_reg": "AB12 CDE"
      },
      "event_type": "JourneyStart"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "1ac0e4b3-786b-4dee-a0ce-9ae4035963ac"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

Updates the journey state to in_progress and updates the vehicle registration on the Journey if vehicle_reg is supplied

JourneyCancel

Description

Cancelling a journey will change the journey state from in_progress to cancelled.

Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03 10:50:31 +0000",
      "recorded_at": "2020-12-03 10:50:31 +0000",
      "notes": "Additional information about this event",
      "details": {
      },
      "event_type": "JourneyCancel"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "ed0ec488-2875-45bb-9594-4b4bb7fa8cb3"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

Updates the journey status to cancelled

JourneyComplete

Description

Completing a journey will change the journey state from in_progress to completed. NB: suppliers must complete Journeys when the person has been handed over to staff at a designated location.

Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move. for billing.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:32+00:00",
      "recorded_at": "2020-12-03T10:50:32+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_reg": "AB12 CDE"
      },
      "event_type": "JourneyComplete"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "efd413e2-00c5-4f0c-bc4b-ab38c728ba51"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

Updates the journey status to completed and updates the vehicle registration of the Journey if vehicle_reg is supplied

JourneyLockout DEPRECATED

Description

DEPRECATED Recording a lockout event does not change the journey's state. After recording the lockout, the journey should be completed or cancelled and additional journey records created to a new location.

Attributes

  • from_location - The location the person was locked out from.

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
      },
      "event_type": "JourneyLockout"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "868a6c7e-f3b7-4ed8-aae3-ea737f599956"
        }
      },
      "from_location": {
        "data": {
          "id": "e2374a91-af87-44a2-8c68-171ca0aafffa",
          "type": "locations"
        }
      }
    }
  }
}

Validations

  • from_location must be present in relationships.

Triggers

None

JourneyLodging DEPRECATED

Description

DEPRECATED Recording a lodging event does not change the journey's state and is purely an auditing event.

Attributes

  • to_location - The location the person was lodging in.

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
      },
      "event_type": "JourneyLodging"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "419b99fd-691f-4a00-9487-1021de358a0d"
        }
      },
      "to_location": {
        "data": {
          "id": "99c66b71-f89e-4e04-be4d-7b9d094db018",
          "type": "locations"
        }
      }
    }
  }
}

Validations

  • from_location must be present in relationships.

Triggers

None

JourneyPersonBoardsVehicle

Description

Indicates the moment when the person was expected to board the vehicle.

Attributes

  • vehicle_reg - the registration of the vehicle that was boarded. Required for reporting
  • vehicle_type - indicates the type of the vehicle being boarded.

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:34+00:00",
      "recorded_at": "2020-12-03T10:50:34+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_type": "pro_cab",
        "vehicle_reg": "CQE-2755"
      },
      "event_type": "JourneyPersonBoardsVehicle"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "0cdbbeb7-a813-4ae6-bab6-ebaa30ee070c"
        }
      }
    }
  }
}

Validations

  • vehicle_type - presence, one of c4, pro_cab, mpv, 2_cell, 3_cell, 6_cell or 12_cell
  • vehicle_reg - presence

Triggers

JourneyPersonLeaveVehicle

Description

Person leaves escort vehicle.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_reg": "AB12 CDE"
      },
      "event_type": "JourneyPersonLeaveVehicle"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "c46efa19-17c7-4bdc-a228-3ca00875bfe0"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

None

JourneyReadyToExit

Description

Escort vehicle loaded and ready to exit from the pick-up designated location. The location must be specified in the relationship data of the request.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:32+00:00",
      "recorded_at": "2020-12-03T10:50:32+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_reg": "AB12 CDE"
      },
      "event_type": "JourneyReadyToExit"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "3dc7a534-da02-4784-976e-4c29ed1ec11b"
        }
      },
      "location": {
        "data": {
          "id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
          "type": "locations"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

None

JourneyReject

Description

Rejecting a journey will change the proposed journey state to rejected.

Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:32+00:00",
      "recorded_at": "2020-12-03T10:50:32+00:00",
      "notes": "Additional information about this event",
      "details": {
      },
      "event_type": "JourneyReject"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "e79aa38e-d432-474e-9b54-cd5c0aa5ed3e"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

Changes the state of a journey from proposed to rejected

JourneyExitThroughOuterGate

Description

The vehicle exited through the outer gate of the pick-up designated location. The location must be specified in the relationship data of the request.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:32+00:00",
      "recorded_at": "2020-12-03T10:50:32+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_reg": "AB12 CDE"
      },
      "event_type": "JourneyExitThroughOuterGate"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "91297dea-9648-4efe-9f6a-e2162c02ea27"
        }
      },
      "location": {
        "data": {
          "id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
          "type": "locations"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

None

JourneyArriveAtOuterGate

Description

The vehicle for the current journey has arrived at the outer gate of the pick-up or drop-off designated location. The location must be specified in the relationship data of the request.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_reg": "AB12 CDE"
      },
      "event_type": "JourneyArriveAtOuterGate"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "9274313a-8e87-4ff0-82e6-248d72464a4f"
        }
      },
      "location": {
        "data": {
          "id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
          "type": "locations"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

None

JourneyAdmitThroughOuterGate

Description

The vehicle was admitted through the outer gate of the pick-up or drop-off designated location. The location must be specified in the relationship data of the request.

Attributes

  • vehicle_reg - the registration of the vehicle that was admitted through the outer gate. Required for reporting
  • supplier_personnel_number - the supplier's unique identifier of the personnel driving the vehicle

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_reg": "DYV-5576",
        "supplier_personnel_number": "cd0c8221-6d7a-453d-b7f6-8816bf40a17d"
      },
      "event_type": "JourneyAdmitThroughOuterGate"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "05307eb0-141d-4ffb-80e5-6010eafaab28"
        }
      },
      "location": {
        "data": {
          "id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
          "type": "locations"
        }
      }
    }
  }
}

Validations

  • vehicle_reg must be present in attributes.

Triggers

None

JourneyAdmitToReception

Description

The supplier has been admitted to the reception of the pick-up or drop-off designated location in order to perform a handover. The location must be specified in the relationship data of the request.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_reg": "AB12 CDE"
      },
      "event_type": "JourneyAdmitToReception"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "05307eb0-141d-4ffb-80e5-6010eafaab28"
        }
      },
      "location": {
        "data": {
          "id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
          "type": "locations"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

None

JourneyHandoverToDestination

Description

Person admitted to the Reception/Custody area of a designated location and handed over

Attributes

  • supplier_personnel_number - the supplier's unique identifier of the personnel handing over the person

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:34+00:00",
      "recorded_at": "2020-12-03T10:50:34+00:00",
      "notes": "Additional information about this event",
      "details": {
        "supplier_personnel_number": "cb90b124-b1b6-4ebb-b5a2-e50bc09db5e6"
      },
      "event_type": "JourneyHandoverToDestination"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "8daaef1c-a3f2-481e-be95-cd3aa3d96cb9"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

None

JourneyHandoverToSupplier

Description

Person handed over from a pick-up designated location to the custody of the supplier

Attributes

  • supplier_personnel_number - the supplier's unique identifier of the personnel handing over the person

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:34+00:00",
      "recorded_at": "2020-12-03T10:50:34+00:00",
      "notes": "Additional information about this event",
      "details": {
        "supplier_personnel_number": "cb90b124-b1b6-4ebb-b5a2-e50bc09db5e6"
      },
      "event_type": "JourneyHandoverToSupplier"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "8daaef1c-a3f2-481e-be95-cd3aa3d96cb9"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

None

JourneyUncancel

Description

Uncancelling a journey will revert the cancelled journey state to in_progress.

Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
      },
      "event_type": "JourneyUncancel"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "0f8bdc1c-0494-4a24-83ee-223dbf153a2c"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

Changes a journey's state from cancelled to in_progress

JourneyUncomplete

Description

Uncompleting a journey will revert the completed journey state back to in_progress.

Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.

Attributes

Common attributes, only

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
      },
      "event_type": "JourneyUncomplete"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "742146df-2293-49da-9420-517011c3f748"
        }
      }
    }
  }
}

Validations

Common validations, only

Triggers

Changes a journey's state from completed to in_progress

JourneyChangeVehicle

Description

Reflects a change in vehicle for pricing purposes. Usually after a PersonMoveVehicleBrokeDown or PersonMoveVehicleSystemsFailed event a change of vehicle happens. Use this event to capture when this event occurs and needs to be stored.

Attributes

  • vehicle_reg - The registration of the vehicle
  • previous_vehicle_reg - The registration of the vehicle that needed replacing

Request Example

POST /api/events

{
  "data": {
    "type": "events",
    "attributes": {
      "occurred_at": "2020-12-03T10:50:33+00:00",
      "recorded_at": "2020-12-03T10:50:33+00:00",
      "notes": "Additional information about this event",
      "details": {
        "vehicle_reg": "YYR-3044",
        "previous_vehicle_reg": "CID-1535"
      },
      "event_type": "JourneyChangeVehicle"
    },
    "relationships": {
      "eventable": {
        "data": {
          "type": "journeys",
          "id": "d7bb8e16-6f35-4997-abe1-46eb53fa8dc0"
        }
      }
    }
  }
}

Validations

  • vehicle_reg - presence
  • previous_vehicle_reg - presence

Triggers

Updates the Journey vehicle_registration attribute which gets reflected in the JPC price calculations.

Clone this wiki locally