update_cobie
Update COBie Excel workbooks by applying structured or natural-language instructions, with dry-run, backup, and output options for safe modifications.
Instructions
Update COBie workbook with structured instructions or natural language text.
**Before first update:** Call get_update_workflow() or get_actor_contact_schema() to get
the required structure and avoid validation errors. Use MCP prompt 'how_to_update_cobie' for the full guide.
**IMPORTANT - File Modification Behavior:**
- **DEFAULT (output_path=None):** Edits the original file IN-PLACE (modifies excel_path directly)
- **With output_path:** Creates a NEW file at output_path, leaves original untouched
- **With create_backup=True:** Creates "excel_path.bak" backup before editing in-place
**Use Cases:**
- Normal editing: Don't specify output_path (edits original)
- Create a modified copy: Specify output_path
- Safe editing with backup: Set create_backup=True
**Actor contact (required):** Provide updater identity to stamp CreatedBy/CreatedOn.
{
"email": "john@example.com",
"company": "ACME Corp",
"phone": "555-1234",
"category": "Installer"
}
**Input format:** Use EITHER instruction_text OR structured_update_json (not both).
**instruction_text format (natural language):**
- "Update <ComponentName> <FieldName> to <value>"
Examples:
- "Update Tap-1 InstallationDate to 2026-02-16"
- "Update Pump-3A SerialNumber to SN-12345"
- "Update DR:T1A Material to Steel"
**structured_update_json format:**
{
"instructions": [
{
"component_name": "Tap-1",
"attribute_name": "InstallationDate",
"new_value": "2026-02-16",
"target_sheet": "Component",
"target_key": "Tap-1"
}
]
}
**Common mistakes:**
- Field names are case-sensitive: use lowercase 'email', 'company', 'phone', 'category'
- Provide ALL required actor_contact fields at once (not gradually)
- Don't specify output_path unless you want to create a separate copy
**Safety (commit gate):** Call with dry_run=False only after user has confirmed
the preview. No confirm_token on server; client must enforce confirm_token (e.g.
CONFIRM_APPLY). After commit, call validate_cobie(excel_path) to revalidate.
Example (preview):
update_cobie(excel_path, structured_update_json={"instructions": [...]},
actor_contact=actor, dry_run=True, diff=True)
# Returns: success, updated_count, errors, diffs, summary, next_actions
Example (commit, after user confirm):
update_cobie(excel_path, structured_update_json={"instructions": [...]},
actor_contact=actor, dry_run=False)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| diff | No | ||
| dry_run | No | ||
| key_mode | No | name | |
| as_of_date | No | ||
| excel_path | Yes | ||
| output_path | No | ||
| actor_contact | No | ||
| create_backup | No | ||
| instruction_text | No | ||
| structured_update_json | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| diffs | No | ||
| errors | No | ||
| dry_run | No | ||
| success | Yes | ||
| summary | No | ||
| provenance | No | ||
| updated_at | No | ||
| output_path | No | ||
| next_actions | No | ||
| updated_count | Yes | ||
| evidence_items | No |