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

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

display

Display tasks in a table.

The table will have the following columns:

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

Minimum Plugin Version: 3.0.0

Input

• text: the title of the table

• tasks: any number of Tasks to display in the table

Output

Nothing is outputted by this action.

Example

- ppa_api.tasks.started_by_me:
  save: my_tasks

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

ppa_api.tasks.

get_all

Get all tasks visible to the current user.

Minimum Plugin Version: 2.0.0

Input

deployed: set to true or false to only return deployed/undeployed tasks (defaults to all tasks)

Output

A list of Task dictionaries.

Example

- ppa_api.tasks.get_all:
    deployed: true
  save: deployed_tasks

ppa_api.tasks.

get_recent

Get tasks visible to the current user that were started in the last x days.

Minimum Plugin Version: 2.0.0

Input

days: the number of past days to include in the search (defaults to 30)

deployed: set to true or false to only return deployed/undeployed tasks (defaults to all tasks)

Output

A list of Task dictionaries.

Example

- ppa_api.tasks.get_recent:
    deployed: true
  save: recent_deployed_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

- 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

- ppa_api.tasks.get_started_by_me:
  save: my_tasks

ppa_api.tasks.

is_running

Find out if the supplied task is still running.

Minimum Plugin Version: 4.2.0

Input

• uuid: the task UUID

Output

A boolean is outputted by this action:

true if the task is running

false if it is not

Example

- ppa_api.tasks.start_async:
    name: Local Group Audit
    payload:
      group_name: Remote Desktop Users
  save: task

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

ppa_api.tasks.

select

Display tasks in a table, & prompt 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: 3.0.0

Input

• text: the title of the table

• tasks: any number of Tasks to display in the table

• minimum: the minimum number of acceptable selections

• maximum: the maximum number of acceptable selections

Output

A Selection containing:

• total: the number of selected Tasks

• all: a list of selected Tasks

• first: the first selected Task

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

- ppa_api.tasks.started_by_me:
  save: my_tasks

- ppa_api.tasks.select:
    text: My Tasks
  load:
    tasks: my_tasks
  save: selection

- ppa_api.tasks.display:
    text: Selected Tasks
  load:
    tasks: selection.all

ppa_api.tasks.

select_one

Display tasks in a table, & prompt the task operator to select one.

The table will have the following columns:

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

Minimum Plugin Version: 3.0.0

Input

• text: the title of the table

• tasks: any number of Tasks to display in the table

Output

A single Task.

Example

- ppa_api.tasks.started_by_me:
  save: my_tasks

- ppa_api.tasks.select_one:
    text: My Tasks
  load:
    tasks: my_tasks
  save: selected_task

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

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

- 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

- ppa_api.tasks.start_after:
    name: Local Group Audit
    minutes: 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

- 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

- ppa.ui.input_timestamp:
    text: Supply a Start Time
  save: start_time

- ppa_api.tasks.start_at:
    name: Local Group Audit
    description: Audit of Remote Desktop Users
    payload:
      group_name: Remote Desktop Users
  load:
    timestamp: start_time
  save: delayed_task