Working with Playbook Tasks

Templates are automated workflows that consist of an ordered list of tasks. This page documents the fields used to define the tasks. Examples can be found by exporting a template from the template library in Secureworks® Taegis™ XDR. Official reference documentation for the domain specific language (DSL) can be found here: DSL

name ⫘

Defines the name of the task. Task names must be unique within a given template. Task names should not contain spaces, and any special characters outside of underscore: _. The name must match the regex pattern: [a-z][a-zA-Z0-9_]*

Default Value— n/a

Data Type— string

description ⫘

This field is used to describe the task. This is not a documentation field, but a short one or two sentence description for the task.

Default/suggested value: one or two sentences that clearly identify the purpose of the task.

Data type— string

inputs ⫘

This field is used to define the input values for the task. When the task is a connector function, the inputs here should match/map to the inputs on the action. Inputs are evaluated/built AFTER the variables on the task is evaluated. This field is optional.

Default Value— should match the JSON schema for the connector action

Data Type— object/map

variables ⫘

Allows the template author to define variables for the task as key/value pairs. Variables are similar to inputs, but exist for flow control task types. The variables for each task can be used/referenced in subsequent steps in the playbook using task_name.variables.variable_name notation. Variables are evaluated and built after the condition on the task is evaluated. This field is optional.

Default Value— n/a

Data Type— object/map

condition ⫘

Allows the template author to define a condition which is evaluated before the task is executed. This field is optional.

Default Value— n/a

Data Type— string

Task Types ⫘

The domain-specific language (DSL) supports a handful of task types. Some tasks are defined by fields specific to that task type. The task types are defined below:

action ⫘

Allows the template author to call a connector function. In most cases, this task type defines inputs that align to the inputs defined on the connector function. Use a format of connector_name.function_name for the value.

Default Value— connector_name.function_name

Data Type— string

exec ⫘

Allows the template author to call another template. In most cases, the exec task type defines inputs which align/map to the inputs defined on the template. Use the full template name for the default value. Note any playbooks executed in an exec task must also be added to the required playbooks list on the template.

Default Value— template_name

Data Type— string

do while ⫘

Allows the template author to perform a number of tasks repeatedly until a condition is met. Not that the tasks inside the do while are executed before the condition is evaluated. The output of a do while task is the result of the last task executed. The iteration variable is created inside the do while and contains the current iteration of the loop.

Default Value— n/a

do Data Type— list/array of tasks

while Data Type— string

Iteration— integer

for range ⫘

Allows the template author to iterate over a list or map value and perform tasks on each iteration within the range. The output is the result of the last task executed. A number of special variables allow the template author to access data on each iteration:

index— an integer indicating the element in the list, or a string map key

value— the current value for this iteration of the list/map

iteration— a counter for each iteration

Default Value— n/a

Data Types ⫘

for-- list/array of tasks range— list/array or map index-- integer if range is a list/array or string if range is a map value— Any (depends on data type of elements in the range) iteration— integer

for condition ⫘

Allows the template author to perform a number of tasks repeatedly if a condition is met. Note in a for condition task, the tasks inside the for condition are executed after the condition is evaluated. Output of a for condition task is the result of the last task executed. The iteration variable is created inside the do while and contains the current iteration of the loop.

Default Value— n/a

Data Types ⫘

for— list/array of tasks condition— string iteration— integer

switch ⫘

Allows the template author to define criteria the execution path follows. Case values must be strings and multiple tasks can be defined in each case.

Default Value— n/a

Data Types ⫘

switch— string case— object/map, where the value for each key is a list/array of tasks

let ⫘

Allows the template author to define variables which can be used in subsequent steps in the template. The variables are name/value pairs.

Default Value— n/a

Data Type— object/map

call ⫘

Allows the template author to execute a function. In most cases, the call task type defines inputs which align to the inputs defined in the function. The value is the full function name. Note any playbooks that are executed in an exec task must also be added to the required interfaces list on the template.

Default Value-- activity_name

Data Type-- string