Two step participant registration process

1 Introduction
2 Handling Matches
3 Handling No Match
4 Steps to Configure Two-step participant registration process
- 4.1 A. Setting Spring bean name at the System level
- 4.2 B. JSON Configuration
  - 4.2.1 Steps to set up JSON configure at the CP level
  - 4.2.2 Steps to set up JSON configure at the System level
5 JSON Example
- 5.1 Lookup JSON for MRN and MRN Site
- 5.2 Lookup JSON for eMPI and Registration Site
6 Steps to lookup and register the EMR participants
- 6.1 Steps to register EMR participants based on MRN and MRN site
7 Allow non-EMR patient registration
- 7.1 Steps to allow registration of non-EMR patients
8 Locking the retrieved fields
- 8.1 Example JSON code

Introduction

This feature is useful when patient data is available from another system, such as an EMR, patient registry, or another system. In the standard workflow (single-step registration), a user manually creates a participant profile and immediately registers them to a study. This step leads to duplicate data entry, human errors, stale data when the source is edited (multiple sources of truth), etc.

To avoid this, OpenSpecimen supports a “Two-step participant registration” workflow where:

Data from the external system is stored in a staging table
User has to enter the MRN to look up the patient details
Review the matches and register the patient

This feature is useful when participant data originates from an external source, such as an EMR (e.g., Epic, Cerner) or a patient registry.

In the standard single-step registration workflow, users have to manually create a participant and register them to a CP. This leads to duplicate data entry effort and errors.

To eliminate these issues, OpenSpecimen supports a “Two-Step Participant Registration” workflow:

Step 1 (Staging Data): Participant data from external systems should be stored in a designated staging table (this must be done by the customer via SQL queries).
Step 2 (Participant registration):
- The coordinator searches for the participant using their Medical Record Number (MRN).
- OpenSpecimen fetches the matched staging record.
- The coordinator reviews the details and registers the patient to the specific Collection Protocol.

Gliffy Diagram

Handling Matches

User enters the patient identifier fields (like MRN) to search for matching participants.
OpenSpecimen displays matching participants from EMR
Data fetched from EMR will be displayed in read-only format
User selects the match and proceeds to the next step.

Handling No Match

If no match is found, then you have two options:

Let the user create a new participant (useful in cases where you recruit external patients)
Disable creating new participants (i.e. patient has to be in EMR)

Steps to Configure Two-step participant registration process

To configure two-step participant registration, you need to first configure the “spring bean name” for participant lookUp at the system level followed by JSON configuration.

A. Setting Spring bean name at the System level

You need to add the "spring bean name" to the 'Participants LookUp Workflow' in the system's setting to allow OpenSpecimen to LookUp participants on the staging table.

Go to Homepage → Settings → Search 'LookUp'.
Select property 'Participants LookUp Workflow ' → Add value 'bean: stagedParticipantsDbLookup' → 'Update'.

B. JSON Configuration

The fields that need to be used for lookup have to be set with property: "participantLookup": true on your JSON workflow. The JSON can be configured on any of the following levels: individual CP or system.

Steps to set up JSON configure at the CP level

Go to the CP overview page → More → Export Workflows. Open the file on the editor of your choice → Set the property: "participantLookup": true for the fields that need to be used for lookup as shown below in the JSON example→ Save it. Go back to the CP overview page → Import Workflows → Upload the updated file → Import.

Steps to set up JSON configure at the System level

Go to the Homepage → Settings → Search 'System Workflows' →Download the workflow. Open the file on the editor of your choice → Set property: "participantLookup": true for the fields that need to be used for lookup as shown below in the JSON example→ Save it. Go back to the “System WorkFlows” →Upload the updated file → Update.

JSON Example

Lookup JSON for MRN and MRN Site

[ { "name" : "dictionary", "view" : null, "ctrl" : null, "data" : { "fields" : [ { "name" : "cpr.participant.pmis", "type" : "collection", "participantLookup" : true, "fields" : [ { "name" : "siteName", "caption" : "MRN Site", "type" : "dropdown", "multiple" : false, "optional" : true, "participantLookup" : true, "listSource" : { "apiUrl" : "sites", "displayProp" : "name", "selectProp" : "name", "queryParams" : { "dynamic" : { "operation" : "op" }, "static": { "listAll": true }, "search" : "name" } } }, { "name" : "mrn", "caption" : "MRN", "type" : "text", "optional" : true } ] }, { "name" : "cpr.registrationDate", "caption" : "Registration Date", "type" : "date", "optional" : false, "defaultValue" : "current_date" }, ......... ......... Sample JSON

Lookup JSON for eMPI and Registration Site

[ { "name":"dictionary", "data":{ "fields":[ { "name":"cpr.participant.empi", "caption":"Master Patient Index", "type":"text", "participantLookup":true, "optional":true, "showIf":{ "rules":[ { "field":"mpiFmt", "op":"not_exist" } ] } }, { "name":"cpr.site", "caption":"Registration Site", "type":"dropdown", "participantLookup":true, "optional":true, "listSource":{ "apiUrl":"collection-protocols/{{cp.id}}/sites", "displayProp":"name", "selectProp":"name", "queryParams":{ } } }, { "name":"cpr.registrationDate", "caption":"Registration Date", "type":"date", "optional":false, "defaultValue":"current_date" }, { "name":"cpr.externalSubjectId", "caption":"External Subject ID", "type":"text", "optional":true }, ......... ......... Sample JSON

Steps to lookup and register the EMR participants

Once all the configuration is complete. You can start registering the EMR participants from the staging table to the CP of your choice.

Steps to register EMR participants based on MRN and MRN site

Go to the CP List view page → Add Participant. Enter the MRN site and MRN number for the participant → LookUp. If a match is found, it will show a message saying ‘Following participant found. Please review the details and save'. You can review the details and click on 'Add Partcipant’ to register the participant. If a match is not found, it will give an error saying 'No matching participant is found'.

Allow non-EMR patient registration

By default, users can ONLY register participants present in EMR. However, it is possible to allow users to register participants not present in EMR.

Steps to allow registration of non-EMR patients

Go to Homepage → Settings → Search 'Add Participant on No Match'. Select property ‘Add Participant on No Match' → Select 'Enabled’ → 'Update'.

When registration of non-EMR patients is not allowed

When registration of non-EMR patients is allowed

Locking the retrieved fields

The retrieved fields can be locked (read only) at the participant level on Openspecimen UI. The source of the fields is the name of the DB from where the participant data is being populated. In the example below, the source is 'ASIG'. In the OpenSpecimen database table catissue_participant, the source column for the participants should be 'ASIG' so that the fields will be locked. This JSON should be set at the system level since the participants are registered across CPs. Example JSON code { "name": "locked-fields", "data": { "participant": { "ASIG": [ //this is the source from where the data is populated "cpr.ppid", "cpr.participant.vitalStatus", "cpr.participant.deathDate" ] } } } Screenshot: