Splunk® SOAR (On-premises)

Build Playbooks with the Playbook Editor

The classic playbook editor will be deprecated soon. Convert your classic playbooks to modern mode.
After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:
This documentation does not apply to the most recent version of Splunk® SOAR (On-premises). For documentation on the most recent version, go to the latest release.

Convert classic playbooks to modern playbooks

If you have been using playbooks created with the classic playbook editor, you can now convert them to modern playbooks that use the modern Visual Playbook Editor.

The conversion tool is currently available only through the command line interface.


Be aware of the following limitations when using the conversion tool.

Unsupported scenarios

Playbooks with the characteristics described below will not convert to modern playbooks because they are not currently supported in the modern Visual Playbook Editor.

  • An action block has multiple assets, either from the same app or from different apps.
  • A filter or decision block has multiple conditions that connect to the same downstream block.

Do not run the conversion tool on modern playbooks. Modern playbooks are already in the appropriate format and running the tool on them will result in creating an invalid playbook file.

Follow-up required before setting to active

After converting your playbooks, check the converted files before setting them to active. Newly converted playbooks are set to inactive, so you can test them.

  • Run the playbook manually in your development or test environment to verify that it runs as expected.
  • Review the code and linkages to ensure they look correct.

Keep the following points in mind:

  • When converting playbooks with child playbooks, both the main and child playbooks are converted. After conversion, always check the linkage between the playbooks.
  • Even if the classic playbook was marked active, the converted modern playbook is marked inactive.

Conversion features

Note the following features of the conversion tool before you begin:

  • The conversion tool will not overwrite your existing playbook. It creates a copy of your existing classic playbook with a suffix at the end (by default, modern) so you can distinguish the modern from the classic versions of the playbook.
  • When converting a playbook with one or more child playbooks, the conversion tool also attempts to convert the child playbooks.

Convert classic playbooks with the command line interface

To use the playbook conversion tool, type the following command. Arguments are described in the table after the command.

phenv classic_to_modern [-h] [-d] [-s SUFFIX] [-w WORKERS] [-v {0,1,2,3}] [--no-color] [--skip-checks] repo/ repo2/playbook_name ... [repo/ repo2/playbook_name ... ...] repo

In this example, the classic repository is local, the classic playbook name is classic_pb, the target repository is local, and the suffix for the converted playbook is _modern:

phenv classic_to_modern local/classic_pb local -s "_modern"

The conversion tool automatically marks newly converted, modern playbooks as inactive. Test the newly converted playbook before setting it to active. For details, see the Follow-up section earlier in this article.

Argument Required? Description
 repo/ repo2/playbook_name ... Yes List of repositories or playbooks to convert to modern playbooks. Provide only the repository name not the full repo path. If you specify multiple repositories, the tool will convert every playbook in every repo.
 repo Yes Output repository for the newly converted playbooks. Provide only the repository name not the full repo path.
 -h, --help No Display the help message, the information in this table, and exit.
 -d, --dry-run No Use this option to see which playbooks would be converted without performing the conversion.
 -s <SUFFIX>, --suffix <SUFFIX> No Suffix added to the names of converted playbooks in the conversion process. Default is "_converted". Only alphanumeric characters and "_" are allowed as part of the suffix.
 -w WORKERS, --workers WORKERS No Number of workers running the conversion tool. Default is 20. Increasing the number of workers to might affect performance of while playbooks undergo conversion.
 -v {0,1,2,3}, --verbosity {0,1,2,3} No Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
 --no-color No Don't colorize the command output.
 --skip-checks No Skip system checks.

Error Messages

During playbook conversion, you might see the following error messages. This list can help you troubleshoot issues with the conversion process.

Message Description
Could not find the playbook <playbook_name> to create an association with playbook <playbook_name> Could not find the child playbook in the specified repository. Both the main and child playbooks are successfully converted. You must manually update the linked playbook.
Parent playbook has child playbooks and parent playbook contains custom code. Both parent and child playbooks are converted successfully. Check the link between the main and child playbooks and correct if needed.
Invalid output scm Invalid output repository. Specify a valid repository to save the new playbooks in.
Could not map key pin-to-hud for utility block A utility block in your playbook has pin to hud functionality, which is not supported in the API for the modern Visual Playbook Editor. Your playbook is converted but might require you to make additional updates.
Could not get api definition for pin-to-hud <playbook_name>: pin_to_hud_sample A utility block in your playbook has pin to hud functionality, which is not supported in the API for the modern Visual Playbook Editor. Your playbook is converted but might require you to make additional updates.
Could not load playbook utilities json Contact Splunk Support.
Last modified on 26 September, 2023
Use playbooks to automate analyst workflows in   Choose between playbooks and classic playbooks in

This documentation applies to the following versions of Splunk® SOAR (On-premises): 6.1.1

Was this topic useful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters