1 Cross-study setup

Do the tasks listed in this chapter when you set up DMW. Settings apply to all studies.

• Set up lab and other file-based data sources
  
• Select Oracle InForm tables and views for use in Oracle Health Sciences Workbench
  
• Create categories for flags, discrepancies, and validation checks
  
• Create flags for data
  
• Use tags and APIs to create a custom discrepancy workflow
  
• Compare flags, tags, and categories
  
• Set up coding in TMS
  
• Set up a data visualization tool
  
• Configure session timeout (optional)
  

Set up lab and other file-based data sources

This list populates the list of values for creating file-based input clinical data models. Add each lab and any other entity that sends data files to Oracle Health Sciences Workbench. If you are using a clinical electronic data capture system other than Oracle Health Sciences InForm, enter it here.

1. Click the Navigation icon at the top of any page and then click Administration.
2. Make sure the Data Sources tab is selected, then click the Labs subtab.
3. Click the Add icon.
4. Data Source Name: Enter the name of the data source; for example, Central Lab. This value appears in the list of data sources in the File Watcher configuration tab for file-type input clinical data models.

   The system uses only the data source name. All other fields are for your own records.

   The Send All Open Discrepancies? field has no effect in this release.

5. Click OK.

Select Oracle InForm tables and views for use in Oracle Health Sciences Workbench

Select tables and views to be available in all studies by default. The study configurator can override these choices.

Internal InForm metadata and operational tables can be used in DMW studies as source tables in data transformations and viewed in the Default Listings page. Any tables and views used in study templates or standard transformations should be included in studies by default. For example, you may need SUBJECTVISITS metadata for structural reference.

The system stores the tables and views in two internal clinical data models:

• The Metadata model contains tables used by the DMW metadata loading process to create the tables in each InForm input clinical data model.

• The Operational Data model contains tables that store information collected during the course of the study that supports clinical data, including InForm queries, form state flags, comments, and subject visit information.

1. Click the Navigation icon at the top of any page and then click Administration.
2. Make sure the Data Sources tab is selected, then click the InForm Tables and Views subtab.

   The system displays InForm tables and views alphabetically. To sort by the internal data model they are part of if selected, click the heading of the Internal Data Model column.

3. Select the tables and views you want to include by default in DMW studies.

   Tip:

   Some tables are required for internal processing and cannot be deselected.

4. Click the Save icon.

• Available InForm tables and views
  

Available InForm tables and views

Required tables are marked with an asterisk (*).

Metadata

IRV_CONTROL_REVS

IRV_FORM_REVS

*IRV_ITEM_REVS

IRV_ITEMSET_REVS

*IRV_MD_FORMS_CONTROLS

IRV_STUDYVERSIONS

IRV_SECTION_REVS

*IRV_STUDYVERSION_FORMS

*IRV_STUDYVERSION_REVISIONS

*IRV_STUDYVERSION_VISITS

IRV_VISIT_REVS

*RD_DATADICTIONARY

In addition, the Metadata model includes the following required DMW tables:

*DME_IA_SRC_TABLES

*DME_IA_SRC_COLUMNS

*DME_IA_STANDARD_COLUMNS

*DME_IA_TABLE_MAPPING

*DME_IA_COLUMN_MAPPING

*DME_IA_COLUMN_MAPPING_SOURCES

Operational Data

*IRV_COMMENT_REVS

IRV_CUR_COMMENT

IRV_CUR_QUERY

IRV_CUR_SITE

*IRV_CUR_SUBJECT

IRV_CUR_USER

IRV_DIM_SUBJECTVISIT

*IRV_QUERY_REVS

IRV_SV_SUBJECTVISITS

IRV_SUBJECT_REVS

IRV_USERS_SITES

*RT_ACTIVATED_FORMS

*RT_ITEMSTATE

Create categories for flags, discrepancies, and validation checks

Categories are used for two purposes:

• Labeling Discrepancies Users can filter discrepancies by category.

  Create categories to characterize discrepancies (for example, Protocol Violation, Validation Check Not Working, Range or Date Alignment). Categories can also indicate who should review a discrepancy next (for example, Medical Review, DM Review) as an alternative to creating custom actions using APIs with these labels as tags.

  • Users can assign a category directly to a discrepancy.

  • Users can assign a category to a validation check. The validation check then assigns the category to all discrepancies it creates.

• Flagging Records Categories determine which flags are available to assign to which records. You assign categories to clinical data model types. When you create a flag, you assign a category to it. The flag is then available for users to assign to records in model types assigned to the same category.

  Users can assign flags to records and then filter records by flag.

  Tip:

  To simplify flag creation, include the clinical data model type (Input (InForm), Input (File), and Target) in the name of flag categories.

  A discrepancy, validation check, or flag can have only one category assigned at a time. Some categories are created and used by the system and cannot be modified. They have IDs under 100.

To create a category:

1. Click the Navigation icon at the top of any page and then click Administration.
2. Click the Categories tab.
3. Click the Add icon.
4. Enter values in the following fields:

   • Category Name: This label is displayed in the Discrepancies, Listings, Validation Check, and Filter user interfaces.

   • Description: (Optional) The description is not displayed anywhere but here.

   • For Discrepancies?: If selected, users can assign the category to discrepancies.

   • For Validation Checks?: If selected, users can assign the category to validation checks. The validation checks then assign the category to the discrepancies they create.

   • For Flags?: If selected, users can assign flags of this category to records in the type(s) of clinical data model you specify. Additional fields appear and you select one or more data model types:

     • Input (File) for input models that receive their data from data files, usually from labs.

     • Input (InForm) for input models that receive their data from InForm.

     • Input (EDC System) for input models that receive their data from an integrated electronic data capture system other than InForm.

     • Target for models whose data is populated by a transformation from other model(s).

5. Click OK. The system assigns an ID greater than 100 to the category.

Create flags for data

Flags can help track the data review process or move the process along. See Examples of flag use. Users can apply flags to records (not discrepancies) in the Listings pages and filter records by flag in the Listings and Discrepancies pages.

Each flag can have any number of states, and users must assign a flag state to a record as well as the flag. A record can have multiple flags assigned, but only one state per flag. The system does not enforce any rules concerning the transition of a record from one flag state to another.

Flags created in DMW are assigned to records in DMW. These flag assignments are not sent to InForm. The system imports InForm form and item states as flags with the records they are assigned to in InForm. These flag assignments cannot be changed in DMW.

The system audits changes in flag assignments to records with the timestamp and user name, by category, in the internal table DME_FLAG_DATA_A.

Tip:

To have a single flag's assignments audited separately, you can create a separate category for it.

• Create a flag
  
• Examples of flag use
  

Create a flag

1. Click the Navigation icon at the top of any page and then click Administration.
2. Click the Flags tab.
3. Click the Add icon.
4. Enter values:

   • Name: Enter the text you want to appear in the user interface.

   • Description: The description is not displayed anywhere but here.

   • Categories (Required) Select a category. The flag can then be assigned to records in the data model type the category is assigned to. See Create categories for flags, discrepancies, and validation checks.

   • Subject Visit Flag Select this option if the flag is to be applied to records in the Subject Visit table to track subject visit status. Leave it deselected if the flag is to be applied to clinical data records.

   • User-settable Flag If selected, users and validation checks can assign this flag to records. If not selected, the flag is imported from InForm and cannot be changed in DMW.

   • States: Click the Add icon to create a flag state.

     • State Name

     • State Description

     • State Priority Select Low, Medium, or High relative to other states of the same flag and other flags, to help data reviewers prioritize their work.

       The Listings page displays an icon for the highest priority flag state currently applied to each record.

5. Click OK.

Examples of flag use

Flags can help track the data review process or move the process along:

You can create the following flags and write validation check custom programs that examine data and call the public API dme_pub_flag_data.setFlag to set the flag. See the API guide for information about initializing APIs.

• Create a flag called Needs Review with states Medical Monitor and Data Manager. These users can then check for data needing their review.

• Create a flag called Record Complete with two states: Yes and No. Data managers can use this flag to filter for missing data.

  Write a custom program to ascertain that all required fields in a record have a value and apply the flag with the state Yes if they do.

• Create a flag called Validation Checks with the states Validation Not Done, Validation Incomplete, and Validation Complete.

  Write a custom program that compares the timestamp of the last data update for each unlocked record to the execution timestamp for all validation checks run for that study and sets the Validation Checks flag for each record with the appropriate state.

• Create a flag called Data Readiness with states: Not Clean, Clean for Medical Review, and Clean for Analysis. Medical reviewers and statisticians can then query for data with the appropriate flag for their review.

  Write a custom program that uses the above flags or others to set its values.

• Create a subject visit flag called Subject Visit Complete with a single state of On, to be applied only when the subject visit is complete.

  Write a custom program that aggregates flag values for the individual clinical record flags in the examples above: loop through each subject/visit combination and set the Subject Visit Complete flag to On when every record for the current subject and visit in the Adverse Events, Concommitant Medications, and Vital Signs tables, for example, has the Record Complete flag set to On, the Validation Checks flag set to Validation Complete, and the Number of Discrepancies set to an acceptable number.

A validation check can apply a flag to records if it has a custom program that calls the API DME_PUB_FLAG_DATA.SetFlag. The API requires the target table instance object ID and the record's surrogate key value as input. See the and the Oracle Health Sciences Data Management Workbench Application Programming Interface Guide for more information.

Use tags and APIs to create a custom discrepancy workflow

Data reviewers apply an action to a discrepancy to change its state, send it to an external data source, or mark it for review by someone else. Oracle DMW comes with a set of actions; see Default actions.

If your company needs a more granular workflow such as the ability to send a discrepancy for review by different teams while remaining in an Open state, you can use tags and APIs to create custom actions and disable any default actions you do not need.

Custom actions must conform to allowed state transitions; see Discrepancy states and allowed transitions.

Tip:

The Discrepancies page allows users to apply only actions that are valid for all selected discrepancies. Valid actions are determined by:

• The discrepancies' Start State.

• The discrepancies' Start Tag, if any. Default actions do not have Start Tags but custom actions may have them.

• The data source. For example, the Send to InForm action is not available for discrepancies on lab data.

1. Create a tag in the DMW user interface. Tags serve as substates. See Create tags for discrepancies for details.
2. Run an API. See Use APIs to create or modify actions.

• Discrepancy states and allowed transitions
  
• Default actions
  
• Create tags for discrepancies
  
• Use APIs to create or modify actions
  

Discrepancy states and allowed transitions

Figure 1-1 Discrepancy States and Allowed Transitions for Discrepancies

Description of "Figure 1-1 Discrepancy States and Allowed Transitions for Discrepancies"

The diagram shows valid transitions for discrepancies in Oracle DMW integrated with InForm.

Note:

If you are using Oracle DMW with a clinical data system other than InForm, the conditions are configurable. See My Oracle Support article ID 2172786.1, Using the Generic Connector to Integrate DMW with a Clinical Data System.

• Candidate and Open are the two valid beginning states for a discrepancy.

• Cancelled and Closed are the two valid end states for a discrepancy.

• Candidate discrepancies can always move to Open.

• Candidate discrepancies can always move to Cancelled.

• Candidate discrepancies can move to Closed if they have not been sent to InForm. Candidate discrepancies that are in InForm (whether they originated in InForm or DMW) can move to Closed if they were previously in the Open state within InForm. This matches InForm rules.

• Open discrepancies can move to Answered if they were created in Oracle DMW and have not been sent to InForm.

• Open discrepancies can always move to Closed.

• Open discrepancies can move to Cancelled only if they were created in Oracle DMW and have not been sent to InForm.

• Open discrepancies can move to Candidate if they were created in Oracle DMW and have not been sent to InForm.

• Answered discrepancies can be reopened in either the Open or Candidate state.

• Discrepancies can be always be closed from the Open or Answered state.

When a discrepancy is sent to InForm, the system limits the actions an Oracle DMW user can take on the discrepancy. The same limited actions are allowed whether the discrepancy originated in InForm or in Oracle DMW.

• While a discrepancy is in InForm, Oracle DMW users can apply comments and categories to it. These are never sent to the source system.

• While a discrepancy is in Oracle DMW, a user can apply an action that changes the state of the discrepancy and must supply a reason for the change. The reason for change is sent to InForm.

Default actions

Table 1-1 Default Actions

Start State	Action Name	Routing Operation	Result State	Result Tag
Candidate	Open	None	Open	None
Candidate	Cancel Discrepancy	None	Cancelled	None
Candidate	Open in InForm	SendToInForm	Open	SentToInForm (This action creates a new Open InForm query.)
Candidate	Send to InForm	SendToInForm	Candidate	SentToInForm (This action creates a new Candidate InForm query.)
Candidate	Close Discrepancy	None	Closed	ClosedAsIs
Candidate	Needs DM Review	None	Candidate	NeedsDMReview
Candidate	Send to Spreadsheet	Send to Spreadsheet	Open	None
Open	Cancel	None	Cancelled	None
Open	Send to InForm	Send To InForm	Open	Sent To InForm (This action creates a new Open InForm query.)
Open	Send to Spreadsheet	Send To Spreadsheet	Open	Sent to Spreadsheet (This action generates a .csv file in the location you specify that includes all selected discrepancies. The file can then be sent to the lab.)
Open	Needs DM Review	None	Open	NeedsDMReview
Open	Answer Discrepancy	None	Answered	Answered By User Response (if a user uses the action Answer) Answered By Data Change (if a data change occurred in the source system)
Open	Reset to Candidate	None	Candidate	None
Open	Close Discrepancy	None	Closed	Closed By Data Change (if a data change occurred in the source system)
Answered	Reopen Discrepancy	None	Open	None
Answered	Reopen to Candidate	None	Candidate	None
Answered	Close Discrepancy	None	Closed	Closed With Answer

Create tags for discrepancies

A tag is a label that a user can apply to discrepancies by using an action. A discrepancy can have only one tag at a time. Tag uses include:

• Users can filter discrepancies by state/tag combination.

• You can use tags to create substates to direct communication among teams while the discrepancy remains in the same state. For example, two discrepancies might have the state Open but different tags such as DM Review and Med Review.

1. Click the Navigation icon at the top of any page and then click Administration.
2. Click the Tags tab.
3. Click the Add icon.
4. Enter values in the following fields:

   • Tag Name: This text is displayed in the Discrepancies page. Spaces and special characters are allowed.

   • Description: (Optional)

   • Enabled?: Check to allow the tag to be used.

   Note:

   System Tag indicates whether a tag was created by the system or by a user. You cannot modify system tags, but you can disable them.

5. Click OK. The system generates an ID.

Use APIs to create or modify actions

See the API Guide for details on using APIs to create or modify actions. Their attributes include:

• Start and Result States: An action is available to a user only for discrepancies that are in the start state. When the user applies an action, the discrepancy's state changes to the result state.

  The start and result states must constitute an allowed transition (see Discrepancy states and allowed transitions) or be the same. If an action does not change the state, it must apply a tag.

  Note:

  No defined action is required to create a discrepancy.

• Start and Result Tags (Optional): An action is available to a user only for discrepancies with the start tag. When the user applies an action, the discrepancy's tag changes to the result tag.

• Enabled: This attribute determines whether an action is available for use.

Compare flags, tags, and categories

The following table compares flags, tags, and categories. All are available for use in any study.

Table 1-2 Flags, Tags, and Categories

Object	Applied To	Applied By	Used as Filter?	Has Multiple States?	Used for
Flag	Records	User or validation check. InForm flag assignments are imported and can be viewed but not changed.	Yes	Yes	Data management
Tag	Discrepancies	User or validation check, via actions	Yes	No, but can be used to create discrepancy substates	Discrepancy management
Category	Discrepancies, Validation Checks, Flags	Validation check or user	Yes	No	Discrepancy and data management

Set up coding in TMS

Prerequisites:

• TMS must be installed.

• TMS must be integrated with DMW as specified in the DMW Installation Guide.

• Dictionaries and TMS domains must be defined in TMS. Domains allow you to customize terminologies differently for different studies by creating domain-specific terms and classifications. Domains also determine default TMS system behavior.

  Tip:

  DMW displays the domain description, if there is one, for the user to select a TMS domain for use with a particular study. If there is no description, the system displays the TMS domain name.

Show me how!

• Define TMS Sets
  
• Define TMS Set columns
  
• Force rederivation
  

Define TMS Sets

Specify which information to derive by creating one or more TMS Sets for each dictionary. The study configurator then associates TMS domains and their terminologies to a study and maps TMS Set columns to target data model columns.

The study configurator does not need to map all the columns in the TMS Set. You can either:

• Define a single TMS Set for each dictionary in TMS with the maximum number of columns that might ever be required, and let the study configurator select and map the columns needed in each study.

• Define multiple TMS Sets for each dictionary, each with exactly the columns required in a particular study. The study configurator can then map all TMS Set columns to target table columns in that study.

1. Click the Navigation icon at the top of any page and then click Administration.
2. Click the TMS tab.
3. Click the Add icon in the TMS Sets pane.
4. Enter a Name and Description for the TMS Set. Both are displayed on the Study Configuration page.
5. Select a Terminology to code against. All terminologies (dictionaries) defined in the local TMS instance are listed.
6. Click OK. The system adds a column for the dictionary coding level to the TMS Set columns.

Next: Define TMS Set columns

Define TMS Set columns

Define a TMS Set column for each piece of information to be derived from TMS to DMW for each coded term.

1. Click the Navigation icon at the top of any page and then click Administration.
2. Click the TMS tab.
3. Select a TMS Set.
4. Click the Add icon in the TMS Set Columns pane.
5. Column Designation: Enter a descriptive name to enable the study configurator to map this TMS Set column to a table column that will store the derived data.
6. Column Type: Select one:

   • Auxiliary Input: for mapping to a DMW table column that contains auxiliary information required to code data in WHO-Drug Format C, such as the country where the drug is distributed, its form (for example, tablets or coated tablets), or strength.

   • Derived: for mapping to a DMW table column that will hold data derived from TMS.

   • Indicator: for mapping to a DMW table column that contains the indication for which a drug was prescribed. This is used to derive a related high-level term, for example in the Anatomical - Therapeutic - Chemical (ATC) level in WHO-Drug Format C, where the value may vary depending on the indication.

   Each TMS Set also has one column of type Primary. The primary column must be mapped to the column containing items (terms) to be coded.

7. TMS Level Name: Select the level from which to derive data into the mapped column. The choices include all of the dictionary's defined levels and Dictionary Informative Notes, which may be defined in TMS and contain the dictionary version.
8. TMS Field: The options vary depending on whether you specified a dictionary level or InFormative Notes.

   If you specified a dictionary level, the TMS Field choices include:

   • TERM: The dictionary term related to the coded term in the selected level.

   • TERM_UPPER: The dictionary term related to the coded term in the selected level, in uppercase.

   The choices also include optional, customizable level details that your company may have defined for the dictionary level in TMS:

   • CATEGORY: A category value defined by your company in TMS.

   • DICT_CONTENT_ID: The unique ID generated by TMS for the dictionary level.

   • DICT_CONTENT_ALT_CODE: An alternate ID for the dictionary level; designed to cross-reference a legacy company dictionary.

   • DICT_CONTENT_CODE: The unique ID of the dictionary level as provided by the vendor. This column is indexed.

   • VALUE_1 through VALUE_4: Four customizable fields can store information about the dictionary level.

   If you specified text Dictionary Informative Notes for TMS Level Name, select:

   • DICTIONARY VERSION: The dictionary version as defined in an Informative Note for the base dictionary in TMS.

   • (RDC ACTION TEXT is not used.)

9. Click OK.

Force rederivation

Normally, transformations process only new or changed data. Use the Force Rederivation job to process all data when you have made structural changes related to TMS in an ongoing study such as:

• Adding columns to target tables to hold derived data.

• Updating a dictionary to a new version with a different structure from the old one.

• Changing domain-related settings in the TMS reference codelist TMS_CONFIGURATION.

1. Go to the Home page.
2. Select the study.
3. Click the Modify icon at the top of the Studies pane.
4. In the Modify Study window, click TMS.
5. Click Force Rederivation. A confirmation message appears because running the job may take a long time. You can still work while it runs.
6. Click OK.

For information about TMS-DMW data processing, forced rederivation, and DMW data displayed in TMS, see Oracle Thesaurus Management System (TMS) integration.

Set up a data visualization tool

You can integrate an external data visualization tool so that users can view data graphically and interactively with the protection of Oracle DMW security and blinding access privileges.

Visualization tools access one clinical data model at a time, along with any custom listings that read from the model. If you are using custom listings, we recommend setting a profile value as detailed in Use custom listing name for the custom listing schema.

You can use:

• Third-party tools that use generic-type business areas to work with Oracle LSH and Oracle DMW.
• Oracle Business Intelligence Enterprise Edition (OBIEE). An adapter is included with Oracle LSH. See the Oracle Life Sciences Data Hub Installation Guide and System Administrator's Guide for instructions.

  Note:

  To use OBIEE, you must create business areas in Oracle LSH. The business areas that are created automatically for a clinical data model in Oracle DMW are "generic," not specialized for OBIEE. See the Oracle Life Sciences Data Hub Application Developer's Guide for instructions.
• You can build an integration to a different tool. See the DMW Data Visualization Integration Guide, My Oracle Support article 2284413.1. If you are using custom listings, use the API CDR_PUB_API_GVA.getCustomListingBA.

To allow users to see data in a particular DMW clinical data model, the study configurator must select the Business Area option for the model.

Configure session timeout (optional)

By default, a user session times out after 20 minutes of inactivity. To change this setting:

1. Open the plan.xml file, which is contained in the software directory on the WebLogic Server, in a text editor.
2. Locate the following code:

   <variable>
         <name>SessionTimeout</name>
         <value>20</value>
   </variable>
   

3. Change the value to the number of minutes you want to use as a timeout value.

   Note:

   The plan.xml file is replaced for each middle tier DMW patch. You need to repeat this procedure after each patch installation.

4. Redeploy the DMW middle tier, following instructions in the patch release notes or installation guide.
5. Restart the WebLogic Server.