Participant study adherence

This is a v2 science API. These APIs are currently being implemented. Some features described in “Evolution of the Bridge System” are not yet available.

Adherence Records

The third and final part of the Bridge scheduling system are AdherenceRecords. These records support schedule state management on mobile clients, and they are the basis for adherence reporting to study administrators.

This collection of records is sparse; if the participant does not do a scheduled session or assessment, there will not be a record for that session or assessment in the set of records. Furthermore, these records are persisted by the client, so they will only exist if the client updates the server on the current state of timeline performance.

Updating adherence records and persistent time windows

Clients are expected to update the assessment adherence records. The server will create and/or update session adherence records based on the state of the assessments in each occurrence of a session. The server manages the startedOn, finishedOn, and declined fields:

• The startedOn timestamp will be set to the earliest startedOn timestamp of any assessment in that session instance once any assessment is started;
• The finishedOn timestamp will be set to the latest finishedOn timestamp of any assessment in that session instance, when all the assessments are finished (unless any assessment in the session instance is declined, see below);
• The declined boolean will be set to true if all the assessments in the session instance have been declined;
• Sessions with any number of declined or unstarted assessments will be left in the started but not finished state (and thus be out of compliance).

Clients can also submit session adherence records in order to update fields like clientData and clientTimeZone. For example, there may be state that is more accurately related to an entire session rather than individual sessions, that would most logically stored as clientData on a session instance adherence record.

An assessment adherence record would look like the following:

{
  "instanceGuid":"7PVMTOm6ga4w3mGYudQFCg",
  "startedOn":"2020-05-10T10:32:12.937Z",
  "finishedOn":"2020-05-10T10:38:39.192Z",
  "eventTimestamp":"2020-05-09T16:43:33.431Z",
  "clientData": {
    "testResult": 100.23
  },
  "assessmentGuid": "D2DKsx9NOuZ8vGrT-yidhA",
  "type":"AdherenceRecord"
}

Adherence records are specific to a participant in a given study. However, persistent time windows (where a user is allowed to perform a set of assessments as many times as they want within the time window) change the behavior of adherence records in some subtle ways.

The primary key for assessments scheduled through non-persistent time windows includes the instanceGuid and the eventTimestamp. For a scheduled assessment in a given event time stream, there can be only one adherence record. The primary key for assessments scheduled through persistent time windows includes the instanceGuid, eventTimestamp, and startedOn value of the record, so such a scheduled assessment can produce more than one adherence record.

So while all state fields in a non-persistent time window adherence record can be updated by resubmitting the record with different values, the startedOn field in a persistent time window adherence record, when it is changed in this manner, will simply create a new adherence record. Because changing timestamps in adherence records is mostly needed when developing and testing mobile clients, we recommend in this situation that you delete an adherence record before recreating it.

Once assessment records start to be added or updated for a session, the server will update the session record’s startedOn, finishedOn, or declined values in the following manner:

1. When any assessment in a session is started, and the session has not been started, the session will be started with the earliest startedOn assessment value in the session;
2. When all assessments in a session are finished, and the session has not been finished, the session will be finished with the latest finishedOn assessment value in the session;
3. If all assessments in a session are declined, and the session has not been declined, the session will be marked as declined.

If a session adherence record does not exist, one will be created to record this information.

To prevent overwriting user-submitted values, once these session fields are set, the server will not update them again. For example, if an assessment updated with an earlier startedOn timestamp, the session will not reflect it, or if a finishedOn timestamp is updated after all assessments in a session have been finished, this will not be reflected in the session. To change the session record, update the session record directly. For example, you might always submit the session record with null startedOn, finishedOn and declined fields if you want the server to check and update these values with every state change.

Querying for adherence records

The adherence record query API and adherence record query for participants API allows for a wide variety of filters to be applied when searching for the adherence records a participant (records are always scoped to a participant in a particular study). The study-scoped adherence record query API allows study administrators to search across all the adherence records for all participants in a study.

Here is an example of the search object:

{
  "instanceGuids":["dAGKM4nN39cDbyADic_bDNXs"],
  "assessmentIds":[],
  "sessionGuids":[],
  "timeWindowGuids":[],
  "adherenceRecordType":"session",
  "includeRepeats":true,
  "currentTimestampsOnly":true,
  "eventTimestamps":{
    "clinic_visit":"2015-01-26T23:38:32.486Z"
  },
  "startTime":"2015-01-26T23:38:32.486Z",
  "endTime":"2015-01-27T01:38:32.486Z",
  "offsetBy":0,
  "pageSize":100,
  "sortOrder":"asc",
  "type":"AdherenceRecordsSearch"
}

AdherenceRecordSearch

If none of these search values are set, all records will be returned.

To see how these search options can be used to retrieve different useful subsets of the adherence data, it helps to look at a concrete example of some data as it could be collected from a sample schedule. In the following examples, we will work with data that was collected as a result of the following example-timeline.json:

Session 1 starts with enrollment, and has two time windows which create two session instances every 3 days (after a 2 day delay). Both sessions include only Assessment A, but the afternoon session is persistent, so the user can perform the assessment as many times as they want in the session’s window.

Session 2 is triggered by an event (the client or some other API consumer creates or updates the custom:trigger event). Each time this event timestamp is added or updated on the server, the app will ask for Assessment A and then Assessment B on a weekly schedule. This time series can occur more than once, because custom:trigger is a mutable event, and will then go for the duration of the study, which is four weeks. So these timelines can extend beyond the end of the earliest timestamp (such as enrollment). Each sequence can be differentiated from the others because the instances will be grouped by the same eventTimestamp value.

Session 3 creates one time window that never expires, with an assessment that is persistent. In effect, the participant can do Assessment B whenever they like.

Given this timeline, here is one potential set of data that could be collected for a user who was very diligent in completing their scheduled sessions:

There are a few things of note in this data set:

1. On May 18th and May 27th, the participant did their afternoon Session #1 assessment more than once;
2. On May 18th, the trigger event started Session #2 and a sequence of four sessions. Then on September 3rd, the event timestamp was updated, and the participant was prompted to complete the four sessions of Session #2 again, under a different event timestamp;
3. The participant did Assessment B as part of Session #3 a total of five times. These differ only in their createdOn timestamps.

Given this data set, let’s look at the options for how to retrieve these records through the adherence APIs.

By instance GUIDs

Querying by instance GUID is possible, but not as useful as it might appear since instance GUIDs can be repeated in some circumstances.

{
  "instanceGuids":[
    "pKUAWjp3Lt6MSQCotkHaeg",
    "PFLNzqgiSLiM1pVQLihG5A",
    "JX0ClGqZ-_KVz10x3LLFbA",
    "KUt0q5qvK5zfl1SwMBe-cA",
    "F-kbi5VXYqKIw7BdrQGRgQ",
    "Ca353c2ZH7d4Dlrs4LvLBw",
    "tZNpSCQhD18wy0UricUOBA"
  ],
  "type": "AdherenceRecordsSearch"
}

Would retrieve the following records:

These results might not be entirely satisfactory since the consumer may have wished to address specific records in specific time streams, or specific records in a stream of persistent assessments. In this case, search criteria can be refined, or the client can use a more specific format for addressing record instances that incorporates the startedOn value of the record into the instance GUIDs:

{
  "instanceGuids":[
    "pKUAWjp3Lt6MSQCotkHaeg@2020-05-12T10:13:38.345Z",
    "PFLNzqgiSLiM1pVQLihG5A@2020-05-18T18:45:02.569Z",
    "JX0ClGqZ-_KVz10x3LLFbA@2020-05-27T08:10:32.931Z",
    "KUt0q5qvK5zfl1SwMBe-cA@2020-05-25T13:01:23.456Z",
    "F-kbi5VXYqKIw7BdrQGRgQ@2020-06-01T13:16:28.982Z",
    "Ca353c2ZH7d4Dlrs4LvLBw@2020-09-24T20:34:12.673Z",
    "tZNpSCQhD18wy0UricUOBA@2020-05-20T18:12:03.915Z"
  ],
  "type": "AdherenceRecordsSearch"
}

This pulls up more specific records, but at the cost of needing to know the startedOn values of these records:

By assessment IDs

A query can retrieve records for an assessment type, as indicated by its ID, regardless of where those assessments were prompted for in the timeline. The identifier will apply to both shared and local assessments in a schedule. If you wish to differentiate between these assessments, you will need to change the assessment ID of the local (app-specific) assessment.

{
  "assessmentIds": [
    "assessment-a"
  ],
  "adherenceRecordType":"assessment",
  "type": "AdherenceRecordsSearch"
}

Retrieves the following records:

By session GUIDs

A query can retrieve all session instances of the same type by searching for the GUID of the session they were created from:

{
  "sessionGuids": [
    "oGO1ojQte74bEm_Ph8XZEA3z"
  ],
  "type": "AdherenceRecordsSearch"
}

Retrieves the following records:

By changing the adherenceRecordType flag you can limit these results to just the session or assessment records:

{
  "sessionGuids": [
    "oGO1ojQte74bEm_Ph8XZEA3z"
  ],
  "adherenceRecordType":"session",
  "type": "AdherenceRecordsSearch"
}

Retrieves the following records:

Get latest records only

Sessions with mutable events present a challenge for mobile clients. Once the time series has been performed by a participant, the timestamp can be updated, but the client will still receive the adherence records for the older time series, making it appear that the participant has completed the session. To prevent this, the client can send the current event timestamps to the server, and only records that were tied to that event timestamp will be returned:

{
  "sessionGuids": [
    "oGO1ojQte74bEm_Ph8XZEA3z"
  ],
  "eventTimestamps": {
    "trigger": "2020-09-03T14:23:32.452Z"
  },
  "type": "AdherenceRecordsSearch"
}

This returns only the most recent set of records. If there are no records returned for the given timestamp, the client knows the session series should be performed again.

To make this query simpler, the client can also set the currentTimestampsOnly flag to true, which will use all the current event timestamp values that are known to the server to filter this query. The only issue with using this flag over the explicit timestamps would be a case where the client and the server are not in sync with one another.

By time window

To find the performance of one time window in a session, you can refere to the time window’s GUID (note: this is not currently in the Timeline, only the Schedule, but it will be added):

{
  "timeWindows": [
    "Z39tJejSi_P70vjjcBVuWk36"
  ],
  "adherenceRecordType": "assessment",
  "type": "AdherenceRecordsSearch"
}

Retrieves the following records:

Repeat assessments can be removed with the includeRepeats flag:

{
  "timeWindows": [
    "Z39tJejSi_P70vjjcBVuWk36"
  ],
  "includeRepeats": false,
  "adherenceRecordType": "assessment",
  "type": "AdherenceRecordsSearch"
}

Retrieves the following records:

By time range

Queries can ask for records within a given time range (the values returned are based on the startedOn value of the records):

{
  "startTime": "2020-05-10T01:14:38.451Z",
  "endTime": "2020-05-17T16:57:01.196Z",
  "adherenceRecordType": "assessment",
  "type": "AdherenceRecordsSearch"
}

By Upload IDs

To get all adherence records associated with an upload, you can use the uploadId field:

{
  "uploadId": "FRV1VReEy_HzeF7RdFZImqTq",
  "type": "AdherenceRecordsSearch"
}

If you want to get all adherence records that are associated with multiple upload IDs, you can use the hasMultipleUploadIds flag. If you use this flag, you will need to specify both eventTimestampStart and eventTimestampEnd:

{
  "eventTimestampStart": "2020-05-10T01:14:38.451Z",
  "eventTimestampEnd": "2020-05-17T16:57:01.196Z",
  "hasMultipleUploadIds": true,
  "type": "AdherenceRecordsSearch"
}

Similarly, if you want to get all adherence records that are associated with no upload IDs, you can use the hasNoUploadIds flag. This flag also requires both eventTimestampStart and eventTimestampEnd:

{
  "eventTimestampStart": "2020-05-10T01:14:38.451Z",
  "eventTimestampEnd": "2020-05-17T16:57:01.196Z",
  "hasNoUploadIds": true,
  "type": "AdherenceRecordsSearch"
}

Post-Processing Attributes

If your study has a post-processing pipeline, you may want to record post-processing status and other information on adherence records. To do so, you will need

• Bridge account with the developer, researcher, study coordinator, or study designer role with access to the study
• study ID
• participant's health code
• instance Guid
• event timestamp
• assessment startedOn

The last 4 items on that list can be found as annotations in exported Synapse files, or object metadata in exported S3 files, under the names healthCode, instanceGuid, eventTimestamp, and startedOn respectively.

Bridge provides a special API to write only these post-processing attributes to the adherence record and not others. This way, your post-processing pipeline doesn't have to worry about any attributes outside of post-processing.

To call this API, send an HTTP POST to /v5/studies/{studyId}/participants/healthcode:{healthCode}/adherence/{instanceGuid}/{eventTimestamp}/postprocessing (or use your platform's SDK). Example request body:

{
  "postProcessingAttributes":{
    "arbitrary-key":"arbitrary value"
  },
  "postProcessingCompletedOn":"2023-06-08T12:34:56.789Z",
  "postProcessingStatus":"in_progress",
  "startedOn":"2023-06-06T22:59:27.308Z"
}

Attributes written this way will appear on Adherence records through any other Adherence API.

Adherence Reports

Bridge provides APIs for a few reports summarizing the adherence of study participants. These reports only report on the state of session instances in the schedules of one or more participants. There are no reports of assessment-level adherence data.

Because adherence reports contain a lot of information copied from the study schedule, we refer you to the object browser for full documentation; here we only describe fields in the reports that are unique to these reports.

Participant adherence reports

These reports are for a specific participant in the study.

Event Stream Adherence Report

The EventStreamAdherenceReport is an intermediate data structure that is calculated for use in other reports. It is available through both client-facing APIs and study coordinator APIs should it prove useful for creating other kinds of adherence reports.

EventStreamAdherenceReport

The EventStream objects map a set of activities to a particular “day since event N,” measuring the duration from the timestamp of the startEventId of the stream to the current day when the report is being generated (this date can be modified via the API call, though if it is not provided, the server uses the current time).

EventStream

The map of of byDayEntries maps a day since the event of the stream to an array of sessions that will start on that day. Each session is represented by a separate EventStreamDay object with these properties (the name of this object is unfortunate because there can be more than one of these objects in a day, but often enough there will only be one in the array).

EventStreamDay

The event stream window objects describe when the session ends and what the state of the session is for this participant. That is because different windows define discrete session instances with different scheduling:

EventStreamWindow

Study Adherence Report

This is the main adherence report for a participant, which shows overview of a participant’s adherence to the entire protocol of a study. (The event stream report is normalized into one stream of activities, based on the study’s studyStartEventId. Then those activities are broken down into weeks in the study.) It can be retrieved via the study adherence report API. Study coordinators can view adherence in terms of what day in the study the participant is currently at.

If events occur before the study’s studyStartEventId, the study adherence report will not break, but the participant will have sessions that occur before “Week 1” (that is, in “Week 0” or in negative weeks like “Week -2”). This indicates the study design is flawed insofar as the studyStartEventId is not the true start of the study for the participant.

StudyAdherenceReport

StudyReportWeek

The row entries are WeeklyAdherenceReportRow objects with information to display the EventStreamDay arrays in the byDayEntries map. The row object at index 0 describes the EventStreamDay at index 0 of the array, on every day of the week (where needed, empty day objects pad the arrays to maintain the correct index).

The searchableLabel field provides a string that can be used to filter the weekly adherence reports API to return only those participants who are in particular stages of the study. It is possibly to provide substrings of this searchableLabel to widen this search.

For example, the searchableLabel “:Session #2:Week 1:” will find all participants in week 1 of their session #2 work. You could also submit “:Session #2:” to find participants in any week where they are being asked to perform session #2 assessments. The colons are important to ensure correct substring matches (e.g. so you don’t get “Session #22” in your results).

Weekly Adherence Report

The WeeklyAdherenceReport can be retrieved through the weekly adherence report API (only available to study administrators). It is similar to the StudyReportWeek objects in the full study adherence report, but only the current week of that report is returned through this API. The WeeklyAdherenceReport also has some small differences. For example, it can be present for weeks that don't appear in the full adherence report at all, which can be sparse (it does not have weeks where the participant is not being asked to perform any assessments). In that case, the report may include information like the participant’s NextActivity. As well, if the participant has sessions from prior weeks that are still available and unfinished, these will be present on Day 0 of the weekly adherence report.

WeeklyAdherenceReport

The row entries are WeeklyAdherenceReportRow objects with information to display the EventStreamDay arrays in the byDayEntries map. The row object at index 0 describes the EventStreamDay at index 0 of the array, on every day of the week (where needed, empty day objects pad the arrays to maintain the correct index).

Study-level reports

Weekly Adherence Reports

The weekly adherence reports can be retrieved for all participants via the paginated weekly adherence reports API. This API returns a weekly adherence report for all active users in a study, and it has a number of search parameters in the API to adjust the results that are returned (most importantly, to find participants that are out of compliance with the study protocol).

The weekly adherence reports are generated one of three ways:

1. When a user calls for a participant’s entire study adherence report, their weekly adherence report is also calculated and persisted;
2. When a study administrator calls for a participant’s weekly adherence report, it is also calculated and persisted before being returned;
3. Bridge updates this record for every participant in a study at 4am and 11am in the local time zone set for that study (if no time zone is set for a study, the time zone used is Central Time in the United States), if the following conditions apply:
   • The study has a schedule and is in the design, recruitment or in_flight phase;
   • The participant has signed in at least once to the Bridge server.

The paged list of adherence for all users in their current week should be up-to-date as of the morning of the current day. It is important to not move your study to completed until you are certain all the participants are finished with the study, or you will lose adherence information.

Stats

Finally the study adherence stats API provides summary information about study adherence for all participants in a study. Participants who have not started the study are not included in these reports. The adherenceThresholdPercentage will be set to the Study.adherenceThresholdPercentage value unless a different value is provided as a query parameter to the API. The number of participants at or above the threshold, and under it, will be returned in the compliant and noncompliant counts (these should equal the totalActive count).

The AdherenceStatisticsEntry array includes a count of participants at every unique moment in the study (e.g., Week 3 of a particular session). Because participants can be in more than one part of the schedule on a given week, these counts will likely be greater than the sum of the totalActive value.