Last updated on January 16, 2018

Defining tasks

Device Tasks is accessed via 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.

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 configured 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.).
- Script - Allows the execution of javascript fragments, which may invoke sign 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.
Note

Only Portal Administrators are able to set tasks to Global.

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
Sample Shell tasks
Sample RS-232 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

A list of HTTP APIs is available in the Edge-300-Configuration-Guide-Release-1.5.
The URL used in this task definition points to localhost (127.0.0.1) as the task is executed on the device itself.

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

A list of HTTP APIs is available in the Edge-300-Configuration-Guide-Release-1.5.
The URL used in this task definition points to localhost (127.0.0.1) as the task is executed on the device itself.

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.