Run and monitor workflows created in Dynatrace Workflows

Latest Dynatrace

Building workflows goes hand in hand with running them. For example:

You add a new task or change a task, and now you would like to try your changes and run the workflow.
You want to look into executions, that happened or are still ongoing, and inspect the status or outcome.

Running a workflow creates an execution. An execution has all the details about the state of each task of the workflow that is run. Each task executes an action with a given input and might produce a result.

Let's take a closer look at the concepts involved while running a workflow.

Workflow execution

A workflow execution is the instantiation of a workflow. There can be as many executions of a workflow running at any given time as requested (within system capacity). A workflow execution is triggered manually via Workflows, automatically via an API call, a trigger event, or according to schedule.

A running workflow processes its tasks as defined by the workflow structure, which results in task executions.

Workflow execution states

These are all possible workflow execution states.

State	Description
`Running`	At least one task execution is idle or running.
`Success`	All tasks with matching task conditions have completed and there was no unhandled failed task (failed task has successor task).
`Error`	The workflow execution had at least one unhandled failed task. Running tasks are completed and no new task executions are triggered.
`Canceled`	The user canceled the workflow or task. Cancel attempts for running tasks and running action executions will complete.

Task execution

A task execution is the instantiation of a task within a workflow. It runs an action with the defined input and might return a result.

By default, a task will run if its predecessors ended successfully.
A task will run until the action ends (success, error), times out, or is canceled manually.

A running task always has at least one action execution. In the case of task retries or loop configurations, triggering multiple action executions might happen. The outcome of the task executions defines the final state of the workflow execution.

Task execution states

These are all possible task execution states.

State	Description
`Idle`	The task has not been triggered yet, as successor tasks didn't complete yet.
`Running`	At least one action execution is running or waiting to be started.
`Success`	The action execution completed successfully (in the case of a retry, the last action execution was successful, or for a loop, all action executions were successful).
`Error`	The action execution completed with failure (in the case of a retry, all action executions failed, or for a loop, at least one or the last action execution failed) or the task timed out.
`Skipped`	Predecessor tasks completed, state and custom conditions are unfulfilled, and the user configured the workflow to skip this task in this case or disabled the task.
`Discarded`	Predecessor tasks completed, state and custom conditions are unfulfilled, and the user configured the workflow to stop this task.
`Canceled`	The user canceled the workflow or task. Running action executions were completed.

Action execution

An action execution is the instantiation of an action (see Integrations). Invocation happens with the inputs defined on the task. Depending on the inputs and action implementation, it will either succeed or fail and might produce a result. For the processing of actions, the limitations for functions in the AppEngine apply. Action execution results can never be larger than 1 MB. The AutomationEngine is designed as a process orchestrator and isn't suitable as a data pipeline. Results larger than the limit will cause the task to fail. In case you need to work with data larger, you may want to use a custom JavaScript task to pull and store the data directly in its final destination.

The outcome of the action executions defines the behavior and final state of the task execution.

Action execution states

These are all possible action execution states.

State	Description
`Running`	Action execution is running.
`Success`	Action execution completed successfully.
`Error`	Action execution completed with failure.

Loop task, retry on error, and task timeout

Loop

The loop task option makes it possible for a task to iterate over a list of items.

While there is only a single task execution, there is an action execution for each iteration. The implications for a task are the following.

The task result is a list containing the results of the action executions.
The task log is a concatenation of the log of the action executions.
The task state is Success if all action executions succeed or Error if at least one failed.

Retry on error

The retry on error task option will retry a task based on a defined number of attempts and wait between retries by the given delay.

While there is only a single task execution, there is an action execution for each retry attempt. The implications for a task are the following:

The task state is Success with the first successful action execution and Error in case none succeeds.

Combined loop and retry on error

There is an option to combine loop task and retry on error.

Retries happen for failed iterations only.
Additional action executions occur for each failed iteration based on the retry configuration.
It's possible to rerun all iterations if one of the action executions involved fails.

Timeout

The task timeout always applies.

For a task loop or a retry attempt, the task will fail as soon as the task times out.
Any running action execution at this point will be completed, but its success or failure completion is not considered anymore for the resulting task state.

Execution retention period

Execution information is retained for 30 days from the start date of the execution. This is valid for workflow, task, and action execution information.

This also implies a workflow execution timeout of 30 days. After this period, no further processing will happen, as the execution state is purged.

Run a workflow

A workflow can be run manually via the Workflows App, via an API request, or via a trigger event or schedule.

To run a workflow manually

List the available workflows. This is the default view when you start the Workflows app.
Do one of the following:
- In the table, find the workflow, open the menu, and select Run workflow.
- In the table, select the workflow name to open it, and then select Run.
optional If the workflow has an event trigger defined, you'll be presented with a dialog where you can adjust the event context as you see fit. To confirm your changes, select Run.
The execution monitor opens and displays the current state of the execution.

Workflow authorization settings

A workflow always runs with a user context, the actor. You can find the actor of a workflow in the workflow settings ( in the workflow editor). By default, the last editor of a workflow is the actor.

You can control which permissions you authorize the workflow service to use if your user is the actor. The workflow authorization setting is available via the Settings menu in the upper-right corner of the Workflows app.

Running your first workflow for the first time in an environment requires you to configure the authorization setting for the workflow service. In a modal, you need to authorize the workflow service. Opting for the default option (Allow and run), your user's permissions are granted to the workflow service. You can return to the authorization setting to make a more restrictive configuration at any time.

The workflow service can never exceed the permissions of your actual user, no matter the authorization settings.

Run a workflow with inputs

When triggering a workflow via the Automation service API, you can provide inputs to the workflow. That is the recommended approach to passing information to the workflow execution.

Find details about the request in the Swagger documentation for the /workflows/{id}/run endpoint of the Automation service API.

This endpoint expects the following attributes in a JSON payload.

input: A user JSON object with properties for accessing workflows
params: A system JSON object with properties for accessing workflows, for example, passed from automatic event triggers

It's separated from input to avoid collisions with custom input provided via API.

Both are accessible in the workflow via the execution() expression. E.g execution()['input']['foo']

Execution monitor

If you run a workflow or go to an existing execution, you are presented with the execution monitor. In the execution monitor you can see if a task was successful or if it's failed.

The execution monitor consists of the following sections.

Workflow monitor after running first workflow successfully

Title section

The title section shows you the title of the workflow currently or formerly running.

To the right of the title, Running, Success, or Error indicates the status of the workflow execution.
Available controls include options to edit the workflow, cancel a running execution, refresh the data, rerun the last execution, or open the execution history of the workflow.

Execution graph pane

Below the title section, the execution graph pane shows the workflow, its tasks, and their runtime state.

The color and status label of a task node indicate the task's status.
Task nodes also display the runtime once they're in a final state.
Selecting the trigger node or a task node updates the details and log panes with the details of the selected item.

Log pane

Under the execution graph pane, the log pane shows the output of a task produced during its execution. The log should give you an idea of what happened during the task processing and provide details for analysis in case of an error.

Details pane

The details pane on the right provides access to the detailed attributes of the execution depending on your selection in the execution monitor pane.

Selecting the trigger node gives access to the attributes of the workflow itself (details, input, and parameters).
Selecting one of the tasks switches the details pane to attributes of the selected task (details, input, or result).

Detail

The Detail tab consists of

State: The state of the action.
State info: Additional information on the current state if any is available. For successful tasks, this field is usually empty. For failed tasks, this will show additional error information, such as the task was skipped because of a task condition. This error message is displayed in the log pane.
Started at: The time a task began to run.
Ended at: The time the task is completed.
Runtime: The length of time in seconds it takes to complete.
Conditions: The configured condition.

If you select a specific task, it also shows the action type of the task. Tasks with predecessors (not tasks directly connected to the trigger) also show the conditions and their evaluation results to let you analyze in detail why a task ran or not.

Input

The Input tab gives you access to the inputs and values passed to a task. You will see the evaluated value for any expression used in the input definition. This information, combined with the log and results, forms the audit trail of your execution.

Params

The Params tab is available only for the workflow when selecting the trigger. It provides access to the parameters passed to the execution, for example, the event context in case the execution was triggered by one.

Result

The Result tab is available only if you select a task on the left. It gives you access to the result produced by the selected task.

Monitor an execution

If you open an execution by running a workflow or open a monitor of an existing execution, the execution monitor shows. The execution monitor will refresh itself until the execution has reached a final state (Success, Error). You can discover more details in the monitor by selecting individual tasks and looking at their output in the log pane and their attributes in the details pane.

To actively change the state of an execution or an individual task, see the sections below.

Cancel a task

You can cancel a task so that you don't process all its loop iterations, but you can't actively interrupt and cancel a running task.

The running task will be processed but will end in Cancelled.
Further processing of the workflow and successor tasks depends on their condition configurations (for example, "run if success" or "run if error or canceled").

Open executions from the top navigation.
Select the execution from the list to open the execution monitor.
From the execution monitor pane, select the task that you want to cancel.
Select Cancel task in the details pane.

The task will keep processing (for looped tasks, its current iteration only), but end in Cancelled. Further processing of the workflow depends on task conditions configurations.

Cancel an execution

In case you triggered an execution by accident, you always have the option to cancel a running execution. Canceling an execution will cancel all currently running tasks and no further tasks will be started. The execution will end in state Cancelled.

Open executions from the top navigation.
Select > Cancel execution in the execution list or the upper-right corner of the execution monitor.

All running tasks will be completed, but no new tasks will begin, and the execution will end in status Cancelled.

Repeat an execution

During development, or to recover from a failure/incomplete state in third-party systems, you might want to repeat an existing execution. There might be this event trigger that is hard to reproduce, where it would be handy if you could repeat the execution after you made some changes to the workflow. Re-run means you want to leverage the input and params configuration of the original execution.

Open executions from the top navigation.
Select > Re-run execution in the list of executions or the execution monitor.
If the workflow defines an event trigger, you'll be presented with the event context as it was for the original execution. Adjust the values as you see fit and confirm with Run.

Re-run execution and params

In case you used expressions like {{ event() }} and you repeat an execution that was triggered by an event trigger, the expressions will have access to the event context from the original execution.