Customize Business Manager

You can create a custom cartridge to modify existing Business Manager pages and add new ones.

The following four parts of the Business Manager user interface can be extended.

  • menu items
  • menu actions
  • dialog actions
  • forms

Each of the four types of extensions provides a different way to hook custom functionality into Business Manager. Because standard Business Manager menus use menu items and menu actions to access business functionality, Business Manager Extensions provided by merchants seamlessly integrate with existing menus.

Your custom Business Manager menus and functions must not reference Business Manager (core) URLs, because they are not part of the standard Salesforce B2C Commerce API. They can be changed in any release (even hotfix level) without further notice.

Business Manager extensions are defined in XML files that are read during server startup. These XML files are placed in cartridges that implement the portions of Business Manager. A B2C Commerce server without customization has only one XML file located in the app_business_manager cartridge. This file contains all the menu items and menu actions you can see in an unaltered Business Manager.

The Business Manager extensions framework takes the list of cartridges assigned to Sites to collect all XML files from which to load Business Manager extensions. All Business Manager extensions read from the XML files are merged into a table. The table contains the Business Manager extensions that are applicable for the current organization.

You can customize certain Business Manager functionality by creating a custom cartridge and modifying specific ISML templates in it. These templates, which override standard Business Manager templates, exist in folders under /cartridge/templates/default. You can only customize the Business Manager templates listed here.

FolderCustomizable Templates
/cartridge/templates/default/application
  • MenuFrame.isml
/cartridge/templates/default/custom
  • modules.isml
/cartridge/templates/default/marketing
  • giftcertificateemail.isml
  • powerreviewsemail.isml
/cartridge/templates/default/order
  • orderdetails.isml
  • orderemailcancellation.isml
  • orderemailconfirmation.ismal
  • orderemailcss.isml
  • orderemailgeneral.isml
  • orderemailpaymentconfirmation.isml
  • orderemailshippingconfirmation.isml
  • paymentdetails.isml
  • printordergeneral.isml
  • printorderinvoice.isml
  • printorderpackingslip.isml
/cartridge/templates/default/user
  • miniaddress.isml
  • minicreditcard.isml
  • minishippingaddress.isml
  • passwordemail.isml

For example, a merchant conducts business in a region that uses VAT (Value-Added Tax), and wants to print legally valid VAT invoices from the Order page. The output of the standard invoice print function does not qualify. To implement this functionality, customize the /cartridge/templates/default/order/printorderinvoice.isml template to add the required information to the output of the Print Invoice button.

  1. Set up a custom cartridge.

  2. Create a file with name *bm_extensions.xml_in directory/*\<cartridge_name>*/cartridge of your custom cartridge.

  3. Add the following lines of XML to your file:

    XML Snippet for Business Manager Extension

  4. Add the extension to that file.

  5. Implement the extension you want by implementing B2C Commerce scripts, pipelines, and templates. Place that implementation in your custom cartridge.

  6. Deploy your custom cartridge to the server.

  7. Add the cartridge to the cartridge path at Administration > Sites > Manage Sites > Sites-Site: < Effective Cartridge Path >.

  8. Test extensions.

To add a menu item, for example, Merchants Custom Menu Item:

  1. Add the following XML in the <extensions> tag to your bm_extensions.xml file:

    XML Snippet for Custom Menu Item

  2. Choose a unique ID for the menu item.

  3. Place the menu item in the Administration navigation menu by setting the site attribute to false.

  4. Use the position attribute to place the new menu item in the preferred order in the navigation list. The higher the number, the higher in the list it appears.

  5. To enhance the menu item, you can assign an image to it; put the image in directory /*\<cartridge_name>*/cartridge/static/default/<my-image-directory>. If you want different images for different languages, make sure to have a separate directory for each language. Use the ISO locale of the language as the directory name.

Menu actions are the bridge between the navigation (menu item) and the business functionality. To link the navigation (menu item) with the business logic:

  1. Add the following XML inside the <extensions> tag to your bm_extensions.xml file:

    XML Snippet for Custom Menu Action

  2. Supply a unique ID to the menu action.

  3. Because the parent menu item is hooked into the Administration section of the navigation, set this site attribute to false.

    You can't add a menu action under a menu action. It must be below an existing menu item (custom or supplied by Salesforce).

  4. When selecting a menu action at the Business Manager overview, a pipeline is executed to show the first page of your custom business functionality. Specify the name of that pipeline and start node in the XML element exec:

    Pipeline and Start Node in the XML Element exec

  5. List all pipelines that implement your menu action in the menu action's XML definition. List them inside the < subpipelines> tag. Use a separate < _pipeline__ for each pipeline. If only some of a pipeline's start nodes belong to the menu action, you can restrict it by specifying __name of the pipeline-Name of the start node_.

    XML Snippet Sub Pipeline

    Always add the exec-pipelines to the < subpipelines> section. Non-public pipelines (where all start nodes have call mode = "Private") need not be added to the < subpipelines> section.

  6. After successfully deploying your cartridge on the server, you can grant permissions on the menu action.

Change the context to a site if your menu action is site-specific.

Don't change the ID of a menu action after you have granted permissions on it. Otherwise, you have to grant permissions again and the former permission remains in the database, unused.

Dialog actions hook into existing Business Manager page. The dialog action can open a popup or navigate to a subpage.

  1. Add your custom dialog to the bm_extensions.xml file:

    XML Snippet for Custom Dialog Action

  2. Select a unique ID for the dialog action.

  3. Choose the extension point from the list of available extension points (to which you want to hook the dialog action). The extension points are listed at the end of the bm_extension.xml file.

  4. Add this ID as a value of the xp_ref attribute to the XML.

  5. Make sure the tag < exec pipeline=.. contains the name of the pipeline executed when the user clicks the button of the dialog actions hook.

  6. To open a popup, set the attribute extern to true. Make sure the page to be opened is designed to appear as a popup.

  1. Add the form extension to bm_extensions.xml.

    XML Snippet for Custom Form Extension

  2. Choose the ID (into which you want to add the form extension) from the list of available extension points.

  3. Add this ID to the XML as the attribute ID value. Each <valueinput> element is rendered as an HTML form input field. The name of the form field must be unique within your form extension. Each form input field must specify the type of input data captured by the form field. Available data types are string, int, double.

  4. Specify a label to appear beside the form field. Specify the label at least for x-default locale. Add more < *label...*elements to localize for other languages.

Make sure that the search attributes defined by attribute name map to the attributes of the business object to search for. For example, if you extend Order Search, you can view that business object's attributes by selecting Administration > Site Development > System Object Types > Order > Attribute Definitions.

Business Manager Form Extensions only support custom attributes; they don't support system attributes.

You can customize Business Manager user interface elements to meet your storefront information management requirements:

Business Manager has two first-level navigation elements: Administration and Site. A Business Manager menu item is a second-level navigation element in the Business Manager navigation panel. You can decide that you want more menu items than are supplied with Business Manager.

A menu item has the following properties:

PropertyUsageDescription
IDMandatory, uniqueidentifies the menu item; must be unique across all menu items
NameMandatory, localizableThe caption of the menu item
DescriptionOptional, localizableDescribes the menu item; shown at the overview that appears upon selecting the item
Short descriptionOptional, localizableDescribes the menu item; used for GUI elements like tool tip texts and status bar messages
SiteOptionalIf True (default), then appears in the Site menu section; otherwise appears in the Administration section
PositionOptionalNumber indicating position of menu item within its main menu (default, last position)
IconOptionalRelative path name of icon image for this menu item; appears in content section when parent main menu item is selected in menu section

Business Manager menu actions are the third-level navigation element of Business Manager. They are submenu items of Business Manager menu items and are shown on the overview page of a menu item. Selecting a menu action at the overview page leads to the execution of an implemented functionality. Menu actions are the direct connection between the navigation panel and the actual business functionality. For example, the Products menu action is the linking element between the navigation and the list view that shows products.

A menu action has the following properties:

PropertyUsageDescription
IDMandatory, uniqueIdentifies the menu action; must be unique across all menu actions
MenupathOptionalID of the parent menu item to which this menu action is assigned; must refer to the ID of an existing menu item. The menu item can be in the same bm_extensions.xml file or in a bm_extensions.xml file of another cartridge that is loaded in the same application. If the menupath property refers to an unknown menu item, then the extension framework rejects the menu action and does not display it in the user interface. (This behavior prevents orphan menu items.)
NameMandatory, localizableThe name shown as the caption of the menu action
DescriptionOptional, localizableDescription of the menu action; shown at the overview that appears upon selecting the parent menu item
Short descriptionOptional, localizableShorter description of the menu action; used for GUI elements such as tool tip texts and status bar messages
SiteOptionalIf True (default), the menu item of this menu action appears in the Site menu section; otherwise appears in the Administration section. Value must be the same as the site attribute of the containing menu item (see Menupath property).
ExecOptionalEntry pipeline (and start node) to be executed when the menu action is selected
ParametersOptionalSome static parameters passed to the exec-pipeline
Sub-pipelinesMandatoryList of those pipelines that implement the menu action. All pipelines that are linked inside the menu action's business functionality must be specified here. The exec-pipeline is included.
SupportOptionalFlag indicating that this menu action is only visible to Commerce Cloud Support (default = false)
PositionOptionalNumber indicating the position of this menu action within its parent menu (default = last position)
ExternOptionalDefault = false; if true, selecting this menu action causes a new browser window to open
IconOptionalRelative path name of the image for the icon of this menu action; appears in the content section of the parent menu item
PermissionsOptionalDeprecated since server version 2.6. Required if migrating Business Manager extensions and access privileges from a pre-2.6 version to 2.6

Business Manager dialog actions enable you to add new functionality to the pages of a menu action. HTML buttons represent the extension points in which to hook dialog actions. Selecting a corresponding button on pages (templates) executes them. Existing templates contain extension points that are referenced using a unique ID.

Dialog actions have the following properties:

PropertyUsageDescription
ID Identifies the dialog action; must be unique across all dialog actions
NameOptionalNames the action
Extension point reference ID of the extension point where this action is made accessible by the user
Exec The pipeline and start node to be executed when a user triggers the action
Menuaction-refMandatoryThe menu action where the dialog action extension is hooked in
ParametersOptionalThe names of the context parameters whose values are passed as dictionary entries to the executed pipeline
PositionOptionalA number indicating the position within all the actions linked to the same extension point
ExternOptionalDefault = false; if true, clicking the button representing this dialog action triggers a new browser dialog to open

Business Manager form extensions are a way to extend existing Business Manager forms, such as the search form, with more form fields. The values entered into these fields can be of type string, int, or double, and predefined values (options) can be specified for each field.

Business Manager form extensions only support custom attributes; they don't support system attributes.

When the additional fields have been declared in the XML descriptor (bm_extensions.xml), an arbitrary form containing a specific ISML tag (<isformextension ..>) can access that data, or, more specifically, a search form containing another specific ISML tag (<issearchformextension ..>) automatically contains the added (search) fields. To enable this functionality, you must specify a unique ID for the FormExtension in the XML file and in the ISML file that is supposed to use the respective data.

Salesforce recommends that you make every Business Manager form extensible by adding one of these form extension ISML tags, specifying extension IDs to use later in the XML descriptor (bm_extensions.xml). Choose IDs carefully, possibly by including parts of the corresponding pipeline or ISML template name (for example, order-search).

When defining a Business Manager form extension, the following attributes of the <formextension ..> element are specified:

PropertyDescription
IDA unique identifier of this extension

The direct child elements of the <formextension id=".."> tag are <valueinput..> elements. These elements each correspond to an added field and have the following attributes:

PropertyUsageDescription
Type string, int, or double
Name The name of the field, also used as the name for the respective GET / POST parameter
DefaultvalueOptionalA default value for this field

Child elements must be specified for each <valueinput..> element. One is the <label..> element, which contains a descriptive label for this field. Because it's localizable, multiple <label..> elements can occur at the same level (that is, for the same field or value input). Salesforce recommends that you specify at least one label, preferably with the default locale; attributes are as follows:

|xml:lang|Any locale ID (for example, en_US), or "x-default" to specify the default label for any locale not specified here explicitly|

The <option> element is also available. It has no attributes (and thus is not localizable). Use it to encapsulate any text that could appear as an option for this value input.

If at least one option is specified, the user can no longer enter text freely, but must select from a set of options.

If any options are specified, and a default value is given, this value must be specified as one of the available options.

Business Manager provides a convenient way for you to determine your application's deprecated API usage.

For a list of deprecated APIs, refer to What's New page provided with each release of the API.

  1. Select Administration > Site Development > Deprecated API Usage.

    With the proper permission, you can now see a list of deprecated APIs and their current usage. The usage count reflects the number of times a deprecated method was called within the last 24 hours.