Understanding the Portal configuration JSON file structure

Overview

All portal applications (front-ends, asset picker, office specialized asset pickers) are configured through a JSON Object that is fetched at an early stage during the boot of the application.

All portal applications have their own specificities and therefor specific configuration, but also share a lot of common configuration.

In order to ease the configuration of your different portal applications, the portal project integrates in its build process a task dedicated to produce the different configurations of each portal applications.

Understanding the config files generation

The portal plugin npm script (defined in package.json) is the task that will build the final WEDIA plugin to be deployed on the server. During the execution of this script, different config files will be generated.

The plugin npm script relies on a single environment variable to start the generation of your different config files: VUE_APP_ALIAS_PATHThis variable must contain the relative path (from /portal/src/wedia-plugin-template/res) to a JSON file containing the description of the different config files that must be generated.

As a default, within /portal/.envfile, you will find:

VUE_APP_ALIAS_PATH=aliases-dev-club-wed.json

As a result, the file loaded to retrieve the different configuration aliases is: /portal/src/wedia-plugin-template/res/aliases-dev-club-wed.json and contains a JSON object :

{
  "portal": "dev-club-wed",
  // ...
}

Basic configuration

Each key of the object represents a named config to generate. The value associated to each key gives the path to the perticular configuration. With previous example, the portal config will be generated from the path: /portal/src/wedia-plugin-template/res/dev-club-wed

When the config is generated, all configuration path files are merged into a single JSON Object:

Each folder name will be translated to camelCase and define a new entry in the currentObject. The content will be the result of the folder analysis.

Each file (except _.json) name (without final extension) will be translated to camelCase and define a new entry in the currentObject. The content of the file will be used as a value for the entry.

Example:

Given the /portal/src/wedia-plugin-template/res/dev-club-wed structure contains following file structure :

/portal/src/wedia-plugin-template/res/dev-club-wed
├─ demo
|  ├─ my-file.json
|  ├─ -my-other-file.json
|  ├─ some-sub-directory.json
|  |  ├── my-sub-file-1.json
|  |  └── my-sub-file-2.json
|  └─ _.json
└─ sample.json

Will end up with a config object looking like:

Configuration with inheritance

It is possible to create a config be extending an existing configuration. To do so, you need to prefix the configuration you want to inherit from with @:

Example

Given environment variables contains VUE_APP_ALIAS_PATH=aliases-dev-club-wed.json

Given /portal/src/wedia-plugin-template/res/aliases-dev-club-wed.json contains :

Given /portal/src/wedia-plugin-template/res/ contain :

When picker config will be resolved, it will be based on dev-club-wed, meaning that files and folders contained in dev-club-wed@picker will be added (and eventually replace) the one from dev-club-wed.

Then config portal will contain an object with this shape :

And config picker will contain an object with this shape :

It is possible to chain multiple configurations to be more and more specific along the chain.

Include an “absolute” path

If after the @ a $ char is found, for example dev-club-wed@$_picker

The configuration dev-club-wed will be loaded, and after the config from directory _picker is applied

Its allow to apply the same “patch” folder to a set of configuration.

Combined to post processors, described below, it’s quite powerfull and allow reusability

More info in git, dev-club-wed-aliases.json file

Post processos

Sometimes, we want a distinct configuration for int, pp and production. A common use case could be distinct google analitycs tracking ID.

So, in top of all generated configurations, we need to have an int, pp and prod version.

post processors are dedicated to this.

aliases file can contains a _postProcessors entry

It should be an array of array of string

For example

For distinct env '', env_pp”, “env_prod”, we have an empty value to generate a version withtout suffix.

(for generated last 4 configs, without env_ someting)

Configuration with code

At some point, you might want to create an alternative config to remove entries, or to act on arrays. In such circumstances, inheritance does not offer you the ability to remove items and you need to write code to adapt a configuration.

This can be achieved by defining javascript files in place of json files.

Such javascript files must export one function that will be evaluated to return the content of the property:

Example:

Given environment variables contains VUE_APP_ALIAS_PATH=aliases-dev-club-wed.json

Given /portal/src/wedia-plugin-template/res/aliases-dev-club-wed.json contains :

Given /portal/src/wedia-plugin-template/res/ contain :

Given /portal/src/wedia-plugin-template/res/dev-club-wed@picker/my-other-file.js contains:

Then picker config will have the shape:

Product VS Project

R&D deliver a standard _portal configuration

It contains all base configuration . It’s not specific to club-wed and it’s apply to all portals.

Its a base configuration. All project should inherit from this config, and apply transformations like definiing new curors, nos filters, change behaviors config,..

Overload should be done using .js file and not json file to retrieve initial / base configuration and edit some part of it.

For example :

feature/_.json

signin/_.json

So if we add a new entry in the source json file, your generated config will contains it, and your project have applied only a modification on a targetted scope

R&D furnish 3 base configuration

_portal

It’s the base configuration

_picker

It’s for transforming a configurated portal to a content picker

Example of inheritence chain : _portal@club-wed@$_picker@$club-wed-picker

_officepicker

It’s for transforming a configurated content picker to an office picker

Example of inheritence chain : _portal@club-wed@$_picker@$club-wed-picker@$_officepicker

Fetching configuration from server

The configuration is loaded through the api service /api/packaged/vue-app-helper/merge-json provided by the PACKAGED_VueApp_Helper plugin.

This service expects 2 query parameters:

pluginThe name of the plugin from which we want to retrieve the configuration (defaults to current plugin)
pathThe path (starting from the target plugin res folder) to the configuration.

This API returns a JSON stream describing the configuration of the whole application.

Within PACKAGED_VueApp_Helper plugin, the parameter aliases allows you to define a mapping between the given path query parameter of the API call and the path that will be used as a base path from the server config:

Given that the aliases parameter is defined as:

When the merge-json end point is called with path=my_config
Then the returned configuration will be loaded from PACKAGED_VueApp_Helper/res/config1

When the merge-json end point is called with path=other_config
Then the returned configuration will be loaded from PACKAGED_VueApp_Helper/res/other_config

This allows you to deploy multiple configurations and to load the correct one based on a server configuration. Expecially, if you need to have different configurations based on the environment (dev, staging, production), you are able to deliver the different configurations on all environments and to configure on each environment the appropriate mapping.