PI-1725: Document Prison Identifier and Delius service (#2921)

projects/prison-identifier-and-delius/README.md

@@ -1,3 +1,54 @@
-# prison-identifier-and-delius
+# Prison Identifier and Delius
 
-// TODO Describe the service
+## Business Need
+
+HMPPS has a number of systems each holding information about a person's interaction with different aspects of the justice system. These systems have been set up and managed over a long period of time resulting in different identifiers being used for a person in each. In order to integrate these independent systems we must match the person records using the information held in each. To achieve this for NOMIS (NOMS Number) and Delius (CRN) we query the two systems and determine that likely matches based on the data. Once we have a likely match we can link the records by adding the NOMS Number to the person record in the Delius database. When this link is in place the two systems can be integrated in other ways to support case management as the person moves through different stages of HMPPS supervision.
+
+## Context Map
+
+![Context Map](./tech-docs/source/img/prison-identifier-and-delius-context-map.svg)
+
+## Workflow Triggers
+
+### Batch Processing
+
+The matching process can be triggered by a request to the integration service API endpoint
+
+| Business Event        | API Endpoint                 |
+|-----------------------|------------------------------|
+| List of CRNs to Match | /person/populate-noms-number |
+
+### Domain Event Processing (Not Yet Implemented)
+
+The matching process will be triggered by domain events raised by Delius, once these events are implemented
+
+| Business Event                     | Message Event Type / Filter     |
+|------------------------------------|---------------------------------|
+| New Sentence Added to Delius       | probation-case.sentence.created |
+| Sentence Changed in Delius         | probation-case.sentence.amended |
+| Sentence Moved to New Delius Event | probation-case.sentence.move    |
+
+## Workflows
+
+### Batch Processing
+
+![Batch Processing Workflow](./tech-docs/source/img/prison-identifier-and-delius-workflow-id-update.svg)
+
+## Interfaces
+
+### API Access Control
+
+API endpoints are secured by roles supplied by the HMPPS Auth client used in
+the requests
+
+| API Endpoint | Required Role                                   |
+|--------------|-------------------------------------------------|
+| All          | ROLE\_PROBATION\_API_\_PRISON_IDENTIFIER__UPDATE |
+
+## Concepts
+
+### Person Record Matching Process
+
+The logic used to match NOMIS person records to Delius person records uses the basic personal details, any additional identifiers and the recorded sentence dates.
+
+![Matching Process](./tech-docs/source/img/prison-identifier-and-delius-match-process.svg)

projects/prison-identifier-and-delius/tech-docs/diag/prison-identifier-and-delius-context-map.d2

@@ -0,0 +1,45 @@
+
+
+context-nomis: NOMIS/DPS Context {
+
+  entities: Entities {
+    grid-columns: 3
+    pip: Person\nin Prison
+    noms-number: NOMS Number
+    sentence: Sentence
+    booking: Booking
+    identifiers: Additional\nIdentifiers
+  }
+}
+
+context-delius: Delius Context {
+  style.stroke-width: 8
+
+  interface: Prison Identifier and Delius {
+    type: Anti-Corruption Layer
+  }
+
+  entities: Entities {
+    grid-columns: 3
+    pop: Person\non Probation
+    crn: Case Reference\nNumber (CRN)
+    sentence: Sentence
+    prison_number: Prisoner Number
+    identifiers: Additional\nIdentifiers
+  }
+}
+
+context-nomis--context-delius.interface: Upstream\n\n\nDownstream
+
+# Styles
+
+style {
+  fill: "#ffffff"
+}
+
+** {
+  style {
+    border-radius: 10
+    stroke-width: 2
+  }
+}

projects/prison-identifier-and-delius/tech-docs/diag/prison-identifier-and-delius-match-process.d2

@@ -0,0 +1,118 @@
+# Prison / Probation Person Matching
+
+direction: down
+
+one: Delius  {
+    explanation: |md
+    ## Delius Person Record / CRN
+    - Delius record must have an active event
+    - Delius record must have an active disposal
+    - Delius record must not have a NOMS number
+    |
+}
+
+
+two: NOMIS {
+    explanation: |md
+    ## Search NOMIS using Prison API Global Search
+    - Fields used for search are:
+      - First Name, Last Name
+      - Date of Birth
+      - Gender
+      - One Identifier - Either PNC, CRO or none
+    - The name search includes aliases
+    - Remove any results without booking number
+    - Remove any results without sentence dates
+    |
+}
+
+three: Delius {
+    explanation: |md
+    ## Match Sentence Start Date
+    - Match sentence start date across NOMIS and Delius
+    - There is tolerance of 1 week
+    |
+}
+
+four: Delius {
+    explanation: |md
+    ## Match Other System Identifiers
+    - Matching PNC is taken as a definitive match
+    - Matching CRO is taken as a definitive match
+    |
+}
+
+five: Delius {
+    explanation: |md
+    ## Match on Personal Details
+    - Exact match on forename, surname and date of birth is taken as a match
+    - Variations on spelling of names results in no match
+    - Variation in date of birth results in no match
+      - i.e. There is no tolerance on birth date matching
+    |
+}
+
+clash_check: Delius  {
+    explanation: |md
+    ## Determine if Record Would be a Duplicate
+    - Check if the matched NOMS Number is present\
+      on another Delius record
+    |
+}
+
+match: Delius  {
+    explanation: |md
+    ## Add Prison Details to Delius
+    - NOMS number added to the Delius person record
+    - Booking number added to the Delius custody record\
+    (as Prisoner Number)
+    |
+}
+
+no_action: No Action  {
+    explanation: |md
+    ## No Match
+    - No updates to Delius are made
+    |
+}
+
+end_1: End {
+  shape: circle
+}
+
+end_2: End {
+  shape: circle
+}
+
+one -> two
+
+two -> three: Results
+two -> no_action: No Results
+
+three -> four: Match
+three -> no_action: No Match
+
+four -> clash_check: Yes
+four -> five: No
+
+five -> clash_check: Yes
+five -> no_action: No
+
+clash_check -> match: Not Present on Other Record
+clash_check -> no_action: Present on Other Record
+
+match -> end_1
+no_action -> end_2
+
+# Styles
+
+style {
+  fill: "#ffffff"
+}
+
+** {
+  style {
+    border-radius: 10
+    stroke-width: 2
+  }
+}

projects/prison-identifier-and-delius/tech-docs/diag/prison-identifier-and-delius-workflow-id-update.d2

@@ -0,0 +1,54 @@
+# Prison Identifier Workflow: Prison Identifier Update - Batch
+
+direction: right
+
+integration_service: Prison Identifier and Delius {
+    style.font-size: 24
+
+    explanation: |md
+    ## Batch Request
+    List of CRNs to attempt NOMIS matching
+    |
+
+}
+
+integration_service -- nomis
+integration_service -- delius
+
+# What triggers the workflow?
+nomis: NOMIS  {
+     style.font-size: 24
+
+     explanation: |md
+     ## Prison API Query
+     Attempt to match person records across systems
+     |
+}
+
+# What happens in Delius?
+delius: Delius {
+    style.font-size: 24
+
+    explanation: |md
+    ## Person Record Updates
+    When a match is found
+    |
+
+    noms: NOMS Number added
+    booking: NOMIS booking number\nadded as 'Prisoner Number'
+
+    noms->booking
+}
+
+# Styles
+
+style {
+  fill: "#ffffff"
+}
+
+** {
+  style {
+    border-radius: 10
+    stroke-width: 2
+  }
+}