Send coded SNOMED data to a patient's General Practice

In this scenario, when a patient engages in activities within your system, you may want to send a summary of the encounter to the patient's General Practice, including coded SNOMED data that represents the encounter.

Sending SNOMED data through the conneQt Platform is an optional capability. The successful import of coded data into a recipient's system depends on the compatibility of the recipient system used by the patient's General Practice. The conneQt Toolbar's ability to handle coded data is not guaranteed and varies depending on the recipient systems.

Coded data should always be accompanied by other document types when sent. For example, if your system generates a consultation summary as a PDF document, it should include human-readable content along with coded SNOMED data that reflects the content within the PDF.

It is crucial that your system ensures the accuracy of the coded SNOMED data sent via the conneQt platform to recipient systems. The conneQt platform does not validate, verify, or translate coded SNOMED data; this responsibility lies with your system to maintain data accuracy.

Prerequisites

To send SNOMED data to another organisation for inclusion in a patient record, your system needs to have the following information in advance:

The patient's verified NHS Number to match with the patient's record in the recipient organisation's clinical system.
The national ODS code of the recipient organisation, enabling the conneQt platform to direct the document appropriately.
Identification of the message type, referred to as a "topic" by the conneQt platform. More details about topics will be covered shortly.
Your system's API Key, provided by Quicksilva, which is essential for authenticating every API call made to the conneQt platform.

It's important to note that when sending SNOMED data via the conneQt platform, it must always be accompanied by at least one other document, such as a PDF file, containing the human-readable representation of the coded data items. This ensures that the recipient organisation can access both the coded data and the human-readable information.

Getting Started

If you have access to our conneQt SDK, you'll have the following resources available for this walkthrough:

Our Test PAS (Patient Administration System) along with a login ID (Spine User ID).
A set of test patient data that can be imported into the Test PAS.
An API key that can be used when sending messages to our test system.
Our conneQt Toolbar desktop client.
A Postman collection with sample messages that can be used to follow along.

If you're interested in learning more about our SDK and gaining access to it, please refer to Software Development Kit for further information.

Setting up the Test PAS

Log in to the Test PAS

To start the Test PAS, follow these steps:

Double-click on the "Qxlva.TestPAS.Web.exe" file. This will initiate a web application running locally on your machine, listening for HTTP requests on port 5000.
Once the Test PAS has started, open a web browser to the following URL - http://localhost:5000.
In the web browser, select the "log in" option.
When prompted, enter your Spine User ID, which was provided to you with your SDK.
Complete the login process.

Upon successfully logging into the Test PAS, you will see some data on the home page about your user, including an Organisation ID value. This Organisation ID represents an ODS code of a test GP practice assigned to you with the SDK. Make a note of this Organisation ID as we will use it later when sending a message.

Check patient data is available

After logging in to the Test PAS, follow these steps:

Select the "Subjects" option from the left navigation menu. This will load all patients contained within the PAS.
If you see a list of patients because you've previously run the Test PAS, you can skip the rest of this step.
If you see a message stating "Currently there are no test patient records loaded in the system," it means you need to load some test patients. In that case, select the "Manage Data" option from the left navigation menu.
From the "Manage Data" options, select the "Load Subject Data" option.
An open-file dialog box will appear, prompting you to select a JSON file containing a set of test patients. The SDK includes a file named "test-pas-patients.json," so locate and select this file.
The Test PAS will load the patient data from the JSON file.
Finally, select "Subjects" from the left navigation menu to view a list of patients now available in the system.

Setting up Postman

Importing files

To configure Postman for sending a message, follow these steps:

Open Postman.
Import the Postman collection named "IM1_Send_Message" from the file "IM1_Send_Message.postman_collection" that is included with our SDK. To do this, go to "File" > "Import" and select the collection file.
Import the environment file ending with ".postman_environment.json" that contains the environment details you require. This environment file will contain variables unique to your issued SDK, including:

An API key that authorizes you to send HTTP requests to our web server.
A GP Practice ODS code representing a recipient organisation you can send messages to.
An NHS Number representing a patient that ships with the PAS test data.

To import the environment, go to "File" > "Import" and select the environment file.

With these configurations in place, you'll be ready to use Postman for sending messages using the provided environment variables and collection.

Testing connectivity

In every Postman collection that comes with our SDK, you will find a "test-connection" message at the top level. This message is designed to send an HTTP GET request to our server. It serves the purpose of verifying that you can successfully communicate with our server and that your API Key is working correctly.

During development or even in production, your application is free to make use of this "test-connection" endpoint as well. It can be a useful tool to periodically test connectivity from your system to ours to ensure everything is functioning as expected.

GET https://int.conneqt.health/api/v1/test HTTP/1.1
ApiKey: {{my_api_key}}

To test connectivity using the "test-connection" request in Postman, follow these steps:

Open Postman and ensure the conneQt Platform environment is selected.
Locate the "test-connection" request within the Postman collection you imported earlier.
Select the "test-connection" request.
Click the "Send" button to execute the request.
If connectivity is successful, you will receive an HTTP 200 OK response with an empty body. This indicates that your system can communicate with our server, and your API Key is working correctly.

HTTP/1.1 200 OK

Steps

Step 1: Querying for available topics

To ensure the successful processing of your message on the conneQt® platform, it's crucial to specify the type of message accurately. For instance, if you are an online pharmacy sending a dispense notification to a patient's registered GP practice, you must categorize the message correctly.

The conneQt® platform offers an API that allows your system to query the complete set of available topics. Selecting the appropriate topic is essential to ensure that the document is imported accurately into the recipient's system. If you cannot find a suitable topic or need guidance on which one to use for your specific use case, please don't hesitate to contact us for assistance.

To retrieve a list of available topics, your system should send an HTTP GET request to our "api/v1/topics" endpoint. To do this, open the "step-1-query-topics" request within the Postman collection and send the message. This will provide you with the list of topics to choose from for your message.

GET https://int.conneqt.health/api/v1/topics HTTP/1.1
ApiKey: {{my_api_key}}

Note

In Postman, the {{my-api-key}} placeholder will be automatically replaced with the API Key value you configured within the environment variables during the Getting Started section. This ensures that your API Key is correctly used for authentication in your requests.

When you make the request to the conneQt® platform's "api/v1/topics" endpoint in the test environment, you will receive an HTTP 200 OK response. This response will contain a JSON payload with an array of topic names. Please note that the available topic names in the test environment may not necessarily reflect those available in the live environment.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    { 
        "topicName": "topic-1"
    },
    { 
        "topicName": "Triage"
    }
]

The list of topics is relatively stable and doesn't change frequently. Therefore, it's acceptable for your application to cache the list of topics returned. Alternatively, if your system is designed for a specific use case, you can read the topic name directly from your application's configuration.

The important point to remember is that when sending a document, your request must include a topic name that is present in the list returned by the "/api/v1/topics" endpoint. Otherwise, your request to send a document will be rejected.

For our walkthrough, we will use the first topic name in the list, which is imaginatively named "topic-1."

Note

The Postman collection includes code to read and store the topic name value, eliminating the need for manual copying and pasting. This simplifies the process and ensures that the correct topic name is used in your requests.

Step 2: Sending coded SNOMED data

When sending a set of coded SNOMED data items related to a patient's consultation to their GP practice for integration into the local patient record, the message request from your system should include additional data items to provide context for the message sending activity. This context is essential for the recipient to understand and properly handle the message. It typically includes information such as:

Data Item	Location in message
Messaging topic	.topic
Recipient organisation ODS code	.recipient.id.value
Patient's verified NHS Number	.subject.id.value
base64-encoded text content	.attachments[0].content

In addition to the data listed in the table, there are additional data requirements to populate the request message:

messageId (Unique GUID): This field should be populated with a unique GUID (Globally Unique Identifier) that will later be used to query the message's status. Each message should have a distinct messageId to track its progress.
Description (Optional Plain-Text): You have the option to include a short, plain-text description of what is being sent. This description will be visible to users within the organisation receiving the message. In this example, you can use the text "Consultation summary for SMITH, John" to provide context to the recipients.

Including these additional data elements ensures that the message is uniquely identifiable, and the description helps users within the recipient organisation understand the content and purpose of the message.

The coded SNOMED data is included within the message as an array of coded data items. Each coded data item has the following fields:

Data Item	Type	Mandatory?	Description
code	string	Y	The SNOMED code you are sending
value	number	N	If the code represents a quantifyable value then the value goes here
units	string	N	The unit of measurement that should be used in conjuction with the value
additionalText	string	N	Text description to accompany the coded data

Your system initiates an HTTP POST request to our "api/v1/messages" endpoint, which stores the message, PDF attachment entry, and coded values for delivery to the recipient organisation. To execute this action within the Postman collection, please follow these steps:

Open the request named "step-2-sending-snomed-data" in the Postman collection.
Send the message by clicking the "Send" button in Postman.

This action will trigger the HTTP POST request, allowing your system to send the necessary data to the specified endpoint for further processing and delivery to the recipient organisation.

POST  https://int.conneqt.health/api/v1/messages HTTP/1.1
Content-Type: application/json
ApiKey: {{my_api_key}}

{
    "messageId": "{{$randomUUID}}",
    "topic": "{{send_message_topic}}",
    "recipient": {
        "id": {
            "value": "{{my_gp_practice_ods_code}}",
            "type": "OcsClientIdentifier"
        }
    },
    "subject": {
        "id": {
            "value": "{{my_target_nhs_number}}",
            "type": "VerifiedNhsNumber"
        }
    },
    "codedDataItems": [
        {
        "code": "407554009",
        "value": 140,
        "units": "mmHg",
        "additionalText": "Sitting systolic blood pressure"
        },
        {
        "code": "407555005",
        "value": 80,
        "units": "mmHg",
        "additionalText": "Sitting diastolic blood pressure"
        },
        {
        "code": "248223005",
        "additionalText": "Feeling faint"
        }
    ],
    "attachments": [       
        {
            "fileName": "medication-dispense-jsmith.pdf",
            "mimeType": "application/pdf",
            "content": "{{base64-encoded-content}}"
        }        
    ]
}

After sending the message to the conneQt platform, you can expect to receive an HTTP 200 OK response along with a JSON payload. This JSON payload will contain a relative link that your system can utilize to query the status of the message. The GUID within this status endpoint path should match the value you used in the messageId property when sending the documents.

You can proceed to use this relative link to query and monitor the status of the message, ensuring that it has been processed and delivered as expected.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "messageStatusEndpoint": "/api/v1/messages/eed25f0b-f95b-4f42-99a1-5046e72dac0a/status"
}

Now that the message has been sent to the conneQt platform within a message, we can check the status of the message.

Important

The conneQt platform conducts virus scans on all incoming documents to ensure the security and integrity of the platform and its documents. If your system encounters an error response indicating an issue with the document's content during the sending process, it is essential to take appropriate action and refrain from attempting to resend the attachment to the conneQt platform. This helps maintain the security and reliability of the platform.

Step 3: Querying the message status

Your system will send an HTTP request to query the status of the message we sent, to do this open the "step-3-querying-the-message-status" message within the Postman collection and send the message:

GET https://int.conneqt.health/api/v1/messages/{{latest_message_id}}/status HTTP/1.1
ApiKey: {{my_api_key}}

Note

If you are following each step, the Postman collection contains code to read and store the messageId from the HTTP request we previously sent; there is no need to make any changes to the URL.

The conneQt platform will respond with the current status of our message:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "messageId": "eed25f0b-f95b-4f42-99a1-5046e72dac0a",
    "status": "PENDING",
    "updated": "2023-09-06T10:46:12.20403Z"
}

The message we sent has a state of "PENDING" meaning the consultation notes are currently stored by the conneQt platform waiting to be imported by an individual in the GP practice.

Note

If you are following along, we are about to switch roles and start working in a General Practice...

Step 4: Import the SNOMED Data into a patient record

To simulate working within a patient's practice and follow the end-to-end flow, perform the following steps:

Ensure you have the Test PAS and conneQt Toolbar client running.
After a short period, a red dot will appear next to the messages icon in the conneQt Toolbar, indicating the availability of a message. Click the messages icon.
You will see the message you sent in a list view. Click on the message to open it.
The conneQt Toolbar will open the message preview window and carry out the following activities:

Attempt to find a single matching patient within the local PAS with a matching verified NHS number.
Display a preview of the PDF content for your review before importing it into the patient's record.

Assuming you sent a message using an NHS number found in your Test PAS dataset, you will see the matching patient displayed to the left of the document preview area. Options to import or reject the document become available.
If you did not use an NHS number known in your Test PAS, you can still handle this situation. Within your Test PAS, select the "Subjects" option from the left navigation and view any of the patient records you have available.
In the conneQt Toolbar, click the button on the document preview window that says "use current." This tells the conneQt Toolbar that you want to import the document into the patient record you currently have open in your PAS.
Select the import option on the document preview window, and you will be asked to confirm your selection. Choose the affirmative option.
The consultation notes will be imported into the patient record. Close the document preview window in the conneQt Toolbar as no further action is needed there.
Back in the Test PAS, you will find the document within the view for your patient.

Following these steps allows you to simulate the process of receiving, reviewing, and importing a document into a patient's record within a healthcare practice setting.

Step 5 Query the message status post-import

Your system can check the status endpoint we used earlier to track when our consultation notes are imported. You can resend the same request we used earlier to inquire about the document's status. To do this, use Postman and send the "step-3-querying-the-message-status" message once again.

GET https://int.conneqt.health/api/v1/messages/{{latest_message_id}}/status HTTP/1.1
ApiKey: {{my_api_key}}

The conneQt platform will reply with the current message status:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "messageId": "eed25f0b-f95b-4f42-99a1-5046e72dac0a",
    "status": "COMPLETED",
    "updated": "2023-09-06T10:57:17.20306Z"
}

The message status now displays "COMPLETED," confirming the successful import of the SNOMED data the patient record.

Send coded SNOMED data to a patient's General Practice

Prerequisites

Getting Started

Setting up the Test PAS

Log in to the Test PAS

Check patient data is available

Setting up Postman

Importing files

Testing connectivity

Steps

Step 1: Querying for available topics

Note

Note

Step 2: Sending coded SNOMED data

Important

Step 3: Querying the message status

Note

Note

Step 4: Import the SNOMED Data into a patient record

Step 5 Query the message status post-import

See Also