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.

This chapter contains the following topics:

10.1 About the Oracle BI Server XML API

The Oracle BI Server XML schema document (xudml1.xsd) contains the grammar for the structure of XML repository files. You can find this file at:

ORACLE_HOME/bifoundation/server/bin

You can view this file to see relationships between XML metadata objects, but you must not modify this file. Doing so can lead to errors and crashes in the biserverxmlexec utility.

The structure of the repository is primarily a flat list of objects, in the format:

<?xml version="1.0" encoding="iso-8859-1"?>
<Repository xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <DECLARE>
    <ObjectType {attributes}>
      Contents…
    </ObjectType>
    <ObjectType {attributes}>
      Contents…
    </ObjectType>
    …
  </DECLARE>
</Repository>

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.

It is also a good idea to equalize the upgrade IDs to ensure that there are no accidental clashes. Equalizing objects causes objects in two repositories that have the same name but different upgrade ids to be treated as the same object. See "Equalizing Objects" in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition for more information.

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:

ORACLE_INSTANCE/bifoundation/OracleBIApplication/coreapplication/setup

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.

This section contains the following topics:

10.2.1 Generating XML from an Existing RPD

Use biserverxmlgen to generate an XML file from an existing repository file (RPD). To use this utility, execute the following at the command prompt:

biserverxmlgen -R repository_pathname [-P password] -O output_file_pathname [-8]

Where:

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.

To use this utility, execute the following at the command prompt:

biserverxmlexec -I input_file_pathname [-B base_repository_pathname] [-P password] 
-O output_repository_pathname

Where:

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

Examples

The following example creates a new repository called rp1:

biserverxmlexec -I testxudml.txt -O rp1.rpd
Give password: my_rpd_password

The following example modifies rp1 and writes to rp2:

biserverxmlexec -I testxudml.txt -B rp1.rpd -O rp2.rpd
Give password: my_rpd_password

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.

To use this utility, execute the following at the command prompt:

biserverxmlcli -U user_name [-P user_password] [-R repository_password]
-D data_source_name [-w ssl_pass_phrase |-y] -I XML_file_pathname

Where:

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:

biserverxmlexec -I A2-0delta.xml -B A0.rpd -O A2reproduced.rpd
Give password: my_password

Alternatively, if you stored changes between A0 and A1, and then A1 and A2, you can run two commands to apply the latest changes on the original file:

biserverxmlexec -I A1-0delta.xml -B A0.rpd -O A1reproduced.rpd
Give password: my_password

biserverxmlexec -I A2-1delta.xml -B A1reproduced.rpd -O A2reproduced.rpd
Give password: my_password

Make sure to specify different names for the -B and -O arguments to avoid overwriting the original repository file.

See Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition for more information about patch merges.

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:

biserverxmlcli -U my_user -D my_server_dsn -I my_xml_file_pathname
Give user password: my_password
Give repository password: my_repos_password

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)".

Figure 10-1 illustrates the goal of the example.

Figure 10-1 Logical Column Exists in Repository with No Corresponding Presentation Column

Description of Figure 10-1 follows
Description of "Figure 10-1 Logical Column Exists in Repository with No Corresponding Presentation Column"

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

  1. 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.

  2. 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.

Figure 10-2 Administration Tool Equivalent for New Presentation Column

Description of Figure 10-2 follows
Description of "Figure 10-2 Administration Tool Equivalent for New Presentation Column"

To update the metadata, first create an XML file called Change.rpdx. This file will contain the metadata changes needed, in XML format. Add the following code:

<?xml version="1.0" encoding="iso-8859-1"?>
<Repository xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <DECLARE>
    <PresentationColumn name="Billed Qty" parentName="&quot;Sample Small&quot;..
    &quot;Facts Revenue&quot;" parentId="4008:2143" parentUid="73625" 
    hasDispName="false"
    overrideLogicalName="true">
      <Description>
        <![CDATA[This presentation column was added using the XML metadata API.]]>
      </Description>
      <RefLogicalColumn uid="946" id="2006:106" qualifiedName="&quot;Sample 
      Small&quot;.&quot;F0 Rev Base Measures&quot;.&quot;2-01 Billed Qty (Sum 
      All)&quot;"/>
    </PresentationColumn>
  </DECLARE>
</Repository>

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:

    <PresentationTable name="Facts Revenue" parentName="&quot;Sample Small&quot;.
    &quot;&quot;" parentId="4004:2137" parentUid="73609" id="4008:2143"
    uid="73625"
    hasDispName="false">
      <Description>
        <![CDATA[This folder contains several types of aggregation metrics
        leveraging single revenue fact column. It also contains aggregations
        metrics based on Forecast physical table]]>
      </Description>
      <Aliases>
      <Alias name="F1 Revenue"/>
      </Aliases>
      <Columns>
        <RefPresentationColumn uid="72927" id="4010:1707" qualifiedName=
        "&quot;Sample Small&quot;..&quot;Facts Revenue&quot;.
        &quot;Revenue&quot;"/>
      </Columns>
    </PresentationTable>

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:

<?xml version="1.0" encoding="iso-8859-1"?>
<Repository xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <DECLARE>
    <PresentationTable name="Facts Revenue" parentName="&quot;Sample Small&quot;.
    &quot;&quot;"
    parentId="4004:2137" parentUid="73609" id="4008:2143" uid="73625"
    hasDispName="false">
      <Description>
        <![CDATA[This folder contains several types of aggregation metrics
        leveraging single revenue fact column. It also contains aggregations
        metrics based on Forecast physical table]]>
      </Description>
      <Aliases>
      <Alias name="F1 Revenue"/>
      </Aliases>
      <Columns>
        <RefPresentationColumn uid="72927" id="4010:1707" qualifiedName=
        "&quot;Sample Small&quot;..&quot;Facts Revenue&quot;.
        &quot;Revenue&quot;"/>
        <RefPresentationColumn qualifiedName="&quot;Sample Small&quot;.
        .&quot;Facts Revenue&quot;.&quot;Billed Qty&quot;"/>
      </Columns>
    </PresentationTable>
    <PresentationColumn name="Billed Qty" parentName="&quot;Sample Small&quot;.
    .&quot;Facts Revenue&quot;" parentId="4008:2143" parentUid="73625"
    hasDispName="false" overrideLogicalName="true">
      <Description>
        <![CDATA[This presentation column was added using the XML metadata API.]]>
      </Description>
      <RefLogicalColumn uid="946" id="2006:106" qualifiedName="&quot;Sample 
      Small&quot;.&quot;F0 Rev Base Measures&quot;.&quot;2-01 Billed Qty (Sum 
      All)&quot;"/>
    </PresentationColumn>
  </DECLARE>
</Repository>

Finally, run the biserverxmlexec utility to execute Change.rpdx to update the original RPD file. Figure 10-3 shows what the updated repository looks like in the Administration Tool.

Figure 10-3 Updated Repository with New Presentation Column in the Administration Tool

Description of Figure 10-3 follows
Description of "Figure 10-3 Updated Repository with New Presentation Column in the Administration Tool"

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.

See "Moving Oracle Business Intelligence Components to a Production System" in Oracle Fusion Middleware Administrator's Guide for more information about moving from test to production environments in Oracle Business Intelligence.

Example 10-1 Updating Connection Pool Test Values to Production Values

This example shows how to programmatically update test values for two example connection pools to production values.

The following table shows example values for the two example data sources, in both test and production environments.

Environment Data Source Type Data Source Name User Name Password
Test Relational orcl_test user_test password_test
XML VALUEOF(ORACLE_HOME)/XML_data/Forecast n/a n/a
Production Relational orcl_prod user_prod password_prod
XML VALUEOF(ORACLE_HOME)/fcast_data/Forecast n/a n/a

To programmatically update connection pool test values to production values:

  1. Open the test repository (for example, SampleApp_test.rpd) in the Administration Tool.

  2. In the Physical layer, open the connection pool for the relational source that needs to be changed.

  3. Update the values for Data Source Name, User Name, and Password to the production values. Then, click OK.

  4. Open the connection pool for the XML source that needs to be changed.

  5. Update the value for Data Source Name to the production value. Then, click OK.

  6. Select File, then select Save As. Then, save the repository under a new name (for example, SampleApp_prod.rpd).

  7. Select File, then select Compare.

  8. Select the original repository file (SampleApp_test.rpd) to compare to the currently open repository file (SampleApp_prod.rpd).

    Note that the Compare repositories dialog lists the two connection pools you modified, as shown in Figure 10-4.

    Figure 10-4 Compare Repositories Dialog

    Description of Figure 10-4 follows
    Description of "Figure 10-4 Compare Repositories Dialog"

  9. Click Create Patch, enter the name of the patch file you want to create (for example, SampleApp_diff.xml), and click Save.

    The resulting XML patch file might appear as follows:

    <?xml version="1.0" encoding="UTF-8" ?>
    <Repository xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <DECLARE>
    <ConnectionPool name="SampleApp_XML" parentName="&quot;1 - Sample App Xml 
      Data&quot;" parentId="3023:84" parentUid="2160747198" id="3029:1158"   uid="2160747199"
      password="D7EDED84BC624A917F5B462A4DCA05CDCE256EEEEEDC97D5AC4D07C3A079829F"
      timeout="300" maxConnDiff="10" maxConn="10"
      dataSource="VALUEOF(BI_EE_HOME)/fcast_data/Forecast" type="Default"
      reqQualifedTableName="false" isSharedLogin="false"
      isConcurrentQueriesInConnection="false" isCloseAfterEveryRequest="true"
      xmlRefreshInterval="4294967295" outputType="xml" bulkInsertBufferSize="0"
      transactionBoundary="0" xmlaUseSession="false" multiThreaded="false"
      supportParams="false" isSiebelJDBSecured="false">
      <Description></Description>
    </ConnectionPool>
    <ConnectionPool name="SampleApp_Relational" parentName="&quot;1 - Sample App 
      Data&quot;" parentId="3023:85" parentUid="2160747204" id="3029:1159" 
      uid="2160747205" user="user_prod"
      password="D7EDED84BC624A917F5B462A4DCA05CDCE256EEEEEDC97D5A1
      50C61FBEB9092AF80FAEC9819DD51771A41425D03FB466B55BB9F03BCF6439"   timeout="4294967295" maxConnDiff="10" maxConn="10" dataSource="orcl_prod"
      type="OCI10G" reqQualifedTableName="false" isSharedLogin="true"
      isConcurrentQueriesInConnection="false" isCloseAfterEveryRequest="false"
      outputType="xml" bulkInsertBufferSize="131072" tempTablePrefix="TT"
      transactionBoundary="1000" xmlaUseSession="false" isSiebelJDBSecured="false">
      <Description></Description>
    </ConnectionPool>
    </DECLARE>
    </Repository>
    
  10. 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.

  11. 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:

    biserverxmlexec -I SampleApp_diff.xml -B SampleApp_test.rpd 
    -O SampleApp_prod.rpd
    Give password: my_rpd_password
    

    To execute the XML patch file against a repository loaded into the Oracle BI Server, use biserverxmlcli.

10.3.6 Using XSL to Transform XML Files

You can use XSL to perform transformations on the XML files you generate. For example, you might want to use XSL to remove object IDs or UIDs to avoid conflicts.

Example 10-2 shows a sample XSL script that you can use as a model for your own transformations. The example script disables all logical table sources in the repository.

Example 10-2 Sample XSL Script

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"
xmlns:xalan="http://xml.apache.org/xslt"
xmlns:fn="http://www.w3.org/2003/11/xpath-functions">
<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"
cdata-section-elements="Description Expr Value" xalan:indent-amount="4"/>
<xsl:strip-space elements="*"/>

<xsl:template match="/Repository/DECLARE">
  <xsl:element name="Repository">
    <xsl:element name="DECLARE">
      <xsl:for-each select="./*">
        <xsl:call-template name="objectmatch"/>
      </xsl:for-each>
    </xsl:element>
  </xsl:element>
</xsl:template>

<!-- The 'objectmatch' template is matched for every metadata object -->
<xsl:template name="objectmatch">
  <xsl:choose>
    <!-- We copy every object except for Logical Table Sources. We call the
    'ltsmatch' template for LTSs -->
    <xsl:when test="name() = 'LogicalTableSource'">
      <xsl:call-template name="ltsmatch"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:copy-of select=".">
        <xsl:apply-templates/>
      </xsl:copy-of>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

<!-- The 'ltsmatch' template gets matched for every logical table source. -->
<xsl:template name="ltsmatch">
  <xsl:element name="LogicalTableSource">
    <xsl:for-each select="./@*">
      <!-- We call the 'ltspropmatch' template to process specific attributes on
      the LTS -->
      <xsl:call-template name="ltspropmatch"/>
    </xsl:for-each>
    <xsl:for-each select="./*">
      <xsl:call-template name="objectmatch"/>
    </xsl:for-each>
  </xsl:element>
</xsl:template>

<xsl:template name="ltspropmatch">
  <xsl:choose>
    <!-- When we encounter the 'isActive' property, we set it to false. -->
    <xsl:when test="name() = 'isActive'">
      <xsl:attribute name="isActive">
        <xsl:text>false</xsl:text>
      </xsl:attribute>
    </xsl:when>
    <xsl:otherwise>
      <xsl:copy-of select=".">
        <xsl:apply-templates/>
      </xsl:copy-of>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

</xsl:stylesheet>

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:

qualifiedName="&quot;Sample Sales&quot;.&quot;F3 
Rolling Measures&quot;.&quot;1-22L Revenue (All Hist 
Sum)&quot;"

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:

    qualifiedName="&quot;Sample Sales&quot;.&quot;H0 Time&quot;.&quot;Month&quot;"
    

    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:

    qualifiedName="&quot;Sample Small&quot;..&quot;Facts Revenue&quot;.&quot;Billed 
    Qty&quot;"
    

    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"