Reference13r3:Concept App Service Connector for kuando®

From innovaphone-wiki

Jump to: navigation, search

Contents

[edit] Applies To

  • innovaphone PBX from version 13r3

[edit] 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 short videotalk about this solution.

[edit] 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.

[edit] 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

[edit] Requirements

  • innovaphone AppPlatform
  • innovaphone myApps
  • innovaphone SoftphoneApp or PhoneApp

[edit] Setup without a physically Busylight

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

[edit] Setup with a physically Busylight

[edit] 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")

[edit] 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 Connector for kuando®
  3. The Connector for kuando® distribute this information to the HTTP-Interface of the kuandoHUB®
  4. optional: If you use the kuandoHUB®, it 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.

Image:Kuando_connector_example_flow.png

[edit] Technical Overview

Image:Kuando_connector.png

[edit] 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.

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 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 Skype, you have to install the kuandoHUB® innovaphone Edition 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.

[edit] 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.

  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.

[edit] 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.

[edit] Zoom

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

[edit] MS Teams

After installing and starting the "Busylight for MS Teams" plugin from plenom, this popup might be shown:
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 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.

To get rid of it permanently, the only solution is, to disable the Office Integration in myApps.
If myApps is already installed, you have to disable it via registry entry on the Windows host. 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).

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®.

[edit] Synchronization kuandoHUB®-innovaphone

As mentioned above, currently the only supported plenom plugins are:

  • MS Teams
  • Webex
  • Zoom


[edit] Apps

[edit] 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.

[edit] 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.

[edit] Configuration

[edit] innovaphone configuration

[edit] 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®.

[edit] 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
URL Example: https://ap.domain.com/domain.com/kuandoconnector/innovaphone-kuando
Options to activate: Hidden, Websocket, Admin, PbxApi


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

[edit] 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.

[edit] 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.

[edit] kuandoHUB® innovaphone Edition

There is no configuration UI.

[edit] Special Setups

[edit] 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 - 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
  • 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:
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).

[edit] Known Limitation

[edit] myApps Office Integration won't work, if MS Teams plugin is used

As mentioned above, the myApps Office Integration can't be used anymore, if you use the MS teams plugin for kuandoHUB®.

[edit] 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.

[edit] 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.

[edit] 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:

  • kuando-log:
  • kuando-config-log:
  • or use a regex to get all relevant logfiles /(kuando-config-log|kuando-log)/

to see all the output from the specific app.

[edit] 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 http://localhost:8989/. If you get this JSON output {"response": "OK"} it works fine.

[edit] 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: kuando-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 Connector for kuando® App)

[edit] kuandoHUB® site

[edit] 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.

[edit] 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.

Personal tools