PPA PPA: Events

Summary

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

Actions

ppa.events.

create_wait_hook

Create a waithook with a URL & secret.

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: 1.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

  • reason: text to display when the action runs (defaults to no text displayed)

Output

Nothing is returned from this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
- ppa.events.send_email:
    subject: PPA Notification
    html: >
      <html>
        <head>PPA Email Header</head>
        <body>PPS Email Body</body>
      </html>
    text: Start
    plain_text: >
      PPA Email Header

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

Remember

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

Any default SMTP recipients configured in PPA will be appended to the recipients list.

ppa.events.

send_syslog_event

Send a CEF 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