Plans and mappings

A plan makes a proposed workflow reviewable before it runs. Open Plans to find drafts, approved plans and run history. Search by title or description, and filter by status - including Failed, for plans whose last run did not finish. Check the plan kind first: approval has different effects for different kinds.

Create a plan

Two paths, and they produce the same artifact. New plan opens the agent in Plan mode: describe the source, destination, entities, volume and expected outcome, and the agent maps the interfaces and records the coverage and gaps a blank title cannot supply. Write it myself takes a title, a description and the plan kind, and opens the new draft in its editor for you to fill in. Either way the plan starts as a draft; nothing is written to any system until it is approved and run.

Edit a plan

Open a plan and choose Edit. Entities, generation stages and the definition of done have form controls - an entity's volume, its template and the endpoint its rows are written to are picked rather than typed. Blocks that have no form yet (tasks, flow, mappings, gaps and the rest) are edited as JSON in the same panel.

You can also ask the agent, in the chat that authored the plan or a new one: "revise the plan to 500 rows" updates the existing plan rather than saving a second one. A running plan cannot be edited at all until its run finishes or is stopped.

The agent creates a task plan by default: the work grouped into phases, each phase a list of tasks. Ask for a flow plan when you want the interface map between systems, or for an entity plan when you want a runnable generation plan with entities and volumes.

Review an entity or task plan

Ask the agent to create a plan describing the goal, the systems involved and the expected outcome; for an entity plan, ask for one and include the source, destination, entities and volumes. Open the resulting plan and review its assumptions, missing inputs, coverage and gaps. Use Run checks for readiness evidence where available; readiness checks are separate from the plan's execution action.

An entity plan can offer Approve & run, Run now or Re-run. Follow the Run panel and inspect the artifacts and errors. For a task plan, Approve plan records approval; arrange its actual execution through the relevant workflow.

What a run may write

A generation run writes rows into the endpoints its plan names, so the approved specification is also the run's write scope. Before any endpoint write inside a run, the endpoint is checked against the entities of the approved plan; anything the plan did not name is refused, and the refusal is recorded on the audit trail.

The check answers from the plan alone and fails closed. A specification that names no endpoint authorizes none, and one that will not parse authorizes none either. It engages only inside a plan run, so ordinary chat and scenarios are unaffected, and it runs ahead of the volume cap: how much is being written does not matter when the destination was never approved.

Approval is a decision about a document. This is what makes that decision bind the run, so an approved plan can only write where it said it would.

Read a run's result

A completed generation run is graded per entity against the volume the plan approved. The Run tab reports the shortfall, anything that could not be counted, what was delivered and what failed to arrive, so a plan asking for 10,000 rows that came back with 10 no longer reads like one that produced them all.

The tolerance is exact, deliberately. Generation asks a template for exactly the approved volume rather than sampling towards it, so there is no natural band to allow for and any shortfall is a real one. The shortfall counts only what can be proven missing: an entity whose artifacts could not be counted is reported as uncounted and left out of the total rather than assumed lost, while an entity counted at zero is fully short. Rows for an entity are the largest total across its artifact formats and never the sum, because a run records both a JSON and a CSV per entity.

Every endpoint write is recorded with whether it was attempted, whether it succeeded, and its row count, status and error, so a run whose deliveries all failed can no longer read as a success. A short run still completes and keeps its artifacts; whether it is good enough is a human decision.

Accept a run

A completed generation run can be accepted from the plan's Readiness & reconciliation section by someone holding plan:approve. Acceptance produces the same kind of hash-stamped artifact a check sign-off produces, over what the run made rather than over a verdict, and it verifies through the same button.

Accepting a run that fell short of its approved volume is allowed, but never silently: it needs a stated reason, exactly as accepting a non-green check does. The record names the endpoints the plan asked for and what the run produced against what was asked. Read it with the run's delivery record and the target system itself; an acceptance is evidence of a decision, not proof that the rows arrived.

Review a mapping

1. Identify the source and target schemas and the selected project.
2. Review each target field's source, expression, default and relationship. AI-suggested rules need human review.
3. Resolve unmapped and ambiguous rows. A transform refuses a mapping that still contains rows not marked mapped.
4. Use the mapping dry run on a small sample. POST /plans/{id}/mapping-dry-run accepts draft plans and is capped at 50 rows; it does not persist transformed data.
5. Choose Approve mapping when the rules are ready.
6. Execute the approved mapping through the transform workflow and inspect the output and rejected rows.

Editing an approved specification can return it to draft and require review again. Retain the exact reviewed specification with your evidence; approval of one version is not an instruction to execute arbitrary later edits.

Track a task plan

An approved task plan is where the work is recorded. Open the Tasks tab and tick each task off as it is done; the plan keeps who completed it and when, and the phase narrative on the Overview shows how much of each phase is finished. Reopen a task the same way.

Completing a task is not an edit to the plan, so an approved plan stays approved - only changing what the plan says returns it to draft for re-approval. Recording work needs permission to edit plans; an approver-only role accepts a plan rather than reporting progress against it.

If someone else changed the plan while you had the editor open, saving is refused rather than silently undoing their change - reload the plan and make the edit again.

Verify a flow plan

A flow plan is verified rather than generated. Each step should name the registered endpoint it goes through; Approve & run then checks those endpoints against the project and reports, per step:

• verified - bound to an endpoint that exists here,
• unbound - the step claims to be reachable but names no endpoint, so nothing can confirm it,
• missing - it names an endpoint this project does not have,
• gap - the plan itself says no interface exists yet.

A flow is approved only when every step is verified or a declared gap. The check writes nothing; it never changes the plan's status on its own.

Run history

The Run tab opens on the newest run and keeps every earlier one. Select any run in the history to read its logs and download the artifacts it produced - useful when the same plan has been run against several environments. A run's link (?run= on the plan URL) opens that run directly.

When you start a run, DataMaker tells you when it finishes, wherever you are in the app by then, and on your next visit if you closed it. Grant notification permission when prompted to also be told while the window is in the background. A run that is still going is never announced as finished.

Signoffs and evidence

Where available, retain a signoff with the plan so reviewers can verify the recorded specification and decision. A check sign-off and a run acceptance are both stamped this way and verify the same way. A signoff is review evidence, not a target-write approval or proof that the output meets every business requirement.

Approving a plan, running it, cancelling a run, signing off a check and accepting a run are all recorded on the audit trail, so a plan's authorization history survives the plan itself.

See Data jobs, Approvals and Reconciliation for the execution steps that follow.