Purpose and Scope
The EMIS Portal SDK addresses a fundamental challenge in healthcare IT: how to provide clinicians with single-click, context-rich access to external systems while maintaining security, governance, and performance. It supports both “Session Service Invocation” and “Direct Client Invocation” models, catering to varied architectural preferences and levels of security compliance required by different portal vendors.
Two primary methods of launching a portal from within an EMIS application are supported. Session Service Invocation (SSI) is a server-mediated launch model wherein the EMIS application makes a server-to-server POST request to the portal’s Session Service, which returns a session identifier and a URL to launch the portal. This is the recommended approach where tighter control over authentication and security is needed, particularly as it allows for the use of mutual TLS (TLS-MA) and restricts client-side exposure to credentials.
In contrast, Direct Client Invocation (DCI) is a lighter-touch, client-mediated method where the EMIS application posts the SessionRequest XML directly from the client browser to the portal landing page. While DCI simplifies implementation and can be suitable for less sensitive use cases, it does expose more of the transaction to the client environment and may be less suited to deployments requiring stringent control over access and authentication.
Structure of a Session Request
At the heart of both launch models is the SessionRequest XML, which encapsulates provenance, user credentials, application metadata, and patient demographics. Provenance includes essential metadata such as the EMIS user ID, job role, smartcard token (where available), and external credentials if the portal relies on username/password authentication. These credentials are securely hashed using PBKDF2 with a defined iteration count, salt size, and hash size – ensuring compliance with NHS-grade security expectations.
Patient information includes a flexible combination of identifiers (NHS number, CHI, EMIS-specific IDs), birth date, name, and optionally, full address and contact details. These fields are governed by portal configuration, allowing EMIS administrators to tailor the payload based on what the receiving system requires.
A portal receiving a SessionRequest must respond with a well-formed SessionResponse XML, indicating either success (with a session ID, expiry timestamp, and invocation URI) or failure (with detailed error messaging). The use of standard HTTP response codes (e.g. 400 for malformed input, 403 for failed authentication, 503 for service unavailability) ensures predictable behaviour and easier debugging. Additionally, the SDK mandates that each SessionRequest and SessionResponse carry unique request and response identifiers to support traceability, auditing, and robust fault diagnostics.
SAML-Based Authentication
Where required, the SDK supports SAML 2.0 assertions for user authentication. These assertions are digitally signed and include role and user identity claims, with strict rules around audience restriction, time-bound validity, and naming conventions. Notably, the assertion includes a compound identifier in the form [EMIS Web User Name]:[User in Role GUID], URL-encoded to ensure safe transmission.
The receiving portal is responsible for validating the digital signature and establishing trust based on a pre-agreed public key. This adds an additional layer of assurance in contexts such as cross-organisational access or smartcard-based workflows.
Patient Availability Service
In scenarios where it is desirable to check the presence of a patient record before launching a portal, the SDK outlines a Patient Availability Service (PAS). This is a RESTful GET endpoint that the EMIS application calls asynchronously upon patient switch. The PAS request includes user credentials and patient identifiers, enabling the portal to return a simple XML indicating whether a matching patient record exists. A successful call returns either an available or unavailable state, while any operational faults are returned using a fault schema. To mitigate performance issues, results are cached per user for up to 10 patients, and failed calls are not reattempted for five minutes.
Configuration and Extensibility
The EMIS platform supports extensive configuration to tailor how portals behave within an organisation. Each portal is assigned a unique GUID, and parameters such as available views, display name, launch type (SSI or DCI), authentication method, and PAS support can all be managed centrally. At the organisation level, administrators can enable or disable portals, specify patient data requirements, and assign user credentials on a per-role basis. These configurations are stored securely and ensure that each portal behaves predictably within the user’s clinical context.
Additionally, the SDK allows for dynamic configuration of portal views, user-role mappings, and iconography. If a portal supports multiple entry points (e.g. different modules or services), these can be presented as selectable options within the EMIS interface at the point of launch.
User Interface and Workflow Integration
From the user’s perspective, launching a portal is as simple as clicking an icon within the EMIS user interface. These icons can be placed in default locations, such as the Care Record screen, or hidden entirely if integration is to occur via other mechanisms. The interface supports multiple view selections if the portal defines them and overlays availability icons to indicate whether a patient record is accessible in real time.
Importantly, EMIS applications do not capture consent for data access within the portal; this responsibility lies with the portal provider as the data controller. Likewise, EMIS cannot audit actions performed within the portal – only the invocation itself is logged.
Security and Governance Considerations
The portal is considered a separate clinical system with its own responsibilities for information governance, clinical safety, and data accuracy. While the EMIS application ensures that patients marked as sensitive or sealed are not launched into a portal, all other safeguards must be implemented by the portal provider. For example, once launched, EMIS prevents the user from swapping patients until the portal is closed – ensuring that patient context is preserved throughout the session.
In terms of security, all data exchanges must occur over HTTPS with TLS v1.2 or higher. Where SSI is used, mutual TLS authentication with client certificates ensures that only authorised EMIS instances can request sessions. Passwords are never transmitted in plain text and must be hashed using PBKDF2 with a standard configuration of 64,000 iterations and 32-byte salt and hash sizes. Replay protection is implemented via unique invocation identifiers and short session expiries, typically set at one minute.
Session re-use is explicitly forbidden. Portals must enforce one-time usage and treat attempts to re-use session identifiers as security incidents, potentially logging these events for further review.
Portal Availability and SLAs
Given that portal integrations can become a critical part of clinical workflows, the SDK encourages portal vendors to communicate expected downtimes, usage patterns, and escalation routes to EMIS. This allows for proactive monitoring and efficient triaging of issues. It is expected that EMIS users encountering portal issues will first contact EMIS support, so a clear pathway for redirection and collaborative support is vital for maintaining trust and efficiency.
Conclusion
The EMIS Portal SDK provides a mature, comprehensive, and security-conscious framework for integrating third-party portals into EMIS clinical systems. By standardising how sessions are initiated, how patient and user data are transferred, and how availability is checked, the SDK dramatically reduces integration complexity and cost. For developers and system integrators, the specification offers clear guidance, extensible schemas, and robust mechanisms for supporting a wide range of authentication and workflow models – all while ensuring patient safety, system security, and high availability.
As digital interoperability becomes more critical to modern healthcare delivery, the EMIS Portal SDK is a well-architected, scalable foundation for seamless system-to-system integration across primary care in the NHS.