Processing Settings

Configuring Installation Settings

On this stage of instantiating service, the Controller should prompt a user to configure parameters needed for service installation and configuration:

Full instance URL. The full address at which the installed application will be accessible. The option is prompt, in case, URL Mapping is declared as service provisioning method. The form in which the full instance URL is prompted is not defined in the Specification and completely depends on the Controller implementation. What is important here is that the URL data input by user is correctly validated and processed by the Controller so that this results in successful creation of the environment variables - BASE_URL_SCHEME, BASE_URL_HOST, BASE_URL_PORT, BASE_URL_PATH - defined by the specification. For details, refer to the 5.3.2.2.1. URL Mapping Variables section in the Specification.
Service settings. Additional parameters needed for successful service provisioning and configuration. The options are prompt, in case, service declares settings and their values can not be determined without user intervention. Selection of settings that should be prompted depends on the Controller implementation.
Service settings are described in the package metadata file APP-META.xml with "/service/settings/setting" elements.

When prompting the user to configure the service settings, the Controller must do the following:
1. Select settings to be prompted. The Controller may rely on setting attributes, such as:
- class - attribute informs about the setting or group of settings meaning. For details, refer to the 5.2.5.2 Settings Semantics section in the Specification;
- value-of-setting - attribute defines value of what setting should be used for the current setting. The referenced setting must be declared in the metadata and is searched in ascending order. For details, refer to the 5.2.5. Service Settings section in the Specification;
- type - attribute defines setting value type. The static-text type dictates that value of the setting should not be changed by user and displayed as a static text. The hidden type dictates that neither setting name nor value can appear anywhere on application configuration screen. For details, refer to the 5.2.5.1 Data Types section in the Specification;
1. Group the settings basing on the "/service/settings/group" elements;
2. Distinguish whether a setting is configurable only during installation or it can be reconfigured later (installation-only and regular settings), basing on the presence or lack of the installation-only="true" attribute;
3. Distinguish whether the setting requires its value uniqueness within some scope. Such settings are marked with uniq attribute that value defines scope of setting value uniqueness. The Controller must validate and ensure such settings values uniqueness.
4. If a verification script is declared in the "/service/provision/" section. The Controller may run it to get list of choices for enum setting type. The Controller should cache this list of choices and suggest it for respective setting editing. For details on verification script 5.3.3 Verification Script section of the Specification.
5. Represent a setting in full compliance with how it is described in the metadata, basing at least on the values of the "//setting/name" element and the "//setting[@type]" attribute. For details, refer to the 5.2.5.1. Data Types section of the Specification.

When processing the settings data input by the user, the Controller should do the following:

validate the submitted settings values according to the settings data types (the "//setting[@type]" attribute), and their optional restrictions (if any provided in the metadata, for example uniqueness).
If a verification script is declared, the Controller may run it itself to validate settings values or provide a user with dialog window where user can click special control for verification, for example, Verify button. A verification script definition may include structured-output element. In this case a script returns report on erroneous values in the form defined by the Specification. The Controller should catch output stream independently of error stream and process it. For details on script structured output, refer to the 5.3.2.3 Configuration script output section of the Specification;
store the entered values of the settings in order to be able to present them during the instance reconfiguration;
prepare environment variables SETTINGS_<id>, where <id> stands for a value of "//setting[@id]" attribute, set each variable to the corresponding input value, and pass to the application configuration script. If a setting has the track-old-value attribute Controller must pass to configuration script old value together with new one. Child services may reference to values of parent service settings using value-of-setting attribute. (For details, refer to the Specification's section 5.2.5. Service Settings.)

Processing Global Settings

The Controller must somehow store global settings of each application package available at its repository. (For details, refer to the Configuring Application's Global Settings section.)

When instantiating a package, the Controller must retrieve the package global configuration it stored, prepare from each global setting the SETTINGS_<id> environment variable, in just the same way it does for service settings (see above), and pass the variables to the configuration script. (For details, refer to the Specification's section 5.1.15. Global Settings.)