Send a document to a patient's General Practice

In this scenario, a patient has carried out one or more activities within your system and you want to send a document to the patient's GP practice containing details about the interaction and its outcome. Your system has produced a PDF document containing all of the relevant information and will use the conneQt® platform to send that document to the patient's General Practice.

Prerequisites

To send a document to another organisation for import into a patient record your system must know a few things in advance:

  • The patient's verified NHS Number so we can match to a patient record within the receiving organisation's clinical system.
  • The national ODS code of the recipient organisation so the conneQt® platform knows where to route the document to.
  • The type of message that is being sent, which the conneQt® platform calls a "topic". We will cover more about topics shortly.
  • Your system's API Key, provided by Quicksilva, which is used to authenticate every API call you make to the conneQt® platform.

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 a document

Once you've determined the topic, you will send the document to the patient's General Practice. This involves creating an HTTP POST request to the conneQt® platform's "api/v1/messages" endpoint. The request should include the following information:

  • `messageId`: A unique identifier for the message.
  • `topic`: The chosen topic for your message.
  • Recipient organisation ODS code: The national ODS code of the recipient organisation (patient's General Practice).
  • Patient's verified NHS Number: The NHS Number of the patient to associate the document with their record.
  • `body`: A plain-text description of the document's content.
  • `attachments`: An array containing the document(s) you want to send. Each attachment should include details like fileName, mimeType, and content, where content is the base64-encoded content of the document.:
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": "Dispense notification for SMITH, John"
    },
    "attachments": [
        {
            "fileName": "medication-dispense-jsmith.pdf",
            "mimeType": "application/pdf",
            "content": "{{base64-encoded-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.

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

{
    "messageStatusEndpoint": "/api/v1/messages/eed25f0b-f95b-4f42-99a1-5046e72dac0a/status"
}
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

After sending the document, you can query the conneQt® platform to check the status of your message. You will send an HTTP GET request to the status endpoint, which will provide information about the current status of the message. This step helps you confirm if the document has been successfully received and processed by the General Practice.

Within Postman open and 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 document is 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 document into a patient record

This part of the process involves simulating the import of the document into the patient's record, which typically occurs at the General Practice. Here are the steps you need to follow to simulate this process using the conneQt® Toolbar:

  1. Ensure that you have the Test PAS and conneQt® Toolbar client running, as mentioned in the instructions.
  2. After a short period of time, you will see a red dot appear next to the messages icon in the conneQt® Toolbar. This indicates that there is a message available for you.
  3. Click the messages icon to access the list of messages, and you will see the message you have just sent in the list view.
  4. Click on the message, and the conneQt® Toolbar will open the message preview window.
  5. The conneQt® Toolbar will perform the following activities:
    • Attempt to find a single matching patient within the local PAS that has a matching verified NHS number.
    • Display a preview of the PDF content for you to review before importing it into the patient's record.
  6. Assuming you sent a message using an NHS number that is found in your Test PAS dataset, you will see the matching patient displayed to the left of the document preview area.
  7. You will also see options to either "Import" or "Reject" the document. Since we want to simulate importing the document, choose the "Import" option.
  8. If you did not use an NHS number that was known in your Test PAS, don't worry. The conneQt® Toolbar provides a workaround. In your Test PAS, select the "Subjects" option from the left-navigation menu and view any of the patient records you have available.
  9. Back 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 that is currently open in your PAS.
  10. Select the "Import" option again on the document preview window.
  11. You will be asked to confirm your selection. Select the affirmative option to proceed with the import.
  12. The consultation notes or document will be imported into the patient's record.
  13. You can now close the document preview window in the conneQt® Toolbar, as there are no further actions required.
  14. Back in the Test PAS, you will find the document within the view for the patient whose record you used for the import.

This step allows you to simulate the process of importing the document into the patient's record, which is typically done by the General Practice. It helps complete the end-to-end flow of sending a document through the conneQt® platform.

Step 5 Query the message status post-import

Your system can utilize the previously used status endpoint to check if and when our document has been imported. To query the document's status, resend the "step-3-querying-the-message-status" message 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 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 indicates "COMPLETED," confirming the successful import of the document into the patient record.

See Also