The SystmOne Client Integration API provides a powerful interface for third-party applications and devices to interact with the SystmOne client. This API allows developers to perform various functions, including searching for patient records, extracting patient data, and adding new patient information. In this post we are taking a look at how the SystmOne Client Integration API works and the capabilities it offers.
The SystmOne Client Integration interface enables seamless communication between third-party applications and the SystmOne client via a TCP socket connection. Communication occurs through XML documents, where the application sends function requests, and SystmOne processes these requests and returns responses. This interface supports a wide range of functions, from retrieving patient data to updating records and managing appointments.
The function requests and responses form the backbone of the SystmOne Client Integration API. Each interaction between the application and the SystmOne client is initiated by a request, which is an XML document that the application sends to the SystmOne client. This request includes various mandatory elements such as an API key, Device ID, Device Version, a unique Request UID, the function name, and its version. Depending on the specific function being requested, additional parameters may also be included to tailor the request to the required operation.
Once the SystmOne client processes the request, it generates a response, also in the form of an XML document. The response mirrors the structure of the request but includes additional elements such as a Response UID and the results of the requested function. This structured communication ensures that each request is paired with a corresponding response, maintaining the integrity and traceability of all interactions between the application and the SystmOne client.
The consistency in the request-response format is crucial for error handling and auditing purposes, as it allows for clear identification and resolution of issues that may arise during the integration process.
The SystmOne Client Integration API encompasses a wide range of functions, each designed to perform specific operations within the SystmOne client. These functions provide the necessary tools for third-party applications to interact with patient data, manage appointments, and retrieve organisational metadata. Among the core functions are:
To maintain optimal performance and ensure fair resource allocation, the SystmOne client imposes throttling limits on function requests. The client processes a maximum of one function request per 1 second, which helps prevent server overload and ensures smooth operation.
Specifically, the GetPatientRecord function is throttled to once every 30 seconds to manage the high demand for patient data retrieval (and the fact that a single patient record can be very large). Exceptions to this throttling are made when the request is filtered to retrieve only demographics or information entered within the last day. This fine-tuned throttling mechanism ensures that the system remains responsive and efficient even under heavy usage.
It is worth noting that performance considerations are integral to the design of the SystmOne Client Integration API. The response time for function requests can vary significantly based on the complexity of the request and the state of the SystmOne client. If all necessary data is already in memory, responses are near-instantaneous. However, if data retrieval from the SystmOne server is required, the response time may be longer, though generally still within sub-second intervals.
Maintaining a comprehensive audit trail is crucial for ensuring the transparency and security of interactions with the SystmOne client.
The SystmOne API audits all messages sent via the interface, which can be reviewed using the Client Integration Message Audit screen within the SystmOne client. This audit trail includes timestamps, message IDs, and the success status of each function.
Accurate patient identification is critical in any healthcare system, and the SystmOne API ensures this by using unique identifiers for patient records.
The primary identifier in SystmOne is the patient’s NHS number, but in cases where this is not available, a pseudo number is used. Function requests that involve patient data use these identifiers to ensure the correct patient record is accessed or updated. Additionally, the API includes a strategic reporting identifier in response to API requests, which facilitates easy correlation of data across different systems and reports.
This robust identification mechanism ensures that patient data remains accurate and consistent across all interactions.
Effective error handling is another crucial component of the SystmOne Client Integration API. The API provides structured error responses that help developers identify and resolve issues quickly. When an error occurs, the response includes an ErrorMessage element detailing what went wrong and a PermanentError element indicating whether the error is permanent or temporary. For example, if a PatientSearch function is attempted without specifying search constraints, the response will indicate that at least two search parameters must be provided.
The SystmOne Client Integration API is a robust interface for integrating third-party applications with the SystmOne client, enabling comprehensive management and interaction with patient records. By following the structured XML request and response format, developers can efficiently perform a wide range of functions, ensuring seamless and secure transactional data integration with SystmOne.
At 6B, we have extensive experience developing integrations with the Systmone Client Integration API, and we provide comprehensive support for digital health innovators looking to integrate with this API as well as other SystmOne APIs, from initial consultation to live deployment. If your team is considering SystmOne Client Integration API development please contact 6B for assistance and leverage our expertise to implement your SystmOne integration quickly, securely, and compliantly.
