B2c Metadata

Metadata Skill

This skill guides you through working with site metadata XML for Salesforce B2C Commerce, including custom attributes, custom objects, and site preferences.

Overview

Metadata defines the structure of your B2C Commerce data:

| Metadata Type | Purpose | |---------------|---------| | System Object Extensions | Add custom attributes to Products, Orders, Customers, etc. | | Custom Objects | Define entirely new data types | | Site Preferences | Site-specific configuration values |

Site Archive Structure

Metadata is organized in site archives:

/site-archive
    /meta
        system-objecttype-extensions.xml    # Custom attributes on system objects
        custom-objecttype-definitions.xml   # Custom object definitions
    /sites
        /MySite
            preferences.xml                 # Site preferences

System Object Extensions

Add custom attributes to existing system objects.

Basic Structure

    
        
            
                My Custom Attribute
                string
                false
                false
            
        
        
            
                My Custom Group
                
            
        
    

Common System Objects

| Object Type | Use Case | |-------------|----------| | Product | Product attributes | | Order | Order metadata | | Profile | Customer profile data | | Basket | Cart data | | SitePreferences | Site configuration | | Category | Category attributes | | Content | Content asset attributes |

Attribute Types

| Type | Description | Example | |------|-------------|---------| | string | Text (max 4000 chars) | SKU, descriptions | | text | Long text (unlimited) | Rich content | | int | Integer | Quantity, rank | | double | Decimal | Percentage, weight | | boolean | true/false | Flags | | date | Date only | Birth date | | datetime | Date and time | Timestamps | | email | Email address | Contact email | | password | Encrypted | API keys | | html | HTML content | Rich text | | enum-of-string | Single select | Status | | enum-of-int | Numeric enum | Priority level | | set-of-string | Multi-select | Tags | | set-of-int | Numeric multi-select | Categories | | image | Image reference | Thumbnails |

Enum Value Definitions

Enum types (enum-of-string, enum-of-int, set-of-string, set-of-int) require value-definitions with display/value pairs:

> Element order matters. Inside each `, the element must come **before** . The metadata.xsd schema enforces this strict ordering — putting first fails site import validation with cvc-complex-type.2.4.d: Invalid content was found starting with element 'display'`.

    Warranty Type
    enum-of-string
    false
    
        
            No Warranty
            none
        
        
            Limited Warranty
            limited
        
        
            Full Warranty
            full
        
    

| Element | Purpose | |---------|---------| | ` | Human-readable label shown in Business Manager (must appear first) | | ` | The stored/API value (use lowercase, no spaces) |

Product Custom Attribute Example

    
        
            
            
                Vendor SKU
                string
                false
                true
            

            
            
                Product Condition
                enum-of-string
                false
                
                    
                        New
                        new
                    
                    
                        Refurbished
                        refurbished
                    
                    
                        Used
                        used
                    
                
            

            
            
                Hazardous Material
                boolean
                false
                false
            

            
            
                Product Features
                set-of-string
                false
                
                    
                        Waterproof
                        waterproof
                    
                    
                        Recyclable
                        recyclable
                    
                
            
        

        
            
                Custom Product Information
                
                
                
                
            
        
    

Custom Object Definitions

Create entirely new data types.

    
        Store Locations
        Physical store information
        source-to-target
        site
        
            Store ID
            string
            1
        
        
            
                Store Name
                string
                true
            
            
                Latitude
                double
            
            
                Longitude
                double
            
            
                Phone
                string
            
            
                Active
                boolean
                true
            
        
        
            
                Store Information
                
                
                
                
                
                
            
        
    

Site Preferences

Site-specific configuration via custom attributes on SitePreferences.

Metadata (system-objecttype-extensions.xml)

    
        
            
                Enable Feature X
                boolean
                false
            
            
                API Endpoint
                string
            
            
                Max Items Per Page
                int
                20
            
        
        
            
                Custom Settings
                
                
                
            
        
    

Values (sites/MySite/preferences.xml)

Preferences can be set per instance type (development, staging, production) or for all instances:

    
        
            
            25
        
        
            
            true
            https://dev-api.example.com/v1
        
        
            true
            https://staging-api.example.com/v1
        
        
            false
            https://api.example.com/v1
        
    

Access in Code

var Site = require('dw/system/Site');

var enableFeatureX = Site.current.getCustomPreferenceValue('enableFeatureX');
var apiEndpoint = Site.current.getCustomPreferenceValue('apiEndpoint');
var maxItems = Site.current.getCustomPreferenceValue('maxItemsPerPage');

Attribute Definition Options

    Display Name
    Description for BM tooltip
    string
    false
    false
    false
    true
    false
    false
    false
    0
    256
    default
    none
    kg

| Flag | Purpose | |------|---------| | localizable-flag | Can have different values per locale | | mandatory-flag | Required in BM | | externally-managed-flag | Read-only in BM | | visible-flag | Shown in BM | | site-specific-flag | Different value per site | | order-required-flag | Required for order export | | searchable-flag | Indexed for search |

Best Practices

1. Use attribute groups to organize in Business Manager
2. Prefix custom attributes with organization name (e.g., acme_myAttribute)
3. Set externally-managed for data imported from external systems
4. Use enums over strings for controlled vocabularies
5. Document with descriptions - they appear as tooltips

Detailed Reference

• [System Objects Reference](references/SYSTEM-OBJECTS.md) - All system object types
• [XML Examples](references/XML-EXAMPLES.md) - Complete import/export examples

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SalesforceCommerceCloud
• Source: SalesforceCommerceCloud/b2c-developer-tooling
• License: Apache-2.0
• Homepage: https://salesforcecommercecloud.github.io/b2c-developer-tooling/

Install and usage instructions live in the source repository linked above.