Steps to Migrate BI Publisher Reports to Production

Steps to Migrate BI Publisher Reports to Production

How to migrate all the reports developed at a development instance to a testing or production instance with BI Publisher Server?

This is the very typical thing you as an administrator or reports developer would concern about. The good news is, migrating BI Publisher reports from one instance to another is pretty simple. All the reports are stored in a BI Publisher repository, which is typically on a file system or inside the Oracle XML database. So, all you need to do is to copy the BI Publisher repository from the source system

paste it to the target system. Here is a diagram that shows the migration.

Of course, you need to have the BI Publisher server installed and up and running at the target system before the migration. Either if your repository is on the file system or XML DB, this process would be pretty much the same. I’ll talk about the process assuming that the repository is on the file system in this post.

What is BI Publisher Repository?

So what is really the BI Publisher repository? It stores the following types of content and information.

    • Reports

    • Server Configuration

    • Translation

BI Publisher Repository Screenshot

It not only stores the reports but also contains all the configuration-related information. Let’s take a look at the detail for each. 

1. Reports

Under the ‘Reports’ folder in the repository, all the reports are organized in a folder-based structure, which is in the same way that you see in the BI Publisher Enterprise server’s reports list UI page. Each report has its own folder, which contains one report definition file (.xdo) and reports templates such as .rtf or .pdf.

1.1. Reports Definition

All the information for the BI Publisher reports are stored in the reports definition files which have a file extension as ‘.xdo’ It stores the information like sql query, report name, parameter name, list of values, template name, reports translation, bursting setting, report property, etc.

1.2. Reports Template

When you work on reports development most of the work is done within the report layout templates such as RTF Templates, PDF Templates, to design the layout and formatting of the report. Once you complete the development you upload them to the BI Publisher Enterprise Server and register them as layout templates for each report. These uploaded report templates are also stored in the BI Publisher repository and reside along with the reports definition file (.xdo) in the same report folder.

2. Enterprise Server Configuration

All the BI Publisher server configuration-related information is also stored in the BI Publisher repository. The configuration information includes the following.

    • Server Configuration

    • Security

    • Scheduler

    • Delivery

    • Data Source

This information is stored under the Admin folder within the repository.

3. Translation

There are two types of translation. One is a translation for the BI Publisher Server product UI. BI Publisher Server supports 28 languages translations (includes English) for its UI. All the translated strings are stored in a set of XLIFF files and each language has its own XLIFF file to store the translation. These translations are located under Admin/Translation.

And another is a translation for the reports. If you are French and open a report you want to see all the text are written in French. If you are a German you expect the same way. BI Publisher separates the translation from the report so you don’t need to create multiple reports for each language. Instead, you can just have one report and multiple translation XML files (XLIFF format), which contains only the translatable strings. These translations are located along with each report.

Now you get an idea of the BI Publisher Repository. Let’s start the migration.

 

Migration Process Overview

Before you start the migration, again, ensure the BI Publisher Server exists at a target instance! The migration process has two parts.

    1. Migrate BI Publisher repository

    2. Perform Post-Migration Configuration

1 Migrate BI Publisher Repository

First, we need to obtain the repository from the source instance. Then locate it to the target BI Publisher repository.

1.1 Obtain BI Publisher Repository from a Source Instance

The screen below shows the root directory of the BI Publisher repository

    1. Identify the BI Publisher Repository at the source instance

You can find this information in a BI Publisher’s system configuration file, which can be found at %J2EE_HOME%/applications/xmlpserver/xmlpserver/WEB-INF/xmlp-server-config.xml (e.g. C:\OracleBI\oc4j_bi\j2ee\home\applications\xmlpserver\xmlpserver\WEB-INF)

<?xml version="1.0" encoding="UTF-8"?>

<xmlpConfig xmlns="http://xmlns.oracle.com/oxp/xmlp">

<resource>

<file path="C:\OracleBI\xmlp\XMLP"/>

</resource>

</xmlpConfig>

    0. Go to the BI Publisher Repository folder

e.g. C:\OracleBI\xmlp\XMLP

    1. Copy all the folders except ‘DemoFiles’ under the above folder. (If you want to migrate a set of demo XML data files you can copy the ‘DemoFiles’ folder as well.

    2. Save the folders onto your local machine or check them into your source control system

1.2 Locate BI Publisher Repository Content to a Target Instance

    1. log in to the target instance machine

    2. Go to the BI Publisher Repository directory.

    3. Copy the source repository folders, which are the ones you have copied at the above steps, to this folder.

1.3 Validate the Repository Migration

    1. Restart your target J2EE server, such as the Oracle OC4J server.

    2. log in to the Target BI Publisher Enterprise Server

Once you have logged in, you should see all the directories and reports migrated from the source instance under the Reports tab in the new target BI Publisher Enterprise Server.

Post-Migration Task at Target Instance

After the BI Publisher Repository has been migrated successfully you want to perform a post-migration task to review target-specific information. Often that the development application instance doesn’t share the same information such as data source, delivery system, scheduling information, etc with the target instance.

For example, when you have a project where you develop financial reports out of a financial database, usually you would have one financial database for development, one for testing, and one for Production. And you would expect that each of the BI Publisher Enterprise Server instances would talk to each financial database but not share the same database among multiple BI Publisher servers. This is just an example for a data source but it can be applied to other settings such as follows.

    • Data Source

    • Security

    • Scheduler

    • Delivery

When you have completed the migration process all the above settings are just copies from the source system so you want to review the settings and update them appropriately so that they can be specific to a target system.

When you do this review and need to update any of the information, it is strongly recommended that you do it through the BI Publisher Enterprise Server Admin UI, not through the manual file modification. Just to make sure you don’t accidentally break the system.