...
Method | Path (Under /v5/studies/{studyId} | Description |
|---|---|---|
GET | /participants/{userId}/adherence/eventstream | List of SessionStream reports for one user. The only view that shows scheduling for events the user does not have, this is a detailed view for one user of the whole schedule. |
GET | /participants/{userId}/adherence/weekly | A single WeeklyAdherenceReport for one users. This API would generate and persist this report before returning it in the call, so that this call can be used by a worker process to build a record for every participant, but the call could also be called for up-to-date state information on a specific participant. |
GET | /participants/adherence/weekly | A paged list where each record is a WeeklyAdherenceReport for one user. If no call has generated this report, it is not generated as part of this call, so a worker process will need to periodically generate these out-of-request. |
GET | /v1/apps/{appId}/studies/{studyId} | Worker endpoint to create and persist the weekly report for users, to enable the paged view across all accounts. |
Each report builds on the latter report.
EventStream Report (all adherence data for one participant)
This is what the JSON would like like:
...
We can calculate a compliance percentage from these values across a participant’s entire participation in the study. In the weekly report below, we can calculate adherence for that week alone.
Weekly Adherence Report
This report always returns seven days of adherence records for a given user. The report calculates this information by finding the “week since event N” for every event and every session, that is the week that has the day that falls on “today” (this timestamp won’t be adjustable since every timestamp would require a recalculation of all these reports—so it’ll have to be a date on the server). This means that the individual sessions listed in this report are not lined up by calendar date. The structure of this report would be as follows:
...
The “labels” column will pull out the labels from the JSON into a pipe-delimited string, to enable searching for records that match the label (this is a design requirement) in the study-scoped API.
Weekly Adherence Reports for Study
The weekly adherence API for a user will persist the report. Another API will allow an admin to retrieve all these records using a paging API that is similar to the study participants search API. Those search criteria will be used to retrieve the page of user IDs, and then those will be used to retrieve and sort the appropriate set of adherence reports. If the adherence report hasn’t been requested for a specific user, it will come back empty. (A worker process will be created to run through users nightly and regenerate these reports, but the weekly adherence report API will accomplish the same refresh for one user).
...