In agreement with stakeholders engaged in building against GP Connect 1.0.0 the following changes were made to improve and simplify two parts of the GP Connect interface, since the original release on the 23 Feb 2018:
- Retrieve a patient's appointments - simplification of API use case search parameters
- Cross organisation audit and provenance - removal of the
requested_record
claim from the JWT
Introduction
The GP Connect 1.0.0 release is a re-release of the previous Appointment Management 1.0.0-rc.3, Foundations 1.0.0-rc.4 and GP Connect 1.0.0-rc.1 releases using the new version number standard.
A number of changes were made when re-releasing as GP Connect 1.0.0 to:
- provide information on the new version number standard
- tidy the specification, including:
- removing out of date content
- renaming content inline with new names
- fixing broken links
- update MIME type and wire format representation requirements to align with support by providers
Please see below for further details.
Changes
Entire specification
-
added version number banner at header of all pages, linking to versions page containing a list of all specification versions
-
renamed Access Record REST to Access Record Structured to align with new naming for this capability pack
- removed the content of and replaced the following capability packs with an information notice, as they are not available in this version of the specification:
-
removed the top navigation menus as these are not preserved when hosting on NHS Developer Network
-
fixed a number of broken links
- fixed title bar styling when viewing on smaller screens
Core specification
-
added Specification versioning to explain new single version number standard
-
suffixed interaction IDs with
-1
in line with new version number standard -
removed compatibility support for old MIME types
-
updated wire format representations in line with provider support
-
migrated releases notes from individual capability packs into Core specification
-
removed the out of date maturity model
Core specification changes
These changes were previously released as GP Connect 1.0.0-rc.1 on 28 Nov 2017:
- Security guidance - updated security guidance around the protocols that suppliers should implement
- Cross organisation audit and provenance - updated JSON Web Tokens (JWT) specification examples to use the new profile and value sets and included requirement for patient demographic cross-checking
- Operation guidance - corrected ‘Example URL pattern’ for searches so that
System
andCode
are in the correct order - Error handling guidance - updated page to reflect move from ‘gpconnect-error-or-warning-code-1’ to ‘spine-error-or-warning-code-1’
- Security guidance - removed contradiction within specification for cache-control headers
- Common API guidance - uplifted guidance around the inclusion of profile details within the FHIR resource metadata element when a consumer performs a create or amend interaction
- Common API guidance - added clarification on use of PUT to make clear an update should not create a resource if the resource being updated does not already exist
- Common API guidance - added guidance on the behaviour of consumer and provider systems where Must-Support flag is present
- Common API guidance - split this page into ‘General API guidance’ and ‘FHIR implementation guidance’ pages
- Cross organisation audit and provenance - added section to clarify the expected use of the
requested_record
claim within the JWT - Information governance principles - updated teminology around the consumer responsibilities in regards to NHS Codes of Practice and Legal Obligations related to the use of GP Connect API; additionally added reference to the ongoing review of the information governance (IG) model, particularly in the light of General Data Protection Regulation (GDPR); additionally added more Access Record capability links to ‘Patient dissent to share’ and indicated that this was not applicable to Appointment Management capability
- Fhir library guidance - the FHIR library guidance page has been updated to improve GP Connect guidance around using existing FHIR libraries to aid its development
- Error handling guidance - updated error handling guidance to include expectations around a resource not found, provide details of Spine error codes expected and restructured to clarify differing error condition types.
- FHIR API guidance - corrected in scope search prefixes to be consistent with other pages
- Cross organisation audit and provenance - added additional guidance around the population of the requesting_organization claim within the JWT
- General API guidance - added details relating to the expectations around demographic cross checking of patient details when retrieving patient information
- Clinical terminologies - added wording around inclusion of SNOMED DescriptionID and ConceptID
- Cross organisation audit and provenance - added guidance around temporary support for deprecated values and elements within the JWT
- General API guidance - updated the URL requirements on the API page with the addition of an optional routing segment
Foundations
These changes were previously released as Foundations 1.0.0-rc.4 on 28 Nov 2017:
- Get the FHIR® CapabilityStatement
- Conformance statment page has been updated to reflect the change in STU3 to a CapabilityStatement resource.
- Changed metadata interaction id from
gpconnect:fhir:rest:read:metadata
togpconnect:fhir:rest:read:metadata-1
- Foundation Resources - Updated the resources to be the new GP Connect profiled STU3 resources.
- Design Decisions, Book an appointment - Added additional detail around the expected use of the Location and Organization where there specific meaning within the Appointment resource and the Patient resource.
- Information Governance - Added business rule for application of PDS S-Flag
Appointment management
These changes were previously released as Appointment Management 1.0.0-rc.3 on 28 Nov 2017:
- Retrieve a patient’s appointments
- Uplifted to STU3 profiles.
- Updated the wording and examples relating to the
start
search parameter(s) to clear up the expectations and remove the mis- leading wording around start and end of the date range - Updated wording to reflect the decision that only a Patient’s future appointments should be available via GP Connect
- Payload Response Body - Added requirement to only return appointments in the future.
- Search for free slots
- Uplifted to STU3 FHIR profiles for all resources
- Available Slot Filtering: Added requirement for Provider Systems to immediately support filtering of available slots such that only those bookable via GP Connect are provided, with strong indication that more granular slot availability control will be required to through the use of a newly added place-holder parameter called searchFilter.
freeBusyType
has changed tostatus
- The Practitioner reference has moved in the schedule resource from an extension to
Schedule.actor
- Read an appointment
- Uplifted to STU3 profiles.
- Updated requirements that only future appointments may be read by a consumer and the provider should return and error if the consumer tries to read a past appointment.
- Book an appointment
- Uplifted to STU3 profiles
- The ‘create’ extension has become the standard ‘created’ element within the Appointment resource
- Added guidance for providers that do not support both Appointment Description and Appointment Comment to append the received comment string to the mandatory description element
- Amend an appointment
- Uplifted to STU3 profiles
- Updated wording to reflect the decision that only a Patient’s future appointments should be available via GP Connect
- Added guidance for providers that do not support both Appointment Description and Appointment Comment to append the received comment string to the mandatory description element
- Updated requirements that only future appointments may be amended by a consumer and the provider should return and error if the consumer tries to amend a past appointment.
- Cancel an appointment
- Uplifted to STU3 profiles
- Updated requirements that only future appointments may be cancelled by a consumer and the provider should return and error if the consumer tries to cancel a past appointment.
- Introduction
- Uplifted wording to reflect inclusion of Urgent Care deployment setting
- Uplifted wording to reflect requirement for Provider Systems to filter slot availability so that the ones available via GP Connect can be controlled by the Practice, with indication of further requirement to support more granular Appointment Slot Control
- Clinical scenarios
- Uplifted wording to include the GP Practice requirement to control slot availability via GP Connect
- Uplifted wording to reflect the decision that only a Patient’s future booked appointments should be available via GP Connect
- Design Decisions
- Uplifted wording to reflect the decision that only a Patient’s future booked appointments should be available for viewing/amending via GP Connect
- Uplifted wording to reflect the decision that Patient Dissent to Share will NOT be applied for this capability
- Information Governance
- New page to describe the IG controls to be applied in the Appointment Management Capability
Appointment management
These changes were previously released as Appointment Management 1.0.0-rc.2 on 13 Oct 2017:
Specification Updates
- Appointment Management, Search for free slots, Operation Guidance - Changed to the InteractionId for “Search for free slots” to reflect move to restful endpoint instead of operation.
- Search for free slots - Updated formatting of search for free slots page and added clarification around the use of start and end parameters.
- Book an appointment - Added guidance around use of bookingOrganization and creation dateTime extension within appointment resource.
- Search for free slots - Added
disposition
andservice-id
search parameters for urgent care use cases. - Appointments - Consumer Sessions Illustrated, Spine Integration Illustrated - Added pages to highlight the sequence of interactions required to perform common business processes using the GP Connect API.
Profile Updates
- gpconnect-appointment-1 - Added
bookingOrganization
extension andcreated
extension within appointment resource profile.
Foundations changes
These changes were previously released as Foundations 1.0.0-rc.3 on 06 Oct 2017:
- Register a patient - Additional fields in patient profile which are marked with Must-Support flag
- Foundations Design - Added design decision to clarify how GP practice organisations and practice sites are represented in the FHIR Organization and Location resources.
- Foundation Resources, Register a patient - Changed “Register a patient” response to use “gpconnect-searchset-bundle-1” profiled bundle resource rather than the “gpconnect-registerpatient-bundle-1” profiled bundle resource.
- Register a Patient - registrationStatus extension element has been removed. Active status can be indicated through Patient.active element.
- Find a patient, Read a patient, Register a patient - Update patient resource examples to conform to structured definition.
- Find a Location - the API Use Case for “Find a Location” has been removed from the specification
- Register a patient - Added guidance on Register patient around consumer providing and storage expectaions for patient telecom and address information.
Appointment management
These changes were previously released as Appointment Management 1.0.0-rc.1 on 22 Sep 2017:
- Book an appointment, Search for free slots - Additional information has been added on how providers should indicate that slots are adjacent and therefore can be used for multi slot appointment booking by consumers.
- Design Decisions - API will not provide appointment re-scheduling through a single API interaction.
- Book an appointment - where participants are specified in request body, these must include a actor resource reference.
- Amend Appointment - Uplifted error handling guidanace around modification of appointment resource elements.
- Amend Appointment - Changed specification to clarify which fields may be amended.
- Book an appointment, Common API Guidance - Moved and uplifted guidance on resource state from book appointment to common api guidance.
- Search for free slots - Provider will return only details of free slots which have a date/time span fully within the time period specified
- Book an appointment - Added guidance around providers right to implement business rules to prevent misuse of the appointment booking api.
- Amend an appoinment - Clarity on use of PUT verb and the effect on the resultant state of the
Appointment.reason
element. - Search for free slots Use Case, Appointment Management Resources - Changed “Search for free slots” from a fhir operation to restful call.
Appointment management changes
These changes were previously released as Appointment Management 1.0.0-beta.2 on 08 Sep 2017:
- Removed practitioner participant as a mandatory element within the appointment resource (Page - Book an appointment).
- Added location participant as a mandatory element within the appointment resource (Page - Book an appointment).
- Updated datalibrary to be capability specific, moving it to reside under the “Development” menu within the capability. This is to allow the Profiled FHIR Resources to be referenced per capability and updated independantly. For Appointment Management we have updated specification to reference FHIR profiles stored on FHIR reference server rather than those on the old DMS capability pack.
- Updated book appointment with guidance on use of the comment and description elements within the resource.
- Updated search prefixes listed on “Retrieve a patient’s appointments” page, within Appointment Management API Use Case section, to align with common API guidance, removed “ne” search prefix and added the “eq” search prefix. Also updated the link to the Common API Guidance page to directly link to the search section.
- Corrected examples on API Use Cases pages to include FHIR Resource Profile in the returned FHIR resources.
- Added clarification on the expected response when the Search for free slots API use case does not return any free slots for the requested time period.
- Updated API Use Case pages to make clear the expectations around the FHIR Resource Metadata Profile element, along with updates to examples to show new profile definitions.
- Added clarification around GP Connect “FHIR Resource Profile” and “Metadata Profile” requirements on the request/consumer side of the Book an Appointment, Amend an Appointment and Cancel an appointment API use cases.
- Added clarification on the expected response content for the Retrieve a Patient’s Appointments API use case.
- Additional detail on error conditions for Read an appointment
- Cancel an appointment API use case associated with cancel an appointment interaction
- Book an appointment emphasised requirement for provider to return Location header describing details of the newly created resource.
- Retrieve a patient’s appointments includes guidance on what data items should be returned where date range parameters are ommitted in the request querystring.
- Search for free slots - updated identifier system within examples to match identifiers within new fhir profiles
- Added design decision to clarify responsibilities for consumer, SSP and provider in an implementation which provides a federated appointment management capability.
- Amend Appointment, Book Appointment, Cancel Appointment, Read Appointment, Retrieve a patiens appointments, Search for free slots - Added C# and Java code examples for all the appointment management API Use Cases.
- Book and appointment - Added clarification around the prerequisites, indicating that the consumer should have performed a “Find a patient” request to obtain the patient logical identifier on the fhir server.
- Amend Appointment, Book Appointment, Cancel Appointment, Read Appointment, Retrieve a patiens appointments, Search for free slots - Uplifted examples to use correct urls and elements.
Foundations changes
These changes were previously released as Foundations 1.0.0-rc.2 on 08 Sep 2017:
- Updated the system identifier URIs for Patient (https://fhir.nhs.uk/Id/nhs-number), Practitioner (https://fhir.nhs.uk/Id/sds-user-id), Organization (https://fhir.nhs.uk/Id/ods-organization-code) and Location (https://fhir.nhs.uk/Id/ods-site-code), this affects all the “Find” foundation API Use Cases. (Pages - development_fhir_operation_guidance.html, foundations_design.html, foundations_use_case_find_a_patient.html, foundations_use_case_find_a_practitioner.html, foundations_use_case_find_an_organisation.html, foundations_use_case_find_a_location.html)
- Read Organization, Conformance Profile, Read Location, Register Patient - Updated examples to conform to Care Connect profile uplifts.
- Glossary - updated glossary to make definition of Active Patient clear, used in Find a Patient API Use Case.
- Register Patient - Updated register patient example response to include the registration details extension.
Foundations changes
These changes were previously released as Foundations 1.0.0-rc.1 on 01 Sep 2017:
- Updated datalibrary to be capability specific, moving it to reside under the “Development” menu within the capability. This is to allow the Profiled FHIR Resources to be referenced per capability and updated independantly. For foundations we have updated specification to reference FHIR profiles stored on FHIR reference server rather than those on the old DMS capability pack.
- Updated Api Use Case pages to make clear the expectations around the Fhir Resource Metadata Profile element, along with updates to examples to show new profile definitions.
- Added information around what GP Connect considers as an Active Patient and use of Active Patient within the “Find a patient” capability (Page - foundations_use_case_find_a_patient.html, overview_glossary.html).
- Added additional information for “Register Patient” capability around re-activating inactive patients instead of registering new patient each time. (Page - foundations_use_case_register_a_patient.html)
- Removed the Practitioner and Organization as mandatory resources within the response bundle for the “Register Patient” interaction (Page - foundations_use_case_register_a_patient.html)
- Added clarification around the use of the “registrationDetails” extension for the “Register patient” interaction (Page - foundations_use_case_register_a_patient.html)
- Removed ODS-Site-Code as a search parameter and identifier from the Organization resource for “Find Organization” and “Organization Read”
Foundations changes
These changes were previously released as Foundations 1.0.0-beta.2 on 01 Aug 2017:
- Updated example conformance profile to include GP Connect profile information (Page - Get the FHIR Conformance Statement).
- Clarified use of Register a patient API is only to support local-only temporary patient registrations to support federated appointment booking
- Added additional clarification around use of identifiers for all foundation search capabilities (Pages - Find a practitioner, Find a patient, Find an organisation, Find a location).
- Clarity on mandatory data items for Register a patient API
- Moved VRead to out of scope (Pages - Get the FHIR Conformance Statement, Common API Guidance)
- Added java example code to specification for Read capabilities (Pages - Read a practitioner, Read a patient, Read an organisation, Read a location).
- Updated example code to bring in line with FHIR Server Root URL format guidance.
- Updates to Register a patient to include latest operation definition XML, and provide clarity on profiles used on response.