Updating Flows

Edit an existing flow by exporting it, modifying the YAML, and pushing the changes back.

Workflow

1. Export with Identity Metadata

flowctl --instance https://myco.service-now.com \
  --export <sys_id> --with-uuid > my-flow.yaml

The --with-uuid flag includes step IDs and a _metadata section. The update pipeline needs these to match steps between your YAML and the live flow.

2. Edit the YAML

Make your changes — add steps, modify inputs, reorder steps, remove steps.

steps:
  - action: lookup_record
    id: find-caller          # Keep existing IDs
    inputs:
      table: sys_user
      conditions: "email=$trigger.current.caller_id.email"  # Changed
  - action: send_email       # New step (no id needed)
    inputs:
      to: $find-caller.record.email
      subject: "Your incident was received"
      body: "We're on it."

3. Preview Changes

flowctl --instance https://myco.service-now.com \
  --update my-flow.yaml --dry-run

Shows the structural diff: which steps will be inserted, updated, deleted, or reordered.

4. Apply the Update

flowctl --instance https://myco.service-now.com \
  --update my-flow.yaml

The tool computes a structural diff between the live flow and your YAML, then applies only the changes — no full re-creation needed.

What Can Be Updated

Flow metadata — name, description, run_as, access, priority
Trigger — table, conditions
Step inputs — change field values, conditions, scripts
Step order — reorder steps within a container
Step nesting — move steps between containers
New steps — insert at any position
Remove steps — delete steps and their children
Containers — add/remove else, else_if, catch blocks
Variables — add, update, or remove inputs/outputs/variables

The `_metadata` Section

The _metadata section maps step IDs to internal ServiceNow identifiers. Don’t edit it manually.

_metadata:
  trigger_sys_id: abc123...
  top_level_try_uiid: def456...
  steps:
    find-caller:
      sys_id: aaa111...
      type: action
  containers:
    "uuid:else":
      kind: else
      uiid: bbb222...

Tips

Export a fresh copy before editing to avoid conflicts with changes made in Flow Designer
Keep step id: fields stable — they’re how the tool matches steps
New steps don’t need an id: — one is assigned automatically
Published flows are handled automatically: the tool reverts to draft, applies changes, and re-publishes

The web UI and REST API are available on the hosted version at flowctl.sh.