Customize the format of your playbook content

Use the Format block to craft custom strings and messages from various objects.

You might consider using a Format block to put together the body text for creating a ticket or sending an email. Imagine you have a playbook set to run on new artifacts that does a basic lookup of source IP address artifacts. You want to take the results of that lookup, format the results, and send the information as an email. You craft your playbook so that the action results are available to the format block. See Use custom names.

To configure a format block, perform the following steps:

1. Drag and drop the half-circle icon attached to any existing block in the editor. Select a Format block from the menu that appears.
2. Configure the template parameter variables by clicking in the Parameters field and then searching for the parameter you want to use. You can select data from any upstream block. For details on specifying datapaths for the first part of this process, see Specify data in your playbook. You will use these datapaths in the following formatting steps.
3. Repeat this process for each variable. The first variable is identified as {0}, the next as {1}, and so on.
4. In the Template field, craft a message using the variables you define.

You can also configure Advanced settings for a format block. Use the Delimiter box to specify an alternate separator to use when joining parameters that result in a list together. The default separator is ",". Use the Drop None checkbox to select whether or not you want to drop the "None" values from the resulting lists of parameters. By default, the "None" values are included. For more information on other Advanced settings, see Advanced settings.

Additionally, you can click the Info tab to create a custom name for the block, add a description for the block, and add a tooltip to the block.

Example of defining a template

This example defines a template:

IP address: {0}
IP address country: {1}
IP address reputation: {2}

The message returned as a result of this template looks like this:

IP address: 1.2.3.4
IP address country: United States
IP address reputation: Malicious

If multiple events are picked up at the same time, you see the following message:

IP address: 1.2.3.4, 10.11.12.13
IP address country: United States, Turkey
IP address reputation: Malicious

To make each set of values display on its own line, wrap %% around a formatting block. For example:

%%
The IP address {0} originates from {1}.
%%

Wrapping %% around a formatting block produces results like this:

The IP address 1.2.3.4 originates from United States.
The IP address 10.11.12.13 originates from Turkey.

To use a number in your formatting and not have it confused with a variable number, wrap the number in an extra set of curly braces, like this:

{{5}}

This pattern results in a number wrapped in curly braces, not in a variable replacement:

{5}

Example of using the Python str.format() function to create more advanced templates

More complicated formatting is supported using all the capabilities of the Python str.format() function. The first section of this template demonstrates double curly brackets to support curly bracket escaping. This is particularly important as if you don't use double curly brackets with curly bracket escaping, unintended errors can occur. For example, if you wanted to input JSON strings, you would need to escape the literal using double curly brackets or the system returns an invalid token.

The second section in this template demonstrates automatic escaping of backslashes and quotes, and centered string alignment with a custom filler character:

JSON Formatting:
{{"notable_id":"{0}","event_count":{1}}}

Backslashes and quotes are escaped:
"ls /Applications/System \Preferences.app/"

Python formatting is supported:
|{0:-^50}|{1:-^50}|
|{2:-^50}|{3:-^{3}{2}{1}{3}{2}{1}50}|

The template produces output as in the following example:

JSON Formatting: 
{"notable_id":  "1004", "event_count": 10}

Backslashes and quotes are escaped:
"ls /Applications/System \Preferences.app/"

Python formatting is supported:
|-----------------------1004-----------------------|-----------------------10-----------------------|
|----------------------events----------------------|-------Zeus infection on HQ finance server------|