diff --git a/manifest.json b/manifest.json index 920bb76..09efdbd 100644 --- a/manifest.json +++ b/manifest.json @@ -53,21 +53,22 @@ ] }, { - "name": "Retrieve Commerce Storefront Metadata", - "path": "prompts/commerce/retrieve-commerce-storefront.md", - "description": "Download and version-control an existing B2B/B2C Commerce LWR storefront from your org after creating the Commerce Store", + "name": "Create and Retrieve B2B Commerce Storefront", + "path": "prompts/commerce/create-retrieve-b2b-storefront.md", + "description": "Interactive guide to create a Commerce B2B Store and retrieve storefront metadata", "category": "commerce", "tags": [ - "commerce", "b2b", - "b2c", + "scom", + "scom b2b", + "commerce b2b", "storefront", "lwr", "retrieve", "metadata" ], "requires_setup": true, - "setup_summary": "Commerce Store must be created in the org first via Setup → Commerce → Store Administration" + "setup_summary": "Requires Commerce licenses; agent guides through store creation interactively" }, { "name": "Account Layout Field Enhancement", @@ -339,14 +340,15 @@ ] }, { - "name": "Commerce Store Creation Requirements", - "path": "rules/commerce/commerce-store-requirements.md", - "description": "Critical workflow for creating B2B/B2C Commerce stores and storefronts - understand the distinction between Commerce Store (runtime data) and Storefront (LWR site).", + "name": "Commerce B2B Store Creation Requirements", + "path": "rules/commerce/commerce-b2b-store-requirements.md", + "description": "Critical workflow for creating B2B Commerce stores - understand Store vs Storefront distinction", "category": "commerce", "tags": [ - "commerce", "b2b", - "b2c", + "scom", + "scom b2b", + "commerce b2b", "store", "storefront", "lwr", diff --git a/prompts/commerce/README.md b/prompts/commerce/README.md index 975818d..e45136b 100644 --- a/prompts/commerce/README.md +++ b/prompts/commerce/README.md @@ -1,6 +1,6 @@ # Commerce Prompts -Prompts for building and managing Salesforce B2B Commerce and B2C Commerce storefronts. +Prompts for building and managing Salesforce B2B Commerce storefronts. ## Overview @@ -33,58 +33,65 @@ Commerce consists of two distinct but connected parts: ### Correct Workflow +> See full interactive flow in `create-retrieve-b2b-storefront.md` + ```bash # 1. Create Commerce Store in org (via UI) -# Setup → Commerce → Store Administration → Create Store +# Setup → Commerce → Stores → Create Store -# 2. Retrieve the auto-generated storefront metadata -sf project retrieve start --metadata ExperienceBundle:My_Store_Name +# 2. List available storefronts +sf org list metadata --metadata-type DigitalExperienceConfig -# 3. Customize with additional LWCs or pages +# 3. Retrieve the auto-generated storefront metadata +sf project retrieve start -m DigitalExperienceBundle:site/My_Store_Name + +# 4. Customize with additional LWCs or pages # Add custom components, modify layouts in Experience Builder -# 4. Version control and deploy -git add force-app/main/default/experiences/ +# 5. Version control and deploy +git add force-app/main/default/digitalExperiences/ git commit -m "feat: add My Store storefront" ``` ### ❌ Incorrect Approach -Don't manually create StorefrontName.digitalExperience-meta.xml or StorefrontName.digitalExperience-meta.xml from scratch. The Commerce setup wizard generates complex configurations that are difficult to replicate manually. +Don't manually create StorefrontName.digitalExperience-meta.xml from scratch. The Commerce setup wizard generates complex configurations that are difficult to replicate manually. ## Available Prompts -### Retrieve Commerce Storefront Metadata -**Use when:** You've created a Commerce Store in your org and want to download the storefront to version control +### Create and Retrieve B2B Commerce Storefront +**Use when:** You want to create a Commerce B2B Store and download the storefront to version control **Prerequisites:** -- Commerce Store created via Commerce app -- Experience Cloud site exists and is associated with store -- Default org authorized with Salesforce CLI +- Commerce licenses available in org +- Experience Cloud enabled +- Salesforce CLI authorized with default org **What it does:** -- Guides you through retrieving ExperienceBundle metadata -- Explains what files you'll get -- Provides customization next steps -- Includes deployment instructions for other orgs +- Guides through interactive 7-step workflow +- Explains Store vs Storefront concept +- Lists available Digital Experiences in org +- Retrieves ExperienceBundle metadata +- Provides customization and deployment guidance ## Related Rules Before using these prompts, review: -**`rules/commerce/commerce-store-requirements.md`** +**`rules/commerce/commerce-b2b-store-requirements.md`** - Explains Store vs Storefront distinction - Details the required creation workflow - Lists what is/isn't source-controllable - Provides deployment checklist +- Contains agent guidance for interactive flow ## Common Scenarios ### Scenario 1: New B2B Store ``` -1. Follow commerce-store-requirements.md rule +1. Follow commerce-b2b-store-requirements.md rule 2. Create Store in org via Commerce app -3. Use "Retrieve Commerce Storefront Metadata" prompt +3. Use "Create and Retrieve B2B Commerce Storefront" prompt 4. Customize with custom LWCs (hero banner, promotions) 5. Commit and deploy to other environments ``` @@ -129,34 +136,32 @@ After retrieving a Commerce storefront: ``` force-app/main/default/ -├── experiences/ -│ └── My_B2B_Store/ -│ ├── StorefrontName.digitalExperience-meta.xml # Site config -│ ├── StorefrontName.digitalExperience-meta.xml # Bundle metadata -│ ├── config/ # Store settings -│ ├── views/ # Page definitions -│ │ ├── home.json -│ │ ├── category.json # PLP -│ │ ├── product.json # PDP -│ │ ├── cart.json -│ │ └── checkout.json -│ └── routes/ # URL routing -└── lwc/ - ├── b2bHeroBanner/ # Custom components - ├── b2bPromotionCard/ - └── b2bNavHelper/ +└── digitalExperiences/ + └── site/ + └── My_B2B_Store1/ + ├── My_B2B_Store1.digitalExperience-meta.xml # Bundle metadata + ├── sfdc_cms__view/ # Pages + │ ├── home/ + │ ├── current_cart/ + │ ├── current_checkout/ + │ ├── detail_*/ # PDP + │ └── list_*/ # PLP + ├── sfdc_cms__route/ # URL routing + ├── sfdc_cms__site/ # Site settings + ├── sfdc_cms__theme/ # Theme config + └── [other sfdc_cms__* directories] ``` ## Tags Commerce prompts use these tags: -- `commerce` - General Commerce functionality - `b2b` - B2B Commerce specific -- `b2c` - B2C Commerce specific -- `storefront` - Buyer-facing storefront -- `store` - Backend store configuration +- `scom` - Salesforce Commerce +- `scom b2b` - Salesforce Commerce B2B +- `commerce b2b` - Commerce B2B specific +- `storefront` - Buyer-facing storefront (metadata) +- `store` - Backend store configuration (data) - `lwr` - Lightning Web Runtime sites -- `experience-cloud` - Experience Cloud/Digital Experiences - `retrieve` - Metadata retrieval operations - `metadata` - Source-controllable assets @@ -164,8 +169,8 @@ Commerce prompts use these tags: **Salesforce Documentation:** - [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_guide/) -- [B2C Commerce on Core Guide](https://help.salesforce.com/s/articleView?id=sf.comm_digital_overview.htm) - [Experience Cloud LWR Sites](https://developer.salesforce.com/docs/platform/lwr-sites/guide/overview.html) +- [DigitalExperienceBundle Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle.htm) **Trailhead:** - [B2B Commerce Basics](https://trailhead.salesforce.com/content/learn/modules/b2b-commerce-basics) @@ -174,12 +179,11 @@ Commerce prompts use these tags: **CLI Commands:** ```bash # List Commerce metadata -sf org list metadata --metadata-type DigitalExperience -sf org list metadata --metadata-type ExperienceBundle +sf org list metadata --metadata-type DigitalExperienceConfig # Retrieve storefront -sf project retrieve start --metadata ExperienceBundle:StoreName +sf project retrieve start -m DigitalExperienceBundle:site/StoreName # Deploy storefront -sf project deploy start --source-dir force-app/main/default/experiences/ +sf project deploy start --source-dir force-app/main/default/digitalExperiences/site/StoreName/ ``` diff --git a/prompts/commerce/create-retrieve-b2b-storefront.md b/prompts/commerce/create-retrieve-b2b-storefront.md new file mode 100644 index 0000000..edb51a7 --- /dev/null +++ b/prompts/commerce/create-retrieve-b2b-storefront.md @@ -0,0 +1,238 @@ +--- +name: Create and Retrieve B2B Commerce Storefront +description: Interactive guide to create a Commerce B2B Store and retrieve storefront metadata +tags: commerce, b2b, scom, scom b2b, commerce b2b, storefront, lwr, retrieve, metadata +category: commerce +requires_setup: true +setup_summary: Requires Commerce licenses; agent guides through store creation interactively +--- + +## Context + +This interactive workflow guides you through creating a Commerce B2B Store in your Salesforce org and retrieving the auto-generated storefront metadata to your local repository. + +**Important:** Commerce B2B consists of two components: +1. **Commerce Store (Backend)** - Runtime data configured in the org (NOT source-controllable) +2. **Storefront (Frontend)** - LWR Digital Experience site (source-controllable metadata) + +The Store must be created first because it automatically generates the associated Digital Experience site. + +> **See:** `rules/commerce/commerce-b2b-store-requirements.md` for detailed Store vs Storefront distinction + +--- + +## Interactive Flow + +### Step 1: Explain Commerce B2B Store Concept + +**Agent should explain:** + +Commerce B2B on Salesforce Core consists of two components that work together: + +1. **Commerce Store (Backend)** - Runtime data configured in the org (WebStore records, buyer groups, pricing policies, payment settings). This is NOT source-controllable. + +2. **Storefront (Frontend)** - LWR Digital Experience site for buyers. This IS source-controllable as metadata (ExperienceBundle). + +The Store must be created in the org first because the setup wizard automatically generates the associated Digital Experience site with all necessary Commerce components configured correctly. + +> **See:** `rules/commerce/commerce-b2b-store-requirements.md` for detailed Store vs Storefront distinction + +--- + +### Step 2: Ask User to Create B2B Store + +**Agent should provide these steps:** + +1. In your Salesforce org, navigate to **Setup → Commerce → Stores** + - OR use the Commerce app from **App Launcher → Commerce → Create Store** + +2. Click **"Create Store"** or **"Setup New Store"** + +3. Select **"B2B Store"** as the store type + +4. Follow the store setup wizard: + - **Store Name**: Choose a descriptive name (e.g., "My B2B Store") + - ⚠️ Important: This name determines the folder name (spaces become underscores) + - **Default Buyer Group**: Associate with Account objects + - **Price Book**: Select or create price book + - **Checkout Settings**: Configure checkout flow + +5. Complete the wizard - it will automatically create: + - WebStore record + - Default buyer group and entitlement policies + - Associated Digital Experience (LWR site) + +6. Optionally configure: + - Payment gateway (Stripe, Adyen, etc.) + - Tax provider (Avalara, Vertex) + - Shipping methods + +**Agent should then ask:** +"Have you completed creating the B2B Store in your org? Please reply 'yes' when ready, and let me know the store name you used." + +--- + +### Step 3: Get Confirmation from User + +**Agent waits for:** User confirmation (e.g., "yes") and store name + +**Agent validates:** Store name format +- No special characters +- Spaces in name will appear as underscores in folder (e.g., "My B2B Store" → "My_B2B_Store1") + +**Agent acknowledges:** "Great! Let me list the available storefronts in your org..." + +--- + +### Step 4: Run CLI Command to List LWR Sites + +**Agent executes:** +```bash +sf org list metadata --metadata-type DigitalExperienceConfig +``` + +**Agent should:** +- Parse the output to extract site names +- Display as a numbered list for easy selection +- Explain: "The store name appears with underscores and may have a number suffix (e.g., 'My_B2B_Store1')" + +**Example output format:** +``` +Available Digital Experience sites: +1. My_B2B_Store1 +2. Partner_Portal +3. Customer_Community +``` + +--- + +### Step 5: Let User Select Storefront + +**Agent should ask:** +"Which site corresponds to your B2B Store? Enter the number or the full site name:" + +**Agent validates:** +- Selection matches one of the available sites +- If unclear, ask user to confirm the exact name + +**Agent confirms:** "Got it! I'll retrieve the metadata for [site-name]..." + +--- + +### Step 6: Retrieve Storefront Metadata + +**Agent executes:** +```bash +sf project retrieve start -m DigitalExperienceBundle:site/ +``` + +**Agent should:** +- Show retrieval progress +- Confirm successful retrieval +- List the retrieved directory structure + +**Expected output:** +``` +Retrieved: force-app/main/default/digitalExperiences/site/My_B2B_Store1/ +├── My_B2B_Store1.digitalExperience-meta.xml +├── sfdc_cms__view/ (home, current_cart, detail_*, list_*, etc.) +├── sfdc_cms__site/ +├── sfdc_cms__route/ +└── [other sfdc_cms__* directories] +``` + +--- + +### Step 7: Inform User About Next Steps + +**Agent provides:** + +✅ **Storefront metadata successfully retrieved!** + +**What you can do next:** + +1. **Customize the storefront:** + - Add custom LWCs for unique B2B features + - Modify page layouts in Experience Builder + - Customize branding (colors, fonts, logos) + - Add content pages (About Us, Contact, etc.) + +2. **Version control:** + ```bash + git add force-app/main/default/digitalExperiences/ + git commit -m "feat: add B2B Commerce storefront metadata" + ``` + +3. **Deploy to other orgs:** + - First create B2B Store in target org with same name + - Then deploy the metadata: + ```bash + sf project deploy start --source-dir force-app/main/default/digitalExperiences/site/My_B2B_Store1/ + ``` + +**📚 Documentation Resources:** +- [DigitalExperienceBundle Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle.htm) +- [DigitalExperienceBundle Site](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle_site.htm) +- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_guide/) + +**🎯 For Advanced Customization:** +See `rules/commerce/commerce-b2b-store-requirements.md` for: +- B2B-specific workflow patterns +- Custom LWC development guidelines +- Multi-org deployment strategies + +--- + +## Important Notes + +### ⚠️ Commerce Store Data vs Storefront Metadata + +**What IS source-controllable (Storefront):** +- ✅ ExperienceBundle metadata (this prompt) +- ✅ Custom LWCs +- ✅ Page layouts and content +- ✅ Navigation structure + +**What is NOT source-controllable (Commerce Store):** +- ❌ WebStore records (store settings, buyer groups) +- ❌ Product catalog data +- ❌ Price books and pricing rules +- ❌ Entitlement policies +- ❌ Inventory data +- ❌ Payment/tax/shipping configurations + +**To migrate Commerce Store data between orgs:** +- Use Data Loader or Salesforce Data APIs +- Or recreate via Commerce app UI +- Or use Commerce APIs for programmatic setup + +--- + +## Troubleshooting + +### Issue: "No DigitalExperienceConfig found" + +**Cause:** Store name mismatch or store not yet created + +**Fix:** +1. Verify store exists: Setup → Commerce → Stores +2. Verify Experience site exists: Setup → Digital Experiences → All Sites +3. Check exact name (case-sensitive, underscores for spaces) +4. Try: `sf org list metadata --metadata-type DigitalExperienceConfig` + +### Issue: "Deployment failed - Store not found" + +**Cause:** Target org doesn't have a Commerce Store with matching name + +**Fix:** +1. In target org, create Commerce Store with SAME NAME as source +2. Then deploy Experience metadata + +### Issue: "Commerce components not rendering" + +**Cause:** Store configuration missing or incorrect WebStore association + +**Fix:** +1. Verify WebStore is active in target org +2. Check Experience is associated with correct WebStore +3. Verify buyer user has correct entitlements and permissions diff --git a/prompts/commerce/retrieve-commerce-storefront.md b/prompts/commerce/retrieve-commerce-storefront.md deleted file mode 100644 index 6372d2a..0000000 --- a/prompts/commerce/retrieve-commerce-storefront.md +++ /dev/null @@ -1,356 +0,0 @@ ---- -name: Retrieve Commerce Storefront Metadata -description: Download and version-control an existing B2B/B2C Commerce LWR storefront from your org after creating the Commerce Store -tags: commerce, b2b, b2c, storefront, lwr, retrieve, metadata, scom -category: commerce -requires_setup: true -setup_summary: Commerce Store must be created in the org first via Setup → Commerce → Stores ---- - -## Context - -You have created a Commerce Store (B2B or B2C) in your Salesforce org using the Commerce app, and now you want to: -1. Download the auto-generated Experience Cloud storefront metadata -2. Version-control it in your repository -3. Customize it with additional LWCs or pages - -**Important:** This prompt assumes you have ALREADY created the Commerce Store in your org. If you haven't done that yet, refer to the "Commerce Store Creation Requirements" rule first. - -## Setup - -### 1. Verify Commerce Store Exists in Org - -Before proceeding, confirm your Commerce Store is set up: - -```bash -# Check your connected org -sf org display --verbose - -# Verify the store exists -# Go to Setup → Commerce → Stores -# You should see your store listed with status "Active" -``` - -**Required information:** -- Store name (e.g., "My B2B Store") -- Associated Experience Cloud site name (usually matches store name with underscores) -- Store is active and has default configurations - -### 2. Find Your Experience Site Name - -The Commerce setup wizard automatically creates an Experience Cloud site. To find it: - -1. **In Setup:** - - Go to Setup → Digital Experiences → All Sites - - Look for the site with same name as your store (e.g., "My B2B Store") - - Note the exact folder name used in metadata (e.g., "My_B2B_Store1") - -2. **Or use CLI:** - ```bash - sf org list metadata --metadata-type DigitalExperience - ``` - -## Instructions - -### Step 1: List Available Digital Experiences - -First, see what's available in your org: - -```bash -# List all Digital Experiences -sf org list metadata --metadata-type DigitalExperience - -# List all Experience Bundles (more detailed) -sf org list metadata --metadata-type ExperienceBundle -``` - -**Example output:** -``` -DigitalExperience/My_B2B_Store -DigitalExperience/Partner_Community -``` - -### Step 2: Retrieve the Experience Bundle - -Retrieve the complete storefront metadata for your Commerce store: - -```bash -# Replace "My_B2B_Store" with your actual store name -sf project retrieve start --metadata ExperienceBundle:My_B2B_Store - -# Alternative: Retrieve all experiences (if you're unsure of the name) -sf project retrieve start --metadata ExperienceBundle -``` - -**What this retrieves:** -``` -force-app/main/default/digitalExperiences/site/StorefrontName/ -├── StorefrontName.digitalExperience-meta.xml # Digital Experience Bundle metadata -├── sfdc_cms__appPage/ # App page configuration -├── sfdc_cms__brandingSet/ # Branding assets -├── sfdc_cms__label/ # Labels and translations -├── sfdc_cms__languageSettings/ # Language configuration -├── sfdc_cms__lwc/ # Lightning Web Components (custom) -├── sfdc_cms__mobilePublisherConfig/ # Mobile configuration -├── sfdc_cms__route/ # URL routing configuration -├── sfdc_cms__site/ # Site settings -├── sfdc_cms__styles/ # CSS styles -├── sfdc_cms__theme/ # Theme configuration -├── sfdc_cms__themeLayout/ # Theme layouts -└── sfdc_cms__view/ # Page definitions (views) - ├── home/ # Homepage - ├── current_cart/ # Shopping cart page - ├── current_checkout/ # Checkout page - ├── detail_*/ # Product Detail Pages (PDP) - ├── list_*/ # Product List Pages (PLP) - ├── order/ # Order confirmation - ├── global_search/ # Search results - └── [other pages...] -``` - -**Example:** For a store named "My B2B Store", the folder would be: -``` -force-app/main/default/digitalExperiences/site/My_B2B_Store1/ -├── My_B2B_Store1.digitalExperience-meta.xml -└── [subdirectories as shown above] -``` - -### Step 3: Verify Retrieved Files - -Check that the metadata was retrieved successfully: - -```bash -# List the experience files -ls -la force-app/main/default/digitalExperiences/My_B2B_Store1/ - -# Check the digitalExperience metadata file -cat force-app/main/default/digitalExperiences/site/My_B2B_Store1/My_B2B_Store1.digitalExperience-meta.xml -``` - -**Expected content in digitalExperience-meta.xml:** -```xml - - - - ... - -``` - -### Step 4: Inspect Commerce Pages - -Review the out-of-box Commerce pages: - -```bash -# List all views (pages) -ls force-app/main/default/digitalExperiences/site/My_B2B_Store1/sfdc_cms__view/ - -# View a product detail page directory -ls force-app/main/default/digitalExperiences/site/My_B2B_Store1/sfdc_cms__view/detail_*/ -``` - -**Key Commerce pages you'll find in sfdc_cms__view/:** -- **home/** - Homepage with hero banner, featured products -- **list_*/** - Product List Pages (PLP) with filters, facets -- **detail_*/** - Product Detail Pages (PDP) with images, add-to-cart -- **current_cart/** - Shopping cart with quantity updates, remove items -- **current_checkout/** - Multi-step checkout flow (shipping, payment, review) -- **global_search/** - Search results page -- **addresses/** - Buyer address management (B2B) -- **order/** - Order confirmation and history - -### Step 5: Commit to Version Control - -Add the retrieved metadata to your repository: - -```bash -# Add the experience files -git add force-app/main/default/digitalExperiences/My_B2B_Store1/ - -# Commit with descriptive message -git commit -m "feat: add My B2B Store commerce storefront metadata - -Retrieved from org after creating Commerce Store via Setup. -Includes home, category, product, cart, checkout pages with -out-of-box Commerce components." - -# Push to remote -git push origin main -``` - -## Testing & Verification - -### 1. Test Retrieval in a Scratch Org - -**Important:** You cannot deploy Commerce storefront metadata to a scratch org without first creating the Commerce Store in that org. - -To test in another org: - -```bash -# 1. Create scratch org with Commerce features -sf org create scratch --definition-file config/project-scratch-def.json --alias commerce-scratch - -# 2. In the scratch org Setup, create a Commerce Store with the SAME NAME as your source org -# (Setup → Commerce → Stores → Create Store) -# Use the same store name: "My B2B Store" - -# 3. THEN deploy the experience metadata -sf project deploy start --source-dir force-app/main/default/digitalExperiences/My_B2B_Store1/ --target-org commerce-scratch - -# 4. Open Experience Builder to verify -sf org open --target-org commerce-scratch --path /lightning/setup/SetupNetworks/home -``` - -### 2. Verify Components in Experience Builder - -1. Open your org in Setup -2. Go to Digital Experiences → All Sites -3. Click "Builder" next to your store site -4. Verify all pages load correctly: - - Home page with hero banner - - Category page with product grid - - Product page with add-to-cart - - Cart with line items - - Checkout flow - -## Customization Next Steps - -Now that you have the storefront metadata, you can customize it: - -### 1. Add Custom LWCs - -```bash -# Create a custom promotion banner component -sf lightning generate component --type lwc \ - --name b2bPromotionBanner \ - --output-dir force-app/main/default/lwc - -# Make it available to Experience Builder -# Edit b2bPromotionBanner.js-meta.xml: -# true -# -# lightningCommunity__Page -# -``` - -**Follow these rules for Commerce LWCs:** -- Use LDS-first approach (no Apex unless necessary) -- Expose `@api` properties for Experience Builder configuration -- Use `lightning-` base components (SLDS) -- Use `NavigationMixin` for routing -- Follow naming: `b2b[ComponentName]` or `b2c[ComponentName]` - -### 2. Modify Page Layouts - -1. Open Experience Builder in your org -2. Edit the page layout (e.g., add your custom component to Home) -3. Save and publish -4. Retrieve the updated metadata: - ```bash - sf project retrieve start --metadata ExperienceBundle:My_B2B_Store - ``` -5. Commit the changes: - ```bash - git add force-app/main/default/digitalExperiences/ - git commit -m "feat: add custom promotion banner to home page" - ``` - -### 3. Add Content Pages - -Create additional non-commerce pages (About Us, FAQ, Contact): - -1. In Experience Builder → Pages → New Page -2. Add content (text, images, forms) -3. Retrieve updated metadata -4. Commit changes - -## Important Notes - -### ⚠️ Commerce Store Data vs Storefront Metadata - -**What IS source-controllable (Storefront):** -- ✅ ExperienceBundle metadata (this prompt) -- ✅ Custom LWCs -- ✅ Page layouts and content -- ✅ Navigation structure - -**What is NOT source-controllable (Commerce Store):** -- ❌ WebStore records (store settings, buyer groups) -- ❌ Product catalog data -- ❌ Price books and pricing rules -- ❌ Entitlement policies -- ❌ Inventory data -- ❌ Payment/tax/shipping configurations - -**To migrate Commerce Store data between orgs:** -- Use Data Loader or Salesforce Data APIs -- Or recreate via Commerce app UI -- Or use Commerce APIs for programmatic setup - -### 🔄 Sync Workflow - -After making changes in Experience Builder: - -```bash -# Always retrieve after UI changes -sf project retrieve start --metadata ExperienceBundle:My_B2B_Store - -# Check what changed -git diff - -# Commit meaningful changes -git add force-app/main/default/digitalExperiences/ -git commit -m "chore: update homepage hero banner CTA" -``` - -## Troubleshooting - -### Issue: "No ExperienceBundle found" - -**Cause:** Store name mismatch or store not yet created - -**Fix:** -1. Verify store exists: Setup → Commerce → Stores -2. Verify Experience site exists: Setup → Digital Experiences → All Sites -3. Check exact name (case-sensitive, underscores for spaces) -4. Try: `sf org list metadata --metadata-type ExperienceBundle` - -### Issue: "Deployment failed - Store not found" - -**Cause:** Target org doesn't have a Commerce Store with matching name - -**Fix:** -1. In target org, create Commerce Store with SAME NAME as source -2. Then deploy Experience metadata - -### Issue: "Commerce components not rendering" - -**Cause:** Store configuration missing or incorrect WebStore association - -**Fix:** -1. Verify WebStore is active in target org -2. Check Experience is associated with correct WebStore -3. Verify buyer user has correct entitlements and permissions - -## Follow-ups - -After retrieving your storefront: - -- [ ] Document your store name and configuration in README.md -- [ ] Create deployment scripts for other environments -- [ ] Set up CI/CD pipeline for storefront changes -- [ ] Create a catalog of custom LWCs for reusability -- [ ] Document Commerce Store setup steps for new environments -- [ ] Test complete buy flow (browse → PDP → cart → checkout) - -## Additional Resources - -**Salesforce CLI:** -- `sf project retrieve start --help` -- `sf org list metadata --help` - -**Commerce Documentation:** -- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore.htm) -- [Commerce Customization Guide](https://help.salesforce.com/s/articleView?id=sf.comm_digital_customize.htm) - -**Experience Cloud:** -- [LWR Sites Developer Guide](https://developer.salesforce.com/docs/platform/lwr-sites/guide/overview.html) diff --git a/rules/commerce/README.md b/rules/commerce/README.md index ea7169d..f57b8f4 100644 --- a/rules/commerce/README.md +++ b/rules/commerce/README.md @@ -1,6 +1,6 @@ # Commerce Rules -Rules and guardrails for developing B2B Commerce and B2C Commerce solutions on Salesforce. +Rules and guardrails for developing B2B Commerce solutions on Salesforce. ## Overview @@ -21,10 +21,12 @@ The most important concept in Commerce development is understanding the distinct | **Deployment** | Data APIs or manual recreation | Salesforce CLI metadata deploy | | **Examples** | Pricing policies, payment settings | Product pages, cart, checkout UI | +> **See:** `commerce-b2b-store-requirements.md` for comprehensive details + ## Available Rules -### Commerce Store Creation Requirements -**`commerce-store-requirements.md`** +### Commerce B2B Store Creation Requirements +**`commerce-b2b-store-requirements.md`** **Apply when:** Developer is creating a new Commerce storefront @@ -41,17 +43,7 @@ The most important concept in Commerce development is understanding the distinct - Confusion about what can/cannot be source-controlled **Required Workflow:** -``` -1. Create Commerce Store (org UI) - ↓ -2. Store wizard creates Digital Experience - ↓ -3. Retrieve Experience metadata to repo - ↓ -4. Customize and commit - ↓ -5. Deploy to other orgs (after creating Store in target) -``` +> See full workflow in `commerce-b2b-store-requirements.md` ## When to Apply These Rules @@ -59,17 +51,17 @@ The most important concept in Commerce development is understanding the distinct **User says:** - "Create a B2B Commerce store" -- "Build a B2C storefront" +- "Build a B2B storefront" - "Set up Commerce on Core" - "Create an LWR Commerce site" - "Build a digital storefront" **Agent should:** -1. ✅ Cite `rules/commerce/commerce-store-requirements.md` -2. ✅ Explain Store vs Storefront distinction -3. ✅ Guide user to create Store in org first -4. ✅ Provide CLI commands to retrieve metadata -5. ❌ **DO NOT** create StorefrontName.digitalExperience-meta.xml or StorefrontName.digitalExperience-meta.xml from scratch +1. ✅ Follow interactive flow from `prompts/commerce/create-retrieve-b2b-storefront.md` +2. ✅ Explain Store vs Storefront (link to rule file) +3. ✅ Use `sf org list metadata --metadata-type DigitalExperienceConfig` to list sites +4. ✅ Get user confirmation at each step +5. ❌ **DO NOT** create storefront files from scratch ### Trigger: User asks to deploy storefront @@ -105,7 +97,7 @@ The most important concept in Commerce development is understanding the distinct ### ❌ Deploying Without Store ```bash # WRONG - Will fail if Store doesn't exist in target -sf project deploy start --source-dir force-app/main/default/experiences/My_Store/ +sf project deploy start --source-dir force-app/main/default/digitalExperiences/My_Store/ # Error: WebStore not found ``` @@ -113,7 +105,7 @@ sf project deploy start --source-dir force-app/main/default/experiences/My_Store ```bash # 1. First create Store in target org (UI or API) # 2. THEN deploy -sf project deploy start --source-dir force-app/main/default/experiences/My_Store/ +sf project deploy start --source-dir force-app/main/default/digitalExperiences/My_Store/ ``` ### ❌ Trying to Version Control Store Data @@ -127,7 +119,8 @@ sf project retrieve start --metadata WebStore ```bash # Use Data Loader, APIs, or manual recreation for Store data # Only retrieve Experience metadata -sf project retrieve start --metadata ExperienceBundle:My_Store +sf org list metadata --metadata-type DigitalExperienceConfig +sf project retrieve start -m DigitalExperienceBundle:site/My_Store ``` ## Enforcement Guidelines @@ -137,11 +130,11 @@ sf project retrieve start --metadata ExperienceBundle:My_Store When processing Commerce-related requests: 1. **Detection Phase** - - Parse user intent for Commerce keywords (store, storefront, B2B, B2C, Commerce) + - Parse user intent for Commerce keywords (store, storefront, B2B, Commerce) - Identify if request is for creation vs modification vs deployment 2. **Rule Application** - - Load `commerce-store-requirements.md` into context + - Load `commerce-b2b-store-requirements.md` into context - Cite relevant sections in response - Enforce the correct workflow order @@ -160,7 +153,7 @@ When processing Commerce-related requests: **Before starting any Commerce work:** -- [ ] Read `rules/commerce/commerce-store-requirements.md` completely +- [ ] Read `rules/commerce/commerce-b2b-store-requirements.md` completely - [ ] Understand Store (data) vs Storefront (metadata) - [ ] Have org access with Commerce licenses - [ ] Have Commerce Admin permissions @@ -231,7 +224,7 @@ When building complete Commerce solutions: Rules work with these prompts: -- **`prompts/commerce/retrieve-commerce-storefront.md`** - Step-by-step retrieval workflow +- **`prompts/commerce/create-retrieve-b2b-storefront.md`** - Interactive 7-step retrieval workflow - (Future) Create custom Commerce LWC components - (Future) Commerce data seeding and migration - (Future) Multi-store management diff --git a/rules/commerce/commerce-store-requirements.md b/rules/commerce/commerce-b2b-store-requirements.md similarity index 79% rename from rules/commerce/commerce-store-requirements.md rename to rules/commerce/commerce-b2b-store-requirements.md index 9ac56b1..86e4f66 100644 --- a/rules/commerce/commerce-store-requirements.md +++ b/rules/commerce/commerce-b2b-store-requirements.md @@ -1,12 +1,12 @@ --- -name: Commerce Store Creation Requirements -description: Critical workflow for creating B2B/B2C Commerce stores and storefronts - understand the distinction between Commerce Store (runtime data) and Storefront (LWR site). -tags: commerce, b2b, b2c, store, storefront, lwr, experience-cloud, rules, scom +name: Commerce B2B Store Creation Requirements +description: Critical workflow for creating B2B Commerce stores - understand Store vs Storefront distinction +tags: commerce, b2b, scom, scom b2b, commerce b2b, store, storefront, lwr, experience-cloud, rules --- ## ⚠️ CRITICAL: Commerce Store vs Storefront Distinction -When creating a Commerce B2B or B2C solution, you must understand the distinction between two separate but related components: +When creating a Commerce B2B solution, you must understand the distinction between two separate but related components: ### 1. Commerce Store (For Merchandisers) **What it is:** @@ -51,7 +51,7 @@ When creating a Commerce B2B or B2C solution, you must understand the distinctio ## 🚫 Common Mistake: Creating Storefront Metadata from Scratch -**DO NOT** attempt to manually create Commerce storefront metadata files (StorefrontName.digitalExperience-meta.xml, StorefrontName.digitalExperience-meta.xml) from scratch in your repository. +**DO NOT** attempt to manually create Commerce storefront metadata files (StorefrontName.digitalExperience-meta.xml) from scratch in your repository. **Why this fails:** - Commerce storefronts have complex dependencies on the Commerce Store data @@ -61,7 +61,28 @@ When creating a Commerce B2B or B2C solution, you must understand the distinctio --- -## ✅ Required Workflow for Creating Commerce B2B/B2C Sites +## Agent Guidance: Interactive Flow Requirements + +**When user asks to create Commerce storefront, agent MUST:** + +1. Follow the interactive flow from `prompts/commerce/create-retrieve-b2b-storefront.md` +2. Explain the Store vs Storefront concept first +3. Guide user to create B2B Store in org with clear steps +4. Get explicit confirmation that Store was created +5. Run `sf org list metadata --metadata-type DigitalExperienceConfig` to list available sites +6. Let user select from the list (don't assume store name) +7. Retrieve with: `sf project retrieve start -m DigitalExperienceBundle:site/` +8. Provide next steps with documentation links + +**What agents should NEVER do:** +- Create .digitalExperience-meta.xml files from scratch +- Skip the Store creation step +- Assume store name without listing/confirming +- Deploy without verifying Store exists in target org + +--- + +## ✅ Required Workflow for Creating Commerce B2B Sites ### Step 1: Create Commerce Store in the Org (MUST BE DONE FIRST) @@ -71,14 +92,12 @@ When creating a Commerce B2B or B2C solution, you must understand the distinctio 2. **Create New Store (via UI):** - Click "Create Store" or "Setup New Store" - - Choose store type: - - **B2B Store** - For business buyers with account hierarchies, buyer groups, negotiated pricing - - **B2C Store** - For individual consumers with guest checkout + - Choose store type: **B2B Store** - For business buyers with account hierarchies, buyer groups, negotiated pricing - Follow the store setup wizard 3. **Store Setup Wizard will create:** - WebStore record with unique name - - Default buyer group (B2B: associated with Accounts; B2C: AllBuyers) + - Default buyer group (associated with Accounts) - Default entitlement policies (who can see which products) - Default price book association - Default checkout flow configuration @@ -89,8 +108,7 @@ When creating a Commerce B2B or B2C solution, you must understand the distinctio - Tax provider (Avalara, Vertex, manual) - Shipping methods - Search settings - - Guest checkout (B2C) - - Account-based features (B2B) + - Account-based features 5. **Verify Store Creation:** - Setup → All Sites → Find your new Experience Cloud site @@ -103,13 +121,11 @@ After the Commerce Store is created in the org, retrieve the generated Experienc ```bash # List all Digital Experiences in your org -sf project retrieve start --metadata DigitalExperience - -# Or retrieve specific Experience by name -sf project retrieve start --metadata DigitalExperience:My_B2B_Store +sf org list metadata --metadata-type DigitalExperienceConfig # Retrieve the complete ExperienceBundle -sf project retrieve start --metadata ExperienceBundle:My_B2B_Store +# Note: Salesforce appends a number suffix (e.g., "My B2B Store" becomes "My_B2B_Store1") +sf project retrieve start -m DigitalExperienceBundle:site/My_B2B_Store1 ``` **What you'll get:** @@ -217,7 +233,7 @@ sf project deploy start --source-dir force-app/main/default/digitalExperiences/s When deploying your storefront to a new org: -- [ ] Target org has Commerce licenses (B2B Commerce or B2C Commerce) +- [ ] Target org has Commerce licenses (B2B Commerce) - [ ] Experience Cloud is enabled and domain configured - [ ] Commerce Store has been created in target org (via Commerce app UI) - [ ] WebStore name matches the Experience name in your metadata @@ -239,12 +255,7 @@ When deploying your storefront to a new org: - Configure negotiated pricing and entitlement policies - Set up account hierarchies -### For B2C Commerce: -- Configure guest checkout settings -- Set up customer registration flows -- Configure AllBuyers entitlement policy - -### For Both: +### General Setup: - Seed product catalog (Products, ProductCategory, ProductCatalog) - Create price books and price book entries - Configure inventory (ProductItem, LocationInventory) @@ -261,7 +272,7 @@ When deploying your storefront to a new org: 2. ✅ Instruct them to create the Commerce Store in their org first 3. ✅ Provide the Salesforce CLI retrieve commands 4. ✅ Optionally: Create custom LWCs for extending the retrieved storefront -5. ❌ DO NOT create StorefrontName.digitalExperience-meta.xml or StorefrontName.digitalExperience-meta.xml from scratch +5. ❌ DO NOT create StorefrontName.digitalExperience-meta.xml from scratch **Acceptable to create from scratch:** - Custom LWCs for storefront extensions (hero banners, promotions, custom product cards) @@ -281,7 +292,6 @@ When deploying your storefront to a new org: - Setup → Commerce → Stores - Commerce app from App Launcher → Create / Select App - Help Article: "Set Up a B2B Commerce Store" -- Help Article: "Set Up a B2C Commerce Store" **Storefront Customization:** - Experience Builder → Open your store site @@ -291,13 +301,17 @@ When deploying your storefront to a new org: **Metadata Retrieval:** ```bash # List all retrievable metadata types -sf org list metadata --metadata-type DigitalExperience -sf org list metadata --metadata-type ExperienceBundle +sf org list metadata --metadata-type DigitalExperienceConfig # Retrieve specific experience -sf project retrieve start --metadata ExperienceBundle:YourStoreName +sf project retrieve start -m DigitalExperienceBundle:site/YourStoreName ``` +**Documentation:** +- [DigitalExperienceBundle Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle.htm) +- [DigitalExperienceBundle Site](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle_site.htm) +- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_guide/) + --- ## 🎓 Key Takeaway