W-21685788: Expand using-webapp-salesforce-data guidance #101
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| # Mutation Query Generation | ||
|
Contributor
There was a problem hiding this comment. should the folder name for these be "references" or maybe "assets" instead of "docs"? https://agentskills.io/specification#directory-structure
Contributor
Author
There was a problem hiding this comment. good catch, will update to references (I see that in other skills as well) |
||
|
|
||
| ## Mutation Types | ||
|
|
||
| The GraphQL engine supports three mutation operations: | ||
|
|
||
| - **Create** — Insert a new record | ||
| - **Update** — Modify an existing record (Id-based) | ||
| - **Delete** — Remove an existing record (Id-based) | ||
|
|
||
| Mutations are GA in API v66+. They live under `mutation { uiapi { ... } }` and only support UI API-available objects. | ||
|
|
||
| ## Generation Rules | ||
|
|
||
| 1. **Input fields validation** — Validate that input fields satisfy the constraints for the operation type | ||
| 2. **Output fields validation** — Validate that output fields satisfy the constraints for the operation type | ||
| 3. **Type consistency** — Variables used as query arguments and their related fields must share the same GraphQL type. Verify types via the schema search script — do NOT assume types | ||
| 4. **Input arguments** — `input` is the default argument name unless otherwise specified | ||
| 5. **Output field** — For `Create` and `Update`, the output field is always named `Record` (type: EntityName) | ||
| 6. **Field name validation** — Every field name in the generated mutation **MUST** match a field confirmed via the schema search script. Do NOT guess or assume field names exist | ||
| 7. **Raw input values** — Numeric values must be raw numbers without commas, currency symbols, or locale formatting (e.g., `80000` not `"80,000"` or `"$80,000"`). Compound fields (like addresses) require constituent fields (e.g., `BillingCity`, `BillingStreet`) — do not attempt to set the compound wrapper itself. | ||
|
|
||
| ## Transactional Semantics: `allOrNone` | ||
|
|
||
| The `uiapi` mutation input accepts an `allOrNone` argument that controls rollback behavior: | ||
|
|
||
| - **`allOrNone: true` (default)** — If any operation fails, all operations in the request are rolled back. Use when operations must succeed or fail together. | ||
| - **`allOrNone: false`** — Independent operations can succeed individually. However, dependent operations (those using `@{alias}` references) still roll back together with their dependencies. | ||
|
|
||
| Always set `allOrNone` explicitly to make transactional intent clear. | ||
|
|
||
| ## Mutation Schema Patterns | ||
|
|
||
| Replace `EntityName` with the actual entity name (e.g., Account, Case). `Delete` operations use generic `Record` types. | ||
|
|
||
| ```graphql | ||
| input EntityNameCreateRepresentation { | ||
| # Subset of EntityName fields | ||
| } | ||
| input EntityNameCreateInput { EntityName: EntityNameCreateRepresentation! } | ||
| type EntityNameCreatePayload { Record: EntityName! } | ||
|
|
||
| input EntityNameUpdateRepresentation { | ||
| # Subset of EntityName fields | ||
| } | ||
| input EntityNameUpdateInput { Id: IdOrRef! EntityName: EntityNameUpdateRepresentation! } | ||
| type EntityNameUpdatePayload { Record: EntityName! } | ||
|
|
||
| input RecordDeleteInput { Id: IdOrRef! } | ||
| type RecordDeletePayload { Id: ID } | ||
|
|
||
| type UIAPIMutations { | ||
| EntityNameCreate(input: EntityNameCreateInput!): EntityNameCreatePayload | ||
| EntityNameDelete(input: RecordDeleteInput!): RecordDeletePayload | ||
| EntityNameUpdate(input: EntityNameUpdateInput!): EntityNameUpdatePayload | ||
| } | ||
| ``` | ||
|
|
||
| ## Input Field Constraints | ||
|
|
||
| ### Create | ||
|
|
||
| - **Must** include all required fields (unless `defaultedOnCreate` is `true` and not explicitly requested) | ||
| - **Must** only include `createable` fields | ||
| - Child relationships cannot be set — exclude them | ||
| - Reference fields (`REFERENCE` type) can only be assigned IDs through their `ApiName` name | ||
| - **No nested child creates** — Creating a record with child relationships in a single create operation is not supported. To create a parent and child together, use separate operations with `IdOrRef` chaining (see [Mutation Chaining](#mutation-chaining)). | ||
|
|
||
| ### Update | ||
|
|
||
| - **Must** include the `Id` of the entity to update | ||
| - **Must** only include `updateable` fields | ||
| - Child relationships cannot be set — exclude them | ||
| - Reference fields (`REFERENCE` type) can only be assigned IDs through their `ApiName` name | ||
|
|
||
| ### Delete | ||
|
|
||
| - **Must** include the `Id` of the entity to delete | ||
|
|
||
| ## Output Field Constraints | ||
|
|
||
| ### Create and Update | ||
|
|
||
| - **Must** exclude all child relationships (child relationships cannot be queried in mutations) | ||
| - **Must** exclude all `REFERENCE` fields unless accessed through their `ApiName` member (no navigation to referenced entity, no sub fields) | ||
| - Inaccessible fields are reported in the `errors` attribute of the returned payload | ||
|
|
||
| ### Delete | ||
|
|
||
| - **Must** only include the `Id` field | ||
|
|
||
| ## Mutation Chaining | ||
|
|
||
| Chain related mutations in a single request using references to `Id` values from previous mutations. This is the required approach for creating parent-child records together, since nested child creates are not supported. | ||
|
|
||
| 1. **Ordering** — Mutation `B` can reference mutation `A` only if `A` comes first in the query | ||
| 2. **Notation** — Use `SomeId: "@{A}"` in mutation `B` to set a field to the `Id` produced by mutation `A` | ||
| 3. **IDs only** — `@{A}` is always interpreted as the `Id` from mutation `A` | ||
| 4. **Restrictions** — `A` must be a `Create` or `Delete` mutation (chaining from `Update` will fail) | ||
|
|
||
| ### Chaining Example | ||
|
|
||
| ```graphql | ||
| mutation CreateAccountAndContact { | ||
| uiapi(input: { allOrNone: true }) { | ||
| AccountCreate(input: { Account: { Name: "Acme" } }) { | ||
| Record { Id } | ||
| } | ||
| ContactCreate(input: { Contact: { LastName: "Smith", AccountId: "@{AccountCreate}" } }) { | ||
| Record { Id } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Mutation Query Template | ||
|
|
||
| ```graphql | ||
| mutation mutateEntityName( | ||
| # arguments | ||
| ) { | ||
| uiapi(input: { allOrNone: true }) { | ||
| EntityNameOperation(input: { | ||
| # For Create and Update only: | ||
| EntityName: { | ||
| # Input fields — use raw values, no formatting | ||
| } | ||
| # For Update and Delete only: | ||
| Id: ... # id here | ||
| }) { | ||
| # For Create and Update only: | ||
| Record { | ||
| # Output fields | ||
| } | ||
| # For Delete only: | ||
| Id | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| # Query Testing | ||
|
|
||
| ## Testing Method | ||
|
|
||
| Use `sf api request rest` to POST the query to the GraphQL endpoint. Run from the **SFDX project root** (where `sfdx-project.json` lives). | ||
|
|
||
| ```bash | ||
| sf api request rest /services/data/v66.0/graphql \ | ||
| --method POST \ | ||
| --body '{"query":"query GetData { uiapi { query { EntityName { edges { node { Id } } } } } }"}' | ||
| ``` | ||
|
|
||
| - Use the API version of the target org (v66.0+ for mutation support, v65.0+ for `@optional`) | ||
| - Replace the `query` value with the generated query string | ||
| - If the query uses variables, include them in the JSON body as a `variables` key | ||
|
|
||
| ## Critical: HTTP 200 Does Not Mean Success | ||
|
|
||
| Salesforce returns HTTP 200 even when the GraphQL operation has errors (e.g., invalid fields, permission failures, invalid IDs). **Always parse the `errors` array in the response body regardless of HTTP status code.** Do not treat HTTP 200 as confirmation that the query succeeded. | ||
|
|
||
| ## Testing Workflow | ||
|
|
||
| This workflow applies to both read and mutation queries: | ||
|
|
||
| 1. **Report method** — State the exact method: `sf api request rest` POST to `/services/data/vXX.0/graphql` from the project root | ||
| 2. **Ask user** — Ask the user whether they want to test the query. For mutations, also ask for input argument values — mutations modify real data, so explicit consent is essential. Wait for the user's answer before proceeding. Do not fabricate test data. | ||
| 3. **Execute test** — Only if the user explicitly agrees. Run `sf api request rest` with the query, variables, and correct API version | ||
| 4. **Report result** — Classify the result using the status definitions below. Always check the `errors` array in the response, even on HTTP 200. | ||
|
|
||
| ## Result Status Definitions | ||
|
|
||
| | Status | Condition | Meaning | | ||
| | --------- | ----------------------------------------------- | --------------------------------------------- | | ||
| | `SUCCESS` | `errors` is absent or empty | Query is valid (even if no data is returned) | | ||
| | `FAILED` | `data` is empty or null | Query is invalid | | ||
| | `PARTIAL` | `data` is present **and** `errors` is not empty | Some fields are inaccessible (mutations only) | | ||
|
|
||
| ## FAILED Status Handling | ||
|
|
||
| The query is invalid. Follow this sequence: | ||
|
|
||
| ### 1. Error Analysis | ||
|
|
||
| Parse the `errors` array and check `errors[].extensions.ErrorType` for Salesforce-specific error classification. Categorize into: | ||
|
|
||
| | Category | ErrorType / Message Contains | Resolution | | ||
| | --------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | ||
| | **Syntax** | `InvalidSyntax` | Fix syntax errors using the error message details | | ||
| | **Validation** | `ValidationError` | Field name is likely invalid — re-run the schema search script, ask user if still unclear | | ||
| | **Type** | `VariableTypeMismatch` or `UnknownType` | Use error details and schema to correct the argument type; adjust variables | | ||
| | **Execution** | `DataFetchingException`, `invalid cross reference id` | Entity is unknown/deleted — create entity first if possible, or ask for a valid Id | | ||
| | **Navigation** | `is not currently available in mutation results` | Field cannot be in mutation output — apply PARTIAL status handling | | ||
| | **Unsupported** | `OperationNotSupported` | The operation is not supported — check object availability and API version | | ||
| | **API Version** | `Cannot invoke JsonElement.isJsonObject()` (on update mutations) | `Record` selection requires API version 64+ — report and retry with version 64 | | ||
|
|
||
| ### 2. Targeted Resolution | ||
|
|
||
| Apply the resolution from the table above based on the error category. Update the query accordingly. | ||
|
|
||
| ### 3. Test Again | ||
|
|
||
| Re-run the testing workflow with the updated query. Increment and track the attempt counter. | ||
|
|
||
| ## PARTIAL Status Handling | ||
|
|
||
| The query executed but some fields are inaccessible (mutations only): | ||
|
|
||
| 1. Report the fields listed in the `errors` attribute | ||
| 2. Explain that these fields cannot be queried as part of a mutation | ||
| 3. Explain that the query will report errors if these fields remain | ||
| 4. Offer to remove the offending fields | ||
| 5. **STOP and WAIT** for the user's answer. Do NOT remove fields without explicit consent. | ||
| 6. If the user agrees, restart the mutation generation workflow with the updated field list | ||
|
|
||
| ## Retry and Escalation | ||
|
|
||
| - **Maximum 2 test attempts** per generated query | ||
| - If targeted resolution fails after 2 attempts, ask the user for additional details and **restart the entire workflow from Step 1 (Acquire Schema)** to re-validate entity and field information |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
not related to your pr (let's add it to the back burner): i would love to tweak this, @optional on everything may be too extreme and masks real permission misconfigurations during development, fields critical to business logic (Id, fields used in filtering/routing) should fail loudly, not silently return undefined
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yup, I replied to this in the webapps PR, and also agreed we should tweak it (but in a follow up PR)