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