Changes to data management workflows introduced with CDMS v2024.4.0.0

+ More

Table of Contents

Automated (re-)execution of calculations How it works While building a study Validation for cyclic dependencies Restriction on deleting fields During data entry When importing data Enabling the feature for existing studies Automated (re-)evaluation and persistence of validations How it works While building a study During data entry When importing data Enabling the feature for existing studies

With the release of Castor CDMS version 2024.4.0.0 in December 2024, we are introducing two new features to enhance data management workflows: automated (re-)execution of calculations and automated (re-)evaluation and persistence of validations. These features will be automatically enabled for new studies.

This article outlines these features, explains their impact on study building, data entry, and data import, and describes how to enable them in studies created before this update.

Automated (re-)execution of calculations

Calculation fields are fields that automatically compute and display values based on predefined formulas using data from other fields within a study.

This feature ensures that calculations get (re-)executed automatically in the background throughout the data collection process (whenever data are entered or imported) and when there are changes to calculation templates or the study structure. Previously, users had to reopen forms to trigger recalculations, as calculations were only updated on the current form.

How it works

This feature is enabled by default for new studies created after the 2024.4.0.0 release.

While building a study

Calculations automatically re-execute in the background for all participants whenever:

A calculation field is created, updated, copied, or imported.
A form containing a calculation field is created, copied, or imported.

If the result of a calculation changes, the updated value is stored similarly to regular data entry and is attributed to a System User. This also applies to changes applied via Form Sync. An event is logged in the Audit Trail, similar to regular data entry events (Participant result, Repeating Data Instance result, Survey result).

Validation for cyclic dependencies

When saving or importing calculation fields, the system verifies that calculations do not depend on each other in a circular manner, which would prevent execution. If a cyclic dependency is detected, an error message is displayed when the calculation is added.

Restriction on deleting fields

Fields used in calculations cannot be deleted. To delete a field that is part of a calculation, the calculation field must be updated or removed first.

During data entry

Calculations automatically re-execute in the background for a participant whenever:

Values of fields that are part of a calculation are entered or changed.
New Repeating Data Instances or Survey Package Instances are created or archived that either:
- Include fields used in calculations elsewhere.
- Contain calculation fields themselves.
Participants, Visits, Forms, Repeating Data Instances, or Survey Package Instances are unlocked or unarchived when they either:
- Have fields used in calculations elsewhere.
- Contain calculation fields themselves.

If the result of a calculation changes, the updated value is stored and attributed to the user performing the data entry. An event is logged in the Audit Trail, similar to regular data entry events (Participant result, Repeating Data Instance result, Survey result).

When importing data

Calculations automatically re-execute in the background for a participant whenever:

Data for fields that are used in a calculation are imported (via CSV or FHIR) or pushed to CDMS through the API.

If the result of a calculation changes, the updated value is stored and attributed to the user performing the import. An event is logged in the Audit Trail, similar to regular data entry events (Participant result, Repeating Data Instance result, Survey result).

Enabling the feature for existing studies

To maintain consistency in the execution of calculations, this feature is not enabled by default for studies created before CDMS version 2024.4.0.0.

For existing studies, you can enable this feature on the Study Settings page. When activated on an active study, the automated re-execution of calculations will only occur from the moment it is enabled. Previously calculated values will not be updated upon enabling; they will only be updated when a re-execution is triggered as described above.

To enable this feature:

Go to the Study Settings page and select the Study properties tab.
Check the ‘Enable automated re-execution of calculations’ checkbox.

Enabling this feature triggers a validation of all calculation templates in the study to ensure they can execute properly. This validation includes:

Checking for circular dependencies between calculations (i.e., verifying that calculations do not reference each other in a loop).
Ensuring that all variable names used in calculations resolve correctly.

If any invalid calculation templates are found, the feature cannot be enabled. Please review all calculation templates to resolve any issues.

Please note that once enabled, this feature cannot be disabled for your study.

Automated (re-)evaluation and persistence of validations

Validations (also known as system edit checks) notify users about required actions or warn them of potential errors based on the data entered.

This feature ensures that validations are automatically evaluated in the background whenever data is entered or when changes are made to the study structure. It also ensures that the complete history of validations is persistently maintained and can be reviewed in the study's audit trail. Previously, automatically closed validations were no longer visible in the interface.