Configuration Advice

Note: This page is relevant to both on-premises and unblu Cloud implementations.

Note: If you are working in a team and need to direct someone to a configuration field, in the Agent Desk, see Sharing Configuration-Field Locations at the foot of this page.

Normally, this page would start with the 'easy stuff' (configuring properties in the Agent Desk) and become progressively more technical, but reading the 'advice' on this page is a good way for non-technical users (both Cloud and on-premises) to get an idea of what is going on inside the product and why 'designing' your own implementation of unblu is better performed iteratively by non-developers. That is, the seeming complexity of roles and hierarchies and look and feel and behavior is not only infinitely easier to enact within the Agent Desk but it is the only way that 'everyone' in your effort gets to be a part of the design process.

This is one of the pages where integrators, and everyone else involved in the project, can clearly see where to draw lines of delineation between the highly technical people, who 'make it all work' and the business people, who 'need it all to work'. But more than that, it is a place where the language of business and the language of software really can come together, not only to define and create the design, but to create the 'thing' itself.

System integrators 'configure' the 'guts' of the system; everything required to get it working. The hardware, the synchronization tool, the database, authentication integration, the rendering service and a host of other things have to be built for on-premises installations. Cloud customers already have 'everything' in place and ready to be 'configured', inside the Agent Desk.

If you perform a search here for 'configuration' or 'configuration properties' or 'settings' you will be presented, in the main, with what looks like scary stuff.

But, if you have to perform an on-premises integration, before you say, "We've got plenty of great system integrators, let's hand them the configuration.properties file and tell them what we want", you should understand that it is best if the file itself be populated only by the absolute bare minimum of entries. Everything within the configuration.properties file has a global effect. To get the most power from your system you would want to keep the configuration file as 'clean' as possible and do the bulk of your configuration in the Agent Desk interface (where you have greater control of the finer resolution). So, in an on-premises installation, for the configuration.properties file, think 'minimalist'. There are a number of reasons why this is so but while most are technical reasons, the most important reason is that after your system integrators have got your system up and running, not only can anyone 'design' the interface but it makes sense for non-technical people, with a vested interest, to take this task on.

Note: The database, the sync tool, authentication integration and rendering service connectivity information, for example, have to go into the configuration file. Customization and business process definitions can be set in the Agent Desk.

Whether you use our Cloud or your own on-premises implementation there are ways to configure the settings/properties that make it more of a voyage of discovery than a headache.

There are two ways to alter configuration properties to suit your needs.

• The first, and only applicable to on-premises installations, is by adding configuration items to the configuration.properties file. (The configuration.properties file is where your integrators will live.)

• The second way, and the way that almost all of you should end up doing it, is to fumble around the Agent Desk clicking on things and looking at the results. (Fumbling around = iterative design.)

Software design usually happens in advance of actually building something. Teams are brought together to analyze, to gather business and technical requirements. These requirements are usually rendered to a state where technical people can start to build the design.

The elephant in every room with this approach is the possible breakdown or fracturing of concepts at the interface between business requirements and the final, technical implementation.

Configuration properties are simply values. (Or, more explicitly, they are key-value pairs, meaning: which property to modify and the value of that property.) They can be binary (on/off), or ranges of values, or colors, or directives to enable this or that feature and to disable features you do not want.

Note: Each and every property is listed here but there is no place within this documentation where the possible consequences of the interactions between all possible settings is listed.

Here is a configuration.properties file:

#com.unblu.logging.outputDirectory=/home/david/Unblu/4.3/log

com.unblu.visual.resourcehistory.enabled=false

com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.MySQLPlatform
com.unblu.storage.database.driver=com.mysql.jdbc.Driver
com.unblu.storage.database.jdbcProperties=connectTimeout=60000,socketTimeout=60000,useUnicode=yes,characterEncoding=UTF-8,useLegacyDatetimeCode=no,serverTimezone=UTC,autoReconnect=true,useSSL=false
com.unblu.storage.database.url=jdbc:mysql://localhost:3306/unblu-4-3
com.unblu.storage.database.user=david
com.unblu.storage.database.password=Sw3Edf%6Y
com.unblu.storage.database.schema=unblu-4-3

com.unblu.storage.createSuperAdmin=true
com.unblu.storage.superAdminPassword=KkK8I76v
com.unblu.storage.users=unblu;John;Doe;secret;REGISTERED_USER,partner;R&D;Partner;partner;PARTNER,admin;R&D;Admin;admin;ADMIN,supervisor;R&D;Supervisor;supervisor;SUPERVISOR,webuser;R&D;Webuser;webuser;WEBUSER,anonymous;R&D;Anonymous;anonymous;ANONYMOUS_USER
com.unblu.storage.user.useEmailAsUsername=false


com.unblu.cobrowsing.startWithChatOptionEnabled=true

As an example, let's look at one thing that is 'wrong' with it. This file will run without any problems, it is technically sound. But the entry com.unblu.cobrowsing.startWithChatOptionEnabled at the bottom of the page is telling the collaboration server to start every session using the 'chat' option (meaning that any visitor who clicks on the 'flap' will be offered the option to chat with an Agent) and while it will function without any problem, the item (enable 'start with chat') would be better configured inside the Agent Desk, and not inside the configuration file.

If you do fill the configuration.properties file with entries that could be configured in the Agent Desk you will end up with a configuration.properties file that looks like a giant ball of wool. You must separate that which is truly required to simply run the system from that which tailors the system to your needs.

Let's say you no longer want visitors to be presented with the chat option. To change the item (in the configuration properties file) to 'false' would probably require an arduous process that ends up with an administrator stopping the server, changing the value, then starting the server, but the internal (to your own organization) machinations to make changes to servers at this level can be a long and frustrating road. This is another reason to apply good practice: You won't have to bug systems integrators for small things you could better do 'yourself'. Depending on your internal (quality) structures, adherence to the simple rule of thumb of configuring 'in the right place' can save untold resources and people power.

But, even if you are using on-premises within a highly-regulated environment, to make this change you only have to go to the Agent Desk, search for the value, then switch it off. That is to say: Changes at the server-configuration level are likely to require a validation process while changes to the interface of a running system do (or may) not.

Here is a picture of the Agent Desk interface:

To open the Agent Desk:

• Cloud: start.unblu.com

• On-premises: <yourserverhere>/co-unblu/desk

In the Agent Desk you get to this configuration item by selecting Settings from the main menu then selecting Global or Account or Team or Users then navigating to the Settings for that role (see Precedence Matters for more on 'Roles') then, in the Filter box type chat and scroll down until you find it.

This (Enable to start session with chat) property within the Agent Desk looks like this: com.unblu.cobrowsing.startWithChatOptionEnabled (in an on-premises configuration file).

This software is all about collaboration. But while it is easy to simply harp on the subject it is not enough to properly foster it within 'design teams' (you). One of the ways we try to enable 'you' to talk to each other is by offering an 'information-rich' interface. Unfortunately, this can be confusing, at first. After all, com.unblu.cobrowsing.startWithChatOptionEnabled does not look the same as (Enable to start session with chat).

But if you click on the Advanced button things will start to get clearer.

Note that now another panel has dropped into the space below the Filter field. There are a number of Options here but the one named Technical Labels is what interests us. If you select the Technical Labels check box you will see that the name (Enable to start session with chat) has changed to com.unblu.cobrowsing.startWithChatOptionEnabled.

Now we can look at the final piece of the configuration puzzle. If you hover your mouse over the information icon beside the item a popup displays.

This popup offers even more information regarding any particular configuration item.

So, before you ask your modelling team to tell your server people you might like to see what any given option looks like, and could we set up some meetings and workshops to tackle a few configuration properties, you can use the Settings in the Agent Desk to see for yourself.

Changes made, at any role level, within the Agent Desk interface, will be implemented instantly, with no requirement for server configuration nor restarts.

It is this ability, to build iteratively, that makes it possible for you to figure out for yourself what any given change might mean, and to correct those changes very quickly indeed.

For a conceptual look at the Agent Desk (Cloud and On-Premises) see the Introduction to the Agent Desk. (A 'must read' for both Cloud and On-Premises customers.)

On-Premises configurations will require you read Configuration. (Technical)

Another useful document to have at hand, for On-Premises installations, is Order of Deployment. (Short; leading to technical content.)

Sharing Configuration-Field Locations

If you ever need to communicate exactly where any given (configuration item) field is, in the Agent Desk, there may be a quick way to do it.

Some (not all) configuration fields in the Agent Desk have an icon beside the field name. If you see this icon it means that you can copy and paste the location of the field and send it to someone, in order that they can instantly find the field.

Example:

Select the icon. The Shareable link popup displays.

The popup contains a URL that points to this field (not the information contained within the field but the 'address' of the field itself).

Select the copy button to copy the location of the field. Anyone who pastes this link into their browser (given appropriate permissions) will be taken directly to that field.

• deploycloud
• deployonprem