Interaction Update

Update operation describes interaction required to update a Reasonable Adjustment Flag, an Adjustment or an Impairment on Spine via the FHIR® Reasonable Adjustments API

Important: This site is under active development by NHS Digital and is intended to provide all the technical resources you need to successfully develop applications using the FHIR® Reasonable Adjustments API. This project is being developed using an agile methodology so iterative updates to content will be added on a regular basis.

Warning: This site is provided for information only and is intended for those engaged with NHS Digital. It is advised not to develop against these specifications until a formal announcement has been made.

1 Update RA Record Use Case

1.1 Trigger:

Post-op appt with GP. Patient requests change of ‘Easy Read’ Adjustment to ‘Large Print’

1.2 Pre-requisites:

(This scenario assumes someone has created an ‘Easy Read’ Reasonable Adjustment between the Read and Update examples)
Practioner Dr D. logged on w SmartCard/National Identity > URPId - see API Security
Patient Mrs M. PDS Trace > verified NHS#, Name, DoB demographic data - see Patient Demographics
ClientSystem has Patient’s existing RArecord available - see ‘Read an RA Flag’

1.3 System Scope:

ClientSystem includes GPSystem client, SCRa, 1-click etc.
ServerSystem includes Spine, PDS, SDS, FlagServer etc.

1.4 Summary:

During appt GP discusses RA Record. Patient requests change of Reasonable Adjustment ‘Easy Read’ to ‘Large Print’.
Practitioner updates (soft deletes) existing ‘Easy Read’ Adjustment, records Removal reason ‘Entered in error’
[then creates new ‘Large Print’ Adjustment - not shown cf. Create Consent response].

Pre

Patient arrives at post-op appt Practitioner opens GPSystem, traces & verifies demographic info (internal call to PDS) Practitioner opens Patient’s RARecord System retrieves and displays RARecord for Patient’s NHS

Main

Practitioner discusses RARecord and RA with Patient, Patient doesn’t like Easy Read
Practitioner discusses options w Patient, Patient agrees change RA ‘Easy Read’ to ‘Large Print’
Practitioner updates (soft deletes) existing ‘Easy Read’ Adjustment, records Removal reason ‘Entered in error’;
- ClientSystem updates held Flag resource
Practitioner commits RARecord
- ClientSystem submits Update Flag request
  - ServerSystem services Update Consent request
    - ServerSystem submits Update Consent response
Practitioner records new ‘Large Print’ Adjustment
- ClientSystem captures and structures Adjustment information as new RARecord-Flag-1 resource
- …
- not shown cf. Create Consent request & response as a directly analogous operation etc…

2 Update RA Record Examples

2.1 Update Flag Request

http request

PUT https://clinicals.spineservices.nhs.uk/STU3/Flag/744eec7d-8951-4722-ad74-dc34e86d4e1a HTTP/1.1
If-Match: W/"25777f7d-27bc"

body

RARecord-UpdateFlagRequestBody-example XML Example

<!-- UpdateFlagRequestBody-example.xml -->
<Flag xmlns="http://hl7.org/fhir">
    <id value="744eec7d-8951-4722-ad74-dc34e86d4e1a"/>
    <meta>
        <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Flag-1"/>
    </meta>
    <contained>
        <Provenance>
            <id value="2c625745-c551-419d-beaf-96ba5c4a3790"/>
            <meta>
                <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Provenance-1"/>
            </meta>
            <target>
                <reference value="Flag/744eec7d-8951-4722-ad74-dc34e86d4e1a"/>
            </target>
            <recorded value="2016-03-01T10:05:33+00:00"/>
            <agent>
                <role>
                    <coding>
                        <system value="https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1"/>
                        <code value="R0260"/>
                        <display value="General Medical Practitioner"/>
                    </coding>
                </role>
                <whoReference>
                    <reference value="https://sds.spineservices.nhs.uk/STU3/Practitioner/2ee4tr6a9"/>
                    <display value="Dr.D"/>
                </whoReference>
                <onBehalfOfReference>
                    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/a3e5i7"/>
                    <display value="Some GP Clinic"/>
                </onBehalfOfReference>
            </agent>
        </Provenance>
    </contained>
    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-Provenance-1">
        <extension url="created">
            <valueReference>
                <reference value="#2c625745-c551-419d-beaf-96ba5c4a3790"/>
            </valueReference>
        </extension>
    </extension>
    <!-- updated provenance would go here, but will be populated server-side -->
    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-RemovalReason-1">
        <valueCodeableConcept>
            <coding>
                <system value="https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-RemovalReason-1"/>
                <code value="Error"/>
                <display value="The Reasonable Adjustment Flag was created in error"/>
            </coding>
        </valueCodeableConcept>
    </extension>
    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-AdjustmentCategory-1">
        <valueCodeableConcept>
            <coding>
                <system value="https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-AdjustmentCategories-1"/>
                <code value="comms"/>
                <display value="Communication"/>
            </coding>
        </valueCodeableConcept>
    </extension>
    <status value="inactive"/>
    <category>
        <coding>
            <system value="https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-FlagCategory-1"/>
            <code value="reasonable adjustments flag"/>
            <display value="Reasonable Adjustments Flag"/>
        </coding>
    </category>
    <code>
        <coding>
            <system value="https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-AccessibleInformationAdjustments-1"/>
            <code value="requiresinformationineasyread"/>
            <display value="Requires information in Easyread"/>
        </coding>
    </code>
    <subject>
        <identifier>
            <reference value="demographics.spineservices.nhs.uk/STU3/Patient/999999998"/>
        </identifier>
    </subject>
</Flag>

RARecord-UpdateFlagRequestBody-example JSON Example

{
  "resourceType": "Flag",
  "id": "744eec7d-8951-4722-ad74-dc34e86d4e1a",
  "fhir_comments": [
    " UpdateFlagRequestBody-example.xml "
  ],
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Flag-1"
    ]
  },
  "contained": [
    {
      "resourceType": "Provenance",
      "id": "2c625745-c551-419d-beaf-96ba5c4a3790",
      "meta": {
        "profile": [
          "https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Provenance-1"
        ]
      },
      "target": [
        {
          "reference": "744eec7d-8951-4722-ad74-dc34e86d4e1a"
        }
      ],
      "recorded": "2016-03-01T10:05:33+00:00",
      "agent": [
        {
          "role": [
            {
              "coding": [
                {
                  "system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1",
                  "code": "R0260",
                  "display": "General Medical Practitioner"
                }
              ]
            }
          ],
          "whoReference": {
            "reference": "https://sds.spineservices.nhs.uk/STU3/Practitioner/2ee4tr6a9",
            "display": "Dr.D"
          },
          "onBehalfOfReference": {
            "reference": "https://directory.spineservices.nhs.uk/STU3/Organization/a3e5i7",
            "display": "Some GP Clinic"
          }
        }
      ]
    }
  ],
  "extension": [
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-Provenance-1",
      "extension": [
        {
          "url": "created",
          "valueReference": {
            "reference": "#2c625745-c551-419d-beaf-96ba5c4a3790"
          }
        }
      ]
    },
    {
      "fhir_comments": [
        " updated provenance would go here, but will be populated server-side "
      ],
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-RemovalReason-1",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-RemovalReason-1",
            "code": "Error",
            "display": "The Reasonable Adjustment Flag was created in error"
          }
        ]
      }
    },
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-AdjustmentCategory-1",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-AdjustmentCategories-1",
            "code": "comms",
            "display": "Communication"
          }
        ]
      }
    }
  ],
  "status": "inactive",
  "category": {
    "coding": [
      {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-FlagCategory-1",
        "code": "reasonable adjustments flag",
        "display": "Reasonable Adjustments Flag"
      }
    ]
  },
  "code": {
    "coding": [
      {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-AccessibleInformationAdjustments-1",
        "code": "requiresinformationineasyread",
        "display": "Requires information in Easyread"
      }
    ]
  },
  "subject": {
    "identifier": {
      "system": "https://fhir.nhs.uk/Id/nhs-number",
      "value": "999999998"
    }
  }
}

headers

Client systems SHALL carry the security HTTP headers as defined on the Security page.

In addition, updates MUST include the If-Match header specifying the version of the resource they are updating.

2.2 Update Flag Response

http response

FHIR Reasonable Adjustments API requests are to follow standard Spine Core response and error handling patterns. Details of the handling patterns and error codes are found on their Error handling pages
Edge cases TBD and detailed during development

body

RARecord-UpdateFlagResponseBody-example XML Example

<!-- UpdateFlagResponseBody-example.xml -->
<Flag xmlns="http://hl7.org/fhir">
    <id value="04bc263e-af5d-4b78-81ab-d527f2ebc839"/>
    <meta>
        <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Flag-1"/>
    </meta>
    <contained>
        <Provenance>
            <id value="de615f06-41d7-4659-b543-b401ece571cb"/>
            <meta>
                <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Provenance-1"/>
            </meta>
            <target>
                <reference value="Flag/04bc263e-af5d-4b78-81ab-d527f2ebc839"/>
            </target>
            <recorded value="2016-03-01T10:05:33+00:00"/>
            <agent>
                <role>
                    <coding>
                        <system value="https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1"/>
                        <code value="R0260"/>
                        <display value="General Medical Practitioner"/>
                    </coding>
                </role>
                <whoReference>
                    <reference value="https://sds.spineservices.nhs.uk/STU3/Practitioner/2ee4tr6a9"/>
                    <display value="Dr.D"/>
                </whoReference>
                <onBehalfOfReference>
                    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/a3e5i7"/>
                    <display value="Some GP Clinic"/>
                </onBehalfOfReference>
            </agent>
        </Provenance>
    </contained>
    <contained>
        <Provenance>
            <id value="916be0f8-be88-4d12-b3a9-4077ed05292e"/>
            <meta>
                <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Provenance-1"/>
            </meta>
            <target>
                <reference value="Flag/04bc263e-af5d-4b78-81ab-d527f2ebc839"/>
            </target>
            <recorded value="2016-03-01T10:05:33+00:00"/>
            <agent>
                <role>
                    <coding>
                        <system value="https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1"/>
                        <code value="R0260"/>
                        <display value="General Medical Practitioner"/>
                    </coding>
                </role>
                <whoReference>
                    <reference value="https://sds.spineservices.nhs.uk/STU3/Practitioner/2ee4tr6a9"/>
                    <display value="Dr.D"/>
                </whoReference>
                <onBehalfOfReference>
                    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/a3e5i7"/>
                    <display value="Some GP Clinic"/>
                </onBehalfOfReference>
            </agent>
        </Provenance>
    </contained>
    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-Provenance-1">
        <extension url="created">
            <valueReference>
                <reference value="#de615f06-41d7-4659-b543-b401ece571cb"/>
            </valueReference>
        </extension>
        <extension url="updated">
            <valueReference>
                <reference value="#916be0f8-be88-4d12-b3a9-4077ed05292e"/>
            </valueReference>
        </extension>
    </extension>
    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-RemovalReason-1">
        <valueCodeableConcept>
            <coding>
                <system value="https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-RemovalReason-1"/>
                <code value="Error"/>
                <display value="The Reasonable Adjustment Flag was created in error"/>
            </coding>
        </valueCodeableConcept>
    </extension>
    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-AdjustmentCategory-1">
        <valueCodeableConcept>
            <coding>
                <system value="https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-AdjustmentCategories-1"/>
                <code value="comms"/>
                <display value="Communication"/>
            </coding>
        </valueCodeableConcept>
    </extension>
    <status value="inactive"/>
    <category>
        <coding>
            <system value="https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-FlagCategory-1"/>
            <code value="reasonable adjustments flag"/>
            <display value="Reasonable Adjustments Flag"/>
        </coding>
    </category>
    <code>
        <coding>
            <system value="https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-AccessibleInformationAdjustments-1"/>
            <code value="requiresinformationineasyread"/>
            <display value="Requires information in Easyread"/>
        </coding>
    </code>
    <subject>
        <identifier>
            <reference value="demographics.spineservices.nhs.uk/STU3/Patient/999999998"/>
        </identifier>
    </subject>
</Flag>

RARecord-UpdateFlagResponseBody-example JSON Example

{
  "resourceType": "Flag",
  "id": "04bc263e-af5d-4b78-81ab-d527f2ebc839",
  "fhir_comments": [
    " UpdateFlagResponseBody-example.xml "
  ],
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Flag-1"
    ]
  },
  "contained": [
    {
      "resourceType": "Provenance",
      "id": "de615f06-41d7-4659-b543-b401ece571cb",
      "meta": {
        "profile": [
          "https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Provenance-1"
        ]
      },
      "target": [
        {
          "reference": "04bc263e-af5d-4b78-81ab-d527f2ebc839"
        }
      ],
      "recorded": "2016-03-01T10:05:33+00:00",
      "agent": [
        {
          "role": [
            {
              "coding": [
                {
                  "system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1",
                  "code": "R0260",
                  "display": "General Medical Practitioner"
                }
              ]
            }
          ],
          "whoReference": {
            "reference": "https://sds.spineservices.nhs.uk/STU3/Practitioner/2ee4tr6a9",
            "display": "Dr.D"
          },
          "onBehalfOfReference": {
            "reference": "https://directory.spineservices.nhs.uk/STU3/Organization/a3e5i7",
            "display": "Some GP Clinic"
          }
        }
      ]
    },
    {
      "resourceType": "Provenance",
      "id": "916be0f8-be88-4d12-b3a9-4077ed05292e",
      "meta": {
        "profile": [
          "https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Provenance-1"
        ]
      },
      "target": [
        {
          "reference": "04bc263e-af5d-4b78-81ab-d527f2ebc839"
        }
      ],
      "recorded": "2016-03-01T10:05:33+00:00",
      "agent": [
        {
          "role": [
            {
              "coding": [
                {
                  "system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1",
                  "code": "R0260",
                  "display": "General Medical Practitioner"
                }
              ]
            }
          ],
          "whoReference": {
            "reference": "https://sds.spineservices.nhs.uk/STU3/Practitioner/2ee4tr6a9",
            "display": "Dr.D"
          },
          "onBehalfOfReference": {
            "reference": "https://directory.spineservices.nhs.uk/STU3/Organization/a3e5i7",
            "display": "Some GP Clinic"
          }
        }
      ]
    }
  ],
  "extension": [
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-Provenance-1",
      "extension": [
        {
          "url": "created",
          "valueReference": {
            "reference": "#de615f06-41d7-4659-b543-b401ece571cb"
          }
        },
        {
          "url": "updated",
          "valueReference": {
            "reference": "#916be0f8-be88-4d12-b3a9-4077ed05292e"
          }
        }
      ]
    },
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-RemovalReason-1",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-RemovalReason-1",
            "code": "Error",
            "display": "The Reasonable Adjustment Flag was created in error"
          }
        ]
      }
    },
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-RARecord-AdjustmentCategory-1",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-AdjustmentCategories-1",
            "code": "comms",
            "display": "Communication"
          }
        ]
      }
    }
  ],
  "status": "inactive",
  "category": {
    "coding": [
      {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-FlagCategory-1",
        "code": "reasonable adjustments flag",
        "display": "Reasonable Adjustments Flag"
      }
    ]
  },
  "code": {
    "coding": [
      {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/CodeSystem-RARecord-AccessibleInformationAdjustments-1",
        "code": "requiresinformationineasyread",
        "display": "Requires information in Easyread"
      }
    ]
  },
  "subject": {
    "identifier": {
      "system": "https://fhir.nhs.uk/Id/nhs-number",
      "value": "999999998"
    }
  }
}

headers

Client systems SHALL carry the security HTTP headers as defined on the Security page.

Tags:

API Hub

Explore and Make use of Nationally Defined Messaging APIs

Interaction | Update

1 Update RA Record Use Case

1.1 Trigger:

1.2 Pre-requisites:

1.3 System Scope:

1.4 Summary:

Pre

Main

2 Update RA Record Examples

2.1 Update Flag Request

http request

body

RARecord-UpdateFlagRequestBody-example XML Example

RARecord-UpdateFlagRequestBody-example JSON Example

headers

2.2 Update Flag Response

http response

body

RARecord-UpdateFlagResponseBody-example XML Example

RARecord-UpdateFlagResponseBody-example JSON Example

headers