b2c-metadata

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Metadata Skill

元数据Skill

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

本Skill将指导你处理Salesforce B2C Commerce的站点元数据XML，包括自定义属性、自定义对象和站点偏好。

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

元数据定义了你的B2C Commerce数据结构：

元数据类型	用途
系统对象扩展	为产品、订单、客户等添加自定义属性
自定义对象	定义全新的数据类型
站点偏好	站点专属的配置值

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

元数据在站点归档中按如下结构组织：

/site-archive
    /meta
        system-objecttype-extensions.xml    # 系统对象上的自定义属性
        custom-objecttype-definitions.xml   # 自定义对象定义
    /sites
        /MySite
            preferences.xml                 # 站点偏好

System Object Extensions

系统对象扩展

Add custom attributes to existing system objects.

为已有的系统对象添加自定义属性。

Basic Structure

基础结构

xml

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="Product">
        <custom-attribute-definitions>
            <attribute-definition attribute-id="myCustomAttribute">
                <display-name xml:lang="x-default">My Custom Attribute</display-name>
                <type>string</type>
                <mandatory-flag>false</mandatory-flag>
                <externally-managed-flag>false</externally-managed-flag>
            </attribute-definition>
        </custom-attribute-definitions>
        <group-definitions>
            <attribute-group group-id="MyCustomGroup">
                <display-name xml:lang="x-default">My Custom Group</display-name>
                <attribute attribute-id="myCustomAttribute"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>

xml

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="Product">
        <custom-attribute-definitions>
            <attribute-definition attribute-id="myCustomAttribute">
                <display-name xml:lang="x-default">My Custom Attribute</display-name>
                <type>string</type>
                <mandatory-flag>false</mandatory-flag>
                <externally-managed-flag>false</externally-managed-flag>
            </attribute-definition>
        </custom-attribute-definitions>
        <group-definitions>
            <attribute-group group-id="MyCustomGroup">
                <display-name xml:lang="x-default">My Custom Group</display-name>
                <attribute attribute-id="myCustomAttribute"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>

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

对象类型	使用场景
`Product`	产品属性
`Order`	订单元数据
`Profile`	客户档案数据
`Basket`	购物车数据
`SitePreferences`	站点配置
`Category`	分类属性
`Content`	内容资产属性

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

类型	描述	示例
`string`	文本（最多4000字符）	SKU、描述
`text`	长文本（无长度限制）	富内容
`int`	整数	数量、排序权重
`double`	小数	百分比、重量
`boolean`	true/false	标记位
`date`	仅日期	出生日期
`datetime`	日期和时间	时间戳
`email`	邮箱地址	联系邮箱
`password`	加密内容	API密钥
`html`	HTML内容	富文本
`enum-of-string`	单选下拉框	状态
`enum-of-int`	数值枚举	优先级
`set-of-string`	多选下拉框	标签
`set-of-int`	数值多选	分类
`image`	图片引用	缩略图

Enum Value Definitions

枚举值定义

Enum types (

enum-of-string

enum-of-int

set-of-string

set-of-int

) require

value-definitions

with value/display pairs:

xml

<attribute-definition attribute-id="warrantyType">
    <display-name xml:lang="x-default">Warranty Type</display-name>
    <type>enum-of-string</type>
    <mandatory-flag>false</mandatory-flag>
    <value-definitions>
        <value-definition>
            <value>none</value>
            <display xml:lang="x-default">No Warranty</display>
        </value-definition>
        <value-definition>
            <value>limited</value>
            <display xml:lang="x-default">Limited Warranty</display>
        </value-definition>
        <value-definition>
            <value>full</value>
            <display xml:lang="x-default">Full Warranty</display>
        </value-definition>
    </value-definitions>
</attribute-definition>

Element	Purpose
`<value>`	The stored/API value (use lowercase, no spaces)
`<display>`	Human-readable label shown in Business Manager

枚举类型（

enum-of-string

、

enum-of-int

、

set-of-string

、

set-of-int

）需要包含带值/展示名称对的

value-definitions

：

xml

<attribute-definition attribute-id="warrantyType">
    <display-name xml:lang="x-default">Warranty Type</display-name>
    <type>enum-of-string</type>
    <mandatory-flag>false</mandatory-flag>
    <value-definitions>
        <value-definition>
            <value>none</value>
            <display xml:lang="x-default">No Warranty</display>
        </value-definition>
        <value-definition>
            <value>limited</value>
            <display xml:lang="x-default">Limited Warranty</display>
        </value-definition>
        <value-definition>
            <value>full</value>
            <display xml:lang="x-default">Full Warranty</display>
        </value-definition>
    </value-definitions>
</attribute-definition>

元素	用途
`<value>`	存储/API返回的值（使用小写，无空格）
`<display>`	Business Manager中展示的人类可读标签

Product Custom Attribute Example

产品自定义属性示例

xml

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="Product">
        <custom-attribute-definitions>
            <!-- Simple string attribute -->
            <attribute-definition attribute-id="vendorSKU">
                <display-name xml:lang="x-default">Vendor SKU</display-name>
                <type>string</type>
                <mandatory-flag>false</mandatory-flag>
                <externally-managed-flag>true</externally-managed-flag>
            </attribute-definition>

            <!-- Enum (dropdown) attribute -->
            <attribute-definition attribute-id="productCondition">
                <display-name xml:lang="x-default">Product Condition</display-name>
                <type>enum-of-string</type>
                <mandatory-flag>false</mandatory-flag>
                <value-definitions>
                    <value-definition>
                        <value>new</value>
                        <display xml:lang="x-default">New</display>
                    </value-definition>
                    <value-definition>
                        <value>refurbished</value>
                        <display xml:lang="x-default">Refurbished</display>
                    </value-definition>
                    <value-definition>
                        <value>used</value>
                        <display xml:lang="x-default">Used</display>
                    </value-definition>
                </value-definitions>
            </attribute-definition>

            <!-- Boolean attribute -->
            <attribute-definition attribute-id="isHazardous">
                <display-name xml:lang="x-default">Hazardous Material</display-name>
                <type>boolean</type>
                <mandatory-flag>false</mandatory-flag>
                <default-value>false</default-value>
            </attribute-definition>

            <!-- Multi-select attribute -->
            <attribute-definition attribute-id="productFeatures">
                <display-name xml:lang="x-default">Product Features</display-name>
                <type>set-of-string</type>
                <mandatory-flag>false</mandatory-flag>
                <value-definitions>
                    <value-definition>
                        <value>waterproof</value>
                        <display xml:lang="x-default">Waterproof</display>
                    </value-definition>
                    <value-definition>
                        <value>recyclable</value>
                        <display xml:lang="x-default">Recyclable</display>
                    </value-definition>
                </value-definitions>
            </attribute-definition>
        </custom-attribute-definitions>

        <group-definitions>
            <attribute-group group-id="CustomProductInfo">
                <display-name xml:lang="x-default">Custom Product Information</display-name>
                <attribute attribute-id="vendorSKU"/>
                <attribute attribute-id="productCondition"/>
                <attribute attribute-id="isHazardous"/>
                <attribute attribute-id="productFeatures"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>

xml

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="Product">
        <custom-attribute-definitions>
            <!-- Simple string attribute -->
            <attribute-definition attribute-id="vendorSKU">
                <display-name xml:lang="x-default">Vendor SKU</display-name>
                <type>string</type>
                <mandatory-flag>false</mandatory-flag>
                <externally-managed-flag>true</externally-managed-flag>
            </attribute-definition>

            <!-- Enum (dropdown) attribute -->
            <attribute-definition attribute-id="productCondition">
                <display-name xml:lang="x-default">Product Condition</display-name>
                <type>enum-of-string</type>
                <mandatory-flag>false</mandatory-flag>
                <value-definitions>
                    <value-definition>
                        <value>new</value>
                        <display xml:lang="x-default">New</display>
                    </value-definition>
                    <value-definition>
                        <value>refurbished</value>
                        <display xml:lang="x-default">Refurbished</display>
                    </value-definition>
                    <value-definition>
                        <value>used</value>
                        <display xml:lang="x-default">Used</display>
                    </value-definition>
                </value-definitions>
            </attribute-definition>

            <!-- Boolean attribute -->
            <attribute-definition attribute-id="isHazardous">
                <display-name xml:lang="x-default">Hazardous Material</display-name>
                <type>boolean</type>
                <mandatory-flag>false</mandatory-flag>
                <default-value>false</default-value>
            </attribute-definition>

            <!-- Multi-select attribute -->
            <attribute-definition attribute-id="productFeatures">
                <display-name xml:lang="x-default">Product Features</display-name>
                <type>set-of-string</type>
                <mandatory-flag>false</mandatory-flag>
                <value-definitions>
                    <value-definition>
                        <value>waterproof</value>
                        <display xml:lang="x-default">Waterproof</display>
                    </value-definition>
                    <value-definition>
                        <value>recyclable</value>
                        <display xml:lang="x-default">Recyclable</display>
                    </value-definition>
                </value-definitions>
            </attribute-definition>
        </custom-attribute-definitions>

        <group-definitions>
            <attribute-group group-id="CustomProductInfo">
                <display-name xml:lang="x-default">Custom Product Information</display-name>
                <attribute attribute-id="vendorSKU"/>
                <attribute attribute-id="productCondition"/>
                <attribute attribute-id="isHazardous"/>
                <attribute attribute-id="productFeatures"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>

Custom Object Definitions

自定义对象定义

Create entirely new data types.

xml

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <custom-type type-id="StoreLocations">
        <display-name xml:lang="x-default">Store Locations</display-name>
        <description xml:lang="x-default">Physical store information</description>
        <staging-mode>source-to-target</staging-mode>
        <storage-scope>site</storage-scope>
        <key-definition attribute-id="storeId">
            <display-name xml:lang="x-default">Store ID</display-name>
            <type>string</type>
            <min-length>1</min-length>
        </key-definition>
        <attribute-definitions>
            <attribute-definition attribute-id="storeName">
                <display-name xml:lang="x-default">Store Name</display-name>
                <type>string</type>
                <mandatory-flag>true</mandatory-flag>
            </attribute-definition>
            <attribute-definition attribute-id="latitude">
                <display-name xml:lang="x-default">Latitude</display-name>
                <type>double</type>
            </attribute-definition>
            <attribute-definition attribute-id="longitude">
                <display-name xml:lang="x-default">Longitude</display-name>
                <type>double</type>
            </attribute-definition>
            <attribute-definition attribute-id="phone">
                <display-name xml:lang="x-default">Phone</display-name>
                <type>string</type>
            </attribute-definition>
            <attribute-definition attribute-id="isActive">
                <display-name xml:lang="x-default">Active</display-name>
                <type>boolean</type>
                <default-value>true</default-value>
            </attribute-definition>
        </attribute-definitions>
        <group-definitions>
            <attribute-group group-id="StoreInfo">
                <display-name xml:lang="x-default">Store Information</display-name>
                <attribute attribute-id="storeId" system="true"/>
                <attribute attribute-id="storeName"/>
                <attribute attribute-id="latitude"/>
                <attribute attribute-id="longitude"/>
                <attribute attribute-id="phone"/>
                <attribute attribute-id="isActive"/>
            </attribute-group>
        </group-definitions>
    </custom-type>
</metadata>

创建全新的数据类型。

xml

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <custom-type type-id="StoreLocations">
        <display-name xml:lang="x-default">Store Locations</display-name>
        <description xml:lang="x-default">Physical store information</description>
        <staging-mode>source-to-target</staging-mode>
        <storage-scope>site</storage-scope>
        <key-definition attribute-id="storeId">
            <display-name xml:lang="x-default">Store ID</display-name>
            <type>string</type>
            <min-length>1</min-length>
        </key-definition>
        <attribute-definitions>
            <attribute-definition attribute-id="storeName">
                <display-name xml:lang="x-default">Store Name</display-name>
                <type>string</type>
                <mandatory-flag>true</mandatory-flag>
            </attribute-definition>
            <attribute-definition attribute-id="latitude">
                <display-name xml:lang="x-default">Latitude</display-name>
                <type>double</type>
            </attribute-definition>
            <attribute-definition attribute-id="longitude">
                <display-name xml:lang="x-default">Longitude</display-name>
                <type>double</type>
            </attribute-definition>
            <attribute-definition attribute-id="phone">
                <display-name xml:lang="x-default">Phone</display-name>
                <type>string</type>
            </attribute-definition>
            <attribute-definition attribute-id="isActive">
                <display-name xml:lang="x-default">Active</display-name>
                <type>boolean</type>
                <default-value>true</default-value>
            </attribute-definition>
        </attribute-definitions>
        <group-definitions>
            <attribute-group group-id="StoreInfo">
                <display-name xml:lang="x-default">Store Information</display-name>
                <attribute attribute-id="storeId" system="true"/>
                <attribute attribute-id="storeName"/>
                <attribute attribute-id="latitude"/>
                <attribute attribute-id="longitude"/>
                <attribute attribute-id="phone"/>
                <attribute attribute-id="isActive"/>
            </attribute-group>
        </group-definitions>
    </custom-type>
</metadata>

Site Preferences

站点偏好

Site-specific configuration via custom attributes on SitePreferences.

通过SitePreferences上的自定义属性实现站点专属配置。

Metadata (system-objecttype-extensions.xml)

元数据（system-objecttype-extensions.xml）

xml

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="SitePreferences">
        <custom-attribute-definitions>
            <attribute-definition attribute-id="enableFeatureX">
                <display-name xml:lang="x-default">Enable Feature X</display-name>
                <type>boolean</type>
                <default-value>false</default-value>
            </attribute-definition>
            <attribute-definition attribute-id="apiEndpoint">
                <display-name xml:lang="x-default">API Endpoint</display-name>
                <type>string</type>
            </attribute-definition>
            <attribute-definition attribute-id="maxItemsPerPage">
                <display-name xml:lang="x-default">Max Items Per Page</display-name>
                <type>int</type>
                <default-value>20</default-value>
            </attribute-definition>
        </custom-attribute-definitions>
        <group-definitions>
            <attribute-group group-id="CustomSettings">
                <display-name xml:lang="x-default">Custom Settings</display-name>
                <attribute attribute-id="enableFeatureX"/>
                <attribute attribute-id="apiEndpoint"/>
                <attribute attribute-id="maxItemsPerPage"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>

xml

<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
    <type-extension type-id="SitePreferences">
        <custom-attribute-definitions>
            <attribute-definition attribute-id="enableFeatureX">
                <display-name xml:lang="x-default">Enable Feature X</display-name>
                <type>boolean</type>
                <default-value>false</default-value>
            </attribute-definition>
            <attribute-definition attribute-id="apiEndpoint">
                <display-name xml:lang="x-default">API Endpoint</display-name>
                <type>string</type>
            </attribute-definition>
            <attribute-definition attribute-id="maxItemsPerPage">
                <display-name xml:lang="x-default">Max Items Per Page</display-name>
                <type>int</type>
                <default-value>20</default-value>
            </attribute-definition>
        </custom-attribute-definitions>
        <group-definitions>
            <attribute-group group-id="CustomSettings">
                <display-name xml:lang="x-default">Custom Settings</display-name>
                <attribute attribute-id="enableFeatureX"/>
                <attribute attribute-id="apiEndpoint"/>
                <attribute attribute-id="maxItemsPerPage"/>
            </attribute-group>
        </group-definitions>
    </type-extension>
</metadata>

Values (sites/MySite/preferences.xml)

配置值（sites/MySite/preferences.xml）

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

xml

<?xml version="1.0" encoding="UTF-8"?>
<preferences xmlns="http://www.demandware.com/xml/impex/preferences/2007-03-31">
    <custom-preferences>
        <all-instances>
            <!-- Values that apply to all instance types -->
            <preference preference-id="maxItemsPerPage">25</preference>
        </all-instances>
        <development>
            <!-- Development-specific values -->
            <preference preference-id="enableFeatureX">true</preference>
            <preference preference-id="apiEndpoint">https://dev-api.example.com/v1</preference>
        </development>
        <staging>
            <preference preference-id="enableFeatureX">true</preference>
            <preference preference-id="apiEndpoint">https://staging-api.example.com/v1</preference>
        </staging>
        <production>
            <preference preference-id="enableFeatureX">false</preference>
            <preference preference-id="apiEndpoint">https://api.example.com/v1</preference>
        </production>
    </custom-preferences>
</preferences>

偏好可以按实例类型（开发、预发、生产）设置，也可以为所有实例统一设置：

xml

<?xml version="1.0" encoding="UTF-8"?>
<preferences xmlns="http://www.demandware.com/xml/impex/preferences/2007-03-31">
    <custom-preferences>
        <all-instances>
            <!-- Values that apply to all instance types -->
            <preference preference-id="maxItemsPerPage">25</preference>
        </all-instances>
        <development>
            <!-- Development-specific values -->
            <preference preference-id="enableFeatureX">true</preference>
            <preference preference-id="apiEndpoint">https://dev-api.example.com/v1</preference>
        </development>
        <staging>
            <preference preference-id="enableFeatureX">true</preference>
            <preference preference-id="apiEndpoint">https://staging-api.example.com/v1</preference>
        </staging>
        <production>
            <preference preference-id="enableFeatureX">false</preference>
            <preference preference-id="apiEndpoint">https://api.example.com/v1</preference>
        </production>
    </custom-preferences>
</preferences>

Access in Code

代码中访问

javascript

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

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

javascript

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

属性定义选项

xml

<attribute-definition attribute-id="myAttribute">
    <display-name xml:lang="x-default">Display Name</display-name>
    <description xml:lang="x-default">Description for BM tooltip</description>
    <type>string</type>
    <localizable-flag>false</localizable-flag>
    <mandatory-flag>false</mandatory-flag>
    <externally-managed-flag>false</externally-managed-flag>
    <visible-flag>true</visible-flag>
    <site-specific-flag>false</site-specific-flag>
    <order-required-flag>false</order-required-flag>
    <searchable-flag>false</searchable-flag>
    <min-length>0</min-length>
    <max-length>256</max-length>
    <default-value>default</default-value>
    <select-mode>none</select-mode>
    <unit>kg</unit>
</attribute-definition>

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

xml

<attribute-definition attribute-id="myAttribute">
    <display-name xml:lang="x-default">Display Name</display-name>
    <description xml:lang="x-default">Description for BM tooltip</description>
    <type>string</type>
    <localizable-flag>false</localizable-flag>
    <mandatory-flag>false</mandatory-flag>
    <externally-managed-flag>false</externally-managed-flag>
    <visible-flag>true</visible-flag>
    <site-specific-flag>false</site-specific-flag>
    <order-required-flag>false</order-required-flag>
    <searchable-flag>false</searchable-flag>
    <min-length>0</min-length>
    <max-length>256</max-length>
    <default-value>default</default-value>
    <select-mode>none</select-mode>
    <unit>kg</unit>
</attribute-definition>

标记	用途
`localizable-flag`	可按地区设置不同值
`mandatory-flag`	在BM中为必填项
`externally-managed-flag`	在BM中为只读
`visible-flag`	在BM中展示
`site-specific-flag`	不同站点可设置不同值
`order-required-flag`	订单导出时必填
`searchable-flag`	建立搜索索引

Best Practices

最佳实践

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

使用属性组在Business Manager中组织内容
为自定义属性添加前缀使用组织名称（例如
```
acme_myAttribute
```
）
为从外部系统导入的数据设置externally-managed标记
优先使用枚举而非字符串实现受控词汇表
添加描述做好文档它们会作为BM中的提示词展示

Detailed Reference

详细参考

System Objects Reference - All system object types
XML Examples - Complete import/export examples

系统对象参考 - 所有系统对象类型
XML示例 - 完整的导入/导出示例