Contact usRequest a demo

Configuration property scope and the configuration cascade

Unblu has many 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 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 doesn’t 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 can 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 might 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 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 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 aren’t 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, won’t 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' 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 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 audio and video 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 can, in principle, make audio and video 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.

Each conversation template has a switch that specifies whether conversations should inherit changes to the configuration of the template they were created from.

  • If the switch is enabled (the default), changes to a template configuration or text properties are inherited by any conversation created based on the template.

  • If the switch is disabled, conversations are created with a copy of the template’s configuration at that time. The conversation’s configuration is then separate from that of the template it was based on. Changes to the template’s configuration don’t affect the conversation’s configuration.

When you create a conversation using the Unblu web API, you can specify whether the conversation should inherit changes to properties of the template it’s based on independently of the template’s setting in this regard. For example, you can specify that the conversation should inherit changes to the template’s properties, even though the conversation template it was created from states that conversations don’t inherit changes to its properties.

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’re viewing.

If you wanted to allow a visitor to make a video call, but the feature wasn’t 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’re 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 only affects visitors, set the configuration property in the AREA or APIKEY scope.

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

  3. If a setting affects 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 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’s assigned this value in the source code.

The configuration property 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 can 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 Java virtual machine (JVM)

  • System properties

  • Files containing configuration properties

GLOBAL

The GLOBAL scope affects all 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 applies to all the accounts.

Only superadminis can set configuration properties in the GLOBAL scope. Setting properties in the GLOBAL scope requires access to the Global Server Configuration interface.

The configuration cascade

As you 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. However, 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’s 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 short and straightforward: 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’s 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.

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

  1. 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 (UHNW) 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, that is, 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 the configuration properties set in the conversation template are copied to a conversation when it’s 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 is 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 has 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 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 audio and video call feature.

In the dependency cascade below, the client won’t be able to start a video call:

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

The client isn’t be able to start a video call.

See also

  • For more information on the configuration properties you can change, their default values, and the scopes you can set them in, refer to the configuration reference.