Deploying the web app on WebSphere Application Server

You can deploy the Rational® Publishing Engine web app on WebSphere® Application Server version 8.x or later with IBM® DB2®.

Before you begin

You must install WebSphere Application Server V8.x or later and Rational Publishing Engine with the RPE Remote Services feature before deploying the web app.
You must have access to the following web app files available in the RPE_HOME\remote-services directory:
  • com.ibm.rpe.web.app.ear (or the rpeng.war and dgaas.war files)
Remember: The com.ibm.rpe.web.app.ear enterprise application is a bundle of the two web applications: rpeng.war and dgaas.war. You have one of the following deployment options:
  • Deploy the single com.ibm.rpe.web.app.ear enterprise application
  • Deploy both the rpeng.war and dgaas.war web applications together
The deployment scenario and examples explain how to deploy the single com.ibm.rpe.web.app.ear enterprise application.

Procedure

  1. Set global security.
  2. Set JVM.
  3. Set session management.
  4. Set the environment variable.
  5. Restart the server.
  6. Deploy the web app on the server.
  7. Create a shared library for the dgaas application.
  8. Configure users for the web app on WebSphere Application Server.
  9. Associate shared libraries with applications.
  10. Configure the licensing variable.

Setting global security on WebSphere Application Server

Procedure

  1. Start the WebSphere Application Server.
  2. Open the administrative console in a browser: https://server:port/ibm/console

    For example: https://localhost:9043/ibm/console

  3. Expand Security and click Global security.
  4. In the Application security section, verify that the Enable application security check box is selected.
  5. In the Java™ 2 security section, clear all of the options. If the Warn if applications are granted custom permissions option is selected and cannot be edited:
    1. Select the Use Java 2 security to restrict application access to local resources option. The Warn if applications are granted custom permissions becomes enabled.
    2. Clear the Warn if applications are granted custom permissions option.
    3. Clear the Use Java 2 security to restrict application access to local resources option.
  6. Click Apply.
  7. Click Save to save changes directly to the master configuration.

Results

This is a screen capture of the global security page in the WebSphere Application Server

Setting JVM

About this task

Define the following Java virtual machine (JVM) settings in the custom properties for your application server:
  • com.ibm.websphere.jaxrs.server.DisableIBMJAXRSEngine=true
  • org.eclipse.emf.common.util.URI.archiveSchemes=wsjar wszip jar zip

Procedure

  1. Open the administrative console in a browser: https://server:port/ibm/console

    For example: https://localhost:9043/ibm/console

  2. Expand Servers > Server Types and click WebSphere application servers.
  3. In the Application servers section, click your server link, for example server1.
  4. In the Configuration tab, under the Server Infrastructure section, expand Java and Process Management and click Process definition link.
  5. Under the Additional Properties section, click Java Virtual Machine link.
  6. Under the Additional Properties section, click Custom properties link.
  7. In the Custom properties table, click New.
  8. Under the General Properties section, for each entry specify the following values and click OK:
    Table 1. Custom JVM properties for WebSphere Application Server
    Name Value Description
    com.ibm.websphere.jaxrs.server.DisableIBMJAXRSEngine true Disable IBM JAXRS
    org.eclipse.emf.common.util.URI.archiveSchemes wsjar wszip jar zip  
  9. Click Save to save changes directly to the master configuration.

Results

This is a screen capture of the Comstom properties page from the administrative console of WebSphere Application Server

Setting session management

About this task

Define the following Session Management settings in the custom properties for your application server:
  • InvalidateOnUnauthorizedSessionRequestException=true

Procedure

  1. Open the administrative console in a browser: https://server:port/ibm/console

    For example: https://localhost:9043/ibm/console

  2. Expand Servers > Server Types and click WebSphere application servers.
  3. In the Application servers section, click your server link, for example server1.
  4. In the Configuration tab, under the Container Settings section, click Session management link.
  5. Under the Additional Properties section, click Custom properties link.
  6. In the Custom properties table, click New.
  7. Under the General Properties section, specify the following value and click OK:
    Table 2. Custom Session Management property for WebSphere Application Server
    Name Value Description
    InvalidateOnUnauthorizedSessionRequestException true In response to an unauthorized request, the session manager invalidates a session instead of issuing an UnauthorizedSessionRequestException error message.
  8. Click Save to save changes directly to the master configuration.

Results

This is a screen capture of the Session management properties page from the administrative console of WebSphere Application Server

Setting the environment variable

Procedure

  1. Open the administrative console in a browser: https://server:port/ibm/console

    For example: https://localhost:9043/ibm/console

  2. Expand Servers > Server Types and click WebSphere application servers.
  3. In the Application servers section, click your server link, for example server1.
  4. In the Configuration tab, under the Server Infrastructure section, expand Java and Process Management and click Process definition link.
  5. On the Configuration tab, under the Additional Properties section, click Environment Entries link.
  6. In the Environment Entries table, click New.
  7. Under the General Properties section, for each entry specify the following values, and click OK:
    Table 3. Environment variable properties for WebSphere Application Server
    Name Value Description
    DGAAS_URL http://<server IP>:<port>/dgaas/ Document generation service environment variable
    VCAP_SERVICES {"sqldb":[{}]} When you use DB2 as your database, you must set this environment variable.
    This is a screen captures of the Environment Entries page in the administrative console for WebSphere Application Server.
  8. Click Save to save changes directly to the master configuration.

Restart the WebSphere Application Server

About this task

Restart the WebSphere Application Server profile that you want to deploy the web app (com.ibm.rpe.web.app.ear, or alternatively the rpeng.war and dgaas.war files):

Procedure

  1. Stop the WebSphere Application Server.
  2. Start the WebSphere Application Server.

Deploying the web app on WebSphere Application Server

Before you begin

  • Create a database for Rational Publishing Engine in DB2
  • Create the rpeng data source with the JNDI name: RPENG_DB
  • Create DGAAS data source with the JNDI name: DGAAS_DB
For details, see Configuring WebSphere Application Server with DB2 as a data source.

Procedure

  1. Open the administrative console in a browser: https://server:port/ibm/console

    For example: https://localhost:9043/ibm/console

  2. Expand Applications and click New Application.
  3. Click New Enterprise Application.
  4. In the Preparing for the application installation window, specify the path to com.ibm.rpe.web.app.ear on a local or remote file system:
    • If you are using a local file, select Local file system.
    • If you are using a remote file, select Remote file system.
    Type or click Browse to specify the path to the com.ibm.rpe.web.app.ear file. By default, the archive file is located in RPE_HOME\remote-services\com.ibm.rpe.web.app.ear.
  5. Click Next.
  6. Select Fast Path - Prompt only when additional information is required and click Next.
  7. In the Select these installation options page, accept the default settings, and click Next.
    This is a screen capture of the Select these install options page in the administrative console for WebSphere Application Server
  8. In the Map modules to servers page, select the Rational Publishing Engine and DGaaS module and click Next.
  9. In the Map resource references to resources page, you must specify the data source for the Rational Publishing Engine and DGaaS modules.
    Tip: To continue with this step, you must complete the steps in Configuring WebSphere Application Server with DB2 as a data source topic.
    1. For the Rational Publishing Engine module entry, in the Target Resource JNDI Name column, click Browse.
      This is a screen capture of the Map resource references to resources page in the administrative console of WebSphere Applicaiton Server.
    2. In the New Application page, select the rpeng option with the JNDI name set to RPENG_DB.
      This is a screen capture of the New Application page of the administrative console for WebSphere Application Server.
    3. Click Apply.
    4. Repeat the steps similarly for the DGaaS module entry, in the Target Resource JNDI Name column, click Browse.
    5. In the New Application page, select the DGAAS option with the JNDI name set to DGAAS_DB.
    6. Click Apply.
    7. Click Next.
    This is a screen capture of the Map resource refernces to resources page in the administrative console for WebSphere Application Server.
  10. In the Map virtual hosts for Web modules page, select Rational Publishing Engine and DGaaS and click Next.
  11. Review the Summary, and click Finish.
    This is a screen capture of the Summary page in the administrative console in the WebSphere Application Server.
  12. To confirm that your web app is deployed on the server successfully, search for the following output message that displays in the process log:
    Application com.ibm.rpe.web.app installed successfully.
  13. Click Save to save changes directly to the master configuration.
    This is a screen capture of the process log page of the administrative console for WebSphere Application Server.
  14. Expand Applications > Application Types and click WebSphere enterprise applications. The com.ibm.rpe.web.app application you added is listed as the application name you entered.
  15. In the Name column, click com.ibm.rpe.web.app link.
    This is a screen capture of the Enterprise Applications page of the administrative console for WebSphere Application Server.
  16. In the Detail Properties section, click Class loading and update detection link.
  17. In the Class loader order section, select Classes loaded with local class loader first (parent last), and click OK.
    This is a screen capture of the Class Loader page in the administrative console in WebSphere Application Server.
  18. Verify the context roots of the com.ibm.rpe.web.app application:
    1. Under the Web Module Properties section, click Context Root for Web Modules.
    2. Verify that the context root specified for the web modules matches the following values, and then click OK:
      Table 4. Verifying context roots for com.ibm.rpe.web.app application
      Web module URI Context Root
      Rational Publishing Engine com.ibm.rpe.web.ui.war, WEB-INF/web.xml rpeng
      DGaaS com.ibm.rpe.web.service.docgen.war, WEB-INF/web.xml dgaas
      This is a screen capture of the Context Root page in the administrative console for WebSphere Application Server
    3. On the Configuration tab, click OK.
  19. Click Save to save changes directly to the master configuration.
  20. Start the web app on the server:
    1. Select the com.ibm.rpe.web.app check box and click Start.
    2. If the web app starts on the server successfully, the following message displays:
      Application com.ibm.rpe.web.app on server server_name and node node_name started succesfully.  The collection may need to be refreshed to show the current status.
      This is a screen capture of the Enterprise applications page of the administrative console for WebSphere Application Server.

Configure users for the web app on WebSphere Application Server

About this task

To complete this task, you must complete the steps in the Configuring users for the web app on WebSphere Application Server

Creating a shared library for the dgaas application

Procedure

  1. Go to the Shared libraries page.
  2. Click Environment > Shared libraries in the console navigation tree.
  3. Select a shared library scope. Change the scope of the collection table to see what shared libraries are in a particular cell, node or server. Select the Node and Server option.
    Shared libraries scope page
  4. Click New.
  5. Specify the name, for example, dgaas.ear.
  6. Specify the class path for the following HTTP .jar files:
    <WAS_HOME>\profiles\AppSrv01\installedApps\<cell Name>\com.ibm.rpe.web.app.ear\dgaas.war\WEB-INF\lib\org.apache.httpcomponents.httpclient_<version>.jar
    <WAS_HOME>\profiles\AppSrv01\installedApps\<cell Name>\com.ibm.rpe.web.app.ear\dgaas.war\WEB-INF\lib\org.apache.httpcomponents.httpcore_<version>.jar
  7. Select the Use an isolated class loader for this shared library class loading option, and click OK.
    Shared libraries page for container-wide shared library
  8. Click Save to update your changes to the master configuration.

What to do next

Tip: Starting in Rational Publishing Engine version 2.0.1, you no longer need to create the additional shared library, rpe.lib, to consume a license. The product now automates this task.

Associating shared libraries with applications

Procedure

  1. Click Applications > Application Types > WebSphere enterprise applications > com.ibm.rpe.web.app > Shared library references to access the Shared library references page.
    Shared libraries page for rpe.lib
  2. On the Shared library references page, select an application to which you want to associate a shared library, in this case com.ibm.rpe.web.app.
  3. Click Reference shared libraries.
    Shared libraries references page
  4. On the Shared library mapping page, select the dgaas.ear shared library that the application or modules use.
  5. Click >> to move the libraries from the Available list to the Selected list.
    Shared libraries mapping page
  6. On the Shared library references page, click OK.
  7. Save the changes to the master configuration.

Configuring the licensing variable

Procedure

  1. Verifying the TELELOGIC_LICENSE_FILE environment variable.
  2. Restart WebSphere Application Server.

Results

You can confirm that the web app is deployed by opening the following URL in a browser: http://server:port/rpeng/
Tip: You might encounter the following error message in the web browser:
Error 500: com.ibm.websphere.servlet.session.UnauthorizedSessionRequestException:
    SESN0008E: A user authenticated as anonymous has attempted to access a session owned by
    user:defaultWIMFileBasedRealm/uid=rpe_designer,o=defaultWIMFileBasedRealm.
To resolve this error message, verify that you set the InvalidateOnUnauthorizedSessionRequestException session management property to true in the custom properties for WebSphere Application Server. For more details, see the Setting session management section of this topic.

You can log in by providing the user name and password of the appropriate user, such as rpe_admin, rpe_designer or rpe_user and click Log in.

This is a screen capture of the web app log in screen.

The following Rational Publishing Engine web app should display in your browser:

Web app home page

You can verify the status of the document generation service by entering http://server:port/dgaas/debug in a browser.

Web app home page

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 web app listed on the http://server:port/rpeng/ page. See Web app URLs for an explanation of how each URL is used and tasks for configuring each of the features.

Feedback