1 About the Oracle BI Server MDS XML API

This chapter provides information about Oracle BI Server MDS XML, an XML format that is compatible with Oracle Metadata Services and the Oracle BI repository. Oracle Business Intelligence provides the ability to save Oracle BI repository metadata as a set of XML documents in MDS XML format.

Using this feature, you can integrate with third-party source control management (SCM) systems for Oracle BI repository development. For more details, see "Using a Source Control Management System for Repository Development" in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

Note:

MDS XML format is different from the XML format generated by the Oracle BI Server XML API, where the metadata for an Oracle BI repository is generated in a single XML file. For more information about the Oracle BI Server XML API, see Chapter 6, "About the Oracle BI Server XML API."

This chapter contains the following topics:

1.1 About the Oracle BI Server MDS XML API

The contents and structure of the Oracle BI Server MDS XML repository files are defined through the following schema element files:

  • xudml_mds_admin.xsd and xudml_mds.xsd

    These files contain the basic MDS XML grammar for the repository elements.

  • xudml_mds_core.xsd

    This file contains the detailed MDS XML grammar for the repository elements and attributes and the relationships between the elements.

You can find these files at:

ORACLE_HOME/bifoundation/server/bin

You can view these files to see the relationships between MDS XML metadata objects, but you must not modify these files.

1.2 Generating MDS XML

You can generate MDS XML from an existing repository file either from within the Administration Tool or by using a command-line utility.

This section contains the following topics:

1.2.1 Generating MDS XML from an Existing RPD Using the Administration Tool

Perform these steps to generate MDS XML from an existing repository file using the Administration Tool:

  1. Open your existing repository file (RPD) in the Administration Tool in offline mode.

  2. Select File, then select Save As, then select MDS XML Documents.

  3. Select a root location for your MDS XML repository files, and then click OK.

The output files are generated in directories under the following path:

  • root_location/oracle/bi/server/base.

The number of generated directories depends on the complexity of your repository.

For example, with C:\SampleApp_MDS selected as your root location, the output directory structure could be as shown in Figure 1-1.

Figure 1-1 Example of Directories Containing MDS XML Elements

Description of Figure 1-1 follows
Description of "Figure 1-1 Example of Directories Containing MDS XML Elements"

1.2.2 Generating MDS XML from an Existing RPD Using a Command-Line Utility

Oracle Business Intelligence provides the biserverxmlgen command-line utility to generate MDS XML output from a repository file.

Before running biserverxmlgen, you must first run bi-init to launch a command prompt or shell window that is initialized to your Oracle instance. This utility is called bi-init.sh on Linux and UNIX systems, bi-init.bat on client installations of the Administration Tool, and bi-init.cmd for all other Windows installation types.

For example, on Windows:

  1. In Windows Explorer, go to the location appropriate for your install type:

    • Client installations:

      ORACLE_HOME/bifoundation/server/bin
      
    • All other installations:

      ORACLE_INSTANCE/bifoundation/OracleBIApplication/coreapplication/setup
      
  2. Double-click bi-init.cmd (or bi-init.bat for client installations) to display a command prompt that is initialized to your Oracle instance.

  3. At the command prompt, type biserverxmlgen with the desired options. You can also run biserverxmlgen with no arguments or parameters to see usage information.

To use biserverxmlgen to generate MDS XML output from an existing repository file, execute the following at the command prompt:

biserverxmlgen -M -R repository_pathname [-P password] -D output_directory [-8] [-N] [-Q|-S]

Where:

-M indicates that you want MDS XML output.

repository_pathname is the name and location of the repository file from which you want to generate MDS 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_directory is the name and location of the directory under which you want to generate your MDS XML output.

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.

Specify -N to generate output without upgrade ids (uids). These are the internal identifiers of objects. Use this if you want to create a new repository without the old upgrade ids.

You can use one of the two options -Q and -S to control the generation of security objects:

  • Use -Q to generate output without security objects

  • Use -S to generate output for only security objects

If you use both -Q and -S on the same call of biserverxmlgen, the second option on the call command takes precedence, and the first is ignored.

1.3 Executing MDS XML

You can use the biserverxmlexec command-line utility to execute MDS XML in offline mode to create or modify a repository file. This utility can generate an entire repository file (RPD) from a set of MDS XML documents, or it can modify an existing repository file by applying the changes specified in the MDS XML. The input MDS XML is validated against the MDS XML schema. Any objects that exist in both the RPD and the MDS XML documents are overwritten by the corresponding object definitions in the MDS XML. Note that the same object cannot be defined twice in the MDS XML documents.

Before running biserverxmlexec, you must first run bi-init to launch a command prompt or shell window that is initialized to your Oracle instance. This utility is called bi-init.sh on Linux and UNIX systems, bi-init.bat on client installations of the Administration Tool, and bi-init.cmd for all other Windows installation types.

For example, on Windows:

  1. In Windows Explorer, go to the location appropriate for your install type:

    • Client installations:

      ORACLE_HOME/bifoundation/server/bin
      
    • All other installations:

      ORACLE_INSTANCE/bifoundation/OracleBIApplication/coreapplication/setup
      
  2. Double-click bi-init.cmd (or bi-init.bat for client installations) to display a command prompt that is initialized to your Oracle instance.

  3. At the command prompt, type biserverxmlexec with the desired options. You can also run biserverxmlexec with no arguments or parameters to see usage information.

To use biserverxmlexec to execute MDS XML, execute the following at the command prompt:

biserverxmlexec -D MDS_XML_document_directory [-S MDS_XML_password] 
[-B base_repository_pathname] -O output_repository_pathname [-P rpd_password] [-M]
[-E] [-C]

Where:

MDS_XML_document_directory is the location of the input MDS XML documents.

MDS_XML_password is the password for the set of MDS XML documents. You only need to specify -S when the set of MDS XML documents has a different password than the password specified for -P. Note also that you can specify -C to avoid password checking for the MDS XML documents.

The MDS_XML_password argument is optional. If you do not provide an MDS XML password argument, and if the set of MDS XML documents has a different password than the password specified for -P, you are prompted to enter an MDS XML password when you run the command (unless you have specified -C). 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.

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

rpd_password is the password for the RPD file. 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. Note that you must specify an output repository regardless of whether you are generating a new RPD, or whether you are modifying an existing base repository. The changes that result from executing MDS XML on a base repository are contained in the specified output repository, not in the base repository.

Specify -M to specify that you want to execute MDS XML documents. If you specify -D, the -M argument is not needed. You only need to specify -M when you have a single MDS XML file that contains all the object definitions.

Specify -E to exit without creating the RPD output file if an expression parsing error occurs.

Specify -C to skip prompting for the input MDS XML password. When you use this option, all connection pool passwords are removed from the output RPD.

Example

The following example creates a new repository called rp1 based on the input MDS XML document directory:

biserverxmlexec -D C:\MDS_dir -O rp1.rpd
Give password: my_rpd_password

1.4 Generic MDS XML Elements and Attributes

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

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 nine common attributes defined under the object_t element. Table 1-1 lists these attributes.

Table 1-1 Common MDS XML Attributes in object_t

Attribute Name Description

name

The name of the object.

id

Not used for MDS XML.

mdsid

mdsid is a universally unique identifier, 37-characters long.

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, an additional common attribute is defined in ref_t. This attribute is used when one object references another object or set of objects. For example, business model objects reference the logical display folders contained in that business model, using the sub-element RefLogicalDisplayFolder.

All referenced sub-elements have the same common attribute refId shown in Table 1-2.

Table 1-2 Common MDS XML Attribute in ref_t

Attribute Name Description

refId

Consists of the mdsid of the referencing object and the mdsid of the referenced object, separated by "-".


1.4.1 About MDS XML Object Identifiers

Oracle BI Server MDS XML metadata objects have a single unique identifier:

  • mdsid. This identifier consists of 37 characters, and is unique across the entire repository. The mdsid is created by the Oracle BI Server for the lifetime of the object.

    For example: mdsid="m1d08ed10-0bf4-1000-806e-0a9716a80000".

1.5 Example: Analysis of an MDS XML Logical Table Element

This section illustrates the use of MDS XML identifiers and reference attributes for a Logical Table called F2 Coupon Usages.

The logical table F2 Coupon Usages has the following properties:

  • It contains four logical columns, including the column ORDER_ID

  • It has a logical key CUSTOMER_ID, that consists of the single logical column ORDER_ID

  • It is contained within the business model Fusion Order Demo

  • It has one logical table source COUPON_USAGES

The MDS XML elements to illustrate this example occur in three separate MDS XML files: a file that describes the logical table elements and two files that describe the associated business model and logical table source elements.

The focus of this example is the logical table file, especially the references in the file to related elements and attributes. The only details shown of the business model and logical table source files are those that illustrate relationships with the logical table.

As an overview, the following figure shows these three files highlighted within the general directory structure created when MDS XML is generated from an Oracle BI repository.

Figure 1-2 MDS XML Example Element Files

Description of Figure 1-2 follows
Description of "Figure 1-2 MDS XML Example Element Files"

The contents of the main Logical Table file

F2 Coupon Usages_80cbbde8-07f3-0000-714b-e31d00000000.xml

appear in this section, with the mdsid of the logical table highlighted (the italicized line numbers have been inserted for easy element tag identification in the subsequent sections of this topic).

 1 <?xml version="1.0" encoding="UTF-8" ?>
 2 <LogicalTable mdsid="m80cbbde8-07f3-0000-714b-e31d00000000" 
 3    name="F2 Coupon Usages" 
 4    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 5    xmlns="http://www.oracle.com/obis/repository/"
 6    x="133" y="378" 
 7    subjectAreaRef="/oracle/bi/server/base/BusinessModel
 8       /Fusion Order Demo_80cbbdd2-07d0-0000-714b-e31d00000000.xml#
 9       m80cbbdd2-07d0-0000-714b-e31d00000000">
10    <LogicalColumn mdsid="m80cbbefc-07d6-0000-714b-e31d00000000"
11       name="Applied Date" isWriteable="false">
12    </LogicalColumn>
13    <LogicalColumn mdsid="m80cbbeff-07d6-0000-714b-e31d00000000" 
14       name="# of Customers" isWriteable="false">
15    </LogicalColumn>
16    <LogicalColumn mdsid="m80cbbf00-07d6-0000-714b-e31d00000000" 
17       name="# of Coupons and Discounts" isWriteable="false">
18    </LogicalColumn>
19    <LogicalColumn mdsid="m80cbbf04-07d6-0000-714b-e31d00000000" 
20       name="Order ID" isWriteable="false">
21    </LogicalColumn>
22    <LogicalKey mdsid="m80cbbf39-07d8-0000-714b-e31d00000000" 
23       name="CUSTOMER_ID" isPrimary="true">
24       <RefColumns>
25          <RefLogicalColumn
26             refId="m80cbbf39-07d8-0000-714b-e31d00000000-
27                    m80cbbf04-07d6-0000-714b-e31d00000000"
28             logicalColumnRef="/oracle/bi/server/base/LogicalTable
29                /F2 Coupon Usages_80cbbde8-07f3-0000-714b-e31d00000000.xml#
30                m80cbbf04-07d6-0000-714b-e31d00000000" /> 
31       </RefColumns>
32    </LogicalKey>
33    <RefTableSources>
34       <RefLogicalTableSource
35          refId="m80cbbde8-07f3-0000-714b-e31d00000000-
36                 m80cbc055-07f5-0000-714b-e31d00000000"
37          logicalTableSourceRef=
38            "/oracle/bi/server/base/LogicalTableSource
39             /COUPON_USAGES_80cbc055-07f5-0000-714b-e31d00000000.xml#
40             m80cbc055-07f5-0000-714b-e31d00000000" /> 
41    </RefTableSources>
42 </LogicalTable>

Reference from Logical Table to Business Model

The subjectAreaRef attribute (lines 7 to 9) points to the file and mdsid that describe the related business model:

7 subjectAreaRef="/oracle/bi/server/base/BusinessModel
8                 /Fusion Order Demo_80cbbdd2-07d0-0000-714b-e31d00000000.xml#
9                                   m80cbbdd2-07d0-0000-714b-e31d00000000">

Note that the file name includes most of the business model mdsid.

The Business Model file (full contents not shown here) contains the BusinessModel tag, which includes the Business Model mdsid attribute:

<BusinessModel mdsid="m80cbbdd2-07d0-0000-714b-e31d00000000" 
               name="Fusion Order Demo" ..... 

Reference from Logical Key to Logical Column (in current Logical Table)

The logical key tag (lines 22 to 32) contains the mdsid of the logical key.

22 <LogicalKey mdsid="m80cbbf39-07d8-0000-714b-e31d00000000" 
23             name="CUSTOMER_ID" ... 

In general, a logical key can consist of several logical columns. In this case, the logical key, CUSTOMER_ID, consists of one logical column, Order ID.

The logical column of the logical key CUSTOMER_ID is referenced in the RefColumns tag (lines 24 to 31), and specifically the RefLogicalColumn sub-element.

24 <RefColumns>
25  <RefLogicalColumn
26   refId="m80cbbf39-07d8-0000-714b-e31d00000000-
27          m80cbbf04-07d6-0000-714b-e31d00000000"
28   logicalColumnRef="/oracle/bi/server/base/LogicalTable
29                     /F2 Coupon Usages_80cbbde8-07f3-0000-714b-e31d00000000.xml#
30                      m80cbbf04-07d6-0000-714b-e31d00000000" /> 
31 </RefColumns>

logicalColumnRef (lines 28 to 30) points to the current Logical Table file (lines 28 to 29) and the mdsid that describe the logical column within the logical table that makes up the logical key (line 30).

The logical column mdsid (line 30) references the mdsid of the LogicalColumn tag (lines 19 to 21), that appears just before the LogicalKey tag in the current Logical Table file:

19  <LogicalColumn mdsid="m80cbbf04-07d6-0000-714b-e31d00000000" 
20                 name="Order ID" ...

The refId value of the RefLogicalColumn sub-element of the logical table (lines 26 to 27):

26  refId="m80cbbf39-07d8-0000-714b-e31d00000000-
27         m80cbbf04-07d6-0000-714b-e31d00000000"

consists of the mdsid of the logical key itself (line 22 of the logical table file, shown in bold at the beginning of this topic) and the mdsid of the logical column to which it refers (line 19 of the logical table file, shown in bold in the main body of this topic), separated by "-".

Reference from Logical Table to Logical Table Source

In general, a logical table can refer to several logical table sources. In this case, the logical table F2 Coupon Usages refers to the single logical table source COUPON_USAGES.

The RefTableSources tag (lines 33 to 41) is a child element of the LogicalTable tag. The explicit reference to the logical table source appears within the RefLogicalTableSource sub-element.

33  <RefTableSources>
34    <RefLogicalTableSource
35     refId="m80cbbde8-07f3-0000-714b-e31d00000000-
36            m80cbc055-07f5-0000-714b-e31d00000000"
37     logicalTableSourceRef=
38           "/oracle/bi/server/base/LogicalTableSource
39            /COUPON_USAGES_80cbc055-07f5-0000-714b-e31d00000000.xml#
40                          m80cbc055-07f5-0000-714b-e31d00000000" /> 
41  </RefTableSources>

logicalTableSourceRef (lines 37 to 40) points to the file and the mdsid that describe the logical table source (note that the file name includes most of the logical table source mdsid).

The Logical Table Source file (full contents not shown here) contains the LogicalTableSource tag, which includes the mdsid of the logical table source:

<LogicalTableSource mdsid="m80cbc055-07f5-0000-714b-e31d00000000"
                    name="COUPON_USAGES" ...

The refId value of the RefLogicalTableSource sub-element of the logical table (lines 35 to 36):

35  refId="m80cbbde8-07f3-0000-714b-e31d00000000-
36         m80cbc055-07f5-0000-714b-e31d00000000"

consists of the mdsid of the logical table itself (shown in bold in line 2 of the logical table file listing, at the beginning of Section 1.5, "Example: Analysis of an MDS XML Logical Table Element") and the mdsid of the logical table source (shown in bold in the body of this topic), separated by "-".

1.6 Topics of Interest in Other Guides

Some topics that may be of interest to XML schema reference users are covered in other guides. Table 1-3 lists these topics, and indicates where to go for more information.

Table 1-3 Topics Covered in Other Guides

Topic Where to Go for More Information

Designing and building an Oracle BI repository using the Oracle BI Administration Tool

Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition

Using a source control management system for repository development

Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition

Starting and stopping Oracle Business Intelligence processes

Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition

Using the Oracle BI Server Web services

Oracle Fusion Middleware Integrator's Guide for Oracle Business Intelligence Enterprise Edition

Managing configuration settings that affect repository development in Fusion Middleware Control and NQSConfig.INI

Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition

Managing users, groups, and application roles

Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition

Moving from test to production environments

Oracle Fusion Middleware Administrator's Guide

Setting up DSNs for the Oracle BI Server

Oracle Fusion Middleware Integrator's Guide for Oracle Business Intelligence Enterprise Edition

Managing logging

Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition

General information about managing Oracle WebLogic Server

Oracle Fusion Middleware Administrator's Guide


1.7 System Requirements and Certification

Refer to the system requirements and certification documentation for information about hardware and software requirements, platforms, databases, and other information. Both of these documents are available on Oracle Technology Network (OTN).

The system requirements document covers information such as hardware and software requirements, minimum disk space and memory requirements, and required system libraries, packages, or patches:

http://www.oracle.com/technology/software/products/ias/files/fusion_requirements.htm

The certification document covers supported installation types, platforms, operating systems, databases, JDKs, and third-party products:

http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html