Moving Catalog Objects Between Environments

This chapter covers the following topics:

Overview
Preparing to Use the BI Publisher Catalog Utility
Exporting BI Publisher Reporting Objects
Importing BI Publisher Reporting Objects
Generating Translation Files and Checking for Translatability

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 when you need 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:

Export BI Publisher reports from the catalog
Import BI Publisher reports into the catalog
Extract translatable strings and generate a translation file (XLIFF)
Generate a security.xml file that contains the reporting object-level permission settings

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 following diagram:

the picture is described in the document text

Other Options for Moving Catalog Objects

If you need 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 Downloading and Uploading Catalog Objects in the Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Publisher.

Caution: 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 it is possible to restore it by deleting the corrupt file and restarting BI Publisher.

What Files Are Moved

The following table lists the files that are included when you export an object from the catalog:


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 - 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 will include 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 - 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 - 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 - 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

Preparing to Use the BI Publisher Catalog Utility

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

ORACLE_HOME/clients/bipublisher

Configuring the Environment

In the environments in which you will be running the catalog utility, perform the following:

Set the following environment variables:


Variable	Value
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

Edit xmlp-client-config.xml. This configuration file is located under the BIPCatalogUtil/config directory.

Specify the BI Publisher instance URL ("bipurl") and the username and password of the BI Publisher instance from which you will be exporting or to which you will be importing.
```
<?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 wish to store this information in the configuration file, 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.

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:

-export - use this command to export a single report object
-exportfolder - use this command to export a folder and its contents

Following is a list of the supported parameters for the -export and -exportfolder 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 will be saved to {basedir}/datamodels; reports will be saved to {basedir}/reports; style and subtemplates will be saved to {basedir}/templates.
extract	-export -exportfolder	true/false	The default is ‘false’, which means that the utility will export 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’, the utility will export 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' all reporting objects in all subfolders will be downloaded. If you specify 'false', subfolder contents will not be downloaded.
overwrite	-export -exportfolder	true/false	Specify 'true' to overwrite existing objects in the target area.

Example Export Command Lines

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

Export 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

Export 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 will be overwritten.

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

Export 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

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. Following is the list of the supported parameters for the 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, the reporting object will be 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 would import the reporting object to where it was originally exported from. When you export the reporting object with the utility it will generate a metafile (.meta) that contains the catalog path information. The utility will use this information to import the reporting object to the original location. However, if you want to import the objects into a different location, you can override the original catalog path location by specifying the catalogpath parameter.

Example Import Command Lines

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

Import a Report to an Original Location

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

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

Import 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

Import 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

Import 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

Generating Translation Files and Checking for Translatability

The catalog utility supports the -xliff command to generate a translatable XLIFF file for a specific file.

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 will include all user-entered strings from the report definition interface, for example: description, layout names, parameter names.


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.

Generate 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/

Generate Translation File for 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/