Merging changes from test environment to production environment in CDMS

Learn how to safely and efficiently merge changes from a test environment to a production environment in CDMS in the article below.

Final changes are always applied from the test to production study, never the other way around. Once the changes are applied to the production environment, it is no longer possible to revert them. To remove any changes that have been applied you will need to open the test study, reverting the changes in the test study manually and merging these changes to the production environment.

Reviewing changes and data impact in the production study

Once the changes are finalized in the test study, navigate to the production study. Follow the steps below to merge changes from the test study to the production study:

1. Navigate to the Study Design page
2. Form Sync sub-tab.
3. Click on the Review Merge Changes button:
   
4. If there are no changes detected, a message will appear informing you that no changes have been detected in the test study:
   
5. If changes to the test study are detected, Review Changes to Production page will appear, listing all the changes in the test study. 
   The default 'Table' view, which shows the summary of detected changes:
   The 'Tree' view displays the entire study structure of the test study including the detected changes. Use buttons: 
   • Collapse All
   • Expand Updated
   • Expand All 
     To either expand or collapse the study structure and check which changes have been detected. It is possible to switch to the 'Table' view, which shows the summary of detected changes
6. Press the Review implications button.
7. The Review and accept data impact page displays participants that currently exist in the production environment, and data impact with indication of the number of data points and number of participants that are affected by each change. 
   
8. To confirm and finalize your structure updates, you will need to review and accept all of the data changes. The changes will apply to all existing participants in the study, including locked and archived participant records
9. Click on the Accept & apply changes button to apply changes. A dialog window 'Accept and Apply Changes' will appear.
10. Choose to either 'Continue with download' or 'Continue without download' or 'Cancel'.
    
    Choosing the option to 'Continue with download' will download the full backup (including data) of your study. Please note that the study team member who will be performing the downloading of backup needs to have all permissions enabled across all institutes and not just export rights across all institutes. For example, if the encryption module is enabled, the study team member needs to have Decrypt rights enabled. 
    
    Continue without download option means that the changes will be applied to the production study without downloading the full backup of your study. 'Cancel' option will allow you to cancel the process of merging changes from your test study to the production study.

Versioning of the study structure

Form Sync version number is a production study form version and represents the number of previously applied changes from the test to the production environment. The version number increases every time new changes have been merged successfully.

Allowed changes

• Only changes made to the test study structure will be applied to your production study.
  This excludes changes to the study settings such as changes in the automation engine and notifications.
• Changes to fields, visits, and forms will automatically drop the SDV, Signature, Custom verifications, and Lock statuses. 
  • This includes: updating field labels, updating field variable names, reordering fields in forms, updating field properties
  • This excludes: updating visit labels, reordering forms in visits, adding a new option in an Option Group, updating the configured field validation(s)

Interim Data Impact report for mid-study updates

User can generate an interim data impact report during the Form Sync process, providing detailed insights into structural changes, data loss, and SDV (source data verification) impacts. The 'Data Impact' page also shows cumulative data loss across all study instances.

⚠️ Important: the Interim Data Impact Report does not reflect all downstream effects of calculated field changes.
The report shows the expected, direct impact of the changes being merged. It does not predict downstream changes triggered by updates to calculated fields, such as altered dependency triggers or automatic field clearing. Before applying a Form Sync that includes new or modified calculations, review those calculations manually. See Limitations and important considerations below.

The 'Generate Interim Report' button is available on the initial Form Sync page for production studies that are linked to a test study. The report is a set of CSV files:

1. structural-changes.csv: Overview of all detected structural changes. For each change it lists the change type, category, affected entity and variable name, the value before and after, and flags indicating data loss and (where applicable) impact on SDV, locks, signatures and data validations.
2. collected-data-impact-summary.csv: Aggregated summary per change, with the number of impacted participants and data points and a short description.
3. collected-data-impact-per-participant.csv: Per-participant view of the collected data impacted by each change, including the value before the change and its location (field, visit, repeating data instance or survey package).
4. data-validations-impact-per-participant.csv: Per-participant view of the data validations impacted by the changes, indicating validations that are auto-closed, newly triggered or re-triggered, with field and location.
5. lock-impact-per-participant.csv: Per-participant view of the locked forms and instances impacted by the changes, with their visit or repeating data location.
6. sdv-impact-per-participant.csv: Per-participant view of the fields whose SDV (source data verification) status is impacted, including the SDV plan name, the value before the change and the location.
7. signature-impact-per-participant.csv: Per-participant view of the signed forms and instances impacted by the changes, with their visit or repeating data location.

Note: The exact set of files depends on the features enabled for your study. For example, the sdv-impact-per-participant file is generated only when an SDV Plan and monitoring are active. Files for features that are not enabled in your study will not be included in the report.

Limitations and important considerations

Before applying a Form Sync, review the following limitations of the Interim Data Impact Report and of the Form Sync process, and the manual steps you may need to take.

The report does not surface downstream effects of calculated field changes

The Interim Data Impact report shows the expected, direct impact of the changes being merged. It does not evaluate or predict downstream changes caused by updates to calculated fields.

When a Form Sync introduces or modifies a calculation, the report does not simulate how that recalculated value will, in turn, affect other fields once the sync is applied to production study. In particular, the report does not surface:

- Altered dependency triggers: a calculated field whose new value causes a dependency to show or hide a different set of fields than before.
- Automatic field clearing: fields that are cleared as a downstream consequence of a dependency no longer being triggered.

Example. Suppose a change modifies a calculation so that it no longer triggers a dependency it previously triggered. The fields controlled by that dependency may be automatically cleared when the sync runs in production study, because the dependency condition is no longer met. This downstream clearing is the expected behaviour of the Form Sync engine, but it is not visible in the report.

Because of this, the report should not be treated as a complete record of every change a Form Sync will make. Whenever a change set includes new or modified calculated fields, review those calculations and their dependencies manually before applying the sync.

Validations and calculations are regenerated

For fields incurring data loss or transformation, where the field values are referenced in validations or calculations, new validation messages or calculated values will be generated. If recalculated values or regenerated validation messages do not appear for existing participant data, the affected forms will need to be manually opened.

For variable name changes where the variable name is referenced in summary and calculation fields, the new variable name will need to be reflected in the summary or calculation template in the test study.

Other Form Sync behaviour to be aware of

A field's type can only be changed to a compatible type using Form Sync (for example, a number field can be changed to a text field, but not the other way around). When there is already data collected for a field, incompatible type changes are blocked to prevent data loss. To use an incompatible type, add a new field instead.

Option groups that are not in use in the production study will be deleted when merging the changes.