NPA-6124: Add Free Text For Status Change

sandbox/api/constants.py

@@ -83,6 +83,7 @@
 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__PERFORMER_IDENTIFIER_ERROR = f"{POST_CONSENT__DIRECTORY}errors/invalid_performer_identifier_error.yaml"
+POST_CONSENT__MISSING_FREE_TEXT_FOR_OTHER = f"{POST_CONSENT__DIRECTORY}errors/missing_free_text_for_other.yaml"
 
 # PATCH Consent
 PATCH_CONSENT__DIRECTORY = "./api/examples/PATCH_Consent/"
@@ -93,6 +94,7 @@
 PATCH_CONSENT__INVALID_STATUS_REASON = f"{PATCH_CONSENT__DIRECTORY}errors/invalid_status_reason.yaml"
 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"
 
 # POST QuestionnaireResponse
 POST_QUESTIONNAIRE_RESPONSE_DIRECTORY = "./api/examples/POST_QuestionnaireResponse/"

sandbox/api/patch_consent.py

@@ -10,6 +10,7 @@
     PATCH_CONSENT__RESOURCE_NOT_FOUND,
     PATCH_CONSENT__SUCCESS,
     PATCH_CONSENT__INVALID_STATUS_REASON,
+    PATCH_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
 )
 from .utils import generate_response_from_example
 
@@ -63,6 +64,24 @@ def patch_consent_response(id: str) -> Union[dict, tuple]:
             # Invalid state transition
             return generate_response_from_example(PATCH_CONSENT__INVALID_STATE_TRANSITION, 422)
 
+        # Mandatory free text for OTHER reason codes
+        elif id == "d4e8a6f2-1c3b-4a7e-9d2f-8b5c7e9f1a3d":
+            # Missing free text for OTHER reason code (should fail)
+            return generate_response_from_example(PATCH_CONSENT__MISSING_FREE_TEXT_FOR_OTHER, 400)
+
+        elif id == "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7":
+            # Valid OTHER reason code WITH free text (should succeed)
+            return generate_response_from_example(PATCH_CONSENT__SUCCESS, 200)
+
+        # Optional free text for non-OTHER reason codes
+        elif id == "b2c3d4e5-f6a7-4890-b1c2-d3e4f5a6b7c8":
+            # Non-OTHER reason code WITHOUT free text (should succeed)
+            return generate_response_from_example(PATCH_CONSENT__SUCCESS, 200)
+
+        elif id == "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9":
+            # Non-OTHER reason code WITH free text (should succeed)
+            return generate_response_from_example(PATCH_CONSENT__SUCCESS, 200)
+
         else:
             # Resource not found
             return generate_response_from_example(PATCH_CONSENT__RESOURCE_NOT_FOUND, 404)

sandbox/api/post_consent.py

@@ -8,6 +8,7 @@
     POST_CONSENT__DUPLICATE_RELATIONSHIP_ERROR,
     POST_CONSENT__PERFORMER_IDENTIFIER_ERROR,
     POST_CONSENT__SUCCESS,
+    POST_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
 )
 from .utils import generate_response_from_example
 
@@ -38,9 +39,31 @@ def post_consent_response() -> Union[dict, tuple]:
         # Duplicate relationship
         elif patient_identifier == "9000000049":
             response = generate_response_from_example(POST_CONSENT__DUPLICATE_RELATIONSHIP_ERROR, 409)
+
         # Invalid performer NHS number
         elif patient_identifier == "9000000000":
             response = generate_response_from_example(POST_CONSENT__PERFORMER_IDENTIFIER_ERROR, 422)
+
+        elif patient_identifier == "9000000050":
+            # Missing free text for OTHER reason code (should fail)
+            response = generate_response_from_example(POST_CONSENT__MISSING_FREE_TEXT_FOR_OTHER, 400)
+
+        elif patient_identifier == "9000000051":
+            # Valid OTHER reason code WITH free text (should succeed)
+            header = {"location": f"{CONSENT_APP_BASE_PATH}/a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7"}
+            response = generate_response_from_example(POST_CONSENT__SUCCESS, 201, headers=header)
+
+            # Optional free text for non-OTHER reason codes
+        elif patient_identifier == "9000000052":
+            # Non-OTHER reason code WITHOUT free text (should succeed)
+            header = {"location": f"{CONSENT_APP_BASE_PATH}/b2c3d4e5-f6a7-4890-b1c2-d3e4f5a6b7c8"}
+            response = generate_response_from_example(POST_CONSENT__SUCCESS, 201, headers=header)
+
+        elif patient_identifier == "9000000053":
+            # Non-OTHER reason code WITH free text (should succeed)
+            header = {"location": f"{CONSENT_APP_BASE_PATH}/c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9"}
+            response = generate_response_from_example(POST_CONSENT__SUCCESS, 201, headers=header)
+
         else:
             # Out of scope errors
             raise ValueError("Invalid Request")

sandbox/api/tests/test_patch_consent.py

@@ -12,6 +12,7 @@
     PATCH_CONSENT__RESOURCE_NOT_FOUND,
     PATCH_CONSENT__SUCCESS,
     PATCH_CONSENT__INVALID_STATUS_REASON,
+    PATCH_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
 )
 
 CONSENT_API_ENDPOINT = "/FHIR/R4/Consent"
@@ -44,6 +45,26 @@
             PATCH_CONSENT__INVALID_STATE_TRANSITION,
             422,
         ),
+        (
+            "d4e8a6f2-1c3b-4a7e-9d2f-8b5c7e9f1a3d",
+            PATCH_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
+            400,
+        ),
+        (
+            "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
+            PATCH_CONSENT__SUCCESS,
+            200,
+        ),
+        (
+            "b2c3d4e5-f6a7-4890-b1c2-d3e4f5a6b7c8",
+            PATCH_CONSENT__SUCCESS,
+            200,
+        ),
+        (
+            "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9",
+            PATCH_CONSENT__SUCCESS,
+            200,
+        ),
         ("xxxxxxxx", PATCH_CONSENT__RESOURCE_NOT_FOUND, 404),
         ("12345678", PATCH_CONSENT__RESOURCE_NOT_FOUND, 404),
     ],

sandbox/api/tests/test_post_consent.py

@@ -8,6 +8,7 @@
     POST_CONSENT__DUPLICATE_RELATIONSHIP_ERROR,
     POST_CONSENT__PERFORMER_IDENTIFIER_ERROR,
     POST_CONSENT__SUCCESS,
+    POST_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
 )
 
 CONSENT_API_ENDPOINT = "/FHIR/R4/Consent"
@@ -30,6 +31,30 @@
         ),
         ("9000000000", POST_CONSENT__PERFORMER_IDENTIFIER_ERROR, 422, None),
         ("9000000049", POST_CONSENT__DUPLICATE_RELATIONSHIP_ERROR, 409, None),
+        (
+            "9000000050",
+            POST_CONSENT__MISSING_FREE_TEXT_FOR_OTHER,
+            400,
+            None,
+        ),
+        (
+            "9000000051",
+            POST_CONSENT__SUCCESS,
+            201,
+            "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
+        ),
+        (
+            "9000000052",
+            POST_CONSENT__SUCCESS,
+            201,
+            "b2c3d4e5-f6a7-4890-b1c2-d3e4f5a6b7c8",
+        ),
+        (
+            "9000000053",
+            POST_CONSENT__SUCCESS,
+            201,
+            "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9",
+        ),
     ],
 )
 @patch("sandbox.api.post_consent.generate_response_from_example")

specification/examples/responses/GET_Consent/filtered-relationships-status-inactive.yaml

@@ -112,5 +112,12 @@ ConsentMultipleRelationshipsStatusInactiveBundle:
                 - system: https://terminology.hl7.org/CodeSystem/consent-reason
                   code: ROLE_DEACTIVATED_END_DATE_REACHED
                   display: End-date reached
+          - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+            valueCodeableConcept:
+              coding:
+                - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                  code: OTHER
+                  display: Other
+              text: Patient would not respond to phone calls
         search:
           mode: match

specification/examples/responses/GET_Consent/multiple-relationships-include-patient.yaml

@@ -260,5 +260,12 @@ ConsentMultipleRelationshipsIncludePatientBundle:
                 - system: https://terminology.hl7.org/CodeSystem/consent-reason
                   code: ROLE_DEACTIVATED_END_DATE_REACHED
                   display: End-date reached
+          - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+            valueCodeableConcept:
+              coding:
+                - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                  code: OTHER
+                  display: Other
+              text: Patient would not respond to phone calls
         search:
           mode: match

specification/examples/responses/GET_Consent/multiple-relationships-include-performer-patient.yaml

@@ -328,5 +328,12 @@ ConsentMultipleRelationshipsIncludePerformerPatientBundle:
                 - system: https://terminology.hl7.org/CodeSystem/consent-reason
                   code: ROLE_DEACTIVATED_END_DATE_REACHED
                   display: End-date reached
+          - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+            valueCodeableConcept:
+              coding:
+                - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                  code: OTHER
+                  display: Other
+              text: Patient would not respond to phone calls
         search:
           mode: match

specification/examples/responses/GET_Consent/multiple-relationships-include-performer.yaml

@@ -237,6 +237,13 @@ ConsentMultipleRelationshipsIncludePerformerBundle:
                 - system: https://terminology.hl7.org/CodeSystem/consent-reason
                   code: ROLE_DEACTIVATED_END_DATE_REACHED
                   display: End-date reached
+          - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+            valueCodeableConcept:
+              coding:
+                  - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                    code: OTHER
+                    display: Other
+              text: Patient would not respond to phone calls
         search:
           mode: match
 

specification/examples/responses/GET_Consent/multiple-relationships-single-patient-include-patient.yaml

@@ -195,5 +195,12 @@ ConsentMultipleRelationshipsSinglePatientIncludePatientBundle:
                 - system: https://terminology.hl7.org/CodeSystem/consent-reason
                   code: ROLE_DEACTIVATED_END_DATE_REACHED
                   display: End-date reached
+          - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+            valueCodeableConcept:
+              coding:
+                - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                  code: OTHER
+                  display: Other
+              text: Patient would not respond to phone calls
         search:
           mode: match

specification/examples/responses/GET_Consent/multiple-relationships-single-patient-include-performer-patient.yaml

@@ -259,5 +259,12 @@ ConsentMultipleRelationshipsSinglePatientIncludePerformerPatientBundle:
                 - system: https://terminology.hl7.org/CodeSystem/consent-reason
                   code: ROLE_DEACTIVATED_END_DATE_REACHED
                   display: End-date reached
+          - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+            valueCodeableConcept:
+              coding:
+                - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                  code: OTHER
+                  display: Other
+              text: Patient would not respond to phone calls
         search:
           mode: match

specification/examples/responses/GET_Consent/multiple-relationships-single-patient-include-performer.yaml

@@ -228,5 +228,12 @@ ConsentMultipleRelationshipsSinglePatientIncludePerformerPatientBundle:
                 - system: https://terminology.hl7.org/CodeSystem/consent-reason
                   code: ROLE_DEACTIVATED_END_DATE_REACHED
                   display: End-date reached
+          - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+            valueCodeableConcept:
+              coding:
+                - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                  code: OTHER
+                  display: Other
+              text: Patient would not respond to phone calls
         search:
           mode: match

specification/examples/responses/GET_Consent/multiple-relationships-single-patient.yaml

@@ -164,5 +164,12 @@ ConsentMultipleRelationshipsSinglePatientBundle:
                 - system: https://terminology.hl7.org/CodeSystem/consent-reason
                   code: ROLE_DEACTIVATED_END_DATE_REACHED
                   display: End-date reached
+          - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+            valueCodeableConcept:
+              coding:
+                - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                  code: OTHER
+                  display: Other
+              text: Patient would not respond to phone calls
         search:
           mode: match

specification/examples/responses/GET_Consent/multiple-relationships.yaml

@@ -164,5 +164,12 @@ ConsentMultipleRelationshipsBundle:
                 - system: https://terminology.hl7.org/CodeSystem/consent-reason
                   code: ROLE_DEACTIVATED_END_DATE_REACHED
                   display: End-date reached
+          - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+            valueCodeableConcept:
+              coding:
+                - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                  code: OTHER
+                  display: Other
+              text: Patient would not respond to phone calls
         search:
           mode: match

specification/examples/responses/PATCH_Consent/errors/missing_free_text_for_other.yaml

@@ -0,0 +1,15 @@
+PatchConsentMissingFreeTextForOtherError:
+  summary: Bad request when free text is missing for OTHER reason code
+  description: 400 error response when free text is not provided for OTHER reason codes
+  value:
+    issue:
+      - code: invalid
+        diagnostics: "Free text is required when reason code is OTHER."
+        details:
+          coding:
+            - code: "MISSING_FREE_TEXT_FOR_OTHER"
+              display: "Free text must be provided for OTHER reason codes."
+              system: "https://fhir.nhs.uk/R4/CodeSystem/ValidatedRelationships-ErrorOrWarningCode"
+              version: '1'
+        severity: error
+    resourceType: "OperationOutcome"

specification/examples/responses/POST_Consent/errors/missing_free_text_for_other.yaml

@@ -0,0 +1,15 @@
+PostConsentMissingFreeTextForOtherError:
+  summary: Bad request when free text is missing for OTHER reason code
+  description: 400 error response when free text is not provided for OTHER reason codes
+  value:
+    issue:
+      - code: invalid
+        diagnostics: "Free text is required when reason code is OTHER."
+        details:
+          coding:
+            - code: "MISSING_FREE_TEXT_FOR_OTHER"
+              display: "Free text must be provided for OTHER reason codes."
+              system: "https://fhir.nhs.uk/R4/CodeSystem/ValidatedRelationships-ErrorOrWarningCode"
+              version: '1'
+        severity: error
+    resourceType: "OperationOutcome"

specification/validated-relationships-service-api.yaml

@@ -794,6 +794,8 @@ paths:
                   $ref: "./examples/responses/POST_Consent/errors/invalid_request.yaml#/PostConsentInvalidRequestError"
                 postConsentInvalidFHIRRequest:
                   $ref: "./examples/responses/POST_Consent/errors/invalid_request.yaml#/PostConsentInvalidFHIRRequestError"
+                postConsentMissingFreeTextForOther:
+                  $ref: "./examples/responses/POST_Consent/errors/missing_free_text_for_other.yaml#/PostConsentMissingFreeTextForOtherError"
 
         "5XX":
           description: |
@@ -1071,6 +1073,8 @@ paths:
                   $ref: "./examples/responses/PATCH_Consent/errors/invalid_status_reason.yaml#/PatchConsentInvalidStatusReasonError"
                 patchConsentInvalidStateTransitionError:
                   $ref: "./examples/responses/PATCH_Consent/errors/invalid_state_transition.yaml#/PatchConsentInvalidStateTransitionError"
+                patchConsentMissingFreeTextForOther:
+                  $ref: "./examples/responses/PATCH_Consent/errors/missing_free_text_for_other.yaml#/PatchConsentMissingFreeTextForOtherError"
         "5XX":
           description: |
             Errors will be returned for the first error encountered in the request. An error occurred as follows: