Reference13r3:Concept App Service Connector for kuando®

Applies To

• innovaphone PBX from version 13r3

Overview

The basic aim of this app is to control a USB-busylight from the manufacturer Plenom / kuando® which is connected to the PC via USB and displays the current telephony status in different colors. Furthermore, the busy status can also be synchronized across other applications via a software called "kuandoHUB®".

Features

• Synchronizes call state (line is free/busy) and presence between Innovaphone PBX and kuandoHUB®
• Support to switch a myApps user to busy when calling in a supported 3rd party application
• Support for virtual desktop environments, as myApps and kuandoHUB® communicate with each other via HTTP

Requirements

• innovaphone AppPlatform
• innovaphone myApps
• innovaphone SoftphoneApp or PhoneApp
• Windows kuandoHUB® (minimum 1.1.12.0)
• Desired Windows kuandoHUB® Plugins from kuando® Website
  • Check the Synchronization Concept for supported 3rd-party Software

Setup with a physically Busylight

• A physically Plenom ® / kuando® USB-Busylight
• license "App(innovaphone-kuando)"

Concept

The basic concept is to synchronize the callstates and presence across different software solutions and to meet the requirements of the respective user.

From the user's point of view, he usually has several communication tools, but he can and usually only wants to make calls with one of these tools at the same time. This is exactly where the approach lies in bringing together the respective status of various software.

This approach is taken over by the kuandoHUB®. Any software can register to the kuandoHUB® as 3rd-party application and distribute his own information about active calls or current presence to them. The kuandoHUB® serves as a central collection point for all states and thus forms the center of the integration. With an active registration to the kuandoHUB® every 3rd-party application can set and revoke his own states.

Within the kuandoHUB® configuration, there is a software prioritization that can be defined by the user to obtain the desired behavior in each case. (Example: An "innovaphone call state" has a higher priority than a "Microsoft Teams presence note")

Example flow

In this example, we would like to illustrate the flow of an incoming call in the innovaphone envrionment:

1. The PBX tells myApps about a call
2. myApps forward this information to the App kuando® Connector
3. The kuando® Connector distribute this information to the HTTP-Interface of the kuandoHUB®
4. The kuandoHUB® can communicate with the LED Lamp via USB
5. Other 3rd-party applications are able to request for the current state and do stuff in his own environment with this

The chain shown below acts in the opposite direction if, for example, a Skype call is received. The result would be that the user would be on the phone in Skype and would also be busy in the PBX and a corresponding call partner would be shown.

Technical Overview

Technical Concept

We start the technical details in the myApps environment (top left of the picture). This is the starting point for a myApps user. The admin has already assigned both apps (kuando® Connector and kuando® Connector config) to the user.

myApps

When starting myApps, only the app kuando® Connector config is visible with an app icon, as the kuando® Connector is a hidden app that should only have background tasks.

If the user opens the app kuando® Connector config, it authorizes itself to the appropriate PBX object, which has a connection to the app service of the same name of the respective app instance. Likewise, a separate websocket connection is established from the client (the opened app) to the endpoint of the app instance, via which the app can speak directly with the app service. In this case, user-specific configurations can be read from the database and saved via the connection to the app service.

When the app is opened for the first time, a default configuration is created, which the user can change afterwards.

The same applies to the hidden service kuando® Connector, which is automatically started as soon as the first call is distributed via the PbxApi. Once the service has been started, it runs continuously in the background and serves the kuandoHUB®.

kuandoHUB®

If you look at the kuandoHUB® (center left in the picture), it forms a kind of collection point to which all applications on the PC (myApps, Skype, MS Teams, Webex, etc.) can communicate their current status.

Within the kuandoHUB® there is a user configuration to achieve a weighting of the different solutions. (Example: An "innovaphone call state" should have a higher priority than a "Microsoft Teams presence note"). Based on this weighting, exactly one status is always gained and used as the current status.

The colour of the selected status is displayed by the kuandoHUB® on the installed USB lamp. If you have connected several busylights, they will all be controlled in parallel. In addition, the kuandoHUB® provides an interface with which any software can query the current status.

This means, for example: Skype can report an active call. The kuandoHUB® sets the lamp to red and knows that an active call is running in the Skype software. myApps can now query the current status and knows that the user has an active call in Skype.

kuando® offers a small mini installation for download per supported 3rd party application. That means, if you want to use this solution with Skype, you have to install the kuandoHUB® and the kuando® Skype Extension. If you want to use Skype and Webex, you have to install both the Skype Extension and the Webex Extension.

When recognizing calls, it is important that no calls can be recognized in a web session. If you want MS Teams calls to be recognized, for example, you must have installed the extension and use the client for the call and not participate in a session in the browser. As a rule, it is sufficient to have the client installed. If you then receive an invitation to a conference from an external contact, the installed client opens automatically, if available.

Synchronization Concept

It is not trivial to reconcile the various statuses of active phone calls, conferences and presences. The following rules apply for prioritizing to a single status.

1. Calls overwrite presence information
2. A manual presence in myApps overwrite a presence from kuandoHUB®
3. The prioritization of the active state (only one is possible) results from the kuandoHUB® configuration. (see: kuandoHUB® prioritization)

The following states are supported by myApps: free, busy, away, dnd, onthephone

We will use the following mapping to apply the names state from a 3rd-party software that submit their state via kuandoHUB® to myApps:

kuandoHUB® platform / Source Software	Event(s)	Transformed myApps State
3CX	Call Alert, On-The-Phone	onthephone
Alcatel Rainbow Office	Call Alert, In-a-Conference, On-The-Phone	onthephone
Atos Unify Office	Call Alert, In-a-Conference, On-The-Phone	onthephone
Avaya Cloud Office	Call Alert, In-a-Conference, On-The-Phone	onthephone
Avaya Workplace	Call Alert, In a call	onthephone
Avaya One-X Communicator	Call alert, On-The-Phone	onthephone
AT&T Office@Hand	Call Alert, In-a-Conference, On-The-Phone	onthephone
BT Cloud Work	Call Alert, In-a-Conference, On-The-Phone	onthephone
Cisco Jabber	Call Alert, In-a-Conference, On-The-Phone	onthephone
Ecotel	Call Alert, In-a-Conference, On-The-Phone	onthephone
Eastlink	Call Alert, In-a-Conference, On-The-Phone	onthephone
MS Teams	On-The-Phone, In-a-Conference, Call Alert	onthephone
Plantronics Hub	Call Alert, On-The-Phone	onthephone
RingCentral Unified	Call Alert, On-The-Phone, In-a-Conference	onthephone
RingCentral Softphone	Call alert, In a call	onthephone
Slack	Call-Alert, On-The-Phone, In-A-Meeting	onthephone
Symphony	Call Alert, On-The-Phone, In-A-Conference	onthephone
TELUS Business Connect	Call Alert, On-The-Phone, In-a-Conference	onthephone
Broadsoft UC-One	Call Alert, On-The-Phone, In-a-Conference	onthephone
Jabra	Call Alert, On-The-Phone	onthephone
Verizon	Call Alert, On-The-Phone, In-a-Conference	onthephone
Vodafone	Call Alert, On-The-Phone, In-a-Conference	onthephone
Webex	Call Alert, On-The-Phone	onthephone
Zoom	Call Alert, In-a-Zoom-Meeting	onthephone
Manual Changer	Available, LTM (listen the music), Off	free
Manual Changer	Busy	busy
Manual Changer	Away, NAW (not at work)	away
Manual Changer	DND	dnd
Manual Changer	Lunch	lunch (implicit away with lunch message)

A software or event that is not listed in the mapping table above result in none which have no effect to call state or presence state. In this case, you will see transforming: ignored, sending application is unknown or transforming: ignored, sending event is unknown in the myApps trace. It is possible that new/different commands may be sent from third party applications in the future. If you have an application that is not on this list, but a kuandoHUB® plugin exists for it, please let us know.

Specialities for some kuandoHub® plugins

Please note: innovaphone supports a variety of "commands" and "states" produced by external third-party applications. innovaphone cannot and has not tested every single third-party application, and cannot provide detailed information about the dedicated configuration of a specific third-party application. Nevertheless, we are happy to list special configurations hints to be aware of with the respective third-party applications.

Zoom

You have to be logged on with your account in the Zoom client, otherwise Zoom will not broadcast the state.

Apps

innovaphone-kuandoconnector

This endpoint provides all the necessary components for the background process to talk to the kuandoHUB®, the LED lamp and the PBX and to perform the respective call state or presence updates.

innovaphone-kuandoconnector-config

This endpoint provides the user app for a test of the local LED lamp and a frontend for user-specific configurations.

Configuration

innovaphone

After you have installed the App and create an instance, the PBX Manager provides a plugin to perform the configuration. Two apps need to be created at this point.

• kuando® Connector which is not visible to the user and runs purely as a hidden service in the user's myApps environment to communicate with the kuandoHUB® in background.
• kuando® Connector Config which gives the user the possibility to test his physical LED lamp and to make local settings if necessary.

Afterwards, you have to distribute both apps directly via configuration at the user or via config template.

Also make sure, that the user has a kuando® App license (innovaphone-kuando) assigned.

Note: The apps should only be activated for users who actually use them. Since the service is always started in the background, many unnecessary log files are written if the kuandoHUB® is not rechable and repeated attempts are made to reach the kuandoHUB®.

kuandoHUB®

In the left menu you find an entry Plattform-Prioritäten. There you have to set a default configuration.

• Set the source Manual Changer to the bottom of the List and enable the checkmark Aktiv
• Navigate in the left menu to Farben and select the green one

With this setup, you have a default configuration, that your lamp shows a green color if no other software distribute a status.

The HTTP Server function must also be activated in the advanced settings.

kuandoHUB® prioritization

In the kuandoHUB® you can check the currently active states. It will be indicated with a gray background in the 3rd party software list. It is very important that presence states that "free signal" like "Free / Available" such as "MS Teams / available" are deactivated in the kuandoHUB®, otherwise they may overwrite other states.

Also you have to sort you events in the kuandoHUB® configuration. Make sure that all telephone events (ringing, busy, on the phone, ...) are of higher value than simple presence events. You can download here a sample configuration file.

Using a remote busylight

If the busylight isn't connected locally on the same client, where you use myApps - for example in a Citrix environment, where myApps is started inside the environment, but the busylight is connected at the local computer -, you can still access the busylight with some configuration on the local client.

Configuration on the client, where the busylight is physically connected

• install the kuandoHUB® software
• in the Windows registry, open the path Computer\HKEY_CURRENT_USER\Software\Busylight and create an entry with type "REG_SZ", name it "http_uri" and set the value to "http://+:8989/"
• create an incoming Windows Firewall entry, where incoming traffic to tcp port "8989" is allowed
  • Windows-Powershell command for this: New-NetFirewallRule -DisplayName "Allow Busylight HTTP Port 8989" -Direction Inbound -Action Allow -EdgeTraversalPolicy Allow -Protocol TCP -LocalPort 8989
• create an entry in the http.sys-file for the URL http://+:8989/
  • Windows-Powershell command for this: netsh http add urlacl url=http://+:8989/ user=DOMAIN\user
• make sure, that HTTP Server is activated in the kuandoHUB® softwares advanced settings

Configuration on the client, where myApps is installed

• open the KUANDO CONNECTOR CONFIG-App
• set the HTTP Server URL: according to the clients IP address and port, where the busylight is physically connected to
  • example: http://192.168.0.100:8989
• enter the HTTP Server access token:, which you can either copy from the kuandoHUB® (advanced settings), or the registry

Now the busylight can be used, even from an remote computer. For more information, the kuandoHUB® manual can be found in the downloaded kuandoHUB® setup folder.

Troubleshooting

Troubleshooting can be a bit tricky at this point. You should first think about which side the error is on in order to be able to approach it accordingly.

myApps site

Tracing

You will find trace output in the browser console or in the myApps log if you have enabled before the checkmarks browser, browser console in the trace options.

To better understand the logfile flow, you here will find a sample startup if the hidden service is closed (you have no calls before) and you get an incoming call.

open kuandoconnector url=https://...
started: kuandoconnector (hidden)
...
send to kuandoconnector: {"mt":"ApiUpdate","apis":{"com.innovaphone.notificationhandler":{...
...
kuandoconnector-log: start.url=wss://... start.originalUrl=https://...
kuandoconnector-log: debug - lamp_myapps_state: free
kuandoconnector-log: debug - lamp_call_state: free
kuandoconnector-log: debug - kuando_hub_installed: undefined
kuandoconnector-log: debug - count_calls: 0
...
kuandoconnector-log: app not initialized, sleep
...
kuandoconnector-log: Instance Connected
kuandoconnector-log: init http post request: http://localhost:8989/?http_token=
kuandoconnector-log: init http get request: http://localhost:8989/?action=currentpresence&http_token=
kuandoconnector-log: 3rd party state result: innovaphone myApps / Blink / Blink

You see that there is a prefix in all needed logfiles.

So it is a good thing to filter for:

• kuandoconnector-log:
• kuandoconnector-config-log:

to see all the output from the specific app.

Test the kuandoHUB® connection

• You can use the kuando® Connector Config App to test the connection and test the UBS-Busylight
• You can test the functionality of your local kuandoHUB® if you open the URL http://localhost:8989/. If you get this JSON output {"response": "OK"} it works fine.

Nothing happens / I do not see related logfiles in the console

• Make sure that the user has a valid license. If not you will see a error message in the kuando® Connector Config App or the following message in your myApps trace: kuandoconnector-log: no app license, stop service
• Make sure that the user has configured a "default telephony app" in his myApps or started the phone app. (If no phone app is opened a standard app has to be defined, that the PBX can wake up the associated phone app. Waking up the phone app implicitly wakes up the kuando® Connector App)

kuandoHUB® site

kuandoHUB® traces

You don't have direct logfiles of the kuandoHUB®, but there is a solution from Microsoft called Debug view which the kuandoHUB® uses for its debug output. You only need to start the software Debug view. No further configuration is necessary. All debug outputs of current processes that support the Debug View method are recorded directly. You can then save these log files.

Support Case

If you have problems with the kuandoHUB® or a kuandoHUB®-Plugin for a third-party software, you can open a corresponding ticket with Plenom at support@plenom.com.