Installing BI Publisher into Weblogic Server 11g

I was on-site yesterday helping an ISV integrate BI Publisher into their product, and hit a few issues getting the product installed and running on the Weblogic application server. BI Publisher comes integrated out-of-the-box with OC4J and Oracle Application Server, but you'll need to install and configure it manually to work with other application servers such as WebLogic, Websphere and Tomcat. The issues we hit were a bit tricky to work around and I couldn't see much information on the 'net about them, so I thought I'd write them down here in case anyone else hits similar issues.

To start off, after installing WebLogic 11g downloaded from OTN, I used the configuration utility to create a new Weblogic domain to hold the BI Publisher application.

On the next screen, I chose the Generate the domain configured automatically to support the following products option, and then called the new domain bipublisher. After giving the domain a username and password, I then selected the Sun SDK rather than JRocket as the JDK, as the BI Publisher docs state that there is a known incompatibility with the JRocket JDK.

On the next screen, you change change the port number of the Admin Server if you are looking to run two on the same server, but for me I then completed the wizard and let it create the new domain for my BI Publisher application. Once that's done, it's time to move on to BI Publisher.

BI Publisher installs automatically, using the Universal Installer, when you are deploying it to OC4J or Oracle Application Server. If you're deploying to WebLogic though you're on your own, and you need to do the install manually. Unzipping the download file shows you the following folder structure, and it's the manual one that we are interested in.

Going into the manual folder shows us the bits we need to deploy.

In the manual/generic folder are a couple of Java archive files that contain the BI Publisher Enterprise web-based application. The manual/XMLP folder contains the BI Publisher repository together with configuration files for the Scheduler, amongst other things. Now with OBIEE, you can just take the .ear files for the Presentation Services plug-in and the BI Office plug-in and deploy them directly to the WebLogic server, but for BI Publisher it's a bit trickier as we first need to unpack them, edit a configuration file and then deploy them in this unpacked state.

To do this unpacking, I need to create a folder within the server filevstructure that will hold the deployed application. I create this as /u01/app/oracle/product/xmlpserver, and copy the xmlpserver.war file from the manual/generic folder to this new folder, like this:

So now I've got a new folder next to all my regular Oracle product installation folders, and I've copied the .war file into it ready for unpacking. To unpack it, I use the command prompt and use the java xvf command, like this:

cd /u01/app/oracle/product/xmlpserver
jar xvf xmlpserver.war
rm xmlpserver.war

This then leaves me with an installation directory where the contents of the .war file have been exploded to give me the full application structure, like this:

Next I need to back to the download directory for BI Publisher, and copy the manual/XMLP folder into the above folder structure, so that it's alongside the WEB-INF, xdo, xml etc directories.

So now I've got the repository and configuration files within the main BI Publisher application directory. Now, I need to find the configuration file that needs editing, and tell it where I've put the repository. Within the BI Publisher xmlpserver directory structure, I locate the WEB-INF/xmlp-server-config.xml file, which initially looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<xmlpConfig xmlns="http://xmlns.oracle.com/oxp/xmlp">
  <resource>
     <file path="${oracle.home}/xdo/repository"/>
   </resource>
</xmlpConfig>

I then edit it so that it reads:

<?xml version="1.0" encoding="UTF-8"?>
<xmlpConfig xmlns="http://xmlns.oracle.com/oxp/xmlp">
  <resource>
     <file path="/u01/app/oracle/product/xmlpserver/XMLP"/>
   </resource>
</xmlpConfig>

It's vitally important that you get this file path correct, as if you don't the application will still deploy to WebLogic but it won't start, and the error message that you'll get is that it can't find the ${oracle.home}/xdo/repository path which makes you think that the configuration file isn't being read, or hasn't updated, whereas this is a default and the file's value is being ignored because it's invalid.

Once you've made the configuration file change, it's then time to register the application in WebLogic. To do this, first of all start the Admin Server from the unix command line, like this:

cd /u01/app/oracle/middleware/user_projects/domains/bipublisher
./startWebLogic.sh

Once WebLogic starts up, using your Web browser start the Admin Console, and log in using the username and password you defined when setting up the new domain.When the Administration Console screen comes up, look for the Deployments link on the left-hand side of the screen and click on it (this assumes you are running the console in Development mode, otherwise you'll need to Lock and Edit beforehand.

Then when the Deployments screen comes up, press the Install button and then navigate to the folder that you put the BI Publisher files in to, like this:

Then press Next, then select Install this deployment as an application, select DD Only as the Security and I will make this deployment accessible from the following location as the Source Accessibility, then press Next, Finish and then Save.

If you click back on the Deployments link on the left-hand side, the xmlpserver application should show a Health of OK. If it doesn't, click on the link to find out what the problem is - for me, it was usually due to the wrong path being put in the xmlp-server-config.xml file.

So far, so good. You should now be able to navigate to http://localhost:7001/xmlpserver to log into BI Publisher, log in using the default Administrator/Administrator credentials and see your repository in place.

At this point, probably the first post-install step you'd carry out is to set up the Scheduler tables. To do this, you select the Admin tab and locate the Scheduler Configuration entry, and then enter the details of the database schema that will hold the scheduler tables.

When you press the Test Connection button, if you've entered the credentials properly you should get a Connection Established Successfully message, like this:

However when you press the Install Schema button, nothing happens. If you check back at the console from which you launched the WebLogic Admin Server, you'll probably see a message looking like this:

What this is saying is that WebLogic can't access the Toplink libraries (a Java persistence layer from Oracle) that it needs to create the database tables for the scheduler. Now Toplink is shipped with the BI Publisher software, but you need to edit the script that launches the WebLogic Admin Server so that it knows about it. To do this, shut down the WeLogic Admin Server (just CTRL-C in the console window that's running it), locate the script that runs the Admin Server startup (mine was at /u01/app/oracle/middleware/user_projects/domains/bipublisher/bin/startWebLogic.sh) and add -Dtoplink.xml.platform=oracle.toplink.platform.xml.jaxp.JAXPPlatform to the startup script, so that it goes from this:

if [ "${WLS_REDIRECT_LOG}" = "" ] ; then
	echo "Starting WLS with line:"
	echo "${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} -Dweblogic.Name=${SERVER_NAME} -Djava.security.policy=${WL_HOME}/server/lib/weblogic.policy ${JAVA_OPTIONS}  ${PROXY_SETTINGS} ${SERVER_CLASS}"
	${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} -Dweblogic.Name=${SERVER_NAME} -Djava.security.policy=${WL_HOME}/server/lib/weblogic.policy ${JAVA_OPTIONS}  ${PROXY_SETTINGS} ${SERVER_CLASS}
else
	echo "Redirecting output from WLS window to ${WLS_REDIRECT_LOG}"
	${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} -Dweblogic.Name=${SERVER_NAME} -Djava.security.policy=${WL_HOME}/server/lib/weblogic.policy ${JAVA_OPTIONS}  ${PROXY_SETTINGS} ${SERVER_CLASS}  >"${WLS_REDIRECT_LOG}" 2>&1
fi

to this

if [ "${WLS_REDIRECT_LOG}" = "" ] ; then
	echo "Starting WLS with line:"
	echo "${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} -Dweblogic.Name=${SERVER_NAME} -Djava.security.policy=${WL_HOME}/server/lib/weblogic.policy ${JAVA_OPTIONS} -Dtoplink.xml.platform=oracle.toplink.platform.xml.jaxp.JAXPPlatform ${PROXY_SETTINGS} ${SERVER_CLASS}"
	${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} -Dweblogic.Name=${SERVER_NAME} -Djava.security.policy=${WL_HOME}/server/lib/weblogic.policy ${JAVA_OPTIONS} -Dtoplink.xml.platform=oracle.toplink.platform.xml.jaxp.JAXPPlatform ${PROXY_SETTINGS} ${SERVER_CLASS}
else
	echo "Redirecting output from WLS window to ${WLS_REDIRECT_LOG}"
	${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} -Dweblogic.Name=${SERVER_NAME} -Djava.security.policy=${WL_HOME}/server/lib/weblogic.policy ${JAVA_OPTIONS} -Dtoplink.xml.platform=oracle.toplink.platform.xml.jaxp.JAXPPlatform ${PROXY_SETTINGS} ${SERVER_CLASS}  >"${WLS_REDIRECT_LOG}" 2>&1
fi

Now stop the Weblogic Admin Server and then restart it, using the above script, make sure it's started OK (it's very easy to make typing errors when adding this command), and then go back into the BI Publisher Web interface. If you now try to create the scheduler tables, it should now work correctly.

So there you go. I bit painful to set up, but once you get the toplink directive into the WebLogic startup script, it all works fine.