Developing Custom Script with CLI

Prerequisites

signageOS CLI - version 1.8.0 and newer
Minimal Core App version per platform that supports Custom Scripts:

Core App	Minimal Version
Samsung Tizen	2.8.0-rc.0 and newer
LG webOS	to be released
Windows	to be released
Linux	to be released
BrightSign	to be released
ChromeOS	to be released
Emulator	14.15.1 and newer

Create a new project

Copy the boilerplate code from signageOS/custom-script-boilerplate.

You will have a project with the following structure:

.
├── README.md
├── .sosconfig.json
├── .gitignore
├── default
│   └── setBrightness.js
├── linux
│   └── setBrightness.sh
├── tizen
│   └── setBrightness.js

How it works

Config file

When calling sos custom-script upload, it reads the .sosconfig.json file. This file contains several fields:

name - Custom Script will be created and displayed using this name
description - Short description of the Custom Script that will be displayed in Custom Script detail. It should help the user to understand what the Custom Script does.
version - Used for version control. Must follow the semantic versioning format. Each time the Custom Version changes, it should be incremented, however it's possible to overwrite the same version as long as its not published.
dangerLevel - Can be one of the following:
- low, medium, high, critical
- It represents the danger level of the Custom Script. It should be set according to the potential impact of the Custom Script on the device.
platforms - List of platforms and their files that will be uploaded to the signageOS platform.
configDefinition - list of accepted configuration parameters. It's a mandatory item, keep it empty if you do not need any variables ("configDefinition": [])

Platforms

The general structure of the platforms field is as follows:

{
	"{platform}": {
		"rootDir": "{rootDir}",
		"mainFile": "{mainFile}",
		"runtime": "{runtime}"
	}
}

{platform} - name of the platform. It should be one of:
- default, tizen, webos, android, linux, windows, brightsign
{rootDir} - relative path to the platform implementation. This is where the platform-specific files are located in this repository.
{mainFile} - entry point of the platform implementation. This file will be executed
{runtime} - runtime of the platform. It should be one of:
- ps1, bash, sh, nodejs, browser, brs

Platforms and supported runtimes matrix:

Platform	Available Runtimes
Samsung Tizen	browser
LG webOS	browser
Windows	ps1
Linux	bash sh
Android	browser sh
BrightSign	browser brs
ChromeOS	browser
Emulator (default)	browser

Config Definition

configDefinition is a list of accepted configuration parameters. It's a mandatory item, keep it empty if you do not need any variables ("configDefinition": []).

Config Definition item has the following options (same as Applet configuration):

Key	Value type	Description
name	string	name of the configuration
valueType	string \| url \| enum \| number \| secret \| encrypted	expected value type
list	array of strings \| numbers	only for valueType enum, list of predefined options
mandatory	boolean	required to be filled before building applet or assigning applet
description	string	description shown in the UI to guide user
placeholder	string	field placeholder in the UI to guide user; `placeholder` is never used as default value
min	number	minimum number value user can fill in to the field
max	number	maximum number value user can fill in to the field

`secret` and `encrypted` type in configuration

Script configuration is often used to pass sensitive data, such as tokens, credentials, and passwords. To protect these values, use the Script configuration with one of these value types.

secret value type

Use this type if you want to mask the value in the Box UI. It is suitable for less sensitive data. The value is stored in the database in its raw form and may be visible, for example, in deive history.
encrypted value type:

This type provides stronger protection. The value is encrypted using asymmetric encryption with a provided public key, which is generated for your company on demand. It is stored in encrypted form in the database and cannot be read anywhere.

Full example

.sosconfig.json with defined configDefinition
{
// ... .sosconfig.json 
"configDefinition": [
      {
        "name": "wifiSSID",
        "valueType": "secret",
        "mandatory": true,
        "description": "An SSID for the WiFi network.",
      },
      {
        "name": "authToken",
        "valueType": "encrypted",
        "mandatory": true,
        "description": "A token generated by My Control used for authentication against My cloud."
      },
      {
        "name": "myBaseUrl",
        "valueType": "URL",
        "description": "A base URL to My cloud. No slash at the end required.",
        "placeholder": "https://api.signageos.io"
      },
      {
        "name": "playerDuration",
        "valueType": "string",
        "description": "A length of generated playlist in '##s' format (seconds).",
        "placeholder": "172800s"
      },
      {
        "name": "refreshIntervalMs",
        "valueType": "number",
        "description": "Frequency of trying to generate new playlist from My cloud in milliseconds.",
        "placeholder": "65000",
        "min": 60000,
        "max": 70000
      },
      {
        "name": "playerId",
        "valueType": "string",
        "description": "An identifier for the device used to identifying against cloud. E.g. platform: SSSP, WEBOS, BRIGHTSIGN, ANDROID, WINDOWS, LINUX",
        "placeholder": "{PLATFORM}_{SERIAL_NUMBER}"
      },
      {
        "name": "proxyUrl",
        "valueType": "URL",
        "description": "A prefix for all HTTP(s) requests done by My player to My cloud. Default is no proxy.",
        "placeholder": "https://cors-anywhere.herokuapp.com/"
      }
    ]
}

.sosconfig.json when not using configDefinition
{
// ... .sosconfig.json 
    "configDefinition": []
}

Script output

Script can return back response(s) during it's execution. Each script runtime has a platform-specific syntax described below.

Runtime	Platform	Response
browser	Tizen BrightSign webOS	javascript function - `postResult('your response')`
bash / sh	Linux	Terminal - `stdout` or `echo 'your response'`
ps1	Windows	PowerShell - `Write-Output`

Sample code for browser runtime:

Script output in browser runtime
var brightness = sos.config.brightness;

sos.management.screen.setBrightness('03:00:00', brightness, '23:00:00', brightness)
	.then(function() {
        // pass custom response of the script
        postResult("SUCCESS! Brightness set to " + brightness);
    }).catch(function(e) {
        // pass custom response of the script
        console.log(e);
        postResult("FAILURE! Brightness not set to " + brightness);
    });

Upload custom script

Run the following command to upload your custom script to signageOS

sos custom-script upload

When calling sos custom-script upload, it reads the .sosconfig.json file. After the upload is completed, you will get customScriptUid in the uid field in .sosconfig.json file. Which you can use to run custom scripts using REST APIs.

Execute custom script

Your custom script can be executed on device using Box or REST API.

Custom scripts can be executed on one-by-one basis as well as using Bulk actions.

Prerequisites​

Create a new project​

How it works​

Config file​

Platforms​

Config Definition​

secret and encrypted type in configuration​

Full example​

Script output​

Upload custom script​

Execute custom script​