Property files

Two different types of properties are contained within a PAA distribution. They can be classified as being either user editable that is requiring user input, for example a database URL, or as developer-provided settings required for a component to function. However, for user convenience, a separation between user properties from those settings that are supplied by the developer is advised.

In general custom Ant tasks that are provided by the developer handle such properties. The exception is when properties for connecting to an external database are included. The other exception is a selection property for cases when the user wants to install a template other than the default template in the PAA templates directory is required. However, there are cases where properties required by the Solution Installer might also need to be set. In this case, they need to be included with user editable properties.

Users might need to edit such content before they run the installation. Therefore, it makes sense to consolidate such properties in the one place instead of having the user edit multiple files in different locations. However, there is a trade-off with keeping all the properties required by a component together to allow for component reuse. Therefore, a number of approaches to storing properties in the PAA file are allowed.

User editable properties can be defined in the properties file specific to a component, component_name.properties, which can be found in the top-level directory of a component. The naming scheme of this file is important because the Solution Installer loads it automatically. When the PAA file is expanded, users are free to edit them as needed. They can then rerun any ConfigEngine function that is associated with the component to take account of these new values. The values in this file are the defaults for the properties and can be overwritten by parent properties files.

There are two ways in which the properties in the component level properties files can be overwritten by parent properties. The properties files that contain user editable properties for the components of the PAA assembly can be consolidated into one properties file. They are placed in the top-level directory of the PAA file. It is called assembly_name.properties. The user can edit this file to set any values that are required for the installation to ConfigEngine and HCL Digital Experience to run smoothly. When the user starts the installation process for the ConfigEngine, these properties are read first. The values in the default properties files are redundant because the Ant properties cannot be overwritten, unless they are out of scope.

Alternatively, the user editable properties can be passed in on the command line as parameters to the Solution Installer tasks. Individual property name=value pairs can be typed on the command line with a -D prefix to inform solution installer and the ConfigEngine that they are to be treated as Ant properties. Alternatively a properties file containing all of the user editable properties can be passed in on the command line with the Ant -propertyfile parameter.

The Solution Installer checks the command line to establish if properties were passed in when the task was started. If so, the properties are loaded by the installer and the values of the properties set are the ones that are used during the deployment to HCL. Similarly, if a properties file is not received on the command line, then it looks in the highest level directory of the PAA distribution for such files. When found, these values are loaded as the values for the properties. If there are extra properties in the assembly level file, then these properties are also read. If no properties file is found, values from the component level property files are used. Otherwise, it is assumed that no user editable properties are required and the installation continues.

Property files that contain developer-provided settings must be at the component level. To aid reuse of components across multiple PAA files, keep required settings local to a component.

When you decide on property names, take great care. A limitation of Ant means that when a property is created in a run of the scripts, it cannot be overwritten. Therefore, if you install multiple components that have a setting with the same name but different values, the first one to be created is used throughout the installation. It can cause unexpected results. Employ a pattern for naming the properties to ensure that property names across components do not clash. For example, a property name might have the name of the component to which it relates, prefixed to the name to ensure uniqueness.