Version 1.2.1

This release only impacts the JavaScript/TypeScript release:

• Fixed "unknown polymorphic" serialization for JS released sources (#473).

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp

Version 1.2.0

This release helps implementing infrastructures (specifically CAWS) to implement web-based studies with anonymous participant invites. The underlying mechanism to do so is not different from "username" identification/authentication of users. The username simply needs to be an anonymous ID generated by the infrastructure, and the infrastructure can pass the username/password to the user using their preferred mechanism (e.g., embedded in a one-time link).

These changes require no database migration. If a relational database was used to store AccountIdentity (instead of a document store simply storing the serialized JSON), you may need to add support to store UsernameAccountIdentity, although this type was already defined before this release.

In addition, improvements to JavaScript sources and TypeScript declarations:

• API is now packaged as ES modules (#456)
• Export of kotlin's Nullable (#445)
• Provide access to base properties of snapshots (#457)

Dependency updates:

• Kotlin 1.9.23
• kotlinx.serialization 1.6.3
• coroutines 1.8.0
• datetime 0.5.0

Subsystem changes

Common

• Added Website primary device (#465)

Studies

• Added RecruitmentService.AddParticipant() overload which accepts users that are identified by a username (#467). The existing AddParticipant request object was renamed to AddParticipantByEmail and the new method was added as AddParticipantByUsername.

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp

Version 1.1.2

This release contains no functional API changes. The main reason for release is a bugfix:

• Deserializing Measurement fails when using custom data types

But, there are some major changes which help out infrastructure implementers:

• Backend: Decorator functionality for all application services to apply crosscutting concerns on all requests. E.g., logging, authorization, etc. See types extending from ApplicationServiceDecorator.
• Frontend: JS/TypeScript sources have received a major overhaul.
  • They now rely on the new Kotlin JS backend. This means that the sources are not backwards compatible with sources of past releases.
  • TypeScript declarations are now available for most types in the application namespace. Ugly "name mangled" interfaces have been replaced with clean facades published as separate packages.
  • The packages are now generated as scoped npm packages in a @cachet scope.
  • Packages still aren't published to npm, but will be manually attached to releases for now.

Dependency updates:

• Kotlin 1.8.21
• kotlinx.serialization 1.5.0
• coroutines 1.7.0

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp

Version 1.1.1

The main reason for this release is to upgrade to Kotlin 1.8.0, which also allows updating other dependencies. Since 1.6.10, no upgrade was possible due to compiler bugs which have been fixed in 1.8.0.

This release contains no major new features, hence the patch version bump. However, it does introduce a small AnyDeviceConfiguration.isPrimary() helper method.

Dependency updates:

• Kotlin 1.8.0
• kotlinx.serialization 1.4.1
• coroutines 1.6.4
• datetime 0.4.0

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp

Version 1.1.0

The main reason for this release, although it contains various new features, is to be able to handle concurrency issues when an infrastructure using CARP core is set up to allow parallel incoming application service requests.

... infrastructures using CARP core can now verify on repository writes whether the version of the snapshots in the DB match those of the expected fromSnapshotVersion from the [aggregate root (AR)] which is loaded in memory and on which edits were performed. If not, this means a concurrent incoming requests manipulated the same AR, and an exception can be thrown. This exception can be handled uniformly by retrying the whole request.

This requires a database migration!

Subsystem changes

Common

• isValidMeasurement can now be called on merged DataTypeMetaDataMap, which is useful if you have types defined in addition to CarpDataTypes in your own DataTypeMetaDataMap (#393)
• Support handling concurrent repository updates. Repository writes can now verify whether the version of the snapshot being written matches that which is present in the DB. If not, this means another request simultaneously modified the same object. We recommend implementing a custom exception for this with an associated retry strategy which tries to replay the full application service request. (#402)
• New sensor data types:
  • EDA
  • PPG
• For sensors which can be configured using a sampling interval (IntervalSamplingScheme), support configuring a fixed set of valid options (#407)
• If device-specific data is needed on sensor data (e.g., calibration data used to derive the reported EDA values), it can now be passed using the sensorSpecificData field (#411)

Studies

• Fix: ensure that RecruitmentService.inviteNewParticipantGroup does not send out invitations when repository update fails. This supports replaying this request in case of concurrent repository writes, which in this release can now be verified. (#403)

Deployments

• Fix: failing DeploymentService requests after calling unregisterDevice (#406)
• Fix: redeploying devices (when unregistering and re-registering them) failed (#413)

Clients

• When using ClientManager, prevent having to cast to DeploymentStatusAvailable when StudyStatus is Running (#400)

Database migration

A version field was added to Snapshot. This should be set to 0 when migrating the database. The affected snapshots are:

• StudySnapshot, including the containing protocolSnapshot if the value is non-null.
• StudyDeploymentSnapshot, including the containing studyProtocolSnapshot.
• ParticipantGroupSnapshot
• StudyProtocolSnapshot
• RecruitmentSnapshot, including the containing studyProtocol if the value is non-null.

Additionally, the StagedParticipantGroup.invitedOn field was removed, and a isDeployed field was added. The isDeployed field should be set to true. Concretely, when using a document store and CARP's JSON serialization, all values of RecruitmentSnapshot.participantGroups need to:

• remove the invitedOn field
• add a isDeployed: true field

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp

Version 1.0.0

The first stable release of CARP core. The backend application services have been stabilized, and migration functionality is included so that older clients will still be able to call newer backends of the same major API level.

In addition, participants are now invited using participant roles, which dictate which devices they will be assigned to, and which data they are expected to input. This impacts various objects that previously held assigned device role names. (#373) For the majority of studies that only contain a single participant role, no roles need to be specified, and AssignedTo.All can be used to have the same behavior as in older versions.

Dependency updates:

• kotlinx.serialization 1.3.2
• coroutines 1.6.0

Common

• Big rename:
  • TaskDescriptor to TaskConfiguration
  • Trigger to TriggerConfiguration
  • Consistently use statusList for plural of status (#359)
• Removed FreeFormText. This was a catch-all solution for extensibility, which was already possible by implementing custom DataTypes.
• Functionality to migrate incoming API requests to the runtime version (#367):
  • Each application service has a matching ApplicationServiceApiMigrator.
  • Call migrateRequest for incoming JSON requests, which can be old versions, to retrieve a MigratedRequest which holds the runtime version in request.
  • Call MigratedRequest.invokeOn to call the application service and return the JSON response in the version expected by the caller.
• Add ACCELERATION, including gravity, to Smartphone. (#369)
• Username serialized as string primitive in JSON, rather than object (only used in UsernameAccountIdentity).
• Renamed RRInterval to InterbeatInterval, which is more general since not all interbeat intervals need to be based on RR peaks (4083b64).

Protocols

• Optional participant roles can be defined in StudyProtocol, and devices can be assigned to participant roles. By default, devices are assigned to "all" roles, meaning all participants in case no roles are specified. (#373)
• Expected participant data now includes an optional participant role the ParticipantAttribute applies to. The equivalent of the old behavior is using AssignedTo.All, in which case the data can be edited by all participants in the deployment. When assigning data to one or more specific participant roles, the data can be set per role.

Deployments

• Expected participant data is now included in PrimaryDeviceDeployment, so that clients have access to the necessary meta data to determine validity of data.
• ParticipationService.setParticipantData now includes a inputByParticipantRole parameter to set data assigned to a specific participant role.

Studies

• Added StudyService.RemoveProtocol. (#360)
• Added studyProtocolId to StudyStatus, which is null until study protocol is set. (#365)
• RecruitmentService.inviteNewParticipantGroup now uses AssignedParticipantRoles rather than AssignParticipantDevices.
• StudyService.setInternalDescription can now set description to null to indicate no description is set (it is null to start out with).

Data

• DataStreamService.removeDataStreams returns IDs of study deployments for which data streams were removed.
• Removed DataTimeType.EITHER: all data points in a data stream sequence should be POINT or TIME_SPAN, but not a mix of the two.
• Timestamps in sequences are now validated (#366):
  • POINT: start time of subsequent points should always be > last point
  • TIME_SPAN: end time should be > last end time; start time >= last start time

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp

Version 1.0.0-alpha.39

The last release prior to a stable 1.0 release. This includes the start of some big renaming, and preparations for API stabilization.

• JSON schemas: Starting from this release, you can find JSON schemas for all application service requests and responses under the rpc/schemas folder. In addition, example requests and responses will be added as an asset to the release. (#351)
• Versioned API: application service request objects and integration events now carry an apiVersion with a major and minor component. Within major versions, minor versions will be backwards compatible. Helper classes will be provided by core to perform the necessary migrations. (#354, #357)

Dependency updates:

• Kotlin 1.6.10
• kotlinx.serialization 1.3.1

Common

• All AggregateRoots now have an id; no more custom IDs.
• IntegrationEvent now carries an aggregateId; implementing infrastructures need to guarantee ordering for all events sharing the same aggregateId. (#338)
• Only lowercase and alphanumerics are allowed in NamespacedId. (#340)
• Added an optional displayName to DeviceRegistration which front-ends can use to render concise information about registered devices without worrying about concrete types. (#350)
• Big rename:
  • $type discriminator in JSON has been replaced with __type
  • MasterDeviceDescriptor to PrimaryDeviceConfiguration
  • MasterDeviceDeployment to PrimaryDeviceDeployment
  • DeviceDescriptor to DeviceConfiguration
  • as well as all related names and references to them, e.g., assignedPrimaryDeviceRoleNames

Protocols

• #346 Study names still need to be unique to study owners.
• Replaced ProtocolOwner with UUID. (#343)
• Renamed ProtocolService.getAllFor to getAllForOwner.

Deployments

• StudyDeploymentsRemoved event now only carries a single studyDeploymentId, so removing multiple deployments fires multiple events.
• Renamed DeploymentRepository.getStudyBy renamed to getStudyByDeployment.

Studies

• Replaced StudyOwner with UUID. (#343)

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp

Version 1.0.0-alpha.38

Common/Protocols

• Data type changes (#331):

  • Acceleration renamed to NonGravitationalAcceleration and should hold SI unit (m/s^2) excluding gravity instead of g force.
  • Added AngularVelocity.
  • Both Acceleration and AngularVelocity were added to Smartphone.Sensors.

• For known supported data stream data types on DeviceDescriptor, the sampling configuration is now validated (#312).

• Devices can now be configured to be optional, using DeviceDescriptor.isOptional (#323).

• Various new TypeScript declarations to access members of StudyProtocolSnapshot, including devices, tasks, and triggers.

Studies

Various changes related to managing participant group life cycle (#314):

• Added StagedParticipantGroup to Recruitment domain object to store participant groups that aren't necessarily deployed yet. But, this functionality is not exposed in application service yet.
• ParticipantGroupStatus is turned into a state machine with states Staged, Invited, Running, and Stopped. Invited contains an invitedOn field, and Stopped a stoppedOn field.
• RecruitmentService.deployParticipantGroup renamed to inviteNewParticipantGroup.

Deployments

• Renamed StudyDeploymentStatus.DeploymentReady to Running.
• Renamed MasterDeviceDeployment.configuration to registration.
• Renamed DeploymentService.deploymentSuccessful to deviceDeployed.
• Include assigned device roles in StudyDeploymentStatus.participantsStatus, as the new type ParticipantStatus which in the future will also hold information on consent, etc. (#329).

Clients

Cleaner API to obtain default sampling configurations (#318):

• DeviceDescriptor.getDefaultSamplingConfiguration() moved to RuntimeDeviceInfo.defaultSamplingConfiguration. RuntimeDeviceInfo can be retrieved through MasterDeviceDeployment.getRuntimeDeviceInfo().
• Updated documentation for client implementations which sampling configuration to use at runtime.

Major rework of client API, in line with DDD principles (#321):

• Main API, accessed through ClientManager has been moved to the application namespace.
• StudyRuntime is split into Study and StudyDeploymentProxy.
• Study state is represented in StudyStatus, representing the state based on incoming study deployment events.
• ClientManager.addStudy() no longer calls tryDeployment(). You can thus add a study without trying to deploy it, at which point it will be in the DeploymentNotStarted state.

Data

• The data subsystem now accepts data types for which no corresponding Data object is available at runtime (#334).
• Completed tasks should be uploaded using CompletedTask.
• Better defined SyncPoint behavior and helper methods (#333).

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp

Version 1.0.0-alpha.28.5 (hotfix)

Applies six hotfixes to version 1.0.0-alpha.28:

• Bugfix: ProtocolVersion.date should always be serialized.
• Bugfix: load classDiscriminator for unkown polymorphism at runtime.
• Fallback to normal polymorphic serialization for non-Json formats in UnknownPolymorphicSerializers.
• Make sure ParticipantGroupSnapshot can be serialized as BSON.
• Devices can now be optional, specified as an isOptional property on DeviceDescriptor. Now, only non-optional master devices need to be deployed. Only non-optional master devices need to be deployed. (cherry-picked from #323)
• Add assigned device role names in DeanonymizedParticipation. After having called ParticipantService.deployParticipantGroup() it was impossible to retrieve which devices were assigned to participants. A different solution to this was implemented on the main branch, including ParticipantStatus in StudyDeploymentStatus, but given the amount of changes since alpha 28, aligning this API would introduce many more breaking changes rather than this rather simplistic hotfix.

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp

Version 1.0.0-alpha.28.4 (hotfix)

Applies five hotfixes to version 1.0.0-alpha.28:

• Bugfix: ProtocolVersion.date should always be serialized.
• Bugfix: load classDiscriminator for unkown polymorphism at runtime.
• Fallback to normal polymorphic serialization for non-Json formats in UnknownPolymorphicSerializers.
• Make sure ParticipantGroupSnapshot can be serialized as BSON.
• Devices can now be optional, specified as an isOptional property on DeviceDescriptor. Now, only non-optional master devices need to be deployed. Only non-optional master devices need to be deployed. (cherry-picked from #323)

Multiplatform release accessible through Maven:
https://mvnrepository.com/artifact/dk.cachet.carp