Contact usRequest a demo

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:

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 Configure conversation icon 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:

  1. If a setting will only affect visitors, set the configuration property in the AREA or APIKEY scope.

  2. If a setting will only affect agents, set the configuration property in the USER or TEAM scope.

  3. 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:

The configuration cascade
Figure 1. The configuration cascade

In the diagram above, the various paths the configuration cascade may follow are colored differently depending on the entity affected by a configuration property:

  1. 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.

  2. The cascade for configuration properties that affect visitors go through the scopes in the following order: GLOBAL → ACCOUNT → AREA → APIKEY.

  3. Like the visitor cascade, the cascade for configuration properties that affect agents goes through the GLOBAL and ACCOUNT scopes. It then carries on through the TEAM and USER 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:

Configuration cascade: enabling video call mode
Figure 2. Configuration cascade: enabling video call mode

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:

Configuration cascade: enabling calls in the conversation template
Figure 3. Configuration cascade: enabling calls in the conversation template

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:

The dependency cascade for a video call
Figure 4. The dependency cascade for a video call

  1. 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.

  2. 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.

  3. For the callEnabled property in the scope of the conversation template to have an effect, the configuration property com.unblu.messenger.callEnabled must be true in the account scope, either because it was set there or because it was inherited from the global scope.

  4. 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:

Dependency cascade with video calls blocked
Figure 5. Dependency cascade with video calls blocked

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.