API Use Case
The “Register a patient” capability should either create a new temporary patient registration or re-activate an existing “Inactive” patient registration, as a temporary patient registration within the GP Practice system (Definition of a GP Connect Active Patient).
This specification describes a single use case. For complete details and background please see the Foundations 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:
- SHALL have previously resolved the organisation’s FHIR endpoint Base URL through the Spine Directory Service
- SHALL have previously traced the patient’s NHS Number using the Personal Demographics Service or an equivalent service.
API Usage
Request Operation
FHIR Relative Request
POST /Patient/$gpc.registerpatient
FHIR Absolute Request
POST https://[proxy_server]/https://[provider_server]/[fhir_base]/Patient/$gpc.registerpatient
Request Headers
Consumers SHALL 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.registerpatient-1 |
Example HTTP request headers:
POST http://gpconnect.aprovider.nhs.net/GP001/DSTU2/1/Patient/$gpc.registerpatient HTTP/1.1
User-Agent: .NET FhirClient for FHIR 1.2.0
Accept: application/fhir+json;charset=utf-8
Prefer: return=representation
Host: michaelm-pc
Content-Type: application/fhir+json;charset=utf-8
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.registerpatient-1
Payload Request Body
The following data-elements are mandatory (i.e. data SHALL be present):
- A
registerPatient
parameter containing a patient resource profiled to the CareConnect-GPC-Patient-1 profile. This is the patient who you want to be registered. Within this resource:- The NHS Number and Date of Birth as a minimum SHALL be populated to enable a provider to perform a PDS trace.
- Where the gender, name or birth date are available these SHALL also be supplied (as indicated by the Must-Support FHIR property)
- The consumer SHALL NOT populate the “registrationDetails” extension within the patient resource.
The following data-elements SHOULD be populated if available:
- Within the patient resource of the
registerPatient
parameter:- the
telecom
element SHOULD be populated- the consumer SHALL NOT populate the
telecom.use
value withold
- the consumer SHOULD populate only one
telecom
pertelecom.use
value
- the consumer SHALL NOT populate the
- the
address
element SHOULD be populated- the consumer SHALL NOT populate the
address.use
value withold
- the consumer SHOULD populate only one
address
peraddress.use
value - the
address.use
valuehome
SHOULD be mapped to PDS Address UseHP
(Primary Home)
- the consumer SHALL NOT populate the
Note: The consumer SHOULD include telecom and address information within the temporary patient registration so that the receiving system has relevant contact details for the patient.Note: The provider system receiving the telecom and address details SHOULD store these details in addition to any telecom or address details obtained through the PDS trace done as part of the patient registration. - the
The request payload is a set of Parameters conforming to the gpconnect-registerpatient-operation-1
profiled OperationDefinition
, see below:
<OperationDefinition>
<id value="0857bd2a-9c1f-4e2a-ac48-f6a81f88ab01" />
<meta>
<versionId value="1" />
<lastUpdated value="2017-11-03T12:21:35.991+00:00" />
<tag>
<system value="urn:hscic:examples" />
<code value="Operation-Register-Patient" />
<display value="Register Patient Operation" />
</tag>
</meta>
<url value="https://fhir.nhs.uk/STU3/OperationDefinition/GPConnect-Registerpatient-Operation-1" />
<version value="0.0.1" />
<name value="GPConnect-RegisterPatient-Operation-1" />
<status value="active" />
<kind value="operation" />
<publisher value="NHS Digital" />
<contact>
<name value="Interoperability Team" />
<telecom>
<system value="email" />
<value value="interoperabilityteam@nhs.net" />
<use value="work" />
</telecom>
</contact>
<date value="2016-08-03T00:00:00+01:00" />
<description value="Request to register a patient at a healthcare organisation" />
<code value="gpc.registerpatient" />
<system value="false" />
<type value="Patient" />
<instance value="false" />
<parameter>
<name value="registerPatient" />
<use value="in" />
<min value="1" />
<max value="1" />
<documentation value="Patient demographic information captured in the patient resource to register the patient." />
<type value="Patient" />
<profile>
<reference value="https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1" />
</profile>
</parameter>
<parameter>
<name value="response" />
<use value="out" />
<min value="1" />
<max value="1" />
<documentation value="The searchset bundle resource that has been returned in response to the given input parameters" />
<type value="Bundle" />
<profile>
<reference value="https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Searchset-Bundle-1" />
</profile>
</parameter>
</OperationDefinition>
Patient
resource as a temporary patient record once a PDS trace has been confirmed.On the wire a JSON serialised $gpc.registerpatient
request would look something like the following:
{
"resourceType": "Parameters",
"parameter": [{
"name": "registerPatient",
"resource": {
"resourceType": "Patient",
"meta": {
"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1"]
},
"identifier": [{
"extension": [{
"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-NHSNumberVerificationStatus-1",
"valueCodeableConcept": {
"coding": [{
"system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1",
"code": "01"
}]
}
}],
"system": "https://fhir.nhs.uk/Id/nhs-number",
"value": "9476719931"
}],
"name": [{
"use": "usual",
"family": ["Jackson"],
"given": ["Jane"],
"prefix": ["Miss"]
}],
"gender": "female",
"birthDate": "22/02/1982"
}
}]
}
Error Handling
The Provider system SHALL return an error if:
- the
registerPatient
is invalid. - the
registerPatient
doesn’t include a single active NHS Number identifier. - the
registerPatient
demographics don’t match that of the triggered PDS trace.
Provider systems SHALL return an GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data fields are corrupt or a specific business rule/constraint is breached.
Refer to Development - FHIR API Guidance - Error Handling for details of error codes.
Request Response
Response Headers
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/fhir+json; charset=utf-8
Date: Sun, 07 Aug 2016 11:13:05 GMT
Content-Length: 1464
Payload Response Body
Provider systems:
- SHALL return a
200
OK HTTP status code on successful registration of the patient into the provider system. - SHALL include the URI of the relevant GP Connect
StructureDefinition
profile in the{Resource}.meta.profile
element of the returned resources. - SHALL return a searchset
Bundle
profiled to GPConnect-Searchset-Bundle-1 including the following resourcesPatient
profiled to CareConnect-GPC-Patient-1 containing details of the newly registered or re-activated patient. This will include details sourced from PDS.
- SHALL populate the “registrationDetails” extension within the returned patient resource, within the “registrationDetails” extension:
- The “registrationType” should be populated with a value from the valueset which matches the registration type used within the provider system. If an appropriate registration type is not available within the valueset then the
Other
type should be use and more detail around the specific type of registration can be added using the “text” element of the CodeableConcept.
- The “registrationType” should be populated with a value from the valueset which matches the registration type used within the provider system. If an appropriate registration type is not available within the valueset then the
{
"resourceType": "Bundle",
"meta": {
"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Searchset-Bundle-1"]
},
"type": "searchset",
"entry": [{
"resource": {
"resourceType": "Patient",
"id": "9",
"meta": {
"versionId": "636180880331209494",
"lastUpdated": "2016-08-10T13:35:57.319+01:00",
"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1"]
},
"extension": [{
"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-RegistrationDetails-1",
"extension": [{
"url": "registrationPeriod",
"valuePeriod": {
"start": "2017-09-07T14:17:44+01:00"
}
},
{
"url": "registrationType",
"valueCodeableConcept": {
"coding": [{
"system": "https://fhir.nhs.uk/CareConnect-RegistrationType-1",
"code": "T"
}]
}
}]
}],
"identifier": [{
"extension": [{
"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-NHSNumberVerificationStatus-1",
"valueCodeableConcept": {
"coding": [{
"system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1",
"code": "01"
}]
}
}],
"system": "https://fhir.nhs.uk/Id/nhs-number",
"value": "9476719931"
}],
"name": [{
"use": "usual",
"family": ["Jackson"],
"given": ["Jane"],
"prefix": ["Miss"]
}],
"gender": "female",
"birthDate": "22/02/1982"
}
}]
}
Examples
C#
var client = new FhirClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
client.PreferredFormat = ResourceFormat.Json;
var parameters = new Parameters();
parameters.Add("registerPatient", new Patient
{
Active = true,
BirthDate = "1976-01-10",
Gender = (AdministrativeGender)Enum.Parse(typeof(AdministrativeGender),"Male"),
Name = new List<HumanName>
{
new HumanName()
{
Given = new[] {"Mike"},
Family = new[] {"Smith"},
Use = HumanName.NameUse.Usual
}
},
Identifier =
{
new Identifier("https://fhir.nhs.uk/Id/nhs-number","1234569999")
}
});
var resource = client.TypeOperation("gpc.registerpatient","Patient",parameters);
FhirSerializer.SerializeResourceToJson(resource).Dump();
Java
FhirContext ctx = FhirContext.forStu3();
IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
Patient patient = new Patient();
patient.addIdentifier()
.setSystem("https://fhir.nhs.uk/Id/nhs-number")
.setValue("1234569999");
patient.addName()
.addFamily("Smith")
.addGiven("Mike")
.setUse(NameUseEnum.USUAL);
patient.setGender(AdministrativeGenderEnum.MALE);
patient.setBirthDate(new DateDt("1976-01-10"));
// Create the input parameters to pass to the server
Parameters inParams = new Parameters();
inParams.addParameter().setName("registerPatient").setValue(patient);
Parameters outParams = client
.operation()
.onType(Patient.class)
.named("gpc.registerpatient")
.withParameters(inParams)
.execute();
Bundle responseBundle = (Bundle) outParams.getParameter().get(0).getResource();
System.out.println(ctx.newXmlParser().setPrettyPrint(true).encodeResourceToString(responseBundle));