Custom Deployment of Publishing Document Builder on WebSphere Application Server Liberty Profile

You can customize the deployment of Publishing Document Builder on WebSphere® Application Server Liberty Profile.

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 Application Server Liberty Profile:

IBM Db2®
Oracle
Microsoft SQL Server

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

To start the WebSphere Application Server Liberty Profile server that is packaged with Publishing Document Builder, go to the command line and start the server from:
- : Document_Builder_InstallDir\server\server.startup.bat
  For example: C:\Program Files\IBM\DocumentBuilder\server\server.startup.bat
- : 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.
630 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:
- : Document_Builder_InstallDir\server\server.shutdown.bat
  For example: C:\Program Files\IBM\DocumentBuilder\server\server.shutdown.bat
- : 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.
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.
Create a database for the Publishing Document Builder with 16 K pages and UTF-8 code set.
- For Db2: For example, to create a database called pubdb with 16 K pages and the UTF-8 code set, use the following command:
```
db2 CREATE DATABASE pubdb AUTOMATIC STORAGE Yes USING CODESET UTF-8
    TERRITORY US COLLATE USING SYSTEM PAGESIZE 16384;
```
  See the Db2 product documentation for information about creating a database
- For Oracle, see the example in the Create a database and table space section of Configuring WebSphere Application Server with Oracle as a data source
- For SQL Server, create a database. Ensure that you are using the Microsoft JDBC Driver 6.0 for SQL Server.
- For Derby: Not applicable.
For Db2, Oracle, or SQL Server, set the VCAP_SERVICES variable at the top (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":[{}]}
```

Edit the server.xml file to configure the database connectivity for Liberty Profile server.

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:

<library id="MSJDBCLib">
<file name="C:\sqljdbc_8.4\enu\mssql-jdbc-8.4.1.jre8.jar"/>
</library>

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>

For SQL Server


<dataSource id="RPENG" jndiName="jdbc/RPENG_DB">      
<jdbcDriver libraryRef="MSJDBCLib"/><properties databaseName="pubdb" serverName="hostname" portNumber="1433" password="password" user="sa"/>  
</dataSource>  
<dataSource id="DGAAS" jndiName="jdbc/DGAAS_DB">    
<jdbcDriver libraryRef="MSJDBCLib"/><properties 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.

Verify your configuration settings against the server.xml example available at the bottom of this topic in the Example section.
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. By default, the heap memory is set to 4 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. Heap memory can be updated in server.startup.bat file in Document_Builder_InstallDir/server.
1. Update the below 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.
4. To verify the database status, open https://hostname:port/dgaas/debug/db.
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
Where <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:
- : C:\Program Files\IBM\DocumentBuilder\server\liberty\servers\clm\server.xml
- : /opt/IBM/DocumentBuilder/server/liberty/servers/clm/server.xml
When you are prompted, provide your user name and password to authenticate the Publishing 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 basicUserRegistry.xml file and restart the server. See Configuring users for Publishing Document Builder on WebSphere Application Server Liberty Profile topic.
  Tip: The basicUserRegistry.xml file is at Document_Builder_InstallDir\server\liberty\servers\clm\conf\basicUserRegistry.xml

User name	Password
`pub_user`	`pub_user`
`pub_designer`	`pub_designer`
`pub_admin`	`pub_admin`

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>

For SQL server: An example of the server.xml file configured to deploy Publishing Document Builder:

<?xml version="1.0" encoding="UTF-8"?>
<server description="Document builder">

    <!-- Enable features -->
    <featureManager>
    <feature>jsp-2.2</feature>
	<feature>appSecurity-2.0</feature>
	<feature>servlet-3.0</feature>
	<feature>jndi-1.0</feature>
	<feature>jpa-2.0</feature>
	<feature>jdbc-4.0</feature>
    </featureManager>
    <keyStore id="defaultKeyStore" password="{xor}Nj0ycis6PjI=" type="PKCS12" location="ibm-team-ssl.p12"/>
	
    <!-- 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" hostName="*" host="*"/>
	<httpSession invalidateOnUnauthorizedSessionRequestException="true" cookieSecure="true"/>
	
	<classloading useJarUrls="true"/>
	<webContainer deferServletLoad="false"/>
	<include location="conf/basicUserRegistry.xml"/>
	<include location="conf/application.xml"/>
	<executor coreThreads="100"/>	
	<webAppSecurity ssoCookieName="rpeLtpaToken2" ssoUseDomainFromURL="true" ssoRequiresSSL="true"/>
	<!--<webAppSecurity singleSignonEnabled="false" />-->
	<applicationManager autoExpand="true"/>
	
	<!--Database Configuration   -->
	<library id="MSJDBCLib">
		<file name="C:\sqljdbc_8.4\enu\mssql-jdbc-8.4.1.jre8.jar" />
	</library>
	
	<dataSource id="RPENG" jndiName="jdbc/RPENG_DB">
        <jdbcDriver libraryRef="MSJDBCLib"/>
        <properties databaseName="databasename" serverName="ipaddres" portNumber="1433" password="password" user="sa"/>
    </dataSource>

    <dataSource  id="DGAAS" jndiName="jdbc/DGAAS_DB">
        <jdbcDriver libraryRef="MSJDBCLib"/>
        <properties databaseName="databasename" serverName="ipaddres" portNumber="1433" password="password" user="sa"/>
    </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 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 name="pub_designer"/>

</group>

</basicRegistry>

</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 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.