NPA-6153: Create Update Proxy Role Grantor Field (#300)

# Pull Request

## 🧾 Ticket Link

<!-- Add the Jira ticket link here -->

https://nhsd-jira.digital.nhs.uk/browse/NPA-6153

---

## 📄 Description/Summary of Changes

<!-- Describe the changes made in this PR. Include the
purpose/scope/impact of the changes -->

- Added grantor validation logic to ensure active proxy roles contain a
valid ODS code in the grantor extension with correct FHIR structure and
identifier system
- Updated spec files
- Updated sandbox code for relevant endpoints and added unit test
scenarios

---

## 🧪 Developer Testing Carried Out

<!-- Describe what tests (automated/unit/manual etc.) have been done for
the ticket. Include: -->
<!-- - Any tests added/updated -->
<!-- - Evidence that each acceptance criterion from the Jira ticket is
met -->

- <!-- Add bullet points for testing instructions -->
- <!-- Add bullet points for testing instructions -->
- <!-- Add bullet points for testing instructions -->

---

## 🧪 Reviewer Testing Required

<!-- Describe how to test the changes that have been made in the ticket.
Include: -->
<!-- - Testing environment details (e.g. sandbox/local setup) -->
<!-- - Steps to verify the changes -->

- [ ] <!-- Add bullet points for testing instructions -->
- [ ] <!-- Add bullet points for testing instructions -->
- [ ] <!-- Add bullet points for testing instructions -->

---

## ✅ Developer Checklist

<!-- Complete before submitting the PR -->

- [x] PR title follows the format: `NPA-XXXX: <short-description>`
- [x] Branch name follows the convention:
`<type>/NPA-XXXX/<short-description>`
- [x] Commit messages follow the template: `NPA-XXXX:
<short-description>`
- [x] All acceptance criteria from the Jira ticket are addressed
- [x] Automated tests (unit/integration/API/infrastructure etc. tests)
are added or updated
- [x] Assignees and appropriate labels (e.g. `terraform`,
`documentation`) are added

---

## 👀 Reviewer Checklist

<!-- To be completed by the reviewer -->

- [ ] Changes meet the acceptance criteria of the Jira ticket
- [ ] Code is able to be merged (no conflicts and adheres to coding
standards)
- [ ] Sufficient test evidence is provided (manual and/or automated)
- [ ] Infrastructure/operational/build changes are validated (if
applicable)

---

## 🚀 Post-merge

<!-- Actions to complete after merging -->

After merging and deploying changes to the sandbox, Postman collection
or spec examples please run the Run Postman
collection workflow.

This will run the tests within the collection to check that the sandbox
is working as expected once deployed.

Author: LeoKHoward

.github/pull_request_template.md

@@ -36,9 +36,9 @@ https://nhsd-jira.digital.nhs.uk/browse/NPA-XXXX
 <!-- - Testing environment details (e.g. sandbox/local setup) -->
 <!-- - Steps to verify the changes -->
 
-- [ ] <!-- Add bullet points for testing instructions -->
-- [ ] <!-- Add bullet points for testing instructions -->
-- [ ] <!-- Add bullet points for testing instructions -->
+- <!-- Add bullet points for testing instructions -->
+- <!-- Add bullet points for testing instructions -->
+- <!-- Add bullet points for testing instructions -->
 
 ---
 

postman/validated_relationship_service.integration.postman_collection.json

@@ -83,6 +83,10 @@
 POST_CONSENT__SUCCESS = f"{POST_CONSENT__DIRECTORY}success.yaml"
 POST_CONSENT__DUPLICATE_RELATIONSHIP_ERROR = f"{POST_CONSENT__DIRECTORY}errors/duplicate_relationship_error.yaml"
 POST_CONSENT__MISSING_FREE_TEXT_FOR_OTHER = f"{POST_CONSENT__DIRECTORY}errors/missing_free_text_for_other.yaml"
+POST_CONSENT__MISSING_GRANTOR = f"{POST_CONSENT__DIRECTORY}errors/missing_grantor.yaml"
+POST_CONSENT__INVALID_GRANTOR_VALUE = f"{POST_CONSENT__DIRECTORY}errors/invalid_grantor_identifier_value.yaml"
+POST_CONSENT__INVALID_GRANTOR_SYSTEM = f"{POST_CONSENT__DIRECTORY}errors/invalid_grantor_identifier_system.yaml"
+POST_CONSENT__MISSING_GRANTOR_REFERENCE = f"{POST_CONSENT__DIRECTORY}errors/missing_grantor_reference.yaml"
 
 # PATCH Consent
 PATCH_CONSENT__DIRECTORY = "./api/examples/PATCH_Consent/"
@@ -94,6 +98,7 @@
 PATCH_CONSENT__RESOURCE_NOT_FOUND = f"{PATCH_CONSENT__DIRECTORY}errors/resource_not_found.yaml"
 PATCH_CONSENT__INVALID_STATE_TRANSITION = f"{PATCH_CONSENT__DIRECTORY}errors/invalid_state_transition.yaml"
 PATCH_CONSENT__MISSING_FREE_TEXT_FOR_OTHER = f"{PATCH_CONSENT__DIRECTORY}errors/missing_free_text_for_other.yaml"
+PATCH_CONSENT__MISSING_GRANTOR_FOR_ACTIVE = f"{PATCH_CONSENT__DIRECTORY}errors/missing_grantor_for_active_status.yaml"
 
 # POST QuestionnaireResponse
 POST_QUESTIONNAIRE_RESPONSE_DIRECTORY = "./api/examples/POST_QuestionnaireResponse/"

postman/validated_relationship_service.sandbox.postman_collection.json

@@ -11,6 +11,7 @@
     PATCH_CONSENT__SUCCESS,
     PATCH_CONSENT__INVALID_STATUS_REASON,
     PATCH_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
+    PATCH_CONSENT__MISSING_GRANTOR_FOR_ACTIVE,
 )
 from .utils import generate_response_from_example
 
@@ -82,6 +83,10 @@ def patch_consent_response(id: str) -> Union[dict, tuple]:
             # Non-OTHER reason code WITH free text (should succeed)
             return generate_response_from_example(PATCH_CONSENT__SUCCESS, 200)
 
+        elif id == "90957744-b971-496e-b7c3-ab971868ce14":
+            # PATCH to activate proxy role without providing grantor extension
+            return generate_response_from_example(PATCH_CONSENT__MISSING_GRANTOR_FOR_ACTIVE, 400)
+
         else:
             # Resource not found
             return generate_response_from_example(PATCH_CONSENT__RESOURCE_NOT_FOUND, 404)

sandbox/api/constants.py

@@ -8,6 +8,10 @@
     POST_CONSENT__DUPLICATE_RELATIONSHIP_ERROR,
     POST_CONSENT__SUCCESS,
     POST_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
+    POST_CONSENT__MISSING_GRANTOR,
+    POST_CONSENT__INVALID_GRANTOR_VALUE,
+    POST_CONSENT__INVALID_GRANTOR_SYSTEM,
+    POST_CONSENT__MISSING_GRANTOR_REFERENCE,
 )
 from .utils import generate_response_from_example
 
@@ -59,6 +63,22 @@ def post_consent_response() -> Union[dict, tuple]:
             header = {"location": f"{CONSENT_APP_BASE_PATH}/c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9"}
             response = generate_response_from_example(POST_CONSENT__SUCCESS, 201, headers=header)
 
+        elif patient_identifier == "9000000054":
+            # Missing grantor entirely when active
+            response = generate_response_from_example(POST_CONSENT__MISSING_GRANTOR, 400)
+
+        elif patient_identifier == "9000000055":
+            # Invalid/empty ODS code
+            response = generate_response_from_example(POST_CONSENT__INVALID_GRANTOR_VALUE, 422)
+
+        elif patient_identifier == "9000000056":
+            # Wrong system
+            response = generate_response_from_example(POST_CONSENT__INVALID_GRANTOR_SYSTEM, 422)
+
+        elif patient_identifier == "9000000057":
+            # Missing valueReference/identifier
+            response = generate_response_from_example(POST_CONSENT__MISSING_GRANTOR_REFERENCE, 400)
+
         else:
             # Out of scope errors
             raise ValueError("Invalid Request")

sandbox/api/patch_consent.py

@@ -13,6 +13,7 @@
     PATCH_CONSENT__SUCCESS,
     PATCH_CONSENT__INVALID_STATUS_REASON,
     PATCH_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
+    PATCH_CONSENT__MISSING_GRANTOR_FOR_ACTIVE,
 )
 
 CONSENT_API_ENDPOINT = "/FHIR/R4/Consent"
@@ -50,6 +51,11 @@
             PATCH_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
             400,
         ),
+        (
+            "90957744-b971-496e-b7c3-ab971868ce14",
+            PATCH_CONSENT__MISSING_GRANTOR_FOR_ACTIVE,
+            400,
+        ),
         (
             "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
             PATCH_CONSENT__SUCCESS,

sandbox/api/post_consent.py

@@ -8,6 +8,10 @@
     POST_CONSENT__DUPLICATE_RELATIONSHIP_ERROR,
     POST_CONSENT__SUCCESS,
     POST_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
+    POST_CONSENT__MISSING_GRANTOR,
+    POST_CONSENT__INVALID_GRANTOR_VALUE,
+    POST_CONSENT__INVALID_GRANTOR_SYSTEM,
+    POST_CONSENT__MISSING_GRANTOR_REFERENCE,
 )
 
 CONSENT_API_ENDPOINT = "/FHIR/R4/Consent"
@@ -35,6 +39,30 @@
             400,
             None,
         ),
+        (
+            "9000000054",
+            POST_CONSENT__MISSING_GRANTOR,
+            400,
+            None,
+        ),
+        (
+            "9000000055",
+            POST_CONSENT__INVALID_GRANTOR_VALUE,
+            422,
+            None,
+        ),
+        (
+            "9000000056",
+            POST_CONSENT__INVALID_GRANTOR_SYSTEM,
+            422,
+            None,
+        ),
+        (
+            "9000000057",
+            POST_CONSENT__MISSING_GRANTOR_REFERENCE,
+            400,
+            None,
+        ),
         (
             "9000000051",
             POST_CONSENT__SUCCESS,

sandbox/api/tests/test_patch_consent.py

@@ -46,3 +46,9 @@ ConsentAdultToAdultGuardianRequest:
           identifier:
             system: https://fhir.nhs.uk/Id/nhs-number
             value: '9000000017'
+      - url: http://hl7.org/fhir/5.0/StructureDefinition/extension-Consent.grantor
+        valueReference:
+          identifier:
+            system: https://fhir.nhs.uk/Id/ods-organization-code
+            value: "G8101234"
+

sandbox/api/tests/test_post_consent.py

@@ -47,3 +47,8 @@ ConsentParentChildProxyCreationRequest:
           identifier:
             system: https://fhir.nhs.uk/Id/nhs-number
             value: '9000000009'
+      - url: http://hl7.org/fhir/5.0/StructureDefinition/extension-Consent.grantor
+        valueReference:
+          identifier:
+            system: https://fhir.nhs.uk/Id/ods-organization-code
+            value: "G8101234"