field-service-sobject-create-configure

Managing Sfs Sobject Create

When to Use This Skill

Create sObject records via Headless 360 REST API. Describes the flow (describe → query → create), Field Service data model DAG, field requirements, insertion order, and common pitfalls. Reference when creating Skill, WorkType, SkillRequirement, or other Field Service sObjects.

Workflow

Create an sObject record via headless-360

Be helpful — understand business context before creating records. Consider the business domain of the sObject being created and iterate through short, structured questions (ask/why/impact) until no ambiguities remain that would change what gets created. Skip questions when answers are already obvious from context or existing data.

Flow

Phase 1: Describe — dispatch_readonly GET /services/data/v67.0/sobjects/<SObject>/describe

Phase 2: Query existing records — learn the org's shape...

dispatch_readonly GET /services/data/v67.0/query, queryParams.q = "SELECT <required + picklist fields> FROM <SObject> ORDER BY CreatedDate DESC LIMIT 20". Use it to: match naming/value conventions, see which optional fields are actually populated, catch duplicates, and confirm write access before spending a create.

Phase 3: Create — dispatch POST to create records. Single...

Data model DAG

Example (Field Service junction pattern — same pattern applies to any sObject DAG based on the data shape):

Skill (0C5)    WorkType (08q)    ← roots (parallel)
    └──────────┬──────────┘
       SkillRequirement (0Hx)     ← junction (last)

Fields and insertion order

Scan describe fields[] for createable:true (skip the rest — describe is large). Such a field is required when also nillable:false and defaultedOnCreate:false (defaulted ones the platform fills — omit). Two kinds:

• Scalar → put its value in the create body.
• `type:"reference"` → foreign key. If nillable:false (hard edge), create parent in referenceTo[] first. Polymorphic refs list many — pick one. Topo-sort: roots first, pass each id to dependents. nillable:true refs → optional, PATCH later.

Pitfalls:

• Base sObject CRUD is NOT in the discover corpus — skip discover, go straight to describe → dispatch.
• CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY on write → that sObject blocks sObject-REST writes

(e.g. ExternalDataSource, CustomPermission); use Tooling/Metadata API instead.

• 400/403 → likely a CRUD/FLS/sharing gap for the gateway user, not a payload bug — don't blindly retry the body.

Example — WorkType

Describe WorkType, apply the rule to fields[]. The fields that come back createable:true, nillable:false, defaultedOnCreate:false are the required ones — build the body from those, don't assume field names. Then query a few existing WorkTypes to see conventions and dupes. Then create with the derived body, e.g.

{ "url": "/services/data/v67.0/sobjects/WorkType", "method": "POST",
  "body": { "Name": "Standard Repair", "EstimatedDuration": 2 } }

───── Runtime context (Headless 360 / agentic): When this skill runs in the Headless 360 / agentic context, prefer the platform dispatch tool (`dispatch in the hosted Headless 360 MCP; dispatch in the local-dev MCP) over CLI tools (sf project deploy, sfdx, shell commands) when possible. The operations available to you are listed below in steps:`; each has been verified against the live org. Call the dispatch tool against the canonical paths. CLI fallback is acceptable only when no API path exists for a given capability.

Critical Constraints

Preconditions:

• Target sObject is createable and not on the sObject-REST block list. (check: GET /services/data/v67.0/sobjects/{N}/describe returns createable: true at the top level. A CANNOTINSERTUPDATEACTIVATEENTITY on POST means the sObject blocks base REST writes (e.g. ExternalDataSource, CustomPermission) — switch to Tooling or Metadata API.)
• Gateway user has object CRUD + relevant FLS for the required createable fields. (check: 400 / 403 with INSUFFICIENTACCESSOR_READONLY on POST → CRUD/FLS gap, not a payload bug. Grant the user's profile / permset the Create on the entity and Edit-access on every field in the body.)
• For composite/graph transactions, the caller has independently topo-sorted parents before children within each graph node's records. (check: `referenceIds used with @{...} MUST refer to a record earlier in the same graph. Wrong ordering surfaces as INVALID_REFERENCE_ID on the child node, and the entire graph rolls back atomically.`)

Operations Reference

Operations grouped by purpose. Use these as the building blocks for the workflows above.

Summary

Dependency graph

graph TD
  describe_sobject["describe-sobject (read)"]
  query_existing_records["query-existing-records (read)"]
  create_sobject_record["create-sobject-record (write)"]
  composite_graph_create["composite-graph-create (write)"]
  update_sobject_record["update-sobject-record (write)"]
  delete_sobject_record["delete-sobject-record (write)"]
  describe_sobject --> query_existing_records
  describe_sobject --> create_sobject_record
  describe_sobject --> composite_graph_create
  create_sobject_record --> update_sobject_record

Read operations

describe-sobject

Fetch the field catalog for {SObjectName}. Scan fields[] for createable:true; hard-required fields are those also with nillable:false and defaultedOnCreate:false. type:"reference" fields are FKs — hard edges when nillable:false. Base sObject CRUD is intentionally OUT of the discover corpus (skill §Pitfalls); agents must skip discover and call describe directly.

Call: GET /services/data/v67.0/sobjects/{SObjectName}/describe

Inputs:

• SObjectName (`string`) — API name of the sObject (e.g. WorkType, Skill, SkillRequirement). Path segment.

Output: SObjectDescribeSObjectResult. Load-bearing keys: createable, updateable, deletable, fields[] (each with name, type, createable, nillable, defaultedOnCreate, referenceTo[], picklistValues[]). Payload is large (>60KB for WorkType) — filter to createable:true fields before reasoning.

query-existing-records

Warm-read a small window of existing rows to match naming conventions, spot dupes, and confirm write access before spending a create. Skill §Flow.2 suggested SOQL: SELECT <required + picklist fields> FROM <SObject> ORDER BY CreatedDate DESC LIMIT 20.

Call: GET /services/data/v67.0/query

Inputs:

• q (`string`) — SOQL query. Pass via queryParams.q (URL-encoded on the wire). LIMIT 20 or fewer is the recommended window for convention scanning.

Depends on: describe-sobject

Output: {totalSize, done, records: [<row>]}. records[] is the shape an agent scans for conventions. done:false + nextRecordsUrl surface when > 200 rows — irrelevant at LIMIT 20.

Write operations

create-sobject-record

Create ONE record. Body carries only fields that were createable:true on describe. For DAGs (parents + children + junctions), prefer composite/graph so all rows land atomically in one transaction. 201 → {id, success, errors:[]}; non-2xx returns [{errorCode, message, fields:[]}].

Call: POST /services/data/v67.0/sobjects/{SObjectName}

Inputs:

• SObjectName (`string`) — API name of the sObject (path segment).
• body (`object`) — Field/value map. Only include fields with createable:true on describe; omit defaultedOnCreate:true fields (the platform fills them).

Depends on: describe-sobject

Output: 201 → {id: "<15/18-char id>", success: true, errors: []}. 4xx → array of {errorCode, message, fields}.

Rollback: delete-sobject-record

Notes: ERROR CONTRACT:

• CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY → sObject blocks base

REST writes; switch to Tooling / Metadata API. Common for ExternalDataSource, CustomPermission.

• INSUFFICIENT_ACCESS_OR_READONLY → CRUD/FLS/sharing gap on

the gateway user; don't retry the same body.

• REQUIRED_FIELD_MISSING → re-check describe filter (some

fields are createable+nillable:false only in specific record types).

• INVALID_FIELD_FOR_INSERT_UPDATE → field is not

createable:true; drop from body.

composite-graph-create

Atomically create a DAG of related records in one transaction. Skill §Data-model-DAG example: Skill + WorkType (roots) → SkillRequirement (junction). Use referenceId on each record and @{parentRef.id} in a child's FK field to bind at write time. Success returns 200 with per-node compositeResponse[] entries carrying per-child 201s. Any failure rolls back the ENTIRE graph.

Call: POST /services/data/v67.0/composite/graph

Inputs:

• body (`object`) — `{graphs: [{graphId, compositeRequest: [{referenceId,

method:"POST", url:"/services/data/v67.0/sobjects/<N>", body:{...}}, ...]}]}`. Multiple graphs may share one call; each isolates atomicity.

Depends on: describe-sobject

Output: 200 → {graphs: [{graphId, graphResponse: {compositeResponse: [{body:{id, success, errors}, httpHeaders, httpStatusCode, referenceId}]}, isSuccessful}]}. isSuccessful:false + per-child 4xx bodies on any failure.

Rollback: delete-sobject-record

Notes: ERROR CONTRACT:

• INVALID_REFERENCE_ID → child references a referenceId

that appears LATER in the array or doesn't exist. Topo-sort the compositeRequest[] parents-first.

• LIMIT_EXCEEDED → composite/graph caps at 500 records per

graph and 75 graphs per call.

• MIXED_DML_OPERATION → **the graph mixes setup-object

sObjects (e.g. Skill, Group, User, Permission*) with non-setup sObjects (e.g. WorkType, Account, Contact) in one transaction — the platform forbids this even inside composite/graph.** Split into two calls: create setup-side in call 1, capture the id, then create non-setup-side + junction referencing that id in call 2. The skill's Skill+WorkType+SkillRequirement example REQUIRES this split.

• Any HTTP 4xx on ANY child → the graph's entire

compositeResponse rolls back; sibling children report PROCESSING_HALTED and DELETE cleanup is unnecessary for a failed graph.

update-sobject-record

Field-level update on an existing record. Use for late-bound nillable:true reference attachment (skill §Fields-and- insertion-order) or corrections. PATCH is field-merge, not full-replacement: only fields in the body change; omitted fields are untouched. 204 on success (no response body).

Call: PATCH /services/data/v67.0/sobjects/{SObjectName}/{Id}

Inputs:

• SObjectName (`string`)
• Id (`string`) — 15- or 18-char record id (path segment).
• body (`object`) — Field/value map. Only include fields with updateable:true on describe.

Depends on: create-sobject-record

Output: 204 No Content on success. 4xx → same [{errorCode, message, fields}] shape as POST.

delete-sobject-record

Delete a record. Rollback target for create-sobject-record (single) and composite-graph-create (children where the transaction succeeded but a downstream verify failed). 204 on success. Note: composite/graph atomically rolls back on failure — DELETE is only needed after a SUCCESSFUL graph that a later validation rejects.

Call: DELETE /services/data/v67.0/sobjects/{SObjectName}/{Id}

Inputs:

• SObjectName (`string`)
• Id (`string`)

Output: 204 No Content. 404 → id already gone (idempotent); treat as success.