5 Developing BI Publisher Reports

5.1 Introduction to Oracle BI Publisher

As a plug-in developer, you are responsible for the following steps:

1. Developing the report using data models and report templates.

   For more information on developing a report, see Developing a Report

2. Staging and deploying reports

   For more information on staging and deploying reports, see Using the Enterprise Manager EDK for Staging and Deploying BI Publisher Reports

5.2 Training and Resources

Before you start to develop a BI Publisher report, you should take advantage of the training and reference resources available from Oracle:

• Getting Started with Oracle BI Publisher 11g

  http://st-curriculum.oracle.com/obe/fmw/bi/bip/bip11g/gettingstarted/gettingstarted.htm
  

• Oracle BI Publisher on Oracle Technology Network (OTN)

  http://www.oracle.com/technology/products/xml-publisher/index.html
  

• Oracle By Example Tutorial

  http://www.oracle.com/technology/obe/obe_bi/bipub/index.html
  

• Oracle BI Publisher Blog

  http://blogs.oracle.com/xmlpublisher/
  

• Oracle BI Publishing Consulting Blog

  http://bipconsulting.blogspot.com/
  

5.3 About the Report Data Source

The EMREPOS data source is available from BI Publisher server configured for use with Enterprise Manager reports. The EMREPOS data source connects to the MGMT_VIEW account in the Management Repository and establishes the proper security context (VPD) for the Enterprise Manager user logged on to BI Publisher.

As a security measure, BI Publisher reports that use the EMREPOS data source have read-only access to the public MGMT$VIEW and GC$ views, and not to the underlying Enterprise Manager tables; this model also supports sharing of report queries with Enterprise Manager users who might want to use the Enterprise Manager-provided reports as a basis for their own reports.

5.4 Developing a Report

By default the reports and data models in the Enterprise Manager Cloud Control folder are read-only. Develop your own reports in your local folders and then have a BI Publisher System Administrator put the finished reports in a shared folder, outside of the Enterprise Manager Cloud Control folder.

To develop a BI Publisher report, complete the following:

1. Develop your data model, based on SQL queries against the EM repository.

   To develop a BI Publisher report, the following components are required:

   • Data Model

   • Report Template

   • Sub Template

   First, you develop your data model, based on SQL queries against the EM repository. You then design the layout of your report (the template) using MS Word on Windows. Your template refers to one of the two common Oracle subtemplates, namely, Portrait or Landscape.

   You can use the following reports as examples of this:

   Enterprise Manager Cloud Control -> EM Sample Reports -> Targets of Specified Type
   
   Enterprise Manager Cloud Control -> EM Datamodels -> Targets of Specified Type
   

2. Develop and test the SQL queries for report data and input parameters.

3. Create a data model in BI Publisher for your data queries.

4. Create parameters in BI Publisher for your report parameters.

5. Create a report layout for your report.

   Start with the sample landscape or portrait layout RTF file provided with the Extensibility Development Kit (EDK).

6. Create and test your report.

   Download the report and data model using the BI Publisher UI. The download option is located on the 'more...' link under the name of each report/data model.

7. Export the report (.xdoz) and data models (.xdmz) from BI Publisher into local files.

5.5 Using the Enterprise Manager EDK for Staging and Deploying BI Publisher Reports

BI Publisher reports are deployed from a plug-in (that is, ADDON or MP) to a BI Publisher web application in a series of steps:

1. Create a metadata file that adheres to the following schema:

   emcore/source/oracle/sysman/emSDK/ip/bipublisherreport/BIPublisherReport.xsd
   

   The following is an example of a Reports metadata file:

   <?xml version = '1.0' encoding = 'UTF-8' ?>
   <BIPublisherReports
           xmlns="http://www.example.com/DataCenter/BIPublisherReport">
           <ReportFile relativePath="emreports" fileName="tvmlrb104a.jar"/>
           <ReportFile relativePath="emreports" fileName="tvmlrb104b.jar"/>
   </BIPublisherReports>
   

2. Stage the BI Publisher Reports, which are ZIP files with the extension .xdoz (report definition) or .xdmz (report data model, that is, SQL) into one or more JAR files. These files are referenced in the previous metadata file.

   The $ORACLE_HOME/sysman/jlib/emreports.jar file provides an example.

   $ unzip -l emreports.jar
   Archive:  emreports.jar
   Label: EMGC_MAIN_LINUX_110220
     Length      Date    Time    Name
   ---------  ---------- -----   ----
           0  02-20-2011 23:08   META-INF/
          71  02-20-2011 23:08   META-INF/MANIFEST.MF
           0  02-20-2011 23:08   bipublisherreports/
           0  02-20-2011 23:08   bipublisherreports/EM Datamodels/
        4776  02-20-2011 23:08   bipublisherreports/EM Datamodels/Usage Trend Report.xdmz
        4854  02-20-2011 23:08   bipublisherreports/EM Datamodels/Usage Summary Report.xdmz
        5008  02-20-2011 23:08   bipublisherreports/EM Datamodels/Charge Trend Report.xdmz
        7344  02-20-2011 23:08   bipublisherreports/EM Datamodels/Consolidation Reports.xdmz
        5043  02-20-2011 23:08   bipublisherreports/EM Datamodels/Charge Summary Report.xdmz
           0  02-20-2011 23:08   bipublisherreports/Chargeback/
       52291  02-20-2011 23:08   bipublisherreports/Chargeback/Charge Trend Report.xdoz
       66994  02-20-2011 23:08   bipublisherreports/Chargeback/Charge Summary Report.xdoz
       26505  02-20-2011 23:08   bipublisherreports/Chargeback/Usage Trend Report.xdoz
      112150  02-20-2011 23:08   bipublisherreports/Chargeback/Usage Summary Report.xdoz
           0  02-20-2011 23:08   bipublisherreports/Consolidation Planner/
       50114  02-20-2011 23:08   bipublisherreports/Consolidation Planner/Consolidation Reports.xdoz
   ---------                     -------
      335150                     16 files
   

3. Create your plug-in JAR files.

   The first directory in each JAR file must be bipublisherreports. All the data models for the reports must be in the same subdirectory, EM_Datamodels, just under the bipublisherreports directory. For example:

   1. The plug-in, which contains all the metadata files and BI Publisher report JAR files, is installed in an Oracle home directory (for Addons) or installed dynamically (for Metadata Plug-ins) using the plug-in environment.

   2. The BI Publisher report JAR files are placed in a subdirectory of the metadata/bipublisherreport directory and referenced in the metadata file (emreports).

   3. The BI Publisher reports for both platform and plug-ins are deployed to a BI Publisher web application (either at plug-in installation time or sometime later when BI Publisher is installed).

      Plug-in reports are deployed when BI Publisher is integrated with Enterprise Manager using the configureBIP script or sometime later using one of the following EMCLI verbs:

      • * emcli setup_bipublisher (see help for usage details)

      • * emcli deploy_bipublisher_reports[-force]

        This last verb deploys the EM System Reports (and optionally Extensibility Development Kit plug-in loaded reports) to a previously setup EM to BI Publisher relationship (using setup_bipublisher). It can also be used to upload a reports JAR file (located on the OMS filesystem). The operation will not overwrite existing BI Publisher Reports in the EM Reports folder unless -force is used in the command.

        The following options are available:

        Option	Description
        [-pluginid]	In addition to EM system reports, you can use this option to deploy any subsequently loaded plug-in based BI Publisher reports.
        [-pluginversion]	Limit the plug-ins to a specific version
        [-reportsjarfile]	Deploy a single EM Reports JAR file that contains one or more BI Publisher Reports. This JAR file is located relative to the OMS's $ORACLE_HOME

        
        

        For example, the syntax for the emct plug-in would be:

        emcli deploy_bipublisher_reports -pluginid=oracle.sysman.emct -pluginversion=12.1.0.0.0
        

        Note:

        Using overlapping folders from the different JAR files and PLATFORM JAR files causes reports from the different JAR files to be placed in the same BI Publisher folder. If the same report name is referenced in multiple JAR files, there is no way of knowing which one will get deployed last, so this is not supported.