Updating Flows

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

Workflow

1. Export with Identity Metadata

From the Flows page, click a flow and choose Export for Update. This includes step IDs and a _metadata section that the update pipeline needs to match steps between your YAML and the live flow.

You can also use the REST API:

GET /api/v1/flows/{sys_id}/yaml?with_uuid=true

2. Edit the YAML

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

schema: nebula
name: Updated Flow Name
type: flow
trigger:
  type: record_created
  table: incident
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
    inputs:
      to: $find-caller.record.email
      subject: "Your incident was received"
      body: "We're on it."

3. Apply the Update

Open the YAML in the Editor and click Update. The tool computes a structural diff between the current live flow and your YAML, then applies only the changes.

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 at the bottom of an exported YAML file maps step IDs to internal ServiceNow identifiers. Do not edit this section 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

• Always export a fresh copy before editing to avoid conflicts
• Keep step id: fields stable — they're how the tool matches steps
• New steps don't need an id: — one is assigned automatically
• The tool handles published flows by temporarily reverting to draft, applying changes, and re-publishing