Application settings

Overview

Settings are a collection of parameters, which can be used to provide application with information that is needed for it to work correctly. App manifest contains a section which collects customer's specific settings. Elements defined as settings will be used to create a configuration step for an app when it's being launched by a customer. Application code can retrieve settings for a specific routeId in runtime, using a key injected in a header of every request to an app.

App manifest

Settings are configured in socotra-app.json manifest file at the following path

{
  "name": "org-name/app-name",
  "version": "0.0.1",
  "app": {
    "fields": [
      // Collection of setting objects
    ]
  }
}

Each entry in settings collection is a json object with following properties.

name string (required) - Property which defines field name and, thus, a key in a map that will be used by app to retrieve value of this setting, configured by customer.

title string (required) - Description of a field for configuration step.

type string (required) - Fixed type of a field. This defines how field input will be rendered. Supported values :

• Select - renders a dropdown for provided list of values
• Text - renders an input for text.
• Password - renders an input for text, but text input value is not visible by default.

hint string (optional) - Optional text which can be used to explain details or give more context to customer, in addition to Title

required boolean (optional) - A flag which indicates whether application strictly requires an input for this field or it's optional and can be skipped in configuration step.

sensitive boolean (optional) - A special flag for setting which enables the same behaviour as Password type - value can be entered or selected but can't be never read for reconfiguration of an app. Customer would need to enter\select value again or old one will be reused.

values array (required if type='Select') - Array of objects for a dropdown list. Each object in this array has 2 properties - text to render for this item and value which is used as actual value for a selected item.

Example:

{
  "name": "org-name/app-name",
  "version": "0.0.1",
  "app": {
    "fields": [
      {
        "name": "input-setting",
        "title": "Required input field",
        "type": "Text",
        "required": true,
        "hint": "This is a hint for simple input field."
      },
      {
        "name": "password-setting",
        "title": "Required password field",
        "type": "Password",
        "required": true
      },
      {
        "name": "sensitive-input",
        "title": "Optional sensitive input",
        "type": "Text",
        "sensitive": true,
      },
      {
        "name": "week-start-day",
        "title": "First day of the week (no hint needed)",
        "type": "Select",
        "values": [
          {
            "text": "Monday",
            "value": "MON"
          }
          {
            "text": "Sunday",
            "value": "SUN"
          }
        ]
      }
    ]
  }
}