Setting Up a New Application

This topic specifies the general steps and requirements for developing a Web application built on the Web Application Toolkit. To deploy a Web application into a production environment, see the FileNet P8 Developer's Roadmap.

If your application requires that you modify Workplace source code, the source code is available upon request. For a comprehensive list of all of the JARs required to compile the Workplace source code, see JAR File Dependencies.

Follow these steps to set up your development environment. For details on a particular step, click the applicable link.

  1. Create a web application folder.
  2. Configure the default controller (ConfigurableController).
  3. Implement servlets.
  4. Modify web.xml.
  5. Create your event Java™Server Pages (JSP) pages.
  6. Implement your preferences API.

For a high-level summary of these steps, see New Application Diagram.

Step 1: Create a Web Application Folder Structure

Your application structure should be similar to the following.

application structure

Step 2: Configure ConfigurableController

As described in the ConfigurableController section (ConfigurableController), Web Application Toolkit provides an implemented controller that supports named configurations. This section shows you how to use this default controller for your custom application. To implement your own controller, see Implementing a Controller.

To use the default controller:

  1. In the <app_root>/WEB-INF/p8controller.xml file, modify the default settings under this element: <list key="controllerConfig">.

    For a description of the preferences, see ConfigurableController Preferences.

    NOTE  If you do not want your application to connect to the Content Engine, set the following settings to false: bootstrapRequired and signInRequired.

  2. To do an additional configuration, make a copy of the whole <object key="controllerConfig"> block, and within the new copy, change the value of the <object key="configurationName"> element, for example, change the "default" value to "myCustom".
  3. In the additional configuration, change any of the values to suit your scenario.
  4. In each event JSP page, declare the ConfigurableController bean. For example:

    <jsp:useBean id="controller"
      class="com.filenet.wcm.toolkit.server.base.ConfigurableController"
      scope="request">
    </jsp:useBean>

  5. In each event JSP page that will use the additional configuration, set the controllerConfigName bean property to tell ConfigurableController which configuration from p8controller.xml to use. For example:

    controller.setControllerConfigName("myCustom");

    NOTE  You do not have to set the controllerConfigName bean property in event JSP pages that use the default configuration.

Step 3: Implement Servlets

Subclass the following servlet classes and implement the specified abstract methods.

Step 4: Modify Web.xml

Configure Basic Parameters in Web.xml

In the servlet descriptor <app_root>/WEB-INF/web.xml, set the following parameters:

Modify Additional Parameters for Container-managed Authentication

If you installed Workplace with the option for container-managed authentication, you must also perform the following:

  1. Copy the following files from the Workplace directory:
  2. When SSO authentication will not be used and the FORM auth method is configured, the ContainerLogin.jsp file is displayed as the login page. You can modify presentation elements of this page to meet your custom application requirements.

    <login-config>
      <auth-method>FORM</auth-method>
      <realm-name>MyJAASRealm</realm-name>
      <form-login-config>
        <form-login-page>/ContainerLogin.jsp</form-login-page>
        <form-error-page>/ContainerError.jsp</form-error-page>
      </form-login-config>
    </login-config>


    CAUTION  When you modify the ContainerLogin.jsp file, the form field names and form action name of the page, as dictated by Servlet 2.3 specifications, must remain unchanged. In addition, the ContainerError.jsp file is used to trigger the addition of a sign-in error message to the presentation of ContainerLogin.jsp. This logic must remain intact if user feedback is desired when the user enters the wrong password.

    NOTE  When container-managed authentication is in use and the user signs out of Workplace, the user is routed to the ContainerSignout.jsp "session terminated" page. This page may be modified as desired.
  3. Review the contents of the exclude init parameter block in the filter definition for AE PreprocessorFilter. This is a list of URL patterns representing the resources in the application that will not require authentication.

    NOTE  WebSphere 6 does not use the exclude init list. When deploying on WebSphere 6, you must specify the resources as a list of protected URL pattern entries in the security-constraint element. For more information, see Adjust Configuration Settings for Deployment on WebSphere 6.

    The following example demonstrates how to implement the exclude init list:

    <filter>
      <filter-name>AE PreprocessorFilter</filter-name>
      <filter-class>
        com.filenet.ae.toolkit.server.servlet.filter.PreprocessorFilter
      </filter-class>
      <init-param>
        <param-name>challenge</param-name>
        <param-value>false</param-value>
      </init-param>
      <init-param>
        <!-- Path entries are listed here for URI's that are not to be
             secured by container based authentication. -->
        <param-name>exclude</param-name>
        <param-value>
          /css/*,
          /download/*,
          /FnJavaV1Files/*,
          /images/*,
          /js/*,
          /Samples*,
          /Source*,
          /UI-INF/*,
          /ContainerError.jsp,
          /ContainerLogin.jsp,
          /ContainerSignout.jsp,
          /containerSecured/*,
          /WcmError.jsp,
          /WcmSignIn.jsp,
          /GetUserToken.jsp,
          /GetTokenSignIn.jsp,
          /axis,
          /axis/services/*,
          /servlet/AdminServlet,
          /setCredentials,
          /SOAPMonitor,
          /webdav*,
          /P8BPMWSBroker/*,
          *j_security_check*
        </param-value>
      </init-param>
    </filter>
  4. When SSO authentication will be used by your application and your SSO implementation will include the use of a proxy server, then several init parameters in the filter definition for ContainerBasedFilter must be configured. The following example shows the default values for these init parameters.

    NOTE  When deploying on WebSphere 6, the ContainerBasedFilter challengeProxyEnabled init parameter must be set to false. In addition, further adjustments must be made as described in Adjust Configuration Settings for Deployment on WebSphere 6.

    <filter>
      <!-- -----------------------------------------------------------------
        -- Set the default values for the ContainerBasedFilter init parameters.
        -- If you are NOT deploying on WebSphere,
        --    specify the values as needed
        -- otherwise,
        --    set challengeProxyEnabled to false.
        -- ----------------------------------------------------------------- -->
      <filter-name>ContainerBasedFilter</filter-name>
      <filter-class>
        com.filenet.ae....ContainerBasedFilter
      </filter-class>
      <init-param>
        <param-name>challengeProxyEnabled</param-name>
        <param-value>true</param-value>
      </init-param>
      <init-param>
        <param-name>challengeProxyURI</param-name>
        <param-value>containerSecured/Return.jsp</param-value>
      </init-param>
      <init-param>
        <param-name>perimeterChallengeMode</param-name>
        <param-value>false</param-value>
      </init-param>
      <init-param>
        <param-name>ssoProxyContextPath</param-name>
        <param-value></param-value>
      </init-param>
      <init-param>
        <param-name>ssoProxyHost</param-name>
        <param-value></param-value>
      </init-param>
      <init-param>
        <param-name>ssoProxyPort</param-name>
        <param-value></param-value>
      </init-param>
      <init-param>
        <param-name>ssoProxySSLPort</param-name>
        <param-value></param-value>
      </init-param>
    </filter>


    By default, perimeterChallengeMode is set to false, and the various sso* parameters are set to blank values. However, if you intend to deploy Workplace into an SSO environment where users will access Workplace via an SSO proxy server, then the sso* parameters may have to be modified.

    The sso* parameter values are used to modify one or more elements of the native URL that Workplace sees on a request. Wherever the value of a SSO proxy host element in the URL request is different from the equivalent information for the host where Workplace is deployed, then the corresponding sso* parameter for that element in the URL must be set to the value for the SSO proxy host. Setting the sso* parameters to the SSO proxy host values modifies the URL request, which causes Workplace to behave as though it were running natively on the SSO proxy host.

    For example, let's say the host URL where Workplace is deployed is http://deploy_server/Workplace and the corresponding SSO proxy host URL is http://sso_proxy_server/Workplace, then we can see that the SSO proxy host server is different from the Workplace deploy host server. Assuming that the SSO proxy context path, port, and SSL port are the same for both the SSO proxy host and the Workplace deploy host, then only the ssoProxyHost parameter needs to be modified as follows:

      <init-param>
        <param-name>ssoProxyHost</param-name>
        <param-value>sso_proxy_server</param-value>
      </init-param>

    As another example, let's say that the Workplace deploy host URL is http://deploy_server:7001/Workplace and the SSO proxy host URL is http://sso_proxy_server.domain.com/fn/Workplace. In addition, let's assume that that the native SSL port for the Workplace deploy host is 7002. In this case, the SSO proxy host server, context path, port, and SSL port are all different from those used by the Workplace deploy host. Therefore, all of the sso* parameters need to be modified as follows:

      <init-param>
        <param-name>ssoProxyContextPath</param-name>
        <param-value>/fn/Workplace</param-value>
      </init-param>
      <init-param>
        <param-name>ssoProxyHost</param-name>
        <param-value>sso_proxy_server.domain.com</param-value>
      </init-param>
      <init-param>
        <param-name>ssoProxyPort</param-name>
        <param-value>80</param-value>
      </init-param>
      <init-param>
        <param-name>ssoProxySSLPort</param-name>
        <param-value>443</param-value>
      </init-param>


    In general, the init parameters should be configured as follows:

Adjust Configuration Settings for Deployment on WebSphere 6

If you intend to deploy your application on WebSphere 6, you must adjust your configuration settings as follows:

  1. When deploying on WebSphere 6, the ContainerBasedFilter init parameter (as described in Step 4 above) must be set to false:

    <filter>
      <filter-name>ContainerBasedFilter</filter-name>
      <filter-class>false</filter-class>
      ...
    </filter>

  2. WebSphere 6 does not use the exclude init list (as described in Step 3 above). When deploying on WebSphere 6, you must specify the resources as a list of protected url-pattern entries in the security-constraint element, as follows:

      <addSecurityConstraint>
        <security-constraint>
          <web-resource-collection>
            <web-resource-name>action</web-resource-name>
            <description>Define the container secured resource</description>
            <url-pattern>/containerSecured/*</url-pattern>
            <!-- -----------------------------------------------------------------
              -- Uncomment the following url-patterns if either is true:
              --
              -- 1) All resources that require credentials must be secured
              --    in order to obtain a secured Thread.
              -- 2) You are deploying on WebSphere.
              --
              -- If neither of the above statements are true,
              -- leave the following url-patterns commented out.
              -- ------------------------------------------------------------- -->
            <url-pattern>/</url-pattern>
            ...
            <url-pattern>/Workflows/*</url-pattern>
          </web-resource-collection>
          ...
        </security-constraint>
      </addSecurityConstraint>

  3. Set the auth-constraint element role name to " All Authenticated":

      <addSecurityConstraint>
        <security-constraint>
          <web-resource-collection>
          ...
          <auth-constraint>
            <!-- -----------------------------------------------------------------
              -- Uncomment the correct role-name definition.
              --
              -- If you are NOT deploying on WebSphere,
              --    use the wildcard "*"
              -- otherwise,
              --    use the "All Authenticated" setting.
              --
              -- In addition, if you are deploying on WebSphere
              -- Uncomment the addLoginConfig security-role element (see below).
              -- -----------------------------------------------------------------
              -->
            <!-- Use the wildcard "*" if not deploying on WebSphere
              -- <role-name>*</role-name> -->
            <!-- WebSphere role-name definition. -->
            <role-name>All Authenticated</role-name>
          </auth-constraint>
          ...
        </security-constraint>
      </addSecurityConstraint>

  4. Add the security-role element after the login-config element, near the bottom of the descriptor file:

      <addLoginConfig>
        <login-config>
          <auth-method>FORM</auth-method>
          <realm-name>AE Workplace</realm-name>
          <form-login-config>
            <form-login-page>/ContainerLogin.jsp</form-login-page>
            <form-error-page>/ContainerError.jsp</form-error-page>
          </form-login-config>
        </login-config>
        <security-role>
          <description>All Authenticated</description>
          <role-name>All Authenticated</role-name>
        </security-role>

      </addLoginConfig>

Step 5: Create Your JSP Pages

In addition to your application-specific pages, create the following framework JSP pages, or modify copies from the FileNet P8 Workplace application. Declare your implemented controller in these pages.

See Also
Framework Page
Creating a Sign-In Form

Step 6: Implement Your Preferences API

This section lists the steps for implementing your preferences API. For conceptual information on the preferences object model and base classes, see Preferences API.

  1. Create your preference data file(s), following the Preferences XML Schema.
  2. Place your site and user preferences files in this directory of your Toolkit-based application: <app_root>/WEB-INF/xml.
  3. Decide whether to store the current version of your preferences files on the Content Engine, with the original preferences stored in <app_root>/WEB-INF/xml. Storing preferences on the Content Engine provides for file versioning. Alternatively, you may want to keep the preferences local, for development purposes. For general information about preferences, see About Site Preferences .

    You specify the preferences location in /WEB-INF/bootstrap.properties.

    To store preferences in a Content Engine object store, set the objectStoreId option with a valid object store name.

    To store preferences locally, set the objectStoreId option to "skip", or set it to a blank value.

  4. Subclass WcmPrefsObject if necessary.

    WcmPrefsObject is a base map-like class for XML-based preferences. You can create a tree structure of WcmPrefsObjects and/or subclasses. For a small number of preferences, you can use WcmPrefsObject straight as a generic map. For details, see WcmPrefsObject.

  5. Subclass WcmConfiguration.

    WcmConfiguration is the point of entry into WcmPrefsObject objects. It is intended to be subclassed to load application-specific preferences. For details, see WcmConfiguration.

    NOTE  If you disable the sign-in for your application, override WcmConfiguration.initialize(), which attempts to return sign-in credentials. The override method should not return sign-in credentials.

  6. In the <app_root>/WEB-INF/p8controller.xml file, set the value of the following element to your WcmConfiguration subclass, including the package name: <setting key="configuration">.

See Also
Sample Applications

New Application Diagram

The following diagram is a high-level view of a new application setup.

diagram of application setup