# The app.json file

# Usage

The app.json file is used in Edge Apps to tell the user interface what parameters have to be set and what each parameter is. It also defines pages that the user is expected to view with details of every parameter. It is expected that the user also have to set the installation before the guide starts and that the name of the instance is chosen by the user.

# Inputs

Inputs are description of form items that the user is expected to enter to configure the app. It is up to the UI to implement the different components that is shown here. The resulting configuration should be sent as the config parameter in the API to configure a new instance.

All inputs have the following variables:

Name	Default	Description
required	false	If the field is required to continue
name		Display name for the variable
type		Type of selector, as described here
description		Help text to describe what the variable actually is used for

# `single_function_selector`

Let the user select a single function in a list of functions. Optionally allow the user to set a value of the selected function. For example if the app should control a light the dimmer or on/off state can be set. When selecting a value the UI is expected to show differently for different function-types.

Name	Default	Description
filter	`{}`	A json object with key-value mapping used as query params for FunctionX query
value	false	If the user is expected to set the value (example on/off or dimmer)

# Config result

With values:

{
  "input-name": { "<function-id>": <value> }
}

Without values:

{
  "input-name": <function-id>
}

# `multi_function_selector`

Same as single-selector but the user can set several functions.

Name	Default	Description
filter	`{}`	A json object with key-value mapping used as query params for FunctionX query
value	false	If the user is expected to set the value (example on/off or dimmer)

# Config result

With values:

{
  "input-name": {
    "<function-id-1>":  <value>,
    "<function-id-2>":  <value>,
  }
}

Without values:

{
  "input-name": [
    <function-id-1>,
    <function-id-2>
  ]
}

# `single_device_selector` and `multi_device_selector`

Same as function-selectors but with devices displayed.

# `single_notification_output_selector`

Allows the user to select one of the existing notification outputs already present on the installation. Optionally also allow the user to leave the current configuration step and go to a new flow for adding a notification output. This should be done in a separate flow (eg. New tab, new window, popup, overlay). After completion the user should return to the configuration guide for the app where the list of available notifications have been refreshed. Allowing the user to select the notification output that was just created.

Name	Default	Description
allow_add	`true`	Allow adding new notification outputs

# Config result

{
  "input-name": <notification-output-id>
}

# `multi_notification_output_selector`

Same as single-notification-selector but the user can set several outputs.

Name	Default	Description
allow_add	`true`	Allow adding new notification outputs

{
  "input-name": [
    <notification-output-id-1>,
    <notification-output-id-2>
  ]
}

# `text`

Let the user select a text string, optionally conforming to the validator regexp.

Name	Default	Description
default		Value to populate the field with when nothing is entered
multiline	false	If the text input field should be single or multiline
validator		Optional regexp for validating the input field, empty means no validation
on_error		Optional error message if the validator fails on the input field

# Config result

{
  "input-name": "<value>"
}

# `number`

Name	Default	Description
default		Value to populate the field with when nothing is entered

# Config result

{
  "input-name": <value>
}

# `option`

Let the user select one of several values.

Name	Default	Description
default		The initial selected value
values	`{ }`	A mapping of value to name for the selection as a JSON object

# Config result

{
  "input-name": <value>
}

# `checkbox`

Let the user select one or several options in a checkbox style.

Name	Default	Description
default		The value of the selection by default
values	`{ }`	A mapping of value to name for the selection in JSON object

# Config result

{
  "input-name": [
    <value-1>,
    <value-2>
  ]
}

# `toggle`

Let the user toggle between two values for a boolean style parameter.

Name	Default	Description
default	false	The initial state of the toggle-switch
false_value		The value to set if the toggle is in the false position
true_value		The value to set if the toggle is in the true position

# Config result

{
  "input-name": <value>
}

# `repeat`

Let the user select the same variables several times resulting in an array of objects in the config.

Name	Default	Description
min	0	The min amount of entries needed
max	unlimited	The max amount of entries needed
input_fields		The fields that should be included in every iteration of the repeat instruction.

# Config result

{
  "input-name": [
    {
      "input-name-1": <config-object>,
      "input-name-2": <config-object>
    },
    {
      "input-name-1": <config-object>,
      "input-name-2": <config-object>
    },
  ]
}

# Guide

The guide part describes different pages that the user is expected to step through. Each page should consist of one or several input fields. The rendering of the fields is determined by the inputs object. The pages are rendered in the order of the array.

Each page can have a title and description to explain the scope of that page and its options. It also have an array of variables that are expected to render for the user. The names of the input_fields should correspond to the JSON-name of the input objects.

# Example

This is an example for a configuration with two function selectors and a text-field.

{
  "author": "IoT Open",
  "licence": "MIT",
  "input": {
    "actuator_function": {
      "type": "single_function_selector",
      "name": "Controlled functions",
      "description": "This function that is turned to on when app is triggered."
    },
    "trigger_function": {
      "type": "single_function_selector",
      "name": "Trigger function",
      "description": "The door that will trigger the light to turn on.",
      "value": true
    },
    "timeout": {
      "type": "number",
      "name": "Light on time",
      "description": "The time that the control function will be on before turning off again in minutes.",
	  "default": "10"
    },
    "trigger_value": {
      "type": "single_function_selector",
      "name": "Function",
      "description":  "Select function",
      "value": true,
      "filter": {
        "type": "temperature"
      }
    },
    "temp": {
      "type": "repeat",
      "name": "Temperature triggers",
      "description": "Select a function and the value that should trigger the app to run.",
      "min": 2,
      "max": 4,
      "input_fields": [
        "trigger_value"
      ]
    },
    "notification": {
      "type": "single_notification_output_selector",
      "name": "Notification",
      "description": "Select how you should be notified if the app have to send an alarm."
    },
    "text_example": {
      "type": "text",
      "multiline": false,
      "default": "Example text",
      "validator":  "[a-zA-Z]*",
      "on_error": "The text can only contain letters"
    }
  },
  "guide": [
    {
      "id": "stage_1",
      "title": "Function selection",
      "description": "Set the functions you want to use.",
      "input_fields": [
        "trigger_function",
        "actuator_function"
      ]
    },
	{
	  "id": "stage_2",
	  "title": "Timeout settings",
	  "description": "",
	  "input_fields": [
		"timeout",
        "temp",
        "notification",
        "example_text"
	  ]
	}
  ]
}

The resulting config-object for the API then looks like this:

{
  "app_id": 5,
  "installation_id": 12,
  "version": "1.0.0",
  "config": {
    "timeout": 10,
    "trigger_function": 123,
    "actuator_function" : {
      "4456": 255
    },
    "temp": [
      { "trigger_value": { "9":  26}},
      { "trigger_value": { "9":  35}},
      { "trigger_value": { "12":  10}}
    ],
    "notification": 456,
    "example_text": "HelloWorld"
  },
  "name": "My app instance"
}

← Schedules Package lynx →

# The app.json file

# Usage

# Inputs

# single_function_selector

# Config result

# multi_function_selector

# Config result

# single_device_selector and multi_device_selector

# single_notification_output_selector

# Config result

# multi_notification_output_selector

# text

# Config result

# number

# Config result

# option

# Config result

# checkbox

# Config result

# toggle

# Config result

# repeat

# Config result

# Guide

# Example

# `single_function_selector`

# `multi_function_selector`

# `single_device_selector` and `multi_device_selector`

# `single_notification_output_selector`

# `multi_notification_output_selector`

# `text`

# `number`

# `option`

# `checkbox`

# `toggle`

# `repeat`