Skip to content

user-interface.md

Latest commit

 

History

History
90 lines (55 loc) · 3.75 KB

user-interface.md

File metadata and controls

90 lines (55 loc) · 3.75 KB

User Interface

The Orchestrator plugin supports two primary modes of workflow interaction:

1. Direct Workflow Access

The user interface is accessible via the orchestrator button added in the Backstage sidebar. It provides a list of workflows and the option to run the workflows and view the results.

user interface

2. Template-based Workflow Integration

Workflows can also be invoked from Backstage software templates using the orchestrator:workflow:run action. When workflows are executed this way, a dedicated "Workflows" tab appears on the entity page, allowing users to view and manage workflow instances associated with that specific entity.

Key Features

Workflow Management

  • Browse available workflows
  • Execute workflows with custom parameters
  • Monitor workflow execution status
  • View workflow results and outputs

Execute Workflow Form Prepopulation

The Execute Workflow page supports prepopulating form fields from URL query parameters. When the workflow schema defines input fields, any query parameter whose name matches a schema property path will be used to prepopulate the corresponding form field.

Path format

  • For flat schemas, use the property name directly: ?language=English&name=John
  • For nested (multi-step) schemas, use dot notation: ?firstStep.fooTheFirst=test or ?provideInputs.language=English
  • For fields inside oneOf or anyOf branches, use the same dot notation: ?mode.alphaValue=test

Schema support

The prepopulation logic supports the full JSON Schema draft-07 spec, including:

  • Fields defined via $ref in $defs or definitions
  • oneOf and anyOf — the correct branch is resolved from the provided data
  • Array fields — use comma-separated values: ?tags=foo,bar,baz
  • Type coercion for numbers, integers, and booleans

Schema constraints

For fields with enum constraints in the schema, the query param value must match one of the allowed values. Case-insensitive matching is supported (e.g. ?language=english maps to English when the enum is ['English', 'Spanish']). Values that do not match any enum option are ignored and will not prepopulate the field.

Query parameters that do not match any schema property path are ignored and will not be merged into the form.

Reserved parameters

The following query parameters are reserved for navigation and are not used for form prepopulation:

  • targetEntity — Used to associate the workflow run with a catalog entity
  • instanceId — Used when re-running or viewing a specific workflow instance

Examples

/orchestrator/workflows/yamlgreet/execute?targetEntity=default:component:my-app&language=English&name=alice

In this example, targetEntity is excluded (reserved), while language and name prepopulate the form when those fields exist in the workflow schema.

/orchestrator/workflows/my-workflow/execute?language=English&mode.alphaValue=prefilled&tags=a,b,c

This example prepopulates a flat field (language), a nested field inside an oneOf branch (mode.alphaValue), and an array field (tags).

Entity Integration

  • Workflow tabs on entity pages
  • Entity-specific workflow instances
  • Integration with Backstage catalog

Template Integration

  • Scaffold integration via custom actions
  • Workflow execution from software templates
  • Automated workflow triggering

Navigation

  • Main Interface: Access via the "Orchestrator" sidebar item
  • Entity Workflows: Available on entity pages when workflows are associated
  • Template Workflows: Launched from software template execution

Permissions

The user interface respects the permission system configured for the orchestrator backend. See the Permissions Guide for details on access control configuration.