Introduction

The integration of PainChek with an RCS can be achieved in one of two methods, mainly depending on whether the RCS has an open API or not.

In the case that the RCS does not have an open API, the developers or the RCS would have to develop the integration module, relying on some form of internal/private API to transfer data to/from the RCS. This is termed "RCS driven integration" and can be modelled as follows:

As you can see above, the RCS API (that provides a means to access the underlying databases) is private and hence a third party cannot access it. Therefore, the only integration option available is for the RCS provider to write the integration logic (which may be considered an extension of their core RSC system). The RCS developers use the open/public PainChek API to send and receive data to/from PainChek.

In the case that the RCS does have an open API, then it is possible for the RCS team, the PainChek team or indeed any other third party to write the integration logic. This is termed "Open Integration":

The difference, in this case, is that both sides (RCS and PainChek) have an open API and that allows anyone to write the integration logic. The integration logic remains separated from the core RCS and core PainChek systems.

The diagrams in the rest of this section will assume the "RCS driven integration" model as the purpose of this documentation is to provide guidance to a third party (such as an RCS provider) in regards to integration with PainChek. Furthermore, subsequent diagrams omit showing the API and Database components as separate entities in order to simplify the diagrams.

The RCS is always considered the source-of-truth (or master) for:

PainChek is the source-of-truth for:

In the event of a conflict, the source-of-truth wins out. This means, for example, that a change made to a resident record on PainChek (e.g. updating the persons' nickname) would be overridden by the RCS the next time that resident is synchronised.

PainChek is deployed as a web-based, multi-tenanted system. Each PainChek client is assigned their own license and all data for that client - users, resident, assessments, etc - is linked to the license.

Generally, data stored on a license can only be accessed by users linked to that license. It is, however, possible for a license holder to explicitly grant access to one or more of their resident to another license, but that is not material for this discussion.

When the RCS synchronises data with PainChek, it is on a per Client/License basis. Each set of PainChek API credentials is only valid for one license and hence the RCS must use the correct set of credentials for each Client/Licence.

In the case that the RCS is also multi-tenanted, the following architecture would apply:

In this case, the integration logic needs to maintain credentials for each license and ensure the correct set of credentials for each client is used when calling the PainChek API. Note that the RCS can have clients where there is no corresponding PainChek license (and hence there is no integration - e.g Client "C" in the above diagram).

In the case the RCS is not multi-tenanted, the following architecture would apply:

PainChek maintains a list of sites (also known of facilities or institutions) that serve two main purposes:

a) Recording where a resident is located

b) Limiting access to PainChek data - by linking users to one or more sites, we can limit those users to only being able to access data from those sites.

PainChek does not maintain a site hierarchy. If the RCS does maintain a hierarchy (e.g. Regions → Facilities → Wings), then a decision needs to be made about what the appropriate level of linking is. In this particular example, it would make most sense to map the RCSs "Facilities" to PainChek "sites". The "Region" level would be ignored and the "Wing" name would be recorded as the "ward" when recording the admission for a resident.

Often PainChek is trialled at one or two sites prior to a full rollout. During this phase, the RCS must maintain a whitelist of sites and only synchronise data for those sites.

In the diagram above, you can see that sites "A" and "C" are whitelisted and hence they are the only sites whose data (i.e. resident records) is sent to PainChek.

There are two fundamental approaches that can be adopted when trying to sync two systems, such as the RCS and PainChek. When a relevant change to a resident record is detected on the RCS system, either:

In an ideal world, both of these approaches achieve the same result. However, the former approach, whilst simpler and potentially easier to implement, is far more fragile. If the systems ever get out of sync, it may be difficult to get them to realign.

For this reason, when synchronising resident details, we strongly recommend the latter approach.

In addition, the later logic can also be utilised for initial data migrations (there is no need to replay a list of all events that have occurred on the PCS, we simply need to iterate through all PCS resident records and apply the compare & sync logic).

The integration process should handles failures gracefully. If the PainChek API is down, for instance, the process must maintain its state and/or queue new events and process the changes when PainChek is back online.

This is another reason why the second approach to synchronising data (where we compare the resident details recorded on both the RCS and on PainChek and perform all actions required to ensure PainChek is in sync) is beneficial. If the synchronisation process fails at any stage, it can be restarted without trying to recover to the exact point of failure.

To simplify the integration with PainChek, a number of bespoke "integration" endpoints have been developed. Where available, these bespoke endpoints should always be used as they will minimise the work required to integrate with PainChek.

See Integration Endpoints for more details on the available endpoints and how they are used.

Both the RCS and PainChek systems will record the same entities (e.g. residents and sites) and hence there needs to be a means to link the records together.

This is achieved by ensuring that when the RCS is creating records in PainChek, the RCS identifier is supplied to PainChek. This is achieved by passing the "external_id" field in the payloads for the PainChek API.

The RCS could also choose to record the PainChek unique identifier (provided in the "uuid" field of the responses from the PainChek API), but this is generally not required. The RCS identifier can always be used to fetch the details for a PainChek record should that prove necessary (e.g. for a "patient" by invoking a GET to "../api/patients/external_id={RCS Id}").