Last updated on July 30, 2015

Introduction to Device Tasks

Device Tasks is an Appspace extension that provides a task-based workflow to monitor, manage, and configure registered devices across your network. The extension is accessed via the Admin group in the Appspace extension drop-down menu, .


With the Device Tasks extension, network administrators can run a variety of device tasks with enhanced management options and reporting for Cisco Digital Media Players Under the Device Tasks extension, the following classes of tasks can be executed:

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

The following digital media player devices are supported in Device Tasks:

  • Cisco Edge 340
  • Cisco Edge 300
  • Cisco DMP 4310
  • Cisco DMP 4400

Task Definition

This is the most important detail to complete in creating a new task template. In this section, administrators are able to define the task parameters, commands, transform and triggers for each supported device type within their network.


Administrators are able to define settings for single as well as multiple devices in a single template, e.g. DMP4310 or EDGE300 devices.

The following settings are available for configuration in this section:

  • Parameters – user-defined variables that are passed or used in a device command (e.g. String, Number, Binary Stream).
  • Command – commands executed by the device and goes through a protocol (e.g. HTTP/S, RS-232).
  • Transform – applied to the output value of a task to convert it into a human readable value with context (e.g. from JSON or XML to String value).

Parameters

  • 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 and 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
    • ENV_DEVICE_PASSWORD – device password
  • 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.

Commands

Commands are specific instructions that will be executed on a device. The following command protocols are accepted:

  • 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.).
  • 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 sections 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}}

Transforms

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.

The following transforms can be performed:

  • Regex Match (String)
  • Regex Replace (String)
  • XSLT (String)
  • JSON (Input String | Output String)
  • String Replace (Input String | Output String)

Target Device

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:

  • Cisco Edge 340
  • Cisco Edge 300
  • DMP 4310
  • DMP 4400

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

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.