Pre-requisites

In addition to the guidance on this page the guidance and requirement on the Generic Subscription API Requirements page SHALL be followed when using the NEMS subscription API.

Creating a Subscription

To create a subscription, a client MUST:

1. construct a Subscription resource conforming to the EMS-Subscription-1 FHIR profile and additional population guidance on this page
2. POST the constructed EMS-Subscription-1 resource to the NEMS FHIR endpoint on the Spine

POST /Subscription

Important: Currently the National Events Management Service (NEMS) supports JSON and XML formats for interactions with the subscription API, but currently all event messages will be forwarded to subscribers in an XML format.

Request Headers

The subscribing organisation MUST include the following HTTP request headers when making the call to the Create Subscription API endpoint:

Header	Description
fromASID	ASID of the system posting to the Subscription API
toASID	ASID of the NEMS service
InteractionID	Fixed value: urn:nhs:names:services:clinicals-sync:SubscriptionsApiPost

Additional information about standard headers and endpoint looking is available in the Spine Core specification.

EMS-Subscription-1 resource population

FHIR element	Cardinality	Requirement
status	1..1	The status of the subscription (initially this will always be “requested” until the subscription is reviewed and activated
contact	1..*	Contact details for the subscription. The first instance of the contact element within the Subscription resource SHALL represent the organization requesting the subscription. The element SHALL contain the organisation ODS Code which matches the MESH mailbox ID specified in the channel.endpoint element. The elements within the first contact element should be as follows: “use” must have a fixed value of “work“ “system” must have fixed value of “url“ “value” must have the URL to the organization accessable via the ODS API, for example: “https://directory.spineservices.nhs.uk/STU3/Organization/[Org_ODS_Code] “ Additional contact elements included within the Subscription resource will be stored and returned by when managing the subscriptions but will not be validated as part of the business rules.
end	0..1	End date/time for subscription if relevant (e.g. for a temporary subscription). If not provided the subscription will be perpertual and not expire.
reason	1..1	The reason for creating the subscription (human readable description). Used primarily for reviewing the subscription in order to make it active, and also for patients / services to review what subscriptions exist and why they were created.
criteria	1..1	Criteria to match events against for this subscription - see below for examples. NOTE: Currently, the criteria cannot be used for searching.
channel.type	1..1	The delivery channel to use to deliver the event to the subscriber (currently only “message” is supported). NOTE: In this case “message” refers to the use of MESH for as a delivery channel.
channel.endpoint	1..1	The specific endpoint (initially MESH mailbox ID) to deliver to. NOTE: The ODS code associated with the mailbox MUST match the ODS code within the first instance of the contact element of the Subscription resource.

Once submitted, additional metadata will automatically be added to the Subscription resource by the NEMS:

FHIR element	Cardinality	Requirement
id	1..1	Identifier for the subscription
meta.lastUpdated	0..1	Date the subscription was last updated
meta.versionId	0..1	The ID for the specific version of the subscription

The create request MUST NOT include the fields above, as they can only be added by the NEMS (see Create Example below).

Once the subscription has been created it may require IG review prior to becoming active, at which point the status of the Subscription resource will be changed by the NEMS to ‘active’.

Criteria Components

The criteria element of the Subscription will use the FHIR search string format using the following components:

Component	Cardinality	Description
/Bundle?type=message	1..1	This identifies that we are interested in events (which are sent as Bundles in FHIR), of type “message”
serviceType=[CODE]	0..1	This element identifies the service type making the subscription. Current accepted values are: GP - GP Practice related services CHO - Child Health Organisation related services UHV - Health Visitor related services EPCHR - Electronic Personal Child Health Record services
Patient.identifier=[IDENTIFIER]	1..1	This is used for Explicit Subscriptions for an individual patient. The [IDENTIFIER] is the NHS Number for the patient. For example: “&Patient.identifier=http://fhir.nhs.net/Id/nhs-number|[NHS Number]”
MessageHeader.event=[CODE]	1..*	This is the type of event to subscribe to (see the EMS Event Types). For example: “&MessageHeader.event=PDS001&MessageHeader.event=PDS002&MessageHeader.event=PDS003” is an expression to specify events where the MessageHeader.event is of type PDS001, PDS002 or PDS003
Patient.age=[AGE]	0..2	This is a filter to only match events where the age of the patient meets the criteria supplied. Examples: - “&Patient.age=lt14“ - “&Patient.age=gt60“ - “&Patient.age=gt5&Patient.age=lt19” For more detail see the Search Parameter EMS Patient Age

Criteria Examples

Scenario	Subscribing Organisation	Subscription Type	Criteria String
A PHR system subscribing to change of address events for a specific patient registered for a PHR	N/A	Explicit	/Bundle?type=message<br/>&amp;serviceType=GP<br/>&amp;Patient.identifier=http://fhir.nhs.net/Id/nhs-number|9434765919<br/>&amp;MessageHeader.event=PDS002

Error Handling

If an error occurs when the NEMS processes the subscription request, a HTTP error status code will be returned along with an OperationOutcome FHIR resource within the payload. The OperationOutcome resource will contain one of the Spine ErrorOrWarning Codes and conform to the structure set out in the Spine Core FHIR specification.

Response

When a subscription request is successfully received by the NEMS, the Subscription will be assigned a logical ID and the NEMS will return:

• a HTTP status code of 201 Created
• a Location header containing the new logical ID of the created Subscription resource

No payload will be returned with the successful response.

Create Subscription Example

HTTP request:

POST https://clinicals.spineservices.nhs.uk/STU3/Subscription HTTP/1.1

<Subscription xmlns="http://hl7.org/fhir">
	<meta>
		<profile value="https://fhir.nhs.uk/STU3/StructureDefinition/EMS-Subscription-1"/>
	</meta>
	<status value="requested"/>
	<contact>
		<system value="url"/>
		<value value="https://directory.spineservices.nhs.uk/STU3/Organization/RR8"/>
		<use value="work"/>
	</contact>
	<reason value="Health visiting service responsible for Leeds"/>
	<criteria value="/Bundle?type=message&amp;serviceType=UHV&amp;Patient.identifier=http://fhir.nhs.net/Id/nhs-number|9434765919&amp;MessageHeader.event=PDS002" />
	<channel>
		<type value="message"/>
		<endpoint value="Mailbox1234"/>
	</channel>
</Subscription>

HTTP 201 Created
Date: Fri, 25 May 2018 16:09:50 GMT
Last-Modified: Fri, 25 May 2018 16:09:50 GMT
ETag: W/"25777f7d-27bc"
Location: https://clinicals.spineservices.nhs.uk/STU3/Subscription/ea0a485187204b49b978bdcf7102388c

Tags: fhir