View source for Reference13r3:Concept App Service Connector for kuando®

[[Category:Concept|Apps]]
[[Category:Concept App Service Connector for kuando®]]
<!-- busylight, busy lamp, busylamp, busy light, kuando, kuandohub, kuando hub, plenom, connector -->
== Applies To == 

* innovaphone PBX from version 13r3

== Overview ==
The basic aim of this app is to synchronize the busy status across innovaphone and other applications via a software called "kuandoHUB®". Optionally, the control of 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. You can checkout a [https://www.youtube.com/watch?v=wtFEswUKnTE short videotalk] about this solution.

== Licensing ==
For both solutions (with/without Busylight) a license is needed.
* '''license "App(innovaphone-kuando-with-busylight)"''' - a Busylight is required
* '''license "App(innovaphone-kuando)"''' - no busylight is required 

The license "App(innovaphone-kuando)" can ALSO be used for a Busylight setup. For example, if the setup is started without a Busylight, but in a later step the customer wants a Busylight.

== Features ==
* Support to control a physical Busylight for calls in the innovaphone environment
* Support for virtual desktop environments, as myApps and ''kuandoHUB®'' communicate with each other via HTTP

'''Additional Features in Windows Systems'''
* Synchronizes call state (line is free/busy) and presence between Innovaphone PBX and various 3rd Party Applications via ''kuandoHUB®''
* Support to switch a myApps user to busy, when calling in a supported 3rd party application

== Requirements ==
* innovaphone AppPlatform
* innovaphone myApps 
* innovaphone SoftphoneApp or PhoneApp
* a separate .zip package called "Additional Software - Connector for kuando®" with additional Software which you can get from https://store.innovaphone.com/ in the tab "Software"

=== Setup with a physically Busylight ===
* A physically ''Plenom ®'' / ''kuando®'' USB-Busylight
* license "App(innovaphone-kuando-with-busylight)"
* Windows
** kuandoHUB® (minimum 1.1.14.4)
** Desired Windows kuandoHUB® Plugins and/or additional Plugins from kuando® Website
*** Check the [[#Synchronization_Concept|Synchronization Concept]] for supported 3rd-party Software
* MacOS
** kuandoHUB® (minimum 1.0.9)
** MacOS_BusylightHTTP (minimum 1.0.8)

=== Setup without a physically Busylight ===
* license "App(innovaphone-kuando)"
* Windows
** kuandoHUB®-innovaphone (minimum 0.9.1)
** Supported Windows kuandoHUB® Plugins
*** MS Teams
*** Webex
*** Zoom

;Important setup instructions
: Currently, the Zoom- and Team plugins include the presence priorities (available, away, busy etc.) per default, which we don’t want here.<br>
:In further versions, we will ignore these presence states. For the moment, please import the attached busylight_example.reg into your local Windows registry, which includes the correct states for Zoom and Teams, which is just the call state.

== 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:
# The PBX tells myApps about a call 
# myApps forward this information to the App ''Connector for kuando®'' 
# The ''Connector for kuando®'' distribute this information to the HTTP-Interface of the kuandoHUB®
# optional: If you use the ''kuandoHUB®'', it can communicate with the LED Lamp via USB
# 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.

[[Image:Kuando_connector_example_flow.png]]

=== Technical Overview ===
[[Image:Kuando_connector.png]]

=== 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 (''Connector for kuando®'' and ''Connector for kuando® config'') to the user.

;myApps
When starting myApps, only the app ''Connector for kuando® config'' is visible with an app icon, as the ''Connector for kuando®'' is a hidden app that should only have background tasks and will start automatically.

If the user opens the app ''Connector for kuando® 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.

The same applies to the hidden service ''Connector for kuando®'', which is automatically started as soon myApps is started. 
Once the service has been started, it runs continuously in the background and serves the kuandoHUB®.

;kuandoHUB®
If you want to use a physically USB Busylight, you can use 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.

;kuandoHUB® innovaphone Edition
If you don't want to use a physically USB Busylight, you can use the ''kuandoHUB® innovaphone Edition'' (center left in the picture). It forms a kind of collection point to which supported applications on the PC can communicate their current status.

Within the ''kuandoHUB® innovaphone Edition'' there is no configuration.

kuando® offers a small mini installation for download per supported 3rd party application.
That means, if you want to use this solution with MS-Teams, you have to install the ''kuandoHUB® innovaphone Edition'' and the ''kuando® MS-Teams Extension''.
If you want to use ''MS-Teams'' and ''Webex'', you have to install both the ''MS-Teams 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 kuandoHUB® ===
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.

# Calls overwrite presence information
# A manual presence in myApps overwrite a presence from ''kuandoHUB®''
# The prioritization of the active state (only one is possible) results from the ''kuandoHUB®'' configuration. (see: [[#kuandoHUB.C2.AE_prioritisation|kuandoHUB® prioritization]])

The following states are supported by myApps: <code>free, busy, away, dnd, onthephone</code>

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


{| class="wikitable sortable" border="1" cellspacing="2" cellpadding="5"
|-
! 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 <code>transforming: ignored, sending application is unknown</code> or <code>transforming: ignored, sending event is unknown</code> 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.

==== MS Teams ====
After installing and starting the "Busylight for MS Teams" plugin from plenom, this popup might be shown:<br />
[[Image:Busylight teams popup.jpg]]

You have to follow the instructions from the popup, to make the teams-plugin work.

This is caused by the [[Reference13r3:Concept_myApps_Office_Integration | myApps Office Integration]], which sets myApps as "default IM Provider" in the Windows Registry, at every start of myApps.
But for the kuando-teams-plugin to work, Microsoft Teams needs to be set as "default IM Provider".

So after every restart of the computer, you have to make these changes in team.<br /><br />

To get rid of it permanently, the only solution is, to disable the Office Integration in myApps.<br />
If myApps is already installed, you have to disable it via registry entry on the Windows host. [[Reference13r1:Concept_myApps_platform_services#MSI_Parameters_and_install_options | Here]] you can find all information, regarding the entry.
This entry can also be deployed via .msi-file, as written in the same section.

Also for new myApps installations, you can disable the Office Integration in the setup process (activate "disable Office Integration" there).<br />

To sum it up and since only one default IM Provider can exist (Microsoft restriction, not from our side), you can't use the Office Intregration anymore, if you want to use the Teams plugin for kuandoHUB®.

=== Synchronization kuandoHUB®-innovaphone ===
As mentioned [[Reference13r3:Concept_App_Service_Connector_for_kuando%C2%AE#Setup_without_a_physically_Busylight | above]], currently the only supported plenom plugins are:
* MS Teams
* Webex
* Zoom


== Apps ==

=== Connector for kuando® App (innovaphone-kuando) ===
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.

=== Connector for kuando® Config App (innovaphone-kuando-config) ===
This endpoint provides the user an app, for a test of the local LED lamp and a frontend for user-specific configurations and tracing settings.

== Configuration ==
=== innovaphone configuration ===
==== Creating app objects via PBX Manager ====
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. 
* ''Connector for kuando®'' 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.
* ''Connector for kuando® 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 Connector for 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®.''

==== Creating app objects manually ====
If you don't want to use the PBX Manager and rather create the App objects manually: 
* Create two App objects - one for the connector for kuando and for the connector for kuando config
* Name them properly
* Set the correct App URL, which points to the app instance on the AP
* set the required config options

Example for App '''Connector for Kuando''' app object<br />
'''URL Example:''' ''https://ap.domain.com/domain.com/kuandoconnector/innovaphone-kuando''<br />
'''Options to activate:''' ''Hidden, Websocket, Admin, PbxApi''


Example for App '''Connector for Kuando Config''' app object<br />
'''URL Example:''' ''https://ap.domain.com/domain.com/kuandoconnector/innovaphone-kuando-config''<br />
'''Options to activate:''' none

=== kuandoHUB® configuration ===
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 [[:Media:Default_kuando_prioritiesbackup.zip‎|'''''here''''']] a sample configuration file.

=== kuandoHUB® innovaphone Edition ===
There is no configuration UI.

== Special Setups ==
=== 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 <code>Computer\HKEY_CURRENT_USER\Software\Busylight</code> 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: <code>New-NetFirewallRule -DisplayName "Allow Busylight HTTP Port 8989" -Direction Inbound -Action Allow -EdgeTraversalPolicy Allow -Protocol TCP -LocalPort 8989</code>
* create an entry in the '''http.sys'''-file for the URL http://+:8989/
** Windows-Powershell command for this: <code>netsh http add urlacl url=http://+:8989/ user=DOMAIN\user</code> - change the "user"-part to your needs.
* make sure, that '''HTTP Server''' is activated in the kuandoHUB® softwares advanced settings
** registry entry for this is: entry type '''"REG_DWORD"''', name '''"http_enabled"''', value '''1'''
* restart the kuandoHUB®

'''Configuration on the client, where myApps is installed'''
* open the '''CONNECTOR FOR KUANDO 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
** if no registry entry exist, you can create one: entry type '''"REG_SZ"''', name it '''"http_token"''', and set the value to whatever you want - a crypto entry is recommended

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.

'''IMPORTANT:'''<br />
You have to use the myApps Launcher for this special setup, since Web-Browsers doesn't allow mixed content, which is needed (kuandoHUB® use http, whereas myApps uses https).

== Known Limitation ==

=== myApps Office Integration won't work, if MS Teams plugin is used===
As mentioned [[#MS Teams|above]], the [[Reference13r3:Concept_myApps_Office_Integration | myApps Office Integration]] can't be used anymore, if you use the MS teams plugin for kuandoHUB®.

== 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 ===

The configuration app will show some red warning banner:
* no license
* no kuandoHUB® detected
* to old kuandoHUB® version

If you don't see a red error message at the top of the app, you should go ahead to find your issue.

==== Tracing ====
You will find trace output in the browser console, or in the myApps log if you have enabled before the trace flags ''browser console'' in the myApps launcher trace options and the ''enabled-logfile'' checkmark in the configuration app.

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 kuando url=https://...
 started: kuando (hidden)
 ...
 send to kuando: {"mt":"ApiUpdate","apis":{"com.innovaphone.notificationhandler":{...
 ...
 kuando-log: start.url=wss://... start.originalUrl=https://...
 kuando-log: debug - lamp_myapps_state: free
 kuando-log: debug - lamp_call_state: free
 kuando-log: debug - kuando_hub_installed: undefined
 kuando-log: debug - count_calls: 0
 ...
 kuando-log: app not initialized, sleep
 ...
 kuando-log: Instance Connected
 kuando-log: init http post request: http://localhost:8989/?http_token=
 kuando-log: init http get request: http://localhost:8989/?action=currentpresence&http_token=
 kuando-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:
* <code>kuando-log:</code>
* <code>kuando-config-log:</code> 
* or use a regex to get all relevant logfiles <code>/(kuando-config-log|kuando-log)/</code>
to see all the output from the specific app.

==== Test the kuandoHUB® connection ====
* You can use the ''Connector for kuando® 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 <code>http://localhost:8989/</code>. If you get this JSON output <code>{"response": "OK"}</code> 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 ''Connector for kuando® Config App'' or the following message in your myApps trace: <code>kuando-log: no app license, stop service</code>
* 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 ''Connector for kuando® App'')

=== kuandoHUB® site ===

==== kuandoHUB® traces ====
You don't have direct logfiles of the kuandoHUB®, but there is a solution from Microsoft called [https://docs.microsoft.com/en-us/sysinternals/downloads/debugview 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 [mailto:support@plenom.com support@plenom.com].

==== Problem with Office 365 Cloud ====
For each mail Outlook show: "Ein Programm versucht, auf Ihre in Outlook gespeicherten Informationen zu E-Mail-Adressen zuzugreifen. ..."<br>
<u>Solution</u><br>
Configure and activate all Outlook functions in kuando hub. Send an E-Mail and now the light goes purple. Now deactivate the service and delete this service in "Plattformprioritäten". Outlook will now automatically shut down. Now the service of kuando is deinstalled in outlook.