Maps the information specified in a study protocol to runtime configurations used by the 'clients' subystem to run the protocol on concrete devices (e.g., a smartphone) and allow researchers to monitor their state. To start collecting data, participants need to be invited, devices need to be registered, and consent needs to be given to collect the requested data.
The following diagram depicts a typical sequence of calls to application services in the deployments subsystem to create a study deployment, invite participants, and deploy it successfully on a client device.
The events between DeploymentService and ParticipationService are opaque to the user and are merely an implementation detail.
The application and domain services in carp.studies and carp.client abstract away this entire sequence.
Matching code for these calls can be found in the main README as part of the carp.deployments and carp.client examples.
Most of the the DeploymentService endpoints return the current status of a study deployment after the requested operation has been executed.
Depending on the current state of the deployment, different operations are available.
This is represented by StudyDeploymentStatus, which reflects the underlying state machine:
The overall deployment state depends on the aggregate of individual device deployment states.
Each device within the study deployment has a corresponding DeviceDeploymentStatus:
The 'Require' and 'Grant' column lists claim-based authorization recommendations for implementing infrastructures. Respectively, the required claims and claims to grant upon a successful request.
Allows deploying study protocols to participants and retrieving primary device deployments for participating primary devices as defined in the protocol.
| Endpoint | Description | Require | Grant |
|---|---|---|---|
createStudyDeployment |
Instantiate a study deployment for a given protocol with invited participants. | manage deployment: studyDeploymentId, in deployment: studyDeploymentId |
|
removeStudyDeployments |
Remove study deployments and all related data to it. | manage deployment: (all) studyDeploymentId |
|
getStudyDeploymentStatus |
Get the status for a study deployment. | in deployment: studyDeploymentId |
|
getStudyDeploymentStatusList |
Get the status for a set of deployments. | in deployment: (all) studyDeploymentIds |
|
registerDevice |
Register a device for a study deployment. | in deployment: studyDeploymentId |
|
unregisterDevice |
Unregister a device for a study deployment. | in deployment: studyDeploymentId |
|
getDeviceDeploymentFor |
Get the deployment configuration for a primary device in a study deployment. | in deployment: studyDeploymentId |
|
deviceDeployed |
Indicate to stakeholders in a study deployment that a primary device was deployed successfully, i.e., that the study deployment was loaded on the device and that the necessary runtime is available to run it. | in deployment: studyDeploymentId |
|
stop |
Stop a study deployment. No further changes to this deployment will be allowed and no more data will be collected. | in deployment: studyDeploymentId |
Allows retrieving participations for study deployments, and managing data related to participants which is input by users.
| Endpoint | Description | Require | Grant |
|---|---|---|---|
getActiveParticipationInvitations |
Get all participations of active study deployments a specified account has been invited to. | authenticated: accountId |
|
getParticipantData |
Get currently set data for all expected participant data. | in deployment: studyDeploymentId |
|
getParticipantDataList |
Get currently set data for all expected participant data for a set of study deployments. | in deployment: studyDeploymentId |
|
setParticipantData |
Set participant data for a specified study deployment. | in deployment: studyDeploymentId |