IM1 - Interface Mechanism

IDS47
Version2.0.0
TypeInteroperability Standard
StatusEffective
Effective Date 

Introduction

IM1 is a mechanism for accessing data held in GP Systems (Systems providing one or more Capabilities as part of the GP IT Futures Framework). The interface mechanism should facilitate the following use-cases: 

  • Patient - real-time access to APIs exposed over the Internet supporting both read and limited write / transactional operations for the purposes of Patient/Citizen Facing Services (including registration and authentication of Citizens)
  • Bulk - Bulk data extracts of all data held by the GP System Supplier
  • Practice real-time APIs for integrating systems, which may operate locally

Provider Suppliers acting as consumers of their own interfaces must take note of requirements in the Interoperability Standard, particularly those relating to equitable access to functionality and data (Requirement: ISNFR07)

Please also note that suppliers must be compliant with the overarching Commercial Standard, and comply with the Model Interface Licence contained within.

Applicability

A system or application is required to provide IM1 interfaces if ANY of the following are true:

  • It offered IM1 interfaces under GPSoC
  • It offers ALL Foundation capabilities under GP IT Futures

Where a GP Connect interface capability is available, suppliers would be expected to develop against that, rather than developing a new bespoke or proprietary interface.

A system or application may wish to consume IM1 interfaces where they have a requirement to access data held in GP Systems.

Requirements 

This page describes integration requirements for systems which are required to be an IM1 interface provider and\or consumer.

The scope of this document includes:

  • Generic requirements which allude to best practices in Applications integration, Extract Transformation Loading & API Management 
  • Requirements around some high level API Calls and its expected behaviour in generic terms 
  • Requirements around System Context, Authentication & Version Management

The following are not in scope:

  • Low level Interface specifications and schema definitions. IM1 interfaces are not built to a standard specification and core system suppliers are currently free to implement in whatever way they see fit, however, suppliers should read the Principles section of the Interoperability Standard and ensure their approach is aligned accordingly. Where applicable they should be able to demonstrate adherence to Principles  
  • Commercial arrangements and charging
  • Assurance and testing
  • Mechanisms to get a Consumer Supplier on board and giving access to test environments 

Generic Integration Requirements

Monitoring & Response Times

This pertains to individual requests and responses for each message interaction and how these are monitored. 

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_resp_001The Provider Integration Architecture must be capable of monitoring requests received by various Consumers, including the capture of response times required for processing the request within the confines of the Supplier Data Centre / Cloud boundaryProviderPractice & PatientMUST

Authentication and End Points 

This refers to how Consumer Systems and Users are authenticated and mechanisms for Consumer systems to access the IM1 interfaces

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_auth_001

The Provider must provide a seamless process to authenticate Consumer systems and Users without any extra overhead or usability issues 

User of a Consumer Solution can refer to a patient in case of Citizen Facing capabilities or refer to a healthcare professional or NHS Staff

ProviderAllMUST
im1_auth_002

The access to Provider Endpoints should not be constrained by existence of a User Session on the Provider Solution

ProviderPractice

SHOULD 

im1_auth_003For the Practice IM1 where feasible, the access to Provider Endpoints should not be constrained by requiring the Consumer integration components to be present within a Practice or within the GP's workstation/PCProviderPracticeSHOULD 
im1_auth_004The access to Provider file Extracts must not be constrained by requiring the Consumer integration components to be present within a Practice or within the GP's workstation/PC for the Bulk IMProviderBulkSHOULD

System Context & Invocation 

This refers to the context of the User Session within a Provider Solution and its visibility to the Consumer

IDRequirementConsumer or ProviderIM1 TypeLevel

im1_context_001

The Provider Solution must provide mechanism for Consumer to be kept aware/notified of context information. At the very minimum notification should include

  • user
  • patient 

Note: Providers will notify Consumers of state/context changes; Consumers will not be required to poll or repeatedly call the Provider system to establish if there has been a change

ProviderPracticeSHOULD 

im1_context_002

In addition the Provider Solution context information must include, where appropriate (and where subscribed to / requested by Consumer):

  • Complete set of changes (additions, deletions, amendments) to patient demographics where applicable
  • Functional state (e.g. prescribing module selected, add Appointment selected)
  • Data state (e.g. the drug selected, the problem/diagnosis selected) identified uniquely using the appropriate terminology
ProviderPracticeSHOULD
im1_context_003The Provider Solution should have a mechanism to launch the Consumer Solution, in a particular Context, by a User of the Provider Solution- This will be dependent on Consumer Solution providing a suitable link via which the Provider could launch / invoke the Consumer SolutionProviderPracticeMAY

Appropriate use of integration capability

Ensuring the Provider Solution is not impacted by huge influx of request messages and how it handles such scenarios. 

IDRequirementConsumer or ProviderIM1 TypeLevel

im1_use_001

Provider must be capable of applying appropriate throttling techniques in order to spread the processing load of incoming requests or Extracts processing

ProviderAllMUST
im1_use_002Provider must be capable of notifying the Consumer of unavailability or delay of request processing (eg. during heavy usage of the Provider System) ProviderAllMUST

im1_use_003

If the Consumer supports non user-initiated actions/events that may affect either Provider or Consumer Solution performance then such actions/events must be capable of being scheduled at appropriate times

ConsumerAllMUST
im1_use_004Where a Provider includes mechanisms to retrieve large sets of data in real time, they must provide guidance on when to use each API call or method- The documentation that describes the supplier's IM1 must also indicate whether the use of any particular Interface Mechanism may adversely affect the performance of the system, e.g. extracting all the clinical data for all patients impedes general system performance and should be run during periods of low usage or when no users are using the systemProviderPractice & PatientMUST
im1_use_005The Consumer must ensure it displays the most up-to date information to its user - Where the information is not up-to date then it should be clearly notified to the User and the User should have visibility of date-time modified for the particular data item ConsumerAllMUST

Interface Version Management

It is recognized that suppliers will need to update their interface mechanisms. These requirements ensure version updates are done in a standard manner giving enough notification to Consumers and also providing them the relevant details pertaining to changes. 

IDRequirementConsumer or ProviderIM1 TypeLevel

im1_ver_001

The version of the Interface Mechanism will be available to Consumer systems either via API calls or messages, or provided on request to Provider

ProviderAllMUST

im1_ver_003

Provider implement updates in a manner that supports backward compatibility leaving existing interfaces working. Where an interface has to be retired then relevant requirement applies

ProviderAllMUST

im1_ver_004

Deprecation of interfaces must only be carried out with agreements from Authority and Consumers by providing them with enough advanced noticeProviderAllMUST

im1_ver_005

Any interface change which would break existing Consumer App needs to be notified beforehand and Consumers should be given the opportunity to test their Solutions against it. ProviderAllMUST
im1_ver_006Any new changes in an interface needs to be very clearly documented such that different between latest version and earlier version is very clearProviderAllMUST
im1_ver_007Consumers of IM1 will be notified of deprecated interfaces and will be given suitable notice in order for their Solution to be migrated away from deprecated interfaces and utilize the latest offering of IM1 from the Provider. Consumers must work to implement the latest versionConsumerAllMUST

Error & failure handling

How errors in message processing should handled and notified to consumers

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_error_001Any error condition experienced by the Provider in processing a request needs to be clearly identified, captured and logged - The Consumer should get clear specific information as to what that error was ProviderAllMUST
im1_error_002Error conditions must not result in abrupt disconnection or failure of the overall Provider interface. The provider should gracefully exit when errors occur and return meaningful error messages to the consumer
Provider & ConsumerAllMUST
im1_error_003Consumer must display the relevant specific error message to the end-user to give them a clear indication as to what went wrongConsumerPractice & PatientMUST

Terminology & Coding Data Sets

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_code_001Provide a mechanism for a Consumer Supplier to discover versions of any coding schemes used within the Provider Solution (including SNOMED-CT, DM+d, any other standard coding terms)ProviderPractice and BulkMUST

Test Environments

ID
Requirement
Consumer or Provider
IM1 Type
Level
TE-IS-01For each Type 1 Catalogue Solution that includes one or more of the Qualifying Interfaces as defined within the Model Interface Licence, the Supplier must provide stable and secure supported test environments which can be utilised by any supplier that has entered into a Model Interface Licence (or equivalent) as a consumer of such Interface.ProviderAllMUST

TE-IS-02

With regard to the test environments required under requirement TE-IS-01, the test environments must be provisioned by the Supplier based on demand and be internet facing with no dependency on N3/HSCN.ProviderAllMUST
TE-IS-03The Supplier is required to produce a Fair Usage Policy as referred to in the Model Interface License to be applied to their Qualifying Interfaces. Within this statement, the Supplier shall declare their maximum capacity in respect of concurrent provision of supported test environments (which shall be agreed with the Catalogue Authority and amended from time to time with the consent of the parties) for the purposes of management of  capacity and scheduling of environment access to third party suppliers.ProviderAllMUST
TE-IS-04

With regard to the test environments required under requirement TE-IS-01, the Supplier must, within 5 Working Days of receipt of a request from the Catalogue Authority provide additional test environment capacity. 

This provision is subject to maximum Supplier capacity constraints as recorded in consideration of requirement TE-IS-03 above.

ProviderAllMUST
TE-IS-05With regard to the test environments required under requirement TE-IS-01, the Supplier must grant the Catalogue Authority sufficient rights to schedule and commit access to supported test environments to third party suppliers, without reference to the Supplier.ProviderAllMUST
TE-IS-06With regard to the test environments required under requirement TE-IS-01, the Supplier must ensure that they reflect the live environments.  Any differences identified between test and live environments are to be rectified within 48 hours.ProviderAllMUST
TE-IS-07With regard to the test environments required under requirement TE-IS-01, the Supplier shall ensure that each test environment is available for use by relevant Consumer Suppliers on a 24x7 basis with periods of planned downtime being minimised and notified to all relevant Consumer Suppliers.ProviderAllMUST
TE-IS-08The test environments provisioned under requirement TE-IS-01 are to support multiple suppliers connecting concurrently in line with scheduling as defined in TE-IS-05 (subject to any maximum capacity constraints identified under TE-IS-03).ProviderAllMUST
TE-IS-09The Supplier must ensure that a Consumer Supplier that has entered into a Model Interface Licence (or equivalent) is granted access and able to commence testing using the test environments provisioned as part of TE-IS-01 within 30 days, subject to: (a) the Consumer Supplier meeting its connection obligations; and (b) any maximum capacity constraints identified under TE-IS-03.ProviderAllMUST

Transaction or Practice Integration

Requirements are listed in terms of API Calls or Methods categorized by GP IT Futures Capabilities. For existing IM1 Providers none of the API calls should be removed unless an equivalent or an uplifted version is provided. 

Patient Information Maintenance 

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_cap_001

Search Patient

Description: The Supplier must provide a mechanism that allows Consumer systems to search for a patient by providing patient demographic data items as search parameters. At the very minimum the Provider should provide search using the following fields used independently or used in combination:  first name, last name, dob, NHS Number and Provider should return the full set of demographics for the matching patient(s)

ProviderPracticeMUST
im1_cap_002

Update Demographics

Description: The Supplier should provide a mechanism for Consumer systems to create a request for amending patient demographics via APIs, which can then be performed by a user of the Provider system

ProviderPracticeSHOULD
im1_cap_003Get Patient DemographicsProviderPracticeMUST
im1_cap_004Get Full Medical RecordProviderPracticeMUST
im1_cap_005File Data in Patient RecordProviderPracticeMUST

Appointments Management

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_cap_006

Get Bookable Slots (Appointment) 

Note: This should be met via GP Connect requirements as per Interoperability Standard

ProviderPractice

SHOULD

im1_cap_007

Book Appointment

Note: This should be met via GP Connect requirements as per Interoperability Standard

ProviderPractice

SHOULD

im1_cap_008

Cancel Appointment

Note: This should be met via GP Connect requirements as per Interoperability Standard

ProviderPractice

SHOULD

im1_cap_009Check in a Patient (on arrival)ProviderPracticeSHOULD

Consultation Management

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_cap_010Get Consultation Records for a PatientProviderPracticeSHOULD
im1_cap_011Create a new Consultation RecordProviderPracticeSHOULD
im1_cap_012Add a document or attachment to a Consultation RecordProviderPracticeSHOULD

Documents Management

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_cap_013File Document into a Patient RecordProviderPracticeMUST
im1_cap_014Retrieve Documents for a PatientProviderPracticeMUST

Prescribing

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_cap_016Get All Current MedicationsProviderPracticeMUST
im1_cap_017Prescribe a Drug for a PatientProviderPracticeSHOULD

Referral Management

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_cap_018Get All ReferralsProviderPracticeSHOULD
im1_cap_019Create a ReferralProviderPracticeSHOULD

Resource Management

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_cap_021Get Details For Specific StaffProviderPracticeMUST

Communications Management

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_cap_022Send Message to a PatientProviderPracticeMAY

Patient/Citizen Facing interfaces

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_pfs_001The interface mechanism provided by the Solution must be sufficient to support the epics and requirements of the consumer Solutions that provide citizen online services as described in the Citizen capabilities.ProviderPatientMUST
im1_pfs_002

The interface mechanism must support the query of services (capabilities) that are available with respect to a specified practice, and to a specific patient.

ProviderPatientMUST
im1_pfs_003

The interface mechanism must support the query of which patients are associated with a specific authenticated Verified User Account (VUA).

ProviderPatientSHOULD

Non Primary Care Settings 

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_nonpc_001

In an environment where Provider provides information-sharing across clinical settings, data provided to Practice Facing Consumer systems should include all data (including that from other settings) that is visible to the Provider Solution user.

Where such data is provided to Consumer systems, it must be made clear to the Consumer system which data is managed by the Provider Solution within the context of the Practice (Primary Care), and which is visible as a result of information-sharing mechanisms

Data provided to Patient Facing Consumer systems must only include data for which the Practice acts as Data Controller.

ProviderPracticeSHOULD

IM1 Refresh 

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_refresh_001

The Provider needs to ensure all IM1 APIs are maintained to reflect relevant updates to the Providers Solution, for example new or amended data fields being collected and stored by the Provider.  IM1 release cycles should be aligned with overall Solution release cycle.  The appropriate API versioning should be applied as part of any new release.

This requirement is intended to cover changes initiated by the Provider as part of BAU product maintenance and is distinct from the change process for Minor and Patch Changes, which is intended to cover changes initiated by the Authority

ProviderAllSHOULD

Bulk Extracts

In order to support the needs of the Practice and its related organisations (e.g. commissioners, organisations responsible for public health) access to bulk clinical data that exists in Provider systems needs to be available, whilst being securely and appropriately controlled.

IDRequirementConsumer or ProviderIM1 TypeLevel

im1_bulk_001

All data and entities which are part of the Data Model as defined by the Supplier, must be made available as required in the Extracts. These must include data for all patients for which the Practice is the data controller and should also include schema definitions, relationship diagrams (where applicable) and logical model in order for a Consumer to correctly interpret the extracts 

The only exception is Transient data and if the Provider Supplier wishes these could be excluded. The definition of Transient data is provided further below in the page.

Bulk Schemas and consumer requests will be reviewed every 3 months and new entities or fields required for inclusion must incorporated as agreed & directed by the ‘Minor or patch changes’ section of the Change Management Process

ProviderBulkMUST
im1_bulk_002There must be at least one extract of bulk data in a 24 hr periodProviderBulkMUST
im1_bulk_003Batch/bulk data extracts must include all data updates older than 30 minutes from the start of the extract processProviderBulkMUST
im1_bulk_005Provider must use a consistent Protocol / agreement for the transfer of Bulk extracts to relevant locations such that Consumer can consume it in a safe, complete manner ProviderBulkMUST

im1_bulk_006

Provider should have mechanisms of filtering Entities / Fields / Records based on Data Controller definitions before providing the Extracts

ProviderBulk

MUST

im1_bulk_007The Provider must have an ability to log the full extraction process and various activities which takes place during the extraction process including capturing of response times for the extracts - In addition it should log start and stop events, errors & exceptions, statusesProviderBulkMUST 
im1_bulk_008Provider should provide a capability for a Consumer to send a custom request for bulk extracts (for particular patient cohorts) to be processed by Provider. This request could be processed in an asynchronous manner (in a reasonable time frame not more than 2 or 3 hrs)ProviderBulkMAY
im1_bulk_009Consumer must provide their approach and strategy for combining data from several different disparate sources and their adherence to Information Governance guidelines in terms of acquiring and access to this dataConsumerBulkMUST
im1_bulk_010Consumer must be able to demonstrate their anonymisation and de-anonymisation processes ensuring they are in line with the Information Governance requirementsConsumerBulkMUST
im1_bulk_011Consumer must have a mechanism to perform data quality checks on ingested data and have a process for highlighting corrupt data values or fieldsConsumerBulkMUST
im1_bulk_012Consumer Supplier must be able to demonstrate efficient mechanisms for data ingestion of Bulk extracts for both Full Bulk extracts and Delta drops ConsumerBulk MUST
im1_bulk_013

Consumer must provide an approach strategy for any transformations they plan to undertake, including a clear rationale explaining the transformations, before or during the Consumer's integration development

ConsumerBulkMUST

Deprecation of Interfaces

In relation to the planned deprecation of IM1 interfaces the following requirements will apply from the time that the interfaces are deprecated:

IDRequirementConsumer or ProviderIM1 TypeLevel
im1_dep_001Deprecated interfaces must not be switched off, decommissioned or have service degraded while there are live consumers using the interface - Relevant SLA's still apply ProviderAllMUST
im1_dep_002

Deprecated interfaces may be decommissioned where:

  1. The supplier has implemented into live a replacement as per the NHS Digital roadmap for the interface AND
  2. There are no longer any live consumers of the deprecated interface
ProviderAllMUST

Compliance & Assurance

On boarding suppliers acting as providers or consumers will be required to evidence compliance against the IM1 interface line item requirements, as detailed on this page.

IM1 consuming suppliers will also need to complete the pairing process, before going live within the framework and this carries its own set of compliance and assurance requirements which currently lived outside of this framework. 

The pairing process will remain the responsibility of the IM1 operations function. For advice and assistance from NHS Operations Function, please contact im1.team@nhs.net.

Important terms and definitions

Transient Data Definition

  • Application log files for operational diagnostic trace, information, warnings and errors
  • Completed message, scheduled historical operational/non patient record reports and other document correspondence Application archives
  • Application user session data
  • Application cache data
  • Application help information
  • Service configuration settings e.g. Firewall, VPN, SAN setup, Microsoft SQL Server settings, Microsoft IIS machine.config and web.config settings, batch scheduling settings

Definition of Administration and Clinical Data

Administrative: Any data entities or objects which are involved in any aspect of administration of Patient Care and Management  

Clinical: Any data entities or objects which contain data of clinical nature

Suppliers wishing to exclude data which falls within either of these definitions from the interfaces must agree this with the Authority.

Dependencies (Patient facing interface Only)

Creating a compliant implementation of IM1 Patient interface requires implementing the following dependent interface standard:

  • NHS login service

Roadmap