# Running Workflows

A workflow can be executed in several different ways depending on the need

- Manually executed

  The simplest method to execute a workflow is directly in the workflow builder itself. Either the entire workflow can be executed or only specific steps.

- Scheduled

  Workflows can be scheduled to run once at a specific time or reoccurring at specific times using the UI or a CRON-like syntax.

- From a notification

  In response to an event in Avantra, for example a Critical check, a workflow can be triggered to remedy the problem.

- Externally by an API call

  Using our SOAP API or our command line tools, workflows can be started and monitored externally to Avantra.

## Workflow variants

To simplify execution of a workflow with input parameters, a variant can be created to save pre-defined input parameters of a workflow. These variants can then be selected when starting the execution of a workflow.

Procedure: Creating a new variant

1. Choose Automation Workflows and double click on the workflow that you wish to add a variant to

2. Open the Variants tab and click the New button.

3. In the next screen you should give the variant a Name which will be used to select it when executing the workflow and optionally specify a Description to document the purpose of the variant.

4. Select a Customer that this variant applies to. The selection here affects user permissions to interact with this variant at execution.

5. Specify at max one variant with the Default configuration flag to default this variant for each new execution.

6. Marking a variant as Exportable allows the Workflow import and export function to export this variant for backup or use in a different Avantra.

7. Finally, in the Values section, specify the default values for each input parameter of the workflow.

8. Click the Apply button.

The variant is now created for use at execution or assigned to schedules.

| Variants can only be created with unique names to make it easier to select the correct one at execution time.

## Manual execution

Starting a workflow is easily accomplished in Avantra.

Procedure: Execute a workflow

1. Choose Automation Workflows and double click on the workflow that you wish to execute

2. Click the Execute button.

3. In the window that appears, if the workflow has input parameters:

   - select from one of the pre-created Variants, or

   - enter values for any input parameters as required

4. Click the Run

The execution log then appears. This window can be monitored or, the closed and viewed on the Executions tab or in the Automation Executions at a later time.

Workflows can also be executed partially byy selecting the steps that need to be executed and selecting the Execute selected button.

| When performing a partial execution of a workflow, if one or more inputs to a selected step are generated by steps not selected, these step inputs become workflow inputs and it is required to fill these in manually. Care should be taken to ensure the correct format is used to prevent errors.

## Workflow Schedules

Schedules are a great way to ensure regular tasks are executed automatically. A Schedule can be defined either using our UI or by using a CRON-like syntax to have greater control.

Procedure: Create a schedule

1. Choose Automation Workflows and double click on the workflow that you wish to schedule

2. Open the Schedules tab and click the New button.

3. In the popup that appears, give the schedule a unique Name.

4. Double click on the newly created line to edit its properties.

5. For workflows that have inputs, choose from the list of pre-created Variants to use at execution time.

6. Click the Edit Schedule to add schedule times and enter a timezone.

7. Fill in only one of the tabs of the dialog depending on requirements:

   - Non-Recurrent

     Specify a date and time that this schedule will run in the future. The schedule will not repeat.

   - Recurrent

     Specify a simple repeating pattern for daily, weekly, monthly or yearly activities with start and end dates.

   - Advanced

     Use the advanced tab to specify more granular or complex recurrence patterns in a CRON-like syntax. Enter 5 values each separated by a space to determine the pattern, for example `0 11 1 11 *`. See below for a more detailed explanation of this syntax.

8. Optionally, click the Info button to check Avantra’s understanding of the schedule and when the next run will be.

9. Click the OK button to close the schedule dialog.

10. Before clicking the Apply button, ensure the schedule is active by ensuring the Active box is ticked.

The schedule line will now appear in the table as active.

### Understanding the CRON-like schedule

When defining a schedule, the Advanced tab allows specification of a CRON-like schedule, for example `0 11 * * *`. There are five values here in a specific order separated by a space to define the schedule. These values are explained in the table below:

Name | Allowed Values | Allowed Special Characters
--- | --- | ---
Minute | 0-59 | , - * /
Hour | 0-23 | , - * /
day of the month | 1-31 | , - * /
month | 1-12 or JAN-DEC | , - * /
day of the week | 0-7 (0 or 7 is Sunday) or MON-SUN | , - * /

Therefore `0 11 * * *` means that a schedule will run every day at 11:00 AM. These are some more examples:

Expression | Meaning
--- | ---
0/5 * * * * | Every 5 minutes
0 * * * * | Every hour
0,30 * * * * | Every 30 mins
0 11 * * * | Every day at 11:00 AM
0 11 * * MON-FRI | Monday to Friday at 11:00 AM
0 9-17 * * MON-FRI | Every hour from 9 AM to 5 PM on Monday to Friday
0 11 1/5 * * | 11:00 AM every 5 days starting first day of the month

Always use the Info button on the Schedule window to validate the expression entered.

## Monitoring Workflows

When a workflow is executed, a dialog appears with the status of the workflow, which step it is executing now and outputs of those steps as they execute. For useful to get immediate feedback that a workflow has started and is executing, and for short running workflows this can be used to monitor a workflow until it finishes.

However, to continue working while this workflow executes, you can close this window and carry on your tasks while Avantra executes these steps in the background. The status of the workflow can then been seen either on the Executions tab of the workflow details or in the Automation Executions menu.

### Performing manual activities

Workflows can include a manual step in them. When a workflow gets to a manual step, the workflow pauses and waits for a user to continue the workflow or abort.

To interact with a manual step, open the workflow execution, and simply press the Confirm button.

### Stopping a workflow

Workflows can also be stopped, either while executing a step, when a step has failed or when waiting for a manual step to be confirmed. Simply click the Stop execution button in the toolbar when viewing the execution.

| If a workflow is executing a step and the Stop execution button is pressed, most workflow steps cannot be interrupted and will continue processing. Subsequent steps won’t be started after a stop is issued though.

### Dealing with errors

If a workflow step is configured with an On Failure value of Stop - Ask to resume or a Retry and the step fails with an error, the workflow pauses and asks the user how to deal with this situation.

The user can click the Stop button to completely stop the workflow or the Resume button to be then given the choice of skipping this step (useful if the action can be performed manually) or the step can be retried again if the error was caused by a temporary failure or can be addressed by altering the workflow parameters. See Changing Variables.

### Changing variables

If a workflow is paused, either by a manual step or if a step fails and is asking how the failure can be solved, you can use the Change variables toolbar button to inspect and change the values of the workflow inputs (entered to start the workflow) and the already executed step results that will be used in subsequent steps so that you can correct an entry.

This is very useful when running larger workflows and you realise you have incorrectly entered a password or file location that has caused an error.

| Caution should be taken when editing a step output in this mode to ensure the correct format is used to prevent further unexpected errors.

### Notifications

When starting a workflow, you can define who gets notified when workflow events happen, such as errors or manual steps, workflow start/end, etc. Tick the corresponding checkboxes while configuring the workflow to set up the notification.