6 Defining and Loading Dictionaries

Strong Dictionaries

A strong dictionary definition in TMS consists of a fixed number of hierarchical levels with defined relations between the levels. You store every dictionary term in a particular level and define relations from each term to terms in other levels, according to the relations you have defined for the levels themselves. This type of TMS dictionary definition is appropriate for external dictionaries such as MedDRA and WHO-Drug.

Strong dictionaries can serve as the base for creating virtual dictionaries and filter dictionaries; see "Virtual Dictionaries" and "Filter Dictionaries".

For more information, see "Planning Strong Dictionary Structure".

Weak Dictionaries

Some external dictionaries, such as SNOMED, require a different type of structure, one that is dynamically created by relations between terms. TMS supports these with weak dictionaries and named relations between terms.

Where strong dictionaries have fixed hierarchies, represented by levels, weak dictionary have dynamic hierarchies, which are variable. For example, a strong dictionary with four levels from the coding level to the highest derivation level will only have four terms in a hierarchical chain:

A weak dictionary does not depend on dictionary levels to identify the hierarchy. The hierarchical structure of the dictionary is defined by the relationships permitted and used in the dictionary. Named relations describe the connection between terms. For example, you can use the named relation Narrower term to link the terms "aspirin" and "pain reliever," or the named relation Is part of to define a hierarchical series of relations as follows:

In the above example, the number of terms that can be linked in a hierarchical chain is not limited by the number of levels. In fact, all of the terms (1 through 6) are on the same level, and the length of the hierarchical chain is unlimited. Dictionaries with this characteristic are called dynamic.

TMS requires that each dictionary definition have at least one level to contain dictionary terms. If your dictionary is really a collection of dynamic dictionaries, you can define a TMS dictionary level for each component dictionary and fully define the dynamic dictionary within that level. (Do not define level relations as you do in strong dictionaries.) If your dictionary is a single dynamic dictionary, define a single dictionary level for it. You can define named relations between terms in the same or different levels of a weak dictionary, as business needs dictate.

See "Defining Named Relations" for more information.

Virtual Dictionaries

Base dictionaries usually contain the latest dictionary and verbatim terms, because they are updated on an ongoing basis. These dictionaries are useful for studies that require the most up-to-date dictionary information.

By contrast, virtual dictionaries have defined cut-off dates, after which no dictionary terms can be added. Using a virtual dictionary enables you to continue coding verbatim terms for a clinical study against one version of a dictionary while the base dictionary changes. You can also use virtual dictionaries to view the state of a dictionary's terms and relations for any date in that dictionary's history. Virtual dictionaries can only be based on a single, active base dictionary, from which the virtual dictionary inherits its definition.

To set up a virtual dictionary in TMS, choose a base dictionary (and activate it, if the base dictionary is still provisional), define the virtual dictionary's name and cut-off date, and assign the virtual dictionary to a domain (see "Assigning a Dictionary to a Domain").

1. Define and activate the base dictionary on which you want to base the virtual dictionary; see "Defining a Dictionary" and set it to active; see "Setting the Dictionary's Status to Active".

2. Load data into the base dictionary and activate the data; see "Loading a Dictionary".

3. With the base dictionary displayed in the Base Dictionary tab of the Define Dictionaries window, click the Virtual Dictionaries tab.

4. From the Record menu, choose Insert Record. The system displays values for most fields that are inherited from the base dictionary. You can modify the Short Name, Name, and Description to make them more meaningful.

5. Define a Cut-off Date. All terms current at the point in time you specify will constitute the virtual dictionary. You cannot change the cut-off date after saving. Click in the Cut-off Date field. If other virtual dictionaries have been created for the same base dictionary, their cut-off dates are available in the LOV. If not, you can enter the date using the format:

   DD-MON-YYYY HH:MM:SS

   for example, 01-NOV-2006 10:01:15

   You can enter the date portion only and the system will enter a time of midnight.

6. If a Release Label has already been associated with the timestamp you selected, the system displays it in the Release Label field. You can modify it if necessary. Save.

7. When you are satisfied with your virtual dictionary definition, set its Status to Active and Save.

8. You can then assign an Informative Note of type Dictionary Version to the virtual dictionary by clicking the Info Notes button. See "Defining Dictionary-wide Informative Notes" for instructions.

To browse the state of a dictionary at a particular point in time, adjust the data currency to view the terms that were current in a dictionary at any date in the dictionary's history. To view such a representation of the dictionary, launch the Browse Repository Data form and enter the date in the appropriate field at the top of the window. For more instructions on browsing the repository, see Chapter 14, "Using the TMS Lite Browser."

Filter Dictionaries

This section includes:

• About Filter Dictionaries

• Using MedDRA SMQs in TMS

• Filter Dictionary Rules

• Defining Informative Notes for SMQ Algorithms

• Maintaining Filter Dictionaries

• Searching Filter Dictionaries Using the TMS Lite Browser

About Filter Dictionaries

Standardized MedDRA Queries (SMQs) are designed to aid in the identification and retrieval of case safety reports in clinical studies. The MedDRA Maintenance and Support Services Organization (MSSO) defines SMQs as follows:

SMQs are groupings of terms from one or more MedDRA System Organ Classes (SOCs) that relate to a defined medical condition or area of interest. They are intended to aid in case identification. The included terms may relate to signs, symptoms, diagnoses, syndromes, physical findings, laboratory and other physiologic test data, etc., related to the medical condition or area of interest. Lowest Level Terms (LLTs) that are not subordinate to an included Preferred Term (PT) are excluded.

See Figure 6-1, "Acute Pancreatitis SMQ Terms and Algorithm" for an example of a MedDRA SMQ.

TMS provides filter dictionaries as a generic way to support SMQs and potential similar features for other standard dictionaries. You define, load, and maintain a filter dictionary in the same way you define, load, and maintain a base dictionary such as MedDRA. You must define a filter dictionary as a strong dictionary with at least one level and link the filter dictionary to one and only one base dictionary. In addition, before you load MedDRA SMQs you must define broad and narrow named relations and algorithm Informative Notes (see below).

You can use the TMS Lite Browser to perform SMQ (filter dictionary) searches to retrieve dictionary terms and the VTAs and source terms related to them.

MedDRA SMQs may use one or more of the following design features:

• Broad and Narrow. SMQ relations with dictionary terms may be identified as broad or narrow. Narrow terms are highly likely to represent the condition of interest while broad terms help to identify all possible cases, including some that may prove to be of little or no interest. A broad search retrieves broad terms. A narrow search retrieves narrow terms.

  To support broad and narrow SMQ searches in TMS, define and load broad and narrow named relations from SMQ terms to base dictionary terms.

• Algorithm. Algorithms within SMQs are used to further define combinations of specific terms based on rules defined in an algorithm that can be processed programmatically during a search operation.

  To support SMQ algorithms, define an Informative Note of type Algorithm for SMQ terms with algorithms; see "Defining Informative Notes for SMQ Algorithms".

  MSSO provides predefined categories of terms called A…F. You must load these categories with SMQ filter dictionary terms and store them in the Status column of the table TMS_DICT_RELATIONS. Some SMQ algorithms use these categories.

• Hierarchy. Some SMQs are a series of queries related to one another in a hierarchical relationship similar to the hierarchical structure of MedDRA itself.

  To support hierarchical SMQ searches in TMS, load SMQ terms into different levels of the filter dictionary with relations between the terms.

Figure 6-1 Acute Pancreatitis SMQ Terms and Algorithm

Description of ''Figure 6-1 Acute Pancreatitis SMQ Terms and Algorithm''

Virtual Dictionaries of Filter Dictionaries You can create a virtual dictionary of a filter dictionary—that is, a filter dictionary at a specific point in time. The filter dictionary's virtual dictionary must have the same cut-off date and time as an existing virtual dictionary of its base dictionary.

For example, given the following dictionary definitions:

• MedDRA SMQ is the filter dictionary of MedDRA

• MedDRA Version 7 is a virtual dictionary of MedDRA with the cut-off date 8/1/2006 00:00:00

you can define a virtual dictionary called MedDRA SMQ Version 7 of MedDRA SMQ with the same cut-off date as virtual dictionary MedDRA Version 7: 8/1/2006 00:00:00. It will reference terms in virtual dictionary MedDRA Version 7.

In other words, if you are using a virtual dictionary for coding and you want to use a filter dictionary with it, you must create a virtual dictionary of the filter dictionary with the same cut-off date as the virtual dictionary you are using for coding.

Nonunique Coding Level Dictionaries

In WHO-Drug Format C, many drug names occur more than once in the coding level. They are distinguished from one another by auxiliary information including the country where they are distributed, their pharmaceutical form (for example, tablets or coated tablets), and their strength (for example, the number of milligrams per tablet). In the TMS dictionary definition, each type of auxiliary information (country or strength, for example) is defined as a sublevel of the classification level.

Auxiliary information must be imported from the source data system for each source term as a definition-value pair consisting of a dictionary level and data value; for example, Strength and 500mg. Updates to auxiliary information should be treated as source term updates.

If you are using Oracle Clinical, you can set up question sets to handle multiple input question responses for each source term. In addition to providing auxiliary information about the drug, you can send information about the indication for which the drug is being taken. This is required in cases where the term must be classified differently depending on the indication, or where a different higher level term must be derived depending on the indication. See "Classifying High-Level Terms Based on Indication,""Defining Question Set Variables," and "Classifying Indication Omissions."

The classification of a verbatim term with a specific set of auxiliary information values to a nonunique dictionary term is called a verbatim term individual (VTI), similar to a verbatim term assignment (VTA) for classifications to unique dictionary terms. Both VTAs and VTIs are supported in the same dictionary. TMS handles VTIs similarly to VTAs, but with some differences. VTIs are always created as approved and are always specific to a domain—never global. Both VTAs and VTIs can be designated either misspelled or accepted.

TMS captures and stores sets of auxiliary information values, assigning an ID to each set and reusing it for terms in all dictionaries and domains that have the same combination of auxiliary information values. For example, the first time the source term Carbamazepine is classified to the dictionary term Carbamazepine with auxiliary values Netherlands, coated tablet, and 200mg, TMS creates an ID such as 1000 for the value collection. When a different verbatim term that shares the same values—Netherlands, coated tablet, 200mg—is classified to any drug, TMS uses the same auxiliary information ID for the new VTI. The ID is stored with its values in the Auxiliary Information table, and the ID is included in the Omissions and Source Terms tables.

Autoclassification cannot match a source term to a nonunique dictionary term until a user manually classifies it. After that, if the dictionary is defined to allow autoclassification with auxiliary information, it classifies all occurrences of the same verbatim term with the same auxiliary information to the same dictionary term.

MedDRA also supports classifying the same source term to different dictionary terms. For example, the source term "Migraine Headache" might sometimes be classified as "Headache" and other times as "Migraine."

Classifying High-Level Terms Based on Indication

Different instances of the same dictionary coding-level term may be classified to different high level terms—for example, Anatomical - Therapeutic - Chemical (ATC) terms in WHO-Drug Format C—based on the indication for which the drug was taken by a patient. In this case, multiple high-level terms are related to a single lower-level dictionary term with no primary path defined. TMS cannot derive the high-level term and creates an indication omission. After a user has manually classified the indication omission, TMS derives all current and future occurrences of the same term for the same verbatim term/indication combination.

In Oracle Clinical you can create a question set variable of type Indication to collect the indication; see "Defining Question Set Variables". If you are using a different external source data system you must also import "Indication" and the indication value as a value pair to support this feature.

Uniqueness of Terms

In addition to the flexibility with which many internal and vendor-supplied dictionaries define their hierarchies and relationships, dictionaries can also differ in the manner in which they handle a term's uniqueness. You can specify that terms be unique throughout a level or group level in a dictionary, throughout all levels of a dictionary, or choose not to enforce uniqueness of terms at all for a particular dictionary.

If you plan to use a dictionary for classification of verbatim terms, you must enforce uniqueness on the classification level. For other internal or vendor-supplied dictionaries, choose the degree of uniqueness based on how duplicate terms exist within the dictionary.

TMS evaluates uniqueness based on the "term upper" version of a dictionary term, in which TMS converts the dictionary term to all uppercase letters and removes all extraneous spaces.

Defining Relationships Between Dictionary Levels

To create strong dictionary relations in TMS, so that you can link terms in one level to terms in another, you must define relations between the levels in the dictionary structure.

During Activation, TMS checks all terms and relations against the relations defined for their dictionary levels. Terms and relations whose definitions conflict with the defined level relations cannot be activated. For example, if you have defined relations to more than one term in a level with a Single cardinality relation, the Activation job activates the first relation it processes and rejects the rest.

You must define the following attributes for relations between levels within a strong dictionary: Mandatory Relations and Cardinality. For relations with Many cardinality defined you can also define a Primary Link or, if the dictionary includes a group level, a primary path.

The relations you define between levels create the derivation path for verbatim terms associated with the dictionary. A valid derivation path enables TMS to derive one and only one term from each level above the verbatim term level, and send the derived terms to an external system such as Oracle Clinical (see "Derivation Path"). If Single cardinality is defined from the lower to the higher level, no Primary Link is required because a term in the lower level can be related to only one term in the higher level, and TMS can derive that term. If Many cardinality is defined, so that a term in the lower level can be related to multiple terms in the higher level, you must require a Primary Link to identify which related term in the higher level is derived. See "Primary Links and Primary Path Links".

Primary Links and Primary Path Links

If you define a relation where a term in Lower Level B can be linked to many terms in Higher Level A (Many cardinality), you can specify that each term in Lower Level B must have a Primary Link to a single term in Higher Level A. If the relation is on the derivation path—levels from which TMS can derive terms to be sent to an external system—you must require a Primary Link. Otherwise, TMS cannot activate the dictionary.

When a Primary Link is required, it is possible to create a Domain Primary Link for a particular term to override its Global Primary Link within a particular domain.

When you define a group level, you can define primary relations from terms outside (and below) the group level to the group level in two different ways:

• Primary Link. If you define a Primary Link to the group level, and Many cardinality is defined on the higher side of level relations, the lower-level term can have links to multiple terms on multiple levels in the group level, but only one link can be the Primary Link. The Primary Link can be between the lower-level term and a single term on any level within the group level.

• Primary Path Link. If you define a Primary Path Link to the group level, a term in the lower level can have links to multiple terms in multiple levels within the group level, but it must have a Primary Link to a term in the lowest level within the group, and to a related term in the next highest level, all the way to the top level.

  You must load or define the Primary Link for each lower-level term to a term in each of the group levels from the bottom up. TMS restricts your choices at each level to terms that are related to the Primary Link term in the immediately lower level. Thus, different lower-level terms can have a Primary Link to the same term in the lowest group level but different terms in the higher group levels (see Figure 6-2).

  Primary Path Links are designed to accommodate MedDRA's structure.

See "Grouping Levels" for background information on group levels.

Figure 6-2 shows derivation paths using Primary Link (on the left) and a primary path (on the right). In these examples, all relations between levels are many-to-many, so Primary Links are required for each relation in the derivation path.

• The example on the left shows a dictionary structure without a group level, where a Primary Link is required between each level and the next higher level. Terms PT1 and PT2 are both defined with a Primary Link to the same term—HLT1—in the next higher level. Their derivation path is the same because the rest of the derivation path depends on the Primary Links defined for the higher-level terms: HLT1 has a single Primary Link to HLGT1, which has a single Primary Link to SOC1.

• The example on the right shows a dictionary structure where the HLT, HLGT, and SOC levels are all included in a group level, but a primary path is defined between the PT level and the group level. In this case, terms PT1 and PT2 can be linked to the same term in the HLT level and yet be linked to different terms in the two higher levels. This model conforms to MedDRA's structure.

Note:

Note that there is a third possible structure. If you defined the same group level as in the example on the right—containing the SOC, HLGT, and HLT levels—and defined a Primary Link from the PT level to the group level instead of a Primary Path Link, then the terms PT1 and PT2 would each link to HLT1 but, if Many cardinality were defined from the HLT to the HLGT and from the HLGT to the SOC, their derivation path would end there. No higher level terms could be derived because no other Primary Links or primary paths would exist.

If Single cardinality were defined from the HLT to the HLGT and from the HLGT to the SOC, and those levels were defined as reportable and their relations as derivable, the derivation path would continue all the way to the SOC level.

Figure 6-2 Derivation Path Examples for MedDRA

Description of ''Figure 6-2 Derivation Path Examples for MedDRA''

Grouping Levels

You can arrange levels of a strong dictionary into a group level, and define other levels as having a relation with the group level rather than one or more of its sublevels. You can then define individual terms as having relations with terms in sublevels within the group level. This enhances efficiency and functionality by:

• Eliminating unnecessary duplication of terms in more than one level. By enforcing uniqueness of terms throughout the VTC group level in Figure 6-3, for example, you can ensure that no duplicate terms exist between the PN and SYN levels.

• Allowing you to define a Primary Link requirement to the group level as a whole; when you define specific Primary Links for terms from outside the group level to the group level, you can choose to create the Primary Link to a term in any one of the group's sublevels.

For example, you could define WHO-Drug as shown in Figure 6-3, with two group levels, ATC and classification level VTC:

Figure 6-3 Group Levels in a Sample WHO-Drug Dictionary

Description of ''Figure 6-3 Group Levels in a Sample WHO-Drug Dictionary''

This definition of WHO-Drug makes use of the Group Level feature as described in the following two sections.

Tree Structure Display of Group Levels

Group levels do not fit easily into a standard tree structure display. TMS displays them as follows:

• If a group level exists below the top of the hierarchy, its sublevels are displayed twice: once below the group level, which is displayed as a sibling level to the level above (because it cannot be defined as a child level), and once directly under the higher level with the relation between the top sublevel and the higher level displayed.

• The Group Level icon is displayed to the left of the group level.

• The relation icons (lines, dotted lines, and branches) appear in color for all sublevels within a group except the topmost, which by definition cannot have a conventional relation defined to the group level.

This display is for a sample WHO-Drug dictionary as shown in Figure 6-4.

Figure 6-4 Sample WHO-Drug Dictionary in the TMS Navigator Tree

Description of ''Figure 6-4 Sample WHO-Drug Dictionary in the TMS Navigator Tree''

Deriving Terms

When TMS successfully maps a verbatim term to a dictionary term, it derives related terms or other user-defined information from the dictionary levels you specify when you set up the derived questions in Oracle Clinical question sets. See "Defining Questions". When you use TMS with another external system, you must create the objects to receive the derived values and the mechanism to call for them. If TMS is fully integrated with the external system, it derives the values to the external system on demand.

In MedDRA, for example, you can classify the verbatim term secondary anemia to the classification level term secondary anaemia (LLT). In the dictionary definition, you can specify that the Preferred Term (PT) and System Organ Class (SOC) levels be derivable and reportable. If you have specified that TMS should derive a term, TMS returns the PT level term secondary anaemia and the SOC level term blood and lymphatic system disorders.

See the Oracle Thesaurus Management System Technical Reference Manual for more information on integrating TMS with external systems.

Enforcing the Structure

Each time TMS tries to activate a term, it runs several types of validation tests to ensure that the term and its relations conform to the dictionary structure you have defined. During this process, TMS:

• Checks if the term and its relations to terms in other levels do not violate the cardinality and optionality specifications you have defined between levels.

• Runs any additional validation code to enforce further rules and relations (see Step 8, "Add Validation Code (Optional)").

• Prevents deletion of terms linked to a verbatim term assignment.

Strong Dictionary Structure in Other Forms

TMS reflects the structure you define in the way it displays the dictionary in the Maintain Repository Data and Browse Repository Data windows. See "Using the Tree Structure" for details on how TMS reflects dictionary structure in these windows.

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.

Appendix A, "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).

   Notes:

   • 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 Appendix A, "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.

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.

   • Web Search Accessible? This setting is obsolete.

   • Accessible to Light Browser? Can the dictionary be used at all in the TMS Lite Browser? If selected, TMS users will be able to browse and search this dictionary's terms, relations, and VTAs in the TMS Lite Browser.

     Before activating this option, consider this dictionary' usage and the sensitivity of its data. The TMS Lite Browser may be set for Auto-login, meaning that users do not have to enter a user name and password to browse accessible data. See "Customizing the TMS Lite Browser URL to Support Additional Databases or Automatic Login."

     Do check this flag for filter dictionaries to enable filter dictionary searches using MedDRA SMQs.

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

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

   • Autoqueried in Light Browser? Is the dictionary available for browsing in the Exploration/Hierarchies tab of the HTML Browser? If selected, the TMS Lite Browser automatically queries for all terms in the top level of the dictionary when you select the dictionary in the main TMS Lite Browser window. This setting is appropriate only for strong dictionaries (dictionaries with hierarchical levels defined).

     Not recommended for dictionaries in which most or all of the terms are stored in the highest or only level, because autoqueries in such dictionaries can be very time- and resource-consuming.

     Note:

     The Terminologies tab in the TMS Lite Browser appears only if both Autoqueried in Light Browser? and Accessible to Light Browser? are checked for at least one of the dictionaries linked to the current domain.

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 delete a level, see "Deleting a Level".

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

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

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

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

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

11. Save. TMS inserts the level into the tree structure, and populates the audit information fields.

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

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 Highlighted and Selected Levels in Define Dictionaries

Description of ''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 Level Details

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

• Understanding Level Details

• Defining a Dictionary's Level Details

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.

Required Setup

Before you load a dictionary, check that you have the necessary setup:

• Loading data into the temporary tables requires Oracle SQL Loader, which is part of your basic Oracle software package, and is located in the bin directory.

• Create a new user for loading data into TMS. In the TMS Define Users window, create a superuser and set the Load User? flag to Yes. For more information, see "Defining Users".

• Define the dictionary structure, domains, activation groups, dictionary named relationships and dictionary informative notes attributes (instructions in this chapter and in Chapter 7, "Defining Other TMS Elements").

• Download the appropriate sample scripts from My Oracle Support and edit them for your installation. See "Downloading Sample Scripts."

About Load Scripts

If you are loading data into TMS, a load script is necessary to move the data from temporary tables to the predict tables (pre-dictionary tables). Your load script must be consistent with your dictionary level and level relation definitions.

Oracle supplies sample load scripts for various dictionaries including MedDRA, MedDRA Primary Path, MedDRA SMQ, WHO-Drug B, B2, and C, and SNOMED on My Oracle Support. The corresponding dictionary structures are described in Appendix A, "Sample Dictionary Definitions."

Load scripts must do the following for each defined element that you are using:

• Load dictionary terms into tms_predict_contents.

• Load relations between terms, including named relations, into tms_predict_relations.

• Load named relation definitions into tms_def_named_rels.

• Load mappings between named relationships and dictionaries into table tms_def_dict_nrls.

• Load Informative Notes into tables tms_predict_info_hdrs, tms_predict_info_strs, and tms_predict_info_clobs.

• Load Informative Note attributes into tms_def_details.

• Load mappings between Informative Notes and the items they describe or complement—dictionaries, terms, or relations—into table tms_def_dict_info_dets.

Downloading Sample Scripts

Download instructions and sample scripts from My Oracle Support at https://support.oracle.com.

1. Sign in to My Oracle Support.

2. Search for Article ID: 258975.1; see "Searching by Article ID." The article is titled Sample Maintenance Scripts for MedDRA, MedDRA Primary Path, MedDRA SMQ, WHO-Drug Formats B, B2, and C, and SNOMED.

3. Scroll down to the Attachments section and download the file for the dictionary you want to load.

Creating or Assigning an Activation Group

You must assign all data to an Activation Group for TMS to load it into predict tables and, later, to activate it. TMS activates all data in the group in the same batch job. You can use an existing group or define a new one. To define a new Activation Group:

1. From the Repository Maintenance menu, select Maintain Repository Data. The Maintain Repository Data window appears.

2. Highlight Activation Groups in the tree structure and select Insert Record.

3. Enter a name and description. (If you are setting up the practice drug dictionary CLS, name the Activation Group CLS_AG.)

4. Under Dictionaries within the Activation Group, click in the Short Name field and press F9 to see the LOV. Select the dictionaries you want to include in the Activation Group.

5. Save. TMS populates the Name and In Domain? fields. When you run Activation on this Activation Group, TMS processes all dictionaries associated with this group. However, if a dictionary is not assigned to the current domain, you cannot see it in the Maintain Repository Data window and therefore cannot use the GUI to modify it. To add a dictionary to a domain, from the Definition menu, select Define Domains, and click the Dictionaries button.

Running the Activate Preliminary Data Batch Job from the GUI

To invoke Activation from the TMS Graphical User Interface:

1. From the Repository Maintenance menu, select Activate Preliminary Data. The Batch Job window appears.

   Note:

   You can also invoke Activation (immediately, in Transfer mode only, on the current Activation Group) from the Maintain Repository Data window by clicking the Transfer Data button.

2. In the Job Specific section, click the Activation Group field. A list arrow appears.

3. Select an Activation Group from the list. (For information about Activation Groups, see "Creating or Assigning an Activation Group".)

4. Click the Activation Mode field. A list arrow appears.

5. Select an activation mode from the list. The choices are:

   • Check. TMS invokes the Activation process, but stops short of transferring valid data to the production tables. You can view data that would fail activation in the Maintain Repository Data window and make the necessary changes before activating the data.

   • Transfer. TMS runs the Activation process to completion. Valid data is transferred to the production tables. Invalid data remains in the predict tables.

6. In the Schedule section, enter the name of the report server. Other schedule options appear.

7. Select Submit from the Job menu or click the Submit icon.

Running Activation from SQL*Plus

To run Activation in Transfer mode, type:

exec tms_user_activation.activateterms (Predict_Group_Id, 'T')

To run Activation in Check mode, type:

exec tms_user_activation.activateterms (Predict_Group_Id, 'C')

You can monitor the Activation process and analyze the tables to optimize execution speed. To do so, from SQL*Plus, type:

select count (*) from tms_dict_contents

In previous versions, it was necessary at this stage to compute statistics to speed the job, then reanalyze tables after job completion. The Activation batch job performs these steps for TMS 4.0 and later, so these steps are no longer necessary.

Add Validation Code (Optional)

TMS provides an empty package, tms_ud_activation_rules, that runs immediately after TMS has completed its own activation process. You can modify the package to include additional validation code.

For example, you can specify using a SQL statement that in MedDRA, a preferred term must always also exist as a lowest level term. If TMS finds a preferred term without a corresponding lower level term, the preferred term stays in the predictionary table with an error message saying it failed activation due to user-defined validation code.

When you write code in TMS, refer to the package tms_def_dict_cons for constants including the dictionary ID, dictionary levels, and any other constants relevant to all active dictionaries.

Refreshing the Context Server Index

After activation refresh the context server index; see "Refreshing the Context Server Index".

Gathering Statistics to Improve Performance

Refresh schema statistics to improve performance. This is especially important after activating WHO-Drug C. See "Running Scripts to Gather Schema Statistics for the 12c Optimizer."

About Activation

During Activation, TMS processes terms and relations in one Activation Group at a time, enforcing the integrity of their relations against the level relations defined for the dictionary. TMS gathers threads of data—terms related directly and indirectly to each other—and checks all the links in the thread.

Maintain Data Repository Window

From the Repository Maintenance menu, select Maintain Repository Data, and select All Data from the Data Source list to see data in the production and predict tables. Terms and relations that failed activation have error messages explaining the reason for the failure in the Error Message field. See "About the Maintain Repository Data Window" for more information.

Preliminary Repository Report

To run the Preliminary Repository Report, do the following:

1. From the Repository Maintenance menu, select Preliminary Repository Report.

2. Enter a Destination Type and any dependent fields (see "Running a Job").

3. Under Job Specific, enter values for the following parameters:

   • Activation Group. From the list, choose the Activation Group whose data you want to check.

   • Activation Data Scope. From the list, choose All to see all records in the Activation, whether or not they were successfully activated; or Errors Only to see only data that failed activation.

4. Set schedule parameters, to run the job at a future time (optional; see "Scheduling Parameters").

5. Click the Submit Job icon.

Defining a Cross-Dictionary Link

Using cross-dictionary links can help you migrate a study from one base dictionary to another more easily. It also provides you more flexibility in creating relations in the repository.

Before you can define relations between terms in different dictionaries, you must link the dictionaries using the Dictionary Link tab window. TMS refers to the links you define in this window when it lists the candidate dictionaries for a reference term in the Repository Authoring window. After you select the first term in a relation, TMS restricts the list of candidate dictionaries for the reference term in the relation by using the cross-dictionary links defined for the first term's dictionary.

After you define the cross-dictionary links you need for a particular dictionary, see "Setting Up Cross-Dictionary Relations" to define relations between terms in the linked dictionaries.

Rule

You must choose two Active base dictionaries. Term mappings can span dictionary levels, although group and VT levels do not support term mappings.

Creating a Cross-dictionary Link

To create a cross-dictionary link in the TMS user interface:

1. From the Define Dictionaries window, choose either dictionary in the relation by clicking its name in the structured part of the window.

2. Click the Dictionary Link tab. The Define Dictionaries window displays the Dictionary Link tab window.

3. Choose Record, then Insert.

4. From the Link Type field, choose Cross Dictionary Link.

5. From the To Dictionary list, choose the dictionary to which you want to link.

6. Save. If both dictionaries satisfy the linkage criteria listed above, TMS commits this cross-dictionary link to the database.

You can create links from one dictionary to multiple target dictionaries. Select links to other target dictionaries by selecting the next lines and inserting records.

You can break a cross-dictionary link by deleting its row from the Dictionary Link tab window. TMS allows you to remove a cross-dictionary link only if no dictionary named relations have been defined between the linked dictionaries.

Defining a Translation Derivation Link

Translation Derivation Link enable you to connect a global language dictionary (usually one with terms and relations in English) to an identically structured local language dictionary. Once you define the link, the reporting levels of the two dictionaries are linked. You can then automatically derive a translation for a reported level term in either direction: you can determine the global language equivalent of a term in the local language dictionary, or vice versa.

TMS derives a term's translation by searching in the non-coding dictionary for a term on the same level that shares the same dictionary code. Note that TMS still derives values in the coding dictionary by using the hierarchy of that dictionary.

Because TMS cannot derive translations correctly unless each code appears exactly once in each of the linked dictionaries, you should run the Translation Reports to resolve differences between the data in these dictionaries after you link them. See "Translation Reports to Identify Inconsistent Data" for details.

In this section, you only define the Translation Derivation Link between two dictionaries. During the process of Linking an Oracle Clinical Study to TMS in the TMS Domain Elements window, you identify the global language dictionary and local language dictionary in this pairing, and define which one is the coding dictionary for this Oracle Clinical project or study.

Rules

The dictionaries must satisfy the following criteria:

• You must select two Active base dictionaries with identical structure. The short names of the dictionary levels must match exactly.

• The dictionaries must be in different languages. You set a dictionary's language from the Language field in the Base Dictionary tab.

• Both dictionaries must have a coding level.

• The linked dictionaries must have dictionary codes that use the same number of bytes to store each digit. Single-byte and multibyte (or "narrow" and "wide") representations of the same characters are not considered equivalent by TMS.

You can only delete Translation Derivation Links when neither of the linked dictionaries contains any data. You also cannot set a dictionary to Provisional status if it has a Translation Derivation Link.

Defining a Translation Derivation Link

To define a Translation Derivation Link:

1. From the Define Dictionaries window, choose either dictionary in the relation.

2. Click the Dictionary Link tab. The Define Dictionaries window displays the Dictionary Link tab window.

3. Choose Record, then Insert.

4. From the Link Type field, choose Translation Derivation Link.

5. From the To Dictionary list, choose the dictionary to which you want to link.

6. Save. If both dictionaries satisfy the linkage criteria listed above, TMS commits this cross-dictionary link to the database.

To delete a Translation Derivation Link, select its row in the Dictionary Link tab window, choose Record, and then Delete. As stated in the Rules, you cannot delete a Translation Derivation Link if data exists in either of the linked dictionaries.

Defining Filter Dictionary Links

When you define a filter dictionary, you must create a dictionary link between the filter dictionary and its base dictionary. You can define the link in either direction; TMS then displays the link from each dictionary. You must define these links before you can activate the filter dictionary.

Each filter dictionary can have only one base dictionary, and each base dictionary can have only one filter dictionary.

Filter to Base To create a link from the filter dictionary to its base dictionary, do the following:

1. With the filter dictionary selected in the Define Dictionaries window, click the Dictionary Link tab. The Dictionary Link tab opens.

2. From the Link Type list, select Filter Dictionary of.

3. Click in the To Dictionary field. The Cross Dictionary Link Dictionaries list of values appears.

4. Select the base dictionary. For the MedDRA SMQ filter dictionary you must select MedDRA as the base dictionary.

5. Save.

Base to Filter To create a link from the base dictionary to a filter dictionary, do the following:

1. With the base dictionary selected in the Define Dictionaries window, click the Dictionary Link tab. The Dictionary Link tab opens.

2. From the Link Type list, select has Filter Dictionary.

3. Click in the To Dictionary field. The Cross Dictionary Link Dictionaries list of values appears.

4. Select the filter dictionary.

5. Save.

Creating a Domain

To create a domain:

1. From the Definition menu, select Define Domains to reach the Define Domains window. The Define Domains window has two tabs: Domains displays a single domain and its audit information, and Multi Display Domains displays the names and descriptions of several domains at once.

2. Insert a new record in either tab window, and enter a name and description for the new TMS domain.

   Note:

   Do not use special characters in the Domain Name. Characters such as (& @ *) may cause problems, including preventing using the Disconnected System Integration feature for studies associated with the domain.

3. Save. TMS populates the audit fields.

4. Click the Dictionaries button to reach the Define Domain Dictionaries window. See "Assigning a Dictionary to a Domain".

Assigning a Dictionary to a Domain

You must assign a base dictionary to a TMS domain before you can use it (filter dictionaries inherit their domain assignments from their base dictionary). A dictionary may be assigned to more than one domain, and a domain may have more than one dictionary, and any number of non-external terms, assigned to it.

To assign a dictionary to an existing TMS domain:

1. From the Definition menu, select Define Domains to reach the Define Domains window and query for the domain to which you want to assign one or more dictionaries.

2. Click the Dictionaries button to reach the Define Domain Dictionaries window.

3. Click the ellipsis (…) or press F9 to launch the list of values for available dictionaries.

4. Select a dictionary and click OK.

5. Select VTA Appr Reqd? to require that in this dictionary/TMS domain combination, all VTAs are created as Unapproved. There is one exception to this rule: if the VTA has been created via Synchronization because of a direct match to a dictionary term, the VTA is created as approved.

   This may be useful at the beginning stages of a study, or use of the TMS domain, because it gives you the opportunity to manually check TMS's classifications. When you are satisfied that a classification is correct, you can manually approve the VTA in the Approve VTAs window under the Omission Management menu. After you do, TMS classifies all future occurrences of the verbatim term automatically.

   The default setting of the VTA Appr Reqd? flag is determined by the setting of a reference codelist value that appears in the TMS_CONFIGURATION codelist; see "DOMVTAAPPRREQD".

   You can change the VTA Appr Reqd? flag setting at any time, including during an ongoing study.

6. Select the Action Appr Reqd? box to require that in this dictionary/TMS domain combination, all Answerable Action assignments must be manually approved. Internal Actions are used for this purpose.

   The default setting of the Action Appr Reqd? flag is determined by the setting of a reference codelist value that appears in the TMS_CONFIGURATION codelist; see "DOMACTAPPRREQD".

   You can change the Action Appr Reqd? flag setting at any time, including during an ongoing study.

7. VTI Allowed? Check to make it possible to create Verbatim Term Individual (VTI) classifications. This is required if non-unique terms are allowed. It is possible to select this setting only if VTIs are allowed in the dictionary definition.

8. Autocode with Aux? Check to enable the TMS autoclassification process to create VTIs after the same term with the same auxiliary information has been manually classified. It is possible to select this setting only if it is allowed in the dictionary definition. Changing this setting affects only future executions of Autoclassification.

9. In the Non Appr DT drop-down:

   • Select None to prevent classification to nonapproved dictionary terms.

   • Select VTA to allow classification to nonapproved dictionary terms. This setting may be appropriate, for example:

     • during post-marketing surveillance if you do not want to have to reclassify verbatim terms whose dictionary terms become invalid (nonapproved) after a dictionary upgrade

     • if you are using MedDRA-J and want to be able to classify terms to nonpreferred Japanese terms when multiple Japanese terms correspond to the same English term.

     When you select this option, in this domain the Autoclassification job treats nonapproved terms exactly the same as approved terms in this dictionary.

     Note:

     You can change this value from VTA to None only if no current VTAs are linked to a nonapproved dictionary term in the dictionary/domain combination.

10. To add another dictionary, click in the next row and repeat the process.

11. Click OK. TMS saves the domain/dictionary links you have defined.

Unassigning a Dictionary from a Domain

To unlink a dictionary (to prevent its use in this TMS domain), highlight it and select Record, then Delete.