Following best practices for designing playbooks

Use the visual Playbook Editor

You don't have to know Python to create a playbook. The visual Playbook Editor allows developers to create playbooks using visual building blocks and execution flow lanes but without writing code. The Playbook Editor automatically generates the code for you. 

As you create your playbook, keep the following in mind about your blocks:

General

• Giving your blocks custom names helps with readability. 
• The description and notes fields let you provide useful information for future maintenance.
• Except for action blocks, all blocks run in the order they are called.
• The datapath picker only shows two levels, so more complex paths must be entered manually.

Start blocks

• Blocks without a path leading back to the start block will be ignored.
• You can choose to disconnect blocks as a way of commenting out a part of a playbook to stop it from running.

Action blocks

• A block can call more than one subsequent block, so multiple action blocks in a playbook can execute simultaneously and the order of their completion is arbitrary.
• The delay timer allows you to specify a number of minutes before a block runs.
• Using a wildcard in an artifact Common Event Format (CEF) data path makes the playbook more flexible for different types of data but can make CEF values harder to work with.

Filter blocks

• Filters produce a subset of data that matches one or more condition statements.
  • If there is only one condition, that path is not executed unless data matches the condition.
  • For two or more conditions, if data matches any filter condition, all matched paths are executed.
• Filter blocks can execute multiple paths in the playbook but they can be difficult to debug and manage. If you want to select just one of multiple available paths, use a decision block instead.

Format blocks

• If a parameter passed to a format block contains a list, it is inserted as a comma-separated list by default.
• You can merge static text and dynamic values.

Prompt blocks

• Approvers can be static users or roles, event owners, or the user who ran playbook.
• If the approver is a role, all users in the role are notified, and the first to complete prompt will cause the playbook to continue.

Utility blocks

• Use these blocks to promote an event to a case when an initial playbook investigates a new event and finds it to be significant enough to bring to human attention.

End blocks

• You do not need to configure the end block, but you can use it to pass values back to a parent playbook.
• The end block will run automatically as the final block and does not require any connections to function. You can add connections for clarity if needed, but they won't affect how the playbook runs.

Troubleshooting your playbooks

• If some users have trouble accessing playbooks, check the permissions.
  • When a playbook is executed automatically, the automation account in the playbook settings is used for permissions.
  • When a playbook is executed manually, it is limited to the permissions of the current user.
• If a playbook doesn't run on a container, it might be out of scope. Automation playbooks execute when artifacts are added to a container, which normally only happens during data ingestion for a new event. After an automation playbook runs on a new artifact, it is marked updated and will be out of scope if a playbook runs on the container again.
• If a decision block doesn't return a TRUE condition when you know it should, check whether the block was left on the default case-sensitive setting.
• OR joins can cause problems in block logic; therefore, using them is not best practice.
  • If a downstream block won't run, it might be waiting on input from an action block that didn't run because of a bad OR join.
• Loops in playbooks can be endless if a user can't respond. Additionally loops can sometimes lead to unexpected join errors.
  • A better configuration for handling user prompt timeouts is to call another playbook that escalates to a designated manager or group about the issue.
• Good playbook design uses smaller, more focused playbooks that interact to perform complex tasks. If your playbooks don't work as expected, consider breaking up single, complex playbooks into modular ones that call each other. These are easier to maintain.
• If the custom lists you created to store data on Splunk SOAR aren't performing as expected, check that
  • Your list has a maximum size of 2GB. 
  • The list you created is acceptable for users to read, write, and delete on. There is no per-object permissioning for these lists.
  • You are not allowing more than one playbook to update the list. There is no per-row locking.
  • Your playbook searches aren't using == or != to search the list. They must use the in or not in operators.