Skip to content
CARP Documentation

DeploymentService

Application service which deploys study protocols to participants and hands out the PrimaryDeviceDeployment for each primary device.

This is the service a client talks to when it joins a study deployment. A client (see ClientManager and StudyDeploymentProxy) uses it in this order: getStudyDeploymentStatus -> registerDevice -> getDeviceDeploymentFor -> deviceDeployed; and stop to end the study.

Key points:

  • Most methods return null instead of throwing when the deployment does not exist.
  • Implemented by the CARP web services client (carp_webservices) and, for local studies, by SmartphoneDeploymentService in CARP Mobile Sensing.

Constructors

DeploymentService

DeploymentService()

Constants

API_VERSION

String const API_VERSION

Methods

createStudyDeployment

Future<StudyDeploymentStatus> createStudyDeployment(
  1. StudyProtocol protocol, [
  2. List<ParticipantInvitation> invitations = const [],
  3. String? id,
  4. Map<String, DeviceRegistration>? connectedDevicePreregistrations,
])

Instantiate a study deployment for a given StudyProtocol with participants defined in invitations.

The identities specified in the invitations are used to invite and authenticate the participants. In case no account is associated to an identity, a new account is created for it. An invitation (and account details) is delivered to the person managing the identity, or should be handed out manually to the relevant participant by the person managing the identity.

id specifies the study deployment id. If not specified, a UUID v4 id is generated. connectedDevicePreregistrations lists optional pre-registrations for connected devices in the study protocol.

deviceDeployed

Future<StudyDeploymentStatus?> deviceDeployed(
  1. String studyDeploymentId,
  2. String primaryDeviceRoleName,
  3. DateTime deviceDeploymentLastUpdatedOn
)

Indicate to stakeholders in the study deployment with studyDeploymentId that the device with primaryDeviceRoleName was deployed successfully, using the deployment with the specified deviceDeploymentLastUpdatedOn, i.e., that the study deployment was loaded on the device and that the necessary runtime is available to run it.

Returns null when:

  • a deployment with studyDeploymentId does not exist
  • primaryDeviceRoleName is not present in the deployment
  • the deviceDeploymentLastUpdatedOn does not match the expected date. The deployment might be outdated.
  • the deployment cannot be deployed yet, or the deployment has stopped.

getDeviceDeploymentFor

Future<PrimaryDeviceDeployment?> getDeviceDeploymentFor(
  1. String studyDeploymentId,
  2. String primaryDeviceRoleName
)

Get the deployment configuration for the primary device with primaryDeviceRoleName in the study deployment with studyDeploymentId. Returns null if studyDeploymentId is not found.

getStudyDeploymentStatus

Future<StudyDeploymentStatus?> getStudyDeploymentStatus(
  1. String studyDeploymentId
)

Get the status for a study deployment with the given studyDeploymentId. Returns null if studyDeploymentId is not found.

getStudyDeploymentStatusList

Future<List<StudyDeploymentStatus?>> getStudyDeploymentStatusList(
  1. List<String> studyDeploymentIds
)

Get the statuses for a set of deployments with the specified studyDeploymentIds. Returns null for IDs in studyDeploymentIds for which no deployment exists.

registerDevice

Future<StudyDeploymentStatus?> registerDevice(
  1. String studyDeploymentId,
  2. String deviceRoleName,
  3. DeviceRegistration registration
)

Register the device with the specified deviceRoleName for the study deployment with studyDeploymentId.

registration is a matching configuration for the device with deviceRoleName. Returns null if studyDeploymentId is not found.

removeStudyDeployments

Future<Set<String>> removeStudyDeployments(
  1. Set<String> studyDeploymentIds
)

Remove study deployments with the given studyDeploymentIds. This also removes all data related to the study deployments.

Returns the IDs of study deployments which were removed (empty set if none were removed). IDs for which no study deployment exists are ignored.

stop

Future<StudyDeploymentStatus?> stop(
  1. String studyDeploymentId
)

Permanently stop the study deployment with the specified studyDeploymentId.

No further changes to this deployment will be allowed and no more data can be collected and uploaded to a DataStreamService. Returns null if studyDeploymentId is not found.

unregisterDevice

Future<StudyDeploymentStatus?> unregisterDevice(
  1. String studyDeploymentId,
  2. String deviceRoleName
)

Unregister the device with the specified deviceRoleName for the study deployment with studyDeploymentId. Returns null if studyDeploymentId is not found.