Dictionaries

Extend the configuration via dictionaries

Sometimes you need to choose from a predefined list of values already existing in the system.

In the configuration, it's not always easy as the values may be related to the configuration itself. The values may be available only after configuring the API Key in step one etc, therefore, cannot be part of the regular schema.

That's where the dictionaries come in handy. There are two sources of the configuration. The data either come from Ergonode or App.

The source of the dictionary is recognized via prefixes ergonode: and app:

Ergonode

List of available dictionaries

• ergonode:attributes

  • it is possible to limit types of attributes thanks to query parameters - egonode:attributes?type=TEXT,TEXT_AREA

• ergonode:categories

• ergonode:languages

App

In App, you can define as many custom dictionaries as you require.

In Manifest configuration_schema you reference the dictionary by the conjunction of app: prefix and dictionary ID suffix i.e app:attributes.

App provides custom dictionaries by implementing /dictionary/{dictionary} endpoint.

For the above example, the endpoint would be /dictionary/attributes.

The dictionary endpoint will be called only when the step of the configuration schema it is defined in is generated, so you have all the configuration from earlier steps at your disposal during dictionary retrieval(like API keys, etc).

The endpoint response for the valid dictionary should return

{
  "dictionary": [
    {
      "id": "value",
      "label": "Presentation label"
    }
  ]
}

Type validation

If your mapping requires extra type validation, you may provide type for every entry that matches the mapping context. For multiple types, separate them with |.

{
  "dictionary": [
    {
      "id": "description",
      "label": "Description attribute",
      "type": "TEXT_AREA|TEXT"
    }
  ]
}

Merging values

By default, mapping on dictionary items allows only one value to be mapped to a specific attribute. It is possible to override this behavior by declaring the possibility of merging via allows_merging flag.

If enabled, the App is responsible for merging value itself according to internal strategy - flag only changes the behavior of the mapper, and values are provided to App the same way.

{
  "dictionary": [
    {
      "id": "description",
      "label": "Description attribute",
      "allows_merging": true
    }
  ]
}