PI-1575: Document 'Custody Key Dates and Delius' service (#2416)

projects/custody-key-dates-and-delius/README.md

@@ -1,3 +1,42 @@
-# custody-key-dates-and-delius
+# Custody Key Dates and Delius
 
-// TODO Describe the service
+## Business Need
+
+Inbound service that keeps Delius updated with key date changes recorded in custody services, primarily NOMIS.
+
+## Context Map
+
+![Context Map](./tech-docs/source/img/custody-key-dates-and-delius-context-map.svg)
+
+## Interfaces
+
+The service responds to HMPPS Offender Event messages via an
+[SQS Queue](https://github.com/ministryofjustice/cloud-platform-environments/blob/main/namespaces/live.cloud-platform.service.justice.gov.uk/hmpps-probation-integration-services-prod/resources/custody-key-dates-and-delius-queue.tf).
+
+Example [messages](./src/dev/resources/messages/) are in the development source tree
+
+## Event Triggers
+
+| Business Event                         | Message Class  | Message Event Type / Filter    |
+|----------------------------------------|----------------|--------------------------------|
+| Release date changed in NOMIS/DPS      | Offender Event | CONFIRMED_RELEASE_DATE-CHANGED |
+| Sentence dates changed in NOMIS/DPS    | Offender Event | SENTENCE_DATES-CHANGED         |
+| General key date change in NOMIS/DPS   | Offender Event | KEY_DATE_ADJUSTMENT_UPSERTED   |
+| General key date deletion in NOMIS/DPS | Offender Event | KEY_DATE_ADJUSTMENT_DELETED    |
+
+## Workflows
+
+### Update Key Dates
+
+![Key Dates Workflow](./tech-docs/source/img/custody-key-dates-and-delius-workflow-key-dates.svg)
+
+## Custody Key Dates Recorded in Delius
+
+Prison API provides a set of dates recorded in NOMIS that are recorded in the Throughcare section of Delius when the key dates updates are triggered. The dates are displayed in the 'Throughcare Dates' and 'Additional Throughcare Dates' section of the 'Throughcare Details' screen, which is accessed via the Delius Event. All dates that do not match the existing Delius values will be updated on receiving an event trigger. The custody dates obtained via Prison API are:
+
+- Sentence Expiry Date
+- Licence Expiry Date
+- Conditional Release Date / Override Date
+- Expected Release Date
+- Home Detention Curfew Eligibility Date
+- Post Sentence Supervision End Date

projects/custody-key-dates-and-delius/tech-docs/diag/custody-key-dates-and-delius-context-map.d2

@@ -0,0 +1,44 @@
+# Custody Key Dates and Delius Context Map
+
+style {
+  fill: "#ffffff"
+}
+
+context-nomis: NOMIS/DPS Context {
+  entities: Entities {
+    grid-columns: 3
+    pip: Person in Prison
+    booking: Booking
+    sentence: Sentence
+  }
+
+  interface: Prison API {
+    type: Open Host Service
+  }
+}
+
+context-delius: Delius Context {
+  link: https://github.com/ministryofjustice/delius
+  style.stroke-width: 8
+
+  entities: Entities {
+    grid-columns: 3
+    pop: Person on Probation
+    event: Event
+    disposal: Disposal
+    custody: Custody
+    key_dates: Key Dates
+    contact: Contact
+  }
+
+  interface: Custody Key Dates and Delius {
+    link: https://ministryofjustice.github.io/hmpps-probation-integration-services/tech-docs/projects/custody-key-dates-and-delius/
+    type: Anti-Corruption Layer
+  }
+}
+
+context-nomis.interface--context-delius.interface: Upstream\n\n\nDownstream
+
+*.style.border-radius: 10
+*.*.style.border-radius: 10
+*.*.style.stroke-width: 2

projects/custody-key-dates-and-delius/tech-docs/diag/custody-key-dates-and-delius-workflow-key-dates.d2

@@ -0,0 +1,35 @@
+# Custody Key Dates Workflow: Update Delius Key Dates
+
+direction: right
+
+style {
+  fill: "#ffffff"
+}
+
+# What triggers the workflow?
+nomis: NOMIS/DPS {
+     style.font-size: 15
+     nomis_key_dates: Any custody\nkey date updated {
+         shape: oval
+     }
+}
+
+# What happens in Delius?
+delius: Delius {
+    style {
+        font-size: 20
+    }
+
+    d_key_date_comparison: Compare key dates
+    d_key_date_update: Update changed\ndate values
+    d_contact: Create contact\nto record activity
+
+    d_key_date_comparison -> d_key_date_update -> d_contact
+}
+
+nomis -> delius
+
+*.style.border-radius: 10
+*.*.style.border-radius: 10
+*.*.style.stroke-width: 2
+*.*.style.font-size: 12

projects/custody-key-dates-and-delius/tech-docs/source/async-api-reference.html.md.erb

@@ -0,0 +1,9 @@
+---
+title: AsyncAPI Reference
+source_url: 'https://github.com/ministryofjustice/hmpps-probation-integration-services/blob/main/projects/custody-key-dates-and-delius/tech-docs/source/async-api-reference.html.md.erb'
+weight: 30
+---
+
+# ASyncAPI Reference
+
+<iframe width="100%" onload="this.height=screen.height" frameborder=0 src="https://studio.asyncapi.com/?url=https://raw.githubusercontent.com/ministryofjustice/hmpps-probation-integration-services/main/projects/custody-key-dates-and-delius/tech-docs/spec/async-api.yaml&readOnly" title="ASync-API Spec"></iframe>

projects/custody-key-dates-and-delius/tech-docs/spec/async-api.yaml

@@ -0,0 +1,128 @@
+asyncapi: 2.6.0
+info:
+  title: Custody Key Dates and Delius
+  description: Reflect changes to custody key dates in Delius
+  version: 0.1.0
+
+servers:
+  development:
+    url: https://sqs.eu-west-2.amazonaws.com/754256621582/probation-integration-dev-custody-key-dates-and-delius-queue
+    protocol: sqs
+  preproduction:
+    url: https://sqs.eu-west-2.amazonaws.com/754256621582/probation-integration-preprod-custody-key-dates-and-delius-queue
+    protocol: sqs
+  production:
+    url: https://sqs.eu-west-2.amazonaws.com/754256621582/probation-integration-prod-custody-key-dates-and-delius-queue
+    protocol: sqs
+
+channels:
+  hmpps-offender-events/custody-key-dates-and-delius/sentence-dates-changed:
+    subscribe:
+      operationId: SENTENCE_DATES-CHANGED
+      message:
+        name: Sentence Dates Changed
+        title: Sentence Dates Changed
+        summary: Sentence Dates have been updated in NOMIS
+        contentType: application/json
+        payload:
+          type: object
+          properties:
+            eventType:
+              type: string
+              example: SENTENCE_DATES-CHANGED
+            eventDateTime:
+              type: string
+              example: "2023-10-18T06:38:58Z"
+            bookingId:
+              type: integer
+              example: 1200835
+            sentenceCalculationId:
+              type: integer
+              example: 5628783
+            nomisEventType:
+              type: string
+              example: "S2_RESULT"
+  hmpps-offender-events/custody-key-dates-and-delius/confirmed-release-date-changed:
+    subscribe:
+      operationId: CONFIRMED_RELEASE_DATE-CHANGED
+      message:
+        name: Confirmed Release Date Changed
+        title: Confirmed Release Date Changed
+        summary: Confirmed release date has been updated in NOMIS
+        contentType: application/json
+        payload:
+          type: object
+          properties:
+            eventType:
+              type: string
+              example: CONFIRMED_RELEASE_DATE-CHANGED
+            eventDateTime:
+              type: string
+              example: "2023-10-18T06:38:58Z"
+            bookingId:
+              type: integer
+              example: 1200835
+  hmpps-offender-events/custody-key-dates-and-delius/key-dates-adjusted:
+    subscribe:
+      operationId: KEY_DATE_ADJUSTMENT_UPSERTED
+      message:
+        name: Key Date Adjustment Changed
+        title: Key Date Adjustment Changed
+        summary: Custody key Dates have been updated in NOMIS
+        contentType: application/json
+        payload:
+          type: object
+          properties:
+            eventType:
+              type: string
+              example: KEY_DATE_ADJUSTMENT_UPSERTED
+            eventDateTime:
+              type: string
+              example: "2023-10-18T06:38:58Z"
+            bookingId:
+              type: integer
+              example: 585671
+            offenderIdDisplay:
+              type: string
+              example: G9100VF
+            nomisEventType:
+              type: string
+              example: "OFF_KEY_DATES_ADJ-UPDATED"
+            auditModuleName:
+              type: string
+              example: "DPS_SYNCHRONISATION"
+            adjustmentId:
+              type: integer
+              example: 315427
+  hmpps-offender-events/custody-key-dates-and-delius/key-dates-adjustment-deleted:
+    subscribe:
+      operationId: KEY_DATE_ADJUSTMENT_DELETED
+      message:
+        name: Key Date Adjustment Deleted
+        title: Key Date Adjustment Deleted
+        summary: Custody key dates have been updated in NOMIS
+        contentType: application/json
+        payload:
+          type: object
+          properties:
+            eventType:
+              type: string
+              example: KEY_DATE_ADJUSTMENT_DELETED
+            eventDateTime:
+              type: string
+              example: "2023-10-18T06:38:58Z"
+            bookingId:
+              type: integer
+              example: 585671
+            offenderIdDisplay:
+              type: string
+              example: G9100VF
+            nomisEventType:
+              type: string
+              example: "OFF_KEY_DATES_ADJ-UPDATED"
+            auditModuleName:
+              type: string
+              example: "DPS_SYNCHRONISATION"
+            adjustmentId:
+              type: integer
+              example: 315427