7 Defining Other TMS Elements

Defining HTML Layout Functions

Before you can define an HTML Layout in the TMS application, you must define a function that you will use to derive data for that layout.

This section describes how to structure data in a package specification and package body so that the function can be used by an HTML Layout. For full samples, see the TMS Knowledge page on the My Oracle Support website.

CREATE OR REPLACE PACKAGE dmo_package IS

  FUNCTION LayoutOne(
             pRec      IN sys_refcursor
           )
  RETURN Tms_qry_result_TypeSet PIPELINED
  ;

  FUNCTION LayoutTwo(
             pRec      IN sys_refcursor
           )
  RETURN Tms_qry_result_TypeSet PIPELINED
  ;


END dmo_package;
/
sho err
grant execute on dmo_package to rxclin_read;
exec opa_ddl.CreateDropPublicSynonym( 'dmo_package');

Defining the Layout Name and Function

An HTML Layout uses one TMS dictionary and one layout function. This unique linkage is necessary because layout functions are written to be very dictionary-specific. In this section, you specify the dictionary that will use this layout, and the layout function that will deliver data to the HTML Layout.

To define a layout name and its function:

1. From the Definition menu, select Define HTML Layouts. The Define HTML Layouts window opens.

2. Choose Dictionary as the Ref Type. This is currently the only choice available.

3. From the Ref Name field, choose the dictionary to which you want to link this layout. You will only be able to use this layout in the TMS Lite Browser when this dictionary is selected.

4. Enter a Display Name for this layout. This name appears in the Layout list in the TMS Lite Browser when the linked dictionary is selected.

5. Enter the name of the function you want to use for this layout, in
   package_name.function_name format. To use LayoutOne from Example 7-1, enter dmo_package.LayoutOne.

6. Save.

Proceed to "Defining the Layout Columns" to complete the layout definition.

Defining the Layout Columns

Defining the columns for a layout means specifying which columns will display in the layout, in which order, and the headings that will display for those columns. You can choose the columns that are made available in the layout function: if you want a particular layout column to display the term name, and the layout function handles this data in the term_6 column, enter "6" as the Col ID for this column. See "Defining HTML Layout Functions" for information on writing an HTML Layout function.

You should define the columns in the order that you want them to display in the layout. The first column you enter in the Columns block will be the leftmost column in the layout.

The names that you enter for the columns are the names that display as headings when you use the layout in the TMS Lite Browser. You can change column display names at any time.

To define the columns for a layout, choose the layout you want to modify from the upper block of the window, then repeat the following steps for each column in the layout.

1. In the Columns block, click in an empty row or add a record.

2. In the Col ID field, enter the number that corresponds to the data column you want to use in the layout function. If you want this column to display the term name, and the layout function handles this data in the term_6 column, enter "6" for this column.

3. Enter the Display Name for this column. The TMS Lite Browser displays this name in the column heading when it displays results in this layout.

4. Repeat for each additional column, then save. TMS makes this layout available to the TMS Lite Browser.

Deleting a Layout

You can remove HTML Layouts from the database by first deleting all of the layout's columns, then deleting the layout itself.

Downloading a Report Template

To download a report template, follow the instructions below:

1. Log into TMS.

2. Click the TMS Lite Browser link from the TMS opening screen. The TMS Lite Browser opens.

3. Click the Reports tab.

4. Select the appropriate report from the Report field. The form refreshes and lists the selected report's templates in the table below.

5. From the list, click the appropriate template name. (The predefined default template is called the Oracle Template.) A standard File Download pop-up box opens.

6. Click Save. A standard Browse pop-up box opens.

7. Navigate to the location where you want to work on the template and click Save. The system saves a copy of the template as an .rtf file on your local system.

8. Save the file.

Modifying a Report Template

To create your first custom template for any report, begin by downloading the default Oracle template. You can create additional custom templates or modify existing custom templates at any time.

1. Open the downloaded template file locally in MS Word.

2. Make the changes you require. For information about using Oracle BI Publisher, go to the following website:

   http://docs.oracle.com/cd/E23943_01/bi.1111/e22254/toc.htm
   

3. Save your changes.

Uploading a Custom Report Template

To upload the template after customization, follow the steps below:

1. Log into TMS.

2. Click the TMS Lite Browser link from the TMS opening screen. The TMS Lite Browser opens.

3. Click the Reports tab.

4. Enter a name for the new customized template in the Template Name field.

5. Using the Browse… button, select the .rtf template file from your system.

6. Click the Create New Template button. The form refreshes and adds the customized template to the list of templates for this report.

Updating or Deleting a Custom Report Template

To update or delete an existing template, follow the steps below:

1. Log into TMS.

2. Click the TMS Lite Browser link from the TMS opening screen. The TMS Lite Browser opens.

3. Click the Reports tab.

4. Select the appropriate report from the Report field. The form refreshes and lists the selected report's templates in the table below.

5. Choose the appropriate template by clicking its corresponding button in the Select column. You may select only one template at a time.

6. Click Checkout Template. Your user ID appears in the Checkout column.

   Only one person can check out a template at a time. The template version that was current at the time of checkout remains available for use in TMS until the updated version is uploaded. The new version is then available.

   Note:

   If you decide not to update or delete the template, click Undo Checkout.

7. If you are updating the template, download the template and modify it locally; see "Downloading a Report Template" and "Modifying a Report Template".

8. Select the report you are updating or deleting, if it is not already selected.

9. If you are updating the report, enter a template name and browse for the modified local .rtf template file, then click Upload Template. The system updates the template and automatically checks it in.

   If you are deleting the template, click Delete Template.

   TMS does not allow you to overwrite or delete the default Oracle template.

Action Types

There are three types of actions: Answerable Actions and Unanswerable Actions (includes Negative List), both of which TMS sends to an external system, and Internal Actions, which are used within TMS.

After you apply an Action of any type to a term, TMS automatically applies the same Action to new occurrences of the same term in the same dictionary/domain combination.

Using Actions

Using actions involves many parts of TMS described elsewhere:

• Defining Actions is described in this section.

• Requiring Approval for Action Assignments. You can require that actions assigned to omissions be approved before they are sent to the external system. You require this approval for a particular dictionary/domain combination; see "Assigning a Dictionary to a Domain". Internal Actions are used for this purpose; see "Internal Actions" for further information.

• Applying Actions to Omissions. You assign actions to omissions in the Classify VT Omissions window; see "Apply an Action to a Term" for details.

• Applying Actions to VTs Before They Occur. You can apply actions to verbatim terms proactively, even before a verbatim term enters the system. In the Maintain Actions window, you can enter any verbatim term you choose (or any term that you think may be entered as a verbatim term in the future) and assign an Action to it. See "Maintaining Action Assignments".

• Viewing Action Assignment History. You can see actions that have been assigned to a term as follows:

  • You can see the actions that have been assigned to a verbatim term in the Distinct VT Actions tab of the Classify VT Omissions window; see Chapter 10, "Omission Management."

  • You can see the actions that have been assigned to a specific source term in the All VT Actions tab in Classify VT Omissions form; see Chapter 10, "Omission Management."

  • The Status/Notes window, called from Classify VT Omissions, Approve VTAs, Approve VTA Assignments, or VT History window, shows all term status history information, including actions; see "Using the Status/Notes Pop-up Window".

  • The TMS Lite Browser displays terms' complete Action history; see "Viewing a Term's Action History"

Defining an Action

To create an Action Definition, do the following:

1. From the Definition menu, select Create Action Definitions. The Create Action Definitions window opens.

2. In the Action field, enter a short (no more than 15 characters), descriptive name for the Action. In the bad headache and nausea example above, this might be "Split term."

   Note:

   If you are defining an Internal Action with a base Un/Answerable Action, use a naming convention such as base Answerable Action name _INT to name the Internal Action, so that coders can select the correct Internal Action to assign to an omission. For example, if the base Un/Answerable Action is named SPLIT TERM, name the corresponding Internal Action SPLIT TERM_INT. (Note that if you follow this naming convention, which requires 4 characters for the Internal Action name, base Un/Answerable Actions can have a maximum of 11 characters in their name.)

3. In the Action Type field, select Answerable, Unanswerable or Internal. See "Action Types" for information.

   When the choice is Internal for the purpose of requiring an Action assignment to be approved before sending to the external system, you must select an option from the Base Un/Answerable Action LOV. This LOV contains all defined Answerable and Unanswerable actions. Each Internal Action can be based on only one Action. Likewise, an Action can be associated with only one Internal Action.

4. Leave the Status field value set to Active. If you need to stop using the Action in the future, you can set the status to Retired. The system then removes all current assignments of the Action.

   Note:

   If an Action has never been applied to a term, you can delete it. After it has been applied, you can only retire it.

5. Base Action. Use this field only if you are defining an Internal Action with a base Answerable or Unanswerable action for use in one or more dictionary/domain combinations where Action approval is required. Specify the Answerable or Unanswerable action to be sent to the external system if the assignment of the Internal Action you are defining is approved.

   An Internal Action can have only one Base Un/Answerable Action (and should have a similar name to the Base Un/Answerable Action's name or text; see above). An Answerable or Unanswerable Action can be associated with only one Internal Action as a Base Un/Answerable Action.

   Note:

   In dictionary/domain combinations where Action approval is not required, you can apply an Un/Answerable Action directly to an omission, even if it is associated with an Internal Action.

6. In the Text field, enter the default text to send to external system users, explaining what they need to change to allow the system to process the term. In the same example, this text might be "Please split this term."

   If you are defining an Internal Action with a base Action, click in the Text field. TMS populates it with the base Un/Answerable Action's text. This text will be sent to the external system associated with a source term after the Action assignment is approved. The person who approves the assignment can modify the text.

7. In the External System field, specify one or more external systems collecting source terms (Oracle Clinical, for example) to which you may want to send this Action.

8. In the Omission Status field, enter the omission status you want the external system to assign to the omission when it returns from TMS. In Oracle Clinical, this status is normally Inv Review (Investigator Review) to indicate that the investigator must take the next step in resolving the discrepancy, but you can enter any valid status.

   An external system-specific LOV is available for this field; you can define this LOV in the Multiple Term Action Omission Statuses LOV field of the Define External Systems window.

   For each external system, select one omission status.

9. Save.

Defining VT Transformation

A verbatim term transformation allows an administrative user to create a transformation through a regular expression in order to manipulate the verbatim term.

A transformation can represent a substitution of a verbatim term text or a replacement of the text from a verbatim term. For example, stop words or temperature can be removed from the verbatim term. You can also replace abbreviations with the full spelling of a term.

Sample substitution and replacement transformations are included in the application. The sample transformations may not be removed or updated. You can create a copy of the sample transformation and customize. For more information, see "Sample Substitution and Replacement Transformations".

To define a VT transformation:

1. From the Definition menu, select Define Search Objects. The window opens with the VT Transformations tab selected.

2. Specify the following information about the VT transformation, then save:

Substitution Transformation

It consists of:

• Name is a required text field to uniquely label a substitution transformation.

• Type is a required drop-down list displaying: Word, Prefix, or Suffix.

  • Word is any alphanumeric text string.

  • Prefix is partial text string representing beginning characters of a verbatim term. For example, Anti-, Pre-, or Post-.

  • Suffix is partial text string representing later characters of a verbatim term. For example, -et, -aire, or -es.

• Level is a required drop-down list displaying: Substitution Terminology - Stopwords, Substitution Terminology - Abbreviations, Substitution Terminology - Prefix, Substitution Terminology - Suffix, and all other levels associated with active dictionaries of type Substitution. This field contains the Substitution Dictionary Name and Levels.

  • Substitution Terminology - Stop words represent words that are removed from the verbatim term. For example, as, an, the, and, OR at.

  • Substitution Terminology - Abbreviations represent words that are shorten to represent a whole word. For example, Fx is fracture or Dr is doctor.

  • Substitution Terminology - Prefix is an affix placed before a word, base, or another prefix to modify a term's meaning, as by making the term negative. For example, un- or Ms.

  • Substitution Terminology - Suffix is an affix that follows the element to which it is added. For example, -ly.

• Description is a text field to describe the term substitution transformation.

• Test is a button that triggers the test (for testing purposes only)

• Test Verbatim Term is a field to allow entry of a verbatim term (for testing purposes only).

  Note:

  In the PL/SQL regexp_replace function, this is the value used in the string parameter.

• Test Result is a read-only field displaying the result of the test (for testing purposes only).

• Created By is a read-only field displaying user that created the record.

• Creation Timestamp is a read-only field displaying timestamp when record was created.

• Modified By is a read-only field displaying user that last modified the record.

• Modification Timestamp is a read-only field displaying timestamp when record was last modified.

For each Substitution transformation record, you can test the substitution transformation by entering a text string in the Test Verbatim Term field and clicking the Test button. The Test field will display the resulting transformation.

Replacement Transformation

It consists of:

• Name is a required text field to uniquely label a replacement transformation. Must be unique across all substitution and replacement transformation objects.

• Pattern is a required field. PL/SQL regular expression to be applied to a verbatim term. When saved, a test is performed and an error will be thrown if the regular expression is not valid.

  Note:

  In the PL/SQL regexp_replace function, this is the value used in the pattern parameter.

  • With replacement transformations, PLSQL regular expressions are applied to the verbatim term and text in the verbatim term is replaced when matches are made by the regular expression.

  • The format of the REGEXP_REPLACE function is: REGEXP_REPLACE( string, pattern [, replacement_string [, start_position [, nth_appearance [, match_parameter ] ] ] ] )

• Repl. Str. is an optional replacement text field. When the regular expression finds a match in the verbatim term, the matching text is replaced with this value. If left empty, then the matching text is simply removed from the verbatim term. This can be static text or a pattern.

  Note:

  In the PL/SQL regexp_replace function, this is the value used in the replacement_string parameter.

• Space - Select this checkbox when a single space " " needs to be configured in the "Repl. Str" field. Entering any character other than space in "Repl. Str" will automatically uncheck this box. (This must be to workaround a forms issue attempting to save a value with only a single space)

• Start - Optional start position. This value specifies the position in the string where the regular expression will start searching from. If empty, then 1 is used by default.

  Note:

  In the PL/SQL regexp_replace function, this is the value used in the start_position parameter.

• Occ - Optional occurrence. This value specifies which occurrence of the pattern within the string to replace. If empty, then all occurrences of the pattern within the string will be replaced. If set to 0, then all occurrences of the pattern within the string will be replaced.

  Note:

  In the PL/SQL regexp_replace function, this is the value used in the nth_appearance parameter.

• Description is a text field to describe the term replacement transformation.

• Test is a button that triggers the test (for testing purposes only).

• Test Verbatim Term is a field to allow entry of a verbatim term (for testing purposes only) (NOTE: In the PL/SQL regexp_replace function, this is the value used in the string parameter).

• Test Result is a read-only field displaying the result of the test (for testing purposes only).

• Created By is a read-only field displaying user that created the record.

• Creation Timestamp is a read-only field displaying timestamp when record was created.

• Modified By is a read-only field displaying user that last modified the record.

• Modification Timestamp is a read-only field displaying timestamp when record was last modified.

For each Replacement Transformation record, you can test the replacement transformation by entering text into the Test Verbatim Term field and clicking Test. The Test Result field will display the resulting transformation.

Defining Packages

The packages tab allows you to continue to use the custom PL/SQL packages assigned to a search object. You can continue to use custom packages during autocoding or to determine candidate matches.

To define a package:

1. From the Definition menu, select Define Search Objects.

2. Click the Packages tab.

3. Specify the following information about your package, then save:

   • Name: Enter a name identifier for the package object. Name is the search object label as defined in TMS pre-5.3. It is a required text field and unique across all package objects.

     Note:

     No validation is performed when the package is saved to verify that the entry is valid.

   • Autocode Object: Enter the name of the function you have written for TMS to run during Autoclassification. For the Domain Match search object, this is predefined. For user-defined search objects, enter the function name here or, if the function is included in a package, enter package_name.function_name. See "Creating Custom Search Algorithms".

   • Candidate Object: Enter the name of the function you have written for TMS to run to generate Candidate Terms during manual classification. For the Domain Match search object this is predefined. For user-defined search objects, enter the function name here or, if the function is included in a package, enter package_name.function_name. See "Creating Custom Search Algorithms".

   • Description: It is a text field used to describe the search object.

   • NonApproved VTA Package: TMS includes a pre-defined packaged called NonApproved VTA. It searches in the current domain for an exact match that is a Nonapproved VTA. The Nonapproved VTA package cannot be modified in the Packages tab. However, in order to include the Nonapproved VTA package, you will need to add the package to the search object, see Defining a Search Object.

     Note:

     The NonApproved VTA search object will no longer be executed during autocoding by default. You will need to add the NonApproved VTA search object to each domain/dictionary and identify the order to execute the NonApproved VTA search object during autocoding. See "Defining a Search Object", "Assigning Search Object to a Dictionary", and "Defining the Search Object Order" to complete the setup.

   • Domain VTA Package: TMS includes a pre-defined search object called Domain VTA that is available for you to use as you wish. It searches for an exact match of a VTA in another domain. If it finds more than one match, it returns multiple Candidate Terms. If it finds one and only one match, it either autoclassifies the term or returns a Candidate Term, depending on the Approval Type setting. In addition, if it finds one and only one match:

     • If the verbatim term's dictionary/domain combination allows classification to nonapproved dictionary terms, the Domain Match search object includes VTAs linked to nonapproved dictionary terms in its search.

     • If the verbatim term's dictionary/domain combination does not allow classification to nonapproved dictionary terms, the Domain Match search object does not include VTAs linked to nonapproved dictionary terms in its search, even if they exist in other domains.

     In order to include the Domain VTA package, you will need to add the package to the search object, see "Defining a Search Object".

Defining a Search Object

In the Search Object tab, you will define the search object by assigning a name, the VT Transformation, how to match the term using the Term Matching, what terms to include, and a description of the search object. The Domain Match and Non appr vta match search objects are included as part of the TMS installation and cannot be updated. You can test each search object against a base dictionary to verify the results as expected.

To define a search object:

1. From the Definition menu, select Define Search Objects.

2. Click the Search Objects tab.

3. Specify the following information about your search object, then save:

   • Name is a mandatory text field to label the search object and must be unique.

   • VT Transformation is a mandatory drop-down list of VT transformations defined from the VT Transformation tab. The list also displays an option for "None" in case a transformation is not to be performed on the term.

   • Term Matching is a mandatory drop-down list with the following options:

     • All words: To match all words independent of order.

     • Any: To search for at least one occurrence of any of the transformed verbatim term.

     • Exact: Matching the transformed verbatim term with a precise match.

     • Fuzzy: Matching the transformed verbatim term using the fuzzy operator,?, to include words that are spelled similarly to the specified term. This type of expansion is helpful for finding more accurate results when there are frequent misspellings in your document set. For example, . ?aspirin finds aspirin, ascriptin, and aspellin.

     • Left: Matching the transformed verbatim term with term in dictionary that starts the same.

     • None: Perform no match.

       Note:

       This will generate an omission since no match is performed.

     • Soundex: Matching the transformed verbatim term using the soundex operator, !, to include words that have similar sounds; that is, words that sound like other words. This function enables comparison of words that are spelled differently, but sound alike in English. For example, !hair finds hair and air.

     • Stem: Matching the transformed verbatim term using the stem,$, operator to search for terms that have the same linguistic root as the query term. For example, $crush finds crush, crushed, and crushing.

     • Text: Uses the Oracle Text Index to perform match.

     • P: DomainVTA: Uses the Domain VTA package to match the transformed verbatim term to VTAs across domains.

     • P: NonApprovedVTA: Uses the NonApproved VTA package to match the transformed verbatim to a non-approved VTA.

     • In addition, any other custom packages defined on the Packages tab will be displayed prefixed with "P:".

       Note:

       The following Term Matching use Oracle Context Search: All Words, Any, Fuzzy, Soundex, Stem, and Text. If a verbatim contains a reserved word or character from the Oracle Text Queries, TMS will escape the reserved word or character. See Special Characters in Oracle Text Queries, https://docs.oracle.com/en/database/oracle/oracle-database/12.2/ccref/special-characters-in-oracle-text-queries.html#GUID-4639581C-7F65-4C9E-96CE-0A7EAA10086F.

   • Include is a mandatory drop-down list of Dictionary Terms or All Terms.

     • Dictionary Terms: Matching the transformed verbatim term against dictionary terms only.

     • All Terms: Matching the transformed verbatim term against dictionary terms or VTAs.

   • Description is a text field to provide detail about the search object.

Assigning Search Object to a Dictionary

After setting up the Search Object, assign the search object to a dictionary and domain. You must specify the dictionaries with which each Search Object is available for use, as follows:

1. From the Definition menu, select Define Search Objects.

2. Click the Apply to Dictionary tab.

3. Select a dictionary from the Dictionary drop-down list. This drop-down displays all active (base and virtual) dictionaries with a folder type set to Strong and the VT Level Required? checkbox selected.

   The Dictionary Type field displays the type of selected dictionary whether the selected dictionary is a Base or Virtual Dictionary.

4. Assign a defined search object to the dictionary in the first table (top block). This table displays the following fields:

   • Search Object is a drop-down list. This is the available search objects defined in the Search Objects tab.

   • All Versions? checkbox indicates the search object is used in all versions of a dictionary which includes all virtual dictionaries of a base dictionary. Only a search object in the base dictionary can be assigned the "All Versions?". If a search object is assigned with "All Versions?", then the virtual dictionary will use the search object and the search object cannot be removed. However, if the search object "All Versions?" is not selected in the base dictionary, then the virtual dictionary will inherit the search object from the base dictionary but the search object can be removed from the search object order.

   • Comment is a field to provide any notes about the assigned search object.

   • For each record in this table, there are read-only fields: Created By, Creation Timestamp, Modified By, and Modification Timestamp.

5. The second table (bottom block) displays the assignment of a domain to a search object(s).

   • Domain field displays the domains that are assigned to the selected dictionary.

   • Disabled? checkbox indicates the search objects are disabled for the assigned domain.

   • Comment Text is a field to provide any notes about the assigned domain.

Defining the Search Object Order

In the Search Object Order tab, you can define the order in which search objects are executed during autocoding for a given domain/dictionary. The search objects assigned in the Apply to Dictionary are available once you have selected the Dictionary/Domain.

To define the order in which search objects are executed:

1. From the Definition menu, select Define Search Objects.

2. Click the Search Object Order tab.

3. Select a dictionary from the Dictionary drop-down list. This drop-down displays all active (base and virtual) dictionaries with a folder type set to Strong and the VT Level Required? checkbox selected.

   Once you select the dictionary, the Domain drop-down list displays only the domains assigned to the selected dictionary.

4. Define the search object execution in the first table (top block) which is a multi-record table. This table displays the following fields:

   • Order is a numeric, unique, and mandatory field.

   • Search Object is a drop-down list of the available search objects for the selected dictionary/domain as defined in the Apply to Dictionary tab and it is mandatory.

   • Action 1:1 Match is a drop-down list indicating if a match is found to Create VTA or Omission.

   • Stop 1:1 Match? checkbox indicates the exit criteria if a match is found and you want the system to stop the search if it finds more than one match using the search object.

     Note:

     If the system finds more than one match during a Candidate Term search, it will return all the matches it finds.

   • Reset VT? checkbox indicates if the original verbatim is restored when autocoding for the current selected search object. If the checkbox is not selected, then the transformed verbatim term is used from the previous search object defined in the order.

     Note:

     The first search object in the order always uses the original verbatim term and not dependent on the Reset VT.

     Example of the Reset VT? use case:

     • Order 1: Search Object 1 Reset VT checked >> Original VT always used

     • Order 2: Search Object 2 Reset VT not checked >> Transformed VT from Order 1 search object used

     • Order 3: Search Object 3 Reset VT checked >> Original VT used

     • Order 4: Search Object 4 Reset VT not checked >>> Transformed VT from Order 3 search object used

   • Disabled? checkbox indicates if the search object is not to be executed. The search object is disabled in the Apply to Dictionary tab for a given domain/dictionary combination.

   • Comment is a field to provide any notes for the assigned search object.

Once you have defined the search object execution order, you can test the execution order.

Testing the Search Object Order

Test the search object order in the second table (bottom block). This table displays the following fields:

• Verbatim Term is an enterable free-form text field.

• Result is a display only drop-down list (Omission, Classified, Error, Setup Error):

  • Omission result is if no match, multiple matches can be found from the search object order, OR if a direct match is found on the search object order when the Action 1:1 Match is set to Omission.

  • Classified result is if an exact match is found from the search object order.

  • Error result is if an unexpected exception is thrown in database. Data corruption of the dictionary.

  • Setup Error is if an error encountered in database setting global variables (for example, instance needs to be registered, synchronization needs to be run on instance, and so on). For example, if dictionary is not assigned to a domain or dictionary not a base/virtual dictionary.

• Test Search button.

• The Candidates table displays the matched term(s) in the dictionary. The results must be the same as the Classify VTO candidate search where only distinct matches are returned.

  • Term is the dictionary term or VTA in the domain/dictionary.

  • (Term) Type is either a dictionary term or verbatim term.

  • Code is the dictionary code field.

  • Alt Code is the alternate code defined for the dictionary term.

  • Approved? checkbox indicates if the dictionary term/VTA is approved.

  • Comment is a field displaying any text entered about the dictionary term/VTA.

Removing a Search Object's Association with a Dictionary

If you decide that you no longer want to use a particular search object with a dictionary in any domain, you can remove the search object from the Search Object Order, Apply to Dictionary, and Search Objects tabs.

Omissions previously created using the search object still exist and are queryable and viewable in the Classify VT Omissions window. However, the Search Object field for these omissions is blank, and the system does not use the search object to create any additional omissions associated with the dictionary.

To remove a search object execution order in a dictionary:

1. From the Definition menu, select Define Search Objects.

2. Click the Search Object Order tab.

3. From the Dictionary list, choose the dictionary from which you want to remove a search object.

4. Select the domain from the Domain drop-down list. TMS lists the search objects defined for this dictionary and domain.

5. Scroll to, or query for, the search object you want to remove, and select its row.

6. With the search object's row highlighted, delete the record.

7. Save. TMS deletes the search object's association with this dictionary.

Deleting a Search Object

If you decide that you no longer want to use a search object with any dictionary, you can delete it entirely from TMS. Previously created omissions still exist, and are queryable and viewable in the Classify VT Omissions window. However, the Search Object field for these omissions is blank, and the system does not use the search object to create any additional omissions.

To delete a search object assigned to a dictionary:

1. From the Definition menu, select Define Search Objects.

2. Click the Apply to Dictionary tab.

3. From the Dictionary drop-down list, choose the dictionary from which you want to remove a search object. TMS lists the search objects defined for this dictionary.

4. Select the Search Object record and delete the record.

To delete a search object:

1. From the Definition menu, select Define Search Objects.

2. Click the Search Objects tab.

3. Query for the search object you want to delete.

4. Select the Search Object record and delete the record.

Creating Custom Search Algorithms

Each of the search algorithms provided with TMS searches only for direct matches to the verbatim term in the TMS repository. You may want to take advantage of the text-retrieval capabilities available in the Oracle database. The interMedia Text software, formerly known as the Context Server Cartridge, is integrated in the RDBMS. See "Entering a Context Query".

To create a custom search algorithm, create a PL/SQL function in the database and enter its name in the Search Object Definition window in TMS in the appropriate field—Autocode Object or Candidate Object—and set the candidate_type='package'. For an overview, see "Defining a Search Object").

If the function is part of a package, follow the naming convention
package_name.function_name for functions. When TMS runs Autoclassification, a Candidate Term search, it calls the function in the order you specify in the Exec Order field.

You will probably want to make each search algorithm available in both situations, but this is optional.

The input and output parameters vary in each situation as follows:

FUNCTION function_name (
  pDefDictionaryId IN tms_def_dictionaries.def_dictionary_id%TYPE
  , pDefDomainId IN tms_def_domains.def_domain_id%TYPE
  , pVtLevelId IN tms_def_levels.def_level_id%TYPE
  , pVtCodeLevelId IN tms_def_levels.def_level_id%TYPE
  , pVTASearchFlag IN VARCHAR2
  , pTermUpper IN tms_dict_contents.term_upper%TYPE
  , pVDefDictionaryID IN tms_def_dictionaries.def_dictionary_id%TYPE
  , pCutoffDate IN tms_def_dictionaries.cutoff_date%TYPE
  , pDictContentid IN OUT tms_dict_contents.dict_content_id%TYPE
) RETURN PLS_INTEGER;

FUNCTION function_name (
  pDefSearchId IN tms_vt_omissions.def_search_id%TYPE
  , pDefDictionaryId IN tms_vt_omissions.def_dictionary_id%TYPE
  , DefDomainId IN tms_vt_omissions.def_domain_id%TYPE
  , pVtLevelId IN tms_def_levels.def_level_id%TYPE
  , pVtCodeLevelId IN tms_def_levels.def_level_id%TYPE
  , pTermUpper IN tms_dict_contents.term_upper%TYPE
  , pVDefDictionaryID IN tms_def_dictionaries.def_dictionary_id%TYPE
  , pCutoffDate IN tms_def_dictionaries.cutoff_date%TYPE
  , pCutoffDate IN tms_def_dictionaries.cutoff_date%TYPE) RETURN VARCHAR2;

AND end_ts = to_date(3000000, 'J')

About Named Relations

Standard-type named relations create a structure for weak dictionary folders by describing the nature of relations between terms. You can define named relations as being one-directional or bi-directional, as shown in Figure 7-1.

Figure 7-1 One-directional and Bi-directional Relationships

Description of ''Figure 7-1 One-directional and Bi-directional Relationships''

Bi-directional relationships like the one above between "United States" and "California" have two components, an Indicator relationship and a Reciprocal Indicator relationship. Indicator relationships describe the link from the source term to the reference term, and Reciprocal Indicators describe the reverse relation. If "United States" is the source term for the above relation, "Broader Term Than" is the Indicator for this relationship and "Narrower Term Than" is the Reciprocal Indicator.

One-directional named relations have Indicator relationships only. Thus, in the example one-directional relation above, no relationship is defined from "state" to "California."

Named relations also define the cardinality of the relation between terms. The cardinality of a relationship determines the maximum number of reference terms (one or many) to which a term may be linked. If you specify Many Cardinality for the Indicator relationship but Single Cardinality for the Reciprocal Indicator, then source terms can be linked to many reference terms, and each reference term must link to only one source term.

Because named relations create a dynamic dictionary structure, you cannot enforce that named relations be mandatory. You can, however, enforce mandatory relations between levels in a strong dictionary; see "Mandatory Relations".

TMS does not allow circular named relations of the same type among terms. That is, if you define an Indicator relationship of a particular type (such as Related Term) between Term A and Term B, and another Indicator relationship of the same type between Term B and Term C, you cannot define an Indicator relationship of the same type between Term C and Term A. Activation of the final relationship in the circle fails. (The reason for this restriction is that the ANSI/NISO Z39.19-1993 standards for thesauri specify that you must be able to represent a thesaurus structure using a flat display, which is impossible with circular relations.)

You can introduce a named relationship into your installation using the Define Named Relationships window, or by loading the relationship directly into the repository with a load script (see "About Load Scripts"). TMS stores named relations in the tms_def_named_rels table, and enables you to use any named relation to link terms in any dictionaries throughout the TMS installation.

See "Defining Named Relations" and "Creating Named Relations Between Terms" for more information, including information on other types of named relations.

Types of Named Relations

You can use named relations to create browsable relations between dictionary terms.

There are three types of named relations:

• Standard. Use standard named relations to create relations among terms in weak dictionary folders or to supplement existing relations among terms in strong dictionaries.

  After you define a standard named relation, you can create standard named relations between terms in the Repository Authoring window under the Repository Maintenance menu.

• Translation. Use named relations of type Translation to define a relationship between a term in one dictionary and a term with the same meaning in another dictionary in a different language. TMS allows named relations of type Translation only between terms in different dictionaries, each of which must have a different language defined.

  After you define a Translation named relation, you can create Translation named relations between terms in the Repository Authoring window under the Repository Maintenance menu.

• Release Label. Use named relations of type Release Label to create relations between terms in the same or different dictionaries at different points in time.

  This is especially useful for maintaining an audit trail of complex changes to a term from one dictionary version to another; for example, where two terms are merged, or one term is split into two or more terms, or one term is substituted for another.

  After you define a Release Label named relation, you can create Release Label named relations between terms in the Release Label Authoring window under the Repository Maintenance menu; see "Using the Release Label Authoring Window".

Release Label Named Relation Example 1 The MedDRA 7 high level terms "Liver and spleen infections" and "Gallbladder infections" were merged in MedDRA 8 into a single term, "Hepatobiliary and spleen infections."

If you are currently using MedDRA 7 in TMS, do the following:

1. After upgrading to TMS 4.6, define a label prefix for MedDRA 7: 7.0.

2. Create a virtual dictionary of MedDRA 7. TMS creates a Release Label for the virtual dictionary.

3. Define a named relation called "is merged into;" see "Defining Named Relations".

4. Update the label prefix to 8.0.

5. Load data for MedDRA 8 into the predictionary tables.

6. Define two named relations in the Release Label Authoring window, one from "Liver and spleen infections" to "Hepatobiliary and spleen infections" and one from "Gallbladder infections" to "Hepatobiliary and spleen infections." In both cases, given the definition "is merged into," "Hepatobiliary and spleen infections" must appear in the Reference section of the screen. See "Creating Named Relations Between Terms". Use the NEXT setting for "Hepatobiliary and spleen infections," which is in the predictionary tables and does not yet have a Release Label.

7. Activate the data (MedDRA 8).

8. View the data in the TMS Lite Browser; see "Examining a Term's Details and History".

Release Label Named Relation Example 2 If you have already loaded and activated MedDRA 8, do the following to trace the relationship between MedDRA 7 high level terms "Liver and spleen infections" and "Gallbladder infections" the single MedDRA 8 high level term, "Hepatobiliary and spleen infections":

1. Create label prefixes for MedDRA 7 and MedDRA 8.

2. Create virtual dictionaries for MedDRA 7 and MedDRA 8. TMS creates a Release Label for each.

3. Define the "is merged into" named relation as above.

4. Define named relations between the two terms in MedDRA 7 and the term they are merged into in MedDRA 8.

5. View the data in the TMS Lite Browser; see "Examining a Term's Details and History".

Defining Named Relations

To create a new named relation:

1. From the Definition menu, select Define Named Relations. The Define Named Relations window opens, with the Named Relation tab displayed.

   Note:

   By clicking the Multi Display Named Relations tab, you can view all of the named relations defined in this TMS installation. Examine the existing named relations before creating a new named relation to avoid creating similar but extraneous relationships.

2. Define the Indicator relationship:

   1. In the Name field, enter the relationship name that will appear for relations from a term to its referenced term.

   2. Select the Many Cardinality box to allow multiple source terms to relate to one (or more) reference terms using the Indicator relationship.

3. Define the Reciprocal Indicator:

   1. In the Name field, enter the relationship name that will appear for relations from the reference term back to the source term. If the relationship does not have a reciprocal, leave the Name field blank.

   2. Select the Many Cardinality box to allow multiple reference terms to relate to one (or more) source terms using the Reciprocal Indicator relationship.

4. Define the relationship details. All the fields in the Details block are optional except for the Type field.

   1. In the Relationship Code field, you can enter an optional code about this named relation. For example, when loading named relations into TMS via the API, you could populate the Relationship Code with the vendor-supplied dictionary from which you loaded the relationship, or the relationship's ID in that dictionary.

   2. Select a Type.

      Standard. Use for normal named relations between terms. TMS does not enforce any special behavior.

      Translation. TMS validates that the two terms in the relation are from dictionaries that have different languages specified. Because translation relationships must be between dictionaries of different languages, you can only instantiate such relations as cross-dictionary relations. See "Creating Cross-Dictionary Relations Between Terms" for instructions on using these relationships in the Repository Authoring window.

      Release Label. Release Label named relations create links between terms in the same or different dictionaries at different points in time; see "Types of Named Relations".

   3. In the Short Name field, enter a unique value for the short name of this relationship. TMS allows names containing up to ten bytes of alphanumeric text. If you leave this field blank and save the record, TMS supplies a default, unique value.

   4. In the Activation Rule field, you can specify a function that you want to use as the Activation Rule for this relationship. "Writing Named Relation Activation Rules".

   5. In the Category field, you can enter a category to define further this named relation.

   6. In the Description field, you can provide more information about this named relation. Information entered here could help other TMS users.

5. Save. TMS records the named relation in the repository, and updates the audit fields in the bottom of the window.

You can modify many attributes of named relations in the same manner. Because TMS only uses the internal ID of the relationship to identify which named relation is associated with a particular relation, you can change any information about an existing named relation except its ID, cardinality, and type.

Defining Dictionary NRLs

For each named relation you define, you must specify the dictionaries and dictionary combinations where it should be available for creating named relations between terms.

To specify the dictionaries where a named relation is available for use, do the following:

1. In the Define Named Relations window, with the named relation for which you want to specify dictionaries selected, click Dictionary NRLs. The Define Dictionary Named Relationships window opens.

2. Click in the first empty row. The fields become enterable.

3. In the From Dictionary column, from the list, select a dictionary in which you want the named relation to be available.

4. In the To Dictionary column, from the list, select a dictionary:

   • To make the named relation available to define relations between terms in a single dictionary, choose the same dictionary you specified in the From Dictionary column.

   • To make the named relation available to define relations between terms in the dictionary you specified in the From Dictionary column and a second dictionary, choose the name of the second dictionary.

     Note:

     In the To Dictionary list of values, TMS displays:

     • The From Dictionary; you can always define relations between terms in the same dictionary.

     • Dictionaries that have a filter dictionary link with the From Dictionary; one is a filter of the other.

     • Dictionaries with a cross-dictionary link defined to the From Dictionary. To define a dictionary link, go to the Define Dictionaries window, select a dictionary, and click the Dictionary Link tab. See "Defining Links Between Dictionaries".

5. Leave Status set to Active.

   You can set the status to Retired in the future to prevent this named relation definition's being used to create additional relations in this dictionary or dictionary combination. This is the only modification possible.

   You can set the status back to Active only if the To and From Dictionaries have one of the relationships described in the above Note.

6. Save.

Writing Named Relation Activation Rules

Named relation Activation Rules can perform further validation of the terms and their relationship(s) before Activation. For example, if you create a named relation "Abbreviation for," you could write a function to verify that the reference term you plan to use as the abbreviation is, in fact, shorter in length than the original term.

Named relation Activation Rules must be part of database packages, and the proper format for definition is package_name.function_name.

The function must use the parameters described in the following table.

Overview of Informative Notes and Attributes

Informative notes are data structures that you can create to provide more information about a term, relation, VTA, VTI, or dictionary in the database. The advantage that Informative Notes offer over the other detail items—the code, alternate code, category, and the value_1 through value_4 columns—is their flexibility. Using Informative Notes, you can attach a URL, text in a Character Large Object (CLOB), or a note of predefined length containing character, number, mixed, or date data.

Each time you create an Informative Note, you must base it upon an Informative Note Attribute, which gives the note its type, data type, maximum length, and other properties. Using attributes as the basis for Informative Notes saves time during note definition and provides more consistency among the Informative Notes defined in your database.

You can define dictionary-wide Informative Notes that are inherited by all terms in a dictionary. Users can create an Informative Note for a specific term, relation, VTA/VTI, action assignment, or an SMQ algorithm in a filter dictionary such as MedDRA SMQs. See:

• "Defining Dictionary-wide Informative Notes"

• "Creating Informative Notes for Terms and Relations"

• "Using the Status/Notes Pop-up Window" for creating Informative Notes for VTAs, VTIs, and Action Assignments

• "Defining Informative Notes for SMQ Algorithms".

Defining an Informative Note Attribute

This section includes:

• Defining Informative Note Attribute Properties

• Defining the Details for the Informative Note Attribute

• Making Informative Note Attributes Available for Dictionaries and Record Types

Defining Informative Note Attribute Properties

Launch the Define Informative Note Attributes window by navigating to Definition, then Define Informative Note Attributes. The Define Informative Note Attributes window opens, with the Informative Note Attributes tab selected. This tab shows detailed information about one Informative Note Attribute, and is the window for defining new attributes. Click the Multi Display Informative Note Attributes tab to view several attribute records at once.

The Properties block contains the essential information about the attribute: its name, type, and other settings that control its use in TMS.

Description of the illustration ''tmsdfatt_properties_block.gif''

To define the attribute's properties, from either tab of the Define Informative Note Attributes window:

1. In the Label field, enter text to describe the sort of information you store in Informative Notes based on this attribute. Users defining an informative note for a particular object use the label to choose an informative note attribute on which to base the note.The label text appears as a header wherever the Informative Note appears in TMS.

2. From the Type list, select:

   • Standard. For Informative Notes that contain text, a number, or date, to provide supplementary information about a term, relation, VTA, VTI, or dictionary.

   • URL. For Informative Notes that are character strings representing URLs.

   • Workflow. For Informative Notes used in workflow processes, such as approval of VTAs. If you are creating an Informative Note during classification, VTA approval, or reclassification, TMS requires that you base the note on an attribute of type Workflow.

   • Algorithm. For use with filter dictionaries such as MedDRA SMQs. See "Defining Informative Notes for SMQ Algorithms" for more information.

3. The Derivable list choice determines whether external systems will be able to derive Informative Notes that you define based on this attribute. Choose Yes to enable external systems to derive this Informative Note data, or No to prevent this derivation.

4. Select the Updateable? box if you want users to be able to update Informative Notes based on this attribute.

5. Select the LOV Validation box if you want TMS to limit the values for a particular Informative Note to those defined in the SQL statement you enter in the LOV Statement field in the Details panel below. This setting is not applicable if no LOV is generated from the LOV statement, and is not relevant for Informative Note Attributes of data type Memo or of attribute type URL.

6. From the Data Type list, choose one of the four available Informative Note data types: Char (character), Date, Memo (for character large objects or CLOBs up to 32K), or Number.

   Attribute types Algorithm and URL should always have a data type of Char.

   You can use the Memo data type for either STANDARD or WORKFLOW Informative Note types.

7. In the Entry Length field, enter a maximum length for Informative Notes based on this attribute. Entry length is irrelevant for Informative Notes of data type Memo or Date. If you do not enter a value in this field for a Char or Number Informative Note, TMS supplies the default value of 300 characters.

8. Save.

Defining the Details for the Informative Note Attribute

Attribute details are optional, but you can create a more specific and useful Informative Note Attribute by specifying them for some applications.

Description of the illustration ''tmsdfatt_details_block.gif''

To define attribute details:

1. Navigate to the Details block on the Informative Note Attributes tab to enter attribute details.

2. In the Attribute Code field, enter a mixed-case code to use to link this Informative Note Attribute to an attribute defined in a vendor's dictionary.

3. In the Short Name field, you can enter a unique value for the short name of this Informative Note Attribute. TMS allows short names containing up to ten bytes of alphanumeric text. If you leave this field blank and save the record, TMS supplies a default, unique value.

4. In the Description field, you can enter user-defined text about this Informative Note Attribute.

5. In the LOV Statement field, you can enter the SQL statement you want to use to populate a list of values for Informative Notes based on this attribute. The system limits values to those in the LOV only if you select the LOV Validation? box, described in the above section, "Defining Informative Note Attribute Properties".

6. Save. TMS commits this Informative Note Attribute to the database, which enables you to create Informative Notes based on this attribute.

Entering Variables in Dictionary-wide URL Informative Notes

You can use variables to add information in the text of the URL. For example, if you include the variable %TERM% in a dictionary-wide URL Informative Note, TMS substitutes the term name in the text of the URL. Thus, when you define the dictionary-wide URL Informative Note https://www.google.com/#q=%TERM%, the term rubeola inherits https://www.google.com/#q=rubeola as an Informative Note. You can connect to this URL from the Browse Informative Notes window.

You can insert the following variables into URL values. They correspond to columns in two internal TMS tables.

• These variables correspond to columns in the TMS_DICT_CONTENTS table and apply to term records:

  • TERM

  • TERM_UPPER

  • VALUE_1, VALUE_2, VALUE_3, VALUE_4

  • COMMENT_TEXT

  • CATEGORY

  • DICT_CONTENT_ID

  • DICT_CONTENT_CODE

  • DICT_CONTENT_ALT_CODE

• These variables correspond to columns in the TMS_DEF_DETAILS table and apply to Informative Notes:

  • LABEL_TEXT

  • LABEL_TEXT_UPPER

  • DEF_DETAIL_ID

  • DICT_INFO_HDR_ID

To add a variable to a URL Informative Note:

1. Click in the Value field and enter the basic URL.

2. While the cursor is in the Value field, press F9 or select Edit to see the list of values.

3. Select a variable and click OK. TMS appends %variable% to any text in the Value field.

You can also cut and paste variables in the Value field to create a valid URL.

RDC Action Informative Notes

If you have TMS integrated with Oracle Clinical and are using Remote Data Capture (RDC) Release 4.5.3.10 or above, you can use the RDC Special Listings page to display information about a patient's adverse events, concomitant medications, or other data in TMS.

You use a special type of Informative Note to specify the text of the item in the drop-down list on the Home and Casebooks pages for a particular dictionary. By default, this text is: Review TMS_Dictionary_name / DCM_name. On the Special Listings page itself the same value (without "Review") appears in the Listing Type drop-down.

You can replace the dictionary name with text that would be more meaningful to RDC users, such as Adverse Events or Concomitant Medications, so that the item in the Home and Casebooks pages' drop-down list would be "Review Adverse Events / DCM_Name," for example, rather than "Review MedDRA / DCM_Name."

To do this:

1. In the Informative Notes field, select RDC Action Text from the list of values.

2. In the Value field, enter the text you want to appear in the RDC drop-down list, such as Adverse Events or Concomitant Medications.

3. Save.

   Note:

   You can define only one Informative Note of Attribute RDC Action Text for each dictionary. The value text is used in RDC for every study and domain where the dictionary is used.

Defining a Dictionary Version Informative Note

You can use a specialized, predefined Informative Note Attribute called Dictionary Version to assign a version number to a dictionary. To define the version for a dictionary, using an Informative Note:

1. Open the Define Dictionaries window and select a dictionary. You can define a version number for base or virtual dictionaries.

2. Click the Informative Notes button. The Maintain Dictionary Informative Notes window opens.

3. In the Informative Note field, click the ellipsis (…) button. TMS opens the Informative Note Attributes list of values window.

4. Choose Dictionary Version from the list of values, and click OK. TMS populates the Informative Note and Type fields with your attribute selection.

5. Enter the version number in the Value field.

6. (Optional) Enter a status to define this version number further.

7. Save. TMS validates the entry and saves the Informative Note, returning you to the Define Dictionaries window.