Synchronize Study Design from a Core Data Definition

Study designers can use an uploaded Core Data Definition (CDD) to automatically create and update parts of a study design, instead of having to manually create them in Studio.

When you run the Studio Validation job in your Study with the Synchronize Form Design with Core Data Definition option selected, Vault compares the CDD to your study’s design and builds out Forms, Item Groups, Items, Units, and Codelists to match what’s in the CDD.

The Synchronize Study Design feature is intended to accelerate study builds driven by an external Metadata Repository (MDR) or similar system, where the CDD represents the sponsor’s intended design standard.

Synchronization works from the Form and down:

  • Forms, Item Groups, Items, Units, and Codelists that exist in the CDD but not in your study design are created.
  • Properties on existing definitions that don’t match the CDD are updated to match it.
  • Forms, Item Groups, and Items that are in your schedule but aren’t in the CDD are removed from the schedule. Vault doesn’t delete the underlying definition record, only its placement in the schedule.
  • The schedule is reordered so Forms, Item Groups, and Items occur in the same order as the CDD.

Event Groups and Events are never created or removed by synchronization. If the CDD maps a Form to an Event that doesn’t already exist in your schedule, Vault logs an error and doesn’t place that Form into the schedule.

Prerequisites

The following are configuration prerequisites for this feature:

  • A CDD file must already be attached to the casebook version you want to synchronize.
  • The casebook version must be unpublished. Synchronization isn’t available on a published casebook version, and starting a job with synchronization enabled against a published version fails immediately.

Users with the CDMS Study Designer and CDMS Librarian standard study roles can perform the actions described below by default. If your organization uses user-defined Study Roles, your role must grant the following permissions:

Type Permission Label Controls
Standard Tab Studio Tab

Ability to access the Studio tab

Functional Permission Design Study

Ability to create study design definitions and a study schedule from Studio

If your Study contains restricted data, you must have the Restricted Data Access permission to view it.

Learn more about Study Roles.


Before You Synchronize

We recommend copying forms from your library before you synchronize, rather than relying on synchronization to build every form from scratch. The CDD doesn’t capture every form property, including range checks, progressive display, and derived items. When synchronization finds a form, item group, or item that already exists with a matching name, it updates only the mismatched properties and keeps the richer configuration from your library copy. When it has to create a new definition from scratch, it applies Veeva’s standard design template instead, which you’ll likely need to refine afterward.

If the CDD doesn’t include a study schedule, synchronization still creates the form-level definitions but doesn’t place them in the schedule.

After synchronizing, review and manually configure the following, since the CDD doesn’t define them:

  • Minimum and maximum values for date and datetime items
  • Minimum and maximum values and lengths for integer and float items
  • Whether a text item is a label type
  • Derived items and the rules that calculate them

A CDD can’t indicate that an item is meant to be a Label rather than a standard data-collecting item. Synchronization always creates text items using the standard Text item type. If an item is meant to be a Label, it has a validation error until you manually change its item type to Label in Studio.

Synchronizing Your Study Design

Synchronization runs as part of the Studio Validation job. You enable it as part of the job from the same Validate Study dialog you use to run a standard validation.

Best Practice: Veeva strongly recommends running a comparison-only validation first (leave Synchronize Form Design with Core Data Definition set to No) so you can review the differences between your study design and the CDD before Vault makes any changes.

To synchronize your study design with the CDD:

  1. Navigate to your Study in Studio.
  2. From the Actions menu (), select Validate.
  3. In the Validate Study dialog, select Yes for Compare Core Data Definitions to Study Design.
  4. Set Prevent Validated Status when Core Data Definition Errors are Found according to your preference.
  5. Select Yes for Synchronize Form Design with Core Data Definition. Vault only displays this option when a CDD is attached to the current, unpublished casebook version.
  6. Click Next.
  7. In the Synchronize Study Design confirmation dialog, read the warning. Synchronizing creates, updates, and removes study design components, and you can’t undo the result.
  8. Type “SYNC” exactly as shown (the keyword is case-sensitive) in the confirmation field.
  9. Click Validate & Synchronize.
  10. Vault begins the validation job. When complete, Vault sends an email notification with a link to download the results.

If you type the keyword incorrectly or leave the field blank, Vault displays an error and doesn’t start the job. If you click Cancel from the confirmation dialog, Vault returns you to the Validate Study dialog with your previous selections still in place.

Reviewing the Results

The job output includes the standard Studio Validation log, along with the CDD comparison results, covering both the differences Vault found and the changes it made. Download and review this file to confirm the synchronized design matches your expectations, and to identify anything you still need to configure manually.

Synchronization Issues

In addition to the standard CDD validation issues, synchronization can raise the following issues as part of Studio Validation:

Type Issue No. Name Explanation Actions
Error DDE-005 Feature not enabled Synchronization couldn't run because this feature isn't enabled in your vault.
  • Enable this feature for your vault.
Error DDE-101 Missing critical data definition in study definition Vault couldn't find the Event for the Form in the schedule.
  • Create the Event and add it to your study schedule.
  • Update the Form to reference an Event that is on the study schedule.
Error DDE-201 Definition is missing at least one child record Vault couldn't create a Form, Item Group, Unit Definition, or Codelist Definition because the CDD definition doesn't contain at least one required child record (for example, a form with no item groups).
  • Add the child record.
Error DDE-202 Definition contains nesting repeating structures Vault couldn't create a Form because both the Form and one of its Item Groups have a repeat maximum greater than one in the CDD. Veeva doesn't support nested repeating structures.
  • Update the Repeat Maximum.
Warning DDW-203 Definition exceeds variable limit Vault created a Form that has more than 50 nested variables, which exceeds the recommended limit.
  • Reduce the number of nested variables.
Warning DDW-204 Definition properties are not identical as recommended Vault created a definition with a Name and External ID in the CDD that aren't identical.
  • Update the Name and External ID to match.
Warning DDW-205 Definition property exceeds recommended property length Vault created an Item with a Name in the CDD is longer than eight characters, which exceeds the recommended length.
  • Reduce the length of the item's Name
Warning DDW-206 Definition created in previous casebook version Vault couldn't delete a Unit Item Definition or Codelist Item Definition because it was created in a previous casebook version.
  • Mark the Unit Item Definition or Codelist Item Definition as Hidden.

Limitations

The following limitations apply:

  • Synchronization only acts on Forms, Item Groups, Items, Units, and Codelists. It never creates, updates, or removes Event Groups or Events.
  • Changes made by synchronization can’t be undone.
  • Synchronization only runs against an unpublished casebook version.
  • Synchronization doesn’t configure range checks, progressive display, derived items, or minimum/maximum values. Configure these manually after synchronizing.

The Studio Validations API endpoint accepts a synchronize_form_design_with_cdd boolean parameter, equivalent to the Synchronize Form Design with Core Data Definition option in the UI. For details, see the EDC API Reference.