Integrating with BPF Web Application

The IBM® FileNet® BPF Integration Servlet (Bp8IntegrationServlet) is designed to allow for the leveraging of reusable BPF components from external applications, including Workplace, with a minimal amount of coding.

This help topic focuses on integration with Workplace. It covers the following topics:

• Command overview tells you how to send a command to the Bp8IntegrationServlet.
• Response overview describes the core parameters returned by the Bp8IntegrationServlet.
• Label encoding/decoding URL parameters describes the FileNet utility for encoding and decoding qualifying parameters.
• Example: Invoking a command shows sample JSP pages for invoking a command and handling the response parameters.
• Invoking IntegrationServlet online help shows you how to invoke online help as you develop your custom pages.
• Command reference describes all of the commands supported by the Bp8IntegrationServlet.
• Integrating with Workplace describes the steps required to integrate the Bp8IntegrationServlet with Workplace.
• Integrating with Process Engine (PE) e-mail notification describes the steps required to integrate the Bp8IntegrationServlet with PE work assignment e-mail notifications.
  

Command overview

Web-based thin clients use request URLs to send commands to the Bp8IntegrationServlet. The following example shows a basic call to the Bp8IntegrationServlet:

http://<host>:<port>/bpf/Bp8IntegrationServlet?_commandId=<id>&_modeId=<modeId>&_responseURL=<url>[&_windowTitle=<title>&ut=<user token>]&caseId=<caseId>&caseGuid=<caseGuid>&objectStoreName=<objectStoreName>&timeZone=<timeZone>

The following table describes the parameters passed to the Bp8IntegrationServlet. Note that some parameters may contain values with double-byte characters, and, therefore, must be label-encoded with a FileNet utility. Other parameters must be URL-encoded with the Java™ API method URLEncoder.encode.

In addition to the parameters listed above, users should also include the command-specific parameters. Command-specific parameters are covered in the Command reference.

To call the Bp8IntegrationServlet from an external application requires the user know the base URL of the BPF application. In a High Availability environment, the URL needs to point to a load balancing server. You can obtain the base URL on the client side with a getBaseURL() JavaScript™ call.

Response overview

When a command has completed, the Bp8IntegrationServlet redirects the user back to the page in the calling application, which was specified in the _responseURL parameter of the command, as long as the _mode parameter of the command is set to 2. The URL contains a query string containing the response information in the form of parameter/value. For example:

http://<host>:<port>/externalApp/responseResult.jsp?_returnCode=0&_commandId=9000

The page should be coded to read the response parameters and act on them according to the requirements of your application.

Each response will minimally be populated with the following three status parameters in the request string:

• _returnCode contains a numeric return code value. Possible values are:
  
  

  Constant Name	Value	Description
  RETURN_CODE_SUCCESS	0	Success
  RETURN_CODE_EXCEPTION	1040	Exception thrown

• _commandId contains the ID of the command that was originally invoked.
• _message is an optional parameter that contains an error message if the command did not succeed. Note that _message is label-encoded and must be label decoded with a FileNet utility.
  
  Other returned parameters are specific to the command that was executed. Some returned parameters may have to be label decoded.

Label encoding/decoding URL parameters

Some URL parameters passed to and from the Bp8IntegrationServlet may contain values with double-byte characters, such as objectStoreName or ;label. You must label-encode these parameter values on the request, and decode them on the response.

Workplace includes an encode/decode utility class, WcmEncodingUtil. It is located in the com.filenet.wcm.toolkit.util package, in p8toolkit.jar.

To encode a command parameter value, use the static method encodeLabel(...). Note that a parameter requiring label encoding must be encoded even if its value has been URL encoded with the Java API method URLEncoder.encode().

To decode a response parameter value, use the static method decodeLabel(...).

NOTE  In a J2EE Web Application, request parameters that are label-encoded must be explicitly decoded. URL-encoded parameters are decoded automatically when returned from request.getParameter(...).

Example: Invoking a command

Below are two JSP listings. The first is a user interface module JSP from an external application. It simply renders an HTML anchor link that invokes the Bp8IntegrationServlet in a BPF application. The second JSP listing handles the response parameters from the call to the Bp8IntegrationServlet. This JSP page is specified in the _responseURL parameter of the HTML link rendered by the user interface module JSP.

User interface module JSP that calls Bp8IntegrationServlet

In the following code listing, a user token is included in the call to the Bp8IntegrationServlet. The token is retrieved from the credentials servlet, WcmWorkplaceCredentialsServlet.

NOTES 

• The user ID and password passed to the servlet must first be label-encoded. Some IntegrationServlet parameter values require label-encoding as well.
• WcmWorkplaceCredentialsServlet is referenced by setCredentials, the URL pattern to which the servlet is mapped. The credentials servlet returns the token in a URL-encoded format. For details on getting tokens, see User Tokens.
• An HTML link is created that calls into IntegrationServlet, using the bp8IntegrationWebBasedCommand URL pattern. It includes the numeric command ID for View Case, which invokes a BPF JSP that displays the Case in the Case Query mode. It also includes parameters for the user token and window title. Lastly, it includes the URL-encoded _responseURL parameter, which specifies the page in the calling application to handle the response from the invoked command.

<%@ page import="com.filenet.wcm.toolkit.util.*, java.net.*, java.io.* "%>
   <% // Label-encode token parameter values
      String userid=WcmEncodingUtil.encodeLabel("suser");
      String password=WcmEncodingUtil.encodeLabel("greetings");
      String timeZone=WcmEncodingUtil.encodeUTF8URL("GMT 08:00");
   %>
   <% // Get token
      String token;
      URL url =new URL( "http","moorea",8080,"/Workplace/setCredentials?op=getUserToken&userId="+userid+"&password="+password);


      URLConnection conn=url.openConnection();
      ((HttpURLConnection)conn).setRequestMethod("POST");
      InputStream contentFileUrlStream=conn.getInputStream();
      BufferedReader br=new BufferedReader(new InputStreamReader(contentFileUrlStream));
      token=br.readLine();
   %>

   <% // Label-encode Bp8IntegrationServlet parameters values that require it
      String windowTitle=WcmEncodingUtil.encodeLabel("Custom Application");
      String objStore=WcmEncodingUtil.encodeLabel("Dev1 FS");
   %>

   <% // URL-encode IntegrationServlet parameters values that require it
      String responseURL = URLEncoder.encode("http://moorea:8080/custom/thinClientOperations/OperationResult.jsp");
   %>

   <% // Call Bp8IntegrationServlet from browser link
      out.println("<p><a href=\"http://moorea:8080/bpf/Bp8IntegrationServlet"+
      "?_commandId=9010"+
      "&ut="+ token+
      "&_windowTitle="+ windowTitle+
      "&_mode=2"+
      "&timeZone=" + timeZone +
      "&_responseURL="+responseURL + "\" target=\"_self\">"+
      "Process Case (9010)</a></p>");
   %>  

JSP that handles Bp8IntegrationServlet response

The following code is from responseResult.jsp, specified in the _responseURL parameter in the call to the Bp8IntegrationServlet in the above listing. This JSP simply iterates through its request parameters and prints out the parameter names and values.

<!-- This is a sample page to demonstrate Response handling from Bp8IntegrationServlet -->
<%@ page import="com.filenet.wcm.toolkit.util.*, java.util.*, java.io.*" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>BPF Integration Servlet: Response Parameters</title>
</head>
<body>
<%
String sParm;
String sString;
Enumeration enum = request.getParameterNames();
out.println("<table border='0'> ");
while(enum.hasMoreElements())
{
sParm = enum.nextElement().toString();
out.println("<Tr>");
out.println("<TD><b>"+sParm + ":</b> ");
sString = request.getParameter(sParm);
if (sParm.equalsIgnoreCase("objectStoreName") || sParm.equalsIgnoreCase("label") || sParm.equalsIgnoreCase("_message"))
out.println(WcmEncodingUtil.decodeLabel(sString));
else
out.println(sString);
out.println("</TD></Tr>");
}
out.println("</table>");
%>
</body>
</html>

Invoking BPF Integration Servlet online help

As a development aid, the Bp8IntegrationServlet includes online help for all of its supported commands. To invoke the list of available commands, enter the URL shown below in your browser's address box, specifying the host and port of your BPF installation. Exclude the query string on the URL.

http://<host>:<port>/bpf/Bp8IntegrationServlet

For details on a command, click its ID link.

Command reference

This section describes the URL-based commands supported by the Bp8IntegrationServlet. Unless otherwise specified, input parameters are optional. If you don't specify an optional parameter, the Bp8IntegrationServlet will ignore the parameter.

Command-specific parameters requiring label encoding or decoding are so indicated. As discussed in the Command overview, some Bp8IntegrationServlet URL parameters must be label-encoded or URL-encoded, if you choose to use them.

NOTE  In a J2EE Web application, request parameters that are label-encoded must be explicitly decoded. URL-encoded parameters are decoded automatically when returned from request.getParameter(...). This would include the _responseURL parameter.

The table below lists the commands according to functional groups. For details on a specific command, click the applicable link. You can also get online command help from the Bp8IntegrationServlet.

View Case

Process Case

Integrating with Workplace

In order to enable viewing and processing of Case custom objects from Workplace, a URL to the Bp8IntegrateServlet is placed in Action.xml and InfoPages.xml in the OpenCase objectKey tag.

Structure of Actions.xml

Actions are used to invoke the Bp8IntegrationServlet via a right-click context menu. Actions.xml contains the definitions of actions displayed in the context menu, multi-select menu, and on Information pages. The file is located in Workplace/WEB-INF folder. Actions.xml follows the Workplace Preferences XML Schema, Preferences.xsd, located in Workplace/WEB-INF/xml.

NOTE  Back up Actions.xml before modifying it. After modifying Actions.xml, reload it from Workplace to avoid restarting the Application Engine (AE).

As shown in the listing below, Actions.xml consists of three sections: topLevelActions, multiSelectActions, and actionDefinitions. In the topLevelActions array and in the multiSelectActions array, you define the order of the actions as they appear in the user interface. That is, in the topLevelActions array, the order of the value elements is reflected in the context menu and on the Information pages. In the multiSelectActions array, the order of the value elements is reflected in the multi-select menu. You can hide actions by commenting them out.

In the multiSelectActions array, you can specify actions to be multi-select only; that is, a multi-select action does not have to be listed in the topLevelActions array.

The actionDefinitions list consists of actionDefinition objects, each of which contains a list of conditions which define whether the action is displayed for each individual object. Note that a top-level action can contain a submenu, and if it does, its action definition must include a subActions setting. Also note that the definition for an action listed in the multiSelectActions array must include a multiSelectURL setting.

To add Bp8IntegrationServlet actions, add the object element with the applicable settings. Refer to the section highlighted in red as a Bp8IntegrationServlet configuration sample.

Sections in the actions descriptor XML file

<object key="actionsConfiguration" version="3.0">
  <array key="topLevelActions">
    <value>download</value>
    <!--<value>checkout</value>   These 3 actions are
    <value>cancelCheckout</value> commented out; they
    <value>checkin</value>        won't appear in Workplace UI-->
    <value>save</value>
    <value>file</value>
    <value>unfile</value>
    <value>deleteVersions</value>
    <value>delete</value>
    <value>move</value>
    <value>addToWeb</value>
    <value>removeFromWeb</value>
    <value>demoteVersion</value>
    <value>promoteVersion</value>
    <value>addToShortcuts</value>
    <value>addDocument</value>
    <value>addFolder</value>
    <value>openCase</value>
     ...
  </array>
     ...
  <list key="actionDefinitions">
    <object key="actionDefinition">
      <setting key="id">download</setting>
      <setting key="title" localizationKey="server.Actions_xml.download"> Download</setting>
      <setting key="url">
        getContent?
        mode=download&amp;
        objectType={OBJECT_TYPE}&amp;
        id={OBJECT_ID}&amp;
        vsId={VERSION_SERIES_ID}&amp;
        objectStoreName={OBJECT_STORE_NAME}
      </setting>
      <setting key="multiSelectURL">
        operations/WcmMultiDownloadObject.jsp?
        returnUrl={RETURN_URL}
      </setting>
      <setting key="img">images/action/Download16.gif</setting>
      <setting key="showInPath">false</setting>
      <setting key="hideInThickClientWindow">true</setting>
      <array key="objectTypes">
        <value>document</value>
      </array>
    </object>
    <object key="actionDefinition">
      <setting key="id">openCase</setting>
      <setting key="title" localizationKey="server.Actions_xml.openInCaseQuery">Open Case </setting>
      <setting key="url">
        http://rangiroa:7001/bpf/Bp8IntegrationServlet?
        _commandId=9000&amp;
        id={OBJECT_ID}&amp;
        objectStoreName={OBJECT_STORE_NAME}&amp;
        timeZone={TIME_ZONE}&amp;
        objectType={OBJECT_TYPE}
      </setting>
      <setting key="showInPath">false</setting>
      <setting key="hideInThickClientWindow">true</setting>
      <array key="objectTypes">
        <value>customobject</value>
      </array>
    <array key="classes">
      <value>{63F8AA94-E2B9-11D0-ADF6-00C04FB66DAD}</value>
      <value>{A73BEEB2-B0B7-11D2-8853-0000F80883E3}</value>
    </array>
    <setting key="isPopup">false</setting>
    <setting key="useToken">true</setting>
    <setting key="requestWindowId">false</setting>
    </object>
</list>
</object>

Configuration settings in Actions.xml

The following table describes each action definition setting in Actions.xml required to integrate the Bp8IntegrationServlet. Each setting is identified by its key attribute. Unless otherwise specified, each setting is optional. If an optional setting is not present, its default value is used.

NOTE  To circumvent restarting AE, you can reload modified settings from Workplace Site Preferences.

Structure of InfoPages.xml

As shown in the listing below, InfoPages.xml consists of two sections. The first is a list of one or more custom Information pages. The second is an object element specifying the default Information page. The default Information page is invoked if an object's object type, content type, or class ID does not match any of the criterion in the list of custom Information pages.

To add a Bp8IntegrationServlet infoPage, add an infoPage object element with the applicable settings. Refer to section highlighted in red as a Bp8IntegrationServlet configuration sample. Refer to Settings as described in Configuration Settings in InfoPages.xml.

<object key="objectInfoPages" version="3.0">
<!-- list of custom Information pages -->
  <list key="pages">
   <object key="infoPage">
    <array key="objectTypes">
      <value>document</value>
    </array>
    <array key="contentTypes">
      <value>text/plain</value>
    </array>
    <setting key="url">properties/customInfo1.jsp</setting>
    <setting key="isPopup">true</setting>
    <setting key="popupHeight">250</setting>
    <setting key="popupWidth">550</setting>
    <setting key="useToken">true</setting>
   </object>
   <object key="infoPage">
    <array key="objectTypes">
      <value>customobject</value>   
    </array>
    <array key="classes">
      <value>{63F8AA94-E2B9-11D0-ADF6-00C04FB66DAD}</value>
      <value>{A73BEEB2-B0B7-11D2-8853-0000F80883E3}</value>
    </array>
    <setting key="url">http://rangiroa:7001/bpf/Bp8IntegrationServlet?_commandId=9000&amp;timeZone={TIME_ZONE}</setting>
    <setting key="isPopup">true</setting>
    <setting key="popupHeight">550</setting>
    <setting key="popupWidth">650</setting>
    <setting key="useToken">true</setting>
   </object>
   ...
  <list/>

  <!-- default Information page -->
  <object key="defaultInfoPage">
    <setting key="url">properties/ObjectInfo.jsp</setting>
    <setting key="isPopup">false</setting>
    <setting key="useToken">false</setting>
  </object>
</object>

Configuration settings in InfoPages.xml

The following table describes each action definition setting in Actions.xml required to integrate the Bp8IntegrationServlet. Actions are used to invoke the Bp8IntegrationServlet via a right-click context menu. Each setting is identified by its key attribute. Unless otherwise specified, each setting is optional. If an optional setting is not present, its default value is used.

Integrating with Process Engine e-mail notification

Users can optionally enable e-mail notification of workflow activity using the Preferences page in BPF Web Application. You can modify the default HTML-formatted text files used to create the e-mail notifications to provide users with a link to the BPF Case, matching your corporate identity and meeting your localization needs. See Modifying Notifications in the Help for Process Development for detailed instructions on customizing an e-mail notification message. The following URL is an example of a customized link within the email notification template.

<a href="http://rangiroa:8080/bpf/Bp8IntegrationServlet?_commandId=9010&timeZone=GMT%2008%3A00&_mode=1&wobNum=<$F_WobNum>">
Process Case...
</a>