Oracle Thesaurus Management System (TMS) enables you to design, define, and load dictionary data into its repository.
You must have the tms_define_priv role to define dictionaries and domains. See Chapter 3, "Administration" for information on granting this role to users.
This section includes:
You can define the following types of 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.
For more information, see "Planning Strong Dictionary Structure".
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.
Note:You cannot code verbatim terms against weak dictionaries because they do not have a specific classification level.
See "Defining Named Relations" for more information.
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").
Load data into the base dictionary and activate the data; see "Loading a Dictionary".
With the base dictionary displayed in the Base Dictionary tab of the Define Dictionaries window, click the Virtual Dictionaries tab.
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.
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:
for example, 01-NOV-2006 10:01:15
You can enter the date portion only and the system will enter a time of midnight.
When you are satisfied with your virtual dictionary definition, set its Status to Active and Save.
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."
This section includes:
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.
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.
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.
To use MedDRA SMQs in TMS, do the following:
Define a filter dictionary for MedDRA SMQs; see "Filter Dictionary Rules".
Specify its base dictionary in the Dictionary Links tab, using the link type Filter Dictionary Of. For the MedDRA SMQs filter dictionary, the base dictionary must be a MedDRA dictionary. See "Defining Filter Dictionary Links".
Note:Filter dictionaries inherit their domain assignments from their base dictionary.
Define two named relations of type Standard with Many Cardinality, each with no reciprocal relation defined, to support broad and narrow relationships. Include the exact short name you define for these named relations in your MedDRA SMQs load script; see "Defining Named Relations".
Include the DEF_NAMED_REL_ID of these named relations in your MedDRA SMQs load script.
For the broad and narrow named relationships you have defined, create a dictionary named relationship record from the filter dictionary to the base dictionary; see "Defining Dictionary NRLs".
Define Informative Note attributes of type Algorithm for SMQ algorithms; see "Defining Informative Notes for SMQ Algorithms.".
Create a load script and load MedDRA SMQs; see "Loading a Dictionary".
You can use the load script to load Algorithm-type Informative Notes and Broad and Narrow named relations or define them manually; see "Defining Informative Notes for SMQ Algorithms" and "Creating Named Relations Between Terms".
Use the TMS Lite Browser to search for filter dictionary terms and their related base dictionary terms; see "Searching for Terms Using Filter Dictionaries".
See "Defining a Dictionary" for detailed instructions on how to define a dictionary. Select Filter as the Dict Type and observe the following rules for filter dictionaries:
Language. Filter dictionaries and their base dictionaries must have the same language attribute setting.
VT Level Required. Uncheck. Filter dictionaries cannot have a VT level.
Folder Type. Filter dictionaries must be designated as Strong type.
Dictionary Link. A filter dictionary must have one and only one "Filter Dictionary Of" dictionary link to a base dictionary. This dictionary link defines the fact that the filter dictionary will contain only terms defined in the base dictionary.
A base dictionary can have one and only one "has Filter Dictionary" link to a filter dictionary.
Virtual Dictionaries. Filter dictionaries can have associated virtual dictionaries. These "versions" of filter dictionaries must have the same cut-off date as an existing virtual dictionary of the filter dictionary's base dictionary.
Domains. Filter dictionary domains are maintained by TMS. A filter dictionary inherits all the domains of its base dictionary. You can see a filter dictionary's domains in the Define Domain Dictionaries form, but you cannot change them.
Some MedDRA SMQs include algorithms that return refined search results. You can use these algorithms in TMS to search for source terms that report relevant symptoms or diagnoses; see "Searching for Terms Using Filter Dictionaries".
To use SMQ algorithms in TMS you must do the following:
Create one Informative Note attribute of type Algorithm; see "Defining Informative Note Attributes".
Create an Informative Note of type Algorithm for each SMQ filter dictionary term with an algorithm defined, either manually (see "Creating Informative Notes for Terms and Relations") or as part of the load script; see "About Load Scripts".
To support MedDRA SMQs, include the algorithm defined by MSSO for the SMQ filter dictionary term, but transform the format of the algorithm so that TMS can execute it. For example, in MedDRA 9.0, the SMQ algorithm defined by the MSSO for "Acute pancreatitis (SMQ)" is:
A or (B and C)
where A…F are categories of terms predefined by MSSO. You must load these categories with SMQ filter dictionary terms and store them in the Status column of the TMS table TMS_DICT_RELATIONS.
To translate this into a format that TMS understands, replace "or" with "UNION", replace "and" with "INTERSECT", and add the column name of the relations table that stores the SMQ category:
status = 'A' UNION (status='B' INTERSECT status='C')
Note:You can substitute your own algorithm if you prefer. However, each term can have only one Informative Note of type Algorithm.
Maintain filter dictionaries as you do base dictionaries:
Maintain Repository Data. Use the Maintain Repository Data window to maintain terms within a filter dictionary. In the lower block, the R. Status column contains the SMQ category of the target term, which is used in SMQ algorithms; see "Modifying Repository Data in the Maintain Repository Data Window".
Repository Authoring. Maintain named relations to base dictionary terms in the Repository Authoring window; "Repository Authoring".
From both windows you can click the Informative Notes button to navigate to the Maintain Informative Notes forms, where you can maintain the SMQ algorithm as well as other Informative Notes; see "Creating Informative Notes for Terms and Relations".
You can use the TMS Lite Browser to do the following kinds of searches based on a filter dictionary term:
Search for VTAs related to the filter dictionary term or its child, grandchild, etc. terms.
Search for source terms related to the filter dictionary term and its related VTAs. This functionality is also available using the API; see the Oracle Thesaurus Management System Technical Reference Manual.
Use the filter dictionary term's named relations, such as Broad or Narrow, to search for base dictionary terms.
Use the filter dictionary term's algorithm to search for source terms; see "Performing a Simple Source Data Filter Search".
See "Searching for Terms Using Filter Dictionaries" for information on all the above searches.
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."
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.
Users cannot classify an indication omission without an indication, and after a verbatim term is classified, there is no way to send an action message to the source system requesting information. So you must set up indication collection before classifying indication omissions.
Indication omissions are not highlighted in Oracle Clinical Data Entry as verbatim term omissions.
This section includes:
TMS provides flexibility in designing dictionaries, including those supplied by vendors. You can design the dictionary structure, ranking levels hierarchically and/or creating levels at the same rank. You can define the cardinality and optionality of level relations, and specify a Primary Link or Primary Path Link between levels.
Ranking levels in a vertical hierarchy so that terms become more general and fewer in each higher level of the hierarchy, effectively organizing lower-level terms into categories.
Adding levels horizontally, at the same rank, to provide supplementary information about terms, such as preferred names or indications.
Assigning levels to group levels to promote efficiency and enforce Primary Links to more than one level (see "Requiring a Primary Link to a Group Level").
Defining the classification level as a group level that includes both the conventional classification level and a synonym level with a many-to-one relation to the classification level. In this case, TMS searches in both sublevels for a match to a verbatim term. If it finds a match in the synonym level, it creates the VTA to link directly to the related conventional classification level term. Because of this behavior, using group levels as classification levels greatly increases the likelihood that a match will be found without increasing the number of terms in the conventional classification level.
Review each of the remaining sections in this chapter to consider your dictionary needs before defining a TMS dictionary or writing load scripts.
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.
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".
For each level relation you can require that a term in each level have a relation with a term in the other level, or define the relation as optional in either direction. For example:
Terms in Level A must have a relation to a term in Level B, but terms in Level B may or may not have a relation to a term in Level A.
Terms in Level B must have a relation to a term in Level A, and terms in Level A must have a relation to a term in Level B.
The cardinality of a level relation controls the ratio allowed between terms in two levels and must be defined in both directions:
Can a single term in Level A be linked to more than one term in Level B?
Can a single term in Level B be linked to more than one term in Level A?
You can define a level relation as many-to-many, one-to-many in either direction, or one-to-one.
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.
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:
This definition of WHO-Drug makes use of the Group Level feature as described in the following two sections.
By defining the classification level (the level in which TMS looks for a match to verbatim terms) as a group level, you can include more than one sublevel within the group for TMS to search. This increases the number of terms TMS can search without forcing the same terms to exist on multiple levels, which reduces the size of the dictionary. If you define a group level to be the classification level, you must specify that a term can exist in only one of the group's sublevels at a time. To enforce this structure, choose Level from the Term Uniqueness list when you define the group level.
In the WHO-Drug structure shown above, the classification level is defined as the group level called VTC, which contains as sublevels the Preferred Name level and the Synonym level. When TMS attempts to classify a verbatim term, it searches both sublevels, one after the other. Because TMS searches both levels to find a match, it is not necessary to include every preferred term in the Synonym level because TMS searches both levels to find a match.
Grouping the dictionary's higher levels and requiring a Primary Link to the group level enables you to define a Primary Link for a specific term to any one of the group's sublevels. TMS derives the Primary Link term and related terms in any higher levels within the group if the following conditions apply:
There is a many-to-one or one-to-one relation between each lower and higher level (Single cardinality is required at the higher end).
The group level and all its sublevels are defined as reportable.
The relations between the levels are defined as derivable.
Alternatively, you can define a primary path between the group level and a lower level. A primary path enables you to specify which terms to derive for each lower level term from each of the group sublevels (see "Primary Links and Primary Path Links").
Note:In addition, you must create structures in the external system to receive the derived values; in Oracle Clinical you need a question set variable and derived question for each sublevel that might contain the Primary Link term (see "Setting Up Data Collection in Oracle Clinical").
TMS enforces the following additional constraints for group levels.
A level can be linked to a group level or a sublevel within it, but not to both.
If two group levels are linked, none of the sublevels can be linked directly to sublevels in the other group.
A group level cannot be a child level because that might cause problems during derivation. However, a group level can be lower in the hierarchy than other levels if the top sublevel (not the group level itself) has the child relation with the parent level.
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.
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.
In the TMS dictionary structure, you must define one and only one derivation path. A derivation path is a series of consecutively related levels defined as derivable that begins at the classification level and includes all levels from which you want to derive terms. There must be one and only one path from the verbatim term level to each derivable level.
Deriving terms from TMS into an external system such as Oracle Clinical requires setup activity in both TMS and the external system.
To set up derivation:
Select Report Value? in the Define Dictionary Level window to be able to derive terms from the level you are defining. The Report Value? setting is optionally used by the external system to display the levels available for reporting.
Select the Derivable? box in the Define Level Relations window for each level in the path of derivable levels. There must be one and only one pathway to derivable terms in any level from the classification level. All levels you define as reportable must also be derivable, but derivable levels do not necessarily have to be reportable.
Create objects to receive the derived values and the mechanism to call for them. This process varies according to the external system and the level of integration. For information on deriving terms for Oracle Clinical, see Chapter 4, "Integrating TMS with Oracle Clinical." For information on levels of integration, see Chapter 1, "Getting Started."
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.
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.
To use a dictionary in TMS you must define it in the TMS user interface. This section includes:
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.
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:
From the Definition menu, select Define Dictionaries. The Define Dictionaries window opens, with the Base Dictionary tab selected.
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.
Define the dictionary itself (Name, Short Name, Description).
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.
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.
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.
From the Folder Type list, select Strong to create a strongly defined dictionary or Weak to create a dictionary folder.
Leave the Status set to Provisional until you are ready to activate and use the dictionary; see "Setting the Dictionary's Status to Active".
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
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.
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.
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.
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:
Click the Base Dictionary tab. (You cannot add levels to virtual dictionaries.)
Click the name of your selected dictionary in the navigator tree.
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.
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.
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.
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.
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.
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.
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.
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 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.
Save. TMS inserts the level into the tree structure, and populates the audit information fields.
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.
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.
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.
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.
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.
To define relations between levels of a strong dictionary:
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:
Highlight or select the parent level in the tree structure, click the Level Relations tab, select Record, and then Insert.
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.
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.
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.
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.
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 Appendix A, "Sample Dictionary Definitions" for sample dictionary diagrams and the corresponding definitions.
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.
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.
Define the child side of the relation. Select or leave clear each box as it relates to the child side of the relation.
Mandatory? Select if terms in the child level must have a link to a term in the parent level.
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".
Save. TMS populates the audit information fields.
This section describes what level details are and how to define them.
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:
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.
Corresponding to the dict_content_code column, this field is designed to serve as the primary key within this dictionary. This column is indexed.
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.
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.
This section describes how to define a dictionary's level details using the Define Dictionaries window.
To define a dictionary's level details:
Click the Level Details tab. The Level Details window opens.
In the Level Detail field, choose a value from the list. See the explanations of these fields for more information.
Specify the label of the field to appear on the Maintain Repository Data form.
Write a description of the purpose and/or content of the field.
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.
In the Description field, define the purpose or content of the field.
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.
select 'A', 'Approved' from dual
select 'P', 'Provisional' from dual
Note:Do not put a semicolon (;) at the end of the statement.
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.
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.
Modifying the dictionary short name
Changing the folder type (before any levels exist)
Changing enforcement of uniqueness of terms
Changing the VT Level Reqd? setting
Modifying the level hierarchy
For weak dict. folders only
Adding new level details
Modifying the dictionary name
Modifying the dictionary description
Modifying the dictionary Release Label prefix
Changing the level order
See "Overview of Informative Notes and Attributes" for general information about Informative Notes. You must define Informative Note Attributes and associate them with a dictionary before you can define dictionary-wide Informative Notes for the dictionary; see "Defining Informative Note Attributes" and "Making Informative Note Attributes Available for Dictionaries and Record Types".
This section describes adding dictionary-wide Informative Notes to the pre-dictionary tables, using the TMS API. This approach enables you to validate the notes you add by running Activation. You can also add dictionary-wide Informative Notes directly to the production tables by using the Define Dictionaries window (see "Defining Dictionary-wide Informative Notes"). The direct approach skips the Activation process.
Dictionary-wide Informative Notes serve one of two purposes in TMS, depending on the note type you choose:
Notes of type Standard and URL cascade down to that dictionary's data. By defining a dictionary-wide Informative Note, you also assign that note to every data record within the dictionary.
Dictionary version numbers enable you to specify which version of a dictionary you have loaded into the database. Dictionary versions are based upon the attribute Dictionary Version, which is derivable. See "Defining a Dictionary Version Informative Note".
You cannot use the Workflow note type for dictionary-wide Informative Notes.
You can create dictionary-wide Informative Notes for either base or virtual dictionaries, but the dictionary must be active.
To add a dictionary-wide Informative Note to the pre-dictionary tables:
Connect to SQL*Plus as the load user.
Run the API procedure tms_user_mt_info.insertInfo.
You must specify a pInfoNoteType of 'D' to create a dictionary-wide Informative Note.
Use the instructions in this section to load a dictionary for the first time or to upgrade a loaded dictionary to a new version. For more information on upgrading a dictionary, see Chapter 8, "Upgrading to a New Dictionary Version."
This section includes:
Important:Oracle is not responsible for the files you upload.
You are solely responsible for obtaining a valid license for any dictionary file(s) you upload. By uploading dictionary files you confirm that you understand all terms that apply to the use of the dictionary.
By uploading a version of WHODrug Enhanced, WHODrug Global, or other Uppsala Monitoring Centre products, you confirm that you hold a valid license granted by the Uppsala Monitoring Centre for the uploaded Uppsala Monitoring Centre product.
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."
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."
Note:This documentation is not intended to provide complete and specific instructions for the loading process, which may vary depending on the dictionary and on the individual needs of your location. Rather, these instructions are a guideline by which you can create load scripts that are compatible with your dictionaries. Oracle provides only sample load scripts that are not intended to dictate the usage or maintenance strategy for individual customers. These scripts are supported only to the extent that the API functions are specified.
Load scripts must do the following for each defined element that you are using:
Note:Using named relations and Informative Notes is optional.
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.
Your load script must:
Consist mainly of a series of select statements to transfer data from the temporary tables into the predict tables.
Set the DML column value in the predict tables to indicate the transaction to be performed as Insert, Update or Delete for each term and relation.
Make use of the constants in the tms_def_dict_cons package to avoid hardcoding constants.
Call the necessary packages for all appropriate transactions. The load script for loading a dictionary for the first time only needs to allow for insert transactions, but the load script for updating a dictionary must allow for Insert, Update, and Delete transactions. You can use the same script for loading and updating if it allows for all three transactions. The information on the transaction required for each term and relation is contained in the ASCII files supplied by the vendor.
All inserts, updates and deletes must be done using API calls rather than direct DML statements. Some of these packages are explained in "The API", and full API descriptions are available in the Oracle Thesaurus Management System Technical Reference Manual, which is available from Oracle Support.
The sample load scripts work on one Activation Group at a time, but you can write one that loads more than one Activation Group at a time. By default, when you run the load script, all of the terms in the temporary tables are inserted into the Activation Group you specify. See "Creating or Assigning an Activation Group".
Download instructions and sample scripts from My Oracle Support at
Sign in to My Oracle Support.
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.
Scroll down to the Attachments section and download the file for the dictionary you want to load.
The TMS Activation process runs against terms and relations in the predict tables that are associated with the Activation Group you choose. Activation includes two stages:
TMS validates terms and relations against dictionary definitions. During this process, TMS validates pre-dictionary Informative Notes as well.
TMS moves records that do not violate dictionary definitions to the production tables. The system leaves any records that do violate these rules in the pre-dictionary tables and populates the error message field for each record with the reason that the record failed activation.
You can run Activation in Check or Transfer mode. Check mode stops short of transferring data to the production tables while enabling you to see the results of the data validation. See "About Activation".
You can run Activation from the GUI or from SQL*Plus. You can monitor the process and, if you run in Check mode, you can view data that would fail activation in the Maintain Repository Data window and make the necessary changes before transferring the data to the production tables.
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:
From the Repository Maintenance menu, select Maintain Repository Data. The Maintain Repository Data window appears.
Highlight Activation Groups in the tree structure and select Insert Record.
Enter a name and description. (If you are setting up the practice drug dictionary CLS, name the Activation Group
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.
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.
Note:TMS populates the audit information fields.
To invoke Activation from the TMS Graphical User Interface:
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.
In the Job Specific section, click the Activation Group field. A list arrow appears.
Select an Activation Group from the list. (For information about Activation Groups, see "Creating or Assigning an Activation Group".)
Click the Activation Mode field. A list arrow appears.
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.
In the Schedule section, enter the name of the report server. Other schedule options appear.
Select Submit from the Job menu or click the Submit icon.
To run Activation in Transfer mode, type:
exec tms_user_activation.activateterms (
To run Activation in Check mode, type:
exec tms_user_activation.activateterms (
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.
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.
After activation refresh the context server index; see "Refreshing the Context Server Index".
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."
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.
Note:During Activation, TMS checks for cardinality violations. If you have defined relations to more than one term in a level with only a single cardinality relation defined, TMS rejects all relations.
In addition to user-defined dictionary level relations and optional validation rules, TMS enforces the following internal rules about external, company, and TMS domain terms:
A domain or company term cannot be linked to more than one external term, but an external term can be linked to more than one domain or company term.
A domain term cannot be linked to more than one company term, but a company term can be linked to more than one domain term.
TMS stores terms awaiting activation in the predict tables (tms_predict_contents and tms_predict_relations) and moves them to the production tables (tms_dict_contents and tms_dict_relations) when they are successfully activated. Terms that fail the Activation process remain in the predict tables associated with an error message.
You can view the error messages associated with failed data in the Error field of the Maintain Repository Data and Repository Authoring windows, or by running the Preliminary Repository Report.
TMS uses a series of Insert, Update and Delete transactions to move the data from the predict tables to the production tables. During the load process—when you are loading a dictionary for the first time—all transactions will be of type Insert.
The Activation process uses objects and relations defined in many parts of the system and documented as follows:
Activation Groups: See "Creating or Assigning an Activation Group."
From the Repository Maintenance menu, select Maintain Repository Data, then choose Activation Groups.
Dictionary Level Relations: See "Defining Relationships Between Dictionary Levels" and"Defining Relations Between Levels (Strong Dictionaries Only)."
From the Definition menu, select Define Dictionaries, then choose Level Relations.
Level Details (Optional): See "Defining Level Details."
From the Definition menu, select Define Dictionaries, then choose Level Details.
Validation Code (Optional): See "Add Validation Code (Optional)."
Terms and Relations: See Chapter 12, "Repository Maintenance."
From the Repository Maintenance menu, select Maintain Repository Data.
If you are upgrading to a new dictionary version, additional tools are available; see Chapter 8, "Upgrading to a New Dictionary Version."
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.
To run the Preliminary Repository Report, do the following:
From the Repository Maintenance menu, select Preliminary Repository Report.
Enter a Destination Type and any dependent fields (see "Running a Job").
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.
Set schedule parameters, to run the job at a future time (optional; see "Scheduling Parameters").
Click the Submit Job icon.
You cannot relate terms in separate TMS dictionaries until you establish linkage between the dictionaries. TMS allows you to define the following types of linkage between dictionaries:
A cross-dictionary link allows you to define a dictionary named relation between two dictionaries; see "Defining Dictionary NRLs". After you create the dictionary named relation, you can create relations between terms in the linked dictionaries.
A Translation Derivation Link connects two dictionaries of different languages, enabling you to derive translations between corresponding terms in the dictionaries based on the dictionary code. These links are only permissible between dictionaries with identical structure.
Define an Is Filter Dictionary Of link from a filter dictionary to its base dictionary. See "Defining Filter Dictionary Links".
Define a Has Filter Dictionary link from a base dictionary to its filter dictionary. See "Defining Filter Dictionary Links".
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.
Note:Links between dictionaries are bi-directional, so you can define relationships from terms in either dictionary to terms in the other dictionary once you create the link.
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.
You must choose two Active base dictionaries. Term mappings can span dictionary levels, although group and VT levels do not support term mappings.
To create a cross-dictionary link in the TMS user interface:
From the Define Dictionaries window, choose either dictionary in the relation by clicking its name in the structured part of the window.
Click the Dictionary Link tab. The Define Dictionaries window displays the Dictionary Link tab window.
Choose Record, then Insert.
From the Link Type field, choose Cross Dictionary Link.
From the To Dictionary list, choose the dictionary to which you want to link.
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.
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.
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.
To define a Translation Derivation Link:
From the Define Dictionaries window, choose either dictionary in the relation.
Click the Dictionary Link tab. The Define Dictionaries window displays the Dictionary Link tab window.
Choose Record, then Insert.
From the Link Type field, choose Translation Derivation Link.
From the To Dictionary list, choose the dictionary to which you want to link.
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.
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.
With the filter dictionary selected in the Define Dictionaries window, click the Dictionary Link tab. The Dictionary Link tab opens.
From the Link Type list, select Filter Dictionary of.
Click in the To Dictionary field. The Cross Dictionary Link Dictionaries list of values appears.
Select the base dictionary. For the MedDRA SMQ filter dictionary you must select MedDRA as the base dictionary.
With the base dictionary selected in the Define Dictionaries window, click the Dictionary Link tab. The Dictionary Link tab opens.
From the Link Type list, select has Filter Dictionary.
Click in the To Dictionary field. The Cross Dictionary Link Dictionaries list of values appears.
Select the filter dictionary.
This section includes:
A domain is a logical group of dictionary terms and VTAs. You must explicitly associate a dictionary with a domain in order to use it in that domain. In addition, you can define terms, relations, and verbatim term assignments (VTAs) for use only in a particular domain.
When you use TMS, you usually see a domain view of repository data; that is, you see only data associated with the current domain, including global and domain-specific terms and relations, for the dictionary or dictionaries you have linked to the domain.
TMS domains enable you to use the TMS repository differently in different situations as necessary. For example, you can use domains in the following ways:
You can tailor dictionary modifications and VTAs for a particular use by defining them as domain-specific. For example, you could create two domains for reference by two studies that needed to track one drug's effect on different body systems.
You can associate different dictionary combinations with different domains. For example, you might need to reference one adverse event dictionary in one country, and a different one in a different country. Your sites in the two countries can use different TMS domains.
If you choose, you can allow classifying terms to nonapproved dictionary terms in some domains but not others. For example, in a domain used for an active study you can prevent classification to nonapproved terms, but in a domain used for post-marketing surveillance, you can allow classification to nonapproved terms to prevent unnecessary reclassification after a dictionary upgrade.
To create a domain:
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.
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.
Save. TMS populates the audit fields.
Click the Dictionaries button to reach the Define Domain Dictionaries window. See "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.
Note:All dictionaries associated with a single domain must be either base dictionaries or virtual dictionaries with an identical cut-off date and time. Do not use a combination of base and virtual dictionaries or virtual dictionaries with different cut-off dates (including the complete timestamp, down to the second) with a single domain.
In addition, a domain can be associated with only one rendition—base or virtual—of any one base dictionary.
To assign a dictionary to an existing TMS domain:
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.
Click the Dictionaries button to reach the Define Domain Dictionaries window.
Click the ellipsis (…) or press F9 to launch the list of values for available dictionaries.
Select a dictionary and click OK.
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.
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.
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.
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.
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.
To add another dictionary, click in the next row and repeat the process.
Click OK. TMS saves the domain/dictionary links you have defined.
To unlink a dictionary (to prevent its use in this TMS domain), highlight it and select Record, then Delete.
Note:You cannot delete a domain/dictionary assignment if a filter dictionary is defined on the base dictionary and contains dictionary terms. Filter dictionaries inherit the domain assignments of their base dictionary. See "Filter Dictionaries" for more information.