Configuration Script

Configuration script is used by the Controller for service provisioning, if it is declared in the package metadata file APP-META.xml by the "//service/provision/configuration-script" element defined by the Specification in section 5.3.2. Configuration Script.

By the moment of script invocation, the following operations are to be performed by the Controller:

Application files should be unpacked and deployed in hosting environment;
All service requirements should be satisfied and requested resources allocated;
Service settings are processed and transformed into respective environment variables. If URL mapping rules are declared for the service, respective environment variables for each mapping should be prepared as well.

Provisioning service operation with configuration script implies that the Controller performs the following steps:

Determine configuration script interpreter. To determine configuration script interpreter, the Controller reads from the package metadata the identifier of the script's language (the value of the "//provision/configuration-script/script-language" element). What interpreter must be used to run scripts written in a particular language is defined in the aspects, so the Controller must pass the identifier to the Aspects Parser. If the Aspects Parser supports the corresponding aspect, it returns the required interpreter information. Otherwise, the Controller must stop instantiating the application and roll back all the changes it has already done to the server.
Run the script with the required interpreter passing to it all the required environment variables. If the script interpreter is identified successfully, the Controller runs the configuration script with the install argument using the interpreter and passing to the script all the environment variables it prepared on the previous stages of instantiating. What variables must be passed to configuration script is defined by the Specification in section 5.3.2.2. Environment Variables.
Check whether the script was executed successfully. If the configuration script fails (returns non-zero exit code), it must be treated as a fatal error and the Controller must refuse to continue instantiating application. The Controller should also capture the script's stdout and stderr streams in order to log the error.
The configuration 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.

The Controller should go to instantiating child service (if any) only after all parent services are instantiated in the hosting environment.

In case, URL mapping rules are declared for the service and web access to the service was not configured before configuration script execution, the Controller should go to performing service mapping. For details, refer to the URL Mapping section further in this guide.