Agent skill

b2c-business-manager-extensions

Create Business Manager extension cartridges for B2C Commerce. Use when building admin tools, BM menu items, or custom BM pages (bm_* cartridges). Covers bm_extensions.xml, menu items, dialog actions, and form extensions.

View SKILL.md on GitHub Repository
Stars 34
Forks 10

Install this agent skill to your Project

npx add-skill https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/tree/main/skills/b2c/skills/b2c-business-manager-extensions

SKILL.md

Business Manager Extensions Skill

This skill guides you through creating Business Manager (BM) extension cartridges to customize the admin interface.

Overview

BM extensions allow you to add custom functionality to Business Manager:

Extension Type Purpose
Menu Items Add top-level menu sections
Menu Actions Add functional links under menus
Dialog Actions Add buttons to existing BM pages
Form Extensions Add fields to existing forms

File Structure

/bm_my_extension
    /cartridge
        bm_extensions.xml           # Extension definitions (required)
        /controllers
            MyExtension.js          # Controller for menu actions
        /templates
            /default
                /extensions
                    mypage.isml     # Custom BM pages
        /static
            /default
                /icons
                    my-icon.gif     # Menu icons

Basic bm_extensions.xml

xml
<?xml version="1.0" encoding="UTF-8"?>
<extensions xmlns="http://www.demandware.com/xml/extensibility/2013-04-24">
    <!-- Menu Item: Creates section in navigation -->
    <menuitem id="my-tools" name="label.menu.mytools"
              site="false" position="10">
        <icon path="icons/my-icon.gif"/>
    </menuitem>

    <!-- Menu Action: Creates link under menu item -->
    <menuaction id="my-dashboard" menupath="my-tools"
                name="label.action.dashboard">
        <exec pipeline="MyExtension" node="Dashboard"/>
        <sub-pipelines>
            <pipeline name="MyExtension"/>
        </sub-pipelines>
    </menuaction>
</extensions>

Menu Items

Create top-level navigation sections:

xml
<menuitem id="custom-tools"
          name="label.menu.customtools"
          site="false"
          position="10">
    <description>Custom administration tools</description>
    <icon path="icons/tools-icon.gif"/>
</menuitem>
Attribute Required Description
id Yes Unique identifier
name Yes Resource key for display name
site No true = Site menu, false = Admin menu (default: true)
position No Sort order (higher = higher in list)

Menu Actions

Add functional pages under menu items:

xml
<menuaction id="product-export"
            menupath="custom-tools"
            name="label.action.productexport">
    <description>Export products to CSV</description>
    <exec pipeline="ProductExport" node="Start"/>
    <sub-pipelines>
        <pipeline name="ProductExport"/>
    </sub-pipelines>
    <icon path="icons/export-icon.gif"/>
</menuaction>
Attribute Required Description
id Yes Unique identifier
menupath No Parent menu item ID
name Yes Resource key for display name

Note: For controllers, use pipeline="ControllerName" and node="ActionName".

Dialog Actions

Add buttons to existing BM pages:

xml
<dialogaction id="order-export-btn"
              menuaction-ref="order-search"
              xp-ref="OrderPage-OrderDetails">
    <exec pipeline="OrderExport" node="Export"/>
    <icon path="icons/export.gif"/>
    <parameters>
        <parameter name="OrderNo"/>
    </parameters>
</dialogaction>
Attribute Required Description
id Yes Unique identifier
menuaction-ref Yes Parent menu action ID
xp-ref Yes Extension point ID

Common extension points: OrderPage-OrderDetails, ProductPage-Details, CustomerPage-Profile

Form Extensions

Add fields to existing BM forms:

xml
<formextension id="order-search-extension">
    <valueinput type="string" name="customOrderField">
        <label xml:lang="x-default">Custom Field</label>
        <label xml:lang="de">Benutzerdefiniertes Feld</label>
    </valueinput>
    <valueinput type="string" name="exportStatus">
        <label xml:lang="x-default">Export Status</label>
        <option>Pending</option>
        <option>Exported</option>
        <option>Failed</option>
    </valueinput>
</formextension>

Controller Example

javascript
'use strict';

var ISML = require('dw/template/ISML');
var URLUtils = require('dw/web/URLUtils');

exports.Dashboard = function () {
    ISML.renderTemplate('extensions/dashboard', {
        title: 'My Dashboard',
        data: getReportData()
    });
};
exports.Dashboard.public = true;

exports.ProcessAction = function () {
    var params = request.httpParameterMap;
    var itemId = params.itemId.stringValue;

    // Process the action
    var result = processItem(itemId);

    // Redirect back or show result
    response.redirect(URLUtils.url('MyExtension-Dashboard', 'result', result));
};
exports.ProcessAction.public = true;

Template Example

html
<!DOCTYPE html>
<html>
<head>
    <title>${pdict.title}</title>
    <link rel="stylesheet" href="${URLUtils.staticURL('/css/bm-custom.css')}"/>
</head>
<body>
    <div class="bm-content">
        <h1>${pdict.title}</h1>

        <table class="bm-table">
            <thead>
                <tr>
                    <th>ID</th>
                    <th>Name</th>
                    <th>Actions</th>
                </tr>
            </thead>
            <tbody>
                <isloop items="${pdict.data}" var="item">
                    <tr>
                        <td>${item.id}</td>
                        <td>${item.name}</td>
                        <td>
                            <a href="${URLUtils.url('MyExtension-ProcessAction', 'itemId', item.id)}">
                                Process
                            </a>
                        </td>
                    </tr>
                </isloop>
            </tbody>
        </table>
    </div>
</body>
</html>

Localization

Add resource bundles for labels:

templates/resources/bm_extensions.properties:

properties
label.menu.customtools=Custom Tools
label.action.dashboard=Dashboard
label.action.productexport=Product Export

templates/resources/bm_extensions_de.properties:

properties
label.menu.customtools=Benutzerdefinierte Werkzeuge
label.action.dashboard=Instrumententafel
label.action.productexport=Produktexport

Enabling the Extension

  1. Add cartridge to Business Manager site's cartridge path:

    • Administration > Sites > Manage Sites > Business Manager
    • Add cartridge ID to cartridge path

  2. Grant permissions to roles:

    • Administration > Organization > Roles
    • Select role > Business Manager Modules
    • Enable your custom modules

Best Practices

  1. Prefix IDs with your organization name to avoid conflicts
  2. Use resource keys for all displayed text (localization)
  3. Keep cartridge separate - don't mix with storefront cartridges
  4. Test permissions with different user roles
  5. Don't reference internal BM URLs - they may change

Detailed Reference

  • Extensions XML Reference - Complete XML schema and examples

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

SalesforceCommerceCloud/b2c-developer-tooling

api-client-development

Creating typed API clients with OpenAPI specs, authentication, and OAuth scopes for SCAPI and similar APIs. Use when adding a new SCAPI client, generating types from an OpenAPI spec, setting up OAuth middleware, or integrating a new Commerce API endpoint.

34 10
Explore
SalesforceCommerceCloud/b2c-developer-tooling

testing

Writing tests for the B2C CLI project using Mocha, Chai, and MSW. Use when writing unit or integration tests, mocking HTTP requests with MSW, testing CLI commands with oclif, isolating config in tests, setting up test coverage, using sinon stubs, c8 coverage, capturing or silencing stdout, or creating MSW handlers.

34 10
Explore
SalesforceCommerceCloud/b2c-developer-tooling

documentation

Updating user guides, CLI reference, and API documentation for the B2C CLI project. Use when adding or changing CLI command docs, writing JSDoc for TypeDoc generation, updating Vitepress sidebar config, or creating new guide pages.

34 10
Explore
SalesforceCommerceCloud/b2c-developer-tooling

cli-command-development

Creating new CLI commands and topics for the B2C CLI using oclif. Use when adding a new command, creating a topic, adding flags or arguments, implementing table output, or extending BaseCommand/OAuthCommand/InstanceCommand.

34 10
Explore
SalesforceCommerceCloud/b2c-developer-tooling

sdk-module-development

Adding new modules and exports to the @salesforce/b2c-tooling-sdk package. Use when creating a new SDK module, adding barrel file exports, configuring package.json exports, or building client factory functions.

34 10
Explore
SalesforceCommerceCloud/b2c-developer-tooling

b2c-code

Deploy and manage code versions/cartridges on B2C Commerce instances/sandboxes with the b2c cli. Always reference when using the CLI to upload cartridges, deploy code, activate code versions, manage code versions, or watch for file changes during development.

34 10
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results