# Plan a batch of records before creating them Write the records as a reviewable plan — check what will be born, approve it, then create them all together under your own permissions. Work · a play in 4 steps. ## The steps 1. Start the scratchpad — name it and say what you intend. — [createScratchpad](/reference/scratchpad/createScratchpad/) 2. Write the steps; each is checked and problems come back marked on the exact step. — [setScratchpadPlan](/reference/work-and-notes/setScratchpadPlan/) 3. Hold the plan for review, then approve it — approval pins the reviewed plan. — [transitionScratchpad](/reference/scratchpad/transitionScratchpad/) 4. Create every planned record, in order; each step remembers exactly what it made. — [realizeScratchpad](/reference/work-and-notes/realizeScratchpad/) ## The calls Every operation this use case runs, in the order it first appears, with the request and the response its reference page shows. ### createScratchpad [createScratchpad](/reference/scratchpad/createScratchpad/) — mutation · Create a new scratchpad — a plan of records to create, reviewed and approved before anything is born at your organization. **Example request** ```graphql mutation ExampleCreateScratchpad($input: NewScratchpadInput!) { createScratchpad(input: $input) { id sysId type caption status parentId rootId createdAt updatedAt revisionNum revision origin intent planRevision approvedPlanRevision inFlightSeq realizationFault } } ``` Variables: ```json { "input": { "caption": "Blue jeans" } } ``` Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`. **Example response** ```json { "data": { "createScratchpad": { "id": "01900000-0000-7000-8000-37386ae00000", "sysId": "SD-EXMP-0000-000F", "type": "Scratchpad", "caption": "Blue jeans", "status": "draft", "parentId": "01900000-0000-7000-8000-065235280000", "rootId": "01900000-0000-7000-8000-a093dd800000", "createdAt": "2027-01-31T00:00:00.000Z", "updatedAt": "2027-01-31T00:00:00.000Z", "revisionNum": 1, "revision": "01900000-0000-7000-8000-b7960e180000", "origin": "", "intent": "", "planRevision": 1, "approvedPlanRevision": 1, "inFlightSeq": 1, "realizationFault": "" } }, "extensions": { "at": { "callId": "01EXAMPLE-CALL-ID", "version": { "requested": { "name": "genesis", "number": 0 }, "serviced": { "name": "genesis", "number": 0 } } } } } ``` ### setScratchpadPlan [setScratchpadPlan](/reference/work-and-notes/setScratchpadPlan/) — mutation · Write or replace the whole plan on a draft scratchpad — the ordered list of records it will create. **Example request** ```graphql mutation ExampleSetScratchpadPlan($id: ID!, $revision: ID!, $steps: [ScratchpadPlanStepInput!]!) { setScratchpadPlan(id: $id, revision: $revision, steps: $steps) { id sysId type caption status parentId rootId createdAt updatedAt revisionNum revision origin intent planRevision approvedPlanRevision inFlightSeq realizationFault } } ``` Variables: ```json { "id": "01900000-0000-7000-8000-37386ae00000", "revision": "01900000-0000-7000-8000-b7960e180000", "steps": [ { "operation": "", "input": "" } ] } ``` Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`. **Example response** ```json { "data": { "setScratchpadPlan": { "id": "01900000-0000-7000-8000-37386ae00000", "sysId": "SD-EXMP-0000-000F", "type": "Scratchpad", "caption": "Blue jeans", "status": "draft", "parentId": "01900000-0000-7000-8000-065235280000", "rootId": "01900000-0000-7000-8000-a093dd800000", "createdAt": "2027-01-31T00:00:00.000Z", "updatedAt": "2027-01-31T00:00:00.000Z", "revisionNum": 1, "revision": "01900000-0000-7000-8000-b7960e180000", "origin": "", "intent": "", "planRevision": 1, "approvedPlanRevision": 1, "inFlightSeq": 1, "realizationFault": "" } }, "extensions": { "at": { "callId": "01EXAMPLE-CALL-ID", "version": { "requested": { "name": "genesis", "number": 0 }, "serviced": { "name": "genesis", "number": 0 } } } } } ``` ### transitionScratchpad [transitionScratchpad](/reference/scratchpad/transitionScratchpad/) — mutation · Move a scratchpad through its life — hold the plan for review, reopen it for editing, approve it, or abandon it. **Example request** ```graphql mutation ExampleTransitionScratchpad($id: ID!, $revision: ID!, $op: ScratchpadTransitionOp!, $reason: String) { transitionScratchpad(id: $id, revision: $revision, op: $op, reason: $reason) { id sysId type caption status parentId rootId createdAt updatedAt revisionNum revision origin intent planRevision approvedPlanRevision inFlightSeq realizationFault } } ``` Variables: ```json { "id": "01900000-0000-7000-8000-37386ae00000", "revision": "01900000-0000-7000-8000-b7960e180000", "op": "ready", "reason": "Correcting a miscount." } ``` Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`. **Example response** ```json { "data": { "transitionScratchpad": { "id": "01900000-0000-7000-8000-37386ae00000", "sysId": "SD-EXMP-0000-000F", "type": "Scratchpad", "caption": "Blue jeans", "status": "draft", "parentId": "01900000-0000-7000-8000-065235280000", "rootId": "01900000-0000-7000-8000-a093dd800000", "createdAt": "2027-01-31T00:00:00.000Z", "updatedAt": "2027-01-31T00:00:00.000Z", "revisionNum": 1, "revision": "01900000-0000-7000-8000-b7960e180000", "origin": "", "intent": "", "planRevision": 1, "approvedPlanRevision": 1, "inFlightSeq": 1, "realizationFault": "" } }, "extensions": { "at": { "callId": "01EXAMPLE-CALL-ID", "version": { "requested": { "name": "genesis", "number": 0 }, "serviced": { "name": "genesis", "number": 0 } } } } } ``` ### realizeScratchpad [realizeScratchpad](/reference/work-and-notes/realizeScratchpad/) — mutation · Execute an approved plan — create its records one step at a time under YOUR OWN permissions. **Example request** ```graphql mutation ExampleRealizeScratchpad($id: ID!, $revision: ID!, $reason: String) { realizeScratchpad(id: $id, revision: $revision, reason: $reason) { id sysId type caption status parentId rootId createdAt updatedAt revisionNum revision origin intent planRevision approvedPlanRevision inFlightSeq realizationFault } } ``` Variables: ```json { "id": "01900000-0000-7000-8000-37386ae00000", "revision": "01900000-0000-7000-8000-b7960e180000", "reason": "Correcting a miscount." } ``` Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`. **Example response** ```json { "data": { "realizeScratchpad": { "id": "01900000-0000-7000-8000-37386ae00000", "sysId": "SD-EXMP-0000-000F", "type": "Scratchpad", "caption": "Blue jeans", "status": "draft", "parentId": "01900000-0000-7000-8000-065235280000", "rootId": "01900000-0000-7000-8000-a093dd800000", "createdAt": "2027-01-31T00:00:00.000Z", "updatedAt": "2027-01-31T00:00:00.000Z", "revisionNum": 1, "revision": "01900000-0000-7000-8000-b7960e180000", "origin": "", "intent": "", "planRevision": 1, "approvedPlanRevision": 1, "inFlightSeq": 1, "realizationFault": "" } }, "extensions": { "at": { "callId": "01EXAMPLE-CALL-ID", "version": { "requested": { "name": "genesis", "number": 0 }, "serviced": { "name": "genesis", "number": 0 } } } } } ```