Managing Synonym Lists

Vault Coder uses Synonym Lists to inform autocoding. When autocoding, Vault compares pending Code Requests to Synonyms in the Synonym List that is assigned to the Form. If Vault finds a match between the pending request’s properties and a Synonym, Vault autocodes the request and assigns the code from the Synonym. You can manage the available Synonym Lists in your vault, including creating new Synonym Lists and upversioning existing Synonym Lists, from Coder Tools > Synonym Lists. From here, you can also review and either approve or reject new Synonyms for a Synonym List as coders request to add them.

Each Synonym List record contains a number of Synonym records. Each Synonym record contains a Verbatim with its assigned dictionary code. The Synonym may include other fields that are used for coding decisions such as Indication and Route. Each Synonym List is associated with a specific MedDRA or WHODrug dictionary release.

You can access Synonym Lists in your vault from Coder Tools > Synonym Lists.

Synonym Lists listing

Prerequisites

Required Permissions

Users with the CDMS Clinical Coder Administrator study role can perform the actions described above by default. If your vault uses custom Study Roles, you must have a Study Role that grants the following permissions:

Type Permission Label Controls
Standard Tab Coder Tools Tab

Ability to access the Coder Tools tab
Functional Permission Manage Coding Lists

Ability to create, edit, import, and export Synonym Lists and Do Not Autocode Lists in Coder Tools

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

Learn more about Study Roles.

Accessing Coder Tools

To access the Coder Tools administration area, click the Tools tab in the primary navigation bar, and then click Coder Tools.

Access Coder Tools from the Tools Tab

Once in Coder Tools, you can click the sub-tabs to navigate to different areas within.

Viewing Synonym Lists

Once you navigate to Coder Tools > Synonym Lists, Vault displays a list of all existing Synonym Lists in your vault. To view a specific Synonym List, click that synonym list’s Name in the listing. This opens the Synonym List Details page, which lists all Synonyms in the list.

Synonym List Details page

To locate a specific Synonym, you can search for it from this page.

Search Synonyms

Create a Synonym List

You can create new Synonym Lists from Coder Tools > Synonym Lists. You can also create Synonym Lists by importing them as a CSV file. See details below. Once you create a Synonym List, you can assign it to a Form. Once coders begin coding, they can request to add terms to the Synonym List.

To create a new Synonym List:

  1. Navigate to Coder Tools > Synonym Lists.

  2. Click New Synonym List. Vault opens the New Synonym List dialog. New Synonym List button

  3. Enter a Name for your synonym list. New Synonym List dialog, showing the Name, Dictionary, and Status fields

  4. Select a Dictionary to associate with your Synonym List.
  5. Optional: Select a Status. The default status is Active.
  6. Click Confirm.

Vault creates your Synonym List record. You can now add Synonyms and assign the list to a Form.

Assign a Synonym List to a Form

Before Vault can use a Synonym List for autocoding, and before coders can request to add new Synonyms, you must first assign a Synonym List to a coding Form.

To assign a Synonym List to a Form:

  1. Locate the Form you want to edit in Coder Tools > Study Settings > Form Configuration.
  2. Hover over the Form to display the Actions menu.

  3. From the Actions menu, select Edit. Edit action

  4. In the Edit Form dialog, select a Synonym List.
  5. Click Save.
  6. Vault assigns the Synonym List to the Form. Vault now uses this Synonym List to inform autocoding on this Form.

You can edit the Synonym List assignment later.

Batch Assign a Synonym List to Multiple Forms

You can use the Batch Assign Lists feature to assign the same Synonym List to multiple Forms.

Batch Assign Lists: Contact Veeva Support to enable Batch Assign Lists in your vault.

To Batch Assign a Synonym List:

  1. Navigate to Coder Tools > Batch Assign Lists.
  2. For List Type, select Synonym List.
  3. Select the Synonym List you want to assign from the Synonym List dropdown. You can check the Assigned Dictionary Release to confirm that the selected Synonym List is on the correct dictionary version.
  4. Select the forms that you want to assign this Synonym List to.

  5. Optional: To select all Forms at once, select the checkbox in the header. A popup will appear informing you of how many rows are selected. You can select all rows across all the pages by clicking Select all [#] rows. Row selector notification message

  6. Optional: You can use the search box to search for and select the Forms you want to assign the selected Synonym List to. Forms that are already selected are not un-selected when you perform a search.

  7. Click Assign . Assign button

  8. In the Assign Synonym List dialog, click Assign. Assign Synonym List dialog

Unassign a Synonym List from a Form

You can remove a Synonym List from a coding Form.

To unassign a Synonym List from a Form:

  1. Locate the Form you want to edit in Coder Tools > Study Settings > Form Configuration.
  2. Hover over the Form to display the Actions menu.

  3. From the Actions menu, select Edit. Edit action

  4. In the Edit Form dialog, select the empty field in the Synonym List dropdown.
  5. Click Save.
  6. Vault unassigns the Synonym List from the Form. Vault will not use any Synonym List to perform autocoding on this Form moving forward.

See Form Configuration in Coder Tools for additional details about available form configuration options.

Edit a Synonym List

You can edit your Synonym List to change the Name. Note that you can’t edit the Dictionary Version. You can only change the Dictionary Version of a Synonym List by upversioning it. See details below.

To edit a Synonym List:

  1. Locate the Synonym List you want to edit in Coder Tools > Synonym Lists.
  2. Hover over the Synonym List to display the Actions menu.

  3. From the Actions menu, select Edit. Vault opens the Edit Synonym List dialog. Edit action

  4. Make your changes. Edit Synonym List dialog showing the Name and Status fields, and the Confirm button

  5. Click Confirm.

Upversioning a Synonym List

To change the Dictionary Version associated with a Synonym List, you must upversion the Synonym List. See Upversioning to a New Dictionary Release for details.

Review & Approve or Reject New Synonyms

Depending on your study’s configuration, you may have to review new Synonyms before they can enter into a Synonym List. When a coder user adds a term as a Synonym, that Synonym enters the Pending Review status. Until you approve the Synonym, Vault does not add it to the Synonym List for use in autocoding and suggestions.

Feature Availability: Review and approval for Synonyms is only available when Review Additions to Synonym Lists is enabled for your Study. When this feature is not enabled, all new Synonyms are automatically approved.

Approving Synonyms

To approve a Synonym:

  1. Locate the Synonym List new Synonyms in Coder Tools > Synonym Lists.
  2. Click to open the Synonym List.
  3. Hover over a Synonym to display the Actions menu.

  4. From the Actions menu, select Approve. Approve action

  5. Vault moves the Synonym into the Approved status. Vault now uses this Synonym to inform autocoding and suggestions.

To approve Synonyms in bulk:

  1. Locate the Synonym List new Synonyms in Coder Tools > Synonym Lists.
  2. Click to open the Synonym List.

  3. Select the checkbox to the left of each Synonym that you want to approve. Approve multiple synonyms

  4. Optional: To select all Synonyms at once, select the checkbox in the header.
  5. Click Approve. Approve button

Rejecting & Deleting Synonyms

For any Synonyms that you do not want to add to the Synonym List, you can either reject or delete the Synonyms. If you reject a Synonym, Vault does not use the synonym to inform autocoding, but the Synonym remains on the Synonym List. If you delete a Synonym, Vault does not use it for autocoding and deletes the record entirely.

To reject or delete a Synonym:

  1. Locate the Synonym List new Synonyms in Coder Tools > Synonym Lists.
  2. Click to open the Synonym List.
  3. Hover over a Synonym to display the Actions menu.
  4. From the Actions menu, select Reject or Delete.

To reject or delete Synonyms in bulk:

  1. Locate the Synonym List new Synonyms in Coder Tools > Synonym Lists.
  2. Click to open the Synonym List.
  3. Select the checkbox to the left of each Synonym that you want to approve.
  4. Optional: To select all Synonyms at once, select the checkbox in the header.
  5. From the Approve menu, click the Arrow ().
  6. Click Reject or Delete. Select Reject or Delete from the Approve menu

Import Synonyms

You can create Synonyms and add them into a Synonym List in bulk using a CSV (.csv) file.

Excel Localization for .CSV Files: Vault CDMS uses commas as the default separator for .CSV files. If your system is configured in a non-English language, you may encounter errors when attempting to upload .CSV files created or modified in Excel. We recommend that you change the localization of your system to English while working on the .CSV to avoid this issue.

During import, Vault validates each of the Synonyms in your imported CSV file to ensure that all assigned dictionary codes are also available in the dictionary release assigned to the Synonym List.

Importing Unmatched Synonyms and Codes: You can import Synonyms with a Noncurrent status in the Synonym List CSV file and the Synonym will retain that status in the Synonym List after import, however, Vault will not autocode Synonyms with a Noncurrent or Rejected status. If a Synonym in your CSV file has an assigned code that doesn’t exist in the target dictionary, that code can still be imported. If you’d like to import the unmatched code, you must assign the Synonym a Rejected or Noncurrent status to prevent the system from autocoding the unmatched code.

You can create an import CSV file using these templates:

  Download the WHODrug with ATCs Template   Download the WHODrug without ATCs Template   Download the MedDRA Template

Creating the Import File

  1. Download the template and open it in your preferred editor.
  2. Add a row for each Synonym you want to add to the Synonym List.
  3. Save your file.

Required Columns for WHODrug with ATCs Synonyms

The following columns are required in your import file:

  • Verbatim
  • Indication1
  • Route1
  • Drug Code
  • Drug Name
  • Preferred Code
  • Preferred Name
  • ATC4 Code2
  • ATC4 Name2
  • ATC3 Code2
  • ATC3 Name2
  • ATC2 Code2
  • ATC2 Name2
  • ATC1 Code2
  • ATC1 Name
  • Status

1 Leave the Indication and Route columns empty if you are importing for a Synonym List assigned to a Form that doesn’t collect data for Indication or Route.

Required Columns for WHODrug without ATCs Synonyms

The following columns are required in your import file:

  • Verbatim
  • Indication1
  • Route1
  • Drug Code
  • Drug Name
  • Preferred Code
  • Preferred Name
  • Status

1 Leave the Indication and Route columns empty if you are importing for a Synonym List assigned to a Form that doesn’t collect data for Indication or Route.

Required Columns for MedDRA Synonyms

The following columns are required in your import file:

  • Verbatim
  • LLT Code
  • LLT Name
  • PT Code
  • PT Name
  • HLT Code
  • HLT Name
  • HLGT Code
  • HLGT Name
  • SOC Code
  • SOC Name
  • Primary Path1
  • Status

1 The Primary Path is available to inform you and other administrators of the nature of each Synonym in the Synonym List. This value only applies to Synonym Lists.

Importing the File

To import the file:

  1. Locate the Synonym List you want to import Synonyms into.
  2. Hover over the Synonym List to display the Actions menu.

  3. From the Actions menu, select Import Synonyms. Import Synonyms action

  4. Either drag and drop your CSV file into the Drag and drop file here area, or click anywhere in the area and browse to and select your import file. Import Synonyms area

  5. Vault uploads the file and validates your new Synonym records. Validation results display in the Preview area. See possible validation errors below.
  6. Optional: If your import file contains any validation errors, edit the file to resolve them. Then click Change File to re-upload.
  7. Once all of your new Synonym records are ready for import, click Import. Vault begins a job to import and create all of your new Synonym records. Vault sends you an email notification when the job is complete.

Import Statuses

There are three possible statuses for a new Synonym List record as you prepare it for import:

Status Explanation
Error There is at least one error on this row. Errors indicate missing or invalid values.
Warning There is at least one warning on this row. Warnings indicate conflicts with existing Synonym List records.
Ready for Import This Synonym List record is complete and can be successfully imported into the vault.

Validation Errors

Error Field or Type Explanation Steps to Resolve
{Field} is required Verbatim This field is required. Provide a value for this field and re-upload your import file.
Duplicate Entry Verbatim Duplicate entry. Remove the duplicate entry from your file and re-upload your import file.
Synonym Already Exists User trying to import a Synonym that already exists The Synonym already exists on the Synonym List. Remove the Synonyms that already exist from your file and re-upload your import file.
{Field Name} exceeded allowed character length Character count exceeds max allowed in database Number of characters entered by the user is greater than database column length. Reduce the number of characters in the indicated field and re-upload your import file.
Code must include an ATC1 code and ATC1 name Code does not include an ATC1 code or name The Synonym List is configured to include ATCs and a record in the file does not include a value for ATC1 code and ATC1 name. Provide an ATC1 code or ATC1 name value for this field and re-upload your import file.
Code must not include any ATC codes or names Code includes ATC codes or names The Synonym List is configured to not include ATCs and a row in the file includes a value for one or more of the below ATC fields:
  • ATC1 Code
  • ATC1 Name
  • ATC2 Code
  • ATC2 Name
  • ATC3 Code
  • ATC3 Name
  • ATC4 Code
  • ATC4 Name
 Remove the ATC field(s) and re-upload your import file.

Export a Synonym List

You can export a Synonym List from your Study into a CSV file. This can be useful for record keeping and allows you to use all or a portion of your original Synonym List for another Synonym List.

  1. Locate the Synonym List you want to export.
  2. Hover over the Synonym List to display the Actions menu.

  3. From the Actions menu, select Export. Export action

  4. Vault begins a job to create a CSV of your study’s Synonym List. When finished, Vault sends you an email notification with a link to download the output CSV file.

The Synonym List export includes the same columns as the import file (WHODrug with ATCs, WHODrug without ATCs, and MedDRA).