Managing Synonym Lists


Vault Coder uses Synonym Lists to inform autocoding. When autocoding, Vault compares pending Code Requests to Synonyms in the form’s Synonym List. 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

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. 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.

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 or Status. 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.

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, 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. Reject action Delete action

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. Then click Reject or Delete. Select Reject or Delete from the Approve menu

  6. Click Reject or Delete.

Import Synonyms

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

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.

If a Synonym in your CSV file does not match an entry in the dictionary, Vault allows you to import it and assigns that Synonym the Noncurrent status in Coder.

You can create an import CSV file using these templates:

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 Fields for WHODrug Synonyms

The following columns are required in your import file:

  • Verbatim
  • Indication
  • Route
  • Drug Code
  • Drug Name
  • Preferred Code
  • Preferred Name
  • ATC4 Code
  • ATC4 Name
  • ATC3 Code
  • ATC3 Name
  • ATC2 Code
  • ATC2 Name
  • ATC1 Code
  • ATC1 Name
  • Status
Leave the Indication and Route columns empty if you are importing Synonyms for a Synonym List assigned to a Form that is not configured to collect data for Indication or Route.

Required Fields 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
  • HTGT Code
  • HTGT Name
  • SOC Code
  • SOC Name
  • Primary Path
  • Status
The Primary Path value is available to inform you and other synonym list curators 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. No action needed.
{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.

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 file.

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


Last Updated: