PPA API PPA API: Tasks

Summary

This module contains actions for starting tasks in PPA & viewing task history.

PPA Version

The actions in this module require PPA v2.7.x or newer.

Actions

ppa_api.tasks.

cancel

Cancel a running task.

Minimum Plugin Version: 2.0.0

Input
  • uuid: the task UUID
Output

Nothing is outputted by this action.

Example
1
2
3
4
5
6
7
8
9
- ppa_api.tasks.start_async:
    name: Local Group Audit
    payload:
      group_name: Remote Desktop Users
  save: task

- ppa_api.tasks.cancel:
  load:
    uuid: task.uuid

ppa_api.tasks.

get_all

Get all tasks visible to the current user.

Minimum Plugin Version: 2.0.0

Input

This action takes no inputs.

Output

A list of Task dictionaries.

Example
1
2
- ppa_api.tasks.get_all:
  save: all_tasks

ppa_api.tasks.

get_result

Get the saved result from the supplied task.

This is the only action that outputs the result_json saved by a task.

Minimum Plugin Version: 2.0.0

Input
  • uuid: the UUID of the task
Output

A single TaskResult dictionary.

Example
1
2
3
4
- ppa_api.tasks.get_result:
  load:
    uuid: task.uuid
  save: task_result

ppa_api.tasks.

get_started_by_me

Get all tasks that were started by the current user.

Minimum Plugin Version: 2.0.0

Input

This action takes no inputs.

Output

A list of Task dictionaries.

Example
1
2
- ppa_api.tasks.get_started_by_me:
  save: my_tasks

ppa_api.tasks.

input_table

Display tasks in a table, & allow the task operator to make a selection.

The table will have the following columns:

  • Name
  • Started By
  • Started At
  • Stopped At
  • State

Minimum Plugin Version: 2.0.0

Input
  • text: the title of the table

  • tasks: a single or list of Task dictionaries to display in the table

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

Output

A single or list of Task dictionaries.

Tip
  • If neither a minimum or maximum is provided, the task operator will be able to submit 0 selections.
  • If minimum or maximum are provided, the operation will repeat until the task operator makes a valid number of selections.
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
- ppa_api.tasks.started_by_me:
  save: my_tasks

- ppa_api.tasks.input_table:
    text: My Tasks
    minimum: 1
    maximum: 1
  load:
    tasks: my_tasks
  save: selected_task

- ppa_api.tasks.get_result:
  load:
    uuid: selected_task.uuid

ppa_api.tasks.

output_table

Display tasks in a table.

The table will have the following columns:

  • Name
  • Started By
  • Started At
  • Stopped At
  • State

Minimum Plugin Version: 2.0.0

Input
  • text: the title of the table

  • tasks: a single or list of Task dictionaries to display in the table

Output

Nothing is outputted by this action.

Example
1
2
3
4
5
6
7
- ppa_api.tasks.started_by_me:
  save: my_tasks

- ppa_api.tasks.output_table:
    text: My Tasks
  load:
    tasks: my_tasks

ppa_api.tasks.

start

Start a task & wait for it to complete.

Minimum Plugin Version: 2.0.0

Task Interaction

This plugin cannot interact with a task once it has started.

If the task requires user input once started, the task may never complete.

You can use payloads to create tasks that require no interaction.

Input
  • name: the name of the inventory image

  • payload: an optional payload to supply to the task (defaults to empty)

  • timeout: optional number of seconds to wait (defaults to 600)

Output

A single Task dictionary.

Example
1
2
3
4
5
- ppa_api.tasks.start:
    name: Local Group Audit
    payload:
      group_name: Remote Desktop Users
  save: task

ppa_api.tasks.

start_after

Create a delayed task that will start after a number of minutes has elapsed.

Minimum Plugin Version: 2.0.0

Minimum PPA Version: 2.8.0

Input
  • name: the name of the inventory image

  • description: a description explaining the purpose of the delayed task

  • minutes: the number of minutes to wait until starting the task

  • payload: an optional payload to supply to the task (defaults to empty)

Output

A single DelayedTask dictionary.

Example
1
2
3
4
5
6
- ppa_api.delayed_tasks.create:
    name: Local Group Audit
    delay: 60
    payload:
      group_name: Remote Desktop Users
  save: delayed_task

ppa_api.tasks.

start_async

Start a task & continue without waiting.

Use this action if:

  • You don't need to wait for the task to finish

  • You want to loop & poll the task state yourself

Minimum Plugin Version: 2.0.0

Task Interaction

This plugin cannot interact with a task once it has started.

If the task requires user input once started, the task may never complete.

You can use payloads to create tasks that require no interaction.

Input
  • name: the name of the inventory image

  • payload: an optional payload to supply to the task (defaults to empty)

Output

A single Task dictionary.

Example
1
2
3
4
5
- ppa_api.tasks.start_async:
    name: Local Group Audit
    payload:
      group_name: Remote Desktop Users
  save: task

ppa_api.tasks.

start_at

Create a delayed task that will start at a certain time & date.

Minimum Plugin Version: 2.0.0

Minimum PPA Version: 2.8.0

Input
  • name: the name of the inventory image

  • description: a description explaining the purpose of the delayed task

  • timestamp: a TimeStamp outputted by the input_timestamp action

  • payload: an optional payload to supply to the task (defaults to empty)

Output

A single DelayedTask dictionary.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- ppa.ui.input_timestamp:
    text: Supply a Start Time
  save: start_time

- ppa_api.delayed_tasks.create:
    name: Local Group Audit
    payload:
      group_name: Remote Desktop Users
  load:
    timestamp: start_time
  save: delayed_task