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

When integrated with EMRs like Epic, the Participant registration process can be configured to be done in a two-step process.

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: