3 Administration

Predefined Roles

This section illustrates the predefined roles, with the functions permitted and the menu option associated with each:

A description of each predefined role is included below.

In addition, you can see the grants that are predefined for each of these roles by logging into SQL*Plus as SYSTEM and entering the following:

select *from dba_tab_privs where grantee='TMS_ROLE';

opa_admin

This role grants access to the Security menu, which contains Define Users, Define Security Columns, and Maintain DAGS windows, as well as the DAG and Setting Inconsistencies report and the Create/Drop EXT_Value Indexes job. The three windows allow you to create new users, define their privileges, and migrate user information from an Oracle Clinical database. The DAG and Setting Inconsistencies report displays inconsistencies between users' data access via DAG and their profile settings. The Create/Drop EXT_Value Indexes job creates or drops indexes on external value columns for performance.

rxclin_read

All users are granted this role by default, which gives them access to items under the Repository menu. Thus, all users can browse repository data, VT classification data, and Informative Note data; and all users can run the Date Comparison Report, Dictionary Comparison Report, Dictionary Export Report, and view the TMS Lite Browser.

tms_access

All users are granted this role automatically. This role enables you to view the TMS menu and the Favorites menu.

tms_allocate_priv

This role gives users access to the windows under the Task Allocation menu. In these windows, users can set up task allocation and allocate tasks—approving VTAs, approving Action assignments, and classifying omissions—to other users.

tms_approve_priv

This role gives users access to the Approve VTAs and Approve Action Assignments window under Omission Management. In this window, users can approve and unapprove VTAs, and create workflow Informative Notes for the VTA approval process.

tms_classify_priv

This role gives users access to all the items under Omission Management and also the Task Allocation By Term window under Task Allocation. However, users who do not also have tms_approve_priv cannot approve VTAs or Action assignments. Users with tms_classify_priv can classify verbatim terms, apply actions to omissions, and run the VTA Creation Report and VT Domain Differences Report.

tms_define_priv

This role give users access to all items under Definition and to the Reports tab in the TMS Lite Browser. Users with tms_define_priv can define dictionaries, domains, external systems, Global Actions, search objects, TMS settings, named relations, and Informative Note Attributes. Users can also run synchronization, refresh the context server index, analyze tables, force rederivation from DSI, and purge classified omissions.

tms_dictupg_priv

This role gives users access to every item under Dictionary Upgrade where you can view and manipulate verbatim terms and their relations in the predictionary tables before Activation.

tms_dsi_priv

This role gives users access to the menu item DSI Maintenance including the Maintain DSI Files window and several jobs related to data exchange between TMS and disconnected systems.

tms_integrate_priv

This role gives users access to special integration features in the API, but does not unlock any menus or windows in the application.

tms_maintain_priv

This role gives users access to all items under the Repository Maintenance and Translation Reports menus. Repository Maintenance tasks include: creating and maintaining and deleting terms, relations, and Informative Notes; maintaining dictionary loading error logs; running the Preliminary Repository Report, and running Activation.There are three reports under the Translation Reports menu: Inconsistent Dictionary Codes, Duplicate Dictionary Codes, and Inconsistent Dictionary Relations.

tms_reclassify_priv

This role give users access to all items under VTA Maintenance. Users with this role can promote or demote VTAs, maintain actions, reclassify and declassify verbatim terms, perform high-level reclassification, copy domains, maintain domain copying error logs, and run the Nonapproved VTs Report, Classification to a New Domain Report, and the VT Modifications Report.

tms_research_priv

This role enables Oracle Clinical and Oracle AERS users that do not have any other TMS privileges to use the TMS Lite Browser for drilling down to external system data. You may want to grant this role to external system users who require access to source data searches in the TMS Lite Browser, but do not need access to any TMS windows.

Enrolling an Administrator

In a new installation, you must use a script to create one user with the OPA_ADMIN role. That administrator can then use the Define Users window to create user accounts for all the other users in this database; see "Defining Users" for instructions.

To create a new account for a TMS administrator:

1. Connect to SQL*Plus as SYSTEM and run the following script:

   opa_home\tms\install\tmsadduser.sql

2. Enter the user's first name.

3. Enter the user's last name.

4. Enter a password for this user. Your input is hidden.

   The script creates a user account for the user you specified and gives the user the OPA_ADMIN database role.

   Note:

   You cannot use this script to create a nonadministrator user.

Defining a New User

When you create a new user in the database, you define the user's first and last name, user name in the database, and set a password. Additionally, you can add an email address and set superuser status.

To define a new user, from the Define Users window under the Security menu:

1. Define the Account Name, which is the user name a user specifies upon login to the application. The account name is often prefixed with OPS$ but this prefix is not required.

2. Enter the user's First Name and Last Name. The first name and last name appear in the menu bar when this user is connected to TMS.

3. Set the Super User? field to either Yes or No. If this person is a superuser then no Data Access Group information is stored (see "Assigning Data Access Groups to a User"). Superusers have access to all data. Only superusers can run the following jobs and reports:

   • all Disconnected System Integration (DSI) jobs, including importing and exporting data

   • Autoprocess VTAs

   • Predict VTA/VTI Report

   • Site Impacts Report

   • Omission Impacts Report

   • Cross Dictionary Impacts

   • X Areas with Outstanding Changes

   • Classification Statistics Report

   • Date Comparison

   • Dictionary Comparison

   • Dictionary Export

4. Set the Load User? field to either Yes or No. If set to Yes, this person can load dictionaries into the predictionary tables. Most TMS users do not need this ability.

5. (Optional) Enter a Comment about this user. Comment information can help administrators identify users, and thus maintain each user's privileges more effectively.

6. (Optional) Enter an Email Address for the user. This field is added to support future functionality.

7. Click Create Schema. The "Password to be Assigned to User Account Name" window opens.

   
   Description of the illustration ''users_password.gif''
   
   

8. Enter and confirm the password for this user, and click OK.

If the password entries match, TMS adds this user to the OPA_ACCOUNTS table and TMS_ACCOUNTS table, and grants the TMS_ACCESS role to the account. Proceed to "Assigning and Revoking Roles" to assign additional roles for this user.

Assigning and Revoking Roles

TMS uses menu-based security, so roles give a user access to particular TMS menus or windows. The TMS role TMS_MAINTAIN_PRIV, for example, allows a TMS user to use all of the windows and batch jobs under the Repository Maintenance menu.

This section describes how to assign roles to, and revoke roles from, a TMS user.

Changing a User's Password

You can change any user's password in a database where you have administrator privileges.

To change a user's password:

1. Start a SQL*Plus session as SYSTEM.

2. Issue the following alter user command:

   alter user username
identified by new_password

Assigning Data Access Groups to a User

Data Access Groups (DAGs) work in conjunction with roles to control a user's access to TMS data. You can use them to fine tune the data that a particular user or class of users can operate on. For example, the user with TMS_MAINTAIN_PRIV would still be able to access all of the windows and batch jobs under the Repository Maintenance menu, but if you also assign a DAG that only allows access to MedDRA, then he would see only items relevant to MedDRA.

If a person is designated as a superuser in the Define Users window, he or she belongs to all DAGs and has access to all data.

To assign a DAG:

1. Select the user in the Define Users window, then click Assign DAGs.

   The "Assign DAGs to user Account Name" window opens. If the user has been assigned any DAGs, they are listed.

   
   Description of the illustration ''user_assign_dags.gif''
   
   

2. Place the cursor in an empty field under Dag Name. From the LOV, select the DAG to assign.

3. Click OK. TMS assigns the DAG or DAGs you selected to this account.

Migrating Account Information from Oracle Clinical

This section applies only to TMS installations that are integrated with Oracle Clinical.

TMS stores general user account information in the OPA_ACCOUNTS table and TMS-specific user account information in the TMS_ACCOUNTS tables. See the Oracle Thesaurus Management System Technical Reference Manual for details.

If you have already set up user accounts in Oracle Clinical, you can migrate all account information from ORACLE_ACCOUNTS to OPA_ACCOUNTS, as follows:

1. In TMS, go to Security, then select Define Users.

2. Click Get O*Clinical Account Data.

   The system inserts all records from the ORACLE_ACCOUNTS table into the OPA_ACCOUNTS table. The default comment text for each record is "Maintained in Oracle Clinical."

3. Set up TMS-specific security for each user:

   • Either set their Superuser flag to Yes in the Define Users window or assign a Data Access Group; see "Assigning Data Access Groups to a User".

   • Assign roles as required; see "Assigning Roles to a User".

   • Give dictionary loading privileges if required; see "Defining a New User".

   • Set password; see "Defining a New User".

You must continue to maintain these accounts in Oracle Clinical.

Defining Security Columns

Before you define any DAGs, you must specify which TMS table columns—each of which stores a particular type of data—are available to include in DAGS; if a column is available to DAGs, a particular DAG can limit the data its users can see to one or more values stored in that column in TMS. If the column is not available to DAGs, data for all its values is always viewable to users with normal security access.

The columns available for use in DAG security are:

• DEF_ DICTIONARY_ID. This column contains the IDs of dictionaries defined in TMS. If you make this column available for use in DAGs, you can allow users assigned to DAGs to see data associated with only one or a few dictionaries.

• DEF_DOMAIN_ID. This column contains the IDs of domains defined in TMS. If you make this column available for use in DAGs, you can allow users assigned to DAGs to see data associated with only one or a few domains.

• DEF_INSTANCE_ID. This column contains the IDs of your TMS databases. If you make this column available for use in DAGs, you can allow users assigned to DAGs to see data collected on only one or a few databases.

• DEF_INTEGRATION_KEY. If you have integrated one or more external source data systems with TMS, this column holds the name of the system(s). If you make this column available for use in DAGs, you can allow users assigned to DAGs to see data associated with only one or a few external systems.

• EXT_VALUE_1. This column holds external system data associated with a term and stored in the EXT_VALUE_1 column in the tables TMS_SOURCE_TERMS and TMS_VT_OMISSIONS. For external systems other than Oracle Clinical, you specify the data stored in this column; see "Setting Up External System Columns and Details". For Oracle Clinical, this column stores the name of the Project associated with a source term. If you make this column available for use in DAGs, you can allow users assigned to DAGs to see data associated with only one or a few Oracle Clinical projects, for example.

• EXT_VALUE_2. This column holds external system data associated with a term and stored in the EXT_VALUE_2 column in the tables TMS_SOURCE_TERMS and TMS_VT_OMISSIONS. For external systems other than Oracle Clinical, you specify the data stored in this column; see "Setting Up External System Columns and Details". For Oracle Clinical, this column stores the name of the Study associated with a source term. If you make this column available for use in DAGs, you can allow users assigned to DAGs to see data associated with only one or a few Oracle Clinical studies, for example.

• ASSIGNED. This column holds the user name of the person to whom a term is assigned as a task allocation because the term requires work: approving a VTA, approving an Action assignment, or classifying an omission. If you make this column available for use in DAGs, you can allow users assigned to DAGs to see terms assigned only to themselves (LOGIN_USER) or to specific other users.

To make columns available for use in DAGs, do the following:

1. In the Security menu, select Define Security Columns. The Define Security Columns window opens, displaying each column in a different row.

2. For each column, select a value for the following fields:

   • Used?. If set to Yes, you can define DAGs to control whether users can see the corresponding field in TMS windows. If set to No, DAGs cannot control whether users see the field. The field is visible or enterable to anyone with access to the window.

     Note:

     You can change the Used? setting from No to Yes at any time. After a column is included in a DAG definition you can no longer change the setting from Yes to No.

   • Create Index?. You can set this flag to Yes only for the EXT_VALUE columns. If set to Yes, when you run the Create/Drop EXT_VALUE Indexes job (under the Security menu) TMS creates an index on the values in this column to speed performance when these values are used in the context of security. If set to No, TMS drops the index when you run the same job.

3. Save. TMS enters values in the Creation Time and Created By fields. If you modify the settings for any column, TMS enters values in the Modification Time and Modified By columns.

Creating a DAG

The process of defining a Data Access Group includes three parts: creating the DAG, specifying the DAG rules, and assigning users to the DAG. There are three tabs in the Maintain DAGs window, one for each task.

To create a DAG:

1. In the Security menu, select Maintain DAGs. The DAGs tab is displayed.

2. On the DAGs tab, enter a Name and a Short Name for the DAG.

3. Select an option for the Modify Flag? option. If you want users assigned to this DAG to be able to modify data in the windows to which they have DAG access, select Yes. If not, select No.

4. Enter a Status of Provisional. You can set it to Active any time after the definition is completed, including defining the DAG rules. You can add users to a DAG whose status is either Provisional or Active. Only active DAGs are used to enforce data security.

5. Save. Click the DAG Rules tab and select settings as described below.

Setting DAG Rules

This section includes:

• About DAG Rules

• Defining DAG Rules

• Rules for External System Data

• Rules for Task Allocation

Assigning Users to DAGs

You can assign users to a DAG either in the User Assignments tab of the Maintain DAGs window or in the Define Users window. In the Maintain DAGs window, you can add multiple users to a single DAG at the same time. In the Define Users window you can assign a single user to multiple DAGs at the same time. See "Defining Users" for more information.

To add users to a DAG in the Maintain DAGs window, do the following:

1. In the Security menu, select Maintain DAGs. The Maintain DAGs window opens.

2. Click the User Assignment tab. The User Assignment tab opens.

3. Click in the Account Name field in the first empty row. TMS displays … in the right corner of the field.

4. Click the … to retrieve the list of values including all user accounts available for assignment to a DAG (superusers are not included).

5. Select the user account you want to assign to the DAG. You can query in the Find field to narrow your search.

6. Repeat the procedure to add another user account in the next row as many times as necessary. If necessary, select Insert from the Record field to additional rows, one at a time.

7. Save. TMS assigns the users you specified to the DAG, which now controls their access to TMS data.

DAG and Settings Inconsistencies Report

This section includes:

• About the DAG Settings and Inconsistencies Report

• Running the DAG and Setting Inconsistencies Report

Creating and Dropping External System Value Indexes

Use this job to create or drop indexes on the column EXT_VALUE_1 and/or EXT_VALUE_2 in the TMS tables TMS_VT_OMISSIONS and TMS_SOURCE_TERMS. You specify which column or columns to create an index for in the Define Security Columns window (see "Defining Security Columns") but you must run this job to actually create the index.

For best performance, run this job whenever you add or remove values from the EXT_VALUE_1 or EXT_VALUE_2 columns in a DAG definition.

To run the job, do the following:

1. Under Job-Specific parameters, click in the Actions field and select a value from the drop-down list: Create Indexes or Drop Indexes.

2. Under Schedule, select a Report Server.

3. To run the job at a later time, set the other scheduling parameters; see "Scheduling Parameters".

4. Submit the job.

Profiles

A profile is a catalog of TMS settings values. You can define profiles that specify one or more of the TMS settings, then assign any profiles to users to control their default behavior in TMS. For example, you can create a profile that defines default values for the Action Owner and External System. If you assign this profile to a user (see "User Profiles"), these settings could control that user's default settings for these two fields in TMS.

Two default profiles provide baseline settings for TMS. The Oracle profile includes a standard set of keys and settings that provide default settings throughout the system. The Company Settings profile establishes default values that are specific to your company. Company settings override Oracle settings, and provide a baseline set of values for all users in your company.

The additional, custom profiles you define enable you to set up more specific default values for groups of users. Custom profiles override both the Company Settings and Oracle profiles. You can set up as many custom profiles in TMS as you want, and assign multiple profiles to each user.

User Profiles

The user profile is the set of profiles that have been assigned to a user. For each profile that you assign to a user, you must define a Search Order Number. The Search Order Number shows TMS which profiles to consider first when a user profile contains multiple profile definitions.

TMS sets a user's default values by checking through each profile in the user profile:

1. TMS finds the first user profile (the user profile with the lowest Search Order Number) and sets the value of each TMS field that the setting specifies.

2. TMS then checks each subsequent user profile row in ascending order by Search Order Number. For each of these profiles, TMS sets defaults that have not been set by an earlier profile. If the first user profile created this user's default domain setting, the other profiles cannot override it.

3. The system then checks the Company Settings profile for other TMS settings that have not been specified for this user by any of the user's custom profiles.

4. Finally, TMS checks the Oracle profile for other unspecified TMS settings.

Full List of TMS Settings

Each setting value controls the default behavior of one field in TMS. To determine your default domain, for example, TMS checks through your hierarchy of profiles for a value in the TMS_CURRENT_DOMAIN setting. The system then chooses that domain for you when you log in to TMS.

Many TMS settings control the default value for fields that also appear in the TMS filter windows. The following windows have filters: Approve VTAs, Reclassify Verbatim Terms, Classify VT Omissions, and Maintain DSI Files.

The Approve VTAs and Reclassify Verbatim Terms windows both use the Omissions Filter, with the same settings. The TMS_DSI settings control values in the Maintain DSI Files window. Enter values for TMS_DSI settings only if you are using the Disconnected System Integration feature, and only if you want a default value set in your filter for that window (see "Using TMS with Disconnected Systems").

For information on how to enter values for parent and child settings, see "Defining a Setting When No Parent-Child Setting Relationship Exists" and "Defining a Setting in Parent-Child Relationships".

Settings are grouped according to the part of the application they control:

• OPA Settings

• TMS Forms Settings

• TMS HTML Settings

Defining the Settings for a Particular Profile

The Settings tab enables you to define the default settings values for a profile. All settings are grouped hierarchically by their Top External Area (Top X Area), which describes what part of the application they control. The Top External Areas are OPA, TMS Forms, and TMS HTML.

Some settings also have parent-child relationships, where the child setting depends on the selected value of the parent. For example, the TMS Forms setting TMS_CURRENT_DOMAIN is a parent key for the child key TMS_CURRENT_DICTIONARY. While you can use TMS_CURRENT_DOMAIN to define which domain is selected by default for your profile, you can specify for non-default domains which dictionary is selected by default when you switch to that domain.

This section includes:

• Defining a Setting When No Parent-Child Setting Relationship Exists

• Defining a Setting in Parent-Child Relationships

Defining and Maintaining Profiles

Profiles are the basis for creating default settings. By default, TMS includes the default Oracle Profile and a default Company Profile. You can use the Profiles tab to add, modify, and delete profiles.

To add a new profile, insert a row and enter a display name and a description. The display name appears in the Settings and User Profiles tabs.

To delete a custom profile (that is, one other than the Oracle or Company Profiles), select its row and delete the record. TMS prompts you to confirm the deletion; click Yes to complete the profile deletion. You cannot delete the Oracle or Company Settings profiles.

You can also change the profile's display name or description at any time.

Assigning Profiles to Users

The User Profiles tab displays user/profile combinations, and enables you to assign profiles to (or remove profiles from) users, and to modify a user profile. Because you can assign multiple profiles to a user, the User Profile determines the relative precedence of these profiles.

This tab is also convenient for assigning a profile to all members of a group.

Configuring a User's Profile Search Order

Search Order determines the hierarchy of profiles for a particular user. TMS first consults the profile with the lowest Search Order value and implements the default values it specifies. The system then proceeds through the remaining profiles in ascending order by Search Order value, implementing any defaults that have not yet been set for this session.

Description of the illustration ''settings_user_profiles.gif''

To configure a user's profile Search Order:

1. Query for the user. The window displays a row for each group to which that user belongs, with a Search Order specified for each.

2. Rank the profiles by updating numbers for each row. The lower the Search Order Number, the earlier TMS will consult this profile for this user. Each Search Order Number must be unique for a user.

3. Save.

Reference Codelists in Integrated and Nonintegrated Environments

To integrate TMS with Oracle Clinical, you must set three reference codelists in Oracle Clinical; see "Setting Integration Reference Codelist Values".

If you are using the Disconnected System Integration feature of TMS, see "Setting DSI Preferences with Reference Codelist Settings".

Editing Reference Codelists

To edit a reference codelist:

1. Navigate to the Definition menu and click either Installation Reference Codelists or Local Reference Codelists. The window opens in Query mode.

2. In the Name field, query for the codelist that you want to edit.

3. Define the codes in the lower part of the window using the Description field and documentation for each codelist.

   1. The short value for the code is read-only.

   2. The long value for the code. You can edit this value.

   3. Active? If selected, this codelist value will appear in lists that use this codelist for an LOV. If not selected, this value will not appear.

   4. Default? This box has no effect in TMS.

4. Save.

TMS_CONFIGURATION

TMS_CONFIGURATION provides a list of values and behaviors that you can set for the application. The Short Value column provides a short name for the value or behavior. The Long Value column is enterable, and you can accept the value provided or modify it. If you select Active?, the value becomes valid in the system.

There is no default value for TMS_CONFIGURATION, so selecting Default? does not change the behavior of this reference codelist.

This section provides additional descriptions of TMS_CONFIGURATION values and the features they drive in TMS. See also "Changing TMS_CONFIGURATION Settings After Data Has Been Processed".

The settings are:

Other Installation-wide Codelists

Descriptions of the TMS installation-wide codelists, other than the TMS_CONFIGURATION codelist, follow.

Local Codelists

TMS includes the following local reference codelists.

jdbc/opadatabase_nameDS

Using Search Objects

You can use search objects to supplement TMS's basic Autoclassification process, increasing the likelihood that TMS will find a match for a verbatim term, and specify the order in which you want TMS to execute them. Depending on the Approval Type setting in the Define Search Objects window, if TMS finds a match via a search object, it creates:

• An Omission with a Candidate Term

• An Approved VTA

• A Nonapproved VTA

See "Defining Search Objects".

Creating Global VTAs during Autoclassification

Before running Autoclassification, consider whether you want the VTAs that you create to be available only within the domain in which you create them (Domain VTA) or available to all domains (Global VTA). Two settings in the TMS reference codelist TMS_CONFIGURATION control the default status of VTAs created during Autoclassification: ALLOWGLOVTAS and ALLOWGLOVTAS. If both are set to Y, Autoclassification creates global VTAs. If either is set to N, Autoclassification creates domain VTAs.

You can change the scope of the VTA after autoclassification. For information about promoting a VTA (making a Domain VTA available globally) or demoting a VTA (making a Global VTA specific to a domain), see "Promoting and Demoting VTAs".

Running Autoclassification

When TMS is fully or partially integrated with an external system, the Autoclassification process is triggered by the batch job through which the two systems share information (for Oracle Clinical, this is Batch Validation). When there is no integration between TMS and an external system, you must run the tms_user_autocode package from the API.

You can also do a trial run of Autoclassification without updating the Omissions table by running the TryClassifying function in the tms_user_autocode API package, and view the results by looking in the function output. This allows you to see what the results of Autoclassification would be, without actually updating any data.

Scheduling Frequency

Oracle recommends that you run Synchronization at least five times during the business day at each site. You should also run Synchronization before and after batch jobs that exchange information between TMS and an external system. When TMS is integrated with Oracle Clinical, this happens automatically during Batch Validation.

Data Processed During Synchronization

The Omissions table contains source terms that Autoclassification could not classify. The Source Terms table includes all locally collected source terms and the classification (VTA ID or dict_content_id) for each one. When an omission is classified manually, the Synchronization job moves the source term from the Omissions table to the Source Terms table, associated with its classification. If a VTA is changed at any point, Synchronization changes the VTA ID in the Source Terms table.

The following types of changes require synchronization with the Source Terms table:

• Classifying source term omissions

• Declassifying and reclassifying verbatim terms

• Approving and unapproving VTAs

• Loading a new dictionary (to mark the dictionary for future processing)

• Loading a new dictionary version (to mark the dictionary version and its source terms and omissions for future processing)

• Changes to Informative Notes that are derived to the external system

In addition, if TMS is integrated with an external system, the following changes to source terms in the external system must be synchronized in TMS:

• Definitional changes such as question definition changes or mapping a study or project to a different domain in Oracle Clinical

• Deletion of source terms in the source system (Oracle Clinical responses)

Synchronization runs on data imported using the TMS DSI feature; because the systems are not integrated, the importing instance owns the data.

Synchronization Processing Order

Synchronization always includes two phases, pre-synchronization and post-synchronization.

Pre-synchronization Pre-synchronization runs first. It updates records as outlined "Data Processed During Synchronization" and sets the Update flag to Y so that records will be updated in the external system during the next data exchange (Batch Validation in Oracle Clinical).

Post-synchronization Post-synchronization runs last. It refreshes materialized views if the TMS_CONFIGURATION reference codelist value SYNCREFRESHMV is set to Y (see "SYNCREFRESHMV").

External System Integration If TMS is integrated with an external source data system, additional processing occurs between these two phases during data exchange between the two systems. The data exchange job must:

• Run full autocode on all source terms that have been changed since the last data exchange and on all records in the Source Terms and Omissions tables whose Update flag is checked

• Reset the Update flag on all processed records to N

Oracle Clinical Batch Validation is predefined to do both.

The batch processing unit (a study in Oracle Clinical) is called an X Area in TMS. The following indexes use the X Area to give fast access to source terms and omissions that need to be processed:

• TMS_SOURCE_TERMS_BI3

• TMS_VT_OMISSIONS_BI1

Both indexes include the following columns: NONUNIQUE X_AREA, NONUNIQUE DEF_INTEGRATION_KEY, NONUNIQUE UPDATE_FLAG.

Running Synchronization

To run Synchronization:

1. From the Definition menu, select Jobs, then Synchronize Dictionary Data. The Synchronization batch job window appears. There are no parameters to enter.

2. Use the runner icons in the toolbar to save and retrieve parameter sets as necessary, submit the job, and monitor its progress.

See Chapter 2, "Reports and Batch Jobs" for more information.

Writing a Dictionary Term Display Procedure

Any Dictionary Term Display Procedure must be written with the input and output parameters shown below. Oracle recommends that you create the procedure from the TMS role.

PROCEDURE procedure_name (
   pDictContentId IN NUMBER
   , pDefLevelId IN NUMBER
   , pTermType IN NUMBER
   , pCutOffDate IN DATE
   , pReturnLevel IN OUT VARCHAR2
   , pReturnTerm IN OUT VARCHAR2

After you write a procedure, grant the proper execute privilege to the tms_classify_priv role by issuing the following statement from TMS (or the role you used to write the procedure):

grant execute on procedure_name to tms_classify_priv

Choosing Materialized or Regular Views for Each External System Value

The installation reference codelist TMS_SOURCE_MAT_VIEWS controls whether regular views or materialized views are used to populate the list of values for external system values in the Filter window. Each value in the codelist controls the view behavior of one external system field: for example, setting the long value of the codelist value MV1 to Y will make TMS use a materialized view to populate the list of values for the external value 1 in these Filter windows.

By default, TMS_SOURCE_MAT_VIEWS specifies that materialized views be created for external values 1 to 5, and regular views for external values 6 to 8.

Whenever any of the values in TMS_SOURCE_MAT_VIEWS are changed, you must run the Create Source Terms Views batch job. See "Creating Source Term Views".

To change the view settings for an external system value:

1. Open the Installation Reference Codelists window. (From the Definition menu, select Installation Reference Codelists.)

2. Query for the TMS_SOURCE_MAT_VIEWS codelist.

3. Update the long value for each external system value that you want to change.

4. Save.

Creating Source Term Views

Whenever you change any of the values in the TMS_SOURCE_MAT_VIEWS reference codelist, TMS must create a new view for each external system value you changed. Run the Create Source Terms Views batch job to create the materialized or regular views that your change requires.

To run this job from the user interface:

From the Definition menu, select Jobs, then choose Create Source Terms Views.

To run this job from a SQL*Plus prompt, execute the following API call:

tms_user_data_admin.configSTMatViews

Including the Materialized Views Refresh in the Synchronization Process

You can control whether TMS refreshes materialized views during the Synchronization process by changing the reference codelist value SYNCREFRESHMV in the TMS_CONFIGURATION reference codelist. If this setting is Y, the materialized views refresh will be included in Synchronization.

If you remove the materialized views refresh from Synchronization, you must periodically run the Refresh Source Term Materialized Views batch job to refresh them manually. See "Refreshing Source Term Materialized Views".

To change the inclusion status of materialized views in Synchronization:

1. Open the Maintain Installation Codelists window. (From the Definition menu, select Installation Reference Codelists.)

2. Query for the TMS_CONFIGURATION reference codelist.

3. Scroll down to the SYNCREFRESHMV row, and change its long value setting. A long value of Y includes the materialized views refresh in Synchronization; N removes this refresh from Synchronization.

4. Save. TMS will either couple or de-couple the materialized views refresh and the Synchronization process.

Refreshing Source Term Materialized Views

If you do not refresh the materialized views as part of Synchronization, you must refresh them periodically by running the Refresh Source Term Materialized Views batch job.

To run this job from the user interface:

From the Definition menu, select Jobs, then select Refresh Source Term Mat. Views.

To run this job from a SQL*Plus prompt, execute the following API call:

tms_user_synchronization.RefreshMviews

Add Data Sources

Go through these instructions for one data source at a time.

1. Log in to the WebLogic Server Administration Console at:

   http://host:7101/console/login/LoginForm.jsp
   

2. Select Data Sources, then New, then Generic Data Source.

3. Enter a name for the data source.

4. Enter the JNDI name as:

   • For TMS: jdbc/tmsdatabase_nameDS

   • For OPA: jdbc/opadatabase_nameDS

     Note:

     Enter the JNDI name for OPA in the REPORTS_CONFIG local reference codelist, JDBC_DATA_SRC setting.

5. On the next screen:

   • If the database you want to connect to is a RAC database, choose Oracle's Driver (Thin) for Service connections; Versions:9.0.1 and later

   • If the database is not a RAC database, choose Oracle's Driver (Thin) for Instance connections; Versions 9.0.1 and later

6. On the next screen, deselect Supports Global Transactions.

7. On the next screen, enter the database name, host name, and port for the database. For the user, enter the following user account and its password:

   • For OPA: bc4j_internal

   • For the TMS Lite Browser: ops$tmsbrowser

8. On the next screen, select Test Configuration to validate if you can connect using the pool setup.

9. On the next screen, assign OpaServer1 as the target.

10. Click Finish.

11. Select the newly created Data Source, click the Connection Pool tab, and then click Advanced.

12. Add the property dataSourceName=OracleDataSource into the Properties field (without quotes).

13. If the following property has not already been created by the Create Data Source wizard, add the property databaseName=SID_or_servicename into the Properties field (without quotes).

14. Uncheck Wrap Data Types and save.

15. Review and set additional parameters in Advanced Settings as appropriate for your expected data load.

16. Activate your changes or restart OpaServer1 for the changes to take effect.

Configure Maximum Connections

By default, the value for the Maximum Capacity parameter for each data source, which determines the maximum number of concurrent connections, is 15.

The value for the Maximum Capacity parameter should be equal to or greater than the maximum number of concurrent users you expect for:

• TMS TMS Lite Browser (TMS data source)

• TMS Reports (OPA data source)

To change this value:

1. Log in to the WebLogic Server Administration Console at:

   http://host:7101/console/login/LoginForm.jsp
   

2. Select Data Sources, then select the data source whose setting you want to modify: for example, DS_1_tms for TMS or DS_1_ops for OPA (TMS reports).

3. Click the Connection Pool tab.

4. Scroll down to find the parameter Maximum Capacity.

5. Enter a value as described above.

6. Save.

You must then restart the OPA Server:

1. In the same OPA domain WLS Administration Console, click on Servers, then the Control tab.

2. Select OpaServer1 and then Shutdown - Force Shutdown now.

3. Click Refresh to ensure the State changes to Shutdown.

4. Select OpaServer1 and then Start.

5. Click Refresh to see the State change to Running.

Configure Inactive Connection Timeout

To ensure that a connection is available for a user who needs to run a report, change the default setting of the Inactive Connection Timeout of 0 to 5 or a similar value. This is the number of seconds of inactivity that is allowed before the connection is made available to another user. If set to zero, the feature is disabled.

To change this value:

1. Log in to the OPA domain WebLogic Server Administration Console at:

   http://host:7101/console/login/LoginForm.jsp
   

2. Select Data Sources, then select the data source whose setting you want to modify: for example, DS_1_ops for OPA (TMS reports).

3. Click the Connection Pool tab.

4. Scroll down to find the parameter Inactive Connection Timeout.

5. Enter a value; for example, 5.

6. Save.

You must then restart the OPA Server:

1. In the same OPA domain WLS Administration Console, click on Servers, then the Control tab.

2. Select OpaServer1 and then Shutdown - Force Shutdown now.

3. Click Refresh to ensure the State changes to Shutdown.

4. Select OpaServer1 and then Start.

5. Click Refresh to see the State change to Running.

Granting User Privileges for Using the TMS Lite Browser

Users require the rxclin_read privilege to browse dictionary data. See "Security" for information about creating TMS users and granting them roles appropriate to their work.

Creating a Launch Page, Button, or Link for the TMS Lite Browser

You can customize the shipped TMS Launch page to add a link to the TMS Lite Browser, create a new Launch page, or create a button or link to the TMS Lite Browser from an existing website such as your users' Home page. Oracle provides scripts that help prevent problems that may arise in the TMS Lite Browser.

In addition, you may want to customize the TMS Lite Browser URL:

• If you have multiple databases, you can specify a database other than the default one set up during installation.

• You can enable automatic login, so that the system automatically logs in any user as ops$tmsdbrowser.

  Note:

  By default, automatic login is disabled.

See "Customizing the TMS Lite Browser URL to Support Additional Databases or Automatic Login."

function launch(event,url,windowname){
            if(detectIECompatibility(event)){
                cancelEvent(event);
                return false;
            }
            if(!!!windowname){
                windowname="_blank";
            }
            window.open(url,windowname,'location=0,resizable=1,toolbar=0,titlebar=1,status=1,scrollbars=1,menubar=0','true');
} 

function IECompatDetect(){       
        this.isCompatOn = function(){
                    var ua = navigator.userAgent;
                    var on = false;
                    for(var index=0; index< this.ieUAProps.length; index++){
                        var ieProp = this.ieUAProps[index];
                        if(ua.search(ieProp.layoutEngine) == -1){
                            continue;
                        }
                        if(ua.search(ieProp.browser) == -1){
                            on = true;
                            break;
                        }                   
                    }
                    return (on);
                };       
        this.ieUAProps= [
                        {
                            browser: 'MSIE 10',
                            layoutEngine: 'Trident/6'
                        },
                        {
                            browser: 'MSIE 9',
                            layoutEngine: 'Trident/5'
                        },
                        {
                            browser: 'MSIE 8',
                            layoutEngine: 'Trident/4'
                        }
                    ]
 
    }
function cancelEvent(e){
    var event = e || window.event;
    if(event == null){
        return;
    }
    if(event.preventDefault){
        event.preventDefault();
    }else{
        event.returnValue=false;
        event.cancelBubble=true;
    }
}
 
function compatCheck(event,isCompatRequiredToBeOn){
    var compatOn=(new IECompatDetect()).isCompatOn();
    if(compatOn && !isCompatRequiredToBeOn){
        cancelEvent(event);
        alert("Please turn off IE's Compatibility View. Go to Tools->Compatibility View/Compatibility View Settings to do so.");   
    }
    if(!compatOn && isCompatRequiredToBeOn){
        cancelEvent(event);       
        alert("Please turn on IE's Compatibility View. Go to Tools->Compatibility View/Compatibility View Settings to do so.");   
    }
    return compatOn;
}
function detectIECompatibility(e){   
    return compatCheck(event,false);   
}
 
//Call on load
(function(){
    compatCheck(null,false);
})();

Customizing the TMS Lite Browser URL to Support Additional Databases or Automatic Login

The format of the TMS Lite Browser URL is:

https://server.domain/tmsadf/faces/Login?setUpDone=Y &parameter1=value1&parameter2=value2

This URL, without any parameters, goes to the default database set up during installation and requires the user to log in. You can use one or more parameters to change this behavior:

For example, when both parameters are used:

https://server.domain/tmsadf/faces/Login?setUpDone=Y & db=database& event=doAutoLogin

Enabling and Disabling Automatic Login

If automatic login is enabled, any user can click a link for the TMS Lite Browser and the application opens immediately, bypassing the Login page. The system passes the credentials for the ops$tmsbrowser user, using the password entered in the TMS Installer. Users who log in with automatic login cannot perform searches on patient data.

By default, automatic login is disabled and when users click the link the Login page opens and they must enter their own credentials.

Enabling TMS Lite Browser Logs

Do the following to enable exception log files for the TMS Lite Browser. A file named OpaServer-tms_1.log will be created in Middlware_HOME\user_projects\domains\OPADomain\ servers\OpaServer1\logs.

1. Open the logging config file logging.xml that is located at:

   Middlware_HOME\userprojects\domains\OPADomain\config\fmwconfig\ servers\OpaServer1

2. Add the following entry:

   <?xml version='1.0' encoding='UTF-8'?> 
   <logging_configuration> 
   <log_handlers> 
   .. 
   .. 
    <log_handler name='tmshandler'   
   class='oracle.core.ojdl.logging.ODLHandlerFactory'   
   filter='oracle.dfw.incident.IncidentDetectionLogFilter'> 
      <property name='path'   
   value='${domain.home}/servers/${weblogic.Name}/logs/${weblogic.Name}-tms_1.log 
     
   '/> 
      <property name='maxFileSize' value='10485760'/> 
      <property name='maxLogSize' value='104857600'/> 
      <property name='encoding' value='UTF-8'/> 
      <property name='useThreadName' value='true'/> 
      <property name='supplementalAttributes'   
   value='J2EE_MODULE.name,composite_name,component_name'/> 
     </log_handler> 
   .. 
   .. 
   </log_handlers> 
   <loggers> 
   .. 
   .. 
     <logger name='oracle.pharma.tms.logging' level='ALL'   
   useParentHandlers='false'>   
      <handler name='tmshandler'/> 
     </logger> 
   .. 
   .. 
   </loggers> 
   </logging_configuration> 
     
   

3. Add the following to the URL to get all debug information:

   ?setUpDone=Y&debug=all
   

Using the About Window

The About window shows information about the TMS and other Oracle Health Sciences releases that have been applied to this database. Choose either TMS or OPA from the Installed Product list to browse:

• Which releases have been applied to the middle and database tiers.

• The dates in which these releases were installed.

Report Error

If you are getting an error message like "Java exception" followed by another message like "http://127.0.0.1/opaxdo/getXdoReport not found" when you try to run a TMS report, you may want to modify the setting of registry variable OPA_LOCAL_MT_URL. This variable is used to redirect the server to the opaxdo servlet to get reports. When not defined, http://127.0.0.1 is used as default value.

Depending on the settings on middle tier, you may encounter this problem. To fix it, add a port number to the registry variable OPA_LOCAL_MT_URL value on the middle tier; for example, http://127.0.0.1:7777.

To confirm that the path in the registry variable is correct, submit the value such as http://127.0.0.1:7777 (or, without port, http://127.0.0.1) from a browser on the middle tier. If the registry value is correct, you receive the message "Got Request."

Restart Application Server After Redeploying TMS Lite Browser

If you redeploy the TMS Lite Browser .ear file—for example, to apply a patch—restart the application server, including the WebLogic Admin Server. This helps clear connection pools and any DLLs that may be loaded.

If you do not restart the server, an error message may be displayed the next time a user opens the TMS Lite Browser that includes:

java.lang.UnsatisfiedLinkError: Native Library

Cannot Log In to Application

If you cannot log in to the TMS Lite Browser, you may have entered the application's URL twice in the same browser window.

Close all browser windows and try the URL again.