@salesforce/afv-skills 1.24.0 → 1.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/package.json +1 -1
  2. package/skills/commerce-b2b-open-code-components-replace/SKILL.md +244 -0
  3. package/skills/commerce-b2b-open-code-components-replace/assets/ootb-to-open-code-mapping.json +66 -0
  4. package/skills/dx-org-manage/SKILL.md +192 -0
  5. package/skills/dx-org-manage/examples/README.md +45 -0
  6. package/skills/dx-org-manage/examples/scratch-orgs/error_no_devhub.json +9 -0
  7. package/skills/dx-org-manage/examples/scratch-orgs/error_timeout.json +13 -0
  8. package/skills/dx-org-manage/examples/scratch-orgs/success_definition_file.json +28 -0
  9. package/skills/dx-org-manage/examples/scratch-orgs/success_edition.json +26 -0
  10. package/skills/dx-org-manage/examples/scratch-orgs/success_snapshot.json +27 -0
  11. package/skills/dx-org-manage/examples/snapshots/error_output.json +9 -0
  12. package/skills/dx-org-manage/examples/snapshots/success_output.json +15 -0
  13. package/skills/dx-org-manage/references/cli_flags.md +67 -0
  14. package/skills/dx-org-manage/references/creating-scratch-org.md +164 -0
  15. package/skills/dx-org-manage/references/creating-snapshot.md +103 -0
  16. package/skills/dx-org-manage/references/definition_file_options.md +224 -0
  17. package/skills/dx-org-manage/references/edition_types.md +78 -0
  18. package/skills/dx-org-manage/references/opening-org.md +160 -0
  19. package/skills/dx-org-manage/references/snapshot_usage.md +74 -0
  20. package/skills/dx-org-permission-set-assign/SKILL.md +98 -0
  21. package/skills/dx-org-permission-set-assign/examples/error_output.json +19 -0
  22. package/skills/dx-org-permission-set-assign/examples/success_output.json +16 -0
  23. package/skills/dx-org-permission-set-assign/references/cli_flags.md +68 -0
  24. package/skills/experience-cms-brand-apply/SKILL.md +1 -1
  25. package/skills/experience-ui-bundle-app-coordinate/SKILL.md +31 -19
  26. package/skills/experience-ui-bundle-file-upload-generate/SKILL.md +1 -1
  27. package/skills/experience-ui-bundle-frontend-generate/implementation/header-footer.md +1 -1
  28. package/skills/experience-ui-bundle-salesforce-data-access/SKILL.md +336 -581
  29. package/skills/experience-ui-bundle-salesforce-data-access/references/caching.md +172 -0
  30. package/skills/experience-ui-bundle-salesforce-data-access/references/graphiti-cli.md +373 -0
  31. package/skills/experience-ui-bundle-salesforce-data-access/references/graphql-hand-authoring.md +376 -0
  32. package/skills/experience-ui-bundle-salesforce-data-access/references/migration.md +119 -0
  33. package/skills/experience-ui-bundle-salesforce-data-access/references/rest-and-integration.md +152 -0
  34. package/skills/experience-ui-bundle-salesforce-data-access/references/sdk-api.md +217 -0
  35. package/skills/experience-ui-bundle-salesforce-data-access/scripts/graphql-search.sh +36 -9
  36. package/skills/platform-agentsetup-categories-fetch/SKILL.md +109 -0
  37. package/skills/platform-agentsetup-categories-fetch/references/api-response-schema.md +121 -0
  38. package/skills/platform-custom-object-generate/SKILL.md +62 -7
  39. package/skills/platform-custom-object-generate/references/description-enrichment.md +125 -0
  40. package/skills/platform-metadata-retrieve/SKILL.md +121 -0
  41. package/skills/platform-metadata-retrieve/examples/error_output.json +10 -0
  42. package/skills/platform-metadata-retrieve/examples/success_output.json +27 -0
  43. package/skills/platform-metadata-retrieve/references/cli_flags.md +138 -0
  44. package/skills/platform-metadata-retrieve/references/retrieval_modes.md +181 -0
  45. package/skills/platform-sharing-rules-generate/SKILL.md +165 -0
  46. package/skills/platform-sharing-rules-generate/references/rule-types.md +199 -0
  47. package/skills/platform-tracing-agentforce-configure/SKILL.md +118 -0
  48. package/skills/platform-tracing-agentforce-configure/assets/AgentforcePlatformTracing-template.xml +4 -0
  49. package/skills/platform-tracing-configure/SKILL.md +118 -0
  50. package/skills/platform-tracing-configure/assets/EventSettings-template.xml +4 -0
  51. package/skills/platform-trust-archive-manage/SKILL.md +25 -11
  52. package/skills/platform-trust-archive-manage/examples/monitor-failed-jobs.md +2 -2
  53. package/skills/platform-trust-archive-manage/references/archive-activity-entity.md +1 -1
  54. package/skills/platform-trust-archive-manage/references/connect-api-operations.md +51 -12
@@ -0,0 +1,27 @@
1
+ {
2
+ "status": 0,
3
+ "result": {
4
+ "username": "test-snap9012@example.com",
5
+ "orgId": "00D5g00000aDEF3EAM",
6
+ "scratchOrgInfo": {
7
+ "Id": "2SR5g000000EfGhIJK",
8
+ "Edition": "Developer",
9
+ "Status": "Active",
10
+ "SignupUsername": "test-snap9012@example.com",
11
+ "AdminEmail": "dev@example.com",
12
+ "Namespace": null,
13
+ "OrgName": "Company",
14
+ "ScratchOrg": "00D5g00000aDEF3EAM",
15
+ "SnapshotName": "MySnapshot",
16
+ "CreatedDate": "2026-06-12T15:20:00.000+0000",
17
+ "ExpirationDate": "2026-06-19"
18
+ },
19
+ "authFields": {
20
+ "accessToken": "00D5g...",
21
+ "instanceUrl": "https://...-dev-ed.develop.my.salesforce.com",
22
+ "username": "test-snap9012@example.com",
23
+ "orgId": "00D5g00000aDEF3EAM"
24
+ },
25
+ "warnings": []
26
+ }
27
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "status": 1,
3
+ "name": "NOT_FOUND",
4
+ "message": "Org snapshots are not enabled in this org. Contact Salesforce to enable org snapshots.",
5
+ "exitCode": 1,
6
+ "commandName": "SnapshotCreate",
7
+ "stack": "NOT_FOUND: Org snapshots are not enabled in this org...",
8
+ "warnings": []
9
+ }
@@ -0,0 +1,15 @@
1
+ {
2
+ "status": 0,
3
+ "result": {
4
+ "Id": "0Oo5g00000001ABCAA",
5
+ "Status": "Pending",
6
+ "SourceOrg": "00D5g00000001XyEAI",
7
+ "SnapshotName": "MySnapshot",
8
+ "Description": "Baseline configuration with Package v1.2.0",
9
+ "Content": "metadatadata",
10
+ "CreatedDate": "2026-06-04T20:00:00.000+0000",
11
+ "CreatedBy": "0055g00000001UserEAA",
12
+ "LastModifiedDate": "2026-06-04T20:00:00.000+0000",
13
+ "LastModifiedBy": "0055g00000001UserEAA"
14
+ }
15
+ }
@@ -0,0 +1,67 @@
1
+ # CLI Flags Reference
2
+
3
+ Complete reference for `sf org create snapshot` command flags.
4
+
5
+ ## Required Flags
6
+
7
+ | Flag | Alias | Description | Example |
8
+ |------|-------|-------------|---------|
9
+ | `--source-org` | `-o` | ID or authenticated username/alias of scratch org to snapshot | `--source-org my-scratch` |
10
+ | `--name` | `-n` | Unique name for the snapshot | `--name MySnapshot` |
11
+ | `--target-dev-hub` | `-v` | Dev Hub org username or alias (required unless default is set) | `--target-dev-hub DevHub` |
12
+
13
+ ## Optional Flags
14
+
15
+ | Flag | Alias | Description | Example |
16
+ |------|-------|-------------|---------|
17
+ | `--description` | `-d` | Description of snapshot contents | `--description "Package v1.2.0"` |
18
+ | `--api-version` | | Override the API version used for API requests | `--api-version 66.0` |
19
+
20
+ ## Global Flags
21
+
22
+ | Flag | Description |
23
+ |------|-------------|
24
+ | `--json` | Format output as JSON (ALWAYS use this) |
25
+
26
+ ## Usage Patterns
27
+
28
+ ### Basic Snapshot Creation
29
+
30
+ ```bash
31
+ sf org create snapshot --source-org my-scratch --name MySnapshot --json
32
+ ```
33
+
34
+ ### With Description
35
+
36
+ ```bash
37
+ sf org create snapshot \
38
+ --source-org my-scratch \
39
+ --name MySnapshot \
40
+ --description "Baseline with Package v1.2.0" \
41
+ --json
42
+ ```
43
+
44
+ ### Using Org ID Instead of Alias
45
+
46
+ ```bash
47
+ sf org create snapshot \
48
+ --source-org 00D5g00000001XyEAI \
49
+ --name MySnapshot \
50
+ --json
51
+ ```
52
+
53
+ ### Specify Dev Hub Explicitly
54
+
55
+ ```bash
56
+ sf org create snapshot \
57
+ --source-org my-scratch \
58
+ --name MySnapshot \
59
+ --target-dev-hub MyDevHub \
60
+ --json
61
+ ```
62
+
63
+ ## Important Notes
64
+
65
+ - **Source org auto-resolution**: Accepts org ID (starts with 00D) or username/alias — aliases are automatically resolved to org IDs
66
+ - **Description best practice**: Include version control reference (git tag, commit SHA) to track snapshot contents
67
+ - **Asynchronous creation**: Snapshot creation happens asynchronously — use `sf org get snapshot` to check status
@@ -0,0 +1,164 @@
1
+ # Creating Scratch Orgs
2
+
3
+ Detailed workflow for creating Salesforce scratch orgs using `sf org create scratch`. Supports four creation methods: definition file, edition flag, snapshot, and org shape.
4
+
5
+ ---
6
+
7
+ ## Required Inputs
8
+
9
+ Gather or infer before proceeding:
10
+
11
+ - **Dev Hub org**: Username or alias of authenticated Dev Hub (or use default from `target-dev-hub` config)
12
+ - **Creation method**: Which approach to use (see Workflow step 1)
13
+ - **Alias**: Optional but recommended for easy reference
14
+
15
+ Optional but commonly used:
16
+ - **Duration**: Days before org expires (default: 7, max: 30)
17
+ - **Set as default**: Whether to make this the default org
18
+ - **Source tracking**: Whether to enable (default: yes, disable for CI/CD performance)
19
+
20
+ ---
21
+
22
+ ## Workflow
23
+
24
+ ### 1. Identify creation method
25
+
26
+ Determine which approach based on user request:
27
+
28
+ | Method | When to use | Required flags |
29
+ |--------|-------------|----------------|
30
+ | Definition file | User provides config file or needs org features/settings | `--definition-file <path>` |
31
+ | Edition only | Quick simple org, no special config needed | `--edition <edition>` |
32
+ | Snapshot | Clone from existing snapshot | `--snapshot <name>` |
33
+ | Org shape | Mimic another org's structure | `--source-org <id>` |
34
+
35
+ **Mutually exclusive**: `--edition`, `--snapshot`, and `--source-org` cannot be combined.
36
+
37
+ ### 2. Verify Dev Hub authentication
38
+
39
+ Check if Dev Hub is authenticated:
40
+ - If `--target-dev-hub` not provided, check `sf config get target-dev-hub`
41
+ - If no Dev Hub configured, prompt user to authenticate: `sf org login web --set-default-dev-hub`
42
+
43
+ ### 3. Build the command
44
+
45
+ Construct based on creation method:
46
+
47
+ **Definition file approach:**
48
+ ```bash
49
+ sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json
50
+ ```
51
+
52
+ **Edition-only approach:**
53
+ ```bash
54
+ sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json
55
+ ```
56
+
57
+ **Snapshot approach:**
58
+ ```bash
59
+ sf org create scratch --snapshot <name> --target-dev-hub <alias> --alias <name> --json
60
+ ```
61
+
62
+ **Org shape approach:**
63
+ ```bash
64
+ sf org create scratch --source-org <id> --target-dev-hub <alias> --alias <name> --json
65
+ ```
66
+
67
+ **Common optional flags:**
68
+ - `--duration-days <days>` — Set expiration (default 7, max 30)
69
+ - `--set-default` — Make this the default org
70
+ - `--no-track-source` — Disable source tracking for CI/CD performance
71
+ - `--wait <minutes>` — Wait for completion (default 5 minutes, min 2)
72
+ - `--async` — Return immediately, don't wait for completion
73
+
74
+ **⚠️ CRITICAL: This is a BLOCKING command**
75
+ - The command **WAITS** until the scratch org is fully created (or times out)
76
+ - When the command returns success, the org is **READY TO USE** — do NOT poll with `sf org list` waiting for it to become ready
77
+ - The JSON response with `username` and `orgId` means creation is **COMPLETE**
78
+ - Only use `--async` if you want to check status later with `sf org resume scratch`
79
+ - **Note**: SKILL.md Step 4 requires running `sf org list --json` once after creation for artifact collection (not for polling status)
80
+
81
+ **Before executing, verify:**
82
+ - [ ] `--json` flag is present in the command
83
+ - [ ] At least ONE of `--edition`, `--snapshot`, `--source-org`, or `--definition-file` is specified (flags can override definition file values)
84
+ - [ ] `--snapshot` and `--source-org` are not combined (mutually exclusive)
85
+ - [ ] `--target-dev-hub` is resolved (either in command or from config)
86
+
87
+ ### 4. Handle async creation
88
+
89
+ If `--async` or `--wait` timeout occurs:
90
+ - CLI displays: "The scratch org did not complete within your wait time."
91
+ - CLI automatically shows the resume command with Request ID
92
+ - Timeout exits with code 69
93
+ - User can resume with the displayed command: `sf org resume scratch --job-id <request-id> --json`
94
+
95
+ ### 5. Report result
96
+
97
+ When the command returns, check JSON response. If it contains `username` and `orgId`, the org is **COMPLETE and READY**. Do NOT run additional commands to verify completion.
98
+
99
+ Successful creation returns:
100
+ ```json
101
+ {
102
+ "username": "test-...@example.com",
103
+ "orgId": "00D...",
104
+ "scratchOrgInfo": {
105
+ "Id": "2SR...",
106
+ "ScratchOrg": "00D...",
107
+ "SignupUsername": "test-...@example.com"
108
+ }
109
+ }
110
+ ```
111
+
112
+ This JSON response means: org is created, authenticated, and ready for `sf org open`, `sf project deploy`, or any other commands.
113
+
114
+ ---
115
+
116
+ ## Rules / Constraints
117
+
118
+ | Constraint | Rationale |
119
+ |-----------|-----------|
120
+ | Always include `--json` flag | Returns structured output for parsing success/failure |
121
+ | **Command blocks until completion — do NOT poll for status** | The command waits until the org is created (or times out). When it returns with `username` and `orgId` in JSON, the org is ready. Do NOT poll repeatedly with `sf org list` waiting for it to become ready — the command already waited for you. Only exception: if using `--async` flag or command timed out (exit code 69), then use `sf org resume scratch` to check status. **Note**: SKILL.md Step 4 requires a single `sf org list --json` call after creation for artifact collection (not polling) |
122
+ | Dev Hub must be authenticated | Scratch org creation requires Dev Hub access |
123
+ | `--edition`, `--snapshot`, `--source-org` are mutually exclusive | Only one creation source allowed per command |
124
+ | Definition file overrides can use flags | Flags like `--edition`, `--name`, `--username`, `--release`, `--admin-email` override definition file values |
125
+ | Snapshot requires same Dev Hub | Snapshot must be created in the same Dev Hub you're using |
126
+ | Duration max is 30 days | Platform limit for scratch org expiration |
127
+ | Source tracking enabled by default | Disable with `--no-track-source` only for CI/CD or performance needs |
128
+
129
+ ---
130
+
131
+ ## Troubleshooting
132
+
133
+ | Issue | Resolution |
134
+ |-------|------------|
135
+ | `No default Dev Hub org found` | Authenticate Dev Hub with `sf org login web --set-default-dev-hub` or specify `--target-dev-hub` |
136
+ | `NamedOrgNotFoundError` on Dev Hub | Dev Hub org is not authenticated — run `sf org login web` |
137
+ | `edition value must be one of` | Invalid edition specified — use developer, enterprise, group, professional, or partner variants |
138
+ | `Snapshot not found` | Snapshot doesn't exist in this Dev Hub — run `sf org list snapshot` to see available |
139
+ | `sourceOrg value must be 15 or 18 characters` | Org shape ID format incorrect — use output from `sf org list shape` |
140
+ | `The org could not be created` | Generic creation failure — check Dev Hub limits, licensing, or try again |
141
+ | Timeout during creation (exit code 69) | Command timed out waiting for org. CLI displays the resume command with Request ID. User can run the displayed command or increase `--wait` time (min 2 minutes) for next attempt |
142
+ | `Definition file not found` | Path to definition file is incorrect — verify file exists |
143
+ | Partner editions unavailable | Partner editions only work if Dev Hub is a Partner Business Org |
144
+
145
+ ---
146
+
147
+ ## Output Expectations
148
+
149
+ Deliverables:
150
+ - **Created scratch org**: Authenticated and ready to use
151
+ - **JSON response**: Contains `username`, `orgId`, `scratchOrgInfo` with Request ID
152
+ - **Local auth info**: Stored in `.sf/` directory for future CLI commands
153
+
154
+ If `--async` used or timeout occurs:
155
+ - **Request ID**: Returned in `scratchOrgInfo.Id` (format: `2SR...`)
156
+ - **Resume command**: `sf org resume scratch --job-id <request-id> --json`
157
+ - **Timeout exit code**: 69
158
+
159
+ ---
160
+
161
+ ## Additional Resources
162
+
163
+ - See `definition_file_options.md` for org features, settings, and configuration templates
164
+ - See `edition_types.md` for available edition types and when to use each
@@ -0,0 +1,103 @@
1
+ # Creating Snapshots
2
+
3
+ Creates a point-in-time snapshot of a scratch org using `sf org create snapshot`. Snapshots preserve scratch org state and configuration for reuse in scratch org definition files.
4
+
5
+ ---
6
+
7
+ ## Required Inputs
8
+
9
+ Infer from the user's request:
10
+
11
+ - **Source org**: Scratch org ID (starts with 00D) or username/alias to snapshot
12
+ - **Snapshot name**: Unique name for the snapshot (required)
13
+ - **Dev Hub**: Dev Hub org alias/username (uses default if not specified)
14
+ - **Description** (optional): Document snapshot contents, version control reference
15
+
16
+ ---
17
+
18
+ ## Workflow
19
+
20
+ 1. **Gather inputs** — get source org, snapshot name, and optional description
21
+ 2. **Build command** — construct `sf org create snapshot` with appropriate flags
22
+ 3. **Execute via Bash tool** — run command with `--json` flag
23
+ 4. **Return result** — report snapshot ID and status
24
+
25
+ ### Command Patterns
26
+
27
+ | User intent | Execute via Bash tool |
28
+ |-------------|---------|
29
+ | Create snapshot with name only | `sf org create snapshot --source-org <orgId or alias> --name <SnapshotName> --json` |
30
+ | Create snapshot with description | `sf org create snapshot --source-org <orgId or alias> --name <SnapshotName> --description "<desc>" --json` |
31
+ | Specify Dev Hub explicitly | `sf org create snapshot --source-org <orgId or alias> --name <SnapshotName> --target-dev-hub <devHubAlias> --json` |
32
+
33
+ ---
34
+
35
+ ## Rules / Constraints
36
+
37
+ | Constraint | Rationale |
38
+ |-----------|-----------|
39
+ | Always use `--json` flag | Provides structured output for reliable parsing and error handling |
40
+ | Snapshot names must be unique in the Dev Hub | Duplicate names cause creation to fail |
41
+ | Source org must be a scratch org | Snapshots only work with scratch orgs, not sandboxes or production orgs |
42
+ | Dev Hub must have snapshot feature enabled | "NOT_FOUND" error means Dev Hub doesn't support snapshots |
43
+ | Source org accepts ID or username/alias | Command auto-resolves aliases to org IDs; org IDs start with 00D |
44
+ | Include description for tracking | Best practice: reference version control tag or commit ID in description |
45
+
46
+ ---
47
+
48
+ ## Troubleshooting
49
+
50
+ | Issue | Resolution |
51
+ |-------|------------|
52
+ | "NOT_FOUND" error when creating snapshot | Dev Hub doesn't have snapshot feature enabled — contact admin to enable in Dev Hub settings |
53
+ | "No org found for <alias>" error | Source org alias doesn't exist or isn't authenticated — verify with `sf org list` |
54
+ | Snapshot name already exists | Use a different unique name — snapshot names must be unique per Dev Hub |
55
+ | "An error while created the org snapshot" | Generic error — check that source org is a scratch org and still active |
56
+ | Long-running snapshot creation | Use `sf org get snapshot --snapshot <name>` to check status — snapshot creation is asynchronous |
57
+
58
+ ---
59
+
60
+ ## Output Expectations
61
+
62
+ The command returns JSON output with the created snapshot details.
63
+
64
+ See `examples/snapshots/success_output.json` and `examples/snapshots/error_output.json` for complete response structures.
65
+
66
+ Example success response:
67
+ ```json
68
+ {
69
+ "result": {
70
+ "SnapshotId": "0Ym...",
71
+ "SnapshotName": "MySnapshot",
72
+ "Status": "Active",
73
+ "SourceOrg": "00D..."
74
+ }
75
+ }
76
+ ```
77
+
78
+ ---
79
+
80
+ ## Using Snapshots
81
+
82
+ After creating a snapshot, use it to create scratch orgs by:
83
+
84
+ 1. **In scratch org definition file:**
85
+ ```json
86
+ {
87
+ "snapshot": "MySnapshot"
88
+ }
89
+ ```
90
+
91
+ 2. **Or via command flag:**
92
+ ```bash
93
+ sf org create scratch --snapshot MySnapshot --target-dev-hub <alias> --alias <name> --json
94
+ ```
95
+
96
+ See `snapshot_usage.md` for detailed examples.
97
+
98
+ ---
99
+
100
+ ## Additional Resources
101
+
102
+ - See `cli_flags.md` for detailed explanation of all available flags
103
+ - See `snapshot_usage.md` for how to use snapshots in scratch org creation
@@ -0,0 +1,224 @@
1
+ # Scratch Org Definition File Options
2
+
3
+ Complete reference for scratch org definition file configuration. Use this when users need to configure org features, settings, or advanced options beyond basic org creation.
4
+
5
+ ## File Structure
6
+
7
+ ```json
8
+ {
9
+ "orgName": "My Company",
10
+ "edition": "Developer",
11
+ "features": ["<feature>", "<feature>"],
12
+ "settings": {
13
+ "<SettingType>": {
14
+ "<settingName>": <value>
15
+ }
16
+ },
17
+ "adminEmail": "admin@example.com",
18
+ "description": "Scratch org for feature X development",
19
+ "hasSampleData": false,
20
+ "snapshot": "SnapshotName",
21
+ "sourceOrg": "00D1234567890ABC",
22
+ "username": "custom.username@example.com"
23
+ }
24
+ ```
25
+
26
+ ## Core Fields
27
+
28
+ | Field | Type | Required | Description |
29
+ |-------|------|----------|-------------|
30
+ | `orgName` | string | Yes | Name of the company (user-visible) |
31
+ | `edition` | string | Yes* | Developer, Enterprise, Group, Professional, or Partner variants |
32
+ | `adminEmail` | string | No | Email for the admin user |
33
+ | `description` | string | No | Description shown in Dev Hub |
34
+ | `hasSampleData` | boolean | No | Include standard sample data (default: false) |
35
+ | `username` | string | No | Custom username for admin (must be globally unique) |
36
+
37
+ \* Not required if using `snapshot` or `sourceOrg`.
38
+
39
+ **CLI Flag Overrides:** When using a definition file with `--definition-file`, you can override any of these fields with CLI flags:
40
+ - `--edition` overrides `edition`
41
+ - `--name` overrides `orgName`
42
+ - `--username` overrides `username`
43
+ - `--description` overrides `description`
44
+ - `--admin-email` overrides `adminEmail`
45
+ - `--release` overrides `release`
46
+ - `--snapshot` overrides `snapshot`
47
+ - `--source-org` overrides `sourceOrg`
48
+
49
+ CLI flags take precedence over definition file values.
50
+
51
+ ## Features Array
52
+
53
+ Enable org features by adding to `features` array. Common features:
54
+
55
+ ```json
56
+ "features": [
57
+ "Communities",
58
+ "ServiceCloud",
59
+ "Sites",
60
+ "MultiCurrency",
61
+ "PersonAccounts",
62
+ "Walkthroughs",
63
+ "AdvancedPersonAccountSecurity"
64
+ ]
65
+ ```
66
+
67
+ **Finding available features:**
68
+ - Run: `sf org list metadata-types --target-org <dev-hub>`
69
+ - Look for `FeatureParameterValueSet` type
70
+ - Or check: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file.htm
71
+
72
+ ## Settings Object
73
+
74
+ Configure org settings by type. Format:
75
+
76
+ ```json
77
+ "settings": {
78
+ "lightningExperienceSettings": {
79
+ "enableS1DesktopEnabled": true
80
+ },
81
+ "mobileSettings": {
82
+ "enableS1EncryptedStoragePref2": false
83
+ },
84
+ "securitySettings": {
85
+ "passwordPolicies": {
86
+ "minimumPasswordLength": 10
87
+ }
88
+ }
89
+ }
90
+ ```
91
+
92
+ **Common settings:**
93
+
94
+ ### Language Settings
95
+ ```json
96
+ "languageSettings": {
97
+ "enableTranslationWorkbench": true
98
+ }
99
+ ```
100
+
101
+ ### Chatter Settings
102
+ ```json
103
+ "chatterSettings": {
104
+ "enableChatter": true
105
+ }
106
+ ```
107
+
108
+ ### Path Settings
109
+ ```json
110
+ "pathAssistantSettings": {
111
+ "pathAssistantEnabled": true
112
+ }
113
+ ```
114
+
115
+ ## Alternative Creation Sources
116
+
117
+ ### Snapshot
118
+ ```json
119
+ {
120
+ "snapshot": "BaselineSnapshot"
121
+ }
122
+ ```
123
+
124
+ Creates org from a snapshot. The `edition` field is optional when using snapshots.
125
+
126
+ ### Source Org (Org Shape)
127
+ ```json
128
+ {
129
+ "sourceOrg": "00D1234567890ABC"
130
+ }
131
+ ```
132
+
133
+ Creates org from an org shape. The `edition` field is optional when using org shapes.
134
+
135
+ **Note:** `snapshot` and `sourceOrg` are mutually exclusive.
136
+
137
+ ## Release Overrides
138
+
139
+ Control which Salesforce release the scratch org uses:
140
+
141
+ ```json
142
+ {
143
+ "release": "preview"
144
+ }
145
+ ```
146
+
147
+ Options: `preview` (next release), `previous` (previous release). Only use during Salesforce release transition periods.
148
+
149
+ ## Duration Control
150
+
151
+ While not part of the definition file, you can override duration with the CLI flag:
152
+ ```bash
153
+ --duration-days 15
154
+ ```
155
+
156
+ Maximum: 30 days. Default: 7 days.
157
+
158
+ ## Packaging Options
159
+
160
+ ```json
161
+ {
162
+ "ancestorId": "04t...",
163
+ "ancestorVersion": "1.0",
164
+ "namespace": "myns"
165
+ }
166
+ ```
167
+
168
+ Used for second-generation package (2GP) development.
169
+
170
+ **CLI Packaging Flags:**
171
+ - `--no-ancestors` - Exclude 2GP ancestors from the scratch org
172
+ - `--no-namespace` - Create scratch org without namespace, even if Dev Hub has one
173
+
174
+ ## Example: Full Configuration
175
+
176
+ ```json
177
+ {
178
+ "orgName": "Acme Corp Dev Org",
179
+ "edition": "Developer",
180
+ "description": "Feature X development scratch org",
181
+ "adminEmail": "dev-team@acme.com",
182
+ "hasSampleData": false,
183
+ "features": [
184
+ "Communities",
185
+ "ServiceCloud",
186
+ "MultiCurrency"
187
+ ],
188
+ "settings": {
189
+ "lightningExperienceSettings": {
190
+ "enableS1DesktopEnabled": true
191
+ },
192
+ "securitySettings": {
193
+ "passwordPolicies": {
194
+ "minimumPasswordLength": 10,
195
+ "minimumPasswordLifetime": false,
196
+ "obscure": false
197
+ }
198
+ },
199
+ "languageSettings": {
200
+ "enableTranslationWorkbench": true
201
+ }
202
+ }
203
+ }
204
+ ```
205
+
206
+ ## Connected App Authentication
207
+
208
+ For enhanced security, use a Connected App for authentication:
209
+
210
+ ```bash
211
+ sf org create scratch --definition-file config.json --client-id <consumer-key>
212
+ ```
213
+
214
+ When `--client-id` is provided, CLI prompts for the client secret. The scratch org will use the Connected App for authentication instead of default JWT.
215
+
216
+ ## Common Pitfalls
217
+
218
+ | Issue | Cause | Fix |
219
+ |-------|-------|-----|
220
+ | Features not available | Feature name spelled wrong or not available in edition | Check feature name spelling and edition compatibility |
221
+ | Settings ignored | Invalid setting name or structure | Verify setting exists in Metadata API docs |
222
+ | JSON parse error | Invalid JSON syntax | Validate JSON with linter |
223
+ | Conflicting options | Both `snapshot` and `sourceOrg` specified | Use only one alternative creation source |
224
+ | CLI flag ignored | Trying to override a field that doesn't support override | Only certain fields can be overridden (see CLI Flag Overrides section) |
@@ -0,0 +1,78 @@
1
+ # Scratch Org Edition Types
2
+
3
+ Reference for choosing the right Salesforce edition for scratch org creation.
4
+
5
+ ## Available Editions
6
+
7
+ | Edition | When to use | License limits | Features |
8
+ |---------|-------------|----------------|----------|
9
+ | `developer` | Default choice for most development | 2 user licenses | Most features available, best for general development |
10
+ | `enterprise` | Enterprise-specific features needed | 5 user licenses | All enterprise features, territory management, advanced approvals |
11
+ | `group` | Testing Professional edition behavior | 5 user licenses | Professional edition features |
12
+ | `professional` | Professional edition-specific testing | 5 user licenses | Professional edition feature set |
13
+
14
+ ## Partner Editions
15
+
16
+ Only available if the Dev Hub is a Partner Business Org:
17
+
18
+ | Edition | When to use |
19
+ |---------|-------------|
20
+ | `partner developer` | Partner app development |
21
+ | `partner enterprise` | Partner enterprise app testing |
22
+ | `partner group` | Partner professional edition testing |
23
+ | `partner professional` | Partner professional edition apps |
24
+
25
+ ## Edition Comparison
26
+
27
+ ### Developer Edition (Recommended Default)
28
+ - **Best for**: General development, most common use case
29
+ - **Features**: Apex, Visualforce, Lightning, Process Builder, Flow, most platform features
30
+ - **Limitations**: 2 user licenses (sufficient for most dev work)
31
+ - **Use when**: User doesn't specify or needs general Salesforce development environment
32
+
33
+ ### Enterprise Edition
34
+ - **Best for**: Enterprise-specific features, larger team testing
35
+ - **Additional features**: Territory Management 2.0, Advanced Approval Processes
36
+ - **Use when**: Testing enterprise-only features or need more than 2 users
37
+
38
+ ### Group/Professional Edition
39
+ - **Best for**: Testing behavior specific to Professional edition
40
+ - **Use when**: Building apps for Professional edition customers or testing edition-specific constraints
41
+
42
+ ## Choosing an Edition
43
+
44
+ Follow this decision tree:
45
+
46
+ ```text
47
+ 1. Does user specify edition? → Use specified edition
48
+ 2. Does user need Partner edition? → Check if Dev Hub is Partner Business Org
49
+ 3. Does user need Enterprise features? → Use enterprise
50
+ 4. Default → Use developer
51
+ ```
52
+
53
+ ## CLI Usage
54
+
55
+ **With flag:**
56
+ ```bash
57
+ sf org create scratch --edition developer --alias my-org
58
+ ```
59
+
60
+ **With definition file:**
61
+ ```json
62
+ {
63
+ "edition": "Developer"
64
+ }
65
+ ```
66
+
67
+ **Important notes:**
68
+ - Edition value is case-insensitive in CLI flags but case-sensitive in definition files (capital first letter)
69
+ - Partner editions use space format: `partner developer`, `partner enterprise`, etc. (no hyphen)
70
+ - CLI flag `--edition` overrides definition file `edition` if both are specified
71
+
72
+ ## Common Errors
73
+
74
+ | Error | Cause | Fix |
75
+ |-------|-------|-----|
76
+ | `edition value must be one of` | Invalid edition name | Use: developer, enterprise, group, professional, or partner editions (e.g., "partner developer") |
77
+ | Partner edition not available | Dev Hub is not a Partner Business Org | Use non-partner edition or switch to Partner Dev Hub |
78
+ | Features not available in edition | Requested features not available in chosen edition | Use Enterprise edition or remove unavailable features |