The catalog utility enables administrators and report developers to export the reporting object-related files from the catalog where all the pixel-perfect reports are stored, and to import them to a different catalog.
Use this tool to manage pixel-perfect 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. You must first run the GenerateBIPUtility script to generate the BIPCatalogUtil utility. See Generating the Utilities.
Use the catalog utility to perform the following tasks:
Export pixel–perfect reports from the catalog
Import pixel–perfect 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
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 below.
To download or upload a small number of objects, the download feature of the 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.
See Downloading and Uploading Catalog Objects in User's Guide for Oracle Business Intelligence Publisher.
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.
Styles and skins are organized into folders that contain Cascading Style Sheets (CSS) and images.
Object | Files |
---|---|
Report Example: Balance+Letter.xdo |
|
Data Model Example: myDataModel.xdm |
|
Subtemplate Example: mysubtempate.xsb |
|
Style Template Example: myStyleTemplate.xss |
|
A pixel-perfect report references the following components using the physical path to the component in the catalog: data models, subtemplates, and style templates.
When you move a report between environments the report maintains the physical mappings to the referenced components. Therefore if you move a data model into a different folder location under Shared Folders in the new environment, the report cannot find the data model and the report does not run. In the case of style templates or subtemplates, the report may run, but the referenced component is not applied.
For example, assume in your test environment Report A references Data Model B that is located in Shared Folders/Test/Data Models. When you move this report and its data model to the production environment you place Data Model B under the different path Shared Folders/Data Models. When you run the report in the new environment it still expects the data model to be located under Shared Folders/Test/Data Models. The report cannot find the data model and does not run.
You can correct the mapping in the new environment by opening the report in the report editor, selecting the data model in its new location, and saving the report.
To avoid manual steps, Oracle recommends that you maintain the same folder names and structure in the environments across which you intend to move reports.
The catalog utility is installed in the following location:
ORACLE_HOME/clients/bipublisher
Use the export command to export either a single reporting object or a set of 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.
The table below describes 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 as a 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', and '.cfg'. Use the default option of exporting the reporting object to a zip format to handle the international characters. If you set the value 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. |
Refer to the examples below on how to use the utility to export the reporting objects.
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
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
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
Use the import command to import either a single reporting object or a set of reporting objects under a specified folder.
The table below describes 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, 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.
Refer to the following examples on how to use the utility to import reports.
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
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
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
The catalog utility supports the -xliff command to generate a translatable XLIFF file for a specific file.
The table below 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.
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:
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/
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/