Work with the Playbook Simulator

The Playbook Simulator provides a streamlined approach to develop playbooks with reduced time and effort.

Key features

• Lets you to work in a pre-production environment, testing actions and results without impacting production data (if the playbook is deactivated).
• Facilitates testing of each playbook step or block to confirm the required workflow.
• Lets you test of all possible playbook condition branches.

Using the simulator with your playbook

When using an existing playbook or creating a new one, start by turning on the Playbook Simulator. A green indicator at the top of the screen confirms that the simulator is active. If you use the Playbook Simulator on an active playbook, it impacts all incoming alerts that trigger the playbook. This is because saving a playbook with inserted simulation data applies it to live cases in production, potentially impacting the results.

1. Go to the Cases page, place your cursor on one of the alerts in the case, and click more_vert Alert Options, and select Ingest alert as test case. This creates a test case for running your simulated playbook on. Entities modified within test cases don't have any influence on entities in regular cases.
2. Move your cursor to the bottom of the Playbooks page and select a test case. Be sure that the selected test case matches the playbook you're running. A good way of checking that the case and playbook match is to click the Entities button and confirm that the playbook can process the entities within the test case.
3. Click Run. The simulator processes the steps, runs the actions, and provides the results.

Interpreting simulator results for each step

After you click Run, the first row in the console displays as if it was a live playbook.

Each simulated step presents various options, typically including: Case Data, View Results, Pin Results (or Insert Results). Manual steps prompt a button to input parameters, provide responses, and execute the step.

Case Data
The Case Data icon is at the bottom right.

The case data dialog shows the case information at a specific stage (after this specific action finished running). Case data dialog will be updated at playbook runtime with the current step results. If this step added enrichment to the case you will see it here. Because it shows information for the current state of the case (what the case looks like when the step finished running) – this data will be different for each step of the simulation console. Inspecting the case data of different steps will explain what was changed in the case between the different steps execution. There are different tabs you can click through which provide more information.

View Results
The next option is View Results. This action shows the action results of the current step. The information displayed here is similar to case overview/case wall – view results and also includes information on enrichments. You can see output message, tables, links, attachments in the main tab, and you can see action result, and JSON result (where present) in the technical details tab.
As with the previous option, there's also an option to tab through data. Another action you can take from the View Results screen is to click Set JSON result.
Set JSON result replaces the JSON sample of this action. You can change the JSON sample from the IDE and use it within the Expression Builder to extract data from the JSON result.

Pin Results
This option is available when a step is run successfully. Pin Results is a highly useful feature that lets you treat the outcome of an action as fixed. This can save you time by eliminating the need to wait for third-party results and reducing the number of queries to third-party services, thereby conserving credentials. In other words, when you rerun the playbook, this step is "passed over"; the code does not execute again, and the pinned results are used as is. You can also modify the outcome by inserting your own mock data. When you enable Pin Results, the action enters simulate mode, and the visual representation of the step typically changes from a blue background to a gray background, indicating that Simulate mode is active.

Insert Results
This option becomes available if a step has failed. Insert Results lets you manually insert simulation data so that the next time you run this step, it returns the simulation data as the result. Once you click this option, the action has the simulate mode enabled and the step changes from a blue background to a gray background to indicate that the Simulate mode is on. Script Result is a mandatory field for all steps in simulation mode.

Insert mock data

To insert mock data, you have a few use cases to consider:

• I want to build and test my playbook on the go. In this case I can run a step, view the results and understand how I can us it further along in the playbook.
• After a successful run, I want to pin the step results and save time by not running it again and again against third parties APIs.
• I want to change my step results to test my playbook in different scenarios. In this case I'll set different simulation data to influence conditions and actions that are using previous results. For example, if you have a playbook with a condition that branches off to two or more branches. You can experiment with the simulation data to "force" the playbook to take a different branch.

Insert simulation data

There are several ways to insert simulation (mock) data:

• Access the Playbook step configuration dialog
• Use Pin Results (or Insert Results) after a simulator run.

Playbook step configuration dialog

1. Click the step configuration dialog in the playbook and click the Simulate mode toggle to enable. The action appears in gray.
2. In the Action results, insert your simulation (mock) data – such as script result, JSON result by taking specific data from the JSON code. You can use enrichments from previous simulation runs or create custom enrichment keys of your own. Additionally, the JSON result can be loaded from the sample output by clicking the Load Sample button. The Load Sample button will load the action's Sample Output (a JSON result sample which represents the result that you would expect the action to return) as the simulated step JSON result. This option is particularly useful if:
   • The simulation was never run, and the output is empty.
   • The simulation failed and there are no results to be displayed.
   • Results are displayed (either from previously pinning or inserting them), but the goal is to override them with the sample.
3. This data will now be returned every time the step runs.

Pin Results

1. Click Pin Results next to the action. The step opens in Simulate mode by default.
2. The results from the latest simulation run will be pinned to the step. These pinned results can be used as is or they can be edited. The JSON result can be edited using the JSON editor or it can be overridden by clicking Load Sample. You can use enrichments from previous simulation runs or create custom enrichment keys of your own.
3. This data will now be returned every time the step runs.

Insert Results

1. Click Insert Results next to the action.
2. In the Action results, insert your simulation (mock) data – such as script result, JSON result by taking specific data from the JSON code. Additionally, the JSON result can be loaded from the sample by clicking Load Sample. You can use enrichments from previous simulation runs or create custom enrichment keys of your own.
3. This data will now be returned every time the step runs.

Turn off the Playbook Simulator

When you turn off the Playbook Simulator, it hides the bottom console, and any step in simulate mode reverts to regular 'live' mode. The exception is the playbook blocks—you must turn off the block simulator to close the simulation mode for it. Any inserted simulation mock data is saved for use the next time you turn on the simulator.

Work with playbook blocks

You can also use the Playbook Simulator to build a new playbook block. When a block is in simulation mode, all playbooks using this block also use the block's mock data.