The collaboration server supports a wide range of configuration properties (see Configuration Properties).
While most configuration properties can be set dynamically (and in different scopes, see Agent Desk Settings) on the running server using the configuration editor UI on the various scopes in the agent desk UI, some configuration properties, however, must already be known when the unblu server starts up.
This page describes the steps required to use configuration settings in your server installation.
Configuration settings keys are case insensitive. For better readability configuration setting keys are written in camel case (http://en.wikipedia.org/wiki/CamelCase) in the documentation and references.
Using Configuration Files
In order to use a configuration file, you need to specify where the
collaboration server should load the configuration file from using the
"com.unblu.propertyoverlay" JNDI or Java System Property.
The value of
"com.unblu.propertyoverlay" (JNDI or Java System
Property) must point to a valid Java properties file. It can be a local
file system path (absolute or relative) or any valid url supported by
file:///etc/unblu/unblu-configuration.properties). We recommend always
using forward slashes ("/") as the delimiter between path elements (also
on windows systems), as using other delimiters (such as back slashes)
only works if they are escaped properly.
How JNDI Properties are set depends on the server software you are using.
On Tomcat, for instance, JNDI properties can be set using
$CATALINA_BASE_DIR/conf/Catalina/localhost/ROOT.xml for the root
context in a default tomcat setup).
<Context> <Environment name="product" value="product.com.unblu.enterprise.universe.sso" type="java.lang.String" override="false"/> <Environment name="com.unblu.propertyoverlay" value="42x-sso.properties" type="java.lang.String" override="false"/> <Environment name="com.unblu.textoverlay" value="42x-sso-text.properties" type="java.lang.String" override="false"/> </Context>
For more on configuring JNDI for your servlet container see the following links:
How Java System Properties are specified depends on the server software
you are using. A general way to set the
"com.unblu.propertyoverlay"Java System Property is using the following
notation when the Java process is started:
java -Dcom.unblu.propertyoverlay=/etc/unblu/unblu-configuration.properties com.mycompany.mypackage.MyMainClass
Many Java Application Servers support OS environment variables for
setting additional Java System Properties. Tomcat, for instance,
"JAVA_OPTS" OS environment variable for declaring
additional System Properties.
# example that adds a com.unblu.propertyoverlay System Property using the JAVA_OPTS environment variable export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.propertyoverlay=/etc/unblu/unblu-configuration.properties"
Configuration File Format
Configuration files use the Java properties file format. The Java properties file format is a simple text-based format that consists of key/value pairs that are delimited by the equals sign ("="). Every key/value must start on a new line. You can use \ to escape newlines or other special characters. Blank lines are ignored. Lines that start with # are comments. See http://en.wikipedia.org/wiki/.properties for more details about the Java properties file format.
CAUTION: The Java properties file must always be encoded using the ISO-88591-1 character encoding. Make sure any special characters are escaped properly. (See http://en.wikipedia.org/wiki/.properties)
Using Multiple Configuration Files
Instead of using a single configuration file, it is also possible to split configuration across multiple files. Multiple configuration files are specified using a coma separated list of file path or urls in the com.unblu.propertyoverlay System or JNDI Property instead of a single value.
# example for using multiple configuration files (using the JAVA_OPTS OS environment variable, i.e. in Tomcat) export JAVA_OPTS="$JAVA_OPTS - Dcom.unblu.propertyoverlay=http://configurationserver/unblu/unblu- configuration.properties,/etc/unblu/unblu-configuration.properties"
This example specifies two configuration files:
When using multiple configuration files, the ones that are defined later will always take precedence over the ones defined earlier.
In the example above this means that properties defined in
/opt/unblu/unblu-configuration.properties will take precedence over
properties defined in
Using multiple configuration files can make sense, for instance, when there are multiple environments (i.e., prod, stage, development) that share most of the configuration but still need some individual configuration).
Using JNDI directly
Instead of using a configuration file (specified via JNDI or System Property) it is also possible to use configuration properties in JNDI directly.
Using System Properties Directly
Instead of using a configuration file (specified via JNDI or System Property) it is also possible to pass configuration properties directly via System Properties.
# example for how to use a Java System Property to set a configuration # setting using the -D notation in an OS level environment variable export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.logging.outputDirectory=/var/log/unblu"
Configuration Setting Types
Every configuration setting has a type associated (one of Boolean, String, Enum, Integer, Float, URL and Pattern).
For Boolean settings the value must be either "true" or "false".
For Enum settings the value must be one of the allowed values.
For Integer settings the value must be a valid integer.
For Float settings the value must be a valid float.
For URL settings the value must be a valid (fully qualified) URL.
For Pattern settings the value must be a valid Java regular expression.
# example of a list using comma separated values (CAUTION: no way to escape the , character here) com.unblu.text.supportedLanguages=en,fr,de # example of a list using the JSON format com.unblu.text.supportedLanguages=["en","fr","de"]
- Configuration Properties (Reference)