Deploy Salesforce Layout

Purpose

Deploy generated or modified layouts to Salesforce orgs with comprehensive pre-deployment validation, automatic backup creation, profile assignments, and post-deployment verification.

When to Use

✅ Use this command when:

• Deploying layouts generated by /design-layout
• Deploying layout modifications to sandbox or production
• Assigning layouts to specific profiles
• Rolling back failed layout deployments
• Verifying layout deployment success

❌ Do NOT use this command for:

• Generating layouts (use /design-layout instead)
• Analyzing existing layouts (use /analyze-layout instead)
• Deploying non-layout metadata (use standard sf project deploy instead)

Prerequisites

Required Access

• Salesforce CLI authenticated to target org
• Metadata API write permissions
• Profile/Permission Set management (for assignments)
• Target org accessible

Required Configuration

• Salesforce CLI installed (sf)
• Target org alias configured
• Layout files ready for deployment

Usage

Basic Deployment

/deploy-layout --source {path} --org {org-alias}

Dry-Run (Validation Only)

/deploy-layout --source {path} --org {org-alias} --dry-run

With Profile Assignments

/deploy-layout --source {path} --org {org-alias} --profiles "Sales User,Support User" --layout "Account-Sales Layout"

Backup Only

/deploy-layout --backup {object} --org {org-alias}

Rollback

/deploy-layout --rollback {backup-path} --org {org-alias}

Verify Deployment

/deploy-layout --verify {object} --org {org-alias}

Parameters

Required Parameters

• --org (REQUIRED): Salesforce CLI org alias
  • Must match authenticated org in sf org list

Source Selection (one required)

• --source: Path to layout source directory or file

  • Can be directory with multiple layouts
  • Can be single metadata file
  • Supports: FlexiPages, Layouts, CompactLayouts

• --backup: Object name to backup existing layouts

  • Creates timestamped backup before any changes

• --rollback: Path to backup directory to restore

  • Restores layouts from previous backup

• --verify: Object name to verify deployment

  • Queries org to confirm layouts exist

Optional Parameters

• --dry-run: Validate without deploying

  • Runs full validation
  • Shows what would be deployed
  • Does not make changes

• --check-only: Run check-only deployment

  • Validates deployment in org
  • Does not activate changes

• --profiles: Comma-separated profiles for assignment

  • Assigns deployed layout to these profiles
  • Use API names (e.g., "Sales User", not label)

• --record-types: Comma-separated record types

  • For record type-specific assignments
  • Format: Object.RecordTypeName

• --layout: Layout name for profile assignment

  • Required when using --profiles
  • Full layout name (e.g., "Account-Sales Account Layout")

• --ignore-warnings: Continue despite deployment warnings

  • Useful for minor issues

• --verbose: Show detailed output

  • Validation details
  • Deployment progress
  • Verification results

What This Command Does

Standard Deployment Flow

Step 1: Pre-Deployment Validation

• Validates XML syntax for all metadata files
• Checks required elements present
• Validates field references (where possible)
• Verifies API version compatibility

Step 2: Create Backup (Production)

• For production orgs, automatically creates backup
• Retrieves existing layouts for the affected objects
• Stores with timestamp for easy identification

Step 3: Deploy Metadata

• Uses sf project deploy start
• Monitors deployment progress
• Captures success/failure details

Step 4: Profile Assignments (if specified)

• Updates profile layout assignments
• Handles record type-specific assignments
• Deploys profile metadata updates

Step 5: Post-Deployment Verification

• Queries org for deployed metadata
• Confirms layouts exist and are active
• Reports verification results

Step 6: Display Results

• Shows deployment summary
• Lists any errors or warnings
• Provides rollback instructions if needed

Output Examples

Successful Deployment

/deploy-layout --source ./output/layouts --org my-sandbox --verbose

✓ Connected to: user@sandbox.company.com

🔍 Running pre-deployment validation...
✓ Pre-deployment validation passed
  📦 FlexiPages: 2
  📦 Layouts: 3
  📦 CompactLayouts: 2

📦 Creating backup at .backups/my-sandbox/Account_2025-12-12T14-30-00Z...
✓ Backup created successfully

🚀 Deploying to my-sandbox...
  Deploying: Account_Sales_FlexiPage.flexipage-meta.xml
  Deploying: Account_Sales_Layout.layout-meta.xml
  Deploying: Account_Sales_CompactLayout.compactLayout-meta.xml
✓ Deployment successful

🔍 Verifying deployment for Account...
  ✓ Found 3 FlexiPage(s)
  ✓ Found 2 CompactLayout(s)

📊 Summary:
  Total components: 7
  Deployed successfully: 7
  Errors: 0
  Warnings: 0

✓ Deployment complete

Dry-Run Output

/deploy-layout --source ./output/layouts --org my-sandbox --dry-run

✓ Connected to: user@sandbox.company.com

🔍 Running pre-deployment validation...
✓ Pre-deployment validation passed
  📦 FlexiPages: 2
  📦 Layouts: 3
  📦 CompactLayouts: 2

🔎 Dry-run mode - Skipping actual deployment

Would deploy:
  1. Account_Sales_FlexiPage.flexipage-meta.xml
  2. Account_Sales_Layout.layout-meta.xml
  3. Account_Sales_CompactLayout.compactLayout-meta.xml
  4. Contact_Sales_FlexiPage.flexipage-meta.xml
  5. Contact_Sales_Layout.layout-meta.xml
  6. Contact_Sales_CompactLayout.compactLayout-meta.xml
  7. Opportunity_Sales_FlexiPage.flexipage-meta.xml

✓ Validation passed - safe to deploy

Failed Validation

/deploy-layout --source ./output/layouts --org my-sandbox

✓ Connected to: user@sandbox.company.com

🔍 Running pre-deployment validation...
✗ Pre-deployment validation failed
  ❌ FlexiPage Account_Record_Page.flexipage-meta.xml: Missing masterLabel
  ❌ CompactLayout Contact_Compact.compactLayout-meta.xml: Exceeds 10 field limit (12 fields)
  ⚠️  Layout Opportunity_Layout.layout-meta.xml: API version 55.0 is outdated

📊 Result: ✗ Failed
  Cannot proceed with deployment until validation errors are fixed

💡 Suggestions:
  1. Add <masterLabel> to Account_Record_Page.flexipage-meta.xml
  2. Reduce fields in Contact_Compact to 10 or fewer
  3. Update API versions to 62.0

With Profile Assignments

/deploy-layout --source ./output/layouts --org my-sandbox \
  --profiles "Sales User,Sales Manager" \
  --layout "Account-Sales Account Layout"

✓ Connected to: user@sandbox.company.com

🔍 Running pre-deployment validation...
✓ Pre-deployment validation passed

🚀 Deploying to my-sandbox...
✓ Deployment successful

📝 Updating profile assignments...
  ✓ Updated Sales User → Account-Sales Account Layout
  ✓ Updated Sales Manager → Account-Sales Account Layout

🔍 Verifying deployment...
  ✓ Layouts deployed
  ✓ Profile assignments updated

✓ Complete

Example Workflows

Workflow 1: Full Layout Deployment Pipeline

# Step 1: Generate layout
/design-layout --object Account --persona sales-rep --org my-sandbox

# Step 2: Review generated files
ls instances/my-sandbox/generated-layouts/latest/

# Step 3: Dry-run deployment
/deploy-layout --source instances/my-sandbox/generated-layouts/latest/ \
  --org my-sandbox --dry-run

# Step 4: Deploy to sandbox
/deploy-layout --source instances/my-sandbox/generated-layouts/latest/ \
  --org my-sandbox

# Step 5: Verify deployment
/deploy-layout --verify Account --org my-sandbox

# Step 6: Analyze deployed layout
/analyze-layout --object Account --org my-sandbox

Workflow 2: Production Deployment with Rollback Plan

# Step 1: Create backup
/deploy-layout --backup Account --org production

# Step 2: Deploy with check-only first
/deploy-layout --source ./layouts/ --org production --check-only

# Step 3: Full deployment
/deploy-layout --source ./layouts/ --org production

# Step 4: Verify
/deploy-layout --verify Account --org production

# If issues found - Rollback:
/deploy-layout --rollback .backups/production/Account_2025-12-12T10-00-00Z \
  --org production

Workflow 3: Profile-Based Layout Assignment

# Generate different layouts for different personas
/design-layout --object Opportunity --persona sales-rep --org sandbox
/design-layout --object Opportunity --persona sales-manager --org sandbox

# Deploy sales rep layout and assign
/deploy-layout --source ./output/sales-rep/ --org sandbox \
  --profiles "Sales User" \
  --layout "Opportunity-Sales Rep Layout"

# Deploy manager layout and assign
/deploy-layout --source ./output/sales-manager/ --org sandbox \
  --profiles "Sales Manager" \
  --layout "Opportunity-Sales Manager Layout"

Common Errors and Solutions

Error: "Field does not exist"

Cause: Layout references a field that doesn't exist in target org

Solution:

1. Create the missing field in target org first
2. Or remove the field reference from the layout
3. Or deploy to org with the field

Error: "Profile not found"

Cause: Profile name doesn't match target org

Solution:

1. Use API name, not label
2. Verify profile exists in target org
3. Check spelling (case-sensitive)

Error: "Invalid component"

Cause: Component requires feature not available in org

Solution:

1. Enable required feature (e.g., Path requires Sales Cloud)
2. Remove component from layout
3. Deploy to org with feature enabled

Error: "EACCES: permission denied"

Cause: Cannot write to backup or temp directory

Solution:

1. Check directory permissions
2. Run with appropriate user
3. Use --verbose to see exact path

Rollback Procedure

If deployment fails or causes issues:

Step 1: Identify Available Backups

node scripts/lib/layout-deployer.js <org> history

Step 2: Select Backup to Restore

Choose the backup from before the problematic deployment

Step 3: Execute Rollback

/deploy-layout --rollback .backups/<org>/<backup-name> --org <org>

Step 4: Verify Rollback

/deploy-layout --verify <object> --org <org>

Best Practices

Before Deployment

1. Always dry-run first - Use --dry-run to validate
2. Create backup for production - Automatic for prod, manual for sandbox
3. Test in sandbox first - Never deploy directly to production
4. Review generated files - Verify layout contents before deployment

During Deployment

1. Monitor progress - Watch for errors during deployment
2. Check warnings - Even successful deployments may have warnings
3. Verify completion - Don't assume success without confirmation

After Deployment

1. Run verification - Use --verify to confirm deployment
2. Test with users - Have actual users validate the layout
3. Check profile assignments - Verify correct profiles are assigned
4. Document changes - Record what was deployed and why

Integration with Skills

This command integrates with layout skills for enhanced capabilities:

Layout CLI Reference

skill: layout-cli-api-reference

• Detailed CLI command patterns
• Profile assignment management
• Error recovery procedures

Layout Planning Guide

skill: layout-planning-guide

• Persona selection guidance
• Object-specific recommendations
• Dynamic Forms decision tree

---

Agent Execution Instructions

When this command is invoked, delegate to the sfdc-layout-deployer agent:

Task: Invoke sfdc-layout-deployer agent with parameters:
  - Source: {source path or backup/rollback/verify target}
  - Org: {org-alias}
  - Action: {deploy | backup | rollback | verify}
  - Dry-Run: {dry-run flag}
  - Check-Only: {check-only flag}
  - Profiles: {profiles list}
  - Record Types: {record-types list}
  - Layout Name: {layout name for assignment}
  - Verbose: {verbose flag}

Expected Deliverables:
  1. Pre-deployment validation results
  2. Backup confirmation (if applicable)
  3. Deployment status and results
  4. Profile assignment confirmation (if applicable)
  5. Post-deployment verification results

Success Criteria:
  - Validation passes
  - Deployment succeeds
  - Verification confirms deployment
  - No unresolved errors

---

Command Version: 1.0.0 Last Updated: 2025-12-12 Part of: salesforce-plugin (Layout Designer Phase 3)