Convert classic playbooks to modern playbooks

The classic playbook editor will be deprecated soon. Convert your classic playbooks to modern mode.

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

Conversion features

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

• The conversion process 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 process also attempts to convert the child playbooks.

Custom code does not necessarily follow strict coding standards and the conversion tool, as a best-effort tool, might not be able to automatically migrate your custom code from a classic playbook into a modern playbook. See the section below about required follow-up steps when converting playbooks.

Make sure that all of your classic playbooks use Python 3.x. For information, see Convert playbooks or custom functions from Python 2 to Python 3.

Do not attempt to convert modern playbooks. Modern playbooks are already in the appropriate format and attempting to convert them them will result in creating an invalid playbook file.

Currently unsupported scenarios

Some scenarios that were supported in the classic playbook editor are not currently supported in the modern Visual Playbook Editor.

Playbooks with the characteristics described below will not convert to modern playbooks.

• 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.

Important: Playbooks with the characteristics described below will convert to modern playbooks. Some functionality that was present in the original, classic playbook is not available in the converted playbook.

• Datapaths for artifact CEF and headers in action blocks.
  In newly converted playbooks, these datapaths are not available in the modern VPE when configuring downstream blocks.

Some playbooks require additional configuration before they are functional. Refer to the Follow-up required before setting to active section later in this article.

Convert classic playbooks within the user interface

This section describes converting your playbooks from the Playbook List.

You must convert playbooks one at a time to ensure that you can test the converted playbooks before using them.

To convert a playbook while you are viewing it, select Convert to Modern and continue with Step 4 in the process below.

To convert your playbooks from classic mode to modern mode, follow these steps:

1. Open . From the Home menu, select Playbooks.
2. At the top of the page, select the Classic mode tab to display only classic playbooks in your organization's repositories. These are the only playbooks you need to convert.
3. Select the checkbox corresponding to a playbook you want to convert, then select Convert to Modern.
4. Specify a suffix to add to the names of converted playbooks to distinguish them from the original playbooks. The default suffix is "_modern". Use only alphanumeric characters and "_" in the suffix and make sure that the total number of characters in the playbook name and suffix combined is 250 or fewer.
5. Specify the repository to store the newly converted playbooks.
6. Select Convert.
7. Read the message that appears.
   • If the playbook converted successfully, review the playbook, including linkages to other playbooks, and test it before setting it to Active. Refer to the next section to to ensure you complete required follow-up steps.
   • If the playbook did not convert successfully, follow instructions in the error message. See the Error Messages section later in this article.
8. Select Close.
9. Repeat these steps for all of your classic playbooks.

Keep track of which classic playbooks you have converted. The conversion process does not change your classic playbooks or their names, so all classic playbooks, whether converted or not, appear in the '''Classic mode''' playbook list.

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.
• Make sure to convert all of your playbooks from classic to modern mode. Check all of your repositories and include drafts and inactive playbooks if you might use them in the future.

Specific scenarios:

• Classic playbooks with uppercase or camel case (camelCase) names: The Modern VPE uses all lower case characters for names, including snake case (snake_case). After you convert your playbooks to modern mode, the names of your customized playbook blocks and functions, variables, and data paths are all lower case. Make sure that all references to these names are also lower case, matching the intended element. Save the playbook, test it, and set it to active.
• Classic playbooks with custom code: After you convert your playbooks, in the custom code sections, check your custom code, including variable name capitalization, as described in the previous bullet. Make any needed corrections to the custom code and its references. Save the playbook, test it, and set it to active.
• Classic playbooks with Prompt blocks: Classic playbooks with Prompt blocks convert successfully and require specific follow-up action, because playbooks in modern mode require Questions for Prompt blocks. Open the converted playbook in the modern playbook editor and make sure that you entered a Question for the Prompt block configuration. For details on Prompt blocks, see Require user input using the Prompt block in your Splunk SOAR (Cloud) playbook.
• Classic playbooks containing synchronous playbook blocks: Follow-up steps are based on whether the synchronous playbook block contains custom code.
  • Without custom code: Save the converted, modern playbook. Test it and set it to active.
  • With custom code: In the converted, modern playbook, copy the code for the synchronous playbook block. Delete the playbook block. Re-add the playbook block and the custom code. Save the playbook, test it, and set it to active.
• Close connection lines: If your classic playbook has connections that are very close to each other, the modern playbook might create an extra connection.
  Before you convert a playbook, spread out your playbook blocks so your connections are not close or overlapping. Then convert the playbook. Save the converted playbook, test it, and set it to active.

Error and Information Messages

During playbook conversion, you might see the following messages. These lists can help you troubleshoot issues with the conversion process.

Error messages

These messages provide additional information when playbooks cannot be converted.

Error message	Additional information
Could not save playbook <new playbook name>. A playbook with that name already exists in the specified repository. Specify a different suffix or repository and try again.	The new playbook is not converted. Check that you have not already converted this classic playbook.
Invalid output repository: <repository name>. Specify a valid repository to save the new playbooks in.	The new playbook is not converted. Check that the output repository exists and is spelled correctly.
A <block type> block in your playbook has <functionality name> 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.	Your playbook is converted but might require you to make additional updates. The specified block type in your playbook contains functionality that was present in classic mode, but is not supported in modern mode. See the Limitations section at the top of this article.
An upstream node has multiple links to a single downstream block. Cannot convert this playbook because this feature is not supported in modern playbooks. Redesign the playbook in modern mode.	The new playbook is not converted. Redesign the playbook in modern mode without the multiple links to a single downstream block. See the Limitations section at the top of this article. If you need assistance, contact Splunk Support.
An action block contains multiple assets. Cannot convert this playbook because this feature is not supported in modern playbooks. Redesign the playbook in modern mode.	The new playbook is not converted. Redesign the playbook in modern mode without the multiple assets in a single action block. See the Limitations section at the top of this article. If you need assistance, contact Splunk Support.
Could not load playbook utilities json. Contact Splunk Support.	Contact Splunk Support.

Information messages

These messages appear when playbooks are converted successfully and there is additional information you need to know.

Information message	Additional information
Could not find the child playbook <playbook name> in the specified directory to create an association with playbook <playbook name>. Check the link from the parent playbook and update if needed.	Both parent and child playbooks were converted. Check the link from the parent playbook and update if needed.
Parent playbook contains custom code and has child playbooks. Check the link between the main and child playbooks and update if needed.	Both parent and child playbooks are converted successfully.

Dismiss the notification banner for all users

A banner displays across the top of the screen to alert users to the important shift from classic playbook mode to modern playbook mode. Each user can dismiss the banner themselves, after they have reviewed it. If you choose, you can remove the banner for all users. If you remove the banner, make sure to share the information about the shift to modern playbook mode.

To remove the playbook migration notification banner for all users, use the following code:

curl --location -k --request POST '<deploymentURL>/rest/system_settings/features' \
-u "<admin_name>:<password>" \
--header 'Content-Type: text/plain' \
--data-raw '{
    "set_feature_enabled": false,
    "feature": "classic_playbook_deprecation_banner"
}'

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 required before setting to active 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.