Work with customizing BPF actions

This help topic describes modification of the Bp8Actions.xml file to create custom actions within the IBM® FileNet® BPF Case user interface. The BPF Web Application allows usage of custom actions, very similar to the Workplace application, by right-clicking on a piece of content in the case view. These actions are available by right-clicking attachments in the attachments pane of the BPF case view or by right-clicking an attachment in the list view pane of the BPF viewer window. The actions available in the context menu when a BPF attachment is right-clicked are of two distinct types; Version Related and Non-Version Related. Version Related actions are associated with functions from the Workplace application and can be configured by modifying the Bp8Actions.xml file. Non-versioning related actions can be implemented by modifying the Bp8Actions.xml file.

This help topic covers the following:

  • Standard BPF actions details the context menu actions available in the BPF core application.
  • Enabling version related actions describes the setting used to enable/disable versioning specific actions in the BPF context menu.
  • URL pattern macros describes the values used in the URL key defined in Bp8Actions.xml action definitions.
  • BPF context menu actions using Workplace Integration Servlet describes the use of the Workplace Integration Servlet for context menu actions.
  • BPF context menu actions using custom pages provides an example of invoking a custom Web page from BPF context menu actions.
  • Remove attachment action configuration describes enabling and disabling the Remove Attachment context menu action using BPF configuration parameters.
  • Localization of action names describes using localization to change display values for context actions based on browser settings.

    • The file locations are:

    /WEB-INF/Bp8Actions.xml

    Versioning related actions will only be available for documents with versionable document classes and if versioning is enabled in the BPF configuration.

    Standard BPF actions

    This section details the standard actions included in the base BPF deployment. These actions can be removed by removing the respective reference in the topLevelActions section of the Bp8Actions.xml file as detailed below.

    Action Type Description
    Check Out Version Related This action checks out the document from the Content Engine (CE) repository for modification. While a document is checked out other users cannot modify the document until it has been checked in. Other users can view a checked out document while it is checked out.
    Cancel Checkout Version Related This action cancels the checkout status of a checked-out document. The previous version of the document becomes the latest checked-in version.
    Check In Version Related This action checks in a new version of a checked out document. When you check in a document, the document version information is updated, and the document is available for others to check out. During check-in the user has the option to change the document properties and security.
    Quick CheckIn Version Related The Quick Checkin action provides a fast method to check in a document without changing the document class, properties, or security. The only wizard page displayed is the Select File page for you to locate the new version of the document. Quick Checkin uses the default setting for Check In as Major Version (Properties page) as defined by your site administrator.
    Remove Attachment Non-Version Related

    This action allows users to remove the attachment from the BPF case. The attachment is not deleted from content engine. Only the association to the BPF case is removed.

    This option is configurable by Inbasket using the BPF Explorer tool.
    Notes
    • Versioning can be disabled in the BPF configuration. If versioning is disabled in BPF, or if the class of document that is referenced is non-versionable, version related actions will not be displayed in the context menu on right-click.
    • The Remove Attachment action is a system function that is not configurable other than being enabled or disabled via the BPF Explorer Tool.
    • The Bp8ContextMenu.js file is part of the BPF core and should not be modified for customizations.

    Enabling versioning related actions

    There is a Boolean setting in the BPF Explorer management tool (see the IBM FileNet Business Process Framework Explorer Handbook) that enables or disables version-related actions on the BPF context menu. This setting is located in the /Application Settings/Web Application node of the BPF Explorer tool. Actions listed in the table of standard BPF actions above of type Version Related will not be available if this value is set to False. This setting is a global setting for this BPF deployment. Versioning related context menu actions will only be displayed for CE document classes with versioning enabled. A single case may have both version-enabled and non-versionable documents attached. The appropriate context menu actions will be displayed for each attachment.

    Structure of the Bp8Actions file

    The Bp8Actions.xml file has two basic sections used to list the available actions and define the available actions. A section labeled Top Level Actions makes up a list of available actions. Each <value> entry in this section represents a custom action defined later in the same file. Actions can be defined by adding a topLevelAction and an action Definition to the Bp8Actions.xml file and deploying the pages referenced by the action under the <setting key="url"> value. The ExtCommand.jsp file is used to reference the associated workplace deployment using the configured workplace URL in the bpfmetastore database. This value is set in the BPF Explorer tool under /Application Settings/System-Wide Settings/ in the Workplace preference name value.


    <array key="topLevelActions">
       <value>checkout</value>
       <value>cancelCheckout</value>
       <value>checkin</value>
       <value>quickCheckin</value>
    </array>

    Another section of the Bp8Actions.xml file is used to define the actions listed in the Top Level Actions values. The actionDefinitions section contains a distinct section for each value in the top level actions. The example below is the checkout function of the native Bp8Actions.xml file.

    <list key="actionDefinitions">
    <object key="actionDefinition">
     <setting key="id">checkout</setting>
     <setting key="title" localizationKey="bp8.client.CheckOut">Check Out</setting> <-- See Localization of Action Names
     <setting key="url">
      ExtCommand.jsp?ExtTask=CheckOutDocument&amp;
      objectStoreName={OBJECT_STORE_NAME}&amp;
      label={OBJECT_LABEL}&amp;
      id={OBJECT_ID}&amp;
      objectType={OBJECT_TYPE}&amp;
      vsId={VERSION_SERIES_ID}&amp;
      majorVersion={MAJOR_VERSION}&amp;
      minorVersion={MINOR_VERSION}&amp;
      versionStatus={VERSION_STATUS}&amp;
      returnUrl={RETURN_URL}&amp;
      mimeType={CONTENT_TYPE}&amp;
      selectEventName=StateChanged&amp;
      selectEventCommand=checkout&amp;
     </setting>
    <setting key="img">img/action/Checkout16.gif</setting>
     <setting key="showInPath">false</setting>
     <setting key="hideInThickClientWindow">true</setting>
     <array key="objectTypes">
       <value>document</value>
     </array>
     <array key="excludedContentTypes">
       <value>application/x-filenet-entrytemplate</value>
       <value>application/x-filenet-documententrytemplate</value>
       <value>application/x-filenet-folderentrytemplate</value>
       <value>application/x-filenet-customobjectentrytemplate</value>
       <value>application/x-filenet-formdataentrytemplate</value>
       <value>application/x-filenet-declarerecordentrytemplate</value>
       <value>application/x-filenet-documentpolicy</value>
       <value>application/x-filenet-workflowpolicy</value>
       <value>application/x-filenet-formdata</value>
       <value>application/x-filenet-rm-physicalrecord</value>
       <value>application/x-filenet-rm-electronicrecord</value>
       <value>application/x-filenet-rm-emailrecord</value>
     </array>
     <setting key="isPopup">true</setting>
     <setting key="isPopupInMultiSelect">true</setting>
     <setting key="popupHeight">250</setting>
     <setting key="popupWidth">600</setting>
     <array key="versionStatusConditions">
       <value>inprocess</value>
       <value>released</value>
     </array>
    </object>

    The table below identifies each setting defined in the action definition. Entries in the table list each setting by it's key attribute.

    Setting Value
    <setting key="id">checkout</setting> Defines the ID for the action. This setting is required and the value has to be unique for each action.
    <setting key="title" localizationKey="bp8.client.CheckOut">Check Out</setting>

    Defines the action's label, which will appear in the user interface. This setting is required.

    The localizationKey value is used to resolve the label value for localization. An entry in the strings.txt file will match the value of bp8.client.CheckOut to resolve the displayed label to other languages as appropriate for current browser localization settings.
     <setting key="url">
      ExtCommand.jsp?ExtTask=CheckOutDocument&amp;
      objectStoreName={OBJECT_STORE_NAME}&amp;
      label={OBJECT_LABEL}&amp;
      id={OBJECT_ID}&amp;
      objectType={OBJECT_TYPE}&amp;
      vsId={VERSION_SERIES_ID}&amp;
      majorVersion={MAJOR_VERSION}&amp;
      minorVersion={MINOR_VERSION}&amp;
      versionStatus={VERSION_STATUS}&amp;
      returnUrl={RETURN_URL}&amp;
      mimeType={CONTENT_TYPE}&amp;
      selectEventName=StateChanged&amp;
      selectEventCommand=checkout&amp;
     </setting>

    Defines the URL pattern. This setting is required.

    Defines the URL of the page that implements the action and the parameters passed to that page on the URL. The format of this string is described in URL pattern macros. Note that spaces and line breaks are allowed in the value of this setting for convenience.

    NOTE  When Actions.xml is read, spaces and line breaks are automatically removed from this string because they are not valid URL characters.
    <setting key="img">img/action/Checkout16.gif</setting>

    Defines the icon displayed for the action. This setting is not required. To maintain proper formatting the image used must be 16x16 pixels in size.

    A relative path may be used.
    <setting key="showInPath">false</setting>

    A Boolean value;

    True = The action will appear on the context menu when the user clicks on the last item in the path view.
    False (default) = Object will not appear on the context menu.

    NOTE This setting applies only to objects that appear in the path view, such as an object store or folder and is irrelevant for other object types.
    <setting key="hideInThickClientWindow">true</setting> Not used.
    <array key="objectTypes">
       <value>document</value>
    </array>    		 Specifies the object types this action can be applied to. Default value is Document.
    <array key="excludedContentTypes">
       <value>application/x-filenet-entrytemplate</value>
       <value>application/x-filenet-documententrytemplate</value>...
     </array>

    Defines the list of mime types and container types that are invalid for this action. The current action will be available for all objects that are not content types listed in this array.

    NOTE  This setting supports "*" and "?" wildcards.

    <setting key="isPopup">true</setting>

    True (default) = This action will open in a new window.
    False = This action will open in current window.
    <setting key="isPopupInMultiSelect">false</setting> Multi-select functions are not supported in the current version of BPF.
    <setting key="popupHeight">250</setting> This setting is ignored if the isPopup setting is set to False. Defines the height of the newly opened window in pixels. The default value is 600.
    <setting key="popupWidth">600</setting> This setting is ignored if the isPopup setting is set to False. Defines the width of the newly opened window in pixels. The default value is 600.
    <array key="versionStatusConditions">
       <value>inprocess</value>
       <value>released</value>
    </array>

    Defines the values of the version status that are valid for the action. If this setting is not present, any value of the version status is valid.

    Valid values are: released, reserved, superseded, inprocess, or inprocessNoMajor. Use inprocess for a version series that has a major version. Use inprocessNoMajor for a version series that does not have a major version.

    For more information on version status values, see the Versioning Properties section of the FileNet P8 Platform documentation.
    Notes
    • Unless otherwise specified all settings are optional. If an optional setting is not defined it's default value will be utilized.

    URL pattern macros

    The macros in the following table are used in the URL setting of action definitions. They define the URL of the page that implements the action and the parameters passed to that page on the URL. The macros are replaced by the corresponding value in the actual URL.

    For example, if the pattern is operations/Test.jsp?id={OBJECT_ID}, and the object for which the operation is invoked has an ID of {A73BEEB2-B0B7-11D2-8853-0000F80883E3}, then the operation URL will be operations/Test.jsp?id={A73BEEB2-B0B7-11D2-8853-0000F80883E3}.

    Macro Value
    {OBJECT_STORE_NAME} Object store name, for example: DEV1.__.FS
    {OBJECT_ID} Object ID in GUID or path format.
    {OBJECT_LABEL} Object label as it appears in the user interface.
    {OBJECT_TYPE} Object type as a String, for example, document, folder, customobject.
    {VERSION_SERIES_ID} Version series ID as a GUID.
    {CLASS_ID} Class ID as a GUID.
    {CONTENT_TYPE} Content type as String, URL-Encoded.
    {MAJOR_VERSION} Major version, for example: 1.
    {MINOR_VERSION} Minor version, for example: 2.
    {VERSION_STATUS} Version status as a number, for example: 1.
    {RETURN_URL} Return URL, URL-encoded, for example, http://<server>:<port>/Workplace/WcmBrowse.jsp
    Notes
    • All URL pattern macro values are required.

     

    BPF context actions using Workplace Integration Servlet

    Custom actions may be added to the BPF document context menus by modifying Bp8Actions.xml. The actions defined in Bp8Actions.xml that make use of the Workplace Integration Servlet to access Workplace function reference the ExtCommand.jsp file located in the BPF root deployment folder. This file, in turn, references the Bp8ExtCommands.xml file which contains the action definition data required by the Workplace Integration Servlet. Actions that make use of custom pages may reference other resources.

    Bp8Actions.xml

    This section will detail the data stored in the Bp8Actions.xml file for the quick checkout function (as an example) and the Bp8ExtCommands.xml file. Locate the Bp8Actions.xml file under your BPF deployment folder bpf/WEB-INF/. The entries in Bp8Actions.xml that are specific to quick checkin are detailed in red below. The value key for the quick checkin is quickCheckin.

    <!-- top level actions -->
    <array key="topLevelActions">
       <value>checkout</value>
       <value>cancelCheckout</value>
       <value>checkin</value>
       <value>quickCheckin</value>
     </array>

    This will result in a new actionDefinition as below. Change the values as noted in the sample below to modify the settings to re-label this action, change the associated icon, and point the action to the file document .jsp page from the Workplace application.

    <object key="actionDefinition">
    <setting key="id">quickCheckin</setting> <-- Matches the key value in top level actions above
    <setting key="title" localizationKey="bp8.client.QuickCheckIn">Quick Checkin</setting> <--Changes the display label in the context menu
    <setting key="url">
      ExtCommand.jsp?ExtTask=QuickCheckIn&amp; <-- Calls the ExtCommand.jsp requesting the "QuickCheckIn" action defined in Bp8ExtCommands.xml
      objectStoreName={OBJECT_STORE_NAME}&amp;
      label={OBJECT_LABEL}&amp;
      id={OBJECT_ID}&amp;
      objectType={OBJECT_TYPE}&amp;
      vsId={VERSION_SERIES_ID}&amp;
      majorVersion={MAJOR_VERSION}&amp;
      minorVersion={MINOR_VERSION}&amp;
      versionStatus={VERSION_STATUS}&amp;
      returnUrl={RETURN_URL}&amp;
      mimeType={CONTENT_TYPE}&amp;
      selectEventName=StateChanged&amp;
      selectEventCommand=checkout&amp;
     </setting>
    <setting key="img">img/action/File16.gif</setting> <--Changes the associated icon on the context menu.
    <setting key="showInPath">false</setting>
    <setting key="hideInThickClientWindow">true</setting>
     <array key="objectTypes">
       <value>document</value>
     </array>
    <array key="excludedContentTypes">
       <value>application/x-filenet-entrytemplate</value>
       <value>application/x-filenet-documententrytemplate</value>
       <value>application/x-filenet-folderentrytemplate</value>
       <value>application/x-filenet-customobjectentrytemplate</value>
       <value>application/x-filenet-formdataentrytemplate</value>
       <value>application/x-filenet-declarerecordentrytemplate</value>
       <value>application/x-filenet-documentpolicy</value>
       <value>application/x-filenet-workflowpolicy</value>
       <value>application/x-filenet-formdata</value>
       <value>application/x-filenet-rm-physicalrecord</value>
       <value>application/x-filenet-rm-electronicrecord</value>
       <value>application/x-filenet-rm-emailrecord</value>
    </array>
    <setting key="isPopup">true</setting>
    <setting key="isPopupInMultiSelect">true</setting>
    <setting key="popupHeight">250</setting>
    <setting key="popupWidth">600</setting>
     <array key="versionStatusConditions">
       <value>inprocess</value>
       <value>released</value>
     </array>

    Bp8ExtCommands.xml

    The Bp8ExtCommands.xml file contains data specific to Workplace Integration Servlet commands. The COMMAND ID value in red below is a direct match to the <setting key="url"> parameter located in the Bp8Actions.xml file action definition. The EXTERNALID value directly correlates to the Workplace Integration Servlet command ID. (See the Command Reference section of the Integrating with Workplace topic in the FileNet P8 Platform documentation.) Note that required parameters vary depending upon the servlet command being initiated.

    <COMMAND ID='QuickCheckIn' EXTERNALID='4060' CLASS='com.filenet.bp8.apps.server.integration.RedirectCommand'>
     <PARAMETERS>
      <PARAMETER NAME='objectStoreName' REQUIRED='true' ENCODING='no'>
      </PARAMETER>
      <PARAMETER NAME='id' REQUIRED='false' ENCODING='no'>
      </PARAMETER>
      <PARAMETER NAME='vsId' REQUIRED='false' ENCODING='no'>
       <VALUE>The Version Series Id of Document</VALUE>
      </PARAMETER>
      <PARAMETER NAME='objectType' REQUIRED='true' ENCODING='no'>
      </PARAMETER>
      <PARAMETER NAME='rootDocClass' REQUIRED='false' ENCODING='no'>
      </PARAMETER>
      <PARAMETER NAME='restrictDocClass' REQUIRED='false' ENCODING='no'>
      </PARAMETER>
      <PARAMETER NAME='op' REQUIRED='true' ENCODING='no'>
      </PARAMETER>
      <PARAMETER NAME='selectEventName' REQUIRED='true' ENCODING='no'>
      </PARAMETER>
      <PARAMETER NAME='quickCheckin' REQUIRED='true' ENCODING='no'>
      </PARAMETER>
     </PARAMETERS>
    </COMMAND>

    BPF context actions using custom pages

    Custom actions may be added to the BPF document context menus by modifying Bp8Actions.xml to invoke a custom Web page. The actions defined in Bp8Actions.xml that use the Workplace Integration Servlet reference the ExtCommand.jsp file located in the BPF root deployment folder. Actions that make use of custom web pages are entered in Bp8Actions.xml differently. The example below details modifying Bp8Actions.xml to call the WcmFileObject.jsp file in order to file the current document in a folder in the Workplace application.

    Extending Bp8Actions.xml with custom actions

    Custom actions may be added to the BPF document context menus by modifying Bp8Actions.xml. This section details the steps to add a custom action to the Bp8Actions.xml file to add a basic action to the context menu.

    For the sake of simplicity this example will add a link to the BPF sample help page (Bp8SampleHelp.jsp) to the BPF context menu.

    1. Add your target .jsp page to be called by your custom action.
      1. As a simple example, locate the Bp8SampleHelp.jsp file in the BPF deployment directory. It should be located under the /bpf root folder. Once you have validated the location of this file proceed to step 2.
    2. Add topLevelActions entry to the Bp8Actions.xml file.
      1. Locate the Bp8Actions.xml file under your BPF deployment folder bpf/WEB-INF/... Make a backup copy of the Bp8Actions.xml file. Open the Bp8Actions.xml file (not the backup copy) and add the following entry, denoted in red, to the topLevelActions section of the file.

        <!-- top level actions -->
        <array key="topLevelActions">
           <value>checkout</value>
           <value>cancelCheckout</value>
           <value>checkin</value>
           <value>quickCheckin</value>
           <value>BPFHelp</value>
        </arra

      2. Once this entry has been added, save the Bp8Actions.xml file but do not close it.
    3. Add the actionDefinition to the Bp8Actions.xml file.
      1. Locate the actionDefinitions section of the Bp8Actions.xml file. Copy the section for the Checkout action. Copy from the <object key="actionDefinition"> entry to the </object> entry (the entire definition for this action object). Do not copy the <list key="actionDefinitions"> tag itself.
      2. Locate the last action definition in the Bp8Actions.xml file. This should be a tag of </object> just before the closing of the actions list with the </list> tag. Paste the copy of the Checkout action below the </object> tag and before the </list> tag as shown below.

        </object>
        <<<----Your new action definition here.
         </list>

      3. This will result in a new actionDefinition as below. Change the values as noted in the sample below to modify the settings to re-label this action, change the associated icon, and point the action to the file document .jsp page from the Workplace application.

        <object key="actionDefinition">
        <setting key="id">BPFHelp</setting>
        <setting key="title" localizationKey="bp8.client.Bp8HelpSampleTool">BPF Help</setting> <--For localization a key will need to be added to string.xx.txt.
        <setting key="url">
           http://p8design:7001/bpf3510001/Bp8SampleHelp.jsp? <--Must be modified to point to the new .jsp file for your custom action as shown.
           objectStoreName={OBJECT_STORE_NAME}&amp;
           label={OBJECT_LABEL}&amp;
           id={OBJECT_ID}&amp;
           objectType={OBJECT_TYPE}&amp;
           vsId={VERSION_SERIES_ID}&amp;
           majorVersion={MAJOR_VERSION}&amp;
           minorVersion={MINOR_VERSION}&amp;
           versionStatus={VERSION_STATUS}&amp;
           returnUrl={RETURN_URL}&amp;
           mimeType={CONTENT_TYPE}&amp;
           selectEventName=StateChanged&amp;
           selectEventCommand=checkout&amp;
        </setting>
        <setting key="img">img/action/File16.gif</setting> <--Changes the associated icon on the context menu.
        <setting key="showInPath">false</setting>
        <setting key="hideInThickClientWindow">true</setting>
         <array key="objectTypes">
           <value>document</value>
         </array>
        <array key="excludedContentTypes">
           <value>application/x-filenet-entrytemplate</value>
           <value>application/x-filenet-documententrytemplate</value>
           <value>application/x-filenet-folderentrytemplate</value>
           <value>application/x-filenet-customobjectentrytemplate</value>
           <value>application/x-filenet-formdataentrytemplate</value>
           <value>application/x-filenet-declarerecordentrytemplate</value>
           <value>application/x-filenet-documentpolicy</value>
           <value>application/x-filenet-workflowpolicy</value>
           <value>application/x-filenet-formdata</value>
           <value>application/x-filenet-rm-physicalrecord</value>
           <value>application/x-filenet-rm-electronicrecord</value>
           <value>application/x-filenet-rm-emailrecord</value>
        </array>
        <setting key="isPopup">true</setting>
        <setting key="isPopupInMultiSelect">true</setting>
        <setting key="popupHeight">250</setting>
        <setting key="popupWidth">600</setting>
         <array key="versionStatusConditions">
           <value>inprocess</value>
           <value>released</value>
         </array

    Remove attachment action configuration

    The context menu action to remove attachments can be enabled or disabled per Inbasket configuration. The Allow Removing Attachments checkbox that is found in the Inbasket configuration options (properties display) in the BPF Explorer tool on the General tab controls this configuration. If this box is checked, this action will be available for this Inbasket. If it is not checked, this action will not be available on the context menu.

    Localization of action names

    The display names of context menu actions can be altered using localization settings. The values for localization keys are located in the string.xx.txt file for the applicable language. See the IBM FileNet Business Process Framework Localization Guide for detailed information about creating or updating localization values. The localizationKey value below is used to match a key from the current strings.xx.txt file (according to current browser language settings) to a display value. If a value exists in the strings.txt file the value in the Bp8Actions.xml file will be over-ridden. However, if no value exists in the strings.xx.txt file, the value set in Bp8Actions.xml will be used.

     <setting key="title" localizationKey="bp8.client.CheckOut">Check Out</setting>

    NOTE When adding BPF user-defined actions to P8 Workplace, such as openCase, refer to ECM Help for localizing entries in Actions.xml.