Budget import skill

Sample skill for validating a structured workbook and safely importing monthly group-account and dimension-item budget values.

This write-capable sample supports monthly values by group account and optional group dimension item. Entity-scoped rows are outside this sample, not outside Control: a plan that must be split by entity is written through the budget allocation bulk endpoint instead. See Plan values per entity.

Copy this skill

---
name: budget-import
description: Validate and import monthly group-account and dimension-item budget values through Control MCP with a dry run, explicit confirmation, and post-write reconciliation.
---

# Budget import

1. Confirm that `set_budget_group_account_monthly_values` is present and the MCP session has write access. If not, stop.
2. Confirm the source file, target budget, month range, currency basis, and aggregation rules.
3. Call `list_budgets` and resolve exactly one target budget.
4. Read the source file locally. Normalize each supported row to a group account, optional group dimension item, month in `YYYY-MM-01` format, numeric value, and source row id.
5. Resolve accounts with `list_group_accounts` and use stable `groupAccountId` values. Never match by name alone when multiple accounts could match.
6. For dimension-level rows, resolve the dimension with `list_group_dimensions` and the item with `list_group_dimension_items`, then include its stable `dimensionItemId`. Stop and report rows that carry entity detail rather than collapsing them silently: they need the entity-grain path below, not this tool. Aggregate duplicate account-dimension-month rows only when the user has approved the aggregation rule.
7. Compare the proposed rows with `get_budget_plan_values` and produce a change set showing inserts, replacements, unchanged values, and validation failures.
8. Split the exact change set into batches of at most 240 values. Run every batch with `dryRun: true` before asking for approval.
9. Show the row count, affected months and accounts, totals by month, and the exact values that will change. Ask for explicit confirmation.
10. After confirmation, submit the unchanged batches with `dryRun: false` and stable client mutation ids. If a batch fails, stop and report committed and uncommitted batches.
11. Re-read the affected months with `get_budget_plan_values` and reconcile every committed value.

## Rules

- Never write during parsing, mapping, or preview.
- Never choose the target budget from a partial name match.
- Never drop unresolved source rows. Report every unresolved account, entity, dimension item, or counterparty with its affected row count and total value. Propose missing-account creation for separate approval, then retry the complete input. A partial import requires explicit approval of the shortfall.
- Omitted rows do not mean delete or zero.
- Do not convert currencies unless the user supplies an approved conversion basis.
- Preserve source row ids and reuse mutation ids when retrying the same import.
- Do not claim atomicity across several batches.

## Output

Before confirmation, return a preview and validation report. After execution, return committed and failed batches, reconciliation results, and rows requiring manual review.

Plan values per entity

The typed tool writes group-account grain. A budget that must hold a value per entity, per entity account, or per entity and dimension is written through the budget allocation bulk-upsert endpoint using control_api_request. The budget must have been created in local-account mode when its rows are keyed by an entity’s own account, or in entity mode when they are keyed by the entity alone — a group-account budget cannot be split by entity after the fact. Look the endpoint up with control_api_endpoint_catalog for its exact path, body shape, and target kinds.

Grain	writeTargetKind	naturalKey
Group account total	0	groupAccountId
Group account, one dimension item	1	groupAccountId, dimensionItemId
Entity-scoped account row	2	parent key
Entity-scoped, one dimension item	3	parent key, dimensionItemId
Entity-scoped, one counterparty	4	parent key, counterpartyId

Kinds 0 and 1 are group-account only. For kinds 2, 3 and 4 the parent key follows the budget’s account mode: localAccountId in a local-account budget, entityId in an entity budget. Sending a local account id to an entity-mode budget is rejected as an unsupported row capability rather than silently rewritten.

Send writeTargetKind and sourceKind as integers rather than enum names. Parent rows reconcile from their children, so write the leaf cells and never write a parent total over rows that already carry a split.

Preserve unresolved rows in the uploaded file. Budget file imports accept account codes and exact reference names as well as IDs. Validation reports missing or ambiguous references with their affected row counts and total values, and submission is blocked until they are resolved. The server cannot detect rows omitted before upload: compare the reported source row count and total with the original workbook. A partial import requires explicit approval of the shortfall.

Recover missing references in a bulk file

Call describe_bulk_file_import_format with targetModel: "Budget", then preserve every normalized source row in the canonical file. In place of IDs, you can supply groupAccountCode, localAccountCode, entityName, groupDimensionName, dimensionItemName, and counterpartyName. Matching is exact; ambiguous names or a code/name that conflicts with a supplied ID are rejected. Local account codes need an entity, and dimension item names need a dimension (or the budget’s configured dimension). Dimension vectors also accept groupDimensionName and groupDimensionItemName in place of their IDs.

1. Call validate_bulk_file_import. No budget values or accounts are created during validation.
2. If it returns unresolved_budget_references, show each requirement’s reference, scope, affected row count, and total value. Overall reconciliation totals count each unresolved row once, even if it has several missing references. Detailed requirements and sample row indexes are capped; omittedRequirementCount reports additional requirement groups, while reconciliation covers the complete file.
3. Ask the user to select an existing reference or approve creating the missing account. Account creation is a separate write action. For local accounts backed by an accounting integration, create the account in that source and sync it instead.
4. After the repair, validate the same complete file again and reconcile sourceRowCount and sourceTotalValue with the workbook. Obtain confirmation before submit_bulk_file_import, then poll get_file_upload_status until it completes or fails. Submission checks references again, and the worker uses the atomic budget upsert.

A missing-reference failure during a confirmed chat submission is returned to the assistant so it can propose the repair. The import stays unqueued until its reference requirements pass.

Try it

Preview this workbook against the Approved Budget for July through December 2026. Do not write anything.

Import the confirmed monthly group-account rows, then re-read the plan and reconcile every value.

Check whether this file can be imported without losing its entity and dimension detail. Report which rows need the entity-grain path before writing anything.

Write tools can change plan data. Review the dry-run output and the exact proposed change set before confirming the commit.