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

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.

Parameter Required/Optional Description Requires Encoding
_commandId required The integer code for the command that will be invoked. For example, the _commandId value for the View Case command is 9000. Command IDs are mapped to operation URLs in bpf/WEB-INF/Bp8Integration.xml no
_mode optional 1 - Process and remain in BPF Web Application.
2 - Process, sign out of BPF, and redirect to _responseURL.
no
_responseURL required if _mode=2 A fully-qualified URL of the page to which the Bp8IntegrationServlet redirects after the command executes. The page must handle the response information returned by the command.
URL-encoded
ut optional User token, allowing BPF to authenticate the user without first prompting the user for logon credentials. For more information, see User Tokens in the FileNet P8 Platform documentation.
URL-encoded
timeZonerequiredThe browser's time zone, such as timeZone=GMT%2008%3A00 for the time zone of GMT+08:00 in URL-encoded format. This  parameter is required, otherwise, you'll get an error of "The browser timezone is not configured".
URL-encoded

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:

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 

<%@ 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.

Command ID Description
9000 View Case
9010 Process Case

View Case

Command ID
9000 Opens BPF Case user interface in View mode. This is also referred to as opening a Case from a CASEQUERY Inbasket.
Parameters       label-encode if underlined
caseId Required if id is missing. This parameter should contain the Case ID.
id Required if caseId is missing. This parameter should contain the object identifier (GUID) of the Case custom object.
objectStoreName Required. This parameter should contain the Object Store Name.
objectType This is an optional parameter that should contain customobject, of supplied.
Example
http://rangiroa:8080/bpf/Bp8IntegrationServlet?_commandId=9000&id={95ACE274-915E-49F8-824C-08C9C353696C}&objectStoreName=Bp8ObjectStore&timeZone=GMT%2008%3A00
Notes
  • _mode parameter is always ignored.
  • If ut parameter is not specified or is invalid, a logon page will be displayed.
  • If both caseId and id parameters are specified, id will be used. If id is invalid, caseId will be used. An exception will be displayed if both id and caseId are invalid.
  • If both caseId and id parameters are omitted, an exception will be displayed to the user and the logon dialog will not be displayed.
  • If objectStoreName parameter is omitted, an exception will be displayed to the user and the logon dialog will not be displayed.

Process Case

Command ID
9010 Opens BPF Case user interface in Processing mode.
Parameters       label-encode if underlined
caseId Required if id and wobNum are missing. This parameter should contain the Case ID.
id Required if caseId and wobNum are missing. This parameter should contain the object identifier (GUID) of the Case custom object.
objectStoreName Required. This parameter should contain the Object Store Name.
wobNum Required if id and caseId are missing. This parameter should contain the work object number (wobNum) from the PE.
userName This is an optional parameter that may contain the user's logon name. It user token is not used, this user name will be populated on the logon page.
hideInbaskets

If hideInbaskets=1 is specified in the URL, the Inbaskets list will be hidden, producing the same result as selecting the Hide Inbaskets option in user preferences in the BPF Web Application.

If hideInbaskets=0 is specified or this parameter is omitted from the URL, the Inbasket list will be displayed or hidden based on user preferences.

Example

Open the Case from an external application and remain in BPF Web Application after user completed an action, so that user can process other Cases:

http://rangiroa:8080/bpf/Bp8IntegrationServlet?_commandId=9010&_mode=1&caseId=312341&objectStoreName=Bp8ObjectStore&timeZone=GMT%2008%3A00

Notes
  • If ut parameter is not specified or is invalid, a logon page will be displayed.
  • If wobNum, caseId and id parameters are specified, then combination of wobNum and caseId will be used to determine the Case object. The id parameter will be ignored.
  • If both caseId and id parameters are omitted, but wobNum is present, then wobNum will be used to determine the Case object.
  • If objectStoreName parameter is omitted, an exception will be displayed to the user and the logon dialog will not be displayed.
  • If wobNum is missing but caseId or id is present, a first available workflow object for that Case will be used to determine the Inbasket.
  • userName attribute is always ignored if a valid token was provided in the URL or if the Bp8IntegrationServlet was executed within the same Web session.
  • If there is no active work object found for the Case, Bp8IntegrationServlet will redirect to commandId=9000. There will be a message displayed to a user indicating that Case was opened in View Mode.
  • Lower case alpha hex digit characters should not be used for the id (GUID) parameters in Actions.xml and InfoPages.xml. Due to a limitation in Workplace, specifying {92689f34-9f53-44ce-85ef-2d561e50d139} instead of {92689F34-9F53-44CE-85EF-2D561E50D139}, for example, as a GUID value in the InfoPages.xml and Actions.xml files (for the Bp8Case custom object class) will fail to work. Workplace will not pick up the value. Only upper case alpha hex digit characters should be used.

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.

Setting Value
<setting key="id">openCase</setting> Defines the ID for the Open Case action. This setting is required and the value has to be unique for each action.
<setting key="title" localizationKey="server.Actions_xml.openInCaseQuery">Open Case </setting> Defines the action's label, which will appear in the user interface. This setting is required.
-- id={OBJECT_ID}&amp;
objectType={OBJECT_TYPE}&amp;
bpfURL=http://<host>:<port>/bpf/Bp8IntegrationServlet</setting> --> <setting key="url">http://<host>:<port>/bpf/Bp8IntegrationServlet?
_commandId=9000&amp;
id={OBJECT_ID}&amp;
objectStoreName={OBJECT_STORE_NAME}&amp;
timeZone={TIME_ZONE}&amp;
objectType={OBJECT_TYPE}
Defines the URL pattern. This setting is required. It defines the URL of the page that implements the action and the parameters passed to that page on the URL. The format of this string is described in URL Pattern Macros found in the FileNet P8 Platform documentation.

Note that spaces and line breaks are allowed in the value of this setting for convenience. When Actions.xml is read, spaces and line breaks are automatically removed from this string, they are not valid URL characters.
<setting key="img">images/action/Launch16.gif</setting> Defines the icon for the action. This setting is not required. The value must be a valid path to an image with a size of 16x16 pixels.

Note that like the URL setting, you can use a relative path.
<setting key="useToken">true</setting>

If the value is true, a user token will be appended to the URL before redirecting. This will only happen if token support is turned on in Site Preferences. The default value is true.

<array key="classes">
  <value>{63F8AA94-E2B9-11D0-ADF6-00C04FB66DAD}</value>
  <value>{A73BEEB2-B0B7-11D2-8853-0000F80883E3}</value>
</array>
Defines the list of Case object classes that are valid for this action. The values must be in GUID format. The action will be available only for the classes listed.

If this setting is present, exclude the excludedClasses setting.
<array key="excludedClasses">
  <value>{d24d4450-1f01-11d1-8e63-006097d2df48}</value>
  <value>{f81e9010-6ea4-11ce-a7ff-00aa003ca9f6} </value>
</array>
Defines the list of Case object classes that are not valid for this action. The values must be in GUID format. The action will not be available for the classes listed.

If this setting is present, exclude the classes setting.
<array key="objectTypes">
  <value>customobject</value>
</array>
Defines the list of object types valid for this action. This setting is required. Valid values are:

customobject

If this setting is present, exclude the excludedObjectTypes setting.
<array key="roles">
  <value>Indexer</value>
  <value>Supervisor</value>
</array>
Defines the list of access roles that are valid for this action. Only users that are members of one or more of the listed roles will see the action. Access roles are defined on the Content Engine (CE). Default value is Everyone.

NOTE  You can also set roles in Workplace Site Preferences using the Actions Role Access page.
<setting key="isPopup">false</setting> If the value is True, this action will open in a new window. The default value is False.
<setting key="popupHeight">600</setting> Defines the pixel height of the new window. This setting is ignored if the isPopup setting is set to False. The default value is 600.
<setting key="popupWidth">800</setting> Defines the pixel width of the new window. This setting is ignored if the isPopup setting is set to False. The default value is 800.
<setting key="requestWindowId">false</setting> Required. This setting disables the window id. It should always be set to False.

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.

"infoPage" Object Setting Value
<array key="objectTypes">
  <value>customobject</value>
</array>
Defines the list of object types valid for this Information page. Valid values are:

customobject
<array key="classes">
  <value>{63F8AA94-E2B9-11D0-ADF6-00C04FB66DAD}</value>
  <value>{A73BEEB2-B0B7-11D2-8853-0000F80883E3}</value>
</array>
Defines the list of classes that are valid for this Information page. This setting is required. The values must be in GUID format. The page will be available only for the classes listed.
<setting key="url">
  http://<host>:<port>/bpf/Bp8IntegrationServlet?_commandId=9000&amp;timeZone={TIME_ZONE} </setting>
Defines the URL of the Information page. This setting is required. If the URL does not start with "http://", then it's considered to be a relative URL, and, when redirecting, the base path of the Workplace application will be prepended to the URL.

For example, if the URL is properties/customInfo2.jsp, and the base URL is http://myserver/Workplace, Workplace will redirect to http://myserver/Workplace/properties/customInfo2.jsp.
<setting key="useToken">true</setting>

If the value is true, a user token will be appended to the URL before redirecting. This will only happen if token support is turned on in Site Preferences. The default value is true.

<setting key="isPopup">true</setting> If the value is true, this action will open in a new window. The default value is true.
<setting key="popupHeight">600</setting> Defines the pixel height of the new window. This setting is ignored if the isPopup setting is set to False. Default value is 600.
<setting key="popupWidth">800</setting> Defines the pixel width of the new window. This setting is ignored if the isPopup setting is set to False. Default value is 800.

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>