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.
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.
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:
Constant Name | Value |
Description |
---|---|---|
RETURN_CODE_SUCCESS |
0 |
Success |
RETURN_CODE_USER_CANCEL |
1020 |
User canceled command |
RETURN_CODE_EXCEPTION |
1040 |
Exception thrown |
Other returned parameters are specific to the command that was executed. Some returned parameters may have to be label decoded.
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
request.getParameter(
)
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.
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:
integrationWebBasedCommand
URL pattern. It includes the numeric command ID for Checkout List,
which invokes a Workplace JSP that lists the user's checked-out objects. It also includes parameters for the user token, window title, object store, and time zone. 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.*, 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>");
%>
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>
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.