mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-05 23:41:31 +08:00
88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# Data + Tooling API Skill — Usage Guide
|
|
|
|
Supplementary reference for `platform-data-and-tooling-api-context-get`. Load only when needed; the core rules
|
|
live in `SKILL.md`.
|
|
|
|
- **API version:** 67.0 (summer-26)
|
|
- **Generated:** 2026-07-23 20:16:53
|
|
|
|
## Worked Examples
|
|
|
|
### Example 1: Build a filtered SOQL query (section-specific)
|
|
|
|
**User**: "Query open high-value opportunities with their account name."
|
|
|
|
1. Load only the `fields` section of `assets/enterprise_api/Opportunity.json`.
|
|
2. Confirm `Amount` (Filter, Sort), `StageName` (Filter), and `AccountId`
|
|
(reference, relationship_name = `Account`).
|
|
3. Generate:
|
|
```sql
|
|
SELECT Id, Name, Amount, Account.Name
|
|
FROM Opportunity
|
|
WHERE IsClosed = false AND Amount > 100000
|
|
ORDER BY Amount DESC
|
|
```
|
|
Token savings: ~80% vs loading the whole Opportunity file with its WSDL segment.
|
|
|
|
### Example 2: Safe DML (respect read-only fields)
|
|
|
|
**User**: "Update the account rating and its formula health score."
|
|
|
|
1. Load `fields` on `assets/enterprise_api/Account.json`.
|
|
2. `Rating` has `Update` → writable. A formula field has no `Create`/`Update`
|
|
→ read-only; attempting to set it fails. Only include writable fields in the
|
|
`update` payload.
|
|
|
|
### Example 3: Tooling API code coverage
|
|
|
|
**User**: "What fields give per-class Apex code coverage?"
|
|
|
|
1. Load `fields` on `assets/tooling_api/ApexCodeCoverageAggregate.json`.
|
|
2. Note `NumLinesCovered`, `NumLinesUncovered`, `ApexClassorTriggerId` (lowercase "or" — check exact casing per object, don't assume `Or`).
|
|
3. Query via the Tooling endpoint (`/services/data/vXX.0/tooling/query`), per
|
|
`supported_rest_api_http_methods`.
|
|
|
|
## Relationship Traversal
|
|
|
|
- Parent (child→parent): use `relationship_name` — `Owner.Name`, `Account.Industry`.
|
|
- Custom lookups: `__c` id field, traverse with `__r` (`Foo__r.Name`).
|
|
- Child (parent→children): use the child relationship name in a subquery, e.g.
|
|
`SELECT Id, (SELECT Id FROM Contacts) FROM Account`.
|
|
- Polymorphic (`WhoId`, `WhatId`, `OwnerId` on some objects): `refers_to` lists
|
|
multiple targets — use `TYPEOF` for surface-specific fields.
|
|
|
|
## Section Glossary
|
|
|
|
| Section | Meaning |
|
|
|---|---|
|
|
| `fields` | field API names, types, properties, and (enterprise) relationship columns |
|
|
| `fields_columns` | which columns each `fields` entry carries |
|
|
| `usage` | (enterprise) notes on how the sObject is used |
|
|
| `associated_objects` | (enterprise) related objects — **unstructured prose, not indexable JSON**; parse the markdown-style bullet list. Whether a named associated object resolves to a real file in `assets/enterprise_api/` depends on whether Salesforce crawled it as its own docs page: names ending in `Share` or `OwnerSharingRule` reliably do (Salesforce documents these per-object); names ending in `ChangeEvent` or `Feed` reliably don't (documented only generically, never as a separate page); names ending in `History` are inconsistent (sometimes crawled separately, sometimes not) — always verify with a file check before assuming either way, don't trust the name alone in any direction. |
|
|
| `ispersonaccount_fields` | (enterprise) fields present only when Person Accounts are enabled — rare; present on very few objects |
|
|
| `field_reference` | (enterprise) a **separate, largely disjoint** field catalog (label/length/precision/scale, no query/DML properties) — NOT a superset of `fields`. Check it when a field isn't in `fields`. See `field_reference_columns` for its column shape. |
|
|
| `supported_soap_calls` | (tooling) SOAP operations the record supports |
|
|
| `supported_rest_api_http_methods` | (tooling) REST methods the record supports |
|
|
| `wsdl_segment` | raw WSDL schema for the object (verbose; skip by default) |
|
|
|
|
## Field Properties Cheat Sheet
|
|
|
|
| Property | Enables |
|
|
|---|---|
|
|
| Create | set on `insert` |
|
|
| Update | set on `update` |
|
|
| Filter | use in `WHERE` |
|
|
| Sort | use in `ORDER BY` |
|
|
| Group | use in `GROUP BY` |
|
|
| Nillable | may be null (non-nillable = required on insert) |
|
|
|
|
`properties` is a single string with tokens separated by `", "` — **always split on
|
|
`", "`, never on whitespace alone.** Some tokens are multi-word (`Restricted picklist`,
|
|
`Defaulted on create`); splitting on whitespace fragments them into garbage tokens.
|
|
A field with `Defaulted on create` and no `Nillable` is not strictly required on
|
|
insert — Salesforce supplies a default if omitted.
|
|
|
|
---
|
|
|
|
*Generated by `skill-generator/scripts/generate_data_and_tooling_skill.py`.*
|