Skip to content

Advanced

This page contains advanced WhosOn options and configurations, these are provided for information purposes and may not be covered by regular support contracts.
Some of the guides in this page may break your WhosOn instance if not followed correctly or may cause unexpected behaviour. Please bear this mind as you proceed.

HTTP Interface

The 2019 version of the WhosOn Server has its own HTTP interface on port 8899. It will only respond to requests from hosts in the whitelist. Each request must also pass the Authentication String in the URL 'a={authstring}', e.g. http://localhost:8899/loadallsites.htm?a=AUTH

  • index.htm (default) - the Server status page can be viewed via http://localhost:8899?a={authstring}. The status page shows server info, monitored sites and blacklisted clients.
  • status.xml - returns the current server status as XML.
  • status.json - returns the current server status as JSON.
  • getgeoip.txt, getgeoip.xml, getgeoip.htm, getgeoip.json - returns GeoIP data for a given IP. Pass the ip address in the query string (eg: http://localhost:8899/getgeoip.xml?a=AUTH&ip=8.8.8.8)
  • getlog.txt - returns the server log file for the current server session.
  • chat.json - returns the JSON for a specific chat. Pass the Sitekey and ChatUID in the querystring (eg: http://localhost:8899/chat.json?a=AUTH&sitekey=1&chatuid=abcdefgh). The JSON returned is the same format that is used for the Cosmos Archiving.
  • chat.htm - renders a chat using the chat template assigned to the site. Pass the Sitekey and ChatUID in the querystring.
  • chat.xml, chat.txt - returns a chat as XML or text.
  • site.xml, site.json - returns the XML or JSON site settings for the specified site. Pass the SiteKey in the querystring (eg: http://localhost:8899/site.json?a=AUTH&sitekey=1)
  • loadsite.htm - forces a reload of the specified site. Pass the SiteKey in the querystring.
  • loadallsites.htm - forces a reload of all sites.
  • loaduser.htm - forces a reload of a specified user. Pass the username in the querystring (&username={username}).
  • loadallusers.htm - forces a reload of all users.
  • loadusergroups.htm - forces a reload of all user groups.
  • loadworkperiods.htm - forces a reload of all work periods.
  • loadskills.htm - forces a reload of all skills.
  • loadsettings.htm - forces a reload of server settings.
  • deletesite.htm - deletes a site. Pass the SiteKey in the querystring.
  • deleteuser.htm - deletes a user.
  • deleteusergroup.htm - deletes a user group. Pass the ID of the usergroup in the querystring (?id={id}).
  • deleteworkperiod.htm - deletes a work period. Pass the ID of the work period in the querystring.
  • user.json - returns JSON for a specified user. Pass the username in the querystring (&username={username}).
  • users.json - returns a JSON array of users. Querystring params (all optional): &contains={text}&domain={domain}&status=[all,connected,0,1,2,3]&skills={skill,[skill]}.
  • userphoto.json - returns a users photo as a JSON document. The photo is in base64 format.
  • cannedresponses.json - returns a JSON document of all canned responses for a given user (&username={username}).
  • pausesite.htm - pauses a site. Pass the SiteKey in the querystring.
  • resumesite.htm - resumes a site. Pass the SiteKey in the querystring.
  • chattingvisitors.json - returns a JSON list of all current chats.

Azure SSO

Azure SSO is only available for dedicated server or On Premise (Installable) customers.
If you want to use this with your dedicated server, please contact your account manager.
SSO works in the Settings Portal, Data Portal, Web Client and Desktop Client. WhosOn Charts is not supported.

We are using OpenID Connect (OIDC) to support SSO. OIDC is an authentication layer that sits on top of OAUTH and is supported by many providers.

OIDC is currently only supported for Azure AD. Other providers may work, but they are not tested.

To use Azure SSO you must create an Azure AD Application, the steps are provided below.

WhosOn must be running over HTTPS for SSO to work.

Generating an authentication section in Azure

  1. Go to Azure Active Directory.
  2. Go to "App Registrations" on the left.
  3. Click "New Registration".
  4. Enter the name for the application. This will show up to users when they login if it is not pre-added to their user profile.
  5. Choose what type of accounts you want to support. Most enterprises will select "accounts in this organizational directory only" however customers could select multi-tenant if they wanted to allow multiple servers or external accounts.
  6. Click "Register".
  7. Click "Certificates & secrets" on the left.
  8. Click "New client secret".
  9. Enter the description for example "WhosOn Server Secret".
  10. Set the expiry date that is appropriate for you - note that if this secret expires, then authentication in WhosOn will stop working and a new secret will need to be generated.
  11. Click "Add".
  12. Copy the "Value" from the secret you have just created and replace this in the Template OIDC JSON below as {clientsecret}.
  13. Click "Authentication".
  14. Click "Add platform".
  15. Select "Web".
  16. Enter the first Redirect URI of "https://{server}/data/?openid=Parkersoft.WhosOn.OpenId.MicrosoftOidcProvider" this must be HTTPS.
  17. Check both boxes to allow "Access tokens" and "ID tokens".
  18. Click Configure.
  19. Click "Add URI" below the web section and add the following URIs:
  20. Click Save.
  21. Click "Overview" on the left.
  22. Copy the "Directory (tenant) ID" from the Essentials area and replace this in the Template OIDC JSON below as {tenantid}.
  23. Copy the "Application (client) ID from the Essentials area and replace this in the Template OIDC JSON below as {clientid}.
  24. Replace {customer-login-domain} with the main login domain for the Azure AD.

You may notice we are adding the nativeclient URI to the web section here - this is because although the desktop client is a desktop application, it is not performing a desktop authentication - the server is performing the authentication, but doing it out of band by messaging sent back from the desktop client. The desktop client doesn't have access to the OIDC secrets.

Template OIDC JSON

{ "IdDomain": "{customer-login-domain}", "IsEnabled": "true", "Name": "Azure AD", "Properties": { "TENANT": "{tenantid}", "CLIENTID": "{clientid}", "CLIENTSECRET": "{clientsecret}" } }

Adding SSO to the server

Use the Template OIDC JSON. Note that this JSON should be a single line for the registry to display it properly.

  1. Access your WhosOn server.
  2. Open regedit.
  3. Go to HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Parkersoft\WhosOn\7\Settings
  4. Add a new string.
  5. Name it: OpenIdConnectSettings
  6. Paste the OIDC JSON into the string.
  7. Restart WhosOn Server.
  8. Restart IIS.

Using SSO

  1. SSO will now be enabled for any email addresses that match the IdDomain.
  2. Create a new user, and use the email address for the username. For existing users, the username OR email address should match with the username in the SSO system.
  3. The password input field should disappear in the settings portal when adding / editing one of these users.
  4. Save the user.
  5. You should now be able to login correctly in the client, settings portal, data and web.
  6. The login process always asks you your username the first time, and if you use a username that is in an OIDC directory, then you won't be asked for a password after clicking next.
  7. If you check the "remember me" box then you won't be asked the username again unless you explicitly log out of the application.

Active Directory / LDAP Integration

This integration allows users to login with their LDAP or AD password to the WhosOn components.

This is not an SSO based integration, WhosOn users will need to enter their username and password when they login.

Setting Up

  1. Ensure that the windows server that WhosOn server is installed on is joined to the domain
  2. Open up the service manager
  3. Go to server settings
  4. Go to advanced
    srver-advanced.png
  5. Check the box to "Enable LDAP for User Logins"
  6. Enter your LDAP Domain name (for example test.com)
  7. Save the configuration

Creating Users

  1. Open the settings portal
  2. Create a new user as normal.
  3. The username should be the same as the user's LDAP/AD username without any email address components
  4. The password input box should be disabled.

Using the integration

  1. Log in to WhosOn as normal, but input your LDAP or AD username or password.

Column level encryption

This guide describes how to configure column level encryption against your WhosOn database and have WhosOn function against this configuration.

Some minor aspects of WhosOn will not function with column level encryption, such as: chat searching on visitor name and chat content will not work, the WhosOn survey answers will not display against the built-in reports.

SQL Server configuration

Below are the recommended steps to configuring column level encryption on your database, these settings are what WhosOn has been tested against but you are welcome to try encrypted more or fewer columns than recommended, but note that any divergent configuration has not been tested.

Our technical support services are unable to provide support for this section as it relates to SQL Server configuration.

  1. Install SSMS (SQL Server Management Studio) onto the WhosOn server.
  2. Launch SQL Management Studio with "Run as administrator".
  3. Log in to the correct database server with server admin details.
  4. Right-click on the appropriate database.
  5. After the right click go to Tasks -> Encrypt Columns.
    1. Column selection, set these options:
      • Userchatvars -> vardata. Encryption type = deterministic
      • VisitFormVars -> vardata. Encryption type = deterministic
      • UserChats -> MessageText. Encryption type = Randomized
      • UserChats -> VisitorName. Encryption type = deterministic
      • UserChats -> MessageEmail. Encryption type = deterministic
      • UserTranscript -> LineText. Encryption type = Randomized
    2. Next. Master Key Configuration
      • Auto Generate
      • Windows Certificate Store
      • Select a Master Key Source = Local Machine
    3. Next. Run Settings – Proceed to finish now
    4. Summary -> Finish

  6. Open a New Query window and run the following SQL statements (replace with the SQL user that your WhosOn server is using to connect to the database):

    SET ANSI_NULLS ON
  GO
  SET QUOTED_IDENTIFIER ON
  GO
  ALTER FUNCTION [dbo].[GetChatVars]
    (@SiteKey INT, @ChatUID CHAR (10))
    RETURNS NVARCHAR (MAX)
  AS
  BEGIN
    RETURN '';
  END

  ALTER FUNCTION [dbo].[GetChatTags]
    (@SiteKey INT, @ChatUID CHAR (10))
    RETURNS NVARCHAR (MAX)
  AS
  BEGIN
    RETURN '';
  END
  GO

  EXEC sp_refresh_parameter_encryption GetChatTags
  EXEC sp_refresh_parameter_encryption GetChatVars

  GRANT VIEW ANY COLUMN MASTER KEY DEFINITION TO <username>
  GRANT VIEW ANY COLUMN ENCRYPTION KEY DEFINITION TO <username>

    Copy

WhosOn server configuration

  1. Open up MMC on your local machine.
  2. Add in the Certificates Snap-In as Computer Account.
  3. Expand out Certificates -> Personal -> Certificates.
  4. Find and right-click on the "Always Encrypted Auto Certificate" and go to All Tasks -> Manage Private Keys...
    1. Click Add..., to add in a new user.
    2. Change the Locations... to the location machine (not the domain).
    3. Enter: IIS APPPOOL\WhosOnData as the object name and click Check Names. This should underline the user.
    4. Click OK and ensure that the new user has Full Control rights then click OK again.
  5. Access the WhosOn registry location:
    HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ParkerSoft\WhosOn\7\Settings and edit the DBConnection and DBConnection.NET keys, replace the encrypted password with the plain text version.
  6. Access the WhosOn registry location:
    HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ParkerSoft\WhosOn\7\Settings and edit the DBConnection and DBConnection.NET keys and add the following onto the end of the key (a single semi-colon should separate this from the rest of the key): Column Encryption Setting=enabled
    e.g. Provider=SQLNCLI11;Initial Catalog=dbname;Data Source=server;User ID=uid;Password=pwd;Column Encryption Setting=enabled
  7. Restart the server.
  8. Perform a Sanity Test and check the WO server log for any errors: migration

Chat Event Codes

If you want to review the chat data within the WhosOn database directly you will notice that the Events are coded into short descriptors, the below list is the glossary for those descriptors.

Code Text Description
AC Operator %username% Sent auto pickup request Operator was sent an auto pickup request
ACB Operator %username% Auto Accept No Support Operator was an auto pickup, though their Client does not support the request (out of sync Client and Server pairing)
ACQ Operator %username% acquired chat session. Operator acquired a chat session from another user.
ACR Operator %username% Sent Auto Pickup Request Retry Operator was sent an auto pickup request via a retry
BOT Bot %bot name% picked up chat session. A bot accepted a chat session
BX Operator Blocked Visitor Operator blocked the visitor
CBK %call event data% Click to call (twilio) used to dial
CBS Operator requested start of cobrowse session Upscope session start
CNR Chat accepted with no routing rule Chat went through but didn't match routing rule
CQ Chat Queued as Operators are currently talking to other users. Queue Length %position%. expected time %expected% Chat has been queued
CQM Chat not queued because the queue is full Chat missed and not queued as the queue is full
CQT Chat not queued because the queue expected time is exceeded Chat missed and not queued as the Expected queue time exceeds the configured maximum
CS Concierge step has taken place. Concierge has performed an action on the session - either a step + form, a start chat, a redirect or a cancel
CVF Cobrowse session was ended Upscope session end
FLx First line received from operator. Operator sent its first line of the session. X is the operator index in the chat transcript table
MR %channel% Matched skill rule: %rule name% Each time a chat matches a routing rule
OC Operator %username% Forced Closed Session The operator clicked Exit & Close
OF Chat not taken as no suitable operators are online to take the chat Chat missed as no operators were Online who had the skills to pickup the chat
OL Operator %username% Left The Session The operator clicked "Exit Chat" or closed the chat window/client
OO Chat not taken as outside site-defined opening hours Chat missed as outside of Site Proeprties -> Visitor Chat -> Opening Hours
OP Operator %username% Picked up Session Operator picked up the chat session
OPF Operator %username% Failed to Picked up session as already taken Operator attempted to pickup a chat that had already been taken by another, usually occurs on slower connections where the client screen isn't updated quick enough to inform the offending operator that the chat is no longer waiting.
PS Post-chat survey submitted (%visitorname%) Visitor has submitted the post-chat survey
QAC Operator %username% Sent Auto Pickup Request from Queue after %waitedForSecs% seconds Operator sent auto pickup request on a queued chat
QALL Chat Sent To Online Users From Queue Queue has been configured to send to all online operators and this action has fired.
QERR Removed from queue due to queue error
QERR Operator %username% Was Going To BE Send Auto Pickup Request from Queue after %waitedForSecs% seconds, but cannot access site
QERR Chat moved from queue to active due to error in qf
QERR Chat moved from active to queue because of an error
QL Server Side Queue Loss of Session
QM %message% Any message from the queue - e.g. queue position and time
QMAN Chat Removed From Queue Manually By %username% Chat has manually been picked up from the queue by an operator
QON Chat Sent To Online User From Queue
QR Operator %client name% removed session from queue. Position %position% queued for %seconds waited% seconds. An operator took a chat from the queue manually
QTO Server Side Time-Out of Queued Chat
RMS Automatic Rule Message used for "visitor's browser disconnected from the chat session" messages
SC Webhook forced closed session A webhook service response triggered a close
SC - not currently used Operator started side chat Side chat started
SCO Scheduled chat reopened by visitor
SCO Scheduled chat reopened by operator
SCR Server Side Script Closed Session A script configured against the site's Site Proeprties closed the session
SK Chat shown message by skill rule (status: %status%) Chat routing rule has the "Message" configuration and this condition was met and the message sent, followed by the status of that queue
SK Chat redirected to %skill% by skill rule (Status: %status%) Chat routing rule has redirected the chat to another skill rule, followed by the status code of that queue
SK Chat cancelled by skill rule (Status: %status%) Chat routing rule has cancelled the chat, followed by the status code of that queue
SK Chat shown message by outside hours skill rule Chat routing has a message configured against the Outside Hours tab, this was displayed to the visitor, chat cancelled
SK Chat redirected to %skill% by outside hours skill rule Outside hours chat routing action redirected the chat to another skill
SK Chat cancelled by outside hours skill rule Outside hours chat routing action cancelled the chat
SK Chat shown message by always skill rule "always perfrom this action" in chat routing displayed a message to the visitor, chat cancelled
SK Chat redirected to %skill% by always skill rule "always perform this action" in chat routing redirected the chat to another skill rule
SK Chat cancelled by always skill rule "always perform this action" in chat routing cancelled that chat
SK Chat expired in queue because it exceeded the maximum actual time chat expired from a queue due to the queue time exceeding the maximum configured against the site
SK Chat expired in queue because it exceeded the maximum expected time chat expired from a queue due to the queue time exceeeding the expected maximum time that has been configured against the site
SK Chat in queue shown message by offline skill rule Chat routing has been configured to show a message when offline, this rule fired, cancelling the chat
SK Chat in queue redirected to %skill% by offline skill rule offline chat routing action redirected the chat to another skill
SK Chat in queue cancelled by outside hours skill rule offline chat routing action cancelled the chat
ST Server Side Time-Out of Session No response from either visitor or agent for 15 minutes
SX Operator %client name% softed closed the conversation. Operator used the soft close button in the client
TAC Operator %operator name% sent auto pickup request from transfer A transferred chat that was waiting for acceptance was automatically accepted
TFEF Transfer failed could not be sent. Any time when transfer couldn't complete
TFER Site transfer request to %targets% A cross site transfer was succesful
TFER Transfer request to %targets% A transfer was succesful
TR text rule forced closed session A chat text rule was set to close the chat
TRERR Translation failed: %original text% Translation service failed to work
TRSF Site transfer failed from %domain% to %newdomain% A cross site transfer failed
TRSS Site transfer from %domain% to %newdomain% A cross site transfer was attempted
UC Chat unclosed. Old state was %state% An async chat was reopened by the client or by the customer
VC Visitor Closed Session Visitor closed the chat window, or clicked Exit chat, or suffered some networking issue which caused them to disconnect
VT Visitor Client Side Time-Out
WAC Operator %operator name% sent auto pickup request from waiting chat A waiting chat was automatically accepted. (No skill rule, or client dropout)