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.

Limitations

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.