From ea7e9135528dcddda97c916cd3685dc61d1f8cf6 Mon Sep 17 00:00:00 2001 From: Ciaran Hannigan Date: Tue, 24 Mar 2026 15:51:56 -0400 Subject: [PATCH] refactor(using-webapp-salesforce-data): rename docs to references Made-with: Cursor --- skills/using-webapp-salesforce-data/SKILL.md | 12 ++++++------ .../mutation-query-generation.md | 0 .../{docs => references}/query-testing.md | 0 .../{docs => references}/read-query-generation.md | 0 .../{docs => references}/schema-introspection.md | 4 ++-- .../{docs => references}/webapp-integration.md | 0 6 files changed, 8 insertions(+), 8 deletions(-) rename skills/using-webapp-salesforce-data/{docs => references}/mutation-query-generation.md (100%) rename skills/using-webapp-salesforce-data/{docs => references}/query-testing.md (100%) rename skills/using-webapp-salesforce-data/{docs => references}/read-query-generation.md (100%) rename skills/using-webapp-salesforce-data/{docs => references}/schema-introspection.md (94%) rename skills/using-webapp-salesforce-data/{docs => references}/webapp-integration.md (100%) diff --git a/skills/using-webapp-salesforce-data/SKILL.md b/skills/using-webapp-salesforce-data/SKILL.md index ab5e5f2..a4ae5f5 100644 --- a/skills/using-webapp-salesforce-data/SKILL.md +++ b/skills/using-webapp-salesforce-data/SKILL.md @@ -64,11 +64,11 @@ const res = await sdk.fetch?.("/services/apexrest/my-resource"); These rules exist because Salesforce GraphQL has platform-specific behaviors that differ from standard GraphQL. Violations cause silent runtime failures. -1. **Schema is the single source of truth** — Every entity name, field name, and type must be confirmed via the schema search script before use in a query. Never guess — Salesforce field names are case-sensitive, relationships may be polymorphic, and custom objects use suffixes (`__c`, `__e`). See [Schema Introspection](docs/schema-introspection.md) for entity identification and iterative lookup procedures. +1. **Schema is the single source of truth** — Every entity name, field name, and type must be confirmed via the schema search script before use in a query. Never guess — Salesforce field names are case-sensitive, relationships may be polymorphic, and custom objects use suffixes (`__c`, `__e`). See [Schema Introspection](references/schema-introspection.md) for entity identification and iterative lookup procedures. 2. **`@optional` on all record fields** (read queries) — Salesforce field-level security (FLS) causes queries to fail entirely if the user lacks access to even one field. The `@optional` directive (v65+) tells the server to omit inaccessible fields instead of failing. Apply it to every scalar field, parent relationship, and child relationship. Consuming code must use optional chaining (`?.`) and nullish coalescing (`??`). -3. **Correct mutation syntax** — Mutations wrap under `uiapi(input: { allOrNone: true/false })`, not bare `uiapi { ... }`. Always set `allOrNone` explicitly. Output fields cannot include child relationships or navigated reference fields. See [Mutation Query Generation](docs/mutation-query-generation.md). +3. **Correct mutation syntax** — Mutations wrap under `uiapi(input: { allOrNone: true/false })`, not bare `uiapi { ... }`. Always set `allOrNone` explicitly. Output fields cannot include child relationships or navigated reference fields. See [Mutation Query Generation](references/mutation-query-generation.md). 4. **Explicit pagination** — Always include `first:` in every query. If omitted, the server silently defaults to 10 records. Include `pageInfo { hasNextPage endCursor }` for any query that may need pagination. @@ -107,11 +107,11 @@ The script outputs five sections per entity: 4. **Create input** — fields accepted by create mutations 5. **Update input** — fields accepted by update mutations -Use this output to determine exact field names before writing any query or mutation. **Maximum 2 script runs.** If the entity still can't be found, ask the user — the object may not be deployed. For entity identification procedures (`_Record` suffix, `__c` conventions) and iterative introspection cycles, see [Schema Introspection](docs/schema-introspection.md). +Use this output to determine exact field names before writing any query or mutation. **Maximum 2 script runs.** If the entity still can't be found, ask the user — the object may not be deployed. For entity identification procedures (`_Record` suffix, `__c` conventions) and iterative introspection cycles, see [Schema Introspection](references/schema-introspection.md). ### Step 3: Generate Query -Use the templates below. Every field name **must** be verified from the script output in Step 2. For detailed generation rules, filtering, pagination, ordering, semi-joins, and field value wrappers, see [Read Query Generation](docs/read-query-generation.md). For mutation chaining, input/output constraints, and transactional semantics, see [Mutation Query Generation](docs/mutation-query-generation.md). +Use the templates below. Every field name **must** be verified from the script output in Step 2. For detailed generation rules, filtering, pagination, ordering, semi-joins, and field value wrappers, see [Read Query Generation](references/read-query-generation.md). For mutation chaining, input/output constraints, and transactional semantics, see [Mutation Query Generation](references/mutation-query-generation.md). #### Read Query Template @@ -236,7 +236,7 @@ const fields = response?.data?.uiapi?.objectInfos?.[0]?.fields ?? []; bash scripts/graphql-search.sh ``` -Then fix the query using the exact names from the script output. For detailed error categories, status handling, and retry strategy, see [Query Testing](docs/query-testing.md). +Then fix the query using the exact names from the script output. For detailed error categories, status handling, and retry strategy, see [Query Testing](references/query-testing.md). --- @@ -277,7 +277,7 @@ if (response?.errors?.length) { const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? []; ``` -For detailed patterns (external .graphql files, codegen, error handling strategies, quality checklists), see [Webapp Integration](docs/webapp-integration.md). +For detailed patterns (external .graphql files, codegen, error handling strategies, quality checklists), see [Webapp Integration](references/webapp-integration.md). --- diff --git a/skills/using-webapp-salesforce-data/docs/mutation-query-generation.md b/skills/using-webapp-salesforce-data/references/mutation-query-generation.md similarity index 100% rename from skills/using-webapp-salesforce-data/docs/mutation-query-generation.md rename to skills/using-webapp-salesforce-data/references/mutation-query-generation.md diff --git a/skills/using-webapp-salesforce-data/docs/query-testing.md b/skills/using-webapp-salesforce-data/references/query-testing.md similarity index 100% rename from skills/using-webapp-salesforce-data/docs/query-testing.md rename to skills/using-webapp-salesforce-data/references/query-testing.md diff --git a/skills/using-webapp-salesforce-data/docs/read-query-generation.md b/skills/using-webapp-salesforce-data/references/read-query-generation.md similarity index 100% rename from skills/using-webapp-salesforce-data/docs/read-query-generation.md rename to skills/using-webapp-salesforce-data/references/read-query-generation.md diff --git a/skills/using-webapp-salesforce-data/docs/schema-introspection.md b/skills/using-webapp-salesforce-data/references/schema-introspection.md similarity index 94% rename from skills/using-webapp-salesforce-data/docs/schema-introspection.md rename to skills/using-webapp-salesforce-data/references/schema-introspection.md index 2aaca30..013434e 100644 --- a/skills/using-webapp-salesforce-data/docs/schema-introspection.md +++ b/skills/using-webapp-salesforce-data/references/schema-introspection.md @@ -11,9 +11,9 @@ Do not use cat, less, more, head, tail, editors (VS Code, vim, nano), or program Run the search script from the **SFDX project root** to get all relevant schema info in one step: ```bash -bash .a4drules/skills/using-salesforce-data/graphql-search.sh +bash scripts/graphql-search.sh # Multiple entities: -bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account Contact Opportunity +bash scripts/graphql-search.sh Account Contact Opportunity ``` **Maximum 2 script runs.** If the entity still can't be found after checking naming variations, ask the user. diff --git a/skills/using-webapp-salesforce-data/docs/webapp-integration.md b/skills/using-webapp-salesforce-data/references/webapp-integration.md similarity index 100% rename from skills/using-webapp-salesforce-data/docs/webapp-integration.md rename to skills/using-webapp-salesforce-data/references/webapp-integration.md