# 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"
}