Migrate a document

Important: This migrate a patient’s document interaction MAY be implemented by existing suppliers on the GP IT Futures framework and it MUST be implemented by New Market Entrants.

Use case

Retrieve a document for the purpose of migrating it to a patient’s new registered practice.

Security

GP Connect utilises TLS Mutual Authentication for system level authorization
GP Connect utilises JSON Web Tokens (JWT) to transmit clinical audit and provenance details

Prerequisites

Consumer

The consumer system:

SHALL have previously resolved the organisation’s Access Document FHIR endpoint base URL through the Spine Directory Service
MUST have previously traced the patient’s NHS Number using the Personal Demographics Service or an equivalent service
MUST have used the Migrate a patient’s structured record to retrieve a list of the patient’s documents

API usage

Interaction diagram

Retrieve a document interaction diagram

Request

FHIR® relative request

GET /Binary/[id]

FHIR® absolute request

GET https://[proxy_server]/https://[documents_provider_server]/[documents_fhir_base]/Binary/[id]

Availability of data

The record migration use case requires that information is always available regardless of whether the documents capability has been enabled, or whether clinical areas have been turned off using configuration for clinical areas.

Confidential and sensitive documents

This interaction allows confidential and sensitive documents to be retrieved. This interaction can only be used if an appropriate requested_scope value is provided in the JWT, more guidance is available in the Cross-organisation audit and provenance page

File size limit

There is no limit on the size of files able to be retrieved through this API. Files may exceed 100MB and in rare circumstances they maybe closer to 250MB. However, due to there being no imposed limit they may be larger than this.

Request headers

Consumers MUST include the following additional HTTP request headers:

Header	Value
`Ssp-TraceID`	Consumer’s Trace ID (a GUID or UUID)
`Ssp-From`	Consumer’s ASID
`Ssp-To`	Provider’s ASID
`Ssp-InteractionID`	`urn:nhs:names:services:gpconnect:documents:fhir:rest:migrate:binary-1`

Example HTTP request headers:

Accept: application/fhir+json;charset=utf-8
Content-Type: application/fhir+json;charset=utf-8
Ssp-TraceID: 629ea9ba-a077-4d99-b289-7a9b19fd4e03
Ssp-From: 200000000115
Ssp-To: 200000000116
Ssp-InteractionID: urn:nhs:names:services:gpconnect:documents:fhir:rest:migrate:binary-1

Payload request body

N/A

Error handling

The provider system MUST return a GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data field is corrupt or a specific business rule/constraint is breached.

The table below shown common errors that may be encountered during this API call, and the returned Spine error code. Please see Error handling guidance for additional information needed to create the error response or to determine the response for errors encountered that are not shown below.

Errors returned due to query parameter failure MUST include diagnostic information detailing the invalid query parameter.

Error encountered	Spine error code returned
A document could not be found with the document id provided	`NO_RECORD_FOUND`
The document could not be retrieved due to it exceeding the file size limit	`NO_RECORD_FOUND`
GP Connect is not enabled at the practice (see Enablement)	`ACCESS DENIED`
The Access Document capability is not enabled at the practice (see Enablement)	`ACCESS DENIED`
An unauthorised request has been made for sensitive information	`NOT_AUTHORISED`
The ODS code in the JWT doesn’t match the ODS code for the patient’s registered practice on PDS	`NOT_AUTHORISED`
The JWT `requested_scope` is set to `conf/N` when a request has been made for sensitive information	`NOT_AUTHORISED`

Request response

Response headers

Provider systems are not expected to add any specific headers beyond that described in the HTTP and FHIR® standards.

Payload response body

Provider systems MUST:

return a 200 OK HTTP status code to indicate successful execution of the operation
return a Binary resource conforming to the Binary resource definition
include the versionId of the current version of the Binary resource

Payload response examples

Examples of the payload requests and responses can be found here:

Documents - FHIR® examples