Deploying Document Builder on WebSphere Application Server Liberty profile

You can deploy the Rational® Publishing Engine Document Builder on WebSphere® Application Server Liberty with IBM® DB2® , Oracle, or the Derby database that is included with the Document Builder web application (for evaluation purposes only).

Before you begin

You must install WebSphere Application Server Liberty and Rational Publishing Engine with the RPE Document Builder feature before deploying Document Builder.

Procedure

  1. Create a Liberty profile server for the Document Builder.
  2. Deploy the com.ibm.rpe.web.app.ear file by copying it from the RPE_HOME\document-builder directory to the Liberty apps directory. See Deploying a web application to the Liberty profile in the WebSphere Application Server Liberty product documentation.
  3. Create a database for the Document Builder with 16K pages and UTF-8 code set.
  4. For DB2 or Oracle, set the VCAP_SERVICES variable (not required for Derby):
    • For Windows: Add the following text to the <Liberty_install_dir>\bin\server.bat file :
      set VCAP_SERVICES={"sqldb":[{}]}
    • For Linux: Add the following text to the <Liberty_install_dir>\bin\server.sh file:
      export VCAP_SERVICES={"sqldb":[{}]}
  5. (Optional) If you have deployed the rpeng.war and dgaas.war files on different application servers or machines, then you must set the DGAAS_URL variable. If you have deployed the com.ibm.rpe.web.app.ear file, you can skip this step.
    • For Windows: Add the following text to the <Liberty_install_dir>\bin\server.bat file :
      set DGAAS_URL="http://[server IP]:[port]/dgaas/"
    • For Linux: Add the following text to the <Liberty_install_dir>\bin\server.sh file:
      export DGAAS_URL="http://[server IP]:[port]/dgaas/" 
  6. Edit the server.xml file to configure the database connectivity for the Liberty profile.
    1. Add the following features:
      <featureManager>
                 <feature>jsp-2.2</feature> 
                 <feature>servlet-3.0</feature> 
                 <feature>appSecurity-2.0</feature> 
                 <feature>jndi-1.0</feature>   
                 <feature>jpa-2.0</feature>  
                 <feature>jdbc-4.0</feature>
          </featureManager>
    2. Define a shared library pointing to the location of your JDBC driver JAR or compressed files (not required for Derby).
      For DB2:
      <jdbcDriver id="db2-lib">
                 <library>
                     <fileset caseSensitive="false" dir="C:\Program Files\IBM\SQLLIB\java"/>  
                 </library> 
                </jdbcDriver>
      For Oracle:
      <jdbcDriver id="OracleLib">
                 <library>
                      <fileset caseSensitive="false" dir="/oracle_jdbc" includes="*.jar">  
                 </library> 
                </jdbcDriver>
    3. Define a data source using the JDBC driver for the rpeng and dgaas data sources with database connection details (not required for Derby).
      For DB2:
      <dataSource id="rpeng" jdbcDriverRef="db2-lib" jndiName="jdbc/RPENG_DB">
                 <properties.db2.jcc databaseName="databasename" password="password" serverName="ipaddress" user="db2admin"/>
                </dataSource> 
               <id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
                 <properties.db2.jcc databaseName="databasename" password="password" serverName="ipaddress" user="db2admin"/>
                </dataSource> 
      For Oracle:
       <dataSource id="rpeng_db" jdbcDriverRef="OracleLib" jndiName="jdbc/RPENG_DB">
             <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname/lib1" user="rpe_user"/>
          </dataSource>
          <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
             <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname/lib1" user="rpe_user"/>
          </dataSource>
    See Configuring database connectivity in the Liberty profile in the WebSphere Application Server Liberty product documentation.
  7. In the server.xml file, add the following entry to enable the http://server:port/dgaas/debug:
    <classloading useJarUrls="true"/>
  8. In the server.xml file, add the following entry to invalidate a session instead of issuing an UnauthorizedSessionRequestException error message when the session manager responds to an unauthorized request:
    <httpSession invalidateOnUnauthorizedSessionRequestException="true" cookieSecure="true"></httpSession>
  9. Add the following configuration to the server.xml file. The id and name attributes are optional. The location attribute does not have to be fully qualified, as Liberty will look in the apps directory by default.
    For DB2:
    <application id="" name="rpeng" type="ear" location="[Liberty_install_dir]\usr\servers\rpeng\apps\com.ibm.rpe.web.app.ear" >
         <classloader apiTypeVisibility="spec,ibm-api,api"/>
    </application>
    For Oracle:
    <application type="ear" location="/opt/IBM/WebSphere/Liberty/usr/servers/rpe_oracle/apps/com.ibm.rpe.web.app.ear">
           <classloader apiTypeVisibility="spec, ibm-api, api" commonLibraryRef="rcl" />
          
    If you have deployed the rpeng.war and dgaas.war files instead of the .ear file, you need to add 2 application entries instead of one:
    <application id="" name="rpeng" location="rpeng.war" type="war>
         <classloader commonLibraryRef="rcl" apiTypeVisibility="spec,ibm-api,api"/>
    </application>
    <application id="" name="dgaas" location="dgaas.war" type="war>
         <classloader commonLibraryRef="rcl" apiTypeVisibility="spec,ibm-api,api"/>
    </application>
  10. Verify your configuration settings against the server.xml example available at the bottom of this topic in the Example section.
  11. Set the licensing variable. See Verifying the TELELOGIC_LICENSE_FILE environment variable.
  12. Start the Liberty profile. When document generation is performed, all the assets and data will be stored in the database.

Results

You can confirm that Document Builder is deployed by opening the introductory page in a browser at http://server:port/rpeng/
Remember: If you encounter an UnauthorizedSessionRequestException error message in the web browser, verify that you have completed the previous step which adds the following entry the server.xml file:
<httpSession invalidateOnUnauthorizedSessionRequestException="true"></httpSession>

Example

For DB2: An example of the server.xml file configured to deploy Document Builder:
<?xml version="1.0" encoding="UTF-8"?>
<server description="new server">
    <!-- Enable features -->
    <featureManager>
       <feature>jsp-2.2</feature>
       <feature>jndi-1.0</feature>
       <feature>jpa-2.0</feature>
       <feature>jdbc-4.0</feature>
       <feature>servlet-3.0</feature>
       <feature>appSecurity-2.0</feature>
    </featureManager>
    <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" -->
    <httpEndpoint id="defaultHttpEndpoint" httpPort="9080" httpsPort="9443" host="localhost"/>
    <classloading useJarUrls="true"/>
    <!-- User creation-->
    <basicRegistry id="form" realm="WebRealm">
       <user name="rpe_user" password="xyz" />
       <user name="rpe_report_designer" password="xyz" />
       <user name="rpe_admin" password="xyz" />
    </basicRegistry>
    <application type="ear" location="C:\IBM\WebSphere\Liberty\usr\servers\rpeng\apps\com.ibm.rpe.web.app.ear">
       <classloader apiTypeVisibility="spec, ibm-api, api" commonLibraryRef="rcl" />
       <application-bnd>
          <security-role name="rpe_user">
             <user name="rpe_user" />
          </security-role>
          <security-role name="rpe_report_designer">
             <user name="rpe_report_designer" />
          </security-role>
          <security-role name="rpe_admin">
             <user name="rpe_admin" />
          </security-role>
       </application-bnd>
    </application>
    <httpSession invalidateOnUnauthorizedSessionRequestException="true"></httpSession>
    <!--Database Configuration -->
    <jdbcDriver id="db2-lib">
       <library>
          <fileset caseSensitive="false" dir="C:\Program Files\IBM\SQLLIB\java"/>
       </library>
    </jdbcDriver>
    <dataSource id="rpeng" jdbcDriverRef="db2-lib" jndiName="jdbc/RPENG_DB">
       <properties.db2.jcc databaseName="databasename" password="password" serverName="ipaddress" user="db2admin"/>
    </dataSource>
    <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
       <properties.db2.jcc databaseName="databasename" password="password" serverName="ipaddress" user="db2admin"/>
    </dataSource>
</server>
For Oracle: An example of the server.xml file configured to deploy Document Builder:
<?xml version="1.0" encoding="UTF-8"?>
<server description="new server">
    <!-- Enable features -->
    <featureManager>
       <feature>jsp-2.2</feature>
       <feature>jndi-1.0</feature>
       <feature>jpa-2.0</feature>
       <feature>jdbc-4.0</feature>
       <feature>servlet-3.0</feature>
       <feature>appSecurity-2.0</feature>
       <feature>ssl-1.0</feature>
    </featureManager>
    <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" -->
    <httpEndpoint id="defaultHttpEndpoint" httpPort="9445" httpsPort="9082" host="localhost"/>
    <keystore id="defaultKeyStore" password="password"/>
    <classloading useJarUrls="true"/>
   <httpSession cookieSecure="true invalidateOnUnauthorizedSessionRequestException="true"></httpSession>
    <!-- User creation-->
    <basicRegistry id="form" realm="WebRealm">
       <user name="rpe_user" password="xyz" />
       <user name="rpe_designer" password="xyz" />
       <user name="rpe_admin" password="xyz" />
    </basicRegistry>
   <!-- Define licensing Library consumption for RPE  -->
    <application type="ear" location="/opt/IBM/WebSphere/Liberty/usr/servers/rpe_oracle/apps/com.ibm.rpe.web.app.ear">
       <classloader apiTypeVisibility="spec, ibm-api, api" commonLibraryRef="rcl" />
       <application-bnd>
          <security-role name="rpe_user">
             <user name="rpe_user" />
          </security-role>
          <security-role name="rpe_report_designer">
             <user name="rpe_designer" />
          </security-role>
          <security-role name="rpe_admin">
             <user name="rpe_admin" />
          </security-role>
       </application-bnd>
    </application>
   
    <!--Database Configuration -->
    <jdbcDriver id="OracleLib">
       <library>
          <fileset caseSensitive="false" dir="/oracle_jdbc" includes="*.jar">
       </library>
    </jdbcDriver>
    <dataSource id="rpeng_db" jdbcDriverRef="OracleLib" jndiName="jdbc/RPENG_DB">
       <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname/lib1" user="rpe_user"/>
    </dataSource>
    <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
       <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname/lib1" user="rpe_user"/>
    </dataSource>
</server>

What to do next

Optionally, you can deploy and run the Newskeeper sample application that uses document generation service technology for generating documents, and provides a storage interface for document generation service assets and documents. For more details, see Running the Newskeeper sample.

Configure the Rational Publishing Engine Document Builder listed on the http://server:port/rpeng/ page. See Document Builder URLs for an explanation of how each URL is used and tasks for configuring each of the features.

Feedback