Customizing Actions on an Object

This topic applies to the administrator or developer, depending on the desired level of customization.

For the various objects accessible through the FileNet P8 Workplace application, the application presents a set of operations or actions that an end user can perform on a particular object type. For example, the actions available for a document object include checkout, download, change to compound, and move; for a folder object, they include add objects, move, and delete.

As an administrator, you can customize the actions that can be performed on any object that appears in the Workplace UI. You can do cosmetic-type configurations, like removing an action completely from the UI or changing an action icon. Drawing from a number of filtering criteria, you can also define the conditions under which an action will appear. For example, you can define the download action to appear only when users click on documents of a certain class description, version status, and content type.

As a developer with an understanding of the underlying framework of the Workplace application, you can add new actions. See the FileNet Web Application Toolkit Developer's Guide for information on the framework and base modules on which Workplace is built.

This topic points out the places in the Workplace UI where actions are presented to users, and describes the actions descriptor XML file used to configure actions.

Actions in the Workplace UI

Actions are available to the user in context menus, in the Actions menu, and on Information pages.

As shown below, the context menu appears when a user right-clicks on an object in a list view, or on the last item in the path view. The list of available actions will depend on the type of object selected. The same actions appear in the Information page for the object.

context menu

When a user selects one or more items in the list view, then clicks the "Actions Menu" button, the Action menu opens. If multiple items are selected as shown below, only the actions that are valid for all selected items are shown in the menu.

Actions menu

Actions are also available on the Information page of an object.

Information page

Actions Descriptor XML File

Actions.xml contains the definitions of actions displayed in the context menu, multi-select menu, and on Information pages. The file is located in <AE_install_path>/FileNet/Config/AE folder. Actions.xml follows the Workplace Preferences XML Schema, Preferences.xsd, located in <AE_install_path>/Workplace/WEB-INF/xml.

NOTES  

File Structure

As shown in the listing below, Actions.xml consists of three sections: topLevelActions, multiSelectActions, and actionDefinitions. In the topLevelActions array and in the multiSelectActions array, you define the order of the actions as they appear in the UI. That is, in the topLevelActions array, the order of the value elements is reflected in the context menu and on the Information pages. In the multiSelectActions array, the order of the value elements is reflected in the multi-select menu. You can hide actions by commenting them out.

In the multiSelectActions array, you can specify actions to be multi-select only; that is, a multi-select action does not have to be listed in the topLevelActions array.

The actionDefinitions list consists of actionDefinition objects, each of which contains a list of conditions which define whether the action is displayed for each individual object. Note that a top-level action can contain a submenu, and if it does, its action definition must include a subActions setting. Also note that the definition for an action listed in the multiSelectActions array must include a multiSelectURL setting. See Action Definition Settings for a description of all settings.

Sections in the Actions Descriptor XML File

<object key="actionsConfiguration" version="4.0">
  <array key="topLevelActions">
    <value>download</value>
    <value>checkout</value>
    <value>cancelCheckout</value>
    <value>checkin</value>
    <value>save</value>
    <value>file</value>
    <value>unfile</value>
    <value>deleteVersions</value>
    <value>delete</value>
    <value>move</value>
    <value>addToWeb</value>
    <value>removeFromWeb</value>
    <value>demoteVersion</value>
    <value>promoteVersion</value>
    <value>addToShortcuts</value>
    <value>addDocument</value>
    <value>addFolder</value>
     ...
  </array>
  <array key="multiSelectActions">
    <value>download</value>
    <value>checkout</value>
    <value>cancelCheckout</value>
    <value>file</value>
    <value>moveFolder</value>
    <value>delete</value>
    <value>assignSecurityPolicy</value>
    <value>sendMail</value>
  </array>
  <list key="actionDefinitions">
    <object key="actionDefinition">
      <setting key="id">download</setting>
      <setting key="title"
          localizationKey="server.Actions_xml.download">
        Download
      </setting>
      <setting key="url">
        getContent?
        mode=download&amp;
        objectType={OBJECT_TYPE}&amp;
        id={OBJECT_ID}&amp;
        vsId={VERSION_SERIES_ID}&amp;
        objectStoreName={OBJECT_STORE_NAME}
      </setting>
      <setting key="multiSelectURL">
        operations/WcmMultiDownloadObject.jsp?
        returnUrl={RETURN_URL}
      </setting>
      <setting key="img">images/action/Download16.gif</setting>
      <setting key="showInPath">false</setting>
      <setting key="hideInThickClientWindow">true</setting>
      <array key="objectTypes">
        <value>document</value>
      </array>
</object>

Action Definition Settings

The following table describes each action definition setting in Actions.xml. Each setting is identified by its key attribute. Unless otherwise specified, a setting is optional. If an optional setting is not present, its default value is used.

Key Setting Value
baseURLKey <setting key="baseURLKey">
  rm
</setting>
If this setting is present, the base URL of the Records Manager application will be used instead of the Workplace base URL (the default). The only valid value is "rm".
classes <array key="classes">
  <value>{63F8AA94-E2B9-11D0
      -ADF6-00C04FB66DAD}</value>
  <value>{A73BEEB2-B0B7-11D2
      -8853-0000F80883E3}</value>
</array>
Defines the list of classes that are valid for this action. The values must be in GUID format. The action will be available only for the classes listed.

NOTE  If this setting is present, exclude excludedClasses.
contentTypes <array key="contentTypes">
  <value>image/jpeg</value>
  <value>image/tiff</value>
  <value>text/*</value>
  <value>application/??-word</value>
</array>
Defines the list of mime types and container types valid for this action. The action will be available only for objects of the specified content types. If not present, this action will be available for all content types.

The values in this setting support "*" and "?" wildcards. "*" means any number of characters (including 0 characters). "?" means one character.

NOTE  If this setting is present, exclude excludedContentTypes.
customObjectsOnly <setting key="customObjectsOnly">
  true
</setting>
If the value is true, this action will only appear when custom objects are enabled in the Site Preferences. Note that this setting applies only to the addCustomObject action definition. Default value is true.
excludedClasses <array key="excludedClasses">
  <value>{d24d4450-1f01-11d1
      -8e63-006097d2df48}</value>
  <value>{f81e9010-6ea4-11ce
      -a7ff-00aa003ca9f6}</value>
</array>
Defines the list of classes that are not valid for this action. The values must be in GUID format. The action will not be available for the classes listed.

NOTE  If this setting is present, exclude classes.
excludedContentTypes <array key="excludedContentTypes">
  <value>text/xml</value>
  <value>text/plain</value>
</array>
Defines the list of mime types and container types invalid for this action. The action will be available for all objects that are not of any listed content types. The values in this setting also support "*" and "?" wildcards.

NOTE  If this setting is present, exclude contentTypes.
excludedObjectTypes <array key="excludedObjectTypes">
  <value>storedsearch</value>
  <value>publishtemplate</value>
  <value>securitytemplate</value>

</array>
Defines the list of object types invalid for this action.

NOTE  If this setting is present, exclude objectTypes.
hiddenForGuests <setting key="hiddenForGuests">
  true
</setting>
If the value is true, the action will be hidden from users signed on as guests. Default value is false.
hideForVersions <setting key="hideForVersions">
   true
</setting>
If the value is true, this action will not be shown for a version of an object in an Information page. That is, if from an Information page for an object you go to the "Versions" property page, then go to the Information page for a particular object, the action will not be available. Default value is true.
hideInShortcutsPage <setting key="hideInShortcutsPage">
  true
</setting>
If the value is true, the action will not appear on the Shortcuts page. This key is applicable only to the addToShortcuts and addToShortcutsForDocObjType action definitions. Default value is false.
hideInThickClientWindow <setting key="hideInThickClientWindow">
  true
</setting>
If the value is true, the action will not be shown in a thick client window. This is used by Application Integration to turn off some actions. Default value is false.
img <setting key="img">
  images/action/TestAction16.gif
</setting>
Defines the icon for the action. This setting is not required. The value must be a valid path to an image with a size of 16x16 pixels.

NOTE  Similar to url, you can use a relative path.
isPopup <setting key="isPopup">
  true
</setting>
If the value is true, this action will open in a new window when one object is selected. Default value is false.
isPopupInMultiSelect <setting key="isPopupInMultiSelect">
  false
</setting>
If the value is true, this action will open in a new window when two or more objects are selected. Default value is true.
multiSelectPopupHeight <setting key="multiSelectPopupHeight">
  250
</setting>
Defines the pixel height of the new window. This setting is ignored if isPopup is set to false, or if multiSelectURL is not used. Default value is 600.
multiSelectPopupWidth <setting key="multiSelectPopupWidth">
  550
</setting>
Defines the pixel width of the new window. This setting is ignored if isPopup is set to false, or if multiSelectURL is not used. Default value is 800.
multiSelectURL <setting key="multiSelectURL">
  operations/WcmMultiDownloadObject.jsp?
  returnUrl={RETURN_URL}
</setting>
Defines multi-select URL. It defines the URL of the page that implements the multi-select action. Any action that supports multi-select must have this setting. The action must also be included in the multiSelectActions section of Actions.xml.
objectTypes <array key="objectTypes">
  <value>document</value>
  <value>folder</value>
  <value>customobject</value>
</array>
Defines the list of object types valid for this action. If this setting is not present, all object types are valid. Valid values are:
 - objectstore
 - folder
 - document
 - storedsearch
 - searchtemplate
 - customobject
 - link
 - event

NOTE  If this setting is present, exclude excludedObjectTypes.
popupHeight <setting key="popupHeight">
  250
</setting>
Defines the pixel height of the new window. This setting is ignored if isPopup is set to false. Default value is 600.
popupWidth <setting key="popupWidth">600
</setting>
Defines the pixel width of the new window. This setting is ignored if isPopup is set to false. Default value is 800.
rmOnly <setting key="rmOnly">
  false
</setting>
If the value is true, this action will only appear when Records Manager is turned on in the Site Preferences. Default value is false.
roles <array key="roles">
  <value>PSDesigner</value>
  <value>PWAdministrator</value>
</array>
Defines the list of access roles that are valid for this action. Only users that are members of one or more of the listed roles will see the action. Access roles are defined on the Content Engine. Default value is "Everyone".

NOTE  You can also set roles in Site Preferences, Actions Role Access page.
showInPath <setting key="showInPath">
  false
</setting>
If the value is true, this action will appear on the context menu when the user clicks on the last item in the path view. Default value is false.

NOTE  This setting applies only to objects that appear in the path view, such as an object store or folder. It is irrelevant for other object types.
subActions <array key="subActions">
  <value>infoProperties</value>
  <value>infoSystemProperties</value>
  <value>infoSecurity</value>
  <value>infoFolders</value>
</array>
Defines the list of actions displayed in a submenu. Note that you must define an actionDefinition for each value in the subActions array.

NOTE  You can only have one level of submenus; no action listed in the subActions array can have submenus of its own.
testAction <setting key="id">
  testAction
</setting>
Defines the ID for the action. This setting is required and the value has to be unique for each action.
title <setting key="title">
  TEST ACTION
</setting>
Defines the action's label, which will appear in the UI. This setting is required.
titleForSitePreferences <setting key="titleForSitePreferences">
  Download Documents
</setting>
The title of the action as it appears in Site Preferences, Actions Role Access page. If this setting is excluded, the value of title is used.
url <setting key="url">
  operations/MyOperation.jsp?
  id={OBJECT_ID}&amp;
  classId={CLASS_ID}&amp;
  label={OBJECT_LABEL}&amp;
  objectStoreName={OBJECT_STORE_NAME}&amp;
  minorVersion={MINOR_VERSION}&amp;
  objectType={OBJECT_TYPE}&amp;
  vsId={VERSION_SERIES_ID
</setting>
Defines the URL pattern. This setting is required. It 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  Spaces and line breaks are allowed in the value of this setting for convenience. When Actions.xml is read, spaces and line breaks are automatically removed from this string -- they are not valid URL characters.
useToken <setting key="useToken">
  true
</setting>
If the value is true, a user token will be appended to the URL before redirecting. This will only happen if token support is turned on in Site Preferences. Default value is false.
versionStatusConditions <array key="versionStatusConditions">
  <value>released</value>
  <value>superseded</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
 - 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 information on these values, see Versioning Properties.
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 UI.
{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"
{TIME_ZONE} The time zone ID. Use this macro in calls to the Application Engine UI Service, so that the time displayed on pages invoked through the AE UI Service are synched up with the time zone of the calling application. Note that this macro is useful only for a url setting that specifies a remote Workplace application rather than the local Workplace application from which the Actions menu is invoked. In this situation, the remote Workplace page that is invoked will display the time zone of the local Workplace application.

The AE UI Service is referenced by integrationWebBasedCommand, the URL pattern to which the service is mapped. The following example shows a url setting for the AE UI Service:

<setting key="url">http://remoteServer:8080/integrationWebBasedCommand?_commandId=1540&objectStoreName={OBJECT_STORE_NAME}&objectId={OBJECT_ID}&folderId={FOLDER_ID}&returnUrl={RETURN_URL}&contentType={CONTENT_TYPE}&timeZone={TIME_ZONE}</setting>

NOTE  Any valid time zone ID which is supported by the JDK is available for use in custom applications built with Workplace Application Toolkit or the AE UI Service. The JDK includes the TimeZone class (representing a time zone offset) that offers methods, such as getAvailableIDs, which can be used to iterate through all of the supported time zone IDs. For more information on obtaining or constructing a valid time zone ID, see the appropriate JDK documentation on the IBM Developer Kits site.