Playbook Steps

Playbook steps are the foundational elements of playbooks, designed to follow a predefined sequence that enhances investigation and response efficiency. A playbook is built using triggers, actions, and flows.

At the core of playbooks are steps, which represent distinct actions or data processing tasks during the playbook's execution. Steps are linked in sequences to define the flow of the playbook, starting with the Trigger step. For more information, see Trigger Steps.

Editing or Removing a Playbook Step

To edit or remove an existing playbook step, double-click the step to reopen it. From there, you can edit the step or delete it by clicking Delete Step.

Connecting Steps and Removing Step Connections

To connect a playbook step, hover over the step to reveal connection points. Select a connection point and drag the arrow connector to the step you want to link.

To remove a connection between steps, hover over the arrow connector between the steps until a red "X" appears. Click X to remove the link.

Actions Available within Playbook Steps

Each Playbook step includes icons for Info, Reference Playbook (only for the Reference A Playbook step), Edit, Clone, and Delete actions, allowing you to perform various actions directly within the step:

• Info: Displays additional information about the step (if available).

• Reference Playbook (applicable only to the Reference A Playbook step): Opens the 'Referenced' playbook in a new window. This allows users to view the referenced playbook's contents without losing context of the current playbook's flow.
  

  Note: The Reference Playbook will open in a new window only when users select the reference playbook from the Playbook Reference drop-down list in the 'References' step and not when user refers to a playbook using Dynamic Values (jinja).
  

• Clone: Creates a copy of the current step and opens this step with the name as Copy of %Step Name%. All properties of the original step are copied to the cloned version, which you can edit and save.

• Edit: Reopens the step for editing its properties. After making changes, save the step.

• Delete: Deletes the step entirely from the playbook.

Playbook Actions used for Extending Playbook Steps

Variables

To add a variable to a step, click Variables in the footer of the step or use the Variables section within the step. Variables allow you to store and access custom expressions within the playbook, for example store the output of the step directly in the step itself, providing flexibility in your playbook design. Therefore, instead of frequently using the Set Variable step to o capture specific response data, you can directly use variables within the step itself.

Caution: Do not use reserved words, which are listed in the List of reserved keywords section, as variable names.

To insert dynamic values:

• Type $ and select from the list of suggested variables.

• Select Input/Output to search for variables, inputs, and step results

• Select Functions to search for and add 'Utility' functions.

• Click More Options and choose from the following options:

  • Select Switch to Advanced Editor to add jinja for advanced expressions and create complex conditions.

  • Select Test to check the validity of the Jinja and the output before adding the Jinja to the Playbook.

Loop

To iterate the playbook step, click the Loop link in the footer of the playbook step. There are two types of loops: 'for each' loop and 'do until'.

for each loop

The input for the for each loop is an array of objects and the for each loop iterates over an array of objects. Use the reserved keyword item to access each object in the array. For example, to iterate over indicator objects:

[{"name":"Indicator Name1"},{"name":"Indicator Name2"},{"name":"Indicator Name3"}]

Access each object using vars.item.name. You can optionally add a 'condition' to the for each loop, based on which the loop to determine when the loop executes.

The 'for each' loop can run in Sequential or Parallel execution mode. Sequential execution processes one item at a time in a serial manner, while parallel execution uses multiple independent paths to processes items in parallel threads for improved performance.

do until loop

The do until loop executes the step at least once and continues to executes the step until the specified condition is met or the retry limit is reached. You can configure the number of retries the playbook step will execute to meet the condition and also the delay in seconds before the step gets re-executed in a loop. By default, the number of retries is set to 3 and delay is set to 5 seconds.

In a do until loop, you can access the current step's result using vars.steps.<step_name>.keyname notation. For example, use vars.steps.<step_name>.message == 'Success' to retry a connector action until it succeeds.

Caution: Do not use do until with when or for_each.

Condition

To add a condition to a step, click the Condition link in the footer of the playbook step. This adds the When field where you can define an expression (condition) that determines whether the step executes. If the condition is met, then the playbook step is executed. If the condition is not met, then the playbook step is skipped.

To insert dynamic values, click More Options, then choose Input/Output to search variables, inputs, and step results, or choose Functions to search for and add 'Utility' functions. Choose Test to check the validity of the Jinja and the output before adding the Jinja to the Playbook.

Note: If you use when without a for each loop, the condition applies to the entire step and it is the first thing that is evaluated for the step. If you use when with the for each loop, then the condition applies to each item in the loop.

Mock Output

You can use mock output (in JSON format) for a step to simulate real outputs for debugging purposes. Mock output will override the actual step output when the playbook is run.

Tooltip: To enable mock output, either trigger the playbook with the Use Step Mock Output option or add a variable named useMockOutput and set its value to 'true' in the trigger step. If this variable is set to false or not declared, the playbook will use actual step outputs. Also, ensure that you write useMockOutput as is since this variable name is case-sensitive.

Ignore Error

You can configure a step to continue executing even if it fails by clicking the Yes/No button next to Ignore Error. If this option is enabled, the status of this step will be Finished with Error in the playbook log. To view the log, click the Execution Logs tab.

List of Reserved Keywords

Following is the list of reserved words that must not be used as 'Variable' names:

• 'items'

• 'result'

• 'input'

• 'request

• 'values'

• 'keys'

• 'files'

• 'env'

• 'message'

• 'resources'

• 'step_variables'

• 'do_until'

• 'ignore_errors'

• 'when'

• 'for_each'

• 'cyops_playbook_iri'

• 'cyops_playbook_name'

• 'collaborationNote'

• 'inputVariables'

• 'displayConditions'