Testing (Transactional)

Overview

We provide test environments to our patient-facing and transactional API partners. Each test environment fully replicates the current production version of Medicus, including the API and user interface.

Any updates performed by us will be automatically reflected in both the test and production environments; there is no need for a user or Consumer to take any action.

All non-technical and technical documentation can be found on the Medicus Help Centre.

We will provide support for any issues in the test environment via our dedicated Partner Slack channels.

All data in a test environment is synthetic data and is in no way reflective of real-world patient or staff data. Any similarity is purely coincidental.

Test users are free to create their own test data via the Medicus user interface, or via the API.

Test Environment Status

The Medicus Status page will alert partners to any issues with the Medicus test or production environments.

In accordance with our API Operating Procedure, API partners will be made aware of any planned maintenance work that may affect site performance. In the event of an unexpected disruption to service, we will be in touch with all partners via email and Slack.

Requesting Access to a Test Environment

To request access to a test environment, get in touch with your designed Medicus Partner Manager via Slack or email.

Please note, if your integration with Medicus is via the NHS IM1 framework then please also CC im1.team@nhs.net into any correspondence.

Limitations of the Test Environment

Medicus' test environments replicate a live environment. This means that all requests and usage are subject to our Fair Use Policy.

Accessing a Test Environment

Each Medicus test environment consists of a base URL (e.g. myorganisation.medicus.health)

Within each test environment, there are multiple Medicus “tenants”, each with a unique identifier (e.g. b10001). Each tenant within the test environment is representative of a single healthcare organisation.

Depending on your requirements and intended use, we will grant you access to one or more tenants within a test environment.

Test Environment Staff Interface

To access the interface that staff members at a healthcare organisation would login to. We will provide you with a Medicus username and password.

Each account created is granted administrative rights. This means that you will be able to:

• Add new users

• Manage the permissions of existing users

• Manage third-party integrations

Test Environment API

The test environment API URL has the following structure: https://{{tenantId}}.{{baseUrl}}. For example: https://b1001.myorganisation.medicus.health/transactional-api/v1/patient/eb8d8f70-360c-11ed-a5b3-060b232f1aa2/name .

API requests can be made to this base URL via HTTPS.

To make requests to the PFS and Transactional API endpoints, your app must be registered on the Medicus Developer portal. Your Medicus Partner Manager will guide you through registration and the process for managing and uploading the public keys required to sign your JWT payloads.

By default, all Medicus “Accredited Interactions” and endpoints will be available to consumer using the test environment.

In a production environment, access will be restricted to the endpoints that have been accredited by Medicus.

Using Postman to Query API Endpoints

For convenience, Postman can be used to query the Medicus developer APIs.

Access to the Medicus Developer GitHub repository will be provided by your dedicated Partner Manager.

Importing the Postman Collections

1. Download the Postman collection

2. Import into Postman (File → Import)

3. Edit the collection variables to reflect the desired setup
   

   

JWT Token Generation in Postman

The JWT token is generated at run time. See Sample Environment Variables below for more details.

The following JWT body properties can be set as variables in Postman:

• iss - The App's Developer Portal UUID (as found on the Developer Portal)

• kid - The Developer Key UUID (as found on the Developer Portal)

• userName

• userEmail

• userIdentifierType

• userIdentifierValue

• softwareSystem

• applicationName

• organisationName

• organisationIdentifierType

• organisationIdentifierValue

Postman Pre-request Script

The pre-request script performs the following actions:

• Downloads and loads the jsrsasign library and stores the library in the jsrsasign variable. This is a one time action, if jsrsasign is set, then the library is loaded from the local variable.

• Creates the JWT Token.

• Sends the JWT token with the request.