field-service-sobject-create-configure

Sfs Sobject の作成を管理する

このスキルを使用する場面

Headless 360 REST API を介して sObject レコードを作成します。フロー（describe → query → create）、Field Service のデータモデル DAG、項目の要件、挿入順序、よくある落とし穴について説明します。Skill、WorkType、SkillRequirement、その他の Field Service sObject を作成する際の参考にしてください。

ワークフロー

headless-360 を介して sObject レコードを作成する

役立つ対応を心がけてください — レコードを作成する前に、ビジネスの背景を把握してください。作成する sObject のビジネスドメインを考慮し、作成内容に影響する曖昧さがなくなるまで、短く構造化された質問（質問／理由／影響）を繰り返します。回答が文脈や既存データから明らかな場合は、質問を省略してください。

フロー

フェーズ 1：Describe — dispatch_readonly GET /services/data/v67.0/sobjects/<SObject>/describe

フェーズ 2：既存レコードをクエリ — 組織のデータ構成を把握します...

dispatch_readonly GET /services/data/v67.0/query, queryParams.q = "SELECT <required + picklist fields> FROM <SObject> ORDER BY CreatedDate DESC LIMIT 20". これを使用して、命名規則や値の規則を照合し、実際に入力されている任意項目を確認し、 重複を検出し、作成を試みる前に書き込み権限を確認します。

フェーズ 3：作成 — レコードを作成するために dispatch POST を実行します。単一...

データモデル DAG

例（Field Service のジャンクションパターン — データ形状に基づくあらゆる sObject DAG に同じパターンが適用されます）：

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

項目と挿入順序

describe の fields[] を調べ、createable:true の項目を確認します（残りは無視してください — describe は大きいためです）。その項目が nillable:false かつ defaultedOnCreate:false でもある場合、必須です（デフォルト値が設定される項目はプラットフォームが入力するため、省略します）。項目は次の 2 種類です。

• スカラー → 作成ボディに値を設定します。
• type:"reference" → 外部キーです。nillable:false（必須の依存関係）の場合は、まず referenceTo[] の親を作成します。ポリモーフィック参照には複数の候補が含まれるため、そのうち 1 つを選びます。トポロジカルソートして、ルートから順に処理し、各 id を依存先に渡します。nillable:true の参照は任意です。後から PATCH してください。

落とし穴：

• 基本的な sObject CRUD は discover のコーパスに含まれていません — discover を省略し、describe → dispatch に直接進んでください。
• 書き込み時に CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY が発生する場合 → その sObject は sObject-REST による書き込みをブロックしています （例：ExternalDataSource、CustomPermission）。代わりに Tooling/Metadata API を使用してください。
• 400／403 → ペイロードの問題ではなく、ゲートウェイユーザーの CRUD／FLS／共有権限の不足が原因と考えられます — リクエストボディをむやみに再試行しないでください。

例 — WorkType

WorkType を describe し、ルールを fields[] に適用します。createable:true、nillable:false、defaultedOnCreate:false となる項目が必須項目です — 項目名を決めつけず、それらを使ってボディを作成します。次に、既存の WorkType をいくつかクエリして、規則や重複を確認します。その後、導き出したボディを使って作成します。例：

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

───── ランタイムコンテキスト（Headless 360 / エージェント型）： このスキルを Headless 360／エージェント型のコンテキストで実行する場合、可能であれば CLI ツール（sf project deploy、sfdx、シェルコマンド）よりも、プラットフォームの dispatch ツール（ホスト型 Headless 360 MCP の dispatch、ローカル開発用 MCP の dispatch）を優先してください。利用可能な操作は以下の steps: に記載されています。各操作はライブ組織で検証済みです。正規パスに対して dispatch ツールを呼び出してください。特定の機能に API パスが存在しない場合に限り、CLI へのフォールバックが許容されます。

重大な制約事項

前提条件：

• 対象の sObject は作成可能であり、sObject-REST のブロックリストに含まれていないこと。（確認方法：GET /services/data/v67.0/sobjects/{N}/describe returns createable: trueat the top level. ACANNOT_INSERT_UPDATE_ACTIVATE_ENTITYon POST means the sObject blocks base REST writes (e.g.ExternalDataSource, CustomPermission) — switch to Tooling or Metadata API.）
• ゲートウェイユーザーが、オブジェクトの CRUD と、作成に必要なフィールドの FLS を持っていること。（確認方法：POST で 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.）
• コンポジット／グラフトランザクションでは、呼び出し元が各グラフノードの records 内で、親を子より先に独立してトポロジカルソートしていること。（確認方法：``referenceIds used with @{...}MUST refer to a record earlier in the same graph. Wrong ordering surfaces asINVALID_REFERENCE_ID on the child node, and the entire graph rolls back atomically.）

操作リファレンス

操作を目的別にまとめています。上記のワークフローを構成する要素として使用してください。

概要

操作	目的	ステータス	呼び出し	依存先
describe-sobject	読み取り	—	GET /services/data/v67.0/sobjects/{SObjectName}/describe	—
query-existing-records	読み取り	—	GET /services/data/v67.0/query	describe-sobject
create-sobject-record	書き込み	—	POST /services/data/v67.0/sobjects/{SObjectName}	describe-sobject
composite-graph-create	書き込み	—	POST /services/data/v67.0/composite/graph	describe-sobject
update-sobject-record	書き込み	—	PATCH /services/data/v67.0/sobjects/{SObjectName}/{Id}	create-sobject-record
delete-sobject-record	書き込み	—	DELETE /services/data/v67.0/sobjects/{SObjectName}/{Id}	—

依存関係グラフ

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

読み取り操作

describe-sobject

{SObjectName} のフィールドカタログを取得します。fields[] を確認し、 createable:true のフィールドを探します。必須フィールドは、 nillable:false および defaultedOnCreate:false も満たすものです。type:"reference" のフィールドは外部キー（FK）であり、nillable:false の場合は必須の依存関係になります。基本の sObject CRUD は意図的に検出対象から除外されています（スキル §Pitfalls）。 エージェントは検出をスキップし、describe を直接呼び出す必要があります。

呼び出し： GET /services/data/v67.0/sobjects/{SObjectName}/describe

入力：

• SObjectName （string） — sObject の API 名（例：WorkType、Skill、SkillRequirement）。パスセグメントです。

出力： SObjectDescribeSObjectResult。重要なキー：createable、updateable、deletable、fields[]（各項目に name、type、createable、nillable、defaultedOnCreate、referenceTo[]、picklistValues[] を含みます）。ペイロードは大きいため（WorkType では 60KB 超）、推論を行う前に createable:true のフィールドに絞り込んでください。

query-existing-records

既存のレコードを少数取得し、命名規則を把握して重複を見つけ、レコードの作成に取りかかる前に書き込みアクセスを確認します。スキル §Flow.2 で推奨されている SOQL： SELECT <required + picklist fields> FROM <SObject> ORDER BY CreatedDate DESC LIMIT 20。

呼び出し： GET /services/data/v67.0/query

入力：

• q （string） — SOQL クエリ。queryParams.q として渡します（送信時に URL エンコードされます）。命名規則の確認には、LIMIT 20 以下の件数を推奨します。

依存先： describe-sobject

出力： {totalSize, done, records: [<row>]}。エージェントは records[] を確認して命名規則を把握します。200 件を超えると done:false と nextRecordsUrl が返されますが、LIMIT 20 では該当しません。

書き込み操作

create-sobject-record

レコードを1件作成します。リクエストボディには、describe で createable:true だったフィールドのみを含めます。DAG（親 + 子 + ジャンクション）の場合は、すべての行が1つのトランザクションで アトミックに作成されるよう、composite/graph を優先してください。201 → {id, success, errors:[]}、2xx以外の場合は [{errorCode, message, fields:[]}] を返します。

呼び出し: POST /services/data/v67.0/sobjects/{SObjectName}

入力:

• SObjectName (string) — sObject の API 名（パスセグメント）。
• body (object) — フィールドと値のマップです。describe で createable:true のフィールドのみを含め、defaultedOnCreate:true のフィールドは省略してください（プラットフォームが値を設定します）。

依存関係: describe-sobject

出力: 201 → {id: "<15/18-char id>", success: true, errors: []}。4xx → {errorCode, message, fields} の配列。

ロールバック: delete-sobject-record

注記: エラー契約:

• CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY → sObject が基本 REST 書き込みをブロックしています。Tooling / Metadata API に切り替えてください。ExternalDataSource、CustomPermission でよく発生します。
• INSUFFICIENT_ACCESS_OR_READONLY → ゲートウェイユーザーに CRUD/FLS/共有の不足があります。同じボディで再試行しないでください。
• REQUIRED_FIELD_MISSING → describe のフィルターを再確認してください（一部のフィールドは、特定のレコードタイプでのみ createable+nillable:false になります）。
• INVALID_FIELD_FOR_INSERT_UPDATE → フィールドが createable:true ではありません。ボディから除外してください。

composite-graph-create

関連レコードの DAG を1つのトランザクションでアトミックに作成します。 Skill §Data-model-DAG の例：Skill + WorkType（ルート） → SkillRequirement（ジャンクション）。各レコードに referenceId を指定し、子の FK フィールドに @{parentRef.id} を指定すると、書き込み時に親レコードへ 関連付けられます。成功すると、子ごとの201を含む compositeResponse[] エントリが格納された200を返します。失敗すると グラフ全体がロールバックされます。

呼び出し: POST /services/data/v67.0/composite/graph

入力:

• body (object) — {graphs: [{graphId, compositeRequest: [{referenceId, method:"POST", url:"/services/data/v67.0/sobjects/<N>", body:{...}}, ...]}]}。1回の呼び出しで複数のグラフを指定できます。 各グラフのアトミック性は個別に保たれます。

依存関係: describe-sobject

出力: 200 → {graphs: [{graphId, graphResponse: {compositeResponse: [{body:{id, success, errors}, httpHeaders, httpStatusCode, referenceId}]}, isSuccessful}]}。失敗時は isSuccessful:false と、子ごとの4xxボディを返します。

ロールバック: delete-sobject-record

注記: エラー契約:

• INVALID_REFERENCE_ID → 子が、配列内で後に現れる、または存在しない referenceId を参照しています。compositeRequest[] を親が先になるようトポロジカルソートしてください。
• LIMIT_EXCEEDED → composite/graph は、グラフあたり最大500件、呼び出しあたり最大75グラフです。
• MIXED_DML_OPERATION → グラフ内で、設定オブジェクトの sObject（例：Skill、Group、User、Permission*）と、非設定オブジェクトの sObject（例：WorkType、Account、Contact）が混在しています。プラットフォームでは composite/graph 内であっても、1つのトランザクションでの混在は禁止されています。 2回の呼び出しに分割してください。呼び出し1で設定側を作成してIDを取得し、呼び出し2で非設定側と、そのIDを参照するジャンクションを作成します。このスキルの Skill+WorkType+SkillRequirement の例では、この分割が必須です。
• 子のいずれかで HTTP 4xx が発生すると、グラフ全体の compositeResponse がロールバックされます。兄弟の子は PROCESSING_HALTED を返すため、失敗したグラフの後処理として DELETE する必要はありません。

update-sobject-record

既存レコードに対するフィールド単位の更新です。レイトバインディングの nillable:true 参照のアタッチ（スキル §Fields-and- insertion-order）や修正に使用します。PATCH はフィールドマージであり、 完全置換ではありません。ボディに含まれるフィールドのみが変更され、省略された フィールドはそのまま維持されます。成功時は 204（レスポンスボディなし）。

呼び出し: PATCH /services/data/v67.0/sobjects/{SObjectName}/{Id}

入力:

• SObjectName (string)
• Id (string) — 15 文字または 18 文字のレコード ID（パスセグメント）。
• body (object) — フィールドと値のマップ。describe で updateable:true となっているフィールドのみを含めてください。

依存先: create-sobject-record

出力: 成功時は 204 No Content。4xx → POST と同じ [{errorCode, message, fields}] の形式。

delete-sobject-record

レコードを削除します。create-sobject-record （単一）および composite-graph-create（トランザクションは成功したものの、 後続の検証が失敗した子レコード）のロールバック対象です。 成功時は 204。注意: composite/graph は失敗時にアトミックにロールバックします。 DELETE が必要となるのは、グラフが成功した後に、その後の検証で拒否された場合のみです。

呼び出し: DELETE /services/data/v67.0/sobjects/{SObjectName}/{Id}

入力:

• SObjectName (string)
• Id (string)

出力: 204 No Content。404 → ID はすでに存在しない（冪等）。成功として扱います。