Inventory View: Testing Playbooks

This view is very handy when creating playbooks, as it shows the processing of sample data for the selected step. The Inventory view shows the full package data, the variables and graphs that enter the step, and the variables and graph that exit the step. A step that has processed the package turns green in the playbook editor view.

The Inventory View is a part of the PRO Playbooks perspective, and is by default a tab in the same window as the Step Editor view. The Inventory View can also be opened in any perspective by choosing Window→Show View and selecting Inventory.

The view shows the input and output for a selected step in the active playbook. To add sample data that will show up in the Inventory view, choose either Load Package or Load Sample Input from the Playbook's options menu.

  • Choose Load Package if the playbook starts with a Subscribe or Playbook step.
  • Choose Load Sample Input if the playbook starts with an Ingest step.
  • Choose Run Now if the playbook starts with a Schedule step.
    • The Run Now option creates an empty package.

Notes: The package or input you load into the playbook is only available for the playbook for use while it is open for editing. When DarkLight is restarted, you will need to add the sample again. Once you have added a package or input to the playbook, it will run that data through the playbook each time you make a change and click the Save Playbook button.

TIP: Copying an Event from ELK (Kibana)

If you are using an ELK stack to collect incoming data, DarkLight only uses a specific portion of the JSON. Switch to the JSON tab, and double-click just to the left of the curly bracket for the _source variable. This will select the whole object and let you copy it to your clipboard.

Show me

Load Package/Load Sample Input Options

  • Paste a source file (JSON, CSV, etc.)
  • or Click the Browse button to choose a text file
  • Check the Debug Mode checkbox to store data for each step for use in the Inventory view
  • Uncheck the Debug Mode checkbox if you want to run the package through without saving results for each step. Use this option if the playbook has a lot of splits in it that might run into memory issues. Note that if you uncheck Debug Mode you will not be able to see the results of each step in the Inventory view.
  • The input will be stored with each playbook while that playbook is open in the editor, and the playbook will run automatically each time it is saved. If you do not want it to run automatically when you save, click the Clear button to remove the package input.

Use the Inventory View to Turn an Input into a Package

The Inventory view's Raw tab can be used to create a package from a raw input.

  1. Use the Load Sample Input option to put a raw event through the first playbook
  2. Click on the Broadcast step and look at the Inventory view's RAW tab.
  3. Select the Package Out text (Tip: double-click a word, then use Select All)
  4. Copy the text to your system clipboard

You now have a package you can paste into the Load Package dialog in the subscribing playbook.

As soon as data is loaded in, the steps in the playbook that have processed the package turn green. A white step in the playbook indicates that it did not receive the package from the previous step. A red step indicates that step caused an error. The error details are in the Error tab and in the Console.

Inventory Tabs

The top of the Inventory view has a section for viewing the results of split packages (see next section for details) and four tabs: Raw shows the full JSON package as it came into the step and out of the step. Data In shows just the graphs and variable data that came into the step. Data Out shows the graphs and variable data that came out of the step. Error shows any details if the step turned red during the test. Additional error messages are in the Console.

Viewing Multiple Packages

If the playbook uses a Split Package Step, the steps that processed multiple packages will show how many packages were passed to which steps. In this example, 100 packages exited the Calculate step, and then in the Value Number Filter step, 6 went down the TRUE side while 94 went down the FALSE side.

In the same split example, the Inventory view shows that 100 packages (records) were seen by the selected step. Click the left/right arrows to increment through the steps in the order they were processed. For example, in the screenshot above, the rawInput first column values are 730, 920, and 990. Since the Inventory view is set to show the second record, the value of the oneline[0] variable is 920.

Many steps save their results in an output variable. Common steps used to store values in variables are Step: Query Package, Step: Query Knowledge Base, and most of the steps in the Transform and Query categories.

Variables can be one of three types, and many of the steps will indicate which type they output:

Icon Output Type FreeMarker Version
Single Value (Scalar) ${examplevar}
List (One-Dimensional Array) ${examplevar[0]}
Table (Two-Dimensional Array) ${examplevar[0][0]
This SELECT query will output a Table variable, even if there is only one result. When referring to this variable later, you would use the form department[0][0]

The Inventory View can help you know which FreeMarker templates you need to use to reference a specific value in a variable. In addition to the label hints, you can click on a value and copy the generated FreeMarker expression from the Template field.

  • Single Value (Scalar) ${ }
  • List (One-Dimensional Array) ${[*]}
  • Table (Multi-Dimensional Array) ${[*][*]}
  • help/inventory
  • Last modified: 2019/08/02 00:36