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)

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

1. start with the layer starter-kit

2. extend it with layer starter-kit@project-dev

3. 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:

1. start with the layer starter-kit

2. extend it with layer starter-kit@project-dev

3. extend it with layerstarter-kit@project-dev@project

4. extend it with starter-kit-picker

5. 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

1. You change the chaining value on both .wediaportalrc file and WXM_CONFIG_RESOLVER plugin configuration

2. 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

1. You cannot use js files to dynamically patch a config section

2. 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

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