References
NHS Digital Profile: DocumentReference |
HL7 FHIR STU3 Resource: DocumentReference |
User Stories: - |
Create
API to support the creation of NRLS pointers. This functionality is only available for providers.
Create Request Headers
Provider API create requests support the following HTTP request headers:
Header | Value | Conformance |
---|---|---|
Accept |
The Accept header indicates the format of the response the client is able to understand, this will be one of the following application/fhir+json or application/fhir+xml . See the RESTful API Content types section. |
MAY |
Authorization |
The Authorization header will carry the base64url encoded JSON web token required for audit on the spine - see Access Tokens and Audit (JWT) for details. |
MUST |
fromASID |
Client System ASID | MUST |
toASID |
The Spine ASID | MUST |
Create Operation
Provider system will construct a new Pointer (DocumentReference) and submit this to NRLS using the FHIR RESTful create interaction.
Providers systems SHALL only create pointers for records where they are the pointer owner (custodian).
For all create requests the custodian
ODS code in the DocumentReference resource SHALL be affiliated with the Client System ASID
value in the fromASID
HTTP request header sent to the NRLS.
In addition to the base mandatory data-elements, the following data-elements are also mandatory:
- The
type
data-element MUST be included in the payload request.
XML Example of a new DocumentReference resource (pointer)
JSON Example of a new DocumentReference resource (pointer)
Create Response
Success:
- SHALL return a
201
CREATED HTTP status code on successful execution of the interaction and the entry has been successfully created in the NRLS. - SHALL return a response body containing a payload with an
OperationOutcome
resource that conforms to the ‘Operation Outcome’ core FHIR resource. See table below. - SHALL return an HTTP
Location
response header containing the full resolvable URL to the newly created ‘single’ DocumentReference.- The URL will contain the ‘server’ assigned
logical Id
of the new DocumentReference resource. - The URL format MUST be:
https://[host]/[path]?_id=[id]
. - An example
Location
response header:https://psis-sync.national.ncrs.nhs.uk/DocumentReference?_id=297c3492-3b78-11e8-b333-6c3be5a609f5-54477876544511209789
- The URL will contain the ‘server’ assigned
- When a resource has been created it will have a
versionId
of 1.
The NRLS server will ignore any versionId value sent by a client in a create interaction. Instead the server will ensure that the newly assigned verionId adheres to the rules laid out above.
The table summarises the create
interaction HTTP response code and the values expected to be conveyed in the successful response body OperationOutcome
payload:
HTTP Code | issue-severity | issue-type | Details.Code | Details.Display | Details.Text | Diagnostics |
---|---|---|---|---|---|---|
201 | information | informational | RESOURCE_CREATED | New resource created | Spine message UUID | Successfully created resource DocumentReference |
Failure:
The following errors can be triggered when performing this operation:
- Invalid Request Message
- Invalid Resource
- Organisation not found
- Invalid NHS Number
- Invalid Parameter
- Duplicate Resource
Ensuring that masterIdentifier is unique
The masterIdentifier should be unique within the NRLS. For more information see the discussion on Pointer identifiers. The masterIdentifer is a FHIR identifier and for NRLS the system and value properties are mandatory.
The system defines how the value is made unique. As the FHIR specification says this might be a recognised standard that describes how this uniqueness is generated.
The NRLS recommends the use of either an OID or a UUID as an Identifier in keeping with the need for the masterIdentifier value to be unique. In this case then the system SHALL be “urn:ietf:rfc:3986” (see the FHIR identifier registry for details) and the value is of the form –
• OID - urn:oid:[oidValue]
• UUID - urn:uuid:[uuidValue]
See the example OID and UUID based Identifiers from the FHIR specification.
Code Examples
POST a Pointer with C#
The following code samples are taken from the NRLS Demonstrator application which has both Consumer and Provider client implementations built in. More information about the design solution can be found on the NRLS Demonstrator Wiki
First we generate a base pointer request model that includes the custodian and author details, and the specific care plan attachment details that are later used to build our pointer (DocumentReference). These pointer values are taken from the demo crisis plan that is created for the Demonstrator Provider system.
Then we call our DocumentReference service GenerateAndCreatePointer method which will generate our pointer (DocumentReference) using the values stored in the model, build a POST command request and then start the call to the NRLS API.
Within the DocumentReference service GenerateAndCreatePointer method we generate our pointer model and then serialise this generated model ready for posting:
Calling the NRLS
Using our POST command request model we create a connection to the NRLS using HttpClient.
You can view the common connection code example here.
Explore the NRLS
You can explore and test the NRLS POST command using Swagger in our Reference implementation.
The official .NET FHIR Library is utilised to construct, test, parse and serialize FHIR models with ease.