Level: Advanced Michael A. Ahern (ahern@us.ibm.com), Content Manager Partner Enablement, IBM
08 Dec 2005 Integrate the IBM DB2® Content Manager V8.3 eClient with another application using the eClient as the controlling, or initial, application and invoke the other application to perform that application's business functions.
Introduction
There are several existing papers and books that describe how to modify the eClient’s look and feel or to invoke eClient functions from another application with the other application being the controlling, or initial, application. A good example is the Redbook "eClient 101 Customization and Integration" (IBM, October 2003), which discusses how to integrate IBM DB2 Content Manager Version 8 eClient with a Siebel CRM application. The integration allows Siebel end users to retrieve and view documents stored in IBM DB2 Content Manager Version 8 system.
This article provides examples of the different integration options. These examples show one implementation of the concepts and should not be assumed to be the only way these integrations can be accomplished.
Integration options
Adding a custom function to the action list - old style
The "eClient 101 Customization and Integration" Redbook shows an example of adding a function to the search results page pulldown action list. This type of integration would allow for the invoking of a servlet that would forward the request to another application.
This integration is accomplished by modifying the action list and requires modification of at least two JSP files supplied with the eClient. These JSP files need to be modified again after each eClient fixpack is applied.
This type of integration would be controlled manually by the user making the decision to send the item to be processed by the other application.
An example of this type of integration will not be shown in this document.
Adding a custom function to the acton list - new style
With Version 8.3 of IBM DB2 Content Manager, IBM introduced support for user-defined actions.
The customer can create user-defined actions in the IBM DB2 Content Manager System Administration Client that can be added to action lists that can be assigned to a work node. These actions implement customer business logic by writing a servlet or JSP page, which can be launched by the eClient application server.
The user-defined action can be of the following application types:
- Web client (Java Server Page (JSP))
- Desktop client (user exit Dlls)
- Both
The eClient server supports the Web client application type that:
- Must be deployed under the context root of eClient application
- Can optionally accept a parameter of workid (work package pidstring)
This type of integration would be controlled manually by the user making the decision to send the item to be processed by the other application.
- A JSP, in this example called "redir.jsp," is created that has some very simple logic in it. Its function is to read a properties file to determine where the processing of the item should be redirected to. It then redirects the request to that application. This JSP file is copied to $IBMCMROOT/CMeClient/installedApps/eClient.ear/eclient.war.
- Using the CM System Administration Client:
- A new document routing action is created that uses this JSP.
- A new action list is created that includes this new action along with any other predefined CM actions you need.
- A new work basket that uses this action list is created.
- A new worklist is created that includes the new work basket.
- The new work basket is included in a document routing process.
Alternately, existing action lists, work baskets, and worklists can be modified to use the new action. See the example below.
For an automated way to invoke the other application seamlessly from the user’s point of view, see the following sections.
Modifying eClient JSP files
There is a main JSP provided with the IBM DB2 Content Manager eClient that controls the viewing of items:
Normally, this JSP will invoke the IDMDocViewer servlet or the IDMObjectServlet servlet when the Open function is selected. The IDMObjectServlet is invoked if the applet viewer has been enabled. If the applet viewer is not enabled, the IDMDocViewer is invoked.
A servlet, in this example called "DecideRoute," is created that has some very simple logic in it. Its function is to look at the item type of the item being opened and determine if it is one of the item types the other application needs to process. If that servlet decides the item is of a type to be processed by the other application, it redirects the request to that application. If not, the servlet queries the HTTP request attribute "toServlet" to determine the name of the servlet to forward the request to and then does so.
There are three eClient modification steps required for this integration:
- The Heading.jsp is modified to set either IDMDocVewer or IDMObjectServlet as an attribute of the HTTP request called "toServlet." $IBMCMROOT/CMeClient/installedApps/eClient.ear/eclient.war/pageComponents/Heading.jsp. There is already code in the Heading.jsp for Inbound Integration.
The end of the existing inbound integration code looks like this:
Listing 1. End of the existing inbound integration code
// LEAVE Integration Enablement.
//
//@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
%>
|
The following code is added to the Heading.jsp after the existing integration enablement and before the closing ‘%>’:
Listing 2. Code added to the Heading.jsp
// Outbound Application Integration - add these 4 lines of code and change every
// reference to "IDMDocViewer" and "IDMObjectServlet" to reference "DecideRoute"
if(bViewerAppletEnabled)
request.getSession().setAttribute("toServlet","IDMObjectServlet");
else
request.getSession().setAttribute("toServlet","IDMDocViewer");
// End Outbound Application Integration
|
Throughout the Heading.jsp, all references to IDMDocViewer or IDMObjectServlet are changed to reference DecideRoute.
- The application descriptor web.xml file for the Web client needs to be modified to add the DecideRoute servlet. Here is an example (the servlet number may vary by implementation):
Listing 3. Modify the web.xml file to add the DecideRoute servlet
<servlet id="Servlet_27">
<servlet-name>DecideRoute</servlet-name>
<servlet-class>my.test.DecideRoute</servlet-class>
</servlet>
<servlet-mapping id="ServletMapping_27">
<servlet-name>DecideRoute</servlet-name>
<url-pattern>/DecideRoute</url-pattern>
</servlet-mapping>
|
The web.xml file must be modified in two directories:
- $IBMCMROOT/CMeClient/installedApps/eClient.ear/eclient.war/WEB-INF/web.xml
- $WAS_HOME/config/cells/<node name>/applications/eClient.ear/deployments/eClient/eclient.war/WEB-INF/web.xml
- The jar file that contains the DecideRoute.class is put into directory $IBMCMROOT/CMeClient/installedApps/eClient.ear/eclient.war/WEB-INF/lib. The eClient is already configured in WAS to look for jar files in this directory.
Steps 1 through 3 need to be done the first time the integration is installed and then again after each eClient fixpack is applied. Since IBM can change the design and function of the eClient with any fixpack, all the IBM supplied JSPs need to be analyzed after each fixpack to determine if any JSP files other than Heading.jsp need modification. See the example below.
Adding a servlet filter
Servlet filters were introduced in the 2.3 version of Java Servlet Specification, which is implemented in J2EE 1.3. For Version 8.3 of the eClient, the product installation has a prerequisite of WebSphere® Application Server V5.1.1. WAS 5.1.1 can run applications that are either J2EE 1.3 or J2EE 1.2 compliant.
A filter, in this example called "DecideRouteFilter," is created that has some very simple logic in it. Its function is to look at the item type of the item being opened and determine if it is one of the item types the other application needs to process. If the filter decides the item is of a type to be processed by the other application, it redirects the request to that application. If not, the filter exits and the servlet it was attached to is processed.
The eClient is still being deployed as a J2EE 1.2 compliant application. To be able to use servlet filters as an integration point with the eClient, several modifications are needed to make WAS treat it like a J2EE 1.3 compliant application.
If you make these changes, you cannot use connection pooling with the eClient.
- Modify the application.xml dtd definition line
From
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN"
"http://java.sun.com/j2ee/dtds/application_1_2.dtd"> |
To
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
"http://java.sun.com/dtd/application_1_3.dtd"> |
This tells the application server that the application is J2EE 1.3 compliant. The rest of the application.xml file is left unchanged. The application.xml file must be modified in two directories:
- $IBMCMROOT/CMeClient/installedApps/eClient.ear/META-INF/application.xml
- $WAS_HOME/config/cells/<node name>/applications/eClient.ear/deployments/eClient/META-INF/application.xml
- For the application server to know to apply the 2.3 Servlet Specification to this application, the web.xml dtd definition line needs to be modified
From
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> |
To
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd"> |
The web.xml file must be modified in two directories.
- $IBMCMROOT/CMeClient/installedApps/eClient.ear/eclient.war/WEB-INF/web.xml
- $WAS_HOME/config/cells/<node name>/applications/eClient.ear/deployments/eClient/eclient.war/WEB-INF/web.xml
- The filter definition and filter mappings need to be added to the web.xml file. For this example, the filter is called "DecideRouteFilter." The filter will be applied to two servlets -- "IDMObjectServlet" and "IDMDocViewer."
These lines are added after the <display-name> stanza:
Listing 4. Lines added after the <display-name> stanza
<filter>
<filter-name>DecideRouteFilter</filter-name>
<display-name>DecideRouteFilter</display-name>
<filter-class>my.test.DecideRouteFilter</filter-class>
<init-param>
<param-name>path</param-name>
<param-value>OBA.properties</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>DecideRouteFilter</filter-name>
<url-pattern>/DecideRouteFilter</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>DecideRouteFilter</filter-name>
<servlet-name>IDMObjectServlet</servlet-name>
</filter-mapping>
<filter-mapping>
<filter-name>DecideRouteFilter</filter-name>
<servlet-name>IDMDocViewer</servlet-name>
</filter-mapping>
|
The web.xml file must be modified in two directories:
- $IBMCMROOT/CMeClient/installedApps/eClient.ear/eclient.war/WEB-INF/web.xml
- $WAS_HOME/config/cells/<node name>/applications/eClient.ear/deployments/eClient/eclient.war/WEB-INF/web.xml
The "OBA.properties" file is used to pass information to the filter. This will be discussed in the next section.
- The jar file that contains the DecideRouteFilter.class is put into directory $IBMCMROOT/CMeClient/ installedApps/eClient.ear/eclient.war/WEB-INF/lib. The eClient is already configured in WAS to look for jar files in this directory.
Since the eClient is shipped as a J2EE 1.2 compliant application, steps 1 through 4 need to be done the first time the integration is installed and then again after each eClient fixpack is applied.
When the eClient is deployed and shipped as a J2EE 1.3 compliant application, only steps 3 and 4 would be required for this type of integration. See the example below.
Examples
Code samples are supplied in a separate zip file. (See Download.) These examples discuss those samples and how they are used.
A properties files, two Java classes, and an external application are used by all three examples.
- OBA.properties
This file contains attributes that describe how to find the external application and how to access it. It also has information on which Content Manager item types should be redirected to the external application when doing automated forwarding. This properties file is placed in $IBMCMROOT/CMeClient/.
- OBAProperties.java
A very simple bean used to store and retrieve properties from the HTTP session context.
- ReadOBAProperties.java
Reads the OBA.Properties file and stores the properties in the HTTP session context using OBAProperties.java.
- WebProjEAR.ear
A simple Web application that can be deployed on WAS to be used as the external application to redirect to for testing. It just pops up an HTML page.
A sample JSP called "redir.jsp" is also provided to demonstrate adding a custom function to an action list.
Custom function for action list
The sample redir.jsp is provided in the samples zip file. The section "Adding a Custom Function to the Acton List - new style" above lists the CM system administration steps to implement a user-defined action. The following are screen captures showing these steps:
Figure 1. Define a new action that uses the JSP you created
Figure 2. Create an action list that includes the new action
Figure 3. Create a work basket that uses the action list
Figure 4. Create a worklist that includes the work basket
Figure 5. Use the work basket in a process
Figure 6. The eClient showing the action available in the worklist
Modifying eClient JSP files
As described in the "Modifying eClient JSP files" section above, modifications are made to the Heading.jsp to invoke a servlet called DecideRoute, and the web.xml is modified to define that servlet to the application.
The DecideRoute servlet sample :
- Extracts the item PID from the HTTP request.
- Gets the Content Manager connection information out of the HTTP session to be able to pass it to the next application.
- Reads the OBA_propertes file to retrieve the information about where the other application is.
- Determines if the item type described by the PID is the item template. The item template is the CM item type that contains the list of the item types to be processed by the other application. If this item is the item template, it is redirected to the other application. The item template used for this example is provided in the OBA_Items.xsd file that can be imported using the CM System Administration Client.
- Queries the item template to see if the item being processed is listed as one of the items to be redirected. If it is in the list, it is redirected to the other application. If it isn't, it is forwarded to the eClient servlet it was originally destined for, either the IDMDocViewer servlet or the IDMObjectServlet servlet. An item type to be redirected is provided in the OBA_eForm1.xsd file that can be imported using the CM System Administration Client.
You will need to write a quick program to insert an item of the OBA_Items item type with an attribute value of 'OBA_eForm1' and insert an item of the OBA_eForm1 item type that can be used for testing.
Servlet filter
As described in the "Adding a servlet filter" section above, modifications are made to the application.xml and web.xml to invoke a servlet filter called DecideRouteFilter.
The DecideRouteFilter servlet sample :
- Extracts the item PID from the HTTP request.
- Gets the Content Manager connection information out of the HTTP session to be able to pass it to the next application.
- Reads the OBA_propertes file to retrieve the information about where the other application is.
- Determines if the item type described by the PID is the item template. The item template is the CM item type that contains the list of the item types to be processed by the other application. If this item is the Item template, it is redirected to the other application. The item template used for this example is provided in the OBA_Items.xsd file that can be imported using the CM System Administration Client.
- Queries the item template to see if the item being processed is listed as one of the items to be redirected. If it is in the list, it is redirected to the other application. If it isn’t, the filter exits and the servlet it was attached to is processed.
You will need to write a quick program to insert an item of the OBA_Items item type with an attribute value of ‘OBA_eForm1’ and insert an item of the OBA_eForm1 item type that can be used for testing.
Download | Description | Name | Size | Download method |
|---|
| Code Samples | eClient_Integration_Samples.zip | 57 KB | FTP |HTTP |
|---|
Resources Learn
-
IBM DB2 Content Manager Enterprise Edition Version 8.3 publication library: The eClient Installation and Configuration Guide, as well as all the IBM DB2 Content Manager V8.3 documentation, can be reviewed here.
-
"eClient 101 Customization and Integration" (IBM, October 2003): This IBM Redbook provides a basic introduction to IBM DB2 Content Manager Version 8 eClient. By providing helpful, easy-to-understand sample codes, and step-by-step instructions, this Redbook will help you in your next eClient integration and customization project.
-
developerWorks DB2 zone: Learn more about DB2. Find technical documentation, how-to articles, education, downloads, product information, and more.
Get products and technologies
Discuss
About the author | | | Mike Ahern has more than 15 years of experience with the DB2 family of products and more than three years of experience with DB2 Content Manager. His current assignment is with the Content Manager Partner Enablement team assisting business partners with integrating DB2 Content Manager into their solutions. Mike is a DB2 Certified Solutions Expert (Content Manager, Database Administration, and Application Development). |
Rate this page
| 
