Configuring User Names Displayed

This page describes how to display user names. User names, in this context, are the names displayed for authenticated users.

Display names here can be:

  • The name displayed for a mouse cursor in a running co-browsing session.
  • The name displayed in the chat.
  • The name displayed in agent workspace.

User Display Names

The solution is oriented at the MVC (model view controller) pattern and separates:

  • The user model (the data representing a user).
  • The evaluation of the display name depending on the purpose (controller providing the view).
  • The localization of the display name (if a configured name should be taken, e.g., "agent" for a support agent in English or "Berater" in German).

The User Model

The user model is created by a number of different product parts:

In the cloud, user information includes username, firstname, lastname and roles.

In on-premises setups with Single Sign-On (SSO) distribution, these sources are currently supported:

  • trusted headers: HTTP request headers received with each request (provided, e.g., by a proxy in front of the collaboration server) are taken as authentication information (username, displayname, roles can be provided).
  • JEE: The servlet container running unblu inside can provide Authentication information to unblu per request (provides username). Additional information can be provided again using HTTP request headers (displayname).

Display Name Evaluation

Since not all sources can provide the same model information it is important to define a consistent way of selecting model parts for the display name - depending on the display name purpose.

Example requirements:

  • The cloud can provide first and last name. Co-browsing users should be displayed with the last name of the agent as the mouse cursor label.
  • The mouse cursor label should always be displaying a localized text "Agent" (en), "Berater" (de) etc., but the name displayed in the agent workspace should be the real name of the authenticated support agent.
  • The mouse label of the co-browsing visitor should be the technical id submitted to the server but the agent mouse label should represent the real name of the support agent.

Display Name Usage

Display names are used for these purposes:

Evaluation Order Configuration

The following configuration settings exist. They specify the selection order of data to use for particular purposes. Evaluation is done in such a way that if data is available for a key listed further in front, it overrides data available further back in the configuration.

The first example shows how personal or privatename display should be configured. This can be used when you want the user to see their own name as confirmation of a correct login.

privatenamedefault.displayNameEvaluationOrder=displayname,firstlast,lastfirst, username,identifier 
# available are: 'firstlast', 'lastfirst', 'displayname', 'username', 'identifier'

This configuration would take a displayname if available (only available with SSO when using JEE and trusted header sources and not always provided). As a fallback it would use firstname and lastname if available, then the username and last the identifier.

Note: It is also possible to use the value 'lastfirst' instead of 'firstlast'. In this case it would use lastname and firstname, if available. (If you want to use lastname and firstname you would use either firstlast OR lastfirst.

The order of evaluation can be changed by changing the order of the keys in the configuration list. Also, it is possible to only provide a subset:

privatenamedefault.displayNameEvaluationOrder=firstlast,username Note that certain configurations are useless and misleading:

privatenamedefault.displayNameEvaluationOrder=identifier,firstlast,username 
# will always pick identifier since this is mandatory in the model. The other options listed are never taken and thus are misleading in this list

Also note that providing an empty display name evaluation order is an error:

privatenamedefault.displayNameEvaluationOrder= 
# this is logged as an error. The server starts but will always return 'empty' display names

Display name evaluation exists for privatename as well as participantname usage. The latter has two flavours: visitor (old name recorder) as well as co-visitor (old name player).

List of Display Name Configuration Properties

The following list represents all configuration options available regarding display name evaluation. The list always shows the default configuration for each property and as a comment at the end of the list of available options.

# settings affecting the private display name
privatenamedefault.displayNameEvaluationOrder=displayname,firstlast,lastfirst, username,identifier # available are: 'firstlast', 'lastfirst', 'displayname', 'username', 'identifier'

# settings affecting the co-visitor display name
participantnamedefault.player.displayNameEvaluationOrder=firstlast,lastfirst,displayname,nickname,staticname # available are: 'firstlast', 'lastfirst', 'displayname', 'nickname', 'username', 'staticname', 'identifier'
participantnamedefault.player.showFirstnameEnabled=true # whether or not display name should include firstname if evaluation order picked 'firstlast' (or 'lastfirst')
participantnamedefault.player.showLastnameEnabled=true # whether or not display name should include lastname if evaluation order picked 'firstlast' (or 'lastfirst')
participantnamedefault.player.participantNameDefaultPlayerKey=participantnamedefault.player # the name of the text property to use when 'staticname' is chosen

# settings affecting the visitor display name
participantnamedefault.recorder.displayNameEvaluationOrder=firstlast,lastfirst,displayname,nickname,staticname # available are: 'firstlast', 'lastfirst', 'displayname', 'nickname', 'username', 'staticname', 'identifier'
participantnamedefault.recorder.showFirstnameEnabled=true # whether or not display name should include firstname if evaluation order picked 'firstlast' (or 'lastfirst')
participantnamedefault.recorder.showLastnameEnabled=true # whether or not display name should include lastname if evaluation order picked 'firstlast' (or 'lastfirst')
participantnamedefault.recorder.participantNameDefaultPlayerKey=participantnamedefault.recorder # the name of the text property to use when 'staticname' is chosen

Additional information:

If firstname or lastname is available but excluded with showXXnameEnabled=false it will be ignored in the evaluation order and the next evaluation order element is used.

List of Display Name Localized Text Properties

The following list represents the localized text properties typically taken into account if staticname has been chosen in the evaluation order (only available for participantname) or no option was left, but a participant name has to be evaluated (final fallback).

participantnamedefault.player.<lang>=
participantnamedefault.recorder.<lang>=

Examples

In a Cloud Setup

Co-browsing users must see the last name of the agent as the mouse cursor label.

participantnamedefault.player.displayNameEvaluationOrder=firstlast
participantnamedefault.player.showFirstnameEnabled=false

In an On-Premises Setup using JEE

The mouse cursor label must always be displaying a localized text "Agent" (en), "Berater" (de) etc., but the name displayed in the agent workspace must be the real name of the authenticated support agent (falling back to the user id if no real name should be available for some reason).

# JEE providing username as additional header
com.unblu.authentication.idpropagation.jee.enabled=true
com.unblu.authentication.idpropagation.jee.headerDisplayNameTrusted=x-unblu-user-displayname

participantnamedefault.player.displayNameEvaluationOrder=nickname,staticname
privatenamedefault.displayNameEvaluationOrder=displayname,identifier

# localized text properties
participantnamedefault.player.de=Berater
participantnamedefault.player.en=Agent

In an On-Premises Setup using Trusted Headers

The mouse label of the co-browsing visitor to be the technical id submitted to the server in the REMOTE-USER HTTP header (falling back to a static default configuration, in case the id is missing).

com.unblu.authentication.idpropagation.trustedheader.enabled=true
com.unblu.authentication.idpropagation.trustedheader.headerUserId=REMOTE-USER
participantnamedefault.recorder.displayNameEvaluationOrder=identifier,staticname
  • deploycloud
  • deployonprem

results matching ""

    No results matching ""