Oracle® XML Publisher Enterprise

Installation Notes
Release 5.6.2
Part No. B28881-01
June 2006

Introduction
Oracle XML Publisher offers you the most efficient, scalable reporting solution available
for complex, distributed environments. It provides a central architecture for generating
and delivering information to employees, customers, and suppliers—both securely and
in the right format. Oracle XML Publisher reduces the high costs associated with the
development, customization and maintenance of business documents; while increasing the
efficiency of reports management.
This CD contains the XML Publisher Server. This distribution contains:
• XML Publisher Enterprise server application
• XML Publisher runtime libraries
• XML Publisher fonts
• Documentation: User’s Guide, Javadocs, demos, and samples
Note: The application uses Apache Axis and the OpenSymphony Quartz
Scheduler open-source software packages. The Apache license agreement for
Axis is included on the CD under \doc\ApacheLicense.txt and can also be
obtained from http://www.apache.org/licenses/LICENSE-2.0.

For the most current information please check:

XML Publisher Web Page:
http://www.oracle.com/technology/products/applications/publishing/index.html
XML Publisher Forum:
http://forums.oracle.com/forums/forum.jspa?forumID=245

System Requirements
You need the following to run Oracle XML Publisher Enterprise:
• Java Runtime Environment (JRE) / Java Development Kit (JDK) version 1.4 or later
• A J2EE-based application server Oracle OC4J 10.1./2/10.1.3 or Apache Tomcat 5.0
• Oracle Database 9i or 10g (optional, but required for the scheduler database)
• Microsoft Internet Explorer 6.0 or Mozilla Firefox 1.0 or later

Installation
XML Publisher Enterprise is installed with its own application server (OC4J 10.1.3) and
JDK (SUN 1.5.0.5-b5). This release comes with the Oracle Universal Installer for Windows

Copyright © 2006, Oracle. All rights reserved. Oracle, JD Edwards, PeopleSoft, and Siebel are registered
trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
 and Linux x86. For other platforms or to deploy on an existing application server you need
to install manually.

Manual Installation
If you need to deploy XML Publisher Enterprise manually, please follow the steps in the
Manual Installation Readme, page 1-4.

Windows Installation
1. Run the install\setup.exe executable to start the installer and follow the instructions.
2. Start XML Publisher server using the /xmlpserver/xmlpserverstart.bat file in the ORACLE
HOME directory (typical C:\OraHome_1).
3. The installer uses the first free port between 15101-15110 for XML Publisher Enterprise. The
installer will provide you with the server URL on the last dialog of the installation. This
information is also stored in the /xmlpserver/setupinfo.txt file under the Oracle Home
directory.
Typically, the URL looks like:
http://localhost:15101/xmlpserver
Open a compatible browser pointing to this URL.
4. Log in with user admin and password admin.
Important: Please change the admin password on the Account tab under
Preferences.

5. Continue under Database Configuration, page 1-3.

Linux Conguration
1. Run the runInstaller script to start the installer and follow the instructions.
2. You can start XML Publisher server using the /xmlpserver/xmlpserverstart.sh file in the
ORACLE HOME directory (typical $ORACLE_HOME or /oraclehomes).
3. The installer uses the first free port between 15101-15110 for XML Publisher Enterprise. The
installer will provide you with the server URL on the last dialog of the installation. This
information is also stored in the /xmlpserver/setupinfo.txt file under the Oracle Home
directory.
Typically, the URL looks like:
http://localhost:15101/xmlpserver
Open a compatible browser pointing to this URL.
4. Log in with user admin and password admin to set up your system.
Important: Please change the admin password under Preferences >
Accounts.

5. Continue under Database Configuration, page 1-3.

2
Database Conguration
The database configuration is required to send or schedule reports. In this release, only Oracle
Database deployment is supported:

Oracle Database 10g Deployment

Follow the steps below to configure Oracle Database 10g for XML Publisher:
1. Create a new user/schema (for example: "XMLP" with password "welcome").
2. From the SQL script directory: \manual\SQL_Scripts, run the oracle_tables.sql script
with sqlplus:
sqlplus user/password @tables_oracles.sql
where user/password are replaced with correct values. For example:
sqlplus XMLP/welcome @tables_oracles.sql
Note: This script includes the script quartz-1.5.1/tables_oracles.sql that
sets up the database for the Quartz scheduler.

Application Conguration
Follow the steps below to configure XML Publisher Enterprise:

1. Open your browser, http://hostname:port/xmlpserver to see the welcome page.

For example: http://localhost:8888/xmlpserver
Note: Your xmlpserver.war or xmlpsever.ear file should now be unpacked.

2. Open the file \xmlpserver\xmlpserver\WEB-INF\xmlp-server-config.xml

where your application server unpacked the war/ear file.
Typically for OC4J this will be: C:\oc4j1012\j2ee\home\applications
Typically For Apache Tomcat this will be: C:\Program Files\Apache Software
Foundation\Tomcat 5.0\webapps
3. Change the database information in the scheduler section under /xmlpConfig/resource
to reflect the database and schema that you configured for XML Publisher.
For example, for XMLP schema with password welcome on Oracle 10g database
db.company.com:1525:ora10g you would update the file as follows:
<scheduler>
<connection>
<connectionType>jdbc</connectionType>
<url>jdbc:oracle:thin:@db.company.com:1525:ora10g</url>
<username>XMLP</username>
<password>welcome</password>
<driver>oracle.jdbc.driver.OracleDriver</driver>
</connection>
</scheduler>

For more information on setting up the server configuration file, see the
Administration chapter of the Oracle XML Publisher Enterprise User’s Guide found under
(/doc/5_6_2_Users.pdf).

3
 4. Restart the application server.
5. Open your browser, http://hostname:port/xmlpserver to see the welcome page.
For example: http://localhost:8888/xmlpserver
6. Log in using the user/password: admin/admin.
Important: Please change the admin password on the Account tab under
Preferences.

Running the XML Publisher Enterprise Demo Reports

You can test your application installation as follows:
1. Open your browser http://hostname:port/xmlpserver to see the welcome page.
For example:
http://localhost:8888/xmlpserver
2. The sample reports require that the data source “xmlpdemo” is set up correctly. Perform
the following actions:
• Select the Admin tab
• Select JDBC Database Connection in the Data Sources section.
• Select the connection with the name xmlpdemo.
• Change the URL to point to an Oracle 10g database with unlocked oe user.
• Select the Test Connection button to confirm that XML Publisher can access your
database.
• Select Apply to save your changes.
3. Navigate to the Reports tab and view the demo reports.
See the Oracle XML Publisher Enterprise User’s Guide (found under \doc\5_6_2_Users.pdf)
for additional information.

Manual Installation Readme

Introduction
Oracle XML Publisher offers you the most efficient, scalable reporting solution available
for complex, distributed environments. It provides a central architecture for generating
and delivering information to employees, customers, and suppliers—both securely and
in the right format. Oracle XML Publisher reduces the high costs associated with the
development, customization and maintenance of business documents; while increasing the
efficiency of reports management.
This CD contains the XML Publisher Server. This distribution contains:
• XML Publisher Enterprise server application
• XML Publisher runtime libraries
• XML Publisher fonts
• Documentation: User’s Guide, Javadocs, demos, and samples

4
 Note: The application uses Apache Axis and the OpenSymphony Quartz
Scheduler open-source software packages. The Apache license agreement for
Axis is included on the CD under \doc\ApacheLicense.txt and can also be
obtained from http://www.apache.org/licenses/LICENSE-2.0.

For the most current information please check:

XML Publisher Web Page:
http://www.oracle.com/technology/products/applications/publishing/index.html
XML Publisher Forum:
http://forums.oracle.com/forums/forum.jspa?forumID=245

System Requirements
You need the following to run Oracle XML Publisher Enterprise:
• Java Runtime Environment (JRE) / Java Development Kit (JDK) version 1.4 or later
• A J2EE-based application server Oracle OC4J 10.1./2/10.1.3 or Apache Tomcat 5.0
• Oracle Database 9i or 10g (optional, but required for the scheduler database)
• Microsoft Internet Explorer 6.0 or Mozilla Firefox 1.0 or later

XDO Server Application Installation

The server application allows you to create, manage and schedule reports. You must perform
the following steps as described in this document to deploy Oracle XML Publisher manually:
1. Deploy XML Publisher on the application server.
2. Create the XML Publisher schema on the database server.
3. Configure the XML Publisher Application.

Application Server Deployment

XML Publisher is a pure J2EE application and has been extensively tested on:
• Oracle OC4J 10.1.2 / 10.1.3
• Apache Tomcat 5.0
OC4J 10.1.3 Deployment
Follow the steps below to deploy XML Publisher on Oracle OC4J 10.1.3 with the Enterprise
Manager:
1. Open the Application Server Control (typically: http://localhost:8888/em) in your
browser and log in as oc4jadmin.
2. Select the Applications tab and select the Deploy button.
3. Browse for the \manual\OAS10.1.3\xmlpserver.ear on the CD for the Archive
Location and select the Next button.
4. Choose xmlpserver as the Application Name and select the Next button.
5. Change any other deployment settings if required and select the Deploy button.
6. Copy the fonts in the \manual\fonts directory on the CD to the fonts directory of your
Java Runtime Environment (JAVA_HOME\lib\fonts).

5
 For example: C:\Program Files\Java\jdk1.5.0_06\jre\lib\fonts
7. Start or restart OC4J.
8. Open your browser http://hostname:port/xmlpserver to see the login page.
For example: http://localhost:8888/xmlpserver
9. If you see the login page, continue under Database Configuration, page 1-7.
Oracle Application Server 10.1.2 Deployment
Follow the steps below to deploy XML Publisher on Oracle Application Server 10.1.2 with the
Enterprise Manager:
1. Open the Application Server Control (typically: http://localhost:18100) in your
browser and log in as ias_admin.
2. Select the System Component home on the Home tab and then select the Applications tab.
3. Click the Deploy EAR file button.
4. Browse for the \manual\xmlpserver.ear on the CD for the J2EE Application, enter
xmlpserver as the Application name, then select Continue.
5. Choose xmlpserver as the URL Mapping and select Next.
6. Keep the Use JAZN XML User Manager selected and select Next button.
7. Select Deploy.
8. Copy the fonts in the \manual\fonts directory on the CD to the fonts directory of your
Java Runtime Environment (JAVA_HOME\lib\fonts). For example, on Windows the
directory name may be: C:\OraHome_1\jdk\jre\lib\fonts
9. Start or restart OC4J.
10. Open your browser http://hostname:port/xmlpserver to see the login page. For
example: http://localhost:7777/xmlpserver
11. If you see the login page, continue under Database Configuration, page 1-7.
OC4J 10.1.2 Deployment
Follow the steps below to deploy XML Publisher on Oracle OC4J 10.1.2:
1. Copy \manual\xmlpserver.ear from the CD to a directory that can be accessed by
OC4J.
Note that in the following steps we assume that OC4J is installed under C:\oc4j1012
and that you copied the ear file to C:\oc4j1012\j2ee\home\applications.
2. Copy the fonts in the \manual\fonts directory on the CD to the \manual\fonts
directory of your Java Runtime Environment (JAVA_HOME\lib\fonts).
For example: C:\Program Files\Java\j2re1.4.2_08\lib\fonts
3. Add an entry to the server.xml file (under J2EE_HOME\config) for the
xmlpserver.ear:
<application name="xmlpserver" path="../applications/xmlpserver.
ear" auto-start="true" />
using the correct path to the xmlpserver.ear file.
4. Add an entry to the http-web-site.xml file (under J2EE_HOME\config):
<web-app application="xmlpserver" name="xmlpserver" root="/
xmlpserver" />

6
 5. Start or restart OC4J.
6. Open your browser http://hostname:port/xmlpserver to see the login page.
For example: http://localhost:8888/xmlpserver
7. If you see the login page, continue under Database Configuration, page 1-7.
Apache Tomcat 5.0 Deployment
Follow the steps below to deploy XML Publisher on Apache Tomcat 5.0:
1. Copy \manual\xmlpserver.war from the CD to the webapps directory under
your Tomcat home directory (typically C:\Program Files\Apache Software
Foundation\Tomcat 5.0\webapps on Windows).
2. Copy the fonts from \manual\fonts on the CD to the fonts directory of your Java
Runtime Environment (JAVA_HOME\lib\fonts). For example: C:\Program
Files\Java\j2re1.4.2_08\lib\fonts
3. Start or restart Tomcat 5.0 (typically from services).
4. Open your browser, http://hostname:port/xmlpserver to see the demo page.
For example: http://localhost:8080/xmlpserver
5. If you see the login page, continue under Database Configuration, page 1-7.

Database Conguration
The database configuration is required to send or schedule reports. In this release, only Oracle
Database deployment is supported:

Oracle Database 10g Deployment

Follow the steps below to configure Oracle Database 10g for XML Publisher:
1. Create a new user/schema (for example: "XMLP" with password "welcome").
2. From the SQL script directory: \manual\SQL_Scripts, run the oracle_tables.sql script
with sqlplus:
sqlplus user/password @tables_oracles.sql
where user/password are replaced with correct values. For example:
sqlplus XMLP/welcome @tables_oracles.sql
Note: This script includes the script quartz-1.5.1/tables_oracles.sql that
sets up the database for the Quartz scheduler.

3. Continue under Application Configuration, page 1-7.

Application Conguration
Follow the steps below to configure XML Publisher Enterprise:

1. Copy the \manual\XMLP directory to your server.

The following steps assume that you copied XMLP to C:\.
2. Open your browser, http://hostname:port/xmlpserver to see the welcome page.
For example: http://localhost:8888/xmlpserver

7
 Note: Your xmlpserver.war or xmlpsever.ear file should now be unpacked.

3. Open the file \xmlpserver\xmlpserver\WEB-INF\xmlp-server-config.xml

where your application server unpacked the war/ear file.
Typically for OC4J this will be: C:\oc4j1012\j2ee\home\applications
Typically for Apache Tomcat this will be: C:\Program Files\Apache Software
Foundation\Tomcat 5.0\webapps
4. Change the file path in the configuration file to point to the XMLP directory. The file
element is found under /xmlpConfig/resource.
The original entry is <file path="%s_Reports_Path%"/>.
If you copied the XML directory to C: change it to: <file path="C:\XMLP"/>.
5. Change the database information in the scheduler section under /xmlpConfig/resource
to reflect the database and schema that you configured for XML Publisher.
For example, for XMLP schema with password welcome on Oracle 10g database
db.company.com:1525:ora10g you would update the file as follows:
<scheduler>
<connection>
<connectionType>jdbc</connectionType>
<url>jdbc:oracle:thin:@db.company.com:1525:ora10g</url>
<username>XMLP</username>
<password>welcome</password>
<driver>oracle.jdbc.driver.OracleDriver</driver>
</connection>
</scheduler>

For more information on setting up the server configuration file, see the
Administration chapter of the Oracle XML Publisher Enterprise User’s Guide found under
(/doc/5_6_2_Users.pdf).
6. Consult the Oracle XML Publisher Enterprise User’s Guide, "Setting Runtime Properties" for
information on defining a temporary directory and setting other runtime properties.
Important: It is strongly recommended that you set a temporary directory.
7. Restart the application server.
8. Open your browser, http://hostname:port/xmlpserver to see the welcome page.
For example: http://localhost:8888/xmlpserver
9. Log in using the user/password: admin/admin.
Important: Please change the admin password on the Account tab under
Preferences.

Running the XML Publisher Enterprise Demo Reports

You can test your application installation as follows:
1. Open your browser http://hostname:port/xmlpserver to see the welcome page.
For example:
http://localhost:8888/xmlpserver

8
 2. The sample reports require that the data source “xmlpdemo” is set up correctly. Perform
the following actions:
• Select the Admin tab
• Select JDBC Database Connection in the Data Sources section.
• Select the connection with the name xmlpdemo.
• Change the URL to point to an Oracle 10g database with unlocked oe user.
• Select the Test Connection button to confirm that XML Publisher can access your
database.
• Select Apply to save your changes.
3. Navigate to the Reports tab and view the demo reports.
See the Oracle XML Publisher Enterprise User’s Guide (found under \doc\5_6_2_Users.pdf)
for additional information.

Creating XML Publisher Applications

Perform the following steps to add XML Publisher to your own application:
1. Copy the XML Publisher Java libraries (\manual\lib) on the Server CD to the library
directory of your J2EE project or Java Runtime Environment.
2. Copy the fonts in the fonts directory (\manual\fonts) on the Server CD to the fonts
directory of your Java Runtime Environment.
3. Consult "Setting Runtime Properties" in the Oracle XML Publisher Enterprise User’s Guide
(found under \doc\XMLPublisher562.pdf) regarding the configuration file. Please define
the temporary directory!
Please read "Using the Java APIs" in the Oracle XML Publisher Enterprise User’s Guide (found
under \doc\5_6_2_Users.pdf) on how to develop applications that use XML Publisher. Also
consult the XML Publisher Javadocs (found under \doc\JavaDocs\index.html) for a complete
reference of the XML Publisher API).

Oracle OC4J Deployment Notes

The version of the XML Parser shipped with Oracle OC4J is incompatible with XML
Publisher. When you create an XML Publisher application for OC4J you need to configure the
system to use the XML Publisher version of the XML Parser. This can be accomplished by
setting an orion-web.xml configuration file with the following content:
<?xml version = ’1.0’ encoding = ’windows-1252’?>
<orion-web-app>
<web-app-class-loader search-local-classes-first="true" />
</orion-web-app>

Known Issues
The following issues are known about Oracle XML Publisher Enterprise 5.6.2:
1. The installer does not copy the properties.xml file into the \Admin\Delivery
folder. As a result, e-mail confirmations fail. You can resolve the issue by copying
properties.xml from the \manual\XMLP\Admin\Delivery directory on the CD to
the ORACLE_HOME\xmlpserver\manual\XMLP\Admin\Delivery directory of your
installation.

9
 2. If XML Publisher is deployed on Apache Tomcat using the default configuration, folder and
filenames are limited to the use of ASCII characters. To correct this issue, set the following
attributes of the Connector element in the <tomcat home>/conf/server.xml file
as shown:
• URIEncoding="UTF-8"
• BodyEncodingForURI="true"
For example:
<Connector port="8080"
...
URIEncoding="UTF-8" useBodyEncodingForURI="true" />

3. The JDBC connection passwords are stored in clear text in the datasources.xml. It is
recommended that you use a JNDI connection for added security.
4. The scheduler is limited to sending e-mail using UTF-8.
5. If you are using the delivery options FTP or WebDAV and your file name contains
non-ASCII characters, your FTP server must support UTF-8.
6. If you perform a Manual Installation, the translations are not included in the /XMLP folder.
You can obtain the files by running the Oracle Universal Installer on a Linux or Windows
instance. Copy the translations from the installed /XMLP/Admin/Translation/ directory to
the /XMLP folder.
7. The Query Builder is only supported for the Oracle database. If your data source is a
non-Oracle database you must manually enter your query in the SQL Query text box.
The Query Builder is a feature of the report definition interface that allows you to build
SQL queries without coding.

TTY Access to Oracle Support Services

Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services within the
United States of America 24 hours a day, seven days a week. For TTY support, call 800.446.2398.

Documentation Accessibility
Our goal is to make Oracle products, services, and supporting documentation accessible, with
good usability, to the disabled community. To that end, our documentation includes features
that make information available to users of assistive technology. This documentation is
available in HTML format, and contains markup to facilitate access by the disabled community.
Accessibility standards will continue to evolve over time, and Oracle is actively engaged
with other market-leading technology vendors to address technical obstacles so that our
documentation can be accessible to all of our customers. For more information, visit the Oracle
Accessibility Program Web site at http://www.oracle.com/accessibility/ .

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The
conventions for writing code require that closing braces should appear on an otherwise empty
line; however, some screen readers may not always read a line of text that consists solely
of a bracket or brace.

10
Accessibility of Links to External Web Sites in Documentation
This documentation may contain links to Web sites of other companies or organizations that
Oracle does not own or control. Oracle neither evaluates nor makes any representations
regarding the accessibility of these Web sites.

Legal Notices
The Programs (which include both the software and documentation) contain proprietary
information; they are provided under a license agreement containing restrictions on use and
disclosure and are also protected by copyright, patent, and other intellectual and industrial
property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to
the extent required to obtain interoperability with other independently created software or
as specified by law, is prohibited.
The information contained in this document is subject to change without notice. If you find
any problems in the documentation, please report them to us in writing. This document is not
warranted to be error-free. Except as may be expressly permitted in your license agreement
for these Programs, no part of these Programs may be reproduced or transmitted in any form
or by any means, electronic or mechanical, for any purpose.
If the Programs are delivered to the United States Government or anyone licensing or using the
Programs on behalf of the United States Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS
Programs, software, databases, and related documentation and technical data delivered to U.S.
Government customers are "commercial computer software" or "commercial technical data"
pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental
regulations. As such, use, duplication, disclosure, modification, and adaptation of the
Programs, including documentation and technical data, shall be subject to the licensing
restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable,
the additional rights set forth in FAR 52.227-19, Commercial Computer Software–Restricted
Rights (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or
other inherently dangerous applications. It shall be the licensee's responsibility to take all
appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such
applications if the Programs are used for such purposes, and we disclaim liability for any
damages caused by such use of the Programs.
The Programs may provide links to Web sites and access to content, products, and services
from third parties. Oracle is not responsible for the availability of, or any content provided on,
third-party Web sites. You bear all risks associated with the use of such content. If you choose
to purchase any products or services from a third party, the relationship is directly between
you and the third party. Oracle is not responsible for: (a) the quality of third-party products
or services; or (b) fulfilling any of the terms of the agreement with the third party, including
delivery of products or services and warranty obligations related to purchased products or
services. Oracle is not responsible for any loss or damage of any sort that you may incur
from dealing with any third party.

11