...
For the first time the server will need to have knowledge of the participant’s time and time zone;
Because this information depends on the time of the request, it is not very cacheable;
Nevertheless, the reports probably update infrequently (the exact amount depends on many factors), while they may be read frequently in a couple of different formats.
APIs
...
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.
Each report builds on the latter report.
EventStream Report (all adherence data for one participant)
The windows include the state of that session (which is the basis for adherence calculation). The states are:
...
State
...
Description
...
Adherence
...
not_applicable
...
Participant does not have this event in their events, so these sessions will not currently ever be shown to the participant.
...
N/A
...
not_yet_available
...
Participant should not have seen or started this session. It’s in the future.
...
N/A
...
unstarted
...
Participant should see the session (they are being asked to do it now), but they have not started it.
...
unknown
...
started
...
Participant has started the session.
...
unknown
...
completed
...
Participant completed the session before it expired.
...
compliant
...
abandoned
...
Participant started or finished at least one assessment in the session, but there was more work to do and it expired before they finished it.
...
noncompliant
...
expired
...
Participant did not start the session and it is now expired.
...
noncompliant
We can calculate a compliance percentage from these values at the session level, for the week, in the next report.
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 includes the date for “today” (I don’t propose this timestamp will Persistent time windows will be excluded from all adherence reports. Completing assessments that are part of a persistent window do not count for or against adherence.
All of these views operate on the most recent timestamps for all events. Building schedules that rely on a mutable event changing, and triggering a new timeline of sessions to perform, will not work with these adherence APIs. That would be events like “session type X has been completed.” OTOH, it will show compliance with the most recent time stream, and that might be all that matters. Past time streams are no longer actionable.
APIs
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. |
Each report builds on the latter report.
EventStream Report (all adherence data for one participant)
The windows include the state of that session (which is the basis for adherence calculation). The states are:
State | Description | Adherence |
|---|---|---|
not_applicable | Participant does not have this event in their events, so these sessions will not currently ever be shown to the participant. | N/A |
not_yet_available | Participant should not have seen or started this session. It’s in the future. | N/A |
unstarted | Participant should see the session (they are being asked to do it now), but they have not started it. | unknown |
started | Participant has started the session. | unknown |
completed | Participant completed the session before it expired. | compliant |
abandoned | Participant started or finished at least one assessment in the session, but there was more work to do and it expired before they finished it. | noncompliant |
expired | Participant did not start the session and it is now expired. | noncompliant |
We can calculate a compliance percentage from these values at the session level, for the week, in the next report.
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 reportsreports—so it’ll have to be a date on the server). This means that the individual sessions listed in this report are not on the same lined up by calendar date. The structure of this report would be as follows:
| Code Block | ||
|---|---|---|
| ||
{
"participant": {
"firstName": "A-chan",
"email": "alx.dark+achan@sagebase.org",
"externalId": "asdfasdf",
"identifier": "GqYpNUWolebxS2eQudF1hc-a",
"type": "AccountRef"
},
"createdOntimestamp": "2021-11-22T2122T22:0212:2455.052Z769Z",
"weeklyAdherencePercent": 100,
"dailyReports": [
{
"day": 0,
"sessions": [
{
"sessionGuid": "LcWpQFKaGY5FSQ0LT4tnvdO7",
"label": "Session #1 / Week 1 / Study Burst 1",
"symbol": "1",
"startDay": 70,
"startDate": "2021-11-1621",
"timeWindows": [
{
"sessionInstanceGuid": "jX9oQDeCJhGvI5Ee76obsQ1aCbUaFYkixIsIJBf9WGpg",
"timeWindowGuid": "GNp94CnfTTtR-s0OzrFeftrh",
"state": "expired",
"endDay": 70,
"endDate": "2021-11-1621",
"type": "EventStreamWindow"
},
{
"sessionInstanceGuid": "QIi64sd_gZYbA5fgLau8igyQnubrShfYMY9ZzOE3zw3Q",
"timeWindowGuid": "aRaHNKIY0yKgOl5CLuA3ZDHJ",
"state": "expired",
"endDay": 70,
"endDate": "2021-11-1621",
"type": "EventStreamWindow"
}
],
"type": "EventStreamDay"
},
{
"sessionGuid": "eRLgI5gfe1kef_XRZDfdFU9I",
"label": "Session #2 / Week 1",
"symbol": "2",
"startDay": 70,
"startDate": "2021-11-1621",
"timeWindows": [
{
"sessionInstanceGuid": "MzqzKXnkfIrcSiwkH7YjigbDBVV02XrjrOG8NgBYSYFg",
"timeWindowGuid": "KZ1piANVdeD-r8PCHL2bviLh",
"state": "expired",
"endDay": 70,
"endDate": "2021-11-1621",
"type": "EventStreamWindow"
}
],
"type": "EventStreamDay"
},
{
"sessionGuid": "z_jb4p2Lr9Q56z8AwiYNieqw",
"label": "Session #3 / Week 2",
"symbol": "3",
"startDay": 9,
"startDate": "2021-11-24",
"timeWindows": [
{
"sessionInstanceGuid": "WHE_gHE71tk8qFERatcruA",
"timeWindowGuid": "gF6hy-UiipJLXqe7F_yK-wQc",
"state": "started",
"endDay": 9,
"endDate": "2021-11-24",
"type": "EventStreamWindow"
}
],
"type": "EventStreamDay"
}
],
"type": "DailyAdherenceReport"
},
{
"day": 1,
"sessions": [
{
"sessionGuid": "LcWpQFKaGY5FSQ0LT4tnvdO7",
"label": "Session #1", / Week 1 / Study Burst 1",
"symbol": "1",
"startDay": 81,
"startDate": "2021-11-1722",
"timeWindows": [
{
"sessionInstanceGuid": "CS8QpTlrTSJdOE39U7SfKQ7HaIdOehYJrJk3VZcGeNxg",
"timeWindowGuid": "GNp94CnfTTtR-s0OzrFeftrh",
"state": "expiredunstarted",
"endDay": 81,
"endDate": "2021-11-1722",
"type": "EventStreamWindow"
},
{
"sessionInstanceGuid": "aeVdiKislHPpC2w0VBn5fgR0I7n1fEeIR88fYv6iVPTg",
"timeWindowGuid": "aRaHNKIY0yKgOl5CLuA3ZDHJ",
"state": "expiredunstarted",
"endDay": 81,
"endDate": "2021-11-1722",
"type": "EventStreamWindow"
}
],
"type": "EventStreamDay"
},
{
"sessionGuid": "eRLgI5gfe1kef_XRZDfdFU9I",
"label": "Session #2 / Week 1",
"symbol": "2",
"startDay": 81,
"startDate": "2021-11-1722",
"timeWindows": [
{
"sessionInstanceGuid": "K-P_nDWic33zjrxtlABE6Qu-cc8Ou4xqUPVnht4oh-bw",
"timeWindowGuid": "KZ1piANVdeD-r8PCHL2bviLh",
"state": "expiredunstarted",
"endDay": 81,
"endDate": "2021-11-1722",
"type": "EventStreamWindow"
}
],
"type": "EventStreamDay"
},
{
"sessionGuid": "z_jb4p2Lr9Q56z8AwiYNieqw",
"label": "Session #3 / Week 2",
"symbol": "3",
"startDay": 12,
"startDate": "2021-11-27",
"timeWindows": [
{
"sessionInstanceGuid": "2O-jPnpWOYZLx0VjBvvO8g",
"timeWindowGuid": "gF6hy-UiipJLXqe7F_yK-wQc",
"state": "not_yet_available",
"endDay": 12,
"endDate": "2021-11-27",
"type": "EventStreamWindow"
}
],
"type": "EventStreamDay"
}
],
"type": "DailyAdherenceReport"
},
// etc...
{
"day": 6,
"sessions": [
{
"sessionGuid": "LcWpQFKaGY5FSQ0LT4tnvdO7",
"label": "Session #1", / Week 1 / Study Burst 1",
"symbol": "1",
"startDay": 136,
"startDate": "2021-11-2227",
"timeWindows": [
{
"sessionInstanceGuid": "FHBhnKvSxoNXk9ubiWJVSwIUBXsO4ioFgJfi8GA9NSxw",
"timeWindowGuid": "GNp94CnfTTtR-s0OzrFeftrh",
"state": "unstartednot_yet_available",
"endDay": 136,
"endDate": "2021-11-2227",
"type": "EventStreamWindow"
},
{
"sessionInstanceGuid": "PzplumYKek685k_DUU1lqgWdRjHkDWoqmQx4vxRuCVeg",
"timeWindowGuid": "aRaHNKIY0yKgOl5CLuA3ZDHJ",
"state": "completednot_yet_available",
"endDay": 136,
"endDate": "2021-11-2227",
"type": "EventStreamWindow"
}
],
"type": "EventStreamDay"
},
{
"sessionGuid": "eRLgI5gfe1kef_XRZDfdFU9I",
"label": "Session #2 / Week 1",
"symbol": "2",
"startDay": 136,
"startDate": "2021-11-2227",
"timeWindows": [
{
"sessionInstanceGuid": "Kz1NQRlXiDnW_viqoGYfJA-1AlFrrN9IfA5tK-OYvag",
"timeWindowGuid": "KZ1piANVdeD-r8PCHL2bviLh",
"state": "unstartednot_yet_available",
"endDay": 136,
"endDate": "2021-11-2227",
"type": "EventStreamWindow"
}
],
"type": "EventStreamDay"
}
],
"type": "DailyAdherenceReport"
}
],
"type": "WeeklyAdherenceReport"
} |
Persistent time windows will be excluded from all adherence reports. Completing assessments that are part of a persistent window do not count for or against adherence.
All of these views operate on the most recent timestamps for all events. Building schedules that rely on a mutable event changing, and triggering a new timeline of sessions to perform, will not work with these adherence APIs. That would be events like “session type X has been completed.” OTOH, it will show compliance with the most recent time stream, and that might be all that matters. Past time streams are no longer actionable.
"type": "WeeklyAdherenceReport"
} |
The user-specific API will persist this data when it is calculated before returning the report so it can be retrieved as part of a wider study-scoped adherence report. The SQL table for this report will not attempt to store the report normalized.:
| Code Block | ||
|---|---|---|
| ||
CREATE TABLE `WeeklyAdherenceReports` (
`appId` varchar(255) NOT NULL,
`studyId` varchar(255) NOT NULL,
`userId` varchar(255) NOT NULL,
`createdOn` bigint(20) unsigned NOT NULL,
`weeklyAdherencePercent` int(3) unsigned NOT NULL,
`json` mediumtext NOT NULL,
PRIMARY KEY (`appId`, `studyId`, `userId`),
CONSTRAINT `WeeklyAdherenceReports-Study-Constraint`
FOREIGN KEY (`studyId`, `appId`)
REFERENCES `Substudies` (`id`, `studyId`) ON DELETE CASCADE,
CONSTRAINT `WeeklyAdherenceReports-Account-Constraint`
FOREIGN KEY (`userId`)
REFERENCES `Accounts` (`id`) ON DELETE CASCADE,
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; |
Weekly Adherence Reports for Study
...