Actions

When a rule matches the condition(s), it fires the corresponding action for the rule.

Note

Actions can use Jinja filters to transform and manipulate data. See Jinja Filters for details on available filters including regex_replace, basename, dirname, and normpath, as well as Python string methods. Note that Jinja filters cannot be used in conditions.

The following actions are supported:

• run_playbook

• run_module

• run_job_template

• run_workflow_template

• set_fact

• post_event

• retract_fact

• print_event

• shutdown

• debug

• none

run_playbook

Run an Ansible playbook.

Run a playbook

Name	Description	Required
name	The name of the playbook, using the FQCN (fully qualified collection name), or an absolute path or a relative path. If it’s a relative path, it must be relative to the current working dir where the ansible-rulebook command is executed.	Yes
set_facts	Boolean, the artifacts from the playbook execution are inserted back into the rule set as facts. It is recommended that the playbook should use the ansible.builtin.set_stats task to set this data.	No
post_events	Boolean, the artifacts from the playbook execution are inserted back into the rule set as events. It is recommended that the playbook should use the ansible.builtin.set_stats task to set this data.	No
ruleset	The name of the ruleset to post the event or assert the fact to, default is current rule set.	No
retry	If the playbook fails execution, retry it once, boolean value true|false	No
retries	If the playbook fails execution, the number of times to retry it. An integer value	No
delay	The retry interval, an integer value specified in seconds	No
verbosity	Verbosity level when running the playbook, a value between 1-4	No
var_root	If the event is a deeply nested dictionary, the var_root can specify the key name whose value should replace the matching event value. The var_root can take a dictionary to account for data when we have multiple matching events.	No
extra_vars	Additional vars to be passed into the playbook as extra vars.	No
json_mode	Boolean, sends the playbook events data to the stdout as json strings as they are processed by ansible-runner	No
copy_files	Boolean, copy the local playbook file to the ansible-runner project directory, this is not needed if you are running a playbook from an ansible collection.	No
lock	An optional string based lock ensures sequential execution of this action when execution strategy is set to parallel. It can also be a string field from the event payload. The locks are per ruleset, if a lock is in place all actions that use the same lock will wait till the earlier action has completed.	No

run_module

Run an Ansible module

Name	Description	Required
name	The name of the module, using the FQCN (fully qualified collection name)	Yes
module_args	The arguments to pass into the Ansible Module	No
retry	If the module fails execution, retry it once, boolean value true|false. Default false	No
retries	If the module fails execution, the number of times to retry it. Integer value, default 0	No
delay	The retry interval, an integer value	No
verbosity	Verbosity level when running the module, a value between 1-4	No
extra_vars	Additional vars to be passed into the playbook as extra vars.	No
json_mode	Boolean, sends the playbook events data to the stdout as json strings as they are processed by ansible-runner	No
set_facts	Boolean, the artifacts from the module execution are inserted back into the rule set as facts	No
post_events	Boolean, the artifacts from the module execution are inserted back into the rule set as events	No
ruleset	The name of the ruleset to post the event or assert the fact to, default is current rule set.	No
var_root	If the event is a deeply nested dictionary, the var_root can specify the key name whose value should replace the matching event value. The var_root can take a dictionary to account for data when we have multiple matching events.	No
lock	An optional string based lock ensures sequential execution of this action when execution strategy is set to parallel. It can also be a string field from the event payload. The locks are per ruleset, if a lock is in place all actions that use the same lock will wait till the earlier action has completed.	No
labels	Optional list of strings as labels, which can be added to the job in the controller. Requires that Prompt on launch for Labels is enabled. If its not enabled the labels are ignored. ansible-rulebook will add a default label called “Activated by Event-Driven Ansible”	No

run_job_template

Run a job template.

Note

--controller-url and either --controller-token or --controller-username and --controller-password cmd options must be provided to use this action

In order to access event information under the ansible_eda namespace, be sure to check the box for “Prompt on launch” for the Variables field within the job template. Alternatively, a survey can be created that includes the variable ansible_eda. Similarly, if you plan to limit host execution based on event information, enable “Prompt on launch” for the Limit field within the job template.

Note

You can define the environment variable EDA_CONTROLLER_CONNECTION_LIMIT to limit the number of concurrent connections to the controller. The default is 30.

Note

The controller URL is the API end point, that ansible-rulebook will try to reach. If you have a path specified in your URL it should have the api embedded in it. If you have just provided a host and port but no path we will append api to the URL$ for backward compatibility.

Name	Description	Required
name	The name of the job template	Yes
organization	The name of the organization	Yes
include_events	Should we include the matching events in the payload sent to controller. Default is true	No
set_facts	The artifacts from the job template execution are inserted back into the rule set as facts. It is recommended that the playbook inside the job template should use the ansible.builtin.set_stats task to set this data.	No
post_events	The artifacts from the job template execution are inserted back into the rule set as events. It is recommended that the playbook inside the job template should use the ansible.builtin.set_stats task to set this data.	No
ruleset	The name of the ruleset to post the event or assert the fact to, default is current rule set.	No
retry	If the job template fails execution, retry it once, boolean value true|false	No
retries	If the job template fails execution, the number of times to retry it. An integer value	No
delay	The retry interval, an integer value specified in seconds	No
var_root	If the event is a deeply nested dictionary, the var_root can specify the key name whose value should replace the matching event value. The var_root can take a dictionary to account for data when we have multiple matching events.	No
job_args	Additional arguments sent to the job template launch API. Any answers to the survey and other extra vars should be set in nested key extra_vars. Event(s) and fact(s) will be automatically included in extra_vars too. Optionally if the job_args includes an attribute called limit it can be used to over write the limit set from the event payload.	No
lock	An optional string based lock ensures sequential execution of this action when execution strategy is set to parallel. It can also be a string field from the event payload. The locks are per ruleset, if a lock is in place all actions that use the same lock will wait till the earlier action has completed.	No
labels	Optional list of strings as labels, which can be added to the job in the controller. Requires that Prompt on launch for Labels is enabled. If its not enabled the labels are ignored. ansible-rulebook will add a default label called “Activated by Event-Driven Ansible”. If the label gets resolved as None or an empty string it will be dropped. If there are duplicate labels the duplicate ones will be removed. e.g {{ event.payload.my_label | default(None) }} if the attribute doesn’t exist we will skip the label.	No
add_event_uuid_label	A boolean field, when set to true can leverage the event.meta.uuid field as a label, you can establish clear traceability between triggering events and their resulting jobs.	No

run_workflow_template

Run a workflow template.

Note

--controller-url and either --controller-token or --controller-username and --controller-password cmd options must be provided to use this action

Note

You can define the environment variable EDA_CONTROLLER_CONNECTION_LIMIT to limit the number of concurrent connections to the controller. The default is 30.

Note

The controller URL is the api end point, that ansible-rulebook will try to reach. If you have a path specified in your URL it should have the api embedded in it. If you have just provided a host and port but no path we will append api to the URL$ for backward compatibility.

Name	Description	Required
name	The name of the workflow template	Yes
organization	The name of the organization	Yes
include_events	Should we include the matching events in the payload sent to controller. Default is true. If your workflow template does not have Prompt on Launch for Extra Variables or a Survey spec, you will have to set this to false.	No
set_facts	The artifacts from the workflow template execution are inserted back into the rule set as facts	No
post_events	The artifacts from the workflow template execution are inserted back into the rule set as events	No
ruleset	The name of the ruleset to post the event or assert the fact to, default is current rule set.	No
retry	If the workflow template fails execution, retry it once, boolean value true|false	No
retries	If the workflow template fails execution, the number of times to retry it. An integer value	No
delay	The retry interval, an integer value specified in seconds	No
var_root	If the event is a deeply nested dictionary, the var_root can specify the key name whose value should replace the matching event value. The var_root can take a dictionary to account for data when we have multiple matching events.	No
job_args	Additional arguments sent to the workflow template launch API. Any answers to the survey and other extra vars should be set in nested key extra_vars. Event(s) and fact(s) will be automatically included in extra_vars too. Optionally if the job_args includes an attribute called limit it can be used to over write the limit set from the event payload.	No
lock	An optional string based lock ensures sequential execution of this action when execution strategy is set to parallel. It can also be a string field from the event payload. The locks are per ruleset, if a lock is in place all actions that use the same lock will wait till the earlier action has completed.	No
labels	Optional list of strings as labels, which can be added to the job in the controller. Requires that Prompt on launch for Labels is enabled. If its not enabled the labels are ignored. ansible-rulebook will add a default label called “Activated by Event-Driven Ansible”. If the label gets resolved as None or an empty string it will be dropped. If there are duplicate labels the duplicate ones will be removed. e.g {{ event.payload.my_label | default(None) }} if the attribute doesn’t exist we will skip the label.	No
add_event_uuid_label	A boolean field, when set to true can leverage the event.meta.uuid field as a label, you can establish clear traceability between triggering events and their resulting jobs.	No

post_event

Post an event to a running rule set in the rules engine

Name	Description	Required
event	The event dictionary to post	Yes
ruleset	The name of the rule set to post the event, default is the current rule set name	No

Example:

action:
  post_event:
    ruleset: Test rules4
    event:
      j: 4

Example, using data saved with assignment:

name: multiple conditions
condition:
  all:
    - events.first << event.i == 0
    - events.second << event.i == 1
    - events.third << event.i == events.first.i + 2
action:
  post_event:
    ruleset: Test rules4
    event:
      data: "{{events.third}}"

The events and facts prefixes have rule scope and cannot be accessed outside of

rules. Please note the use of Jinja substitution when accessing the event results.

You can also use Jinja Filters to transform the data before posting it.

set_fact

Post a fact to the running rule set in the rules engine

Name	Description	Required
fact	The fact dictionary to post	Yes
ruleset	The name of the rule set to post the fact, default is the current rule set name	No

Example:

action:
    set_fact:
      ruleset: Test rules4
      fact:
        j: 1

Example, using data saved with assignment in multiple condition:

name: multiple conditions
condition:
  all:
    - events.first << event.i == 0
    - events.second << event.i == 1
    - events.third << event.i == events.first.i + 2
action:
  set_fact:
    ruleset: Test rules4
    fact:
      data: "{{events.first}}"

Example, using data saved with single condition:

name: single condition
condition: event.i == 23
action:
  set_fact:
    fact:
      myfact: "{{event.i}}"

A rulebook can have multiple rule sets, the set_fact/retract_fact/post_event allow you

to target different rule sets within the rulebook. You currently cannot assert an event to

multiple rule sets, it can be asserted to a single rule set. The default being the current

rule set. Please note the use of Jinja substitution in the above examples when accessing

the event results in an action.

retract_fact

Remove a fact from the running rule set in the rules engine

Name	Description	Required
fact	The fact dictionary to remove	Yes
ruleset	The name of the rule set to retract the fact, default is the current rule set name	No
partial	The fact being requested to retracted is partial and doesn’t have all the keys. Default is true	No

Example:

action:
  retract_fact:
    ruleset: Test rules4
    fact:
      j: 3

print_event

Write the event to stdout

Name	Description	Required
pretty	A boolean value to pretty print	No
var_root	If the event is a deeply nested dictionary, the var_root can specify the key name whose value should replace the matching event value. The var_root can take a dictionary to account for data when we have multiple matching events.	No

Example:

action:
  print_event:
    pretty: true
    var_root: i

Example with multiple event match:

name: Multiple events with var_root
condition:
  all:
    - events.webhook << event.webhook.payload.url == "http://www.example.com"
    - events.kafka << event.kafka.message.channel == "red"
action:
  print_event:
    var_root:
      webhook.payload: webhook
      kafka.message: kafka

shutdown

Shutdown ansible-rulebook

Name	Description	Required
delay	A numeric value about how long to wait in seconds before shutting down, default 60.0	No
message	A message to be associated with this shutdown	No
kind	Kind of shutdown can be either graceful or now. default is graceful.	No

Generate a shutdown event which will terminate the ansible-rulebook process.

If there are multiple rule-sets running in your rule book, issuing a shutdown will cause

all other rule-sets to end, care needs to be taken to account for running playbooks which

can be impacted when one of the rule set decides to shutdown. A shutdown message is

broadcast to all running rule-sets.

Example:

name: shutdown after 5 events
condition: event.i >= 5
action:
   shutdown:
     delay: 0.125
     message: Shutting down after 5 events

Results

When a rule’s condition(s) are satisfied we get the results back as:

• events/facts for multiple conditions

• event/fact if a single condition

This data is made available to your playbook as extra_vars when its invoked.

In all the examples below you would see that facts/fact is an exact copy of events/event respectively

and you can use either one of them in your playbook.

debug

debug ansible-rulebook

Name	Description	Required
msg	A simple string or an array of strings, which can have references to event or events	No
var	The variable to print, which can have references to event or events. Using {{ }} is optional.	No

The debug action tries to mimic the debug command in ansible.

If no arguments are provided it prints the matching events along with other important properties

msg and var are mutually exclusive, you can have only 1 of them in the debug

msg can be a single string or an array of strings, with references to event or events.

With var using the Jinja style braces is optional like shown in the example below

You can use Jinja Filters to transform the data in debug messages

Example:

name: debug with single message
condition: event.i >= 5
action:
   debug:
     msg: Simple debug message

name: debug with multiple messages
condition: event.i >= 5
action:
   debug:
     msg:
        - "Message 1 {{ event }}"
        - Second Message

name: debug with var
condition: event.i >= 5
action:
   debug:
     var: event.i

none

No action, useful when writing tests No arguments needed

FAQ

Q: What is the purpose of lock in run_job_template, run_playbook, run_module and run_workflow_template?

Ans: A lock is only relevant when you have the execution strategy set to parallel and you are executing

multiple jobs on different systems but you want sequential control based on some attribute, e.g the name of

the datacenter where the job is being executed, you want to ensure only one job is running on a

datacenter at a time but you want to run other jobs in other data centers. All jobs with the same

lock will be run sequentially, the user has the choice of what they want to use as a lock, it could

be any string attribute from the event payload or it could be a static string, where you want all other

actions to run parallel but others to run sequentially. e.g if you have

job to run a backup of a database. The lock does not queue the tasks, it just runs them as the lock is free and

available, if you need to sequence tasks you can keep using the multiple actions for a rule. You can

do other sequencing using workflow templates instead of job templates.

Example:

name: sample rule
condition: event.level == "error"
action:
  run_job_template:
    name: Fix My Datacenter
    organization: Default
    lock: "{{ event.datacenter }}"