Last updated on April 22, 2016

Introduction to Device Tasks

Device Tasks, is an Appspace extension accessed via the Admin group in the Appspace menu, which provides Network Administrators a task-based workflow to monitor, manage, and configure registered devices across a network, such as:

  • Monitoring Tasks – Provides the ability to periodically query devices and read back specific values at set frequencies.
  • Advanced Tasks – Enables the definition of more complex tasks that can be scheduled or deployed immediately.
  • Device Configuration – Provides a framework to define configuration parameters for a device that can be accessed anytime.

A task can have a series of different target devices. Depending on the type of device that is present in the network when the task is executed, the appropriate task definition will be executed for the correct device profile. The list of supported target devices includes the following:

  • Chromebox devices 1
  • Cisco Edge 340
  • Cisco Edge 300
  • Cisco DMP 4310
  • Cisco DMP 4400

Note

1 Chromebox device management is primary handled by Google Chrome Device Management (CDM). Currently, the following Device Tasks are available for Chromebox devices:

  • Software updates
  • RS232 screen ON/OFF commands
  • HTTP
  • Javascript. Javascript tasks are allowed to execute local App APIs or Device APIs, and do not replace or replicate features available on Google CDM.

Device Tasks Layout and Interface

The following illustrates the layout of the Device Tasks extension in Appspace.

Dashboard tab

The Dashboard tab is the default landing page. The Dashboard page displays the network tree, all deployed tasks, and the number of task displayed. You can configure the dashboard to select tasks to monitor.


Device Configuration tab

The Device Configuration page allows administrators to configure various device parameters, whether it is for a single device, a group of devices within a sub-network, or all devices available in the entire network. The open framework also makes it possible to set new configuration options.


Monitoring Tasks tab

The Monitoring Tasks page allows administrators to view the status of tasks for various devices, based on the pre-configured templates in Device Tasks for each device, group of devices, or each network. For each task that is displayed, you can view the name, target devices, parameter, value, source, and the task’s health status with status alert icons displayed next to affected devices.

These attributes can be queried based on a configured frequency.


Advanced Tasks tab

This page enables administrators to customize and deploy tasks containing specific actions for supported devices. There is also the option to schedule task deployments over a defined period, enabling enhanced automation, and simplifying management of the devices.


The details that are viewable in this tab are:

  • Task Name
  • Target Devices for task deployment
  • Source (network, sub-network, device group)
  • Last Deployed date of task
  • Schedule (Immediate, On-Demand or specific timeframe)
  • Task Health Status (with Status Alert Icons displayed next to affected devices)

Task Templates tab

In the Task Templates page, administrators can create and customize task templates for specific device types within a group or network. A default collection of configuration, monitoring, and advanced tasks will be pre-populated in this page for use on the list of supported devices. Task templates can also be imported and exported to allow for contributions from the greater community.

There are three types of templates that can be created here:

  • Configuration templates – for use in the Device Configuration tab.
  • Monitoring templates – for use in the Monitoring Tasks tab.
  • Advanced Task templates – for use in the Advanced Tasks tab.

A newly created task template will need to contain the following details:

  • Task Class (the type of task template)
  • Task Name
  • Description
  • Common Parameters
  • Task Definition (please refer to the next section)
  • Availability (global or specific location)
  • Schedule

Defining a Task

When creating a new task template, defining a task’s parameters, commands, transforms, and triggers for each supported device type within their network, is the most crucial.

Administrators can define settings for single or multiple devices in a single template. The following settings must be configure to define a task:

  • Parameters – User-defined variables that are passed or used in a device command (e.g. String, Number, Binary Stream).

    • Common parameters - Common parameters allow you to enter custom variables that are common across many device types.

    • User-defined parameters - User-defined parameters provide you with more flexibility to define variables and properties that are unique to the system or device. Listed below are the types of parameters a user can define:

      • Type – defines the variable type (String, Number, Binary Stream, Boolean, Enumerator).
      • ID – an identifier that is used for replacements in the task definitions. The ID must contain lowercase characters, numbers, period (.), and underscore (_), (e.g. http_proxy or http.proxy).
      • Display Name – descriptive name for the variable (e.g. HTTP Proxy).
      • Default Value – a default value for the variable. (e.g. http://www.example.com:7777), or it can be left blank and be filled up later during deployment.

    • Environment-defined parameters - Environment-defined parameters are variables that are environment dependent. These variables are not user customizable, are evaluated during task execution, and will finally be replaced with a device-dependent value.

      Listed below are some example environment-defined parameters:

      • ENV_APPSPACE_URL – Appspace URL the device is registered to.
      • ENV_TASK_ID – ID of the current task being executed.
      • ENV_PLAYER_GUID – player GUID.

    • Object Types - Parameters can be of the following object types:

      • String – most common parameter format.
      • Number – used for number-specific parameter variables.
      • Binary Stream – prepares a binary for streaming to a device.
      • Boolean – can be applied to discrete (0/1) values.
      • Enumerator – provides the ability to have a list of enumerated values.

  • Command – Commands are specific instructions executed by the device with one of the following protocols:

    • HTTP/S – The HTTP/S query makes a request to the specific URL and the response is considered the task return value. It can also be used for REST-based queries that make requests to a specified URL using user-specified methods (e.g. PUT, GET, DELETE, etc.).
    • Javascript - Allows the execution of javascript fragments, which may invoke application or device APIs, in Appspace App driven devices.
    • Shell – This accesses the device shell or OS. Enter a shell script command or text for execution.
    • RS-232 – This allows the transmission of RS-232 commands and makes a request over the local COM port.
    • Raw Socket – This allows the transmission of messages via IP/POST and communicated over TCP/UDP.

    All fields in the COMMAND section can accept placeholders for parameter ID replacement. The replacements follow the form {{parameter_id}}. For example: If the parameter ID is “http.proxy” then the placeholder would be {{http.proxy}}


  • Transform – As tasks are executed, the resulting values that are read back from the devices can vary depending on the device type. As different devices may have different commands to execute the same task, the resulting values will be different. In order to normalize these values into a standard output format that can be standardized for reporting, the ability to apply transforms need to be present. A transform is essentially a post-processing step that normalizes the task output, converting it into a human readable value with context (e.g. from JSON or XML to String value), such as the following:
    • Regex Match (String)
    • Regex Replace (String)
    • XSLT (String)
    • JSON (Input String | Output String)
    • String Replace (Input String | Output String)

  • Availability – When creating task templates, the availability defines where the task can be deployed. There are two options for availability:
    • Global – This option will make the task available globally throughout the entire network.
    • Specific Location* – The network tree UI selection is displayed and the selected node will have the task available. For example, a task that is made to be available at the parent network will be available for deployment anywhere in that network. If the task is only made available for a specific player group, then the visibility and deployment will only be to that specific group.

  • Schedule – The schedule property determines when and how often the task is to be executed. The following options are supported:
    • Immediate – The task will be deployed immediately.
    • Over a Date Range – Specify a start and end date/time range.
    • Only on Device Condition (On Boot) – Runs the task when the device boots.
    • On Constant Frequency – This sets a recurrence pattern every x number of minutes.

Sample Tasks and Transforms

Below are several sample custom tasks:


Sample HTTP/S tasks

Example 1: Getting Memory Usage (HTTP/S, GET)

This task retrieves the current memory usage of the target device.



Type: HTTP/S
Method: Get
URL: http://127.0.0.1:7777/get_param?p=sinfo.memory
Parameters: None

Note

  • A full list of available DMP 4310/4400 MIBs parameters can be obtained from http://{DMP IP}/get_param?p=*.
  • The URL used in this task definition points to localhost (127.0.0.1) as the task is executed on the device itself.

Example 2: Deleting Logs (HTTP/S, DELETE)

This task deletes the log file on a device.



Type: HTTP/S
Method: Delete
URL: http://127.0.0.1/api/1.0/sys/log
Header: password={{ENV_DEVICE_PASSWORD}}
Parameters: None

Note


Example 3: Set Log Size (HTTP/S, PUT)

This task sets the log size for an Edge 300 device.


Type: HTTP/S
Method: Put
URL: http://127.0.0.1/api/1.0/sys/size
Header: Content-Type=application/json;password={{ENV_DEVICE_PASSWORD}}
Body: {"size":"{{size}}"}
Parameters: None

Note

Sample Shell tasks

Example 1: Switch Between Player and Desktop Mode

This task switches the device’s mode between player and desktop.



Type: Shell
Device: Edge 340
Command: ./apps/nexus2/switchmode.sh {{mode}} && reboot
Parameters: mode (user defines player or desktop mode during deployment)

Example 2: Retrieve Download Manager Log (DMP)

This task uploads the downloadmanagerlog.txt to a handler in Appspace, allowing you to download it to your local PC.



Type: Shell
Device: DMP 4310/4400
Command:
  wget --post-file=/tmp/ftproot/usb_1/Logs/downloadmanagerlog.txt -qO- "{{ENV_APPSPACE_URL}}"/api/v1/core/tasks/payload/stream/
  upload?filename=downloadmangerlog.txt&clientguid={{ENV_PLAYER_ID}}&deployedtaskid={{ENV_TASK_ID}}

Note

The wget command is used as the wget library on the DMP contains the –post-file flag which allows the contents of a file to be sent via the POST method. For more info, SSH into a DMP4310/4400 and run wget -help.

Example 3: Replacing nexusmediaplayer.swf on the device (EDGE)

This task can be divided into two parts:

The first part copies/backs-up the original nexusmediaplayer.swf and uploads it to Appspace. You will be able to retrieve the file when this task is deployed.

The second part replaces the backed-up nexusmediaplayer.swf file with another nexusmediaplayer.swf file that’s located on a local server with a local IP. The parameter defined is local_ip and upon deploying this task, the user will be asked to set the IP of the local server.



Type: Shell
Device: Edge 340
Command:
  curl --upload-file /apps/nexus2/nexusmediaplayer.swf -X POST"{{ENV-APPSPACE_URL}}/api/v1/core/tasks/payload/stream/upload?
  filename=downloadmanagerlog.txt&clientguid={{ENV_PLAYER_GUID}}&deployedtaskid={{ENV_TASK_ID}}"

  wget -O /apps/nexus2/nexusmediaplayer.swf http://{{local_ip}}/nexusmediaplayer.swf
Parameters: local_ip (user defined during deployment)

Sample RS-232 tasks

Example: Sending an hex command through a device (EDGE)

In this example, the task sends an hex command through an Edge device to be sent to a screen. You will have to define a parameter ID first before setting it as the command in the task definition. In this example, the parameter ID used is hexcommand and it is defined in the task as {{hexcommand}}. During the deployment of this task, the user will be required to set a value for hexcommand which in turn sets the command value that will be sent to the device.



Type: RS-232
Device: Edge 300
Command: {{hexcommand}}
Parameters: hexcommand

Sample Transforms

Example 1: Getting MAC address from a DMP 4400 (Regex Match)

In this example, we use Regex Match to find, match and return output values. Regular expressions can be built using quick references which are available online. This expression shown was built using MSDN’s Regular Expression Language Quick-Reference as a guideline.


Match Pattern: ((\d{2}|\w{2}|\d\w|\w\d):?){6}

Regex expressions can be tested with free Javascript regex testers which are available online. Here is an example of a tested regular expression used to find a DMP’s MAC address.


The output of the task deployment shows both raw and transformed outputs.

Example 2: Getting NTP Server URL from a DMP 4400 (String Replace)

In this example, we set a transform where it searches for the string “ntpc.hostname T_STRING” and replaces it with nothing, effectively removing that string.


The output of the task deployment shows both raw and transformed outputs.

Example 3: Getting gateway from an Edge 300 (JSON Transform)

In this example, we set a JSON transform where it searches for the string “gateway” and displays its associated value/keyword.


The output of the task deployment shows both raw and transformed outputs.