Notification¶

Overview¶

Teflo’s notification section declares what messages are to be sent and to whom when triggered. The current notification mechanism is email.

First lets go over the basic structure that defines a notification task.

---
notifications:
  - name: test_email
    notifier: email-notifier
    credential: email
    on_success: true
    to:
      - jsmith@redhat.com
    from: qe-rh@redhat.com

The above code snippet is the minimal structure that is required to create a notification task within teflo. This task is translated into a teflo notification object which is part of the teflo compound. You can learn more about this at the architecture page. Please see the table below to understand the key/values defined.

Key	Description	Type	Required	Default
name	The name of the notification to define	String	Yes	n/a
description	A description of what the notification is trying to accomplish	String	No	n/a
notifier	The notifier to use to send notifications when triggered above	String	Yes	email-notifier
on_start	trigger to send a notification when a task is going to be executed	Boolean	No	False
on_success	trigger to send a notification when a task has executed successfully	Boolean	No	True
on_failure	trigger to send a notification when a task has executed unsuccessfully	Boolean	No	True
on_demand	disable automatic trigger of the notification. Must be manually triggered	Boolean	No	False
on_tasks	Filter for which tasks should trigger a notification	List	No	All Tasks (Validate, Provision, Orchestrate, Execute, Report, Cleanup)

Triggers¶

By default, Teflo implicitly triggers on both on_success and on_failure for all completed task types. If you would like to set it for either/or, you can explicitly set either parameter to true.

If you would like to have teflo trigger notifications before the start of a task rather than after, you can set on_start to true. The on_start option is mutually exclusive to on_success/on_failure.

If you would like to have teflo not trigger notifications automatically and you would like to control when to trigger notifications in your workflow, you can set the on_demand flag to true.

If you would like to filter so that only certain tasks trigger notifications, you can set on_tasks to a list of any combination of supported teflo tasks. This does not apply to on_demand.

There are further capabilities to controlling the triggering of any notifications from the command line.

For example, if you have defined different notifications in your scenario with different triggers but are interested in triggering certain ones for a particular run, you can specify which ones to skip using the –skip-notify option

teflo run -s scenario.yml -w . -t provision --skip-notify notification_a --skip-notify notification_b

If you would like to temporarily disable triggering notifications for the entire scenario for a particular run without permanently setting them to on_demand. You can use the –no-notify option

teflo run -s scenario.yml -w . -t execute -t report --no-notify

Sending Email Notifications¶

Credentials/Configure¶

To configure the email notification, you will need to have your SMTP configuration in your teflo.cfg file, see SMTP Configuration for more details.

Email¶

The following shows all the possible keys for defining an email notification using the email-notifier notifier:

---
notifications:
  - name: <name>
    notifier: <notifier>
    to: <list_of_values>
    from: <from>
    cc: <list_of_values>
    subject: <subject>
    attachments: <list_of_values>
    message_body: <multiline value>
    message_template: <template_path>

Key	Description	Type	Required
to	A list of email addresses that this notification should be sent to.	List	True
from	The email address the notification should be from.	String	True
cc	The list of email addresses that you want to send teflo copies to.	List	False
subject	The subject of the message that should be included.	String	False
attachments	List of attachments to include when the message is sent.	List	False
message_body	The text body of the message to include overriding Teflo’s default message template.	String	False
message_template	A relative path to a text email body template in Teflo’s workspace that should be used. It overrides Teflo’s default message template.	String	False

Message Content¶

Teflo has a default messaging template that is sent when no message_body or message_template parameter is used. Teflo uses some internal data about the tasks performed by the scenario. Below is the list of data being rendered into the message

overall status of the Scenario execution

The list of Teflo tasks that passed and/or failed

The list of artifacts that were collected after test execution if any

The import result urls of any test artifacts that were imported into a reporting system

Teflo makes its scenario and scenario_graph objects available to user when designing their own messaging template. The key for teflo’s scenario object is scenario and for scenario_graph is scenario_graph

Along with the scenario object, users can get all the variables set during teflo run as well as environment variables as scenario_vars dictionary to be used in the templates. The key for this is scenario_vars

Examples¶

Let’s go into some examples of you can define your notification resources

Example 1¶

You want to trigger a notification on all successful tasks using the default template

---
notifications:
  - name: test_email
    notifier: email-notifier
    credential: email
    on_success: true
    to:
      - jsmith@redhat.com
    from: qe-rh@redhat.com

Example 2¶

You want to trigger a notification before the start of all tasks using a messaging template

---
notifications:
  - name: msg_template
    notifier: email-notifier
    credential: email
    on_start: true
    to:
      - jsmith@redhat.com
      - fbar@redhat.com
    from: qe-team@redhat.com
    subject: test email notification using default template {{ UUID }}
    message_template: email_templ.txt

Teflo’s scenario data could be used to format the template email_templ.txt as shown in the examples below:

Hello All,

This is a Teflo Notification.

Teflo scenario, {{ scenario.name }}, has provisioned  the asset:

{{ scenario.assets[0].name }}

The data directory is {{ scenario_vars.TEFLO_DATA_FOLDER }}

Hello All,

This is a Teflo Notification for Execute task.

 {% if scenario.get_executes() %}
     {% for execute in scenario.get_executes() %}
     Execute task name: {{ execute.name }}
             {% if execute.artifact_locations %}
     Collected the following artifacts:
             {% for file in execute.artifact_locations %}
             - {{ file }}
             {% endfor %}
         {% endif %}
         {% if execute.testrun_results %}

     These are the test results of the scenario:

       Total Tests: {{ execute.testrun_results.aggregate_testrun_results.total_tests }}
       Passed Tests: {{ execute.testrun_results.aggregate_testrun_results.passed_tests }}
       Failed Tests: {{ execute.testrun_results.aggregate_testrun_results.failed_tests }}
       Skipped Tests: {{ execute.testrun_results.aggregate_testrun_results.skipped_tests }}

         {% endif %}
     {% endfor %}
 {% else %}
  No execute tasks were run
 {% endif %}

This is how the email sent using above template will read:

Hello All,

 This is a Teflo Notification for Execute task.

      Execute task name: Test running playbook
      Collected the following artifacts:
              - artifacts/localhost/rp_preproc_qmzls.log
              - artifacts/localhost/junit_example_5_orig.xml

      These are the test results of the scenario:

        Total Tests: 6
        Passed Tests: 4
        Failed Tests: 2
        Skipped Tests: 0

      Execute task name: Execute2
      Collected the following artifacts:
              - artifacts/localhost/rp_preproc_qmzls.log
              - artifacts/localhost/junit_example_5_orig.xml

      These are the test results of the scenario:

        Total Tests: 6
        Passed Tests: 4
        Failed Tests: 2
        Skipped Tests: 0

Example 3¶

You want to trigger a notification regardless on failures of the Validate and Provision task but you want to include a multiline string in the descriptor file.

---
notifications:
  - name: msg_body_test
    notifier: email-notifier
    credential: email
    on_failure: true
    on_tasks:
      - validate
      - provision
    to: [jsnith@redhat.com, fbar@redhat.com]
    from: qe-team@redhat.com
    subject: test notification using message body.
    message_body: |
      Hello All,

      This is a Teflo Test notification. For Jenkins Job {{ Job }}.

      Thanks,

      Waldo

Example 4¶

You want to trigger a notification regardless only on failures of all tasks using the default template message but you want to include a file as an attachment.

---
notifications:
  - name: msg_test
    notifier: email-notifier
    credential: email
    on_failure: true
    to: [jsnith@redhat.com, fbar@redhat.com]
    from: qe-team@redhat.com
    subject: test notification using message attachments.
    attachments:
      - workpsace/folder/file.txt

Example 5¶

You don’t want a notification to trigger automatically.

---
notifications:
  - name: msg_test
    notifier: email-notifier
    credential: email
    on_demand: true
    to: [jsnith@redhat.com, fbar@redhat.com]
    from: qe-team@redhat.com
    subject: test notification only when manually triggered.

Example 6¶

Using custom template and using teflo’s data for formatting

---
notifications:
  - name: msg_template
    notifier: email-notifier
    credential: email
    on_start: true
    to:
      - jsmith@redhat.com
      - fbar@redhat.com
    from: qe-team@redhat.com
    subject: test email notification using default template {{ UUID }}
    message_template: email_templ.txt

Example 7¶

Using custom template and using teflo’s variables for formatting

Consider teflo_var.yml is the file set as the default variable file in teflo.cfg

[defaults]
var_file=./teflo_var.yml

The contents of teflo_var.yml:

---
username: teflo_user
msg_template: template.jinja
var_a: hello

The template template.jinja will look like this

{{scenario_vars.var_a}} {{ scenario_vars.username }},

This is a Teflo Notification.

Teflo has completed executing the scenario, {{ scenario.name }}, with overall status:

{% if scenario.overall_status == 0 %}
Passed
{% else %}
Failed
{% endif %}

The data folder is {{ scenario_vars.TEFLO_DATA_FOLDER }}

Scenario file notification block

---
notifications:
  - name: msg_template
    notifier: email-notifier
    credential: email
    on_tasks: ['provision']
    to:
      - jsmith@redhat.com
      - fbar@redhat.com
    from: qe-team@redhat.com
    subject: test email notification is for user {{ username }}
    message_template: {{ msg_template }}

The above example post run will be seen as following in the results.yml file, where the variables from teflo_var.file are used

notifications:
  - name: msg_template
    notifier: email-notifier
    credential: email
    on_success: true
    on_failure: true
    on_tasks:
      - provision
    on_start: false
    on_demand: false
    to:
      - jsmith@redhat.com
      - fbar@redhat.com
    from: qe-team@redhat.com
    subject: test email notification is for user teflo_user
    message_template: template.jinja

The above example will send email which will look like this:

hello teflo_user,

This is a Teflo Notification.

Teflo has completed executing the scenario, test1, with overall status:
Passed

The data folder is /home/workspace/teflo/data_folder/nzohposc6v/

Sending Chat Notifications¶

Teflo_webhooks_notification_plugin allows users to send chat notification during and/or post teflo run. To get more information about this plugin ,on how to install and use it please visit teflo_webhooks_notification_plugin