Workflows
A workflow is how you orchestrate a series of steps to be performed as a single unit of work. Workflows let you sequence work across multiple environments and assets, add human checkpoints, and call other workflows - all from a single starting action.
Workflows are versioned and can be collaboratively edited. They also support a templating language so you can refer to multiple environments and assets using MintPress's properties.
Supported step types
A workflow can contain any of the following step types, grouped into stages whose steps run either sequentially or in parallel:
- Changes - execute an action against an asset.
- Wait steps - pause until a user manually continues the step.
- Approval steps - pause until a user (or member of an LDAP group) approves or rejects the step.
- Other workflows - call a previously published workflow as a child of this one.
Stages and wait steps can also branch: a stage can run extra steps when its children fail, or run one of several arms depending on the workflow's properties, and a wait step can let a person pick which steps run next. See branching stages and letting a person choose what runs next.
See the step types reference below for the full set of properties each step type accepts.
Take care when nesting workflows - it is possible to create a workflow that indirectly calls itself and therefore never ends.
Workflow list
The first tab on this page lists all the workflows of a selected project.
Each row includes:
| Column | Description |
|---|---|
| Name | Displays the name of each workflow. |
| Version | Displays the latest version of the workflow, and whether it is a draft version or a published one. |
| Code | Shows a unique identifier for the workflow. |
| Description | Provides a short summary or purpose of the workflow. |
| Created by | The user who created the workflow. |
| Created at | Timestamp for when the workflow was created. |
| Updated at | Timestamp for when the workflow was last updated. |
| Archived | Whether the workflow is archived or active. |
Buttons & links
| Buttons & links | Function |
|---|---|
| Project dropdown | Select the project to filter the workflows by. The project is part of the page's address, so the list can be bookmarked or shared. |
| Search bar | Filter the contents of the table based on these criteria. |
| Columns | Hide or display columns in the table. |
Clicking on a specific workflow will redirect you to its details page.
Workflow editor
The workflow editor page allows you to create and edit workflows. It features a tab system, allowing you to switch between different workflows while editing them. The editor is composed of four main panes: the workflow details and actions at the top, the YAML editor, the tree view preview and the logs pane. Each is described below.
To create a new workflow, click the New workflow button, or choose Workflow from New in the top bar on any screen, which picks the project you are viewing for it to be saved to. Any workflows you already have open are available as tabs on this page. Each tab, including an unsaved draft, has its own address, so the browser's back and forward buttons move between them. Edit on a workflow anywhere in the GUI opens it here. As you edit the YAML definition, the tree view on the right updates to preview how the workflow will run.
Workflow details and actions
The top of the editor shows the workflow's details and the actions available for it.
When creating a workflow that has not been saved yet, this area displays Local workflow, indicating the workflow exists only in your browser and is not yet available to other users. A Save button lets you persist it for the first time, prompting you for the workflow's project, name and code.
Once a workflow has been saved, this area shows its project, name, current version and whether that version is a draft or published, along with the following actions:
| Button | Function |
|---|---|
| Run | Allows you to open the run workflow dialog if the currently loaded workflow in the editor is published. |
| Discard changes | Discards the changes made to the workflow. |
| Save changes dropdown | Allows you to save the changes to the current version or create a new version with these changes. |
| Validate | Validates the workflow - will show an error in the logs pane if it does not conform to the expected workflow schema. |
| Publish | Publishes the current version of the workflow. If the current version has not been validated, it will be validated first. If validation fails, the workflow will not be published. |
Until you save a workflow, its definition is kept only in your browser's local storage. If you clear your local storage before saving, an unsaved draft may be lost.
Editor pane
The editor pane holds the YAML definition of the workflow. When creating a new workflow, it is pre-populated with a template definition to get you started, and it offers autocompletion for step properties, target paths and action names as you type.
At the bottom of the editor pane, the Quick add buttons insert ready-made step snippets so you don't have to write them from scratch:
| Quick add | Inserts |
|---|---|
| Action | A change step. Fill in the target path and action name. |
| Workflow | A child workflow step. Fill in the target project, workflow and version. |
| Wait | A wait step. |
| Approval | An approval step. Fill in the name and the users/LDAP groups that can approve it. |
| Sequential | A sequential stage that you can add child steps to. |
| Parallel | A parallel stage that you can add child steps to. |
See the step types reference for the full list of properties each step type accepts.
Tree view
The tree view on the right side of the editor renders a live preview of the workflow as you edit it, showing the stages and steps in the order they will run and how they are nested. This is the same view used to follow a workflow run, so it is a quick way to confirm the structure matches your intent before validating or publishing. When the workflow uses variables, the preview reflects how the workflow resolves with the values you provide. A branching stage shows each of its arms, so you can check every path the workflow can take.
Logs pane
The logs pane records events for the current workflow - when it was created, modified, validated and published. When validation fails, the validation error is shown here, pointing you at the part of the definition that needs fixing.
Using variables in the workflow
You can use properties to dynamically set targets, actions and names based on properties values. In workflows, variables are represented by double curly braces, e.g. {{property_name}}. When clicking on the Validate button, the Validate properties overrides dialog will show you the identified variables and allow you to validate the workflow with values specified by you.
When running the workflow, the properties overrides will be used to resolve the variables. If the provided overrides are invalid or not provided, an error message will be shown in the Run workflow dialog.
{{...}} variables are substituted once, when the run is created. A when condition is checked later, as its step or stage starts, against the properties as they are at that moment.
Read more about properties in the properties concept page, and about how a run's overrides resolve these variables in workflow run property overrides.
Step types reference
Every entry in a workflow's steps list (and in a stage's children, on_failure, on_success, always and on_cancel lists, an arm's children and a wait step's choices) is a step. The type property determines the kind of step. When type is omitted, MintPress infers it from the other properties present:
- a step with
actionis a change step - a step with
targetbut noactionis a workflow step - a step with
requires_approval_fromis an approval step - any other step is a stage.
A wait step has no property that identifies it, so it must always set type: wait.
The sections below list each step type and the properties it accepts. A property marked as required must be present for the step to validate.
Change step
Executes an action against a single asset.
| Property | Required | Description |
|---|---|---|
target | yes | The full MintPress path to the asset to run the action on, e.g. /projects/hello_world/environments/dev/assets/managed_server. |
action | yes | The action to run on the target. |
template_version | no | The asset template version to source the action from. Defaults to the target's current template version at runtime. |
name | no | A human-readable name for the step, shown in the editor and run views. |
start_time | no | A scheduled start time in ISO8601 format (e.g 2026-06-02T10:00:00Z). The step waits until this time before running. |
property_overrides | no | Properties to override or add to the target's configured properties for this run. |
ignore_failure | no | When true, the workflow continues if the change fails. See continuing when a step fails. |
when | no | A condition on the target's properties. When it does not match, the step is skipped. See running a step only when a condition holds. |
Change step with multiple targets
Runs the same action against several targets. Replace target with targets and, optionally, template_version with template_versions.
| Property | Required | Description |
|---|---|---|
targets | yes | A list of MintPress paths to run the action on. |
action | yes | The action to run on each target. |
template_versions | no | A list of template versions, in the same order as targets. |
run_as | no | sequential (default) or parallel - whether to run the action on the targets one at a time or all at once. |
name | no | A human-readable name for the step. |
start_time | no | A scheduled start time in ISO8601 format. |
property_overrides | no | Properties to override or add to the targets' configured properties for this run. |
ignore_failure | no | When true, the workflow continues if a target's change fails. See continuing when a step fails. |
on_failure, on_success, always, on_cancel, recover, retry_from, abort_on_reject, abort_on_cancel | no | Steps to run depending on how the changes finished, as on a stage. See rolling back a multiple target change. Cannot be combined with ignore_failure or when; put the step in a stage that has them instead. |
Wait step
Pauses the workflow until any user with access to the workflow manually continues it.
| Property | Required | Description |
|---|---|---|
type | yes | wait. |
name | no | A human-readable name for the step. Defaults to Wait. |
reset_on_retry | no | When true, the step needs to be continued again if the workflow is retried. Defaults to true. In an action, a plain wait step defaults to false. |
choices | no | A list of choices, each with a name, an optional label and its children. The user picks one when continuing the step. See letting a person choose what runs next. |
default | no | The choice used when the step is continued without one: automatically, in bulk, or through the API or CLI without a choice. |
when | no | A condition on the workflow's project properties, merged with the run's property overrides. When it does not match, the step is skipped. |
Letting a person choose what runs next
Give a wait or approval step choices to have the person continuing it pick which steps run next. Each choice has a name, an optional label shown on its button, and its children, which can be empty:
- type: wait
name: Promote to DR?
requires_approval_from:
ldap_groups: [ops-leads]
choices:
- name: promote
label: Promote DR now
children:
- type: change
name: Promote DR
target: /projects/weblogic/environments/dr/assets/app_domain
action: promote
- name: skip
children: []
default: skip
When the run reaches the step, the step shows a button for each choice, in the order written, in place of Continue or Approve. A choice without a label shows its name with underscores replaced by spaces and a capital first letter, such as Skip. Picking one runs that choice's steps, and the steps in the other choices are set to skipped. On an approval step, only the approvers can choose, and they can still reject the step instead.
A step with a default choice uses it when it is continued without a choice: by Continue selected or Approve selected in manage activity, or through the API or CLI without one. A choices step without a default is left waiting by bulk actions, and a request without a choice is rejected with the list of choices. See choosing without the step's buttons for the API and CLI.
When the run is retried, the person is asked to choose again if the step that failed is inside the step or in one of its siblings, unless the step sets reset_on_retry: false.
Approval step
An approval step is a wait step that can only be continued by specified users or LDAP group members, who have to approve or reject it. Adding requires_approval_from to a wait step turns it into an approval step.
| Property | Required | Description |
|---|---|---|
type | no | wait. Can be omitted, as requires_approval_from identifies an approval step. |
requires_approval_from | yes | An object naming who can approve the step. Must contain user_names and/or ldap_groups. |
requires_approval_from.user_names | – | A list of usernames allowed to approve the step. Must contain at least one username when defined. |
requires_approval_from.ldap_groups | – | A list of LDAP groups whose members can approve the step. Must contain at least one LDAP group when defined. |
name | no | A human-readable name for the step. Defaults to Approval. |
reset_on_retry | no | When true, the step needs to be approved again if the workflow is retried. Defaults to true. In an action, a plain approval step defaults to false. |
choices | no | A list of choices, each with a name, an optional label and its children. The approver picks one when approving the step. See letting a person choose what runs next. |
default | no | The choice used when the step is approved without one. |
when | no | A condition on the workflow's project properties, merged with the run's property overrides. When it does not match, the step is skipped. |
Workflow step
Calls a previously published workflow as a child of the current one.
| Property | Required | Description |
|---|---|---|
type | no | workflow. Can be omitted when the step has no action. |
target | yes | The OpsChain path of the workflow to run, e.g. /projects/hello_world/workflows/backup-environment. |
version | no | The version of the child workflow to run. If omitted, the latest published version is used. |
name | no | A human-readable name for the step. |
start_time | no | A scheduled start time in ISO8601 format. |
property_overrides | no | Property overrides to supply to the child workflow. |
ignore_failure | no | When true, the workflow continues if the child workflow run fails. See continuing when a step fails. |
when | no | A condition on the child workflow's properties. When it does not match, the step is skipped. |
By providing the same property in the property_overrides key multiple times, the child workflow will be called once for each value. You can then use the run_as property to control the execution strategy of these child workflow steps.
Take care when nesting workflows - it is possible to create a workflow that indirectly calls itself and therefore never ends.
Stage
Groups a set of child steps to run sequentially or in parallel. Stages can be nested inside other stages to build more complex structures.
| Property | Required | Description |
|---|---|---|
run_as | see note | sequential to run children one at a time, or parallel to run them all at once. Required unless arms is set. |
name | yes | A human-readable name for the stage. |
children | see note | The list of steps nested within the stage. Required unless arms is set. |
on_failure | no | Steps to run if any of the stage's children fails. See running steps when a stage fails. |
on_success | no | Steps to run if all of the stage's children succeed. |
always | no | Steps to run last, whether the stage's children succeeded or failed. |
on_cancel | no | Steps to run if the run is cancelled while the stage is running. on_failure and always do not run on a cancel. |
recover | no | When true, the stage ends in warning if its on_failure steps succeed, so the run carries on. Defaults to false. |
abort_on_reject | no | When true, a rejected approval among the stage's children stops the stage with no on_failure or always steps, instead of failing it. See when an approval is rejected or a step is cancelled. |
abort_on_cancel | no | When true, a step among the stage's children that is cancelled on its own stops the stage with no on_failure or always steps, instead of failing it. |
retry_from | no | Where a retry restarts a stage whose on_failure steps ran: start (default) or failed_step. |
arms | no | A list of arms, each with a name, a when condition, its own children, which can be empty, and an optional run_as (default sequential). The stage runs the first arm that matches. A stage with arms must set type: stage. See choosing an arm by property. |
default | no | The name of the arm to run when no arm's when matches. |
when | no | A condition on the workflow's project properties, merged with the run's property overrides. When it does not match, the whole stage is skipped, including its arms and handler steps, all shown as not taken, and the run carries on with the next step. When it matches, the stage chooses its arm or runs its handlers as usual. |
reset_on_retry | no | When true, a retried run checks the stage's when again and chooses an arm again, if the step that failed is inside the stage or in one of its siblings. Defaults to false. |
ignore_failure | no | When true, the workflow continues if one of the stage's children fails. See continuing when a step fails. |
The steps generated by the multiple target change and multiple child workflow (via property overrides) steps will follow the execution strategy defined in the step themselves. For example, if a step is defined with run_as: parallel, all of its children will run in parallel, regardless of the execution strategy defined in the stage.
Branching stages
A few terms used here:
- A stage groups steps under a name, and its
childrenare the stage's main steps. - A handler is a list of steps that runs depending on how the main steps finished:
on_failure,on_success,alwaysoron_cancel. - An arm is a named list of steps that runs only in some cases: a handler, one of a stage's
arms, or one of a wait step'schoices. - A step is skipped on request when you skip it with
skip_steps, and not taken when it belongs to an arm that did not run. The step tree shows which.
A stage can branch in two ways. With on_failure, on_success, always and on_cancel, it runs extra steps depending on how its children finished. With arms, it runs one of several arms and none of the others. Arms that do not run are set to skipped, and the run's step tree shows why.
These are the same branches an action can declare in actions.rb, and they finish the same way. Two things differ: a plain wait or approval step asks again on retry by default in a workflow but not in an action, and a when condition compares values differently from an action's run_if. See branching, and how a group with handlers finishes for what each arm does when something fails or the run is cancelled.
When a workflow version is published, MintPress also checks that:
- every arm of a stage, and every choice of a wait step, has a
name, and every stage arm has awhen - the names of a stage's arms, or of a wait step's choices, do not differ only in case
- a step name is not used in more than one arm of the same stage, or more than one choice of the same wait step. It can be repeated within one arm
- a
whencondition'starget:exists and you can read it. In a workflow that uses{{ }}variables, this is checked when a run is created instead - a change step with a single target has no
on_failure,on_success,alwaysoron_cancelsteps. Put it in a stage that has them instead
Running steps when a stage fails
- type: stage
name: Patch prod with rollback
run_as: sequential
children:
- type: change
name: Patch app domain
target: /projects/weblogic/environments/prod/assets/app_domain
action: patch_weblogic
on_failure:
- type: workflow
name: Restore prod
target: /projects/weblogic/workflows/restore-prod
always:
- type: change
name: Notify release channel
target: /projects/weblogic/environments/prod/assets/app_domain
action: notify
If a step in children fails, the on_failure steps run, then the always steps. The stage then ends in error and the run stops, even when the on_failure steps succeeded. Set recover: true for the run to carry on once they have. The stage, and the run, then finish warning rather than success, so a notification subscription or event filter on success does not match a run that recovered. A stage with recover: true whose on_failure steps were all skipped recovered nothing, so it still ends in error, and its on_failure arm shows Recovered nothing: none of its steps ran. A stage with handlers cannot set ignore_failure; use recover: true instead.
When an approval is rejected or a step is cancelled
By default, a rejected approval among a stage's children, or one of its steps cancelled on its own, makes the stage fail, so its on_failure and always steps run. Set abort_on_reject: true or abort_on_cancel: true on the stage to stop it instead, with no handler steps. Cancelling the whole workflow run is different: only on_cancel steps run.
A rejected approval counts anywhere inside the stage's children, including in a plain stage nested in them, and so does a step cancelled on its own inside such a stage. A nested stage with on_failure, on_success or always steps of its own, or with ignore_failure, decides its own outcome. abort_on_cancel reacts only to the stage's own direct children that were cancelled. A rejection or cancellation inside an on_failure, on_success or always list fails that list like any other failure. A failure in on_success or always stops the remaining handlers, which are set to aborted and show Not run: on_success failed, while a failure in on_failure still lets always run. A stage stopped by its own flag fails its parent, so the run does not finish success.
Cleaning up after a cancel
Cancelling a workflow run stops it. A stage that was running when the run was cancelled runs its on_cancel steps, and so do the stages that contain it, once the steps that were running have stopped. Their actions are stopped before the on_cancel steps start. on_failure and always do not run on a cancel, and cancelling the run again stops the on_cancel steps too. The stage then ends in cancelled.
While the on_cancel steps run, the run's status in the GUI reads Cancelling – cleaning up, and its cancel_requested attribute in the API is true.
Cancelling a paused run does not wait for it to be resumed: the on_cancel steps run straight away. The run then ends as cancelled, still flagged as paused.
A workflow step that runs a child workflow run or a change is cancelled at once as well. The child is told to cancel, and its own on_cancel steps may still be running after the parent workflow run has finished as cancelled.
Rolling back a multiple target change
A change step with multiple targets takes the same keys directly, without a stage around it:
- type: change
name: Patch the app tier
targets:
- /projects/weblogic/environments/prod/assets/app_domain
- /projects/weblogic/environments/prod/assets/ohs
action: apply_patches
run_as: parallel
on_failure:
- type: change
name: Remove the patches
targets:
- /projects/weblogic/environments/prod/assets/app_domain
- /projects/weblogic/environments/prod/assets/ohs
action: uninstall_patches
run_as: parallel
always:
- type: change
name: Notify release channel
target: /projects/weblogic/environments/prod/assets/app_domain
action: notify
If the patch fails on any target, the patches are removed from every target. A child workflow step with a list of property_overrides takes the same keys.
Choosing an arm by property
- type: stage
name: Region rollout
arms:
- name: apac
when: { property: region, in: [au, nz] }
children:
- type: workflow
name: APAC rollout
target: /projects/weblogic/workflows/apac-rollout
- name: eu
when: { property: region, equals: eu }
children:
- type: workflow
name: EU rollout
target: /projects/weblogic/workflows/eu-rollout
default: apac
When the run reaches the stage, MintPress checks each arm's when from the top and runs the first that matches, or the default arm if none does. Without a default, a stage where no arm matches fails with an error naming the property and its value, shown on the stage in the step tree.
An arm's when is checked against the project's properties merged with the run's property overrides. A change that sets a project property earlier in the run can therefore steer a later stage.
Running a step only when a condition holds
Give a change or child workflow step a when to run it only when its target's properties match:
- type: change
name: Migrate search index
target: /projects/weblogic/environments/prod/assets/search
action: migrate_index
when: { property: index_migrated, not_equals: true }
The condition is checked against the step's target, with the step's own property_overrides applied, as the step starts. When it does not match, the step is set to skipped and shows Not taken: index_migrated is true. To run a step only once, have its action set a property on its asset when it finishes, here index_migrated, and test that property in when. To let a run override that, set the property in the step's property_overrides from a workflow variable.
Conditions
A when names a property by its dotted path and one test:
| Condition | Matches when |
|---|---|
{ property: <path>, equals: x } | The property equals x. |
{ property: <path>, not_equals: x } | The property does not equal x, or is not set. |
{ property: <path>, in: [x, y] } | The property equals one of the listed values. |
{ property: <path>, not_in: [x, y] } | The property equals none of the listed values, or is not set. |
{ property: <path>, exists: true } | The property is set. Use false to match when it is not set. |
<path>uses the same dot notation as workflow variables, for exampleregion.name.- A property that is not set never matches
equalsorin; it is not an error. - Values are compared with their types as written. Numbers compare by value, so
1matches1.0, but a number never matches a string. - Add
target:to read another project, environment or asset's properties, for examplewhen: { target: /projects/weblogic/environments/prod, property: region, equals: eu }. A condition withtarget:reads that node's own properties, without the run's property overrides or the step'sproperty_overrides. - A
whenis accepted on every kind of step (change, workflow, wait, approval and stage) and on each arm of a stage. A change or workflow step reads its target's properties, with its ownproperty_overridesapplied. A wait, approval or stage step, and each arm, reads the project's properties merged with the run's property overrides. To read another node instead, addtarget:. - A condition is checked as its step or stage starts, and again on a retry when the step's
reset_on_retryis true, which is the default for wait and approval steps but not for stages. A{{...}}variable inside a condition is substituted when the run is created, soequals: '{{target_region}}'compares the live property with the run's override.
when: compares values with their YAML types. Numbers compare by value, so 1 matches 1.0, but a number never matches a string: equals: 1 does not match a property whose value is "1". Quote the value in when: if the property holds text.
when: { property: replicas, equals: 1 } # replicas: 1 or 1.0 → matches; replicas: "1" → no match
when: { property: replicas, equals: '1' } # replicas: "1" → matches; replicas: 1 → no match
Retrying a run with branches
A retried run keeps the arm each stage chose, unless the stage sets reset_on_retry: true and a step that failed is inside the stage or in one of its siblings. Wait steps with choices default to asking again. Only a failure among the stage's own children counts; a failure in an on_success or always list does not. A stage whose on_failure steps ran is retried from its first child, which reruns children that succeeded, unless it sets retry_from: failed_step. A stage with recover: true that recovered is treated as done, and a retry for a later failure does not run it or its on_failure steps again. When a stage that sets reset_on_retry: true chooses a different arm on retry, the new arm runs, and an arm that succeeded in the original run keeps its status, times and the change or child workflow run it ran. A retry cannot change the run's property overrides, so a stage that failed because of an override value needs a new run.
Skipping steps in branches
skip_steps patterns match steps inside arms and choices by their names, and a pattern that names a stage covers everything inside it. An arm's own name is not matched. A skipped region never skips an approval step: the run still reaches every approval in it.
| In a skipped region | What happens |
|---|---|
| Change, workflow and plain wait steps | Skipped, whether named in skip_steps directly or inside a skipped stage |
| An approval step | Still asks for approval |
A when or arm selection on the way to an approval | Still evaluated, which runs that step's own action |
A wait step with choices whose choice leads to an approval | Still asks for the choice |
| An approval in an arm or condition that is not taken | Skipped as not taken |
on_success and always of a stage entered only to reach an approval | Skipped, unless they hold an approval, and not listed as arms taken |
Steps that did not run show as skipped, as requested; a stage whose steps ran shows its real outcome.