Contact usRequest a demo

Migrating from Unblu 6 to Unblu 7

This document describes version 7 of Unblu. If you’re using Unblu Spark 8, go to the latest version of the documentation.

In addition to the new features introduced with Unblu 7, there are several changes that you need to be aware of when migrating from Unblu 6 to Unblu 7.

Java 11 required

Unblu 7 requires Java 11 to run. The Unblu server won’t run with Java 8, the version required for Unblu 6.

Configuration and text properties

As with every major version of Unblu, there are several changes to the configuration and text property schema.

Some keys were removed because they’re no longer used. The possible values for some keys have changed to reflect the changes made with Unblu 7. Some keys were renamed to be more consistent or easier to understand.

Refer to the migration tool in the global configuration page to migrate your existing configuration files.

Scope change for autoclose configuration properties

In Unblu 6, the configuration property com.unblu.conversation.ui.autoCloseOnConversationEnd specified whether the conversation UI should close automatically when a conversation ended. Unfortunately it wasn’t possible to specify how the UI should behave based on a participant’s role for each conversation.

In Unblu 7, the configuration property has been replaced by four new configuration properties:

These new properties can be specified in the CONVERSATION and CONVERSATION_TEMPLATE scopes, allowing for finer granularity when defining the UI’s behavior at the end of a conversation.

Concierge enabled by default

The concierge is now enabled by default, that is, com.unblu.conversation.concierge.conciergeEnabled is true. As a result, the following configuration properties now have an effect on the concierge’s default behavior:

This means that, by default, the concierge is now active during reboarding and offboarding.

If you want the concierge to behave as it did in Unblu 6, you will have to set the configuration properties above accordingly.

Automatic request dispatching enabled by default

Automatic request dispatching is now enabled by default. If you want to continue to use the queue and manual request dispatching, turn off automatic request dispatching by setting com.unblu.queue.ui.autodispatching.autoRequestDispatchingEnabled to false.

For more information, refer to The queue and manual and request dispatching.

HTTP Basic Authorization default encoding

The default charset for the Authorization HTTP header is now UTF-8 and no longer ISO-8859-1. You can change the charset with the configuration property com.unblu.rest.basicAuthEncoding. To avoid problems, make sure that any clients consuming the API use the same charset.

New names for user synchronization tool actions

The names of the actions used in the configuration property com.unblu.addons.synctool.runAtCronExpressions have changed:

Unblu 6 Unblu 7

syncuser

SYNC_USER

syncteam

SYNC_TEAM

syncall

SYNC_ALL

The new names aren’t case sensitive.

The old names still work, but we strongly urge you to update the configuration property to use the new names.

For more information, see the section on scheduling configuration in the article dedicated to the user synchronization tool.

New entry path concept

Unblu 7 introduces a new entry path concept to replace the call origin and system path concepts used in earlier versions of Unblu. This results in a number of important changes:

  • The UNTRUSTED call origin is superseded by the entry path PUBLIC. The default PUBLIC entry path is /unblu. This is the same as the default system path for the UNTRUSTED call origin.

  • The TRUSTED call origin is now the entry path INTERNAL. The default INTERNAL entry path is /app. Before, the default system path for the TRUSTED call origin was /co-unblu in on-premises deployments.

  • The SYSTEM entry path replaces the SYSTEM call origin. The default SYSTEM entry path is /system; the default system path for the SYSTEM call origin was /sys-unblu.

However, in an on-premises deployment, you can set the entry paths to any values you like (provided they’re different from one another). In particular, you can set them to be backwards-compatible with earlier versions of Unblu:

(Note the absence of an initial / in both cases.)

In Unblu 6, it was possible to assign the TRUSTED, UNTRUSTED, and SYSTEM call origins the same system path. That is no longer possible. In Unblu 7, the values for the entry paths must be different.

This change applies to the Unblu Cloud, too. You should update any links for TRUSTED call origins to the default INTERNAL entry path, /app.

A number of configuration properties have been renamed to reflect the changes outlined above:

Unblu 6 Unblu 7

com.unblu.identifier.restrictedPathPrefix

com.unblu.identifier.internalPathPrefix

com.unblu.authentication.untrusted.sources

com.unblu.authentication.public.sources

com.unblu.authentication.trusted.sources

com.unblu.authentication.internal.sources

com.unblu.systempath.*

com.unblu.systementrypath.*

com.unblu.authentication.propagated.trusted.*

com.unblu.authentication.propagated.internal*

com.unblu.authentication.propagated.untrusted.*

com.unblu.authentication.propagated.public.*

In the OpenAPI specification for the Unblu web API, all occurrences of the field x-required-call-origin have been renamed x-required-entry-path. The field values TRUSTED and UNTRUSTED have been replaced with INTERNAL and PUBLIC, respectively.

Changes to the site integration endpoints

Internal endpoints for the Unblu snippet, such as /static/unblu/js-api/v7/floating/floating-api.min.js, no longer work with Unblu version 7. You must adapt the endpoint to match the one in the JS API reference.

If you’re affected by this change and can’t adapt your site integration in time for the migration to version 7, you can use rewrites as a temporary solution:

  • In a cluster deployment, you can add a rewrite rule to a file referenced by nginx-config-hooks:

    Listing 1. Rewrite rule in a cloud deployment 
    location = /unblu/static/js-api/v7/floating/floating-api.min.js {

    # rewrite path
    rewrite                    ^/unblu/static/js-api/v7/floating/floating-api.min.js  /unblu/js-api/v7/floating/floating-api.min.js break; (1)
    rewrite_log                off;

    # send request to haproxy
    proxy_redirect             off;
    proxy_set_header           Host $host;
    proxy_set_header           X-Forwarded-Proto "https";
    proxy_pass_request_headers on;
    proxy_pass                 http://haproxy:8080;
}
    1 Verify the correct path in the JS API reference.

  • In an application server deployment, use the rewrite module of your reverse proxy or web application firewall to rewrite the endpoint to the one in the JS API reference.

Removal of Unblu web API v1

Version 1 of the Unblu web API (web API v1) isn’t supported in Unblu 7 and has been removed. If you are still using v1 of the web API and wish to migrate to Unblu 7, you will have to switch to v2 or, ideally, v3 of the web API.

Refer to the web API documentation related to Unblu 6 for information on changes between v1 and newer versions of the web API.

Help menu item in the Agent Desk settings menu

In Unblu 7, the Help menu item in the Agent Desk settings is now active by default. It’s set to open the URL Agent Desk guide.

To disable the menu item, set com.unblu.ui.usermenu.showHelp to false. To change the URL, edit the configuration property com.unblu.ui.usermenu.uriHelp.

Action bar theming

The configuration property com.unblu.conversation.ui.individualUIActionBarTheme has been replaced by four separate configuration properties:

  • *.actionBarBackgroundColor

  • *.actionBarDividerColor

  • *.actionBarElevation

  • *.actionBarForeground

Each of these configuration properties is available separately for the various Unblu UIs, so you can now specify the action bar theme differently for different Unblu UIs. The table below shows which configuration property path maps onto which Unblu UI.

Table 1. Mapping of configuration property paths to UIs
Configuration property starts with UI whose action bar is affected

com.unblu.recording.ui.*

The action bar as displayed in conversation recordings

com.unblu.agent.ui.actionbar.*

The action bar in the Agent Desk and Single Conversation Desk

com.unblu.si.embedded.ui.*

The action bar in the Embedded Visitor UI

com.unblu.siteintegration.ui.*

The action bar in the Floating Visitor UI

com.unblu.visitor.conversation.ui.*

The action bar in the Visitor Desk

com.unblu.agent.mobile.ui.*

The action bar in agent-side mobile apps

com.unblu.visitor.mobile.ui.*

The action bar in visitor-side mobile apps

You have to set these configuration properties to theme the action bar of each Unblu UI you wish to customize. There is no mechanism for migrating the Unblu 6 configuration property to Unblu 7 automatically.

Example

To recreate the setting com.unblu.conversation.ui.individualUiActionBarTheme=PRIMARY from your Unblu 6 installation in Unblu 7, set the following configuration properties:

Please refer to the properties' entries in the configuration property reference for further information.

File types for upload

The configuration properties com.unblu.filemanager.fileTypeWhitelist and com.unblu.filemanager.fileTypeBlacklist allow you to specify which file types users may or may not upload to a conversation.

In Unblu 6, the name of the file type for Android application packages contained a typo. It was referred to as EXEC_ANROID_APK. In Unblu 7, the file type is spelled correctly: EXEC_ANDROID_APK.

If you use this file type in either of the configuration properties mentioned above, you’ll have to update the file type to reflect the new, correct spelling.

  • If you set the configuration properties in a .properties file, adapt the .properties file.

  • If you set the configuration properties in the Account Configuration interface, you must restore the properties' default values and save your changes. You can then set the properties to the values you want to use.

    Unfortunately, the change in spelling makes it impossible to launch the Account Configuration interface from the Agent Desk. You therefore have to specify the URL of the account settings overview page yourself: https://<yourserver>/app/config-account#/overview.

Changes to conversation request handling

In Unblu 6, you could use the JS API to send requests for conversations of almost any type from the visitor side, regardless of whether an agent was available or not. The only exception to this rule was the engagement type OFFLINE_CHAT_REQUEST. If the configuration property com.unblu.cobrowsing.startWithOfflineChatOptionEnabled was false, it wasn’t possible to create an offline chat request.

Unblu 7 behaves differently:

If you use the Unblu Floating JS API to create conversation requests from the visitor side, you should therefore make the following changes:

  • Always check that an agent is available before you transmit your conversation request.

  • If no agent is available, only send requests with the conversation type OFFLINE_CHAT_REQUEST.

Changes to starting conversations

The process Unblu uses to determine whether a visitor can start a conversation has changed. The details of the new process are outlined in the section on starting a conversation in the Unblu documentation.

As part of these changes, the configuration property com.unblu.cobrowsing.startWithOfflineChatOptionEnabled is now deprecated. As a result, if you use version 3 of the Unblu mobile SDK with Unblu 7, this means visitors on mobile are unable to start conversations when no agent is available. The same issue arises if the configuration property com.unblu.agentavailability.availabilityOverride is set to NEVER_AVAILABLE.

To work around this issue, set the configuration property com.unblu.messenger.ignoreAgentAvailabilityForOnlineRequest to true. You can set it to false again once you’ve migrated to version 4 of the Unblu mobile SDK.