Configuration Settings

In Activator, Configuration Settings are components used to store information or parameters that are rarely modified, or whose changes are very infrequent. These settings allow for efficient management of static data, ensuring system stability while reducing the need for constant updates or dynamic data loading.

For example, they can be used to hold the keys to an external API, the configuration of a module, or perhaps the list of locations for a given geographical area. The applications are many and varied. These settings enable developers to ensure optimized parameter management while maintaining stability in operational processes, without having to frequently update these configurations.

Setting Creation

In Activator Admin, the creation of a configuration parameter involves four components:

1. Configuation Categories (which contains the setting category).
2. Configuration Settings (which contains the setting definition itself).
3. System Setting Driver (which contains the definition of the driver that will capture the setting info).
4. Setting Validators (to add a specific validation for each setting update).

✋CAUTION

Make sure you are in the System Component main module

Configuration Categories

To create a Configuration Setting in Activator Admin, it is essential to start with its associated module, namely the 📄Configuration Categories(illustrated in point (1) of the picture below). Each configuration setting must be linked to a relevant category to allow better classification and more intuitive use within the system.

To initiate the creation of a configuration category, simply click on the +Add new button (illustrated at (2) on the image above). Upon clicking, you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields.

The Meta Data field gathers and provides additional information about the module. As far as the data in this field is concerned, we'll concentrate mainly on the ui property, which is described below. For more information on the other properties contained in this field, please refer to Meta Data for a complete list of additional information relating to this module.

{
    "resourceName": "",
    "titleResKey": "",
    "descResKey": "",
    "icon": "fas fa-cog"
}

As for the Definition field, let's take a closer look at its JSON content. You'll notice that this is where you'll be prompted to fill in various fields. These fields will be used to specify information relating to the identification of the configuration category.

{
    "title": "Category Title",
    "description": "Category Description"
}

Configuration Settings

The next step is to create the Configuration Setting (illustrated in point (1) of the picture below) component itself.

To initiate the creation of a configuration setting, simply click on the +Add new button (illustrated at (2) on the image above). Upon clicking, you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields.

The Meta Data field gathers and provides additional information about the module. As far as the data in this field is concerned, we'll concentrate mainly on the ui property, which is described below. For more information on the other properties contained in this field, please refer to Meta Data for a complete list of additional information relating to this module.

{
    "driver": "sys.systemsettingdrivers.sysJsonDriver",
    "resourceName": "",
    "titleResKey": "",
    "descResKey": "",
    "icon": "fas fa-cog",
}

As for the Definition field, let's take a closer look at its JSON content. You'll notice that this is where you'll be prompted to fill in various fields. These fields will be used to specify information relating to the identification of the configuration setting.

JSON Definition:

{
    "title": "Setting Title",
    "description": "Setting Description",
    "defaultValue": null,
    "category": "sys.settingcategories.sysDefault",
    "contentType": "text/string",
    "validator": ""
}

System Setting Driver

The System Setting Driver (illustrated in point (1) of the picture below) is an important module that manages how configuration settings are retrieved, displayed, manipulated and stored.

Activator provides two essential system drivers (illustrated in point (4) of the picture below) by default for managing configuration settings: sys.systemsettingdrivers.sysJsonDriver and sys.systemsettingdrivers.sysTextDriver. The sysJsonDriver is designed to handle settings stored in JSON format, which is particularly useful for configurations that require hierarchical data structures or nested objects. On the other hand, the sysTextDriver is optimized for managing settings in text format, making it ideal for simple configurations or string values. The use of these drivers allows for tailoring the management of settings to the specific needs of the application.

To initiate the creation of a system setting driver, simply click on the +Add new button (illustrated at (2) on the image above). Upon clicking, you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields.

The Meta Data field gathers and provides additional information about the module, such as configuration and parameters, as well as the accessibility and security measures associated with this module. Please refer to Meta Data for the complete list of additional information related to this module.

As for the Definition field, let's take a closer look at its JavaScript content. You'll notice that this is where you'll be prompted to fill in various fields. These fields will be used Display and manipulate data of the system setting driver.

Definition:

$activator.ui.jsmodules.define(function () {
    //renders the setting UI
    this.render = function (context) {
        return new Promise((resolve, reject) => {
            resolve();
        });
    };
    //Validate the setting
    //revolve() when valid
    //reject() when invalid
    this.validate = function (context) {
        return new Promise((resolve, reject) => {
            resolve(); //is valid
            //reject(); //is not valid
        });
    };
    //get the value
    this.getValue = function (context) {
        return new Promise((resolve, reject) => {
            //return the value of the setting
            resolve({
                value: "{}"
            });
        });
    };
});

Setting Validators

Setting Validator (illustrated in point (1) of the picture below) is a component that manage the mechanism that allows for a validation of configuration settings, this time at the system level.

To initiate the creation of a system setting driver, simply click on the +Add new button (illustrated at (2) on the image above). Upon clicking, you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

The Meta Data field gathers and provides additional information about the module, such as configuration and parameters, as well as the accessibility and security measures associated with this module. Please refer to Meta Data for the complete list of additional information related to this module.

As for the Definition field, let's take a closer look at its C# content. You'll notice that this is where you'll be prompted to fill in various fields. These fields will be used to specify information relating to the identification of the system setting driver.

As this component is of type storedFunction, the developer must be sure to return two possible values in the result.Payload after processing:

• True: if validation has been successful and the new setting value is correct. In this case, the setting content will be updated in the system.
• False: if the new setting value is not valid. In this case, an error will be returned and the setting content will not be updated.

Previsualization

✋CAUTION

Make sure you are in the ⚙️System Settings main module

To preview and modify a configuration setting, go to the menu container where the list of setting categories (illustrated in point (1) of the picture below) related to your tenant is displayed.

For this example we used a configuration setting that implements the driver sys.systemsettingdrivers.sysJsonDriver

In the image above, you're watching:

1. Configuration categories List
2. Configuration settings belonging to the same category.
3. JSON content of a configuration setting.

✋CAUTION

Specify that system-type settings are editable only in a tenant that has this component included in its license.

4. Button to save changes made to the content.

✋CAUTION

Specify that system-type settings are editable only in a tenant that has this component included in its license.

Settings APIs

In Activator, developers can get and update a configuration setting by calling the provided APIs. Here are the details on how to use these APIs:

GET A Setting Value

API

Shortcuts To Get A System Setting In C#

var settingValue = await this.Context.Settings.GetValue("activatord.configurationsettings.settingName");

Update Setting Value

In some cases, developers may need to update the value of a configuration setting from an external application. For example, if an external application needs to modify a setting related to user permissions or application behavior, it can use this API to send an update request.

{
     "value": "string"
}

Conclusion

In conclusion, the comprehensive documentation on configuration settings in Activator Admin highlights the importance and versatility of managing these settings effectively. From understanding the fundamental concepts and components, such as Configuration categories and System Setting Drivers, to utilizing Apis for updating and retrieving settings, this guide provides essential insights for developers. By leveraging these tools and best practices, developers can ensure that their configurations are well-organized, easily manageable, and adaptable to the needs of their applications, ultimately leading to a more robust and efficient system.