2 Setting Up Adapters to External Systems

This chapter contains the following topics:

• About Adapters
  The Oracle Life Sciences Data Hub (Oracle LSH) includes a set of predefined adapters that handle the interface between Oracle LSH and external systems.
• Adapter Structure
  Oracle Life Sciences Data Hub adapters are defined objects like other defined objects in Oracle LSH.
• Creating Your Own Adapters
  You can create adapters to other external systems you want to use with Oracle Life Sciences Data Hub; for example, third party visualization and reporting tools.
• Setting Up Security for Adapters
  This section contains the following topics:
• Clearing Oracle Applications Cache
  Every time you assign a user to a user group, clear the Oracle Applications cache so that users logging into Oracle Life Sciences Data Hub do not see unassigned privileges.

About Adapters

The Oracle Life Sciences Data Hub (Oracle LSH) includes a set of predefined adapters that handle the interface between Oracle LSH and external systems.

Each adapter is customized for a particular system, containing the particular functions that are required internally by Oracle LSH to safely control the exchange of data and metadata with the external system.

When you upgrade to a new version of either Oracle LSH or one of these external systems, you may need to upgrade the adapter, but you do not need to upgrade the other system.

Oracle LSH also includes a set of adapters used for internal purposes.

Oracle LSH includes adapters to different types of external systems: Programming Languages, Source Data Systems, Visualization Tools, and Data Export Tools. You can create custom adapters to allow you to integrate additional systems such as third party visualization tools with Oracle LSH. For more details, see Creating Your Own Adapters.

This section contains the following topics:

• Programming Languages
  Oracle Life Sciences Data Hub is integrated with adapters for programming languages to enable data transformation.
• Source Data Systems
  To load data into Oracle Life Sciences Data Hub from an external system, you must use an adapter. A defined object called a Load Set is also required.
• Visualization Tools
  Oracle Life Sciences Data Hub also uses adapters to allow external systems access to Oracle LSH data for creating data visualizations and reports.
• Data Export Tools
  To transport Oracle Life Sciences Data Hub data to a different system, you create a defined object called a Data Mart.

Programming Languages

Oracle Life Sciences Data Hub is integrated with adapters for programming languages to enable data transformation.

A defined object called Program is also required. Oracle LSH Programs typically read data from source tables and write data into target tables. The source and target tables reside in Oracle LSH. Oracle LSH Programs can also work without interacting with tables, if the requirement is such.

When a Definer creates an Oracle LSH Program, the only Program types available to him or her are those that correspond to the particular adapters to which the Definer has security access.

Source Data Systems

To load data into Oracle Life Sciences Data Hub from an external system, you must use an adapter. A defined object called a Load Set is also required.

When a Definer creates a Load Set, the only Load Set types available to him or her are those that correspond to the particular adapters to which the Definer has security access. The system uses Parameters and Programs predefined as part of the adapter to create the Load Set. For all source data adapters except Text, Oracle LSH pulls table or data set metadata from the external system to create target Tables in Oracle LSH.

When a user runs the Load Set, the adapter handles the interaction between the two systems, including the actual loading of data.

Visualization Tools

Oracle Life Sciences Data Hub also uses adapters to allow external systems access to Oracle LSH data for creating data visualizations and reports.

The defined object required for allowing data access to visualization tools is the Business Area, which specifies which data will be available to a visualization. When a Definer creates a Business Area, the only Business Area types available are those that correspond to the particular adapters to which the Definer has security access. It is possible for customers to create adapters to third-party visualization and reporting tools.

Data Export Tools

To transport Oracle Life Sciences Data Hub data to a different system, you create a defined object called a Data Mart.

There are three types of Data Marts: Text, Oracle Export, and SAS Data Mart.

Adapter Structure

Oracle Life Sciences Data Hub adapters are defined objects like other defined objects in Oracle LSH.

An adapter consists of an Adapter Domain with one or more Adapter Areas, each containing a Work Area. The Adapter Area also contains two Program definitions with source code for each custom function required by the external system, and the Parameter Set required for each Program. The Work Area contains an instance of each Program. Figure 2-1 shows object ownership within an Adapter Domain.

Note:

The Work Area, like other Oracle LSH Work Areas, must be installed in the database in order to function. Adapter Work Areas are installed as part of the post-installation jobs. For more details on running the post-installation programs, see the Oracle Life Sciences Data Hub Installation Guide.

Figure 2-1 Adapter Structure: Object Ownership

Description of "Figure 2-1 Adapter Structure: Object Ownership"

Oracle LSH Release 2.4.8 includes the following Adapter Domains (the names in parentheses appear in the Oracle LSH user interface):

• Oracle Export (ORACLE EXPORT). The Oracle Export adapter is required to create Oracle Export Data Marts.
• Oracle Clinical (ORACLECLINICAL_ADAPTER). The Oracle Clinical Adapter Domain includes many different Adapter Areas, one for each type of Oracle Clinical Load Set. You can assign different user groups to each one if you want to.
• Oracle Family (ORACLEFAMILY_ADAPTER). The Oracle adapter is required to create Load Sets of type Oracle Tables and Views. This adapter is also required to create Programs of type PLSQL and Oracle Reports.
• SAS Family (SASFAMILY_ADAPTER). The SAS adapter is required to create SAS Load Sets.The SAS adapter is also required to create Programs of type SAS, SAS Macro Catalog, and SAS Format Catalog.
• SAS Export (SAS EXPORT). The SAS Export adapter is required to create SAS Data Marts.
• Text Export (TEXT EXPORT). The Text Export adapter is required to create Text Data Marts.
• Text Family (TEXTFAMILY_ADAPTER). The Text adapter is required to create a Text Load Set. It uses the defined Load Set Parameter values to create a control file for the SQL*Loader.
• OBIEE Adapter (OBIEE). The Visualization adapter is required to create Oracle Business Intelligence (OBIEE) visualizations of Oracle LSH data.
• BIP Adapter (BIP_ADAPTER_DOMAIN). The BIP adapter is required to create Oracle LSH Business Intelligence Publisher (BIP) Programs.
• Informatica (INFORMATICA_ADPTR_DOMAIN). The Informatica adapter is required to create Oracle LSH Informatica Programs.
• Generic Visualization Adapter (GENERIC_VISUALIZATION). The generic visualization adapter is required to create visualizations of LSH Data in tools other than OBIEE.
• InForm (INFORMFAMILY_ADAPTER) This is required for use with Oracle Health Sciences Data Management Workbench to enable loading data and metadata from Oracle InForm into Oracle DMW.

Oracle-technology source data adapters (Oracle and Oracle Clinical) contain the Remote Location and Connection information you define for the external Oracle system. For more details, see Registering Locations and Connections.

Creating Your Own Adapters

You can create adapters to other external systems you want to use with Oracle Life Sciences Data Hub; for example, third party visualization and reporting tools.

You must create the same definitional object structure that the predefined adapters use (see Adapter Structure), and install the adapter Work Areas to the database. There is no user interface in Oracle LSH for creating adapter; you must use the Application Programming Interface (API). Instructions are available in a White Paper posted on My Oracle Support.

After you have created an adapter it appears in the Oracle LSH user interface and you can assign user groups to it the same way you do for the predefined adapters; see Setting Up Security for Adapters.

Setting Up Security for Adapters

This section contains the following topics:

You set up security for adapters the same way you do for other definitional objects: assign user groups to them, and assign users to roles within the groups. For more details, see Setting Up Object Security for information on creating user groups and roles.

The Oracle LSH Adapter Security Admin role is required to see the Adapter Security subtab of the Security tab and to perform the following tasks:

• Assigning User Groups to Adapter Domains and Adapter Areas
  This section contains the following topics:
• Creating Roles with the Required Operations for Adapters
  To define an Oracle Life Sciences Data Hub object of a particular type, a user must belong to a user group assigned to the corresponding Adapter Area (either explicitly or by inheritance) and must be assigned a role within the user group that has View privileges on the Adapter Area and on all the objects it contains.

Assigning User Groups to Adapter Domains and Adapter Areas

This section contains the following topics:

As with other defined objects, objects contained in an Adapter Domain inherit the user group assignments of their containing object by default.

Some predefined adapters have only one Adapter Area in the Adapter Domain, and you need only assign a user group at the Domain level.

However, where an Adapter Domain contains multiple Adapter Areas, you can assign security to each Adapter Area separately; for example, if you want different users to be able to run different types of Oracle Clinical Load Sets, you can assign different user groups to the corresponding Adapter Areas.

SAS Family Adapter, Visualization Adapter, Oracle Family Adapter, and Oracle Clinical adapter Domains have more than one Adapter Areas.

This section contains the following topics:

• Assigning User Groups
  To assign a user group to an adapter, do the following:
• Viewing and Modifying User Group Assignments
  To see the user groups currently assigned to an adapter, do the following:

Assigning User Groups

To assign a user group to an adapter, do the following:

1. Navigate to the Security tab and then the Adapter Security subtab.
2. Click the padlock icon in the Apply Security column for the adapter to which you want to assign a user group. The Manage Security screen opens.
3. Click Assign Group. The Search User Group screen opens.
4. In the Group Name field, enter the name of the user group you want to assign, or enter part of the name and use the % wildcard.
5. Click Search. The system displays the search results.
6. Select one or more groups and click Apply to assign those groups to the Adapter Domain. The system displays the assignments with a confirmation message.

Viewing and Modifying User Group Assignments

To see the user groups currently assigned to an adapter, do the following:

1. Navigate to the Security tab and then the Adapter Security subtab.
2. Click the padlock icon in the Apply Security column for the adapter to which you want to assign a user group. The Manage Security screen opens, displaying the current user group assignments.

You can change user group assignments as follows:

• To assign another user group to the adapter, click Assign Group and follow Steps 4 through 6 above.
• To unassign a user group that was explicitly assigned to the Adapter Domain or Adapter Area, click the icon in its Unassign column.
• To unassign a user group that was assigned to an Adapter Area by inheritance, click the icon in the Revoke column.
• To reassign a user group that was assigned to an Adapter Area by inheritance and then revoked, click the icon in the Un-Revoke column.

Creating Roles with the Required Operations for Adapters

To define an Oracle Life Sciences Data Hub object of a particular type, a user must belong to a user group assigned to the corresponding Adapter Area (either explicitly or by inheritance) and must be assigned a role within the user group that has View privileges on the Adapter Area and on all the objects it contains.

Create roles and add operations to roles as usual in Oracle LSH. For more details, see Creating Object Security Roles.

The View operation on the following objects (of subtype Default) is required:

• Adapter Domain
• Adapter Area
• Work Area
• Program
• Program Instance
• Parameter

  Note:

  Do not include Modify privileges on Parameters. If you include Modify privileges, users with that role will be able to modify adapter Parameter definitions through Parameter instances contained in Load Sets, Data Marts, and Business Areas, because they reference the Parameter definition in the Adapter Area. Modifying Parameter definitions in the Adapter Area will increment the version number of the adapter and all Load Sets, Data Marts, and Business Areas of that adapter type will no longer work.
• Parameter Instance
• Parameter Set
• Parameter Set Instance
• Source Code
• Source Code Instance
• Table (required for Oracle Clinical adapters only)

  Note:

  Do not include Modify privileges on Tables. If you include Modify privileges, users with that role will be able to modify adapter Table definitions through Table Descriptors of Oracle Clinical Load Sets, or through Table instances created from those Table Descriptors, because both reference the Table definition in the Adapter Area. Modifying Table definitions in the Adapter Area will increment the version number of the adapter and all Load Sets of that type will no longer work.
• Remote Location (required for any Oracle-technology adapters)
• Connection (required for any Oracle-technology adapter)

In addition, for Oracle-technology adapters include all operations on Connections.

Clearing Oracle Applications Cache

Every time you assign a user to a user group, clear the Oracle Applications cache so that users logging into Oracle Life Sciences Data Hub do not see unassigned privileges.

Note that by not clearing the cache, users can only see unassigned privileges but not use them. However, to avoid any confusion, it is recommended to clear the cache.

Do the following:

1. Log in as anOracle LSH user with the Functional Administrator responsibility. See Assigning Application Roles for instructions on granting this responsibility.

   The Security tab's Grants screen appears.

   Note:

   You can also log in as the sysadmin user if you do not want to assign the Functional Administrator responsibility only for the purpose of clearing cache.
2. Click the Core Services tab from the Grants screen. The Lookup Types screen appears.
3. Click Caching Framework from the list of secondary tabs. The Overview screen opens.
4. Click Global Configuration from the left panel. The Global Cache Configuration screen opens.
5. Click Clear All Cache. A warning appears.

   Click Yes.