Custom Deployment of Publishing Document Builder on IBM WebSphere Liberty

You can customize the deployment of Publishing Document Builder on IBM WebSphere Liberty.

Before you begin

You must install Publishing Document Builder from IBM Engineering Lifecycle Optimization - Publishing (PUB), or IBM Engineering Lifecycle Management launchpad.
By default, Derby database is created, if you want to change the database, you must choose one of the following database vendors that you want to configure the connection with Publishing Document Builder on WebSphere Liberty:
  • IBM Db2®
  • Oracle

About this task

Note: If you are deploying Publishing Document Builder along with IBM Engineering Lifecycle Management, Publishing 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 Liberty server that is packaged with 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 server successfully starts when the console outputs the message: Server clm started.

    The following is an example of the console output when the Liberty server is first created and successfully started:
    Server clm created.
    630 File(s) copied
    Starting server clm.
    Server clm started.
    Remember: To later stop Liberty, 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 server successfully stops when the console outputs the message: Server clm stopped.

  2. For Linux, set the TELELOGIC_LICENSE_FILE licensing variable.
    Create a server.env file that includes TELELOGIC_LICENSE_FILE=port@server. See Customizing the Liberty environment.
  3. Create a database for the Publishing Document Builder with 16 K 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 Document_Builder_InstallDir\server\liberty.server.bat file :
      set VCAP_SERVICES={"sqldb":[{}]}
    • For Linux®: Add the following text to the Document_Builder_InstallDir\server\liberty.server.sh file:
      export VCAP_SERVICES={"sqldb":[{}]}
  5. Edit the server.xml file to configure the database connectivity for Liberty server.
    1. 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>
    2. 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" portNumber="portNumber" password="password" serverName="ipaddress" user="db2admin"/>
                </dataSource> 
               <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
                 <properties.db2.jcc databaseName="pubdb" portNumber="portNumber" 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:port/lib1" user="pub_user"/>
          </dataSource>
          <dataSource id="DGAAS_DB" jdbcDriverRef="OracleLib" jndiName="jdbc/DGAAS_DB">
             <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname:port/lib1" user="pub_user"/>
          </dataSource>
    See Configuring database connectivity in the WebSphere Liberty in the WebSphere Liberty product documentation.
  6. Verify your configuration settings against the server.xml example available towards the end of this topic in the Example section.
  7. Set the heap size for the Java™. The maximum heap size should be incremented to not exceed 50 % of the overall physical memory. By default, the heap memory is set to 4 GB. If concurrent document-style report generation is set to a larger number, or if you are running large document-style report generation jobs, set a larger heap size. Heap memory can be updated in server.startup.bat file in Document_Builder_InstallDir/server.
    1. Update the following Java parameters to change the heap memory.
      set JAVA_OPTS=%JAVA_OPTS% -Xmx4G
      set JAVA_OPTS=%JAVA_OPTS% -Xms4G
      set JAVA_OPTS=%JAVA_OPTS% -Xmn1G
    2. Restart the server to enable changes.
    3. To verify the Status of the Document Generation Service, open https://hostname:port/dgaas/debug.
      Document Generation debug page
    4. To verify the database status, open https://hostname:port/dgaas/debug/db. Database status page
  8. In a web browser, open the Publishing 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
    Here <hostname> is the fully qualified domain name or localhost.
    Tip: Publishing 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
  9. When you are prompted, provide your username and password to authenticate the Publishing Document Builder application and click Log in.
    • You can log in with any of the default users. The username and password of the default users are based on the user role:
      Username Password
      pub_user pub_user
      pub_designer pub_designer
      pub_admin pub_admin
    • Request an administrator to add new users to the basicUserRegistry.xml file and restart the server. See Configuring users for Publishing Document Builder on IBM WebSphere Liberty topic.
      Tip: The basicUserRegistry.xml file is at Document_Builder_InstallDir\server\liberty\servers\clm\conf\basicUserRegistry.xml

Results

You can confirm that Publishing Document Builder is deployed by opening the introductory page in a browser at https://hostname:port/rpeng/login.jsp
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 Publishing 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="9081" httpsPort="9444" host="localhost"/>
    <classloading useJarUrls="true"/>
    <!-- User creation-->
    <httpSession invalidateOnUnauthorizedSessionRequestException="true"/>

<classloading useJarUrls="true"/>

<webContainer deferServletLoad="false"/>

<include location="conf/basicUserRegistry.xml"/>

<include location="conf/application.xml"/>

<executor coreThreads="100"/>

<webAppSecurity ssoRequiresSSL="true" ssoUseDomainFromURL="true" ssoCookieName="rpeLtpaToken2"/>

<!--<webAppSecurity singleSignonEnabled="false" />-->


<applicationManager autoExpand="true"/>
    <!--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" portNumber="portNumber" password="password" serverName="ipaddress" user="db2admin"/>
    </dataSource>
    <dataSource id="DGAAS_DB" jdbcDriverRef="db2-lib" jndiName="jdbc/DGAAS_DB">
       <properties.db2.jcc databaseName="databasename" portNumber="portNumber" password="password" serverName="ipaddress" user="db2admin"/>
    </dataSource>
</server>
For Oracle: An example of the server.xml file configured to deploy Publishing 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="9081" httpsPort="9444" host="localhost"/>
    <keystore id="defaultKeyStore" password="password"/>
    <classloading useJarUrls="true"/>
   <httpSession cookieSecure="true invalidateOnUnauthorizedSessionRequestException="true"></httpSession>
    <!-- User creation-->
    <httpSession invalidateOnUnauthorizedSessionRequestException="true"/>

<classloading useJarUrls="true"/>

<webContainer deferServletLoad="false"/>

<include location="conf/basicUserRegistry.xml"/>

<include location="conf/application.xml"/>

<executor coreThreads="100"/>

<webAppSecurity ssoRequiresSSL="true" ssoUseDomainFromURL="true" ssoCookieName="rpeLtpaToken2"/>

<!--<webAppSecurity singleSignonEnabled="false" />-->


<applicationManager autoExpand="true"/>
   
    <!--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:port/lib1" user="pub_user"/>
    </dataSource>
    <dataSource id="DGAAS_DB" jdbcDriverRef="OracleLib" jndiName="jdbc/DGAAS_DB">
       <properties.oracle password="password" URL="jdbc:oracle:thin:@//hostname:port/lib1" user="pub_user"/>
    </dataSource>
</server>
An example of the application.xml file configured to deploy Publishing Document Builder:
<?xml version="1.0"?>

-<server>


-<application location="${server.config.dir}/apps/rpeng.war" name="rpeng" id="rpeng" type="war">

<classloader apiTypeVisibility="spec,ibm-api,api" commonLibraryRef="rcl"/>


-<application-bnd>


-<security-role name="pub_user">

<group name="JazzGuests"/>

</security-role>


-<security-role name="pub_report_designer">

<group name="JazzUsers"/>

</security-role>


-<security-role name="pub_admin">

<group name="JazzAdmins"/>

</security-role>

</application-bnd>

</application>


-<application location="${server.config.dir}/apps/dgaas.war" name="dgaas" id="dgaas" type="war">

<classloader apiTypeVisibility="spec,ibm-api,api" commonLibraryRef="rcl"/>


-<application-bnd>


-<security-role name="pub_user">

<group name="JazzGuests"/>

</security-role>


-<security-role name="pub_report_designer">

<group name="JazzUsers"/>

</security-role>


-<security-role name="pub_admin">

<group name="JazzAdmins"/>

</security-role>

</application-bnd>

</application>

</server>
An example of the basicUserRegistry.xml file that is configured to deploy Publishing Document Builder:
<?xml version="1.0" encoding="UTF-8"?>

-<server>

<!--Licensed Materials - Property of IBM(c) Copyright IBM Corporation 2015. All Rights Reserved.Note to U.S. Government Users Restricted Rights:Use, duplication or disclosure restricted by GSA ADP ScheduleContract with IBM Corp. -->



-<featureManager>

<feature>appSecurity-2.0</feature>

</featureManager>


-<basicRegistry realm="Jazz" id="Jazz">

<user password="pub_admin" name="pub_admin"/>

<user password="pub_designer" name="pub_designer"/>

<user password="pub_user" name="pub_user"/>


-<group name="JazzAdmins">

<member name="pub_admin"/>

</group>

<group name="JazzProjectAdmins"> </group>


-<group name="JazzGuests">

<member name="pub_user"/>

</group>


-<group name="JazzUsers">

<member ="pub_designer"/>

</group>

</basicRegistry>

</server>

What to do next

You can deploy and run the Newskeeper sample application that uses document generation service technology for generating document-style reports, and provides a storage interface for document generation service resources and document-style reports. For more details, see Running the Newskeeper sample.

Configure the Publishing Document Builder URL listed on the https://hostname:port/rpeng/login.jsp page. See Publishing Document Builder URLs for an explanation of how each URL is used and tasks for configuring each of the features.