Repository

https://github.com/athento/athento-nx-extended-config

Summary

One of the most important enhancements that provides Athento NX is its capability to provide a configuration framework to all modules included within.

This configuration is based on a simple principle: any changes in parameters are applied IMMEDIATELY to Athento, with NO NEED TO REBOOT the application.

Extended Config is partially a module itself, giving the rest of the modules the basics so every module does not need to reimplement once and again the common interface, and partially is a "way of doing things" to include new configurations (in both the technical and semantic way).

As a module, it brings the "Ext.Config" screen, accesible by the administrators, assures that the main configuration structure is declared and created. Once Athento NX Extended Config is in place, new links and configuration structure appears.

On the "way of doing things" part, it guides the way of developing the configuration for every plugin with very simple policies: you just need to create a schema with a metadata for every parameter and the layout to be embedded within the configuration structure. Also, if there is any logic between parameters, developers can implement it in the plugin itself, as part of the customization needed.

Installation

Athento NX Extended Config is available by default in all Athento installations.

To install it as a standalone module: Download the current stable version from "Package" folder and install it via "Local Packages".

User Guide

Extended Config is itself more a configuration framework than an end user functionality, but brings the user a common place to manage all Athento NX parameters.

New "Ext.Config" button, available for administrators.
By clicking this link, the user gain access to the configuration document.
Configuration document has the aspect of a common File in Athento. You can see the summary, modify it, etc. Same as every other document.
Every plugin contributes to the configuration by a module (depending on the modules installed, blocks may be different).
To modify the parameters click in "Modify" tab.
After changing the parameter value, click on Save.
Changes are already accepted. Depending on the functionality changed, changes can be clearly visible or may need some actions to be reflected, but for the platform to take the change into account is immediate with no reboot needed.

Developer Guide

Description

Athento NX Extended Config is a public addon. You can clone the repository via https://github.com/athento/athento-nx-extended-config

It is mainly a "resources" plugin. This picture shows the structure of the resources, and they can change from version to version, but will help us to explain how this addon is built.

On a high level point of view, we have:

Automation chains
- "ExtendedConfig.goto" - A very simple chain, basically the operation "Seam.NavigateTo" to redirect the user to the /ExtendedConfig document.
User actions
- "ExtendedConfig" - One action: a link in Main Tabs that executes the operation "ExtendedConfig.goto"
Documents
- "ExtendedConfig" doctype. Extends File, and includes the "HiddenInNavigation" facet. Always, append="true" in every definition. append=true is very important, this is needed for every plugin to contribute with layouts to this doctype.
Lifecycle
- "ExtendedConfig" has the default lifecycle. Just for coherency, this help us dealing with delete and undelete transitions.
Structure Templates
- "ExtendedConfig" template is included. If does not exist, creates "ExtendedConfig" in the root.
message.properties
- Language

Of course, we also have the MANIFEST.MF to include all files, and deployment-fragment that gives instructions for deployment, including the i18n files.

How to implement a specific configuration on a custom addon to be reflected in Extended Config

Given this Configuration Framework, now every plugin must implement its contribution to the configuration layout.

We are going to see it through an example: Athento NX Extended WF (in its version 1.1).

In the next image we can see the structure of the Athento NX Extended WF:

Athento NX Extended WF is an addon included in Athento NX which contributes with a generic, complex and configurable workflow. The configuration in this plugin is extensive, given the main reason for this plugin is to have a customizable workflow.

In this structure, at a high level, we can see:

data
- In this folder we have the language files, vocabularies, schemas (xsd), and the generic workflow resource (extended-wf.zip)
META-INF
- the MANIFEST.MF, with the project definitiion and reources.
OSGI-INF
- Automation, Vocabularies and Workflows are folders where the functionality is implemented.
- ExtendedConfig is the folder where we are going to include all resources needed for the configuration.
web
- static resources.

In the end, the philosofy behind this structure is:

Keep inside "ExtendedConfig" folder all xml resources related with the configuration.
If vocabulary, schema and i18n file is needed (which, for example the schema, is needed), will be included within all other resources in data.
A static resource is needed, two html, to show the block label in the layout, so will be included in web.

In the end, these are the resources that are related to the configuration:

Important: Not all plugins need all these resources. This is a complex example that covers most of the customization.

Lets see file by file (remember that components MUST have a unique name, examples can be checked out in several screenshots):

messages.properties (EN, ES, FR, or default)
- As in any other addon, translation is needed to be included. Basically for the labels of the metadata in the configuration layout, the block label, are any other message shown.
ExtendedWF.xsd
- This is the Extended Config metadata schema.
- Why is it not named ExtendedConfig.xsd or something similar? In the end, all plugins will have their own xsd, and files and resources must have a different name through plugins. In this case, we chose the name "ExtendedWF.xsd".
extended-config-chains-contrib.xml
- This is the xml contribution with chains related specifically with config management. Typically, here we define here the chain that "reads" the configuration parameters, if needed.
- In this specific example, only one chain is defined here, and it loads to Workflow Variables all parameters included in configuration metadata. Then, the Workflow will use this chain when it needs to access or update configuration metadata.
extended-config-doctype-contrib.xml
- This will always be required. It is needed to contribute to the ExtendedConfig doctype with new schemas at least.
- Basically you need to extend the doctype with new schemas, and add new blocks of layouts. Important: always use append=true if you don't want to override anything.
extended-config-formlayout-extendedWF-contrib.xml
- Again, this is required as a layout must be presented to the user to be able to change the metadata. In this example, as you can see in previous image, layout is "layout@formlayout.extendedWF", and will be the same for all modes (this is not mandatory).
- In this contribution you link the metadata in the schema, with the vocabulary (if needed), with labels translated, with templates used... not different because of being an Extended Config layout, but is important to remember how critical (and extense) is this contribution.
- As any other layout, deines: layout template, rows, widgets.
extended-config-schemas-contrib.xml
- Also a needed contribution. Declaration of the schemas, based on the xsd already commented.
- It is a very simple contribution.
extended-config-vocabularies-contrib.xml
- If any configuration value is really based on a list of values (like a dropdown list, or a suggestion), vocabularies should be declared here.
- In this example, there is no need for vocabularies. Anyway, we keep the file so if later on, in another version, we need to include one, we already have the structure.
ExtendedWF_widget_layout_template.xhtml (+ present_in_edit_label_template.xhtml)
- These two modified resources grants us the hability to set the block label, and also show the label in edit mode (which is not present by default).
- In this example we use the label "label.widget.extendedWF"
  
  .