Customize workflow settings

The app Settings page automatically discovers every installed workflow owned by the app and congregates its safe, configurable Actions inputs. Apps do not need a settings.workflows declaration to get a useful settings page. Credentials, secrets, hidden fields, notices, and unsupported controls are filtered on the server.

Use settings.workflows when you want to customize presentation or give a discovered input a stable product-oriented key. Labels, descriptions, field types, options, defaults, required state, and editor hints still come from the node's Actions catalog definition.

settings: {
  workflows: [
    {
      key: 'write-post',
      label: 'Write a Social Post',
      description: 'Control how the writing model behaves.',
      workflow: ref('workflowDefinitions', 'writePost'),
      fields: [
        {
          key: 'emoji-policy',
          stepKey: 'generate_post',
          property: 'emoji',
          section: 'Writing preferences',
        },
        {
          key: 'temperature',
          stepKey: 'generate_post',
          property: 'temperature',
          label: 'Creativity',
          section: 'Model behavior',
        },
      ],
    },
  ],
}

The workflow reference must target an installed workflow definition. stepKey must identify a node step in that workflow, and property must match a property exposed by that node in the target server's Actions catalog. key replaces the automatically generated stable settings identifier for that binding.

Multiple workflows

Every owned workflow is listed automatically. Add another settings.workflows entry only when another workflow needs presentation overrides. The Settings page presents a workflow selector and keeps each workflow's fields grouped separately.

Presentation overrides

The app may override label, description, or section to make a technical property clearer in its domain. Inputs omitted from the declaration remain visible through automatic discovery. A user can hide noisy inputs from their own view and restore them from the compact N hidden menu. Hiding is a local display preference and never changes workflow data.

Persistence and upgrades

Saving updates only server-discovered, safe Actions parameters on the installed workflow. The installation records those values as overrides. A managed app remains protected from arbitrary workflow editing, while this narrow settings path is allowed. During a catalog upgrade, overrides whose workflow and property bindings still exist are reapplied after the new workflow definition is installed.

Reset to app defaults restores every exposed field in the selected workflow to the values authored by the currently installed app version (falling back to the Actions default when the workflow omits a value) and removes those installation overrides. Discarding changes only restores the last saved values in the browser and does not write to the workflow.

If a workflow needs deeper technical changes, users can choose Open workflow from the Settings page. Managed apps must be cloned before making arbitrary canvas edits.

Authoring rules

• Prefer good Actions metadata because safe configurable inputs are exposed automatically.
• Prefer the Actions property's existing options and structured editor hints.
• Mark credentials, secrets, notices, and internal-only inputs with the appropriate Actions metadata so automatic discovery excludes them.
• Keep stable workflow, step, field, and property keys across compatible upgrades.
• Query GET /api/v1/apps-layer/platform-schema to inspect the target server's current node catalog.