YAML Builder

This topic describes the YAML Builder tool for EDC Migrator.

Prerequisites

Required Permissions

Users with the Migrator, System Administrator, and Vault Owner security profiles can perform the actions described below by default. If your vault uses custom Security Profiles, your profile must grant the following permissions:

Permission Controls
Tabs: Projects Ability to access the Projects tab

The YAML Builder creates the mapping files (YAMLs) used for study migrations. With this tool, you can auto-generate a baseline set of mapping files based on the EDC Study Design.

Users are encouraged to conduct a Study Design Validation in Studio before using the YAML Builder to ensure no core structural design issues are present.

The Builder supports various data source types, including Rave™ and InForm™. Each file corresponds to a specific source and reflects its unique mapping properties. Read the YAML Builder Reference for source data requirements and additional guidance on generating mapping files.

How to Generate Files

To generate files with the YAML Builder:

  1. From the Projects tab, hover next to the project name to show the Actions () menu.
  2. From the Actions menu, click YAML Builder.
  3. Select the Target Vault. This is the EDC vault where the study design is retrieved.
  4. Enter the Study Name. This is the Name and the Study Environment for which you want to create mapping files (for example, “Cholecap_PROD” or “Deetoza_DEV1”).
  5. Select the Data Source (In-Form, Legacy, or Rave). Check that your source data meets all requirements to prevent migration errors.
  6. Enter the Casebook Version.
  7. Click Execute.
Open YAML Builder Action Menu
Open YAML Builder Action Menu

A progression banner displays at the top of the application during YAML file generation. After the generation is complete, you’ll receive in-app and email notifications. If the generation is successful, files are added to the Attachments section of the project’s Details page.

Troubleshooting Job Failure

This feature is only available to users with Admin access.

If your generation job is unsuccessful, you can find information regarding the failure in Admin > Operations > Job Status > History. To find the most recent job under the History section, locate the YAML Builder title and sort by Started Time. You can also download the job’s log file by hovering next to the Job ID, and selecting Actions () menu > Download Log.

Most failures are caused by one of the following:

  • Missing Column Headers: Confirm that the mandatory column headers exist in your source CSV. The Migrator requires FolderName for Rave studies or VISITMNEMONIC for InForm studies.
  • Value Mismatch: Confirm that the text in the source data column matches the external ID in Studio.
  • Header Misalignment: Ensure the YAML Builder correctly identified the Event Type. A common error is the system assigning a standard header.yaml to an event that should have used a logheader.yaml.

Modifying YAML Files

You can manually modify and re-upload YAML files when needed. To make changes, download the YAML file in the Mapping Configurations section of the project’s Details page. Make the appropriate changes and upload the file to the same Mapping Configurations section.

For instructions on uploading, read Creating Mapping Configurations.