From 0e2c956a9d92dab9380625fa347c0cf7943c8c65 Mon Sep 17 00:00:00 2001 From: Charles Lavery Date: Sat, 10 Jan 2026 13:39:49 -0500 Subject: [PATCH 01/13] Add B2C Commerce agent skills with XSD-validated XML examples Add 9 agent skills for B2C Commerce development guidance: **Developer Skills (plugins/b2c/skills/):** - b2c-custom-job-steps: Task and chunk-oriented job step creation - b2c-controllers: SFRA and classic controller patterns - b2c-isml: ISML template tags and expressions - b2c-forms: Form XML definitions and SFRA handling - b2c-localization: Resource bundles and locale support - b2c-business-manager-extensions: BM menu items and extensions - b2c-page-designer: Page and component development - b2c-metadata: System object extensions and custom objects **CLI Skills (plugins/b2c-cli/skills/):** - b2c-site-import-export: Site archive import/export with CLI **Validation against official sources:** - Validated against official B2C Commerce documentation - XML examples validated against XSD schemas from dwre-tools - Key fixes applied: - steptypes.json location (cartridge root, not inside cartridge/) - preferences.xml structure (custom-preferences/preference) - Value definitions use not - Custom object data uses not - ISML tag location constraints documented - Parameter validation attributes for job steps --- .../skills/b2c-site-import-export/SKILL.md | 243 ++++++++++ .../references/METADATA-XML.md | 365 +++++++++++++++ .../b2c-business-manager-extensions/SKILL.md | 258 +++++++++++ .../references/EXTENSIONS-XML.md | 407 ++++++++++++++++ plugins/b2c/skills/b2c-controllers/SKILL.md | 301 ++++++++++++ .../references/CLASSIC-PATTERNS.md | 335 ++++++++++++++ .../references/SFRA-PATTERNS.md | 400 ++++++++++++++++ .../b2c/skills/b2c-custom-job-steps/SKILL.md | 350 ++++++++++++++ .../references/CHUNK-ORIENTED.md | 375 +++++++++++++++ .../references/STEPTYPES-JSON.md | 373 +++++++++++++++ .../references/TASK-ORIENTED.md | 344 ++++++++++++++ plugins/b2c/skills/b2c-forms/SKILL.md | 377 +++++++++++++++ .../skills/b2c-forms/references/FORM-XML.md | 400 ++++++++++++++++ plugins/b2c/skills/b2c-isml/SKILL.md | 320 +++++++++++++ .../skills/b2c-isml/references/EXPRESSIONS.md | 366 +++++++++++++++ .../b2c/skills/b2c-isml/references/TAGS.md | 425 +++++++++++++++++ plugins/b2c/skills/b2c-localization/SKILL.md | 344 ++++++++++++++ .../b2c-localization/references/PATTERNS.md | 399 ++++++++++++++++ plugins/b2c/skills/b2c-metadata/SKILL.md | 345 ++++++++++++++ .../b2c-metadata/references/SYSTEM-OBJECTS.md | 320 +++++++++++++ .../b2c-metadata/references/XML-EXAMPLES.md | 351 ++++++++++++++ plugins/b2c/skills/b2c-page-designer/SKILL.md | 353 ++++++++++++++ .../references/ATTRIBUTE-TYPES.md | 436 ++++++++++++++++++ .../references/META-DEFINITIONS.md | 322 +++++++++++++ 24 files changed, 8509 insertions(+) create mode 100644 plugins/b2c-cli/skills/b2c-site-import-export/SKILL.md create mode 100644 plugins/b2c-cli/skills/b2c-site-import-export/references/METADATA-XML.md create mode 100644 plugins/b2c/skills/b2c-business-manager-extensions/SKILL.md create mode 100644 plugins/b2c/skills/b2c-business-manager-extensions/references/EXTENSIONS-XML.md create mode 100644 plugins/b2c/skills/b2c-controllers/SKILL.md create mode 100644 plugins/b2c/skills/b2c-controllers/references/CLASSIC-PATTERNS.md create mode 100644 plugins/b2c/skills/b2c-controllers/references/SFRA-PATTERNS.md create mode 100644 plugins/b2c/skills/b2c-custom-job-steps/SKILL.md create mode 100644 plugins/b2c/skills/b2c-custom-job-steps/references/CHUNK-ORIENTED.md create mode 100644 plugins/b2c/skills/b2c-custom-job-steps/references/STEPTYPES-JSON.md create mode 100644 plugins/b2c/skills/b2c-custom-job-steps/references/TASK-ORIENTED.md create mode 100644 plugins/b2c/skills/b2c-forms/SKILL.md create mode 100644 plugins/b2c/skills/b2c-forms/references/FORM-XML.md create mode 100644 plugins/b2c/skills/b2c-isml/SKILL.md create mode 100644 plugins/b2c/skills/b2c-isml/references/EXPRESSIONS.md create mode 100644 plugins/b2c/skills/b2c-isml/references/TAGS.md create mode 100644 plugins/b2c/skills/b2c-localization/SKILL.md create mode 100644 plugins/b2c/skills/b2c-localization/references/PATTERNS.md create mode 100644 plugins/b2c/skills/b2c-metadata/SKILL.md create mode 100644 plugins/b2c/skills/b2c-metadata/references/SYSTEM-OBJECTS.md create mode 100644 plugins/b2c/skills/b2c-metadata/references/XML-EXAMPLES.md create mode 100644 plugins/b2c/skills/b2c-page-designer/SKILL.md create mode 100644 plugins/b2c/skills/b2c-page-designer/references/ATTRIBUTE-TYPES.md create mode 100644 plugins/b2c/skills/b2c-page-designer/references/META-DEFINITIONS.md diff --git a/plugins/b2c-cli/skills/b2c-site-import-export/SKILL.md b/plugins/b2c-cli/skills/b2c-site-import-export/SKILL.md new file mode 100644 index 00000000..331681bd --- /dev/null +++ b/plugins/b2c-cli/skills/b2c-site-import-export/SKILL.md @@ -0,0 +1,243 @@ +--- +name: b2c-site-import-export +description: Using the B2C CLI for site archive import/export with metadata XML patterns +--- + +# Site Import/Export Skill + +Use the `b2c` CLI plugin to import and export site archives on Salesforce B2C Commerce instances. + +## Import Commands + +### Import Local Directory + +```bash +# Import a local directory as a site archive +b2c job import ./my-site-data + +# Import and wait for completion +b2c job import ./my-site-data --wait + +# Import a local zip file +b2c job import ./export.zip + +# Keep the archive on the instance after import +b2c job import ./my-site-data --keep-archive + +# Show job log if the import fails +b2c job import ./my-site-data --wait --show-log +``` + +### Import Remote Archive + +```bash +# Import an archive that already exists on the instance (in Impex/src/instance/) +b2c job import existing-archive.zip --remote +``` + +## Export Commands + +```bash +# Export site data +b2c job export + +# Export with specific configuration +b2c job export --wait +``` + +## Common Workflows + +### Adding a Custom Attribute to Products + +1. Create the metadata XML file: + +**meta/system-objecttype-extensions.xml:** +```xml + + + + + + Vendor SKU + string + false + true + + + + + Custom Attributes + + + + + +``` + +2. Create the directory structure: +``` +my-import/ +└── meta/ + └── system-objecttype-extensions.xml +``` + +3. Import: +```bash +b2c job import ./my-import --wait +``` + +### Adding Site Preferences + +1. Create metadata for the preference: + +**meta/system-objecttype-extensions.xml:** +```xml + + + + + + Enable Feature X + boolean + false + + + + +``` + +2. Create preference values: + +**sites/MySite/preferences.xml:** +```xml + + + + + true + + + +``` + +3. Directory structure: +``` +my-import/ +├── meta/ +│ └── system-objecttype-extensions.xml +└── sites/ + └── MySite/ + └── preferences.xml +``` + +4. Import: +```bash +b2c job import ./my-import --wait +``` + +### Creating a Custom Object Type + +1. Define the custom object: + +**meta/custom-objecttype-definitions.xml:** +```xml + + + + API Configuration + source-to-target + site + + Config ID + string + 1 + + + + API Endpoint + string + + + API Key + password + + + Active + boolean + true + + + + +``` + +2. Import: +```bash +b2c job import ./my-import --wait +``` + +### Importing Custom Object Data + +**customobjects/APIConfiguration.xml:** +```xml + + + + https://api.payment.com/v2 + true + + +``` + +## Site Archive Structure + +``` +site-archive/ +├── meta/ +│ ├── system-objecttype-extensions.xml # Custom attributes on system objects +│ └── custom-objecttype-definitions.xml # Custom object type definitions +├── sites/ +│ └── {SiteID}/ +│ ├── preferences.xml # Site preference values +│ └── library/ +│ └── content/ +│ └── content.xml # Content assets +├── catalogs/ +│ └── {CatalogID}/ +│ └── catalog.xml # Products and categories +├── pricebooks/ +│ └── {PriceBookID}/ +│ └── pricebook.xml # Price definitions +├── customobjects/ +│ └── {ObjectTypeID}.xml # Custom object instances +└── inventory-lists/ + └── {InventoryListID}/ + └── inventory.xml # Inventory records +``` + +## Tips + +### Checking Job Status + +```bash +# Search for recent job executions +b2c job search + +# Wait for a specific job execution +b2c job wait + +# View job logs on failure +b2c job import ./my-data --wait --show-log +``` + +### Best Practices + +1. **Test imports on sandbox first** before importing to staging/production +2. **Use `--wait`** to ensure import completes before continuing +3. **Use `--show-log`** to debug failed imports +4. **Keep archives organized** by feature or change type +5. **Version control your metadata** XML files + +## Detailed Reference + +- [Metadata XML Patterns](references/METADATA-XML.md) - Common XML patterns for imports diff --git a/plugins/b2c-cli/skills/b2c-site-import-export/references/METADATA-XML.md b/plugins/b2c-cli/skills/b2c-site-import-export/references/METADATA-XML.md new file mode 100644 index 00000000..3b7c27ed --- /dev/null +++ b/plugins/b2c-cli/skills/b2c-site-import-export/references/METADATA-XML.md @@ -0,0 +1,365 @@ +# Metadata XML Patterns + +Common XML patterns for site archive imports. + +## System Object Extensions + +### Add String Attribute to Product + +```xml + + + + + + External ID + string + false + true + 100 + + + + + External Data + + + + + +``` + +### Add Enum Attribute to Order + +```xml + + + + + + Fulfillment Status + enum-of-string + false + + + pending + Pending + + + processing + Processing + + + shipped + Shipped + + + delivered + Delivered + + + + + + + Fulfillment Info + + + + + +``` + +### Add Boolean Attribute to Customer Profile + +```xml + + + + + + Marketing Opt-In + boolean + false + false + + + Loyalty Member + boolean + false + false + + + + +``` + +## Site Preferences + +### Boolean Preference + +```xml + + + + + + Enable Product Reviews + boolean + true + + + + +``` + +### String Preference (API Key) + +```xml + + + + + + Analytics API Key + password + + + Analytics Endpoint + string + + + + + Analytics Settings + + + + + + +``` + +### Preference Values + +**sites/RefArch/preferences.xml:** + +Preferences can be set per instance type: + +```xml + + + + + true + + + https://dev-analytics.example.com/api + + + https://analytics.example.com/api + + + +``` + +## Custom Object Types + +### Simple Custom Object + +```xml + + + + Banner + source-to-target + site + + Banner ID + string + 1 + + + + Title + string + + + Image URL + string + + + Link URL + string + + + Start Date + datetime + + + End Date + datetime + + + Active + boolean + true + + + + +``` + +### Custom Object Data + +**customobjects/Banner.xml:** +```xml + + + + Summer Sale + /images/banners/summer-sale.jpg + /sale + 2024-06-01T00:00:00.000Z + 2024-08-31T23:59:59.000Z + true + + + Free Shipping + /images/banners/free-shipping.jpg + /shipping-info + true + + +``` + +## Content Assets + +**sites/RefArch/library/content/content.xml:** +```xml + + + + Terms and Conditions + true + false + + + Terms and Conditions

Content here...

]]> + + + + +``` + +## Attribute Types Reference + +| Type | XML Value | Example | +|------|-----------|---------| +| `string` | `string` | Text up to 4000 chars | +| `text` | `text` | Unlimited text | +| `int` | `int` | Whole numbers | +| `double` | `double` | Decimal numbers | +| `boolean` | `boolean` | true/false | +| `date` | `date` | Date only | +| `datetime` | `datetime` | Date and time | +| `email` | `email` | Email format | +| `password` | `password` | Encrypted | +| `html` | `html` | HTML content | +| `image` | `image` | Image reference | +| `enum-of-string` | `enum-of-string` | Single select | +| `set-of-string` | `set-of-string` | Multi-select | + +## Complete Import Example + +Directory structure for adding a custom integration: + +``` +integration-import/ +├── meta/ +│ ├── system-objecttype-extensions.xml +│ └── custom-objecttype-definitions.xml +├── sites/ +│ └── RefArch/ +│ └── preferences.xml +└── customobjects/ + └── IntegrationConfig.xml +``` + +**meta/system-objecttype-extensions.xml:** +```xml + + + + + + Enable Integration + boolean + false + + + + + + + Integration ID + string + true + + + + +``` + +**meta/custom-objecttype-definitions.xml:** +```xml + + + + Integration Configuration + source-to-target + organization + + Config Key + string + + + + Endpoint + string + + + API Key + password + + + + +``` + +**sites/RefArch/preferences.xml:** +```xml + + + + + true + + + +``` + +**customobjects/IntegrationConfig.xml:** +```xml + + + + https://api.integration.com/v1 + + +``` + +Import command: +```bash +b2c job import ./integration-import --wait --show-log +``` diff --git a/plugins/b2c/skills/b2c-business-manager-extensions/SKILL.md b/plugins/b2c/skills/b2c-business-manager-extensions/SKILL.md new file mode 100644 index 00000000..7fe25667 --- /dev/null +++ b/plugins/b2c/skills/b2c-business-manager-extensions/SKILL.md @@ -0,0 +1,258 @@ +--- +name: b2c-business-manager-extensions +description: Guide for creating Business Manager extension cartridges in Salesforce B2C Commerce +--- + +# 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 + + + + + + + + + + + + + + + +``` + +## Menu Items + +Create top-level navigation sections: + +```xml + + Custom administration tools + + +``` + +| 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 + + Export products to CSV + + + + + + +``` + +| 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 + + + + + + + +``` + +| 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 + + + + + + + + + + + + +``` + +## 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 + + + + ${pdict.title} + + + +
+

${pdict.title}

+ + + + + + + + + + + + + + + + + + +
IDNameActions
${item.id}${item.name} + + Process + +
+
+ + +``` + +## 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](references/EXTENSIONS-XML.md) - Complete XML schema and examples diff --git a/plugins/b2c/skills/b2c-business-manager-extensions/references/EXTENSIONS-XML.md b/plugins/b2c/skills/b2c-business-manager-extensions/references/EXTENSIONS-XML.md new file mode 100644 index 00000000..7173763f --- /dev/null +++ b/plugins/b2c/skills/b2c-business-manager-extensions/references/EXTENSIONS-XML.md @@ -0,0 +1,407 @@ +# Business Manager Extensions XML Reference + +Complete reference for bm_extensions.xml schema. + +## File Location + +``` +/bm_cartridge_name + /cartridge + bm_extensions.xml <-- Required file +``` + +## Root Element + +```xml + + + + +``` + +## Menu Item Element + +Creates navigation sections. + +```xml + + Optional description resource key + Short description key + + +``` + +### Attributes + +| Attribute | Required | Default | Description | +|-----------|----------|---------|-------------| +| `id` | Yes | - | Unique identifier | +| `name` | Yes | - | Resource key for menu name | +| `site` | No | `true` | `true` = Site menu, `false` = Admin menu | +| `position` | No | 0 | Sort order (higher = appears higher) | + +### Child Elements + +| Element | Description | +|---------|-------------| +| `` | Tooltip resource key | +| `` | Short description resource key | +| `` | Icon path relative to static folder | + +## Menu Action Element + +Creates functional pages/links. + +```xml + + Export products resource key + + + + + + + + + + +``` + +### Attributes + +| Attribute | Required | Default | Description | +|-----------|----------|---------|-------------| +| `id` | Yes | - | Unique identifier | +| `menupath` | No | - | Parent menu item ID | +| `name` | Yes | - | Resource key for action name | +| `position` | No | 0 | Sort order | + +### Child Elements + +| Element | Required | Description | +|---------|----------|-------------| +| `` | Yes | Controller/pipeline reference | +| `` | Yes | All pipelines used by this action | +| `` | No | Description resource key | +| `` | No | Static parameters | +| `` | No | Icon path | + +### exec Element + +```xml + + + + + +``` + +| Attribute | Description | +|-----------|-------------| +| `pipeline` | Controller or pipeline name | +| `node` | Action/start node name | +| `https` | Require HTTPS (optional) | + +## Dialog Action Element + +Adds buttons/actions to existing BM pages. + +```xml + + + + + + + + false + +``` + +### Attributes + +| Attribute | Required | Description | +|-----------|----------|-------------| +| `id` | Yes | Unique identifier | +| `menuaction-ref` | Yes | Parent menu action ID | +| `xp-ref` | Yes | Extension point ID | +| `position` | No | Sort order | + +### Child Elements + +| Element | Description | +|---------|-------------| +| `` | Controller/pipeline reference | +| `` | Context parameters to pass | +| `` | Icon path | +| `` | `true` opens new window | + +### Common Extension Points + +| Extension Point | Page | +|-----------------|------| +| `OrderPage-OrderDetails` | Order detail page | +| `OrderPage-OrderAttributes` | Order attributes section | +| `ProductPage-General` | Product general section | +| `ProductPage-Images` | Product images section | +| `CustomerPage-Profile` | Customer profile page | +| `CustomerPage-Addresses` | Customer addresses | +| `ContentPage-General` | Content asset page | +| `CatalogPage-CategoryGeneral` | Category general section | + +## Form Extension Element + +Adds fields to existing BM forms. + +```xml + + + + + + + + + + + + + + + + + +``` + +### Attributes + +| Attribute | Required | Description | +|-----------|----------|-------------| +| `id` | Yes | Unique identifier | + +### valueinput Attributes + +| Attribute | Description | +|-----------|-------------| +| `type` | `string`, `int`, `double` | +| `name` | Field name | +| `defaultvalue` | Default value | + +### Child Elements + +| Element | Description | +|---------|-------------| +| `