Send consultation notes to a patient's General Practice

In this scenario, a patient has interacted with your system, and you need to send a summary of the encounter as consultation notes to their General Practice.

Consultation notes have specific significance within the conneQt platform. Some patient administration systems can store notes about an encounter in a way that allows the text within the notes to be indexed and searched by users. This differs from sending a plain text document, which is uploaded to a patient's record as a file attachment.

Both approaches are valid and can be suitable in various situations. However, not all patient administration systems can handle text content. In such cases, the conneQt Toolbar bundles your consultation notes into a text file and includes them as a file attachment. If you're unsure which approach to take, please don't hesitate to contact us for advice related to your specific use case.

Both consultation notes and file attachments are sent through the conneQt platform using the same messaging structure. If you've already followed the send one document scenario, much of this flow will be familiar to you.

Prerequisites

Before sending consultation notes, your system must have the following information:

Patient's verified NHS Number.
Recipient organisation's national ODS code.
Message topic.
API Key provided by Quicksilva for authentication.

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: Query 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 Consultation Notes

You'll send consultation notes as plain text, base64-encoded, in an "attachments" entry of your request message. The conneQt platform distinguishes consultation notes using a custom MIME type. The message must also include other data items for context:

The message request your system sends, that will include the consultation note, must include some other data items to provide some context for the message sending activity:

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

Additionally, some other data is required to populate the request message:

A unique GUID must be written to messageId, which will be used to query the message's status later.
Optionally, a short plain-text description of what is being sent, which will be shown to users within the receiving organisation. In this example, the text "Consultation summary for SMITH, John" is used.

To send the consultation notes, your system sends an HTTP POST request to the "api/v1/messages" endpoint of the conneQt platform. Here's an example of the request using Postman:

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"
        }
    },
    "body": {
        "mimeType": "text/plain",
        "content": "Consultation summary for SMITH, John"
    },
    "attachments": [       
        {
            "fileName": "consultation-notes-jsmith.txt",
            "mimeType": "text/vnd.qxlva.conneqt.consultation",
            "content": "{{base64-encoded-content}}"
        }        
    ]
}

The conneQt platform will return a HTTP 200 OK response and a JSON payload containing a relative link your system can use to query the status of the message, which we will do so next. The status endpoint path includes a GUID that matches the value we used in the messageId property when we sent the consultation notes.

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 consultation notes have 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 Message Status

Send an HTTP GET request to query the status of the message using the message ID, in Postman send the message "step-3-querying-the-message-status":

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 Consultation Note

In a real-world scenario, systems sending documents wouldn't perform these steps in production. However, for this end-to-end demonstration, we'll simulate working in the patient's practice. If you've followed the 'Getting Started' steps, you should have the Test PAS and conneQt Toolbar client running. Switch to the conneQt Toolbar client.

After a short wait, a red dot will appear next to the messages icon, indicating that the conneQt Toolbar has a message available. Click the messages icon to view the sent message in a list. Select the message to open the preview window. Here, the conneQt Toolbar will perform the following tasks:

Attempt to find a matching patient in the local PAS with a verified NHS number. Display a preview of the Consultation Notes for review before importing it into the patient's record. If you sent a message with a known NHS number in your Test PAS data, you'll see the matching patient on the left of the document preview. You can then choose to import or reject the document.

If you didn't use a known NHS number, don't worry. The conneQt Toolbar can handle this situation. In your Test PAS, select the 'Subjects' option from the left navigation and view any patient records available. Then, back in the conneQt Toolbar, click the button on the document preview window that says 'use current.' This tells the conneQt Toolbar to import the document into the patient record you currently have open in your PAS.

Select the import option, confirm your choice, and the consultation notes will be imported into the patient record. You can now close the document preview window in the conneQt Toolbar, as there are no more actions needed. In your Test PAS, the document will appear within the patient's view.

Note

The Test PAS treats consultation notes the same way as attachments, resulting in your consultation notes being saved as a text file attachment in the patient record. In a real PAS, this behavior may vary depending on the PAS's capabilities.

Step 5 Query Message Status Post-Import

Your system can utilize the status endpoint we previously used to determine when the consultation notes have been imported. You can reissue the request we sent earlier to query the status of the document. In Postman, 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 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": "COMPLETED",
    "updated": "2023-09-06T10:57:17.20306Z"
}

The message status now displays "COMPLETED" indicating that the consultation notes have successfully been imported into the patient record.

Send consultation notes 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: Query for Available Topics

Note

Note

Step 2: Sending Consultation Notes

Important

Step 3: Querying Message Status

Note

Note

Step 4: Import the Consultation Note

Note

Step 5 Query Message Status Post-Import

See Also