Skip to content

PPA PPA: Events

Summary

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

Actions

ppa.events.

create_approval_request

Create a waithook with 'approve' & 'reject' URLs & a secret.

This action is similar to create_waithook, but is specifically for approval processes.

Use in conjunction with the wait_approval_response action.

Minimum Plugin Version: 2.1.0

Input

This action takes no inputs.

Output

An ApprovalRequest dictionary.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
- ppa.events.create_approval_request:
  save: approval_request

# In real life the approval_request.approve_url & approval_request.reject_url
# would be pushed somewhere at this point...

- ppa.events.wait_approval_response:
    text: Waiting for approval response...
    approved_message: The changes will be applied right away!
    rejected_message: The changes will not be applied.
  load:
    approval_request: approval_request
  save: approval_response

ppa.events.

create_wait_hook

Create a waithook with a URL & secret.

For approval processes consider using the create_approval_hook instead.

This action allows you to create advanced request processes for your task.

Use in conjunction with the wait action.

Minimum Plugin Version: 1.0.0

Input

This action takes no inputs.

Output

A WaitHook dictionary.

Example
1
2
3
4
5
6
7
8
- ppa.events.create_wait_hook:
  save: wait_hook

# In real life wait_hook.url would be pushed elsewhere at this point...

- ppa.events.wait:
  load:
    secret: wait_hook.secret

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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
- 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
- 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
1
2
3
4
5
6
- 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

Wait for a user to access a waithook URL & authenticate to PPA.

Use in conjunction with the create_wait_hook action.

Minimum Plugin Version: 1.0.0

Input
  • text: the text to display while waiting

  • secret: the secret associated with the WaitHook

  • element_id: an optional ID for the interface element (see here for more)

Output

A WaitHookResponse dictionary.

Example
  • Waiting for a waithook (stored as variable wait_hook) to be accessed.

  • Storing the response as a new variable called response.

1
2
3
4
5
6
7
8
9
- ppa.events.create_wait_hook:
  save: wait_hook

# In real life wait_hook.url would be sent elsewhere at this point...
- ppa.events.wait:
    text: Waiting for URL {{ wait_hook.url }}...
  load:
    secret: wait_hook.secret
  save: response

ppa.events.

wait_approval_response

Wait for a user to respond to an approval request.

Use in conjunction with the create_approval_request action.

Minimum Plugin Version: 8.0.0

Input
  • text: the text to display while waiting

  • approval_request: an ApprovalRequest

  • approved_message: an optional message to show the responder if they approve the request

  • rejected_message: an optional message to show the responder if they reject the request

  • element_id: an optional ID for the interface element (see here for more)

  • reason: set to true to ask the responder for a reason when they submit their response

Output

An ApprovalResponse dictionary.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
- ppa.events.create_approval_request:
  save: approval_request

# In real life the approval_request.approve_url & approval_request.reject_url
# would be pushed somewhere at this point...

- ppa.events.wait_approval_response:
    text: Waiting for approval response...
    approved_message: The changes will be applied right away!
    rejected_message: The changes will not be applied.
  load:
    approval_request: approval_request
  save: approval_response