Oracle Application Express
Return to Oracle APEX Home
PDF Printing in Application Express
  1. Introduction and Architecture
  2. Configuration Options
    2.1  Standard
    2.2  Advanced
    2.3  Advantages of using BI Publisher within Application Express
  3. Installing and Configuring Oracle BI Publisher on Windows
    3.1  Prerequisites
    3.2  Installing BI Publisher
    3.3  Configuring Application Express to use BI Publisher
  4. Installing and Configuring Oracle BI Publisher on Linux
    4.1  Prerequisites
    4.2  Installing BI Publisher
    4.3  Configuring Application Express to use BI Publisher
  5. Installing and Configuring Apache FOP
    5.1  Prerequisites
    5.2  Instructions
  6. Configuring Other XSL-FO Processing Engines
1. Introduction and Architecture Application Express 3.0 introduced the ability to export a report region to PDF - essentially, printing a report. This is defined declaratively and is available for all report regions. Application Express users can now view and print reports with page headings that repeat on each page and content that properly conforms to various page sizes. To accomplish this, report data is transformed to PDF format using an externally defined report server. Further printing enhancements have been incorporated into Oracle Application Express 3.1 within Region Print Attributes and Report Queries. The diagram below illustrates the Application Express PDF printing architecture:

Application Express PDF Printing Architecture

When the end user of the application clicks on a print link, the request is sent to the Application Express engine (which is part of the Oracle database). The Oracle APEX engine then generates the corresponding report data in XML format and the report template in XSL-FO or RTF format. The external reporting engine then transforms the data and the template into a PDF which is displayed to the end user using the convert servlet that ships with BI Publisher 10.1.3.2 (formerly known as Oracle XML Publisher). All of this architectural complexity is transparent to the end users and developers. End users just click on print links, and developers just declaratively set regions to support PDF printing.

 

Back to top

2. Configuration Options Your report server can be Oracle BI Publisher, OC4J with Apache FOP or another standard XSL-FO processing engine. If you choose BI Publisher as your report server, you will enjoy a higher level of functionality. To accommodate the difference in functionality, Oracle Application Express provides two levels of functionality - Standard and Advanced. With standard, you are limited to XSL-FO based report templates.
2.1 Standard

Standard configuration may be implemented with Apache FOP or another standard XSL-FO processing engine. Beginning with Application Express 3.0.1, a supported configuration of Apache FOP in conjunction with Oracle Containers for J2EE (10.1.3.2 or above) is included. This provides declarative formatting of report regions and report queries with basic control over page attributes. These attributes include orientation, size, column heading formats, page header, and page footer. The following screen shots illustrate standard configuration:

Report Region with Print Link PDF Output of Standard Report PDF Output using Background Colors


2.2 Advanced

Advanced configuration requires a valid license for Oracle BI Publisher. With advanced configuration, you have all the capabilities of standard configuration plus the ability to define RTF-based report layouts developed using the BI Publisher Word Template Plug-In. This provides easy graphical control over every aspect of your report. You can add logos to your pages, add complex control breaks, and have full pagination control. You can even embed charts and create reports that look exactly like standard government forms. The following screen shots illustrate advanced configuration:

Grant Application Master Detail with Breaks Multiple Charts and Reports


There is also a How-To for Advanced PDF Reporting: How-To Create a Master-Detail PDF Report.

2.3 Advantages of using BI Publisher within Application Express

Using BI Publisher as your Application Express print server results in more robust and professional applications.

  • Seamless: Print capabilities are fully integrated into Application Express.
  • Multiple Output Formats: Can generate Word, Excel, and HTML output in addition to PDF.
  • Robust Report Layout: Developers can use RTF based templates providing significantly greater control over control breaks, headers, footers, and provide the ability to embed charts.
  • Support for non-western European fonts: Superior localization capabilities, including full support for CJK, BiDi, Unicode, and MLS.
  • Single file Export/Import: RTF based report layouts are part of your application definition so they are exported and imported along with the application.
  • Supported by Oracle: With BI Publisher, you are using a supported Oracle product.
In addition to the advantages of using BI Publisher within Application Express, BI Publisher can benefit your organization in other ways.
  • Scheduling & Delivery
  • Create Reports based on Multiple SQL Queries
  • Heterogeneous Database Support
  • Bursting
  • Report Caching
  • High Performance

Back to top

3. Installing and Configuring Oracle BI Publisher on Windows
3.1 Prerequisites

To use Oracle BI Publisher as your report server, you need to install Oracle Business Intelligence Publisher, v. 10.1.3.2.1 or above. This can be downloaded at the link below under the OTN Developer License (... limited license to use the programs only for the purpose of developing a single prototype of your application, and not for any other purpose ...).

       Oracle Business Intelligence Publisher Downloads, select the latest version of BI Publisher.

You can also download the Desktop software at the same time. This will allow you to create RTF templates to use in your reports. More information about Oracle BI Publisher can be found on their OTN site.

Please note:
1) The minimum required version of BI Publisher, that supports integration with Oracle Application Express, is version 10.1.3.2. XML Publisher was renamed to BI Publisher with the current 10.1.3.2 release. XML Publisher 5.6.2 does not support integration with Oracle Application Express, it cannot be used as the PDF rendering engine.

2) If you are experiencing the following error when trying to load an XML sample file when building a template, "Compile error in hidden module: Module_starter", it was caused by a Windows security patch. The workaround is:

  1. Go to the Start Menu:
       All Programs -> Oracle BI Publisher Desktop -> Template Builder for Word Language
  2. Select your language
  3. Click OK
Now you should be able to use the plug-in as normal.

3.2 Installing BI Publisher

 

  1. Unzip bipublisher_windows_x86_101321_disk1.zip into a new directory ( the_dir). It is important that the directory path not contain any white space, e.g. don't use 'C:\...\My Documents\BI Publisher'.
  2. Navigate to the_dir\Windows\Disk1\install
  3. Double-click setup.exe
    This will take you to the Oracle Installer
  4. Follow the on screen instructions making the following selections
    • For Destination, enter BIHOME
    • For Type, select Basic
      This installs Oracle Containers for Java, Sun JDK, ...
    • Set an OC4J admin password
    • On the final page, 'End of Installation', note the port number. This will be in the URL given that can be used to access BI Publisher (e.g. 9704). You should also note the username and password so that you can use them later if you wish to verify that your XMLP Server is up and running.
Your BI Publisher Server should now be up and running. If you want to verify your installation you can access the BI Publisher server from the Windows start menu under 'Oracle - BIHOME'. Select BI Publisher Server and if the login screens appears, your server is running. If you want to, you can login using the username and password given by the installer (e.g. Administrator/Administrator).

3.3 Configuring Application Express to use BI Publisher

To use BI Publisher as your Report Server, first, access the Report Printing parameters:

  1. Access the Administration Services home page
  2. Select Manage Service
  3. Select Instance Settings, under Manage Environment Settings
  4. Click Report Printing to focus on just the Report Printing attributes
Now, specify the following attributes:
  • Oracle BI Publisher: Advanced Support
  • Print Server Protocol: HTTP or HTTPS (depends on your configuration)
  • Print Server Host Address: the hostname for the machine where you installed BI Publisher - e.g. myhost.mycompany.com
  • Print Server Port: the port given at the end of the BI Publisher installation - e.g. 9704
  • Print Server Script: /xmlpserver/convert
For more information on BI Publisher, reference the BI Publisher OTN site. Application Express is compatible with BI Publisher 10.1.3.2 and above.

 

Back to top

4. Installing and Configuring Oracle BI Publisher on Linux
4.1 Prerequisites

To use Oracle BI Publisher as your report server, you need to install Oracle Business Intelligence Publisher, v. 10.1.3.2.1 or above. This can be downloaded at the link below under the OTN Developer License (... limited license to use the programs only for the purpose of developing a single prototype of your application, and not for any other purpose ...).

       Oracle Business Intelligence Publisher Downloads, select the latest version of BI Publisher.

You can also download the Desktop software at the same time. This will allow you to create RTF templates to use in your reports. More information about Oracle BI Publisher can be found on their OTN site.

Before installing Oracle BI Publisher, ensure that you have Java SDK 1.5.0 installed on your system. The Java SDK can be downloaded here:

       Downloads

Note: The Sun release name was originally Java 2 Platform, Standard Edition 1.5.0 (J2SE Development Kit 1.5.0). The numbering system changed to 5.0 (J2SE 5.0). Both 1.5.0 and 5.0 refer to the same platform and product.

4.2 Installing BI Publisher

Based on the version of BI Publisher downloaded select the appropriate documentation from BI Publisher Documentation and follow the installation guide provided under Getting Started.

After you complete the BI Publisher installation, you need to start OC4J. After starting OC4J, you should open the BI Publisher start page to verify that BI Publisher is up and running. If you are unsure what host address and port you need to use when configuring this in Application Express, please reference the host address and port shown in your browser's URL field after opening the BI Publisher start page.

4.3 Configuring Application Express to use BI Publisher

To use BI Publisher as your Report Server, first, access the Report Printing parameters:

  1. Access the Administration Services home page
  2. Select Manage Service
  3. Select Instance Settings, under Manage Environment Settings
  4. Click Report Printing to focus on just the Report Printing attributes
Now, specify the following attributes:
  • Oracle BI Publisher: Advanced Support
  • Print Server Protocol: HTTP or HTTPS (depends on your configuration)
  • Print Server Host Address: the hostname for the machine where you installed BI Publisher - e.g. myhost.mycompany.com
  • Print Server Port: the port given at the end of the BI Publisher installation - e.g. 9704
  • Print Server Script: /xmlpserver/convert
For more information on BI Publisher, reference the BI Publisher OTN site. Application Express is compatible with BI Publisher 10.1.3.2 and above.

 

Back to top

5. Installing and Configuring Apache FOP
5.1 Prerequisites

A supported configuration of Apache FOP in conjunction with Oracle Containers for J2EE (10.1.3.2 or above) is provided with Application Express 3.0.1. The Apache FOP installation is included in the Application Express distribution under apex_install_directory/utlities/fop/fop.war.

Please note - Beginning with Application Express 3.0.1, Apache FOP in conjunction with Oracle Containers for J2EE (10.1.3.2 or above) is a supported report server but only when installed using the provided files. Alternate configurations of Apache FOP are not supported. Questions related to alternate configurations should be posted on the Application Express OTN Forum.

Before getting started, you will need to have Oracle Containers for J2EE (OC4J) up and running. The following version of OC4J have been verified to work with the FOP solution outlined below.

Step 1: Installing the WAR file

 

Place the fop.war file (located in apex_install_directory/utlities/fop) in an accessible location on your local machine. You then follow the directions below or can view the process by running this viewlet.
  1. Navigate to your OC4J Oracle Enterprise Manager Console eg: http://localhost:8888/em/
  2. Select the Applications Tab
  3. Select Deploy Button
  4. On the "Deploy: Select Archive" page use the option "Archive is present on local host. Upload the archive to the server where Application Server Control is running." Use the file browse to select the fop.war file and click "Next" button
  5. On the "Deploy: Application Attributes" page set the "Application Name" option to "fop" and clear the "Context Root " option and click "Next" Button
  6. On the Deploy: Deployment Settings click the "Deploy" button
Step 2: Configure Oracle Application Express to use the JSP for PDF printing

 

Once you have the FOP installed, access the Report Printing parameters:
  1. Access the Administration Services home page
  2. Select Manage Service
  3. Select Instance Settings, under Manage Environment Settings
  4. Click Report Printing to focus on just the Report Printing attributes
Now, specify the following attributes:
  • Oracle BI Publisher: Standard Support
  • Print Server Protocol: HTTP or HTTPS (depends on your configuration)
  • Print Server Host Address: the hostname for the machine where the java container is running - e.g. myhost.mycompany.com
  • Print Server Port: the port that the OC4J is listening on - e.g. 8888
  • Print Server Script: /fop/apex_fop.jsp
Make sure you enter the print server settings exactly as specified, do not use http:// in front of your hostname, do not use a colon on your port settings and do not use a "/" after the JSP name, only before: "/fop/apex_fop.jsp".

 

Back to top

6. Configuring Other XSL-FO Processing Engines
If you prefer to use another XSL-FO Processing Engine, you will need to create an endpoint that provides similar functionality to the example JSP provided for the Apache FOP example above. Only Oracle BI Publisher and the above described installation of Apache FOP in conjunction with Oracle Containers for J2EE (10.1.3.2 or above) are supported report servers. Questions related to other XSL-FO Processing Engine should be posted on the Application Express OTN Forum.

Back to top

7. Enabling Network Services in Oracle Database 11g
By default, the ability to interact with network services is disabled in Oracle Database 11g release 1 (11.1). Therefore, if running Oracle Application Express with Oracle Database 11g release 1 (11.1), use the new DBMS_NETWORK_ACL_ADMIN package to grant connect privileges to any host for the FLOWS_030100 database user. Failing to grant these privileges results in issues with PDF/report printing, specifically, you will get the following error message:
ORA-20001: The printing engine could not be reached because either 
the URL specified is incorrect or a proxy URL needs to be specified.
Follow the steps mentioned in the Oracle Application Express Installation Guide, Enabling Network Services in Oracle Database 11g. Also refer to the troubleshooting section in case you receive an ORA-44416: Invalid ACL error after running the previous script.

Back to top