In the high-level project phases document, a high-level description is given for the functionality of the CRC project. In this document we’ll describe the integration and interaction between the systems that will be used to implement the first phase, with an eye toward evolving the system in the future.
The Synapse data set should include all the relevant information we collect about participants, including test results. We cannot recover this information later so this must be present even in phase I.
Ideally we’d like users to interact with one identifiable website as participants in this study; we may not reach this in phase I. Because we’ll be switching how people submit samples for lab work, we may be able to achieve this in phase II.
Our external partner for this work is Columbia University Irving Medical Center (CUIMC) OHC. Their system is a part of the overall workflow we are supporting for this project. They have requested that we use HTTP Basic Authentication to authenticate their calls. We will need to create endpoints where we validate their credentials and perform some work. All the functionality exists in Bridge, it would just need to be orchestrated differently.
Questions for CUIMC: is there any rate-limiting? Also, we should record a timestamp for the last state change so we can see (They call us now in all cases, so this hasn’t been an issue.)
Workflow State
The Bridge Account object should be tagged with one (and only one) of the following data groups:
State | Description | Transitions to |
|---|---|---|
<no state> | Accounts should be created with no state. The account exists, but is not consented to participate in the study. | enrolled |
enrolled | When the participant consents to the default consent, we add the | selected, declined |
declined | Researchers have decided this person should not be asked to have lab work done | |
selected | Researchers have indicated this person should get lab work done. | tests_requested |
tests_requested | The worker process or API call to Bridge has created a lab order with the lab, which triggers a message from the lab to go schedule an appointment. | tests_scheduled |
tests_scheduled | CUIMC has verified that the participant has scheduled to have their lab work done. Save this information as a participant report (“appointment” at 1970-01-01) and update the participant to | tests_collected |
tests_cancelled | CUIMC has sent an appointment record with a status field of “cancelled.” (The other known state is “booked” for when an appointment has been scheduled). | Possibly back to tests_scheduled if user reschedules |
tests_collected | CUIMC has verified that the participant has had lab specimens collected, and they are currently being processed. Save this information as a participant report (“collection” at 1970-01-01) and update the participant to | tests_available |
tests_available | CUIMC has verified that tests results are available by submitting them to Bridge, where they have been saved as health data. Bridge will be able to show these results through the patient portal using access to health data raw data API being developed. We also update the participant to | tests_notified |
tests_available_type_unknown | CUIMC has sent us observation JSON, but it’s for a test of a type we don’t know and didn’t expect to receive. | |
tests_notified | The UI can look at this state and adjust the UI to highlight test results, as this is one of the main benefits for participants (the test results). |
I would also record a timestamp in a There’s a state_change_timestamp attribute field, since Wendy’s group will want to know how long someone has been in some states if they are trying to ensure compliance with the protocolin each participant, indicating the last time that either Synapse or CUIMC have updated the participant record through the CRC specific endpoints. The state transitions occur through the following agents:
State | Agent & API |
|---|---|
<no state> | The participant completes the consent, and the |
enrolled | The research team signs into a Synapse UI and reviews all the |
declined | <end state> |
selected | A script written by Megha periodically depends this in Synapse and calls to update the Bridge participant by calling the /v1/cuimc/participants/{userId}/laborders endpoint. This marks the Bridge account as Periodically, CUIMC polls the Bridge server to search for |
tests_requested | The user must then schedule for lab work. When this is completed, the CUIMC system will call back Bridge with an FHIR |
tests_cancelled | If the user has scheduled for lab work, and later cancels, we’ll get an updated FHIR |
tests_scheduled | The user goes to the lab to get specimens collected. CUIMC calls Bridge to notify us that the specimens have been collected and are being processed with a |
tests_collected | When the lab is done processing the specimens, CUIMC will send back an |
tests_available | This state ensures the participant will not be examined again by our worker. The UI can use this data group to highlight testing since it’s available and should be stored in the StudyParticipant |
Sequence Diagram
...
Data Persistence
All the data being submitted for this project needs to be in Synapse, and it needs to be accessible to the participants and researchers. Normally research data is not accessible to the Bridge system. The issue with this is that the calls are not atomic... they can succeed in one call but fail in another, leaving the system in an inconsistent state.
...
API to submit appointment information for a user that will move the state of the user to TESTS_SCHEDULED;
API to submit the fact that the labs have been collected, which moves the state of the user to TESTS_COLLECTED;
API to submit the tests results of the labs that submits the data to our health data API and moves the state of the user to TESTS_AVAILABLE.
Worker Process
We will need a worker process to initiate some of the workflow state transitions, such as notifying Columbia’s lab when we wish to schedule someone for bloodwork.
The message that triggers the worker process can be simple since it’ll work on the state of accounts, rather on time ranges:
...
| language | json |
|---|
...
Synapse has a client that is calling an endpoint to update Bridge records. CUIMC is using a normal Bridge account to sign in and access participant records.