Importing Metadata from ADF Data Sources

There are different ways to import metadata from ADF data sources into Oracle Business Intelligence.

Before you can import metadata from ADF sources, you must complete the steps in Setting Up ADF Data Sources

This section contains the following topics:

• Performing an Initial Import from ADF Data Sources

• Using Incremental Import to Propagate Flex Object Changes

• Automatically Mapping Flex Object Changes to the Logical Model

• Automatically Mapping Flex Object Changes Using the biserverextender Utility

Performing an Initial Import from ADF Data Sources

You can use the Import Metadata Wizard to perform an initial import from ADF data sources.

• See Automatically Mapping Flex Object Changes to the Logical Model.

• See Create a new Application Module configuration, in Deploying the Application EAR File to Oracle WebLogic Server from JDeveloper.

• See About Specifying a SQL Bypass Database.

1. In the Administration Tool, select File, then select Import Metadata.

   Note:

   If you have already defined an existing ADF data source and connection pool, you can right-click the connection pool in the Physical layer and select Import Metadata.

2. The Import Metadata Wizard, in the Select Data Source screen, select OracleADF_HTTP for Connection Type. Then, provide the following values:

   • Select New Connection, or select Existing Connection if you already have a connection pool for this data source. Click Browse to locate and select an existing connection pool. If you select Existing Connection, you do not provide information for Data Source, AppModule Definition, AppModule Config, or URL, and the User Name and Password fields are prefilled.

   • Keep the Data Source field blank to use the default JDBC data source configured in the application module. You only need to provide data source information, a JDBC data source name, such as jdbc/nWindORA05, if you want to use a different data source than the one set up in the application module.

   • For AppModule Definition, provide the fully qualified Java package name of the Root Application Module to which you want to connect, such as oracle.apps.fii.receivables.model.RootAppModule, or snowflakesales.SnowflakeSalesApp.

   • For AppModule Config, provide the name of the configuration you want to use in your connection, such as RootAppModuleShared or SnowflakeSalesAppLocal..

   • For URL, provide the URL to the Oracle Business Intelligence broker servlet, in the format:

     http://host:port/APP_DEPLOYMENT_NAME/obieebroker
     

     For example:

     http://localhost:7001/MyApp/obieebroker
     

     The URL is case-sensitive.

   • For User Name and Password, provide a valid user name and password for the Oracle ADF application. The user name and password must be set up and authenticated in the Oracle WebLogic Server security realm.

   When you have finished providing information in the Select Data Source screen, click Next. The Select Metadata Objects screen appears.

3. Select the objects you want to import in the Data source view and move them to the Repository View, using the > (Import selected) or >> (Import all) buttons. You can also move objects from the Repository View back to the Data source view, using the < (Remove selected) and << (Remove all) buttons.

   To search for a particular item, enter a keyword in the Find box and then click Find Down or Find Up.

   Select Show complete structure to view all objects, including those that have already been imported. Deselecting this option shows only the objects that are available for import. When this option is selected, objects that have already been imported appear grayed out.

   If this import is creating a new connection to the data source, when you move the items from the Data source view to the Repository View list, the Connection Pool dialog opens, showing the values that you provided in the Select Data Source screen of the Import Metadata Wizard. Optionally, click the Miscellaneous tab of the Connection Pool dialog and provide the name of a SQL Bypass database in the SQL Bypass Database field. Then, click OK. If you do not want to specify a SQL Bypass database, click Cancel.

4. Click Finish to close the wizard, or click Next to continue to the Map to Logical Model screen.
5. To validate that your import was successful, expand the database object for the ADF data source in the Physical layer. Then, right-click a physical table and click View Data. If the appropriate data is displayed, the import completed successfully.

Using Incremental Import to Propagate Flex Object Changes

If you make changes to flexfields in your ADF applications, then you can use the Import Metadata Wizard in the Oracle BI Administration Tool to incrementally import the changes to the Physical layer of the Oracle BI repository.

The Import Metadata Wizard includes a synchronization feature for ADF data sources that enables you to import only the changes made to objects. Synchronization detects the changed objects, including new joined dimensions (KFF) and new attributes (DFF and EFF) to enable adding the objects automatically, without the need to search for the changed object.

The synchronization feature detects the following:

• Changes in columns

• Additions or deletions of tables and columns

• Additions of keys and foreign keys

• Newly joined tables

  New tables that are joined to any existing table are only imported when you select the option Automatically include any missing joined objects on the Select Metadata Objects screen.

After import, the ADF data is modeled as shown in the table.

ADF Metadata	Imported BI Metadata
Root Application Module	Database
View Objects	Physical Tables
View Object Attribute	Physical Column
View Object Key	Physical Key
View Links	Physical Joins

Note:

As data is imported incrementally, modifications to properties of attributes are detected and propagated. For example, if an attribute changes its data type, that change is propagated to the physical layer objects.

If you are importing metadata into an existing database in the Physical layer, then confirm that the COUNT_STAR_SUPPORTED option is selected in the Features tab of the Database properties dialog. If you import metadata without the COUNT_STAR_SUPPORTED option selected, then the Update Row Count option will not display in the right-click menu for the database's physical tables.

See Automatically Mapping Flex Object Changes to the Logical Model.

1. In the Administration Tool, in the Physical layer, right-click the connection pool for your ADF OLTP source and select Import Metadata.
2. Click Synchronize to locate and automatically select all recent changes for import.
3. Review the selected metadata to locate the new attributes.
4. Click Finish to close the wizard, or click Next to continue to the Map to Logical Model screen.

Automatically Mapping Flex Object Changes to the Logical Model

After importing changes to flexfields in your ADF application, you can use the Map to Logical Model screen of the Import Metadata Wizard in the Oracle BI Administration Tool to automatically propagate the changes to the Business Model and Mapping layer and Presentation layer.

You can override the default mapping behavior during by renaming logical tables, splitting a view object into multiple tables, and combining multiple view objects into a single logical table.

See Customizing the Mapping Behavior.

You can keep the default behavior, or customize the behavior for your needs. For example, you might want to rename tables and columns in the Business Model and Mapping layer, map to an existing logical table, or map a logical column to multiple source columns. The Column Mapping grid shows alias columns as well as regular columns, so that you can handle customized mappings that include alias columns. The Table Mapping grid enables a single physical table to map to multiple logical tables, and the reverse.

The Table Mapping grid includes a VO Type column. Options include Normal, ETL Only, and Query Only. ETL Only view objects exist only to extend the ETL mappings, and are not used for queries. Logical table sources that reference imported view objects of this type are marked as disabled in the Business Model and Mapping layer. Query Only view objects are only used for queries, and are not passed to the BI Extender for extension into the data warehouse.

The Table Mapping grid also includes a Hierarchy column to use with hierarchies.

Select Create Logical Joins if the imported tables are being mapped to a new business model that is created during the Map to Logical Model step. If the required logical joins in place, do not select the Create Logical Joins option to avoid creating erroneous multiple logical joins.

See Using Incremental Import to Propagate Flex Object Changes.

1. In the Administration Tool, in the Physical layer, right-click Properties.
2. In Properties, select the Connection Pool tab, ADF OLTP source and select Import Metadata.
3. Complete the fields in Select Metadata Objects, and click Next.
4. In Map to Logical Model, review the Table Mapping and Column Mapping grids display the results of a default drag-and-drop.
5. (Optional) In the VO Type, select the option to use.
6. (Optional) In the Hierarchy column, select this option for objects in hierarchies.
7. (Optional) Select Create Logical Joins when the imported logical joins do not already exist.
8. Click Finish to close the wizard.

Customizing the Mapping Behavior

When setting up automatic mapping to the Logical Model, you can create a set of XML files that specify custom requirements for the mappings displayed in the Map to Logical Model screen.

The Administration Tool reads the XML files and then automatically maps the KFF, DFF, and EFF segments according to the specified logic. Each XML file has a top-level element with an appName attribute that specifies the application to which the file applies.

You must create your XML files according to the logic in the XML schema files app_segment_rule.xsd and mapping_rules.xsd. You can find these files in:

ORACLE_HOME\bi\bifoundation\javahost\lib\obisintegration\biextender

All XML files in this directory with the prefix mapping_rules and app_segment_rules are parsed by the Administration Tool for ADF data sources.

You can use the existing app_segment_rules_*.xml and mapping_rules_*.xml in this directory as examples.

See XML Schema Files for ADF Mapping Customizations.

Manually Mapping Flex Object Changes to the Logical Model

You can drag and drop the physical objects to the Business Model and Mapping layer and Presentation layer and skip the logical mapping step in the Import Metadata Wizard.

The Oracle BI Administration Tool supports incremental drag-and-drop for ADF data sources, which enables physical database and schema objects to be dragged and dropped into an existing business model, resulting in updates made only for the incremental changes.

The current logic includes data source-specific default rules that can enable, for example, logical dimensions and hierarchies to be automatically created.

Automatically Mapping Flex Object Changes Using the biserverextender Utility

You can use the biserverextender utility to import flex object changes from your ADF sources and map them to the Business Model and Mapping layer and Presentation layer.

Because this feature does not require the Administration Tool, it is especially useful when you want to map flex object changes on Linux and UNIX systems where the Administration Tool is not available.

To use the biserverextender utility, you must first create an XML parameter file that contains the connection pool for an existing ADF data source. The biserverextender utility retrieves the existing ADF connection pool name from the parameter file, synchronizes the ADF data source, updates the deployed objects in the source, and then maps physical metadata to the Business Model and Mapping and Presentation layers based on the default rule files in the following directory:

ORACLE_HOME/bi/bifoundation/javahost/lib/obisintegration/biextender

See Customizing the Mapping Behavior for information about rule files.

Syntax

biserverextender -R base_repository_name [-P repository_password]
-O output_repository_name -I input_XML_file [-S]

Where:

-R base_repository_name is the name and path of the repository into which you want to import and map flex object changes.

-P repository_password is the Oracle BI repository password for the base repository.

The repository_password argument is optional. If you do not provide the password argument, you are prompted to enter the password when you run the command. To minimize the risk of security breaches, Oracle recommends that you do not provide password arguments from the command line or in scripts. The password argument is supported for backward compatibility only. For scripting purposes, you can pass the password through standard input.

-O output_repository_name is the name and path of the repository generated by the utility.

-I input_XML_file is the name and path of an input XML parameter file that contains the fully-qualified name of a connection pool for an ADF data source.

-S is optional. If -S is not specified, only the changes from the ADF source's DFF, KFF, and EFF objects are synchronized to the Oracle BI Repository. If -S is specified, Oracle BI Administration Tool reimports all of the DFF, KFF, and EFF objects from the ADF source based on the ADF source's database properties, and re-synchronizes the Oracle BI Repository.

-S also incorporates the following changes in the app_segment_rules.xml rules file:

• New mapping rules segments

• New alias table creation

• New ADF VO To Be Exposed subject area or presentation table

Example

biserverextender -R /scratch/my_repos.rpd -O /scratch/my_repos_modelled.rpd 
-I /scratch/ADFSource.xml -S
Give password: password

Sample XML Parameter File

<BIExtenderParameters>
 <ConnectionDetails>
  <ConnectionPool>
   <ConnectionPoolName>"oracle.apps.fscm.model.analytics.applicationModule.Fscm
   TopModelAM_FscmTopModelAMLocal"."Connection Pool"</ConnectionPoolName>
  </ConnectionPool>
 </ConnectionDetails>
</BIExtenderParameters>