Skip to content

Flow Interface Builder ​

The Flow Interface Builder is a visual designer for a flow's run form. Authors compose a React Flow graph of section and field nodes connected by semantic edges; operators never see the graph — they see a normal, sectioned form rendered from a compiled contract on Start Run and Save as Schedule.

Migration required: run the standard migration task before enabling this feature in an environment:

task db:migrate

The builder persists submitted/resolved interface input provenance on runs, and the audit columns for it (runs.submitted_inputs_json and runs.resolved_inputs_snapshot_json) are part of the database schema the migration creates.

Form key and upgrades ​

A flow definition stores its execution graph in graph and its run-input form in form. Imports accept the previous interface_graph spelling and normalize it to form; create, update and draft-save requests do the same for older clients. If both keys are supplied, their values must match. Exports write only form.

Versions before 1.0.0 were internal and never published, and upgrading an instance from one of them is not supported. A 1.0.0 database stores the form only under form; interface_graph survives only as a spelling that imports and requests accept.

Configuration Exchange exports use schema_version: 3; imports accept versions 2 and 3. Older bundles and Git flow.yaml files can be imported directly without re-exporting. Upgrade receiving instances before sharing new exports or pushing canonical forms to a shared Git repository: older versions cannot read form. The first export or Git push after upgrading changes the serialized form key and its content hash, even when the form itself has not changed.

Authoring model ​

Open a flow in the editor and switch to the Form tab.

  • Sections group fields into cards. Sections and fields are laid out by canvas position: nodes sharing a horizontal band form one row (split evenly), rows read top-to-bottom, left-to-right. Fields and notes outside every section show at their place too: between the sections above and below them, in a card with no heading (notes alone show without a card). One that is level with a section's top edge goes after it.

  • Fields declare a field_id (the {{ inputs.<id> }} name), a type, a label, optional default/description, and validation rules (AND/OR/NOT rule trees with per-rule or per-group message overrides). A text field's regex / not_regex rule is matched with RE2, whose run time grows linearly with the value. RE2 reads the usual syntax except backreferences and lookaround, so a pattern using lookahead is refused when the flow is saved, and a stored one fails the validation. A value longer than 65,536 characters fails the validation too. A regex rule that cannot be checked fails the whole validation, even inside a NOT or OR group.

  • Notes are instructions for the person filling in the form: an optional heading and Markdown text (up to 4,000 characters). Add one from Add → Note. A note shows in the run form at its place on the canvas, but always in a row of its own: fields beside it on the canvas move to the next row. Like fields, a note belongs to the section it is dropped in; a note outside every section shows between the sections around it. A note never carries a value, takes no edges, and is never part of a run's inputs. Links work only when they start with https://; images and raw HTML are not shown. The compiler warns about an empty note (EMPTY_NOTE), an edge that touches a note (NOTE_EDGE_IGNORED), and a note whose section is missing (INVALID_NOTE_PARENT).

  • Edges carry one or more semantic relations:

    RelationEffect
    options_filterSource field's value filters the target's options (cascading selects)
    visible_whenTarget is shown only when the source condition holds
    enabled_whenTarget is editable only when the source condition holds
    required_whenTarget becomes required when the source condition holds

    Only these four relation types exist. Stored graphs containing retired types still load — the compiler ignores those relations and reports an UNSUPPORTED_EDGE_RELATION warning.

Built-in field types and option sources ​

Field types: core.text, core.number (int/float subtypes), core.bool, core.enum, core.multi_enum, core.time_window, files.repository_file, and inventory.device.

core.time_window (Maintenance window, category Scheduling) asks for a start, a length and a time zone, and stores {start, end, timezone} with the times in UTC. It has no default value and no validation rules; a window that has already ended is refused when the run is created. A Wait for window node names the field it waits for.

files.repository_file (Repository file, category Files) picks a file from the file repositories. Its value names the file by repository and path, not by id:

json
{"repository": "Firmware", "path": "iosxe/17.9/cat9k_iosxe.17.09.05.SPA.bin"}

The path is the file's folder, a slash and its name; a file in the repository's root has just its name. The repository is looked up in the run's organization, and in the shared organization only when the run's has no repository of that name. With multiple: true the value is a list of these. Two optional settings narrow the choice: repository (only that repository's files) and folder (only files in that folder or below it). Run creation refuses a file that does not exist, one the run's organization may not read, one outside those settings, and a path that names two files (the same name uploaded twice into one folder). A step reads the value with folder and filename added, so {{ inputs.firmware.filename }} works, and a download step takes the whole value as its File setting: {{ inputs.firmware }}. A reference with a template in it (say {{ vars.FW_REPO }}) is checked by the step when it runs.

inventory.device fields are device targets: their submitted value routes to the run's related_targets (the device-targeting path) instead of inputs, and each device field owns a target role (defaulting to its field id). Roles derived from the form win over settings-authored roles of the same name.

Option sources:

KindOptions come fromFilter keys (cascading or fixed)
core.statica hard-coded list on the field—
inventory.devicesinventory devices (searchable)site_id, provider_id, platform, maintenance_state, sync_status, tag.*
inventory.sitesinventory sites (searchable)parent_id, provider_id, tag.*
inventory.providersconfigured inventory providersprovider_type, enabled_only
inventory.objectssynced inventory objects of one type - prefixes, VLANs, whatever the installed plugins register (searchable)provider_id, sync_status, attr.<attribute>
attachment.csva CSV-style file attached to the flowany CSV column name

Filter values may be lists (a multi-select or multi-device parent): they match any of the submitted entries (OR semantics). inventory.providers lists only enabled providers unless a fixed enabled_only: false filter opts in, and it always offers the built-in local provider alongside configured ones.

maintenance_state accepts active, maintenance or disabled, so a form can offer only devices the source of truth still considers in service. It is a filter on the picker, not a gate on the run: nothing stops a run whose targets were chosen some other way.

Both registries are extensible by Python packages via the hegemony.flow_interface entry-point group; a plugin exposes register(registry) and may add field types and option sources.

attachment.csv — options from a file ​

A select/multi-select field can draw its options from a delimited file uploaded to the flow (Attachments tab). The field's option_source.config names the file and the columns:

jsonc
"option_source": {
  "kind": "attachment.csv",
  "config": {
    "filename": "data/locations.csv",
    "value_column": "code",          // optional; defaults to the first column
    "label_column": "datacenter",    // optional; defaults to value_column
    "description_column": "region",  // optional
    "delimiter": ",",                 // optional; defaults to ","
    "has_header": true                // optional; defaults to true
  }
}

Rows are de-duplicated by value (so a column reused as a parent select yields distinct choices), then filtered by search and the limit. The file is read version-consistently: a run pinned to a committed flow version reads that version's attachment snapshot, the live designer reads the current draft. Files are UTF-8 text capped at 1 MB (the attachment limit). Only the first 1,000 columns of the header are used, and rows after the first 500,000 cells are ignored. A row shorter than the header simply has no value in the missing columns.

Authoring-time checks warn (never block) when the config is incomplete or stale: a missing filename at compile time (OPTION_SOURCE_CONFIG), and — via POST /flows/{id}/interface/validate — a file that doesn't exist on the flow (ATTACHMENT_NOT_FOUND), configured columns absent from its header (CSV_COLUMN_UNKNOWN), or a cascading/fixed filter key that isn't a column (CSV_FILTER_UNKNOWN — such a cascade would filter every row out). These warnings list the first ten header columns and how many more there are.

inventory.objects - options from synced inventory objects ​

Any object type an inventory provider syncs can back a select, so a form can offer the VLANs or prefixes that exist in NetBox rather than free text. The field's option_source.config names the type and, optionally, what a picked option submits:

json
{
  "kind": "inventory.objects",
  "config": { "object_type": "vlan", "value_field": "attr.vid" }
}
  • object_type (required) - an object type id. The builder offers the types this instance registers. A type nothing here registers still compiles and still offers whatever rows a provider synced under that id, because a registered type is what the builder reads attributes and search fields from, not a gate on what a provider may sync; the validate endpoint reports it as an OBJECT_TYPE_UNKNOWN warning, since usually nothing synced it either.
  • value_field - what the run receives: id (default, the object's UUID), external_id, name, or attr.<attribute> for a manifest attribute, so a step can use the value as is ({{ inputs.vlan }} is the VID, not a UUID). Rows sharing a value - the same VLAN reported by two providers - become one option.

Options are the type's rows with sync_status: active; a fixed sync_status filter widens that (stale, or a list). provider_id narrows to one or more providers, and attr.<attribute> compares an attribute as text (numbers welcome), which is how a picked VRF or site can cascade into the prefixes under it. Free text matches the name, display name, external id and the type's declared search fields. Tenant-visible discovered types, including repository-defined Git types, supply these fields as well as statically registered types. For example, a Git service type can declare owner as a search field so typing a team name finds its services. Membership is enforced at run creation like every dynamic source: a value that is not among the current options is rejected, by name when the value is an id.

Fixed (static) filters ​

Beyond cascading edges, a field can declare always-on filter values in its option_source.filters config; the compiler turns them into OptionFilter.static_value entries:

jsonc
"option_source": {
  "kind": "inventory.sites",
  "filters": {
    "provider_id": { "static_value": "netbox:prod" },
    "parent_id": { "static_value": null }   // null = explicitly unset → root sites only
  }
}

The null sentinel works wherever the underlying column is nullable: parent_id on inventory.sites (root sites only) and site_id on inventory.devices (devices not assigned to any site).

In the builder these are the Fixed filters rows on a dynamic source (an empty value means "unset"). An options_filter edge with the same key overrides the fixed value (the cascade refines the default). Filter keys starting with __ are reserved and ignored with a RESERVED_FILTER_KEY warning; two edges feeding the same key raise DUPLICATE_FILTER_KEY.

Cascading selects (options_filter) ​

An options_filter edge makes one field's value narrow another field's options. The edge's relation value is the target source's filter key; the source field's current value is passed under that key to the target source. Examples:

CascadeSource → targetEdge relation value
Site → Deviceinventory.sites → inventory.devicessite_id
Provider → Deviceinventory.providers → inventory.devicesprovider_id
Provider → VLANinventory.providers → inventory.objectsprovider_id
VRF → Prefix (an attribute)inventory.objects → inventory.objectsattr.vrf (compared as text)
Parent site → Child siteinventory.sites → inventory.sitesparent_id
Region → Datacenter (one CSV)attachment.csv → attachment.csvregion (a CSV column)
Env → App → Versionchained attachment.csv fieldseach next CSV column

If the relation carries no value, the source field's own id is used as the filter key. Circular options_filter chains are rejected at compile time (CIRCULAR_OPTIONS_DEPENDENCY). At runtime the form re-fetches a field's options whenever one of its parent values changes, and prunes a now-invalid selection (entry-by-entry for multi-selects) unless the source sets allow_clear: false. Pruning only ever runs against a complete, unfiltered result for the current request — it is skipped while a server-side search narrows the list or when the response is truncated by the fetch limit, since absence from a partial view says nothing about validity. Dynamic selects are searchable comboboxes: typing sends the query to the options endpoint, and when the result is capped a "showing N of total" hint appears.

Authoring in the builder. On the Form tab, a select/multi-select field's inspector has an Option source picker (Static list, File attachment (CSV), Inventory sites/providers/devices); choosing File attachment (CSV) reveals the file + column configuration: the file is picked from the flow's attachments, the value/label/description columns from the file's header, and an Options preview shows the first choices the operator will see. To make a cascade, connect two fields and add a Filter options relation to the edge, setting its filter key to the target source's key — the input suggests the source's known keys (for CSV targets, the file's real column names). Fixed filters rows get the same key suggestions, and for CSV sources the value input suggests the chosen column's distinct values.

Device queries (allow_query) ​

A device field normally carries device ids, picked when the run is started. A field whose config sets allow_query: true may instead carry a query, which run creation turns into the devices that match it at that moment:

jsonc
// the field's config
{"option_source": {"kind": "inventory.devices"}, "multiple": true,
 "allow_query": true, "query_max_devices": 50}   // query_max_devices is optional

// its value: in the run form's request, a schedule's params, a webhook's params,
// or as the field's default_value
{"query": {"tag.role": "edge", "platform": "ios-xe"}}

This is what a schedule or a webhook wants when the fleet changes over time: the schedule stores the query, not the devices, so each firing targets the devices that match then.

  • Filters are those of inventory.devices: site_id, provider_id, platform, maintenance_state, sync_status and tag.<name>. All filters must match; a list value matches any of its entries.
  • Fail closed. An unknown filter, an empty value or a malformed one is refused rather than ignored, because ignoring it would widen the query. A query that matches no device refuses the run (400 Target field 'fleet': the device query matched no devices), and so does one that matches more than query_max_devices (default and ceiling: HEGEMONY_INVENTORY_MAX_RUN_TARGETS). A query is never trimmed. A query on a field that is hidden or disabled for the submitted inputs refuses nothing, since that field's role is dropped anyway.
  • Run cap. When a run uses queries, all its device fields together may target at most HEGEMONY_INVENTORY_MAX_RUN_TARGETS distinct devices.
  • Values are checked the way the option source would read them: site_id takes site ids (or __null__ on its own), maintenance_state and sync_status their known states. A bad value in a query default is caught when the flow is saved.
  • Child runs. When a flow.run step is retried and the child run already exists, the same query gets the child's targets back rather than whatever matches now, so the retry finds its run.
  • Scope is the same as for picked devices: the run's organization plus the shared organization. The field's own option filters still check every device the query finds.
  • A field without allow_query: true refuses a query, so existing flows keep taking device ids only. A query default_value on such a field, or a malformed one, is a compile error (INVALID_FIELD_DEFINITION).
  • Audit. The run's submitted inputs keep the query ({"fleet": {"query": {...}}}), and each of the role's run targets records {"source": "query", "query": {...}, "matched": N} in its attributes.
  • Preview (POST /flows/{id}/interface/preview-resolve) resolves the query the same way and reports the same refusals as errors.

The run form shows a query default under the device picker and leaves the field empty, so run creation applies the query; picking devices replaces it. The builder has no query editor yet: set allow_query and the query in the flow's JSON or through Configuration Exchange.

Versioning, storage, and export ​

The authoring graph lives in definition_json["form"] — nowhere else. It is therefore:

  • versioned with the flow: form edits mark the flow dirty, are saved with the draft, committed with versions, and restored by revert/restore;
  • exported/imported with the flow in YAML bundles and git sync;
  • never stale: the runtime contract is compiled on demand from the graph (the compiler is a pure function), so a pinned version always resolves against its own snapshot.

Run-time resolution (authoritative) ​

The frontend is never trusted. At run creation the API:

  1. compiles the contract from the version's definition (compile errors reject the run with HTTP 400);
  2. handles inputs the contract does not declare: a manual run of a flow that declares fields is refused with HTTP 400 naming them; otherwise they are dropped, because a schedule, a webhook or a parent flow cannot correct them, and a flow that declares no fields takes no inputs;
  3. routes device-target field values into related_targets;
  4. evaluates visibility/enablement/requirement conditions — values submitted for hidden or disabled fields are dropped from inputs (a field's last value may still participate in other fields' conditions; the client and server evaluate conditions against the same form state, so they always agree on which fields show);
  5. applies defaults, coerces types, and runs validation rules. A value that still contains a template is only known once the worker renders it, so its checks become warnings. That holds for defaults and for templates someone was allowed to submit (see Templates in run inputs); a webhook's or a parent flow's values are plain text and are checked in full. A rule that compares against vars.NAME reads the run organization's variables, the same set its steps render: its own, over the shared organization's. Variables of any other organization are never read;
  6. enforces option membership for every select — static lists and dynamic sources (attachment.csv, inventory.*) alike. The submitted value must be one the source would actually offer given the submitted sibling values, so cascade constraints hold too (an emea region cannot smuggle in an amer datacenter). Because every entry point — API, schedules, webhooks, nested runs — resolves through this pipeline, the check covers them all. Template values are exempted as in step 5 (worker-resolved), and plugin sources opt in by implementing OptionSource.contains() (sources without it are skipped, never broken);
  7. applies the same membership rule to device-target fields. They route to related_targets rather than inputs, so they are checked separately — a device field narrowed by a cascade (e.g. "devices at the chosen site") or a fixed filter rejects a device the form would not have offered, instead of leaving that constraint to the picker UI. Rejections are reported by name — Target field 'Routers': device fra-edge-01 (09a48b03-…) is not one of the allowed targets — since a bare UUID tells the operator nothing about which device they picked. Sources whose values are opaque ids supply the names via OptionSource.describe_many(); sources whose values are already readable (CSV columns, static lists) leave it unimplemented and the value is shown as-is;
  8. persists the raw submission (submitted_inputs_json) and a provenance snapshot (resolved_inputs_snapshot_json) on the run for audit.

An options_filter edge into a device field therefore constrains it on both sides: the run form's device picker opens pre-filtered (its Site / Inventory source / Platform / tag controls locked to the cascade value), and run creation rejects anything outside that set. Only filter keys the device search understands are pushed into the picker (site_id, provider_id, platform, tag.*); a multi-valued parent has no single-key equivalent there, so the picker stays unfiltered while the server-side check still applies.

Templates in run inputs ​

A field's default may hold a template, written by whoever edits the flow. A value submitted for a run may hold one too ({{ ... }} or {% ... %}), and the worker renders it when a step reads it. A run input is not flow code, though: no review or flow version records it. So:

  • Only someone who may edit the flow may submit a template. The check is the permission for PUT /flows/{id} (flow:manage by default), so it moves with that action under Settings → Permissions. Anyone else gets HTTP 403 naming the fields. The same rule applies when a schedule's parameters are saved, because they are rendered at every firing.
  • A submitted template may not use secret(), env() or file(), from anyone, on a manual run, a schedule or Run Now (HTTP 400). A flow that needs a secret reads it in its own steps. A template may still read {{ vars.* }}, so an organization variable whose value calls secret() is readable this way too, as it is from the flow's steps.
  • A webhook's payload and a parent flow's values are data. The worker never renders them: a step that reads {{ inputs.message }} gets the text that was sent, braces and all. They are checked in full against their fields, so {{ 3 }} is not a number.

The run and schedule forms leave out a templated default that nobody changed, so the flow's own default applies and no permission is needed for it. A rerun copies the earlier run's values into the form, and starts as a manual run under these rules.

API ​

EndpointPurpose
GET /flow-interface/field-typesRegistered field type manifests
GET /flow-interface/option-sourcesRegistered option source manifests
GET /flows/{id}/interfaceGraph + on-demand compiled contract
POST /flows/{id}/interface/validateValidate a provided (unsaved) or the persisted graph
POST /flows/{id}/interface/optionsDynamic options for a field (cascading, search)
POST /flows/{id}/interface/preview-resolveDry-run resolution of form values

The graph itself is saved through the regular flow draft endpoints (PUT /flows/{id} with form).

The interface graph is the sole source of truth for form fields and device targeting - there is no separate inputs or target-roles mechanism.

Released as open source under the AGPL-3.0-or-later license. Development is sponsored by Rexonix s.r.o. Contact — [email protected].