BPF Tab Plug-in Interface

The IBM® FileNet® BPF Web Application provides two out-of-the-box tabs that you can invoke on any Case object: Case and Audit. The Case tab layout differs based on the Case type and could also be extended with custom code or a modified XSL stylesheet. The Audit tab is not customizable.

BPF provides the facility to allow you to plug in your own tabs that can extend the Case data model, display data from external systems, or accommodate any special business requirements that cannot be easily met by the out-of-the-box tabs. This facility will be referred to as Tab Plug-in Interface. In addition to the Case and Audit tabs, two more tab plug-ins come as part of BPF: Attachments and Table. Refer to the Attachment and Table tabs help topic for details about those tabs.

This help topic describes the Tab Plug-In Interface in detail, including steps to develop a simple tab.

Overview

The BPF web application uses a CSI (Client Side Include) approach instead of SSI (Server Side Include) to allow dynamic HTML in plug-in tabs. SSI is static; once the page is loaded, SSI cannot do anything more to change the page. With CSI, developers can make the page fully dynamic. BPF uses an iFrame container to render and display plug-in tab content. As long as the tab handler is deployed within the same application, tab content can access data available via BPF JavaScript Business Object or data on other tabs. URL parameters could be used to pass data to the plug-in page itself.

Tab registration

After creating a custom tab, you must register it, setting its location and configuration in the BPF Metastore. Once you register the tab, you can expose it on the Inbaskets as required.

At the present time, BFP Explorer does not allow registering new parameters for (or modifying existing parameters on) the existing tabs. New plug-in tab registration or modification of the existing tab needs to be done directly in the BPF Metastore using SQL or Oracle client. The tab URL handler is registered in the TAB table, TAB_CONTENT column. The Tab Plug-in Interface supports absolute and relative paths to the tab page. The following table describes the URL formats supported.

URL Type Identifier Description
Absolute Value starts with http:// or https://

A fully-qualified URL of the page to which the Tab Plug-in Interface redirects after the command executes. The tab code must handle the command information passed in the URL. The following example shows a sample URL using an absolute path.

http://rangiroa:7001/bpf/plugins/tabs/table/TableTab.jsp?layout=Securities&TabName={TABNAME}&Inbasket={IID}&Bp8CaseID={CFNAME}
Relative to BPF root Value starts with the /

A relative URL of the page to which the Tab Plug-in Interface redirects after the command executes. This URL is relative to the root of the web application. The tab code must handle the command information passed in the URL.

/plugins/tabs/table/TableTab.jsp?layout=Securities&TabName={TABNAME}&Inbasket={IID}&Bp8CaseID={CFNAME}
Relative to tool root None of the above

A relative URL of the page to which the Tab Plug-in Interface redirects after the command executes. This URL is relative to the root of the tabs folder (/plugin/tabs/{tab_name}). The tab code must handle the command information passed in the URL.

TableTab.jsp?layout=Securities&TabName={TABNAME}&Inbasket={IID}&Bp8CaseID={CFNAME}

Parameters overview

The following table describes the parameters passed to the Tab Interface. Note that some parameters must be URL-encoded with the Java™ API method URLEncoder.encode.

Parameter Value Required/Optional Description Requires Encoding
{case_field_name} {CFNAME} optional

The {CFNAME} macro will be substituted with the Case field value during runtime, where the Case field name is specified as a parameter name. All macros in the URL that contain {CFNAME} will be evaluated during runtime and substituted with the Case field value where the Case field name is determined from the left side of the equal sign, as in {case_field_name}={CFNAME}. Note that the {case_field_name} parameter is case sensitive and should match the Case field name as defined in the BPF Explorer. Spaces are not allowed in the Case field names. A plug-in tab needs to be coded to interpret this parameter.

Example: {plugin_tab_url}?Bp8CaseID={CFNAME}&AccountNum={CFNAME}

 no
iid {IID} optional

The {IID} macro will be substituted with the current Inbasket ID during runtime. Although iid is suggested as the parameter name for consistency, any other parameter name could be used. A plug-in tab needs to be coded to interpret this parameter.

Example: {plugin_tab_url}?iid={IID}

 no
iname {INAME} optional

The {INAME} macro will be substituted with the current Inbasket name during runtime. Although iname is suggested as the parameter name for consistency, any other parameter name could be used. A plug-in tab needs to be coded to interpret this parameter.

Example: {custom_tab_url}?iname={INAME}

 no
tname {TABNAME} optional

The {TABNAME} macro will be substituted with the current tab name during runtime. Although tname is suggested as parameter name for consistency, any other parameter name could be used. A plug-in tab needs to be coded to interpret this parameter.

Example: {custom_tab_url}?tname={TABNAME}

 no
_showatt 1 or 0 optional

The _showatt parameter controls whether the Case attachments list is displayed at the bottom of the tab.

  • When the _showatt=0 parameter is specified, the attachments list will not be displayed at the bottom of this tab, even if enabled on the Inbasket.
  • When the _showatt=1 parameter is specified or _showatt parameter is missing from the URL, the attachments list will be displayed at the bottom of the tab, assuming the attachments list is enabled on the Inbasket.

NOTE  If the attachments list is disabled on the application or Inbasket level, this setting will be ignored.

 no
_cache 1 or 0 optional

The _cache parameter controls whether the plug-in tab content is reloaded on each invocation of the tab.

  • When the _cache=0 parameter is specified, the plug-in tab content will be reloaded each time user selects the tab by clicking the tab name.
  • When the _cache=1 parameter is specified, the plug-in tab content will be loaded upon first invocation, however the content will not be reloaded each subsequent time user selects the tab.
Note Any plug-in tab caching behavior could be overloaded via the onBeforePluginTabLoad event handler defined in EventHandler.js. 		no

In addition to the parameters listed above, you can also include any optional parameters required by your plug-in tab.

Plug-in tab behavior and interface customization

Since plug-in tab content is loaded into an iFrame element on the BPF Main page as an independent HTML document, the plug-in tab design may follow any design pattern desired assuming it is compatible with BPF. There are certain design considerations you must follow in order to make BPF aware of your plug-in tab.

Customizing plug-in tab behavior

Plugin tab behaviors could be customized via the JavaScript Business Object Interface, utilizing the tab object methods and functions. The tab object prototype is defined the in Bp8BusinessObjects.js and is detailed in the IBM FileNet Business Process Framework Developer Guide. The following table provides some details on the most commonly used features.

Object Name Description
tab.dirty

If plug-in tab custom code sets the dirty property on the tab object, BPF will perform the following:

  • When a user clicks the Close button in the toolbar and the dirty field flag on the plug-in tab is set, a "Do you want to save changes..." message will be displayed to a user.
  • When a user clicks the Save button in the toolbar and the dirty field flag on the plug-in tab is set, BPF will execute the save() method on the plug-in tab, if defined.
  • When a user executes an action on the Case and the dirty field flag on the plug-in tab is set, BPF will execute the save() method on the plug-in tab, if defined.

The following JavaScript™ code sample is executed from the plug-in tab and resets the dirty property on the tab object:

var tab = parent.getCurrentInbasket().tabs[parent.currentContext.getCurrentTabName()];
tab.dirty = false;
tab.save() prototype

If a plug-in custom tab exposes a user interface where data could be changed, it may expose a save() method that would save the data on the tab. BPF will call the save() method on each tab where tab.dirty=true when the user is clicking the Save button or executing an action. The save() function logic will be custom to each plug-in tab implementation.

If a save() function is not defined in the plug-in tab code, the tab.save action will have no effect even if tab.dirty=true.
tab.refresh()

If a plug-in custom tab calls the refresh() method to reload the tab content.

The following JavaScript code sample is executed from the plug-in tab, refreshing the tab content:

var tab = parent.getCurrentInbasket().tabs[parent.currentContext.getCurrentTabName()];
tab.refresh();

You can also plug in custom code that will execute when a user clicks the tab. When a plug-in tab is loaded, the onBeforePluginTabLoad event will be raised. Custom code could be added to the EventHandler.js to intercept the onBeforePluginTabLoad event, execute any business logic, and then continue or cancel the tab loading. For example, you can create custom code that would implement a custom caching algorithm, determining whether the tab should be loaded or not. Refer to IBM FileNet Business Process Framework Developer Guide for on details on using EventHandler.js.

Creating a plug-in tab: An overview

Creating a custom tab to plug into the BPF Web Application requires an understanding of the FileNet P8 Platform Web Application Toolkit framework and BPF base modules. This section outlines the general steps you would take to create a new plug-in tab.

To create a custom plug-in tab:

  1. Create a framework JSP page (event JSP and UI JSP).
  2. Create a user interface information module that serves as a container class for one or more information-view modules.
  3. Create a user interface module that handles events and renders output for a specific view.
  4. Register the tab in the BPF Metastore.
  5. Expose the tab on the Inbaskets.

Sample code

Refer to IBM FileNet Business Process Framework Developer Guide for plug-in tab samples.

Updating plug-in tab configuration

If you change the plug-in tab definition in the TABS table in BPF Metastore while the BPF Web Application is running, you must restart the application using the Web server administration console.

Configuring a plug-in tab as a user's Default tab through Preferences

The dropdown list of available tabs that appears on the Preferences dialog in the BPF Web Application for setting the Default tab is hard-coded (static) in the user-preferences.xml file located in the \WEB-INF\ directory. To add or remove your custom plug-in tab to make it available in this list, open the user-preferences.xml file, edit the section at the bottom (shown in the example below), and then save the file. In addition, if you want to localize the display value for your plug-in tab, you will need to add a key to the strings-custom.en.txt file inside the bpfCustomLangResources.jar file in the \WEB-INF\lib directory, such as

	bp8.custom.server.inbasket.tabs.YOUR_TAB_NAME=MY_TAB_NAME

Otherwise, just leave the string value for the label in the section of user-preferences.xml shown below blank (""). You will then need to restart the web service in order to see your changes take effect. The added entry for a new plug-in tab is shown in the example below as item id="4": 

<option-list id="ol-tab-list">
     <option id="1" label="bp8.server.inbasket.tabs.Case">Case</option>
     <option id="2" label="bp8.server.inbasket.tabs.Audit">Audit</option>
		<option id="3" label="bp8.server.inbasket.tabs.attachment">Attachment</option
     <option id="4" label="bp8.custom.server.inbasket.tabs.YOUR_TAB_NAME">{YOUR TAB NAME}</option>
	</option-list>

Please note that the tab list in User Preferences is static and does not change based on the tabs configured in the current Inbasket or user role.