Maps the information specified in a study protocol to runtime configurations used by the 'client' 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 the DeploymentService endpoints to create a study deployment, invite participants, and deploy it successfully on a client device.
When using the application and domain services in carp.studies and carp.client these requests are abstracted away.
Matching code for these calls can be found in the main README as part of the carp.deployment 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 and retrieving master device deployments for participating master devices as defined in the protocol.
| Endpoint | Description | Require | Grant |
|---|---|---|---|
createStudyDeployment |
Instantiate a study deployment for a given protocol. | manage deployment: studyDeploymentId, in deployment: studyDeploymentId |
|
getStudyDeploymentStatus |
Get the status for a study deployment. | in deployment: studyDeploymentId |
|
getStudyDeploymentStatusList |
Get the statuses 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 master device in a study deployment. | in deployment: studyDeploymentId |
|
deploymentSuccessful |
Indicate to stakeholders in a study deployment that a master 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 inviting participants, retrieving participations for study deployments, and managing data related to participants which is input by users.
| Endpoint | Description | Require | Grant |
|---|---|---|---|
addParticipation |
Let a person with a specified identity participate in a study deployment, using a specified master device. | manage deployment: studyDeploymentId |
in deployment (to account with identity): studyDeploymentId |
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 |