This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version. The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu. |
Configuration property scope and the configuration cascade
Unblu has a large number of configuration properties that allow you to influence both the appearance of the Unblu user interfaces and the behavior of the system. This article describes how you can leverage Unblu’s scope concept and the configuration cascade to configure Unblu in such a way that it meets your organization’s needs.
We will introduce both the scope concept and the configuration cascade using an example, the configuration property com.unblu.conversation.actionbar.ui.videoCallActionDisplayMode. It specifies whether the conversation action bar includes a way for participants to launch a video call. You can choose to display a button in the action bar itself or a link in the overflow menu. Alternatively, you can hide the option completely.
Like all configuration properties, videoCallActionDisplayMode
has a default value, HIDDEN
. If necessary, you can overwrite the default value with one that suits your requirements.
Overwriting the default value, does not change the default value itself. The default value of each configuration property is fixed. |
Scope
Being able to set a configuration property is certainly useful, but what should you do if you want a configuration property to have different values for different parts of your website?
Perhaps relationship managers should be able to have video calls with their clients, but the e-banking help desk should only use embedded co-browsing. At this point, the concept of the scope of a configuration property comes into play.
The scope defines the extent to which the value of a configuration property affects Unblu.
If you look up the description of the configuration property videoCallActionDisplayMode
in the reference, you will see that it has the following scopes:
-
GLOBAL
-
ACCOUNT
-
AREA
-
APIKEY
-
TEAM
-
USER
This means that you can specify a different value for the configuration property in each of these scopes. If your setup has different named areas for launching conversations with relationship managers and your help desk, you could configure the video call button as follows:
-
In the named area used for the help desk, set com.unblu.conversation.actionbar.ui.videoCallActionDisplayMode to
HIDDEN
. -
In the named area used for conversations with relationship managers, set com.unblu.conversation.actionbar.ui.videoCallActionDisplayMode to
ALWAYS_SHOW
.
Unblu defines seven different scopes, which are described in the sections below.
ACCOUNT
The ACCOUNT
scope encompasses a single Unblu account. If you set a configuration property in this scope, all of the account’s entities of the type affected by the property will use the value you specify. For example, setting videoCallActionDisplayMode
to HIDDEN
in the ACCOUNT
scope will hide the button to launch video calls in all of the account’s UIs.
Superadministrators, technical administrators, and administrators can set configuration properties in the ACCOUNT
scope. Setting properties in the ACCOUNT
scope requires access to the Account Configuration interface.
AREA
The AREA
scope affects a single named area of an Unblu account. The other named areas of the account are not affected.
If you set videoCallActionDisplayMode
to ALWAYS_SHOW
on the named area "Private banking", the button would not appear in the UI of conversations launched in the named are "Help desk".
Superadministrators, technical administrators, and administrators can set configuration properties in the AREA
scope. Setting properties in the AREA
scope requires access to the Account Configuration interface.
APIKEY
The APIKEY
scope affects the parts of your website or mobile app that use a particular API key.
Setting videoCallActionDisplayMode
to ALWAYS_SHOW
on the API key used for the private banking section of your website, for example, will not affect the retail banking section.
Superadministrators, technical administrators, and administrators can set configuration properties in the APIKEY
scope. Setting properties in the APIKEY
scope requires access to the Account Configuration interface.
TEAM
The TEAM
scope affects a team and users who are members of that team. If a team has subteams, then those subteams are also affected by settings specified in the parent team’s scope, as are the subteams’s users.
If you set videoCallActionDisplayMode
to ALWAYS_SHOW
for the team "HNWI advisors", only members of that team will have the button to launch video calls in the conversation action bar. If the team had a subteam "UHNWI advisors", members of that team would have the button, too.
Superadministrators, technical administrators, and administrators can set configuration properties in the TEAM
scope. Setting properties in the TEAM
scope requires access to the Account Configuration interface.
USER
The USER
scope pertains to a single user. The user in question may have any user role except ANONYMOUS_USER
.
Setting a configuration property in the USER
scope will only affect a single user. If you set videoCallActionDisplayMode
to ALWAYS_SHOW
on the user "John Smith", only John Smith will have a button to launch a video call in the conversation action bar.
Superadministrators, technical administrators, and administrators can set configuration properties in the USER
scope. Setting properties in the USER
scope requires access to the Account Configuration interface.
CONVERSATION_TEMPLATE
Conversation templates are collections of configuration and text properties that are copied to new conversations when the latter are created. By setting a configuration property in a conversation template, all conversations created on the basis of that template will use the value that you set for the configuration property.
The configuration property com.unblu.conversation.feature.callEnabled is one of the configuration properties you must set to allow authorized conversation participants to start video and voice calls. In the configuration reference, you can see that it can be set in two scopes:
-
CONVERSATION_TEMPLATE
-
CONVERSATION
If you set the configuration property callEnabled
on a conversation template, authorized participants in a conversation created from this template will be able, in principle, to make video and voice calls.
Superadministrators, technical administrators, and administrators can set configuration properties in conversation templates. Setting properties in the CONVERSATION_TEMPLATE
scope requires access to the Account Configuration interface.
When you change a configuration property in a conversation template, the new value only affects conversations created after you made the change. Conversations that were created before the change retain the value for the configuration property that they originally inherited from the template. |
CONVERSATION
The CONVERSATION
scope is limited to a single conversation. Users with access to the settings of a conversation via the Configure conversation button in the Agent Desk conversation action bar can change the settings of the conversation they are viewing.
If you wanted to allow a visitor to make a video call, but the feature was not enabled in the conversation template that the conversation is based on, you could set callEnabled
in the settings of the conversation itself.
Only superadministrators and administrators have the Configure conversation button, so they are the only user roles able to set configuration properties in the CONVERSATION
scope.
Which scope to use?
Having so many possibilities to influence your system’s setup may be overwhelming. When planning how to configure your system, use the following rules of thumb as a starting point:
-
If a setting will only affect visitors, set the configuration property in the
AREA
orAPIKEY
scope. -
If a setting will only affect agents, set the configuration property in the
USER
orTEAM
scope. -
If a setting will affect both visitors and agents, set the configuration property in the
ACCOUNT
scope.
Pseudo-scopes: default values, the license, IMMUTABLE
, and GLOBAL
In addition to the scopes you have access to from the Account Configuration interfaces, the values of configuration properties may be defined in four more places:
-
The source code
-
Your Unblu license; this pseudo-scope only includes information on the features you have licensed
-
The
IMMUTABLE
pseudo-scope -
The
GLOBAL
scope, which is only accessible from the Server Configuration interface
You can’t make changes to the source code or the license, and you can only change configuration properties in the IMMUTABLE pseudo-scope or the GLOBAL scope in on-premises installations. If you use the Unblu Financial Cloud, you can only set configuration properties in the scopes described in the previous section. |
Default values
Each configuration property has a default value. It is assigned this value in the source code.
The configuration reference lists the default value of each configuration property.
The Unblu license
Your Unblu license key enables the various features you licensed. In this regard, it has a direct impact on the configuration of your Unblu installation. For example, if your license doesn’t allow you to use embedded co-browsing, no amount of configuration on your part will change that.
IMMUTABLE
The IMMUTABLE
pseudo-scope is the only one of the three pseudo-scopes you can affect independently. It refers to the various ways that you can affect Unblu when you start the Unblu server:
-
Arguments passed to the JVM
-
System properties
-
Files containing configuration properties
GLOBAL
The GLOBAL
scope affects all of the accounts of an Unblu installation. If you have separate Unblu accounts for different parts of your organization — for retail and private banking, say — and you set the value of a configuration property in the GLOBAL
scope, it will apply to all of the accounts.
Only superadministrators can set configuration properties in the GLOBAL
scope. Setting properties in the GLOBAL
scope requires access to the Server Configuration interface.
The configuration cascade
As we saw above, scopes allow for fine-grained configuration of your Unblu system. You determine which scope needs a particular configuration property to have a certain value, and then set the property in that scope.
This solution works well enough when you only need to make a few distinctions. But suppose you have a dozen different named areas, only two of which should allow video calls.
You could set the configuration property to ALWAYS_SHOW
in those two named areas, and set it to HIDDEN
in the other ten named areas. However, such an approach is both time-consuming and prone to error. It would be much better to have a way of specifying that the value of the videoCallActionDisplayMode
is HIDDEN
unless set otherwise.
That is what the configuration cascade allows you to do.
The scopes that Unblu defines have a hierarchical order:

In the diagram above, the various paths the configuration cascade may follow are colored differently depending on the entity affected by a configuration property:
-
The cascade for configuration properties that affect conversations is very short and straight-forward: the values of configuration properties assigned in a conversation template are copied to any conversation created on the basis of that template.
Once a conversation has been created, it is no longer related in any way to its template. Changes to its template have no effect on the conversation. If you need to change the settings of the conversation, you will have to do so by means of the Configure conversation button. -
The cascade for configuration properties that affect visitors go through the scopes in the following order:
GLOBAL
→ACCOUNT
→AREA
→APIKEY
. -
Like the visitor cascade, the cascade for configuration properties that affect agents goes through the
GLOBAL
andACCOUNT
scopes. It then carries on through theTEAM
andUSER
scopes.
Example
Consider the following scenario:
-
Your organization has three Unblu accounts, one for private banking, one for retail banking, and one for your insurance division.
-
You want to offer your ultra-high net worth private banking clients the possibility to make video calls to their advisors and the e-banking help desk. Your other private banking clients should only be able to make video calls to their relationship managers.
-
Private banking advisors should be able to start video calls with their clients, except for one advisor who only recently joined the team.
-
On the help desk team, only the supervisor should be able to start video calls with clients, should the need arise.
The diagram below shows how you might set the configuration property com.unblu.conversation.actionbar.ui.videoCallActionDisplayMode in the various scopes to meet the requirements outlined above:

-
Scopes in red boxes set com.unblu.conversation.actionbar.ui.videoCallActionDisplayMode to
false
, and red arrows show how this value is inherited by scopes further down the configuration cascade. -
Scopes in green boxes set com.unblu.conversation.actionbar.ui.videoCallActionDisplayMode to
true
. Green arrows show how this value is inherited by scopes further down the cascade. -
Scopes in gray boxes simply inherit the value the configuration property from the previous scope.
As you can see, ýou don’t have to set the configuration property in every scope. Scopes inherit the values for configuration properties from the previous scope in the scope hierarchy, unless you set it differently. This allows you to limit the extent to which a change in the value of a configuration property affects your Unblu setup.
In the example above, we must also enable users to make video calls in the conversation template, i.e. by adding the relevant participant roles to com.unblu.conversation.feature.callEnabled.
In this case, the configuration cascade is noticeably shorter:

As mentioned above, all of the configuration properties set in the conversation template are copied to a conversation when it is created.
The dependency cascade
As shown in the previous section, the configuration cascade can be split into three separate strands: one for the license, one for conversations, and one for accounts. These three strands are intertwined by dependencies between configuration properties defined in different scopes. This is referred to as the dependency cascade.
Suppose, in the example outlined above, an UHNW client wants to make a video call to their advisor. The dependency cascade looks like this:

-
Once the client has started a conversation, the button to launch a video call will be available only if the conversation template used for the conversation com.unblu.conversation.call.allowStartVideoCall includes the value
CONTEXT_PERSON
. -
This configuration property depends on com.unblu.conversation.feature.callEnabled being
true
in the same conversation template. If it isn’t,allowStartVideoCall
will have no effect. -
For the
callEnabled
property in the scope of the conversation template to have an effect, the configuration property com.unblu.messenger.callEnabled must betrue
in the account scope, either because it was set there or because it was inherited from the global scope. -
Finally, none of these configuration properties will have an effect if the feature hasn’t been licensed. This is the case if com.unblu.license.account.featureAudioAndVideoChat is defined, which is only the case if your license key includes the video and voice call feature.
In the dependency cascade below, the client will not be able to start a video call:

-
In the conversation template, both com.unblu.conversation.call.allowStartVideoCall and com.unblu.conversation.feature.callEnabled are set to display the video call button.
-
The video and voice call feature has been licensed.
-
The feature was enabled in the configuration properties file loaded at startup. That’s why com.unblu.messenger.callEnabled is
true
in the immutable scope. -
However, in this deployment, the feature has been disabled in the global scope.
-
The configuration property has not been changed in the account scope, so the account inherits the
false
value for com.unblu.messenger.callEnabled from the global scope.
The client will not be able to start a video call.
See also
-
The configuration reference lists all of the configuration properties you can change, their default values, and the scopes you can set them in.