Deploying Document Builder on WebSphere Application Server Liberty Profile

You can quickly get started with Document Builder by running the WebSphere® Application Server Liberty Profile server that is packaged with the Document Builder installation option. You can further configure Document Builder on the WebSphere Application Server Liberty Profile with either IBM® Db2®, Oracle, SQL Server, or the Derby database that is included with the Document Builder web application (for evaluation purposes only).

Before you begin

You must install IBM Engineering Lifecycle Optimization - Publishing (PUB) with the Document Builder feature, or IBM Engineering Lifecycle Management with the Document Builder feature.

About this task

Note: If you are deploying Document Builder along with IBM Engineering Lifecycle Management, Document Builder must be deployed on a separate application server profile from ELM. See this technote for details: https://www.ibm.com/support/docview.wss?uid=ibm10728091.

Procedure

  1. To start the WebSphere Application Server Liberty Profile server that is packaged with IBM Engineering Lifecycle Optimization - Publishing Document Builder, go to the command line and start the server from:
    • Windows icon: Document_Builder_InstallDir\server\server.startup.bat

      For example: C:\Program Files\IBM\DocumentBuilder\server\server.startup.bat

    • Linux icon: Document_Builder_InstallDir/server/server.startup

      For example: opt/IBM/DocumentBuilder/server/server.startup

    The Liberty Profile server successfully starts when the console outputs the message: Server clm started.

    Here is an example of the console output when the Liberty Profile server is first created and successfully started:
    Server clm created.
    7 File(s) copied
    Starting server clm.
    Server clm started.
    Remember: To later stop Liberty Profile, go to the command line and stop the server from:
    • Windows icon: Document_Builder_InstallDir\server\server.shutdown.bat

      For example: C:\Program Files\IBM\DocumentBuilder\server\server.shutdown.bat

    • Linux icon: Document_Builder_InstallDir/server/server.shutdown

      For example: /opt/IBM/DocumentBuilder/server/server.shutdown

    The Liberty Profile server successfully stops when the console outputs the message: Server clm stopped.

  2. Set the TELELOGIC_LICENSE_FILE licensing variable. For example, create a server.env file that includes TELELOGIC_LICENSE_FILE=port@server. See Customizing the Liberty environment.
  3. In a web browser, open the Document Builder application. The URL specified depends on an HTTPS or HTTP connection:
    • https://<hostname>:9444/rpeng/login.jsp
    • http://<hostname>:9081/rpeng/login.jsp
    Where <hostname> is the fully qualified domain name or localhost.
    Tip: Document Builder by default occupies 9444 for HTTPS and 9081 for HTTP. If you need to change the ports, back up your server.xml file and then edit the appropriate port numbers at Document_Builder_InstallDir\server\liberty\servers\clm\server.xml
    For example:
    • Windows icon: C:\Program Files\IBM\DocumentBuilder\server\liberty\servers\clm\server.xml
    • Linux icon: /opt/IBM/DocumentBuilder/server/liberty/servers/clm/server.xml
    This server.xml file is created only after the first time you start the Liberty Profile.
  4. When you are prompted, provide your user name and password to authenticate the Document Builder application and click Log in.
    • You can log in with any of the default users. The user name and password of the default users are based on the user role:
      User name Password
      pub_user pub_user
      pub_designer pub_designer
      pub_admin pub_admin
    • Request an administrator to add new users to the server.xml file and restart the server. See Configuring users for Document Builder on WebSphere Application Server Liberty Profile topic.
      Tip: The server.xml file is at Document_Builder_InstallDir\server\liberty\servers\clm\server.xml
  5. Create a database for the Document Builder with 16 K pages and UTF-8 code set.
  6. For Db2, Oracle, or SQL Server, set the VCAP_SERVICES variable (not required for Derby):
    • For Windows: Add the following text to the Document_Builder_InstallDir\server\liberty\wlp\bin\server.bat file :
      set VCAP_SERVICES={"sqldb":[{}]}
    • For Linux: Add the following text to the Document_Builder_InstallDir\server\liberty\wlp\bin\server.sh file:
      export VCAP_SERVICES={"sqldb":[{}]}
  7. (Optional) If you deployed the rpeng.war and dgaas.war files on different application servers or computers, then you must set the DGAAS_URL variable. If you deployed the com.ibm.rpe.web.app.ear file, you can skip this step.
    • For Windows: Add the following text to the Document_Builder_InstallDir\server\liberty\wlp\bin\server.bat file :
      set DGAAS_URL="http://server IP:port/dgaas/"
    • For Linux: Add the following text to the Document_Builder_InstallDir\server\liberty\wlp\bin\server.sh file:
      export DGAAS_URL="http://server IP:port/dgaas/" 
  8. Edit the server.xml file to configure the database connectivity for Liberty Profile server.
    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 that points 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>
      For SQL Server:
      <jdbcDriver id="SQLServerLib">  <library id="MSJDBCLib">
              <fileset dir="C:\sqljdbc_6.0\enu\jre7" includes="sqljdbc41.jar"/>
          </library>
      </jdbcDriver>
    3. Define a data source that uses 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="pubdb" password="password" serverName="ipaddress" user="db2admin"/>
                </dataSource> 
               <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
                 <properties.db2.jcc databaseName="pubdb" 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="pub_user"/>
          </dataSource>
          <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
             <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname/lib1" user="pub_user"/>
          </dataSource>
      For SQL Server
         <dataSource id="RPENG" jndiName="jdbc/RPENG_DB">
              <jdbcDriver libraryRef="MSJDBCLib"/>
              <properties.microsoft.sqlserver databaseName="pubdb" serverName="hostname" portNumber="1433" password="password" user="sa"/>
          </dataSource>
      
          <dataSource id="DGAAS" jndiName="jdbc/DGAAS_DB">
              <jdbcDriver libraryRef="MSJDBCLib"/>
              <properties.microsoft.sqlserver databaseName="pubdb" serverName="hostname" portNumber="1433" password="password" user="sa"/>
          </dataSource>
    See Configuring database connectivity in the Liberty profile in the WebSphere Application Server Liberty Profile product documentation.
  9. In the server.xml file, add the following entry to enable the http://server:port/dgaas/debug:
    <classloading useJarUrls="true"/>
  10. In the server.xml file, add the following entry to invalidate a session instead of issue an UnauthorizedSessionRequestException error message when the session manager responds to an unauthorized request:
    <httpSession invalidateOnUnauthorizedSessionRequestException="true" cookieSecure="true"></httpSession>
  11. 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 Profile looks in the apps directory by default.
    For Db2:
    <application id="" name="rpeng" type="ear" location="Document_Builder_InstallDir\server\libery\servers\clm\apps\com.ibm.rpe.web.app.ear" >
         <classloader apiTypeVisibility="spec,ibm-api,api" commonLibraryRef="rcl" />
    </application>
    For Oracle:
    <application type="ear" location="/opt/IBM/WebSphere/Liberty/usr/servers/pub_oracle/apps/com.ibm.rpe.web.app.ear">
           <classloader apiTypeVisibility="spec, ibm-api, api" commonLibraryRef="rcl" />
          
    If you deployed the rpeng.war and dgaas.war files instead of the .ear file, you need to add two 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>
  12. Set the heap size for the Java™ Virtual Machine. The maximum heap size should be incremented to not exceed 50 % of the overall physical memory. For example. for demonstration purposes you can set the heap size to 512 MB, but for production, set a minimum of 2 GB. If concurrent document generation is set to a larger number, or if you are running large document generation jobs, set a larger heap size.:
    1. Open the jvm.options file in a text editor and add the following lines:
      # Set the maximum heap size to 2048m
      -Xmx2048m
    2. Restart the server to enable changes.
    3. To verify the memory settings, open the https://host:port/dgaas/debug page and view the maxMemory property.
      Document Generation debug page
  13. Verify your configuration settings against the server.xml example available at the bottom of this topic in the Example section.
  14. Start the Liberty Profile. When document generation is performed, all the assets and data are 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 completed the previous step, which adds the following entry to 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="pub_user" password="pub_user" />
       <user name="pub_designer" password="pub_designer" />
       <user name="pub_admin" password="pub_admin" />
    </basicRegistry>
    <application type="ear" location="com.ibm.rpe.web.app.ear">
       <classloader apiTypeVisibility="spec, ibm-api, api"/>
       <application-bnd>
          <security-role name="pub_user">
             <user name="pub_user" />
          </security-role>
          <security-role name="pub_report_designer">
             <user name="pub_designer" />
          </security-role>
          <security-role name="pub_admin">
             <user name="pub_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="pub_user" password="pub_user" />
       <user name="pub_designer" password="pub_designer" />
       <user name="pub_admin" password="pub_admin" />
    </basicRegistry>
   <!-- Define licensing Library consumption for PUB  -->
    <application type="ear" location="com.ibm.rpe.web.app.ear">
       <classloader apiTypeVisibility="spec, ibm-api, api"/>
       <application-bnd>
          <security-role name="pub_user">
             <user name="pub_user" />
          </security-role>
          <security-role name="pub_report_designer">
             <user name="pub_designer" />
          </security-role>
          <security-role name="pub_admin">
             <user name="pub_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="pub_user"/>
    </dataSource>
    <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
       <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname/lib1" user="pub_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 Document Builder URL 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