Server side configuration

Introduction

Starting from version 2023.1.0 the portal application can be partly configured by a dedicated user interface.

Portal project configuration

The .wediaportalrc file still holds the configuration chains in the same way they did before.

{
  "": {
    "appConfigs": {
      "portal": "starter-kit@project-dev",
      "portal@picker": "starter-kit@project-dev@$starter-kit-picker",
      // ...
      "_postProcessors": [
        ["", /* ... */]
      ]
    }
  }
}

Server configuration

The WXM_CONFIG_RESOLVER plugin is the server plugin hosting the different configurations and end-points required to manage configuration server-side. Find below a quick start-guide on how to configure it for a project.

default_holding_plugin: Refers to a plugin that will store all configurations. The default value is PACKAGED_CONFIGS. Its strongly recommended to duplicate / rename / deploy this plugin to another name so that next releases will not overwrite existing configurations.

config_settings: A JSON configuration of the different configuration chains that exist. Default delivered value is:

{
    "mappings": {
        "portal": "starter-kit@project-dev@project",
        "portal@picker": "starter-kit@project-dev@project@$starter-kit-picker@:userAgent",
        "portal@picker@office": "starter-kit@project-dev@project@$starter-kit-picker@office@:userAgent",
        "portal@picker@office@outlook": "starter-kit@project-dev@project@$starter-kit-picker@office@outlook@:userAgent",
        "wediaConfig": "__wedia_config",
        "portal@$mobile_device": "starter-kit@project-dev@project@$starter-kit-mobile",
        "portal@picker$mobile_device": "starter-kit@project-dev@project@$starter-kit-picker@$starter-kit-mobile",
        "portal@picker@office@$mobile_device": "starter-kit@project-dev@project@$starter-kit-picker@office@$starter-kit-mobile",
        "portal@picker@office@outlook@$mobile_device": "starter-kit@project-dev@project@$starter-kit-picker@office@outlook@$starter-kit-mobile"
    },
    "postProcessors": {
        "surferRole": "fr.wedia.confres.core.model.processor.SurferRolePostProcessor",
        "userAgent": {
            "processor": "fr.wedia.confres.core.model.processor.UserAgentPostProcessor",
            "config": [
                {
                    "pattern": ".*Mobi.*",
                    "name": "$starter-kit-mobile"
                }
            ]
        }
    },
    "baseLocations": {
        "starter-kit": "PACKAGED_BASES",
        "emptyObj": "PACKAGED_BASES",
        "__wedia_config": "PACKAGED_BASES"
    }
}

It is important to understand how the mappings section interfere on the portal configuration.

Each key within the mappings object refers to a configuration name. When a portal application loads, it is configured to load a specific configuration. Such configuration corresponds to a key inside the mappings object. For instance, the portal front end application will by default load portal configuration, whereas the office picker will load portal@picker@office.

Each value associated to a mappings key refers to the configuration chain to resolve in order to retrieve the actual configuration associated. For instance, the portal key refers to value starter-kit@project-dev@project whereas portal@picker@office key refers to value starter-kit@project-dev@project@$starter-kit-picker@office (we’ll come back to :userAgent later)

Note that portal application plugin and server config are not equal

This difference is important as it will make sure you will not overwrite a configuration done server side by delivering the project. The @project final part must not be defined in the portal sources.

Additionally, the name of the last part must be @project on the server side as only layers ending with @project are been written to.

To resolve a configuration, the system will obtain the value of the key, and the pass through an inheritance chain (same as portal build time resolution). For instance, the portal key gives starter-kit@project-dev@project will define to

start with the layer starter-kit
extend it with layer starter-kit@project-dev
extend it with layerstarter-kit@project-dev@project

As previously, if a $ is encountered at the start of a part, the layer name will be reseted. For instance, the portal@picker@office key gives starter-kit@project-dev@project@$starter-kit-picker@office

For this value, the configuration will be defined to:

start with the layer starter-kit
extend it with layer starter-kit@project-dev
extend it with layerstarter-kit@project-dev@project
extend it with starter-kit-picker
extend it with starter-kit-picker@office

Configuring portal sections not covered by the UI

You must use layers prior to the @project containing layers to define “developer defined” configuration. By default, we have named this layer starter-kit@project-dev but you are free to rename it if you want, as long as

You change the chaining value on both .wediaportalrc file and WXM_CONFIG_RESOLVER plugin configuration
You keep a trailing @project named layer for configuration done by the UI.

Configuration in the starter-kit@project-dev is done with the same rule than before. Except that

You cannot use js files to dynamically patch a config section
You can force the deletion of a section by adding a file with .delete extension. Example, you want to delete the configuration point $.dam.cursors.allAssets, in the starter-kit@project-dev directory, create file dam/cursors/all-assets.delete

How to provide additional configuration on sections defined in the UI

You can provide additional configuration to UI defined config by pre-defining a value. The UI will then extend an existing configuration.

For instance, imaging a filter has been created through the UI by defining in dam/named-filters/some-filter/ multiple JSON files (don't worry about what files are in ; you just need to remember that someFilter was defined.

If you want to add i18n that is unfortunately not configurable in 2023.1.0

Create on your local computer in starter-kit@project-dev:

dam/named-filters/some-filter/i18n.json and give it a json value "my.custom.i18n.key.to.use" (don’t forget the double quotes: you must write a valid JSON).

It might feel strange to override a value before definition, but this is perfectly valid as the UI will actually extend existing values of the config. If the UI decides to remove someFilter, by deleting it, it will also delete the inherited part of it.

How to migrate an existing starter-kit project to enable UI

When serving or building the portal application from the portal project, the process will try to discover whether the feature is active or not by checking if the WXM_CONFIG_RESOLVER plugin is active or not.

You can also force the serve / build process switch by defining the useServerConfigResolution value to true or false in the .wediaportalrc file.

Based on this configuration, the portal will be served / built accordingly.

Remember that you will still need to

configure the WXM_CONFIG_RESOLVER appropriately
have an @project ending layer

The build process will send “project-dev” layer to the server as part of the build process
(if you use the --deploy option)

Otherwise, the genconfig can be used to send your local layers to the server

How to retrieve configuration done by UI and deploy it to another environment

Backup the customer configuration

When creating the NAR, there is a checkbox "Application configurations" in the "Configuration files" section of the "Files backup" step (by NAR).

If you check this box, the folder containing the configuration done by UI is saved

Restore the customer configuration (from 2023.3.0)

When restoring a NAR, there is a "Application configurations" checkbox in the "Configuration files" section of the "Selected SAN files to be restored" step of the application restoration (by NAR).

If you check this box, the file is restored: the current folder containing the configuration done by UI is completely replaced by that of the NAR.

From 2023.1 to 2023.2, simply download the plugin configured in WXM_CONFIG_RESOLVER parameter default_holding_plugin