Configuration schema

Overview of how to build App configuration

Introduction

App most usually requires some sort of configuration specific to its installation.

Below you can find the Ergonode CSV App configuration.

Ergonode CSV App configuration

Such configuration can be achieved by setting up the configuration_schema section in the Manifest file.

The value is a list of JSON Schemas allowing you to build a form.

Not full JSON Schema is yet covered in Ergonode.

If you have a case of a feature that suits your needs and is a part of the JSON Schema standard we may consider extending our implementation.

Please contact the respective Ergonode representative with the details.

The reason it's a list is fairly simple - in some scenarios, at first you need to input i.e. API Token, then choose which attributes from the App you'd want to configure - a piece of information that is only accessible once authorized within the system App is handling.

So the following steps in the form(following JSON Schemas) will be built once you correctly fill the current step.

Example schema

{
  // (...) rest of the Manifest file
  "configuration_schema": [
    {
      "title": "Configuration",
      "type": "object",
      "properties": {
        "simpleText": {
          "type": "string",
          "title": "Just a text",
          "propertyOrder": 1
        },
        "secret": {
          "type": "string",
          "title": "Secret password",
          "widget": "password",
          "propertyOrder": 2
        },
        "multilineText": {
          "type": "string",
          "title": "Multiline text",
          "widget": "textarea",
          "propertyOrder": 2
        },
        "simpleEnum": {
          "type": "string",
          "title": "Simple Enum",
          "enum": [
            "1",
            "2"
          ],
          "options": {
            "enum_titles": [
              "one",
              "two"
            ]
          },
          "propertyOrder": 4
        },
        "enumMultiple": {
          "items": {
            "type": "string",
            "enum": [
              "one",
              "two"
            ],
            "options": {
              "enum_titles": [
                "Choice one",
                "Choice two"
              ]
            }
          },
          "minItems": 1,
          "uniqueItems": true,
          "type": "array",
          "title": "Multiple choice enum",
          "propertyOrder": 6
        },
        "dictionaryErgonodeEnum": {
          "type": "string",
          "title": "Dictionary Ergonode Enum",
          "options": {
            "enum_dictionary": "ergonode:languages"
          },
          "propertyOrder": 7
        },
        "dictionaryAppEnum": {
          "type": "string",
          "title": "Dictionary App Enum",
          "items": {
            "type": "string",
            "options": {
              "enum_dictionary": "app:app-dictionary"
            },
            "minItems": 1,
            "uniqueItems": true
          },
          "propertyOrder": 8
        },
        "attributeMapping": {
          "type": "array",
          "title": "Attribute mapping",
          "items": {
            "title": "prototype",
            "type": "object",
            "properties": {
              "ergonode": {
                "type": "string",
                "title": "ergonode",
                "propertyOrder": 1
              },
              "app": {
                "type": "string",
                "title": "app",
                "propertyOrder": 2
              }
            },
            "required": [
              "ergonode",
              "app"
            ]
          },
          "widget": {
            "type": "mapper",
            "options": {
              "ergonodeDictionary": "ergonode:attributes",
              "appDictionary": "app:attributes"
            }
          },
          "propertyOrder": 9
        }
      },
      "required": [
        "simpleText",
        "secret",
        "multilineText",
        "simpleEnum",
        "enumMultiple",
        "dictionaryErgonodeEnum",
        "dictionaryAppEnum",
        "attributeMapping"
      ]
    }
  ]
}

Ok, so a lot is going on in this example. Let's break it down field by field.

simpleText

This is the simplest case.

It's a plain text that your user can input. It'll be displayed as a regular HTML text input.

secret

The secret is very similar to the previous simple text example but as with any other sensitive data you do not always want it visible constantly on your configuration. That's why a password widget is added - it results in a hidden secret text.

multilineText

Sometimes one-line text won't suffice. You can extend the text presentation thanks to the textarea widget.

simpleEnum

Another frequent case is a limited of values from which a user can choose. That's where the enum comes into play. There are 2 additional special fields added here

• enum - represents the actual valid value list to choose from

• options.enum_titles - represents the presentational titles list to be displayed to the user in dropdown

enumMultiple

An extended example of simple enums is when you have multiple choice allowed. Instead of using type string adjust it to array with string type elements.

dictionaryErgonodeEnum

Here's where things get a bit more kinky. You, again, need a predefined set of values but those values are already there in Ergonode i.e. a list of languages to choose from or an attribute.

A field options.enum_dictionary is added - in short, you tell the interpreter to render a list of languages from Ergonode via a dictionary ergonode:languages - this is resolved by Ergonode.

Ergonode dictionaries reference can be found here.

dictionaryAppEnum

Another possibility is that the predefined list is not part of Ergonode data but the App or system it integrates with. The App may define multiple dictionaries with different data.

App dictionaries reference can be found here.

Note this time options.enum_dictionary is wrapped into items - this changes the select to multi-select in the dropdown list.

attributeMapping

Occasionally, especially on synchronization Apps, you'll need attributes mapping from Ergonode to an external system. This is possible by combining two things.

A structure definition that can carry on the mapping

[
  {
    "ergonode": "attribute_one",
    "app": "attribute_two"
  }
]

and mapper widget capable of making it easier to map the data in the configuration user interface.

Widgets

Widgets are dedicated UI components that allow a custom presentation of a specific field.

password

Changes displaying of the plain text in HTML text input into password input.

password widget

textarea

Presents text input in the form of textarea input.

textarea widget

mapper

Allows for drag-and-drop mapping of the attributes and handles validation of their types.

The widget accepts 2 options:

• ergonodeDictionary - saying where from claim data - this option is mandatory

• appDictionary - this field is optional - if not present the Ergonode mapping will be possible to textual values

Attribute mapping widget overview

Attributes mapping widget details