Send documents to a patient's General Practice

The conneQt platform offers a seamless and efficient method for automatically importing essential documents and data into a recipient organisation's patient record system. This feature is designed to streamline data integration processes, particularly for healthcare applications and systems that require real-time access to patient information.

With instant messages, your system can send documents and coded data directly to the recipient organisation, bypassing the need for manual review and approval. This approach is ideal for scenarios where immediate integration is critical, such as laboratory results, medication updates, or critical patient updates.

The conneQt platform ensures that data is securely and accurately integrated into the recipient's patient record, reducing administrative overhead and improving the speed of information dissemination. Instant messages empower healthcare systems to deliver the highest level of patient care by providing timely access to crucial data.

To leverage instant messaging within the conneQt platform, integration and configuration steps are required.

Automate your data integration processes with conneQt's instant messaging, ensuring that essential information flows seamlessly into the patient record, enhancing healthcare delivery, and improving patient outcomes.

In this scenario, a conneQt Toolbar user launches your system via a widget, performs patient-related activities, and generates a PDF summary with an accompanying image. These files should be added to the patient record. After previewing and confirming, your system sends both the PDF and image using the instant message access token. The conneQt Toolbar automatically imports them into the patient record without user intervention.

Prerequisites

To send automatically approved documents for importing into a patient record, your system must have the following information in advance:

  • The patient's verified NHS Number for matching with the patient record in the receiving organisation's clinical system.
  • The national ODS code of the recipient organisation to specify the document's destination.
  • The message type, referred to as a "topic" by the conneQt platform (more details on topics later).
  • Your system's API Key, provided by Quicksilva, for authenticating every API call made to the conneQt platform.

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:

  1. 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.
  2. Once the Test PAS has started, open a web browser to the following URL - http://localhost:5000.
  3. In the web browser, select the "log in" option.
  4. When prompted, enter your Spine User ID, which was provided to you with your SDK.
  5. 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:

  1. Select the "Subjects" option from the left navigation menu. This will load all patients contained within the PAS.
  2. If you see a list of patients because you've previously run the Test PAS, you can skip the rest of this step.
  3. 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.
  4. From the "Manage Data" options, select the "Load Subject Data" option.
  5. 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.
  6. The Test PAS will load the patient data from the JSON file.
  7. 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:

  1. Open Postman.
  2. 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.
  3. 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:

  1. Open Postman and ensure the conneQt Platform environment is selected.
  2. Locate the "test-connection" request within the Postman collection you imported earlier.
  3. Select the "test-connection" request.
  4. Click the "Send" button to execute the request.
  5. 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 documents

You will send a PDF document and a JPG image to the patient's General Practice for inclusion in the local patient record. Both documents must be base64-encoded by your system and included in a single request message as "attachments."

To send these documents, your system will base64-encode them and include them as "attachment" entries within a JSON payload sent to the conneQt platform. This request should also include additional data items to provide 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 PDF content .attachments[0].content
base64-encoded JPG content .attachments[1].content

In addition to the data listed in the table, you need to include some additional information to populate the request message:

  • Generate a unique GUID and assign it to the messageId field. This GUID will be used later to query the message's status.
  • Optionally, provide a short plain-text description of the content being sent. This description will be displayed to users within the receiving organisation. In this example, we are using the text "Consultation summary for SMITH, John."

To send this message, your system should make an HTTP POST request to our "api/v1/messages/instant" endpoint. This request will store the message, along with the PDF and JPEG attachments, for delivery to the recipient organisation. You can find the request named "step-2-sending-documents" within the Postman collection and use it to send the message.

POST  https://int.conneqt.health/api/v1/messages/instant HTTP/1.1
Content-Type: application/json
ApiKey: {{my_api_key}}
Conneqt-Instant-Access-Token: {{current_instant_messaging_token}}

{
    "messageId": "{{$randomUUID}}",
    "type": "ToolbarInstantMessage",
    "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-summary-jsmith.pdf",
            "mimeType": "application/pdf",
            "content": "{{base64-encoded-pdf-content}}"
        },
        {
            "fileName": "consultation-image-jsmith.jpg",
            "mimeType": "image/jpeg",
            "content": "{{base64-encoded-jpg-content}}"
        }
    ]
}

After sending the message and attachments to the conneQt platform, you will receive an HTTP 200 OK response. This response will contain a JSON payload that includes a relative link. Your system can use this link to query the status of the message. The status endpoint path will include a GUID that corresponds to the value you used in the messageId property when you sent the documents. Next, let's proceed with checking the status of the message.

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

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

Now that you've successfully sent the documents to the conneQt platform, it's time to check the status of the message to ensure that everything is in order.

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. Initially, the message will have a status of "PENDING" but once automatic import completes within the conneQt Toolbar client, the status will transition to "COMPLETED". If you see "PENDING", try resending the query after a few seconds:

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

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

See Also