Send multiple documents to a patient's General Practice

In this scenario, a patient has engaged with your system, and you need to send multiple documents to the patient's GP practice. These documents should contain details about the interaction, its outcome, and any images that are required within the document. In this example, your system has generated a PDF document containing all the relevant information and a JPG file for the image. You will use the conneQt platform to send both files to the patient's General Practice as a single consultation.

Prerequisites

To send documents to another organisation for import into a patient record, your system needs to have the following information:

  • The patient's verified NHS Number, allowing matching to a patient record in the receiving organisation's clinical system.
  • The national ODS code of the recipient organisation, enabling the conneQt platform to route the document correctly.
  • The type of message being sent, referred to as a 'topic' by the conneQt platform. More details on topics will be covered later.
  • Your system's API Key, provided by Quicksilva, which is used for authentication in 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

In this step, you will send a PDF document and a JPG image to the patient's General Practice for import into the local patient record. All documents sent to the conneQt platform must have their content base64-encoded by your system and included as "attachments" in a single request message. Here's a breakdown of the data items required for this step:

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

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

The conneQt platform will respond with an HTTP 200 OK response and a JSON payload containing a relative link that your system can use to query the status of the message, which you will do in the next step. The status endpoint path includes a GUID that matches the value used in the messageId property when sending the documents.

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 documents have been sent to the conneQt platform, 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 needs to send an HTTP request to query the status of the message you 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 your message, indicating whether it's pending, completed, or another status.

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 multiple documents into a patient record

In this step, you will simulate the process of importing the documents into a patient's record, even though this is typically done by the General Practice and not the system sending the documents. If you followed the "Getting Started" steps, you should 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 that a message is available.
  • Click the messages icon to view the list of messages.
  • Click on the message you just sent, and the conneQt Toolbar will open the message preview window.

In this preview window, the conneQt Toolbar will:

  1. Attempt to find a single matching patient within the local PAS who has a matching verified NHS number.
  2. Display a preview of the PDF content and other attachments for review before import.

If you sent a message using an NHS number that is known in your Test PAS data set, you will see the matching patient displayed to the left of the document preview area. You will also have options to import or reject the document.

If you used an NHS number that was not known in your Test PAS, you can still handle the situation. Within your Test PAS, select the "Subjects" option from the left navigation and view any patient records you have available. Then, back in the conneQt Toolbar, click the "use current" button on the document preview window. This informs the conneQt Toolbar to import the document to the patient record that is currently open in your PAS.

Select the import option on the document preview window, confirm your selection, and the consultation notes will be imported into the patient record. You can then close the document preview window in the conneQt Toolbar.

Step 5 Query the message status post-import

Your system can use the status endpoint mentioned earlier to determine if and when the documents have been imported successfully. Repeat the request you sent earlier to query the status of the document using Postman:

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 your message, indicating that it is now in a "COMPLETED" status, signifying that the document has been successfully imported into the patient record.

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"
}

See Also