Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Business Intelligence Publisher
11g Release 1 (11.1.1)

Part Number E22255-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

15 Moving Catalog Objects Between Environments

This chapter describes how to move objects between test, production, and development environments using the BI Publisher catalog utility.

It covers the following topics:

15.1 Overview

The BI Publisher catalog utility enables administrators and report developers to export the reporting object-related files from the catalog where all BI Publisher reports are stored, and to import them to a different catalog. Use this tool to manage BI Publisher reports using a third party tool as a source control or to move a specific set of reports from a development environment to a quality assurance or production environment. The catalog utility can also be used to help manage translations of reporting objects.

Use the BI Publisher catalog utility to perform the following tasks:

15.1.1 When to Use the Catalog Utility

Use the catalog utility to move BI Publisher report artifacts from one environment to another. For example, use the catalog utility to move reports from a development environment to a quality assurance environment. This process is illustrated in the Figure 15-1.

Figure 15-1 Using the Catalog Utility

Surrounding text describes Figure 15-1 .

15.1.2 Other Options for Moving Catalog Objects

To download or upload a small number of objects, the download feature of the BI Publisher catalog enables you to bundle and download multicomponent objects (such as reports) in an archive file. You can then use the upload feature to unarchive the data to another location in the catalog. For more information about this feature, see the section "Downloading and Uploading Catalog Objects" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

Note:

Do not manually edit the BI Publisher files in the file system. BI Publisher uses metadata files to maintain information about catalog objects. Manually editing objects in the file system can result in the corruption of the metadata files. If the metadata file becomes corrupt, then you can restore it by deleting the corrupt file and restarting BI Publisher.

15.1.3 What Files Are Moved

Table 15-1 lists the files that are included when you export an object from the catalog.

Table 15-1 Files Included In Catalog Export

Object Files

Report Example: Balance+Letter.xdo

  • _report.xdo — The report definition file

  • xdo.cfg  — The configuration file that contains the report property settings

  • ~metadata.meta — The metadata file that contains the catalog path information. This file is used by the utility to import objects back to their original locations.

  • security.xml file — Specifies the object level permissions defined for the report

  • template files — All template files loaded to the report definition. The file names include the language suffix, for example: My_RTF_template_en_us.rtf, My_BIP_layout_en_us.xpt

  • translation files — All translation files (.xlf), for example: My_RTF_template_jp_jp.xlf

Data Model Example: myDataModel.xdm

  • _datamodel.xdm — The report definition file

  • ~metadata.meta — The metadata file that contains the catalog path information. This file is used by the utility to import objects back to their original locations.

  • security.xml file — Specifies the object level permissions defined for the data model

Subtemplate Example: mysubtempate.xsb

  • _template_en_us.rtf — The subtemplate file with locale designation

  • ~metadata.meta — The metadata file that contains the catalog path information. This file is used by the utility to import objects back to their original locations.

  • security.xml file — Specifies the object level permissions defined for the subtemplate

  • translation files — Any translations, when present; for example: _template_jp_jp.rtf

Style Template Example: myStyleTemplate.xss

  • _template_en_us.rtf — The style template file with locale designation

  • ~metadata.meta — The metadata file that contains the catalog path information. This file is used by the utility to import objects back to their original locations.

  • security.xml file — Specifies the object level permissions defined for the style template

  • translation files — Any translations, when present; for example: _template_jp_jp.rtf


15.2 Preparing to Use the BI Publisher Catalog Utility

The BI Publisher catalog utility is installed in the following location:

ORACLE_HOME/clients/bipublisher

15.2.1 Configuring the Environment

You must configure each environment in which you run the catalog utility.

To configure the environment for the catalog utility:

  1. Set the environment variables to the values in the following list:

    • path = ($HOME/BIPCatalogUtil/bin $path)

    • BIP_LIB_DIR = $HOME/BIPCatalogUtil/lib

    • BIP_CLIENT_CONFIG = $HOME/BIPCatalogUtil/config

    • JAVA_HOME = $HOME/java/jdk1.6.0_18

    The following example shows setting the environment variables for C-shell:

    % set path = ($HOME/BIPCatalogUtil/bin $path)
    % setenv BIP_LIB_DIR $HOME/BIPCatalogUtil/lib
    % setenv BIP_CLIENT_CONFIG $HOME/BIPCatalogUtil/config
    % setenv JAVA_HOME $HOME/java/jdk1.6.0_18
    
  2. Edit xmlp-client-config.xml. This configuration file is located under the BIPCatalogUtil/config directory.

    Specify the BI Publisher instance URL ("bipurl") and the user name and password of the BI Publisher instance from which you must export or to which you must import.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
    <properties>
            <comment>BIP Server Information</comment>
        <entry key="bipurl">http://sta00XXX.us.oracle.com:14001/xmlpserver/</entry>
            <entry key="username">OPERATIONS</entry>
        <entry key="password">welcome</entry>
    </properties>
    

    If you do not want to store this information in the configuration file, then at the time of import/export you can also set the bipurl, username, and password as parameters in the command line to overwrite values defined in xmlp-client-config.xml.

15.3 Exporting BI Publisher Reporting Objects

Use the export command to export either a single reporting object or a set of BI Publisher reporting objects under a specified folder. There are two export commands:

Table 15-2 describes the supported parameters for the -export and -exportfolder commands.

Table 15-2 Parameters for Export Commands

Parameter Used With Sample Description

catalogpath

-export -exportfolder

/Samples/Financials/Balance+Letter.xdo

The path to the object in the catalog. If there are spaces in any of the names, use the '+' sign to substitute.

target

-export

/tmp/Financials/BalanceLetter

The destination directory in which to place the extracted reporting objects.

basedir

-exportfolder

/home/bipub/samples

The base directory into which to place subfolders of extracted reporting objects. When present, data models are saved to {basedir}/datamodels; reports are saved to {basedir}/reports; style and subtemplates are saved to {basedir}/templates.

extract

-export -exportfolder

true/false

The default is false, which means that the utility exports the reporting object in a zip format that contains all the related files such as '.xdo', '.rtf', '.cfg', and so on. If the value is set to 'true', then the utility exports the reporting object-related files under the specified target folder.

subfolders

-exportfolder

true/false

When you specify a folder as the "catalogpath" parameter you can use this "subfolders"' parameter to control whether to download all subfolder content. If you specify true, then all reporting objects in all subfolders are downloaded. If you specify false, then subfolder contents are not downloaded.

overwrite

-export -exportfolder

true/false

Specify true to overwrite existing objects in the target area.


15.3.1 Example Export Command Lines

The following examples show how to use the utility to export the reporting objects:

15.3.1.1 Exporting a Single Report in Archive Format

The following example exports the reporting object in a zip format. The zip file contains all the reporting object related files such as .xdo, .rtf, .cfg, and so on. To extract a report in archived format use the ".xdoz" extension for the target. To extract a data model, use the ".xdmz" extension.

$ BIPCatalogUtil.sh -export catalogpath=/Samples/Financials/Balance+Letter.xdo target=/home/bipub/reports/BalanceLetter.xdoz extract=false

15.3.1.2 Exporting a Single Report with Files Extracted

The following example extracts the reporting object-related files to a directory named "/home/bipub/reports/BalanceLetter". Existing files are overwritten.

$ BIPCatalogUtil.sh -export catalogpath=/Samples/Financials/Balance+Letter.xdo target=/home/bipub/reports/BalanceLetter extract=true overwrite=true

15.3.1.3 Exporting a Set of Reports to a Specified Folder

The following example extracts all the reporting objects under the "/Samples" folder and its subfolders in the catalog. Data models are saved under {basedir}/datamodels. Reports are saved into {basedir}/reports. Style and subtemplates are saved into {basedir}/templates.

$ BIPCatalogUtil.sh -exportfolder catalogpath=/Samples basedir=/home/bipub/samples subfolders=true extract=true overwrite=true

15.4 Importing BI Publisher Reporting Objects

Use the import command to import either a single BI Publisher reporting object or a set of BI Publisher reporting objects under a specified folder. Table 15-3 describes the supported parameters for the import command.

Table 15-3 Parameters for Import Command

Parameter Sample Description

catalogpath

/Samples/Financials/Balance+Letter.xdo

Specify the catalog path to where you want to import the reporting object only when you want to override the default information. If you do not specify this parameter, then the reporting object is imported to the same location where it was originally exported from.

source

/tmp/Financials/BalanceLetter

The directory where the reporting object is located. Use this parameter when you are importing a single report.

basedir

/home/bipub/samples

The directory that contains multiple reports or data models to be imported. Specify this parameter when importing a set of reports or data models.

overwrite

true/false

Specify 'true' to overwrite existing objects in the target area.


Typically, you import the reporting object to where it was originally exported from. When you export the reporting object with the utility, it generates a metafile (.meta) that contains the catalog path information. The utility uses this information to import the reporting object to the original location. To import the objects into a different location, you can override the original catalog path location by specifying the catalogpath parameter.

15.4.1 Example Import Command Lines

The following examples show how to use the utility to import reports:

15.4.1.1 Importing a Report to an Original Location

The following example imports a report to a catalog path saved in its metafile (.meta). Existing reports are overwritten.

$ BIPCatalogUtil.sh -import source=/tmp/Financials/BalanceLetter overwrite=true

15.4.1.2 Importing a Report to a New Location

The following example imports a report into a new location in the catalog.

$ BIPCatalogUtil.sh -import source=/home/bipub/reports/BalanceLetter catalogpath=/Production/Financials/Balance+Letter+Report.xdo 

15.4.1.3 Importing a Zipped Report

The following example imports a zipped reporting object to an original location in the catalog.

$ BIPCatalogUtil.sh -import source=/home/bipub/reports/BalanceLetter.xdoz overwrite=true

15.4.1.4 Importing a set of BI Publisher Reporting Objects Under a Specified Folder

The following example imports all the reports under the base directory (basedir) into the original locations in the catalog.

$ BIPCatalogUtil.sh -import basedir=/Users/bipub subfolders=true overwrite=true

15.5 Generating Translation Files and Checking for Translatability

The catalog utility supports the -xliff command to generate a translatable XLIFF file for a specific file. Table 15-4 describes the supported parameters for generating XLIFF files.

The source file can be the report definition (.xdo) file, an RTF template file (.rtf), or a BI Publisher layout template file (.xpt). When the source is the .xdo file, the generated XLIFF file includes all user-entered strings from the report definition interface, for example: description, layout names, parameter names.

Table 15-4 Parameters for Generating XLIFF Files

Parameter Sample Description

source

/Samples/Financials/Balance+Letter.xdo

The path to the report or template file (RTF or XPT) for which to generate the XLIFF file.

target

/home/bipub/reports/Balance+Letter/Balance+Letter.xlf

The location to save the generated .xlf document.

basedir

/home/bipub/reports/Balance+Letter/

The directory to place the generated .xlf files into.


The following examples show how to generate translation files:

15.5.1 Generating a Translation File for a Report Definition File (.xdo)

The following example generates an XLIFF file for a single report definition file:

$ BIPCatalogUtil.sh -xliff source=/home/bipub/reports/Balance+Letter/Balance+Letter.xdo target=/home/bipub/reports/Balance+Letter/Balance+Letter.xlf

To save the XLIFF to a base directory:

$ BIPCatalogUtil.sh -xliff source=/home/bipub/reports/Balance/Balance+Letter.xdo basedir=/home/bipub/reports/Balance+Letter/

15.5.2 Generating a Translation File for an RTF Template

The following example generates an XLIFF file for a single RTF template file:

$ BIPCatalogUtil.sh -xliff source=/home/bipub/reports/Balance+Letter/Balance+Letter+Template.rtf target=/home/bipub/reports/Balance+Letter/Balance+Letter+Template.xlf

To save the XLIFF to a base directory:

$ BIPCatalogUtil.sh -xliff source=/home/bipub/reports/Balance/Balance+Letter+Template.rtf basedir=/home/bipub/reports/Balance+Letter/