Tag: <task> - Task Definition

Definition

The <task> tag is used to define a task that can be run by either the PxM Platform or a user, depending on how the task is defined.

The tag has the following attributes:

Parameters

  • name (str) : This is the internal name of the task. This is the name is used when calling the task as a subtask.
  • display_name (str) : This is the display string used in the Web Management Interface when picking the task in a profile. The presence of this attribute defines the task as a User Task. Without this attribute the task is not visible in the Web Management Interface.
  • type (str) : This defines the type of task. The default if not specified is status.
  • access (str): This defines the type of access to be used by the task. The default if not specified is shell.

Fieldtypes Values

The fieldtype attribute can have the following values:

Fieldtype Value Description
status This is a task that simply returns a success or failed status. The task also display a message, or fetch a file but the basic underlying task returns success or failed.
namevalue This is a task that returns a set of name value pairs defined by the child command tags. This fieldtype is used exclusively by the inventory_task task.
dataset This is a task that returns an array of multiple name value pairs. This fieldtype is used exclusively by the user_show_all task.
fileout This is a task that retrieves a file from a device and stores it on the PxM Platform. The contents of a file can also be captured and stored in a file on the PxM Platform.

Usage Examples

There are several uses of the <task> tag. Some are special internal tasks that the PxM Platform uses itself to manage accounts and to interact with the device. Some tasks are presented to user to run and others can be run on a schedule.

A basic breakdown of tasks is:

  • version_command
  • user_show_all
  • inventory_task
  • User Management Tasks
  • Device Provisioning Tasks
  • User Tasks
  • Scheduled Tasks
  • File Retrieve Task

version_command Task

The task that reads the device version (version_command) is documented here: Tag: <version>.

user_show_all Task

The user account audit task (user_show_all) is documented here: Tag: <task-user-show-all>.

inventory_task Task

The task that collects device version information to be displayed on the in the inventory report (inventory_task) is documented here: Tag: <task-inventory>..

User Management Tasks

The user management tasks are internal tasks that the PxM Platform uses to manage accounts on a device. These tasks are:

  • tag-task-user-add
  • tag-task-user-set-password
  • tag-task-user-delete.md
  • tag-task-user-enable.md
  • tag-task-user-disable.md

These are all special internal tasks that MUST have these exact task names. The actions they perform are pretty self explanatory by there names. Click on any of the names above for a more detailed explanation of each task.

Device Provisioning Tasks

These four tasks are again special internal tasks, that are used at the start and end of the provisioning and unprovisioning of a device.

  • device_provision_start
  • device_provision_end
  • device_unprovision_start
  • device_unprovision_end

These tasks can be used to perform any special steps that might be required on a device before the PxM Platform performs the main provisioning steps. Then any steps that might be required after provisioning can also be performed. Likewise any commands required before and after unprovisioning can also be defined.

These tasks are just normal type='status' tasks then perform commands to prepare a device for use within the PxM Platform. In most cases these tasks are not required, but the MUST be defined in the template. To define them but mark them as unimplemented, the template might contain:

1
2
3
4
   <task name='device_provision_start' type='unimplemented'/>
   <task name='device_provision_end' type='unimplemented'/>
   <task name='device_unprovision_start' type='unimplemented'/>
   <task name='device_unprovision_end' type='unimplemented'/>

User Tasks

The most common use of the <task> tag is to define new User Tasks.

This online help includes a full tutorial on how to add additional tasks to templates. It can be found here: :ref:tutorial-adding-user-tasks.

File Retrieve Task

Some tasks need to fetch a file back from a device. There are a few ways this can be achieved. Full details of how to do this can be found in the Adding Tasks to Templates tutorial here: Tutorial coping files from a device`

Parent Tags

Child Tags