Customizing FileNet P8 eForms Processor Components

This is a developer-level activity.

FileNet P8 eForms is an electronic forms management application, an add-on product integrated into Workplace, that supplies developers with out-of-the-box components that may be modified to create custom forms or workflows for use in custom web applications. In Workplace, you can create custom eForms that are rendered and processed with a document processor defined in the document policy. You can also create a workflow in Workplace to use your custom-designed eForms for the workflow UI. FileNet P8 eForms provides a launch processor and step processor for authoring your eForms-based workflows. (If you have installed the FileNet P8 eForms help, you'll find more information about working with forms at this topic: Get Started with Form Policies.)

The recommended method for modifying the out-of-the-box processor components is to follow the procedures outlined in the Application Engine Administration Guide. However, because it is possible to programmatically customize the components as well, this topic describes the necessary steps for completing a programmatic customization of processor components, such as would be necessary after modifying the out-of-the-box toolbar.

To implement programmatic customization of a document, launch, or step processor component, perform the following:

Set up your development environment.
Modify the FileNet P8 eForms processor components.
NOTE This task requires the Workplace source code, which is available upon request.
Register the custom launch and step processors with the Process Engine.
Configure the FileNet P8 Workplace application to recognize custom processors.
Update or create document policies.
Update the workflow definitions used in workflow policies.
Update the workflow policies.

Set up Your Development Environment

To develop, deploy, and test processor components, your development environment must include:

JDK 1.3.1 or higher
FileNet P8 Workplace application configured to access a Content Engine and a Process Engine. See the IBM FileNet P8 Platform Installation and Upgrade Guide. You can download this guide from the IBM FileNet P8 Platform publication library.
The following JARs in your project's class search path:

p8toolkit.jar
p8workplace.jar
javaapi.jar (for document processors)
aeeforms.jar

These JARs are located in Workplace/WEB-INF/lib.

The JAR that contains the javax.servlet.http package. The JAR names vary between application servers, for example, weblogic.jar in WebLogic, j2ee.jar in WebSphere, and servlet-api.jar in Tomcat.

Modify the FileNet P8 eForms Processor Components

Programmatically customizing default form or workflow UI elements involves modifying the out-of-the-box FileNet P8 eForms document, launch, and step processor components. The following sections describe the modification procedures for each component type:

UI Module
Event Java™ Server Pages (JSP)
UI JSP

The event JSP, UI JSP, and UI modules are component types in the underlying framework of the FileNet P8 Workplace application. For detailed information on the framework and its component types, see the Web Application Toolkit Developer's Guide.

UI Module

Most of the work associated with customizing out-of-the-box processors is completed in the UI module component. The UI module for a customized document form processor creates, renders, and handles events for the form. In a customized FileNet P8 eForms workflow, the UI module for the launch processor creates the workflow and renders the launch step to the user, and the UI module for the step processor retrieves the workflow from a specified queue and renders the data for a specified step.

To modify a UI module processor component, perform the following:

Copy the Workplace source code files listed below, and rename the copied files. For example, MyDocumentProcessor.java. You will make your modifications in the copied files, not the originals.

Component	UI Module File	Workplace Directory
Document Processor	DocumentProcessor.java	FileNet/Workplace/Source/ com/filenet/eforms/apps/server/ui/info/form
Launch Processor	LaunchProcessor.java	same
Step Processor	StepProcessor.java	same

In the copied files, change all class name references to agree with the names of your custom modules.
In the copied files, add, change, or delete components as necessary.
NOTE Some parameters are of type WcmString, which is a utility class used to retrieve a locale-specific string from a resource file using a specified key. If you want to add multicultural support to your custom module, add locale strings to a resource file, as described in the Web Application Toolkit Developer's Guide. If you have no such requirement, you can simply pass a nonexistent key value to WcmString.
If you added components that should react to events, add corresponding event handlers for each component. To change the behavior of an existing element, modify the corresponding event handler for that element.
NOTE For events that require user action, use a popup window (controller.openPopup(…)).
Compile and test your custom modules.
Package your custom module components in a new JAR (a JAR not supplied by FileNet), and deploy it in the Workplace/WEB-INF/lib directory.

Event JSP

To create custom event JSP components, perform the following:

Copy the out-of-the-box component files listed below, and rename the copied files. For example, MyLaunchForm.jsp. You will make your modifications in the copied files, not the originals.

Component	Event JSP File	Workplace Directory
Document Processor	DocumentForm.jsp	FileNet/Workplace/properties
Launch Processor	LaunchForm.jsp	FileNet/Workplace/eprocess/launchers/html/form
Step Processor	StepForm.jsp	FileNet/Workplace/eprocess/stepprocs/html/form

Change the module declarations to reference your custom processor components. For example, the following event JSP fragment shows the module declarations for MyDocumentProcessor.class and MyLaunchProcessor.class.

<%@ page errorPage="/WcmError.jsp" autoFlush="false" %>

<%-- UI Beans --%>
<jsp:useBean
   id="myDocumentProcessor"
   class="com.filenet.eforms.apps.server.ui.info.form.MyDocumentProcessor"
   scope="request">
   <jsp:setProperty name="myDocumentProcessor" property="name"
      value="myDocumentProcessor" />
</jsp:useBean>

<jsp:useBean
   id="myLaunchProcessor" 
   class="com.filenet.eforms.apps.server.ui.info.form.MyLaunchProcessor" 
   scope="request"> 
   <jsp:setProperty name="myLaunchProcessor" property="name" value="myLaunchProcessor" /> 
</jsp:useBean>          

<%-- Data Provider Beans --%>
<jsp:useBean
   id="authoringDataProvider"
   class="com.filenet.wcm.toolkit.server.dp.WcmAuthoringDataProvider"
   scope="request">
   <jsp:setProperty name="authoringDataProvider" property="name"
      value="authoringDataProvider" />
</jsp:useBean>

<jsp:useBean
   id="searchDataProvider"
   class="com.filenet.wcm.toolkit.server.dp.WcmSearchDataProvider"
   scope="request">
   <jsp:setProperty name="searchDataProvider" property="name"
      value="searchDataProvider" />
</jsp:useBean>        

<jsp:useBean
   id="eProcessDataProvider"
   class="com.filenet.wcm.toolkit.server.dp.WcmEProcessDataProvider"
   scope="request">
   <jsp:setProperty name="eProcessDataProvider" property="name"
      value="eProcessDataProvider" />
</jsp:useBean>		
        
<%-- WcmController CONTROLLER --%>
<jsp:useBean 
   id="controller"
   class="com.filenet.wcm.apps.server.controller.WcmWorkplaceController"      
   scope="request">
</jsp:useBean>        

<% 
   myDocumentProcessor.addDataProvider(authoringDataProvider);
   myDocumentProcessor.addDataProvider(searchDataProvider);
   myLaunchProcessor.addDataProvider(eProcessDataProvider); 
...

UI JSP

To create custom UI JSP components, perform the following:

Copy the out-of-the-box component files listed below, and rename the copied files using the same naming scheme as you employed for your event JSP components. For example, MyLaunchForm.jsp. You will make your modifications in the copied files, not the originals.

Component	UI JSP File	Workplace Directory
Document Processor	DocumentForm.jsp	FileNet/Workplace/UI-INF/jsp/ui/properties
Launch Processor	LaunchForm.jsp	FileNet/Workplace/UI-INF/jsp/ui/ eprocess/launchers/html/form
Step Processor	StepForm.jsp	FileNet/Workplace/UI-INF/jsp/ui/ eprocess/stepprocs/html/form

In the render statement of the UI JSP module files, change the JSP variables to match the variables set in the corresponding event JSP files. For example:

<% WcmUi.render(request, "myDocumentProcessor", out); %>
<% WcmUi.render(request, "myLaunchProcessor", out); %>

Register the Custom Launch and Step Processors

Using the Process Configuration Console, you must register your new launch and step processors with the Process Engine. For details on using the Process Configuration Console, see the Process Configuration Console Help.

To register the custom processors:

Log into FileNet P8 Workplace as a user with administrator rights.
Click Admin.
On the Workplace Admin page, click Process Configuration Console.
From the tree view, right-click "vwconnectionpoint[1]", then choose Properties from the context menu.
Choose the Step Processor Info tab.
Click the Add icon in the right corner.
For a new launch processor, enter the following values:
- Type: Launch
- Name: A unique, descriptive name for your custom launch processor,
  for example, My Form Launch HTML.
- Language: HTML
- Location: html/form/<launchProcessor_eventJsp>,
  for example, html/custom/MyLaunchForm.jsp.
- Width: 800 (suggested value)
- Height: 600 (suggested value)
Press Enter.
Click the Add icon in the right corner
For a new step processor, enter the following values:
- Type: Step
- Name: A unique, descriptive name for your custom step processor,
  for example, My Form Step HTML.
- Language: HTML
- Location: html/custom/<stepProcessor_eventJsp>,
  for example, html/form/MyStepForm.jsp.
- Width: 800 (suggested value)
- Height: 600 (suggested value)
Press Enter.
Choose OK.
Click the Action button and Commit Changes to the Process Engine.
Exit the Process Configuration Console.

Configure the FileNet P8 Workplace Application

This procedure configures the Workplace application to recognize custom processors when creating document and workflow policies. It requires modifying an XML file, then redeploying Workplace.

To modify the XML file:

Using a text editor, open the <AE_install_path>/Workplace/WEB-INF/PolicyProcessors.xml file.
Add the following settings for your customized document processor. For the "type" and "style" settings, enter the same values as shown in bold below. For the "url" setting, specify the location of your custom document processor event JSP file. The "name" setting can be any descriptive name.
```
<object key="processor">
   <setting key="name">Form (Custom)</setting>
   <setting key="type">Document</setting>
   <setting key="style">Form</setting>
   <setting key="url">properties/MyDocumentForm.jsp</setting>
</object>
```

Add the following settings for your customized launch and step processors. The "name" key values must match the "Name" field values that you entered in the Process Configuration Console, as described in the procedure for registering the custom launch and step processors.

<object key="processor">
   <setting key="name">My Form Launch HTML</setting>
   <setting key="type">Launch</setting>
   <setting key="style">Form</setting>
</object>
<object key="processor">
   <setting key="name">My Form Step HTML</setting>
   <setting key="type">Step</setting>
   <setting key="style">Form</setting>
</object>

Save your changes and exit the editor. (Note that if you modified the file to include any extended characters, save the file as UTF-8.)
Redeploy Workplace.

Update or Create Document Policies

To use your new document processor, you must assign it to an existing document policy or to a new document policy that you create. This section covers both the update and create procedures.

To update a document policy with your new processor:

Log in to FileNet P8 Workplace as a user with administrator rights.
Click Author.
Click Advanced Tools.
Under the Add Form Policy link, click Modify Existing.
In the Document Policy Wizard, click Display Settings.
In the Select Type field, select Document Policy.
Navigate the list of document policies and choose the document policy that you want to update.
From the choice list of processors, choose your new processor for the document policy.
Click Finish.
Repeat the previous steps for each document policy that you need to update.

To create a document policy with your new processor:

Log in to FileNet P8 Workplace as a user with administrator rights.
Click Author.
Click Advanced Tools.
Click Add Form Policy.
On the "Add Form Policy - Select Type" page, select Document Policy.
In the Document Policy Wizard, select a form template, and the Display Settings link will appear.
Click Display Settings.
From the choice list of processors, choose your new processor for the document policy.
Click Continue.
Continue with the remaining steps in the Document Policy Wizard.

For details on each wizard step, see the topic FileNet P8 Documentation > Expansion Products > FileNet P8 eForms > Form Policies > Document Policies > Create a Document Policy in the Help for Form Policies. Note that to access this topic, you must have the FileNet P8 eForms help installed on your FileNet P8 Platform Documentation server.

The updated policies are now ready for use.

Update Workflow Definitions

You must update any existing workflow definitions, specified in workflow policies, that will use your custom step processors. If you won't be using your new custom processors with the existing workflow definitions, skip this procedure.

To update the workflow definitions:

Log into FileNet P8 Workplace as a user with administrator rights.
Click Author.
Click Advanced Tools.
Click Process Designer.
Open a workflow definition that will use your custom step processors, and make these changes:
- Select the step that will use your custom processor. Set the step processor to the name of your custom step processor, for example, "My Form Step HTML". For a Launch step, set the step processor to the name of your custom launch processor, for example, "My Form Launch HTML".
- Validate, and then save the workflow definition.
- Transfer the workflow definition: select File < Transfer.
- Cancel the checkout of the workflow: select File < FileNet Cancel Checkout.
Repeat the previous step for each workflow definition that requires your custom step processors.
Close the Process Designer.

Update the Workflow Policies

You must update workflow policies that specify any workflow definitions that you have modified for custom step processors, as described in the Update the Workflow Definitions section. If you did not modify any workflow definitions to use your custom step processors, skip this procedure.

To update the workflow policies:

Log in to FileNet P8 Workplace as a user with administrator rights.
Click Author.
Click Advanced Tools.
Click Edit Workflow Policy.
Select the workflow policy that specifies the workflow definition that you just modified to use your custom processor.
Update the specified workflow definition to the version just updated in the Process Designer.
Continue through the Policy Designer Wizard steps, and select the required versioning setting (Major = True | False).
Click Finish at the end of the wizard.
Repeat the previous steps for each workflow policy that you need to update.

The updated policies are now ready for use.