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 CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY 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 INSUFFICIENT_ACCESS_OR_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

| Operation | Purpose | Status | Call | Depends on |

|-----------|---------|--------|------|------------|

| describe-sobject | read | — | GET /services/data/v67.0/sobjects/{SObjectName}/describe | — |

| query-existing-records | read | — | GET /services/data/v67.0/query | describe-sobject |

| create-sobject-record | write | — | POST /services/data/v67.0/sobjects/{SObjectName} | describe-sobject |

| composite-graph-create | write | — | POST /services/data/v67.0/composite/graph | describe-sobject |

| update-sobject-record | write | — | PATCH /services/data/v67.0/sobjects/{SObjectName}/{Id} | create-sobject-record |

| delete-sobject-record | write | — | DELETE /services/data/v67.0/sobjects/{SObjectName}/{Id} | — |

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.