Workplace Application Engine UI Service Guide

FileNet® P8 Workplace provides the Application Engine UI Service (AE UI Service) to enable custom application developers to leverage reusable Workplace Java™Server Pages (JSP) pages with a minimum amount of coding. The AE UI Service supports calls from both thick client applications and Web-based thin clients. Thick clients use an XML-based protocol to communicate with the AE UI Service, whereas thin clients use request-based command and response URLs. For thick client integration, see the Workplace Application Integration Toolkit Developer's Guide.

This guide focuses on Web-based thin client integration with FileNet P8 Workplace and covers the following topics:

For detailed descriptions of each of the commands available for use with the AE UI Service, see the Application Engine UI Service Command Reference section.

Sending Commands to the AE UI Service

Web-based thin clients use request URLs to send commands to the Application Engine UI Service. In the request URL, the AE UI Service is referenced by integrationWebBasedCommand, the URL pattern to which the AE UI Service is mapped. The following example shows a basic call to the AE UI Service:

http://<host>:<port>/Workplace/integrationWebBasedCommand?_commandId=<id>&_responseURL=<url>[&_windowTitle=<title>&_dismissLabel=<label>&ut=<user token>]

The following table describes the parameters passed to the AE UI Service. 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
Description
Encoding
_commandId
Yes
The integer code for the command that will be invoked. For example, the _commandId value for the CheckoutList command is 2030. Command IDs are mapped to operation URLs in <AE_deploy_path>/Workplace/WEB-INF/Integration.xml.
None
_responseURL
Yes
A fully-qualified URL of the page to which the AE UI Service redirects after the command executes. The page must handle the response information returned by the command.
URL encode
_windowTitle
Optional
The title of the invoked Workplace page. If you don't set this parameter, the default title of the Workplace page is used.
label-encode
_dismissLabel
Optional
The label to use in replacement of the "Close" link in the page banner. If you don't set this parameter, the default label of the Workplace page is used.
label-encode
ut
Optional
User token, allowing Workplace to authenticate the user without first prompting the user for logon credentials. For more information, see User Tokens.
URL encode
timeZone
Optional
The time zone ID, as returned by java.util.TimeZone.getID(). We recommend that you include this parameter to ensure that the time displayed in your client application is synched up with the time zone displayed in the Workplace pages invoked by the AE UI Service. For more information on obtaining or constructing a valid time zone ID, see the JDK documentation on the Sun Web site.
None

In addition to the parameters listed above, you can also include optional command-specific parameters. Command-specific parameters are described in the Application Engine UI Service Command Reference.

To call the AE UI Service from an external application, you must know the base URL of the Workplace application. However, if you want to call the AE UI Service from custom pages within Workplace, you can obtain the base URL with a getWorkplaceBaseURL() call on the WcmSitePrefs object.

Understanding Response Parameters Returned by the AE UI Service

When a command has completed, the Application Engine UI Service redirects the user back to the page in the calling application, which was specified in the _responseURL parameter of the command. The URL contains a query string containing the response information in the form of parameter/values. For example:

http://<host>:<port>/externalApp/responseResult.jsp?_returnCode=0&_commandId=2001&vsId={E2BE6ADE-D7BA-4901-B4AB-548146D5E72A}&label=Fixed.__.Approval.__.Workflow.__..__mTNT.__n&id={95ACE274-915E-49F8-824C-08C9C353696C}&objectStoreName=Dev1.__.FS.__.SQL&objectType=document&windowId=C_WB!1915370968

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:

Other returned parameters are specific to the command that was executed. Some returned parameters may have to be label decoded.

Encoding or Decoding URL Parameters for Use with the AE UI Service

Some URL parameters passed to and from the Application Engine UI Service 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(…).

NOTES

Example: Invoking a Command

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

UI Module JSP that Calls the Application Engine UI Service

In the following code listing, a user token is included in the call to the AE UI Service. The token is retrieved from the JSP page of a web application into which the user is currently signed in. Internally, the page calls the static method getSessionToken() on WcmServerCredentials. Because the user can be authenticated on any web application, the retrieved token is valid on any web application to which it is passed.

When using the token with the AE UI Service, keep in mind the following:

<%@ page import="com.filenet.wcm.toolkit.util.*, java.net.*, java.io.*, java.util.*;"%>
<% // Label-encode the token parameter values
  String userid=WcmEncodingUtil.encodeLabel("suser");
  String password=WcmEncodingUtil.encodeLabel("greetings");
%>

<jsp:useBean id="controller" class="<<webapp controller class>>" scope="request"></jsp:useBean>
<% // Get token from application that user is currently signed on to
   ...
   String token;
   token = controller.generateUserToken();
   ...
%>


<% // Label-encode the AE UI Service parameters values (as needed)
  String windowTitle=WcmEncodingUtil.encodeLabel("Custom Application");
  String objStore=WcmEncodingUtil.encodeLabel("Dev1 FS");
%>

<% // Get the time zone of the client, to be passed to the AE UI Service
  TimeZone tz= TimeZone.getDefault();
  String timeZone=tz.getID();
%>

<% // URL-encode the AE UI Service parameters values (as needed)
  String responseURL = URLEncoder.encode("http://chekov:8080/custom/
    thinClientOperations/OperationResult.jsp");
  token = URLEncoder.encode(token);
%>

<% // Call the AE UI Service from the browser link
  out.println("<p><a href=\"http://norbert:8080/Workplace/integrationWebBasedCommand"+
    "?_commandId=2030"+
    "&ut="+ token+
    "&_windowTitle="+ windowTitle+
    "&objectStoreName="+objStore+
    "&timeZone="+timeZone+
    "&_responseURL="+responseURL + "\" target=\"_self\">"+
    "Checkout List (2030)</a></p>");
%>

JSP that Handles Response Parameters from the Application Engine UI Service

The following code is from OperationResult.jsp, specified in the _responseURL parameter in the call to the Application Engine UI Service in the above listing. This JSP simply iterates through its request parameters and prints out the parameter names and values. The Select Entry Template command returns four parameters in its response: objectStoreName, label, id, and vsId. Two of the parameters are encoded, so OperationResult.jsp decodes the values with WcmEncodingUtil. In addition to the response parameters from the command, OperationResult.jsp receives the standard response parameters always returned by the AE UI Service (_returnCode, _commandId, and, if the command fails, _message.)

<%@ page import="com.filenet.wcm.toolkit.util.*, java.util.*, java.io.*" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Select Entry Template: Response Parameters</title>
</head>
<body>
<%
  String sParm;
  String sString;
  Enumeration enum = request.getParameterNames();
  while(enum.hasMoreElements())
  {
    sParm = enum.nextElement().toString();
    out.println("<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);
  }
%>
</body>
</html>

Invoking the Application Engine UI Service Online Help

As a development aid, the Application Engine UI Service includes online help for all of the commands which it supports. 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 Workplace installation. Exclude the query string on the URL.

http://<host>:<port>/Workplace/integrationWebBasedCommand

For details on a particular command, click the numerical command ID link.