Defining a Dictionary

To use a dictionary in TMS you must define it in the TMS user interface. This section includes:

• Defining the Basic Dictionary Settings
  
• Defining the Dictionary Levels
  
• Defining Relations Between Levels (Strong Dictionaries Only)
  
• Defining Level Details
  
• Setting the Dictionary's Status to Active
  

Defining the Basic Dictionary Settings

The Base Dictionary tab of the Define Dictionaries window enables you to define the high-level settings of a dictionary and to set a dictionary's status from Provisional to Active. This section discusses definition only, because you must keep the dictionary status set to Provisional while you complete the definition tasks. You use the Base Dictionary tab to set a dictionary to Active status later on. See Setting the Dictionary's Status to Active.

The high-level dictionary definition includes:

• The dictionary's name, short name, and description.

• Whether the dictionary is a base dictionary, virtual dictionary, or filter dictionary; see Virtual Dictionaries and Filter Dictionaries.

• The dictionary structure (strong or weak); Strong Dictionaries.

• The language of the dictionary's terms and relations.

• The Release Label prefix.

• Other settings that drive aspects of dictionary structure and the dictionary's availability to other components in TMS.

Sample Dictionary Definitions contains the definitions you must use in order to successfully load and activate practice dictionary CLS.

To define the basic dictionary settings:

1. From the Definition menu, select Define Dictionaries. The Define Dictionaries window opens, with the Base Dictionary tab selected.

2. Choose whether you want to create a base, filter, or virtual dictionary.

   • For a base or filter dictionary, begin by highlighting the Dictionaries line in the tree structure and select Insert Record.

   • For a virtual dictionary, select an active base dictionary folder in the tree and click the Virtual Dictionary tab. Select Insert Record. See Virtual Dictionaries for more information.

3. Define the dictionary itself (Name, Short Name, Description).

   Note:

   • Special characters are not allowed in the Short Name definition.

   • The short name must be exactly the same in the GUI definition and in the load script. Sample load scripts are available on My Oracle Support. See Sample Dictionary Definitions.

   • To delete a dictionary, you must place the cursor on the right side of the window in the Dictionary field (not the Dictionary Name in the tree). Before you can delete the dictionary itself, you must delete all the dictionary data, its levels, and set it to Provisional status.

The following steps apply to base dictionaries only. Virtual dictionaries inherit all settings from their base dictionaries.

1. From the Language list, select the language for this dictionary. You can link terms in dictionaries that have different languages by using named relations of type Translation.
2. From the Dict. Type list, select one of the following:

   • Base: Select Base to define a dictionary published by an external organization (such as MedDRA or WHO-Drug, or a legacy dictionary developed by your company.

   • Filter: Select Filter to use MedDRA SMQs or a similar standardized query dictionary; see Filter Dictionaries for more information.

   • Substitution: Select Substitution to define a dictionary to be used for search object transformations.

3. From the Folder Type list, select Strong to create a strongly defined dictionary or Weak to create a dictionary folder.
4. Leave the Status set to Provisional until you are ready to activate and use the dictionary; see Setting the Dictionary's Status to Active.
5. Enter a Label Prefix. Accept the default value of 1. or enter the prefix of your choice. TMS automatically concatenates this value with a build number that represents the number of times Activation has been run on the dictionary. If you use a numerical prefix, you may want to end it with a period/full stop (.) to separate the prefix from the build number.

   You may want to use additional decimal places to accommodate point releases of the same dictionary, and you may want to use the dictionary's official release number.

   For example, if you define a label prefix of 3.0. when you initially load WHO-Drug 3.0, TMS assigns a Release Label of 3.0.1 to the successfully activated terms and relations the first time you run Activation on the Activation Group, 3.0.2 the second time, and so on. You can use Release Labels, including the label prefix, to define named relations of type Release Label (RL); see Defining Named Relations.

   You can also use a text prefix such as MEDDRA, or a prefix that combines text and numbers, such as MEDDRA7.0.

6. Assess the following options for your dictionary, selecting the appropriate boxes:

   • VT Level Required? For strong dictionaries only. If selected, you must define a classification level or classification group level in your dictionary—which, in turn, creates a Verbatim Term level—before you can activate this dictionary. In the TMS modules that deal with verbatim terms (every module under the VTA Maintenance and Omission Management nodes, as well as Browse VT Classification Data), TMS populates the list of values in the Dictionary field from the set of dictionaries that have a VT Level Required? selected.

   • Term Uniqueness Enforced? If selected, terms in this dictionary must be unique over the scope of the entire dictionary. When you choose to enforce uniqueness for an entire dictionary, you in turn enforce term uniqueness on all levels and group levels within that dictionary.

   • Indication? Read-only flag for a dictionary indicating that can use Indication for classification. This Indication flag is determined by the level relations flag if selected.

   • VTI Allowed? Check to enable creating Verbatim Term Individual VTI) classifications. This is required if nonunique terms are allowed in the coding level, either with auxiliary information as in WHO-Drug C, or with different higher level relations, as you may have in MedDRA.

     If checked, VTIs can be allowed or not allowed for this dictionary in dictionary domains.

   • Autocode with Aux? Check to allow the TMS autoclassification process to create VTIs based on existing VTIs or dictionary terms with the same auxiliary information. Use this option if you are using a dictionary with nonunique terms in the classification level and auxiliary information for each term, such as WHO-Drug C.

     If checked, Autocoding with auxiliary information can be allowed or not allowed for this dictionary in dictionary domains.

7. Dictionary Term Display Procedure If desired, specify a procedure in this field to modify the behavior of the Dictionary Term field in VT classification and reclassification. By default, TMS displays the dictionary term to which the selected verbatim term is classified, if any. By writing a procedure and specifying it for a dictionary, you can display a different term in these fields.

   For details about writing a Dictionary Term Display Procedure, see Writing a Procedure to Change the Dictionary Display. Because this feature is only relevant for verbatim term classification, enter a procedure in this field only for strong dictionaries with verbatim term levels.

8. Save. For a base dictionary, TMS inserts the new dictionary into the tree structure. Virtual dictionaries do not appear in the navigation tree within the Define Dictionaries module. In either case, TMS populates the audit information fields.

The Virtual Dictionary tab window can only display definition information for a single virtual dictionary. If you define multiple virtual dictionaries against a base dictionary, you can scroll through the records to find the virtual dictionary you want to modify. From the Navigate menu, select Previous Record or Navigate, then choose Next Record to navigate to your choice. Alternatively, use the arrows on your keyboard.

Defining the Dictionary Levels

The Level tab of the Define Dictionaries window enables you to define a dictionary's levels. For strong dictionaries, begin by defining the topmost level in the dictionary hierarchy and work your way down. For weak dictionary folders, define all of the dictionaries you want to add to this dictionary folder.

To define dictionary levels:

1. Click the Base Dictionary tab. (You cannot add levels to virtual dictionaries.)
2. Click the name of your selected dictionary in the navigator tree.
3. Select Record, then Insert.

   The Level tabs replace the Dictionary tabs, and the new level definition appears in the Level tab window and in the navigator tree. If you are defining a weak dictionary folder, the fields in the Level Relations tab are grayed out.

4. Define the short name and name of the level.

   Note:

   The level names you define in the GUI must exactly match those you specify in the load script. See Sample Dictionary Definitions for the level names of the practice dictionary CLS.

5. Select Classification Level? if this is the level against which you want TMS to map verbatim terms. You can select classification level for only one level. If you use a group level for the classification level, you must also choose Level from the Term Uniqueness list.

   If you define this level as the classification level, TMS automatically creates a level under it called Verbatim Term Level where it will store verbatim term assignments (VTAs). TMS displays a blue "vt" above the relation line in the tree structure to denote that the level is the Verbatim Term Level.

   You can define classification levels for strong dictionaries only.

6. Select Aux Classifications? if this level is to be used during autocoding for matching to the verbatim term's auxiliary information. For example, you may only want to use MAH, Country, and Pharmaceutical Formulation as auxiliary information when coding the verbatim term to a dictionary term and the external system need to collect only MAH, Country, and Pharmaceutical Formulation.

   If additional Auxiliary Information is loaded into the dictionary and you do not select Aux Classifications for the auxiliary level, TMS will not use the auxiliary level during autocoding.

   Note:

   Aux Classifications? is added for the TMS 5.3 release.

7. Select Report Value? if you want TMS to report terms of this level to the external system as derived terms when they are called for by the external system, as long as the relation between this level and the next lower level is on the derivation path. See Derivation Path for more information.

   You can only create reportable levels in strong dictionaries.

8. In the Level Order field, enter a number only if this level is one of two or more levels at the same rank (children of the same parent level) in the dictionary hierarchy. Enter 1,2…n to specify the order in which TMS should display the levels vertically in the dictionary hierarchy tree structure. Levels with lower Level Order numbers appear higher in the tree structure. This has no functional effect; the setting is necessary only because you cannot display two levels in the same place in the tree structure. The field is enterable for all levels, but TMS only uses it to determine the presentation order of peer levels.
9. In the Level Type list, choose Level or Group Level. A group level is a level that contains more than one level within it. You must define a group level before you define the levels within it. See Group Level Constraints. If you are defining a group level, leave the Group Short Name field blank. To define other levels as sublevels within the group level:

   • Level Definition – Give sublevels a Level Type of Level and enter the group level's short name in the Group Short Name field.

   • Relation Definition – In the Level Relations window, define the top sublevel's relation with the parent group level as a Relation Type of Top Sublevel. See Defining Relations Between Levels (Strong Dictionaries Only). Define subsequent sublevels as having a Relation Type of Level in relation to the next higher sublevel.

   You can only define group levels in strong dictionaries. See Group Level Constraints and Tree Structure Display of Group Levels.

   Note:

   The Verbatim Term Level setting is for system use only; TMS enters this value automatically when it creates the VT Level. Levels that are neither group nor verbatim term levels should be called simply level here, including sublevels within a group.

10. Term Uniqueness:

    • If set to Level, terms within this level must be unique.

    • If set to None, there can be multiple occurrences of the same term in this level. Each occurrence may have different auxiliary information.

    • If set to Parent, term uniqueness is allowed within the parent level of a dictionary definition.

      Note:

      The "Parent" term uniqueness is added for the TMS 5.3 release.

11. If the level you are defining is one of the sublevels within a group, enter the short name of the group level in the Group Short Name field. Leave this field blank for all other levels, including the group level itself.
12. Save. TMS inserts the level into the tree structure, and populates the audit information fields.
13. To define subsequent levels for a strong dictionary, you can either:

    • Highlight the parent level in the tree structure and select Record and then Insert. Then choose New Level from the Level or Relation Creation dialog box.

    • Highlight any field in the Levels window and select Insert Record. TMS creates a child level of the level you highlight.

    To define subsequent dictionaries for a weak dictionary folder, highlight either the dictionary folder name or any of its dictionaries, and add a record.

Deleting a Level

To delete a level, highlight the level short name in the Levels window and select Delete Record. You cannot directly delete a verbatim term level, but you can remove one indirectly by either deleting the classification level above it or clearing the Classification Level? box for the classification level above it. In either case, TMS automatically deletes the verbatim term level.

Defining Relations Between Levels (Strong Dictionaries Only)

You define relations between levels in the Level Relations window, one pair of levels at a time. The child level is highlighted in the tree structure. See Group Level Constraints and Tree Structure Display of Group Levels.

Note:

You cannot define relationships between the levels, or microthesauri, in a weak dictionary folder, although you can define links between their terms. In such cases, the cardinality and optionality of the relation is defined by the named relation itself; see Defining Named Relations for more information.

For more information, see:

• Level Selection in the Define Dictionaries Window
  
• Defining Relations Between Levels
  

Level Selection in the Define Dictionaries Window

This window provides subtle visual cues to show you the currently selected dictionary level. Before defining your dictionary structure any further, be sure that you understand this user interface behavior and its consequences for dictionary definition.

There are two ways that the user interface displays levels as appearing to be selected:

• The level name appears highlighted, as in the left example in Figure 6-5. TMS highlights levels when you click them for the first time.
• The name appears highlighted and dashed lines are present above and below the level name, as in the right example in Figure 6-5. You can select a level by double-clicking any level, or single-clicking a highlighted level.

Figure 6-5 Figure 6-5 Highlighted and Selected Levels in Define Dictionaries

The difference between these selection states appears when you attempt to enter a new level into a dictionary. If you select Insert and then New Record when a level is highlighted, TMS inserts a child level under it.

However, if you insert a new record when a level is selected, TMS prompts you to choose between adding a new level under the selected level, or creating a new relation between the selected level and an existing level in the dictionary.

Defining Relations Between Levels

To define relations between levels of a strong dictionary:

1. Open the Level Relations window using one of the following methods, depending on:
   • If you are defining the relation between the level you have just created and its parent, click the Level Relations tab. TMS populates the parent and child level information.
   • If you are defining a relation between levels that already exist:
2. Highlight or select the parent level in the tree structure, click the Level Relations tab, select Record, and then Insert.
3. If you had selected (instead of highlighted) the level, TMS opens the Level or Relation Creation box. Select New Relation to an Existing Level? and click OK. TMS displays a list that includes all levels that do not currently have a relation with the parent level.
4. Select the level to which you want to define a relation and click OK. TMS enters the new relation in the tree structure: it displays the child level a second time with a relation line to the new parent level.
5. Click the new display of the child level in the tree structure and click the Level Relations tab. TMS populates the parent and child level information.

   For example, to create the standard definition of MedDRA you define a branch of related levels beginning with System Organ Class (SOC) and continuing to High Level Group Term (HLGT), High Level Term (HLT) and Preferred Term (PT), each the parent of the next. However, you can link the PT level directly to the SOC level. To create this relation, after you have created the PT level under the HLT level, select (do not merely highlight) the SOC level in the tree structure, select Insert Record, select New Relation to an Existing Level, select the PT level from the Child LOV, and define the relation.

6. From the Relation Type list, choose either Level or Group Level (Verbatim Level is for TMS system use only).
   • Choosing Top Sublevel instructs TMS to create the new level as the top sublevel within the parent level, which must have a Level Type of Group Level in the Level window. See Group Level Constraints. Top sublevels cannot have any other relation type specified; you cannot select any of the other flags in this window.
   • Choosing Level instructs TMS to create the new level as a child of the parent level. If the parent level is the top sublevel within a group, TMS creates the child as a lower sublevel within the group. If the parent level is a group level, the child level will be linked to the group level as a whole and cannot be linked directly to any of the sublevels within it.
7. Define the parent side of the relation. Select or leave deselected each box as it relates to the parent side of the relation.

   It may help to diagram the relation, indicating whether each end is either multi or single, and either mandatory or optional.

   For example, to define the relation shown below, leave both the Mandatory? and Many Cardinality? boxes clear for the parent level, and select both those boxes for the child level.

   

   See Sample Dictionary Definitions for sample dictionary diagrams and the corresponding definitions.

   • Mandatory? Select if terms in the parent level must have a link to a term in the child level.
   • Many Cardinality? Select if terms in the child level can have links to more than one term in the parent level.
   • Primary Link? Select if Many Cardinality? is selected for the parent level and you want to require that one of the terms in the parent level be defined as the child level term's Primary Link. If Derivable? is also selected for the parent level, you must select either the Primary Link? or Primary Path Link? boxes. Otherwise, TMS will not activate the dictionary.
   • Primary Path Link? Select this to define a Primary Path Link between the selected parent and child levels.
   • Derivable? There must be one and only one pathway to derivable levels from the classification level. Select if you want this relation to be part of that pathway.

     Note:

     • To derive terms from a dictionary level, the level must be on the derivation path (see Derivation Path), the level's Report Value? box must be selected, and the external system must be set up to request derived values from that level. For example, see Setting Up Data Collection in Oracle Clinical.
     • You cannot modify the automatically defined relation between the verbatim term level and the classification level. On the child side, Mandatory? and Many Cardinality? are selected; on the parent side, only Derivable? is selected.
   • Indication? There can be only one level defined with Indication if you want to use Indication Assignments to classify higher level terms and there is a many cardinality to the parent level.

     Note:

     Indication? is added for the TMS 5.3 release.

8. Define the child side of the relation. Select or leave clear each box as it relates to the child side of the relation.
   1. Mandatory? Select if terms in the child level must have a link to a term in the parent level.
   2. Many Cardinality? Select if terms in the parent level can have links to more than one term in the child level.

      Note:

      It is possible to define relations between levels of different dictionaries as well as levels within a dictionary. For more information on linking terms between dictionaries, see Setting Up Cross-Dictionary Relations.

9. Save. TMS populates the audit information fields.

Defining Level Details

This section describes what level details are and how to define them.

For more information, see:

• Understanding Level Details
  
• Defining a Dictionary's Level Details
  

Understanding Level Details

Level details are optional. They store and display additional, customized information about terms in a particular dictionary level. Details reference seven columns in the tms_dict_contents table. Level details enable you to customize these columns for your company's needs.

Note:

Level details and the validation configured within the Define Dictionaries module are only enforced and displayed from within the TMS Graphical User Interface. Batch loading of data does not adhere to these configurations.

TMS displays fields corresponding to Level Details in the Maintain Repository Data and Browse Repository Data windows. You define the field label, content type, and other characteristics for up to seven fields. These fields are:

• Label: The column heading that you want TMS windows to use for this column in this dictionary.

• Category: You can use this field to define a category for the term, such as 'Provisional' for terms as they go through the MSSO Dictionary Maintenance process.

• Dict Content Code: Corresponding to the dict_content_code column, this field is designed to serve as the primary key within this dictionary. This column is indexed.

• Dict Content Alt Code: By default, the Dict Content Alt Code has a function different from Values 1…4. It corresponds to the dict_contents_alt_code column, which is indexed, unlike the Value 1…4 columns. It is designed to allow you a cross-reference to a legacy thesaurus system.

• Value 1, 2, 3, and 4: You can use Value 1…4 to customize other fields in the Maintain and Browse Repository Data windows. For example, you could define that Value 1 for the WHO-Drug Dictionary's Preferred Term level was "number of ingredients." See Step 3 below to define a list of values for the field.

  Note:

  You can modify level details even in an active dictionary.

Defining a Dictionary's Level Details

This section describes how to define a dictionary's level details using the Define Dictionaries window.

To define a dictionary's level details:

1. Click the Level Details tab. The Level Details window opens.
2. In the Level Detail field, choose a value from the list.
3. Specify the label of the field to appear on the Maintain Repository Data form.
4. Write a description of the purpose and/or content of the field.
5. Specify the following:

   • Enterable? Select if you want the user to be able to enter a value in the field to appear on the Maintain Repository Data form.

   • Updateable? Select if you want the user to be able to update a value in the field, following the initial insert of the term.

   • LOV Validation? Select if you want TMS to validate that one of the values from the LOV is entered in the field. If Validation? is selected and the user enters an invalid value in the Maintain Repository Data window, TMS does not allow the user to save the record.

   • Mandatory? Select if you want the user to be required to enter a value in the field. If Mandatory? is selected, and you do not enter a value in the Maintain Repository Data window, TMS does not allow you to save the record.

   • Entry Length. Enter the maximum number of characters the field can contain. TMS does not allow the user to save a longer value in the Maintain Repository Data window.

   • Data Type. From the list, select the type of data to be contained in the field: char, date, or numbers. In the Maintain Repository Data window, TMS does not allow the user to save the wrong data type.

6. In the Description field, define the purpose or content of the field.
7. In the LOV Statement field, write a select statement to determine the items to appear in an LOV for the field (optional). The statement must select two columns from the database, one of which is the value that will be stored in the database, and the other of which is the value displayed in the LOV.

   For example:

   select 'A', 'Approved' from dual

   union

   select 'P', 'Provisional' from dual

   Note:

   Do not put a semicolon (;) at the end of the statement.

8. Save. TMS commits the level details to the database, and populates the audit information fields.

   To define another detail, put your cursor in the existing detail and select Insert Record.

Setting the Dictionary's Status to Active

When you are satisfied with all the dictionary's definitions, set its status to Active in the Status field of the Define Dictionaries window and save.

Once a dictionary is set to Active status, you may set its status back to Provisional only as long as it has no terms, TMS domains or VTAs associated with it, or if the dictionary has any Translation Derivation Links. However, you can still add levels to a weak dictionary folder even when it is set to Active status.

When changing the Active/Provisional status for a base or virtual dictionary, keep the following rules in mind:

• An Active base dictionary cannot be set to Provisional if an Active virtual dictionary based on it exists.

• A base dictionary set to VT Level Required cannot be set to Active unless it has one and only one verbatim term level.

• A Provisional virtual dictionary can be deleted at any time.

• A virtual dictionary with status Active cannot be deleted.

• The status of a virtual dictionary cannot be set from Active to Provisional if it is assigned to a domain.

• A base dictionary cannot be deleted if there are search objects associated with it.

• Changing the status of a base dictionary that has a virtual dictionary defined to provisional deletes the Provisional virtual dictionary.

The following table describes which activities are allowed when the dictionary is Provisional and when you set it to Active.

Table 6-1 Activities Allowed in Provisional and Active Dictionaries

Action	Provisional	Active
Modifying the dictionary short name	Yes	No
Changing the folder type (before any levels exist)	Yes	No
Changing enforcement of uniqueness of terms	Yes	No
Changing the VT Level Reqd? setting	Yes	No
Modifying the level hierarchy	Yes	For weak dict. folders only
Adding new level details	Yes	Yes
Modifying details	Yes	Yes
Modifying the dictionary name	Yes	Yes
Modifying the dictionary description	Yes	Yes
Modifying the dictionary Release Label prefix	Yes	Yes
Changing the level order	Yes	Yes