Import Package Configuration

When preparing to import third party data into CDB, one of the major activities is configuring the manifest file that must be included with the data for import. This manifest file is a JSON (JavaScript Object Notation) file that CDB uses to configure import behavior for the specified Source, as well as to describe the data properties and required mapping. To configure an import package, you need to know what attributes require configuration and how to configure those attributes properly.

CDB includes the CDB Manifest Builder configuration tool for ease of file creation. The CDB Manifest Builder is a step-by-step wizard that guides you through all manifest file configuration options in a user-friendly interface. In the Manifest Builder, CDB presents you with every import option, which you can set without needing to understand JSON.

In the CDB Manifest Builder, you can choose to configure a new file from scratch or to import an existing file to modify. There are four (4) steps in the Manifest Builder:

1. Package Configuration: Define package-level properties, such as the Name of the Study and Source, as well as how the incoming data should be matched to EDC data.
2. Add Data Files: Upload CSVs for import or create CSV file templates for loading data. If the user uploads a CSV file, CDB reads the header row and automatically adds those values for use during the File Configuration step.
3. File Configuration: Define all file-specific mappings, as well as the data type and properties for each column (such as Length, Format, and Precision). Available properties depend on the chosen data type. By default, CDB sets the data type to Text with “1500” for Length.
4. Summary: Preview a summary of all configuration, then generate a ZIP package containing the configured manifest file and a CSV file with the header row for each file in the import package. CDB doesn’t save any configuration in the Manifest Builder, so the only way to maintain a configuration is to generate the ZIP package.

Accessing the CDB Manifest Builder

Users aren’t required to log into Vault to access the CDB Manifest Builder. The CDB Manifest Builder is accessible via direct link. The URL is different across general, limited, and pre-release vaults. Click the links below to open the appropriate version of the manifest builder.

• General Release
• Limited Release

Package Configuration

To create the manifest file:

1. Navigate to the Manifest Builder.
2. Select Import Manifest File (to build from an existing manifest.json file) or Create New Manifest File (to start from scratch).
3. Click Next.
4. Enter the Study Name. This must be an exact match to the Study Name in CDB.

5. Enter the name of the Source.
   

6. If you’re using OpenEDC, select the Primary Source checkbox.
7. For Match Study On, select Name or External ID. This is the field that CDB uses to match the Study.

8. For Match Site On, select Name or Number. This is the field that CDB uses to match the Site.

9. If you want to match on Events in EDC, select Yes. Otherwise, leave this set to No. See details about event matching below. If you selected Yes:
   • For Match Events On, select Name or External ID. This is the field on the Event Definition that CDB uses to match the Event to.
   • If you want to create a new Event when CDB can’t match the imported Event to an existing one, leave the Create new Event in CDB when the Event from the Import cannot be matched to an EDC Event. Otherwise, clear the checkbox.
10. If you aren’t matching to an Event in the CSV file, enter the Name of the Event to use as the Event Default.
11. Click Next.

Add Data Files

If you have CSV files with your data already, you can import these to use when configuring your manifest. Otherwise, you can create new CSV files (with only the headers) to add your data later.

Import Data Files

You can click in the Upload area to browse for and select your CSV files, or you can drag and drop your files into the Upload area. Then, click Next to move to the next step.

Add New Data Files

1. Click Add New Data File.
2. Enter the File Name.

3. To add additional data files, repeat steps 1 and 2.

4. To remove a file, click Remove ().
5. Click Next.

File Configuration

You will go through four (4) configuration steps for each CSV file: Column Mapping, Item Mapping, Reorder Columns, and Unique Identifiers. Switch between files in the File Selection header.

Column Mapping

You can map the columns that don’t represent data items in step 3.1. To map columns when none exist, begin typing the desired column header in the field, then click Add Column. This adds the column header to the drop-down.

To map columns:

1. Select the Study column.
2. Select the Site column.
3. Select the Subject column.
4. Select Map to a column to use a column value for event matching or Set file to specific Event default to automatically add imported data to the Event Default.
5. Select the Event column.
6. To specify columns for Form, Form Sequence, Item Group, and Item Group Sequence (if your file has data that spans more than one Form or Item Group), select the Advanced Options checkbox.
7. Select the Form column.
8. Select the Form Sequence column.
9. Select the Item Group column.
10. Select the Item Group Sequence column.
11. Click Next.

Item Mapping

Now, you can add columns for each data item that you’re importing data for. For each Item, you can specify additional properties.

1. Click Add Item.
2. For Item Column, enter the header of the column containing the item’s value.
3. Select a Data Type. Depending on the data type you selected, CDB allows you to configure the applicable configuration columns (Length, Min, Max, Precision, and Format).
4. Enter or select values for the applicable configurations.
5. Repeat steps 1 through 4 for each of your Items.
6. Optional: Configure Blinding Options. See details below.
7. To add another Item, click repeat steps 1 through 6.
8. When finished, click Next to continue.

Blinding Options

Once you select the Blinding Options checkbox, Workbench adds the Blind all data on this file checkbox, as well as the Blinded Column and Determines Row Blinding columns to the Item Columns table.

Selecting the Blind all data on this file indicates that all data in the file is restricted. To only restrict certain Items, select the Blinded Column checkbox.

If your form contains a boolean-type Item that indicates whether or not the row should be blinded, select the Determines Row Blinding checkbox for that Item.

Reorder Columns

If you didn’t add the item columns in your preferred order, you can reorder them. Use the Top, Up, Down, and Bottom buttons, or drag and drop columns, into your desired column order. When finished, click Next.

Unique Identifiers

If your file has Forms or Item Groups that are repeating, additional configuration is required.

If you don’t have repeating Forms or Item Groups in the file, select No for Does your data contain forms or item groups that repeat within a visit for a subject? and click Next.

If you do have repeating Forms or Item Groups, perform the following steps:

1. Select Yes, there are repeating forms or item groups.
2. Select the Group Identifier checkbox for each column that defines grouping.
3. Select the Distinct Identifier checkbox for each column that distinctly identifies the Form or Item Group within the group.
4. When finished, click Next.

How to Delete a File

You can delete a file from your manifest configuration at any time during step 3.

To delete a file:

1. Locate the file you want to delete in the File Selection header.

2. From the File menu () menu, select Delete.

3. In the confirmation dialog, click Delete Tab.

Review the Summary

The Summary page displays the configuration information for each of your data files. Carefully review your configuration here.

Edit Configuration from the Summary

You can modify package level details by clicking Edit in the Package Configuration panel. This returns you to step 1.2.

To modify file-level configuration:

1. Locate the file you want to delete in the File Selection header.

2. From the File menu () menu, select Edit.

3. This returns you to step 3.1 for the chosen file. Make your changes and click Next for each step until you’ve returned to step 4.

Generate the Summary

Once you’ve reviewed your configuration, you can generate the import package.

1. Click Generate Manifest.

2. Save the manifest file in your chosen location.
3. If you created CSV files from scratch, instead of importing ready CSV files into the builder, unzip the package and add data to your CSV files.

Import the Generated Package

Once your import package contains all of your data, compress the directory into a ZIP file. Then, you can import it into Workbench.