of 3


Unblu 7 (latest)

The collaboration server supports a wide range of configuration properties. See the configuration properties reference.

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 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 in the documentation and references.

Using configuration files

The most common way to set (immutable) configuration settings is to use a configuration file. Configuration files use the Java properties file format.

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 Java (i.e. http://<host>/<pathtoconfigurationfile>; or 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 Environment Entries in the Context configuration file ($CATALINA_BASE_DIR/conf/Catalina/localhost/ROOT.xml for the root context in a default tomcat setup).


	<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"/>

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, supports the "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 pair 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.

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 comma-separated list of file paths 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: http://configurationserver/unblu/unblu-configuration.properties and /etc/unblu/unblu-configuration.properties.

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 http://configurationserver/unblu/unblu-configuration.properties.

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.

Some configuration properties expect list values. These can be declared in two ways: as comma-separated lists or using the JSON list notation.

# example of a list using comma separated values (CAUTION: no way to escape the , character here)

# example of a list using the JSON format