Configuration Management

Config Manager brings git-like version control to ControlBird's configuration system. Your schemas and entity tree are versioned, so every change is tracked. You work on a config effort: a named, isolated workstream you edit with the normal apps, then push to runtime when it is ready. A push can be undone, reverting exactly what it changed.

Reach for Config Manager whenever you need to evolve configuration safely: staging a schema change before it touches production, editing devices or alarms against a draft instead of the live system, reviewing exactly what changed before you apply it, or capturing the running configuration as a backup you can restore on a fresh node. You get the auditability of git and a safe, reversible path to production without leaving the ControlBird UI.

Key Concepts

A few ideas underpin everything Config Manager does:

• Version-controlled configuration: your schemas and entity tree are versioned, so every change is tracked, reviewable, and reversible.
• The entity tree: every configuration entity has a hierarchical path representing its location in the tree (for example /Root/Controllers/Singletons/Config), matching the Store's tree structure.
• Efforts: an effort is a named config workstream backed by its own branch and isolated workspace. Several efforts can run at once without stepping on each other, so different changes stay independent until you push them.
• Edit with the apps you already use: open Device Manager, Schema Editor, or any config app in an effort and your edits go to that effort's draft instead of the live system. The window's titlebar shows which effort it is editing.
• Push to runtime, with undo: pushing applies the difference between the effort and the live system as one all-or-nothing change. Undoing a push reverts exactly the entities and fields that push changed, and nothing else.
• Storage scope: only Configuration-scoped fields are version-controlled. Runtime-scoped fields exist only in memory and reset on restart, so they never appear in version control.

Change tracking

As you edit, Config Manager highlights added entities in green, modified entities in yellow, and removed entities in red, with field-level diffs for each. The same model drives merge-conflict resolution and the diff preview shown before an apply.

Working in an effort

Open the Efforts tab in Config Manager to create an effort, give it a name, and open any config app against it. From there the loop is:

• Create an effort for the change you want to make.
• Open an app in the effort and edit as usual. Edits land in the effort's draft, not the live system, so production keeps running untouched.
• Push to runtime when the change is ready. Config Manager applies the difference between the effort and the live system and reports how many entities changed.
• Undo the last push if something looks wrong. The revert is scoped to exactly what the push changed, so unrelated live activity is left alone.

A push that introduces a new schema cannot be auto-undone, since removing a type could orphan data; those pushes are marked accordingly.

Backups and fresh-node restore

Export from Live captures the running configuration into version control as a point-in-time backup, optionally published to your git remote. To stand up a replacement node, point it at that configuration and it boots with the same setup. This is the recommended way to snapshot a known-good configuration before a large change and to migrate configuration between environments.

The cb-config CLI

Config Manager is backed by the same workflow exposed on the command line through cb-config. The four core operations are:

Common Patterns

• Effort → edit → push → undo if needed: create an effort, open the config apps against it, review the change tracker (green/yellow/red), push to runtime, and undo the push if the result is wrong.
• Parallel work with efforts: run several efforts at once so independent changes stay isolated until each is pushed.
• Export from Live: capture the running configuration to version control for a backup, a baseline, or to sync configuration between environments.
• Diff between revisions: use cb-config diff to compare two configuration databases when reviewing what changed between builds.

Troubleshooting & Limitations

• Validation blocks apply: syntax errors, schema violations, and reference cycles block an apply. Warnings are allowed but indicate potential runtime issues, so review them before applying.
• Circular schema inheritance: a type cannot inherit a chain that leads back to itself (Type A → Type B → Type A). Validation detects and prevents this.
• Orphaned references: entity references must point to existing entities; orphaned references are flagged as warnings during validation.
• Worktree data loss: worktrees are workspace-scoped checkouts. Deleting a worktree discards any uncommitted changes on that branch, so commit before cleanup.
• Runtime fields are not versioned: only Configuration-scoped fields are version-controlled. Runtime-scoped fields are memory-only and reset on restart.
• Merge conflicts: when two branches modify the same configuration, you must manually resolve by choosing or combining versions using the merge-conflict dialog.
• Field-name conflicts in inheritance: child entity types inherit Configuration-scoped fields from parent schemas; field names must not conflict across the inheritance chain.