Modifying the Default HTML Launch Step Processor

This topic describes how to customize the default HTML Launch Step Processor (launcher_main.asp) included with the FileNet Web Services HTML Step Processor Toolkit (for Toolkit information, see Using the FileNet Web Services HTML Step Processor Toolkit). The procedure provided with this topic assumes that you have already set up your development system for ASP development (for information, see Setting Up Your System for Process ASP Development).

While there is no requirement for you to use an Integrated Development Environment (IDE) for developing your ASPs, many developers find using Microsoft's Visual InterDev or Visual Studio helpful. An alternative to using Visual InterDev or Visual Studio is working directly in the <drive>...\Program Files\FileNet\IDM\Web\IDMWS directory structure on your FileNet Web Services/PJAC for FileNet Web Services server. If you know your ASP development requirements and you want to make minor changes to specific files, working directly in the directory structure may be sufficient for your needs. The primary disadvantage is that you will be working in an active web server directory structure, which may make it more difficult to identify and correct errors.

The default HTML Launch Step Processor included with the HTML Step Processor Toolkit is designed to use certain shared files which are located in the ...\Program Files\FileNet\IDM\Web\IDMWS\Redist\WF_Html_Toolkit directory and the \Redist\Toolbar directory on the FileNet Web Services server.

You should not modify any of the files in the ...\WF_Html_Toolkit or \Redist\Toolbar directories without first familiarizing yourself with the following topics:

Caution Modifying any of these shared Toolkit files may cause problems with or a failure of the default HTML Launch Step Processor included with the HTML Step Processor Toolkit.

In addition, you should also understand the basic default HTML Launch Step Processor page data flow, which is as follows:

As indicated in the figure, when the end user launches a workflow definition, the workflow launcher launches the Launch Step Processor page. The only options an end user can select are to either launch the workflow or to cancel the launch. In either case, the user is redirected back to the Workflow Launcher page.

To customize the default HTML Launch Step Processor, use the following procedure:

  1. Create a new directory under the ...\Program Files\FileNet\IDM\Web\IDMWS\Redist\WF_Launcher directory (at the same level as the \HTML directory). If you are using Visual InterDev or Visual Studio, add a new folder.
  2. Name the directory (typically according to the function of the workflow Launch Step Processor is designed to start). This procedure will use the sample directory name \new_HTML_Launcher.
  3. Copy the contents of the ...\Redist\WF_Launcher\html directory into the \new_HTML_Launcher directory.
  4. Rename the launcher_main.asp file (for example to newlauncher_main.asp). If you are not using Visual InterDev or Visual Studio, remember to change the file attribute from Read-only to Read/Write.
  5. Open the newlauncher_main.asp file.
  6. Modify the newlauncher_main.asp file and other related ASP files as needed. Typical changes may, for example, include:
    1. Modifying the user interface; for details, see Modifying HTML Step Processor Toolkit User Interface Files. Note that the default launcher_main.asp file includes the colorOpt variable for controlling the default color of the Launch Step Processor tabs.  The default colorOpt value is a hexadecimal value of "#669966" (corresponding to the RGB color model). The variable is passed to the stepInfo.asp, tab.asp, and tabContent.asp files.
    2. Modifying the frames/frameset; for details, see Default HTML Launch Step Processor File Relationships.
    3. Modifying functions; e.g., for determining and initializing Launch Step Processor field values, for specifying toolbar behavior, for retrieving, parsing, and restructuring XML strings, including XML Step Element strings, XML strings from the client, attachments, properties, etc.; for details, see Modifying the HTML Step Processor Toolkit Core Files.
    4. Modifying JavaScript functions for creating and working with client objects and attachments; for details, see Modifying HTML Step Processor Toolkit Core Script Files.
    5. Modifying sorting functions on the client (e.g., if your Launch Step Processor will require users to sort field arrays) or the server (e.g., if your Launch Step Processor will require a single sorting operation to be distributed for numerous users); for details, see Modifying the HTML Step Processor Toolkit Utility Files.
    6. Be sure to include/reference the appropriate FileNet Web Services files in your ASP(s). For example, the InitApplication.asp to initialize your Launch Step Processor by setting VWSession variables, constants, cookie states, etc. (must be in your top-level ASP), the InitPage.js to initialize your ASP (should be included in every one of your ASPs), and so on. Normally, you should not need or want to modify these included/referenced files; for details, see FileNet Web Services Files Referenced By Process Applications. Similarly, be sure to include/reference the appropriate PJAC files. For example, Attachment.js to enable clients to view attachments, isPWLogon.asp to get Process session (VWSession) information for a Launch Step Processor currently in session or if no session exists to prompt the user to log on, and so on. Normally, you should not need or want to modify these included/referenced files; for details, see PJAC Files Referenced By Process Applications.
    7. Note See HTML Launch Step Processor File Relationships for additional information on HTML Launch Step Processor file dependencies and the frameset implemented in the default launcher_main.asp. See HTML Step Processor Toolkit Files for information on the location and contents of the HTML Step Processor Toolkit.

  7. If you need to modify any of the files in the \WF_Html_Toolkit directory, copy the needed files into the new directory (e.g., \new_HTML_Launcher) created for the new Launch Step Processor.
  8. Change all calls and references to the file(s) that comprise the new Launch Step Processor.
  9. If you have not already fully done so, deploy your HTML Launch Step Processor by copying all files to above-indicated directories on the FileNet Web Services server.
  10. Add the new Launch Step Processor (e.g., newlauncher_main.asp) to the workflow. This process is similar to adding a Step Processor and consists of using the Process Configuration Console to register the new Launch Step Processor, then using the Process Designer to specify the new Launch Step Processor for the step that starts the workflow. For details, see Adding a Custom Step Processor to the Workflow.
  11. Test your new Launch Step Processor pages from your application development server.