NHS England FHIR Implementation Guide (deprecated)

Important Announcement regarding this Implementation Guide
  • As of 04/10/2023, this implementation guide has been deprecated and all development on the legacy NHS England FHIR Implementation Guide assets has ceased.
  • Therefore, vendors looking to start new implementations or looking to update existing implementations should use the new NHS England Implementation Guide. Vendors continuing to implement legacy NHS England FHIR Implementation Guide based solutions do so at their own risk and on the understanding that no maintenance or support will be available.

Design

Design specifications and requirements for Spine FHIR APIs including:

Spine Directory Services (SDS)

Device and Endpoint endpoints providing Search interactions enabling:

  • Look up a provider’s endpoint and ASID
  • Look up a consumer’s own ASID

Design overview

The SDS API design will follow the guiding design principle that the API seeks to hide legacy complexity where possible.

The SDS API will fully hide the consumer from details of the ldap query used to convey SDS information to and from Spine.

Device Data Mapping

This table specifies the mapping from data requirements, Accredited System record, to FHIR targets within the SDS-Device resource

Data Item LDAP Attribute Cardinality FHIR Target Notes
Accredited System Identifier uniqueIdentifier 1 Device.identifier:NhsSpineASID
Managing Organisation Code nhsIdCode 1 Device.extension:managingOrganisation (for GP System supplier)
Client Code nhsAsClient 0..* Device.owner (for GP System i.e. GP Practice) List of Organisation or Site codes, or Organisational Work Groups which use this Accredited System. Though the cardinality is set to 0..*, EPR application ensures there is 1 value in this attribute.
Party Key nhsMhsPartyKey 1 Device.identifier:NhsMhsPartyKey
Service-Interactions nhsAsSvcIA 1..* Device.identifier:NhsEndpointServiceId
ACF Characteristics nhsAsACF 0..* not mapped - not returned
Description description 0..1 not mapped - not returned
Category Bag nhsAsCategoryBag 0..* not mapped - not returned
Product nhsProductKey 1 not mapped - not returned
Requestor’s Identity nhsRequestorURP 1 not mapped - not returned
Date Requested nhsDateRequested 1 not mapped - not returned
Approver’s Identity nhsApproverURP 1 not mapped - not returned
Date Approved nhsDateApproved 1 not mapped - not returned

not mapped - not returned - these data items in the AccreditedSystem record are not returned by the Device endpoint and so are not mapped to a FHIR Target

Device Search Interactions

The SCR API SHALL support a search interaction to return Device resources using search parameters for:

  • [Mandatory] Organisation code - ODS code of the target organisation (i.e. GP practice operating the software instance)
  • [Mandatory] MHS Interaction ID - type of Interaction supported by software instance
  • [Optional ] Manufacturer's organisation code - ODS code of the manufacturer's organisation (i.e. GP System supplier)
  • [Optional ] Party Key - identifier representing the target organisation and service interaction

Device resources are returned as a searchset Bundle containing 0, 1 or many matching Endpoint resources

SearchParameter-SDS-ManagingOrganisation has been defined to specify search on the managingOrganisation extension

The Device Search Interaction supports GP Connect use cases by allowing a consumer system to retrieve the Accredited System (AS) record for a capability at a target GP provider organisation OR at their own organisation

Search Parameter

Data Item Query Parameter Query Target Example
Organisation code organization Device.owner organization=[GPSystemODSCode]
MHS Interaction ID identifier Device.identifier:NhsEndpointServiceId identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|[interactionId]
Manufacturer organisation code managing-organisation Device.extension:Extension-SDS-ManagingOrganisation managing-organisation=[supplierODSCode]
Party Key identifier Device.identifier:NhsMhsPartyKey identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|[partyKey]

Request pattern

GET [baseURL]/Device?
  organization=[ODSNamingSystem]|[GPSystemODSCode]&
  identifier=[EndpointServiceIdNamingSystem]|[interactionId]&
  managing-organisation=[ODSNamingSystem]|[supplierODSCode]&
  identifier=[PartyKeyNamingSystem]|[partyKey]

Example request

GET [baseURL]/Device?
  organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&
  identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05&
  managing-organisation=https://fhir.nhs.uk/Id/ods-organization-code|T10101&
  identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|R8008-0000806

Example response payload

<Bundle xmlns="http://hl7.org/fhir">
    <id value="6cf80168-a1ef-49a2-bb92-e870c8e11e3c" />
    <type value="searchset" />
    <total value="1" />
    <link>
        <relation value="self" />
        <url value="[baseURL]/Device?organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&amp;identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05&amp;managing-organisation=https://fhir.nhs.uk/Id/ods-organization-code|T10101&amp;identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|R8008-0000806" />
    </link>
    <entry>
        <fullUrl value="[baseURL]/Device/ef4a9244-cec1-474a-8694-775dd385d2cc" />
        <resource>
            <Device>
                <id value="ef4a9244-cec1-474a-8694-775dd385d2cc" />
                <extension url="https://fhir.nhs.uk/StructureDefinition/Extension-SDS-ManagingOrganisation">
                    <valueReference>
                        <identifier>
                            <system value="https://fhir.nhs.uk/Id/ods-organization-code" />
                            <value value="T10101" />
                        </identifier>
                        <display value="Some GP System provider" />
                    </valueReference>
                </extension>
                <identifier>
                    <system value="https://fhir.nhs.uk/Id/nhsSpineASID" />
                    <value value="227319907548" />
                </identifier>
                <identifier>
                    <system value="https://fhir.nhs.uk/Id/nhsMhsPartyKey" />
                    <value value="R8008-0000806" />
                </identifier>
                <identifier>
                    <system value="https://fhir.nhs.uk/Id/nhsEndpointServiceId" />
                    <value value="urn:nhs:names:services:psis:REPC_IN150016UK05" />
                </identifier>
                <owner>
                    <identifier>
                        <system value="https://fhir.nhs.uk/Id/ods-organization-code" />
                        <value value="R8008" />
                    </identifier>
                    <display value="Some GP Practice" />
                </owner>
            </Device>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
</Bundle>

{
    "resourceType": "Bundle",
    "id": "6cf80168-a1ef-49a2-bb92-e870c8e11e3c",
    "type": "searchset",
    "total": 1,
    "link":  [
        {
            "relation": "self",
            "url": "[baseURL]/Device?organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05&managing-organisation=https://fhir.nhs.uk/Id/ods-organization-code|T10101&identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|R8008-0000806"
        }
    ],
    "entry":  [
        {
            "fullUrl": "[baseURL]/Device/ef4a9244-cec1-474a-8694-775dd385d2cc",
            "resource": {
                "resourceType": "Device",
                "id": "ef4a9244-cec1-474a-8694-775dd385d2cc",
                "extension":  [
                    {
                        "url": "https://fhir.nhs.uk/StructureDefinition/Extension-SDS-ManagingOrganisation",
                        "valueReference": {
                            "identifier": {
                                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                                "value": "T10101"
                            },
                            "display": "Some GP System provider"
                        }
                    }
                ],
                "identifier":  [
                    {
                        "system": "https://fhir.nhs.uk/Id/nhsSpineASID",
                        "value": "227319907548"
                    },
                    {
                        "system": "https://fhir.nhs.uk/Id/nhsMhsPartyKey",
                        "value": "R8008-0000806"
                    },
                    {
                        "system": "https://fhir.nhs.uk/Id/nhsEndpointServiceId",
                        "value": "urn:nhs:names:services:psis:REPC_IN150016UK05"
                    }
                ],
                "owner": {
                    "identifier": {
                        "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                        "value": "R8008"
                    },
                    "display": "Some GP Practice"
                }
            },
            "search": {
                "mode": "match"
            }
        }
    ]
}

Endpoint Data Mapping

This table specifies the mapping from data requirements, Message Handling System (MHS) record, to FHIR targets within the SDS-Endpoint resource

Data Item LDAP Attribute Cardinality FHIR Target
Organisation Code nhsIdCode 1 Endpoint.managingOrganization
Service-Interaction nhsMhsSvcIA 1 Endpoint.identifier:NhsEndpointServiceId
FQDN of MHS nhsMHSFQDN 1 Endpoint.identifier:NhsMhsFQDN
End Point nhsMhsEndPoint 1 Endpoint.address
Party Key nhsMhsPartyKey 1 Endpoint.identifier:NhsMhsPartyKey
CPA Identifier nhsMhsCPAId 1 Endpoint.identifier:NhsMhsCPAId
MHS Identifier uniqueIdentifier 1 Endpoint.identifier:NhsSpineASID
Sync Reply Mode nhsMhsSyncReplyMode 0..1 Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSSyncReplyMode
Retry Interval nhsMhsRetryInterval 0..1 Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSRetryInterval
Retries nhsMhsRetries 0..1 Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSRetries
Persist duration nhsMhsPersistduration 0..1 Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSPersistDuration
Duplicate Elimination nhsMhsDuplicateElimination 0..1 Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSDuplicateElimination
Ack Requested nhsMhsAckRequested 0..1 Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSAckRequested
Actor nhsMhsActor 0..1 Endpoint.extension:ExtensionSDSReliabilityConfiguration.extension:nhsMHSActor

Endpoint Search Interactions

The SCR API SHALL support a search interaction to return Endpoint resources using search parameters for:

  • [Mandatory] Organisation code - ODS code of the target organisation (i.e. GP practice exposing the endpoint)
  • [Mandatory] MHS Interaction ID - type of Interaction supported by Endpoint

Endpoint resources are returned as a searchset Bundle containing 0, 1 or many matching Endpoint resources

The Endpoint Search Interaction supports GP Connect use cases by allowing a consumer system to retrieve the Message Handling System (MHS) record for a capability at a target GP provider organisation

Search Parameter

Data Item Query Parameter Query Target Example
Organisation code organization managingOrganization organization=[targetODSCode]
MHS Interaction ID identifier Endpoint.identifier:NhsEndpointServiceId identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|[interactionId]

Request pattern

GET [baseURL]/Endpoint?
  organization=[ODSNamingSystem]|[targetODSCode]&
  identifier=[EndpointServiceIdNamingSystem]|[interactionId]

Example request

GET [baseURL]/Endpoint?
  organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&
  identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05

Example response payload

<Bundle xmlns="http://hl7.org/fhir">
    <id value="bbea6247-6d81-4d92-b2c0-8779aacdb838" />
    <type value="searchset" />
    <total value="1" />
    <link>
        <relation value="self" />
        <url value="[baseURL]/Endpoint?organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&amp;identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05" />
    </link>
    <entry>
        <fullUrl value="[baseURL]/Endpoint/f1dc0ac6-45ff-4d2b-bf91-793971e3e286" />
        <resource>
            <Endpoint>
                <id value="f1dc0ac6-45ff-4d2b-bf91-793971e3e286" />
                <extension url="https://fhir.nhs.uk/StructureDefinition/Extension-SDS-ReliabilityConfiguration">
                    <extension url="nhsMHSSyncReplyMode">
                        <valueString value="MSHSignalsOnly" />
                    </extension>
                    <extension url="nhsMHSRetryInterval">
                        <valueString value="PT1M" />
                    </extension>
                    <extension url="nhsMHSRetries">
                        <valueInteger value="2" />
                    </extension>
                    <extension url="nhsMHSPersistDuration">
                        <valueString value="PT5M" />
                    </extension>
                    <extension url="nhsMHSDuplicateElimination">
                        <valueString value="always" />
                    </extension>
                    <extension url="nhsMHSAckRequested">
                        <valueString value="always" />
                    </extension>
                    <extension url="nhsMHSActor">
                        <valueString value="ebs" />
                    </extension>
                </extension>
                <identifier>
                    <system value="https://fhir.nhs.uk/Id/nhsEndpointServiceId" />
                    <value value="urn:nhs:names:services:psis:REPC_IN150016UK05" />
                </identifier>
                <identifier>
                    <system value="https://fhir.nhs.uk/Id/nhsMhsFQDN" />
                    <value value="192.168.128.11" />
                </identifier>
                <identifier>
                    <system value="https://fhir.nhs.uk/Id/nhsMhsEndPoint" />
                    <value value="https://192.168.128.11/reliablemessaging/reliablerequest" />
                </identifier>
                <identifier>
                    <system value="https://fhir.nhs.uk/Id/nhsMhsPartyKey" />
                    <value value="R8008-0000806" />
                </identifier>
                <identifier>
                    <system value="https://fhir.nhs.uk/Id/nhsMhsCPAId" />
                    <value value="S20001A000182" />
                </identifier>
                <identifier>
                    <system value="https://fhir.nhs.uk/Id/nhsSpineASID" />
                    <value value="227319907548" />
                </identifier>
                <status value="active" />
                <connectionType>
                    <system value="http://terminology.hl7.org/CodeSystem/endpoint-connection-type" />
                    <code value="hl7-fhir-msg" />
                    <display value="HL7 FHIR Messaging" />
                </connectionType>
                <managingOrganization>
                    <identifier>
                        <system value="https://fhir.nhs.uk/Id/ods-organization-code" />
                        <value value="R8008" />
                    </identifier>
                </managingOrganization>
                <payloadType>
                    <coding>
                        <system value="http://terminology.hl7.org/CodeSystem/endpoint-payload-type" />
                        <code value="any" />
                        <display value="Any" />
                    </coding>
                </payloadType>
                <address value="https://192.168.128.11/" />
            </Endpoint>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
</Bundle>

{
    "resourceType": "Bundle",
    "id": "bbea6247-6d81-4d92-b2c0-8779aacdb838",
    "type": "searchset",
    "total": 1,
    "link":  [
        {
            "relation": "self",
            "url": "[baseURL]/Endpoint?organization=https://fhir.nhs.uk/Id/ods-organization-code|R8008&identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05"
        }
    ],
    "entry":  [
        {
            "fullUrl": "[baseURL]/Endpoint/f1dc0ac6-45ff-4d2b-bf91-793971e3e286",
            "resource": {
                "resourceType": "Endpoint",
                "id": "f1dc0ac6-45ff-4d2b-bf91-793971e3e286",
                "extension":  [
                    {
                        "extension":  [
                            {
                                "url": "nhsMHSSyncReplyMode",
                                "valueString": "MSHSignalsOnly"
                            },
                            {
                                "url": "nhsMHSRetryInterval",
                                "valueString": "PT1M"
                            },
                            {
                                "url": "nhsMHSRetries",
                                "valueInteger": 2
                            },
                            {
                                "url": "nhsMHSPersistDuration",
                                "valueString": "PT5M"
                            },
                            {
                                "url": "nhsMHSDuplicateElimination",
                                "valueString": "always"
                            },
                            {
                                "url": "nhsMHSAckRequested",
                                "valueString": "always"
                            },
                            {
                                "url": "nhsMHSActor",
                                "valueString": "ebs"
                            }
                        ],
                        "url": "https://fhir.nhs.uk/StructureDefinition/Extension-SDS-ReliabilityConfiguration"
                    }
                ],
                "identifier":  [
                    {
                        "system": "https://fhir.nhs.uk/Id/nhsEndpointServiceId",
                        "value": "urn:nhs:names:services:psis:REPC_IN150016UK05"
                    },
                    {
                        "system": "https://fhir.nhs.uk/Id/nhsMhsFQDN",
                        "value": "192.168.128.11"
                    },
                    {
                        "system": "https://fhir.nhs.uk/Id/nhsMhsEndPoint",
                        "value": "https://192.168.128.11/reliablemessaging/reliablerequest"
                    },
                    {
                        "system": "https://fhir.nhs.uk/Id/nhsMhsPartyKey",
                        "value": "R8008-0000806"
                    },
                    {
                        "system": "https://fhir.nhs.uk/Id/nhsMhsCPAId",
                        "value": "S20001A000182"
                    },
                    {
                        "system": "https://fhir.nhs.uk/Id/nhsSpineASID",
                        "value": "227319907548"
                    }
                ],
                "status": "active",
                "connectionType": {
                    "system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
                    "code": "hl7-fhir-msg",
                    "display": "HL7 FHIR Messaging"
                },
                "managingOrganization": {
                    "identifier": {
                        "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                        "value": "R8008"
                    }
                },
                "payloadType":  [
                    {
                        "coding":  [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/endpoint-payload-type",
                                "code": "any",
                                "display": "Any"
                            }
                        ]
                    }
                ],
                "address": "https://192.168.128.11/"
            },
            "search": {
                "mode": "match"
            }
        }
    ]
}

Modules

back to top