1 About Adapters

This section contains the following topics:

• About Adapters
  Oracle Life Sciences Data Hub is designed for integration with other systems.
• Adapter Components
  An adapter includes a number of components. You should understand these components and their relationships when developing adapters.
• Components and the User Interface
  Your adapter allows Oracle Life Sciences Data Hub Definers to create a new type of Load Set, Program, Data Mart, or Business Area.

About Adapters

Oracle Life Sciences Data Hub is designed for integration with other systems.

You can:

• Load data into Oracle LSH from another system
• Copy Oracle LSH data into a file for export
• Transform and report Oracle LSH data using external technologies as integrated development environments (IDEs)
• Allow read-only access to specified Oracle LSH data through a visualization tool

Oracle LSH ships with adapters to other systems for each of these purposes. If you want to integrate Oracle LSH with a different system, you can create your own adapter.

There is a specialized object type in Oracle LSH for each of these purposes: Load Sets for loading data, Data Marts for exporting data, Programs for manipulating and reporting on data, and Business Areas for specifying the data available to a visualization tool. Oracle LSH developers, or Definers, define an object of the appropriate type in order to accomplish any of these tasks. When you create an adapter, you make it possible for Definers to create a new type of Load Set, Data Mart, Program, or Business Area that uses the logic required by your system.

For example, if you create a Load Set adapter, when a Definer creates a new Load Set in Oracle LSH, your adapter appears in the Load Set/Adapter Type drop-down list in the Create Load Set page. If the Definer selects your adapter type, the attributes you have defined for the adapter (if any) appear on the Load Set definition page and the Definer must provide values for them and specify the source data files or tables to complete the Load Set definition. Using the new Load Set, Definers and other users can load data into Oracle LSH from your external system. Your adapter type is also available to the public API for creating Load Sets.

Oracle LSH includes the following adapters:

• Load Set adapters. Oracle LSH ships with Load Set adapters for SAS and text files, Oracle tables and views, and Oracle Clinical.
• Data Mart adapters. Oracle LSH includes Data Mart adapters to copy Oracle LSH data to SAS data sets, SAS CPort and XPort files, text files, and Oracle Export files.
• Program adapters. Oracle LSH includes Program adapters to allow users to write data transformation and/or reporting programs in SAS, SQL Developer, SQL*Plus, Oracle Reports, and Oracle Business Intelligence Publisher.
• Business Area adapters. Oracle LSH includes Business Area adapters for Oracle Business Intelligence Enterprise Edition (OBIEE), including its Administration tool and Presentation Services.

  Note:

  Oracle LSH also includes a Generic Visualization Adapter that is available for use with other visualization tools. To use this adapter, follow instructions in Using the Generic Visualization Adapter. You do not need to follow instructions in any other chapter.

Adapter Components

An adapter includes a number of components. You should understand these components and their relationships when developing adapters.

An adapter includes the following components.

See Designing an Adapter for more information.

• Defined Objects. You must created defined objects in Oracle Life Sciences Data Hub to create an adapter in the same way you do to create an application in Oracle LSH, in a similar hierarchy; see the Oracle Life Sciences Data Hub Application Developer's Guide for more information. You use public APIs to create these objects. The following objects, which are illustrated in Figure 1-1, are required except as noted:
  • Adapter Domain. Each adapter must have one Adapter Domain to hold all the other defined objects.
  • Adapter Area. Each adapter must have one Adapter Area in the Adapter Domain to hold object definitions and the adapter's Work Area. If your external system interacts with Oracle LSH in multiple ways, you may need to create multiple adapters. You can create a single Adapter Domain containing one Adapter Area for each adapter.

    An Adapter Area has attributes that identify functions you write that are required during Load Set, Data Mart, Program, or Business Area definition, installation, and execution. Other attributes determine which buttons are enabled in the user interface and which functions are required for your adapter. The Adapter Areas table (CDR_ADAPTER_AREAS) also includes a column for the Tech Type ID.

  • Work Area. Each Adapter Area must have one and only one Work Area in the Adapter Area to hold an instance of the Program. You install the Work Area and Program instance to create a database schema for the adapter that contains the PL/SQL packages that you write.
  • Program. Each adapter must have a Program definition inside the Adapter Area and an instance of it in the Work Area.

    If more than one person is writing the functions required for the adapter, you may want to put each person's package in a different Program so that they can install and test their functions at different times.

  • Source Code. Each adapter must have at least one Source Code definition and instance inside the Program to contain the PL/SQL functions and procedures you write. You can include all functions and procedures in one or more defined Source Code objects (one PL/SQL package per Source Code object) in one or more Program objects.
  • Parameters and Parameter Sets. If your adapter requires user input, you must define Parameters and their underlying Variables to receive the input. Each Parameter you define must be contained in a Parameter Set with a predefined name. The system looks for each Parameter Set by name at a different time during object definition and execution.
  • Remote Locations and Connections. If your adapter is for an Oracle-based product, you need to create defined objects to register remote locations and connections.
  • Tables. If your system has a fixed data structure from which you want to load data into Oracle LSH, you may want to define that structure in the adapter itself.
• Technology Type. You run an API to add a row to the internal Tech Types table (CDR_TECH_TYPES). This table has columns to store the names of functions you write that are required during Load Set, Data Mart, Program, or Business Area installation or execution.
• PL/SQL Functions and Procedures. For each action a user performs in the user interface (UI) to define or install a Load Set, Data Mart, Program, or Business Area, or to run a Load Set, Data Mart, or Program or launch a visualization tool, you must write a PL/SQL function or procedure to do the work. You must also enter the name of each function or procedure as a value in the appropriate column when you run the Create Tech Type or Create Adapter Area API.

  You write these functions and procedures in one or more PL/SQL packages and upload each package as the source code file for a defined Source Code object in the defined Program in your Adapter Area.

• Service Type(s). Create a new service type for each new technology type.
• Lookup Values. Extend the Technology Types and Service Types lookups for each technology type and service type you add. If you need new file types, extend the File Types lookup as well.

Figure 1-1 Adapter Components and Their Relationships

Description of "Figure 1-1 Adapter Components and Their Relationships"

The diagram shows the metadata object owning relationships for the adapter. All metadata is contained in the Adapter Domain except the technology type. The arrows in the Adapter Domain portion of the diagram show references between object definitions and instances; these are standard Oracle LSH object relations and you create the definition and instance at the same time, using an API. The Work Area is installed as a set of database schemas that store the custom functions and procedures you write. Each custom function's name is stored in a column of either the Adapter Areas or Tech Types table (CDR_ADAPTER_AREAS or CDR_TECH_TYPES). Each Adapter Area stores the ID of its primary technology type.

Components and the User Interface

Your adapter allows Oracle Life Sciences Data Hub Definers to create a new type of Load Set, Program, Data Mart, or Business Area.

Figure 1-2 Selecting the Adapter Type During Object Creation

Description of "Figure 1-2 Selecting the Adapter Type During Object Creation"

When a Definer creates an object of any type, he or she must select an adapter type. The system adds the name you define for the Adapter Area to the list.

Figure 1-3 Object Properties User Interface

Description of "Figure 1-3 Object Properties User Interface"

Note:

The above "screenshot" is an amalgam of buttons and options from different object types and states.

User interface elements for all objects interact as follows with adapter components:

1. The Apply button calls the status_recalc_function for Data Marts. For Programs and Load Sets this function is called on checkin and checkout; see Status_Recalc_Function .
2. The Submit button (available for Programs, Load Sets, and Data Marts only) opens the Execution Setup page displaying the Parameters in the runtime Parameter Set PARAMETERSET_LOADSETLEVEL_RUN, if any, so that the user can enter values and click Submit again to actually run the Program, Load Set, or Data Mart. The system then automatically generates and dequeues an XML message file and calls the execution function(s) specified for the technology type and Adapter Area. Execution also requires a service type and an execution command to invoke the external system; see Planning for Object Execution and Object Execution Functions and Procedures.
3. The Launch button (available for Programs and Business Areas only) invokes the custom function Build_IDE_Cfg_Function. This button becomes active after the user installs the current version of the Program or Business Area.

   Note:

   Launch IDE functionality is not available using the Generic Visualization adapter.
4. The Install button calls the installation function(s) specified for the technology type; see Object Installation Functions.
5. Object Attributes are the Parameters you define in the Parameter Sets named PARAMETERSET_LOADSETLEVEL_DEF and PARAMETERSET_OPERATORLEVEL. They collect user input to use during object definition and Table Descriptor definition respectively; see Planning Parameters and Parameter Sets.
6. The Add Table Descriptor button requires the Adapter Area flag allow_manual_tab_desc_flag to be set to Yes to be active. Users can then manually add Table Descriptors. If this flag is set to No, the button is not available and the adapter define-time functions must create the Table Descriptors required.

   The Upload and Upload Columns buttons for Programs and Load Sets are displayed if the AllowAutoAddTabDesc and Allow_column_upload flags, respectively, are set to Yes or File. You can then write custom definition procedures that call APIs to upload either the whole Table Descriptor structure or just the Columns.

   See Object Definition Functions and Procedures for information on the related functions.

7. The Source Code tab is available for Programs and Business Areas only. No adapter-specific code is required to upload a source code file from the integrated development environment (IDE).
8. The Parameters tab can contain Parameters that you define in the adapter Parameter Set named PARAMETERSET_LOADSETLEVEL_RUN to collect user input. For example, all SAS Data Marts have predefined Parameters for Mode (CPORT or XPORT) and Zip Result Flag (No or Zip) that the Definer can set during Data Mart definition or the user can set at runtime.

   The Parameters tab can also contain Parameters created by a Definer. These are contained in a different Parameter Set and are handled automatically by the system; you do not need to write code or add parameters to any adapter Parameter Set to support this.

   You may need to write your execution function to handle any additional Parameters the definer may create and pass them to the particular program at execution.

9. Planned Outputs You can use the define_time_function to create predefined Planned Outputs for all objects created using your adapter; for example, as a placeholder for Data Mart data files or log or error files for any object type.

   In addition, you can use the status_recalc_function, which is invoked each time an object is modified, to automatically create a Planned Output when a Definer adds an object that requires it; for example:

   • Write the status_recalc_function so that it automatically creates a new data file for the new Table Descriptor each time a Definer adds a Table Descriptor to a Data Mart of your adapter type.
   • Write the status_recalc_function so that it automatically creates a new log and/or error file each time a Definer adds a Source Code object to a Program.

   The system automatically provides the functionality for Definers to create Planned Outputs in Program definitions.