Designing a Runbook with Visual Designer

Use the visual designer to design and create custom runbooks in Fleet Application Management. The designer provides a drag interface with an option to add code so that you can create and edit runbooks more easily. Runbook can be written in YAML or JSON. However, you can create a runbook without the need to author it in native JSON or YAML by using the visual designer.

With the visual designer, you can perform the following tasks:

Design a runbook by using the runbook components.
Streamline the runbook execution.
Configure conditional statements with the condition builder.
Configure conditional task executions based on product components, input and output variables, or both.
Configure error handling.
Illustrate runbooks provided by Fleet Application Management.
Clone illustrated runbooks to help you create custom runbooks where you add your code in the source or designer mode.

As you create a runbook, the visual designer validates your work and automatically generates code. You can review the generated code or export it for local development. After you create the runbook, you can save it, publish it, and examine the results on the Console.

The visual designer has the following interface components in the Design view:

The actions pane on the right side contains the Components and Properties tabs.
The canvas in the center is a placeholder where you design the runbook. You can drag the components from the actions pane such as parallel or rolling resource groups, and drag tasks into these groups. You can change the order of the components on the canvas by placing them in the order in which you want the tasks to be run, or select actions to configure properties or handle errors.
The canvas also contains the edit icon next to each task component to view and modify the runbook task.
To view the automatically generated YAML or JSON code for the runbook as you're using the visual designer, select Code view on the canvas. When you update the YAML or JSON, the changes are automatically generated in the designer mode.

Actions Pane

From the actions pane, you can select components to drag into the work area on the canvas. The pane contains the following items:

Components Tab

The Components tab provides a set of components that you can drag into the runbook's work area on the canvas. These components are a new task, parallel task group, parallel resource group, and rolling resource group.

Important

To add a task, you must first add a parallel or rolling resource group. A task must be inside a group. For more information about the usage of group types, see Creating a Runbook.

New task: Use this button to create tasks for a runbook. You can now add a task that can run a script by specifying the action type as a script.
Parallel task group: Any tasks part of a parallel task group are run parallel on a resource (Compute and database resources) that are part of a fleet.
For example, If a fleet has two resources and two tasks (task1 and task2) that are part of the parallel task group, task1 and task2 run parallel on resource1 and resource2.
Parallel resource group: Any tasks part of a parallel resource group are run parallel across resources (Compute and database resources) that are part of a fleet. Within a resource, the tasks that are part of a parallel resource group run sequentially.
For example, If a fleet has two resources and two tasks (task1 and task2) that are part of the parallel resource group, task1, and task2 are executed sequentially on resource1 and resource2, and execution on resource1 and resource2 happens in parallel.
Rolling resource group: Any tasks part of a rolling resource group run sequentially across resources (Compute and database resources) that are part of a fleet. Within a resource, the tasks that are part of a rolling resource group run sequentially.
For example, If a fleet has two resources and two tasks (task1 and task2) that are part of the rolling resource group, task1 and task2 are executed sequentially on resource1. After resource1 tasks are complete, task1 and task2 are executed sequentially on resource2.

Properties Tab

The Properties tab provides settings to control the conditional statements and configure error handling of the components you add to the canvas. After you add a component to the work area on the canvas under Tasks or Rollback tasks, configure it to meet your use case. Select the properties icon () of the component to configure its properties and options. You can also see the YAML or JSON code by selecting Code view. The properties are available for a runbook, groups, and tasks.

Runbook Properties

The following are the two properties for a runbook:

On failure of tasks: The option you select for this property is the default value for all groups and tasks inside a runbook.
Run on: The option you select describes where and how tasks are run. It can involve scheduled instances, self-hosted environments, or instances selected based on the outcomes of previous tasks. The following are the subproperties of Run on:
- Instances specified by schedule: This property is used for conditional execution of a runbook on a target when the condition evaluates to true. It is best suited for managing product stack workflows within a runbook.
- Self-hosted instance: This property helps you locate and select a self-hosted instance for post-provisioning tasks
- Instance specified by previous task: This property indicates that the execution of a task relies on the completion of a prior task.

Group Properties

The following are the five properties of a group:

On failure: The option you select for this property decides the next set of actions if one of the tasks of a group fails. The execution of the runbook on the target continues if you select Continue, the execution of the product runbook on the target stops, and the execution of the product stack runbook on the action group stops if you select Abort, and the execution of the runbook moves to the rollback step if you select Rollback. Based on the rollback scope, the rollback action can be on the target or action group level.
Precondition: Specifies the condition using input variables of the current task and output variables of all previous tasks. A task is executed on the target only if the condition evaluates to be true.
Run on: Specifies the condition using the target product name (for product stack runbook), product properties, and component name, and a target's component properties. A task is executed on the target only if the condition evaluates to be true.
For example, in the Oracle WebLogic Server and Java Patching product stack runbook, to run a task only on the Oracle WebLogic Server target if its java_version property value is 1.8.0_391 and when the ADMIN_SERVER component is available, enter the following condition.
```
target.product.name == "Oracle Weblogic Server" AND target.product.properties.java_home == "1.8.0_391" AND target.product.components.ADMIN_SERVER.properties.Server == "AdminServer"
```
Pause execution: An option that halts the runbook execution until you intervene or the set duration lapses. The pause happens before a task is run.
Notification: Notifies you by using the OCI Notification service about the task status.

Task Properties

Tasks include an extra property in comparison to a group. The following is the description of the property:

Output variable mapping: For the Run a script task type, the output of the script logs are parsed to evaluate the value of the input variable with a pattern match of $$VARIABLE=VALUE$$.

For example, if a task depends on the output of the previous task, perform the following steps for mapping the input variable:

Select the output variable checkbox and add an output variable. The Fleet Application Management script execution ensures that the output variable is populated.
In the next task, select the input variable checkbox and add an input variable.
Map the input variable name to the previous tasks output variable name using Output variable mapping.
The Fleet Application Management script now parses the output logs to identify a pattern such as $$VARIABLE=VALUE$$.

Library Tab

The Library tab of tasks provide a list of ready-to-use reusable tasks that exist in Fleet Application Management or that you created. You can use the drag handle icon ( ) at the right corner of a task to drag it into the runbook's work area on the canvas. The library displays only the relevant tasks for a runbook based on the product or product stack and OS type.

Rollback Tasks

To roll back a defined task if it fails, you can add a group and then add the tasks to roll back within the Rollback tasks placeholder on the work area of the canvas. To roll back, ensure you select the On Failure task property as Rollback under Tasks for the specific task.

Note

You can scope the rollback to a target or action group levels. This scoping means Fleet Application Management runs the rollback tasks on a specific target or all groups of targets. The rollback tasks run on the target that fails if you scope for a target, whereas the rollback tasks run on all the group of targets if you scope for an action group.

Canvas

After you determine an action to add to the visual designer, drag a component into the work area of the canvas. To change the order of the components, use the drag handle icon ( ) at the right corner of a component to drag it to a different place on the runbook's work area. This new action is added to the work area and its code is automatically generated.

Keyboard Shortcuts for Navigation

The visual designer supports the following keyboard shortcuts when designing runbooks.


Keyboard Shortcut	Action
Tab	Navigate the focus to the next runbook element.
Shift+Tab	Navigate the focus to the previous runbook element.
Arrow keys	Move a component after that's on the canvas. For example: Move a new task component within a group on the canvas by pressing the left arrow key. Rearrange tasks or groups on the canvas after selection when the focus is on the elements' drag handle icon ( ).
Spacebar or Enter/Return	Select a component from the Components or Properties tab, or a runbook element.
Esc	Cancel the move of a component onto the canvas, or any action before it's triggered.
Spacebar or Enter	Trigger an appropriate activity when the focus is on any of the components, properties, or runbook elements. For example: Place a component at the current position after selecting it. Switch on the toggle for rollback tasks configuration. Place the selected group on the canvas after it's moved by using the arrow keys for the parallel resource or parallel task group components. Place a new task component within a group on the canvas after moving it by using the respective arrow keys. After this action, press the keyboard shortcut (Spacebar or Enter) to open the create task dialog box for the task.

Oracle Cloud Infrastructure Documentation