Use case
This specification describes a single use case. For complete details and background please see the Access Record Capability Bundle.
Security
- GP Connect utilises TLS Mutual Authentication for system level authorization
- GP Connect utilises a JSON Web Tokens (JWT) to transmit clinical audit & provenance details
Prerequisites
Consumer
The consumer system:
- MUST have previously resolved the organisation’s 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 render HTML content in-line with the HTML Implementation Guidance
API usage
Request operation
FHIR relative request
POST /Patient/$gpc.getcarerecord
FHIR absolute request
POST https://[proxy_server]/https://[provider_server]/[fhir_base]/Patient/$gpc.getcarerecord
Request headers
Consumers MUST include the following additional HTTP request headers:
Header | Value |
---|---|
Ssp-TraceID |
Consumer’s TraceID (i.e. GUID/UUID) |
Ssp-From |
Consumer’s ASID |
Ssp-To |
Provider’s ASID |
Ssp-InteractionID |
urn:nhs:names:services:gpconnect:fhir:operation:gpc.getcarerecord |
Example HTTP request headers:
POST http://gpconnect.fhir.nhs.net/fhir/Patient/$gpc.getcarerecord HTTP/1.1
User-Agent: .NET FhirClient for FHIR 1.2.0
Accept: application/json+fhir
Prefer: return=representation
Host: michaelm-pc
Content-Type: application/json+fhir
Content-Length: 289
Expect: 100-continue
Connection: Keep-Alive
Ssp-TraceID: 629ea9ba-a077-4d99-b289-7a9b19fd4e03
Ssp-From: 200000000115
Ssp-To: 200000000116
Ssp-InteractionID: urn:nhs:names:services:gpconnect:fhir:operation:gpc.getcarerecord
Payload request body
The following data-elements are mandatory (meaning, data MUST be present):
- the
patientNHSNumber
is the NHS Number of the patient whose GP care record you want to access - the
recordSection
is the GP care record section you wish to retrieve
The following data-elements are optional (meaning, MAY be supplied for certain care record sections):
- the
timePeriod
is the time period over which the requested information is to be returned
The request payload is a set of Parameters conforming to the gpconnect-carerecord-operation-1
profiled OperationDefinition
, see below:
<OperationDefinition xmlns="http://hl7.org/fhir">
<id value="getcarerecord" />
<version value="0.7.2" />
<name value="Get Care Record" />
<status value="draft" />
<kind value="operation" />
<experimental value="true" />
<publisher value="NHS Digital" />
<date value="2016-08-01" />
<description value="Get The GP Care Record Section For A Given Patient." />
<idempotent value="true" />
<code value="gpc.getcarerecord" />
<system value="false" />
<type value="Patient" />
<instance value="false" />
<parameter>
<name value="patientNHSNumber" />
<use value="in" />
<min value="1" />
<max value="1" />
<documentation value="Patient that matches the NHS Number." />
<type value="Identifier" />
</parameter>
<parameter>
<name value="recordSection" />
<use value="in" />
<min value="1" />
<max value="1" />
<documentation value="Section of the care record defined by the parameter." />
<type value="CodeableConcept" />
</parameter>
<parameter>
<name value="timePeriod" />
<use value="in" />
<min value="0" />
<max value="1" />
<documentation value="The time period for the requested information." />
<type value="Period" />
</parameter>
<parameter>
<name value="response" />
<use value="out" />
<min value="1" />
<max value="1" />
<documentation value="View of the patient's care record which can be a summary view or specified section of the care record." />
<type value="Bundle" />
</parameter>
</OperationDefinition>
Patient
resources for patients who have a valid PDS trace status.On the wire a JSON serialised $gpc.getcarerecord
request would look something like the following:
{
"resourceType": "Parameters",
"parameter": [{
"name": "patientNHSNumber",
"valueIdentifier": {
"system": "http://fhir.nhs.net/Id/nhs-number",
"value": "9480489457"
}
},
{
"name": "recordSection",
"valueCodeableConcept": {
"coding": [{
"system": "http://fhir.nhs.net/ValueSet/gpconnect-record-section-1",
"code": "ALL"
}]
}
}]
}
The provider system MUST:
- use a default time period if no
timePeriod
parameter is specified for a section that can accept a time period
Refer to HTML Implementation Guidance - Per Section Default Time Frames for details of the default time periods that MUST be applied per care record section.
Error handling
The provider system MUST return an error if:
- the
patientNHSNumber
is invalid (meaning, fails NHS Number format and check digit tests) - the
patientNHSNumber
is not associated with aNHS Number Status Indicator Code
ofNumber present and verified
- the GP organisation is not the patient’s nominated primary care provider
- the
recordSection
is invalid (meaning, isn’t from the correct value set) - an invalid
timePeriod
is requested (i.e. end date > start date) - a
timePeriod
is specified for arecordSection
that is time period agnostic (for example, Patient Summary, Allergies etc.) - the patient is recorded as deceased and the request is received after the allowed access period post patient’s death. In this case, the error code “PATIENT_NOT_FOUND” should be returned.
Provider systems MUST return an OperationOutcome resource that provides additional detail when one or more data fields are corrupt or a specific business rule/constraint is breached.
Refer to Development Guidance - Error Handling for details of error codes.
Request response
Response headers
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json+fhir
Date: Sun, 07 Aug 2016 11:13:05 GMT
Content-Length: 1464
Payload response body
Provider systems:
- MUST return a
200
OK HTTP status code on successful retrieval of a care record section - MUST return the care record section as valid XHTML in line with the FHIR Narrative guidance
- MUST include the relevant GP Connect
StructureDefinition
profile details in themeta
fields of the returned response - MUST include the
Patient
,Practitioner
andOrganization
details for the retrieved care record in a searchsetBundle
- MUST include patient’s date of death in Patient.deceased[x](deceasedDateTime) where it is recorded in the provider system
{
"resourceType": "Bundle",
"id": "48b4dc58-9c04-470d-a819-16fbb433daf9",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "Composition",
"id": "77bf75df-3853-4b47-ab53-5edce53f8ee6",
"meta": {
"profile": [
"http://fhir.nhs.net/StructureDefinition/gpconnect-carerecord-composition-1"
]
},
"date": "2017-02-24T13:51:00+00:00",
"title": "Patient Care Record",
"status": "final",
"subject": {
"reference": "Patient/7302348e-e090-4c5d-99e9-14147c266ebe"
},
"author": [
{
"reference": "Device/f4d020c6-eaff-4528-83ba-e81a1cfd30dc"
}
],
"custodian": {
"reference": "Hl7.Fhir.Model.Organization",
"display": "BRIDGE STREET SURGERY"
},
"section": [
{
"title": "Allergies and Sensitivities",
"code": {
"coding": [
{
"system": "http://fhir.nhs.net/ValueSet/gpconnect-record-section-1",
"code": "ALL"
}
],
"text": "Allergies and Sensitivities"
},
"text": {
"status": "generated",
"div": "<div><h1>Allergies and Adverse Reactions<\/h1><div><p><table><tr><td><p>All Data Items<\/p><\/td><\/tr><\/table><\/p><\/div><table><tr><td>Sensitive data has been excluded<\/td><\/tr><\/table><h2>Current Allergies and Adverse Reactions<\/h2><table><th>Start date<\/th><th>Details<\/th><tr><td>31 Oct 2016<\/td><td>Latex allergy<\/td><\/tr><\/table><h2>Historical Allergies and Adverse Reactions<\/h2><table><tr><td><p> This system does not support retrieval of Historical Allergies and Adverse Reactions data. <\/p><p>This data may still exist in the source system.<\/p><\/td><\/tr><\/table><\/div>"
}
}
]
}
},
{
"resource": {
"resourceType": "Patient",
"id": "7302348e-e090-4c5d-99e9-14147c266ebe",
"meta": {
"versionId": "1202600162206596780",
"profile": [
"http://fhir.nhs.net/StructureDefinition/gpconnect-patient-1"
]
},
"identifier": [
{
"system": "http://fhir.nhs.net/Id/nhs-number",
"value": "9480489457"
}
],
"name": [
{
"family": [
"Dolby"
],
"given": [
"Ivan"
],
"prefix": [
"Mr"
]
}
],
"gender": "male",
"birthDate": "1923-03-02",
"address": [
{
"line": [
"",
"53 Burrett Road",
""
],
"city": "Wisbech",
"district": "0",
"postalCode": "PE13 3RT"
}
],
"careProvider": [
{
"reference": "Practitioner/e26035eb-f0e6-4211-9997-6b5365a2eb76"
}
]
}
},
{
"resource": {
"resourceType": "Organization",
"id": "cafe1615-9232-47ae-80ea-e554f943fd9b",
"meta": {
"versionId": "9045189372685666075",
"profile": [
"http://fhir.nhs.net/StructureDefinition/gpconnect-organization-1"
]
},
"identifier": [
{
"system": "http://fhir.nhs.net/Id/ods-organization-code",
"value": "D82015"
}
],
"name": "BRIDGE STREET SURGERY",
"address": [
{
"use": "work",
"line": [
"Fulford Grange, Micklefield Lane",
"Rawdon",
"Rawdon"
],
"city": "Leeds",
"district": "Yorkshire",
"postalCode": "LS19 6BA"
}
]
}
},
{
"resource": {
"resourceType": "Device",
"id": "5A084F08-29D0-4F5B-8809-D1F96578AFB1",
"meta": {
"versionId": "9008072080809363811",
"profile": [
"http://fhir.nhs.net/StructureDefinition/gpconnect-device-1"
]
},
"identifier": [
{
"system": "EMIS",
"value": "EMIS"
}
]
}
},
{
"resource": {
"resourceType": "Practitioner",
"id": "e26035eb-f0e6-4211-9997-6b5365a2eb76",
"meta": {
"versionId": "5944618252807509908",
"profile": [
"http://fhir.nhs.net/StructureDefinition/gpconnect-practitioner-1"
]
},
"name": {
"family": [
"Fidler"
],
"given": [
"Josh"
],
"prefix": [
"Mr"
]
},
"address": [
{
"use": "work",
"line": [
"Fulford Grange, Micklefield Lane",
"Rawdon",
"Rawdon"
],
"city": "Leeds",
"district": "Yorkshire",
"postalCode": "LS19 6BA"
}
],
"gender": "male"
}
}
]
}
Examples
C#
var client = new FhirClient("http://gpconnect.fhir.nhs.net/fhir/");
client.PreferredFormat = ResourceFormat.Json;
var parameters = new Parameters();
parameters.Add("nhsNumber", new Identifier("http://fhir.nhs.net/Id/nhs-number","P003"));
parameters.Add("recordSection", new CodeableConcept("http://fhir.nhs.net/ValueSet/gpconnect-record-section-1","ALL"));
var resource = client.TypeOperation<Patient>("gpc.getcarerecord",parameters);
FhirSerializer.SerializeResourceToJson(resource).Dump();
Java
FhirContext ctx = FhirContext.forstu3();
IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.fhir.nhs.net/fhir/");
client.registerInterceptor(new LoggingInterceptor(true));
// Create the input parameters to pass to the server
Parameters inParams = new Parameters();
inParams.addParameter().setName("patientNHSNumber").setValue(new Identifier().setValue("P003").setSystem("http://fhir.nhs.net/Id/nhs-number"));
inParams.addParameter().setName("recordSection").setValue(new CodeableConcept().addCoding(new Coding().setCode("ALL").setSystem("http://fhir.nhs.net/ValueSet/gpconnect-record-section-1")));
Parameters outParams = client
.operation()
.onType(Patient.class)
.named("gpc.getcarerecord")
.withParameters(inParams)
.execute();
Bundle responseBundle = (Bundle) outParams.getParameter().get(0).getResource();
System.out.println(ctx.newXmlParser().setPrettyPrint(true).encodeResourceToString(responseBundle));