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:
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
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 endpoint response for the valid dictionary should return
The endpoint will be called only on generating the step of the configuration schema it is defined in - so you have all the earlier steps of configuration at your disposal during dictionary retrieval.
Overview of how to build App configuration
App most usually requires some sort of configuration specific to its installation.
Below you can find the 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.
Ok, so a lot is going on in this example. Let's break it down field by field.
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.
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.
Sometimes one-line text won't suffice. You can extend the text presentation thanks to the textarea widget.
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
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.
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.
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.
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
and mapper widget capable of making it easier to map the data in the configuration user interface.
Widgets are dedicated UI components that allow a custom presentation of a specific field.
Changes displaying of the plain text in HTML text input into password input.
Presents text input in the form of textarea input.
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
Full reference of Manifest file.
Manifest is a simple JSON file that describes your App behavior and its possibilities.
To refresh the App Manifest, it has to be changed and reapplied - just like on App registration. Ergonode does not refresh it automatically.
Remember also, on refreshment, to raise the version - otherwise, changes won't be applied as described in the version restrictions description.
Contained fields:
A simple text describing under what name your app is visible in the Ergonode available Apps tab.
This value should allow easy identification of what your App does.
Restrictions:
has to exist and not be empty
the length of the name is limited to 30 chars and should be no less than 3 chars.
A simple text describing the purpose fulfilled by the App.
Restrictions:
has to exist and not be empty
the length of the name is limited to 200 chars and should be no less than 20 chars.
A semantic version of your manifest. It does not necessarily need to address your application version but rather the content of the Manifest file.
Restrictions:
has to exist and not be empty
when reapplying the Manifest for App update the changes may only be applied when the new version is higher than the existing ones - otherwise, changes will not take effect.
A semantic version that the current version of the Manifest is compatible with.
This allows Apps Engine to determine whether an App administrator should take action and reconfigure the App for the new needs - fill out previously not existing configuration fields etc.
So for instance if, on the App update, the compatible field is higher than the last version(i.e. compatible = 1.1.0 and last version = 1.0.0) of the App installations will be set in Configuration required status - implicating the need for action and disallowing following actions with an App.
Restrictions:
has to exist and not be empty
the value cannot be greater than the version field
A list of JSON schemas to allow building simple or multi-step configuration forms.
Detailed reference can be found here.
A list of predefined features App utilizes:
Enables the ability to run synchronization via the App.
The synchronization is always run as delta via this feature - meaning only changes from the last synchronization will be sent to the App.
on first synchronization, all data state is being transferred to an App
on every following synchronization, the App receives only data that has changed from the previous execution
Enables the ability to run full synchronization via the App.
All configured within App data is synchronized via this feature disregarding delta - which means the entire data state is transferred to the App on every synchronization.
This feature is always a secondary option in the Run synchronization split button if enabled together with synchronization.
Claims that the App generates a file as the result of the synchronization - for the enabled feature every finished synchronization will receive a file download button within the right-hand menu as well as a Download last synchronization button in the main App menu
When this feature is enabled follow the File download endpoint reference.
This feature enables Copy feed URL button. This URL is publicly available, with no need for authorization.
When this feature is enabled follow the File download endpoint reference as for synchronization_file_download feature.
Events the App subscribes to. Available:
App installed by the user in the Ergonode interface.
App uninstalled by the user in the Ergonode interface.
Attribute created.
Currently available only in the synchronization context.
In the synchronization context, the event also contains detailed updated payloads.
Attribute updated.
Currently available only in the synchronization context.
Attribute deleted.
Currently available only in the synchronization context.
Category created.
Currently available only in the synchronization context.
In the synchronization context, the event also contains detailed updated payloads.
Category updated.
Currently available only in the synchronization context.
Category deleted.
Currently available only in the synchronization context.
Product created.
Currently available only in the synchronization context.
In the synchronization context, the event also contains detailed updated payloads. It also represents the access granted event i.e. when the product is added to a segment.
Product updated.
Currently available only in the synchronization context.
Product deleted.
Currently only available in the synchronization context.
In the synchronization context, it also represents the access revoked event i.e. when the product is removed from a segment.
The new synchronization process started.
The synchronization process ended.
Claims that the App requires the write access to fulfill its purpose.
A user is notified of the request on App installation.
When installed the App can use Ergonode API write capabilities to manipulate the data.
Restrictions:
currently the field cannot be changed after the initial App registration
Icon allows easy identification of the App within available and installed Apps.
Restrictions:
value has to be represented as a Base64 image i.e. data:image/jpeg;base64,*
value cannot be greater than 10 KB
Base URL under which the App is available. When not provided a host of the Manifest Url is taken as this parameter.
Restrictions:
a valid URL string
currently, the value of the field cannot be changed after the initial App registration
