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.

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.

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.

You can find sample templates by creating a business manager extension cartridge using UX Studio. You can also find sample templates in the UX Studio support bundle, which you can download from any sandbox using a fixed URL: https://abcd-123.dx.commercecloud.salesforce.com/on/demandware.servlet/WFS/Studio/Sites/mock/demandware-mock.zip (use your username and WebDAV/UX Studio access key). The bm_extension.zip file within this bundle contains the example business manager extension and sample templates.

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:

   

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:

   

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:

   

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:

   

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_.

   

   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.

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:

   

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.

   

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.

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:

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:

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:

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.

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:

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:

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.

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.