Documentation

10. Supported Attributes for Custom Notifications

This section describes the list of supported job attributes and the proper syntax for constructing the message text for notifications. The supported job attributes are:

  • allow_simultaneous - (boolean) indicates if multiple jobs can run simultaneously from the JT associated with this job

  • controller_node - (string) the instance that managed the isolated execution environment

  • created - (datetime) timestamp when this job was created

  • custom_virtualenv - (string) custom virtual environment used to execute job

  • description - (string) optional description of the job

  • diff_mode - (boolean) if enabled, textual changes made to any templated files on the host are shown in the standard output

  • elapsed - (decimal) elapsed time in seconds that the job ran

  • execution_node - (string) node the job executed on

  • failed - (boolean) true if job failed

  • finished - (datetime) date and time the job finished execution

  • force_handlers - (boolean) when handlers are forced, they will run when notified even if a task fails on that host (note that some conditions - e.g. unreachable hosts - can still prevent handlers from running)

  • forks - (int) number of forks requested for job

  • id - (int) database id for this job

  • job_explanation - (string) status field to indicate the state of the job if it wasn’t able to run and capture stdout

  • job_slice_count - (integer) if run as part of a sliced job, the total number of slices (if 1, job is not part of a sliced job)

  • job_slice_number - (integer) if run as part of a sliced job, the ID of the inventory slice operated on (if not part of a sliced job, attribute is not used)

  • job_tags - (string) only tasks with specified tags will execute

  • job_type - (choice) run, check, or scan

  • launch_type - (choice) manual, relaunch, callback, scheduled, dependency, workflow, sync, or scm

  • limit - (string) playbook execution limited to this set of hosts, if specified

  • modified - (datetime) timestamp when this job was last modified

  • name - (string) name of this job

  • playbook - (string) playbook executed

  • scm_revision - (string) scm revision from the project used for this job, if available

  • skip_tags - (string) playbook execution skips over this set of tag(s), if specified

  • start_at_task - (string) playbook execution begins at the task matching this name, if specified

  • started - (datetime) date and time the job was queued for starting

  • status - (choice) new, pending, waiting, running, successful, failed, error, canceled

  • timeout - (int) amount of time (in seconds) to run before the task is canceled

  • type - (choice) data type for this job

  • url - (string) URL for this job

  • use_fact_cache - (boolean) if enabled for job, Tower acts as an Ansible Fact Cache Plugin, persisting facts at the end of a playbook run to the database and caching facts for use by Ansible

  • verbosity - (choice) 0 through 5 (corresponding to Normal through WinRM Debug)

  • host_status_counts (count of hosts uniquely assigned to each status)

    • skipped (integer)

    • ok (integer)

    • changed (integer)

    • failures (integer)

    • dark (integer)

    • processed (integer)

    • rescued (integer)

    • ignored (integer)

    • failed (boolean)

  • summary_fields:
    • inventory

      • id - (integer) database ID for inventory

      • name - (string) name of the inventory

      • description - (string) optional description of the inventory

      • has_active_failures - (boolean) (deprecated) flag indicating whether any hosts in this inventory have failed

      • total_hosts - (deprecated) (int) total number of hosts in this inventory.

      • hosts_with_active_failures - (deprecated) (int) number of hosts in this inventory with active failures

      • total_groups - (deprecated) (int) total number of groups in this inventory

      • groups_with_active_failures - (deprecated) (int) number of hosts in this inventory with active failures

      • has_inventory_sources - (deprecated) (boolean) flag indicating whether this inventory has external inventory sources

      • total_inventory_sources - (int) total number of external inventory sources configured within this inventory

      • inventory_sources_with_failures - (int) number of external inventory sources in this inventory with failures

      • organization_id - (id) organization containing this inventory

      • kind - (choice) (empty string) (indicating hosts have direct link with inventory) or ‘smart’

    • project

      • id - (int) database ID for project

      • name - (string) name of the project

      • description - (string) optional description of the project

      • status - (choices) one of new, pending, waiting, running, successful, failed, error, canceled, never updated, ok, or missing

      • scm_type (choice) - one of (empty string), git, hg, svn, insights

    • job_template

      • id - (int) database ID for job template

      • name - (string) name of job template

      • description - (string) optional description for the job template

    • unified_job_template

      • id - (int) database ID for unified job template

      • name - (string) name of unified job template

      • description - (string) optional description for the unified job template

      • unified_job_type - (choice) unified job type (job, workflow_job, project_update, etc.)

    • instance_group

      • id - (int) database ID for instance group

      • name - (string) name of instance group

    • created_by

      • id - (int) database ID of user

      • username - (string) username

      • first_name - (string) first name

      • last_name - (string) last name

    • labels

      • count - (int) number of labels

      • results - list of dictionaries representing labels (e.g. {“id”: 5, “name”: “database jobs”})

Information about a job can be referenced in a custom notification message using grouped curly braces {{ }}. Specific job attributes are accessed using dotted notation, for example {{ job.summary_fields.inventory.name }}. Any characters used in front or around the braces, or plain text, can be added for clarification, such as ‘#’ for job ID and single-quotes to denote some descriptor. Custom messages can include a number of variables throughout the message:

{{ job_friendly_name }} {{ job.id }} ran on {{ job.execution_node }} in {{ job.elapsed }} seconds.

In addition to the job attributes, there are some other variables that can be added to the template:

  • approval_node_name - (string) the approval node name

  • approval_status - (choice) one of approved, denied, and timed_out

  • url - (string) URL of the job for which the notification is emitted (this applies to start, success, fail, and approval notifications)

  • workflow_url - (string) URL to the relevant approval node. This allows the notification recipient to go to the relevant workflow job page to see what’s going on (i.e., This node can be viewed at: {{ workflow_url }}). In cases of approval-related notifications, both url and workflow_url are the same.

  • job_friendly_name - (string) the friendly name of the job

  • job_metadata - (string) job metadata as a JSON string, for example:

    {'url': 'https://towerhost/$/jobs/playbook/13',
 'traceback': '',
 'status': 'running',
 'started': '2019-08-07T21:46:38.362630+00:00',
 'project': 'Stub project',
 'playbook': 'ping.yml',
 'name': 'Stub Job Template',
 'limit': '',
 'inventory': 'Stub Inventory',
 'id': 42,
 'hosts': {},
 'friendly_name': 'Job',
 'finished': False,
 'credential': 'Stub credential',
 'created_by': 'admin'}