10 About the Oracle BI Server XML API

Oracle Business Intelligence provides utilities to create a generic, XML-based representation of the Oracle BI repository metadata, using the Oracle BI Server XML API. This XML file version of the repository can be used to programmatically modify the metadata. The Oracle BI Server XML API can be used for metadata migration, programmatic metadata generation and manipulation, metadata patching, and other functions.

Note that Oracle BI Server XML API objects correspond to metadata repository objects in an RPD file. These objects are not the same as Oracle BI Presentation Catalog XML objects.

Most of the modeling relationships, including the hierarchical ones, are formed using name references between objects, not by the hierarchical structure of the XML.

Note that the metadata objects in the XML file must appear in a particular order. You can view the set order in the XML schema document under the objectList_t element.

10.1.1 About Using the Oracle BI Server XML API to Merge and Append Objects

Do not use the Oracle BI Server XML API to attempt a full repository merge. The merge feature in the Administration Tool handles an extremely complex set of object comparisons and decisions, and it is not possible to account for and resolve these conflicts using the XML utilities. Because of this, using the XML API to perform a full merge is not supported. Attempting to do so might result in a corrupted repository.

However, you can use the XML API to append objects from one repository to another repository, using the -B option with biserverxmlexec to specify a base repository path name. This approach works when you have two completely separate repositories with no shared objects between the two, including no shared variables or application roles. For example, if you have separate repositories for the Credit and Manufacturing departments, you can take objects from the Credit XML metadata and append them to the Manufacturing XML metadata, and then convert to a single RPD that contains both working models. Using this method, you are essentially adding one repository to another.

Before attempting to perform an append operation, you should create a script to ensure that there are no common objects. Even when your repositories are separate, they might contain the same names for common objects, such as a current_date variable.

10.2 Generating and Executing XML

Oracle Business Intelligence provides the following command-line tools to generate and execute XML:

biserverxmlgen generates XML from an existing RPD

biserverxmlexec lets you execute the XML in offline mode to create or modify a repository file

biserverxmlcli executes the XML against the Oracle BI Server

Before running the XML utilities, you must first run bi-init.cmd (or bi-init.sh on UNIX) to launch a command prompt or shell window that is initialized to your Oracle instance. You can find this utility in:

Then, run biserverxmlgen, biserverxmlexec, or biserverxmlcli from the resulting shell window with the desired options.

Note that when you execute XML to update an existing repository with new content, objects are replaced in their entirety. For example, to change the name attribute of a PresentationTable object from name="Facts Revenue" to name="Facts Financial," you must submit the entire PresentationTable object to biserverxmlexec or biserverxmlcli.

In addition, make sure that the qualified name, UID, and ID are correct when replacing existing objects. The Oracle BI Server assumes that a different ID is a different object.

repository_pathname is the name and location of the repository file from which you want to generate XML

password is the repository password.

The password argument is optional. If you do not provide a password argument, you are prompted to enter a password when you run the command. To minimize the risk of security breaches, Oracle recommends that you do not provide a password argument either on the command line or in scripts. Note that the password argument is supported for backward compatibility only, and will be removed in a future release.

output_file_pathname is the name and location of the XML output file you want to generate. It is recommended that you provide an output filename with an .xml extension.

Specify -8 to use UTF-8 encoding in the generated XML file. If you do not specify -8, the generated XML file uses ANSI ISO-8859-1 encoding by default.

10.2.2 Executing XML in Offline Mode

Use biserverxmlexec to execute XML in offline mode. This utility can generate an entire repository file (RPD) from an XML repository file, or it can modify an existing repository file by applying the changes specified in the XML file. The input XML is validated against the Oracle BI Server XML schema. Any objects that exist in both the RPD and the XML file are overwritten by the corresponding object definitions in the XML file. Note that the same object cannot be defined twice in the XML file.

A qualified name (qualifiedName) or upgrade id (uid) must be specified for each object. When the utility resolves and identifies objects, uids have the highest priority, followed by qualifiedNames. See Section 10.4, "Generic XML Elements and Attributes" for more information about identifier attributes.

input_file_pathname is the name and location of the XML input file you want to execute

base_repository_pathname is the existing repository file you want to modify using the XML input file (optional). Do not specify this argument if you want to generate a new repository file from the XML input file.

password is the repository password. If you specified a base repository, enter the repository password for the base repository. If you did not specify a base repository, enter the password you want to use for the new repository.

The password argument is optional. If you do not provide a password argument, you are prompted to enter a password when you run the command. To minimize the risk of security breaches, Oracle recommends that you do not provide a password argument either on the command line or in scripts. Note that the password argument is supported for backward compatibility only, and will be removed in a future release.

output_repository_pathname is the name and location of the RPD output file you want to generate

10.2.3 Executing XML Against the Oracle BI Server

Use biserverxmlcli to execute XML against the Oracle BI Server. This utility is very similar to biserverxmlexec, but is instead used to modify an online repository. An online repository is a running Oracle BI Server instance that has loaded an existing repository into its navigation space.

user_name is a valid user name. This user must have the manage repository permission (oracle.bi.server.manageRepositories).

user_password is the corresponding user password.

The user password argument is optional. If you do not provide a user password argument, you are prompted to enter a user password when you run the command. To minimize the risk of security breaches, Oracle recommends that you do not provide password arguments either on the command line or in scripts. Note that the user password argument is supported for backward compatibility only, and will be removed in a future release.

repository_password is the repository password for the online repository.

The repository password argument is optional. If you do not provide a repository password argument, you are prompted to enter a repository password when you run the command. To minimize the risk of security breaches, Oracle recommends that you do not provide password arguments either on the command line or in scripts. Note that the repository password argument is supported for backward compatibility only, and will be removed in a future release.

data_source_name is the Oracle BI Server ODBC data source name (DSN) to which you want to connect

ssl_pass_phrase is the SSL passphrase for the Oracle BI Server, if the ODBC connection has been configured to use SSL

-y is the SSL passphrase to the private key file

xml_file_pathname is the name and location of the XML input file you want to execute

10.3 Using the Oracle BI Server XML API

This section provides information about different use cases for the Oracle BI Server XML API feature. This section contains the following topics:

10.3.1 Maintaining Versions of the Metadata

The Oracle BI Server XML API provides an efficient way of keeping versions of an RPD. Rather than storing entire RPD files for each version, you can generate XML patch files using the Create Patch feature in the Compare dialog in the Administration Tool. The patch file contains only the delta of the changes between the current and original versions. Using patch files to store changes eliminates the need to store redundant data in entire repository files and saves disk space. Note that you always need to retain a copy of the original repository file to maintain versions using this method.

You can apply a patch to the original file using the patch merge feature in the Administration Tool, using the patchrpd utility, or by running biserverxmlexec with the -B option.

For example, if you have repository versions A0, A1, and A2, and you have an XML patch file called A2-0delta.xml that contains the changes between the latest and original versions, you can run the following command:

10.3.2 Migrating Metadata from Another System

If you have another business intelligence or reporting system and want to migrate the metadata to Oracle Business Intelligence, you can write an adapter to transform the third-party metadata to the Oracle Business Intelligence generic XML format. The XML schema file (xudml1.xsd) provides a way to understand the structure of the Oracle Business Intelligence metadata. After you have a compatible XML metadata file, you can use the biserverxmlexec utility to create a corresponding RPD file.

10.3.3 Applying a Metadata Patch Against a Running Oracle BI Server

If you use the Administration Tool to make changes to your repository in offline mode, you can use the XML patch feature to apply the changes to an online repository, without needing to restart the server or apply the changes manually.

To do this, open the new version of the repository in the Administration Tool, compare it with the running version, and create an XML patch file using the Create Patch feature. You can then apply the patch against the running Oracle BI Server to load the changes, using the biserverxmlcli utility. For example:

10.3.4 Manipulating Metadata Programmatically

You can use the Oracle BI Server XML API to develop custom applications to modify Oracle BI repository metadata. To do this, you can generate XML from your RPD file using the biserverxmlgen utility, and then parse the XML using a generic XML parser. Because the Oracle BI XML utilities are command-line utilities, they can be invoked from batch files, scripts, or as processes from within the code. You can modify the XML programmatically, and then use the biserverxmlexec utility to generate a new RPD that includes the changes.

For example, the Cloning Application Framework (CAF) uses the Oracle BI Server XML API to replicate content developed for one application so that it can be used by another application. The goal of the CAF application is to reuse content across applications so that it does not need to be developed twice.

CAF users can map Presentation layer objects and logical dimension hierarchies from one RPD to the corresponding names in the other RPD. The CAF application generates XML for the first RPD using the biserverxmlgen utility, then scans the XML to determine the Presentation layer object dependencies in the Business Model and Mapping layer and Physical layer. It then creates the necessary Presentation and Business Model and Mapping layer objects (such as columns, subject areas, and expressions), identical to objects in the first RPD but with the appropriate mapped names. When the corresponding XML is ready, it generates the cloned RPD using the biserverxmlexec utility.

10.3.4.1 Example of Programmatically Creating a Repository Object Using XML

This example shows how to add a presentation column called "Billed Qty" to the "Facts Revenue" presentation table of the "Sample Small" subject area. The logical column in the business model on which it is based already exists, and has the name "Sample Small"."F0 Rev Base Measures"."2-01 Billed Qty (Sum All)".

To add the presentation column programmatically, two metadata changes are needed:

A <PresentationColumn> object must be created for the new "Billed Qty" presentation column. It must reference the "2-01 Bill Qty (Sum All)" logical column to which it maps, and the Facts Revenue presentation table to which it belongs.

The <PresentationTable name="Facts Revenue"> object must be updated to reference the new "Billed Qty" presentation column object.

Figure 10-2 shows a view of what the new presentation column looks like in the Administration Tool after it is created.

This code adds a presentation column that references both the parent presentation table to which it belongs ("Facts Revenue"), and the logical column to which it maps ("2-01 Billed Qty (Sum All)"). Note that although the new presentation column has a qualified name, the id and uid are not specified, because they will be automatically created by the Oracle BI Server when it loads the modified RPD file.

In addition to adding the presentation column object, you must also add a reference to the new object from the existing presentation table object. To do this, generate an XML version of the current repository using biserverxmlgen and search the XML for the name of the presentation table (Facts Revenue). Copy the code for the presentation table object to the clipboard, as follows:

Paste the code for the Facts Revenue presentation table into the Change.rpdx file, and add the appropriate presentation column reference to it. The final Change.rpdx file appears as follows, with the key metadata changes shown in bold:

10.3.5 Moving from Test to Production Environments

When you move from test to production environments, you typically need to update connection pool settings for your data sources. You can use the Oracle BI Server XML API to programmatically update these settings in the repository.

To accomplish this task, you first need to open your test repository in the Administration Tool, manually update the connection pool settings for your data sources, and then save the repository under a different name. Next, you can compare the new repository with the original repository using the Administration Tool and then create an XML patch file that contains the changes. Finally, you can use biserverxmlexec or biserverxmlcli to execute the changes against a test repository.

Example 10-1 provides step-by-step information about how to perform these tasks using an example scenario.

After you create the patch, your test repository might continue to change, including name changes that could affect the parentNames or other attributes in your patch code. If this occurs, regenerate the patch using the steps in this section.

You can use biserverxmlexec to execute the generated XML patch file against the test version of the repository to programmatically update the connection pool settings. For example:

10.4 Generic XML Elements and Attributes

This section describes generic elements and attributes that are common, like Description, name, and id. In the Oracle BI Server XML schema (.xsd file), these elements and attributes are defined under the object_t and ref_t elements.

The only common element is the Description element. This element can hold a text string describing a particular object. For example:

<Description>
<![CDATA[ Generated by Time Series Wizard ]]>
</Description>

There are eleven common attributes defined under the object_t element. Table 10-1 lists these attributes.

Table 10-1 Common XML Attributes in object_t

Attribute Name

Description

name

The name of the object.

parentName

The qualified name of the parent of the object, in the format parent1.parent2.parent3, and so on.

parentId

The global unique identifier of the parent of the object, in the format type_id:parent_object_id.

parentUid

The internal identifier of the parent of the object. Referring to objects using this attribute instead of qualified names can provide faster access.

id

The global unique identifier of the object, in the format type_id:object_id.

uid

The internal identifier of the object. Referring to objects using this attribute instead of qualified names can provide faster access.

iconIndex

The index number for the icon of the object in the Administration Tool.

isDefaultReadable

If set to true, indicates that this object is readable by default.

isDefaultReadWriteable

If set to true, indicates that this object is both readable and writable by default.

isDefaultDeletable

If set to true, indicates that this object is deletable by default.

isDefaultGrantable

If set to true, indicates that this object is grantable by default

isDefaultAll

If set to true, indicates that this object is readable, writable, deletable, and grantable by default.

In addition to the common attributes defined in object_t, additional common attributes are defined in ref_t. These attributes are used when one object references another object or set of objects. For example, business model objects reference the logical tables contained in that business model, using the sub-element RefLogicalTable. All referenced sub-elements have the same common attributes shown in Table 10-2.

Table 10-2 Common XML Attributes in ref_t

Attribute Name

Description

id

The global unique identifier of the object, in the format type_id:object_id.

uid

The internal identifier of the object. Referring to objects using this attribute instead of qualified names can provide faster access.

qualifiedName

The fully qualified name of the object. For example, the qualifiedName attribute for a logical column might appear as follows:

10.4.1 About Object Identifiers

Oracle BI Server XML metadata objects can have three different types of object identifiers, any of which can be used to reference the object. Object identifiers include:

Fully qualified name (qualifiedName). This identifier is the only reference you need to include in your XML when creating a new object, because the other identifiers (uid and id) are automatically generated by the Oracle BI Server when it opens the RPD file. The fully qualified name must be unique within the file, but the name (the text after the last dot) only needs to be unique within the scope of its parent.

The fully qualified name is the best identifier to use when searching an XML repository file to find a particular object, because the name of each object is visible in the Administration Tool. For example:

Note that qualified names for Presentation objects use .. between the subject area and the presentation table name. This syntax is used because there is no such thing as a presentation schema, which would normally go between a catalog and a table. For example:

A similar convention is used for Physical layer objects, when the database does not have a physical catalog or physical schema.

uid. This identifier, also called the UpgradeID, is a 32-bit number that is unique across the entire repository. The uid is created by the Oracle BI Server for the lifetime of the object. You can leave it blank when creating new objects in XML, because the server generates it automatically when it loads the RPD file. When you alter an object, make sure not to change the uid.

The uid is used for compare and merge algorithms. It can also be useful for tracing relationships when analyzing or reverse-engineering XML metadata.

For example: uid="73185"

id. This identifier, also called the VoidID, is created by the Oracle BI Server for the lifetime of the object. It is used in situations where the object type can be used to achieve better performance than the uid.

Like the uid, you can leave the id blank when creating new objects in XML, because the server generates it automatically when it loads the RPD file. When you alter an object, make sure not to change the id.

The id is a structure that contains two pieces of information: the type and a unique number within that type (for example, 2000:123456). Each object type, such as a logical column, has a particular number associated with it (for example, 2000). So, two objects of the same type both have the same number in the first part of the id.

The unique number in the second part of the id is a randomly assigned number within that type. It must be unique within the type, but does not need to be unique across different object types. For example, a repository might have the valid ids 2000:123456 and 2001:123456.

Although the id is typically created by the Oracle BI Server, you can create your own if needed, as long as you ensure that it is unique.

For example: id="4010:1720"

Scripting on this page enhances content navigation, but does not change the content in any way.