@salesforce/b2c-cli 2.3.0 → 2.4.0

package/content/guidance/b2c/b2c-metadata/references/SYSTEM-OBJECTS.md

@@ -0,0 +1,320 @@
+# System Objects Reference
+
+All extensible system object types in B2C Commerce.
+
+## Product-Related
+
+### Product
+
+Product master, variant, and standard products.
+
+```xml
+<type-extension type-id="Product">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="vendorSKU">
+            <display-name xml:lang="x-default">Vendor SKU</display-name>
+            <type>string</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+**Common custom attributes:** vendor IDs, compliance flags, external system references
+
+### ProductLineItem
+
+Line items in baskets and orders.
+
+```xml
+<type-extension type-id="ProductLineItem">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="giftMessage">
+            <display-name xml:lang="x-default">Gift Message</display-name>
+            <type>text</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+### Category
+
+Catalog categories.
+
+```xml
+<type-extension type-id="Category">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="bannerImage">
+            <display-name xml:lang="x-default">Banner Image</display-name>
+            <type>image</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+## Order-Related
+
+### Order
+
+Placed orders.
+
+```xml
+<type-extension type-id="Order">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="externalOrderId">
+            <display-name xml:lang="x-default">External Order ID</display-name>
+            <type>string</type>
+            <externally-managed-flag>true</externally-managed-flag>
+        </attribute-definition>
+        <attribute-definition attribute-id="exportStatus">
+            <display-name xml:lang="x-default">Export Status</display-name>
+            <type>enum-of-string</type>
+            <value-definitions>
+                <value-definition>
+                    <display xml:lang="x-default">Pending</display>
+                    <value>pending</value>
+                </value-definition>
+                <value-definition>
+                    <display xml:lang="x-default">Exported</display>
+                    <value>exported</value>
+                </value-definition>
+            </value-definitions>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+### Basket
+
+Active shopping carts.
+
+```xml
+<type-extension type-id="Basket">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="quoteId">
+            <display-name xml:lang="x-default">Quote ID</display-name>
+            <type>string</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+### Shipment
+
+Order/basket shipments.
+
+```xml
+<type-extension type-id="Shipment">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="deliveryInstructions">
+            <display-name xml:lang="x-default">Delivery Instructions</display-name>
+            <type>text</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+## Customer-Related
+
+### Profile
+
+Customer profiles (registered customers).
+
+```xml
+<type-extension type-id="Profile">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="loyaltyNumber">
+            <display-name xml:lang="x-default">Loyalty Number</display-name>
+            <type>string</type>
+        </attribute-definition>
+        <attribute-definition attribute-id="preferredContactMethod">
+            <display-name xml:lang="x-default">Preferred Contact Method</display-name>
+            <type>enum-of-string</type>
+            <value-definitions>
+                <value-definition>
+                    <display xml:lang="x-default">Email</display>
+                    <value>email</value>
+                </value-definition>
+                <value-definition>
+                    <display xml:lang="x-default">Phone</display>
+                    <value>phone</value>
+                </value-definition>
+                <value-definition>
+                    <display xml:lang="x-default">SMS</display>
+                    <value>sms</value>
+                </value-definition>
+            </value-definitions>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+### CustomerAddress
+
+Customer address book entries.
+
+```xml
+<type-extension type-id="CustomerAddress">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="addressType">
+            <display-name xml:lang="x-default">Address Type</display-name>
+            <type>enum-of-string</type>
+            <value-definitions>
+                <value-definition>
+                    <display xml:lang="x-default">Residential</display>
+                    <value>residential</value>
+                </value-definition>
+                <value-definition>
+                    <display xml:lang="x-default">Commercial</display>
+                    <value>commercial</value>
+                </value-definition>
+            </value-definitions>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+## Content-Related
+
+### Content
+
+Content assets.
+
+```xml
+<type-extension type-id="Content">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="author">
+            <display-name xml:lang="x-default">Author</display-name>
+            <type>string</type>
+        </attribute-definition>
+        <attribute-definition attribute-id="publishDate">
+            <display-name xml:lang="x-default">Publish Date</display-name>
+            <type>datetime</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+### Folder
+
+Content folders.
+
+```xml
+<type-extension type-id="Folder">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="folderIcon">
+            <display-name xml:lang="x-default">Folder Icon</display-name>
+            <type>image</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+## Site Configuration
+
+### SitePreferences
+
+Site-level configuration.
+
+```xml
+<type-extension type-id="SitePreferences">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="enableFeature">
+            <display-name xml:lang="x-default">Enable Feature</display-name>
+            <type>boolean</type>
+            <default-value>false</default-value>
+        </attribute-definition>
+        <attribute-definition attribute-id="apiKey">
+            <display-name xml:lang="x-default">API Key</display-name>
+            <type>password</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+### OrganizationPreferences
+
+Organization-wide configuration.
+
+```xml
+<type-extension type-id="OrganizationPreferences">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="orgWideApiKey">
+            <display-name xml:lang="x-default">Organization API Key</display-name>
+            <type>password</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+## Other Objects
+
+### Store
+
+Physical store information.
+
+```xml
+<type-extension type-id="Store">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="googlePlaceId">
+            <display-name xml:lang="x-default">Google Place ID</display-name>
+            <type>string</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+### GiftCertificate
+
+Gift certificates.
+
+```xml
+<type-extension type-id="GiftCertificate">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="purchasedBy">
+            <display-name xml:lang="x-default">Purchased By</display-name>
+            <type>string</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+### SourceCodeGroup
+
+Source code groups for campaigns.
+
+```xml
+<type-extension type-id="SourceCodeGroup">
+    <custom-attribute-definitions>
+        <attribute-definition attribute-id="campaignType">
+            <display-name xml:lang="x-default">Campaign Type</display-name>
+            <type>string</type>
+        </attribute-definition>
+    </custom-attribute-definitions>
+</type-extension>
+```
+
+## Complete List of System Objects
+
+| Object Type | Description |
+|-------------|-------------|
+| `Basket` | Shopping cart |
+| `Category` | Catalog category |
+| `Content` | Content asset |
+| `Coupon` | Coupon codes |
+| `CustomerAddress` | Address book entry |
+| `CustomerGroup` | Customer segments |
+| `Folder` | Content folder |
+| `GiftCertificate` | Gift certificate |
+| `Order` | Placed order |
+| `OrderAddress` | Order shipping/billing address |
+| `OrganizationPreferences` | Org-level config |
+| `PaymentInstrument` | Payment method |
+| `PaymentTransaction` | Payment transaction |
+| `Product` | Catalog product |
+| `ProductLineItem` | Cart/order line item |
+| `Profile` | Customer profile |
+| `Shipment` | Order shipment |
+| `ShippingLineItem` | Shipping charge |
+| `SitePreferences` | Site-level config |
+| `SourceCodeGroup` | Campaign source code |
+| `Store` | Physical store |

package/content/guidance/b2c/b2c-metadata/references/XML-EXAMPLES.md

@@ -0,0 +1,366 @@
+# Metadata XML Examples
+
+Complete examples for common metadata import/export scenarios.
+
+## XSD Schema Reference
+
+For authoritative XML schema definitions, use the `b2c` CLI (if installed):
+
+```bash
+# View specific schemas
+b2c docs schema metadata
+b2c docs schema catalog
+b2c docs schema library
+b2c docs schema preferences
+
+# List all available schemas
+b2c docs schema --list
+```
+
+## Site Archive Structure
+
+```
+/site-archive/
+    /meta/
+        system-objecttype-extensions.xml
+        custom-objecttype-definitions.xml
+    /sites/
+        /RefArch/
+            preferences.xml
+    /catalogs/
+        /storefront-catalog/
+            catalog.xml
+    /libraries/
+        /RefArchSharedLibrary/
+            library.xml
+```
+
+## Adding Custom Attributes to Products
+
+### Metadata (meta/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="Product">
+        <custom-attribute-definitions>
+            <!-- String attribute -->
+            <attribute-definition attribute-id="manufacturerPartNumber">
+                <display-name xml:lang="x-default">Manufacturer Part Number</display-name>
+                <description xml:lang="x-default">MPN from manufacturer</description>
+                <type>string</type>
+                <mandatory-flag>false</mandatory-flag>
+                <externally-managed-flag>true</externally-managed-flag>
+                <min-length>0</min-length>
+                <field-length>50</field-length>
+            </attribute-definition>
+
+            <!-- Enum attribute -->
+            <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>
+                        <display xml:lang="x-default">No Warranty</display>
+                        <value>none</value>
+                    </value-definition>
+                    <value-definition default="true">
+                        <display xml:lang="x-default">Standard Warranty</display>
+                        <value>standard</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">Extended Warranty</display>
+                        <value>extended</value>
+                    </value-definition>
+                </value-definitions>
+            </attribute-definition>
+
+            <!-- Boolean attribute -->
+            <attribute-definition attribute-id="requiresAssembly">
+                <display-name xml:lang="x-default">Requires Assembly</display-name>
+                <type>boolean</type>
+                <mandatory-flag>false</mandatory-flag>
+                <default-value>false</default-value>
+            </attribute-definition>
+
+            <!-- Double attribute -->
+            <attribute-definition attribute-id="weight">
+                <display-name xml:lang="x-default">Product Weight</display-name>
+                <type>double</type>
+                <mandatory-flag>false</mandatory-flag>
+                <unit>kg</unit>
+            </attribute-definition>
+
+            <!-- Multi-select attribute -->
+            <attribute-definition attribute-id="certifications">
+                <display-name xml:lang="x-default">Certifications</display-name>
+                <type>set-of-string</type>
+                <mandatory-flag>false</mandatory-flag>
+                <value-definitions>
+                    <value-definition>
+                        <display xml:lang="x-default">Energy Star</display>
+                        <value>energy-star</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">UL Listed</display>
+                        <value>ul-listed</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">FDA Approved</display>
+                        <value>fda-approved</value>
+                    </value-definition>
+                </value-definitions>
+            </attribute-definition>
+
+            <!-- Localizable attribute -->
+            <attribute-definition attribute-id="localDescription">
+                <display-name xml:lang="x-default">Localized Description</display-name>
+                <type>text</type>
+                <localizable-flag>true</localizable-flag>
+                <mandatory-flag>false</mandatory-flag>
+            </attribute-definition>
+        </custom-attribute-definitions>
+
+        <group-definitions>
+            <attribute-group group-id="ProductExtras">
+                <display-name xml:lang="x-default">Product Extras</display-name>
+                <attribute attribute-id="manufacturerPartNumber"/>
+                <attribute attribute-id="warrantyType"/>
+                <attribute attribute-id="requiresAssembly"/>
+                <attribute attribute-id="weight"/>
+                <attribute attribute-id="certifications"/>
+                <attribute attribute-id="localDescription"/>
+            </attribute-group>
+        </group-definitions>
+    </type-extension>
+</metadata>
+```
+
+## Adding Custom Attributes to Orders
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="Order">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="erpOrderId">
+                <display-name xml:lang="x-default">ERP Order ID</display-name>
+                <type>string</type>
+                <externally-managed-flag>true</externally-managed-flag>
+            </attribute-definition>
+            <attribute-definition attribute-id="syncStatus">
+                <display-name xml:lang="x-default">Sync Status</display-name>
+                <type>enum-of-string</type>
+                <value-definitions>
+                    <value-definition default="true">
+                        <display xml:lang="x-default">Pending</display>
+                        <value>pending</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">Synced</display>
+                        <value>synced</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">Failed</display>
+                        <value>failed</value>
+                    </value-definition>
+                </value-definitions>
+            </attribute-definition>
+            <attribute-definition attribute-id="syncDate">
+                <display-name xml:lang="x-default">Last Sync Date</display-name>
+                <type>datetime</type>
+                <externally-managed-flag>true</externally-managed-flag>
+            </attribute-definition>
+        </custom-attribute-definitions>
+
+        <group-definitions>
+            <attribute-group group-id="ERPIntegration">
+                <display-name xml:lang="x-default">ERP Integration</display-name>
+                <attribute attribute-id="erpOrderId"/>
+                <attribute attribute-id="syncStatus"/>
+                <attribute attribute-id="syncDate"/>
+            </attribute-group>
+        </group-definitions>
+    </type-extension>
+</metadata>
+```
+
+## Custom Object Definition
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <custom-type type-id="NewsletterSubscription">
+        <display-name xml:lang="x-default">Newsletter Subscription</display-name>
+        <description xml:lang="x-default">Email newsletter subscriptions</description>
+        <staging-mode>source-to-target</staging-mode>
+        <storage-scope>site</storage-scope>
+
+        <key-definition attribute-id="email">
+            <display-name xml:lang="x-default">Email Address</display-name>
+            <type>string</type>
+            <min-length>5</min-length>
+            <field-length>256</field-length>
+        </key-definition>
+
+        <attribute-definitions>
+            <attribute-definition attribute-id="firstName">
+                <display-name xml:lang="x-default">First Name</display-name>
+                <type>string</type>
+                <mandatory-flag>false</mandatory-flag>
+            </attribute-definition>
+            <attribute-definition attribute-id="lastName">
+                <display-name xml:lang="x-default">Last Name</display-name>
+                <type>string</type>
+                <mandatory-flag>false</mandatory-flag>
+            </attribute-definition>
+            <attribute-definition attribute-id="subscriptionDate">
+                <display-name xml:lang="x-default">Subscription Date</display-name>
+                <type>datetime</type>
+                <mandatory-flag>true</mandatory-flag>
+            </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-definition attribute-id="topics">
+                <display-name xml:lang="x-default">Subscribed Topics</display-name>
+                <type>set-of-string</type>
+                <value-definitions>
+                    <value-definition>
+                        <display xml:lang="x-default">Promotions</display>
+                        <value>promotions</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">New Arrivals</display>
+                        <value>new-arrivals</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">Tips &amp; Tricks</display>
+                        <value>tips</value>
+                    </value-definition>
+                </value-definitions>
+            </attribute-definition>
+        </attribute-definitions>
+
+        <group-definitions>
+            <attribute-group group-id="SubscriptionInfo">
+                <display-name xml:lang="x-default">Subscription Information</display-name>
+                <attribute attribute-id="email" system="true"/>
+                <attribute attribute-id="firstName"/>
+                <attribute attribute-id="lastName"/>
+                <attribute attribute-id="subscriptionDate"/>
+                <attribute attribute-id="isActive"/>
+                <attribute attribute-id="topics"/>
+            </attribute-group>
+        </group-definitions>
+    </custom-type>
+</metadata>
+```
+
+## Site Preferences
+
+### 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="enableReviews">
+                <display-name xml:lang="x-default">Enable Product Reviews</display-name>
+                <type>boolean</type>
+                <default-value>true</default-value>
+            </attribute-definition>
+            <attribute-definition attribute-id="reviewServiceUrl">
+                <display-name xml:lang="x-default">Review Service URL</display-name>
+                <type>string</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="reviewServiceApiKey">
+                <display-name xml:lang="x-default">Review Service API Key</display-name>
+                <type>password</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="maxReviewsPerProduct">
+                <display-name xml:lang="x-default">Max Reviews Per Product</display-name>
+                <type>int</type>
+                <default-value>10</default-value>
+            </attribute-definition>
+        </custom-attribute-definitions>
+        <group-definitions>
+            <attribute-group group-id="ReviewSettings">
+                <display-name xml:lang="x-default">Review Settings</display-name>
+                <attribute attribute-id="enableReviews"/>
+                <attribute attribute-id="reviewServiceUrl"/>
+                <attribute attribute-id="reviewServiceApiKey"/>
+                <attribute attribute-id="maxReviewsPerProduct"/>
+            </attribute-group>
+        </group-definitions>
+    </type-extension>
+</metadata>
+```
+
+### Preference Values (sites/RefArch/preferences.xml)
+
+Preferences can be set per instance type 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>
+            <preference preference-id="maxReviewsPerProduct">20</preference>
+        </all-instances>
+        <development>
+            <preference preference-id="enableReviews">true</preference>
+            <preference preference-id="reviewServiceUrl">https://dev-reviews.example.com/api</preference>
+        </development>
+        <production>
+            <preference preference-id="enableReviews">true</preference>
+            <preference preference-id="reviewServiceUrl">https://reviews.example.com/api</preference>
+        </production>
+    </custom-preferences>
+</preferences>
+```
+
+## Product Data with Custom Attributes
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<catalog xmlns="http://www.demandware.com/xml/impex/catalog/2006-10-31" catalog-id="storefront-catalog">
+    <product product-id="SKU123">
+        <display-name xml:lang="x-default">Example Product</display-name>
+        <short-description xml:lang="x-default">Short description</short-description>
+        <online-flag>true</online-flag>
+        <custom-attributes>
+            <custom-attribute attribute-id="manufacturerPartNumber">MPN-12345</custom-attribute>
+            <custom-attribute attribute-id="warrantyType">extended</custom-attribute>
+            <custom-attribute attribute-id="requiresAssembly">true</custom-attribute>
+            <custom-attribute attribute-id="weight">2.5</custom-attribute>
+            <custom-attribute attribute-id="certifications">energy-star</custom-attribute>
+            <custom-attribute attribute-id="certifications">ul-listed</custom-attribute>
+            <custom-attribute attribute-id="localDescription" xml:lang="en-US">US Description</custom-attribute>
+            <custom-attribute attribute-id="localDescription" xml:lang="fr-FR">Description en Français</custom-attribute>
+        </custom-attributes>
+    </product>
+</catalog>
+```
+
+## Custom Object Data
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<custom-objects xmlns="http://www.demandware.com/xml/impex/customobject/2006-10-31">
+    <custom-object type-id="NewsletterSubscription" object-id="user@example.com">
+        <object-attribute attribute-id="firstName">John</object-attribute>
+        <object-attribute attribute-id="lastName">Doe</object-attribute>
+        <object-attribute attribute-id="subscriptionDate">2024-01-15T10:30:00.000Z</object-attribute>
+        <object-attribute attribute-id="isActive">true</object-attribute>
+        <object-attribute attribute-id="topics">
+            <value>promotions</value>
+            <value>new-arrivals</value>
+        </object-attribute>
+    </custom-object>
+</custom-objects>
+```