Playbook Definition Language
A template definition contains all of the details, metadata, inputs, and tasks for an automated workflow. Each supported field is documented on this page.
Tip
The following template variables are available in templates:
${TDR.API}— The API URL for Taegis${TDR.URL}— The portal URL for Taegis${TDR.tenant}— The tenant ID when the playbook is executed${TDR.user}— The user ID that triggered the playbook
Template Fields ⫘
The following fields are supported:
apiVersion ⫘
This field is used internally to define the version of the API that supports this definition.
Default/suggested value: v0.0.1
Data type: string
kind ⫘
This field is used to define the type of definition file. In this case of a playbook template, the value should always be Playbook.
Default/suggested value: Playbook
Data type: string
name ⫘
This field defines the name of the template. Template names must be unique within a given tenant. Template names that start with the special Taegis prefix are global and can only be added by Secureworks. Template names should not contain spaces, and any special characters outside of underscore (_) and period (.).
Default/suggested value: n/a
Data type: string
title ⫘
This field defines the value that is displayed in the XDR UI when viewing this template. This field can contain spaces and other special characters.
Default/suggested value: n/a
Data type: string
description ⫘
This field is used to describe the template. This is not a documentation field, but a short one or two sentence description for the template.
Default/suggested value: one or two sentences that clearly identify the purpose of the template.
Data type: string
tenantId ⫘
This optional field contains the XDR tenant ID as a string.
Default/suggested value: n/a
Data type: string
version ⫘
This optional field is a semantic version number (MAJOR.MINOR.PATCH). See Semantic Versioning 2.0.0 for more information. The version is set as draft if this field is omitted.
Note
Using drafts for production purposes is highly discouraged.
Default/suggested value: n/a
Data type: semantic version number
inputs ⫘
This field allows the template author to define any required inputs for the playbook to work properly. The value is a JSON schema which defines the structure of the inputs.
Default/suggested value: n/a
Data type: string (JSON schema)
outputs ⫘
This field allows the template author to define any outputs the playbook produces. The value is a JSON schema which defines the structure of the outputs.
Default/suggested value: n/a
Data type: string (JSON schema)
tags ⫘
This field is a collection/list of labels that are associated with the template. Tags are not currently displayed or searchable in the XDR UI, but may be exposed in the future to support grouping/filtering/searching the library of templates.
Default/suggested value: an empty list ([]) at this time due to lack of UI support.
Data type: list/array of strings
connectorCategories ⫘
This field is a collection/list of pre-defined categories that are associated with the template. Categories are not currently displayed or searchable in the XDR UI, but may be exposed in the future to support grouping/filtering/searching the library of templates.
Default/suggested value: an empty list ([]) at this time due to lack of UI support.
Data type: list/array of strings
connectors ⫘
This field is a collection/list of connectors that this template requires.
Default/suggested value: n/a
Data type: list/array of strings
implements ⫘
This optional field is a string defining the interface that this template implements. Defining this value makes this template an Activity. The implements value should be the full interface name and version in the format: interface_name:version.
Default/suggested value: n/a
Data type: list/array of strings
interfaces ⫘
This optional field is a collection/list of interfaces (activities) that this template requires. The interface values should be the full interface name and version in the format: interface_name:version.
Default/suggested value: n/a
Data type: list/array of strings
dsl ⫘
This field is an object/map which defined the domain-specific language for the automated workflow. This field consists of four fields: name, description, tasks, and outputs.
Default/suggested value: n/a
Data type: object/map
The following fields define parameters for dsl.
name ⫘
This field is a name for the dsl, and should match the name of the template. It is not displayed/used in the XDR UI.
Default/suggested value: same name as the template
Data type: string
description ⫘
This field is a description for the dsl. This field should match the description of the template and is not displayed/used in the XDR UI.
Default/suggested value: same description as the template
Data type: string
tasks ⫘
This field is a list/array of the steps that make up the template. This field defines the workflow as individual steps. The fields that make up each task are documented in detail in Working with Playbook Tasks.
Default/suggested value: n/a
Data type: list/array
outputs ⫘
This field allows the template author to define the output values for the automated workflow. The structure of the outputs should match the JSON schema defined for the template.
Default/suggested value: should match the outputs JSON schema
Data type: object/map