Capture Authorization

To send automatic approval messages through the conneQt platform, your system must first obtain authorization from the recipient user. This process involves the following steps:

  1. Link user details received from the conneQt platform to a local user account within your system.
  2. Allow a user to enter an authorization code generated by the conneQt Toolbar.
  3. Send the authorization code to the conneQt platform within a JSON request.
  4. Store an automatic approval access token against your local user account.

This one-time action establishes a connection between your system and a user of the conneQt Toolbar. It serves as proof that the user has authorized your system to use this feature on their behalf. Your system will exchange a code generated by the conneQt Toolbar for an access token, which can then be used for all subsequent automatic approval messaging between your system and the conneQt platform when sending documents generated by that specific clinical user.

This page provides a step-by-step guide to capturing user authorization and exchanging the code for an access token for your system's use in sending messages.

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: User obtains authorization code from conneQt Toolbar

A clinical user within an organisation using the conneQt Toolbar desktop client can request an authorization code by following these steps:

  1. Right-click anywhere on the conneQt Toolbar to access the right-click menu.
  2. Select the "pre-approved messages" option from the menu.
  3. Choose "Create a new access token" from the screen that appears.

The conneQt Toolbar client will generate an authorization code for you the user to enter into a form within your system, which you need to build.

Step 2: Exchange authorization code for access token

After capturing the user's authorization code, your system should send an HTTP POST request to our "api/v1/messages/instant/access/token" endpoint to validate the code and associate it with the user of the conneQt Toolbar client. Here's an example request:

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

{
    "accessCode": "OMO7UAHG"
}

Upon successful verification, the conneQt platform will respond with an HTTP 200 OK status and a JSON payload containing the access token:

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

{
    "token": "ec050d1b-9be4-48ba-9a74-cec0fea8d20f"
}

Your system should store this "token" value locally against the user's profile data. This token will be used for sending instant messages on behalf of this user in the future.