Skip to content

Commit 0e2c956

Browse files
claveryclavery
committed
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 <display> not <display-value> - Custom object data uses <object-attribute> not <custom-attribute> - ISML tag location constraints documented - Parameter validation attributes for job steps
1 parent d72d682 commit 0e2c956

24 files changed

Lines changed: 8509 additions & 0 deletions

File tree

‎plugins/b2c-cli/skills/b2c-site-import-export/SKILL.md‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
---
2+
name: b2c-site-import-export
3+
description: Using the B2C CLI for site archive import/export with metadata XML patterns
4+
---
5+
6+
# Site Import/Export Skill
7+
8+
Use the `b2c` CLI plugin to import and export site archives on Salesforce B2C Commerce instances.
9+
10+
## Import Commands
11+
12+
### Import Local Directory
13+
14+
```bash
15+
# Import a local directory as a site archive
16+
b2c job import ./my-site-data
17+
18+
# Import and wait for completion
19+
b2c job import ./my-site-data --wait
20+
21+
# Import a local zip file
22+
b2c job import ./export.zip
23+
24+
# Keep the archive on the instance after import
25+
b2c job import ./my-site-data --keep-archive
26+
27+
# Show job log if the import fails
28+
b2c job import ./my-site-data --wait --show-log
29+
```
30+
31+
### Import Remote Archive
32+
33+
```bash
34+
# Import an archive that already exists on the instance (in Impex/src/instance/)
35+
b2c job import existing-archive.zip --remote
36+
```
37+
38+
## Export Commands
39+
40+
```bash
41+
# Export site data
42+
b2c job export
43+
44+
# Export with specific configuration
45+
b2c job export --wait
46+
```
47+
48+
## Common Workflows
49+
50+
### Adding a Custom Attribute to Products
51+
52+
1. Create the metadata XML file:
53+
54+
**meta/system-objecttype-extensions.xml:**
55+
```xml
56+
<?xml version="1.0" encoding="UTF-8"?>
57+
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
58+
<type-extension type-id="Product">
59+
<custom-attribute-definitions>
60+
<attribute-definition attribute-id="vendorSKU">
61+
<display-name xml:lang="x-default">Vendor SKU</display-name>
62+
<type>string</type>
63+
<mandatory-flag>false</mandatory-flag>
64+
<externally-managed-flag>true</externally-managed-flag>
65+
</attribute-definition>
66+
</custom-attribute-definitions>
67+
<group-definitions>
68+
<attribute-group group-id="CustomAttributes">
69+
<display-name xml:lang="x-default">Custom Attributes</display-name>
70+
<attribute attribute-id="vendorSKU"/>
71+
</attribute-group>
72+
</group-definitions>
73+
</type-extension>
74+
</metadata>
75+
```
76+
77+
2. Create the directory structure:
78+
```
79+
my-import/
80+
└── meta/
81+
└── system-objecttype-extensions.xml
82+
```
83+
84+
3. Import:
85+
```bash
86+
b2c job import ./my-import --wait
87+
```
88+
89+
### Adding Site Preferences
90+
91+
1. Create metadata for the preference:
92+
93+
**meta/system-objecttype-extensions.xml:**
94+
```xml
95+
<?xml version="1.0" encoding="UTF-8"?>
96+
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
97+
<type-extension type-id="SitePreferences">
98+
<custom-attribute-definitions>
99+
<attribute-definition attribute-id="enableFeatureX">
100+
<display-name xml:lang="x-default">Enable Feature X</display-name>
101+
<type>boolean</type>
102+
<default-value>false</default-value>
103+
</attribute-definition>
104+
</custom-attribute-definitions>
105+
</type-extension>
106+
</metadata>
107+
```
108+
109+
2. Create preference values:
110+
111+
**sites/MySite/preferences.xml:**
112+
```xml
113+
<?xml version="1.0" encoding="UTF-8"?>
114+
<preferences xmlns="http://www.demandware.com/xml/impex/preferences/2007-03-31">
115+
<custom-preferences>
116+
<all-instances>
117+
<preference preference-id="enableFeatureX">true</preference>
118+
</all-instances>
119+
</custom-preferences>
120+
</preferences>
121+
```
122+
123+
3. Directory structure:
124+
```
125+
my-import/
126+
├── meta/
127+
│ └── system-objecttype-extensions.xml
128+
└── sites/
129+
└── MySite/
130+
└── preferences.xml
131+
```
132+
133+
4. Import:
134+
```bash
135+
b2c job import ./my-import --wait
136+
```
137+
138+
### Creating a Custom Object Type
139+
140+
1. Define the custom object:
141+
142+
**meta/custom-objecttype-definitions.xml:**
143+
```xml
144+
<?xml version="1.0" encoding="UTF-8"?>
145+
<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
146+
<custom-type type-id="APIConfiguration">
147+
<display-name xml:lang="x-default">API Configuration</display-name>
148+
<staging-mode>source-to-target</staging-mode>
149+
<storage-scope>site</storage-scope>
150+
<key-definition attribute-id="configId">
151+
<display-name xml:lang="x-default">Config ID</display-name>
152+
<type>string</type>
153+
<min-length>1</min-length>
154+
</key-definition>
155+
<attribute-definitions>
156+
<attribute-definition attribute-id="endpoint">
157+
<display-name xml:lang="x-default">API Endpoint</display-name>
158+
<type>string</type>
159+
</attribute-definition>
160+
<attribute-definition attribute-id="apiKey">
161+
<display-name xml:lang="x-default">API Key</display-name>
162+
<type>password</type>
163+
</attribute-definition>
164+
<attribute-definition attribute-id="isActive">
165+
<display-name xml:lang="x-default">Active</display-name>
166+
<type>boolean</type>
167+
<default-value>true</default-value>
168+
</attribute-definition>
169+
</attribute-definitions>
170+
</custom-type>
171+
</metadata>
172+
```
173+
174+
2. Import:
175+
```bash
176+
b2c job import ./my-import --wait
177+
```
178+
179+
### Importing Custom Object Data
180+
181+
**customobjects/APIConfiguration.xml:**
182+
```xml
183+
<?xml version="1.0" encoding="UTF-8"?>
184+
<custom-objects xmlns="http://www.demandware.com/xml/impex/customobject/2006-10-31">
185+
<custom-object type-id="APIConfiguration" object-id="payment-gateway">
186+
<object-attribute attribute-id="endpoint">https://api.payment.com/v2</object-attribute>
187+
<object-attribute attribute-id="isActive">true</object-attribute>
188+
</custom-object>
189+
</custom-objects>
190+
```
191+
192+
## Site Archive Structure
193+
194+
```
195+
site-archive/
196+
├── meta/
197+
│ ├── system-objecttype-extensions.xml # Custom attributes on system objects
198+
│ └── custom-objecttype-definitions.xml # Custom object type definitions
199+
├── sites/
200+
│ └── {SiteID}/
201+
│ ├── preferences.xml # Site preference values
202+
│ └── library/
203+
│ └── content/
204+
│ └── content.xml # Content assets
205+
├── catalogs/
206+
│ └── {CatalogID}/
207+
│ └── catalog.xml # Products and categories
208+
├── pricebooks/
209+
│ └── {PriceBookID}/
210+
│ └── pricebook.xml # Price definitions
211+
├── customobjects/
212+
│ └── {ObjectTypeID}.xml # Custom object instances
213+
└── inventory-lists/
214+
└── {InventoryListID}/
215+
└── inventory.xml # Inventory records
216+
```
217+
218+
## Tips
219+
220+
### Checking Job Status
221+
222+
```bash
223+
# Search for recent job executions
224+
b2c job search
225+
226+
# Wait for a specific job execution
227+
b2c job wait <execution-id>
228+
229+
# View job logs on failure
230+
b2c job import ./my-data --wait --show-log
231+
```
232+
233+
### Best Practices
234+
235+
1. **Test imports on sandbox first** before importing to staging/production
236+
2. **Use `--wait`** to ensure import completes before continuing
237+
3. **Use `--show-log`** to debug failed imports
238+
4. **Keep archives organized** by feature or change type
239+
5. **Version control your metadata** XML files
240+
241+
## Detailed Reference
242+
243+
- [Metadata XML Patterns](references/METADATA-XML.md) - Common XML patterns for imports

0 commit comments

Comments
 (0)