innovaphone wiki - User contributions [en]

Reference15r1:Concept App Service Working

2026-04-16T11:37:42Z

Lme: /* Configuration */

[[Category:Concept|Apps]]
The Working App is an app for recording working hours. There is a user app (Working User) to start/stop time tracking and an admin app (Working Manager) to view working hours for all users.

== Applies To ==

* innovaphone PBX from version 15r1

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myApps
* Firmware V15r1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an app to track working hours.
There is a user app (Working User) to start/stop time tracking (clock style) or to add entries manually. These entries must be confirmed (=submitted) to be displayed on the admin app. Once they are confirmed, they can no longer be edited. There is also an admin app (Working Manager) to display the working time information for all users and where the configuration settings can be changed.
The app is designed to help employees and employers to easily track working hours in a digital manner.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working manager App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Features ==

===== Working time tracking and absences such as vacation/sick days and costume work types =====

* Work time account: Overview of the current work time balance
* Add pre-defined labels to working times

===== Working time regulations =====

*Timeout to submit entries (days): max interval the user has to submit the working hours.
* Min break time after 6 hours: min break time if the user has worked more than 6 hours.
* Min break time after 9 hours: min break time if the user has worked more than 9 hours.
* Default working hours

===== Groups/Group rights =====

* Groups can be defined
* Only the managers of the groups can see the users on the group on the Working Manager App
* Working types only available for the users on the group can be configured
* Enable/disable restrictions to submit working hours for the users on the group
* Enable/Disable verification by manager before submission to Human Resources

===== Import and export of existing tracked time with the help of CSV =====

===== Archiving working times of deleted employees =====

===== User replication: New users appear once assigned the Working User App =====

===== Create Connect-Posts with every absence request =====

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png|/Innovaphone-working.png|/Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is an app needed to provide the Working Client API, so that other apps can start/stop working times. The innovaphone-working-client-api app is also a hidden app. The Settings plugin also sets the hidden function. This app should be granted to apps that use it, not to users.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-manager ===
[[Image: Innovaphone-working-admin.png‎|/Innovaphone-working-admin.png|/Innovaphone-working-admin.png]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 workingmanager apps for the user-objects avaiable: 
workingmanager and 
workingmanager~hr. 
The administrator needs both.
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).

* Rights
** Config groups 
== CSV export ==
The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

== CSV import ==
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingmanager: the name of the working admin app.

== Settings Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

You can also configure the Connect instance and language for Connect Posts for absences.

==Configuration==
* Install the Working App with the new AP app installer available in the Settings . ''Hint : after the installation done, close and open again the Settings to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the Settings Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Assign the Working hr mode directly via config template.
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:
*App
*App Database
*App Websocket

Trace flags for myApps Client:
*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/14r2/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/14r2/doc/service/Working.htm SDK Documentation - Working Client API]

Reference15r1:Concept App Service Working

2026-04-16T11:28:30Z

Lme: /* Features */

[[Category:Concept|Apps]]
The Working App is an app for recording working hours. There is a user app (Working User) to start/stop time tracking and an admin app (Working Manager) to view working hours for all users.

== Applies To ==

* innovaphone PBX from version 15r1

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myApps
* Firmware V15r1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an app to track working hours.
There is a user app (Working User) to start/stop time tracking (clock style) or to add entries manually. These entries must be confirmed (=submitted) to be displayed on the admin app. Once they are confirmed, they can no longer be edited. There is also an admin app (Working Manager) to display the working time information for all users and where the configuration settings can be changed.
The app is designed to help employees and employers to easily track working hours in a digital manner.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working manager App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Features ==

===== Working time tracking and absences such as vacation/sick days and costume work types =====

* Work time account: Overview of the current work time balance
* Add pre-defined labels to working times

===== Working time regulations =====

*Timeout to submit entries (days): max interval the user has to submit the working hours.
* Min break time after 6 hours: min break time if the user has worked more than 6 hours.
* Min break time after 9 hours: min break time if the user has worked more than 9 hours.
* Default working hours

===== Groups/Group rights =====

* Groups can be defined
* Only the managers of the groups can see the users on the group on the Working Manager App
* Working types only available for the users on the group can be configured
* Enable/disable restrictions to submit working hours for the users on the group
* Enable/Disable verification by manager before submission to Human Resources

===== Import and export of existing tracked time with the help of CSV =====

===== Archiving working times of deleted employees =====

===== User replication: New users appear once assigned the Working User App =====

===== Create Connect-Posts with every absence request =====

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png|innovaphone-working.png/|/Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png|innovaphone-working-api.png/|/Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png|innovaphone-working-api.png/|/Innovaphone-working-api.png]]
This is an app needed to provide the Working Client API, so that other apps can start/stop working times. The innovaphone-working-client-api app is also a hidden app. The Settings plugin also sets the hidden function. This app should be granted to apps that use it, not to users.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-manager ===
[[Image: Innovaphone-working-admin.png‎|innovaphone-working-admin.png/|/Innovaphone-working-admin.png]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 workingmanager apps for the user-objects avaiable: 
workingmanager and 
workingmanager~hr. 
The administrator needs both.
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).

* Rights
** Config groups 
== CSV export ==
The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

== CSV import ==
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingmanager: the name of the working admin app.

== Settings Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

==Configuration==
* Install the Working App with the new AP app installer available in the Settings . ''Hint : after the installation done, close and open again the Settings to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the Settings Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Open the object workingmanager / App / Modes: (insert here:) hr.
* Open the object Config Admin / Apps / workingmanager~hr (select).
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:
*App
*App Database
*App Websocket

Trace flags for myApps Client:
*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/14r2/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/14r2/doc/service/Working.htm SDK Documentation - Working Client API]

Reference15r1:Concept App Service Working

2026-03-30T06:21:08Z

Lme: /* Requirements */

[[Category:Concept|Apps]]
The Working App is an app for recording working hours. There is a user app (Working User) to start/stop time tracking and an admin app (Working Manager) to view working hours for all users.

== Applies To ==

* innovaphone PBX from version 15r1

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myApps
* Firmware V15r1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an app to track working hours.
There is a user app (Working User) to start/stop time tracking (clock style) or to add entries manually. These entries must be confirmed (=submitted) to be displayed on the admin app. Once they are confirmed, they can no longer be edited. There is also an admin app (Working Manager) to display the working time information for all users and where the configuration settings can be changed.
The app is designed to help employees and employers to easily track working hours in a digital manner.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working manager App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Features ==

===== Working time tracking and absences such as vacation/sick days and costume work types =====

* Work time account: Overview of the current work time balance
* Add pre-defined labels to working times

===== Working time regulations =====

*Timeout to submit entries (days): max interval the user has to submit the working hours.
* Min break time after 6 hours: min break time if the user has worked more than 6 hours.
* Min break time after 9 hours: min break time if the user has worked more than 9 hours.
* Default working hours

===== Groups/Group rights =====

* Groups can be defined
* Only the managers of the groups can see the users on the group on the Working Manager App
* Working types only available for the users on the group can be configured
* Enable/disable restrictions to submit working hours for the users on the group
* Enable/Disable verification by manager before submission to Human Resources

===== Import and export of existing tracked time with the help of CSV =====

===== Archiving working times of deleted employees =====

===== User replication: New users appear once assigned the Working User App =====

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png|innovaphone-working.png/|/Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png|innovaphone-working-api.png/|/Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png|innovaphone-working-api.png/|/Innovaphone-working-api.png]]
This is an app needed to provide the Working Client API, so that other apps can start/stop working times. The innovaphone-working-client-api app is also a hidden app. The Settings plugin also sets the hidden function. This app should be granted to apps that use it, not to users.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-manager ===
[[Image: Innovaphone-working-admin.png‎|innovaphone-working-admin.png/|/Innovaphone-working-admin.png]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 workingmanager apps for the user-objects avaiable: 
workingmanager and 
workingmanager~hr. 
The administrator needs both.
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).

* Rights
** Config groups 
== CSV export ==
The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

== CSV import ==
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingmanager: the name of the working admin app.

== Settings Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

==Configuration==
* Install the Working App with the new AP app installer available in the Settings . ''Hint : after the installation done, close and open again the Settings to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the Settings Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Open the object workingmanager / App / Modes: (insert here:) hr.
* Open the object Config Admin / Apps / workingmanager~hr (select).
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:
*App
*App Database
*App Websocket

Trace flags for myApps Client:
*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/14r2/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/14r2/doc/service/Working.htm SDK Documentation - Working Client API]

Reference16r1:Concept App Service Working

2026-03-30T06:20:33Z

Lme: /* Requirements */

The Working App is used to record working hours and manage absences. The Working User app can be used to start/stop time tracking and create vacation requests. There is also an admin app (Working Manager) which allows users to view working hours and approve vacation requests.

== Applies To ==

* innovaphone PBX from version 16r1

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myApps
* Firmware V16r1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an application for digital time and absence management.

It consists of two parts:

* '''Working User App''' – used by employees to track their working hours (via clock-in/clock-out or manual entries) and to manage absence requests such as vacation or leave. Time entries and vacation requests must be confirmed (=submitted) before they appear in the admin app. Once confirmed, they can no longer be edited.
* '''Working Manager App''' – used by administrators or managers to view and manage working time and absence information for all users. It also allows approval or rejection of vacation requests and provides access to configuration settings.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working manager App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Features ==
=== Working ===
===== Working time tracking and custom work types =====

* Work time account: Overview of the current work time balance
* Add pre-defined labels to working times
* Information about working types marked with a label
* Total break time per month

===== Working time regulations =====

*Timeout to submit entries (days): max interval the user has to submit the working hours.
* Min break time after 6 hours: min break time if the user has worked more than 6 hours.
* Min break time after 9 hours: min break time if the user has worked more than 9 hours.
* Default working hours
* Comment on changes to contractual working hours

===== Groups/Group rights =====

* Groups can be defined
* Only the managers of the groups can see the users on the group on the Working Manager App
* Working types only available for the users on the group can be configured
* Enable/disable restrictions to submit working hours for the users on the group
* Enable/Disable verification by manager before submission to Human Resources

===== Archiving working times of deleted employees =====

===== User replication: New users appear once assigned the Working User App =====
=== Absences ===

==== vacation management ====

* Creating and approving vacation requests
* Define vacation rules in general and user-specific terms
* Creating Other absences with rules
* Configure vacation how many days can be carried over to the next year and how long they will be available

==== holidays and sick days ====

* Entering sick days
* Create a list of Public holidays based on Locations

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png|/Innovaphone-working.png|/Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.
Parameters: 
;Websocket: to set a websocket connection.
;Services: API which is used to get access to APIs provided by other App Services.
;Connect: Needed to access the Connect App and to create a zone for working.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is an app needed to provide the Working Service API, so that other apps can start/stop working times. The Working Service API app is also a hidden app. The Settings plugin also sets the hidden function. This app should be granted to apps that use it, not to users.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-manager ===
[[Image: Innovaphone-working-admin.png‎|/Innovaphone-working-admin.png|/Innovaphone-working-admin.png]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.
Parameters:
;Websocket: to set a websocket connection.
;PbxSignal: Needed for the Badge Counts

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 workingmanager apps for the user-objects avaiable: 
workingmanager and 
workingmanager~hr. 
The administrator needs both.
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).

* Rights
** Config groups 

=== Public Holidays API ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This API provides public holiday data for other apps. It allows them to check whether a specific date is a public holiday in a given country or region.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.

== Import and export of existing tracked time and absences with the help of CSV ==
=== CSV export ===
The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

=== CSV import ===
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingmanager: the name of the working admin app.

== Settings Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

=== Settings Plugin - Configuration ===
General settings for the app can be configured within this area.

* '''PBX Name:''' This refers to the name of the MasterPBX in the respective system environment. This setting must be set correctly for user replication and other functions to work.
* '''Connect Name:''' The H323 name of the Connect app must be configured here. This is usually “connect,” but it depends on the individual setup of the system.
* '''Connect Groups:''' Here you can define a comma-separated list of PBX group names to be used for Connect integration in private posts. This is necessary in order to be able to include separate PBX groups, such as the human resources department, in private posts in addition to department heads.
* '''Language for connectsposts''': Integration with the Connect app and thus the creation of “posts” is carried out from a central location. The language can be set for these posts. Currently, there is ‘de’ for German and “en” for English.

==Configuration==
* Install the Working App with the new AP app installer available in the Settings . ''Hint : after the installation done, close and open again the Settings to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the Settings Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Open the object workingmanager / App / Modes: (insert here:) hr.
* Open the object Config Admin / Apps / workingmanager~hr (select).
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:
*App
*App Database
*App Websocket

Trace flags for myApps Client:
*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/16r1/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/16r1/doc/service/Working.htm SDK Documentation - Working Client API]

Reference16r1:Concept App Service Working

2026-03-30T06:19:33Z

Lme: /* Related Articles */

The Working App is used to record working hours and manage absences. The Working User app can be used to start/stop time tracking and create vacation requests. There is also an admin app (Working Manager) which allows users to view working hours and approve vacation requests.

== Applies To ==

* innovaphone PBX from version 16r1

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myApps
* Firmware V16r1 beta1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an application for digital time and absence management.

It consists of two parts:

* '''Working User App''' – used by employees to track their working hours (via clock-in/clock-out or manual entries) and to manage absence requests such as vacation or leave. Time entries and vacation requests must be confirmed (=submitted) before they appear in the admin app. Once confirmed, they can no longer be edited.
* '''Working Manager App''' – used by administrators or managers to view and manage working time and absence information for all users. It also allows approval or rejection of vacation requests and provides access to configuration settings.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working manager App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Features ==
=== Working ===
===== Working time tracking and custom work types =====

* Work time account: Overview of the current work time balance
* Add pre-defined labels to working times
* Information about working types marked with a label
* Total break time per month

===== Working time regulations =====

*Timeout to submit entries (days): max interval the user has to submit the working hours.
* Min break time after 6 hours: min break time if the user has worked more than 6 hours.
* Min break time after 9 hours: min break time if the user has worked more than 9 hours.
* Default working hours
* Comment on changes to contractual working hours

===== Groups/Group rights =====

* Groups can be defined
* Only the managers of the groups can see the users on the group on the Working Manager App
* Working types only available for the users on the group can be configured
* Enable/disable restrictions to submit working hours for the users on the group
* Enable/Disable verification by manager before submission to Human Resources

===== Archiving working times of deleted employees =====

===== User replication: New users appear once assigned the Working User App =====
=== Absences ===

==== vacation management ====

* Creating and approving vacation requests
* Define vacation rules in general and user-specific terms
* Creating Other absences with rules
* Configure vacation how many days can be carried over to the next year and how long they will be available

==== holidays and sick days ====

* Entering sick days
* Create a list of Public holidays based on Locations

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png|/Innovaphone-working.png|/Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.
Parameters: 
;Websocket: to set a websocket connection.
;Services: API which is used to get access to APIs provided by other App Services.
;Connect: Needed to access the Connect App and to create a zone for working.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is an app needed to provide the Working Service API, so that other apps can start/stop working times. The Working Service API app is also a hidden app. The Settings plugin also sets the hidden function. This app should be granted to apps that use it, not to users.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-manager ===
[[Image: Innovaphone-working-admin.png‎|/Innovaphone-working-admin.png|/Innovaphone-working-admin.png]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.
Parameters:
;Websocket: to set a websocket connection.
;PbxSignal: Needed for the Badge Counts

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 workingmanager apps for the user-objects avaiable: 
workingmanager and 
workingmanager~hr. 
The administrator needs both.
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).

* Rights
** Config groups 

=== Public Holidays API ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This API provides public holiday data for other apps. It allows them to check whether a specific date is a public holiday in a given country or region.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.

== Import and export of existing tracked time and absences with the help of CSV ==
=== CSV export ===
The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

=== CSV import ===
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingmanager: the name of the working admin app.

== Settings Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

=== Settings Plugin - Configuration ===
General settings for the app can be configured within this area.

* '''PBX Name:''' This refers to the name of the MasterPBX in the respective system environment. This setting must be set correctly for user replication and other functions to work.
* '''Connect Name:''' The H323 name of the Connect app must be configured here. This is usually “connect,” but it depends on the individual setup of the system.
* '''Connect Groups:''' Here you can define a comma-separated list of PBX group names to be used for Connect integration in private posts. This is necessary in order to be able to include separate PBX groups, such as the human resources department, in private posts in addition to department heads.
* '''Language for connectsposts''': Integration with the Connect app and thus the creation of “posts” is carried out from a central location. The language can be set for these posts. Currently, there is ‘de’ for German and “en” for English.

==Configuration==
* Install the Working App with the new AP app installer available in the Settings . ''Hint : after the installation done, close and open again the Settings to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the Settings Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Open the object workingmanager / App / Modes: (insert here:) hr.
* Open the object Config Admin / Apps / workingmanager~hr (select).
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:
*App
*App Database
*App Websocket

Trace flags for myApps Client:
*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/16r1/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/16r1/doc/service/Working.htm SDK Documentation - Working Client API]

Reference16r1:Concept App Service Working

2026-03-25T13:55:59Z

Lme: /* Absences */

The Working App is used to record working hours and manage absences. The Working User app can be used to start/stop time tracking and create vacation requests. There is also an admin app (Working Manager) which allows users to view working hours and approve vacation requests.

== Applies To ==

* innovaphone PBX from version 16r1

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myApps
* Firmware V16r1 beta1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an application for digital time and absence management.

It consists of two parts:

* '''Working User App''' – used by employees to track their working hours (via clock-in/clock-out or manual entries) and to manage absence requests such as vacation or leave. Time entries and vacation requests must be confirmed (=submitted) before they appear in the admin app. Once confirmed, they can no longer be edited.
* '''Working Manager App''' – used by administrators or managers to view and manage working time and absence information for all users. It also allows approval or rejection of vacation requests and provides access to configuration settings.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working manager App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Features ==
=== Working ===
===== Working time tracking and custom work types =====

* Work time account: Overview of the current work time balance
* Add pre-defined labels to working times
* Information about working types marked with a label
* Total break time per month

===== Working time regulations =====

*Timeout to submit entries (days): max interval the user has to submit the working hours.
* Min break time after 6 hours: min break time if the user has worked more than 6 hours.
* Min break time after 9 hours: min break time if the user has worked more than 9 hours.
* Default working hours
* Comment on changes to contractual working hours

===== Groups/Group rights =====

* Groups can be defined
* Only the managers of the groups can see the users on the group on the Working Manager App
* Working types only available for the users on the group can be configured
* Enable/disable restrictions to submit working hours for the users on the group
* Enable/Disable verification by manager before submission to Human Resources

===== Archiving working times of deleted employees =====

===== User replication: New users appear once assigned the Working User App =====
=== Absences ===

==== vacation management ====

* Creating and approving vacation requests
* Define vacation rules in general and user-specific terms
* Creating Other absences with rules
* Configure vacation how many days can be carried over to the next year and how long they will be available

==== holidays and sick days ====

* Entering sick days
* Create a list of Public holidays based on Locations

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png|/Innovaphone-working.png|/Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.
Parameters: 
;Websocket: to set a websocket connection.
;Services: API which is used to get access to APIs provided by other App Services.
;Connect: Needed to access the Connect App and to create a zone for working.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is an app needed to provide the Working Service API, so that other apps can start/stop working times. The Working Service API app is also a hidden app. The Settings plugin also sets the hidden function. This app should be granted to apps that use it, not to users.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-manager ===
[[Image: Innovaphone-working-admin.png‎|/Innovaphone-working-admin.png|/Innovaphone-working-admin.png]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.
Parameters:
;Websocket: to set a websocket connection.
;PbxSignal: Needed for the Badge Counts

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 workingmanager apps for the user-objects avaiable: 
workingmanager and 
workingmanager~hr. 
The administrator needs both.
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).

* Rights
** Config groups 

=== Public Holidays API ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This API provides public holiday data for other apps. It allows them to check whether a specific date is a public holiday in a given country or region.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.

== Import and export of existing tracked time and absences with the help of CSV ==
=== CSV export ===
The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

=== CSV import ===
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingmanager: the name of the working admin app.

== Settings Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

=== Settings Plugin - Configuration ===
General settings for the app can be configured within this area.

* '''PBX Name:''' This refers to the name of the MasterPBX in the respective system environment. This setting must be set correctly for user replication and other functions to work.
* '''Connect Name:''' The H323 name of the Connect app must be configured here. This is usually “connect,” but it depends on the individual setup of the system.
* '''Connect Groups:''' Here you can define a comma-separated list of PBX group names to be used for Connect integration in private posts. This is necessary in order to be able to include separate PBX groups, such as the human resources department, in private posts in addition to department heads.
* '''Language for connectsposts''': Integration with the Connect app and thus the creation of “posts” is carried out from a central location. The language can be set for these posts. Currently, there is ‘de’ for German and “en” for English.

==Configuration==
* Install the Working App with the new AP app installer available in the Settings . ''Hint : after the installation done, close and open again the Settings to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the Settings Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Open the object workingmanager / App / Modes: (insert here:) hr.
* Open the object Config Admin / Apps / workingmanager~hr (select).
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:
*App
*App Database
*App Websocket

Trace flags for myApps Client:
*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/14r2/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/14r2/doc/service/Working.htm SDK Documentation - Working Client API]

Reference16r1:Concept App Service Working

2026-03-24T14:51:06Z

Lme: /* holidays and sick days */

The Working App is used to record working hours and manage absences. The Working User app can be used to start/stop time tracking and create vacation requests. There is also an admin app (Working Manager) which allows users to view working hours and approve vacation requests.

== Applies To ==

* innovaphone PBX from version 16r1

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myApps
* Firmware V16r1 beta1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an application for digital time and absence management.

It consists of two parts:

* '''Working User App''' – used by employees to track their working hours (via clock-in/clock-out or manual entries) and to manage absence requests such as vacation or leave. Time entries and vacation requests must be confirmed (=submitted) before they appear in the admin app. Once confirmed, they can no longer be edited.
* '''Working Manager App''' – used by administrators or managers to view and manage working time and absence information for all users. It also allows approval or rejection of vacation requests and provides access to configuration settings.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working manager App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Features ==
=== Working ===
===== Working time tracking and custom work types =====

* Work time account: Overview of the current work time balance
* Add pre-defined labels to working times

===== Working time regulations =====

*Timeout to submit entries (days): max interval the user has to submit the working hours.
* Min break time after 6 hours: min break time if the user has worked more than 6 hours.
* Min break time after 9 hours: min break time if the user has worked more than 9 hours.
* Default working hours

===== Groups/Group rights =====

* Groups can be defined
* Only the managers of the groups can see the users on the group on the Working Manager App
* Working types only available for the users on the group can be configured
* Enable/disable restrictions to submit working hours for the users on the group
* Enable/Disable verification by manager before submission to Human Resources

===== Archiving working times of deleted employees =====

===== User replication: New users appear once assigned the Working User App =====
=== Absences ===

==== vacation management ====

* Creating and approving vacation requests
* Define vacation rules in general and user-specific terms
* Creating Other absences with rules
* Configure vacation how many days can be carried over to the next year and how long they will be available

==== holidays and sick days ====

* Entering sick days
* Create a list of Public holidays based on Locations

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png|/Innovaphone-working.png|/Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.
Parameters: 
;Websocket: to set a websocket connection.
;Services: API which is used to get access to APIs provided by other App Services.
;Connect: Needed to access the Connect App and to create a zone for working.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is an app needed to provide the Working Service API, so that other apps can start/stop working times. The Working Service API app is also a hidden app. The Settings plugin also sets the hidden function. This app should be granted to apps that use it, not to users.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-manager ===
[[Image: Innovaphone-working-admin.png‎|/Innovaphone-working-admin.png|/Innovaphone-working-admin.png]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.
Parameters:
;Websocket: to set a websocket connection.
;PbxSignal: Needed for the Badge Counts

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 workingmanager apps for the user-objects avaiable: 
workingmanager and 
workingmanager~hr. 
The administrator needs both.
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).

* Rights
** Config groups 

=== Public Holidays API ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This API provides public holiday data for other apps. It allows them to check whether a specific date is a public holiday in a given country or region.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.

== Import and export of existing tracked time and absences with the help of CSV ==
=== CSV export ===
The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

=== CSV import ===
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingmanager: the name of the working admin app.

== Settings Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

=== Settings Plugin - Configuration ===
General settings for the app can be configured within this area.

* '''PBX Name:''' This refers to the name of the MasterPBX in the respective system environment. This setting must be set correctly for user replication and other functions to work.
* '''Connect Name:''' The H323 name of the Connect app must be configured here. This is usually “connect,” but it depends on the individual setup of the system.
* '''Connect Groups:''' Here you can define a comma-separated list of PBX group names to be used for Connect integration in private posts. This is necessary in order to be able to include separate PBX groups, such as the human resources department, in private posts in addition to department heads.
* '''Language for connectsposts''': Integration with the Connect app and thus the creation of “posts” is carried out from a central location. The language can be set for these posts. Currently, there is ‘de’ for German and “en” for English.

==Configuration==
* Install the Working App with the new AP app installer available in the Settings . ''Hint : after the installation done, close and open again the Settings to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the Settings Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Open the object workingmanager / App / Modes: (insert here:) hr.
* Open the object Config Admin / Apps / workingmanager~hr (select).
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:
*App
*App Database
*App Websocket

Trace flags for myApps Client:
*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/14r2/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/14r2/doc/service/Working.htm SDK Documentation - Working Client API]

Reference16r1:Concept App Service Working

2026-03-18T13:31:46Z

Lme: /* Working */

The Working App is used to record working hours and manage absences. The Working User app can be used to start/stop time tracking and create vacation requests. There is also an admin app (Working Manager) which allows users to view working hours and approve vacation requests.

== Applies To ==

* innovaphone PBX from version 16r1

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myApps
* Firmware V16r1 beta1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an application for digital time and absence management.

It consists of two parts:

* '''Working User App''' – used by employees to track their working hours (via clock-in/clock-out or manual entries) and to manage absence requests such as vacation or leave. Time entries and vacation requests must be confirmed (=submitted) before they appear in the admin app. Once confirmed, they can no longer be edited.
* '''Working Manager App''' – used by administrators or managers to view and manage working time and absence information for all users. It also allows approval or rejection of vacation requests and provides access to configuration settings.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working manager App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Features ==
=== Working ===
===== Working time tracking and custom work types =====

* Work time account: Overview of the current work time balance
* Add pre-defined labels to working times

===== Working time regulations =====

*Timeout to submit entries (days): max interval the user has to submit the working hours.
* Min break time after 6 hours: min break time if the user has worked more than 6 hours.
* Min break time after 9 hours: min break time if the user has worked more than 9 hours.
* Default working hours

===== Groups/Group rights =====

* Groups can be defined
* Only the managers of the groups can see the users on the group on the Working Manager App
* Working types only available for the users on the group can be configured
* Enable/disable restrictions to submit working hours for the users on the group
* Enable/Disable verification by manager before submission to Human Resources

===== Archiving working times of deleted employees =====

===== User replication: New users appear once assigned the Working User App =====
=== Absences ===

==== vacation management ====

* Creating and approving vacation requests
* Define vacation rules in general and user-specific terms

==== holidays and sick days ====

* Entering sick days
* Create a list of Public holidays based on Locations

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png|/Innovaphone-working.png|/Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.
Parameters: 
;Websocket: to set a websocket connection.
;Services: API which is used to get access to APIs provided by other App Services.
;Connect: Needed to access the Connect App and to create a zone for working.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is an app needed to provide the Working Service API, so that other apps can start/stop working times. The Working Service API app is also a hidden app. The Settings plugin also sets the hidden function. This app should be granted to apps that use it, not to users.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-manager ===
[[Image: Innovaphone-working-admin.png‎|/Innovaphone-working-admin.png|/Innovaphone-working-admin.png]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.
Parameters:
;Websocket: to set a websocket connection.
;PbxSignal: Needed for the Badge Counts

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 workingmanager apps for the user-objects avaiable: 
workingmanager and 
workingmanager~hr. 
The administrator needs both.
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).

* Rights
** Config groups 

=== Public Holidays API ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This API provides public holiday data for other apps. It allows them to check whether a specific date is a public holiday in a given country or region.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.

== Import and export of existing tracked time and absences with the help of CSV ==
=== CSV export ===
The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

=== CSV import ===
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingmanager: the name of the working admin app.

== Settings Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

=== Settings Plugin - Configuration ===
General settings for the app can be configured within this area.

* '''PBX Name:''' This refers to the name of the MasterPBX in the respective system environment. This setting must be set correctly for user replication and other functions to work.
* '''Connect Name:''' The H323 name of the Connect app must be configured here. This is usually “connect,” but it depends on the individual setup of the system.
* '''Connect Groups:''' Here you can define a comma-separated list of PBX group names to be used for Connect integration in private posts. This is necessary in order to be able to include separate PBX groups, such as the human resources department, in private posts in addition to department heads.
* '''Language for connectsposts''': Integration with the Connect app and thus the creation of “posts” is carried out from a central location. The language can be set for these posts. Currently, there is ‘de’ for German and “en” for English.

==Configuration==
* Install the Working App with the new AP app installer available in the Settings . ''Hint : after the installation done, close and open again the Settings to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the Settings Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Open the object workingmanager / App / Modes: (insert here:) hr.
* Open the object Config Admin / Apps / workingmanager~hr (select).
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:
*App
*App Database
*App Websocket

Trace flags for myApps Client:
*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/14r2/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/14r2/doc/service/Working.htm SDK Documentation - Working Client API]

Reference16r1:Concept App Service Working

2026-03-18T13:26:33Z

Lme: /* holidays and sick days */

The Working App is used to record working hours and manage absences. The Working User app can be used to start/stop time tracking and create vacation requests. There is also an admin app (Working Manager) which allows users to view working hours and approve vacation requests.

== Applies To ==

* innovaphone PBX from version 16r1

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myApps
* Firmware V16r1 beta1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an application for digital time and absence management.

It consists of two parts:

* '''Working User App''' – used by employees to track their working hours (via clock-in/clock-out or manual entries) and to manage absence requests such as vacation or leave. Time entries and vacation requests must be confirmed (=submitted) before they appear in the admin app. Once confirmed, they can no longer be edited.
* '''Working Manager App''' – used by administrators or managers to view and manage working time and absence information for all users. It also allows approval or rejection of vacation requests and provides access to configuration settings.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working manager App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Features ==
=== Working ===
===== Working time tracking and costume work types =====

* Work time account: Overview of the current work time balance
* Add pre-defined labels to working times

===== Working time regulations =====

*Timeout to submit entries (days): max interval the user has to submit the working hours.
* Min break time after 6 hours: min break time if the user has worked more than 6 hours.
* Min break time after 9 hours: min break time if the user has worked more than 9 hours.
* Default working hours

===== Groups/Group rights =====

* Groups can be defined
* Only the managers of the groups can see the users on the group on the Working Manager App
* Working types only available for the users on the group can be configured
* Enable/disable restrictions to submit working hours for the users on the group
* Enable/Disable verification by manager before submission to Human Resources

===== Archiving working times of deleted employees =====

===== User replication: New users appear once assigned the Working User App =====
=== Absences ===

==== vacation management ====

* Creating and approving vacation requests
* Define vacation rules in general and user-specific terms

==== holidays and sick days ====

* Entering sick days
* Create a list of Public holidays based on Locations

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png|/Innovaphone-working.png|/Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.
Parameters: 
;Websocket: to set a websocket connection.
;Services: API which is used to get access to APIs provided by other App Services.
;Connect: Needed to access the Connect App and to create a zone for working.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This is an app needed to provide the Working Service API, so that other apps can start/stop working times. The Working Service API app is also a hidden app. The Settings plugin also sets the hidden function. This app should be granted to apps that use it, not to users.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-manager ===
[[Image: Innovaphone-working-admin.png‎|/Innovaphone-working-admin.png|/Innovaphone-working-admin.png]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.
Parameters:
;Websocket: to set a websocket connection.
;PbxSignal: Needed for the Badge Counts

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 workingmanager apps for the user-objects avaiable: 
workingmanager and 
workingmanager~hr. 
The administrator needs both.
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).

* Rights
** Config groups 

=== Public Holidays API ===
[[Image: Innovaphone-working-api.png|/Innovaphone-working-api.png|/Innovaphone-working-api.png]]
This API provides public holiday data for other apps. It allows them to check whether a specific date is a public holiday in a given country or region.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.

== Import and export of existing tracked time and absences with the help of CSV ==
=== CSV export ===
The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

=== CSV import ===
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingmanager: the name of the working admin app.

== Settings Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

=== Settings Plugin - Configuration ===
General settings for the app can be configured within this area.

* '''PBX Name:''' This refers to the name of the MasterPBX in the respective system environment. This setting must be set correctly for user replication and other functions to work.
* '''Connect Name:''' The H323 name of the Connect app must be configured here. This is usually “connect,” but it depends on the individual setup of the system.
* '''Connect Groups:''' Here you can define a comma-separated list of PBX group names to be used for Connect integration in private posts. This is necessary in order to be able to include separate PBX groups, such as the human resources department, in private posts in addition to department heads.
* '''Language for connectsposts''': Integration with the Connect app and thus the creation of “posts” is carried out from a central location. The language can be set for these posts. Currently, there is ‘de’ for German and “en” for English.

==Configuration==
* Install the Working App with the new AP app installer available in the Settings . ''Hint : after the installation done, close and open again the Settings to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the Settings Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Open the object workingmanager / App / Modes: (insert here:) hr.
* Open the object Config Admin / Apps / workingmanager~hr (select).
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:
*App
*App Database
*App Websocket

Trace flags for myApps Client:
*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/14r2/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/14r2/doc/service/Working.htm SDK Documentation - Working Client API]

Reference14r2:MyApps Plugin for Virtual Desktops

2026-03-05T07:19:19Z

Lme: /* Audio Quality issues (e.g. choppy audio) */

[[Category:Concept|Apps]]
== Description ==
A softphone running at a terminal server (Citrix, Windows, ...) has the problem that audio and video streams start and terminate at the server.
Received audio from remote peer at the server must be transmitted to the local client for playback and audio delivered by the audio device must be also transmitted from the local client to the server for transmission to remote peer.
This transmission of the audio stream between server and client adds a delay which makes the communication impossible.
Video suffers from the same limitations.

The myApps Virtual Desktop Plugin enables media data to be transferred to the local client in terminal server environments.
== Applies To ==
* innovaphone PBX from version 14r2
* Client OS: Windows, Linux<ref>VDI Plugin for Linux only connects to Citrix or VMWare Horizon, RDP still not supported</ref>(Ubuntu 22 or 23, RangeeOS<ref>RangeeOS is listed due to a customer testimonial. No tests have been conducted by innovaphone. Tests were done using myapps 14r2sr3, RangeeOS Firmware 12.00 build 203 ff and Citrix Workspace 2311. (Workspace version 2402 & 2405 have a bug with USB redirection and 2408 is not starting reliably)</ref>, IGEL OS<ref>IGEL OS: available at [https://app.igel.com/myAppsPlugin/15.1.455+1 IGEL App Portal]</ref>) or MacOS operating systems
* Hypervisor OS: Citrix, Windows Terminal Server environments and VMWare Horizon<ref>VMWare Horizon OS is listed due to a customer testimonial. No tests have been conducted by innovaphone.</ref> 
<references/>

== Requirements ==
* innovaphone PBX
* innovaphone myApps V14r2
* innovaphone myApps Plugin V14r2
* Firmware V14r2 final

== Concept ==
The myApps Plugin at the client is in charge of all tasks related to the media streams and the management of the Audio/Video devices. For instance:
* start or stop an audio/video device
* gathering of the ICE candidates
* connect to a remote peer with the ICE protocol
* start a ringing device
* rendering of video

But we now need a way of communicating between the myApps running at the terminal server and the myApps plugin running at the terminal client in order to carry out all these actions.

Main VDI Platforms (Citrix, Windows, VMware) provide a way of communicating between server and client through Virtual Channels:

* [https://docs.citrix.com/en-us/citrix-virtual-apps-desktops/technical-overview/virtual-channels Citrix technical overview]
* [https://support.citrix.com/support-home/kbsearch/article?articleNumber=CTX691230 Citrix support article summary]
* [https://learn.microsoft.com/en-us/windows/win32/termserv/using-terminal-services-virtual-channels Microsoft Remote Desktop Services virtual channels]

=== Call signaling ===
The VDI Plugin has no connection to the PBX. Signaling is still done at the terminal server by the myApps client.

=== Audio transmission ===
The plugin connects Audio, ICE and DTLS directly to the other endpoint. Since Audio itself does not use virtual channels, the plugin on the client must be able [[Howto:What_Ports_are_used_for_Signaling_and_Voice_Traffic_in_SIP_and_H.323%3F#ICE_STUN_TURN|to reach the TURN/STUN server via port 3478]].

== Configuration ==
'''Citrix Workspace app must first be installed on all platforms. This is necessary because the myApps plugin must copy a .dll (Windows) / .so (MacOS/Linux) into the Citrix installation directory. '''
For this to work, the Citrix installation directory must be in the %ProgramFiles(x86)% or %ProgramFiles% directory.

=== Windows ===
The myApps Plugin .msi must be installed or deployed at the Thin-Client and does not require any configuration.

=== MacOS ===
Install the myAppsPlugin.dmg or .pkg at the Thin-Client and does not require any configuration.

=== Linux ===
Update your Linux PC first:

'''sudo apt-get update'''

Download latest Citrix Workspace App (Mar 7, 2024) for Debian and x86_64 platform:

'''https://www.citrix.com/downloads/workspace-app/linux/workspace-app-for-linux-latest.html'''

Citrix Workspace app needs '''libwebkit2gtk-4.0-37''' packet and this packet is not available in Ubuntu-24.04 version.

Install it at your Linux PC:

https://docs.citrix.com/en-us/citrix-workspace-app-for-linux/install.html

'''sudo apt install -f ./icaclient_<version>._amd64.deb'''

Install (or update) now the myApps Plugin:

'''sudo apt install -f ./myAppsPlugin.deb'''

Headset Buttons:

*Jabra: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-java.rules
**Add <code>ATTRS{idVendor}=="0b0e", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
*Epos: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-epos.rules
** Add <code>ATTRS{idVendor}=="1395", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
*Plantronics: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-plantronics.rules
** Add <code>ATTRS{idVendor}=="047f", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
* Snom: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-snom.rules
** Add <code>ATTRS{idVendor}=="251c", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
* Yealink: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-yealink.rules
** Add <code>ATTRS{idVendor}=="6993", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>

No additional configuration required.

=== Configuration on the Terminalserver ===
The Softphone App at the terminal server does not require any additional configuration.

== How it works ==
User starts the VDI software (Citrix Workspace App or Windows Remotedesktop) needed to connect to a remote server.

This software automatically starts the myApps Plugin. No user action required.

The user starts myApps at the server for the Softphone App. myApps discovers that it is running in terminal server environment and will connect to the plugin which was already started by the VDI software.

The user does not need to have any knowledge about the myApps Plugin.

== Known issues ==
* The audio module in the MyApps Plugin for Linux/IgelOS has no echo cancellation. It is therefore recommended to use a headset, as headsets usually have their own echo cancellers.
* Webcam and remote videos must be rendered over the Softphone App but for the time being a native window is opened at the terminal client (only for the Windows Plugin)
* Connecting to a conference or 3rd party conference does not transmit video as video starts in the Javascript code of the Softphone App and Javascript has no access to the local webcam at the remote server.
**Video is displayed but with delay due to the rendering process.
**Citrix may provide access to the local webcam internally and the webcam may be available but remote peer will probably experience delay of the received video.
* When MyApps is used as a Citrix Published App, notification pop-ups cannot be displayed. This is because Citrix does not recognize the notifications as part of MyApps and therefore does not show them as part of the published app. If the full desktop is used in Citrix, the notifications function correctly.
* Start of AppSharing remains at the terminal server but the transmission of the media now starts at the local client.
* The MyApps Plugin for macOS supports only Citrix Workspace, the "Windows-App" from Microsoft is currently not supported
 We need to implement an exception for appSharing in the future as the transmission must happen at the server.
 For the time being the appSharing is transmitted to the client and forwarded to the remote peer adding some delay due to this tranmission between server and client (only for the Windows Plugin)

==Troubleshooting==
If the problem still exists after trying the OS-specific hints below, open a support ticket and send a trace from the myApps client (remote) with App and Browser option. Please send also all myAppsPlugin-x.txt and myAppsRemote-x.txt trace files from the myApps-plugin on the local PC.

=== Troubleshooting Windows ===
If Citrix is used as a terminal server environment:
#Citrix must be installed '''BEFORE''' the plugin
#Check in "C:/program files/Citrix/ICA Client" folder, there is the .dll myAppscitrixremoteserviesvc.dll
#Check in the registry, that: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\ICA 3.0 is there. "VirtualDriverEx" must be there with the value: InnovaphoneCitrixPlugin
#In Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\InnovaphoneCitrixPlugin as Drivename and DrivenameWin32 you should find the .dll as value and as innovaphone path the path of the plugin for the file myAppsplugin

Dump files are in the trace folder c:\users\$user\Appdata\local\innovaphone\myAppsPlugin if client crash at start.

'''Remote desktop (Windows)'''

After installing the plugin, check this registry folder:

Computer\HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Default\AddIns\innovaphoneRemoteServicesSvc64

and check as "Name" the path of the .dll <--- c:\program files(x86)\iinnovaphone\myAppsPlugin\myAppsRemoteServiceSvc64.dll

check that the .dll exist in the mentioned direcotry and the plugin.

'''Disable Echo Canceler (Windows PC)'''

Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps einen neuen Eintrag erstellen:

Type: DWORD (REG_DWORD)

Name: disableEchoCanceller

Value: 1 ( or use, Value: 0 to enable the Echo Canceller)

=== Troubleshooting Linux ===

'''Citrix Workspace App must be installed before the myAppsPlugin'''

Innovaphone Plugin is installed under /opt/innovaphone/'''myAppsPlugin''' and in /opt/Citrix/ICAClient/'''myAppsCitrixPlugin.so'''

myAppsCitrixPlugin.so library is called by the Citrix Workspace App and this library opens the myAppsPlugin.

There is a file in the Citrix installation called module.ini (/opt/Citrix/ICAClient/config/module.ini). Inside this file the myApps Citrix Plugin library is included:

- VirtualDriver entry must contain myAppsCitrixPlugin

- a line with '''myAppsCitrixPlugin=On''' must exist and

Following directory '''/var/log/apps/myAppsPlugin/''' must also exist for the log files with write permission for everyone (drwxrwxrwx)

====Audio Quality issues (e.g. choppy audio)====
If you run into audio quality when using myapps on Linux, the following configuration is recommended:

* Use Pipewire as the audio server
* Set the system-wide sample rate (default 44.1 kHz) to 48 kHz, since most USB headsets (e.g. Jabra) operate at 48 kHz.

You need to apply settings on OS level, since the audio backend and sample rate are operating system settings and cannot be controlled by the application.

You can check the Active audio server and sample rate with the following command:

<code>pactl info</code>

Based on your language-settings you will get a different output.
But you want to look for something like "Server Name" and "Default-Sample-Specification".

The expected results are (Language set to English):

Server Name: pulseaudio

Default Sample Specification: s16le 2ch 48000Hz

If you use pipewire you will get something like this:

Server Name: PulseAudio (on PipeWire 1.4.2)

Default Sample Specification: float32le 2ch 48000Hz

=== Troubleshooting MacOS ===

'''Citrix Workspace App must be installed before the myAppsPlugin'''

In /Library/Application Support/Citrix/PlugIns

must exist myAppsCitrixPlugin.plugin -> /Application/myappsPlugin.app/Contents/PlugIns/myapps_citrix_plugin.plugin

under:

/Users/.../Library/Application Support/Citrix Receiver

there is a file called Modules. Inside this file the myApps Plugin is included:

- VirtualDriver entry must contain myAppsCitrixPlugin

- a line with myAppsCitrixPlugin=On must exist

- and another line with [myAppsCitrixPlugin] too

both things are done during the installation. In case something is not working must check that the link to the plugin exists and that the modules file contains these entries.

And under /Users/.../Library/Containers/com.innovaphone.myapps-plugin-14r2/Data/Documents a log file is created: myAppsPlugin.txt

=== Troubleshooting Citrix ===
A Virtual Channel Policy must be added to the Registry at the '''Citrix Server''':

Create '''VCPolicies''' folder under '''HKLM/Software/Policies/Citrix''' if it does not exist.

Create '''VCPolicies''' folder under '''HKLM/Software/WOW6432Node/Policies/Citrix''' if it does not exist.

Create a REG_MULTI_SZ entry with the name '''VirtualChannelWhiteList'''. This entry must contain as value: '''INNOHDX,C:\Program Files (x86)\innovaphone\myApps\myApps.exe'''

=== Troubleshooting RTP Stream ===

You can analyze the RTP stream with the switch "--record-rtp-stream"

* RTP reception after Echo Canceller and JitterBuffer
* Audio from microphone and send to RTP

You have to start the myApps client as follows: myApps.exe --record-rtp-stream

After the call, you can find the audio files in the folder: C:\Users\...\AppData\Local\innovaphone\myApps

Tool to listen to the RTP stream: Audacity

Go to: File / Import / Raw Data and open the Folder with the Rtp stream and select the file.

For RTP-Send and RTP-Recv Data, use the Audio Codec G711 -> A-Law and 8000

For the Wave-in (out) Data Use Signed 16-bit PCM and 8000 Abtastrate

== Related Articles ==

* https://wiki.innovaphone.com/index.php?title=Reference14r2:Concept_myApps
* https://wiki.innovaphone.com/index.php?title=Reference14r2:Concept_App_SoftphoneApp

Reference14r2:MyApps Plugin for Virtual Desktops

2026-01-28T12:55:59Z

Lme: /* Audio Quality issues (e.g. choppy audio) */

[[Category:Concept|Apps]]
== Description ==
A softphone running at a terminal server (Citrix, Windows, ...) has the problem that audio and video streams start and terminate at the server.
Received audio from remote peer at the server must be transmitted to the local client for playback and audio delivered by the audio device must be also transmitted from the local client to the server for transmission to remote peer.
This transmission of the audio stream between server and client adds a delay which makes the communication impossible.
Video suffers from the same limitations.

The myApps Virtual Desktop Plugin enables media data to be transferred to the local client in terminal server environments.
== Applies To ==
* innovaphone PBX from version 14r2
* Client OS: Windows, Linux (Ubuntu 22 or 23, RangeeOS<ref>RangeeOS is listed due to a customer testimonial. No tests have been conducted by innovaphone. Tests were done using myapps 14r2sr3, RangeeOS Firmware 12.00 build 203 ff and Citrix Workspace 2311. (Workspace version 2402 & 2405 have a bug with USB redirection and 2408 is not starting reliably)</ref>, IGEL OS<ref>IGEL OS: available at [https://app.igel.com/myAppsPlugin/15.1.455+1 IGEL App Portal]</ref>) or MacOS operating systems
* Hypervisor OS: Citrix, Windows Terminal Server environments and VMWare Horizon<ref>VMWare Horizon OS is listed due to a customer testimonial. No tests have been conducted by innovaphone.</ref> 
<references/>

== Requirements ==
* innovaphone PBX
* innovaphone myApps V14r2
* innovaphone myApps Plugin V14r2
* Firmware V14r2 final

== Concept ==
The myApps Plugin at the client is in charge of all tasks related to the media streams and the management of the Audio/Video devices. For instance:
* start or stop an audio/video device
* gathering of the ICE candidates
* connect to a remote peer with the ICE protocol
* start a ringing device
* rendering of video

But we now need a way of communicating between the myApps running at the terminal server and the myApps plugin running at the terminal client in order to carry out all these actions.

Main VDI Platforms (Citrix, Windows, VMware) provide a way of communicating between server and client through Virtual Channels:

* [https://docs.citrix.com/en-us/citrix-virtual-apps-desktops/technical-overview/virtual-channels Citrix technical overview]
* [https://support.citrix.com/support-home/kbsearch/article?articleNumber=CTX691230 Citrix support article summary]
* [https://learn.microsoft.com/en-us/windows/win32/termserv/using-terminal-services-virtual-channels Microsoft Remote Desktop Services virtual channels]

=== Call signaling ===
The VDI Plugin has no connection to the PBX. Signaling is still done at the terminal server by the myApps client.

=== Audio transmission ===
The plugin connects Audio, ICE and DTLS directly to the other endpoint. Since Audio itself does not use virtual channels, the plugin on the client must be able [[Howto:What_Ports_are_used_for_Signaling_and_Voice_Traffic_in_SIP_and_H.323%3F#ICE_STUN_TURN|to reach the TURN/STUN server via port 3478]].

== Configuration ==
'''Citrix Workspace app must first be installed on all platforms. This is necessary because the myApps plugin must copy a .dll (Windows) / .so (MacOS/Linux) into the Citrix installation directory. '''
For this to work, the Citrix installation directory must be in the %ProgramFiles(x86)% or %ProgramFiles% directory.

=== Windows ===
The myApps Plugin .msi must be installed or deployed at the Thin-Client and does not require any configuration.

=== MacOS ===
Install the myAppsPlugin.dmg or .pkg at the Thin-Client and does not require any configuration.

=== Linux ===
Update your Linux PC first:

'''sudo apt-get update'''

Download latest Citrix Workspace App (Mar 7, 2024) for Debian and x86_64 platform:

'''https://www.citrix.com/downloads/workspace-app/linux/workspace-app-for-linux-latest.html'''

Citrix Workspace app needs '''libwebkit2gtk-4.0-37''' packet and this packet is not available in Ubuntu-24.04 version.

Install it at your Linux PC:

https://docs.citrix.com/en-us/citrix-workspace-app-for-linux/install.html

'''sudo apt install -f ./icaclient_<version>._amd64.deb'''

Install (or update) now the myApps Plugin:

'''sudo apt install -f ./myAppsPlugin.deb'''

Headset Buttons:

*Jabra: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-java.rules
**Add <code>ATTRS{idVendor}=="0b0e", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
*Epos: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-epos.rules
** Add <code>ATTRS{idVendor}=="1395", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
*Plantronics: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-plantronics.rules
** Add <code>ATTRS{idVendor}=="047f", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
* Snom: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-snom.rules
** Add <code>ATTRS{idVendor}=="251c", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
* Yealink: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-yealink.rules
** Add <code>ATTRS{idVendor}=="6993", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>

No additional configuration required.

=== Configuration on the Terminalserver ===
The Softphone App at the terminal server does not require any additional configuration.

== How it works ==
User starts the VDI software (Citrix Workspace App or Windows Remotedesktop) needed to connect to a remote server.

This software automatically starts the myApps Plugin. No user action required.

The user starts myApps at the server for the Softphone App. myApps discovers that it is running in terminal server environment and will connect to the plugin which was already started by the VDI software.

The user does not need to have any knowledge about the myApps Plugin.

== Known issues ==
* The audio module in the MyApps Plugin for Linux/IgelOS has no echo cancellation. It is therefore recommended to use a headset, as headsets usually have their own echo cancellers.
* Webcam and remote videos must be rendered over the Softphone App but for the time being a native window is opened at the terminal client (only for the Windows Plugin)
* Connecting to a conference or 3rd party conference does not transmit video as video starts in the Javascript code of the Softphone App and Javascript has no access to the local webcam at the remote server.
**Video is displayed but with delay due to the rendering process.
**Citrix may provide access to the local webcam internally and the webcam may be available but remote peer will probably experience delay of the received video.
* When MyApps is used as a Citrix Published App, notification pop-ups cannot be displayed. This is because Citrix does not recognize the notifications as part of MyApps and therefore does not show them as part of the published app. If the full desktop is used in Citrix, the notifications function correctly.
* Start of AppSharing remains at the terminal server but the transmission of the media now starts at the local client.
* The MyApps Plugin for macOS supports only Citrix Workspace, the "Windows-App" from Microsoft is currently not supported
 We need to implement an exception for appSharing in the future as the transmission must happen at the server.
 For the time being the appSharing is transmitted to the client and forwarded to the remote peer adding some delay due to this tranmission between server and client (only for the Windows Plugin)

==Troubleshooting==
If the problem still exists after trying the OS-specific hints below, open a support ticket and send a trace from the myApps client (remote) with App and Browser option. Please send also all myAppsPlugin-x.txt and myAppsRemote-x.txt trace files from the myApps-plugin on the local PC.

=== Troubleshooting Windows ===
If Citrix is used as a terminal server environment:
#Citrix must be installed '''BEFORE''' the plugin
#Check in "C:/program files/Citrix/ICA Client" folder, there is the .dll myAppscitrixremoteserviesvc.dll
#Check in the registry, that: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\ICA 3.0 is there. "VirtualDriverEx" must be there with the value: InnovaphoneCitrixPlugin
#In Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\InnovaphoneCitrixPlugin as Drivename and DrivenameWin32 you should find the .dll as value and as innovaphone path the path of the plugin for the file myAppsplugin

Dump files are in the trace folder c:\users\$user\Appdata\local\innovaphone\myAppsPlugin if client crash at start.

'''Remote desktop (Windows)'''

After installing the plugin, check this registry folder:

Computer\HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Default\AddIns\innovaphoneRemoteServicesSvc64

and check as "Name" the path of the .dll <--- c:\program files(x86)\iinnovaphone\myAppsPlugin\myAppsRemoteServiceSvc64.dll

check that the .dll exist in the mentioned direcotry and the plugin.

'''Disable Echo Canceler (Windows PC)'''

Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps einen neuen Eintrag erstellen:

Type: DWORD (REG_DWORD)

Name: disableEchoCanceller

Value: 1 ( or use, Value: 0 to enable the Echo Canceller)

=== Troubleshooting Linux ===

'''Citrix Workspace App must be installed before the myAppsPlugin'''

Innovaphone Plugin is installed under /opt/innovaphone/'''myAppsPlugin''' and in /opt/Citrix/ICAClient/'''myAppsCitrixPlugin.so'''

myAppsCitrixPlugin.so library is called by the Citrix Workspace App and this library opens the myAppsPlugin.

There is a file in the Citrix installation called module.ini (/opt/Citrix/ICAClient/config/module.ini). Inside this file the myApps Citrix Plugin library is included:

- VirtualDriver entry must contain myAppsCitrixPlugin

- a line with '''myAppsCitrixPlugin=On''' must exist and

Following directory '''/var/log/apps/myAppsPlugin/''' must also exist for the log files with write permission for everyone (drwxrwxrwx)

====Audio Quality issues (e.g. choppy audio)====
If you run into audio quality when using myapps on Linux, the following configuration is recommended:

* Use PulseAudio as the audio server
* Set the system-wide sample rate (default 44.1 kHz) to 48 kHz, since most USB headsets (e.g. Jabra) operate at 48 kHz.

You need to apply settings on OS level, since the audio backend and sample rate are operating system settings and cannot be controlled by the application.

You can check the Active audio server and sample rate with the following command:

<code>pactl info</code>

Based on your language-settings you will get a different output.
But you want to look for something like "Server Name" and "Default-Sample-Specification".

The expected results are (Language set to English):

Server Name: pulseaudio

Default Sample Specification: s16le 2ch 48000Hz

If you use pipewire you will get something like this:

Server Name: PulseAudio (on PipeWire 1.4.2)

Default Sample Specification: float32le 2ch 48000Hz

=== Troubleshooting MacOS ===

'''Citrix Workspace App must be installed before the myAppsPlugin'''

In /Library/Application Support/Citrix/PlugIns

must exist myAppsCitrixPlugin.plugin -> /Application/myappsPlugin.app/Contents/PlugIns/myapps_citrix_plugin.plugin

under:

/Users/.../Library/Application Support/Citrix Receiver

there is a file called Modules. Inside this file the myApps Plugin is included:

- VirtualDriver entry must contain myAppsCitrixPlugin

- a line with myAppsCitrixPlugin=On must exist

- and another line with [myAppsCitrixPlugin] too

both things are done during the installation. In case something is not working must check that the link to the plugin exists and that the modules file contains these entries.

And under /Users/.../Library/Containers/com.innovaphone.myapps-plugin-14r2/Data/Documents a log file is created: myAppsPlugin.txt

=== Troubleshooting Citrix ===
A Virtual Channel Policy must be added to the Registry at the '''Citrix Server''':

Create '''VCPolicies''' folder under '''HKLM/Software/Policies/Citrix''' if it does not exist.

Create '''VCPolicies''' folder under '''HKLM/Software/WOW6432Node/Policies/Citrix''' if it does not exist.

Create a REG_MULTI_SZ entry with the name '''VirtualChannelWhiteList'''. This entry must contain as value: '''INNOHDX,C:\Program Files (x86)\innovaphone\myApps\myApps.exe'''

=== Troubleshooting RTP Stream ===

You can analyze the RTP stream with the switch "--record-rtp-stream"

* RTP reception after Echo Canceller and JitterBuffer
* Audio from microphone and send to RTP

You have to start the myApps client as follows: myApps.exe --record-rtp-stream

After the call, you can find the audio files in the folder: C:\Users\...\AppData\Local\innovaphone\myApps

Tool to listen to the RTP stream: Audacity

Go to: File / Import / Raw Data and open the Folder with the Rtp stream and select the file.

For RTP-Send and RTP-Recv Data, use the Audio Codec G711 -> A-Law and 8000

For the Wave-in (out) Data Use Signed 16-bit PCM and 8000 Abtastrate

== Related Articles ==

* https://wiki.innovaphone.com/index.php?title=Reference14r2:Concept_myApps
* https://wiki.innovaphone.com/index.php?title=Reference14r2:Concept_App_SoftphoneApp

Reference14r2:MyApps Plugin for Virtual Desktops

2026-01-28T10:23:16Z

Lme: /* Troubleshooting Linux */

[[Category:Concept|Apps]]
== Description ==
A softphone running at a terminal server (Citrix, Windows, ...) has the problem that audio and video streams start and terminate at the server.
Received audio from remote peer at the server must be transmitted to the local client for playback and audio delivered by the audio device must be also transmitted from the local client to the server for transmission to remote peer.
This transmission of the audio stream between server and client adds a delay which makes the communication impossible.
Video suffers from the same limitations.

The myApps Virtual Desktop Plugin enables media data to be transferred to the local client in terminal server environments.
== Applies To ==
* innovaphone PBX from version 14r2
* Client OS: Windows, Linux (Ubuntu 22 or 23, RangeeOS<ref>RangeeOS is listed due to a customer testimonial. No tests have been conducted by innovaphone. Tests were done using myapps 14r2sr3, RangeeOS Firmware 12.00 build 203 ff and Citrix Workspace 2311. (Workspace version 2402 & 2405 have a bug with USB redirection and 2408 is not starting reliably)</ref>, IGEL OS<ref>IGEL OS: available at [https://app.igel.com/myAppsPlugin/15.1.455+1 IGEL App Portal]</ref>) or MacOS operating systems
* Hypervisor OS: Citrix, Windows Terminal Server environments and VMWare Horizon<ref>VMWare Horizon OS is listed due to a customer testimonial. No tests have been conducted by innovaphone.</ref> 
<references/>

== Requirements ==
* innovaphone PBX
* innovaphone myApps V14r2
* innovaphone myApps Plugin V14r2
* Firmware V14r2 final

== Concept ==
The myApps Plugin at the client is in charge of all tasks related to the media streams and the management of the Audio/Video devices. For instance:
* start or stop an audio/video device
* gathering of the ICE candidates
* connect to a remote peer with the ICE protocol
* start a ringing device
* rendering of video

But we now need a way of communicating between the myApps running at the terminal server and the myApps plugin running at the terminal client in order to carry out all these actions.

Main VDI Platforms (Citrix, Windows, VMware) provide a way of communicating between server and client through Virtual Channels:

* [https://docs.citrix.com/en-us/citrix-virtual-apps-desktops/technical-overview/virtual-channels Citrix technical overview]
* [https://support.citrix.com/support-home/kbsearch/article?articleNumber=CTX691230 Citrix support article summary]
* [https://learn.microsoft.com/en-us/windows/win32/termserv/using-terminal-services-virtual-channels Microsoft Remote Desktop Services virtual channels]

=== Call signaling ===
The VDI Plugin has no connection to the PBX. Signaling is still done at the terminal server by the myApps client.

=== Audio transmission ===
The plugin connects Audio, ICE and DTLS directly to the other endpoint. Since Audio itself does not use virtual channels, the plugin on the client must be able [[Howto:What_Ports_are_used_for_Signaling_and_Voice_Traffic_in_SIP_and_H.323%3F#ICE_STUN_TURN|to reach the TURN/STUN server via port 3478]].

== Configuration ==
'''Citrix Workspace app must first be installed on all platforms. This is necessary because the myApps plugin must copy a .dll (Windows) / .so (MacOS/Linux) into the Citrix installation directory. '''
For this to work, the Citrix installation directory must be in the %ProgramFiles(x86)% or %ProgramFiles% directory.

=== Windows ===
The myApps Plugin .msi must be installed or deployed at the Thin-Client and does not require any configuration.

=== MacOS ===
Install the myAppsPlugin.dmg or .pkg at the Thin-Client and does not require any configuration.

=== Linux ===
Update your Linux PC first:

'''sudo apt-get update'''

Download latest Citrix Workspace App (Mar 7, 2024) for Debian and x86_64 platform:

'''https://www.citrix.com/downloads/workspace-app/linux/workspace-app-for-linux-latest.html'''

Citrix Workspace app needs '''libwebkit2gtk-4.0-37''' packet and this packet is not available in Ubuntu-24.04 version.

Install it at your Linux PC:

https://docs.citrix.com/en-us/citrix-workspace-app-for-linux/install.html

'''sudo apt install -f ./icaclient_<version>._amd64.deb'''

Install (or update) now the myApps Plugin:

'''sudo apt install -f ./myAppsPlugin.deb'''

Headset Buttons:

*Jabra: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-java.rules
**Add <code>ATTRS{idVendor}=="0b0e", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
*Epos: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-epos.rules
** Add <code>ATTRS{idVendor}=="1395", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
*Plantronics: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-plantronics.rules
** Add <code>ATTRS{idVendor}=="047f", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
* Snom: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-snom.rules
** Add <code>ATTRS{idVendor}=="251c", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>
* Yealink: Create a file sudo <your-favorite-text-editor> /etc/udev/rules.d/50-udev-yealink.rules
** Add <code>ATTRS{idVendor}=="6993", MODE="0666", GROUP="users"</code> as content. After creating the udev file (as root), reload the udev rules using: <code>sudo udevadm control --reload</code>

No additional configuration required.

=== Configuration on the Terminalserver ===
The Softphone App at the terminal server does not require any additional configuration.

== How it works ==
User starts the VDI software (Citrix Workspace App or Windows Remotedesktop) needed to connect to a remote server.

This software automatically starts the myApps Plugin. No user action required.

The user starts myApps at the server for the Softphone App. myApps discovers that it is running in terminal server environment and will connect to the plugin which was already started by the VDI software.

The user does not need to have any knowledge about the myApps Plugin.

== Known issues ==
* The audio module in the MyApps Plugin for Linux/IgelOS has no echo cancellation. It is therefore recommended to use a headset, as headsets usually have their own echo cancellers.
* Webcam and remote videos must be rendered over the Softphone App but for the time being a native window is opened at the terminal client (only for the Windows Plugin)
* Connecting to a conference or 3rd party conference does not transmit video as video starts in the Javascript code of the Softphone App and Javascript has no access to the local webcam at the remote server.
**Video is displayed but with delay due to the rendering process.
**Citrix may provide access to the local webcam internally and the webcam may be available but remote peer will probably experience delay of the received video.
* When MyApps is used as a Citrix Published App, notification pop-ups cannot be displayed. This is because Citrix does not recognize the notifications as part of MyApps and therefore does not show them as part of the published app. If the full desktop is used in Citrix, the notifications function correctly.
* Start of AppSharing remains at the terminal server but the transmission of the media now starts at the local client.
* The MyApps Plugin for macOS supports only Citrix Workspace, the "Windows-App" from Microsoft is currently not supported
 We need to implement an exception for appSharing in the future as the transmission must happen at the server.
 For the time being the appSharing is transmitted to the client and forwarded to the remote peer adding some delay due to this tranmission between server and client (only for the Windows Plugin)

==Troubleshooting==
If the problem still exists after trying the OS-specific hints below, open a support ticket and send a trace from the myApps client (remote) with App and Browser option. Please send also all myAppsPlugin-x.txt and myAppsRemote-x.txt trace files from the myApps-plugin on the local PC.

=== Troubleshooting Windows ===
If Citrix is used as a terminal server environment:
#Citrix must be installed '''BEFORE''' the plugin
#Check in "C:/program files/Citrix/ICA Client" folder, there is the .dll myAppscitrixremoteserviesvc.dll
#Check in the registry, that: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\ICA 3.0 is there. "VirtualDriverEx" must be there with the value: InnovaphoneCitrixPlugin
#In Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Citrix\ICA Client\Engine\Configuration\Advanced\Modules\InnovaphoneCitrixPlugin as Drivename and DrivenameWin32 you should find the .dll as value and as innovaphone path the path of the plugin for the file myAppsplugin

Dump files are in the trace folder c:\users\$user\Appdata\local\innovaphone\myAppsPlugin if client crash at start.

'''Remote desktop (Windows)'''

After installing the plugin, check this registry folder:

Computer\HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Default\AddIns\innovaphoneRemoteServicesSvc64

and check as "Name" the path of the .dll <--- c:\program files(x86)\iinnovaphone\myAppsPlugin\myAppsRemoteServiceSvc64.dll

check that the .dll exist in the mentioned direcotry and the plugin.

'''Disable Echo Canceler (Windows PC)'''

Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps einen neuen Eintrag erstellen:

Type: DWORD (REG_DWORD)

Name: disableEchoCanceller

Value: 1 ( or use, Value: 0 to enable the Echo Canceller)

=== Troubleshooting Linux ===

'''Citrix Workspace App must be installed before the myAppsPlugin'''

Innovaphone Plugin is installed under /opt/innovaphone/'''myAppsPlugin''' and in /opt/Citrix/ICAClient/'''myAppsCitrixPlugin.so'''

myAppsCitrixPlugin.so library is called by the Citrix Workspace App and this library opens the myAppsPlugin.

There is a file in the Citrix installation called module.ini (/opt/Citrix/ICAClient/config/module.ini). Inside this file the myApps Citrix Plugin library is included:

- VirtualDriver entry must contain myAppsCitrixPlugin

- a line with '''myAppsCitrixPlugin=On''' must exist and

Following directory '''/var/log/apps/myAppsPlugin/''' must also exist for the log files with write permission for everyone (drwxrwxrwx)

====Recommendation for Linux Administrators (Audio)====

For optimal and stable audio quality when using myapps on Linux, the following configuration is recommended:

Use PulseAudio as the audio server
PipeWire may cause audio quality issues due to its PulseAudio compatibility layer.

Set the system-wide sample rate to 48 kHz
Most USB headsets (e.g. Jabra) operate at 48 kHz.
Using 44.1 kHz causes unnecessary resampling and may degrade audio quality.

Apply settings on OS level
Audio backend and sample rate are operating system settings and cannot be controlled by the application.

'''THIS WILL NOT HELP YOU IF YOU HAVE NO AUDIO AT ALL'''

You can check the Active audio server and samplerate with the following command:

<code>pactl info</code>

Based on your language-settings you will get a different output.
But you want to look for something like "Server Name" and "Default-Sample-Specification".

The expected results are (Language set to English):

Server Name: pulseaudio

Default Sample Specification: s16le 2ch 48000Hz

=== Troubleshooting MacOS ===

'''Citrix Workspace App must be installed before the myAppsPlugin'''

In /Library/Application Support/Citrix/PlugIns

must exist myAppsCitrixPlugin.plugin -> /Application/myappsPlugin.app/Contents/PlugIns/myapps_citrix_plugin.plugin

under:

/Users/.../Library/Application Support/Citrix Receiver

there is a file called Modules. Inside this file the myApps Plugin is included:

- VirtualDriver entry must contain myAppsCitrixPlugin

- a line with myAppsCitrixPlugin=On must exist

- and another line with [myAppsCitrixPlugin] too

both things are done during the installation. In case something is not working must check that the link to the plugin exists and that the modules file contains these entries.

And under /Users/.../Library/Containers/com.innovaphone.myapps-plugin-14r2/Data/Documents a log file is created: myAppsPlugin.txt

=== Troubleshooting Citrix ===
A Virtual Channel Policy must be added to the Registry at the '''Citrix Server''':

Create '''VCPolicies''' folder under '''HKLM/Software/Policies/Citrix''' if it does not exist.

Create '''VCPolicies''' folder under '''HKLM/Software/WOW6432Node/Policies/Citrix''' if it does not exist.

Create a REG_MULTI_SZ entry with the name '''VirtualChannelWhiteList'''. This entry must contain as value: '''INNOHDX,C:\Program Files (x86)\innovaphone\myApps\myApps.exe'''

=== Troubleshooting RTP Stream ===

You can analyze the RTP stream with the switch "--record-rtp-stream"

* RTP reception after Echo Canceller and JitterBuffer
* Audio from microphone and send to RTP

You have to start the myApps client as follows: myApps.exe --record-rtp-stream

After the call, you can find the audio files in the folder: C:\Users\...\AppData\Local\innovaphone\myApps

Tool to listen to the RTP stream: Audacity

Go to: File / Import / Raw Data and open the Folder with the Rtp stream and select the file.

For RTP-Send and RTP-Recv Data, use the Audio Codec G711 -> A-Law and 8000

For the Wave-in (out) Data Use Signed 16-bit PCM and 8000 Abtastrate

== Related Articles ==

* https://wiki.innovaphone.com/index.php?title=Reference14r2:Concept_myApps
* https://wiki.innovaphone.com/index.php?title=Reference14r2:Concept_App_SoftphoneApp

Reference16r1:Concept App Service Connector for kuando®

2025-12-01T07:33:26Z

Lme: /* Requirements */

[[Category:Concept|Apps]]
[[Category:Concept App Service Connector for kuando®]]

== 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 (LED and Audio) 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 2.1.1)
** Desired Windows kuandoHUB® Plugins and/or additional Plugins from [https://www.plenom.com/downloads/download-software/ kuando® Download Website]
*** Check the [[#Synchronization Concept kuandoHUB®|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.5)
** 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. 
: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|kuando_connector_example_flow.png/]]

=== Technical Overview ===
[[Image:Kuando_connector.png|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® prioritization|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: 
[[Image:Busylight teams popup.jpg|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. 

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

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®#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 
'''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

=== 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 [[index.php?title=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
* If you use a remote workplace, in the windows registry will be a new REG_DWORD with the name "http_port"created under the path <code>Computer\HKEY_CURRENT_USER\Software\Busylight</code>
* create an incoming Windows Firewall entry, where incoming traffic to tcp port '''****''' is allowed
** Windows-Powershell command for this: <code>New-NetFirewallRule -DisplayName "Allow Busylight HTTP Port [PORT]" -Direction Inbound -Action Allow -EdgeTraversalPolicy Allow -Protocol TCP -LocalPort [PORT]</code>
* create an entry in the '''http.sys'''-file for the URL example: http://+:8989/
** Windows-Powershell command for this: <code>netsh http add urlacl url=http://+:[PORT]/ 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:''' 
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).

=== Using kuandoHUB® in a remote environment ===
When kuandoHUB® is started in a remote environment, it uses dynamic ports so that multiple users can use the kuandoHUB® at the same time.
myApps must connect to this port. In this scenario, kuandoHUB® stores the port in the registry and myapps checks whether a dynamic port must be used.

If such a dynamic port is found in the registry, it temporarily overwrites the connection configuration in the app.

You see this in the logfile:
kuando-log: Overwrite local http port with http://localhost:1234

=== Simultaneous use of "Connector for kuando" and "Connector for Office365" ===
To support the coexistence of both apps, the user can activate the ''Ignore MS Teams'' option in their configuration.
This means that incoming MS Teams actions are ignored, as they are processed by the ''Connector for Office365'' app.
Otherwise, you end up in a situation where a call remains in the PBX even though it has been hung up in MS Teams.

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

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

Reference16r1:Concept App Service Connector for kuando®

2025-11-25T10:08:49Z

Lme: /* Special Setups */ change for new kuando remote busy light

[[Category:Concept|Apps]]
[[Category:Concept App Service Connector for kuando®]]

== 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 (LED and Audio) 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 [https://www.plenom.com/downloads/download-software/ kuando® Download Website]
*** Check the [[#Synchronization Concept kuandoHUB®|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. 
: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|kuando_connector_example_flow.png/]]

=== Technical Overview ===
[[Image:Kuando_connector.png|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® prioritization|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: 
[[Image:Busylight teams popup.jpg|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. 

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

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®#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 
'''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

=== 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 [[index.php?title=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
* If you use a remote workplace, in the windows registry will be a new REG_DWORD with the name "http_port"created under the path <code>Computer\HKEY_CURRENT_USER\Software\Busylight</code>
* create an incoming Windows Firewall entry, where incoming traffic to tcp port '''****''' is allowed
** Windows-Powershell command for this: <code>New-NetFirewallRule -DisplayName "Allow Busylight HTTP Port [PORT]" -Direction Inbound -Action Allow -EdgeTraversalPolicy Allow -Protocol TCP -LocalPort [PORT]</code>
* create an entry in the '''http.sys'''-file for the URL example: http://+:8989/
** Windows-Powershell command for this: <code>netsh http add urlacl url=http://+:[PORT]/ 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:''' 
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).

=== Using kuandoHUB® in a remote environment ===
When kuandoHUB® is started in a remote environment, it uses dynamic ports so that multiple users can use the kuandoHUB® at the same time.
myApps must connect to this port. In this scenario, kuandoHUB® stores the port in the registry and myapps checks whether a dynamic port must be used.

If such a dynamic port is found in the registry, it temporarily overwrites the connection configuration in the app.

You see this in the logfile:
kuando-log: Overwrite local http port with http://localhost:1234

=== Simultaneous use of "Connector for kuando" and "Connector for Office365" ===
To support the coexistence of both apps, the user can activate the ''Ignore MS Teams'' option in their configuration.
This means that incoming MS Teams actions are ignored, as they are processed by the ''Connector for Office365'' app.
Otherwise, you end up in a situation where a call remains in the PBX even though it has been hung up in MS Teams.

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

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

Howto15r1:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance

2025-02-27T07:29:08Z

Lme: /* Migration */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
==Applies To==
This information applies to

* IPVA 15r1
* VMWare ESXi (vSphere) 6.7 - 8
* VMWare vCenter Server 6.7 - 8



==More Information==
===Problem Details===
The standby functionality implemented in the innovaphone PBX enables to start PBX software on the standby gateway in fail over scenario. A drawback in this implementation is following - since the standby PBX is running on other physical gateway, all active calls and connections are interrupted while switching from master to standby. The switch to standby hardware takes a while, so the downtime about 2 minutes must be considered additionally.

To be able to implement a PBX with zero downtime on hardware failures, a VMWare [http://www.vmware.com/de/products/vsphere/features/fault-tolerance.html Fault Tolerance(FT)] feature of the VMWare vSphere can be used. Therefore the PBX must be implemented on the innovaphone Virtual Appliance (IPVA) and the Virtual Machine running IPVA must be hosted on a FT-enabled VMWare Cluster.

===System Requirements===
The VMWare infrastructure must fulfil following requirements to be able to run FT-enabled VMs:
* VMware vSphere Advanced or Enterprise Edition (FT Support included in this editions)
* The CPU and chip-set of the Hosts must support Fault Tolerance.
* The ESXi/vSphere hosts must be equipped with same CPU type and be part of FT-enabled Cluster

===Prepare your VM===
If you want to use FT you need to use the IPVA Version which includes SCSI-Disks, it's not possible to use the "Old" IPVA with IDE-Disks.
To Run the SCSI-IPVA on VMware, you need to do Following steps:
* Download and unzip '''ipva-vmx-scsi.zip'''
* Convert all 4 disks to the VM by using the following command.
<syntaxhighlight lang="bash">
vmkfstools -i /vmfs/volumes/datastore/current-VM-folder/disk.vmdk /vmfs/volumes/datastore/new-VM-folder/disk.vmdk
</syntaxhighlight>
* Now you need to attach the New Disks to your VM:
# You need to detach your old Disks from your IPVA in the settings of your IPVA itself.
# After you removed all the old Disks, you now need to open the Settings of your IPVA itself again and attach the new Disks.
# You need to make sure the Disks are on the correct SCSI controllers
# The Disks need to be on following Positions
## hd.boot.vmdk SCSI-Controller 0 0:0
## hd-cf.vmdk SCSI-Controller 0 0:1
## hd-flash.vmdk SCSI-Controller 1 1:0
## hd-dump.vmdk SCSI-Controller 1 1:1

===Installation===
For detailed implementation of FT-enabled VMWare infrastructure, please refer to the [https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-availability/GUID-7525F8DD-9B8F-4089-B020-BAA4AC6509D2.html VMWare documentation].

On the IPVA side no special settings or changes must be performed to enable FT.

We have tested the FT functionality with following setup and also in our cloud setup:

[[File:FT Test setup.png|ft_test_setup.png/|ft_test_setup.png/]]

While testing the Softphones where in a conference and also calling a WQ. While in an active call, a failure of ESXi/vSphere host was simulated. While testing multiple times, there were some noticeable interruptions in the media stream were realized, while the failover. Even with Video streams there were no problem and everything worked without noticeable problematic behavior.

===Migration===
To Migrate your system, you can download your Config and upload it to a Fault Tolerance Compatible IPVA.

===Known Problems===
The Fault Tolerance does not protect the system from software failures(e.g. trap of the IPVA).

== Related Articles ==
*[[Reference15r1:Concept Innovaphone Virtual Appliance]]

[[Category:Howto|{{PAGENAME}}]]

Howto15r1:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance

2025-02-27T07:28:52Z

Lme: /* Migration */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
==Applies To==
This information applies to

* IPVA 15r1
* VMWare ESXi (vSphere) 6.7 - 8
* VMWare vCenter Server 6.7 - 8



==More Information==
===Problem Details===
The standby functionality implemented in the innovaphone PBX enables to start PBX software on the standby gateway in fail over scenario. A drawback in this implementation is following - since the standby PBX is running on other physical gateway, all active calls and connections are interrupted while switching from master to standby. The switch to standby hardware takes a while, so the downtime about 2 minutes must be considered additionally.

To be able to implement a PBX with zero downtime on hardware failures, a VMWare [http://www.vmware.com/de/products/vsphere/features/fault-tolerance.html Fault Tolerance(FT)] feature of the VMWare vSphere can be used. Therefore the PBX must be implemented on the innovaphone Virtual Appliance (IPVA) and the Virtual Machine running IPVA must be hosted on a FT-enabled VMWare Cluster.

===System Requirements===
The VMWare infrastructure must fulfil following requirements to be able to run FT-enabled VMs:
* VMware vSphere Advanced or Enterprise Edition (FT Support included in this editions)
* The CPU and chip-set of the Hosts must support Fault Tolerance.
* The ESXi/vSphere hosts must be equipped with same CPU type and be part of FT-enabled Cluster

===Prepare your VM===
If you want to use FT you need to use the IPVA Version which includes SCSI-Disks, it's not possible to use the "Old" IPVA with IDE-Disks.
To Run the SCSI-IPVA on VMware, you need to do Following steps:
* Download and unzip '''ipva-vmx-scsi.zip'''
* Convert all 4 disks to the VM by using the following command.
<syntaxhighlight lang="bash">
vmkfstools -i /vmfs/volumes/datastore/current-VM-folder/disk.vmdk /vmfs/volumes/datastore/new-VM-folder/disk.vmdk
</syntaxhighlight>
* Now you need to attach the New Disks to your VM:
# You need to detach your old Disks from your IPVA in the settings of your IPVA itself.
# After you removed all the old Disks, you now need to open the Settings of your IPVA itself again and attach the new Disks.
# You need to make sure the Disks are on the correct SCSI controllers
# The Disks need to be on following Positions
## hd.boot.vmdk SCSI-Controller 0 0:0
## hd-cf.vmdk SCSI-Controller 0 0:1
## hd-flash.vmdk SCSI-Controller 1 1:0
## hd-dump.vmdk SCSI-Controller 1 1:1

===Installation===
For detailed implementation of FT-enabled VMWare infrastructure, please refer to the [https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-availability/GUID-7525F8DD-9B8F-4089-B020-BAA4AC6509D2.html VMWare documentation].

On the IPVA side no special settings or changes must be performed to enable FT.

We have tested the FT functionality with following setup and also in our cloud setup:

[[File:FT Test setup.png|ft_test_setup.png/|ft_test_setup.png/]]

While testing the Softphones where in a conference and also calling a WQ. While in an active call, a failure of ESXi/vSphere host was simulated. While testing multiple times, there were some noticeable interruptions in the media stream were realized, while the failover. Even with Video streams there were no problem and everything worked without noticeable problematic behavior.

===Migration===
To Migrate your system, you can download your Config and upload it to a Fault Tolerance Compatible setup.

===Known Problems===
The Fault Tolerance does not protect the system from software failures(e.g. trap of the IPVA).

== Related Articles ==
*[[Reference15r1:Concept Innovaphone Virtual Appliance]]

[[Category:Howto|{{PAGENAME}}]]

Reference15r1:Concept Virtual Background App

2025-02-26T12:51:18Z

Lme: Created page with "{{FIXME|reason=This product is in the beta phase and is not yet finished}} Apps The Virtual Background App is required to use virtual backgrounds in the Softphone, Phone and WebAccess. == Applies to == * Virtual Background App == Requirements == * innovaphone PBX * innovaphone Application Platform * V15r1 == PBX Manager Plugins == === Virtual Background === With the Virtual Background plugin the Virtual Background App Object can be created, edite..."

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
[[Category:Concept|Apps]]

The Virtual Background App is required to use virtual backgrounds in the Softphone, Phone and WebAccess.

== Applies to ==
* Virtual Background App

== Requirements ==
* innovaphone PBX
* innovaphone Application Platform
* V15r1

== PBX Manager Plugins ==
=== Virtual Background ===
With the Virtual Background plugin the Virtual Background App Object can be created, edited and deleted on the PBX.
Furthermore, config templates can be used for distribution to users via the PBX Manager plugin. This affects the availability on Softphone and Phone.
=== Conference ===
In the Conference plugin, the menu item "Virtual Background for WebAccess" appears for conferences. Here you can control the availability in WebAccess. By default, this is automatically enabled once Virtual Background is installed via the Virtual Background plugin.

== More information ==
=== Virtual Background App (innovaphone-virtualbackground) ===
[[File:Virtualbackground.png|50px]]

The hidden app offers an interface via the Service API (com.innovaphone.virtualbackground). If available, the settings options for the virtual background are activated in the respective apps (Softphone, Phone, WebAccess).

Parameters:
;URL: <pre>http://<ap.domain.tld>/<domain.tld>/<instance-name>/innovaphone-virtualbackground</pre>

== Features ==
* Using different filter and effects
** Using a blurred background
** Using a color background
** Using a image background
* Integrated in ...
** Softphone
** Phone
** WebAccess

== Configuration ==
# Download the Virtual Background App via App Store.
# Install the Virtual Background App on the App Platform.
# Create an instance in the Virtual Background App on the App Platform.
# Make sure the Instance is running.
# Create via the PBX Manager Plugin a new Virtual Background App Object and assign the App to authorized users using a config template.

== User interface ==
=== Softphone and Phone ===
The virtual background in Softphone and Phone can be activated via the options. Those menu items are only visible if Virtual Background is installed and configured. The following options are available here:

* Do not use
* Blur background
* Use color background
* Use image background

As soon as a value has been selected, further settings can be changed below the selection (intensity of the blur, color selection, image selection). These affect the image or open a dialog. All options, except the uploaded image, are saved in the local storage. A custom image must be uploaded again when Softphone and Phone is restarted.

<gallery>
Image: VB-Phone.png|Configuration
</gallery>

=== WebAccess ===
The virtual background in WebAccess can be activated via the welcome screen and via the options. Those menu items are only visible if Virtual Background is installed and configured. The following options are available here:
* Do not use
* Blur background
* Use color background
* Use image background

When selecting the color and image background, a corresponding dialog or selection menu opens with which the color or background can be selected. All options, except the uploaded image, are saved in the local storage. A custom image must be uploaded again when WebAccess is restarted.

<gallery type="slider">
Image: VB-WA-Welcome.png|Welcome Screen
Image: VB-WA.png|Configuration
</gallery>

== Restrictions / Known issues ==
* Occasionally errors occur when selecting colors on mobile devices
* Currently, some Firefox's privacy settings may block the use of Virtual Background

== Troubleshooting ==
If any issue can be reproduced, take a screenshot, save the browser logs and send those attached in your support ticket.

== Related Articles ==
Currently no related articles available.

File:VB-WA.png

2025-02-26T12:50:48Z

Lme:

VB-WA

File:VB-WA-Welcome.png

2025-02-26T12:49:34Z

Lme:

VB-WA-Welcome

File:VB-Phone.png

2025-02-26T12:46:44Z

Lme:

VB-Phone

File:Virtualbackground.png

2025-02-26T12:45:28Z

Lme:

icon

Howto15r1:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance

2024-12-05T08:26:06Z

Lme: /* Migration */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
==Applies To==
This information applies to

* IPVA 15r1
* VMWare ESXi (vSphere) 6.7 - 8
* VMWare vCenter Server 6.7 - 8



==More Information==
===Problem Details===
The standby functionality implemented in the innovaphone PBX enables to start PBX software on the standby gateway in fail over scenario. A drawback in this implementation is following - since the standby PBX is running on other physical gateway, all active calls and connections are interrupted while switching from master to standby. The switch to standby hardware takes a while, so the downtime about 2 minutes must be considered additionally.

To be able to implement a PBX with zero downtime on hardware failures, a VMWare [http://www.vmware.com/de/products/vsphere/features/fault-tolerance.html Fault Tolerance(FT)] feature of the VMWare vSphere can be used. Therefore the PBX must be implemented on the innovaphone Virtual Appliance (IPVA) and the Virtual Machine running IPVA must be hosted on a FT-enabled VMWare Cluster.

===System Requirements===
The VMWare infrastructure must fulfil following requirements to be able to run FT-enabled VMs:
* VMware vSphere Advanced or Enterprise Edition (FT Support included in this editions)
* The CPU and chip-set of the Hosts must support Fault Tolerance.
* The ESXi/vSphere hosts must be equipped with same CPU type and be part of FT-enabled Cluster

===Prepare your VM===
If you want to use FT you need to use the IPVA Version which includes SCSI-Disks, it's not possible to use the "Old" IPVA with IDE-Disks.
To Run the SCSI-IPVA on VMware, you need to do Following steps:
* Convert all 4 disks to the VM by using the following command.
<syntaxhighlight lang="bash">
vmkfstools -i /vmfs/volumes/datastore/current-VM-folder/disk.vmdk /vmfs/volumes/datastore/new-VM-folder/disk.vmdk
</syntaxhighlight>
* Now you need to attach the New Disks to your VM:
# You need to detach your old Disks from your IPVA in the settings of your IPVA itself.
# After you removed all the old Disks, you now need to open the Settings of your IPVA itself again and attach the new Disks.
# You need to make sure the Disks are on the correct SCSI controllers
# The Disks need to be on following Positions
## hd.boot.vmdk SCSI-Controller 0 0:0
## hd-cf.vmdk SCSI-Controller 0 0:1
## hd-flash.vmdk SCSI-Controller 1 1:0
## hd-dump.vmdk SCSI-Controller 1 1:1

===Installation===
For detailed implementation of FT-enabled VMWare infrastructure, please refer to the [https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-availability/GUID-7525F8DD-9B8F-4089-B020-BAA4AC6509D2.html VMWare documentation].

On the IPVA side no special settings or changes must be performed to enable FT.

We have tested the FT functionality with following setup and also in our cloud setup:

[[File:FT Test setup.png|FT_Test_Setup.png/|ft_test_setup.png/]]

While testing the Softphones where in a conference and also calling a WQ. While in an active call, a failure of ESXi/vSphere host was simulated. While testing multiple times, there were some noticeable interruptions in the media stream were realized, while the failover. Even with Video streams there were no problem and everything worked without noticeable problematic behavior.

===Migration===
To Migrate your existing System to an FT-System, you need to set up a SCSI-IPVA and Download the Config(NOT download with standard password) from your old IPVA. Upload it to your new SCSI-IPVA. Please make sure you give your new VM the same MAC-Address as the old VM, so there won't be any issues.

===Known Problems===
The Fault Tolerance does not protect the system from software failures(e.g. trap of the IPVA).

== Related Articles ==
*[[Reference15r1:Concept Innovaphone Virtual Appliance]]

[[Category:Howto|{{PAGENAME}}]]

Howto15r1:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance

2024-12-05T08:21:22Z

Lme: /* More Information */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
==Applies To==
This information applies to

* IPVA 15r1
* VMWare ESXi (vSphere) 6.7 - 8
* VMWare vCenter Server 6.7 - 8



==More Information==
===Problem Details===
The standby functionality implemented in the innovaphone PBX enables to start PBX software on the standby gateway in fail over scenario. A drawback in this implementation is following - since the standby PBX is running on other physical gateway, all active calls and connections are interrupted while switching from master to standby. The switch to standby hardware takes a while, so the downtime about 2 minutes must be considered additionally.

To be able to implement a PBX with zero downtime on hardware failures, a VMWare [http://www.vmware.com/de/products/vsphere/features/fault-tolerance.html Fault Tolerance(FT)] feature of the VMWare vSphere can be used. Therefore the PBX must be implemented on the innovaphone Virtual Appliance (IPVA) and the Virtual Machine running IPVA must be hosted on a FT-enabled VMWare Cluster.

===System Requirements===
The VMWare infrastructure must fulfil following requirements to be able to run FT-enabled VMs:
* VMware vSphere Advanced or Enterprise Edition (FT Support included in this editions)
* The CPU and chip-set of the Hosts must support Fault Tolerance.
* The ESXi/vSphere hosts must be equipped with same CPU type and be part of FT-enabled Cluster

===Prepare your VM===
If you want to use FT you need to use the IPVA Version which includes SCSI-Disks, it's not possible to use the "Old" IPVA with IDE-Disks.
To Run the SCSI-IPVA on VMware, you need to do Following steps:
* Convert all 4 disks to the VM by using the following command.
<syntaxhighlight lang="bash">
vmkfstools -i /vmfs/volumes/datastore/current-VM-folder/disk.vmdk /vmfs/volumes/datastore/new-VM-folder/disk.vmdk
</syntaxhighlight>
* Now you need to attach the New Disks to your VM:
# You need to detach your old Disks from your IPVA in the settings of your IPVA itself.
# After you removed all the old Disks, you now need to open the Settings of your IPVA itself again and attach the new Disks.
# You need to make sure the Disks are on the correct SCSI controllers
# The Disks need to be on following Positions
## hd.boot.vmdk SCSI-Controller 0 0:0
## hd-cf.vmdk SCSI-Controller 0 0:1
## hd-flash.vmdk SCSI-Controller 1 1:0
## hd-dump.vmdk SCSI-Controller 1 1:1

===Installation===
For detailed implementation of FT-enabled VMWare infrastructure, please refer to the [https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-availability/GUID-7525F8DD-9B8F-4089-B020-BAA4AC6509D2.html VMWare documentation].

On the IPVA side no special settings or changes must be performed to enable FT.

We have tested the FT functionality with following setup and also in our cloud setup:

[[File:FT Test setup.png|FT_Test_Setup.png/|FT_Test_Setup.png/]]

While testing the Softphones where in a conference and also calling a WQ. While in an active call, a failure of ESXi/vSphere host was simulated. While testing multiple times, there were some noticeable interruptions in the media stream were realized, while the failover. Even with Video streams there were no problem and everything worked without noticeable problematic behavior.

===Migration===
To Migrate your existing System to an FT-System, you need to set up a SCSI-IPVA and Download the Config(NOT download with standard password) from your old IPVA. Upload it to your new SCSI-IPVA.

===Known Problems===
The Fault Tolerance does not protect the system from software failures(e.g. trap of the IPVA).

== Related Articles ==
*[[Reference15r1:Concept Innovaphone Virtual Appliance]]

[[Category:Howto|{{PAGENAME}}]]

Howto15r1:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance

2024-12-04T08:51:18Z

Lme: /* Installation */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
==Applies To==
This information applies to

* IPVA 15r1
* VMWare ESXi (vSphere) 6.7 - 8
* VMWare vCenter Server 6.7 - 8



==More Information==
===Problem Details===
The standby functionality implemented in the innovaphone PBX enables to start PBX software on the standby gateway in fail over scenario. A drawback in this implementation is following - since the standby PBX is running on other physical gateway, all active calls and connections are interrupted while switching from master to standby. The switch to standby hardware takes a while, so the downtime about 2 minutes must be considered additionally.

To be able to implement a PBX with zero downtime on hardware failures, a VMWare [http://www.vmware.com/de/products/vsphere/features/fault-tolerance.html Fault Tolerance(FT)] feature of the VMWare vSphere can be used. Therefore the PBX must be implemented on the innovaphone Virtual Appliance (IPVA) and the Virtual Machine running IPVA must be hosted on a FT-enabled VMWare Cluster.

===System Requirements===
The VMWare infrastructure must fulfil following requirements to be able to run FT-enabled VMs:
* VMware vSphere Advanced or Enterprise Edition (FT Support included in this editions)
* The CPU and chip-set of the Hosts must support Fault Tolerance.
* The ESXi/vSphere hosts must be equipped with same CPU type and be part of FT-enabled Cluster

===Prepare your VM===
If you want to use FT you need to use the IPVA Version which includes SCSI-Disks, it's not possible to use the "Old" IPVA with IDE-Disks.
To Run the SCSI-IPVA on VMware, you need to do Following steps:
* Convert all 4 disks to the VM by using the following command.
<syntaxhighlight lang="bash">
vmkfstools -i /vmfs/volumes/datastore/current-VM-folder/disk.vmdk /vmfs/volumes/datastore/new-VM-folder/disk.vmdk
</syntaxhighlight>
* Now you need to attach the New Disks to your VM:
# You need to detach your old Disks from your IPVA in the settings of your IPVA itself.
# After you removed all the old Disks, you now need to open the Settings of your IPVA itself again and attach the new Disks.
# You need to make sure the Disks are on the correct SCSI controllers
# The Disks need to be on following Positions
## hd.boot.vmdk SCSI-Controller 0 0:0
## hd-cf.vmdk SCSI-Controller 0 0:1
## hd-flash.vmdk SCSI-Controller 1 1:0
## hd-dump.vmdk SCSI-Controller 1 1:1

===Installation===
For detailed implementation of FT-enabled VMWare infrastructure, please refer to the [https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-availability/GUID-7525F8DD-9B8F-4089-B020-BAA4AC6509D2.html VMWare documentation].

On the IPVA side no special settings or changes must be performed to enable FT.

We have tested the FT functionality with following setup and also in our cloud setup:

[[File:FT Test setup.png|FT_Test_Setup.png/|FT_Test_Setup.png/]]

While testing the Softphones where in a conference and also calling a WQ. While in an active call, a failure of ESXi/vSphere host was simulated. While testing multiple times, there were some noticeable interruptions in the media stream were realized, while the failover. Even with Video streams there were no problem and everything worked without noticeable problematic behavior.

===Known Problems===
The Fault Tolerance does not protect the system from software failures(e.g. trap of the IPVA).

== Related Articles ==
*[[Reference15r1:Concept Innovaphone Virtual Appliance]]

[[Category:Howto|{{PAGENAME}}]]

Howto15r1:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance

2024-12-04T08:05:31Z

Lme: /* Installation */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
==Applies To==
This information applies to

* IPVA 15r1
* VMWare ESXi (vSphere) 6.7 - 8
* VMWare vCenter Server 6.7 - 8



==More Information==
===Problem Details===
The standby functionality implemented in the innovaphone PBX enables to start PBX software on the standby gateway in fail over scenario. A drawback in this implementation is following - since the standby PBX is running on other physical gateway, all active calls and connections are interrupted while switching from master to standby. The switch to standby hardware takes a while, so the downtime about 2 minutes must be considered additionally.

To be able to implement a PBX with zero downtime on hardware failures, a VMWare [http://www.vmware.com/de/products/vsphere/features/fault-tolerance.html Fault Tolerance(FT)] feature of the VMWare vSphere can be used. Therefore the PBX must be implemented on the innovaphone Virtual Appliance (IPVA) and the Virtual Machine running IPVA must be hosted on a FT-enabled VMWare Cluster.

===System Requirements===
The VMWare infrastructure must fulfil following requirements to be able to run FT-enabled VMs:
* VMware vSphere Advanced or Enterprise Edition (FT Support included in this editions)
* The CPU and chip-set of the Hosts must support Fault Tolerance.
* The ESXi/vSphere hosts must be equipped with same CPU type and be part of FT-enabled Cluster

===Prepare your VM===
If you want to use FT you need to use the IPVA Version which includes SCSI-Disks, it's not possible to use the "Old" IPVA with IDE-Disks.
To Run the SCSI-IPVA on VMware, you need to do Following steps:
* Convert all 4 disks to the VM by using the following command.
<syntaxhighlight lang="bash">
vmkfstools -i /vmfs/volumes/datastore/current-VM-folder/disk.vmdk /vmfs/volumes/datastore/new-VM-folder/disk.vmdk
</syntaxhighlight>
* Now you need to attach the New Disks to your VM:
# You need to detach your old Disks from your IPVA in the settings of your IPVA itself.
# After you removed all the old Disks, you now need to open the Settings of your IPVA itself again and attach the new Disks.
# You need to make sure the Disks are on the correct SCSI controllers
# The Disks need to be on following Positions
## hd.boot.vmdk SCSI-Controller 0 0:0
## hd-cf.vmdk SCSI-Controller 0 0:1
## hd-flash.vmdk SCSI-Controller 1 1:0
## hd-dump.vmdk SCSI-Controller 1 1:1

===Installation===
For detailed implementation of FT-enabled VMWare infrastructure, please refer to the VMWare documentation.

On the IPVA side no special settings or changes must be performed to enable FT.

We have tested the FT functionality with following setup and also in our cloud setup:

[[File:FT Test setup.png|FT_Test_Setup.png/|FT_Test_Setup.png/]]

While testing the Softphones where in a conference and also calling a WQ. While in an active call, a failure of ESXi/vSphere host was simulated. While testing multiple times, there were some noticeable interruptions in the media stream were realized, while the failover. Even with Video streams there were no problem and everything worked without noticeable problematic behavior.

===Known Problems===
The Fault Tolerance does not protect the system from software failures(e.g. trap of the IPVA).

== Related Articles ==
*[[Reference15r1:Concept Innovaphone Virtual Appliance]]

[[Category:Howto|{{PAGENAME}}]]

Howto15r1:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance

2024-12-04T08:00:54Z

Lme: /* Installation */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
==Applies To==
This information applies to

* IPVA 15r1
* VMWare ESXi (vSphere) 6.7 - 8
* VMWare vCenter Server 6.7 - 8



==More Information==
===Problem Details===
The standby functionality implemented in the innovaphone PBX enables to start PBX software on the standby gateway in fail over scenario. A drawback in this implementation is following - since the standby PBX is running on other physical gateway, all active calls and connections are interrupted while switching from master to standby. The switch to standby hardware takes a while, so the downtime about 2 minutes must be considered additionally.

To be able to implement a PBX with zero downtime on hardware failures, a VMWare [http://www.vmware.com/de/products/vsphere/features/fault-tolerance.html Fault Tolerance(FT)] feature of the VMWare vSphere can be used. Therefore the PBX must be implemented on the innovaphone Virtual Appliance (IPVA) and the Virtual Machine running IPVA must be hosted on a FT-enabled VMWare Cluster.

===System Requirements===
The VMWare infrastructure must fulfil following requirements to be able to run FT-enabled VMs:
* VMware vSphere Advanced or Enterprise Edition (FT Support included in this editions)
* The CPU and chip-set of the Hosts must support Fault Tolerance.
* The ESXi/vSphere hosts must be equipped with same CPU type and be part of FT-enabled Cluster

===Prepare your VM===
If you want to use FT you need to use the IPVA Version which includes SCSI-Disks, it's not possible to use the "Old" IPVA with IDE-Disks.
To Run the SCSI-IPVA on VMware, you need to do Following steps:
* Convert all 4 disks to the VM by using the following command.
<syntaxhighlight lang="bash">
vmkfstools -i /vmfs/volumes/datastore/current-VM-folder/disk.vmdk /vmfs/volumes/datastore/new-VM-folder/disk.vmdk
</syntaxhighlight>
* Now you need to attach the New Disks to your VM:
# You need to detach your old Disks from your IPVA in the settings of your IPVA itself.
# After you removed all the old Disks, you now need to open the Settings of your IPVA itself again and attach the new Disks.
# You need to make sure the Disks are on the correct SCSI controllers
# The Disks need to be on following Positions
## hd.boot.vmdk SCSI-Controller 0 0:0
## hd-cf.vmdk SCSI-Controller 0 0:1
## hd-flash.vmdk SCSI-Controller 1 1:0
## hd-dump.vmdk SCSI-Controller 1 1:1

===Installation===
For detailed implementation of FT-enabled VMWare infrastructure, please refer to the VMWare documentation.

On the IPVA side no special settings or changes must be performed to enable FT.

We have tested the FT functionality with following setup and also in our cloud setup:

[[File:FT Test setup.png|thumb]]

While testing the Softphones where in a conference and also calling a WQ. While in an active call, a failure of ESXi/vSphere host was simulated. While testing multiple times, there were some noticeable interruptions in the media stream were realized, while the failover. Even with Video streams there were no problem and everything worked without noticeable problematic behavior.

===Known Problems===
The Fault Tolerance does not protect the system from software failures(e.g. trap of the IPVA).

== Related Articles ==
*[[Reference15r1:Concept Innovaphone Virtual Appliance]]

[[Category:Howto|{{PAGENAME}}]]

File:FT Test setup.png

2024-12-04T07:55:53Z

Lme:

Test Setup mit welchem FT test durchgeführt wurden

Howto15r1:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance

2024-12-03T09:03:11Z

Lme: /* More Information */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
==Applies To==
This information applies to

* IPVA 15r1
* VMWare ESXi (vSphere) 6.7 - 8
* VMWare vCenter Server 6.7 - 8



==More Information==
===Problem Details===
The standby functionality implemented in the innovaphone PBX enables to start PBX software on the standby gateway in fail over scenario. A drawback in this implementation is following - since the standby PBX is running on other physical gateway, all active calls and connections are interrupted while switching from master to standby. The switch to standby hardware takes a while, so the downtime about 2 minutes must be considered additionally.

To be able to implement a PBX with zero downtime on hardware failures, a VMWare [http://www.vmware.com/de/products/vsphere/features/fault-tolerance.html Fault Tolerance(FT)] feature of the VMWare vSphere can be used. Therefore the PBX must be implemented on the innovaphone Virtual Appliance (IPVA) and the Virtual Machine running IPVA must be hosted on a FT-enabled VMWare Cluster.

===System Requirements===
The VMWare infrastructure must fulfil following requirements to be able to run FT-enabled VMs:
* VMware vSphere Advanced or Enterprise Edition (FT Support included in this editions)
* The CPU and chip-set of the Hosts must support Fault Tolerance.
* The ESXi/vSphere hosts must be equipped with same CPU type and be part of FT-enabled Cluster

===Prepare your VM===
If you want to use FT you need to use the IPVA Version which includes SCSI-Disks, it's not possible to use the "Old" IPVA with IDE-Disks.
To Run the SCSI-IPVA on VMware, you need to do Following steps:
* Convert all 4 disks to the VM by using the following command.
<syntaxhighlight lang="bash">
vmkfstools -i /vmfs/volumes/datastore/current-VM-folder/disk.vmdk /vmfs/volumes/datastore/new-VM-folder/disk.vmdk
</syntaxhighlight>
* Now you need to attach the New Disks to your VM:
# You need to detach your old Disks from your IPVA in the settings of your IPVA itself.
# After you removed all the old Disks, you now need to open the Settings of your IPVA itself again and attach the new Disks.
# You need to make sure the Disks are on the correct SCSI controllers
# The Disks need to be on following Positions
## hd.boot.vmdk SCSI-Controller 0 0:0
## hd-cf.vmdk SCSI-Controller 0 0:1
## hd-flash.vmdk SCSI-Controller 1 1:0
## hd-dump.vmdk SCSI-Controller 1 1:1

===Installation===
For detailed implementation of FT-enabled VMWare infrastructure, please refer to the VMWare documentation.

On the IPVA side no special settings or changes must be performed to enable FT.

We have tested the FT functionality with following setup:

[[Image:Vmware ft test setup.png|vmware_ft_test_setup.png/|vmware_ft_test_setup.png/]]

While testing a call between the IP-Phones was established. The media stream was routed via PBX("RTP Proxy" enabled on PBX/General page). While in an active call, a failure of ESXi/vSphere host was simulated. Two short (1 second) noticeable interruptions in the media stream were realized, while the failover. In case with media stream between the phones (no media relay), no interruption is possible to hear.

===Known Problems===
The Fault Tolerance does not protect the system from software failures(e.g. trap of the IPVA).

== Related Articles ==
*[[Reference15r1:Concept Innovaphone Virtual Appliance]]

[[Category:Howto|{{PAGENAME}}]]

Reference14r2:Concept App Service TechAssist

2024-11-19T12:18:05Z

Lme: /* get_pbx_objects_from_config(string config) : array */

[[Category:Concept|Apps]]
[[Category:Concept App Service TechAssist]]

== Applies To ==

* innovaphone PBX from version 13r2

== Overview ==
The idea of the TechAssist app is to provide helpful tools for technicians, as well as to analyze static and runtime information of a system and check for problems and improvements. In this way, the app can help you find and solve problems and misconfigurations independently and quickly.
For this purpose, the app supports
* the execution of ''tests''
** a bunch of manufacturer tests are supplied with the app
** you can create and save your own tests
** testresults can be downloaded to attach them to a support ticket
* a PBX license overview

== Licensing ==
There are no licenses needed for this app

== Installation ==
The TechAssist App is installed by default for every new installation and is accessible from the Config Admin template.

=== With the PBX manager AP app installer plug-in ===
[[File:Ap_app_installer.png]]

Go to the PBX manager and open the '''"AP app installer"''' plugin. On the right panel, the App Store will be shown. ''Hint : if you access it for the first time, you will need to accept the "Terms of Use of the innovaphone App Store"''
* In the search field located on the top right corner of the store, search for '''"Techassist"''' and click on it
* Select the proper firmware version, here '''"v14"''' and click on install
* Tick "I accept the terms of use" and continue by clicking on the install yellow button
* Wait until the install has been finished
* Close and open the PBX manager to refresh the list of the available colored AP plugin
* Click on the '''"AP techassist"''' and click on '''" + Add an App"'''
* Enter a '''"Name"''' that is used as display name ''(all character allowed)'' for it and the '''"SIP"''' name that is the administrative field ''(no space, no capital letters)''. ''e.g : Name: TechAssist, SIP: techassist''
''Hint : The App needs access-right to one devices-api. The access to "devices-api" will be set automatically. If you want to have another devices-apis working with techassist, you have to configure it manually in the advanced UI.''
* Tick the appropriate template to distribute the App
* Click OK to save the settings and a green check mark will be shown to inform you that the configuration is good

== Test Engine - Overview ==
=== Technical look inside ===
[[File:Concept_TechAssist.png|thumb|upright=1.0|right|Technical Overview]]
The app service receives multiple incoming websocket connections of the app objects from the PBXes. By assigning rights to a to your desired "devices-apis" (in the Apps tab), the app service receives the corresponding rights to connect to the respectively activated DevicesApps. All managed domains and devices can then be read in via this connection. (One TechAssist can only connect with one device-api)
With this procedure, you can work with one DevicesApp instance and across all domains and devices in it.

=== Submodules ===
The app contains various sub-modules in order to be able to carry out the tests provided by the manufacturer and also to be able to integrate custom tests created by yourself.

;scheduler
: The scheduler initially loads all tests and performs a plausibility check of the individual tests. From this status onwards, the scheduler ensures that all tests are executed in the required time intervals.
: Inside the Scheduler the tick is 5000 milliseconds, and test are executed sequentially to prevent high system load
;cmd
: The cmd submodule (derived from "command") can communicate with devices in the installation to query a status, the config or similar. The submodule takes care of all the information that tests from an installation want to have, consolidates them so that queries do not have to be executed multiple times and caches the results.
;test
: The test submodule is instantiated per test and provides all necessary functionalities within a test.

=== Language ===
By design, only the app itself is available in multiple languages. The content of the tests and technical output is intentionally only available in english.

=== Tests ===
The app contains a bunch of embedded test, but it is also possible to create and save your own tests.

== UI ==
=== Expert Mode ===
By default there are some expert information hidden in the left menu bar. You will find a switch for that in the left menu (non-mobile-view) to enable all menu items.

=== Dealing with the Code Editor ===
The Code Editor is a tool for viewing the tests supplied and writing your own tests based on these tests.

The editor is divided into 3 basic areas.
;Left - Code Editor
:This is the code editor where you can write your test code in the browser. When you close the app, the content in the editor is saved, so that the next time you open the app you will find your old code again.

;Top right - Menu bar
:Here you will find the following functions:
:Selection of all existing Tests (predefined vendor Tests and your own custom Tests)
:Load the source code of the selected Test to the code editor
:Delete the selected test from the app (This is only possible for custom tests)
:Execute the source code (with or without cached commands in the service) in the Code Editor and show the result
:Clear the Code Editor
:Save the current Content from the code Editor as Test
::The title of your test is divided from the ''title'' property in your test (lower based without non-alphanumeric characters). This means: If you save another Test with the same ''title'' the value will be saved in the other test.

;Top right - Results
:If you execute, save or delete a test you will get the response/results in this area

== Create your own Testscript ==
You can create your own Test scripts in a JavaScript based environment.
A test itself is a JavaScript object with some configurations properties and a section of ''freestyle'' code to use JavaScript habits to perform your test. If your test will be executed, an above layer will call your ''test()'' method and want to have a return object with your result.

There already exists a global Object called '''tests_add'''. You can add your own Test as Property to this existing Object like:
<syntaxhighlight lang="javascript">
tests_add.my_new_test = tests_add.my_new_test || {
title: 'Check for xyz',
// configuration properties

test: function (cmd, result) {
// your custom test code

return {
success: false,
msg: '....'
};
}
}
</syntaxhighlight>

The way to add a test with <code>tests_add.my_new_test = tests_add.my_new_test || {}</code> is important so that two tests do not overwrite each other. Please also pay attention to this. In this example, we have a ''logical condition'' in the first line. If the test ''my_new_test'' already exists in the object ''tests_add'' the left side from the ''OR-condition'' is ''true'', and the existing test takes place. Otherwise, it is ''false'' and the right side (your new test object) will be written to ''tests_add.my_new_test''.

=== Configuration Properties ===
You must configure certain properties in your test so that the scheduler knows exactly how to handle your test.

Example:
<syntaxhighlight lang="javascript">
tests_add.my_new_test = tests_add.my_new_test || {
title: 'Unknown / New devices',
description: 'Check for unassigned devices in your installation',
todo: 'Please check the unknown devices in your installation and acceppt or delete the devices',
author: 'slu@innovaphone.com',
enabled: true,
schedule: '1h',
commands: { ... },

test: function (cmd, result) {
// your custom test code
}
}
</syntaxhighlight>

==== Mandatory properties ====

; title
: string | The title of your test, which is displayed in the UI
; description
: string | A short description of your test, which is displayed in the UI
; todo
: string | An instruction on what the user has to do if the check fails. It will be displayed above the logfile in failed tests. (You can use ''\r\n'' for line breaks)
: Variable <nowiki>{{VERSION}}</nowiki> will be replaced to current Version of the app like "14r1"
; author
: string | The contact of the person who create the test
; schedule
: string | The time interval during which the test is to be carried out independently. The format is composed of a numerical value and interval value. This allows you to create combinations such as <code>5m (every 5 minutes), 10h (every 10 hours) or 1d (every day) </code>. A special case which is also allowed is the value ''none''. With a ''none'' value, your test will not be executed automatically, but is available in the app. So the user is able to execute your test manually.
: Possible interval values are:
: <code>s</code> (seconds)
: <code>m</code> (minutes)
: <code>h</code> (hours)
: <code>d</code> (days)
: <code>w</code> (weeks)
: Please note that each execution of a test requires resources. For example, if you create a test with ''1m'' that is executed every minute, you may well create an unpleasant impact! The system automatically checks the execution time of your test against your specified interval. If your test runs for a longer time than your schedule, your ''schedule'' parameter is automatically doubled by the system.
: Please note the [[#Submodules|Submodule Scheduler]] with Tick and synchronous execution. For example, it is not possible to execute a test every second.

==== Optional properties ====

; commands
: object | An object in which you can list all the commands, values, etc. that you want to use later in your test. As soon as your test() method is called, the returns of these commands are passed in as parameters so that you can analyze them. For detailed documentation, please see the [[#Property_.22commands.22|commands-documentation]] below.
; minBuild
: int | The minimum build version of the app, that the Test will be executed.
; enabled
: bool | If ''false'' the test will be loaded but not executed. The user will see the test in the list of test, and it is possible to enable it (default: ''true'')
; hidden
: bool | If ''true'' the test will be skipped by the system and will not be loaded (default: ''false'')

=== Property "commands" ===
The property ''commands'' is an object where you can define innovaphone specific commands that are executed before your test will be executed. The results of the given commands will be passed to your test in the parameter ''results''. Think about that, all your commands will be cached until the ''schedule'' timeout is exceeded. This means that you will only get a new result of the command after the schedule time has elapsed in relation to the time of your last execution. The only exceptions is when the user manually re-executes a test via the UI or caching has been explicitly disabled at the command

You have to consider a special nested notation when creating your commands, so that you can use them later.

==== outer commands-object ====
Let's start with some first basic rules:
* ''commands'' is an object with one property per command. At this moment we only list commands, we don't take care about specific devices, types of models or so on.
* Every child-property (let's call it "command-object") is a new object which contains all needed information for this specific command
* The title of the property "command-object" is defined by yourself
** Spoiler: The title of your "command-object" should be used later if you want to read the result for a specific device
* You can list multiple "command-objects"

Up to here we have the following and can define it like this:
<syntaxhighlight lang="javascript">
commands: {
my_command_one: {},
my_command_two: {},
},
</syntaxhighlight>

==== single command-object ====

Then we have some new rules per "command-object":
* A property called ''cmd'' is expected. This property contains the real command which shall be executed (Remember, at this moment we only list commands, we don't take care about specific devices, types of models or so on)
** Example 1: <code>cmd: 'CMD0/box_info.xml'</code> will give you the xml output of the general overview page
** Example 2: <code>cmd: '!mod cmd CDR0 qs'</code> will give you the amount of buffered CDRs in the CDR0 interface
** Example 3: <code>cmd: 'cfg.txt'</code> will give you back the full configuration file
** If you are already firm with the innovaphone based command syntax, you will see that you can use any HTTP command which can be sent to an innovaphone device
* Some more properties can be defined optionally. See documentation below

Up to here we have an idea of a specific "command-object" and can do the following now:
<syntaxhighlight lang="javascript">
commands: {
buffered_cdr0: {
cmd: '!mod cmd CDR0 qs',
},
buffered_cdr1: {
cmd: '!mod cmd CDR1 qs',
},
},
</syntaxhighlight>

With this command, we can collect the "buffered CDRs" on both CDR Interfaces in our boxes. Maybe you see it directly... This will not make really sense in a real setup because CDRs only generated by Gateways/PBXes. So we don't need to bother phones with these requests.
So from now on we take care about our defined command. There are optional parameters that we can also list inside a "command-object" to let the system know what is the to-do with this command.

;cmd
: string | Any HTTP command you can send to an innovaphone device. There is a limit of 15 seconds for every http request. If your request exceeds this limit the request will be cancelled.
;cat
: array | An optional list of device types on which the command is to be executed. If ''cat'' is empty, it means all devices in your installation.
: You can define the following device categories:
: <code>pbx</code> - all PBXes
: <code>gw</code> - all Gateways
: <code>ap</code> - all App Platforms
: <code>dect</code> - all Dect Gateways
: <code>phone</code> - all Phones
;cache
: bool | If you set it to ''false'' you will never get a cached value. Please use this option wisely and only if you really need it. (default: ''true'')

Now let's improve our example from above and get the bufferd CDRx information only from pbxes and gateways.

<syntaxhighlight lang="javascript">
commands: {
buffered_cdr0: {
cmd: '!mod cmd CDR0 qs',
cat: ['pbx', 'gw'],
},
buffered_cdr1: {
cmd: '!mod cmd CDR1 qs',
cat: ['pbx', 'gw'],
},
},
</syntaxhighlight>

==== execution and results of commands ====
Up to now, we have only defined commands that are to be executed on certain devices. When your test is executed, the previously defined commands are executed and the system collects the returns in a corresponding object (called <code>results</code>) which is passed into your <code>test(cmd, results)</code> method. There you can access the results and do whatever you want to test/analyze or whatever with the return value. You will find an example and some sample-code how to use the results-object in the description of the ''test() method.''

==== nested commands-objects ====
You can now send any commands and the results will be returned to you for evaluation.
As you may have already noticed, there is no possibility to place multiple commands in dependency. But this is the way to do this.

For more complicated tests, it is necessary to execute several commands one after the other and to generate following commands dynamically on the basis of the result of the first command.

For such tests, there is the possibility to specify an object "commands" within a "command-object". From this level, you can define a dynamic function in which you can apply your own code based on the first result, and then return a new ''commands-object''. In this return statement, you also have the option of returning another dynamic function in order to be able to create processes of any complexity. Please note that if you not return an ''object'' your return value will be discarded. The results of your nested ''command-objects'' will be passed to the ''test()'' method inside the ''results'' object.

This is certainly not easy to understand. Therefore, let us take a closer look at it with an example.

===== example: nested commands-object which generates the second command from the first result =====
<syntaxhighlight lang="javascript">
commands: {
certificates: {
cmd: 'X509/mod_cmd.xml',
cat: ['pbx', 'gw', 'dect'],
commands: function(cmd, result) {
// free style code to build the following commands
var xml = cmd.parse_xml(result);
//log(JSON.stringify(xml));

var fingerprint;
// get the fingerprint for single cert
if (typeof xml.info.servercert.certificate['@fingerprint'] !== 'undefined') {
fingerprint = xml.info.servercert.certificate['@fingerprint']
}
// use last certificates in case of multiple
else {
fingerprint = xml.info.servercert.certificate[xml.info.servercert.certificate.length - 1]['@fingerprint'];
}
cmd.log('Fingerprint: '+fingerprint);

return {
certificate: {
cmd: 'X509/mod_cmd.xml?cmd=servercert-details&fingerprint='+fingerprint,
}
}
}
}
},
</syntaxhighlight>

Our goal is to check which key-length is used in the device certificate. But there i no direct command to get this information. So we have to do it in multipe steps.

In this sample, we request the following in the commands object:
# Execute our command "certificates" on devices (pbx, gw, dect) the command "X509/mod_cmd.xml" which will give you back the xml payload of the page [[{{NAMESPACE}}:General/Certificates]]
# If the first request is done, the nested "commands" object should be called and we get the result from the first command
## Now, inside the function <code>commands: function(cmd, result) {</code> we can use some free-style code to to what we need, to build a following command
## Here we convert xml to an object and extract the certificate fingerprint from the result of the first request
## then we return an object with "command-objects"
### think about that is possible to add an new <code>commands: function(cmd, result) {</code> inside the return to add a new level :-)
## this second command will be executed to for every device and the xml payload contains the device certifcate of the current device. (like the popup in the UI if you click on a specific certificate)
#If all nested commands are processed, then your test() will be called, and you get all the results (in this case "certificates" and "certificate") in the results-object

===== example: nested commands-object which generates various commands from the first result =====
<syntaxhighlight lang="javascript">
commands: {
config: {
cmd: 'cfg.txt',
cat: ['pbx'],
commands: function(cmd, result) {
var lines = result.split("\r\n");
var output = {};

// get pbx loc
var loc = false;
for (var l = 0; l < lines.length; l++) {
if (!lines[l].startsWith('config change PBX0')) continue; // skip non pbx line
if (lines[l].includes('/mode standby')) continue; // skip slave pbxes

var match = lines[l].match(/config change PBX0 (.*) \/loc ([^ ][^/]+)/);
loc = match[2].substr(0, match[2].length-1);
l = lines.length;
}
cmd.log('use pbx loc: '+loc);

// get user objects
var regex = new RegExp('/$loc='+loc+'$(.*)$guid;bin=([0-9A-Za-z]+)$/');
for (var l = 0; l < lines.length; l++) {
// skip if user is not from this pbx
if (!lines[l].includes('(loc='+loc+')')) continue;

var match = lines[l].match(/$guid;bin=([0-9A-Za-z]+)$/);
if (!match) continue;
cmd.log('user found: '+match[1]);
output[match[1]] = {cmd: 'PBX0/ADMIN/mod_cmd_login.xml?cmd=show&user-guid='+match[1]};
}

return output;
}
},
},
</syntaxhighlight>

Our goal is to get the xml output from the advanced ui for every pbx object. But there i no direct command to get this information. So we have to do it in multipe steps.

In this sample, we request the following in the commands object:
# Execute our command "config" on PBXes the get the plain configuration file
# If the first request is done, the nested "commands" object should be called, and we get the result from the first command
## Now, inside the function <code>commands: function(cmd, result) {</code> we can use some free-style code to do what we need, to build multiple following commands

## Here we split the config file by lines breaks and iterate the whole config
## then we generate an empty return object to fill it later
### think about that is possible to add an new <code>commands: function(cmd, result) {</code> inside the return to add a new level :-)
## If we have checked the pbx and the userobject we add with <code>output[match[1]] = {cmd: 'PBX0/ADMIN/mod_cmd_login.xml?cmd=show&user-guid='+match[1]};</code> a specific command to the retunr value

In the end, we have a big return object with multiple cmd's
In this case we will get all the results in the test() later and can do further stuff with the results.

=== Executable method test() ===
The upper layer expects a method <code>test(cmd, results)</code> in your JavaScript object. This method has two parameters.

;cmd
:An object that offers you a wide range of predefined functions and options. You can see it as a kind of library, which is documented at the [[#cmd object|cmd object]].

;results
:An object of the results of your commands from the given ''command-objects'' in your test definition.
<spoiler show="show sample strcuture of the results object" hide="hide sample strcuture of the results object">
<syntaxhighlight lang="javascript">
// structure of results object
{
// your command is the property
'buffered_cdr0' : {
// the unique id of the device is the property
'1': 'QS messages: 0 max 2000 chars: 0 max 300000',
'4': 'QS messages: 0 max 2000 chars: 0 max 300000',
},
'buffered_cdr1' : {
// the unique id of the device is the property
'1': 'QS messages: 0 max 2000 chars: 0 max 300000',
'4': 'QS messages: 0 max 2000 chars: 0 max 300000',
}
}
</syntaxhighlight>
</spoiler>
 
<spoiler show="show best practice code to deal with the results object" hide="hide best practice code to deal with the results object">
<syntaxhighlight lang="javascript">
// you can use this inside your function "test: function (cmd, results)" to iterate all commands over all affected devices

Object.keys(results).forEach(function(command) {
log.push('command: '+command);
Object.keys(results[command]).forEach(function(device) {
log.push('device: '+device);
var output = results[command][device];
});
});

// expected log array from the code above:
// $ command: buffered_cdr0
// $ device: 1
// $ device: 4
// $ command: buffered_cdr1
// $ device: 1
// $ device: 4
</syntaxhighlight>
</spoiler>
==== return test result ====
Your test has to be return an object with your test result. The system expect an object with the following properties.

; success
: boolean | indicates if your test was successful or not
; msg
: string | an optional short message that will be displayed in the UI as preview
; log
: array | an optional array with lines of logfile that you can use to display detailed information in the UI at your test result. Use <code>log.push()</code> to fill up the logfile array. In the frontend, the log will be parsed and mac addresses <code>/(^|\W)([a-f0-9]{12})(\W|$)/i</code> will be updated with an internal link to devices app. (If you want to create instead debug output to the app-instance logfile you can use <code>cmd.log()</code>)
<syntaxhighlight lang="javascript">
test: function (cmd, results) {
// your stuff
var count = 2;

return {
success: false,
msg: 'There are '+count+' new/unassigned devices in your setup'
};
}
</syntaxhighlight>

=== The full picture ===
==== Complete sample test to check buffered CDRs ====
<syntaxhighlight lang="javascript">
tests_add.cdrs_buffered = tests_add.cdrs_buffered || {
title: 'Buffered CDRs',
description: 'This test will check if CDRs on a gateway was buffered and are not transmit to the CDR target yet',
todo: 'Check the CDR target',
author: 'slu@innovaphone.com',
enabled: true,
schedule: '10m',

commands: {
cdr0: {
cmd: '!mod cmd CDR0 qs',
cat: ['gw'],
},
cdr1: {
cmd: '!mod cmd CDR1 qs',
cat: ['gw'],
},
cdr2: {
cmd: '!mod cmd CDR2 qs',
cat: ['gw'],
},
cdr3: {
cmd: '!mod cmd CDR3 qs',
cat: ['gw'],
},
cdr4: {
cmd: '!mod cmd CDR4 qs',
cat: ['gw'],
},
},

test: function (cmd, results) {
var log = [];
var success = true;

for (var n = 0; n < 5; n++) {
Object.keys(results['cdr'+n]).forEach(function(i){
var check = calculate_cdrs(results['cdr'+n][i]);
// result was not good, lets create a human error message
if (check !== true) {
log.push(cmd.get_device(i).product+' / '+cmd.get_device(i).hwId+' / '+check+'% - '+results['cdr'+n][i]);
if (success) success = false;
}
});
}

return {
success: success,
msg: success ? '' : 'Devices with buffered CDRs exists',
log: log
};

function calculate_cdrs(str) {
// QS messages: 0 max 2000 chars: 0 max 300000
var check = 0;
str = str.split(' ');
// log.push(str);

var messages_current = str[2];
var messages_max = str[4];
var chars_current = str[6];
var chars_max = str[8];

// check messages
check = cmd.percent(messages_current, messages_max);
if (check >= 30) return check;

// check chars
check = cmd.percent(chars_current, chars_max);
if (check >= 30) return check;

return true;
}
}
}
</syntaxhighlight>

==== Complete sample test to check firmware versions ====
<syntaxhighlight lang="javascript">
tests_add.firmware_version = tests_add.firmware_version || {
title: 'Supported firmware versions',
description: 'Check if you have unsupported firmware version in use',
todo: 'Update the firmware on affected devices',
author: 'slu@innovaphone.com',
schedule: '1d',
commands: {
box_info: {
cmd: 'CMD0/box_info.xml',
},
},

test: function (cmd, results) {
var log = [];
var success = true;
var msg = '';

Object.keys(results.box_info).forEach(function(i){
var xml = cmd.parse_xml(results.box_info[i]);
if (typeof xml.info === 'undefined') return;
if (typeof xml.info.sys === 'undefined') return;
if (typeof xml.info.sys['@version'] === 'undefined') return;

if (
xml.info.sys['@version'].includes('6.00') ||
xml.info.sys['@version'].includes('7.00') ||
xml.info.sys['@version'].includes('8.00') ||
xml.info.sys['@version'].includes('9.00') ||
xml.info.sys['@version'].includes('10.00') ||
xml.info.sys['@version'].includes('11.00') ||
xml.info.sys['@version'].includes('11r1') ||
xml.info.sys['@version'].includes('12r1') ||
xml.info.sys['@version'].includes('13r1')
) {
log.push(cmd.get_device(i).product+' / '+cmd.get_device(i).hwId+' / '+xml.info.sys['@version']);
if (success) success = false;
}
});

return {
success: success,
msg: success ? '' : 'You use old firmware which is no longer be supported',
log: log
};
}
}
</syntaxhighlight>

=== cmd object ===
The '''cmd''' object provides you the following methods:

==== get device information / system information ====

===== get_domains() : object =====
You will receive all existing domains

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var domains = cmd.get_domains();
console.log(domains);
{
"1": {
"id": 1,
"name": "slu.de",
"deployAdminPasswords": true,
"isInstanceDomain": true,
"categories": [ ... ]
}
}
</syntaxhighlight>
</spoiler>

===== get_devices() : object =====
You will receive all existing devices

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var devices = cmd.get_devices();
console.log(devices);
{
"0_009033420623": {
"id": "0_009033420623",
"hwId": "009033420623",
"domainId": 0,
"product": "IP0011",
"version": "13r3 dvl [13.7526/132035/600]",
"type": "GW",
"pbxActive": false,
"online": true,
"ethIfs": [ ... ]
},
"1": {
"id": 1,
"hwId": "009033420621",
"name": "PBX - pbx.slu.de",
"domainId": 1,
"product": "IP0011",
"version": "13r3 beta4 [13.7688/137623/600]",
"type": "GW",
"pbxActive": true,
"online": true,
"ethIfs": [ ... ]
},
"2": {
"id": 2,
"hwId": "029033420621",
"name": "AP - apps.slu.de",
"domainId": 1,
"product": "AppPlatform ARM",
"version": "110002 dvl (13r3 137688 beta4 )",
"type": "APP_PLATFORM",
"pbxActive": false,
"online": true,
"ethIfs": [ ... ]
}
}
</syntaxhighlight>
</spoiler>

===== get_devices_from_domain(int id) : object =====
You will receive all devices which are assigned to the given domain

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var devices = cmd.get_devices_from_domain(1);
console.log(devices);
{
"1": {
"id": 1,
"hwId": "009033420621",
"name": "PBX - pbx.slu.de",
"domainId": 1,
"product": "IP0011",
"version": "13r3 beta4 [13.7688/137623/600]",
"type": "GW",
"pbxActive": true,
"online": true,
"ethIfs": [ ... ]
},
"2": {
"id": 2,
"hwId": "029033420621",
"name": "AP - apps.slu.de",
"domainId": 1,
"product": "AppPlatform ARM",
"version": "110002 dvl (13r3 137688 beta4 )",
"type": "APP_PLATFORM",
"pbxActive": false,
"online": true,
"ethIfs": [ ... ]
}
}
</syntaxhighlight>
</spoiler>

===== get_device(int id) : object =====
You will receive a specific device

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var device = cmd.get_device(2);
console.log(device);
{
"id": 2,
"hwId": "029033420621",
"name": "AP - apps.slu.de",
"domainId": 1,
"product": "AppPlatform ARM",
"version": "110002 dvl (13r3 137688 beta4 )",
"type": "APP_PLATFORM",
"pbxActive": false,
"online": true,
"ethIfs": [ ... ]
}
</syntaxhighlight>
</spoiler>

==== helper functions ====

===== percent(int value, int total) : float =====
Returns the number of percent of value to total

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var check = cmd.percent(50, 100);
console.log(check);
50
</syntaxhighlight>
</spoiler>

===== parse_xml(string xml, string element = <nowiki>''</nowiki>) : object =====
Returns an object/array representation of given XML string. Note that very large XML inputs cannot be converted directly because there are some restrictions in the duktape environment. If you receive an exception with ''Error: RangeError: regexp executor recursion limit'' you have to define which element do you want to converted (See the second example).

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var json = cmd.parse_xml('<sample><item property_1="value_1" property_2="value_2">content of item</item><item_short prop_1="value_prop_1" /></sample>');
console.log(json);
{
"sample": {
"item": {
"@property_1": "value_1",
"@property_2": "value_2",
"#": "content of item"
},
"item_short": {
"@prop_1": "value_prop_1"
}
}
}
</syntaxhighlight>
</spoiler>
 
<spoiler show="show sample code with large xml payload" hide="hide sample code with large xml payload">
<syntaxhighlight lang="javascript">

var xml_registrations_on_big_pbx = '\
<show state="up" time="267993" loc="pbx">\
<attrs></attrs>\
<reg cn="Fax" guid="829a6aeec2a76401c62600155d50c817" h323="fax" pwd="********" pwdx="********" prot="JSON">\
<ep type="gk" addr="172.16.176.205" time="10"/>\
<pseudo-common lics=".reporting."/>\
<pseudo type="fax"/>\
</reg>\
<reg cn="Voicemail de" guid="5ceb0ee7c2a76401bb2600155d50c817" h323="voicemail-de" pwd="********" pwdx="********" prot="JSON">\
<ep type="gk" addr="172.16.176.205" time="10"/>\
<pseudo-common lics=".uc.voicemail.reporting."/>\
<pseudo type="vm"/>\
</reg>\
... and so on ...\
</show>';
var json = cmd.parse_xml(xml_registrations_on_big_pbx, 'reg');
console.log(json);
[
{"@cn":"Fax", "@guid":"829a6aeec2a76401c62600155d50c817", ... "ep":{"@type":"gk","@addr":"172.16.176.205","@time":"10"}, ...},
{"@cn":"Voicemail", "@guid":"5ceb0ee7c2a76401bb2600155d50c817", ... "ep":{"@type":"gk","@addr":"172.16.176.205","@time":"10"}, ...},
...
]
</syntaxhighlight>
</spoiler>

===== is_supported_version(string version) : object =====
Return if the given Version string is supported according to [[Howto:Supported innovaphone versions]].
<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
cmd.is_supported_version('13r3 sr9 [13.7886/1000/0]'); // return "true"
</syntaxhighlight>
</spoiler>

===== get_version_from_build(int build) : string =====
Return the named version from given build number. (13r3, 14r1 or similar)
<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
cmd.get_version_from_build(1410485); // return "14r1"
</syntaxhighlight>
</spoiler>

===== get_pbx_objects_from_config(string config) : array =====
Extract from a config file PBX Objects with support for different views, DynPBXes and the removal of marks-as-deleted objects
<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
// "config" contains the result from your "cfg.txt"
cmd.get_pbx_objects_from_config(config);

// return
[
"mod cmd FLASHDIR0 add-item 102 (cn=user-1)(h323=user-1)(e164=10)",
"mod cmd FLASHDIR0 add-item 102 (cn=user-2)(h323=user-2)(e164=20)",
"mod cmd FLASHDIR0 add-item 105 (cn=user-1-in-dynpbx)(h323=user-1-in-dynpbx)(e164=50)",
]

</syntaxhighlight>
</spoiler>

==== debug ====

===== log(string message) : void =====
You can write a logfile line to the app debug log

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var domains = cmd.log('my first logfile line');
07-26 07:58:33.179 TechAssist@slu.de (b0728708) | Test "sample_test" | my first logfile line
</syntaxhighlight>
</spoiler>

== Secret knowledge for good tests ==
; bool PBX-Object config attributes
: You will find config attributes like <code>no-subscribe="true"</code> (this is from a Trunk Object) in the config. Please note that if the attribute is ''missing'' or the value is ''false'' it is false, otherwise it is ''true''. For example, the value <code>no-subscribe="on"</code> is also true.
; bool Interface config attributes
: You will find config attributes like <code>/direct-sig on</code> (this is from a SIP interface) in the config. Please note that they are exists bool-attribute which are ''true'' if the attribute is existing. In the case of bool-attribute the following value make no matter. For example, the attribute <code>/direct-sig off</code> is also true.

== Troubleshooting ==

=== Startup Logfile ===
If you enable the traceflag ''App'' in your App instance, you will find the following logs:

AppService::AppStart TechAssist@slu.de
App instance started 14C1363 14C1363
...
// App begins to load embedded tests
JavaScript: Files tests/*
...
// Scheduler begins to load all the tests
scheduler init
init test "firmware_version"
firmware_version: Test added successful
init test "pbx_mediarelay"
pbx_mediarelay: Test added successful

Howto14r2:Firmware Upgrade V14r1 V14r2

2024-09-20T14:20:43Z

Lme: /* Manual steps needed after upgrade */

== Applies To ==
This information applies to:

* All 14r2 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 14r2, see [[Howto:Firmware Upgrade]]
== Licenses ==
In case of cloud or rental model, don't worry about licenses.

If the system is licensed on premise, and you already have V14 licenses, there is nothing to do. Otherwise, you'll need to regenerate the license file for V14 in https://portal.innovaphone.com/ and load into the system before upgrade.

== Migration Policy ==
Here is how you upgrade a system from 14r1 to 14r2.

Before you begin, be sure that your whole installation is running the latest 14r1 service release. If you are still running 13r3 or earlier, be sure to update to [[Howto14r1:Firmware_Upgrade_V13r3_V14r1|14r1 latest service release]] before. 

=== IPVA - Flash preparations ===
Due to an internal change in the flash segment allocation in the IPVA environment, you may have to prepare your system for the upgrade. 
Please execute the command <code>!mod cmd FLASHMAN0 info</code> on all your IPVAs before the update. You must check whether all flash segments are allocated in your current installation.

In this example, you can see that 228 segments are used by the LDAP (marked in green), and a total of 228 segments are available (marked in yellow).
If the difference between these two numbers is less than 10, you must perform the following steps before the upgrade:
# Download the configuration (NOT "with standard password") from the IPVA
# Upload the configuration to the IPVA
# Reboot the IPVA

segments=249, segment-size=0x10000 (64k)
LDAP - used 47k avail 43k owned 14592k (segments 228) maximum 14592k (segments 228, configured 228)
VARS - used 51k avail 8k owned 1280k (segments 20) maximum 1280k (segments 20, configured 20)

After execute the above command again, you will see the following. The segments used by the LDAP (marked in green) changed.

segments=249, segment-size=0x10000 (64k)
LDAP - used 47k avail 61k owned 128k (segments 2) maximum 14592k (segments 228, configured 228)
VARS - used 24k avail 21k owned 1280k (segments 20) maximum 1280k (segments 20, configured 20)

If the difference between these two numbers is now greater than 10, you can go ahead with your upgrade. Otherwise, please open a support case.

=== App Platform and Apps ===
14r2 Apps are no longer compatible with App Platform Images version 11xxxx or below due to a major update of the used OpenSSL library, as the old 1.1 version is deprecated. 

* upgrade your App Platform to version 12xxxx in the settings of your App Platform Manager via the Update option (open the AP Manager, Burger menu, Settings, update -> update to 12xxxx) and then carry out the '''restart''' offered in the update procedure
* verify that the App Platform is rebooted by checking the version using the "burger menu / Settings / Update" in the App Platform Manager
* upgrade your Apps to version 14r2 now

Note that all previous versions of Apps will still run on App Platform version 12xxxx, just 14r2 Apps require this new image version.

=== App Platform replication ===
Sadly it's not possible to upgrade the App Platform on App Platform Standbys directly due to a major version change of the PostgreSQL database.

So follow these steps:
* disable replication on each '''standby''' App Platform
* shutdown each '''standby''' App Platform
* proceed with the regular update on your infrastructure for all other devices
* verify proper function of your system
* startup each '''standby''' App Platform
* follow the [[#App_Platform_and_Apps|above steps]] to upgrade each '''standby''' App Platform
* activate standby replication on the '''standbys''' App Platforms again now (this will do a full replication again which might take some time)

Alternatively you can install the standbys from scratch.

== Changes visible to the end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a 14r2 upgrade, as the change will be visible/audible in the behaviour of the application/device.

* '''myApps accessibility''': Several improvements in myApps accessibility like '''screen reader support''' and '''keyboard control''' [[Reference14r2:Concept_myApps#Accessibility]]
* '''Connect UI''': Changes and improvements in the UI of the Connect app
* '''Fax Cover Page''': For outgoing FAX documents, a cover page with user content can be prepend

== Manual steps needed after upgrade ==
If the installer is not used for a new installation, some new default settings are not set. Please evaluate per app whether you want to configure the new default settings manually.

=== Calendar App ===
Microsoft Office 365 Exchange. Microsoft [https://techcommunity.microsoft.com/t5/exchange-team-blog/retirement-of-rbac-application-impersonation-in-exchange-online/ba-p/4062671 Retirement of RBAC Application Impersonation in Exchange Online] . You have to change some configurations in the PBX Manager Plugin for the Calendar App. See [[Howto13r2:Setting up Calendar with OAuth2]]

=== Connect App / Search App ===
In order for the Search App to find Connect posts, you need to make sure to change the following things:
* PBX Manager plugin "AP messages" - "Api" - Make sure to enable "Config User" for the Messages API Object. ('''Not''' Administrators or Moderators)
* For the "Connect" PBX-Object
** In the "App"-Tab enable "PbxApi" (additionally to "Websocket" and "PbxSignal")
** In the "Apps"-Tab enable "messages-api"

=== Contacts App ===
You have to enable the checkmark "Websocket" in the App Object. Otherwise you will not have new "Add Contacts" functions inside the PhoneApps

=== Mail2Fax ===
You can now enter mail server settings in the PBX Manager plugin for the fax app, to use the Mail2Fax feature. See [[Reference14r2:Concept_App_Service_Fax]]

=== WorkingManager ===
You need to add the string "hr" to the "Modes" field in the WorkingManager app object to create a special app that can be assigned to a user that grants all rights. Otherwise, users to whom the WorkingManager is assigned will only have the assigned group permissions.
See https://wiki.innovaphone.com/index.php?title=Reference14r2:Concept_App_Service_Working#innovaphone-working-admin

== New Apps ==
New Apps will not be installed automatically by the 14r1 to 14r2 upgrade. The installation description of new 14r2 apps is usually in the concept article. Please rate per app whether you want to install/use the new app and configure it manually.

* [[Reference14r2:Concept_App_Remote_Control]]
* [[Reference14r2:Concept_App_Service_Translations]]

== Removed ==
The following software is no longer included in 14r2.

* Nothing

== Deprecated ==
The following software is based on legacy technology, with no further development and limited maintenance and support.
We strongly recommend migrating to our successor products that are fully compatible with 14r2 and myApps technology.

* running an AP on the CF card of an IPxx10 gateway is no longer supported, use a gateway with an SSD or a Virtual Machine to run the AP instead. The Linux/AP functionality is not yet removed from the firmware, so when migrating to 14r2, existing installations will continue to work (even if unsupported).
* iQM (innovaphone Queue Monitor) is deprecated, and we recommend migrating to the [[Howto:Queueboard_-_MediaRunway_-_Partner_App|Queueboard App]].

== Previously deprecated and now no longer supported ==
The following software is based on legacy technology, with no further development and no more maintenance and support. 
See: [[Howto14r1:Firmware_Upgrade_V13r3_V14r1#Deprecated_in_14r1]] 
We strongly recommend migrating to our successor products.

;Linux Application Platform (v10)
:Please migrate to the '''innovaphone App Platform'''.
;innovaphone Faxserver (v10)
:Please migrate to the '''Fax App'''.
;innovaphone Reporting (v10)
:Please migrate to the '''Reports App'''.
;innovaphone Exchange (v10)
:Please migrate to the '''Calendar App'''.
;Operator (v9)
:Please migrate to the '''Switchboard App'''.
;innovaphone Voice Recording 2014
:Please migrate to the '''Recordings App'''.
;PBX Object External UC
:Existing configurations still work. But new configurations can't be done using the advanced UI anymore.
:Please use the integrated '''UC''' and '''federation''' features of the '''innovaphone PBX'''.
:For presence synchronization with other systems we recommend using
:* '''innovaphone myApps Connector for Microsoft 365'''
:* '''Connector for kuando®'''
:* '''Calendar App'''

==Known Problems==
===Long Update-duration===
When you update, it can be up to 10 minutes before you have access to your app platform again.

===Downgrade on IPVA with large configuration===
The number of 64kB memory segments that an IPVA uses internally to store "VARS" has been increased from 10 to 20. This is only an internal adjustment and does not require any adjustment to the virtual machine.

After an upgrade to v14r2 a downgrade is possible as long as the total space used by VARS is less than 540 kB, i.e. <code>mod cmd FLASHMAN0 info</code> -> VARS - used=nk (n <= 540)

Because VARS data may be scattered over all assigned segments, the downgrade procedure must be:
# "config download" to gather the potentially scattered VARS
# downgrade
# "config upload" to restore the VARS as densely packed

== Resources Considerations ==
New firmware always has more features which in turn requires more resources. Growing firmware will thus consume both more flash and RAM for sure. A given system configuration will run flawlessly after a firmware largely only if there is still enough memory left after boot.

Standard configurations which are according the specs will run on all supported hardware. However, unusual configurations may not. It is a good idea to examine both flash and RAM memory left on high load situations in your existing configuration to see if there is enough resources left for an upgrade. Please find details in Reference:Device Health Check.

=== RAM ===
As a rough rule of thumb, a 14r2 release will consume the same amount of RAM compared to a v14r1 firmware.

=== Flash Memory ===
As a rough rule of thumb, a v14r2 release will consume ~ 64KB more flash memory compared to a v14r1 firmware.
New firmware comes with new code for new features which consumes more flash memory for the firmware image. For this reason, devices may run out of flash memory during upgrade to v14r2. Here is the recommended procedure for upgrade on such devices:

* save entire configuration
* reset to factory defaults
* load saved configuration (this will reorganize the flash memory usage)
* upgrade to new firmware

When there is still not enough flash memory available to store the new firmware (Web GUI ends up in a ''Firmwareupdate failed:no space'' / Update client end in a ''Error 0x00130001 Major FLASHMAN0 no space'' event) please open a support case with your current configuration file.

Reference14r2:Concept App Service Working

2024-07-30T12:27:14Z

Lme: /* innovaphone-working-client-api */

[[Category:Concept|Apps]]
The Working App is an app for recording working hours. There is a user app (Working User) to start/stop time tracking and an admin app (Working Manager) to view working hours for all users.
== Applies To ==

* innovaphone PBX from version 14r2

==Requirements==
* innovaphone PBX
* innovaphone Application Platform
* innovaphone myAPPS
* Firmware V14r2 beta1 or higher
* License “App(innovaphone-working)” (order no. 02-00050-010) per application-user

==Concept==

The innovaphone Service Working App is an app to track working hours.
There is a user app (Working User) to start/stop time tracking (clock style) or to add entries manually. These entries must be confirmed (=submitted) to be displayed on the admin app. Once they are confirmed, they can no longer be edited. There is also an admin app (Working Manager) to display the working time information for all users and where the configuration settings can be changed.
The app is designed to help employees and employers to easily track working hours in a digital manner.

==How it works==

The first time a user starts the Working App on myApps a new entry is created in the database for this user, based on the "Name" of this user, which will be used to store all the working hours entries, vacation days, sick days and national holidays. Entering the working hours is a two step task, because after defining the start/stop time it is also necessary to "confirm/submit" these hours as correct, after the confirmation is done the user can't change them anymore and they will be displayed on the admin app.

In the Working Admin App the list of the users' names is based on the "Display Name", if no DN is set then the "Name" will be used. Once the users have opened the working app at least once, they will appear in the list of all users in the Working Manager App. The app adds a red mark when an user does not fulfill the working hours regulation.

== Apps ==
=== innovaphone-working ===
[[Image: Innovaphone-working.png]]
This is an app (Working User), where the user can enter the working hours, holidays, sick and vacation days. This can be done by clicking on the start/stop button. The user have also a calendar view to add, edit or delete working hours.

=== innovaphone-working-api ===
[[Image: Innovaphone-working-api.png]]
This is a hidden app (Working Api), where the myApps session is been monitorized when the autostart/stop of the working times is enabled on the Working User App.

Parameters:
;Websocket: to set a websocket connection.
;Hidden: to configure the app as hidden.
;Admin: to get the app object name where to send the notifications.
;PbxApi: to send the notifications.

=== innovaphone-working-client-api ===
[[Image: Innovaphone-working-api.png]]
This is an app needed to provide the Working Client API, so that other apps can start/stop working times. The innovaphone-working-client-api app is also a hidden app. The PBX Manager plugin also sets the hidden function.

Parameters:
;Websocket: to set a websocket connection.

=== innovaphone-working-admin ===
[[Image: Innovaphone-working-admin.png‎]]
This is an admin app (Working Manager), where an administrator (i.e. Human Resources) can see the users' working hours. Periodic reports are generated with a list of users who do not comply with the hours restrictions. Several settings like the working hours per day can be configured per user and they are set to 8 hours from monday to friday by default.

Now "hr" must be entered as Mode on the app object on the PBX. With that now there are 2 apps avaiable: workingmanager and workingmanager~hr
* workingmanager: the managers on the group can only see the users on the group (no hamburger menu avaiable)
* workingmanager~hr: all the users can be seen there and all the configurations are available

Also some config items can be edited on the hamburguer menu:

* General settings
** Timeout to submit entries (days): max interval the user has to submit the working hours.
** Min break time after 6 hours: min break time if the user has worked more than 6 hours.
** Min break time after 9 hours: min break time if the user has worked more than 9 hours.
** Config working types: which can be selected on the dropdown for every working interval and are available for all users.

* No email reports are available on 14r2

* Default working hours: workings hours defined per day when a user opens the app for the first time, which can be modified per user on the Admin App (Working Manager).
** Monday
** Tuesday
** Wednesday
** Thursday
** Friday
** Saturday
** Sunday

* Rights
** Config groups
*** Groups can be defined
*** Only the managers of the groups can see the users on the group on the Working Manager App
*** Working types only available for the users on the group can be configured
*** Enable/disable restrictions to submit working hours for the users on the group

The users' data can be exported and imported on CSV format. There are some fixed fields that are available for the import and the export. There are also some other fields that are only displayed on the export file just as extra information, which are marked with (*).

==== CSV export ====
'''Users'''

The fields that come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that come with the CSV are the SIP, the start timestamp, the working hours, label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted), date, and the personal number.
&sip;&start;&duration;&label;&confirmed;&date;&p_number 
atlantis;1712181600000;8;hvacation;true;2024-04-04;0

'''Times'''

The fields that come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted), the display name, the personal number, the start date, the start time, the stop date, the stop time, the amount of hours and the label (if a type has been selected).
&sip;&start;&stop;&confirmed;&dn;&p_number;&start_date;&start_time;&stop_date;&stop_time;&hours;&label 
atlantis;1712651520199;1712651700199;true;Atlantis;0;2024-04-09;10:32:00.199+00:00;2024-04-09;10:35:00.199+00:00;0,1;

==== CSV import ====
'''Users'''

The fields that should come with the CSV are the SIP, GUID, domain, display name, the defined working hours per day and the personal number.
&sip;&guid;&domain;&dn;&monday;&tuesday;&wednesday;&thursday;&friday;&saturday;&sunday;&p_number 
atlantis;null;innovaphone.com;Atlantis;8;8;8;8;8;0;0;0

'''Absences'''

The fields that should come with the CSV are the SIP, the start timestamp, duration (the working hours), label ('''vacation''' for a vacation day, '''hvacation''' for a 1/2 day vacation, '''holiday''' for national holidays, '''sick''' for sick leave), confirmed (if the absence has been submitted) and date (if present timestamp will be ignored). The date must always have the english format, i.e. MM-DD-YYYY.
&sip;&start;&duration;&label;&confirmed;&date 
atlantis;1712181600000;8;hvacation;true;2024-04-04

'''Times'''

The fields that should come with the CSV are the SIP, the start timestamp, the stop timestamp, confirmed (if has been submitted).
&sip;&start;&stop;&confirmed 
atlantis;1712651520199;1712651700199;true

Parameters:
;workingadmin: the name of the working admin app.

== PBX Manager Plugins ==

=== Working ===

With the Working plugin App Objects can be created, edited and deleted on the PBX.

==Configuration==
* Install the Working App with the new AP app installer available in the PBX manager. ''Hint : after the installation done, close and open again the PBX Manager to refresh the list of the installed app (the coloured plug-in)''
* Create a new PBX Object for the Working User, Working Manager and Working API Apps with the PBX Manager Plugin.
* Assign the Working User (to normal users) and Working Manager App (to administration for example Human Resources) by selecting the config template that should include the App.
* Assign the Working API to all the users, so users can use the auto start/stop and push notifications.
* Assign license "App(innovaphone-working)" via config template or directly to all users using the APP.
* Set configuration settings on the "burger" menu of the Working Manager App (i.e. Reports Interval in weeks, groups and types configuration...).

==Troubleshooting==
Trace flags for App on App Platform:

*App
*App Database
*App Websocket

Trace flags for myAPPS Client:

*Browser Console

==Known issues==

==Related Articles==
* [https://sdk.innovaphone.com/14r2/web1/com.innovaphone.working/com.innovaphone.working.htm SDK Documentation - Working API]
* [https://sdk.innovaphone.com/14r2/doc/service/Working.htm SDK Documentation - Working Client API]

Reference13r3:Concept App Service Connector for kuando®

2024-04-03T07:39:06Z

Lme: /* Tracing */

[[Category:Concept|Apps]]
[[Category:Concept App Service Connector for kuando®]]

== 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. 
: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: 
[[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. 

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

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

=== 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:''' 
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'' and ''app'' in the myApps launcher 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 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. ..." 
Solution 
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.

Howto:Wikitogo

2023-11-09T07:49:46Z

Lme:

Wikitogo is an offline version of the innovaphone wiki that you can download and import into your own locally hosted media wiki.

==Applies To==
This information applies to all V7 devices and later.



==More Information==
innovaphone wiki is the source for the innovaphone on-line help. This is great as you always have access to the latest information on-line.

However, once in a while you will need to go to a customer site where you don't have access to wiki.innovaphone.com. To help with this situation, you can use a locally hosted media wiki on your own device for all the needed information.

===Installation===
To import this wiki into your own, you need an .xml file with all the important data. You can get the file [https://wiki.innovaphone.com/index.php?title=Special:Export here] and choose to either download the whole wiki by selecting "Export all pages" or you can add all pages from a category or manually if you just want some pages from the wiki.
After downloading the .xml file, you can import the pages into your own wiki using the special import page. If you want to know how to do this, see the [https://www.mediawiki.org/wiki/Manual:Importing_XML_dumps#Using_Special:Import mediawiki website] for more information.

===Configuration===
The web interface of the V7 innovaphone devices is equipped with a Help button providing context sensitive online help for the current configuration page. In the default configuration it links to a corresponding wiki Reference page on the <code>http://wiki.innovaphone.com</code>. To link to the wikitogo installation on your PC a configuration change on the device is required. Read [[Reference:Configuration/General/Admin#Help_URL]] in order to understand how to change the default Help URL.

===Known Problems===
You have to download it manually everytime pages you need getting updated.

== Related Articles ==
[[Reference:Configuration/General/Admin]]

[[Category:Howto|{{PAGENAME}}]]

Howto14r1:Firmware Upgrade V13r3 V14r1

2023-10-20T11:45:48Z

Lme: /* Known Problems */

{{FIXME|reason=Preliminary working draft}}
== Applies To ==
This information applies to:

* All 14r1 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 14r1, see [[Howto:Firmware Upgrade]]

== Changes visible to end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a 14r1 upgrade, as the change will be visible/audible in the behaviour of the application/device.
=== Softphone/Phone App UI changes ===
* Dial-pad is now a new tab in the navigation.
* On Smartphones, the Navigation is in the bottom.
* Call button is removed from the searchbar. Calling only via the search results.

== Application Platform and its applications ==
===Apps new in 14r1===
New Apps will not be installed automatically by the 13r3 to 14r1 upgrade. The installation description of new 14r1 apps is usually in the concept article. New apps are:
;Search App
* The app is immediately available on the PBX (no configuration is needed). In a new V14r1 configuration the Install provides all Users with this Search App via the "Config User"-Template. If the same configuration is required on an upgraded config, the Search App ("search") can be ticked in the "Config User" template.
;TechAssist
* Application for quality assurance and improvement of systems by collecting static and runtime information. For details refer to [[Reference14r1:Concept_App_Service_TechAssist | the concept article]].

== Configuration Changes ==

=== Fax Object ===
After updating from 13r3 or setting up your device with 14r1, the Fax object has 3 new checkboxes.
* Append user number: if checked, the user number will be appended to the object number.
* ECM: that allows the T.30 connection to use error correction.
* Receiving with 400dpi allowed: which allows you to receive 400*400dpi documents.

== Removed in 14r1 ==
The following software is no longer included in 14r1.
=== myPBX ===
This includes the following components
* myPBX webclient
* myPBX for Windows
* myPBX for iOS
* myPBX for Android
Please migrate to '''innovaphone myApps'''.

===Widgets===
The Widgets were based on the myPBX interfaces that have been removed. Please migrate to the '''Contacts Widget App'''.
===WebRTC toolkit===
The WebRTC toolkit was based on the myPBX interfaces that have been removed.
Please use the current interfaces and libraries described in the '''[https://sdk.innovaphone.com innovaphone SDK]'''.
=== Windows Softwarephone ===
Please migrate to '''innovaphone myApps for Windows''' and the '''Softphone App'''.
===PBX Object Settings ===
The object provided the PBX Settings App that was used to configure dynamic group memberships in myPBX.
Please use the '''Profile App''' instead.

===PBX Object ICP ===
Please use the integrated presence features of the '''innovaphone PBX''' instead.

===Service Call-Lists ===
This service implemented call lists for myPBX on the local CF card.
Please use the '''Reports App''' instead.

== Deprecated in 14r1 ==
The following software is based on legacy technology with no further development and limited maintenance and support.
We strongly recommend migrating to our successor products that are fully compatible with 14r1 and myApps technology.

=== Linux Application Platform (v10) ===
Please migrate to the '''innovaphone App Platform''' for 14r1 installations.

=== innovaphone Faxserver (v10) ===
Please migrate to the '''Fax App''' for 14r1 installations.
=== innovaphone Reporting (v10) ===
Please migrate to the '''Reports App''' for 14r1 installations.
=== innovaphone Exchange (v10) ===
Please migrate to the '''Calendar App''' for 14r1 installations.
=== Operator (v9) ===
Please migrate to the '''Switchboard App''' for 14r1 installations.
=== innovaphone Voice Recording 2014 ===
Please migrate to the '''Recordings App''' for 14r1 installations.
=== PBX Object External UC ===
Existing configurations still work. But new configurations can't be done using the advanced UI anymore.

Please use the integrated '''UC''' and '''federation''' features of the '''innovaphone PBX'''.

For presence synchronization with other systems we recommend using
* '''innovaphone myApps Connector for Microsoft 365'''
* '''Connector for kuando®'''
* '''Calendar App'''
=== PBX Object Session Border ===
Please migrate to '''Reverse Proxy''' and '''[[Reference13r3:Concept_Third_Party_Phones]]'''.

==Known Problems==
===Long Update-duration===
When you update, it can be up to 10 minutes before you have access to your app platform again.

== Resources Considerations ==
New firmware always has more features which in turn requires more resources. Growing firmware will thus consume both more flash and RAM for sure. A given system configuration will run flawlessly after a firmware largely only if there is still enough memory left after boot.

Standard configurations which are according the specs will run on all supported hardware. However, unusual configurations may not. It is a good idea to examine both flash and RAM memory left on high load situations in your existing configuration to see if there is enough resources left for an upgrade. Please find details in Reference:Device Health Check.

=== RAM ===
As a rough rule of thumb, a 14r1 release will consume the same amount of RAM compared to a v13r3 firmware.

=== Flash Memory ===
As a rough rule of thumb, a v14r1 release will consume ~ 1.8 MB more flash memory compared to a v13r3 firmware.
New firmware comes with new code for new features which consumes more flash memory for the firmware image. For this reason, devices may run out of flash memory during upgrade to v14r1. Here is the recommended procedure for upgrade on such devices:

* save entire configuration
* reset to factory defaults
* load saved configuration (this will reorganize the flash memory usage)
* upgrade to new firmware

When there is still not enough flash memory available to store the new firmware (Web GUI ends up in a ''Firmwareupdate failed:no space'' / Update client end in a ''Error 0x00130001 Major FLASHMAN0 no space'' event) please open a support case with your current configuration file.

Howto14r1:Firmware Upgrade V13r3 V14r1

2023-10-20T11:41:11Z

Lme: /* Deprecated in 14r1 */

{{FIXME|reason=Preliminary working draft}}
== Applies To ==
This information applies to:

* All 14r1 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 14r1, see [[Howto:Firmware Upgrade]]

== Changes visible to end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a 14r1 upgrade, as the change will be visible/audible in the behaviour of the application/device.
=== Softphone/Phone App UI changes ===
* Dial-pad is now a new tab in the navigation.
* On Smartphones, the Navigation is in the bottom.
* Call button is removed from the searchbar. Calling only via the search results.

== Application Platform and its applications ==
===Apps new in 14r1===
New Apps will not be installed automatically by the 13r3 to 14r1 upgrade. The installation description of new 14r1 apps is usually in the concept article. New apps are:
;Search App
* The app is immediately available on the PBX (no configuration is needed). In a new V14r1 configuration the Install provides all Users with this Search App via the "Config User"-Template. If the same configuration is required on an upgraded config, the Search App ("search") can be ticked in the "Config User" template.
;TechAssist
* Application for quality assurance and improvement of systems by collecting static and runtime information. For details refer to [[Reference14r1:Concept_App_Service_TechAssist | the concept article]].

== Configuration Changes ==

=== Fax Object ===
After updating from 13r3 or setting up your device with 14r1, the Fax object has 3 new checkboxes.
* Append user number: if checked, the user number will be appended to the object number.
* ECM: that allows the T.30 connection to use error correction.
* Receiving with 400dpi allowed: which allows you to receive 400*400dpi documents.

== Removed in 14r1 ==
The following software is no longer included in 14r1.
=== myPBX ===
This includes the following components
* myPBX webclient
* myPBX for Windows
* myPBX for iOS
* myPBX for Android
Please migrate to '''innovaphone myApps'''.

===Widgets===
The Widgets were based on the myPBX interfaces that have been removed. Please migrate to the '''Contacts Widget App'''.
===WebRTC toolkit===
The WebRTC toolkit was based on the myPBX interfaces that have been removed.
Please use the current interfaces and libraries described in the '''[https://sdk.innovaphone.com innovaphone SDK]'''.
=== Windows Softwarephone ===
Please migrate to '''innovaphone myApps for Windows''' and the '''Softphone App'''.
===PBX Object Settings ===
The object provided the PBX Settings App that was used to configure dynamic group memberships in myPBX.
Please use the '''Profile App''' instead.

===PBX Object ICP ===
Please use the integrated presence features of the '''innovaphone PBX''' instead.

===Service Call-Lists ===
This service implemented call lists for myPBX on the local CF card.
Please use the '''Reports App''' instead.

== Deprecated in 14r1 ==
The following software is based on legacy technology with no further development and limited maintenance and support.
We strongly recommend migrating to our successor products that are fully compatible with 14r1 and myApps technology.

=== Linux Application Platform (v10) ===
Please migrate to the '''innovaphone App Platform''' for 14r1 installations.

=== innovaphone Faxserver (v10) ===
Please migrate to the '''Fax App''' for 14r1 installations.
=== innovaphone Reporting (v10) ===
Please migrate to the '''Reports App''' for 14r1 installations.
=== innovaphone Exchange (v10) ===
Please migrate to the '''Calendar App''' for 14r1 installations.
=== Operator (v9) ===
Please migrate to the '''Switchboard App''' for 14r1 installations.
=== innovaphone Voice Recording 2014 ===
Please migrate to the '''Recordings App''' for 14r1 installations.
=== PBX Object External UC ===
Existing configurations still work. But new configurations can't be done using the advanced UI anymore.

Please use the integrated '''UC''' and '''federation''' features of the '''innovaphone PBX'''.

For presence synchronization with other systems we recommend using
* '''innovaphone myApps Connector for Microsoft 365'''
* '''Connector for kuando®'''
* '''Calendar App'''
=== PBX Object Session Border ===
Please migrate to '''Reverse Proxy''' and '''[[Reference13r3:Concept_Third_Party_Phones]]'''.

==Known Problems==

== Resources Considerations ==
New firmware always has more features which in turn requires more resources. Growing firmware will thus consume both more flash and RAM for sure. A given system configuration will run flawlessly after a firmware largely only if there is still enough memory left after boot.

Standard configurations which are according the specs will run on all supported hardware. However, unusual configurations may not. It is a good idea to examine both flash and RAM memory left on high load situations in your existing configuration to see if there is enough resources left for an upgrade. Please find details in Reference:Device Health Check.

=== RAM ===
As a rough rule of thumb, a 14r1 release will consume the same amount of RAM compared to a v13r3 firmware.

=== Flash Memory ===
As a rough rule of thumb, a v14r1 release will consume ~ 1.8 MB more flash memory compared to a v13r3 firmware.
New firmware comes with new code for new features which consumes more flash memory for the firmware image. For this reason, devices may run out of flash memory during upgrade to v14r1. Here is the recommended procedure for upgrade on such devices:

* save entire configuration
* reset to factory defaults
* load saved configuration (this will reorganize the flash memory usage)
* upgrade to new firmware

When there is still not enough flash memory available to store the new firmware (Web GUI ends up in a ''Firmwareupdate failed:no space'' / Update client end in a ''Error 0x00130001 Major FLASHMAN0 no space'' event) please open a support case with your current configuration file.

Howto14r1:Firmware Upgrade V13r3 V14r1

2023-10-19T14:49:34Z

Lme: /* Configuration Changes */

{{FIXME|reason=Preliminary working draft}}
== Applies To ==
This information applies to:

* All 14r1 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 14r1, see [[Howto:Firmware Upgrade]]

== Changes visible to end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a 14r1 upgrade, as the change will be visible/audible in the behaviour of the application/device.
=== Softphone/Phone App UI changes ===
* Dial-pad is now a new tab in the navigation.
* On Smartphones, the Navigation is in the bottom.
* Call button is removed from the searchbar. Calling only via the search results.

== Application Platform and its applications ==
===Apps new in 14r1===
New Apps will not be installed automatically by the 13r3 to 14r1 upgrade. The installation description of new 14r1 apps is usually in the concept article. New apps are:
;Search App
* The app is immediately available on the PBX (no configuration is needed). In a new V14r1 configuration the Install provides all Users with this Search App via the "Config User"-Template. If the same configuration is required on an upgraded config, the Search App ("search") can be ticked in the "Config User" template.
;TechAssist
* Application for quality assurance and improvement of systems by collecting static and runtime information. For details refer to [[Reference14r1:Concept_App_Service_TechAssist | the concept article]].

== Configuration Changes ==

=== Fax Object ===
After updating from 13r3 or setting up your device with 14r1, the Fax object has 3 new checkboxes.
* Append user number: if checked, the user number will be appended to the object number.
* ECM: that allows the T.30 connection to use error correction.
* Receiving with 400dpi allowed: which allows you to receive 400*400dpi documents.

== Removed in 14r1 ==
The following software is no longer included in 14r1.
=== myPBX ===
This includes the following components
* myPBX webclient
* myPBX for Windows
* myPBX for iOS
* myPBX for Android
Please migrate to '''innovaphone myApps'''.

===Widgets===
The Widgets were based on the myPBX interfaces that have been removed. Please migrate to the '''Contacts Widget App'''.
===WebRTC toolkit===
The WebRTC toolkit was based on the myPBX interfaces that have been removed.
Please use the current interfaces and libraries described in the '''[https://sdk.innovaphone.com innovaphone SDK]'''.
=== Windows Softwarephone ===
Please migrate to '''innovaphone myApps for Windows''' and the '''Softphone App'''.
===PBX Object Settings ===
The object provided the PBX Settings App that was used to configure dynamic group memberships in myPBX.
Please use the '''Profile App''' instead.

===PBX Object ICP ===
Please use the integrated presence features of the '''innovaphone PBX''' instead.

===Service Call-Lists ===
This service implemented call lists for myPBX on the local CF card.
Please use the '''Reports App''' instead.

== Deprecated in 14r1 ==
The following software is based on legacy technology with no further development and limited maintenance and support.
We strongly recommend migrating to our successor products that are fully compatible with 14r1 and myApps technology.

=== Linux Application Platform (v10) ===
Please migrate to the '''innovaphone App Platform''' for 14r1 installations.

=== innovaphone Faxserver (v10) ===
Please migrate to the '''Fax App''' for 14r1 installations.
=== innovaphone Reporting (v10) ===
Please migrate to the '''Reports App''' for 14r1 installations.
=== innovaphone Exchange (v10) ===
Please migrate to the '''Calendar App''' for 14r1 installations.
=== Operator (v9) ===
Please migrate to the '''Switchboard App''' for 14r1 installations.
=== innovaphone Voice Recording 2014 ===
Please migrate to the '''Recordings App''' for 14r1 installations.
=== PBX Object External UC ===
Existing configurations still work. But new configurations can't be done using the advanced UI anymore.

Please use the integrated '''UC''' and '''federation''' features of the '''innovaphone PBX'''.

For presence synchronization with other systems we recommend using
* '''innovaphone myApps Connector for Microsoft 365'''
* '''Connector for kuando®'''
* '''Calendar App'''
=== PBX Object Session Border ===
Please migrate to '''Reverse Proxy''' and '''[[Reference13r3:Concept_Third_Party_Phones]]'''.

== Resources Considerations ==
New firmware always has more features which in turn requires more resources. Growing firmware will thus consume both more flash and RAM for sure. A given system configuration will run flawlessly after a firmware largely only if there is still enough memory left after boot.

Standard configurations which are according the specs will run on all supported hardware. However, unusual configurations may not. It is a good idea to examine both flash and RAM memory left on high load situations in your existing configuration to see if there is enough resources left for an upgrade. Please find details in Reference:Device Health Check.

=== RAM ===
As a rough rule of thumb, a 14r1 release will consume the same amount of RAM compared to a v13r3 firmware.

=== Flash Memory ===
As a rough rule of thumb, a v14r1 release will consume ~ 1.8 MB more flash memory compared to a v13r3 firmware.
New firmware comes with new code for new features which consumes more flash memory for the firmware image. For this reason, devices may run out of flash memory during upgrade to v14r1. Here is the recommended procedure for upgrade on such devices:

* save entire configuration
* reset to factory defaults
* load saved configuration (this will reorganize the flash memory usage)
* upgrade to new firmware

When there is still not enough flash memory available to store the new firmware (Web GUI ends up in a ''Firmwareupdate failed:no space'' / Update client end in a ''Error 0x00130001 Major FLASHMAN0 no space'' event) please open a support case with your current configuration file.

Howto14r1:Firmware Upgrade V13r3 V14r1

2023-10-19T14:42:32Z

Lme: /* Application Platform and its applications */

{{FIXME|reason=Preliminary working draft}}
== Applies To ==
This information applies to:

* All 14r1 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 14r1, see [[Howto:Firmware Upgrade]]

== Changes visible to end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a 14r1 upgrade, as the change will be visible/audible in the behaviour of the application/device.
=== Softphone/Phone App UI changes ===
* Dial-pad is now a new tab in the navigation.
* On Smartphones, the Navigation is in the bottom.
* Call button is removed from the searchbar. Calling only via the search results.

== Application Platform and its applications ==
===Apps new in 14r1===
New Apps will not be installed automatically by the 13r3 to 14r1 upgrade. The installation description of new 14r1 apps is usually in the concept article. New apps are:
;Search App
* The app is immediately available on the PBX (no configuration is needed). In a new V14r1 configuration the Install provides all Users with this Search App via the "Config User"-Template. If the same configuration is required on an upgraded config, the Search App ("search") can be ticked in the "Config User" template.
;TechAssist
* Application for quality assurance and improvement of systems by collecting static and runtime information. For details refer to [[Reference14r1:Concept_App_Service_TechAssist | the concept article]].

== Configuration Changes ==

== Removed in 14r1 ==
The following software is no longer included in 14r1.
=== myPBX ===
This includes the following components
* myPBX webclient
* myPBX for Windows
* myPBX for iOS
* myPBX for Android
Please migrate to '''innovaphone myApps'''.

===Widgets===
The Widgets were based on the myPBX interfaces that have been removed. Please migrate to the '''Contacts Widget App'''.
===WebRTC toolkit===
The WebRTC toolkit was based on the myPBX interfaces that have been removed.
Please use the current interfaces and libraries described in the '''[https://sdk.innovaphone.com innovaphone SDK]'''.
=== Windows Softwarephone ===
Please migrate to '''innovaphone myApps for Windows''' and the '''Softphone App'''.
===PBX Object Settings ===
The object provided the PBX Settings App that was used to configure dynamic group memberships in myPBX.
Please use the '''Profile App''' instead.

===PBX Object ICP ===
Please use the integrated presence features of the '''innovaphone PBX''' instead.

===Service Call-Lists ===
This service implemented call lists for myPBX on the local CF card.
Please use the '''Reports App''' instead.

== Deprecated in 14r1 ==
The following software is based on legacy technology with no further development and limited maintenance and support.
We strongly recommend migrating to our successor products that are fully compatible with 14r1 and myApps technology.

=== Linux Application Platform (v10) ===
Please migrate to the '''innovaphone App Platform''' for 14r1 installations.

=== innovaphone Faxserver (v10) ===
Please migrate to the '''Fax App''' for 14r1 installations.
=== innovaphone Reporting (v10) ===
Please migrate to the '''Reports App''' for 14r1 installations.
=== innovaphone Exchange (v10) ===
Please migrate to the '''Calendar App''' for 14r1 installations.
=== Operator (v9) ===
Please migrate to the '''Switchboard App''' for 14r1 installations.
=== innovaphone Voice Recording 2014 ===
Please migrate to the '''Recordings App''' for 14r1 installations.
=== PBX Object External UC ===
Existing configurations still work. But new configurations can't be done using the advanced UI anymore.

Please use the integrated '''UC''' and '''federation''' features of the '''innovaphone PBX'''.

For presence synchronization with other systems we recommend using
* '''innovaphone myApps Connector for Microsoft 365'''
* '''Connector for kuando®'''
* '''Calendar App'''
=== PBX Object Session Border ===
Please migrate to '''Reverse Proxy''' and '''[[Reference13r3:Concept_Third_Party_Phones]]'''.

== Resources Considerations ==
New firmware always has more features which in turn requires more resources. Growing firmware will thus consume both more flash and RAM for sure. A given system configuration will run flawlessly after a firmware largely only if there is still enough memory left after boot.

Standard configurations which are according the specs will run on all supported hardware. However, unusual configurations may not. It is a good idea to examine both flash and RAM memory left on high load situations in your existing configuration to see if there is enough resources left for an upgrade. Please find details in Reference:Device Health Check.

=== RAM ===
As a rough rule of thumb, a 14r1 release will consume the same amount of RAM compared to a v13r3 firmware.

=== Flash Memory ===
As a rough rule of thumb, a v14r1 release will consume ~ 1.8 MB more flash memory compared to a v13r3 firmware.
New firmware comes with new code for new features which consumes more flash memory for the firmware image. For this reason, devices may run out of flash memory during upgrade to v14r1. Here is the recommended procedure for upgrade on such devices:

* save entire configuration
* reset to factory defaults
* load saved configuration (this will reorganize the flash memory usage)
* upgrade to new firmware

When there is still not enough flash memory available to store the new firmware (Web GUI ends up in a ''Firmwareupdate failed:no space'' / Update client end in a ''Error 0x00130001 Major FLASHMAN0 no space'' event) please open a support case with your current configuration file.

Reference8:TAPI Service Provider

2023-08-11T12:57:18Z

Lme: /* Download */

The ''innovaphone PBX V8.0 based TAPI Service Provider'' (TSP) is an enhanced version of the [[ Reference7:Unified Win32 and x64 TAPI Service Provider | previous TSP version ]] that takes advantage of the [[ Reference8:SOAP API | new SOAP features ]] provided with version 8 PBX firmware. It implements - like the previous versions - TAPI Version 3.0 without MSP (Media Service Provider).

The [[Reference7:Unified Win32 and x64 TAPI Service Provider| previous TSP ]] still must be used for V7 PBX systems.

This article describes how to install and use it as well how to configure the PBX in order for the TSP to work properly.

==Applies To==
This information applies to
* innovaphone PBX V8.0 based TAPI Service Provider, Build 8001 and later
* innovaphone PBX V8 and later (that is, this Service Provider runs with PBX Firmware V8 and later)

==More Information==

=== Enhancements ===
; Support for V8 firmware [[Reference8:Administration/PBX/Objects#Devices | devices]] : Each user object device is represented as a TAPI line (all sharing an identical address, the objects extension a.k.a. ''Number'' property). This now allows to select individual registration devices when multiple devices are registered with the same PBX. Please note that in V8, [[ Reference8:Administration/PBX/Objects/Edit_Forks | mobility devices ]] are not shown and thus not represented by TAPI line device. This was introduced in V9 only.
; Support for presence based lines : These are TAPI lines shown which reflect the users presence state. Presence state ''open'' is mapped to a TAPI device status ''in service''. Presence activity ''on-the-phone'' is mapped to a virtual call in state ''connected''.
: '''NB''': V8 PBX Firmware did set presence activity ''on-the-phone'' for each user object having a call. Unfortunately, as this does create performance issues, this behaviour has been removed from V9 PBX Firmware. The ''presence line'' feature may be useless with V9 PBX when the application did rely on this particular V8 PBX behaviour.

===System Requirements===
The TSP will install on any Windows 32bit and x64 platform down to Windows XP/Server 2003. For older systems, you must use a deprecated [[Reference7:TAPI_Service_Provider | previous TSP version]]. For systems running PBX firmware version 6 or earlier, you must use the even older [[Reference:TAPI_Service_Provider | version 5 based TSP]]. Note that there is no x64 version of the version 5 TSP!

The TSP needs to maintain parallel connections to each individual PBX in the system. For larger systems (i.e. systems with a huge number of PBXs), this may create substantial load to the underlying windows machine. The number of parallel activities scheduled by the TSP is thus limited as a function of the available main memory and number of processors. In particular, a maximum of 20 activities per available processor is allowed (up to build 8088, the limit is 60/processor for later builds). If this limit is exceeded, the TSP will issue performance warnings of class WARNINGS in the TSP log file and system TAPI performance will be poor. Use a more capable machine then.

Microsoft Windows operating system version for desktop clients (as opposed to server systems) limit the number and performance of TCP/IP connections. This may lead to bad performance or occasional request failures. We generally recommend to use server operating systems for 3rd party TAPI installations thus.

No special PBX licenses are required to use the innovaphone TSP.

=== Download ===
The TSP will be available on the tab ''Software'' in the [https://store.innovaphone.com/ Store].

===Installation===
Windows cannot run a Win32 TSP on an x64 platform (although it can run Win32 applications on such platforms). This is why there are 2 versions of the setup, the x64 installer (<code>setup64-release.msi</code>) and the Win32 installer (<code>setup32-release.msi</code>.

The ''release'' setup packages provided will install the retail version. This is recommended for production purposes but provides no debug options whatsoever. To track down possible problems, support may instruct you to install the debug version.

The TSP may be installed on each machine where a desired TAPI based
application is to be run. If for example, Outlook is to be used, then
each client PC running Outlook may have the TSP installed. Although
this is typical for a 1st party configuration, all clients may have full
3rd party functionality, that is, they may control all existing lines.

As an alternative, the TSP can be installed on a single machine and a
3rd party TAPI server product (such as the IXI-Call Server available as
a separate product) may be used to provide the network clients with a
TAPI interface. Also, Microsoft’s Remote TAPI Server should work but is not being tested, so you use it on your own risk.

To install,
* select and download the <code>setup32-release.msi</code> install packages on 32bit platforms or the <code>setup64-release.msi</code> install package on 64bit platforms.
* double-click the install package to launch the installer
[[Image:Unified Win32 and x64 TAPI Service Provider - zipcontent.png]]
* accept the license agreement
* select the target folder
* complete the installer

When the installer has copied all files to the target machine, you need to add the TSP to the machine's TAPI system
* open the ''Telephone and Modem'' control panel
* Switch to the rightmost tab (''Extras'')
* Click on the ''Add...'' button
[[Image:Unified Win32 and x64 TAPI Service Provider - Control Panel Add.png]]
* Select the innovaphone TAPI provider driver
* Fill out the configuration dialogue
* Install the provider by clicking ''OK''

==== File Organization ====
Windows forces all TAPI service provider files to reside in Windows' ''System Folder''. This is the <code>system32</code> folder in your windows install directory (usually <code>C:\windows\system32</code>), even if you are running an x64 platform! The installer will thus copy these files (<code>tsp8.tsp</code> and <code>tsp8UI.dll</code>) in to this directory. All other files however will be copied to the <code>innovaphone AG\innovaphone® PBX V8 TAPI Service Provider</code> folder underneath your systems ''Program Files Folder''.

The subdirectories <code>Debug</code> and <code>Logs</code> are created. <code>Debug</code> contains the driver's debug version, <code>Logs</code> will receive the log files when a debug version is used.

On x64 platform systems, the Win32 version of the configuration DLL (<code>tsp8UI.dll</code>) will be installed to the windows ''Windows on Windows64 System Folder'' (<code>SysWOW64</code>).

====Upgrading to a newer Version====
When you attempt to upgrade the TSP from a previous version, the Windows
installer will first remove any previous installation. When the new
software is installed then, the TSP will be installed again into the
TAPI system.

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

====Upgrading from the old Win32-only Version====
If you upgrade from the older Win32-only versions of the TSP (soap-appl/tapi/7.00 or soap-appl/tapi/5.00), you must first remove the old TSP from ''telephone and modem'' control panel and uninstall the old product from the ''Software'' (or ''Programs and Functions'') control panel.

When you upgrade from the old V7 64-bit TSP (soap-appl/tapi/7.00-64), you should first update this older version to the latest build available.

This procedure ensures that during the upgrade your TAPI lines retain their internal identifiers and thus their meaning in your TAPI application's configuration.

==== Uninstalling the TSP ====
To uninstall the TSP proceed as follows
* Remove the TAPI driver from the TAPI system using ''Telephony and Modem Control Panel''
* close ''Telephony and Modem Control Panel''
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* remove the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

You will notice that Windows may fail to remove the driver files from the ''Windows System Directory''. To clean up remove <code>tsp8.tsp</code> and <code>tsp8UI.dll</code> from the <code>system32</code> folder as well as - on x64 systems - from the <code>SysWOW64</code> folder.

Also, if you did file tracing, any remaining debug files in the <code>Logs</code> folder are left over and need to be removed manually.

The TSP will create some entries in the windows registry which will not be removed on uninstall. It is recommended to leave these entries as is. Only if you are sure you will never install the TSP again on this system or you are sure you will never use it with the PBX installation you used so far, you may want to delete them from the registry.

==== Rolling out First Party TSPs to multiple PCs ====
Normally, when multiple users require CTI and hence TAPI functionality, the best way is to use a server based, multi-client 3rd party CTI application. This will share all functions among all client PCs. If this is not an option, e.g. because the TAPI application in use does not support it, you may want to consider using Microsoft's TAPI Server and remote TSP. See Microsoft's [http://technet.microsoft.com/en-us/library/cc786297%28v=ws.10%29.aspx Telephony service providers overview] and [http://technet.microsoft.com/en-us/library/cc770373.aspx Manage Telephony Servers] documents.

If you still want to use the native innovaphone TSP on a number of PCs (instead of once on a server), you can roll out the TSP using some of the [http://support.microsoft.com/kb/816102/EN-US software deployment schemes Microsoft Server provide]. In such a case, you will likely want to deploy identical configurations to all these PCs. While this theoretically can be done by distributing registry settings, there will be a problem with the PBX access credentials. These are stored in encrypted format in the registry and can only be decrypted on the PC on which they have been set. That is, deploying such registry settings to other PCs will result in a non-functional setup.

To work around this problem, you may store the credentials in clear text in the registry. To do so, you would put the ''Password'' in a REG_SZ value named <code>admin1-free</code> and the ''Account'' into a REG_SZ value named <code>admin2-free</code>. If such a value is found in the proper place in the registry, the values configured using the telephony control panel are ignored.

[[Image:TAPI Service Provider-tsp8-nocrypt.png]]

'''Keep in mind that having credentials in clear in the registry presents a security risk!'''

This feature is available in build 8079 and later.

=== Upgrade from Build 8164 or earlier ===
From build 8165, the TAPI configuration has been moved to a different registry location. This has been done because latest windows versions (namely, Windows 10) do not allow the TSP to access registry information in the location used so far (<code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>). To work around this issue, it is now stored in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>.

The TSP configuration dialogue however runs with user privileges (as opposed to the TSP which runs with limited service privileges). It can therefore read the old configuration information and copy it to the new location. From build 8165, the configuration dialogue will thus copy any old configuration information to the new location when it is opened. When you upgrade an existing installation and open the configuration dialogue, you will see no change. However, when the configuration is saved, it is then present in the new location.

'''To upgrade an installation from build 8164 or earlier (that is TAPI 'V8 TAPI Service Provider (32 and 64bit) - hotfix14'' available in the ''V8 applications hotfix20'' package or earlier), proceed as follows:'''
* stop the telephony service (e.g. <code>net stop tapisrv</code>)
* install the new TSP
* open the TSP configuration dialogue
* verify the configuration data
* save the configuration
* (re) start your TAPI application

If you fail to migrate the configuration as described, the TSP will start, but not work!

===Configuration===
The TSP configuration dialogue looks like this:

[[Image:Unified Win32 and x64 TAPI Service Provider - Config UI.png]]

* The ''VERIFY'' button will verify the configuration. Note that the ''Username'' drop down list will only be populated after a successful verify.
* The ''OK'' button will save the configuration.
* The ''CANCEL'' button will quit the configuration without saving any changes. If it is the initial configuration while you add the TSP via the telephone and modem control panel, the TSP will not be added

TAPI talks to the PBX using [[Reference7:SOAP_API | SOAP ]] which in turn uses HTTP for communication. Both secure (https) and non-secure (http) communication is supported. In any case, HTTP basic authentication is used.
To be able to connect to the PBX, the TSP needs to know proper credentials to use during HTTP authentication. These are referred to as ''PBX Account'' and ''PBX Password''. Also, a suitable ''TAPI User'' must be selected.

==== Controlling the Line Devices handled by TAPI ====

TAPI connects to your PBX as a PBX user referred to as ''TAPI User''. It will see all PBX objects that are members of groups in which the ''TAPI User'' is an active member. If the ''TAPI User'' is not an active member in any group, TAPI will see the ''TAPI User'' object only. This may be useful in a [http://en.wikipedia.org/wiki/Telephony_Application_Programming_Interface 1st party TAPI scenario]. PBX objects are represented as TAPI lines.

The PBX object you use as ''TAPI User'' needs to have at least ''Viewing only'' [[Reference:Administration/PBX/Objects/Edit Rights | PBX user rights]]. Its ''Long Name'' property is used as ''TAPI User Username'', its ''Name'' property as ''PBX Account'' and the password as ''PBX Password''. This is why the PBX object used as ''TAPI User'' must have a password configured.

===== 1st Party Configuration =====
In a 1st party scenario, the TSP will only work on a single PBX object. This will typically be a user's phone and thus the user itself will be used as the ''TAPI User''.

[[Image:Unified Win32 and x64 TAPI Service Provider - FirstParty.png ]]

In such a configuration the TSP is typically installed on the users PC and the CTI software is accessing TAPI directly (such as e.g. Microsoft Outlook does).

The TSP configuration dialogue will check for the number of lines seen. If it is only one, then it will issue a warning message:

[[Image:Unified Win32 and x64 TAPI Service Provider - OnlyOne.png]]

This is because 3rd party configurations are much more common and this situation often indicates a configuration problem. In a first party configuration, you can safely ignore this message.

===== 3rd Party Configuration =====
In a 3rd party configuration, the TSP will work with multiple PBX objects.

[[Image:Unified Win32 and x64 TAPI Service Provider - ThirdParty.png]]

Typically, you will share a single TSP instance on a server system for use by several users on their desktop PCs. This is done by virtue of a ''TAPI Server''. There are various TAPI server products available on the market, including but not limit to the Estos ProCall product and the remote TAPI server included in Microsoft Windows server operating systems.

In this scenario, it is recommended to create a pseudo PBX user object for use as the ''TAPI User''. This pseudo user is often called <code>_TAPI_</code>. You would create a dedicated group to control the list of PBX objects the TSP creates a line device for. This group is often called <code>tapi</code>.

==== Selective Call Forwards ====
Many CTI applications support distinct call forwards for internal and/or external calls. The TSP will translate such requests to a call forward on the PBX which has the [[Reference7:Administration/PBX/Objects/Edit_CFs | ''Only'' or ''Only not'' property]] set to the number of the trunk line. For this to work, it needs to know this number. To know the number, the trunk line PBX object must be seen by the TSP (see above). If this is not the case, the TSP configuration dialogue will issue a warning:

[[Image:Unified Win32 and x64 TAPI Service Provider - NoTrunk.png]]

In a vanilla first party scenario, this is obviously not the case. If you don't care, you can safely ignore this issue. Attempts to set such call forward will be rejected then as ''operation unavailable''.

In a Master/Slave PBX scenario where there is no Trunk Line object on the Master PBX, but only on the Slave PBXs, a workaround is required to suppress the warning and enable selective call forwarding on the Slave PBXs. In this case, create a dummy "Trunk Line" object on the Master PBX with the same extension number used by the "Trunk Line" objects on the Slave PBXs (usually 0).

==== Multi Site Configuration ====
In a system with multiple PBXs, the TSP needs to connect to each of the individual PBXs.

[[Image:Unified Win32 and x64 TAPI Service Provider - MultiSite.png]]

In this case, you would specify your master PBX as ''PBX Master''. There is no need to configure the complete PBX tree to the TSP as it is determined dynamically on runtime by analysing the PBX/Node objects in the master PBX and their registration status. If a registered PBX is found, this PBX is added to the list of active PBXs and a new connection is established. The PBX tree is built and maintained dynamically. A reconfiguration or restart of the TSP is not required on changes thus.
For this to work

* the PBX object used as ''TAPI User'' must exist in each PBX with same properties (including name and the password). You may want to use <code>_TAPI_</code> as ''Name''/''Long Name''. This object must be ''active'' member in a group (which you may want to call <code>tapi</code>). A password must be set. The object must have at least ''Viewing only'' rights
* the slave PBX-objects (or in older firmware versions the slave PBX Node-objects) must be visible to the TSP (that is, must be non-active member of the group the ''TAPI User'' object is an active member of, e.g. <code>tapi</code>) so that the slaves are made known to the TSP.

In a replicated scenario, you would create a ''TAPI user'' as recommended above and [[Reference8:Administration/PBX/Objects#Objects_with_empty_node_or_PBX | leave the ''PBX'' and ''Node'' properties empty ]]. This user should then be used as both ''PBX Account'' and ''TAPI User Username'' in the TAPI configuration dialog.

''Further relevant settings'':

You can disable slave detection by checking ''Do not monitor slaves'' property in the TSP configuration dialogue.

TAPI maintains an ''address'' property per line device. This usually is the lines extension. In a multi site configuration, the address property will be set to the ''Number'' property of the node the respective PBX object is configured in, plus the ''Number'' property of the object itself. So if an object has ''Number'' <code>42</code> and lives in node <code>801</code>, then its correspondence line device will have address <code>80142</code>. By checking the ''Use pure node extensions'' property in the TSP configuration dialogue, you change the algorithm so that only the objects own ''Number'' is used (<code>42</code> in our example).

==== Standby Configurations ====
In a system with standby PBX for the master PBX, you need to specify the ''PBX Standby'' IP address. This will be connected if the master is unavailable. Note that there is no need to explicitly configure slave-standby PBXs.

==== Working with multiple, unrelated PBXs ====
When working with multiple, unrelated PBXs (that is, PBXs that do ''not'' form a PBX tree as slaves and masters do), the TSP cannot derive the list of PBXs to track from the registration status. To support such a configuration, you will need to configure the extraneous master PBXs manually using regedit. Please note that using regedit may harm your system and may even cause inability to boot!

To find and edit the right registry entries, proceed as follows:

* open the key <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>
* open its subkey <code>Device</code>''n'' where ''n'' is the provider id of the installed innovaphone TSP (for builds before 8164 only)
* Open the <code>FQDN</code> key and add all extra PBXs
* For those PBXs that have a standby PBX, add a value to the <code>StandbyFQDN</code> key (please note: these are parallel lists. So master and standby need to have the same respective index in the <code>FQDN</code> and <code>StandbyFQDN</code> value lists)

The standard configuration UI will not show these extra values. However, it will also not touch them. So even if you use the standard UI to edit, only the first value in the lists will be changed and the remainder left unchanged. You can thus safely use the standard UI to edit all other values. As with multi site configurations, all PBXs need to be accessible using the same ''TAPI User''.

Please note that this method is deprecated and will likely be removed from future versions of the TSP.

==== Setting the Line Device Name ====
The TSP will derive the line device's name from the properties of the respective PBX object. By default the name will be the objects ''Long Name'' followed by the name of the PBX the user ought to register with in parentheses. So if the users ''Long Name'' is <code>Foo Bar</code> and the registration PBX is <code>branch1</code>, the line device will be called <code>Foo Bar [branch1]</code>. You can specify a different pattern by changing the ''TAPI Line Names'' property of the TSP configuration dialogue. The following replacement characters are available:

{|
|+
| Meta || Replacement
|+
| %c || The objects ''Long Name'' (cn)
|+
| %C || The objects ''Long Name'' (cn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Long Name''
|+
| %d || The objects ''Display Name'' (dn)
|+
| %D || The objects ''Display Name'' (dn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Display Name''
|+
| %h || The objects ''Name'' (h323 alias)
|+
| %H || The objects ''Name'' (h323 alias) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Name''
|+
| %t || The ''Name'' of the ''Device'' the line represents
|+
| %T || The ''Hardware Id'' of the ''Device'' the line represents (from build 8181)
|+
| %e || The objects extension (e164)
|+
| %E || The objects extension (e164) prefixed with the objects node number
|+
| %N || The line address as reported to TAPI
|+
| %n || host name (of master pbx)
|+
| %p || ''':'''''port-number'' (of master pbx's http access, empty if 80)
|+
| %P || raw port number of master pbx
|+
| %u || url-like user name ('''''user''@''host''''')
|+
| %U || user url as per draft-levin-iptel-h323-url-scheme-04 ('''h323:://''user''@''host'':''port''''')
|+
| %X || the PBX name the user is registered with (note that using this pattern may result in a change of the name when a standby situation occurs)
|+
| %x || the PBX name the user is reported by (note that using this pattern may result in a change of the name when the users ''PBX'' attribute changes)
|}

The default pattern is <code>%C (%x)</code>.



==== Miscellaneous Flags ====
; Show full E164 Numbers : when set, the TSP will announce the full calling number from the root when indicated by the PBX in the TAPI ''calling party name'' attribute. The number will be appended to the calling name with a <code>@</code>.
; Do not show parked Calls : will hide parked calls from the TAPI application (as some get confused and don't know how to handle them)
; Map PBX Devices to Lines : if set, the TSP will create one TAPI line for each individual [[Reference9:PBX/Objects#Devices|PBX device]] configured in a user object. See [[#Enhancements]] above. If you do not set this flag, see [[Support:How should TAPI line device be registered?]]
; Map Presence Status to TAPI Lines : if set, the TSP will create one extra TAPI line for each PBX device object. See [[#Enhancements]] above.
; No special Disconnect Behaviour : normally, lines monitored by TAPI will behave slightly different when a call is terminated. With no TAPI on the line, the call will be disconnected immediately (from a PBX point of view). In cases where the phone would play some tones after termination of the call (e.g. a busy tone when the call has never been connected to the far end), this state is simulated by the phone and not visible to TAPI. Therefore, it is not possible to use TAPI functions on this call any more (as it in reality does not exist any more). When this flag is set, monitored lines will not be treated specially. Available from hotfix 6. To prevent the IP-Phone to play any tones after the call is disconnected, the phone preferences option '''Go onhook if final call is released by remote side even if handset is lifted''' can be activated. This is the feature of the IP-Phone is useful in a e.g. call center at agent phones and can be configured here [[Reference11r1:Phone/Preferences]].
: To prevent an innovaphone IP-Phone from playing any tones after a call is disconnected, the phone preferences option '''Go onhook if final call is released by remote side even if handset is lifted''' can be activated. This feature is useful for agent phones in a call center for example and can be configured in [[Reference11r1:Phone/Preferences]]

===Trouble Shooting===
The TSP will (from build 8095) write messages of type INFO (''informational messages'') or WARNING (''Warnings/Errors'') to the windows event log. Such events are always logged to the application log and event source is the provider name (''innovaphone® PBX V8 TAPI Service Provider'').

==== Turning on Debugging ====
There are 2 versions of the TSP, debug and retail, which are both copied to the machine during setup. The retail version is installed into the system directories, whereas the debug version is stored in a separate directory. This is available through a short cut in the Start menu.

The TSP can produce a number of debugging messages which can be helpful to debug issues (in both ''retail'' and ''debug'' builds). By default, debug messages are written to the systems debug buffer mechanism (using OutputDebugString()). Such messages can be examined using standard debugging tools, such as for example <code>dbgview</code> which is [http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx available from Microsoft].

Debug messages have a class associated with it and the amount of messages written can be controlled by enabling or disabling specific classes. This is done by setting a bitmask in the registry value <code>TraceLevel</code> in the <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/> key.

The easiest way to set the TSP's debug level is with the ''TSP Control'' utility (''tsptray.exe'') which is installed with the TSP.

The available classes include

{|
| Bit in <code>TraceLevel</code> || Class
|-
| 0x00000001 || Minimum tracing
|-
| 0x00000002 || TAPI api traces
|-
| 0x00000020 || Basic telephony object creation/destruction
|-
| 0x00000040 || Thread creation/destruction
|-
| 0x00000080 || Request creation/destruction
|-
| 0x00000100 || call related messages
|-
| 0x00000200 || Call id map
|-
| 0x00000400 || Warnings/Errors
|-
| 0x00000800 || Worker thread execution
|-
| 0x00001000 || Full lock/unlock notifications
|-
| 0x00002000 || Win32 Critical section create/destroy
|-
| 0x00004000 || Agent proxy support
|-
| 0x00008000 || constructor/destructor debug
|-
| 0x00010000 || development debugs
|-
| 0x00100000 || verbose debugging
|-
| 0x00200000 || SOAP trace
|-
| 0x00400000 || SOAP message dumps
|-
| 0x01000000 || ATL debug
|-
| 0x02000000 || line related messages
|-
| 0x04000000 || informational messages
|-
| 0x10000000 || dump call infos
|-
| 0x20000000 || dump PBX infos
|-
| 0x80000000 || output log messages to file
|}

If <code>TraceLevel</code> is not set, it defaults to (hex) <code>04000400</code> in retail builds and to (hex) FFFFFFFF in debug builds. A nice value to use is (hex) <code>92200580</code>. The <code>TraceLevel</code> can be changed during runtime of the provider (it may take up to 10 seconds though for the setting to take effect). In normal scenarios there is no need to install the debug version.

Both ''informational messages'' and ''Warnings/Errors'' are always turned on (from build 8095).

: A problem has been reported on Server 2008 x64 systems which may also apply to others. On such systems, the value of <code>TraceLevel</code> may be reset to its default every 10 seconds. A workaround is to change the account the Telephony service is running in from its default (usually ''Network Service'') to e.g. ''Local System''.

===== Crash Dumps =====
From build 8063 the TSP will write crash dumps to the log directory (usually something like <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8 TSP\Logs</code>) in case of a trap. In release installs, these are not very useful. For debug builds though, they include helfpul information. Please provide these files (the can be zipped to a great extent) to support if requested. A crash dump file will be called something like <code>TSP8build-hour#minute-day.month#seqnr.dmp</code>.

===== Forcing a Crash Dump =====
In rare cases, it may be useful to force a TAPI crash for debug reasons. This can be done by issueing a <code>lineMakeCall</code> with called number <code>0815</code>, called-subaddress <code>4711</code> and called-name <code>!crash!</code> or simply calling <code>0815|4711^!crash!</code> from phone.exe.

==== Saving Log Messages to a File ====
The <code>0x80000000</code> value is special, as it does not denote a message class. Instead, it turns on log file writing, both in retail and debug versions. For this to work, the registry value <code>DoTraceFile</code> must be set to <code>1</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/> when the TSP starts. If this value is not present, it defaults to <code>1</code> in both retail and debug builds. Setting it to 0 disables log file writing regardless of any other setting. This may save some CPU cycles for installations with a real large number of lines.

The TSP will keep 24 log files (a days worth) by default. This value can be changed using the <code>NumLogFiles</code> value in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>. Older log files will be removed. Also, when the TSP shuts down, it by default will remove all log files it created so far. However, any TSP will only remove log files created by itself. This ensures that if the TSP or the system terminates prematurely, the log files will be kept even if a new instance is started and terminated later on. Form TSP V8 hotfix 8 on, this behaviour can be tweaked by setting the DWORD registry value <code>KeepLogFiles</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>:
{|
| 0 || default || remove all log files on termination
|-
| 1 || || keep the last ''n'' log files (depending on <code>NumLogFiles</code>) on termination
|-
| 2 || || keep all log files
|}

Larger systems (500 monitored lines and more) can slow down considerably when using the debug drivers.

==== Installing the Debug Version ====
To install the debug version, you first install the retail version as outlined above. You then copy the debug driver files from the <code>Debug</code> directory to your windows system directory <code>system32</code>. You may want to use the shortcut to the <code>Debug</code> folder which has been installed to the start menu for convenience.

For the copy to work, proceed as follows
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* copy the debug driver files to your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>.(if the copying fails, we recommend to deactivate the telephony service. But don’t forget to reset it to automatically if you are done copying). Overwrite the existing files: <code>installer.dll, installer.pdb, TSP8.pdb, TSP8.tsp</code>
* if the copy does not succeed or the debug driver is not shown n the modem control panel after, it might be that a TAPI application re-starts the windows telephony before you actually to the copy. If so, you can set the ''Startup type'' of the Windows ''Telephony'' service to <code>Disabled</code> instead of ''Manual'' in the services control panel (''services.msc''). You can then ''Stop'' the services, copy the file and finally set the services mode back to <code>Manual</code>

When you open ''Telephony and Modem Control Panel'' again, you should notice that the TSP driver name has changed to the debug version.

==== Switching back to the Retail Version ====
To go back from the debug to the release version, proceed as follows:
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* delete the debug driver files from your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>
* repair the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

Please note that simply re-installing the driver from the original .msi without removing it from the system directory will not work.

===References===
The test applications provided with this setup comes from [http://www.julmar.com Julmar Technology Inc].

=== Limitations ===

Please note that there currently is a limitation to 2000 users being in
all active groups of a particular user. Thus, you cannot configure more
than 2000 users to be handled by TAPI on a single PBX. This is a PBX
limitation (and applies for all PBX groups).

TAPI has a flat line model. That is, all line numbers (aka
''extensions'') are considered to live in a single name space. As a
result, lines with identical numbers cannot be distinguished in TAPI
(although they can exist). All extensions in all nodes of a PBX
numbering tree are represented as TAPI lines. When the TSP works with a
PBX that implements a hierarchical numbering tree, then some lines may
receive identical numbers (their node-local extension which may overlap
between nodes depending on the setting of the ''Use pure node extensions'' property). When a TAPI application uses these numbers to initiate
calls to such lines, the call will work or not work depending on the
calling lines position in the numbering tree (that is, lines within the
same node as the called line will be fine, others may fail).

The PBX's SOAP interface (on top of which the TSP is built) has no primitives to initiate a directed call pick-up based on a target number. The TSP will reject such requests with ''Operation not available''. Pickup by name (which is understood as a group name) or unspecific is supported though.

==== Citrix Environments ====
What happens is that all Citrix sessions share the same TAPI driver. This allows all users in the Citrix sessions to select "their" line from the set of all TAPI lines. Then everything works as desired. It is important to note that theoretically one user can select the line of another user.
You can use the "Microsoft Remote TAPI Server", to implement access rights for lines for separate Citrix sessions.

===Known Problems===

* The TSP is not tested with Microsoft’s Remote Tapi Server. While some installation have reported this to work fine, others have encountered problems. This scenario is not supported by innovaphone
* The TSP will read its configuration when it is loaded by the system. Thus, configuration changes require a re-load of the TSP. Unfortunately, there is no reliable way to force the system to unload the TSP, so you may have to reboot the system for changes to take effect. See the [[ Howto:Troubleshooting_the_TAPI_service_provider | TAPI trouble shooting article ]] for details
* The TSP will use HTTP basic authentication to talk the PBX. So if you disable basic authentication in the PBX's configuration, the TSP will not work. It is recommended to use HTTPS
* TAPI requires the TSP to assign a unique id to each line device. This ID must not change between re-boots of the system or between upgrades of the TSP. This is done by keeping a persistent table in the windows registry (in the <code>leineeGUIDs</code> subkey of <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>) that maps the PBX's line GUID to a fixed integer value (known as ''permanent line id'' in TAPI speak). This key is retained even on uninstall. To get rid of it, you must remove it manually
* Microsoft installer fails to remove driver files installed to the windows system folder. This is why the TSP driver files are still present after an uninstall of the software. To get rid of them, remove <code>TSP8.tsp</code> and <code>TSP8UI.dll</code> from both ''%windir%''<code>\system32</code> and ''%windir%''<code>\sysWOW64</code>
* From Version 9, hotfix 1, the PBX firmware will not list objects tagged as [[Reference9:PBX/Objects#General_Object_Properties | ''hide from LDAP'' ]] in the result of a [[Reference9:Concept_SOAP_API#UserInfo.5B.5D_FindUser.28string_v501.2C_string_v700.2C_string_v800.2C_string_cn.2C_string_h323.2C_string_e164.2C_integer_count.2C_integer_next.29 | FindUser() ]] call. As a result, such objects will not be shown in the TAPI configuration dialogue ''Username'' drop-down. If you want to use such an object as ''TAPI User'' you can simply type in the name without selecting it from the drop down.
* Sometimes, setting configuration with ''TSP Control'' (not the telephone control panel dialogue) does not work due to windows' ''User Access Control (UAC)'', see [[Howto:TAPI_TSP_Control_Windows7]] for Details
* Various users have reported that first party TSP installations do not work reliably with Microsoft Outlook. Symptoms reported are spurious error pop-ups from Outlook although there was no real problem. We do not recommend first party installations anyway (see [[#Rolling_out_First_Party_TSPs_to_multiple_PCs]] for a reasoning), but these issues are related to Microsoft Outlook only. No such problems have been reported with other first party TAPI applications. Consider using solutions like Estos ProCall instead.
* The number of parallel threads used within the TSP is limited to max. 60 per CPU. As each connected PBX (amongst other things) is handled by a separate thread, if you have a large number of PBXs connected and only have a single CPU, you may run out of threads, resulting in a WARNING messages ''about to spawn new workerthread (n requests, m threads) -- but limit l exceeded''. This usually happens when you run the TSP on a virtualized platform such as vmWare and only dedicate a single CPU. Ignoring this warning results in sluggish behaviour.
* The TSP can work with dynamic PBXs too. However, the TSP needs to determine the slave PBXs IP addresses from the master. If the slave is a dynamic PBX and it is hosted on the same device as the master and it is registered to the master using 127.0.0.1, the TSP will only learn the 127.0.0.1 as the slave's IP address. Of course, connection to the slave PBX will fail then.

==== TAPI Operation with 3rd party Phones or innovaphone Phones registered with SIP ====
Various TAPI functions rely on use of the [[Reference:Remote Control Facility|Remote Control Facility]] message. This message is not supported in 3rd party phones and also not fully supported in innovaphone Phones when they are registered to the PBX using SIP. Full TAPI functionality is thus only available for innovaphone phones registered to the PBX using H.323.

Known Limitations:
* Accepting an incoming call (lineAnswer)
* Automatic initiation of an outgoing call in handsfree mode (instead, the calling phone first rings and starts the outgoing call upon of-hook)
* toggle between 2 calls active on a phone (lineSwapHold)
* initiation and termination of a 3PTY (lineCompleteTransfer with mode LINETRANSFERMODE_CONFERENCE, lineDrop on a conference call)

==== TAPI on Windows8 / Server 2012 ====

Windows8 doesn't let you disable ''User Access Control'' (UAC) completely. This has the disadvantage that ''TSP Control'' (tsptray.exe) cannot change system registry entries, which it needs to do to e.g. change debug settings for the TSP.

There are 2 ways around it:
# use the hidden ''Administrator'' account on Windows 8
# elevate the tsptray.exe application

To use the elevated ''Administrator'' account on Windows 8 you first need to un-hide it:
* log in to an account with administrator rights
* use the ''Windows-Key+X'' shortcut and select ''Command Prompt (Administrator)'' (''Eingabeaufforderung (Administrator)''). An elevated cmd prompt appears
* type <code>net user administrator /active:yes</code>
* the fully elevated ''Administrator'' account is now available and you can log-in to this account as usual
* '''Please make sure the account has a password set - by default, it does not!!'''

To elevate the tsptray.exe application;
* log in to an account with administrator rights
* start a windows explorer
* change directory to <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8-x64 TSP</code>
* right click on <code>tsptray.exe</code> and open the ''properties'' (''Eigenschaften'') menu
* switch to the ''Compatibility'' (''Kompatibilität'') tab
* tick the ''Run as administrator'' (''Program als Administrator ausführen'') check mark
* save the settings

Please note that Windows 8 will not let you run any "Metro App" in elevated mode!

===== HTTPS =====
The TSP will not be able to talk to the PBX using HTTPS with Windows8 or Server2012. This [[Reference8:Release_Notes_TAPI_V8#3722_-_HTTPS_SOAP_connections_did_not_work_on_Windows8_.2F_Server_2012|has been fixed]] with V8 TAPI Service Provider (32 and 64bit) - hotfix10.
===== .Net 3.5 missing on Server 2012 =====
Server 2012 has no support for .Net 3.5 by default. Even more, it cannot be installed just by downloading it. Instead, the ''NetFX3 Feature'' needs to be enabled. Here is how:

Microsoft Windows [Version 6.2.9200]
(c) 2012 Microsoft Corporation. Alle Rechte vorbehalten.

C:\Users\Administrator>dism /online /enable-feature /featurename:NetFX3 /all /Source:''<path to windows setup, e.g. d:>''\sources\sxs /LimitAccess

See also
* [http://blogs.technet.com/b/aviraj/archive/2012/08/04/windows-8-enable-net-framework-3-5-includes-net-2-0-and-3-0-i-e-netfx3-feature-in-online-amp-offline-mode.aspx?PageIndex=2 Windows 8: Enable .NET Framework 3.5]
* [http://msdn.microsoft.com/en-us/library/hh506443.aspx Installing the .NET Framework 3.5 on Windows 8]

==== TAPI dialer fails from Outlook when Lync client was/is installed ====
We have received reports that 1st-party TAPI dial-out from Outlook does not work anymore when a Lync client was installed. Some users report that this phenomenon occurred only after an upgrade to Windows 8. Reportedly, this can be [http://support.microsoft.com/kb/959625/en-us fixed by setting a registry key as outlined in Microsoft's knowledge-base]. You may want to give this a try. However, we have not seen this issue ourselves and thus can't comment on it further.

==== Slow Network Performance ====
TAPI is pretty sensitive to slow network performance. While the TSP is multi-threaded, some internal locking must be done so that slow requests to a PBX my block other pending requests, resulting in unpleasant performance. The TSP will create ''Windows Event Log'' entries of type ''slow SOAP call performance'' if this is detected. You should inspect your event log regularly and resolve the reason for such network performance.

Long PBX request round-trips may have a number of reasons:

; slow WAN performance : of course, if the WAN is slow or unstable, bad performance is the result
; inappropriate QoS : SOAP is using HTTP/HTTPS. In a QoS enabled network, call signalling and RTP may work fine, whereas HTTP/HTTPS is considered to be of no importance. You need to keep in mind that such QoS policy may lead to bad TAPI performance, as the SOAP traffic used by the TSP (being based on HTTP/HTTPS) may be delayed. You should assign SOAP traffic a similar priority as you do for VoIP signalling
; overloaded PBX : HTTP traffic is treated on a low priority level in the PBX. If the PBX runs near to 100% CPU load, while all RTP and VoIP signalling will work well still, HTTP traffic may get severely delayed. You should make sure your PBX runs well under 100% CPU load to get good TAPI performance. See [[Reference:Device Health Check]] for more details

==== TAPI on Windows 10 ====
In Windows 10, the TSP is not allowed any longer to read/write its own registry tree. For this reason, it is not possible to store or read the configuration. As a result, the TSP will not work. To fix this, you need to modify the registry access rights so that the TSP has read/write access to <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>.

Note on windows registry paths<ref name="regkey">
Due to a change in ''Windows Registry Access Rights'' in Windows 10, from Build 8165, the configuration is stored in
: <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>
(a place that is suitable for Windows 10 too). Before, the configuration was stored in
: <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>

See [[#Upgrade_from_Build_8164_or_earlier| Upgrade from Build 8164 or_earlier ]] above for more details.
</ref>:
<references/>

=== Tweaks ===
There are a few configuration options which should be used rarely. They can be enabled by setting an appropriate registry key.

Since Hotfix 15 the location to set the interop tweaks has been changed to <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>:

; ProcessorMask : REG_DWORD. If set, the TSP will use <code>SetProcessAffinityMask(GetCurrentProcess(), set)</code> to limit TSP execution to one or more of the existing processors. Set to <code>0xff</code> by default.

; LineTimeOut : REG_DWORD. Can be set to a number of seconds the TSP should wait for the determination of lines to finish (default 90). On a large PBX, or a PBX with slow slaves, the determination might not finish in the default time frame. If this happens, TAPI applications may show ''Line unnamed'' line entries in their line list. If this is a problem, set it to a larger value (e.g. <code>120</code>).

; IgnoreDevStatus : REG_DWORD. Some applications get confused if TAPI reports line to be disconnected or out-of-service dynamically. Setting this to a non-zero value will disable any such notification.

; ClearFwdOnSet : REG_DWORD. If set to a non-zero value, the TSP will clear all current call forward settings before a lineForward request is executed. This implies that all call forward settings are ''replaced'' by the new settings. Standard behaviour is to only modify the settings, that is, replace all current settings of the same type with the settings found in the lineForward request (for example, if there is only one setting in the request that defines a CFU, then the current CFU settings are replaced by the new one provided. All others, such as e.g. CFNR settings, are left untouched).

: Tapi spec is pretty clear on how this should work: ''The provider should "unforward everything" prior to setting the new forwarding instructions''. Even though, for historical reasons, ClearFwdOnSet=0 has been the default in all TAPI versions prior to V8 hotfix 6, from hotfix 6 on, the default changes to 1, as this has turned out to be the widely accepted interpretation.

; No3PTY : REG_DWORD. See [[Reference8:TAPI_Service_Provider#Notes_on_3PTY_Conferences | Notes_on_3PTY_Conferences]] below.

; HiddenRecordingNumber: REG_SZ. Active recording in an innovaphone PBX is implemented as an implicit 3PTY conference with the recording sink as one of the parties. These will be shown as usual in the TAPI callstate. However, some applications get confused as this results in a situation, where a normal endpoint (read: phone) has more than one active (i.e. ''not on hold'') call. To suppress such calls in the TAPI call states, you can set this tweak to the number of the recording sink as configured in the phone's recording configuration tab. If so, any outgoing call from an endpoint that is registered with a PBX user object with a called number that equals the setting of this tweak, will be suppressed. So if your recording sink has the number <code>44</code>, you would set this registry value to <code>44</code> (this is available from TAPI V8 hotfix 8). Please note that this feature actually suppresses any call info for such calls, however, it does not revert previously announced call infos. So if the call is initiated using ''overlapped dialling'', all call states will be shown until the called number matches the value of <code>HiddenRecordingNumber</code> and all subsequent call states will be suppressed. This will probably leave the call shown in ''dialling'' state. The feature should be used for destinations which are called using ''block dialling'' only thus.

; SilentHold : REG_DWORD. When a call is put on hold using <code>lineHold</code>, the held party will hear ''music on hold'' emitted by the PBX. The hold-initiator will hear a dialling tone (PBX firmware v11r2 and up, with older versions the initiator would hear ''music on hold''). When <code>SilentHold</code> is set to a non-zero value, the initiating party will hear silence - i.e. no dialling tone (this is available from TAPI V8 hotfix 8).



; NoDuplicateConnectedCalls : REG_DWORD. If set to 1, the TSP will never show more than one call per line to be active. Extra active calls will be shown as ''on-hold''. The situation occurs e.g. when a user initiates a 3PTY conference on the phone. This essentially is a bug fix for Microsoft's OCS client which forces any extra active call on-hold, thereby disturbing the 3PTY function. If your are using [http://www.estos.de/download/software/eccg.htm ESTOS' Call Control Gateway]: from version ''2.0.1.1474 - 05.11.2008'' there is a fix for this same problem available. This option thus is deprecated.

; UseFirstLeg2 : REG_DWORD. TAPI allows only for a single leg-2 info (redirection information in case of a call forward). If a call is forwarded mutliple times, by default the last redirection is shown in TAPI. If <code>UseFirstLeg2</code> is set to 1 however, the first redirection is shown.

; UseNameForDeviceGuid : REG_DWORD. The TSP will create a TAPI line for each ''Device'' of each PBX object (if ''MapDevices'' is set). The internal unique identifier includes the ''Hardware Id'' found in the ''Device''. If this changes, the TAPI line representing the ''Device'' is considered new and a new TAPI ''permanent line id'' is allocated. This may be annoying cause when a device serial number (e.g. for a telephone) is used as ''Hardware Id'', replacing the device creates a new TAPI line. If ''UseNameForDeviceGuid'' is set to 1, the TSP will use the ''Device''s ''Name'' instead (which usually not changes). While this might be more convenient, be aware that you ''must'' make sure that no PBX object has duplicate ''Name''s! Otherwise, TAPI will get confused. Available from build 8178

; ShowConfGUID : REG_DWORD. If set and not 0, the TSP will implicitly set each call's CallData to a string such as "<code>conf-guid:</code>''call-guid''". ''call-guid'' is a 66-byte Unicode16 string (32 hex characters plus terminating 0). Note that this will interfere with an application's use of the lineSetCallData function (tapi.h) and is therefore disabled by default. Available from build 8190

===List of supported TSPI functions===

The TSP supports the following TAPI Service Provider Interface Functions. Note that these do not map one to one with TAPI user functions. For more information, see the Microsoft TAPI documentation.

*TSPI_lineAnswer
*TSPI_lineBlindTransfer
*TSPI_lineClose
*TSPI_lineCloseCall
*TSPI_lineCompleteTransfer
*TSPI_lineDevSpecific
*TSPI_lineDevSpecificFeature
*TSPI_lineDial
*TSPI_lineDrop
*TSPI_lineForward
*TSPI_lineGenerateDigits
*TSPI_lineGetAddressCaps
*TSPI_lineGetAddressID
*TSPI_lineGetAddressStatus
*TSPI_lineGetCallAddressID
*TSPI_lineGetCallHubTracking
*TSPI_lineGetCallIDs
*TSPI_lineGetCallInfo
*TSPI_lineGetCallStatus
*TSPI_lineGetDevCaps
*TSPI_lineGetExtensionID
*TSPI_lineGetID
*TSPI_lineGetLineDevStatus
*TSPI_lineGetNumAddressIDs
*TSPI_lineHold
*TSPI_lineMakeCall
*TSPI_lineNegotiateExtVersion
*TSPI_lineNegotiateTSPIVersion
*TSPI_lineOpen
*TSPI_linePark
*TSPI_linePickup
*TSPI_lineRedirect
*TSPI_lineSelectExtVersion
*TSPI_lineSendUserUserInfo
*TSPI_lineSetAppSpecific
*TSPI_lineSetCallData
*TSPI_lineSetCallHubTracking
*TSPI_lineSetCallParams
*TSPI_lineSetCurrentLocation
*TSPI_lineSetDefaultMediaDetection
*TSPI_lineSetMediaMode
*TSPI_lineSetStatusMessages
*TSPI_lineSetupTransfer
*TSPI_lineSwapHold
*TSPI_lineUnhold
*TSPI_lineUnpark

*TSPI_providerConfig
*TSPI_providerCreateLineDevice
*TSPI_providerEnumDevices
*TSPI_providerGenericDialogData
*TSPI_providerInit
*TSPI_providerInstall
*TSPI_providerRemove
*TSPI_providerShutdown
*TSPI_providerUIIdentify
=====Notes on Consultation Calls=====
This TSP supports the <code>lineSetupTransfer</code> function. However, strictly speaking, this function is not needed and should not be used. It is merely intended for applications which do not offer a consultation call interface to the user when this function is not available. Instead, <code>TSPI_lineMakeCall</code> can be used where <code>lineSetupTransfer</code> would be otherwise. The notion of a special ''consultation call'' is an idiosyncrasy forced by legacy PBX technologies which were not able to transfer two arbitrary calls. In these scenarios, a potentially to-be-transferred call needed to be linked to the primary call. The PBX can transfer two arbitrary calls and thus there is no need for <code>lineSetupTransfer</code>. This ability is indicated by the <code>LINEADDRCAPFLAGS_TRANSFERMAKE</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE </code> flags. The transfer is then requested by using <code>TSPI_lineCompleteTransfer</code>.

=====Notes on 3PTY Conferences=====
The TSP supports the management of 3PTY conferences. These can be initiated by using <code>TSPI_lineCompleteTransfer</code> with <code>LINETRANSFERMODE_CONFERENCE</code> instead of <code>LINETRANSFERMODE_TRANSFER</code>. This is indicated by the flags <code>LINEADDRCAPFLAGS_CONFERENCEHELD</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE</code>. The 3PTY function is actually implemented by the innovaphone IP phones (such as IP2xx). Therefore, these capabilities are only advertised if the line is based on a PBX user object. Still, some lines where the capabilities are advertised cannot do 3PTY (such as e.g. DECT lines, analogue lines, 3rd party devices, ...). So the call to <code>TSPI_lineCompleteTransfer</code> will succeed but the conference will not be initiated and the subsequent call states will not indicate a conference (as there is no).

Also, if non-telephone devices are registered with a PBX user object and these device have multiple concurrent calls (e.g. a call center connected with a multi-channel XCapi), these will be viewed as 3PTY calls (as this is the way such calls appear to the TAPI: a line with more than one non-held call). If these calls are in fact no 3PTY, this may lead to confusing call indications from TAPI. It is better to register such objects as a PBX gateway object. Special treatment of 3PTY calls can be disabled by setting the registry flag <code>No3PTY</code> (from build 8087 onwards).

A 3PTY conference will create a new call handle for the conference. The only operation available for such a handle is <code>TSPI_lineDrop</code>. This will terminate the conference and restore the state active before the conference was initiated (that is, the phone that implemented the conference will now have 2 calls, one active and one on hold). This is indicated by not setting <code>LINEADDRCAPFLAGS_CONFDROP</code>.

A <code>lineDrop()</code> on one of the 2 ''real'' calls involved will of course cancel this call and thus remove the 3PTY.

======Notes on Intrusion Calls======
A special case of 3PTY is an intrusion call initiated by a [[Reference9:Phone/User/Function-Keys/Partner | partner function key]]. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the intrusion call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is an intrusion call).

======Notes on Recording Calls======
A special case of 3PTY is a recording call. This effectively creates an user-invisible 3PTY on the phone. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the recording call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is a recording call).

Recording calls are shown as normal conferences (unless <code>No3PTY</code> is set). This might be confusing to applications and/or users. See the <code>HiddenRecordingNumber</code> tweak above for a method to hide such calls.

=====Notes on parked Calls=====
The PBX can park calls from and to any existing PBX object, e.g. by virtue of [[Reference8:Configuration/Registration/Function-Keys/Park | specific feature keys]]. They are parked to/from a numeric ''park position''. In SOAP however, calls are parked to an object by providing the objects '''UserInitialize()''' handle and a park position. Parked calls are then reported as straight calls with a distinct signalling state (8). The park position is not conveyed as part of the '''CallInfo''' record. To unpark, '''[[Reference8:SOAP_API#integer_UserPickup.28int_user.2C_string_cn.2C_integer_call.2C_string_group.2C_int_reg.2C_InfoArray_info.29 | UserPickup]]''' can be used providing the parked calls call handle as '''call''' argument.

The TAPI specification is unclear on how the address information required to '''lineUnpark()''' a call can be obtained by an application (except that it is returned from '''linePark()''' if the call was parked using TAPI). The TSP thus indicates parked calls on a line with a call reason <code>LINECALLREASON_PARKED</code>. The caller id information is set to the parked calls call handle. This way, the application can take the caller id information and provide it to '''lineUnpark()''' to unpark a call. If the appication does not support this mode of operation but supports '''lineUnpark()''' and lets the user input the park identifier, the user can just provide the caller id information.

Some applications do not care for parked calls (by examining the call reason) and just blindly report these calls like ordinary connected calls (thereby confusing the user). To work around this problem, reporting parked calls can be turned off in the TSP configuration dialogue.

=====Notes on sending User to User Information =====
The TAPI specification for sending UserUserInfo closely resembles the way ISDN defines this service. Although the innovaphone PBX supports this service both with H.323 and SIP, it is ''not'' supported in this TSP. Instead, sending user to user information is implemented using H.323/SIP messaging. However, there are some important deviations and limitations caused hereby:
* data is ''not transparent''. That is, the TSP only allows for null-terminated unicode to be sent. The data must be of even length and the last two bytes must be null.
* data is ''not sent within the call'', but by initiating a separate call. This implies that the target number used to send the message carrying the data to is 'guessed' from the available call data. For example, if the call is in a connected state and a connected number is known, the message is sent to the connected number. If the call is in the ringback state, then either the called number or - if available - the redirection number is used and so forth.
* message calls are not indicated by the SOAP CallInfo records. As a result, messages (that is, user to user information) cannot be received with TAPI and ''lineReleaseUserUserInfo is not supported''

=====Notes on sending proprietary innovaphone Remote Control Facilities =====
The SOAP [[Reference8:SOAP_API#UserRc.28integer_call.2C_integer_rc.29|UserRc]] function allows to send various [[Reference:Remote Control Facility|facility messages]] to an innovaphone phone device. In some cases, it is useful to be able to invoke this function through a standard TAPI mechanism. This can be achieved by using the TAPI '''lineBlindTransfer''' function. If the ''called party name'' provided as destination for the ''lineBlindTransfer'' (in ''lpszDestAddress'') has the magic value <code>USERRC</code>, then the ''called subaddress'' is converted to an integer and the result is sent as remote control facility to the call the blind transfer is applied for. For details on how to code the ''called party name'' and the ''called subaddress'' into ''lpszDestAddress'' see [http://msdn.microsoft.com/en-us/library/windows/desktop/ms726017%28v=vs.85%29.aspx Microsoft's ''Canonical Address'' specification]. This works from TAPI8 hotfix 4.

For example, initiating a blind transfer to <code>|16^USERRC</code> (empty address, subaddress 16 (that is, [[Reference:Remote Control Facility|''change to handset mode'']]), called name <code>USERRC</code>) will switch the phone having the call to be transferred into handset mode (and <code>|18^USERRC</code> will switch it back to handsfree mode). Of course, no actual transfer will happen in these cases (''lineBlindTransfer'' is merely used as a vehicle to send the facility to the proper call).

Such proprietary facility message can also be sent with ''lineMakeCall'' (that is, in SOAP's [[Reference8:SOAP_API#integer_UserCall.28integer_user.2C_string_cn.2C_string_e164.2C_string_h323.2C_int_reg.2C_InfoArray_info.2C_int_rc.2C_string_srce164.29|UserCall]] function). For example, setting up a call to <code>123|21^USERRC</code> will send an intrusion call to extension 123 and intrude any call that might be active there. This works from TAPI8 hotfix 6. Please note that the innovaphone TAPI service provider does not support TAPI's ''lineCompleteCall'' function with <code>LINECALLCOMPLMODE_INTRUDE</code> though (as TAPI's call model here does not fit with the PBX's call model). Please also note that intrusion calls look like 3PTY calls to TAPI (see [[#Notes_on_Intrusion_Calls|notes on intrusion calls]] above).

Remote control facilities are implemented by the telephone devices, so these functions are subject to the phone firmware in use.

[[Category:Howto|{{PAGENAME}}]]
[[Category:Concept|{{PAGENAME}}]]

== Related Articles ==
* [[Howto:Troubleshooting the TAPI service provider]]
* [[Reference8:Release Notes TAPI]]