PPA: Events

Summary

This module contains actions for sending various events from a task.

Actions

ppa.events.

create_approval_request

Create an approval request that can be activated afterwards.

Minimum Plugin Version: 11.1.0

Minimum PPA Version: 3.3.0

Input

request_message: a message that describes the request (markdown is supported)

Output

An ApprovalRequest.

Example

- ppa.events.create_approval_request:
    request_message: >
      ### Change Summary

      - Reset password for example.user

      - Unlock the account

      - Force password change at next logon
  save: approval_request

ppa.events.

create_wait_hook

This action is deprecated in favour of create_approval_request.

It will be removed in a future release.

ppa.events.

send_email

Send an email using the PPA SMTP configuration.

Minimum Plugin Version: 4.0.0

Input

subject: the email subject
html: an HTML document containing the body of the email
plain_text: an optional plain text version of the email body for older mail clients
recipients: a list of one or more email addresses
attachments: optional list of file names to attach to the email
reason: text to display when the action runs (defaults to The task is sending an email)

Attachments & Recipients

Attachments

The ability to send attachments was introduced in PPA v2.7.0
Sending an email will work on older PPA versions, but attempting to send an attachment will fail

Recipients

Default SMTP recipients were removed in PPA v2.8.0
The recipients input to this action is now mandatory

Output

Nothing is outputted by this action.

Simple HTML Email

- ppa.events.send_email:
    subject: PPA Notification
    html: >
      <html>
        <head>PPA Email Header</head>
        <body>PPA Email Body</body>
      </html>
    plain_text: >
      PPA Email Header

      PPA Email Body
    recipients:
      - recipient_1@email.com
      - recipient_2@email.com

Email With Attachment

Auditing a set of users from Active Directory
Writing the users to a JSON file
Attaching the JSON file to an email

- active_directory.groups.get_users:
    distinguishedName: CN=Domain Admins,CN=Users,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: domain_admins

- write_json_file:
    name: domain_admins.json
  load:
    contents: domain_admins

- ppa.events.send_email:
    subject: Domain Admins Report
    html: >
      <html>
        <head>PPA Domain Admins Report</head>
        <body>The JSON report is attached to this email.</body>
      </html>
    attachments:
      - domain_admins.json
    recipients:
      - recipient_1@email.com
      - recipient_2@email.com

Remember

This action will fail if SMTP is not configured in PPA.

ppa.events.

send_syslog_event

Send a JSON syslog event using the PPA syslog configuration.

Minimum Plugin Version: 2.0.0

Input

message: the event message
level: the event level (defaults to info, see more about event levels below)
reason: optional text to display in the task interface (defaults to no text displayed)
details: optional dictionary of custom event details (defaults to empty)

Event Levels

Valid event levels:

info
warning
error
debug
fatal
panic
trace

Output

Nothing is outputted by this action.

Example

- ppa.events.send_syslog_event:
    message: A user's password has been changed by PPA
    details:
      username: "{{ active_directory_user.sAMAccountName }}"
      was_unlocked: false
      force_password_change: true

Generated Syslog Event

{
    "details": {
        "username": "example.user",
        "was_unlocked": false,
        "force_password_change": true
    },
    "level": "info",
    "msg": "A user's password has been changed by PPA",
    "name": "TaskLog",
    "task": "28b54abb-7e9b-4db0-beaa-dad4b0448eeb",
    "time": "2020-06-10T14:51:41Z"
}

Remember

This action will fail if syslog is not configured in PPA.

ppa.events.

wait

This action is deprecated in favour of wait_approval_response.

It will be removed in a future release.

ppa.events.

wait_approval_response

Wait for a response to an approval request.

The out of this action will contain a boolean approved key.

Use the value of this key to control what the task does once the response is received.

Minimum Plugin Version: 11.1.0

Minimum PPA Version: 3.3.0

Input

text: the text to display while waiting
approval_request: an ApprovalRequest
assignees: a list of usernames responsible for responding to the request

Output

An ApprovalResponse.

Example

- ppa.events.create_approval_request:
    request_message: >
      ### Change Summary

      - Reset password for example.user

      - Unlock the account

      - Force password change at next logon
    assignees:
      - john.smith
      - clare.jones
  save: approval_request

- ppa.events.wait_approval_response:
  load:
    approval_request: approval_request
  save: approval_response