Workflows

This guide provides a conceptual overview of MintPress Workflows. After reading this guide, you should understand what workflows are, their key features, and how they are executed.

Overview

In MintPress, a workflow is a powerful feature that allows you to orchestrate multiple changes from a project's environments and assets into a single, executable process. Workflows enable you to model and automate complex operational procedures, such as multi-stage application deployments or infrastructure provisioning that spans several systems.

Instead of running a series of individual changes manually, you can define them once in a workflow and execute them as a single, consistent and repeatable unit, a workflow run.

Workflows can contain any of the following steps:

• changes
• wait steps
• approval steps
• other workflows

These steps can be grouped into stages, which can be executed sequentially or in parallel.

Versioning

Any time a workflow is modified, validated or published, a new version is created, providing a complete audit trail of how the workflow has evolved over time and who made the changes. This ensures that you can always review, compare, and revert to previous versions of a workflow if needed. Workflows stay in Draft until they are published, meaning they are ready to be executed.

The MintPress platforms provide a user-friendly UI for building and editing workflows collaboratively. Multiple users can work on a workflow definition, making it easy for teams to build and maintain their operational playbooks together. In addition, MintPress provides a templating language to enable you to refer to multiple environments and assets with ease, using the properties system.

Workflow runs

A workflow run is the execution of a published workflow version, it consists of one or more steps. Workflow runs can be triggered manually or via a schedule.

Workflow run execution

Just like changes, workflow runs have a pre-defined lifecycle and transition between states as they execute.

Since workflow runs are primarily designed to execute changes, they do not generate logs themselves. To see the logs of the changes that are executed as part of a workflow run, you can click on the change step in the workflow run step tree to view that change's logs. Approval and continuation steps persist who approved or continued them in the workflow run step tree.

Workflow run lifecycle

When a workflow run is created, its state is set to the pending state. A workflow run remains in the pending state until its steps are validated and processed. If the validation fails, any steps in the same workflow run that are still pending will be set to the aborted state.

When a workflow run starts executing it enters the queued state. Workflow runs and steps stay in the queued state while they are waiting for an OpsChain worker to start executing them (e.g. if all workers are already busy, a workflow run will wait until a worker is available). Whilst a change step is actively executing it is in the running state.

If the workflow step succeeds it transitions to the success state. If the step fails it transitions to the error state.

If a workflow run is cancelled by a user, all finalised steps (i.e. in the success or error state) remain in their existing state, and all pending, queued, or running steps are transitioned to the cancelled state. There is no rollback of any kind, steps that have not yet started will not start, and steps that are in progress are stopped immediately.

A workflow run may also remain in the pending state while waiting for any existing workflow runs of the same workflow (this behaviour can be overridden using workflow execution options).

Limitations

Although workflows can contain other workflows, it's advised against nesting a workflow within itself. This can cause a workflow run to loop indefinitely. MintPress will detect a first-level nesting of a workflow within itself and will prevent the workflow from being run. Indirect nesting is not detected or protected against.

Workflow execution options

By default, MintPress will only allow a single instance of each workflow to be running at any time. This restriction relates to the default change execution options for MintPress changes that restricts running multiple changes in the same MintPress project, environment or asset. Running the same workflow multiple times may cause this to happen and would slow the execution of the workflow.

If all the changes in your workflow perform logic that can be run concurrently, and their respective project, environment and asset allows them to be run in parallel, you can configure the project to allow concurrent workflow runs for the same workflow by modifying the allow parallel runs of the same workflow setting.

Workflow in the GUI

You can create a workflow via the GUI by clicking the New workflow button at the top of the workflows page, which will take you to the workflow editor.

Viewing a workflow's steps

To visualize the step tree of your workflow, go to the overview tab in the workflow details page.

Running a workflow

The workflow details page provides the following buttons to control the execution of the workflow::

Button	Description
Run workflow	Run the workflow, supplying an optional run description and properties overrides.
Schedule workflow	Schedule running the workflow, providing a schedule definition and conditional options to determine if and when the workflow is run.

Viewing workflow runs

The runs tab of the workflow details page provides a list of each time the workflow has been run. Clicking on a run will take you to the workflow run details page to allow you to view each step of the workflow run.

Each step can be viewed or actioned according to its type. If all the workflow's steps complete successfully, the workflow run will be marked as successful. If a workflow step errors or is cancelled, the remaining steps in the workflow run will not execute and the workflow run will be marked as errored or cancelled based on the status of the step that ended the workflow run.

Viewing workflow scheduled activity

The scheduled activity tab of the workflow details page provides a list of all the scheduled activity that have been created for the workflow. To remove a schedule, click on the checkboxes for the schedules you wish to remove, then select delete selected from the bulk operations drop down.