innovaphone wiki - User contributions [en]

Courseware:IT Plus Overview

2026-11-02T12:10:43Z

Tfu:

''innovaphone Plus'' is a series of courses, each covering advanced aspects of the configuration of innovaphone devices in separate topics. Each topic can be worked through on individually or in any order. Further topics will be added over time. Each topic is based on the latest firmware at the time of creation. All topics based on the same firmware version (e.g. 14r2) are included in the same course of the series.

Access to ''innovaphone Plus'' requires a valid innovaphone ''Plus'' corporate subscription. See [https://www.innovaphone.com/en/partner/training/innovaphone-plus-training.html innovaphone Plus Training] for details.

The rest of this article gives you an overview of the topics covered and in which course they can be found.
__NOEDITSECTION__
{{#invoke-url: https://class.lab.innovaphone.com/itplus-overview.php?wiki=true}}

Courseware:IT Plus Overview

2026-11-02T10:25:34Z

Tfu: Undo revision 80765 by Tfu (talk)

''innovaphone Plus'' is a series of courses, each covering advanced aspects of the configuration of innovaphone devices in separate topics. Each topic can be worked through on individually or in any order. Further topics will be added over time. Each topic is based on the latest firmware at the time of creation. All topics based on the same firmware version (e.g. 14r2) are included in the same course of the series.

Access to ''innovaphone Plus'' requires a valid innovaphone ''Plus'' corporate subscription. See [https://www.innovaphone.com/en/partner/training/innovaphone-plus-training.html innovaphone Plus Training] for details.

The rest of this article gives you an overview of the topics covered and in which course they can be found.
__NOEDITSECTION__
{{#invoke-url: https://class.innovaphone.com/moodle2/itplus-overview.php?wiki=true}}

Courseware:IT Plus Overview

2026-11-02T10:25:04Z

Tfu:

Reference15r1:Concept App Service Connector for Microsoft 365

2026-10-26T11:03:42Z

Tfu: /* Calendar Presence */

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 15r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V15r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure_Calendar_Presence_Sync_by_Connector_for_Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.
* Synchronization is limited to events within the next 72 hours. The calendar data is refreshed once every 24 hours, so events further in the future are only synchronized with the first daily refresh after they fall into this 72-hour window.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* Database
* HTTP client
* TLS
* TCP
* App WebSocket
* Config
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 12 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365#Create_an_App_for_syncing_Teams_to_PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto15r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto15r1:Configure Calendar Presence Sync by Connector for Microsoft365]]

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

Reference16r1:Concept App Service Connector for Microsoft 365

2026-10-26T11:03:11Z

Tfu: /* Technical Overview */

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 16r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).
It is also possible to search for your own contacts.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V16r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid on user presence synchronisation]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid on calendar presence synchronisation]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism. Microsoft disables EWS in Exchange Online by default starting October 1, 2026 and shuts it down permanently on April 1, 2027, see [[Support:Calendar App - Exchange Online EWS Retirement]]. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.
* Synchronization is limited to events within the next 72 hours. The calendar data is refreshed once every 24 hours, so events further in the future are only synchronized with the first daily refresh after they fall into this 72-hour window.

=== Contact Search ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure_Contact_Search_by_Connector_for_Microsoft365|Howto guide for basic configuration aid on contact search]].

==== Technical Overview ====
Introduced in 16r1 the Connector for Microsoft 365 will offer a possibility to search for your own contacts (Teams, Exchange online) via the Graph API.

When the configuration of the connector for Microsoft 365 Contact Search is complete, the app connects to Microsoft to receive a token with the contact search app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, the user can search with the Phone App, for example (a myApps search provider will be provided for all apps looking using search providers looking up contacts). The search string is made available to the Connector for Microsoft 365 via the microsoft365-api. The results are sent to the consumer, e.g. the Phone App and presented there. 
 
A user subscription is started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 

* User subscriptions are renewed every 60 minutes.
* License Check is made every hour.

'''Be aware:''' Since the Connector for Microsoft 365 is an app in the Scope of myApps App Platform, IP Phones and other services not using Apps cannot benefit from this search service.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with multi-factor authentication (MFA) are not supported as technical communication users for the Connector.

''We recommend creating a dedicated user account for this purpose rather than using an existing user account.'' 
''This limitation applies only to technical users used for the Connector for Microsoft 365, not standard user accounts. MFA can be used for real users.''

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

== Contact Search ==
=== Limited scope of searchable contacts ===
The contact search only queries the default Contacts folder of the searching user's mailbox via the Microsoft Graph API ('''/users/{id}/contacts'''). The following are currently '''not''' included in the search results:

* Custom/subordinate contact folders
* Contact folders of other mailboxes shared with the user
* The organizational Global Address List (GAL)

Creating and managing custom contact folders is no longer available in Microsoft's own cloud-based Outlook (Outlook on the web / new Outlook). Contacts in folders created earlier are still displayed there, listed under a different category - but the standard Microsoft Graph API contact search used by the Connector does not find these contacts.

Search of the organizational Global Address List (GAL) is currently not supported by the Connector.

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* App WebSocket
* Config
* Database
* HTTP client
* TCP
* TLS
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 12 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365#Create an App for syncing Teams to PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Contact Search by Connector for Microsoft365]]

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

Reference:IP73 WLAN WiFi Wireless IP-Phone

2026-10-15T15:16:23Z

Tfu: Add WinPDM Numbers tab hint to LDAP root certificate upload sentence - Co-Authored-By: AI

This article describes the IP73 WLAN/WiFi wireless IP phone, differences to the deprecated IP62 Wireless IP phone and a list of compatible WLAN infrastructures.

==Applies To==
This information applies to:
*innovaphone IP73 (50-00073-001)

==Requirements==

To perform configuration changes on the IP73 device a desktop programming kit (IP62/IP64/IP65/IP73) (Art.No. 50-00060-021 / Prod.ID DP1-UAAA/1A1) is required. The programming kit enables to connect the IP73 handset to a PC in order the configuration changes can be done using WinPDM software.

==Feature Comparison==
This chapter describes the differences in the feature sets between old and new WiFi handsets.

{|border="2" cellspacing="4" cellpadding="3" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse;empty-cells:show;"
|+ Handset Features Matrix
! Feature !! IP62 !! IP73 !! Description
|-
| Signaling Protocols || H.323/SIP || SIP only ||
|-
| Codecs || G.711, G.722, G.729 A || Opus Wideband, G.711, G.722, G.729 A/B/AB ||
|-
| Talk Time/ Standby Time || 15 h / 100 h || 10 h / 100 h || with U-APSD
|-
| WiFi Standards || 802.11 a/b/g/n || 802.11 a/b/g/n/ac, 802.11r, 802.11k || MCS 0-7 only, Fast BSS Transition (FT or 802.11r)
|-
| SSL Certificates || customer managed || preinstalled by innovaphone/customer managed ||
|-
| call diversion || ok || only with DTMF ||
|-
| Headset Connector || 2,5 mm || 3,5 mm ||
|}

As of firmware version 4.0.0, the connection of a central telephone book via LDAP is supported. For configuration to be carried out refer to the [[#Central Phonebook Access|corresponding section below]].

==WLAN Infrastructure Compatibility==

===Certified WLAN Platforms===
'''IMPORTANT''': Ask [mailto:presales_AT_innovaphone_D0T_com innovaphone Presales Team] for possible interop configuration recommendations and pitfalls before you order the WiFi equipment and start with the roll-out.

Note that availability and combinations of controllers and access points may be subject to change by the manufacturer and are not in the responsability of innovaphone. Errors and omissions excepted.

Wi-Fi infrastructures not listed in this document are not supported. Use of the IP73 in unsupported infrastructures is at your own risk.

{| class="wikitable"
|+Certified WLAN Platforms as of March 2026
!AP Model
!Controller Model
!SW Version
!Test date
!Report
|-
! colspan="5" |Aruba
|-
|AP 303, 304, 305, 314, 315, 324, 325, 334, 335, 344, 345, 504, 505, 514, 515, 534, 535, 554, 555, 635, 655
|7000/7200/9000/MX-VA-xxx
|8.10.0.13 LSR
|09-Sep-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_aruba_networking_8_10_0_13.pdf}}]]
|-
|AP 303, 304, 305, 314, 315, 324, 325, 334, 335, 344, 345, 504, 505, 514, 515, 534, 535, 554, 555, 635, 655
|Networking Central
|10.4.1.3_90100
|12-Aug-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_aruba_networking_central_10_4_1_3.pdf}}]]
|-
! colspan="5" |Cisco
|-
|AP 1832, 1852, 2802, 3802, 4800, 9105, 9115, 9117, 9120, 9130
|WLC 3504, 5520, 8540, vWLC, Mobility Express Solution
|8.10.162
|04-Feb-2022
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_cisco_wlc_8_10_162.pdf}}]]
|-
|AP 1602, 2602, 3502, 3602, 1702, 2702, 3700, 2802, 3802, 1832, 1852
|WLC 2504, 3504, 5508, 5520, 7510, 8510, 8540, vWLC
|8.5.182
|14-Feb-2022
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_cisco_wlc_8_5_182.pdf}}]]
|-
|AP 1702, 2702, 3702
|Catalyst 9800
|17.3.3
|01-Jun-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_cisco_catalyst_17_3_3.pdf}}]]
|-
|AP 1832, 1852, 2802, 3802, 4800, 9115, 9117, 9120, 9130, 9136
|Catalyst 9800
|17.9.3
|20-Jun-2022
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_cisco_catalyst_17_9_3.pdf}}]]
|-
! colspan="5" |Cisco Meraki
|-
|MR20/MR30H/MR33/MR42/MR42E/MR52/MR53/MR53E/MR70/MR74/MR84 (802.11ac wave 2)
MR36/MR44/MR46/MR46E/MR76/MR86 (802.11ax)
| -
|MR 27.7.1
|29-Sept-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_meraki_mr_27_7_1.pdf}}]]
|-
|MR36/MR44/MR46/MR46E/MR76/MR86 (802.11ax)
CW9162/CW9163E/CW9164/CW9166/CW9166D1 (Wifi 6E)
| -
|MR 30.7
|Nov-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_meraki_mr_30_7.pdf}}]]
|-
! colspan="5" |Extreme Networks (Enterasys/IdentiFi)
|-
|AP 3801, 3805, 3825, 3865, 3935
|Extreme Wireless C25, C35, C2110, C5110, C5210, v2110
|AP:10.51.10
|03-Feb-2020
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_wireless_10_51_10.pdf}}]]
|-
|AP 122, 130, 230, 250, 550, 650
|Extreme Cloud
|AP 10.0r8, Cloud 20.1.1.3
|19-Mar-2020
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_cloud_10_0r8.pdf}}]]
|-
|AP 310i/e, 410i/e, 505i/e, 510i/e, 360i/e, 460i/e, 560
|XCC Controllers E1120, E2120, E3120, VE6120/VE6125, VE6120H
|05.16.01.0025
|10-Dec-2020
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_xcc_05_16_01_0025.pdf}}]]
|-
|AP305c/cx, 410c, 460c, 510c/cx, 650
|Extreme Cloud C25, C35, C2110, C5110, C5210, v2110
|AP 10.2.4.0, Cloud 20.1.1.3
|20-Jan-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_cloud_10_2_4_0.pdf}}]]
|-
|AP310i/e, 410i/e, 460i/e, 510i/e, 650i
|Extreme WING NX 5500, 75xx, 9500, 9510, 9600, 9610, VX9000
|7.5.2.0
|12-Apr-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_wing_7_5_2_0.pdf}}]]
|-
|AP 305c/305cx, 410c, 460c, 510c/510cx, 650/650x, 4000, 5010
|Extreme Cloud iQ
|AP 10.8.3.0, Cloud 25.4.3-40
|Aug-2025
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_cloud_10_8_3_0.pdf}}]]
|-
! colspan="5" |Fortinet
|-
|AP1010/1014/1020/822/832, APU221EV/U223EV/U321EV/U323EV/U421EV/U423EV
|MC1550/3x00/4x00/5000/6000 FortiWLC-50D ,200D, 500D, 1000D, 3000D FWC- VM-50, 200, 500, 1000, 3000
|8.5-2-5
|03-Jun-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_fortinet_wlc_8_5_2_5.pdf}}]]
|-
! colspan="5" |Huawei
|-
|AirEngine5760-51/5760-22W/6760-X1/6760-X1E/6760R-51/6760R-51E/8760-X1-PRO/8760R-X1/8760R-X1E
|AirEngine 9700-M1, AC6508/6805/6800V, iMaster NCE-Campus
|V200R022C10SPC100
|10-May-2023
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_huawei_airengine_V200R022C10SPC100.pdf}}]]
|-
! colspan="5" |Juniper Mist
|-
|AP34, AP45
|Mist Cloud
|0.12.26354
|Aug-2023
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_juniper_0_12_26354.pdf}}]]
|-
|AP12, AP32, AP33, AP41, AP 43, AP61, AP 63
|Mist Cloud
|0.12.27139
|Feb-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_juniper_0_12_27139.pdf}}]]
|-
! colspan="5" |Ruckus
|-
|SmartZone ZoneFlex R300, R310, T300, T310, R500, R510, H510, R600, R610, R710, R720
|SmartZone platform, vSZ-(H,E,D), SZ100/300
|5.2.0.0.699
|27-Apr-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_ruckus_smartzone_5_2_0_0.pdf}}]]
|-
|SmartZone ZoneFlex R350, R350e, T350, R550, R650, R750, T750, R850, R500, R510, R610, R710, R720
|SmartZone platform, vSZ-(H,E,D), SZ144/300
|6.1.2.0.404
|29-Apr-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_ruckus_smartzone_6_1_2_0.pdf}}]]
|}

=== DAS Compatibility ===
[http://en.wikipedia.org/wiki/Distributed_antenna_system Distributed Antenna Systems (DAS)] provide a cost-effective solution for extending radio coverage inside large facilities. Simply put, a DAS can be seen as a long cable starting at a base station or access point to which many antennas are connected. While the architecture can be utilized to mitigate certain coverage issues, the innovaphone IP73 was not designed to accommodate for such RF environments. Furthermore it is difficult to ascertain and ensure WLAN reliability in regard to interference, capacity, roaming, location-based services, and some important [http://en.wikipedia.org/wiki/IEEE_802.11n 802.11n] features, such as [http://en.wikipedia.org/wiki/Multiple-input_multiple-output MIMO]. As a consequence thereof, innovaphone will not endorse nor provide RF support for WiFi deployments over any Distributed Antenna System.

=== WPA3 Compatibility ===
The IP73 already supports the configuration option for ''WPA3''. However, this should not yet be actively used. 
''WPA3'' is currently only recommended for demo purposes. Support for ''WPA3'' is implemented, but no successful interoperability tests have been performed. WPA3 is not recommended being used except for demo purposes.

=== U-APSD Required ===
U-APSD is a power saving function that is always enabled on the IP73. It must also be enabled/supported on the AP to avoid packet loss/voice problems.

==Configuration==
IP73 configuration is done via WinPDM-application available at [https://store.innovaphone.com the Software section of the innovaphone App Store]. Use of desktop programming kit (IP62/IP64/IP65) (50-00060-021) is required.

=== Security ===
From version 7.x onwards, the IP73 firmware includes several changes to achieve compliance with the EU Radio Equipment Directive (RED) and the Cybersecurity Delegated Act.

This requires some additional configuration changes to get the handset operational:

====New handset initial configuration====
{{IP73_703_WinPDM_Auth}}

Resolution is to enter the [[#Shortcuts|default admin access code '''40022''']] and afterwards to either disable WinPDM Authentication or change the Admin access code:

[[Image:IP73 703 WinPDMAuth.png|ip73_703_winpdmauth.png/]]

====Configuration changes for PBX connection====
For handsets running firmware 7.x, the following settings must be configured via WinPDM in order to enable a PBX connection:
* Unite connection mode must be set to ‘Off’ at [Device/Unite/Connection mode].
* Admin access code must be set at [Device/General/Admin access code]. 5 - 10 characters required.
* Phone lock code must be set at [Device/Settings/Force phone lock]. 4 - 8 characters required. By setting the phone lock code the phone lock will be applied for every subsequent bootup. Phone lock is enforced on by default but can be turned off by parameter [Device/Settings/Force phone lock] or by admin menu in handset GUI. Note that handset does not comply with RED by turning off forced phone lock!
* Security has also been strengthen by disabling some outdated security protocols by default. If a service is no longer working after upgrade try to use more modern cryptographic protocol or set parameter “<service>/Allow outdated security protocols” to ‘Yes’.

===PBX Registration===
====Authentication via client certificate====
The recommended way to register an IP73 handset at the innovaphone PBX is SIP over TLS with authentication by a client certificate. The IP73 handset is delivered with a preinstalled device certificate already trusted by an innovaphone PBX.

Prerequisites on the PBX for such type of authentication are:

*The issuer of the IP73 client certificate is on the Trust List of the PBX gateway
*The CN of the client certificate used by IP73 equals the MAC address of the IP73 itself (alternatively other CN and registration identity can be used)
*User Object contains a Device with a Hardware Id matching the MAC address of the IP73

On the IP73 the following settings must be configured. Note that the handset parameters (including the certificate selection) are opened in the ''Numbers'' tab of the WinPDM software:
*VoIP->SIP
**SIP TLS client certificate: <select certificate with MAC address as CN> or <Automatic if preinstalled certificate is used>
**SIP Transport: TLS
**Primary SIP proxy: <IP-address of the PBX> or <DNS-name of PBX>
**SIP proxy ID: <PBX system name>
**SIP proxy password: <no password is required>
**Registration and Authentication identity: MAC address

====Authentication via username/hardware id and password====
*VoIP->General->Endpoint ID: username or hardware id on User Object
*VoIP->SIP
**SIP Transport: TCP or UDP
**SIP proxy password: <password on the User Object or PBX System password, depending on Users Device configuration>
**Registration and Authentication identity: Endpoint ID

=== ICE/TURN ===
ICE is enabled by default. It is required to provide STUN and TURN server configuration under VoIP->General to secure correct negotiation of media channels.

=== Factory Reset ===
You can use the local ''Admin menu'' on the Phone or the WinPDM Software (Rightclick on the device) to make a Factory Reset.

=== MWI for IP73===
The IP73 can be configured to display a message waiting indication / MWI.
You need a programming shell and the WinPDM software (available for download in our [https://store.innovaphone.com/release/141A000/download.htm Store] under the Software tab).
*Connect programming cradle to the administration PC
*Install WinPDM and start the application
*Place IP73 into the programming cradle
*If the IP73 is recognized in WinPDM, the parameter settings can be opened by switching to the Numbers tab (1)
*select the respective device type (2 -> WH2 = IP73) and double-clicking the device line (3).
*Select menu Device (4) and step to Message Centre (5)
*Insert the number of the voicemail object for the Message Centre Number (6)
*Insert the user number for the voice mail number (7)
Confirm settings with OK and ensure correct synchronisation of config changes to the handset. Reset of handset is recommended.

[[Image:WIFIMwi.PNG|wifimwi.png/]]

===Central Phonebook Access===
The device offers access to a central LDAP-based directory. Following configuration steps have to be carried out by the administrator:

'''Device Configuration via the WinPDM application'''
* Device has to be plugged into programming cradle and edited via WinPDM
* Device has to be operated with at least firmware '''6.1.13''' available at the [https://store.innovaphone.com innovaphone store].
* Open section Device and step to Central phonebook. Change the central phonebook mode to LDAP and enter the appropriate parameters for the ldap directory to be queried.

For innovaphone PBX query, the following settings and attributes can be used and adapted to the PBX setup.

[[image:IP73_PBX_query.png|ip73_pbx_query.png/]]

In case of using LDAP-secure-queries, upload of the LDAP-server-'''ROOT''' certificate to the IP73 trust list is required (select and upload the certificate in the ''Numbers'' tab of the WinPDM software):

[[image:IP73_Certificate.png|ip73_certificate.png/]]

==Troubleshooting==
Log Options can be configured in the WinPDM software, under Device->Log.

===Remote PCAP Tracing===
You can activate the remote PCAP interface and Trace flags directly in the phone configuration (Admin Menu :: Logging :: Mode) or via WinPDM under Device->Log->PCAP capturing: RPCAP.

Only IP traces are available via RPCAP, no innovaphone or device internal traces are logged.

===PCAP to file via USB Tracing===
It is possible to store PCAP trace file in the ''pcap'' folder on the handset by setting in the phone configuration (Admin Menu :: Logging :: Mode) or via WinPDM under Device->Log->PCAP capturing the option "PCAP to file".

To access the file set Device -> General -> USB behavior to "Ask" and select "File transfer", when connect the handset to the WinPDM. Navigate to the folder ''pcap'' on the ''Handset diagnostics'' drive.

===Trace Options===
Following additional trace options are available:

*WLAN Trace
*Configuration Trace
*GUI Trace
*GLI Trace
*Unite Trace
*VoIP Trace
*System Trace
*Protector Trace
*SaS Trace
*Bluetooth Trace

The resulting traces are available via USB file transfer and are encrypted. The encrypted log files can be encrypted by support only.

===Logging via Syslog, SFTP or logfile===

The handset can be configured to send Syslog messages to a Syslog server, an SFTP server or to a local logfile located in the folder ''tracelog''.

The configuration is available via WinPDM Device -> Log -> Syslog or SFTP.

===Handset Error Messages===

====No network====
The ''No network'' message indicates missing WLAN connection. It can be caused by wrong settings for SSID, Security, reg. domain and WLAN channels or lack of coverage.

====No access====
The ''No access'' message is caused by missing IP connectivity to the PBX or wrong configuration for authentication at the PBX.

== Shortcuts ==
There are some hidden tools for information and analysis, which can be accessed via specific menus and codes:

;Handset Device Information
:''*#34#'' in the main display

;RSSI Indicator
:''*#76#'' in the main display. Type again to exit.
: Here you find the following information in the display:
:* Line 1: SSID
:* Line 2: Current AP
:* Line 3: Current AP MAC
:* Line 4: Previous AP
:* Line 5: Previous AP MAC

;Site Survey Tool
:''*#77#'' in the main display.

;Admin Menu
: Go to the ''Settings menu'' and type in ''40022''

==Known Problems==

===Packet loss and voice quality issues with non-tested WLAN AP and IP73===

'''Issuer: Ascom'''

'''Published: 2022-12-07'''

'''Background''' 
It has come to our (Ascom) knowledge that in later Aruba software versions than Ascom-certified v.8.7.1.1 there is a critical issue affecting clients using power save (U-APSD). 
Data packets will not be transmitted properly to clients in power save.

'''Affected Ascom Certified Aruba Access Points:''' 
7000/7200/9000/MX-VA-xxx Controllers 
AP-303, 304, 305, 314, 315, 324, 325, 334, 335, 344, 345, 
504, 505, 514, 515, 534, 535, 554, 555, 635 

'''Typical symptoms are:''' 
Poor voice quality issues. 

'''Workaround''' 
Currently none available. Disabling U-APSD on the SSID isn’t a viable workaround as this is a requirement for Ascom i63 handsets in enterprise-grade VoWi-Fi deployments. 
Thus it is strongly recommended to avoid upgrades to v. 8.9.x and higher at this point. 

'''Solution''' 
Update Aruba equipment to ArubaOS-8.10.0.11, see [https://arubanetworking.hpe.com/techdocs/ArubaOS-8.x-Books/Release-Notes/810/ArubaOS-8.10.0.11-Release-Notes.pdf Aruba Release notes (search for Ascom)] for details.

===Bluetooth automatically disabled===

'''Issuer: Ascom''' 

'''Version''' 
Handset Firmware 4.0.6

'''Detailed Information''' 
If you have enabled Bluetooth over WinPDM and you want to configure (establish connection to the headset), you get the message "Bluetooth automatically disabled".

'''Background''' 
The chip responsible for handling wireless radio communication, WLAN and BT, has a bug in its current firmware. Thus, using WLAN and BT on similar frequency bands does not work well.

'''Solution/Workaround''' 
Bluetooth is prohibited to be used when WLAN band 2.4 is in use by being automatically disabled. Bluetooth can only be used when WLAN on the 2.4 GHz band is inactive. 
You can disable WLAN 2.4 band over the WinPDM tool.

==Related Articles==
*[[IP73 Technical Data EN]]
*[[Reference:IP62 WLAN WiFi Wireless IP-Phone]]

Reference:IP73 WLAN WiFi Wireless IP-Phone

2026-10-15T14:08:42Z

Tfu: Clarify that handset parameters (incl. certificate selection) are configured in the WinPDM Numbers tab; specify 'Off' for Unite connection mode - Co-Authored-By: AI

This article describes the IP73 WLAN/WiFi wireless IP phone, differences to the deprecated IP62 Wireless IP phone and a list of compatible WLAN infrastructures.

==Applies To==
This information applies to:
*innovaphone IP73 (50-00073-001)

==Requirements==

To perform configuration changes on the IP73 device a desktop programming kit (IP62/IP64/IP65/IP73) (Art.No. 50-00060-021 / Prod.ID DP1-UAAA/1A1) is required. The programming kit enables to connect the IP73 handset to a PC in order the configuration changes can be done using WinPDM software.

==Feature Comparison==
This chapter describes the differences in the feature sets between old and new WiFi handsets.

{|border="2" cellspacing="4" cellpadding="3" rules="all" style="margin:1em 1em 1em 0; border:solid 1px #AAAAAA; border-collapse:collapse;empty-cells:show;"
|+ Handset Features Matrix
! Feature !! IP62 !! IP73 !! Description
|-
| Signaling Protocols || H.323/SIP || SIP only ||
|-
| Codecs || G.711, G.722, G.729 A || Opus Wideband, G.711, G.722, G.729 A/B/AB ||
|-
| Talk Time/ Standby Time || 15 h / 100 h || 10 h / 100 h || with U-APSD
|-
| WiFi Standards || 802.11 a/b/g/n || 802.11 a/b/g/n/ac, 802.11r, 802.11k || MCS 0-7 only, Fast BSS Transition (FT or 802.11r)
|-
| SSL Certificates || customer managed || preinstalled by innovaphone/customer managed ||
|-
| call diversion || ok || only with DTMF ||
|-
| Headset Connector || 2,5 mm || 3,5 mm ||
|}

As of firmware version 4.0.0, the connection of a central telephone book via LDAP is supported. For configuration to be carried out refer to the [[#Central Phonebook Access|corresponding section below]].

==WLAN Infrastructure Compatibility==

===Certified WLAN Platforms===
'''IMPORTANT''': Ask [mailto:presales_AT_innovaphone_D0T_com innovaphone Presales Team] for possible interop configuration recommendations and pitfalls before you order the WiFi equipment and start with the roll-out.

Note that availability and combinations of controllers and access points may be subject to change by the manufacturer and are not in the responsability of innovaphone. Errors and omissions excepted.

Wi-Fi infrastructures not listed in this document are not supported. Use of the IP73 in unsupported infrastructures is at your own risk.

{| class="wikitable"
|+Certified WLAN Platforms as of March 2026
!AP Model
!Controller Model
!SW Version
!Test date
!Report
|-
! colspan="5" |Aruba
|-
|AP 303, 304, 305, 314, 315, 324, 325, 334, 335, 344, 345, 504, 505, 514, 515, 534, 535, 554, 555, 635, 655
|7000/7200/9000/MX-VA-xxx
|8.10.0.13 LSR
|09-Sep-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_aruba_networking_8_10_0_13.pdf}}]]
|-
|AP 303, 304, 305, 314, 315, 324, 325, 334, 335, 344, 345, 504, 505, 514, 515, 534, 535, 554, 555, 635, 655
|Networking Central
|10.4.1.3_90100
|12-Aug-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_aruba_networking_central_10_4_1_3.pdf}}]]
|-
! colspan="5" |Cisco
|-
|AP 1832, 1852, 2802, 3802, 4800, 9105, 9115, 9117, 9120, 9130
|WLC 3504, 5520, 8540, vWLC, Mobility Express Solution
|8.10.162
|04-Feb-2022
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_cisco_wlc_8_10_162.pdf}}]]
|-
|AP 1602, 2602, 3502, 3602, 1702, 2702, 3700, 2802, 3802, 1832, 1852
|WLC 2504, 3504, 5508, 5520, 7510, 8510, 8540, vWLC
|8.5.182
|14-Feb-2022
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_cisco_wlc_8_5_182.pdf}}]]
|-
|AP 1702, 2702, 3702
|Catalyst 9800
|17.3.3
|01-Jun-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_cisco_catalyst_17_3_3.pdf}}]]
|-
|AP 1832, 1852, 2802, 3802, 4800, 9115, 9117, 9120, 9130, 9136
|Catalyst 9800
|17.9.3
|20-Jun-2022
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_cisco_catalyst_17_9_3.pdf}}]]
|-
! colspan="5" |Cisco Meraki
|-
|MR20/MR30H/MR33/MR42/MR42E/MR52/MR53/MR53E/MR70/MR74/MR84 (802.11ac wave 2)
MR36/MR44/MR46/MR46E/MR76/MR86 (802.11ax)
| -
|MR 27.7.1
|29-Sept-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_meraki_mr_27_7_1.pdf}}]]
|-
|MR36/MR44/MR46/MR46E/MR76/MR86 (802.11ax)
CW9162/CW9163E/CW9164/CW9166/CW9166D1 (Wifi 6E)
| -
|MR 30.7
|Nov-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_meraki_mr_30_7.pdf}}]]
|-
! colspan="5" |Extreme Networks (Enterasys/IdentiFi)
|-
|AP 3801, 3805, 3825, 3865, 3935
|Extreme Wireless C25, C35, C2110, C5110, C5210, v2110
|AP:10.51.10
|03-Feb-2020
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_wireless_10_51_10.pdf}}]]
|-
|AP 122, 130, 230, 250, 550, 650
|Extreme Cloud
|AP 10.0r8, Cloud 20.1.1.3
|19-Mar-2020
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_cloud_10_0r8.pdf}}]]
|-
|AP 310i/e, 410i/e, 505i/e, 510i/e, 360i/e, 460i/e, 560
|XCC Controllers E1120, E2120, E3120, VE6120/VE6125, VE6120H
|05.16.01.0025
|10-Dec-2020
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_xcc_05_16_01_0025.pdf}}]]
|-
|AP305c/cx, 410c, 460c, 510c/cx, 650
|Extreme Cloud C25, C35, C2110, C5110, C5210, v2110
|AP 10.2.4.0, Cloud 20.1.1.3
|20-Jan-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_cloud_10_2_4_0.pdf}}]]
|-
|AP310i/e, 410i/e, 460i/e, 510i/e, 650i
|Extreme WING NX 5500, 75xx, 9500, 9510, 9600, 9610, VX9000
|7.5.2.0
|12-Apr-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_wing_7_5_2_0.pdf}}]]
|-
|AP 305c/305cx, 410c, 460c, 510c/510cx, 650/650x, 4000, 5010
|Extreme Cloud iQ
|AP 10.8.3.0, Cloud 25.4.3-40
|Aug-2025
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_extreme_cloud_10_8_3_0.pdf}}]]
|-
! colspan="5" |Fortinet
|-
|AP1010/1014/1020/822/832, APU221EV/U223EV/U321EV/U323EV/U421EV/U423EV
|MC1550/3x00/4x00/5000/6000 FortiWLC-50D ,200D, 500D, 1000D, 3000D FWC- VM-50, 200, 500, 1000, 3000
|8.5-2-5
|03-Jun-2021
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_fortinet_wlc_8_5_2_5.pdf}}]]
|-
! colspan="5" |Huawei
|-
|AirEngine5760-51/5760-22W/6760-X1/6760-X1E/6760R-51/6760R-51E/8760-X1-PRO/8760R-X1/8760R-X1E
|AirEngine 9700-M1, AC6508/6805/6800V, iMaster NCE-Campus
|V200R022C10SPC100
|10-May-2023
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_huawei_airengine_V200R022C10SPC100.pdf}}]]
|-
! colspan="5" |Juniper Mist
|-
|AP34, AP45
|Mist Cloud
|0.12.26354
|Aug-2023
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_juniper_0_12_26354.pdf}}]]
|-
|AP12, AP32, AP33, AP41, AP 43, AP61, AP 63
|Mist Cloud
|0.12.27139
|Feb-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_juniper_0_12_27139.pdf}}]]
|-
! colspan="5" |Ruckus
|-
|SmartZone ZoneFlex R300, R310, T300, T310, R500, R510, H510, R600, R610, R710, R720
|SmartZone platform, vSZ-(H,E,D), SZ100/300
|5.2.0.0.699
|27-Apr-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_ruckus_smartzone_5_2_0_0.pdf}}]]
|-
|SmartZone ZoneFlex R350, R350e, T350, R550, R650, R750, T750, R850, R500, R510, R610, R710, R720
|SmartZone platform, vSZ-(H,E,D), SZ144/300
|6.1.2.0.404
|29-Apr-2024
|[[File:P2pdf.png|40px|link={{fullurl:Special:FilePath/i63_interop_ruckus_smartzone_6_1_2_0.pdf}}]]
|}

=== DAS Compatibility ===
[http://en.wikipedia.org/wiki/Distributed_antenna_system Distributed Antenna Systems (DAS)] provide a cost-effective solution for extending radio coverage inside large facilities. Simply put, a DAS can be seen as a long cable starting at a base station or access point to which many antennas are connected. While the architecture can be utilized to mitigate certain coverage issues, the innovaphone IP73 was not designed to accommodate for such RF environments. Furthermore it is difficult to ascertain and ensure WLAN reliability in regard to interference, capacity, roaming, location-based services, and some important [http://en.wikipedia.org/wiki/IEEE_802.11n 802.11n] features, such as [http://en.wikipedia.org/wiki/Multiple-input_multiple-output MIMO]. As a consequence thereof, innovaphone will not endorse nor provide RF support for WiFi deployments over any Distributed Antenna System.

=== WPA3 Compatibility ===
The IP73 already supports the configuration option for ''WPA3''. However, this should not yet be actively used. 
''WPA3'' is currently only recommended for demo purposes. Support for ''WPA3'' is implemented, but no successful interoperability tests have been performed. WPA3 is not recommended being used except for demo purposes.

=== U-APSD Required ===
U-APSD is a power saving function that is always enabled on the IP73. It must also be enabled/supported on the AP to avoid packet loss/voice problems.

==Configuration==
IP73 configuration is done via WinPDM-application available at [https://store.innovaphone.com the Software section of the innovaphone App Store]. Use of desktop programming kit (IP62/IP64/IP65) (50-00060-021) is required.

=== Security ===
From version 7.x onwards, the IP73 firmware includes several changes to achieve compliance with the EU Radio Equipment Directive (RED) and the Cybersecurity Delegated Act.

This requires some additional configuration changes to get the handset operational:

====New handset initial configuration====
{{IP73_703_WinPDM_Auth}}

Resolution is to enter the [[#Shortcuts|default admin access code '''40022''']] and afterwards to either disable WinPDM Authentication or change the Admin access code:

[[Image:IP73 703 WinPDMAuth.png|ip73_703_winpdmauth.png/]]

====Configuration changes for PBX connection====
For handsets running firmware 7.x, the following settings must be configured via WinPDM in order to enable a PBX connection:
* Unite connection mode must be set to ‘Off’ at [Device/Unite/Connection mode].
* Admin access code must be set at [Device/General/Admin access code]. 5 - 10 characters required.
* Phone lock code must be set at [Device/Settings/Force phone lock]. 4 - 8 characters required. By setting the phone lock code the phone lock will be applied for every subsequent bootup. Phone lock is enforced on by default but can be turned off by parameter [Device/Settings/Force phone lock] or by admin menu in handset GUI. Note that handset does not comply with RED by turning off forced phone lock!
* Security has also been strengthen by disabling some outdated security protocols by default. If a service is no longer working after upgrade try to use more modern cryptographic protocol or set parameter “<service>/Allow outdated security protocols” to ‘Yes’.

===PBX Registration===
====Authentication via client certificate====
The recommended way to register an IP73 handset at the innovaphone PBX is SIP over TLS with authentication by a client certificate. The IP73 handset is delivered with a preinstalled device certificate already trusted by an innovaphone PBX.

Prerequisites on the PBX for such type of authentication are:

*The issuer of the IP73 client certificate is on the Trust List of the PBX gateway
*The CN of the client certificate used by IP73 equals the MAC address of the IP73 itself (alternatively other CN and registration identity can be used)
*User Object contains a Device with a Hardware Id matching the MAC address of the IP73

On the IP73 the following settings must be configured. Note that the handset parameters (including the certificate selection) are opened in the ''Numbers'' tab of the WinPDM software:
*VoIP->SIP
**SIP TLS client certificate: <select certificate with MAC address as CN> or <Automatic if preinstalled certificate is used>
**SIP Transport: TLS
**Primary SIP proxy: <IP-address of the PBX> or <DNS-name of PBX>
**SIP proxy ID: <PBX system name>
**SIP proxy password: <no password is required>
**Registration and Authentication identity: MAC address

====Authentication via username/hardware id and password====
*VoIP->General->Endpoint ID: username or hardware id on User Object
*VoIP->SIP
**SIP Transport: TCP or UDP
**SIP proxy password: <password on the User Object or PBX System password, depending on Users Device configuration>
**Registration and Authentication identity: Endpoint ID

=== ICE/TURN ===
ICE is enabled by default. It is required to provide STUN and TURN server configuration under VoIP->General to secure correct negotiation of media channels.

=== Factory Reset ===
You can use the local ''Admin menu'' on the Phone or the WinPDM Software (Rightclick on the device) to make a Factory Reset.

=== MWI for IP73===
The IP73 can be configured to display a message waiting indication / MWI.
You need a programming shell and the WinPDM software (available for download in our [https://store.innovaphone.com/release/141A000/download.htm Store] under the Software tab).
*Connect programming cradle to the administration PC
*Install WinPDM and start the application
*Place IP73 into the programming cradle
*If the IP73 is recognized in WinPDM, the parameter settings can be opened by switching to the Numbers tab (1)
*select the respective device type (2 -> WH2 = IP73) and double-clicking the device line (3).
*Select menu Device (4) and step to Message Centre (5)
*Insert the number of the voicemail object for the Message Centre Number (6)
*Insert the user number for the voice mail number (7)
Confirm settings with OK and ensure correct synchronisation of config changes to the handset. Reset of handset is recommended.

[[Image:WIFIMwi.PNG|wifimwi.png/]]

===Central Phonebook Access===
The device offers access to a central LDAP-based directory. Following configuration steps have to be carried out by the administrator:

'''Device Configuration via the WinPDM application'''
* Device has to be plugged into programming cradle and edited via WinPDM
* Device has to be operated with at least firmware '''6.1.13''' available at the [https://store.innovaphone.com innovaphone store].
* Open section Device and step to Central phonebook. Change the central phonebook mode to LDAP and enter the appropriate parameters for the ldap directory to be queried.

For innovaphone PBX query, the following settings and attributes can be used and adapted to the PBX setup.

[[image:IP73_PBX_query.png|ip73_pbx_query.png/]]

In case of using LDAP-secure-queries, upload of the LDAP-server-'''ROOT''' certificate to the IP73 trust list is required:

[[image:IP73_Certificate.png|ip73_certificate.png/]]

==Troubleshooting==
Log Options can be configured in the WinPDM software, under Device->Log.

===Remote PCAP Tracing===
You can activate the remote PCAP interface and Trace flags directly in the phone configuration (Admin Menu :: Logging :: Mode) or via WinPDM under Device->Log->PCAP capturing: RPCAP.

Only IP traces are available via RPCAP, no innovaphone or device internal traces are logged.

===PCAP to file via USB Tracing===
It is possible to store PCAP trace file in the ''pcap'' folder on the handset by setting in the phone configuration (Admin Menu :: Logging :: Mode) or via WinPDM under Device->Log->PCAP capturing the option "PCAP to file".

To access the file set Device -> General -> USB behavior to "Ask" and select "File transfer", when connect the handset to the WinPDM. Navigate to the folder ''pcap'' on the ''Handset diagnostics'' drive.

===Trace Options===
Following additional trace options are available:

*WLAN Trace
*Configuration Trace
*GUI Trace
*GLI Trace
*Unite Trace
*VoIP Trace
*System Trace
*Protector Trace
*SaS Trace
*Bluetooth Trace

The resulting traces are available via USB file transfer and are encrypted. The encrypted log files can be encrypted by support only.

===Logging via Syslog, SFTP or logfile===

The handset can be configured to send Syslog messages to a Syslog server, an SFTP server or to a local logfile located in the folder ''tracelog''.

The configuration is available via WinPDM Device -> Log -> Syslog or SFTP.

===Handset Error Messages===

====No network====
The ''No network'' message indicates missing WLAN connection. It can be caused by wrong settings for SSID, Security, reg. domain and WLAN channels or lack of coverage.

====No access====
The ''No access'' message is caused by missing IP connectivity to the PBX or wrong configuration for authentication at the PBX.

== Shortcuts ==
There are some hidden tools for information and analysis, which can be accessed via specific menus and codes:

;Handset Device Information
:''*#34#'' in the main display

;RSSI Indicator
:''*#76#'' in the main display. Type again to exit.
: Here you find the following information in the display:
:* Line 1: SSID
:* Line 2: Current AP
:* Line 3: Current AP MAC
:* Line 4: Previous AP
:* Line 5: Previous AP MAC

;Site Survey Tool
:''*#77#'' in the main display.

;Admin Menu
: Go to the ''Settings menu'' and type in ''40022''

==Known Problems==

===Packet loss and voice quality issues with non-tested WLAN AP and IP73===

'''Issuer: Ascom'''

'''Published: 2022-12-07'''

'''Background''' 
It has come to our (Ascom) knowledge that in later Aruba software versions than Ascom-certified v.8.7.1.1 there is a critical issue affecting clients using power save (U-APSD). 
Data packets will not be transmitted properly to clients in power save.

'''Affected Ascom Certified Aruba Access Points:''' 
7000/7200/9000/MX-VA-xxx Controllers 
AP-303, 304, 305, 314, 315, 324, 325, 334, 335, 344, 345, 
504, 505, 514, 515, 534, 535, 554, 555, 635 

'''Typical symptoms are:''' 
Poor voice quality issues. 

'''Workaround''' 
Currently none available. Disabling U-APSD on the SSID isn’t a viable workaround as this is a requirement for Ascom i63 handsets in enterprise-grade VoWi-Fi deployments. 
Thus it is strongly recommended to avoid upgrades to v. 8.9.x and higher at this point. 

'''Solution''' 
Update Aruba equipment to ArubaOS-8.10.0.11, see [https://arubanetworking.hpe.com/techdocs/ArubaOS-8.x-Books/Release-Notes/810/ArubaOS-8.10.0.11-Release-Notes.pdf Aruba Release notes (search for Ascom)] for details.

===Bluetooth automatically disabled===

'''Issuer: Ascom''' 

'''Version''' 
Handset Firmware 4.0.6

'''Detailed Information''' 
If you have enabled Bluetooth over WinPDM and you want to configure (establish connection to the headset), you get the message "Bluetooth automatically disabled".

'''Background''' 
The chip responsible for handling wireless radio communication, WLAN and BT, has a bug in its current firmware. Thus, using WLAN and BT on similar frequency bands does not work well.

'''Solution/Workaround''' 
Bluetooth is prohibited to be used when WLAN band 2.4 is in use by being automatically disabled. Bluetooth can only be used when WLAN on the 2.4 GHz band is inactive. 
You can disable WLAN 2.4 band over the WinPDM tool.

==Related Articles==
*[[IP73 Technical Data EN]]
*[[Reference:IP62 WLAN WiFi Wireless IP-Phone]]

Reference16r1:Concept App Service Connector for Microsoft 365

2026-10-13T14:35:11Z

Tfu: App trace: wait at least 12 minutes instead of 5 before saving the log

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 16r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).
It is also possible to search for your own contacts.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V16r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid on user presence synchronisation]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid on calendar presence synchronisation]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

=== Contact Search ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure_Contact_Search_by_Connector_for_Microsoft365|Howto guide for basic configuration aid on contact search]].

==== Technical Overview ====
Introduced in 16r1 the Connector for Microsoft 365 will offer a possibility to search for your own contacts (Teams, Exchange online) via the Graph API.

When the configuration of the connector for Microsoft 365 Contact Search is complete, the app connects to Microsoft to receive a token with the contact search app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, the user can search with the Phone App, for example (a myApps search provider will be provided for all apps looking using search providers looking up contacts). The search string is made available to the Connector for Microsoft 365 via the microsoft365-api. The results are sent to the consumer, e.g. the Phone App and presented there. 
 
A user subscription is started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 

* User subscriptions are renewed every 60 minutes.
* License Check is made every hour.

'''Be aware:''' Since the Connector for Microsoft 365 is an app in the Scope of myApps App Platform, IP Phones and other services not using Apps cannot benefit from this search service.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with multi-factor authentication (MFA) are not supported as technical communication users for the Connector.

''We recommend creating a dedicated user account for this purpose rather than using an existing user account.'' 
''This limitation applies only to technical users used for the Connector for Microsoft 365, not standard user accounts. MFA can be used for real users.''

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

== Contact Search ==
=== Limited scope of searchable contacts ===
The contact search only queries the default Contacts folder of the searching user's mailbox via the Microsoft Graph API ('''/users/{id}/contacts'''). The following are currently '''not''' included in the search results:

* Custom/subordinate contact folders
* Contact folders of other mailboxes shared with the user
* The organizational Global Address List (GAL)

Creating and managing custom contact folders is no longer available in Microsoft's own cloud-based Outlook (Outlook on the web / new Outlook). Contacts in folders created earlier are still displayed there, listed under a different category - but the standard Microsoft Graph API contact search used by the Connector does not find these contacts.

Search of the organizational Global Address List (GAL) is currently not supported by the Connector.

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* App WebSocket
* Config
* Database
* HTTP client
* TCP
* TLS
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 12 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365#Create an App for syncing Teams to PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Contact Search by Connector for Microsoft365]]

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

Reference15r1:Concept App Service Connector for Microsoft 365

2026-10-13T14:35:10Z

Tfu: App trace: wait at least 12 minutes instead of 5 before saving the log

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 15r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V15r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure_Calendar_Presence_Sync_by_Connector_for_Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* Database
* HTTP client
* TLS
* TCP
* App WebSocket
* Config
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 12 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365#Create_an_App_for_syncing_Teams_to_PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto15r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto15r1:Configure Calendar Presence Sync by Connector for Microsoft365]]

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

Reference14r2:Concept App Service Connector for Microsoft 365

2026-10-13T14:35:07Z

Tfu: App trace: wait at least 12 minutes instead of 5 before saving the log

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 14r2

= Overview =

Connector for Microsoft 365 synchronises Microsoft Teams presences with the innovaphone PBX and back.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== Configuration ===
Please have a look into our [[How to: Configure Connector for Microsoft365|Howto guide for basic configuration aid]].

=== Technical Overview ===
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

==== User Matching ====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

==== Mapping Table ====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

==== Master/Slave ====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

== Related Articles ==

=Known Limitation=

== Line states set by the PBX does not block calls in Teams ==
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
== Maximum number of supported users ==
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

== Synchronization Delay ==
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the used resource "presence" an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 

== Communication User (UserSynctoPbx) ==
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.

== Multiple sites / instances require multiple communication users ==
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

== Subscription Timeout ==

=== Situation ===
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

=== Impact ===
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=

==Creating an app trace==
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* Database
* HTTP client
* TLS
* TCP
* App WebSocket
* Config
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 12 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

==GUI Feedback==
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

===No connection to Master PBX===
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

===Presence subscription failed===
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

==Teams License for communication user==
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

==SSL Certificate for notification URL==
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

==Correctness of notification URL==
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/137786/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto14r2:Configure Connector for Microsoft365]]

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

Reference16r1:Concept App Service TechAssist

2026-10-06T08:09:16Z

Tfu: /* Configurations */

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

== Applies To ==

* innovaphone PBX from version 15r1

== 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|ap_app_installer.png/|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|concept_techassist.png/|concept_techassist.png/]]
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.

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

==== Tests ====
;Execute all
:This Button will trigger all tests. Keep in mind that this trigger used the cached version of commands.
;Execute all without cache
:This Button will trigger all tests but will clear the cache for all commands before
;Execute a dedicated test
: In this execution, no cache will be used

==== 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, storage) {
// 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, storage) {
// 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_"commands"|commands-documentation]] below.
; minBuild
: int | The minimum build version of the app, that the Test will be executed.
; oneTime
: bool | If ''true'' the test will be self-deactivated after the first successful execution.
; 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 ''(effect at the moement)''
: <code>dect</code> - all Dect Gateways
: <code>phone</code> - all Phones
: <code>monitoring</code> - all categories based on Monitoring settings
;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|Reference15r1: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, storage)</code> in your JavaScript object. This method has three 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, storage)" 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>
 

;storage
:If the test has written something to the test volatile memory during the last execution, you will get the last value back here. (Note that the storage is not available for one-time tests in the code editor. There you will always get an empty storage)

===== 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>)
;storage
: string | an optional string, which can be json or similar, that is stored for this test. The next time the test is executed, the payload saved here is available inside the test again.

<syntaxhighlight lang="javascript">
test: function (cmd, results, storage) {
// 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, storage) {
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, storage) {
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_build() : object ======
You will receive back the current version build of the app

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var build = cmd.get_build();
console.log(build);
// 15012456
</syntaxhighlight>
</spoiler>

====== 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 ===
; use "get_pbx_objects_from_config()" to get Objects from PBX config
: To really get all the required objects (dyn PBXes, different views, deleted objects), there are a few things to consider. It is therefore advisable to always use this function in a test.
; 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.

== Monitoring ==
The App supports a monitoring interface where well known IT-Monitoring Systems or other Statistics Services can connect and collect various data for the whole innovaphone installation.

===Requirements===
* Only devices that are known by the ''Devices App'' will be included in the monitoring data
* Only devices that have a non-empty "Name" in the ''Devices App'' will be included in the monitoring data
* Depending on your monitoring system (to support the automatic host matching magic) it can be needed that all devices has the same ''Name'' in your ''Devices App'' and your external System (Usually the FQDN is used)

===Configurations===
* In the TechAssist Plugin in Settings (former PBX Manager), you have to configure the credentials for the HTTP authorization to get monitoring data
* In the TechAssist App in the settings area, you have to:
** enable/disable the whole monitoring feature. Default is disabled.
** select categories (PBXes, Gateways, AP Platforms, Apps, DECT, Phones) which should be included in the monitoring data
* For all app services that provide statistics, the TechAssist app object must have access rights to these apps (the apps must be checked in the "Apps" tab of the PBX object)
** All Metrics will be placed (in the monitoring output) at the AP where TechAssist is running

===Internal Timers===
*The data for monitoring systems will be updated every 15 minutes by default. You can adjust this timer in the App Settings.
*App Metrics will be updated every 1 minute internally
*App Metrics for the TechAssist itself always have live values

=== HTTP Response Codes ===

* 501 - Monitoring feature is disabled...
* 503 - Service is starting... | You have to try it again later. The app service is starting.
* 503 - Data will be collected... | You have to try it again later. The first bunch of data will be collected at this moment.

===Internal Cached Monitoring Data===
The monitoring data is cached internally. After starting the app, no monitoring data is processed at all to save resources if this function is not used.
If the first call is made to an interface, the data is prepared in Background and you will get a "503 - Data will be collected...". This means that the first call fails. From then on, the app knows that monitoring data is being retrieved and prepares the data in a 1-minute interval so that a call to the monitoring system receives the cached data.

===Supported Integrations===
We support various output formats over different interfaces. Your System can pull the information and append in the needed Interface/Format to the URL. <code><nowiki>Example: https://apps.slu.de/slu.de/techassist/monitoring/JSON (Here is "JSON" the used interface, see below)</nowiki></code>

If you use an old/legacy system that only support http basic-auth instead of digest-auth you can add a "/basic" to the endpoint url. <code><nowiki>Example: https://</nowiki>apps.slu.de/slu.de/techassist'''/basic'''/monitoring/JSON</code>

==== RAW ====
The interface "/RAW" provides the internal TechAssist format as JSON.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
[
{
"id": "1",
"title": "pbx.domain.de",
"metrics": [
{
"id": "online",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "serialnumber",
"value": "005056001338",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "product",
"value": "IPVA",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "version",
"value": "15r1 dvl [15.1.0130/1000/0]",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "versionIsSupported",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "uptime",
"value": 2747,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "CPU",
"value": 1,
"valuePercent": 1,
"comment": null,
"min": 0,
"max": 100
},
{
"id": "CPU-R",
"value": 0,
"valuePercent": 0,
"comment": null,
"min": 0,
"max": 26000
},
{
"id": "MEM",
"value": 46,
"valuePercent": 0.09,
"comment": null,
"min": 0,
"max": 49793
},
{
"id": "ETH0",
"value": 10,
"valuePercent": 0,
"comment": null,
"min": 0,
"max": 1000000
}
]
},
{
"id": "47",
"title": "ap.domain.de",
"metrics": [
{
"id": "online",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "serialnumber",
"value": "00155db3c306",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "product",
"value": "AppPlatform x86_64",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "version",
"value": "120010 (15r1 1510130 dvl )",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "versionIsSupported",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
""
]
}
]
</syntaxhighlight>
</spoiler>

==== CSV ====
The interface "/CSV" provides a simple text based comma separated structure.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
<Hostname>;<Metric>;<Value>;<Result>;<Comment>
pbx.domain.de;"online";true;
pbx.domain.de;"serialnumber";005056001338;
pbx.domain.de;"product";IPVA;
pbx.domain.de;"version";15r1 dvl [15.1.0130/1000/0];
pbx.domain.de;"versionIsSupported";true;
pbx.domain.de;"uptime";3050;
pbx.domain.de;"CPU";2;null
pbx.domain.de;"CPU-R";0;null
pbx.domain.de;"MEM";0.09;null
pbx.domain.de;"ETH0";18;null
ap.domain.de;"online";true;
ap.domain.de;"serialnumber";00155db3c306;
ap.domain.de;"product";AppPlatform x86_64;
ap.domain.de;"version";120010 (15r1 1510130 dvl );
ap.domain.de;"versionIsSupported";true;
</syntaxhighlight>
</spoiler>

==== JSON ====
The interface "/JSON" provides a JSON formatted structure.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
{
"pbx.domain.de": [
{"device":"pbx.domain.de","metric":"online","value":"true","result":true"comment":""},
{"device":"pbx.domain.de","metric":"serialnumber","value":005056001338,"comment":""},
{"device":"pbx.domain.de","metric":"product","value":IPVA,"comment":""},
{"device":"pbx.domain.de","metric":"version","value":15r1 dvl [15.1.0130/1000/0],"comment":""},
{"device":"pbx.domain.de","metric":"versionIsSupported","value":"true","result":true"comment":""},
{"device":"pbx.domain.de","metric":"uptime","value":3050,"comment":""},
{"device":"pbx.domain.de","metric":"CPU","value":2,"comment":"null"},
{"device":"pbx.domain.de","metric":"CPU-R","value":0,"comment":"null"},
{"device":"pbx.domain.de","metric":"MEM","value":0.09,"comment":"null"},
{"device":"pbx.domain.de","metric":"ETH0","value":18,"comment":"null"}
],
"ap.domain.de": [
{"device":"ap.domain.de","metric":"online","value":"true","result":true,"comment":""},
{"device":"ap.domain.de","metric":"serialnumber","value":00155db3c306,"comment":""},
{"device":"ap.domain.de","metric":"product","value":AppPlatform x86_64,"comment":""},
{"device":"ap.domain.de","metric":"version","value":120010 (15r1 1510130 dvl ),"comment":""},
{"device":"ap.domain.de","metric":"versionIsSupported","value":"true","result":true,"comment":""},
]
}
</syntaxhighlight>
</spoiler>

==== Checkmk ====
The interface "/Checkmk" provides a native integration to your Checkmk system with [https://docs.checkmk.com/latest/en/piggyback.html Piggyback] information for all known hosts.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
<<<<pbx.domain.de>>>>
<<<check_mk>>>
AgentOS: innovaphone TechAssist
Hostname: pbx.domain.de
<<<uptime>>>
3050
<<<kernel>>>
util 0
cpu 1728891356864 0 0 1728891356960 0 0 0 0 0 0
<<<mem>>>
MemTotal: 49793 kB
MemFree: 49747 kB
MemAvailable: 49747 kB
Buffers: 0 kB
Cached: 0 kB
SwapTotal: 0 kB
SwapFree: 0 kB
Dirty: 0 kB
Writeback: 0 kB
<<<lnx_thermal>>>
<<<local>>>
0 "online" - online=1
0 "serialnumber" - serialnumber=005056001338
0 "product" - product=IPVA
0 "version" - version=15r1 dvl [15.1.0130/1000/0]
0 "versionIsSupported" - versionIsSupported=1
0 "CPU-R" - CPU-R=0
0 "ETH0" - ETH0=18
<<<innovaphone>>>
<<<<ap.domain.de>>>>
<<<check_mk>>>
AgentOS: innovaphone TechAssist
Hostname: ap.domain.de
<<<uptime>>>
<<<kernel>>>
<<<mem>>>
<<<lnx_thermal>>>
<<<local>>>
0 "online" - online=1
0 "serialnumber" - serialnumber=00155db3c306
0 "product" - product=AppPlatform x86_64
0 "version" - version=120010 (15r1 1510130 dvl )
0 "versionIsSupported" - versionIsSupported=1
<<<innovaphone>>>
</syntaxhighlight>
</spoiler>

===== Configure your Checkmk installation =====
#Setup your Hosts in Checkmk
#*Make sure that "Checkmk agent / API integrations" in the Hostconfiguration of your Application Platform is set to "API integrations if configured, else Checkmk agent", all other Hosts hat to bet set to "No API integrations, no Checkmk agent".
#Create a new Rule for "Individual program call instead of agent access" in "Setup > Agents > Other integrations"
#*Command line to execute: <code>curl --digest -u "user:pass" https://ap.domain.tld/domain.de/techassist/monitoring/Checkmk</code>
#*Explicit hosts: Set this to the Host of your Application Platform

After that, you can run the service discovery and receive new checks for your devices

[[File:Checkmk new checks.png|frameless|500px|checkmk_new_checks.png/|checkmk_new_checks.png/]]

==== Icinga ====
The interface "/Icinga" provides a native integration to your Icinga system for all known hosts.

{{FIXME|reason=This interface is currently being researched, and it is being checked whether icinga can read such data as expected}}

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
[
{
"_host": "pbx.domain.de",
"_ETH0_ipv4": "10.0.102.7",
"online":1,
"serialnumber":005056001338,
"product":IPVA,
"version":15r1 dvl [15.1.0130/1000/0],
"versionIsSupported":1,
"uptime":3353,
"CPU":1,
"CPU-R":0,
"MEM":0.09,
"ETH0":14
},
{
"_host": "ap.domain.de",
"_eth0_ipv4": "10.0.102.8",
"_eth0_ipv6": "2001:4090:e000:9a1::8",
"online":1,
"serialnumber":00155db3c306,
"product":AppPlatform x86_64,
"version":120010 (15r1 1510130 dvl ),
"versionIsSupported":1
}
]
</syntaxhighlight>
</spoiler>

===== Configure your Icinga installation =====

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

=== Websocket Connections ===
The App holds Websocket connections to various targets. To debug and follow these connections in the logfile you will find special log output for outgoing websocket connections.

You can filter the logfile with <code>Websocket Log</code> to get the Websocket flow. Then a good practice should be to click on these lines and check the lines before.
C:\Users\slu\Downloads\techassist-x86_64-20241112-131349.txt (8 Treffer)
Zeile 9: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::close | {...}
Zeile 12: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::close | {...}
Zeile 18: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::add | {...}
Zeile 22: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::add | {...}
Zeile 34: 11-12 13:13:46.290 techassist@slu.de Websocket Log - ServicesInfoApis::remove | {...}
Zeile 41: 11-12 13:13:46.290 techassist@slu.de Websocket Log - ServicesInfoApis::remove | {...}
Zeile 66: 11-12 13:13:46.307 techassist@slu.de Websocket Log - ServicesInfoApis::find | {...}
Zeile 321: 11-12 13:13:46.324 techassist@slu.de Websocket Log - ServicesInfoApis::find | {...}

Reference16r1:Concept App Service TechAssist

2026-10-06T08:08:49Z

Tfu: /* Configurations */

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

== Applies To ==

* innovaphone PBX from version 15r1

== 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|ap_app_installer.png/|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|concept_techassist.png/|concept_techassist.png/]]
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.

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

==== Tests ====
;Execute all
:This Button will trigger all tests. Keep in mind that this trigger used the cached version of commands.
;Execute all without cache
:This Button will trigger all tests but will clear the cache for all commands before
;Execute a dedicated test
: In this execution, no cache will be used

==== 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, storage) {
// 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, storage) {
// 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_"commands"|commands-documentation]] below.
; minBuild
: int | The minimum build version of the app, that the Test will be executed.
; oneTime
: bool | If ''true'' the test will be self-deactivated after the first successful execution.
; 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 ''(effect at the moement)''
: <code>dect</code> - all Dect Gateways
: <code>phone</code> - all Phones
: <code>monitoring</code> - all categories based on Monitoring settings
;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|Reference15r1: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, storage)</code> in your JavaScript object. This method has three 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, storage)" 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>
 

;storage
:If the test has written something to the test volatile memory during the last execution, you will get the last value back here. (Note that the storage is not available for one-time tests in the code editor. There you will always get an empty storage)

===== 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>)
;storage
: string | an optional string, which can be json or similar, that is stored for this test. The next time the test is executed, the payload saved here is available inside the test again.

<syntaxhighlight lang="javascript">
test: function (cmd, results, storage) {
// 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, storage) {
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, storage) {
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_build() : object ======
You will receive back the current version build of the app

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var build = cmd.get_build();
console.log(build);
// 15012456
</syntaxhighlight>
</spoiler>

====== 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 ===
; use "get_pbx_objects_from_config()" to get Objects from PBX config
: To really get all the required objects (dyn PBXes, different views, deleted objects), there are a few things to consider. It is therefore advisable to always use this function in a test.
; 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.

== Monitoring ==
The App supports a monitoring interface where well known IT-Monitoring Systems or other Statistics Services can connect and collect various data for the whole innovaphone installation.

===Requirements===
* Only devices that are known by the ''Devices App'' will be included in the monitoring data
* Only devices that have a non-empty "Name" in the ''Devices App'' will be included in the monitoring data
* Depending on your monitoring system (to support the automatic host matching magic) it can be needed that all devices has the same ''Name'' in your ''Devices App'' and your external System (Usually the FQDN is used)

===Configurations===
* In the Techassist Plugin in Settings (former PBX Manager), you have to configure the credentials for the HTTP authorization to get monitoring data
* In the TechAssist App in the settings area, you have to:
** enable/disable the whole monitoring feature. Default is disabled.
** select categories (PBXes, Gateways, AP Platforms, Apps, DECT, Phones) which should be included in the monitoring data
* For all app services that provide statistics, the TechAssist app object must have access rights to these apps (the apps must be checked in the "Apps" tab of the PBX object)
** All Metrics will be placed (in the monitoring output) at the AP where TechAssist is running

===Internal Timers===
*The data for monitoring systems will be updated every 15 minutes by default. You can adjust this timer in the App Settings.
*App Metrics will be updated every 1 minute internally
*App Metrics for the TechAssist itself always have live values

=== HTTP Response Codes ===

* 501 - Monitoring feature is disabled...
* 503 - Service is starting... | You have to try it again later. The app service is starting.
* 503 - Data will be collected... | You have to try it again later. The first bunch of data will be collected at this moment.

===Internal Cached Monitoring Data===
The monitoring data is cached internally. After starting the app, no monitoring data is processed at all to save resources if this function is not used.
If the first call is made to an interface, the data is prepared in Background and you will get a "503 - Data will be collected...". This means that the first call fails. From then on, the app knows that monitoring data is being retrieved and prepares the data in a 1-minute interval so that a call to the monitoring system receives the cached data.

===Supported Integrations===
We support various output formats over different interfaces. Your System can pull the information and append in the needed Interface/Format to the URL. <code><nowiki>Example: https://apps.slu.de/slu.de/techassist/monitoring/JSON (Here is "JSON" the used interface, see below)</nowiki></code>

If you use an old/legacy system that only support http basic-auth instead of digest-auth you can add a "/basic" to the endpoint url. <code><nowiki>Example: https://</nowiki>apps.slu.de/slu.de/techassist'''/basic'''/monitoring/JSON</code>

==== RAW ====
The interface "/RAW" provides the internal TechAssist format as JSON.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
[
{
"id": "1",
"title": "pbx.domain.de",
"metrics": [
{
"id": "online",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "serialnumber",
"value": "005056001338",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "product",
"value": "IPVA",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "version",
"value": "15r1 dvl [15.1.0130/1000/0]",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "versionIsSupported",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "uptime",
"value": 2747,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "CPU",
"value": 1,
"valuePercent": 1,
"comment": null,
"min": 0,
"max": 100
},
{
"id": "CPU-R",
"value": 0,
"valuePercent": 0,
"comment": null,
"min": 0,
"max": 26000
},
{
"id": "MEM",
"value": 46,
"valuePercent": 0.09,
"comment": null,
"min": 0,
"max": 49793
},
{
"id": "ETH0",
"value": 10,
"valuePercent": 0,
"comment": null,
"min": 0,
"max": 1000000
}
]
},
{
"id": "47",
"title": "ap.domain.de",
"metrics": [
{
"id": "online",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "serialnumber",
"value": "00155db3c306",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "product",
"value": "AppPlatform x86_64",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "version",
"value": "120010 (15r1 1510130 dvl )",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "versionIsSupported",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
""
]
}
]
</syntaxhighlight>
</spoiler>

==== CSV ====
The interface "/CSV" provides a simple text based comma separated structure.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
<Hostname>;<Metric>;<Value>;<Result>;<Comment>
pbx.domain.de;"online";true;
pbx.domain.de;"serialnumber";005056001338;
pbx.domain.de;"product";IPVA;
pbx.domain.de;"version";15r1 dvl [15.1.0130/1000/0];
pbx.domain.de;"versionIsSupported";true;
pbx.domain.de;"uptime";3050;
pbx.domain.de;"CPU";2;null
pbx.domain.de;"CPU-R";0;null
pbx.domain.de;"MEM";0.09;null
pbx.domain.de;"ETH0";18;null
ap.domain.de;"online";true;
ap.domain.de;"serialnumber";00155db3c306;
ap.domain.de;"product";AppPlatform x86_64;
ap.domain.de;"version";120010 (15r1 1510130 dvl );
ap.domain.de;"versionIsSupported";true;
</syntaxhighlight>
</spoiler>

==== JSON ====
The interface "/JSON" provides a JSON formatted structure.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
{
"pbx.domain.de": [
{"device":"pbx.domain.de","metric":"online","value":"true","result":true"comment":""},
{"device":"pbx.domain.de","metric":"serialnumber","value":005056001338,"comment":""},
{"device":"pbx.domain.de","metric":"product","value":IPVA,"comment":""},
{"device":"pbx.domain.de","metric":"version","value":15r1 dvl [15.1.0130/1000/0],"comment":""},
{"device":"pbx.domain.de","metric":"versionIsSupported","value":"true","result":true"comment":""},
{"device":"pbx.domain.de","metric":"uptime","value":3050,"comment":""},
{"device":"pbx.domain.de","metric":"CPU","value":2,"comment":"null"},
{"device":"pbx.domain.de","metric":"CPU-R","value":0,"comment":"null"},
{"device":"pbx.domain.de","metric":"MEM","value":0.09,"comment":"null"},
{"device":"pbx.domain.de","metric":"ETH0","value":18,"comment":"null"}
],
"ap.domain.de": [
{"device":"ap.domain.de","metric":"online","value":"true","result":true,"comment":""},
{"device":"ap.domain.de","metric":"serialnumber","value":00155db3c306,"comment":""},
{"device":"ap.domain.de","metric":"product","value":AppPlatform x86_64,"comment":""},
{"device":"ap.domain.de","metric":"version","value":120010 (15r1 1510130 dvl ),"comment":""},
{"device":"ap.domain.de","metric":"versionIsSupported","value":"true","result":true,"comment":""},
]
}
</syntaxhighlight>
</spoiler>

==== Checkmk ====
The interface "/Checkmk" provides a native integration to your Checkmk system with [https://docs.checkmk.com/latest/en/piggyback.html Piggyback] information for all known hosts.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
<<<<pbx.domain.de>>>>
<<<check_mk>>>
AgentOS: innovaphone TechAssist
Hostname: pbx.domain.de
<<<uptime>>>
3050
<<<kernel>>>
util 0
cpu 1728891356864 0 0 1728891356960 0 0 0 0 0 0
<<<mem>>>
MemTotal: 49793 kB
MemFree: 49747 kB
MemAvailable: 49747 kB
Buffers: 0 kB
Cached: 0 kB
SwapTotal: 0 kB
SwapFree: 0 kB
Dirty: 0 kB
Writeback: 0 kB
<<<lnx_thermal>>>
<<<local>>>
0 "online" - online=1
0 "serialnumber" - serialnumber=005056001338
0 "product" - product=IPVA
0 "version" - version=15r1 dvl [15.1.0130/1000/0]
0 "versionIsSupported" - versionIsSupported=1
0 "CPU-R" - CPU-R=0
0 "ETH0" - ETH0=18
<<<innovaphone>>>
<<<<ap.domain.de>>>>
<<<check_mk>>>
AgentOS: innovaphone TechAssist
Hostname: ap.domain.de
<<<uptime>>>
<<<kernel>>>
<<<mem>>>
<<<lnx_thermal>>>
<<<local>>>
0 "online" - online=1
0 "serialnumber" - serialnumber=00155db3c306
0 "product" - product=AppPlatform x86_64
0 "version" - version=120010 (15r1 1510130 dvl )
0 "versionIsSupported" - versionIsSupported=1
<<<innovaphone>>>
</syntaxhighlight>
</spoiler>

===== Configure your Checkmk installation =====
#Setup your Hosts in Checkmk
#*Make sure that "Checkmk agent / API integrations" in the Hostconfiguration of your Application Platform is set to "API integrations if configured, else Checkmk agent", all other Hosts hat to bet set to "No API integrations, no Checkmk agent".
#Create a new Rule for "Individual program call instead of agent access" in "Setup > Agents > Other integrations"
#*Command line to execute: <code>curl --digest -u "user:pass" https://ap.domain.tld/domain.de/techassist/monitoring/Checkmk</code>
#*Explicit hosts: Set this to the Host of your Application Platform

After that, you can run the service discovery and receive new checks for your devices

[[File:Checkmk new checks.png|frameless|500px|checkmk_new_checks.png/|checkmk_new_checks.png/]]

==== Icinga ====
The interface "/Icinga" provides a native integration to your Icinga system for all known hosts.

{{FIXME|reason=This interface is currently being researched, and it is being checked whether icinga can read such data as expected}}

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
[
{
"_host": "pbx.domain.de",
"_ETH0_ipv4": "10.0.102.7",
"online":1,
"serialnumber":005056001338,
"product":IPVA,
"version":15r1 dvl [15.1.0130/1000/0],
"versionIsSupported":1,
"uptime":3353,
"CPU":1,
"CPU-R":0,
"MEM":0.09,
"ETH0":14
},
{
"_host": "ap.domain.de",
"_eth0_ipv4": "10.0.102.8",
"_eth0_ipv6": "2001:4090:e000:9a1::8",
"online":1,
"serialnumber":00155db3c306,
"product":AppPlatform x86_64,
"version":120010 (15r1 1510130 dvl ),
"versionIsSupported":1
}
]
</syntaxhighlight>
</spoiler>

===== Configure your Icinga installation =====

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

=== Websocket Connections ===
The App holds Websocket connections to various targets. To debug and follow these connections in the logfile you will find special log output for outgoing websocket connections.

You can filter the logfile with <code>Websocket Log</code> to get the Websocket flow. Then a good practice should be to click on these lines and check the lines before.
C:\Users\slu\Downloads\techassist-x86_64-20241112-131349.txt (8 Treffer)
Zeile 9: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::close | {...}
Zeile 12: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::close | {...}
Zeile 18: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::add | {...}
Zeile 22: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::add | {...}
Zeile 34: 11-12 13:13:46.290 techassist@slu.de Websocket Log - ServicesInfoApis::remove | {...}
Zeile 41: 11-12 13:13:46.290 techassist@slu.de Websocket Log - ServicesInfoApis::remove | {...}
Zeile 66: 11-12 13:13:46.307 techassist@slu.de Websocket Log - ServicesInfoApis::find | {...}
Zeile 321: 11-12 13:13:46.324 techassist@slu.de Websocket Log - ServicesInfoApis::find | {...}

Reference16r1:Concept App Service TechAssist

2026-10-06T08:06:11Z

Tfu: /* Configurations */

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

== Applies To ==

* innovaphone PBX from version 15r1

== 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|ap_app_installer.png/|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|concept_techassist.png/|concept_techassist.png/]]
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.

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

==== Tests ====
;Execute all
:This Button will trigger all tests. Keep in mind that this trigger used the cached version of commands.
;Execute all without cache
:This Button will trigger all tests but will clear the cache for all commands before
;Execute a dedicated test
: In this execution, no cache will be used

==== 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, storage) {
// 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, storage) {
// 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_"commands"|commands-documentation]] below.
; minBuild
: int | The minimum build version of the app, that the Test will be executed.
; oneTime
: bool | If ''true'' the test will be self-deactivated after the first successful execution.
; 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 ''(effect at the moement)''
: <code>dect</code> - all Dect Gateways
: <code>phone</code> - all Phones
: <code>monitoring</code> - all categories based on Monitoring settings
;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|Reference15r1: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, storage)</code> in your JavaScript object. This method has three 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, storage)" 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>
 

;storage
:If the test has written something to the test volatile memory during the last execution, you will get the last value back here. (Note that the storage is not available for one-time tests in the code editor. There you will always get an empty storage)

===== 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>)
;storage
: string | an optional string, which can be json or similar, that is stored for this test. The next time the test is executed, the payload saved here is available inside the test again.

<syntaxhighlight lang="javascript">
test: function (cmd, results, storage) {
// 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, storage) {
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, storage) {
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_build() : object ======
You will receive back the current version build of the app

<spoiler show="show sample code" hide="hide sample code">
<syntaxhighlight lang="javascript">
var build = cmd.get_build();
console.log(build);
// 15012456
</syntaxhighlight>
</spoiler>

====== 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 ===
; use "get_pbx_objects_from_config()" to get Objects from PBX config
: To really get all the required objects (dyn PBXes, different views, deleted objects), there are a few things to consider. It is therefore advisable to always use this function in a test.
; 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.

== Monitoring ==
The App supports a monitoring interface where well known IT-Monitoring Systems or other Statistics Services can connect and collect various data for the whole innovaphone installation.

===Requirements===
* Only devices that are known by the ''Devices App'' will be included in the monitoring data
* Only devices that have a non-empty "Name" in the ''Devices App'' will be included in the monitoring data
* Depending on your monitoring system (to support the automatic host matching magic) it can be needed that all devices has the same ''Name'' in your ''Devices App'' and your external System (Usually the FQDN is used)

===Configurations===
* In Settings, you have to configure the credentials for the HTTP authorization to get monitoring data
* In the TechAssist App in the settings area, you have to:
** enable/disable the whole monitoring feature. Default is disabled.
** select categories (PBXes, Gateways, AP Platforms, Apps, DECT, Phones) which should be included in the monitoring data
* For all app services that provide statistics, the TechAssist app object must have access rights to these apps (the apps must be checked in the "Apps" tab of the PBX object)
** All Metrics will be placed (in the monitoring output) at the AP where TechAssist is running

===Internal Timers===
*The data for monitoring systems will be updated every 15 minutes by default. You can adjust this timer in the App Settings.
*App Metrics will be updated every 1 minute internally
*App Metrics for the TechAssist itself always have live values

=== HTTP Response Codes ===

* 501 - Monitoring feature is disabled...
* 503 - Service is starting... | You have to try it again later. The app service is starting.
* 503 - Data will be collected... | You have to try it again later. The first bunch of data will be collected at this moment.

===Internal Cached Monitoring Data===
The monitoring data is cached internally. After starting the app, no monitoring data is processed at all to save resources if this function is not used.
If the first call is made to an interface, the data is prepared in Background and you will get a "503 - Data will be collected...". This means that the first call fails. From then on, the app knows that monitoring data is being retrieved and prepares the data in a 1-minute interval so that a call to the monitoring system receives the cached data.

===Supported Integrations===
We support various output formats over different interfaces. Your System can pull the information and append in the needed Interface/Format to the URL. <code><nowiki>Example: https://apps.slu.de/slu.de/techassist/monitoring/JSON (Here is "JSON" the used interface, see below)</nowiki></code>

If you use an old/legacy system that only support http basic-auth instead of digest-auth you can add a "/basic" to the endpoint url. <code><nowiki>Example: https://</nowiki>apps.slu.de/slu.de/techassist'''/basic'''/monitoring/JSON</code>

==== RAW ====
The interface "/RAW" provides the internal TechAssist format as JSON.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
[
{
"id": "1",
"title": "pbx.domain.de",
"metrics": [
{
"id": "online",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "serialnumber",
"value": "005056001338",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "product",
"value": "IPVA",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "version",
"value": "15r1 dvl [15.1.0130/1000/0]",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "versionIsSupported",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "uptime",
"value": 2747,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "CPU",
"value": 1,
"valuePercent": 1,
"comment": null,
"min": 0,
"max": 100
},
{
"id": "CPU-R",
"value": 0,
"valuePercent": 0,
"comment": null,
"min": 0,
"max": 26000
},
{
"id": "MEM",
"value": 46,
"valuePercent": 0.09,
"comment": null,
"min": 0,
"max": 49793
},
{
"id": "ETH0",
"value": 10,
"valuePercent": 0,
"comment": null,
"min": 0,
"max": 1000000
}
]
},
{
"id": "47",
"title": "ap.domain.de",
"metrics": [
{
"id": "online",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "serialnumber",
"value": "00155db3c306",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "product",
"value": "AppPlatform x86_64",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "version",
"value": "120010 (15r1 1510130 dvl )",
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
{
"id": "versionIsSupported",
"value": 1,
"valuePercent": null,
"comment": "",
"min": null,
"max": null
},
""
]
}
]
</syntaxhighlight>
</spoiler>

==== CSV ====
The interface "/CSV" provides a simple text based comma separated structure.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
<Hostname>;<Metric>;<Value>;<Result>;<Comment>
pbx.domain.de;"online";true;
pbx.domain.de;"serialnumber";005056001338;
pbx.domain.de;"product";IPVA;
pbx.domain.de;"version";15r1 dvl [15.1.0130/1000/0];
pbx.domain.de;"versionIsSupported";true;
pbx.domain.de;"uptime";3050;
pbx.domain.de;"CPU";2;null
pbx.domain.de;"CPU-R";0;null
pbx.domain.de;"MEM";0.09;null
pbx.domain.de;"ETH0";18;null
ap.domain.de;"online";true;
ap.domain.de;"serialnumber";00155db3c306;
ap.domain.de;"product";AppPlatform x86_64;
ap.domain.de;"version";120010 (15r1 1510130 dvl );
ap.domain.de;"versionIsSupported";true;
</syntaxhighlight>
</spoiler>

==== JSON ====
The interface "/JSON" provides a JSON formatted structure.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
{
"pbx.domain.de": [
{"device":"pbx.domain.de","metric":"online","value":"true","result":true"comment":""},
{"device":"pbx.domain.de","metric":"serialnumber","value":005056001338,"comment":""},
{"device":"pbx.domain.de","metric":"product","value":IPVA,"comment":""},
{"device":"pbx.domain.de","metric":"version","value":15r1 dvl [15.1.0130/1000/0],"comment":""},
{"device":"pbx.domain.de","metric":"versionIsSupported","value":"true","result":true"comment":""},
{"device":"pbx.domain.de","metric":"uptime","value":3050,"comment":""},
{"device":"pbx.domain.de","metric":"CPU","value":2,"comment":"null"},
{"device":"pbx.domain.de","metric":"CPU-R","value":0,"comment":"null"},
{"device":"pbx.domain.de","metric":"MEM","value":0.09,"comment":"null"},
{"device":"pbx.domain.de","metric":"ETH0","value":18,"comment":"null"}
],
"ap.domain.de": [
{"device":"ap.domain.de","metric":"online","value":"true","result":true,"comment":""},
{"device":"ap.domain.de","metric":"serialnumber","value":00155db3c306,"comment":""},
{"device":"ap.domain.de","metric":"product","value":AppPlatform x86_64,"comment":""},
{"device":"ap.domain.de","metric":"version","value":120010 (15r1 1510130 dvl ),"comment":""},
{"device":"ap.domain.de","metric":"versionIsSupported","value":"true","result":true,"comment":""},
]
}
</syntaxhighlight>
</spoiler>

==== Checkmk ====
The interface "/Checkmk" provides a native integration to your Checkmk system with [https://docs.checkmk.com/latest/en/piggyback.html Piggyback] information for all known hosts.

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
<<<<pbx.domain.de>>>>
<<<check_mk>>>
AgentOS: innovaphone TechAssist
Hostname: pbx.domain.de
<<<uptime>>>
3050
<<<kernel>>>
util 0
cpu 1728891356864 0 0 1728891356960 0 0 0 0 0 0
<<<mem>>>
MemTotal: 49793 kB
MemFree: 49747 kB
MemAvailable: 49747 kB
Buffers: 0 kB
Cached: 0 kB
SwapTotal: 0 kB
SwapFree: 0 kB
Dirty: 0 kB
Writeback: 0 kB
<<<lnx_thermal>>>
<<<local>>>
0 "online" - online=1
0 "serialnumber" - serialnumber=005056001338
0 "product" - product=IPVA
0 "version" - version=15r1 dvl [15.1.0130/1000/0]
0 "versionIsSupported" - versionIsSupported=1
0 "CPU-R" - CPU-R=0
0 "ETH0" - ETH0=18
<<<innovaphone>>>
<<<<ap.domain.de>>>>
<<<check_mk>>>
AgentOS: innovaphone TechAssist
Hostname: ap.domain.de
<<<uptime>>>
<<<kernel>>>
<<<mem>>>
<<<lnx_thermal>>>
<<<local>>>
0 "online" - online=1
0 "serialnumber" - serialnumber=00155db3c306
0 "product" - product=AppPlatform x86_64
0 "version" - version=120010 (15r1 1510130 dvl )
0 "versionIsSupported" - versionIsSupported=1
<<<innovaphone>>>
</syntaxhighlight>
</spoiler>

===== Configure your Checkmk installation =====
#Setup your Hosts in Checkmk
#*Make sure that "Checkmk agent / API integrations" in the Hostconfiguration of your Application Platform is set to "API integrations if configured, else Checkmk agent", all other Hosts hat to bet set to "No API integrations, no Checkmk agent".
#Create a new Rule for "Individual program call instead of agent access" in "Setup > Agents > Other integrations"
#*Command line to execute: <code>curl --digest -u "user:pass" https://ap.domain.tld/domain.de/techassist/monitoring/Checkmk</code>
#*Explicit hosts: Set this to the Host of your Application Platform

After that, you can run the service discovery and receive new checks for your devices

[[File:Checkmk new checks.png|frameless|500px|checkmk_new_checks.png/|checkmk_new_checks.png/]]

==== Icinga ====
The interface "/Icinga" provides a native integration to your Icinga system for all known hosts.

{{FIXME|reason=This interface is currently being researched, and it is being checked whether icinga can read such data as expected}}

<spoiler show="show sample output" hide="hide sample output">
<syntaxhighlight lang="javascript">
[
{
"_host": "pbx.domain.de",
"_ETH0_ipv4": "10.0.102.7",
"online":1,
"serialnumber":005056001338,
"product":IPVA,
"version":15r1 dvl [15.1.0130/1000/0],
"versionIsSupported":1,
"uptime":3353,
"CPU":1,
"CPU-R":0,
"MEM":0.09,
"ETH0":14
},
{
"_host": "ap.domain.de",
"_eth0_ipv4": "10.0.102.8",
"_eth0_ipv6": "2001:4090:e000:9a1::8",
"online":1,
"serialnumber":00155db3c306,
"product":AppPlatform x86_64,
"version":120010 (15r1 1510130 dvl ),
"versionIsSupported":1
}
]
</syntaxhighlight>
</spoiler>

===== Configure your Icinga installation =====

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

=== Websocket Connections ===
The App holds Websocket connections to various targets. To debug and follow these connections in the logfile you will find special log output for outgoing websocket connections.

You can filter the logfile with <code>Websocket Log</code> to get the Websocket flow. Then a good practice should be to click on these lines and check the lines before.
C:\Users\slu\Downloads\techassist-x86_64-20241112-131349.txt (8 Treffer)
Zeile 9: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::close | {...}
Zeile 12: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::close | {...}
Zeile 18: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::add | {...}
Zeile 22: 11-12 13:13:46.288 techassist@slu.de Websocket Log - ServicesInfoApis::add | {...}
Zeile 34: 11-12 13:13:46.290 techassist@slu.de Websocket Log - ServicesInfoApis::remove | {...}
Zeile 41: 11-12 13:13:46.290 techassist@slu.de Websocket Log - ServicesInfoApis::remove | {...}
Zeile 66: 11-12 13:13:46.307 techassist@slu.de Websocket Log - ServicesInfoApis::find | {...}
Zeile 321: 11-12 13:13:46.324 techassist@slu.de Websocket Log - ServicesInfoApis::find | {...}

Main Page

2026-09-16T13:35:46Z

Tfu: /* Latest News */

__NOTOC__

<div style="margin:0px; margin-right:10px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0em 1em;">
== Remote Support ==
[[Image:RemoteControl-click.png|left|60px|RemoteControl.png/|Download Remote Control|link=https://store.innovaphone.com/release/download/software/remotecontrolwindowsportable/16r1/remoteControl.exe]]
innovaphone only carries out scheduled remote maintenance via our ticket system by prior consultation. 
As Remote Support Tool, we use our own product Remote Control ([https://www.innovaphone.com/en/all-apps/apps-to-work-with/remote-control-app.html more info]).

You can '''[https://store.innovaphone.com/alpha/download/software/remotecontrolwindowsportable/16r1/remoteControl.exe download]''' the Remote Control client already or use the support link received from our support team. 
After installing and opening the client you can '''pass the shown ID''' or '''use the received link''' to request the support session.

== Searching ==
Searching in wiki works, but is sometimes cumbersome. However, you can have Google do the job for you. Try [https://www.google.de/search?q=site%3Ainnovaphone.com+xml+documentation <code>site:innovaphone.com your search terms</code>] to search the innovaphone sites for matches!

If you still don't find what you are looking for, [mailto:presales@innovaphone.com drop us a message]
</div>


<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">



== Latest News ==

[[User:Tfu|Tfu]] 15:35, 16 September 2026 (CET)
[[Support:WinPDM_Software_3130115_(4.3.0)_released| WinPDM Software 3130115 (4.3.0)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Tfu|Tfu]] 14:41, 16 September 2026 (CEST)
[[Support:Wireless_Handset_Firmware_IP73_1015_(8.0.3)_released| Wireless Handset Firmware IP73 1015 (8.0.3) released]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Lmi|Lmi]] ([[User talk:Lmi|talk]]) 15:40, 27 August 2026 (CEST) [[Support:Firmware V16r1 product/16r1/firmware 1610979 (sr4) available | Version 16r1 Service Release 4]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Lmi|Lmi]] ([[User talk:Lmi|talk]]) 15:40, 27 August 2026 (CEST) [[Support:Firmware V15r1 product/15r1/firmware 1510781 (sr16) available | Version 15r1 Service Release 16]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Lmi|Lmi]] ([[User talk:Lmi|talk]]) 15:40, 27 August 2026 (CEST) [[Support:Firmware V14r2 product/14r2/firmware 1420601 (sr24) available | Version 14r2 Service Release 24]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Aer|Aer]] ([[User talk:Aer|talk]]) 17:16, 25 March 2026 (CET) [[Support:Firmware V13r3 product/13r3/firmware 138046 (sr 36) available | Version 13r3 Service Release 36]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Tfu|Tfu]] 10:48, 24 February 2026 (CET)
[[Support:WinPDM Software 3130114 (4.2.1) released| WinPDM Software 3130113 (4.2.1)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Tfu|Tfu]] 15:28, 13 March 2025 (CEST)
[[Support:Wireless Handset Firmware IP73 1012 (6.1.13) released| Wireless Handset Firmware IP73 1012 (6.1.13) released]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msu|Msu]] ([[User talk:Msu&action=edit&redlink=1|talk]]) 15:54, 18 February 2025 (CEST)
[[Support:Wireless Handset Firmware IP64 10317 (4.3.2)/IP65 10122 (4.3.2) released| Wireless Handset Firmware IP64 10317 (4.3.2)/IP65 10122 (4.3.2)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msu|Msu]] ([[User talk:Msu&action=edit&redlink=1|talk]]) 15:54, 18 February 2025 (CEST)
[[Support:Wireless Handset Firmware D83 10002 (2.0.5) released| Wireless Handset Firmware D83 10002 (2.0.5)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 15:38, 6 February 2023 (CET)
[[Support:Wireless Handset Firmware IP62 3040621 (6.2.7) released| Wireless Handset Firmware IP62 3040621 (6.2.7)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 12:46, 16 June 2021 (CEST))
[[Support:TAPI Service Provider 8188 (hotfix21) available|TAPI Service Provider 8188 (hotfix21)]] is now available from [https://store.innovaphone.com/release/download.htm the Software download area].

[[User:Afi|Afi]] 18:21, 12 October 2020 (CEST)
[[Support:Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8) released| Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 21:30, 27 March 2020 (CET)
[[Support:Wireless Handset Firmware and Management Software product/9.00/wireless 100037 (hotfix19) available| Wireless Package hotfix 19]] is now available from the [http://download.innovaphone.com/ice/9.00#wireless V9 download area].

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">

== New Articles ==

{{Special:Newestpages/all/20}}
</div>

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em; font-size:1">
== More innovaphone Ressources ==
* [http://www.innovaphone.com Home Page]
* [http://download.innovaphone.com Download Site ]
* [http://my.innovaphone.com my.innovaphone ]
* [http://mantis.innovaphone.com/ Ticketing System ]
</div>

Main Page

2026-09-16T12:52:05Z

Tfu: /* Latest News */

__NOTOC__

<div style="margin:0px; margin-right:10px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0em 1em;">
== Remote Support ==
[[Image:RemoteControl-click.png|left|60px|RemoteControl.png/|Download Remote Control|link=https://store.innovaphone.com/release/download/software/remotecontrolwindowsportable/16r1/remoteControl.exe]]
innovaphone only carries out scheduled remote maintenance via our ticket system by prior consultation. 
As Remote Support Tool, we use our own product Remote Control ([https://www.innovaphone.com/en/all-apps/apps-to-work-with/remote-control-app.html more info]).

You can '''[https://store.innovaphone.com/alpha/download/software/remotecontrolwindowsportable/16r1/remoteControl.exe download]''' the Remote Control client already or use the support link received from our support team. 
After installing and opening the client you can '''pass the shown ID''' or '''use the received link''' to request the support session.

== Searching ==
Searching in wiki works, but is sometimes cumbersome. However, you can have Google do the job for you. Try [https://www.google.de/search?q=site%3Ainnovaphone.com+xml+documentation <code>site:innovaphone.com your search terms</code>] to search the innovaphone sites for matches!

If you still don't find what you are looking for, [mailto:presales@innovaphone.com drop us a message]
</div>


<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">



== Latest News ==

[[User:Tfu|Tfu]] ([[User talk:Tfu|talk]]) 15:28, 13 March 2025 (CEST)
[[Support:Wireless_Handset_Firmware_IP73_1015_(8.0.3)_released| Wireless Handset Firmware IP73 1015 (8.0.3) released]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Lmi|Lmi]] ([[User talk:Lmi|talk]]) 15:40, 27 August 2026 (CEST) [[Support:Firmware V16r1 product/16r1/firmware 1610979 (sr4) available | Version 16r1 Service Release 4]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Lmi|Lmi]] ([[User talk:Lmi|talk]]) 15:40, 27 August 2026 (CEST) [[Support:Firmware V15r1 product/15r1/firmware 1510781 (sr16) available | Version 15r1 Service Release 16]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Lmi|Lmi]] ([[User talk:Lmi|talk]]) 15:40, 27 August 2026 (CEST) [[Support:Firmware V14r2 product/14r2/firmware 1420601 (sr24) available | Version 14r2 Service Release 24]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Aer|Aer]] ([[User talk:Aer|talk]]) 17:16, 25 March 2026 (CET) [[Support:Firmware V13r3 product/13r3/firmware 138046 (sr 36) available | Version 13r3 Service Release 36]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Tfu|Tfu]] 10:48, 24 February 2026 (CET)
[[Support:WinPDM Software 3130114 (4.2.1) released| WinPDM Software 3130113 (4.2.1)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Tfu|Tfu]] ([[User talk:Tfu|talk]]) 15:28, 13 March 2025 (CEST)
[[Support:Wireless Handset Firmware IP73 1012 (6.1.13) released| Wireless Handset Firmware IP73 1012 (6.1.13) released]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msu|Msu]] ([[User talk:Msu&action=edit&redlink=1|talk]]) 15:54, 18 February 2025 (CEST)
[[Support:Wireless Handset Firmware IP64 10317 (4.3.2)/IP65 10122 (4.3.2) released| Wireless Handset Firmware IP64 10317 (4.3.2)/IP65 10122 (4.3.2)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msu|Msu]] ([[User talk:Msu&action=edit&redlink=1|talk]]) 15:54, 18 February 2025 (CEST)
[[Support:Wireless Handset Firmware D83 10002 (2.0.5) released| Wireless Handset Firmware D83 10002 (2.0.5)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 15:38, 6 February 2023 (CET)
[[Support:Wireless Handset Firmware IP62 3040621 (6.2.7) released| Wireless Handset Firmware IP62 3040621 (6.2.7)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 12:46, 16 June 2021 (CEST))
[[Support:TAPI Service Provider 8188 (hotfix21) available|TAPI Service Provider 8188 (hotfix21)]] is now available from [https://store.innovaphone.com/release/download.htm the Software download area].

[[User:Afi|Afi]] 18:21, 12 October 2020 (CEST)
[[Support:Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8) released| Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 21:30, 27 March 2020 (CET)
[[Support:Wireless Handset Firmware and Management Software product/9.00/wireless 100037 (hotfix19) available| Wireless Package hotfix 19]] is now available from the [http://download.innovaphone.com/ice/9.00#wireless V9 download area].

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">

== New Articles ==

{{Special:Newestpages/all/20}}
</div>

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em; font-size:1">
== More innovaphone Ressources ==
* [http://www.innovaphone.com Home Page]
* [http://download.innovaphone.com Download Site ]
* [http://my.innovaphone.com my.innovaphone ]
* [http://mantis.innovaphone.com/ Ticketing System ]
</div>

Reference16r1:Concept App Service Connector for Microsoft 365

2026-09-01T14:50:48Z

Tfu: Add Known Limitation: Contact Search does not cover subordinate/shared contact folders or the Global Address List - Co-Authored-By: Pi-Agent

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 16r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).
It is also possible to search for your own contacts.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V16r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid on user presence synchronisation]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid on calendar presence synchronisation]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

=== Contact Search ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure_Contact_Search_by_Connector_for_Microsoft365|Howto guide for basic configuration aid on contact search]].

==== Technical Overview ====
Introduced in 16r1 the Connector for Microsoft 365 will offer a possibility to search for your own contacts (Teams, Exchange online) via the Graph API.

When the configuration of the connector for Microsoft 365 Contact Search is complete, the app connects to Microsoft to receive a token with the contact search app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, the user can search with the Phone App, for example (a myApps search provider will be provided for all apps looking using search providers looking up contacts). The search string is made available to the Connector for Microsoft 365 via the microsoft365-api. The results are sent to the consumer, e.g. the Phone App and presented there. 
 
A user subscription is started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 

* User subscriptions are renewed every 60 minutes.
* License Check is made every hour.

'''Be aware:''' Since the Connector for Microsoft 365 is an app in the Scope of myApps App Platform, IP Phones and other services not using Apps cannot benefit from this search service.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with multi-factor authentication (MFA) are not supported as technical communication users for the Connector.

''We recommend creating a dedicated user account for this purpose rather than using an existing user account.'' 
''This limitation applies only to technical users used for the Connector for Microsoft 365, not standard user accounts. MFA can be used for real users.''

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

== Contact Search ==
=== Limited scope of searchable contacts ===
The contact search only queries the default Contacts folder of the searching user's mailbox via the Microsoft Graph API ('''/users/{id}/contacts'''). The following are currently '''not''' included in the search results:

* Custom/subordinate contact folders
* Contact folders of other mailboxes shared with the user
* The organizational Global Address List (GAL)

Creating and managing custom contact folders is no longer available in Microsoft's own cloud-based Outlook (Outlook on the web / new Outlook). Contacts in folders created earlier are still displayed there, listed under a different category - but the standard Microsoft Graph API contact search used by the Connector does not find these contacts.

Search of the organizational Global Address List (GAL) is currently not supported by the Connector.

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* App WebSocket
* Config
* Database
* HTTP client
* TCP
* TLS
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 5 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365#Create an App for syncing Teams to PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Contact Search by Connector for Microsoft365]]

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

Reference16r1:Concept App Service Connector for Microsoft 365

2026-07-06T09:13:04Z

Tfu:

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 16r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).
It is also possible to search for your own contacts.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V16r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

=== Contact Search ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 16r1 the Connector for Microsoft 365 will offer a possibility to search for your own contacts (Teams, Exchange online) via the Graph API.

When the configuration of the connector for Microsoft 365 Contact Search is complete, the app connects to Microsoft to receive a token with the contact search app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, the user can search with the Phone App, for example (a myApps search provider will be provided for all apps looking using search providers looking up contacts). The search string is made available to the Connector for Microsoft 365 via the microsoft365-api. The results are sent to the consumer, e.g. the Phone App and presented there. 
 
A user subscription is started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 

* User subscriptions are renewed every 60 minutes.
* License Check is made every hour.

'''Be aware:''' Since the Connector for Microsoft 365 is an app in the Scope of myApps App Platform, IP Phones and other services not using Apps cannot benefit from this search service.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with multi-factor authentication (MFA) are not supported as technical communication users for the Connector.

''We recommend creating a dedicated user account for this purpose rather than using an existing user account.'' 
''This limitation applies only to technical users used for the Connector for Microsoft 365, not standard user accounts. MFA can be used for real users.''

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* App WebSocket
* Config
* Database
* HTTP client
* TCP
* TLS
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 5 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365#Create an App for syncing Teams to PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Contact Search by Connector for Microsoft365]]

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

Reference16r1:Concept App Service Connector for Microsoft 365

2026-07-06T09:09:06Z

Tfu: /* Communication User (UserSynctoPbx) */

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 16r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).
It is also possible to search for your own contacts.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V16r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

=== Contact Search ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 16r1 the Connector for Microsoft 365 will offer a possibility to search for your own contacts (Teams, Exchange online) via the Graph API.

When the configuration of the connector for Microsoft 365 Contact Search is complete, the app connects to Microsoft to receive a token with the contact search app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, the user can search with the Phone App, for example (a myApps search provider will be provided for all apps looking using search providers looking up contacts). The search string is made available to the Connector for Microsoft 365 via the microsoft365-api. The results are sent to the consumer, e.g. the Phone App and presented there. 
 
A user subscription is started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 

* User subscriptions are renewed every 60 minutes.
* License Check is made every hour.

'''Be aware:''' Since the Connector for Microsoft 365 is an app in the Scope of myApps App Platform, IP Phones and other services not using Apps cannot benefit from this search service.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with multi-factor authentication (MFA) are not supported as technical communication users for the Connector.

''We recommend creating a dedicated user account for this purpose rather than using an existing user account.'' 
''This limitation applies only to technical users used for the Connector for Microsoft 365, not standard user accounts. MFA can be used for real users.''

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* App WebSocket
* Config
* Database
* HTTP client
* TCP
* TLS
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 5 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365#Create an App for syncing Teams to PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Contact Search by Connector for Microsoft365]]

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

Howto16r1:Configure OAuth2 E-Mail

2026-06-10T07:30:08Z

Tfu: /* Exchange admin center */

The innovaphone PBX and apps can be configured to send E-Mails for various subjects and purposes. Major E-Mail providers intent to discontinue the username/password authentication schemes in favour of OAuth2. PBX and Apps version 16r1 does support OAuth2 authentication for SMTP. Here is a step by step guide how to set up OAuth2 support in Microsoft 365 through the Azure Portal and how to set it up on a Google Gmail account in the Google Cloud Console.

== General Information ==
Most of the large email providers offer the possibility to define an app that is allowed to gain access of a certain scope like SMTP. 
It assigns a Client ID / Client Secret. 
 
Authorization for sending from the mail account needs to be given one time either: 
* By providing resource owner username/password. Sending this to the token endpoint results in an access token and long term refresh token.
* By interactive authorization via a popup dialogue that is loaded from the authorization endpoint. After the credentials are verified, the dialogue redirects to the redirect URI with an authorization code that is traded to an access token and refresh token.
 
The access token is sent for authentication in SMTP. It needs regular refresh, which will be done automatically.

=== Modes ===

* '''Exchange''': Microsoft, with interactive authorization
* '''Microsoft 365''': Microsoft, without interactive authorization (Resource owner and password has to be filled)
* '''Gmail''': Google, with interactive authorization
* '''Google Service Account''': Google, without interactive authorization (Client e-mail, Private Key ID and Private Key of the service account must be provided)
* '''Client secret post''': Generic configuration where all parameters of the client secret post OAuth2 flow can be set.
* '''Private key jwt''': Generic configuration where all parameters of the private key jwt OAuth2 flow can be set.

=== Example Redirect URIs ===

* '''PBX''': <nowiki>https://example-pbx.domain.com/OAUTH2-CLIENT/auth.htm</nowiki>
* '''Reporting''': <nowiki>https://example-ap.domain.com/domain.com/reporting/auth.htm</nowiki>
* '''Fax''': <nowiki>https://example-ap.domain.com/domain.com/fax/auth.htm</nowiki>
* '''Users''': <nowiki>https://example-ap.domain.com/domain.com/usersapp/auth.htm</nowiki>
* '''Connect''': <nowiki>https://example-ap.domain.com/domain.com/messages/auth.htm</nowiki>
* '''AP Manager''': <nowiki>https://example-ap.domain.com/manager/auth.htm</nowiki>

== Microsoft 365 ==
=== Azure Portal ===
Log in to Microsoft Azure Portal (https://portal.azure.com) and go to Microsoft Entra ID.
[[File:AzureMicrosoftEntraID.png|none|thumb|600x600px|/AzureMicrosoftEntraID.png|/AzureMicrosoftEntraID.png]]
Add a new app registration to create client credentials.
[[File:AzureAddAppRegistration.png|none|thumb|600x600px|/AzureAddAppRegistration.png|/AzureAddAppRegistration.png]]
Register the application and maybe already fill in the redirect URI for Web based application type to path OAUTH2-CLIENT/auth.htm at the PBX.
[[File:AzureRegisterAnApplication.png|none|thumb|600x600px|/AzureRegisterAnApplication.png|/AzureRegisterAnApplication.png]]
App registration is complete. Client ID and tenant needs to be configured at the PBX and every app that will be sending e-mails.
[[File:AzureApp.png|none|thumb|600x600px|/AzureApp.png|/AzureApp.png]]
Create a client secret. Note that expiry is limited to no longer than 2 years. The client secret must be renewed before expiry and the new secret configured and interactive authorisation carried out again to ensure continuous operation.
[[File:AzureAddClientSecret.png|none|thumb|600x600px|/AzureAddClientSecret.png|/AzureAddClientSecret.png]]
Copy the client secret. It also needs to be configured at the PBX and every app that will be sending e-mails.
[[File:AzureCopyClientSecret.png|none|thumb|600x600px|/AzureCopyClientSecret.png|/AzureCopyClientSecret.png]]
Add permissions located in APIs my organization uses.
[[File:AzureAddApiPermissionMyOrganization.png|none|thumb|600x600px|/AzureAddApiPermissionMyOrganization.png|/AzureAddApiPermissionMyOrganization.png]]
More precisely located in Office 365 Exchange Online.
[[File:AzureAddApiPermissionExchange.png|none|thumb|600x600px|/AzureAddApiPermissionExchange.png|/AzureAddApiPermissionExchange.png]]
And there in the application permissions.
[[File:AzureAddApiExchangeApplication.png|none|thumb|600x600px|/AzureAddApiExchangeApplication.png|/AzureAddApiExchangeApplication.png]]
Namely SMTP Mail.Send.
[[File:AzureAddApiSendMailAsUser.png|none|thumb|600x600px|/AzureAddApiSendMailAsUser.png|/AzureAddApiSendMailAsUser.png]]
Grant admin permission for Mail.Send.
[[File:AzureGrantApiPermissions.png|none|thumb|600x600px|/AzureGrantApiPermissions.png|/AzureGrantApiPermissions.png]]
API permissions are now granted.
[[File:AzureApiPermissionsGranted.png|none|thumb|600x600px|/AzureApiPermissionsGranted.png|/AzureApiPermissionsGranted.png]]
Tell all redirect URIs that the PBX and the apps will be using during interactive authorization.
[[File:AzureRedirectUris.png|none|thumb|600x600px|/AzureRedirectUris.png|/AzureRedirectUris.png]]
Allow public client flows of OAuth2. Resource Owner Password Credentials Flow has the advantage that it doesn't need interactive authorization.
[[File:AzureAllowPublicClientFlows.png|none|thumb|600x600px|/AzureAllowPublicClientFlows.png|/AzureAllowPublicClientFlows.png]]

=== Microsoft 365 admin center ===
Log in to the Microsoft 365 admin center (https://admin.cloud.microsoft).
[[File:MS365AdminCenter.png|none|thumb|600x600px|/MS365AdminCenter.png|/MS365AdminCenter.png]]
Make sure that Microsoft 365 licenses are assigned to your user.
[[File:MS365UserLicenses.png|none|thumb|600x600px|/MS365UserLicenses.png|/MS365UserLicenses.png]]
Set your user active.
[[File:MS365ActiveUsers.png|none|thumb|600x600px|/MS365ActiveUsers.png|/MS365ActiveUsers.png]]
Locate the Mail tab of your user.
[[File:MS365UserEMail.png|none|thumb|600x600px|/MS365UserEMail.png|/MS365UserEMail.png]]
Allow authenticated SMTP.
[[File:MS365AuthenticatedSMTP.png|none|thumb|600x600px|/MS365AuthenticatedSMTP.png|/MS365AuthenticatedSMTP.png]]

=== PBX Example configuration ===
With this Microsoft setup the OAuth2 configuration for the resource owner password credentials flow can be filled in as follows.
[[File:OAuth2ResourceOwnerPasswordCredentials.png|none|thumb|600x600px|/OAuth2ResourceOwnerPasswordCredentials.png|/OAuth2ResourceOwnerPasswordCredentials.png]]
For interactive authorization this is the OAuth2 configuration. Authorize e-mail access one time and send a test mail to verify everything went well.
[[File:OAuth2InteractiveAuthorization.png|none|thumb|600x600px|/OAuth2InteractiveAuthorization.png|/OAuth2InteractiveAuthorization.png]]

== Gmail ==
=== Preparations ===
Login to the Google Cloud Console (https://console.cloud.google.com), select a project, New project.
[[File:GoogleSelectProject.png|none|thumb|600x600px|/GoogleSelectProject.png|/GoogleSelectProject.png]]
Create the project.
[[File:GoogleCreateProject.png|none|thumb|600x600px|/GoogleCreateProject.png|/GoogleCreateProject.png]]
Client credentials will be created in this project.
[[File:GoogleProjectCreated.png|none|thumb|600x600px|/GoogleProjectCreated.png|/GoogleProjectCreated.png]]
From the library specify the APIs needed to access.
[[File:GoogleApisServicesFromLibrary.png|none|thumb|600x600px|/GoogleApisServicesFromLibrary.png|/GoogleApisServicesFromLibrary.png]]
These are in the Gmail API.
[[File:GoogleApisServicesApiLibrary.png|none|thumb|600x600px|/GoogleApisServicesApiLibrary.png|/GoogleApisServicesApiLibrary.png]]
Choose the Gmail API and enable it.
[[File:GoogleGmailApis.png|none|thumb|600x600px|/GoogleGmailApis.png|/GoogleGmailApis.png]]
Credentials need to be created.
[[File:GoogleGmailApiAdded.png|none|thumb|600x600px|/GoogleGmailApiAdded.png|/GoogleGmailApiAdded.png]]
Invoke the help me choose wizard.
[[File:GoogleCreateCredentialsHelpMeChoose.png|none|thumb|600x600px|/GoogleCreateCredentialsHelpMeChoose.png|/GoogleCreateCredentialsHelpMeChoose.png]]
User data access is needed.
[[File:GoogleCredentialsUserData.png|none|thumb|600x600px|/GoogleCredentialsUserData.png|/GoogleCredentialsUserData.png]]
Configure the consent screen of the interactive authorization.
[[File:GoogleOAuthConsentScreen.png|none|thumb|600x600px|/GoogleOAuthConsentScreen.png|/GoogleOAuthConsentScreen.png]]
Specify the permissions that need to be authorized by the user.
[[File:GoogleOAuthScopes.png|none|thumb|600x600px|/GoogleOAuthScopes.png|/GoogleOAuthScopes.png]]
Its mail.google.com in general.
[[File:GoogleScopeMailGoogleCom.png|none|thumb|600x600px|/GoogleScopeMailGoogleCom.png|/GoogleScopeMailGoogleCom.png]]
And its to send email on the users behalf.
[[File:GoogleScopeAuthGmailSend.png|none|thumb|600x600px|/GoogleScopeAuthGmailSend.png|/GoogleScopeAuthGmailSend.png]]
These are the scopes needed.
[[File:GoogleScopes.png|none|thumb|600x600px|/GoogleScopes.png|/GoogleScopes.png]]
Ask client credentials for Web type application.
[[File:GoogleOAuthClientID.png|none|thumb|600x600px|/GoogleOAuthClientID.png|/GoogleOAuthClientID.png]]
Tell all redirect URIs that the PBX and the apps will be using during interactive authorization.
[[File:GoogleRedirectURIs.png|none|thumb|600x600px|/GoogleRedirectURIs.png|/GoogleRedirectURIs.png]]
Download the credentials. This json file contains all information for OAuth2 configuration.
[[File:GoogleClientCredentialsDownload.png|none|thumb|600x600px|/GoogleClientCredentialsDownload.png|/GoogleClientCredentialsDownload.png]]
Customize the OAuth consent screen
[[File:GoogleOAuthConsentScreenSettings.png|none|thumb|600x600px|/GoogleOAuthConsentScreenSettings.png|/GoogleOAuthConsentScreenSettings.png]]
Start the customization wizard.
[[File:GoogleConsentScreenWizard.png|none|thumb|600x600px|/GoogleConsentScreenWizard.png|/GoogleConsentScreenWizard.png]]
Choose which users may authorize.
[[File:GoogleAudienceExternal.png|none|thumb|600x600px|/GoogleAudienceExternal.png|/GoogleAudienceExternal.png]]
Google workspace users may choose internal audience. Users not in Google workspace proceed with external.
[[File:GoogleContactInformation.png|none|thumb|600x600px|/GoogleContactInformation.png|/GoogleContactInformation.png]]
Add a test user.
[[File:GoogleTestUserAdded.png|none|thumb|600x600px|/GoogleTestUserAdded.png|/GoogleTestUserAdded.png]]

=== PBX Example configuration ===
The OAuth2 parameters can be filled in with the information from the json file downloaded above. Authorize e-mail access one time and send a test mail to verify everything went well.
[[File:OAuth2InteractiveGmail.png|none|thumb|600x600px|/OAuth2InteractiveGmail.png|/OAuth2InteractiveGmail.png]]

== Generic ==

For other e-mail providers the client secret post OAuth2 flow may be configured in a generic way. Details need to be supplied by the e-mail provider.

For the Microsoft 365 setup above it would be as follows with Token endpoint ''<nowiki>https://login.microsoftonline.com/af326a34-169c-469e-946b-1ef57925306b/oauth2/v2.0/token</nowiki>'' Authorization URL ''<nowiki>https://login.microsoftonline.com/af326a34-169c-469e-946b-1ef57925306b/oauth2/v2.0/authorize?scope=https://outlook.office.com/SMTP.Send</nowiki> offline_access'' The configuration appends ''&response_type=code&prompt=consent&login_hint=...&redirect_uri=...&client_id=...'' automatically.[[File:OAuth2ClientSecretPost.png|none|thumb|600x600px|/OAuth2ClientSecretPost.png|/OAuth2ClientSecretPost.png]]
For the Gmail example above the generic confguration would be like this with Token endpoint ''<nowiki>https://oauth2.googleapis.com/token</nowiki>'' Authorization URL ''<nowiki>https://accounts.google.com/o/oauth2/auth?access_type=offline&scope=https://mail.google.com/</nowiki>'' The configuration appends ''&response_type=code&prompt=consent&login_hint=...&redirect_uri=...&client_id=...'' automatically.
[[File:OAith2ClientSecretPostGmail.png|none|thumb|600x600px|/OAith2ClientSecretPostGmail.png|/OAith2ClientSecretPostGmail.png]]
The private key jwt OAuth2 flow can be configured generically as well.[[File:OAuth2PrivateKeyJWT.png|none|thumb|600x600px|/OAuth2PrivateKeyJWT.png|/OAuth2PrivateKeyJWT.png]]

== Related Articles ==
* [[Reference16r1:PBX/Config/Authentication]]
* [[Reference16r1:Apps/PbxManager/Email]]
* [[Reference16r1:Concept App Connect#E-Mail configuration]]
* [[Reference16r1:Concept App Service Fax#Mail Configuration (SMTP_Server)]]
* [[Reference16r1:Concept App Service Reports#Configuration]]
* [[Reference16r1:Concept App Service Users#Users Admin App (innovaphone-usersadmin)]]
* [[Reference16r1:Concept App Platform#SMTP]]

Courseware:IT Plus Overview

2026-05-19T08:14:24Z

Tfu:

''innovaphone Plus'' is a series of courses, each covering advanced aspects of the configuration of innovaphone devices in separate topics. Each topic can be worked through on individually or in any order. Further topics will be added over time. Each topic is based on the latest firmware at the time of creation. All topics based on the same firmware version (e.g. 14r2) are included in the same course of the series.

Access to ''innovaphone Plus'' requires a valid innovaphone ''Plus'' corporate subscription. See [https://www.innovaphone.com/en/partner/training/innovaphone-plus-training.html innovaphone Plus Training] for details.

The rest of this article gives you an overview of the topics covered and in which course they can be found.
__NOEDITSECTION__
{{#invoke-url: https://class.innovaphone.com/moodle-debug/itplus-overview.php?wiki=true}}

Howto16r1:Configure Contact Search by Connector for Microsoft365

2026-04-24T15:34:07Z

Tfu:

==Applies To==
This information applies to
Connector for Microsoft 365 from version 16r1

==More Information==

This article outlines a configuration scheme for Connector for Microsoft365 functionality. 
In preparation, you first will need to configure one Application in your Azure Portal. 
After that, you will install the App in your Application Platform, and configure everything.

===System Requirements===

* Licenses '''innovaphone Connector for Microsoft 365''' per user who wants to use the innovaphone myApps Connector for Microsoft 365.
* '''account in Azure Portal of Microsoft''' (for each of the technical communication users, no permission role needed) 
* Must have access from the internet to your App Platform
** This can be done by using a reverse proxy or other firewall
* The public endpoint '''must have ''' a '''valid, public signed certificate''' (in order to make a trusted SSL connection from the Azure cloud to the Application Platform possible)
** A valid certificate is required in all involved network entities - at least in the App Platform and if used in the Reverse Proxy; to ensure transmission of MS365 HTTPS POST requests to the app service in order to send notifications.
* Admin account for Azure Portal (only necessary for granting needed permission for registered app during setup)

==Installation==

===Configuration in Azure Portal===

====Create an App to search for contacts====
* '''In the Azure Portal of Microsoft you have to add an app registration'''
* '''You only have to give a name for the app'''

[[Image:App_Registration_Connector_for_Microsoft365.png|thumb|none|600px|App Registration|app_registration_connector_for_microsoft365.png/]]

* '''Switch to Certificates & Secrets on the left'''
* '''You only have to configure a client secret and save the value for the configuration of the app'''

[[Image:Authentication_Connector_for_Microsoft365_Calendar.png|thumb|none|600px|authentication_connector_for_microsoft365_calendar.png/]]

* '''Switch to api permissions on the left'''
* '''You have to configure application permission (Contacts.Read) and (User.Read.All) as shown in the picture'''
* '''Grant access to the api permissions, if not possible you have to ask an admin'''

[[Image:Azure_Select_Api-Permission.png|thumb|none|600px|azure_select_api-permission.png/]]
[[Image:Azure_Select_Api-Permission_Application.png|thumb|none|600px|azure_select_api-permission_application.png/]]
[[Image:APIPermission Connector for Microsoft365 ContactSearch.png|thumb|none|600px|APIPermission Connector for Microsoft365 ContactSearch/]]

===Installing and configuring App Platform and PBX===
====Installing the connector app====
* First you need to install the connector app from the App Store:
[[Image:Microsoft365_install_app_1.png|thumb|none|600px|microsoft365_install_app_1.png/]]
* Install the app by selecting
# All apps
# innovaphone AG
# innovaphone myApps Connector for Microsoft 365
# select the current Version
# Click install
[[Image:Microsoft365_install_app_2.png|thumb|none|600px|microsoft365_install_app_2.png/]]
====Creating an instance for the connector app====
* For creating an Instance, in the AP Manager you need to
# select '''innovaphone myApps Connector for Microsoft 365'''
# click '''add'''
[[Image:Microsoft365_create_instance_1.png|thumb|none|600px|microsoft365_create_instance_1.png/]]
* Insert the following information and save
# The technical Instance Name (we suggest microsoft365)
# Your Domain (This should be the domain you have already configured in your PBX and your Application Platform)
# define a password for the communication between the PBX and the app instance
# define a password for the communication between the app instance and the database
''All other fields should be filled automatically''
[[Image:Microsoft365_create_instance_2.png|thumb|none|600px|microsoft365_create_instance_2.png/]]

====Creating the PBX app object using the PBX Manager Plugin====
* Open the PBX Manager and
# select the '''AP <code>InstanceName</code>''' Tile
# Click '''Add an app'''
# Click '''Microsoft365 App'''
[[Image:Microsoft365_pbx_manager_1.png|thumb|none|600px|microsoft365_pbx_manager_1.png/]]
* Specify the '''Name''' and the '''SIP''' (We suggest using '''<code>microsoft365</code>''' for this technical names)
[[Image:Microsoft365_pbx_manager_2.png|thumb|none|600px|microsoft365_pbx_manager_2.png/]]

'''Important:''' Please also add the '''microsoft365-api''' to a suitable Config-Template: Every user who should be able to search via the Connector for Microsoft 365 has to have access to the '''microsoft365-api'''.

====Creating the API object using the PBX Manager Plugin====
* Open the PBX Manager and
# select the '''AP <code>InstanceName</code>''' Tile
# Click '''Add an app'''
# Click '''Microsoft365 API'''
[[Image:Microsoft365_pbx_manager_1.png|thumb|none|600px|microsoft365_pbx_manager_1.png/]]
* The '''Name''' and '''SIP''' has to be '''<code>microsoft365-api</code>'''
[[Image:Microsoft_365_Settings_API.png|thumb|none|600px|microsoft_365_Settings_API.png/]]

====Add the admin app to a user or a template====
To be able to configure the connector app, you need users to have access to the admin app. 
You can achieve this by adding the app to a user, or to a template. 
In this Howto - as an example - we will add the app to the <code>Config Admin</code> template. 
* In the PBX Manager
# select the <code>Templates</code> tile
# click on the <code>Config Admin</code> template
[[Image:Microsoft365_template_1.png|thumb|none|600px|microsoft365_template_1.png/]]
* In the <code>Config Admin</code> template
# open Apps
# Check the <code>app name</code> checkbox
# Save the changes
[[Image:Microsoft365_template_2.png|thumb|none|600px|microsoft365_template_2.png/]]

====Configure the connector with the admin app====
Now your admins (designated groups or configured user) should have access to the connector admin app. 
* A user with access to the app can now see a new tile in the '''All Apps''' area
* The name depends on the configured <code>app name</code> from the PBX Manager plugin
[[Image:Microsoft365_admin_app_1.png|thumb|none|600px|microsoft365_admin_app_1.png/]]

=====Configuration of the Contact Search=====
* For the contact search you select '''Configuration for Contact Search''' in the admin app
# '''ClientIDContactSearch''' - Please insert the Application ID (Client ID) from Azure Portal from the in preparation created Contact Search app
# '''TenantContactSearch''' - Please insert the Directory ID (Tenant) from Azure Portal from the in preparation created Contact Search app
# '''ClientSecretContactSearch''' - Please insert the shared secret from the in preparation created Contact Search app
# '''NotificationURL''' - You need to specify the address Microsoft can send presence updates to
## You need to make sure that you define a URL where you can reach your App Platform from the public internet <code>public.dns</code>
## Next you need the domain you have configured in the app instance before (3.2.2) <code>your.domain</code>
## Next you need the name of the instance you have configured before (3.2.2) <code>microsoft365</code>
## The URL will always be terminated by <code>subscriptions</code>
##* <code>https://public.dns/your.domain/microsoft365/subscriptions</code>

==Related Articles==
[[Reference16r1:Concept App Service Connector for Microsoft 365|Concept App Service Connector for Microsoft 365]] 
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 

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

Reference16r1:Concept App Service Connector for Microsoft 365

2026-04-24T15:33:52Z

Tfu:

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 16r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).
It is also possible to search for your own contacts.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V16r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure_Calendar_Presence_Sync_by_Connector_for_Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

=== Contact Search ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 16r1 the Connector for Microsoft 365 will offer a possibility to search for your own contacts (Teams, Exchange online) via the Graph API.

When the configuration of the connector for Microsoft 365 Contact Search is complete, the app connects to Microsoft to receive a token with the contact search app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, the user can search with the Phone App, for example (a myApps search provider will be provided for all apps looking using search providers looking up contacts). The search string is made available to the Connector for Microsoft 365 via the microsoft365-api. The results are sent to the consumer, e.g. the Phone App and presented there. 
 
A user subscription is started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 

* User subscriptions are renewed every 60 minutes.
* License Check is made every hour.

'''Be aware:''' Since the Connector for Microsoft 365 is an app in the Scope of myApps App Platform, IP Phones and other services not using Apps cannot benefit from this search service.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* Database
* HTTP client
* TLS
* TCP
* App WebSocket
* Config
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 5 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365#Create_an_App_for_syncing_Teams_to_PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Contact Search by Connector for Microsoft365]]

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

Reference16r1:Concept myApps platform services

2026-04-21T09:12:06Z

Tfu: /* Device handling */

[[Category:Concept|myApps]]

myApps platform services provide various operating system specific services which can be used by other ''Apps'' running in the [[{{NAMESPACE}}:Concept myApps|myApps client]]. Those services typically are not available in the browser's JavaScript environment and hence must be implemented in native platform code. Therefore, the platform services are installed as native executable on the respective platform.

When myApps is started in a web browser (and hence has no access to the platform services), some Apps will use [https://en.wikipedia.org/wiki/WebRTC WebRTC] services implemented by the browser instead. For ease of reference, features available in this scenario are also described here.

On windows, the platform services also come with their own web browser in which the myApps web App will be started then. This browser is based on google's [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium] open source software.
= Applies To =

* [[{{NAMESPACE}}:Concept myApps|myApps]]
* myApps for Windows
* myApps for macOS
* myApps for iOS
* myApps for Android
* myApps Web App (WebRTC)
* myApps for IP270
version 16r1

=Features=
Not all features are available or required on all platforms.
{|
! style="text-align: left; font-weight: bold" | Feature
! style="text-align: left; font-weight: bold" | Description
! style="text-align: left; font-weight: bold"| Availability
|-
| || || Windows || iOS || Android || macOS || Browser<ref>This refers to the myApps web application running in a browser with no platform services available</ref>
|IP270
|-
| [[#Device handling|Audio Devices]]|| manage local audio devices to record and playback audio conversations || ✔ || ✔ || ✔ || ✔ || ✔ (audio available but devices managed by web browser) || ✔
|-
| Video || manage local displays and cameras to capture and render video live stream || ✔ || ✔ || ✔ || ✔ || ✔ (video available but devices managed by web browser) || ✔
|-
| Ringer || manage local ringing device || ✔ || ✔ || ✔ || ✔ || ✔ || ✔
|-
| [[#Application sharing|Application sharing]]
|-
|   presenter || share an application || ✔ || ✗ || ✔ || ✔ || ✔ || ✔
|-
|   consumer || view an application shared by the peer || ✔ || ✔ || ✔ || ✔ || ✔ || ✔
|-
| [[#Hot keys|Hot keys]]|| capture key presses for quick invocation of phone apps (e.g. dial selected number) || ✔ || ✗ || ✗ || ✔ || ✗ || ✗
|-
| [[#URL Handler|tel: and sip: URI handler]]|| intercept clicks on tel: and sip: links in web sites to invoke phone apps || ✔ || ✔ || ✔ || ✔ || ✗ || ✗
|-
| [[#User activity|User activity]]|| set presence state according to user activity || ✔ || ✗ || ✗ || ✔ || ✔<ref>limited, see [[#User activity|User activity]] below</ref> || ✔
|-
| Docking || myApps can be docked persistently to the right or left edge of your screens || ✔ || ✗ || ✗ || ✗ || ✗ || ✗
|-
| Multi-windowing || Apps can be launched in separate windows|| ✔ || ✗ || ✗ || ✔ || ✗ || ✗
|-
| [[#Recording|Recording]]|| Calls can be recorded to recording app|| ✔ || ✔ || ✔ || ✔ || ✗ || ✔
|-
| [[#Notifications|Notifications]]|| ||
|-
|   display notifications || display notifications with OS standard mechanism || ✔ || ✔ || ✔ || ✔ || ✔ || ✗
|-
|   push notifications || receive push notifications while myApps is not running || ✗ || ✔ || ✔ || ✔ || ✔<ref>The browser needs to be running in order to receive push notifications.</ref> || ✗
|-
|   chat and apps || display notifications for chat and other apps || ✔ || ✔ || ✔ || ✔ || ✔ || ✗
|-
|   calls || display notifications for incoming calls || ✔ || ✔ || ✔ || ✔ || ✗<ref>Call notifications are only displayed locally while the phone or softphone app is started.</ref> || ✗
|-
| [[#Local phonebook access|Local phonebook]]|| access local phone book || ✔ || ✔ || ✔ || ✔ || ✗ || ✗
|-
| [[#Microsoft Office Integration|Office presence provider]]|| maps PBX presence state to Microsoft office presence state || ✔ || ✗ || ✗ || ✗ || ✗ || ✗
|-
| [[#Call an external application for calls|External application start]]|| start arbitrary external applications for calls || ✔ || ✗ || ✗ || ✔ || ✗ || ✗
|-
| [[#App Proxy|App Proxy]]|| a caching proxy that provides app persistence || ✔ || ✔ || ✔ || ✔ || ✗ || ✗
|-
| [[#Auto update|Auto update]]|| automatically updates myApps platform services to the same version the PBX has || ✔ || ✔ || ✗ || ✔ || ✔<ref>The then-current web app is always loaded from the PBX upon startup and hence up-to-date by definition</ref> || ✔
|-
| Three party conference || initiate 3-pty-conference using Softphone-App || ✔ || ✔ || ✔ || ✔ || ✗ || ✔
|-
| Exclude VPN || disable use of VPN connections for audio and appsharing || ✔ || ✔ || ✔ || ✔ || ✗ || ✗
|-
| Screen lock || myApps screen lock against unauthorised use || ✗ || ✗ || ✗ || ✗ || ✗ || ✔
|}

<references/>

=Requirements=
* innovaphone PBX 16r1 and up

== Hardware ==
Recommended hardware requirements
* Processor: Dual-core 2Ghz or higher
* RAM: 4 Gb

== myApps for Windows ==
* Windows 11 and up
* Windows Server 2016 and later versions

=== 32 & 64 bit Windows ===
* 32 bit Windows: install the myAppsSetup32.msi from the App Store
* 64 bit Windows: install the myAppsSetup.msi from the App Store
** the 64 bit variant still installs into Program Files (x86), as the main myApps.exe is still a 32bit application
** the 64 bit variant just contains an additional 64 bit binary for the outlook search

=== Windows N editions ===

Windows N editions are missing the ''Media Feature Pack'' which is pre installed on other Windows versions.

Please install the pack from [https://www.microsoft.com/en-us/software-download/mediafeaturepack Microsoft (Windows 10 pack)] before you install myApps. The installer will check if the file <code>C:\Windows\SysWOW64\mfplat.dll</code> exist on your system.

Make sure to install the correct pack depending on your Windows version! There are different packs for Windows 10 1703, 1803, 1809 and 32bit or 64bit etc.

NB: Sometimes the myApps installation will not work even though the media pack is already installed. This is because the installer has no read access to check if the package is already installed. If the above-mentioned file exists and the installer asks to install the Windows Media Feature Pack nevertheless, you have to start the myApps install with administrative rights.

=== Terminal Server environments ===

Audio driver was removed if myApps discovers that it is running in a terminal server environment like Citrix.

The audio driver is needed for the Softphone App but the Softphone App should not use an audio driver at the server side because the audio devices are plugged locally and there would be a delay sending and receiving audio data with the server.

If a customer wants to use the Softphone App at the server side he needs to make use of the myApps Plugin for virtual desktops solution:

[[{{NAMESPACE}}:MyApps_Plugin_for_Virtual_Desktops|Reference15r1:MyApps_Plugin_for_Virtual_Desktops]]

== myApps for macOS ==
* macOS 13 or higher

== myApps for iOS ==
* iOS 16 or higher

== myApps for Android ==
* Android 13 or higher.

== myApps for IP270 ==
Exclusively used in IP270.

= Licenses =
* No license needed for myApps platform services

= Overview =
myApps platform services is a native executable that is installed using the standard mechanisms on the respective operating system. It provides various advanced services which can be used by the myApps web client code as well as the Apps running in the myApps context.

Also, on Windows, the platform services come with their own, dedicated browser to run myApps in. This browser is based on [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium]. On iOS, macOS and Android, it is based upon native embedded web view facilities (such as WKWebView) instead.
== Components ==

=== RTP service for audio and appsharing ===
The RTP service provides audio and appsharing as a video stream. VoIP RTP endpoints (e.g. for softphones). It supports STUN, TURN, ICE, SRTP, DTLS. Note however that unlike WebRTC, these endpoints do not ''require'' ICE and DTLS. In other words, they can communicate also with non-compliant (i.e. older) VoIP devices.

Note that the available capabilities when not running the myApps platform services depend on the used browser's WebRTC implementation. See your browser documentation for details.

Apps can request RTP channels using the [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol]'s ''AllocChannel'' message.

==== RTP ports ====
{|
| audio || 50000 -> 50099
|-
| video (app sharing) || 50100 -> 50199
|}

The RTP service will enumerate all local interfaces and create local HOST candidates for ICE. There is an option however to disregard VPN interfaces (more precisely such interfaces with type of ''IF_TYPE_PPP'' or ''IF_TYPE_TUNNEL''). This can eliminate quality issues when RTP data is transmitted through TCP based VPN tunnels.

SRFLX and RELAY candidates are obtained using the STUN and TURN server configuration passed by the App (e.g the ''softphone'' App) as part of the ''AllocChannel'' request.
<code>{"mt":"AllocChannel","channel":"81429cba-396d-43de-8a76-ec020ba8796e","iceServers":[{"urls":"turn:myturn.domaincom:4077?transport=udp","username":"turnuser","credential":"pwd","credentialType":"password"},{"urls":"stun:mystun.domain.com:4077"}],"dn":"Foo Bar","type":"RemoteRtp","kind":"video"}</code>

==== Codecs ====
The installed myApps launchers provide codecs that can be used by softphone apps for media streams. When running in a web browser the codecs depend on the browser version and operating system. See the documentation of your browser for details.

The following codecs are supported:
{|
!style="text-align:left;width:100px;"|Codec
!style="width:100px"|Windows-Launcher
!style="width:100px"|Android
!style="width:100px"|iOS
!style="width:100px"|macOS
!style="width:100px"|Firefox (Browser)
!style="width:100px"|Chrome (Browser)
!style="width:100px"|Edge (Browser)
!style="width:100px"|Safari (Browser)
!style="width:100px"|Opera (Browser)
!style="width:100px"|IP270
|-
|style="text-align:left; background-color:lightgray" colspan="11"|Audio
|
|-
|G711A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G711u
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G722
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|[https://caniuse.com/#search=Opus OPUS-NB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|[https://caniuse.com/#search=Opus OPUS-WB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
| colspan="11" style="text-align:left; background-color:lightgray" |Video
|
|-
|[https://caniuse.com/#search=VP8 VP8]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|-
|[https://caniuse.com/#search=VP9 VP9]
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|-
|[https://caniuse.com/#search=H264 H264]
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="11"|Application Sharing
|
|-
|Share
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|Watch
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔*
|}

''* small presentation only'' 
''** only for 1:1 calls, not for conferences

==== Video capture ====
The default resolution for video capture is 1920x1080 if available. Otherwise, 1280x720, 640x480, 352x288 or 320x240 will be used. The frame rate is 30 fps if available, otherwise 15 fps. The resulting average bandwidth could reach 1 Mbps.

==== Application sharing ====
Screen content will be transmitted as video stream by the presenter

==== Device handling ====
The RTP service enumerates microphones, loudspeaker, cameras and ringing devices and notifies apps when devices come and go. It is up to the apps using the devices to store preferences.

The RTP service also enables some extended features (such as hook switch or volume control) for supported USB headsets or Bluetooth headsets connected to myApps.
The supported headset-SDKs determine which headset vendors are recommended to be used with the myApps softphone app. 

For this to work, the following vendor specific development kits are integrated in our myApps client. Be aware that the SDK are updated within our Service release :

{| class="wikitable"
|-
! SDK Vendor !! Supported OS !! SDK Version !! innovaphone Service Release
|-
| Jabra|| MacOS || 1.16.4.0 || 14r2sr11
|-
||| Windows || 1.16.4.0 || 15r1sr3
|-
| Epos ''(formerly Sennheiser)'' || MacOS || 12.4.0.5478 || 14r1sr3
|-
||| Windows || n.a. - [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|to be installed separately]]|| 13r3sr10
|-
| Poly ''(formerly Plantronics)'' || MacOS || 3.25.53799.37131 || 13r3sr9
|-
||| Windows || 3.25.53800.37131 || 13r3sr10
|-
| Yealink || MacOS || 3.1.1.23 || 14r2sr1
|-
||| Windows || 3.1.1.23 || 14r2sr2
|}

Notes:
* It is possible to inhibit the start of the Sennheiser SDK (SenncomSDK.exe) using the <code>DISABLEHEADSETS</code> directive of the installer (see [[#MSI Parameters and install options| MSI parameters]] below).

* Starting with V13r3sr10, the Epos-SDK needs to be installed separately using the Epos Connect software to ensure full compatibility between current Epos headset models and native myApps-Windows client. For details [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|refer to this article]].


myApps-IP270 supports use of [[Reference9:Concept USB Headset|USB devices known for innovpahone desk phones]].

==== Ring tones ====
Ring tones can be played. Apps can choose the tone from a pre-defined list of ring tones.

On Windows, custom ring tones can be uploaded as .mp3 files to the <code>ringtones</code> sub-directory of myApps' roaming directory (which usually is in <code>%appdata%\innovaphone\myApps\ringtones</code>).

On Android, custom ring tones can be added to the system via Android settings.

On iOS, custom ring tones can be uploaded as .mp3 files to the <code>Ringtones</code> subdirectory of the myApps file share that is available in iTunes if the iPhone has been connected via USB.

On macOS, custom ring tones can be uploaded as .mp3 files to <code>~/Library/Containers/com.innovaphone.client-macos/Data/Documents/Ringtones</code>.

==== Debugging ====
For extended debugging, turn on the ''Audio'', ''Media'' and ''AppSharing'' traces in myApps.
=== Hot keys ===
On Windows and macOS systems, myApps platform services can listen for hot keys and invoke certain functions. Invocation is done by sending API messages to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

The hot keys can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below. Any of the function keys F1 to F11 (optionally combined with up to two modifier keys ''alt'', ''ctrl'', ''shift'' or ''win'') can be chosen for each function. If you do not want to start the call with "Hotkey+Enter" because you would have to wait for the focus, the hotkey can also be pressed twice and the number is dialled directly.

; dial selected number : Initiates a call using the currently selected text as target.

: A ''PrepareCall'' message with the ''text'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":"mt":"PrepareCall","text":"13","adjust":true}}</code>

; accept call : Accepts a currently alerting call.

: A ''ConnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"ConnectCall"}}</code>

; reject/disconnect call : Rejects a currently alerting call or disconnects an active call.

: A ''DisconnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"DisconnectCall"}}</code>

=== URL Handler ===

On Windows systems, two URI-handler are installed with the myApps platform services. Windows will call up this URI handler when a user clicks on an appropriate link, for example in a web site.

The handler will the send an API message to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

; tel URI : call a number, e.g. <code>tel:4711</code>

: A ''PrepareCall'' message with the ''num'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","num":"4711","adjust":true}}</code>
; sip URI : call a SIP name, e.g. <code>sip:zkl@innovaphone.com</code>

: A ''PrepareCall'' message with the ''sip'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","sip":"zkl@innovaphone.com","adjust":true}}</code>
; im URI : start chat with SIP name, e.g. <code>im:zkl@innovaphone.com</code>

: A ''StartChat'' message with the ''sip'' argument set to the selected text will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm ''com.innovaphone.chat'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.chat","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartChat","sip":"zkl@innovaphone.com"}}</code>

On macOS systems myApps might be made the default application to handle tel URI e.g. <code>tel:4711</code> via Apple FaceTime. Open the "FaceTime" menu "Settings..." and select myApps as "Default for phone calls".

On iOS ''tel'' URIs are always dialed via GSM. Therefore myApps iOS also reacts to URI schemes ''com.innovaphone.tel'', ''com.innovaphone.sip'' and ''com.innovaphone.im'', e.g. <code><nowiki>com.innovaphone.tel:4711</nowiki></code>, <code><nowiki>com.innovaphone.sip:zkl@innovaphone.com</nowiki></code>, <code><nowiki>com.innovaphone.im:zkl@innovaphone.com</nowiki></code>.

=== User activity ===
On Windows and macOS systems, the myApps platform services can monitor user keyboard/mouse activity and change the user's presence state after a certain amount of inactivity. The timeout can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below.

myApps will then send a [https://sdk.innovaphone.com/doc/appwebsocket/myApps.htm#SetUserActivity''SetUserActivity''] message to the PBX using the ''myApps'' protocol.

: <code>{"mt":"SetUserActivity","inactive":true}</code>

This will change the ''status'' property of the ''im:'' contact for the user's own presence and hence result in a presence update from the PBX to myApps

: <code>{"mt":"UpdateOwnPresence","presence":[{...},{"contact":"im:","activity":"","status":"closed"}]}</code>
The ''closed'' status is reflected in the grey status color when displaying a contact [[Image:myapps-inactive.png|myapps-inactive.png/|myapps-inactive.png/]].

On iOS and Android, the state is set to ''inactive'' as soon as the App is brought to background.
When myApps platform services are not available (i.e. when running the web application in a browser solely) a limited user activity monitoring is available: the state is set to active when the web page is not used for more than 5 minutes.

=== Recording ===

The new launcher offers the possibility to record the audio of incoming and outgoing calls. In order to activate that functionality the URL of the recording instance must be configured in either the PBX (PBX->myApps->Config: Recording URL) or the softphone App (Settings->Audio Recording (URL))

[[Image:PBX-Recording-Settings.png|pbx-recording-settings.png/|pbx-recording-settings.png/]] [[Image:Recording-Softphone-Settings.png|recording-softphone-settings.png/|recording-softphone-settings.png/]].

As long as that URL is configured the audio data of all calls are stored as pcap-files under that URL.
If the URL points to a CF device in the PBX, write access must be granted for that URL (PBX->Services->HTTP->Server:Public compact flash access) and if the URL points to the recording app, the files can be accessed via the recording app [[{{NAMESPACE}}:Concept_App_Service_Recordings|recording]].

Under PBX->myApps the administrator can set a certain default behaviour of the audio recording like whether or not the recording should start automatically at the beginning of the call (Recording by Default ON/OFF), only calls with external numbers should be recorded (Record external calls only) or whether or not the user should be able to start/stop the recording himself (Allow user incall recording control). Except for the last parameter these parameters can also be modified by the user in its softphone settings if the administrator doesn't set the FORCE flag.

If the user was allowed by the admin to control the recording a recording switch is active during the call when the "Media" Panel is opened. There the audio recording may be stopped and continued at will. A red recording notice is shown in the top right corner when the recording actually takes place.

[[Image:Recording-incall-switch.png|recording-incall-switch.png/|recording-incall-switch.png/]]

=== Notifications ===

The myApps platform services can use the OS specific notification mechanism (e.g. ''desktop notifications'' on Windows) to display messages (e.g. ''incoming new chat message'') to the user.

Note that the actual rendering of the notification is under control of the OS. Therefore, myApps must be allowed to show notifications and its appearance can be restricted by OS native settings.

==== Microsoft Windows Notifications ====

Microsoft Windows Server editions (2016, 2019, 2022) are just capable of showing a single ''IncomingCall'' notification at the same time (we couldn't find a workaround for this limitation). 
An ''IncomingCall'' notification is visible the whole time instead of being moved to the action center after a certain time. 
 
A notification about a missed call uses the ''IncomingCall'' type so that this notification is visible until the user returns. 
Due to the above limitation, on a new arriving call such a missed call notification is transformed to a default notification which will be moved to the action center automatically. 
 
On non server editions, you can have multiple IncomingCall notifications at the same time (so two parallel incoming calls will be indeed notified at the same time), but the missed call notification handling is the same on both platforms!

Thus there will be always just '''one''' missed call notification visible and previous missed calls can be found inside your action center!

To see myApps notifications, ensure:
* System -> Notifications
** enable notifications
** disable "Do not disturb" or allow myApps as priority application while "Do not disturb" is active
** enable notifications for myApps in the list of applications
* System -> Focus
** if a focus session is active and the "Do not disturb" is activated during a focus session, make sure that myApps is a priority application (see above)

==== macOS Notifications ====
Notifications are the same as on Windows.
The difference is, that for macOS, notifications need to be allowed in the system settings.
Go to Notifications - myApps, select Banner and enable all check marks.

=== Local phonebook access ===
'''Contact Search:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm ''com.innovaphone.search'' API]]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Search'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{"mt":"Search","type":"contact","search":"john doe"},"apiId":"com.innovaphone.search"}</code>
Search results are delivered as ''SearchInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{"mt":"SearchInfo","relevance":2000,"adjust":true,"type":"contact","contact":{"givenname":"John","sn":"Doe","company":"ACME","position":"Head of everything","telephonenumber":["11111","22222"],"homephone":["+4944444","33333"],"mobile":["+49 (123) 55555"]}},"api":"com.innovaphone.search"}</code>

'''Reverse Lookup:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.phonelookup/lib1_api_phonelookup.htm ''com.innovaphone.phonelookup'' API]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Lookup'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{ mt: "Lookup", prefixIntl: "000", prefixNtl: "00", prefixExt:"0", area: "7031", country: "49", lookup: "0004970311234567" },"apiId":"com.innovaphone.lookup"}</code>

Search results are delivered as ''LookupInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{mt: "LookupInfo", dn: "Jake Blues", contact: { telephonenumber: ["0004970311234567"], givenname: "Jake", sn: "Blues", company: "Blues Brothers" </code>

==== Windows ====
On Windows, the search and lookup are performed in all of the user's Outlook contact folders. As opposed to the search implemented in the ''Contacts'' and ''Users'' App, all items are returned which match any of the search words (i.e. searching for ''a b'' will return items matching either ''a'' or ''b'').

; searched properties : firstname, lastname
; returned properties : Following Outlook contact phone number properties are returned (if available):

:* OFFICE_TELEPHONE_NUMBER as ''telephonenumber''
:* OFFICE2_TELEPHONE_NUMBER as ''telephonenumber''
:* HOME_TELEPHONE_NUMBER as ''homephone''
:* HOME2_TELEPHONE_NUMBER as ''homephone''
:* MOBILE_TELEPHONE_NUMBER as ''mobile''
:* BUSINESS_FAX_NUMBER as ''facsimiletelephonenumber''
Note that contact information is cached in the search provider. Updated contacts may therefore become effective after a while only.
Outlook search will create its own trace file <code>myAppsOutlookSearch-</code>''date-time''<code>.txt</code> in the standard trace directory.

This search provider is always installed and can be disabled. There is no need (nor possibility) to enable it in the ''Apps'' tab of the PBX's user object. Also, no ''App'' object needs to be created for it.

==== Android/iOS ====
The search and lookup are performed in the contacts.

==== macOS ====
The search and lookup are performed in the contacts. If you wish to disable local contact lookup, go to system settings - Security & Privacy and disable the access to contacts for myapps.
=== Microsoft Office integration ===

The myApps platform services has a ''office presence provider'' that can provide the user's presence state to Office applications. See [[{{NAMESPACE}}:Concept_myApps_Office_Integration|myApps Office Integration]] for details.

This feature is installed by default. However, it can be disabled using the ''OFFICEPRESENCE'' MSI Parameter. Also, a check-mark is available in the setup dialog.

=== Call an external application for calls ===

Phone Apps (such as the phoneapp or softphone) can initiate the start of an external application when a new call appears (either incoming or outgoing). The actual spawning of the application is done by the myApps platform service. Also, the application properties (such as e.g. the executable's path) is configured in the myApps platform services (see [[#UI elements|Advanced settings]] in the ''UI elements'' section below).

A number of arguments can be passed to the application by substituting $-variables in the ''Parameter'' field:

; $n : phone number as dialed (called party number for outgoing calls) or received (calling party number for incoming calls)

; $N : called or calling party number in ''national'' format (e.g. 07031730090)

; $I : called or calling party number in ''international'' format (e.g. +497031730090)

: note that both $N and $I only work if $n includes both subscriber number and area code (e.g. 07031730090). Otherwise they are equal to $n

; $d : display name of peer (if known)

; $u : URI name of the peer (if available eg with a federation call)

; $c : conference id

: this is a globally unique ID for this call and may be used to relate the call to the ''guid'' found in the CallInfo structure in the [http://wiki.innovaphone.com/index.php?title=Reference10:SOAP_API#CallInfo SOAP-API] and [http://sdk.innovaphone.com/doc/appwebsocket/RCC.htm RCC-API ]. Also, corresponding [[Reference10:Call Detail Record CDR PBX|CDRs]] can be related using the ''event'' tag's ''conf'' attribute.
The start of an external application can be requested using the ''com.innovaphone.externalapps'' API.

Some setup examples are [[Howto:Integrate External Apps in innovaphone UC clients|shown here]].

=== Push ===

Mobile operating systems usually inhibit network operation of apps which run in the background or are closed by the user. This is done in order to reduce battery consumption. Unfortunately, this also stops such apps to maintain a registration by regularly sending ''keep alive'' messages to a server (in our case to the PBX). As a result, myApps will be disconnected from the PBX. When the PBX determines that there is an event for the application which needs a response, it needs to wake up the app using a dedicated channel provided by the operating system. This mechanism is know as ''push''. When running on iOS or Android, myApps supports ''push''.

For ''push'' to work, a [[{{NAMESPACE}}:PBX/Objects/Push|''push object'']] needs to be configured in the PBX . Also, it needs to be enabled on the mobile phone for the myApps app.
This mechanism is quite similar in v12 and v13, so you can refer to [[{{NAMESPACE}}:Concept_Push_Notifications_for_iOS_and_Android|the concept for push notifications for iOS and Android]] for more details.

Also, helpful hints can be found in [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]].

=== App Proxy ===

myApps runs further ''Apps'' (such as e.g. the ''phoneapp'') as a web page in an IFRAME of the browser myApps is running in. The App's page code is loaded either from the PBX or from an ''application platform'' (AP). This however would mean that the App's IFRAME would remain empty (a dead white screen) when the PBX or AP is not available. To make sure the App can start-up anyway, the myApps platform services feature the so-called ''App Proxy''. This is a caching proxy that caches all the App code so it is available even in case of network failure. When myApps runs in the context of the platform services, Apps are therefore not loaded from the App source directly, but from the local App proxy.

The cached files are stored in the PCs local file system in the <code>%LOCALAPPDATA%\innovaphone\myApps\appproxy</path></code>. There is no configuration required. However, if myApps seems to run with outdated or corrupt cached copies of the App, you can safely delete the entire directory.

=== Auto update ===

On Windows and on macOS, the myApps platform services can auto-update themselves to a common version. This is controlled by the [[{{NAMESPACE}}:PBX/Config/myApps#Launcher_Software_Update | ''Launcher Software Update'']] settings under ''PBX/Config/myApps'' in the PBX.

When myApps is started or the user logs in or myApps needs to re-connect to the PBX, the platform services will use the [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client API] to learn the desired version (''launcherUpdateBuild'', which is part of the API's ''model''). If this differs from the current version, the platform services will try to download the respective new version.

{
"mt": "ApiUpdate",
"apis": {
"com.innovaphone.client": {
"@client": {
"title": "innovaphone myApps",
"model": {
"launcher": true,
"launcherUpdateBuild": "134906",
"appStoreUrl": "http://store.innovaphone.com/release/download/"
}
}
}
}
}

The installation of the downloaded version is done by the ''innovaphonemyAppsUpdateService''. This service is installed and enabled during the initial installation of the myApps platform services. To disable auto-update, either leave the ''Launcher Software Update'' settings empty or set the service's start mode to ''disabled'' in the Windows ''services control panel''.

Note that on Windows the update service does not work on terminal servers. Administrators must do myApps base services updates using standard windows mechanisms.

Note that on macOS if myApps has been installed from the Apple Store it is assumed that auto update from the PBX is not desired and disabled therefore.

On Android/iOS/macOS updates can be downloaded from the respective app store.

The ''Devices'' app can not update software installed on Windows PCs directly. However, when the PBX is updated using an ''update job'' in the ''Devices'' App, the ''Launcher Software Update'' settings will be updated accordingly and hence the myApps base services will ultimately also be updated to the same version.

==== Auto update flow on Windows ====

* On start of myApps, myApps checks if an update is available and ready for installation
** if yes, the update is installed directly, without user interaction (a popup is shown during the installation)
** if not, myApps starts
* if an update is available while myApps is already running, an update notification will be shown which let's the user choose to install the update now or later (the notification will then popup again after one hour)

==UI elements ==
There are a few user interfaces provided by the platform services:
===tray-icon (Windows only) ===
::[[Image:myapps-tray.png|myapps-tray.png/|myapps-tray.png/]]
:Allows to
:* terminate myApps
:* toggle the ''autostart'' state
:* toggle the ''show in task bar'' state
:* open the trace folder
:
=== PBX connect form===
:: [[Image:myapps-connect.png|myapps-connect.png/|myapps-connect.png/]]
: Allows the user to specify the connect data for the PBX (i.e. IP address or DNS name)
:
=== Advanced settings===
::[[Image:myapps-settings0.png|myapps-settings0.png/|myapps-settings0.png/]]
::[[Image:myapps-settings.png|myapps-settings.png/|myapps-settings.png/]] [[Image:myapps-settings2.png|myapps-settings2.png/|myapps-settings2.png/]] [[Image:myapps-settings3.png|myapps-settings3.png/|myapps-settings3.png/]]

: Allows to modify various platform dependant settings (such as e.g. the hotkey selection on Windows)

== Interfaces ==
=== Provided APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm com.innovaphone.search] : access to local phone book entries by the [[#Local phonebook access|Local phonebook access]] component.
; [http://sdk.innovaphone.com/web1/com.innovaphone.launcher/com.innovaphone.launcher.htm com.innovaphone.launcher] : display of OS specific user notifications and receipt of related user actions
; com.innovaphone.notificationhandler : reports back click on a notification.
; com.innovaphone.externalapps : to start external applications, see [[#Call an external application for calls|Call an external application for calls]] above

=== Used APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm com.innovaphone.phone] : used to initiate new or manipulate existing calls by the [[#Hot keys|Hot keys]] and [[#URL handler|URL handler]] components.

; [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm com.innovaphone.chat] : used to start a new chat by the [[#URL handler|URL handler]] component.

; [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client] : the model is used to learn the update settings, see [[#Auto update|Auto update]] above

=== Protocols ===

; [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol] : used by apps to allocate RTP channels, see [[#RTP service for audio.2C video and data|RTP service for audio, video and data]] above

== Related App Services ==

none

== Known limitations ==
; Incoming call as banner on myApps for iOS : Since iOS 14 the iOS CallKit presents incoming calls as a banner leaving the original green answer button of myApps visible. Use only the blue button of the banner to accept the call or change iPhone Settings, App "Phone", "Incoming Calls" to "Full Screen" to hide the myApps user interface again during call answering.

; Call answer in speakerphone mode even with active Bluetooth headset on myApps for iOS : This causes unwanted speakerphone operation if the smartphone is used with a Bluetooth car audio system. The behaviour can be changed by selecting ''Bluetooth Headset'' in this setting:
:''iOS Settings->Accessibility->Touch->Call Audio Routing: Automatic / Bluetooth Headset / Speaker''
:''iOS Einstellungen->Bedienungshilfen->Tippen->Anrufaudioausgabe: Automatisch / Bluetooth-Headset / Lautsprecher''

; Windows Server 2016 (Windows 10 Build 1607) : windows just shows the first notification. Further notifications aren't displayed until the previous ones are removed from the notification center. Current windows builds do not show this behaviour anymore.

; Problems on Mac computers with Yealink USB headsets
: we have received reports that myApps quits unexpectedly on some Mac computers when a Yealink headset is plugged in. Unfortunately, we could not find out the cause yet. If you use Yealink USB headsets and have a similar issue, please open a support ticket and send myApps traces.

; Poly / Plantronics headset buttons only functional if myApps is started with Rosetta
: myApps macOS supports Apple M1/M2 hardware natively. However, the Poly / Plantronics headset SDK is only available for Intel platform and thus myApps needs to be started via Apple's Intel emulator Rosetta if a Poly / Plantronics headset is used. This is done with right-click on the myApps executable, ''Information'', ''Open with Rosetta''.

; Windows surface devices may not work correctly
: Chromium does not get touch keyboard events. USB Keyboards may not be recognized either.

= Installation =

== Windows ==

myApps platform services are installed on Windows using the .msi file found in the ''myApps Windows'' package from [https://store.innovaphone.com/release/download.htm store.innovaphone.com].

myApps can update itself automatically, see [[#Auto update|Auto update]] above.

=== MSI Parameters and install options ===

The MSI installer of myApps for Windows supports the following parameters and can be edited with [https://docs.microsoft.com/en-us/windows/win32/msi/orca-exe Microsoft Orca]. You can add your parameters in the table ''property''.

; SERVER (REG_SZ): the PBX's server address (without protocol like https://)
; OFFICEPRESENCE (REG_DWORD): '''false''' to disable presence integration in Microsoft Office
: this is also available as a check-mark when running the install manually

; DISABLEHEADSETS (REG_DWORD): '''true''' to disable headsets support, see [[#Device handling|Device handling]] above

; EXTERNALAPPS (REG_SZ): pre-define external applications, see [[#Call an external application for calls|Call an external application for calls]] above
: e.g. <code>"{""externalApps"":[{""id"":0,""name"":""Wireshark"",""path"":""C:\\Program Files\\Wireshark\\Wireshark.exe"",""param"":""test $I""}]}"</code>

; FORCERESTART (REG_DWORD): '''true''' (or any string ...) kills myApps during the installation and restarts it for the currently logged in user, if it was running

; DISABLELOCALHOST (REG_DWORD): '''true''' to disable use of '''localhost''' string to access the local webserver. Use '''127.0.0.1''' instead

; EXCLUDEINTERFACES (REG_SZ): some VPN interfaces are not detected by Windows as IF_TYPE_PPP or IF_TYPE_TUNNEL and therefore the '''media outside VPN''' setting is not taking effect. With this option interfaces can be pre-defined that will not be used for media. Interfaces must be comma separated
: e.g. <code>EXCLUDEINTERFACES="172,192.168,10.10"</code>

; FASTERDOWNLOADS (REG_DWORD): '''true''' to have faster downloads without artificially slowing down the download of an update (which is done to avoid audio lags if clients have slow networks).

Current settings are stored in the registry at <code>Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps</code> or at <code>Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\innovaphone\myApps</code>

Boolean values like OfficePresence are stored in registry entries with type REG_DWORD and values 1 or 0. 0 disables the setting and 1 enables it.

== iOS ==

myApps platform services are installed on iOS by loading ''innovaphone myApps'' from the ''App Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

== macOS ==

myApps platform services might be installed directly from the Apple store. An installer package <code>myapps.pkg</code> and a disk image <code>myapps.dmg</code> is also available from the innovaphone app store. Install <code>myapps.pkg</code> by double-click on the file and follow the instructions of the installer. myApps becomes available in the Applications folder and can be opened by double-click. Or download and open <code>myapps.dmg</code> and double klick myApps. If desired integrate it into the app dock by right click, ''Options, Keep in the dock''.

If installed from the innovaphone app store, myApps can update itself automatically, see [[#Auto update|Auto update]] above.

If installed from the Apple store, macOS notifies about updates on the Apple store. myApps [[#Auto update|Auto update]] is disabled then.

If a clean-install of the client is necessary, the folder "/Users/username/Library/Containers/myapps" needs to be deleted. To be on the safe side also delete it from the trash bin.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

=== Preferences ===

macOS supports preference settings that can be set via a shell command or via Mac remote management

defaults write com.innovaphone.client-ios-14r1 server "PBX-server-URL"

The following parameters and can be set through this method:

; server: the PBX's server URL

=== Setting myApps as Default App for SIP-URLs ===

{| class="wikitable"
|defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add '{
LSHandlerURLScheme = sip;
LSHandlerRoleAll = "<CFBundleIdentifier>";
}'
|}

To find the “CFBundleIdentifier”, proceed as follows:
* In the Finder under “Applications”, search for the desired myApps client that you want to set as the default app.
* Right-click on “Show package contents” -> you will find the “CFBundleIdentifier” in the Info.plist file.

A restart of the MAC is required.

=== Using Sennheiser headsets ===
If you use Sennheiser headsets, you should also install the then-current <code>DSEA_SDK_v</code>''version''<code>.pkg</code> package, after you installed the myApps client. Without that, audio will still work, but not the controls on the headset. You will need to keep that up-to-date yourself, as it is not updated by myApps's auto-update function.

== Android ==

myApps platform services are installed on Android by loading ''innovaphone myApps'' from the ''Play Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying a property "server" with string value "pbx.example.com" in the MDM.

== IP270 ==
For configuration instructions, refer to the [[Reference16r1:Concept IP270|IP270 concept article]].

= Configuration =

== Server configuration ==
When opening myApps for the first time, the user is prompted for the Server. Usually only the hostname (DNS host name or IP address) needs to be configured.

But there are more options for special PBX configurations.

; Non-standard HTTPS port
: If the PBX uses a non-standard HTTPS port, it must be appended to the host name separated by a colon (<code>:</code>).
: Example: <code>pbx.example.com:4444</code> (expands to <code>https://pbx.example.com:4444/PBX0/APPCLIENT/appclient.htm</code>)
; DynPBX module name
: If the PBX is a DynPBX, the module id must be appended to PBX0 separated - (<code>/</code>).
: Example: <code>pbx.example.com/PBX0-1</code> (expands to <code>https://pbx.example.com/PBX0-1/APPCLIENT/appclient.htm</code>)
; Softphone physical location
: If user defined physical location shall be used for softphone, you can append it using a parameter <code>#phys=</code>.
: Example: <code>pbx.example.com#phys=slave</code> (expands to <code>https://pbx.example.com/PBX0/APPCLIENT/appclient.htm#phys=slave</code>)

Example 1: PBX pbx.example.com with standard configuration
pbx.example.com

Example 2: PBX slave.example with DynPBX module ID 1, HTTPS port 4444 and physical location master
slave.example.com:4444/PBX0-1#phys=master

=== HTTP proxy support ===

myApps platform services do support operation via HTTP proxy now. If one or more proxies have been configured in the network settings of the operating system for the active network connection, HTTP CONNECT tunnels are established.

On Windows user name and password can be specified for the tunnel servers as generic credentials in the credentials manager (Anmeldeinformationsverwaltung). The name of the credentials must be the tunnel server hostname.

On Android user name and password can be specified through Android ''Settings, Accounts'' by adding a myApps ''HTTP Proxy Credentials'' account. The name of the account must be the tunnel server hostname.

== Platform specific settings ==
When myApps runs under the myApps platform services, it will show various platform specific settings as part of its ''burger menu'', so the user can set them. See ''Advanced settings'' in [[#UI elements|UI elements]] above.

Some options can also be set globally for all myApps clients in the PBX's [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps ''Client Settings'']]
{|
! style="text-align: left; font-weight: bold" | Option

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold" | Where to set

!
! style="text-align: left; font-weight: bold"| Availability
|-

| || || User menu || PBX ''Client Settings'' || Windows || iOS || Android || macOS
|IP270<ref>myApps-IP270 offers device specific settings explained in [[Reference16r1:Concept IP270|IP270 concept article]]</ref>
|-
| Autostart || Launch myApps on login || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|✗
|-

| Appear offline after || controls after which idle time a user is considered ''inactive''. See [[#User activity|User activity]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|✗
|-

| Hotkeys || Hotkeys for call dial, accept, reject. See [[#Hot keys|Hot keys]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|✗
|-

| Docking || Docking mode (left, right, none). See [[#???|??]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✗
|✗
|-

| Desktop notifications|| Turn on/off platform notifications. See [[#Notifications| Notifications]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|✗
|-

| VPN || Disable VPN address for ICE candidate selection. See [[#RTP ports| RTP ports]] above || ✔ ||✔ ||✔ || ✗ || ✔ || ✔
|✗
|-

| Show in taskbar|| Show myApps in the taskbar in addition to it's tray icon. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗
|✗
|-

| Log flags || turn on/off certain trace levels. See [[#Troubleshooting|Troubleshooting]] below. || ✔ ||✔ ||✔ || ✔ || ✔ || ✔
|✔

|-

| External applications || define the applications available for Apps to be started. See [[#Call an external application for calls|Call an external application for calls]] above. || ✔ ||✗ ||✔ || ✗ || ✗ || ✔
|✗
|-

| Ring in headset || send ring tone for incoming to headset instead of loudspeaker. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗
|✗
|}
<references/>

== Start parameters for Windows ==

On Windows, it is not possible to pass start parameters from the [https://www.chromium.org/developers Chromium documentation] to the myApps process.

== OS Settings for Windows ==
Windows settings can influence the display of ''Desktop notifications''. See [https://support.microsoft.com/en-us/help/4028678/windows-10-change-notification-settings Change notification settings in Windows 10/11] for details.

=== Windows 11 ===

* Windows 11 has a feature "do not disturb". This hides notifications if enabled.
* Windows 11 has a feature "focus". This enables "do not disturb" and thus hides notifications too.
* Windows 11 has priority settings for notifications. Ensure that VoIP notifications for calls are allowed any maybe also include myApps as an App which is allowed to show notifications.

== OS settings for Android ==
; Events : The appearance of notifications can be controlled here.

; Call accounts : For proper incoming call signaling, the call account ''myApps'' needs to be enabled. Note that on Samsung smartphones the call account switch likely toggles back and a few tries may need to be done until it persists. Please double-check the state.

; Preferred Calling Account : Choose which calling account (myApps/SIM/..) should be used for outgoing calls initiated from within the native phone app / phone book.

; Background data, unlimited data usage : Grant background data use to enable ''myApps'' to connect to the PBX immediately on an incoming call.

; Overlaying : This setting is not needed if call account ''myApps'' has been enabled. Should there be a reason for not enabling call account ''myApps'', the permission for overlaying needs to be granted on Android 10 or higher for proper call signaling.

Note: If no SIM card is installed some Android smartphones exhibit a problem dialing from the smartphone contacts. The contacts app shows a choice ''Select SIM card for this call'' but all possible dialers are greyed out. In this case make myApps the default phone app in Android settings ''Apps, Default apps, Telephony''.

== OS settings for iOS ==
; Notifications : The appearance of notifications can be controlled in iOS ''Settings, myApps''.

== OS settings for macOS ==

; Notifications : The appearance of notifications can be controlled in macOS ''Preferences, Notifications, myApps''.

=Troubleshooting=

myApps platform services can write various traces for debugging. Trace can be turned on and off selectively in the [[#Advanced settings|Advanced settings]].

The following trace flags can be set:

(''Recommended trace options are: '''App, Browser, ICE, TURN, Signaling and Audio'''. Please do not activate other flags unless innovaphone support says otherwise'')

{|
!style="text-align: left; font-weight: bold" | Abbreviation

!style="text-align: left; font-weight: bold" |code

!style="text-align: left; font-weight: bold" | description

|-
| App||0x000000001|| logs from the App Service itself
|-
| DNS||0x000000008|| logs DNS requests and results
|-
| HTTP client||0x000000080|| http client logs
|-
| TLS||0x000000400|| TLS logs
|-
| TCP||0x000000800|| TCP logs
|-
| LDS||0x000001000|| local domain sockets
|-
| WebSocket client||0x000004000|| logs outgoing websocket connections
|-
| App WebSocket||0x000008000|| logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
|-
| UDP||0x000200000|| UDP logs
|-
| DTLS||0x000400000|| logs DTLS handshake and messages
|-
| Media||0x000800000|| logs media events
|-
| Media channel||0x001000000|| logs RTP/SCTP media connections
|-
| ICE||0x002000000|| logs ICE messages between peers
|-
| TURN||0x004000000|| logs TURN messages between peers
|-
| AppSharing||0x008000000|| logs AppSharing connection
|-
| Audio||0x010000000|| logs Audio connection and headset events
|-
| Video||0x020000000|| logs video connection and webcam events
|-
| Browser||0x040000000|| logs Chromium events
|-
| AppProxy||0x080000000|| logs requests which are proxied between the local webserver and the remote server
|-
| Webserver ||0x200000000|| enables webserver specific logs
|-
| Browser Console ||0x400000000|| logs browser console events
|-
| Signaling||0x800000000|| enables logs in the signaling module for debugging calls
|}
''code'' can be or'ed and used as value for the ''Log flags'' field in [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps/Client Settings]].

; Windows :On Windows, traces are written to the <code>%LOCALAPPDATA%\innovaphone\myApps</code> directory. If you start myApps with --log-size as parameter, you can define the maximum size of a log file (e.g. --log-size=100000000 would be 100MB for each file)

:* myApps-''date-time''.txt : main log file for the platform services

:* myAppsOutlookSearch-''date-time''.txt : log file for the Outlook phone book access

:* myAppsHookController-''date-time''.txt : log file for the hot-key interceptor (see [[#Hot keys|Hot keys]])

; :myApps update installation traces are written to the <code>%windir%\temp\</code> directory.
:* myAppsInstall.txt: MSI installation file

; :myApps update service traces are written to the <code>%ProgramData%\innovaphone\myAppsUpdateService</code> directory.
:* myAppsUpdateService-''date-time''.txt: myApps update service traces

;Android : traces can be sent by e-mail.
: also, an Android device might also be connected to a PC via an USB cable to get the traces. The files can be found in <code>Android/data/com.innovaphone.clientandroid/files</code>

; iOS : traces can be sent by e-mail.

; macOS : traces can be sent by e-mail.
: also, the files can be found in <code>~/Library/Containers/com.innovaphone.client-ios/Data/Documents/</code>. Press ''Alt+N'' followed by space to get tilde ''~''.

; IP270 : Refer to the [[Reference16r1:Concept IP270#Troubleshooting|IP270 concept article section troubleshooting]].

= Known Problems =
[[:Category:Problem myApps platform services|Known Problems]]

= Related Articles =
* [[{{NAMESPACE}}:Concept_myApps]]
* [[{{NAMESPACE}}:Concept_myApps_Redundancy|Concept myApps Redundancy]]
* [[{{NAMESPACE}}:Concept_myApps_Office_Integration|Concept myApps Office Integration]]
* [[{{NAMESPACE}}:Concept_myAPPs_Search_in_local-Outlook_Contacts|Concept myAPPs Search in local Outlook Contacts]]
* [[{{NAMESPACE}}:Call_Detail_Record_CDR_PBX|Call Detail Records]]
* [[{{NAMESPACE}}:Concept Push Notifications for myPBX iOS and Android|Concept Push Notifications for myPBX iOS and Android]]
* [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reference16r1:PBX/Config/myApps]]
* [[{{NAMESPACE}}:Concept_IP270|IP270 concept article]]
[[Category:Concept myApps platform services]]

Reference15r1:Concept myApps platform services

2026-04-21T09:11:24Z

Tfu: /* Device handling */

[[Category:Concept|myApps]]

myApps platform services provide various operating system specific services which can be used by other ''Apps'' running in the [[{{NAMESPACE}}:Concept myApps|myApps client]]. Those services typically are not available in the browser's JavaScript environment and hence must be implemented in native platform code. Therefore, the platform services are installed as native executable on the respective platform.

When myApps is started in a web browser (and hence has no access to the platform services), some Apps will use [https://en.wikipedia.org/wiki/WebRTC WebRTC] services implemented by the browser instead. For ease of reference, features available in this scenario are also described here.

On windows, the platform services also come with their own web browser in which the myApps web App will be started then. This browser is based on google's [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium] open source software.
= Applies To =

* [[{{NAMESPACE}}:Concept myApps|myApps]]
* myApps for Windows
* myApps for macOS
* myApps for iOS
* myApps for Android

* myApps Web App (WebRTC)
version 14r2

=Features=
Not all features are available or required on all platforms.
{|
! style="text-align: left; font-weight: bold" | Feature

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold"| Availability
|-

| || || Windows || iOS || Android || macOS || Browser<ref>This refers to the myApps web application running in a browser with no platform services available</ref>

|-
| audio || manage local audio devices to record and playback audio conversations || ✔ || ✔ || ✔ || ✔ || ✔ (audio available but devices managed by web browser)
|-

| video || manage local displays and cameras to capture and render video live stream || ✔ || ✔ || ✔ || ✔ || ✔ (video available but devices managed by web browser)

|-

| ringer || manage local ringing device || ✔ || ✔ || ✔ || ✔ || ✔
|-

| application sharing

|-

|   presenter || share an application || ✔ || ✗ || ✔ || ✔ || ✔
|-

|   consumer || view an application shared by the peer || ✔ || ✔ || ✔ || ✔ || ✔

|-

| hot keys || capture key presses for quick invocation of phone apps (e.g. dial selected number) || ✔ || ✗ || ✗ || ✔ || ✗
|-
| tel: and sip: URI handler || intercept clicks on tel: and sip: links in web sites to invoke phone apps || ✔ || ✔ || ✔ || ✔ || ✗

|-
| user activity || set presence state according to user activity || ✔ || ✗ || ✗ || ✔ || ✔<ref>limited, see [[#User activity|User activity]] below</ref>

|-

| docking || myApps can be docked persistently to the right or left edge of your screens || ✔ || ✗ || ✗ || ✗ || ✗

|-

| multi-windowing|| Apps can be launched in separate windows|| ✔ || ✗ || ✗ || ✔ || ✗

|-

| recording|| Calls can be recorded to recording app|| ✔ || ✔ || ✔ || ✔ || ✗

|-
| notifications || ||
|-
|   display notifications || display notifications with OS standard mechanism || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   push notifications || receive push notifications while myApps is not running || ✗ || ✔ || ✔ || ✔ || ✔<ref>The browser needs to be running in order to receive push notifications.</ref>
|-
|   chat and apps || display notifications for chat and other apps || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   calls || display notifications for incoming calls || ✔ || ✔ || ✔ || ✔ || ✗<ref>Call notifications are only displayed locally while the phone or softphone app is started.</ref>
|-

| phone book access || access local phone book || ✔ || ✔ || ✔ || ✔ || ✗
|-
| office presence provider || maps PBX presence state to Microsoft office presence state || ✔ || ✗ || ✗ || ✗ || ✗
|-

| external application start || start arbitrary external applications for calls || ✔ || ✗ || ✗ || ✔ || ✗

|-

| app proxy|| a caching proxy that provides app persistence || ✔ || ✔ || ✔ || ✔ || ✗

|-

| auto update || automatically updates myApps platform services to the same version the PBX has || ✔ || ✔ || ✗ || ✔ || ✔<ref>The then-current web app is always loaded from the PBX upon startup and hence up-to-date by definition</ref>
|-

| three party conference || initiate 3-pty-conference using Softphone-App || ✔ || ✔ || ✔ || ✔ || ✗

|-
| exclude VPN || disable use of VPN connections for audio and appsharing || ✔ || ✔ || ✔ || ✔ || ✗

|}

<references/>

=Requirements=
* innovaphone PBX 14r2 and up

== Hardware ==
Recommended hardware requirements
* Processor: Dual-core 2Ghz or higher
* RAM: 4 Gb

== myApps for Windows ==
* Windows 10 and up
* Windows Server 2016 and later versions

=== 32 & 64 bit Windows ===
* 32 bit Windows: install the myAppsSetup32.msi from the App Store
* 64 bit Windows: install the myAppsSetup.msi from the App Store
** the 64 bit variant still installs into Program Files (x86), as the main myApps.exe is still a 32bit application
** the 64 bit variant just contains an additional 64 bit binary for the outlook search

=== Windows N editions ===

Windows N editions are missing the ''Media Feature Pack'' which is pre installed on other Windows versions.

Please install the pack from [https://www.microsoft.com/en-us/software-download/mediafeaturepack Microsoft (Windows 10 pack)] before you install myApps. The installer will check if the file <code>C:\Windows\SysWOW64\mfplat.dll</code> exist on your system.

Make sure to install the correct pack depending on your Windows version! There are different packs for Windows 10 1703, 1803, 1809 and 32bit or 64bit etc.

NB: Sometimes the myApps installation will not work even though the media pack is already installed. This is because the installer has no read access to check if the package is already installed. If the above-mentioned file exists and the installer asks to install the Windows Media Feature Pack nevertheless, you have to start the myApps install with administrative rights.

=== Terminal Server environments ===

Audio driver was removed if myApps discovers that it is running in a terminal server environment like Citrix.

The audio driver is needed for the Softphone App but the Softphone App should not use an audio driver at the server side because the audio devices are plugged locally and there would be a delay sending and receiving audio data with the server.

If a customer wants to use the Softphone App at the server side he needs to make use of the myApps Plugin for virtual desktops solution:

[[{{NAMESPACE}}:MyApps_Plugin_for_Virtual_Desktops|Reference15r1:MyApps_Plugin_for_Virtual_Desktops]]

== myApps for macOS ==
* macOS 10.13 or higher

== myApps for iOS ==
* iOS 13 or higher

== myApps for Android ==
* Android 6.0 or higher. Android 6.x may need an update of the Chrome browser.

= Licenses =
* No license needed for myApps platform services

= Overview =
myApps platform services is a native executable that is installed using the standard mechanisms on the respective operating system. It provides various advanced services which can be used by the myApps web client code as well as the Apps running in the myApps context.

Also, on Windows, the platform services come with their own, dedicated browser to run myApps in. This browser is based on [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium]. On iOS, macOS and Android, it is based upon native embedded web view facilities (such as WKWebView) instead.
== Components ==

=== RTP service for audio and appsharing ===
The RTP service provides audio and appsharing as a video stream. VoIP RTP endpoints (e.g. for softphones). It supports STUN, TURN, ICE, SRTP, DTLS. Note however that unlike WebRTC, these endpoints do not ''require'' ICE and DTLS. In other words, they can communicate also with non-compliant (i.e. older) VoIP devices.

Note that the available capabilities when not running the myApps platform services depend on the used browser's WebRTC implementation. See your browser documentation for details.

Apps can request RTP channels using the [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol]'s ''AllocChannel'' message.

===== RTP ports=====

{|

| audio || 50000 -> 50099

|-

| video (app sharing) || 50100 -> 50199

|}

The RTP service will enumerate all local interfaces and create local HOST candidates for ICE. There is an option however to disregard VPN interfaces (more precisely such interfaces with type of ''IF_TYPE_PPP'' or ''IF_TYPE_TUNNEL''). This can eliminate quality issues when RTP data is transmitted through TCP based VPN tunnels.

SRFLX and RELAY candidates are obtained using the STUN and TURN server configuration passed by the App (e.g the ''softphone'' App) as part of the ''AllocChannel'' request.
<code>{"mt":"AllocChannel","channel":"81429cba-396d-43de-8a76-ec020ba8796e","iceServers":[{"urls":"turn:myturn.domaincom:4077?transport=udp","username":"turnuser","credential":"pwd","credentialType":"password"},{"urls":"stun:mystun.domain.com:4077"}],"dn":"Foo Bar","type":"RemoteRtp","kind":"video"}</code>

===== Codecs =====

The installed myApps launchers provide codecs that can be used by softphone apps for media streams. When running in a web browser the codecs depend on the browser version and operating system. See the documentation of your browser for details.

The following codecs are supported:

{|
!style="text-align:left;width:100px;"|Codec
!style="width:100px"|Windows-Launcher
!style="width:100px"|Android
!style="width:100px"|iOS
!style="width:100px"|macOS
!style="width:100px"|Firefox (Browser)
!style="width:100px"|Chrome (Browser)
!style="width:100px"|Edge (Browser)
!style="width:100px"|Safari (Browser)
!style="width:100px"|Opera (Browser)
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Audio
|-
|G711A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G711u
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G722
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G729
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729B
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729AB
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|[https://caniuse.com/#search=Opus OPUS-NB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|[https://caniuse.com/#search=Opus OPUS-WB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Video
|-
|[https://caniuse.com/#search=VP8 VP8]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|-
|[https://caniuse.com/#search=VP9 VP9]
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|-
|[https://caniuse.com/#search=H264 H264]
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Application Sharing
|-
|Share
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|Watch
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|}

''* small presentation only'' 
''** only for 1:1 calls, not for conferences

===== Video capture =====

The default resolution for video capture is 1920x1080 if available. Otherwise, 1280x720, 640x480, 352x288 or 320x240 will be used. The frame rate is 30 fps if available, otherwise 15 fps. The resulting average bandwidth could reach 1 Mbps.

===== Application sharing =====

Screen content will be transmitted as video stream by the presenter

===== Device handling =====

The RTP service enumerates microphones, loudspeaker, cameras and ringing devices and notifies apps when devices come and go. It is up to the apps using the devices to store preferences.

The RTP service also enables some extended features (such as hook switch or volume control) for supported USB headsets or Bluetooth headsets connected to myApps.
The supported headset-SDKs determine which headset vendors are recommended to be used with the myApps softphone app. 

For this to work, the following vendor specific development kits are integrated in our myApps client. Be aware that the SDK are updated within our Service release :

{| class="wikitable"
|-
! SDK Vendor !! Supported OS !! SDK Version !! innovaphone Service Release
|-
| Jabra|| MacOS || 1.16.4.0 || 14r2sr11
|-
||| Windows || 1.16.4.0 || 15r1sr3
|-
| Epos ''(formerly Sennheiser)'' || MacOS || 12.4.0.5478 || 14r1sr3
|-
||| Windows || n.a. - [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|to be installed separately]]|| 13r3sr10
|-
| Poly ''(formerly Plantronics)'' || MacOS || 3.25.53799.37131 || 13r3sr9
|-
||| Windows || 3.25.53800.37131 || 13r3sr10
|-
| Yealink || MacOS || 3.1.1.23 || 14r2sr1
|-
||| Windows || 3.1.1.23 || 14r2sr2
|}

Notes:
* It is possible to inhibit the start of the Sennheiser SDK (SenncomSDK.exe) using the <code>DISABLEHEADSETS</code> directive of the installer (see [[#MSI Parameters and install options| MSI parameters]] below).

* Starting with V13r3sr10, the Epos-SDK needs to be installed separately using the Epos Connect software to ensure full compatibility between current Epos headset models and native myApps-Windows client. For details [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|refer to this article]].


===== Ring tones =====

Ring tones can be played. Apps can choose the tone from a pre-defined list of ring tones.

On Windows, custom ring tones can be uploaded as .mp3 files to the <code>ringtones</code> sub-directory of myApps' roaming directory (which usually is in <code>%appdata%\innovaphone\myApps\ringtones</code>).

On Android, custom ring tones can be added to the system via Android settings.

On iOS, custom ring tones can be uploaded as .mp3 files to the <code>Ringtones</code> subdirectory of the myApps file share that is available in iTunes if the iPhone has been connected via USB.

On macOS, custom ring tones can be uploaded as .mp3 files to <code>~/Library/Containers/com.innovaphone.client-macos/Data/Documents/Ringtones</code>.

===== Debugging =====
For extended debugging, turn on the ''Audio'', ''Media'' and ''AppSharing'' traces in myApps.

=== Hot keys ===
On Windows and macOS systems, myApps platform services can listen for hot keys and invoke certain functions. Invocation is done by sending API messages to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

The hot keys can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below. Any of the function keys F1 to F11 (optionally combined with up to two modifier keys ''alt'', ''ctrl'', ''shift'' or ''win'') can be chosen for each function. If you do not want to start the call with "Hotkey+Enter" because you would have to wait for the focus, the hotkey can also be pressed twice and the number is dialled directly.

; dial selected number : Initiates a call using the currently selected text as target.

: A ''PrepareCall'' message with the ''text'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":"mt":"PrepareCall","text":"13","adjust":true}}</code>

; accept call : Accepts a currently alerting call.

: A ''ConnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"ConnectCall"}}</code>

; reject/disconnect call : Rejects a currently alerting call or disconnects an active call.

: A ''DisconnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"DisconnectCall"}}</code>

=== URL Handler ===

On Windows systems, two URI-handler are installed with the myApps platform services. Windows will call up this URI handler when a user clicks on an appropriate link, for example in a web site.

The handler will the send an API message to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

; tel URI : call a number, e.g. <code>tel:4711</code>

: A ''PrepareCall'' message with the ''num'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","num":"4711","adjust":true}}</code>
; sip URI : call a SIP name, e.g. <code>sip:zkl@innovaphone.com</code>

: A ''PrepareCall'' message with the ''sip'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","sip":"zkl@innovaphone.com","adjust":true}}</code>
; im URI : start chat with SIP name, e.g. <code>im:zkl@innovaphone.com</code>

: A ''StartChat'' message with the ''sip'' argument set to the selected text will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm ''com.innovaphone.chat'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.chat","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartChat","sip":"zkl@innovaphone.com"}}</code>

On macOS systems myApps might be made the default application to handle tel URI e.g. <code>tel:4711</code> via Apple FaceTime. Open the "FaceTime" menu "Settings..." and select myApps as "Default for phone calls".

On iOS ''tel'' URIs are always dialed via GSM. Therefore myApps iOS also reacts to URI schemes ''com.innovaphone.tel'', ''com.innovaphone.sip'' and ''com.innovaphone.im'', e.g. <code><nowiki>com.innovaphone.tel:4711</nowiki></code>, <code><nowiki>com.innovaphone.sip:zkl@innovaphone.com</nowiki></code>, <code><nowiki>com.innovaphone.im:zkl@innovaphone.com</nowiki></code>.

=== User activity ===
On Windows and macOS systems, the myApps platform services can monitor user keyboard/mouse activity and change the user's presence state after a certain amount of inactivity. The timeout can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below.

myApps will then send a [https://sdk.innovaphone.com/doc/appwebsocket/myApps.htm#SetUserActivity''SetUserActivity''] message to the PBX using the ''myApps'' protocol.

: <code>{"mt":"SetUserActivity","inactive":true}</code>

This will change the ''status'' property of the ''im:'' contact for the user's own presence and hence result in a presence update from the PBX to myApps

: <code>{"mt":"UpdateOwnPresence","presence":[{...},{"contact":"im:","activity":"","status":"closed"}]}</code>
The ''closed'' status is reflected in the grey status color when displaying a contact [[Image:myapps-inactive.png|myapps-inactive.png/|myapps-inactive.png/]].

On iOS and Android, the state is set to ''inactive'' as soon as the App is brought to background.
When myApps platform services are not available (i.e. when running the web application in a browser solely) a limited user activity monitoring is available: the state is set to active when the web page is not used for more than 5 minutes.

=== Recording ===

The new launcher offers the possibility to record the audio of incoming and outgoing calls. In order to activate that functionality the URL of the recording instance must be configured in either the PBX (PBX->myApps->Config: Recording URL) or the softphone App (Settings->Audio Recording (URL))

[[Image:PBX-Recording-Settings.png|pbx-recording-settings.png/|pbx-recording-settings.png/]] [[Image:Recording-Softphone-Settings.png|recording-softphone-settings.png/|recording-softphone-settings.png/]].

As long as that URL is configured the audio data of all calls are stored as pcap-files under that URL.
If the URL points to a CF device in the PBX, write access must be granted for that URL (PBX->Services->HTTP->Server:Public compact flash access) and if the URL points to the recording app, the files can be accessed via the recording app [[{{NAMESPACE}}:Concept_App_Service_Recordings|recording]].

Under PBX->myApps the administrator can set a certain default behaviour of the audio recording like whether or not the recording should start automatically at the beginning of the call (Recording by Default ON/OFF), only calls with external numbers should be recorded (Record external calls only) or whether or not the user should be able to start/stop the recording himself (Allow user incall recording control). Except for the last parameter these parameters can also be modified by the user in its softphone settings if the administrator doesn't set the FORCE flag.

If the user was allowed by the admin to control the recording a recording switch is active during the call when the "Media" Panel is opened. There the audio recording may be stopped and continued at will. A red recording notice is shown in the top right corner when the recording actually takes place.

[[Image:Recording-incall-switch.png|recording-incall-switch.png/|recording-incall-switch.png/]]

=== Notifications ===

The myApps platform services can use the OS specific notification mechanism (e.g. ''desktop notifications'' on Windows) to display messages (e.g. ''incoming new chat message'') to the user.

Note that the actual rendering of the notification is under control of the OS. Therefore, myApps must be allowed to show notifications and its appearance can be restricted by OS native settings.

==== Microsoft Windows Notifications ====

Microsoft Windows Server editions (2016, 2019, 2022) are just capable of showing a single ''IncomingCall'' notification at the same time (we couldn't find a workaround for this limitation). 
An ''IncomingCall'' notification is visible the whole time instead of being moved to the action center after a certain time. 
 
A notification about a missed call uses the ''IncomingCall'' type so that this notification is visible until the user returns. 
Due to the above limitation, on a new arriving call such a missed call notification is transformed to a default notification which will be moved to the action center automatically. 
 
On non server editions, you can have multiple IncomingCall notifications at the same time (so two parallel incoming calls will be indeed notified at the same time), but the missed call notification handling is the same on both platforms!

Thus there will be always just '''one''' missed call notification visible and previous missed calls can be found inside your action center!

To see myApps notifications, ensure:
* System -> Notifications
** enable notifications
** disable "Do not disturb" or allow myApps as priority application while "Do not disturb" is active
** enable notifications for myApps in the list of applications
* System -> Focus
** if a focus session is active and the "Do not disturb" is activated during a focus session, make sure that myApps is a priority application (see above)

==== macOS Notifications ====
Notifications are the same as on Windows.
The difference is, that for macOS, notifications need to be allowed in the system settings.
Go to Notifications - myApps, select Banner and enable all check marks.

=== Local phonebook access ===
'''Contact Search:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm ''com.innovaphone.search'' API]]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Search'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{"mt":"Search","type":"contact","search":"john doe"},"apiId":"com.innovaphone.search"}</code>
Search results are delivered as ''SearchInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{"mt":"SearchInfo","relevance":2000,"adjust":true,"type":"contact","contact":{"givenname":"John","sn":"Doe","company":"ACME","position":"Head of everything","telephonenumber":["11111","22222"],"homephone":["+4944444","33333"],"mobile":["+49 (123) 55555"]}},"api":"com.innovaphone.search"}</code>

'''Reverse Lookup:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.phonelookup/lib1_api_phonelookup.htm ''com.innovaphone.phonelookup'' API]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Lookup'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{ mt: "Lookup", prefixIntl: "000", prefixNtl: "00", prefixExt:"0", area: "7031", country: "49", lookup: "0004970311234567" },"apiId":"com.innovaphone.lookup"}</code>

Search results are delivered as ''LookupInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{mt: "LookupInfo", dn: "Jake Blues", contact: { telephonenumber: ["0004970311234567"], givenname: "Jake", sn: "Blues", company: "Blues Brothers" </code>

==== Windows ====
On Windows, the search and lookup are performed in all of the user's Outlook contact folders. As opposed to the search implemented in the ''Contacts'' and ''Users'' App, all items are returned which match any of the search words (i.e. searching for ''a b'' will return items matching either ''a'' or ''b'').

; searched properties : firstname, lastname
; returned properties : Following Outlook contact phone number properties are returned (if available):

:* OFFICE_TELEPHONE_NUMBER as ''telephonenumber''
:* OFFICE2_TELEPHONE_NUMBER as ''telephonenumber''
:* HOME_TELEPHONE_NUMBER as ''homephone''
:* HOME2_TELEPHONE_NUMBER as ''homephone''
:* MOBILE_TELEPHONE_NUMBER as ''mobile''
:* BUSINESS_FAX_NUMBER as ''facsimiletelephonenumber''
Note that contact information is cached in the search provider. Updated contacts may therefore become effective after a while only.
Outlook search will create its own trace file <code>myAppsOutlookSearch-</code>''date-time''<code>.txt</code> in the standard trace directory.

This search provider is always installed and can be disabled. There is no need (nor possibility) to enable it in the ''Apps'' tab of the PBX's user object. Also, no ''App'' object needs to be created for it.

==== Android/iOS ====
The search and lookup are performed in the contacts.

==== macOS ====
The search and lookup are performed in the contacts. If you wish to disable local contact lookup, go to system settings - Security & Privacy and disable the access to contacts for myapps.

=== Microsoft Office integration ===

The myApps platform services has a ''office presence provider'' that can provide the user's presence state to Office applications. See [[{{NAMESPACE}}:Concept_myApps_Office_Integration|myApps Office Integration]] for details.

This feature is installed by default. However, it can be disabled using the ''OFFICEPRESENCE'' MSI Parameter. Also, a check-mark is available in the setup dialog.

=== Call an external application for calls ===

Phone Apps (such as the phoneapp or softphone) can initiate the start of an external application when a new call appears (either incoming or outgoing). The actual spawning of the application is done by the myApps platform service. Also, the application properties (such as e.g. the executable's path) is configured in the myApps platform services (see [[#UI elements|Advanced settings]] in the ''UI elements'' section below).

A number of arguments can be passed to the application by substituting $-variables in the ''Parameter'' field:

; $n : phone number as dialed (called party number for outgoing calls) or received (calling party number for incoming calls)

; $N : called or calling party number in ''national'' format (e.g. 07031730090)

; $I : called or calling party number in ''international'' format (e.g. +497031730090)

: note that both $N and $I only work if $n includes both subscriber number and area code (e.g. 07031730090). Otherwise they are equal to $n

; $d : display name of peer (if known)

; $u : URI name of the peer (if available eg with a federation call)

; $c : conference id

: this is a globally unique ID for this call and may be used to relate the call to the ''guid'' found in the CallInfo structure in the [http://wiki.innovaphone.com/index.php?title=Reference10:SOAP_API#CallInfo SOAP-API] and [http://sdk.innovaphone.com/doc/appwebsocket/RCC.htm RCC-API ]. Also, corresponding [[Reference10:Call Detail Record CDR PBX|CDRs]] can be related using the ''event'' tag's ''conf'' attribute.
The start of an external application can be requested using the ''com.innovaphone.externalapps'' API.

Some setup examples are [[Howto:Integrate External Apps in innovaphone UC clients|shown here]].

=== Push ===

Mobile operating systems usually inhibit network operation of apps which run in the background or are closed by the user. This is done in order to reduce battery consumption. Unfortunately, this also stops such apps to maintain a registration by regularly sending ''keep alive'' messages to a server (in our case to the PBX). As a result, myApps will be disconnected from the PBX. When the PBX determines that there is an event for the application which needs a response, it needs to wake up the app using a dedicated channel provided by the operating system. This mechanism is know as ''push''. When running on iOS or Android, myApps supports ''push''.

For ''push'' to work, a [[{{NAMESPACE}}:PBX/Objects/Push|''push object'']] needs to be configured in the PBX . Also, it needs to be enabled on the mobile phone for the myApps app.
This mechanism is quite similar in v12 and v13, so you can refer to [[{{NAMESPACE}}:Concept_Push_Notifications_for_iOS_and_Android|Reference14r2:Concept_Push_Notifications_for_iOS_and_Android]] for more details.

Also, helpful hints can be found in [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]].

=== App Proxy ===

myApps runs further ''Apps'' (such as e.g. the ''phoneapp'') as a web page in an IFRAME of the browser myApps is running in. The App's page code is loaded either from the PBX or from an ''application platform'' (AP). This however would mean that the App's IFRAME would remain empty (a dead white screen) when the PBX or AP is not available. To make sure the App can start-up anyway, the myApps platform services feature the so-called ''App Proxy''. This is a caching proxy that caches all the App code so it is available even in case of network failure. When myApps runs in the context of the platform services, Apps are therefore not loaded from the App source directly, but from the local App proxy.

The cached files are stored in the PCs local file system in the <code>%LOCALAPPDATA%\innovaphone\myApps\appproxy</path></code>. There is no configuration required. However, if myApps seems to run with outdated or corrupt cached copies of the App, you can safely delete the entire directory.

=== Auto update ===

On Windows and on macOS, the myApps platform services can auto-update themselves to a common version. This is controlled by the [[{{NAMESPACE}}:PBX/Config/myApps#Launcher_Software_Update | ''Launcher Software Update'']] settings under ''PBX/Config/myApps'' in the PBX.

When myApps is started or the user logs in or myApps needs to re-connect to the PBX, the platform services will use the [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client API] to learn the desired version (''launcherUpdateBuild'', which is part of the API's ''model''). If this differs from the current version, the platform services will try to download the respective new version.

{
"mt": "ApiUpdate",
"apis": {
"com.innovaphone.client": {
"@client": {
"title": "innovaphone myApps",
"model": {
"launcher": true,
"launcherUpdateBuild": "134906",
"appStoreUrl": "http://store.innovaphone.com/release/download/"
}
}
}
}
}

The installation of the downloaded version is done by the ''innovaphonemyAppsUpdateService''. This service is installed and enabled during the initial installation of the myApps platform services. To disable auto-update, either leave the ''Launcher Software Update'' settings empty or set the service's start mode to ''disabled'' in the Windows ''services control panel''.

Note that on Windows the update service does not work on terminal servers. Administrators must do myApps base services updates using standard windows mechanisms.

Note that on macOS if myApps has been installed from the Apple Store it is assumed that auto update from the PBX is not desired and disabled therefore.

On Android/iOS/macOS updates can be downloaded from the respective app store.

The ''Devices'' app can not update software installed on Windows PCs directly. However, when the PBX is updated using an ''update job'' in the ''Devices'' App, the ''Launcher Software Update'' settings will be updated accordingly and hence the myApps base services will ultimately also be updated to the same version.

==== Auto update flow on Windows ====

* On start of myApps, myApps checks if an update is available and ready for installation
** if yes, the update is installed directly, without user interaction (a popup is shown during the installation)
** if not, myApps starts
* if an update is available while myApps is already running, an update notification will be shown which let's the user choose to install the update now or later (the notification will then popup again after one hour)

==UI elements ==
There are a few user interfaces provided by the platform services:
===tray-icon (Windows only) ===
::[[Image:myapps-tray.png|myapps-tray.png/|myapps-tray.png/]]
:Allows to
:* terminate myApps
:* toggle the ''autostart'' state
:* toggle the ''show in task bar'' state
:* open the trace folder
:
=== PBX connect form===
:: [[Image:myapps-connect.png|myapps-connect.png/|myapps-connect.png/]]
: Allows the user to specify the connect data for the PBX (i.e. IP address or DNS name)
:
=== Advanced settings===
::[[Image:myapps-settings0.png|myapps-settings0.png/|myapps-settings0.png/]]
::[[Image:myapps-settings.png|myapps-settings.png/|myapps-settings.png/]] [[Image:myapps-settings2.png|myapps-settings2.png/|myapps-settings2.png/]] [[Image:myapps-settings3.png|myapps-settings3.png/|myapps-settings3.png/]]

: Allows to modify various platform dependant settings (such as e.g. the hotkey selection on Windows)

== Interfaces ==
=== Provided APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm com.innovaphone.search] : access to local phone book entries by the [[#Local phonebook access|Local phonebook access]] component.
; [http://sdk.innovaphone.com/web1/com.innovaphone.launcher/com.innovaphone.launcher.htm com.innovaphone.launcher] : display of OS specific user notifications and receipt of related user actions
; com.innovaphone.notificationhandler : reports back click on a notification.
; com.innovaphone.externalapps : to start external applications, see [[#Call an external application for calls|Call an external application for calls]] above

=== Used APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm com.innovaphone.phone] : used to initiate new or manipulate existing calls by the [[#Hot keys|Hot keys]] and [[#URL handler|URL handler]] components.

; [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm com.innovaphone.chat] : used to start a new chat by the [[#URL handler|URL handler]] component.

; [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client] : the model is used to learn the update settings, see [[#Auto update|Auto update]] above

=== Protocols ===

; [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol] : used by apps to allocate RTP channels, see [[#RTP service for audio.2C video and data|RTP service for audio, video and data]] above

== Related App Services ==

none

== Known limitations ==
; Incoming call as banner on myApps for iOS : Since iOS 14 the iOS CallKit presents incoming calls as a banner leaving the original green answer button of myApps visible. Use only the blue button of the banner to accept the call or change iPhone Settings, App "Phone", "Incoming Calls" to "Full Screen" to hide the myApps user interface again during call answering.

; Call answer in speakerphone mode even with active Bluetooth headset on myApps for iOS : This causes unwanted speakerphone operation if the smartphone is used with a Bluetooth car audio system. The behaviour can be changed by selecting ''Bluetooth Headset'' in this setting:
:''iOS Settings->Accessibility->Touch->Call Audio Routing: Automatic / Bluetooth Headset / Speaker''
:''iOS Einstellungen->Bedienungshilfen->Tippen->Anrufaudioausgabe: Automatisch / Bluetooth-Headset / Lautsprecher''

; Windows Server 2016 (Windows 10 Build 1607) : windows just shows the first notification. Further notifications aren't displayed until the previous ones are removed from the notification center. Current windows builds do not show this behaviour anymore.

; Problems on Mac computers with Yealink USB headsets
: we have received reports that myApps quits unexpectedly on some Mac computers when a Yealink headset is plugged in. Unfortunately, we could not find out the cause yet. If you use Yealink USB headsets and have a similar issue, please open a support ticket and send myApps traces.

; Poly / Plantronics headset buttons only functional if myApps is started with Rosetta
: myApps macOS supports Apple M1/M2 hardware natively. However, the Poly / Plantronics headset SDK is only available for Intel platform and thus myApps needs to be started via Apple's Intel emulator Rosetta if a Poly / Plantronics headset is used. This is done with right-click on the myApps executable, ''Information'', ''Open with Rosetta''.

; Windows surface devices may not work correctly
: Chromium does not get touch keyboard events. USB Keyboards may not be recognized either.

= Installation =

== Windows ==

myApps platform services are installed on Windows using the .msi file found in the ''myApps Windows'' package from [https://store.innovaphone.com/release/download.htm store.innovaphone.com].

myApps can update itself automatically, see [[#Auto update|Auto update]] above.

=== MSI Parameters and install options ===

The MSI installer of myApps for Windows supports the following parameters and can be edited with [https://docs.microsoft.com/en-us/windows/win32/msi/orca-exe Microsoft Orca]. You can add your parameters in the table ''property''.

; SERVER (REG_SZ): the PBX's server address (without protocol like https://)
; OFFICEPRESENCE (REG_DWORD): '''false''' to disable presence integration in Microsoft Office
: this is also available as a check-mark when running the install manually

; DISABLEHEADSETS (REG_DWORD): '''true''' to disable headsets support, see [[#Device handling|Device handling]] above

; EXTERNALAPPS (REG_SZ): pre-define external applications, see [[#Call an external application for calls|Call an external application for calls]] above
: e.g. <code>"{""externalApps"":[{""id"":0,""name"":""Wireshark"",""path"":""C:\\Program Files\\Wireshark\\Wireshark.exe"",""param"":""test $I""}]}"</code>

; FORCERESTART (REG_DWORD): '''true''' (or any string ...) kills myApps during the installation and restarts it for the currently logged in user, if it was running

; DISABLELOCALHOST (REG_DWORD): '''true''' to disable use of '''localhost''' string to access the local webserver. Use '''127.0.0.1''' instead

; EXCLUDEINTERFACES (REG_SZ): some VPN interfaces are not detected by Windows as IF_TYPE_PPP or IF_TYPE_TUNNEL and therefore the '''media outside VPN''' setting is not taking effect. With this option interfaces can be pre-defined that will not be used for media. Interfaces must be comma separated
: e.g. <code>EXCLUDEINTERFACES="172,192.168,10.10"</code>

; FASTERDOWNLOADS (REG_DWORD): '''true''' to have faster downloads without artificially slowing down the download of an update (which is done to avoid audio lags if clients have slow networks).

Current settings are stored in the registry at <code>Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps</code> or at <code>Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\innovaphone\myApps</code>

Boolean values like OfficePresence are stored in registry entries with type REG_DWORD and values 1 or 0. 0 disables the setting and 1 enables it.

== iOS ==

myApps platform services are installed on iOS by loading ''innovaphone myApps'' from the ''App Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

== macOS ==

myApps platform services might be installed directly from the Apple store. An installer package <code>myapps.pkg</code> and a disk image <code>myapps.dmg</code> is also available from the innovaphone app store. Install <code>myapps.pkg</code> by double-click on the file and follow the instructions of the installer. myApps becomes available in the Applications folder and can be opened by double-click. Or download and open <code>myapps.dmg</code> and double klick myApps. If desired integrate it into the app dock by right click, ''Options, Keep in the dock''.

If installed from the innovaphone app store, myApps can update itself automatically, see [[#Auto update|Auto update]] above.

If installed from the Apple store, macOS notifies about updates on the Apple store. myApps [[#Auto update|Auto update]] is disabled then.

If a clean-install of the client is necessary, the folder "/Users/username/Library/Containers/myapps" needs to be deleted. To be on the safe side also delete it from the trash bin.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

=== Preferences ===

macOS supports preference settings that can be set via a shell command or via Mac remote management

defaults write com.innovaphone.client-ios-14r1 server "PBX-server-URL"

The following parameters and can be set through this method:

; server: the PBX's server URL

=== Setting myApps as Default App for SIP-URLs ===

{| class="wikitable"
|defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add '{
LSHandlerURLScheme = sip;
LSHandlerRoleAll = "<CFBundleIdentifier>";
}'
|}

To find the “CFBundleIdentifier”, proceed as follows:
* In the Finder under “Applications”, search for the desired myApps client that you want to set as the default app.
* Right-click on “Show package contents” -> you will find the “CFBundleIdentifier” in the Info.plist file.

A restart of the MAC is required.

=== Using Sennheiser headsets ===
If you use Sennheiser headsets, you should also install the then-current <code>DSEA_SDK_v</code>''version''<code>.pkg</code> package, after you installed the myApps client. Without that, audio will still work, but not the controls on the headset. You will need to keep that up-to-date yourself, as it is not updated by myApps's auto-update function.

== Android ==

myApps platform services are installed on Android by loading ''innovaphone myApps'' from the ''Play Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying a property "server" with string value "pbx.example.com" in the MDM.

= Configuration =

== Server configuration ==
When opening myApps for the first time, the user is prompted for the Server. Usually only the hostname (DNS host name or IP address) needs to be configured.

But there are more options for special PBX configurations.

; Non-standard HTTPS port
: If the PBX uses a non-standard HTTPS port, it must be appended to the host name separated by a colon (<code>:</code>).
: Example: <code>pbx.example.com:4444</code> (expands to <code>https://pbx.example.com:4444/PBX0/APPCLIENT/appclient.htm</code>)
; DynPBX module name
: If the PBX is a DynPBX, the module id must be appended to PBX0 separated - (<code>/</code>).
: Example: <code>pbx.example.com/PBX0-1</code> (expands to <code>https://pbx.example.com/PBX0-1/APPCLIENT/appclient.htm</code>)
; Softphone physical location
: If user defined physical location shall be used for softphone, you can append it using a parameter <code>#phys=</code>.
: Example: <code>pbx.example.com#phys=slave</code> (expands to <code>https://pbx.example.com/PBX0/APPCLIENT/appclient.htm#phys=slave</code>)

Example 1: PBX pbx.example.com with standard configuration
pbx.example.com

Example 2: PBX slave.example with DynPBX module ID 1, HTTPS port 4444 and physical location master
slave.example.com:4444/PBX0-1#phys=master

=== HTTP proxy support ===

myApps platform services do support operation via HTTP proxy now. If one or more proxies have been configured in the network settings of the operating system for the active network connection, HTTP CONNECT tunnels are established.

On Windows user name and password can be specified for the tunnel servers as generic credentials in the credentials manager (Anmeldeinformationsverwaltung). The name of the credentials must be the tunnel server hostname.

On Android user name and password can be specified through Android ''Settings, Accounts'' by adding a myApps ''HTTP Proxy Credentials'' account. The name of the account must be the tunnel server hostname.

== Platform specific settings ==
When myApps runs under the myApps platform services, it will show various platform specific settings as part of its ''burger menu'', so the user can set them. See ''Advanced settings'' in [[#UI elements|UI elements]] above.

Some options can also be set globally for all myApps clients in the PBX's [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps ''Client Settings'']]
{|
! style="text-align: left; font-weight: bold" | Option

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold" | Where to set

!
! style="text-align: left; font-weight: bold"| Availability
|-

| || || User menu || PBX ''Client Settings'' || Windows || iOS || Android || macOS

|-
| Autostart || Launch myApps on login || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Appear offline after || controls after which idle time a user is considered ''inactive''. See [[#User activity|User activity]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|-

| Hotkeys || Hotkeys for call dial, accept, reject. See [[#Hot keys|Hot keys]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Docking || Docking mode (left, right, none). See [[#???|??]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✗

|-

| Desktop notifications|| Turn on/off platform notifications. See [[#Notifications| Notifications]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| VPN || Disable VPN address for ICE candidate selection. See [[#RTP ports| RTP ports]] above || ✔ ||✔ ||✔ || ✗ || ✔ || ✔

|-

| Show in taskbar|| Show myApps in the taskbar in addition to it's tray icon. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗

|-

| Log flags || turn on/off certain trace levels. See [[#Troubleshooting|Troubleshooting]] below. || ✔ ||✔ ||✔ || ✔ || ✔ || ✔

|-

| External applications || define the applications available for Apps to be started. See [[#Call an external application for calls|Call an external application for calls]] above. || ✔ ||✗ ||✔ || ✗ || ✗ || ✔

|-

| Ring in headset || send ring tone for incoming to headset instead of loudspeaker. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗
|}
== Start parameters for Windows ==

On Windows, it is not possible to pass start parameters from the [https://www.chromium.org/developers Chromium documentation] to the myApps process.

== OS Settings for Windows ==
Windows settings can influence the display of ''Desktop notifications''. See [https://support.microsoft.com/en-us/help/4028678/windows-10-change-notification-settings Change notification settings in Windows 10/11] for details.

=== Windows 11 ===

* Windows 11 has a feature "do not disturb". This hides notifications if enabled.
* Windows 11 has a feature "focus". This enables "do not disturb" and thus hides notifications too.
* Windows 11 has priority settings for notifications. Ensure that VoIP notifications for calls are allowed any maybe also include myApps as an App which is allowed to show notifications.

== OS settings for Android ==
; Events : The appearance of notifications can be controlled here.

; Call accounts : For proper incoming call signaling, the call account ''myApps'' needs to be enabled. Note that on Samsung smartphones the call account switch likely toggles back and a few tries may need to be done until it persists. Please double-check the state.

; Preferred Calling Account : Choose which calling account (myApps/SIM/..) should be used for outgoing calls initiated from within the native phone app / phone book.

; Background data, unlimited data usage : Grant background data use to enable ''myApps'' to connect to the PBX immediately on an incoming call.

; Overlaying : This setting is not needed if call account ''myApps'' has been enabled. Should there be a reason for not enabling call account ''myApps'', the permission for overlaying needs to be granted on Android 10 or higher for proper call signaling.

Note: If no SIM card is installed some Android smartphones exhibit a problem dialing from the smartphone contacts. The contacts app shows a choice ''Select SIM card for this call'' but all possible dialers are greyed out. In this case make myApps the default phone app in Android settings ''Apps, Default apps, Telephony''.

== OS settings for iOS ==
; Notifications : The appearance of notifications can be controlled in iOS ''Settings, myApps''.

== OS settings for macOS ==

; Notifications : The appearance of notifications can be controlled in macOS ''Preferences, Notifications, myApps''.

=Troubleshooting=

myApps platform services can write various traces for debugging. Trace can be turned on and off selectively in the [[#Advanced settings|Advanced settings]].

The following trace flags can be set:

(''Recommended trace options are: '''App, Browser, ICE, TURN, Signaling and Audio'''. Please do not activate other flags unless innovaphone support says otherwise'')

{|
!style="text-align: left; font-weight: bold" | Abbreviation

!style="text-align: left; font-weight: bold" |code

!style="text-align: left; font-weight: bold" | description

|-
| App||0x000000001|| logs from the App Service itself
|-
| DNS||0x000000008|| logs DNS requests and results
|-
| HTTP client||0x000000080|| http client logs
|-
| TLS||0x000000400|| TLS logs
|-
| TCP||0x000000800|| TCP logs
|-
| LDS||0x000001000|| local domain sockets
|-
| WebSocket client||0x000004000|| logs outgoing websocket connections
|-
| App WebSocket||0x000008000|| logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
|-
| UDP||0x000200000|| UDP logs
|-
| DTLS||0x000400000|| logs DTLS handshake and messages
|-
| Media||0x000800000|| logs media events
|-
| Media channel||0x001000000|| logs RTP/SCTP media connections
|-
| ICE||0x002000000|| logs ICE messages between peers
|-
| TURN||0x004000000|| logs TURN messages between peers
|-
| AppSharing||0x008000000|| logs AppSharing connection
|-
| Audio||0x010000000|| logs Audio connection and headset events
|-
| Video||0x020000000|| logs video connection and webcam events
|-
| Browser||0x040000000|| logs Chromium events
|-
| AppProxy||0x080000000|| logs requests which are proxied between the local webserver and the remote server
|-
| Webserver ||0x200000000|| enables webserver specific logs
|-
| Browser Console ||0x400000000|| logs browser console events
|-
| Signaling||0x800000000|| enables logs in the signaling module for debugging calls
|}
''code'' can be or'ed and used as value for the ''Log flags'' field in [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps/Client Settings]].

; Windows :On Windows, traces are written to the <code>%LOCALAPPDATA%\innovaphone\myApps</code> directory. If you start myApps with --log-size as parameter, you can define the maximum size of a log file (e.g. --log-size=100000000 would be 100MB for each file)

:* myApps-''date-time''.txt : main log file for the platform services

:* myAppsOutlookSearch-''date-time''.txt : log file for the Outlook phone book access

:* myAppsHookController-''date-time''.txt : log file for the hot-key interceptor (see [[#Hot keys|Hot keys]])

; :myApps update installation traces are written to the <code>%windir%\temp\</code> directory.
:* myAppsInstall.txt: MSI installation file

; :myApps update service traces are written to the <code>%ProgramData%\innovaphone\myAppsUpdateService</code> directory.
:* myAppsUpdateService-''date-time''.txt: myApps update service traces

;Android : traces can be sent by e-mail.

: also, an Android device might also be connected to a PC via an USB cable to get the traces. The files can be found in <code>Android/data/com.innovaphone.clientandroid/files</code>

; iOS : traces can be sent by e-mail.

; macOS : traces can be sent by e-mail.

: also, the files can be found in <code>~/Library/Containers/com.innovaphone.client-ios/Data/Documents/</code>. Press ''Alt+N'' followed by space to get tilde ''~''.

= Known Problems =
[[:Category:Problem myApps platform services|Known Problems]]

= Related Articles =
* [[{{NAMESPACE}}:Concept_myApps]]
* [[{{NAMESPACE}}:Concept_myApps_Redundancy|Reference14r2:Concept_myApps_Redundancy]]
* [[{{NAMESPACE}}:Concept_myApps_Office_Integration|Reference14r2:Concept_myApps_Office_Integration]]
* [[{{NAMESPACE}}:Concept_myAPPs_Search_in_local-Outlook_Contacts|Reference14r2:Concept_myAPPs_Search_in_local-Outlook_Contacts]]
* [[{{NAMESPACE}}:Call_Detail_Record_CDR_PBX|Reference14r2:Call_Detail_Record_CDR_PBX]]
* [[{{NAMESPACE}}:Concept Push Notifications for myPBX iOS and Android|Reference14r2:Concept Push Notifications for myPBX iOS and Android]]
* [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]]
* [[{{NAMESPACE}}:PBX/Config/myApps]]

[[Category:Concept myApps platform services]]

Reference14r2:Concept myApps platform services

2026-04-21T09:01:47Z

Tfu: /* Device handling */

[[Category:Concept|myApps]]

myApps platform services provide various operating system specific services which can be used by other ''Apps'' running in the [[{{NAMESPACE}}:Concept myApps|myApps client]]. Those services typically are not available in the browser's JavaScript environment and hence must be implemented in native platform code. Therefore, the platform services are installed as native executable on the respective platform.

When myApps is started in a web browser (and hence has no access to the platform services), some Apps will use [https://en.wikipedia.org/wiki/WebRTC WebRTC] services implemented by the browser instead. For ease of reference, features available in this scenario are also described here.

On windows, the platform services also come with their own web browser in which the myApps web App will be started then. This browser is based on google's [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium] open source software.
= Applies To =

* [[{{NAMESPACE}}:Concept myApps|myApps]]
* myApps for Windows
* myApps for macOS
* myApps for iOS
* myApps for Android

* myApps Web App (WebRTC)
version 14r2

=Features=
Not all features are available or required on all platforms.
{|
! style="text-align: left; font-weight: bold" | Feature

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold"| Availability
|-

| || || Windows || iOS || Android || macOS || Browser<ref>This refers to the myApps web application running in a browser with no platform services available</ref>

|-
| audio || manage local audio devices to record and playback audio conversations || ✔ || ✔ || ✔ || ✔ || ✔ (audio available but devices managed by web browser)
|-

| video || manage local displays and cameras to capture and render video live stream || ✔ || ✔ || ✔ || ✔ || ✔ (video available but devices managed by web browser)

|-

| ringer || manage local ringing device || ✔ || ✔ || ✔ || ✔ || ✔
|-

| application sharing

|-

|   presenter || share an application || ✔ || ✗ || ✔ || ✔ || ✔
|-

|   consumer || view an application shared by the peer || ✔ || ✔ || ✔ || ✔ || ✔

|-

| hot keys || capture key presses for quick invocation of phone apps (e.g. dial selected number) || ✔ || ✗ || ✗ || ✔ || ✗
|-
| tel: and sip: URI handler || intercept clicks on tel: and sip: links in web sites to invoke phone apps || ✔ || ✔ || ✔ || ✔ || ✗

|-
| user activity || set presence state according to user activity || ✔ || ✗ || ✗ || ✔ || ✔<ref>limited, see [[#User activity|User activity]] below</ref>

|-

| docking || myApps can be docked persistently to the right or left edge of your screens || ✔ || ✗ || ✗ || ✗ || ✗

|-

| multi-windowing|| Apps can be launched in separate windows|| ✔ || ✗ || ✗ || ✔ || ✗

|-

| recording|| Calls can be recorded to recording app|| ✔ || ✔ || ✔ || ✔ || ✗

|-
| notifications || ||
|-
|   display notifications || display notifications with OS standard mechanism || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   push notifications || receive push notifications while myApps is not running || ✗ || ✔ || ✔ || ✔ || ✔<ref>The browser needs to be running in order to receive push notifications.</ref>
|-
|   chat and apps || display notifications for chat and other apps || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   calls || display notifications for incoming calls || ✔ || ✔ || ✔ || ✔ || ✗<ref>Call notifications are only displayed locally while the phone or softphone app is started.</ref>
|-

| phone book access || access local phone book || ✔ || ✔ || ✔ || ✔ || ✗
|-
| office presence provider || maps PBX presence state to Microsoft office presence state || ✔ || ✗ || ✗ || ✗ || ✗
|-

| external application start || start arbitrary external applications for calls || ✔ || ✗ || ✗ || ✔ || ✗

|-

| app proxy|| a caching proxy that provides app persistence || ✔ || ✔ || ✔ || ✔ || ✗

|-

| auto update || automatically updates myApps platform services to the same version the PBX has || ✔ || ✔ || ✗ || ✔ || ✔<ref>The then-current web app is always loaded from the PBX upon startup and hence up-to-date by definition</ref>
|-

| three party conference || initiate 3-pty-conference using Softphone-App || ✔ || ✔ || ✔ || ✔ || ✗

|-
| exclude VPN || disable use of VPN connections for audio/video/appsharing || ✔ || ✔ || ✔ || ✔ || ✗

|}

<references/>

=Requirements=
* innovaphone PBX 14r2 and up

== Hardware ==
Recommended hardware requirements
* Processor: Dual-core 2Ghz or higher
* RAM: 4 Gb

== myApps for Windows ==
* Windows 10 and up
* Windows Server 2016 and later versions

=== 32 & 64 bit Windows ===
* 32 bit Windows: install the myAppsSetup32.msi from the App Store
* 64 bit Windows: install the myAppsSetup.msi from the App Store
** the 64 bit variant still installs into Program Files (x86), as the main myApps.exe is still a 32bit application
** the 64 bit variant just contains an additional 64 bit binary for the outlook search

=== Windows N editions ===

Windows N editions are missing the ''Media Feature Pack'' which is pre installed on other Windows versions.

Please install the pack from [https://www.microsoft.com/en-us/software-download/mediafeaturepack Microsoft (Windows 10 pack)] before you install myApps. The installer will check if the file <code>C:\Windows\SysWOW64\mfplat.dll</code> exist on your system.

Make sure to install the correct pack depending on your Windows version! There are different packs for Windows 10 1703, 1803, 1809 and 32bit or 64bit etc.

NB: Sometimes the myApps installation will not work even though the media pack is already installed. This is because the installer has no read access to check if the package is already installed. If the above-mentioned file exists and the installer asks to install the Windows Media Feature Pack nevertheless, you have to start the myApps install with administrative rights.

=== Terminal Server environments ===

Audio driver was removed if myApps discovers that it is running in a terminal server environment like Citrix.

The audio driver is needed for the Softphone App but the Softphone App should not use an audio driver at the server side because the audio devices are plugged locally and there would be a delay sending and receiving audio data with the server.

If a customer wants to use the Softphone App at the server side he needs to make use of the myApps Plugin for virtual desktops solution:

[[{{NAMESPACE}}:MyApps_Plugin_for_Virtual_Desktops]]

== myApps for macOS ==
* macOS 10.13 or higher

== myApps for iOS ==
* iOS 13 or higher

== myApps for Android ==
* Android 6.0 or higher. Android 6.x may need an update of the Chrome browser.

= Licenses =
* No license needed for myApps platform services

= Overview =
myApps platform services is a native executable that is installed using the standard mechanisms on the respective operating system. It provides various advanced services which can be used by the myApps web client code as well as the Apps running in the myApps context.

Also, on Windows, the platform services come with their own, dedicated browser to run myApps in. This browser is based on [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium]. On iOS, macOS and Android, it is based upon native embedded web view facilities (such as WKWebView) instead.
== Components ==

=== RTP service for audio, video and data ===
The RTP service provides audio, video and data (app sharing) VoIP RTP endpoints (e.g. for softphones). It supports STUN, TURN, ICE, SRTP, DTLS. Note however that unlike WebRTC, these endpoints do not ''require'' ICE and DTLS. In other words, they can communicate also with non-compliant (i.e. older) VoIP devices.

Note that the available capabilities when not running the myApps platform services depend on the used browser's WebRTC implementation. See your browser documentation for details.

Apps can request RTP channels using the [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol]'s ''AllocChannel'' message.

===== RTP ports=====

{|

| audio || 50000 -> 50099

|-

| video || 50100 -> 50199

|-

| data || 50200 -> 50299

|}

The RTP service will enumerate all local interfaces and create local HOST candidates for ICE. There is an option however to disregard VPN interfaces (more precisely such interfaces with type of ''IF_TYPE_PPP'' or ''IF_TYPE_TUNNEL''). This can eliminate quality issues when RTP data is transmitted through TCP based VPN tunnels.

SRFLX and RELAY candidates are obtained using the STUN and TURN server configuration passed by the App (e.g the ''softphone'' App) as part of the ''AllocChannel'' request.
<code>{"mt":"AllocChannel","channel":"81429cba-396d-43de-8a76-ec020ba8796e","iceServers":[{"urls":"turn:myturn.domaincom:4077?transport=udp","username":"turnuser","credential":"pwd","credentialType":"password"},{"urls":"stun:mystun.domain.com:4077"}],"dn":"Foo Bar","type":"RemoteRtp","kind":"video"}</code>

===== Codecs =====

The installed myApps launchers provide codecs that can be used by softphone apps for media streams. When running in a web browser the codecs depend on the browser version and operating system. See the documentation of your browser for details.

The following codecs are supported:

{|
!style="text-align:left;width:100px;"|Codec
!style="width:100px"|Windows-Launcher
!style="width:100px"|Android
!style="width:100px"|iOS
!style="width:100px"|macOS
!style="width:100px"|Firefox (Browser)
!style="width:100px"|Chrome (Browser)
!style="width:100px"|Edge (Browser)
!style="width:100px"|Safari (Browser)
!style="width:100px"|Opera (Browser)
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Audio
|-
|G711A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G711u
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G722
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G729
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729B
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729AB
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|[https://caniuse.com/#search=Opus OPUS-NB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|[https://caniuse.com/#search=Opus OPUS-WB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Video
|-
|[https://caniuse.com/#search=VP8 VP8]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|-
|[https://caniuse.com/#search=VP9 VP9]
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|-
|[https://caniuse.com/#search=H264 H264]
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Application Sharing
|-
|Share
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|Watch
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|}

''* small presentation only'' 
''** only for 1:1 calls, not for conferences

===== Video capture =====

The default resolution for video capture is 1280x720 if available. Otherwise, 640x480, 352x288 or 320x240 will be used. The frame rate is 30 fps if available, otherwise 15 fps. The resulting average bandwidth could reach 1 Mbps.

===== Application sharing =====

Screen content will be transmitted by the presenter.

===== Device handling =====

The RTP service enumerates microphones, loudspeaker, cameras and ringing devices and notifies apps when devices come and go. It is up to the apps using the devices to store preferences.

The RTP service also enables some extended features (such as hook switch or volume control) for supported USB headsets or Bluetooth headsets connected to myApps.
The supported headset-SDKs determine which headset vendors are recommended to be used with the myApps softphone app. 

For this to work, the following vendor specific development kits are integrated in our myApps client. Be aware that the SDK are updated within our Service release :

{| class="wikitable"
|-
! SDK Vendor !! Supported OS !! SDK Version !! innovaphone Service Release
|-
| Jabra|| MacOS || 1.16.4.0 || 14r2sr11
|-
||| Windows || 1.16.4.0 || 15r1sr3
|-
| Epos ''(formerly Sennheiser)'' || MacOS || 12.4.0.5478 || 14r1sr3
|-
||| Windows || n.a. - [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|to be installed separately]]|| 13r3sr10
|-
| Poly ''(formerly Plantronics)'' || MacOS || 3.25.53799.37131 || 13r3sr9
|-
||| Windows || 3.25.53800.37131 || 13r3sr10
|-
| Yealink || MacOS || 3.1.1.23 || 14r2sr1
|-
||| Windows || 3.1.1.23 || 14r2sr2
|}

Notes:
* It is possible to inhibit the start of the Sennheiser SDK (SenncomSDK.exe) using the <code>DISABLEHEADSETS</code> directive of the installer (see [[#MSI Parameters and install options| MSI parameters]] below).

* Starting with V13r3sr10, the Epos-SDK needs to be installed separately using the Epos Connect software to ensure full compatibility between current Epos headset models and native myApps-Windows client. For details [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|refer to this article]].


===== Ring tones =====

Ring tones can be played. Apps can choose the tone from a pre-defined list of ring tones.

On Windows, custom ring tones can be uploaded as .mp3 files to the <code>ringtones</code> sub-directory of myApps' roaming directory (which usually is in <code>C:\Users\...\AppData\Roaming\innovaphone\myApps\ringtones</code>).

On Android, custom ring tones can be added to the system via Android settings.

On iOS, custom ring tones can be uploaded as .mp3 files to the <code>Ringtones</code> subdirectory of the myApps file share that is available in iTunes if the iPhone has been connected via USB.

On macOS, custom ring tones can be uploaded as .mp3 files to <code>~/Library/Containers/com.innovaphone.client-macos/Data/Documents/Ringtones</code>.

===== Debugging =====
For extended debugging, turn on the ''Audio'', ''Media'' and ''AppSharing'' traces in myApps.

=== Hot keys ===
On Windows and macOS systems, myApps platform services can listen for hot keys and invoke certain functions. Invocation is done by sending API messages to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

The hot keys can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below. Any of the function keys F1 to F11 (optionally combined with up to two modifier keys ''alt'', ''ctrl'', ''shift'' or ''win'') can be chosen for each function. If you do not want to start the call with "Hotkey+Enter" because you would have to wait for the focus, the hotkey can also be pressed twice and the number is dialled directly.

; dial selected number : Initiates a call using the currently selected text as target.

: A ''PrepareCall'' message with the ''text'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":"mt":"PrepareCall","text":"13","adjust":true}}</code>

; accept call : Accepts a currently alerting call.

: A ''ConnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"ConnectCall"}}</code>

; reject/disconnect call : Rejects a currently alerting call or disconnects an active call.

: A ''DisconnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"DisconnectCall"}}</code>

=== URL Handler ===

On Windows systems, two URI-handler are installed with the myApps platform services. Windows will call up this URI handler when a user clicks on an appropriate link, for example in a web site.

The handler will the send an API message to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

; tel URI : call a number, e.g. <code>tel:4711</code>

: A ''PrepareCall'' message with the ''num'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","num":"4711","adjust":true}}</code>
; sip URI : call a SIP name, e.g. <code>sip:zkl@innovaphone.com</code>

: A ''PrepareCall'' message with the ''sip'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","sip":"zkl@innovaphone.com","adjust":true}}</code>
; im URI : start chat with SIP name, e.g. <code>im:zkl@innovaphone.com</code>

: A ''StartChat'' message with the ''sip'' argument set to the selected text will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm ''com.innovaphone.chat'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.chat","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartChat","sip":"zkl@innovaphone.com"}}</code>

On macOS systems myApps might be made the default application to handle tel URI e.g. <code>tel:4711</code> via Apple FaceTime. Open the "FaceTime" menu "Settings..." and select myApps as "Default for phone calls".

On iOS ''tel'' URIs are always dialed via GSM. Therefore myApps iOS also reacts to URI schemes ''com.innovaphone.tel'', ''com.innovaphone.sip'' and ''com.innovaphone.im'', e.g. <code><nowiki>com.innovaphone.tel:4711</nowiki></code>, <code><nowiki>com.innovaphone.sip:zkl@innovaphone.com</nowiki></code>, <code><nowiki>com.innovaphone.im:zkl@innovaphone.com</nowiki></code>.

=== User activity ===
On Windows and macOS systems, the myApps platform services can monitor user keyboard/mouse activity and change the user's presence state after a certain amount of inactivity. The timeout can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below.

myApps will then send a [https://sdk.innovaphone.com/doc/appwebsocket/myApps.htm#SetUserActivity''SetUserActivity''] message to the PBX using the ''myApps'' protocol.

: <code>{"mt":"SetUserActivity","inactive":true}</code>

This will change the ''status'' property of the ''im:'' contact for the user's own presence and hence result in a presence update from the PBX to myApps

: <code>{"mt":"UpdateOwnPresence","presence":[{...},{"contact":"im:","activity":"","status":"closed"}]}</code>
The ''closed'' status is reflected in the grey status color when displaying a contact [[Image:myapps-inactive.png|myapps-inactive.png/|myapps-inactive.png/]].

On iOS and Android, the state is set to ''inactive'' as soon as the App is brought to background.
When myApps platform services are not available (i.e. when running the web application in a browser solely) a limited user activity monitoring is available: the state is set to active when the web page is not used for more than 5 minutes.

=== Recording ===

The new launcher offers the possibility to record the audio of incoming and outgoing calls. In order to activate that functionality the URL of the recording instance must be configured in either the PBX (PBX->myApps->Config: Recording URL) or the softphone App (Settings->Audio Recording (URL))

[[Image:PBX-Recording-Settings.png|pbx-recording-settings.png/|pbx-recording-settings.png/]] [[Image:Recording-Softphone-Settings.png|recording-softphone-settings.png/|recording-softphone-settings.png/]].

As long as that URL is configured the audio data of all calls are stored as pcap-files under that URL.
If the URL points to a CF device in the PBX, write access must be granted for that URL (PBX->Services->HTTP->Server:Public compact flash access) and if the URL points to the recording app, the files can be accessed via the recording app [[{{NAMESPACE}}:Concept_App_Service_Recordings|recording]].

Under PBX->myApps the administrator can set a certain default behaviour of the audio recording like whether or not the recording should start automatically at the beginning of the call (Recording by Default ON/OFF), only calls with external numbers should be recorded (Record external calls only) or whether or not the user should be able to start/stop the recording himself (Allow user incall recording control). Except for the last parameter these parameters can also be modified by the user in its softphone settings if the administrator doesn't set the FORCE flag.

If the user was allowed by the admin to control the recording a recording switch is active during the call when the "Media" Panel is opened. There the audio recording may be stopped and continued at will. A red recording notice is shown in the top right corner when the recording actually takes place.

[[Image:Recording-incall-switch.png|recording-incall-switch.png/|recording-incall-switch.png/]]

=== Notifications ===

The myApps platform services can use the OS specific notification mechanism (e.g. ''desktop notifications'' on Windows) to display messages (e.g. ''incoming new chat message'') to the user.

Note that the actual rendering of the notification is under control of the OS. Therefore, myApps must be allowed to show notifications and its appearance can be restricted by OS native settings.

==== Microsoft Windows Notifications ====

Microsoft Windows Server editions (2016, 2019, 2022) are just capable of showing a single ''IncomingCall'' notification at the same time (we couldn't find a workaround for this limitation). 
An ''IncomingCall'' notification is visible the whole time instead of being moved to the action center after a certain time. 
 
A notification about a missed call uses the ''IncomingCall'' type so that this notification is visible until the user returns. 
Due to the above limitation, on a new arriving call such a missed call notification is transformed to a default notification which will be moved to the action center automatically. 
 
On non server editions, you can have multiple IncomingCall notifications at the same time (so two parallel incoming calls will be indeed notified at the same time), but the missed call notification handling is the same on both platforms!

Thus there will be always just '''one''' missed call notification visible and previous missed calls can be found inside your action center!

To see myApps notifications, ensure:
* System -> Notifications
** enable notifications
** disable "Do not disturb" or allow myApps as priority application while "Do not disturb" is active
** enable notifications for myApps in the list of applications
* System -> Focus
** if a focus session is active and the "Do not disturb" is activated during a focus session, make sure that myApps is a priority application (see above)

==== macOS Notifications ====
Notifications are the same as on Windows.
The difference is, that for macOS, notifications need to be allowed in the system settings.
Go to Notifications - myApps, select Banner and enable all check marks.

=== Local phonebook access ===
'''Contact Search:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm ''com.innovaphone.search'' API]]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Search'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{"mt":"Search","type":"contact","search":"john doe"},"apiId":"com.innovaphone.search"}</code>
Search results are delivered as ''SearchInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{"mt":"SearchInfo","relevance":2000,"adjust":true,"type":"contact","contact":{"givenname":"John","sn":"Doe","company":"ACME","position":"Head of everything","telephonenumber":["11111","22222"],"homephone":["+4944444","33333"],"mobile":["+49 (123) 55555"]}},"api":"com.innovaphone.search"}</code>

'''Reverse Lookup:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.phonelookup/lib1_api_phonelookup.htm ''com.innovaphone.phonelookup'' API]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Lookup'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{ mt: "Lookup", prefixIntl: "000", prefixNtl: "00", prefixExt:"0", area: "7031", country: "49", lookup: "0004970311234567" },"apiId":"com.innovaphone.lookup"}</code>

Search results are delivered as ''LookupInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{mt: "LookupInfo", dn: "Jake Blues", contact: { telephonenumber: ["0004970311234567"], givenname: "Jake", sn: "Blues", company: "Blues Brothers" </code>

==== Windows ====
On Windows, the search and lookup are performed in all of the user's Outlook contact folders. As opposed to the search implemented in the ''Contacts'' and ''Users'' App, all items are returned which match any of the search words (i.e. searching for ''a b'' will return items matching either ''a'' or ''b'').

; searched properties : firstname, lastname
; returned properties : Following Outlook contact phone number properties are returned (if available):

:* OFFICE_TELEPHONE_NUMBER as ''telephonenumber''
:* OFFICE2_TELEPHONE_NUMBER as ''telephonenumber''
:* HOME_TELEPHONE_NUMBER as ''homephone''
:* HOME2_TELEPHONE_NUMBER as ''homephone''
:* MOBILE_TELEPHONE_NUMBER as ''mobile''
:* BUSINESS_FAX_NUMBER as ''facsimiletelephonenumber''
Note that contact information is cached in the search provider. Updated contacts may therefore become effective after a while only.
Outlook search will create its own trace file <code>myAppsOutlookSearch-</code>''date-time''<code>.txt</code> in the standard trace directory.

This search provider is always installed and can be disabled. There is no need (nor possibility) to enable it in the ''Apps'' tab of the PBX's user object. Also, no ''App'' object needs to be created for it.

==== Android/iOS ====
The search and lookup are performed in the contacts.

==== macOS ====
The search and lookup are performed in the contacts. If you wish to disable local contact lookup, go to system settings - Security & Privacy and disable the access to contacts for myapps.

=== Microsoft Office integration ===

The myApps platform services has a ''office presence provider'' that can provide the user's presence state to Office applications. See [[{{NAMESPACE}}:Concept_myApps_Office_Integration|myApps Office Integration]] for details.

This feature is installed by default. However, it can be disabled using the ''OFFICEPRESENCE'' MSI Parameter. Also, a check-mark is available in the setup dialog.

=== Call an external application for calls ===

Phone Apps (such as the phoneapp or softphone) can initiate the start of an external application when a new call appears (either incoming or outgoing). The actual spawning of the application is done by the myApps platform service. Also, the application properties (such as e.g. the executable's path) is configured in the myApps platform services (see [[#UI elements|Advanced settings]] in the ''UI elements'' section below).

A number of arguments can be passed to the application by substituting $-variables in the ''Parameter'' field:

; $n : phone number as dialed (called party number for outgoing calls) or received (calling party number for incoming calls)

; $N : called or calling party number in ''national'' format (e.g. 07031730090)

; $I : called or calling party number in ''international'' format (e.g. +497031730090)

: note that both $N and $I only work if $n includes both subscriber number and area code (e.g. 07031730090). Otherwise they are equal to $n

; $d : display name of peer (if known)

; $u : URI name of the peer (if available eg with a federation call)

; $c : conference id

: this is a globally unique ID for this call and may be used to relate the call to the ''guid'' found in the CallInfo structure in the [http://wiki.innovaphone.com/index.php?title=Reference10:SOAP_API#CallInfo SOAP-API] and [http://sdk.innovaphone.com/doc/appwebsocket/RCC.htm RCC-API ]. Also, corresponding [[Reference10:Call Detail Record CDR PBX|CDRs]] can be related using the ''event'' tag's ''conf'' attribute.
The start of an external application can be requested using the ''com.innovaphone.externalapps'' API.

Some setup examples are [[Howto:Integrate External Apps in innovaphone UC clients|shown here]].

=== Push ===

Mobile operating systems usually inhibit network operation of apps which run in the background or are closed by the user. This is done in order to reduce battery consumption. Unfortunately, this also stops such apps to maintain a registration by regularly sending ''keep alive'' messages to a server (in our case to the PBX). As a result, myApps will be disconnected from the PBX. When the PBX determines that there is an event for the application which needs a response, it needs to wake up the app using a dedicated channel provided by the operating system. This mechanism is know as ''push''. When running on iOS or Android, myApps supports ''push''.

For ''push'' to work, a [[{{NAMESPACE}}:PBX/Objects/Push|''push object'']] needs to be configured in the PBX . Also, it needs to be enabled on the mobile phone for the myApps app.
This mechanism is quite similar in v12 and v13, so you can refer to [[{{NAMESPACE}}:Concept_Push_Notifications_for_iOS_and_Android|Reference14r2:Concept_Push_Notifications_for_iOS_and_Android]] for more details.

Also, helpful hints can be found in [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]].

=== App Proxy ===

myApps runs further ''Apps'' (such as e.g. the ''phoneapp'') as a web page in an IFRAME of the browser myApps is running in. The App's page code is loaded either from the PBX or from an ''application platform'' (AP). This however would mean that the App's IFRAME would remain empty (a dead white screen) when the PBX or AP is not available. To make sure the App can start-up anyway, the myApps platform services feature the so-called ''App Proxy''. This is a caching proxy that caches all the App code so it is available even in case of network failure. When myApps runs in the context of the platform services, Apps are therefore not loaded from the App source directly, but from the local App proxy.

The cached files are stored in the PCs local file system in the <code>C:\Users\...\AppData\Local\innovaphone\myApps\appproxy</path></code>. There is no configuration required. However, if myApps seems to run with outdated or corrupt cached copies of the App, you can safely delete the entire directory.

=== Auto update ===

On Windows and on macOS, the myApps platform services can auto-update themselves to a common version. This is controlled by the [[{{NAMESPACE}}:PBX/Config/myApps#Launcher_Software_Update | ''Launcher Software Update'']] settings under ''PBX/Config/myApps'' in the PBX.

When myApps is started or the user logs in or myApps needs to re-connect to the PBX, the platform services will use the [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client API] to learn the desired version (''launcherUpdateBuild'', which is part of the API's ''model''). If this differs from the current version, the platform services will try to download the respective new version.

<code>
{
"mt": "ApiUpdate",
"apis": {
"com.innovaphone.client": {
"@client": {
"title": "innovaphone myApps",
"model": {
"launcher": true,
"launcherUpdateBuild": "134906",
"appStoreUrl": "http://store.innovaphone.com/release/download/"
}
}
}
}
}</code>

The installation of the downloaded version is done by the ''innovaphonemyAppsUpdateService''. This service is installed and enabled during the initial installation of the myApps platform services. To disable auto-update, either leave the ''Launcher Software Update'' settings empty or set the service's start mode to ''disabled'' in the Windows ''services control panel''.

Note that on Windows the update service does not work on terminal servers. Administrators must do myApps base services updates using standard windows mechanisms.

Note that on macOS if myApps has been installed from the Apple Store it is assumed that auto update from the PBX is not desired and disabled therefore.

On Android/iOS/macOS updates can be downloaded from the respective app store.

The ''Devices'' app can not update software installed on Windows PCs directly. However, when the PBX is updated using an ''update job'' in the ''Devices'' App, the ''Launcher Software Update'' settings will be updated accordingly and hence the myApps base services will ultimately also be updated to the same version.

==== Auto update flow on Windows ====

* On start of myApps, myApps checks if an update is available and ready for installation
** if yes, the update is installed directly, without user interaction (a popup is shown during the installation)
** if not, myApps starts
* if an update is available while myApps is already running, an update notification will be shown which let's the user choose to install the update now or later (the notification will then popup again after one hour)

==UI elements ==
There are a few user interfaces provided by the platform services:
===tray-icon (Windows only) ===
::[[Image:myapps-tray.png|myapps-tray.png/|myapps-tray.png/]]
:Allows to
:* terminate myApps
:* toggle the ''autostart'' state
:* toggle the ''show in task bar'' state
:* open the trace folder
:
=== PBX connect form===
:: [[Image:myapps-connect.png|myapps-connect.png/|myapps-connect.png/]]
: Allows the user to specify the connect data for the PBX (i.e. IP address or DNS name)
:
=== Advanced settings===
::[[Image:myapps-settings0.png|myapps-settings0.png/|myapps-settings0.png/]]
::[[Image:myapps-settings.png|myapps-settings.png/|myapps-settings.png/]] [[Image:myapps-settings2.png|myapps-settings2.png/|myapps-settings2.png/]] [[Image:myapps-settings3.png|myapps-settings3.png/|myapps-settings3.png/]]

: Allows to modify various platform dependant settings (such as e.g. the hotkey selection on Windows)

== Interfaces ==
=== Provided APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm com.innovaphone.search] : access to local phone book entries by the [[#Local phonebook access|Local phonebook access]] component.
; [http://sdk.innovaphone.com/web1/com.innovaphone.launcher/com.innovaphone.launcher.htm com.innovaphone.launcher] : display of OS specific user notifications and receipt of related user actions
; com.innovaphone.notificationhandler : reports back click on a notification.
; com.innovaphone.externalapps : to start external applications, see [[#Call an external application for calls|Call an external application for calls]] above

=== Used APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm com.innovaphone.phone] : used to initiate new or manipulate existing calls by the [[#Hot keys|Hot keys]] and [[#URL handler|URL handler]] components.

; [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm com.innovaphone.chat] : used to start a new chat by the [[#URL handler|URL handler]] component.

; [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client] : the model is used to learn the update settings, see [[#Auto update|Auto update]] above

=== Protocols ===

; [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol] : used by apps to allocate RTP channels, see [[#RTP service for audio.2C video and data|RTP service for audio, video and data]] above

== Related App Services ==

none

== Known limitations ==
; Incoming call as banner on myApps for iOS : Since iOS 14 the iOS CallKit presents incoming calls as a banner leaving the original green answer button of myApps visible. Use only the blue button of the banner to accept the call or change iPhone Settings, App "Phone", "Incoming Calls" to "Full Screen" to hide the myApps user interface again during call answering.

; Call answer in speakerphone mode even with active Bluetooth headset on myApps for iOS : This causes unwanted speakerphone operation if the smartphone is used with a Bluetooth car audio system. The behaviour can be changed by selecting ''Bluetooth Headset'' in this setting:
:''iOS Settings->Accessibility->Touch->Call Audio Routing: Automatic / Bluetooth Headset / Speaker''
:''iOS Einstellungen->Bedienungshilfen->Tippen->Anrufaudioausgabe: Automatisch / Bluetooth-Headset / Lautsprecher''

; Windows Server 2016 (Windows 10 Build 1607) : windows just shows the first notification. Further notifications aren't displayed until the previous ones are removed from the notification center. Current windows builds do not show this behaviour anymore.

; Problems on Mac computers with Yealink USB headsets
: we have received reports that myApps quits unexpectedly on some Mac computers when a Yealink headset is plugged in. Unfortunately, we could not find out the cause yet. If you use Yealink USB headsets and have a similar issue, please open a support ticket and send myApps traces.

; Poly / Plantronics headset buttons only functional if myApps is started with Rosetta
: myApps macOS supports Apple M1/M2 hardware natively. However, the Poly / Plantronics headset SDK is only available for Intel platform and thus myApps needs to be started via Apple's Intel emulator Rosetta if a Poly / Plantronics headset is used. This is done with right-click on the myApps executable, ''Information'', ''Open with Rosetta''.

; Windows surface devices may not work correctly
: Chromium does not get touch keyboard events. USB Keyboards may not be recognized either.

= Installation =

== Windows ==

myApps platform services are installed on Windows using the .msi file found in the ''myApps Windows'' package from [https://store.innovaphone.com/release/download.htm store.innovaphone.com].

myApps can update itself automatically, see [[#Auto update|Auto update]] above.

=== MSI Parameters and install options ===

The MSI installer of myApps for Windows supports the following parameters and can be edited with [https://docs.microsoft.com/en-us/windows/win32/msi/orca-exe Microsoft Orca]. You can add your parameters in the table ''property''.

; SERVER (REG_SZ): the PBX's server URL
; OFFICEPRESENCE (REG_DWORD): '''false''' to disable presence integration in Microsoft Office
: this is also available as a check-mark when running the install manually

; DISABLEHEADSETS (REG_DWORD): '''true''' to disable headsets support, see [[#Device handling|Device handling]] above

; EXTERNALAPPS (REG_SZ): pre-define external applications, see [[#Call an external application for calls|Call an external application for calls]] above
: e.g. <code>"{""externalApps"":[{""id"":0,""name"":""Wireshark"",""path"":""C:\\Program Files\\Wireshark\\Wireshark.exe"",""param"":""test $I""}]}"</code>

; FORCERESTART (REG_DWORD): '''true''' (or any string ...) kills myApps during the installation and restarts it for the currently logged in user, if it was running

; DISABLELOCALHOST (REG_DWORD): '''true''' to disable use of '''localhost''' string to access the local webserver. Use '''127.0.0.1''' instead

; EXCLUDEINTERFACES (REG_SZ): some VPN interfaces are not detected by Windows as IF_TYPE_PPP or IF_TYPE_TUNNEL and therefore the '''media outside VPN''' setting is not taking effect. With this option interfaces can be pre-defined that will not be used for media. Interfaces must be comma separated
: e.g. <code>EXCLUDEINTERFACES="172,192.168,10.10"</code>

Current settings are stored in the registry at <code>Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps</code> or at <code>Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\innovaphone\myApps</code>

Boolean values like OfficePresence are stored in registry entries with type REG_DWORD and values 1 or 0. 0 disables the setting and 1 enables it.

== iOS ==

myApps platform services are installed on iOS by loading ''innovaphone myApps'' from the ''App Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<code><plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist></code>

== macOS ==

myApps platform services might be installed directly from the Apple store. An installer package <code>myapps.pkg</code> and a disk image <code>myapps.dmg</code> is also available from the innovaphone app store. Install <code>myapps.pkg</code> by double-click on the file and follow the instructions of the installer. myApps becomes available in the Applications folder and can be opened by double-click. Or download and open <code>myapps.dmg</code> and double klick myApps. If desired integrate it into the app dock by right click, ''Options, Keep in the dock''.

If installed from the innovaphone app store, myApps can update itself automatically, see [[#Auto update|Auto update]] above.

If installed from the Apple store, macOS notifies about updates on the Apple store. myApps [[#Auto update|Auto update]] is disabled then.

If a clean-install of the client is necessary, the folder "/Users/username/Library/Containers/myapps" needs to be deleted. To be on the safe side also delete it from the trash bin.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<code><plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist></code>

=== Preferences ===

macOS supports preference settings that can be set via a shell command or via Mac remote management

<code>> defaults write com.innovaphone.client-ios-14r1 server "PBX-server-URL"</code>

The following parameters and can be set through this method:

; server: the PBX's server URL

=== Setting myApps as Default App for SIP-URLs ===
{| class="wikitable"
|defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add '{
LSHandlerURLScheme = sip;
LSHandlerRoleAll = "<CFBundleIdentifier>";
}'
|}
To find the “CFBundleIdentifier”, proceed as follows:

* In the Finder under “Applications”, search for the desired myApps client that you want to set as the default app.

* Right-click on “Show package contents” -> you will find the “CFBundleIdentifier” in the Info.plist file.

A restart of the MAC is required.

=== Using Sennheiser headsets ===
If you use Sennheiser headsets, you should also install the then-current <code>DSEA_SDK_v</code>''version''<code>.pkg</code> package, after you installed the myApps client. Without that, audio will still work, but not the controls on the headset. You will need to keep that up-to-date yourself, as it is not updated by myApps's auto-update function.

== Android ==

myApps platform services are installed on Android by loading ''innovaphone myApps'' from the ''Play Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying a property "server" with string value "pbx.example.com" in the MDM.

= Configuration =

== Server configuration ==
When opening myApps for the first time, the user is prompted for the Server. Usually only the hostname (DNS host name or IP address) needs to be configured.

But there are more options for special PBX configurations.

; Non-standard HTTPS port
: If the PBX uses a non-standard HTTPS port, it must be appended to the host name separated by a colon (<code>:</code>).
: Example: <code>pbx.example.com:4444</code> (expands to <code>https://pbx.example.com:4444/PBX0/APPCLIENT/appclient.htm</code>)
; DynPBX module name
: If the PBX is a DynPBX, the module id must be appended to PBX0 separated - (<code>/</code>).
: Example: <code>pbx.example.com/PBX0-1</code> (expands to <code>https://pbx.example.com/PBX0-1/APPCLIENT/appclient.htm</code>)
; Softphone physical location
: If user defined physical location shall be used for softphone, you can append it using a parameter <code>#phys=</code>.
: Example: <code>pbx.example.com#phys=slave</code> (expands to <code>https://pbx.example.com/PBX0/APPCLIENT/appclient.htm#phys=slave</code>)

Example 1: PBX pbx.example.com with standard configuration
pbx.example.com

Example 2: PBX slave.example with DynPBX module ID 1, HTTPS port 4444 and physical location master
slave.example.com:4444/PBX0-1#phys=master

=== HTTP proxy support ===

myApps platform services do support operation via HTTP proxy now. If one or more proxies have been configured in the network settings of the operating system for the active network connection, HTTP CONNECT tunnels are established.

On Windows user name and password can be specified for the tunnel servers as generic credentials in the credentials manager (Anmeldeinformationsverwaltung). The name of the credentials must be the tunnel server hostname.

On Android user name and password can be specified through Android ''Settings, Accounts'' by adding a myApps ''HTTP Proxy Credentials'' account. The name of the account must be the tunnel server hostname.

== Platform specific settings ==
When myApps runs under the myApps platform services, it will show various platform specific settings as part of its ''burger menu'', so the user can set them. See ''Advanced settings'' in [[#UI elements|UI elements]] above.

Some options can also be set globally for all myApps clients in the PBX's [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps ''Client Settings'']]
{|
! style="text-align: left; font-weight: bold" | Option

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold" | Where to set

!
! style="text-align: left; font-weight: bold"| Availability
|-

| || || User menu || PBX ''Client Settings'' || Windows || iOS || Android || macOS

|-
| Autostart || Launch myApps on login || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Appear offline after || controls after which idle time a user is considered ''inactive''. See [[#User activity|User activity]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|-

| Hotkeys || Hotkeys for call dial, accept, reject. See [[#Hot keys|Hot keys]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Docking || Docking mode (left, right, none). See [[#???|??]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✗

|-

| Desktop notifications|| Turn on/off platform notifications. See [[#Notifications| Notifications]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| VPN || Disable VPN address for ICE candidate selection. See [[#RTP ports| RTP ports]] above || ✔ ||✔ ||✔ || ✗ || ✔ || ✔

|-

| Show in taskbar|| Show myApps in the taskbar in addition to it's tray icon. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗

|-

| Log flags || turn on/off certain trace levels. See [[#Troubleshooting|Troubleshooting]] below. || ✔ ||✔ ||✔ || ✔ || ✔ || ✔

|-

| External applications || define the applications available for Apps to be started. See [[#Call an external application for calls|Call an external application for calls]] above. || ✔ ||✗ ||✔ || ✗ || ✗ || ✔

|-

| Ring in headset || send ring tone for incoming to headset instead of loudspeaker. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗
|}
== Start parameters for Windows ==

On Windows, it is not possible to pass start parameters from the [https://www.chromium.org/developers Chromium documentation] to the myApps process.

== OS Settings for Windows ==
Windows settings can influence the display of ''Desktop notifications''. See [https://support.microsoft.com/en-us/help/4028678/windows-10-change-notification-settings Change notification settings in Windows 10/11] for details.

=== Windows 11 ===

* Windows 11 has a feature "do not disturb". This hides notifications if enabled.
* Windows 11 has a feature "focus". This enables "do not disturb" and thus hides notifications too.
* Windows 11 has priority settings for notifications. Ensure that VoIP notifications for calls are allowed any maybe also include myApps as an App which is allowed to show notifications.

== OS settings for Android ==
; Events : The appearance of notifications can be controlled here.

; Call accounts : For proper incoming call signaling, the call account ''myApps'' needs to be enabled. Note that on Samsung smartphones the call account switch likely toggles back and a few tries may need to be done until it persists. Please double-check the state.

; Preferred Calling Account : Choose which calling account (myApps/SIM/..) should be used for outgoing calls initiated from within the native phone app / phone book.

; Background data, unlimited data usage : Grant background data use to enable ''myApps'' to connect to the PBX immediately on an incoming call.

; Overlaying : This setting is not needed if call account ''myApps'' has been enabled. Should there be a reason for not enabling call account ''myApps'', the permission for overlaying needs to be granted on Android 10 or higher for proper call signaling.

Note: If no SIM card is installed some Android smartphones exhibit a problem dialing from the smartphone contacts. The contacts app shows a choice ''Select SIM card for this call'' but all possible dialers are greyed out. In this case make myApps the default phone app in Android settings ''Apps, Default apps, Telephony''.

== OS settings for iOS ==
; Notifications : The appearance of notifications can be controlled in iOS ''Settings, myApps''.

== OS settings for macOS ==

; Notifications : The appearance of notifications can be controlled in macOS ''Preferences, Notifications, myApps''.

=Troubleshooting=

myApps platform services can write various traces for debugging. Trace can be turned on and off selectively in the [[#Advanced settings|Advanced settings]].

The following trace flags can be set:

(''Recommended trace options are: '''App, Browser, ICE, TURN, Signaling and Audio'''. Please do not activate other flags unless innovaphone support says otherwise'')

{|
!style="text-align: left; font-weight: bold" | Abbreviation

!style="text-align: left; font-weight: bold" |code

!style="text-align: left; font-weight: bold" | description

|-
| App||0x000000001|| logs from the App Service itself
|-
| DNS||0x000000008|| logs DNS requests and results
|-
| HTTP client||0x000000080|| http client logs
|-
| TLS||0x000000400|| TLS logs
|-
| TCP||0x000000800|| TCP logs
|-
| LDS||0x000001000|| local domain sockets
|-
| WebSocket client||0x000004000|| logs outgoing websocket connections
|-
| App WebSocket||0x000008000|| logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
|-
| UDP||0x000200000|| UDP logs
|-
| DTLS||0x000400000|| logs DTLS handshake and messages
|-
| Media||0x000800000|| logs media events
|-
| Media channel||0x001000000|| logs RTP/SCTP media connections
|-
| ICE||0x002000000|| logs ICE messages between peers
|-
| TURN||0x004000000|| logs TURN messages between peers
|-
| AppSharing||0x008000000|| logs AppSharing connection
|-
| Audio||0x010000000|| logs Audio connection and headset events
|-
| Video||0x020000000|| logs video connection and webcam events
|-
| Browser||0x040000000|| logs Chromium events
|-
| AppProxy||0x080000000|| logs requests which are proxied between the local webserver and the remote server
|-
| Webserver ||0x200000000|| enables webserver specific logs
|-
| Browser Console ||0x400000000|| logs browser console events
|-
| Signaling||0x800000000|| enables logs in the signaling module for debugging calls
|}
''code'' can be or'ed and used as value for the ''Log flags'' field in [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps/Client Settings]].

; Windows :On Windows, traces are written to the <code>C:\Users\[UserName]\AppData\Local\innovaphone\myApps</code> directory. If you start myApps with --log-size as parameter, you can define the maximum size of a log file (e.g. --log-size=100000000 would be 100MB for each file)

:* myApps-''date-time''.txt : main log file for the platform services

:* myAppsOutlookSearch-''date-time''.txt : log file for the Outlook phone book access

:* myAppsHookController-''date-time''.txt : log file for the hot-key interceptor (see [[#Hot keys|Hot keys]])

; :myApps update installation traces are written to the <code>%windir%\temp\</code> directory.
:* myAppsInstall.txt: MSI installation file

; :myApps update service traces are written to the <code>%ALLUSERSPROFILE%\innovaphone\myAppsUpdateService</code> directory.
:* myAppsUpdateService-''date-time''.txt: myApps update service traces

;Android : traces can be sent by e-mail.

: also, an Android device might also be connected to a PC via an USB cable to get the traces. The files can be found in <code>Android/data/com.innovaphone.clientandroid/files</code>

; iOS : traces can be sent by e-mail.

; macOS : traces can be sent by e-mail.

: also, the files can be found in <code>~/Library/Containers/com.innovaphone.client-ios/Data/Documents/</code>. Press ''Alt+N'' followed by space to get tilde ''~''.

= Known Problems =
[[:Category:Problem myApps platform services|Known Problems]]

= Related Articles =
* [[{{NAMESPACE}}:Concept_myApps]]
* [[{{NAMESPACE}}:Concept_myApps_Redundancy|Reference14r2:Concept_myApps_Redundancy]]
* [[{{NAMESPACE}}:Concept_myApps_Office_Integration|Reference14r2:Concept_myApps_Office_Integration]]
* [[{{NAMESPACE}}:Concept_myAPPs_Search_in_local-Outlook_Contacts|Reference14r2:Concept_myAPPs_Search_in_local-Outlook_Contacts]]
* [[{{NAMESPACE}}:Call_Detail_Record_CDR_PBX|Reference14r2:Call_Detail_Record_CDR_PBX]]
* [[{{NAMESPACE}}:Concept Push Notifications for myPBX iOS and Android|Reference14r2:Concept Push Notifications for myPBX iOS and Android]]
* [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]]
* [[{{NAMESPACE}}:PBX/Config/myApps]]

[[Category:Concept myApps platform services]]

Main Page

2026-02-24T09:53:01Z

Tfu: /* Latest News */

__NOTOC__

<div style="margin:0px; margin-right:10px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0em 1em;">
== Remote Support ==
[[Image:RemoteControl-click.png|left|60px|RemoteControl.png/|Download Remote Control|link=https://store.innovaphone.com/alpha/download/software/remotecontrolwindowsportable/16r1/remoteControl.exe]]
innovaphone only carries out scheduled remote maintenance via our ticket system by prior consultation. 
As Remote Support Tool, we use our own product Remote Control ([https://www.innovaphone.com/en/all-apps/apps-to-work-with/remote-control-app.html more info]).

You can '''[https://store.innovaphone.com/alpha/download/software/remotecontrolwindowsportable/16r1/remoteControl.exe download]''' the Remote Control client already or use the support link received from our support team. 
After installing and opening the client you can '''pass the shown ID''' or '''use the received link''' to request the support session.

== Searching ==
Searching in wiki works, but is sometimes cumbersome. However, you can have Google do the job for you. Try [https://www.google.de/search?q=site%3Ainnovaphone.com+xml+documentation <code>site:innovaphone.com your search terms</code>] to search the innovaphone sites for matches!

If you still don't find what you are looking for, [mailto:presales@innovaphone.com drop us a message]
</div>


<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">



== Latest News ==

[[User:Tfu|Tfu]] 10:48, 24 February 2026 (CET)
[[Support:WinPDM Software 3130114 (4.2.1) released| WinPDM Software 3130113 (4.2.1)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msc|Msc]] ([[User talk:Msc|talk]]) 15:05, 2 February 2026 (CET) [[Support:Firmware_V16r1_product/16r1/firmware_1610613_(beta5)_available | Version 16r1 Beta 5]] is now available from the [http://store.innovaphone.com/beta/download.htm Beta Store].

[[User:Ndiehl|Ndiehl]] ([[User talk:Ndiehl|talk]]) 13:47, 10 February 2026 (CET) [[Support:Firmware V15r1 product/15r1/firmware 1510665 (sr 10) available | Version 15r1 Service Release 10]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Ndiehl|Ndiehl]] ([[User talk:Ndiehl|talk]]) 13:47, 10 February 2026 (CET) [[Support:Firmware V14r2 product/14r2/firmware 1420581 (sr 18) available | Version 14r2 Service Release 18]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Ndiehl|Ndiehl]] ([[User talk:Ndiehl|talk]]) 13:47, 10 February 2026 (CET) [[Support:Firmware V13r3 product/13r3/firmware 138045 (sr 35) available | Version 13r3 Service Release 35]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Tfu|Tfu]] ([[User talk:Tfu&action=edit&redlink=1|talk]]) 15:28, 13 March 2025 (CEST)
[[Support:Wireless Handset Firmware IP73 1012 (6.1.13) released| Wireless Handset Firmware IP73 1012 (6.1.13) released]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msu|Msu]] ([[User talk:Msu&action=edit&redlink=1|talk]]) 15:54, 18 February 2025 (CEST)
[[Support:Wireless Handset Firmware IP64 10317 (4.3.2)/IP65 10122 (4.3.2) released| Wireless Handset Firmware IP64 10317 (4.3.2)/IP65 10122 (4.3.2)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msu|Msu]] ([[User talk:Msu&action=edit&redlink=1|talk]]) 15:54, 18 February 2025 (CEST)
[[Support:Wireless Handset Firmware D83 10002 (2.0.5) released| Wireless Handset Firmware D83 10002 (2.0.5)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 15:38, 6 February 2023 (CET)
[[Support:Wireless Handset Firmware IP62 3040621 (6.2.7) released| Wireless Handset Firmware IP62 3040621 (6.2.7)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 12:46, 16 June 2021 (CEST))
[[Support:TAPI Service Provider 8188 (hotfix21) available|TAPI Service Provider 8188 (hotfix21)]] is now available from [https://store.innovaphone.com/release/download.htm the Software download area].

[[User:Afi|Afi]] 18:21, 12 October 2020 (CEST)
[[Support:Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8) released| Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 21:30, 27 March 2020 (CET)
[[Support:Wireless Handset Firmware and Management Software product/9.00/wireless 100037 (hotfix19) available| Wireless Package hotfix 19]] is now available from the [http://download.innovaphone.com/ice/9.00#wireless V9 download area].

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">

== New Articles ==

{{Special:Newestpages/all/20}}
</div>

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em; font-size:1">
== More innovaphone Ressources ==
* [http://www.innovaphone.com Home Page]
* [http://download.innovaphone.com Download Site ]
* [http://my.innovaphone.com my.innovaphone ]
* [http://mantis.innovaphone.com/ Ticketing System ]
</div>

User:Tfu

2026-02-24T09:52:19Z

Tfu: Blanked the page

Main Page

2026-02-24T09:52:01Z

Tfu: /* Latest News */

__NOTOC__

<div style="margin:0px; margin-right:10px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0em 1em;">
== Remote Support ==
[[Image:RemoteControl-click.png|left|60px|RemoteControl.png/|Download Remote Control|link=https://store.innovaphone.com/alpha/download/software/remotecontrolwindowsportable/16r1/remoteControl.exe]]
innovaphone only carries out scheduled remote maintenance via our ticket system by prior consultation. 
As Remote Support Tool, we use our own product Remote Control ([https://www.innovaphone.com/en/all-apps/apps-to-work-with/remote-control-app.html more info]).

You can '''[https://store.innovaphone.com/alpha/download/software/remotecontrolwindowsportable/16r1/remoteControl.exe download]''' the Remote Control client already or use the support link received from our support team. 
After installing and opening the client you can '''pass the shown ID''' or '''use the received link''' to request the support session.

== Searching ==
Searching in wiki works, but is sometimes cumbersome. However, you can have Google do the job for you. Try [https://www.google.de/search?q=site%3Ainnovaphone.com+xml+documentation <code>site:innovaphone.com your search terms</code>] to search the innovaphone sites for matches!

If you still don't find what you are looking for, [mailto:presales@innovaphone.com drop us a message]
</div>


<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">



== Latest News ==

[[User:Tfu|Tfu]] 10:48, 24 February 2026 (CET)
[[Support:WinPDM Software 3130114 (4.2.1) released| WinPDM Software 3130113 (4.1.8)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msc|Msc]] ([[User talk:Msc|talk]]) 15:05, 2 February 2026 (CET) [[Support:Firmware_V16r1_product/16r1/firmware_1610613_(beta5)_available | Version 16r1 Beta 5]] is now available from the [http://store.innovaphone.com/beta/download.htm Beta Store].

[[User:Ndiehl|Ndiehl]] ([[User talk:Ndiehl|talk]]) 13:47, 10 February 2026 (CET) [[Support:Firmware V15r1 product/15r1/firmware 1510665 (sr 10) available | Version 15r1 Service Release 10]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Ndiehl|Ndiehl]] ([[User talk:Ndiehl|talk]]) 13:47, 10 February 2026 (CET) [[Support:Firmware V14r2 product/14r2/firmware 1420581 (sr 18) available | Version 14r2 Service Release 18]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Ndiehl|Ndiehl]] ([[User talk:Ndiehl|talk]]) 13:47, 10 February 2026 (CET) [[Support:Firmware V13r3 product/13r3/firmware 138045 (sr 35) available | Version 13r3 Service Release 35]] is now available from the [http://store.innovaphone.com/release/download.htm download page].

[[User:Tfu|Tfu]] ([[User talk:Tfu&action=edit&redlink=1|talk]]) 15:28, 13 March 2025 (CEST)
[[Support:Wireless Handset Firmware IP73 1012 (6.1.13) released| Wireless Handset Firmware IP73 1012 (6.1.13) released]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msu|Msu]] ([[User talk:Msu&action=edit&redlink=1|talk]]) 15:54, 18 February 2025 (CEST)
[[Support:Wireless Handset Firmware IP64 10317 (4.3.2)/IP65 10122 (4.3.2) released| Wireless Handset Firmware IP64 10317 (4.3.2)/IP65 10122 (4.3.2)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Msu|Msu]] ([[User talk:Msu&action=edit&redlink=1|talk]]) 15:54, 18 February 2025 (CEST)
[[Support:Wireless Handset Firmware D83 10002 (2.0.5) released| Wireless Handset Firmware D83 10002 (2.0.5)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 15:38, 6 February 2023 (CET)
[[Support:Wireless Handset Firmware IP62 3040621 (6.2.7) released| Wireless Handset Firmware IP62 3040621 (6.2.7)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 12:46, 16 June 2021 (CEST))
[[Support:TAPI Service Provider 8188 (hotfix21) available|TAPI Service Provider 8188 (hotfix21)]] is now available from [https://store.innovaphone.com/release/download.htm the Software download area].

[[User:Afi|Afi]] 18:21, 12 October 2020 (CEST)
[[Support:Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8) released| Wireless Handset Firmware IP61 3022811 (4.7.8)/IP63 3022912 (4.7.8)]] is now available from the [https://store.innovaphone.com/release/download.htm App store].

[[User:Afi|Afi]] 21:30, 27 March 2020 (CET)
[[Support:Wireless Handset Firmware and Management Software product/9.00/wireless 100037 (hotfix19) available| Wireless Package hotfix 19]] is now available from the [http://download.innovaphone.com/ice/9.00#wireless V9 download area].

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em;">

== New Articles ==

{{Special:Newestpages/all/20}}
</div>

<div style="margin:0px; margin-right:10px; margin-top:15px; border:1px solid #58C4C3; background-color:#F4F4F4; padding:0em 1em 0.5em 1em; font-size:1">
== More innovaphone Ressources ==
* [http://www.innovaphone.com Home Page]
* [http://download.innovaphone.com Download Site ]
* [http://my.innovaphone.com my.innovaphone ]
* [http://mantis.innovaphone.com/ Ticketing System ]
</div>

Reference16r1:Concept App Service Connector for Microsoft 365

2026-02-13T11:22:31Z

Tfu: /* Correctness of notification URL */

{{FIXME|reason=This article is still work in progress}}

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 16r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).
It is also possible to search for your own contacts.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V16r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure_Calendar_Presence_Sync_by_Connector_for_Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PXB presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

=== Contact Search ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 16r1 the Connector for Microsoft 365 will offer a possibility to search for your own contacts (Teams, Exchange online) via the Graph API.

When the configuration of the connector for Microsoft 365 Contact Search is complete, the app connects to Microsoft to receive a token with the contact search app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, the user can search with the Phone App, for example (a myApps search provider will be provided for all apps looking using search providers looking up contacts). The search string is made available to the Connector for Microsoft 365 via the microsoft365-api. The results are sent to the consumer, e.g. the Phone App and presented there. 
 
A user subscription is started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 

* User subscriptions are renewed every 60 minutes.
* License Check is made every hour.

'''Be aware:''' Since the Connector for Microsoft 365 is an app in the Scope of myApps App Platform, IP Phones and other services not using Apps cannot benefit from this search service.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* Database
* HTTP client
* TLS
* TCP
* App WebSocket
* Config
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 5 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto16r1:Configure User Presence Sync by Connector for Microsoft365#Create_an_App_for_syncing_Teams_to_PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Contact Search by Connector for Microsoft365]]

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

Reference15r1:Concept App Service Connector for Microsoft 365

2026-02-13T11:21:42Z

Tfu: /* Activation of "Public client flow" for the registered app in Azure Portal */

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 15r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V15r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure_Calendar_Presence_Sync_by_Connector_for_Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* Database
* HTTP client
* TLS
* TCP
* App WebSocket
* Config
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 5 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365#Create_an_App_for_syncing_Teams_to_PBX|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto15r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto15r1:Configure Calendar Presence Sync by Connector for Microsoft365]]

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

Reference15r1:Concept App Service Connector for Microsoft 365

2026-02-13T11:20:32Z

Tfu: /* Correctness of notification URL */

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 15r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V15r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure_Calendar_Presence_Sync_by_Connector_for_Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PBX presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* Database
* HTTP client
* TLS
* TCP
* App WebSocket
* Config
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 5 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

=== Activation of "Public client flow" for the registered app in Azure Portal===
If the subscription is not working at all, please make sure "Public client flow" is activated for the registered app in the Azure portal (as described in our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365|HowTo article]]). 
 
The App Service trace will contain the following message if this is not the case: 
<code>AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'.</code>

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto15r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto15r1:Configure Calendar Presence Sync by Connector for Microsoft365]]

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

Reference16r1:Concept App Service Conference Transcriptions

2026-01-30T11:40:11Z

Tfu:

{{FIXME|reason=This article is still work in progress}}
[[Category:Concept|Apps]]
[[Category:Concept App Service Conference Transcriptions]]
== Applies To ==

* innovaphone Conference Transciptions from version 16r1

== Overview ==
[[File:Reference16r1 Concept App Service Conference Transcriptions Softphone App.png|thumb|309x309px|After the meeting ended, find the created summary|reference16r1_concept_app_service_conference_transcriptions_softphone_app.png/]]
The main goal of the Conference Transcriptions Service is to create video‑conference meeting summaries, which can be accessed in the Phone Apps.

To achieve this:
# Users can start a transcription of the conference audio by clicking the '''“Transcribe Conference”''' button in the Phone Apps.
#* This action makes the Conference Transcriptions service connect to the conference room.
#* It records the audio and creates audio files of approximately one minute in length.
#* It forwards these small audio files via the com.innovaphone.transcriptions API, offered by the Transcriptions Service ([[Reference16r1:Concept_App_Service_Transcriptions]])
#* It receives the transcripts of these small files and stores them in the service database.
# If the user stops the transcription by clicking on the "'''Transcribe Conference'''" Button again
#* The Conference Transcriptions Service gathers the transcribed text from the database
#* It retrieves the prompt configured in the settings plugin [[Reference16r1:Apps/PbxManager/App myApps ConferenceTranscriptions]]
#* It sends the transcript together with the prompt to the Assistant App Service via the com.innovaphone.assistant API
#* It receives the meeting summary and stores that summary in the database of the service
# Users may start and stop transcriptions multiple times during a meeting. As long as users remain in the room, the service recognizes that the meeting is still the same for that room.
# After the meeting, users can find the AI‑generated meeting summary in the call list of their Phone Apps by clicking on the '''“i”''' button. 

== Licensing ==

In order to use the service you will need the newly introduced '''UCC license'''
== Installation ==
Go to the '''Settings App''' (fomerly known as 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 '''"Conference Transcriptions"''' and click on it.
* Select the proper firmware version, for example '''"Version 16r1"''' 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 reopen the '''Settings App''' (PBX manager) in order to refresh the list of the available colored AP plugin icons.
* Open the '''"AP Conference Transcriptions"''' Plugin by clicking on it and click on '''" + Add an App"''' and then on the '''"Conference Transcriptions API"''' button.
* Enter a '''"Name"''' ''(used as display name / all character allowed)'' and the '''"SIP"''' ''(no space, no capital letters)''. ''e.g : Name: Conference Transcriptions API, SIP: conference-transcriptions-api''
* Choose a LLM (model) from the dropdown
* Tick the appropriate template to distribute the App (the app is needed at every user object from any user who wants to use the assistant API)
* Click OK to save the settings. A green check mark will be shown to confirm that the configuration is good.

In order to make the service work properly, two supplemental services must be installed:

* the myApps Assistant which will summarize the transcript [[Reference16r1:Concept App Service myApps Assistant]]
* the Transcriptions Service which establishes a connection to a remote transcription server [[Reference16r1:Concept_App_Service_Transcriptions]]

== Conference Transcriptions - App Service ==
The App Service performs tasks in the following areas:
* Transcribes the audio of a conference room
* Stores the transcript in the database
* Creates and stores the summary of the transcript in the database

It can be configured in the '''Settings App''' (formerly known as PBXManager App) [[Reference16r1:Apps/PbxManager/App_myApps_ConferenceTranscriptions]]

== Summary prompts ==
You may configure the prompt freely. Here are some propositions you may copy/paste into the corresponding field of the settings plugin:

<pre>
You will receive a meeting transcript. Your task is to turn it into a structured meeting summary.

The entire summary — including section headers, bullet points, and all text — must be written in the same language as the transcript. Detect the language automatically. If the transcript is in german write the summary in german. If the transcript is in english, write the summary in english...

Follow these instructions exactly:

1. Read the transcript carefully.
2. Extract only the information that is clearly stated. Do not guess or invent anything.
3. Create the final summary using the exact structure below, but translate the section headers into the language of the transcript.

OUTPUT FORMAT (translate the headers into the transcript language, but keep the structure):

 
A short title describing the meeting.
 
 

Summary: 
 
(2–4 sentences describing the purpose of the meeting and the main outcomes.)
 
 
Decisions:
 
 
<ul>
<li>Decision 1</li>
<li>Decision 2</li>

</ul>
 
 
Key Points:
 
 
<ul>
<li>Bullet point 1</li>
<li>Bullet point 2</li>
<li>Bullet point 3</li>


</ul>

 
 
Tasks:
 
 
<ul>
<li>Person — Task — Deadline (or “No deadline mentioned”)</li>

</ul>
 
 
Open Questions:
 
 
<ul>
<li>Question 1</li>
<li>Question 2</li>

</ul>

RULES:

Use HTML lists (<ul><li></li></ul>) only for bullet points.
Do not add information that is not in the transcript.
Keep the writing clear and concise.
Keep the structure exactly as shown, but translate the headers.
Do not wrap the whole answer in a single HTML tag.

TRANSCRIPT:
</pre>

== Troubleshooting ==

For troubleshooting the Conference Transcirptions App Service, you need activate the traceflags ''App'', ''Database and'' ''HTTP-Client'' in your App instance.

== Related Articles ==
* [https://sdk.innovaphone.com/16r1/web1/com.innovaphone.conference-transcriptions/com.innovaphone.conference-transcriptions.htm SDK Documentation - Conference Transcriptions API]
* [[Reference16r1:Concept App Service myApps Assistant]]
* [[Reference16r1:Apps/PbxManager/App myApps ConferenceTranscriptions]]

Reference16r1:Concept App Service Transcriptions

2026-01-30T11:28:24Z

Tfu:

{{FIXME|reason=This article is still work in progress}}
[[Category:Concept|Apps]]
[[Category:Concept App Service Transcriptions]]
== Applies To ==

* innovaphone Transcription Service from version 16r1

== Overview ==

The Transcription Service converts audio input into text using automatic speech recognition (ASR) models. In terms of its concept, it is located between the client services that generate or capture audio data and the transcription backend that performs the actual speech-to-text processing.
These transcription backends can run either as a locally hosted AI service within the same environment or as an external service accessed through a compatible API.

The Transcription Service itself is responsible for managing sessions, handling parallel requests, and coordinating the data flow between clients and the selected backend. The external ASR model performs the actual transcription.

The service is designed to work with OpenAI-compatible APIs, enabling clients to freely choose their preferred backend provider.

== Licensing ==

In order to use the Transcriptions Service including the Transcriptions App the newly introduced UCC license is necessary.
== Installation ==
Go to the '''Settings App''' (formerly known as 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 '''"Transcriptions"''' and click on it
* Select the proper firmware version, for example '''"Version 16r1"''' 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 reopen the '''Settings App''' (PBX manager) in order to refresh the list of the available colored AP plugin icons.
* Open the '''"AP transcriptions"''' plugin by clicking on it and select '''" + Add an App"''' afterwards. Then click on the '''"Transcriptions API"''' button.
* Enter a '''"Name"''' ''(used as display name / all character allowed)'' and the '''"SIP"''' ''(no space, no capital letters)''. ''e.g : Name: Transcriptions API, SIP: transcriptions-api''
* Enter the '''Remote service Url''' (Destination URL of the service provider)
* Enter the '''API Key''' (provided by the service provider)
* Enter the '''model name''' (must be supported by the configured provider)
* Tick the appropriate template to distribute the App (the app is needed at every user object from any user who wants to use the assistant API)
* Click OK to save the settings. A green check mark will be shown to confirm that the configuration is good.

== How it works ==

*A client service that requires transcription initiates the process by sending a transcription request via a WebSocket connection.
* The transcription service creates a session, assigns a transcription ID, and returns a dedicated HTTP endpoint to the client.
* The client uploads the audio data to the transcription service using HTTP connections, targeting the provided endpoint.
* The transcription service forwards the received audio data to the configured ASR backend (for example, a Whisper-compatible API) over HTTP.
* The ASR backend performs the transcription and returns the result to the transcription service, which then forwards the outcome back to the client.

== Transcriptions Flow Overview ==
[[File:Screenshot 2026-01-29 161703.png|center|thumb|964x964px|screenshot_2026-01-29_161703.png/|screenshot_2026-01-29_161703.png/]]

== Transcriptions - App Service ==
The App Service implements an API to use a remote transcription provider (e.g. whisper).

It can be configured in the '''Settings App''' (PBX Manager App) [[Reference16r1:Apps/PbxManager/App_myApps_Transcriptions]]

* The '''Remote Service URL''' defines the target URL of the remote transcription provider.

* The '''API Key''' is required to access the selected backend and to authenticate with the remote provider.

* The '''Model''' defines which model the backend should use for transcription.

These parameters are stored as a configuration and are forwarded to the backend. At present, these values must be entered manually in the Settings plugin.

The service does not validate or confirm these values. It assumes that all the given values are correct and only uses them for communication with the backend. Since the users are able to chose their own providers, they are also responsible for selecting a fitting model and understanding the limitations of the models (such as supported Audio formats, size limits, etc.).

Furthermore, applications that require transcription functionality must explicitly consume the Transcription Service API and demonstrate this functionality in their own user interface, such as applied in the Conference Transcriptions app.

== Transcriptions App ==
The service also provides a user interface where audio files can be uploaded and transcribed directly.

Once the transcription is complete, a simple summary can be generated and exported as a PDF (basic version).

Audio files can be selected using the Choose audio file button. The transcription process and its results are displayed on the same screen.

Neither the uploaded audio data nor the generated transcription text is stored by the service.[[File:ReferenceConceptTranscriptionsAppServiceTranscriptionsApp.png|thumb|referenceconcepttranscriptionsappservicetranscriptionsapp.png/|referenceconcepttranscriptionsappservicetranscriptionsapp.png/]]

== Troubleshooting ==

For troubleshooting the Transcriptions App Service, you need to activate the traceflags ''App'', ''Database and'' ''HTTP-Client'' in your Transcription App instance.

== Limitations ==

* Limitations such as maximum audio size, supported languages, or handling multilingual audio mainly depend on the selected model and provider and may vary based on the user’s provider choice.
* Differences in response structure can also occur. These responses are forwarded unchanged, since they may contain important metadata for the client, such as timestamps.
* The service does not validate the selected model. Choosing a suitable model is therefore the user’s responsibility.
* Transcriptions may contain misheard words or spelling inaccuracies, especially in cases of background noise or strong accents.

== Related Articles ==
* [https://sdk.innovaphone.com/16r1/web1/com.innovaphone.transcriptions/com.innovaphone.transcriptions.htm SDK Documentation - Transcriptions API]
* [[Reference16r1:Apps/PbxManager/App_myApps_Transcriptions]]

Reference16r1:Concept App Service Transcriptions

2026-01-30T11:26:35Z

Tfu:

{{FIXME|reason=This article is still work in progress}}
[[Category:Concept|Apps]]
[[Category:Concept App Service Transcriptions]]
== Applies To ==

* innovaphone from version 16r1

== Overview ==

The Transcription Service converts audio input into text using automatic speech recognition (ASR) models. In terms of its concept, it is located between the client services that generate or capture audio data and the transcription backend that performs the actual speech-to-text processing.
These transcription backends can run either as a locally hosted AI service within the same environment or as an external service accessed through a compatible API.

The Transcription Service itself is responsible for managing sessions, handling parallel requests, and coordinating the data flow between clients and the selected backend. The external ASR model performs the actual transcription.

The service is designed to work with OpenAI-compatible APIs, enabling clients to freely choose their preferred backend provider.

== Licensing ==

In order to use the Transcriptions Service including the Transcriptions App the newly introduced UCC license is necessary.
== Installation ==
Go to the '''Settings App''' (formerly known as 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 '''"Transcriptions"''' and click on it
* Select the proper firmware version, for example '''"Version 16r1"''' 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 reopen the '''Settings App''' (PBX manager) in order to refresh the list of the available colored AP plugin icons.
* Open the '''"AP transcriptions"''' plugin by clicking on it and select '''" + Add an App"''' afterwards. Then click on the '''"Transcriptions API"''' button.
* Enter a '''"Name"''' ''(used as display name / all character allowed)'' and the '''"SIP"''' ''(no space, no capital letters)''. ''e.g : Name: Transcriptions API, SIP: transcriptions-api''
* Enter the '''Remote service Url''' (Destination URL of the service provider)
* Enter the '''API Key''' (provided by the service provider)
* Enter the '''model name''' (must be supported by the configured provider)
* Tick the appropriate template to distribute the App (the app is needed at every user object from any user who wants to use the assistant API)
* Click OK to save the settings. A green check mark will be shown to confirm that the configuration is good.

== How it works ==

*A client service that requires transcription initiates the process by sending a transcription request via a WebSocket connection.
* The transcription service creates a session, assigns a transcription ID, and returns a dedicated HTTP endpoint to the client.
* The client uploads the audio data to the transcription service using HTTP connections, targeting the provided endpoint.
* The transcription service forwards the received audio data to the configured ASR backend (for example, a Whisper-compatible API) over HTTP.
* The ASR backend performs the transcription and returns the result to the transcription service, which then forwards the outcome back to the client.

== Transcriptions Flow Overview ==
[[File:Screenshot 2026-01-29 161703.png|center|thumb|964x964px|/Screenshot_2026-01-29_161703.png|screenshot_2026-01-29_161703.png/]]

== Transcriptions - App Service ==
The App Service implements an API to use a remote transcription provider (e.g. whisper).

It can be configured in the '''Settings App''' (PBX Manager App) [[Reference16r1:Apps/PbxManager/App_myApps_Transcriptions]]

* The '''Remote Service URL''' defines the target URL of the remote transcription provider.

* The '''API Key''' is required to access the selected backend and to authenticate with the remote provider.

* The '''Model''' defines which model the backend should use for transcription.

These parameters are stored as a configuration and are forwarded to the backend. At present, these values must be entered manually in the Settings plugin.

The service does not validate or confirm these values. It assumes that all the given values are correct and only uses them for communication with the backend. Since the users are able to chose their own providers, they are also responsible for selecting a fitting model and understanding the limitations of the models (such as supported Audio formats, size limits, etc.).

Furthermore, applications that require transcription functionality must explicitly consume the Transcription Service API and demonstrate this functionality in their own user interface, such as applied in the Conference Transcriptions app.

== Transcriptions App ==
The service also provides a user interface where audio files can be uploaded and transcribed directly.

Once the transcription is complete, a simple summary can be generated and exported as a PDF (basic version).

Audio files can be selected using the Choose audio file button. The transcription process and its results are displayed on the same screen.

Neither the uploaded audio data nor the generated transcription text is stored by the service.[[File:ReferenceConceptTranscriptionsAppServiceTranscriptionsApp.png|thumb|/ReferenceConceptTranscriptionsAppServiceTranscriptionsApp.png|referenceconcepttranscriptionsappservicetranscriptionsapp.png/]]

== Troubleshooting ==

For troubleshooting the Transcriptions App Service, you need to activate the traceflags ''App'', ''Database and'' ''HTTP-Client'' in your Transcription App instance.

== Limitations ==

* Limitations such as maximum audio size, supported languages, or handling multilingual audio mainly depend on the selected model and provider and may vary based on the user’s provider choice.
* Differences in response structure can also occur. These responses are forwarded unchanged, since they may contain important metadata for the client, such as timestamps.
* The service does not validate the selected model. Choosing a suitable model is therefore the user’s responsibility.
* Transcriptions may contain misheard words or spelling inaccuracies, especially in cases of background noise or strong accents.

== Related Articles ==
* [https://sdk.innovaphone.com/16r1/web1/com.innovaphone.transcriptions/com.innovaphone.transcriptions.htm SDK Documentation - Transcriptions API]
* [[Reference16r1:Apps/PbxManager/App_myApps_Transcriptions]]

Reference16r1:Concept App Service Transcriptions

2026-01-30T10:38:47Z

Tfu: /* Overview */

{{FIXME|reason=This article is still work in progress}}
[[Category:Concept|Apps]]
[[Category:Concept App Service Transcriptions]]
== Applies To ==

* innovaphone from version 16r1

== Overview ==

The Transcription Service converts audio input into text using automatic speech recognition (ASR) models. In terms of its concept, it is located between the client services that generate or capture audio data and the transcription backends that perform the actual speech-to-text processing.
These transcription backends can run either as a locally hosted AI service within the same environment or as an external service accessed through a compatible API.

The Transcription Service itself is responsible for managing sessions, handling parallel requests, and coordinating the data flow between clients and the selected backend. The external ASR model performs the actual transcription.

The service is designed to work with OpenAI-compatible APIs, enabling clients to freely choose their preferred backend provider.

== Licensing ==

In order to use the Transcriptions Service including the Transcriptions App the newly introduced UCC license is necessary.
== Installation ==
Go to the '''Settings App''' (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 '''"Transcriptions"''' and click on it
* Select the proper firmware version, for example '''"Version 16r1"''' 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 reopen the '''Settings App''' (PBX manager) again in order to refresh the list of the available colored AP plugin
* Click on the '''"AP transcriptions"''' and click on '''" + Add an App"''' and then on the '''"Transcriptions API"''' button.
* 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: Transcriptions API, SIP: transcriptions-api''
* Choose a LLM (model) from the dropdown
* Tick the appropriate template to distribute the App (the app is needed at every user object from any user who wants to use the assistant API)
* Click OK to save the settings and a green check mark will be shown to inform you that the configuration is good

== How it works ==

*A client service that requires transcription initiates the process by sending a transcription request via a WebSocket connection.
* The transcription service creates a session, assigns a transcription Id, and returns a dedicated HTTP endpoint to the client.
* The client uploads the audio data to the transcription service using HTTP connections, targeting the provided endpoint.
* The transcription service forwards the received audio data to the configured ASR backend (for example, a Whisper-compatible API) over HTTP.
* The ASR backend performs the transcription and returns the result to the transcription service, which then forwards the outcome back to the client.

== Transcriptions Flow Overview ==
[[File:Screenshot 2026-01-29 161703.png|center|thumb|964x964px|/Screenshot_2026-01-29_161703.png|/Screenshot_2026-01-29_161703.png]]

== Transcriptions - App Service ==
The App Service implements the API to a remote transcription server (e.g. whisper)

It can be configured in the '''Settings App''' (PBX Manager App) [[Reference16r1:Apps/PbxManager/App_myApps_Transcriptions]]

* The Remote service Url defines where requests are sent.

* API key required to access the selected backend and to authenticates with the remote provider.

* Model value defines which model the backend should use for transcription.

These parameters are stored as a configuration and are forwarded to the backend. At present, these values must be entered manually in the Settings plugin.

The service does not validate or confirm these values. It assumes that all the given values are correct and only uses them for communication with the backend. Since the users are able to chose their own providers, they are also responsible for selecting a fitting model and understanding the limitations of the models (such as supported Audio formats, size limits etc.)

Furthermore, Applications that require transcription functionality must explicitly consume the Transcription Service API and demonstrate this functionality in their own user interface, such as in Conference Transcriptions.

== Transcriptions App ==
The service also provides a user interface where audio files can be uploaded and transcribed directly.

Once the transcription is complete, a simple summary can be generated and exported as a PDF (basic version).

Audio files can be selected using the Choose audio file button. The transcription process and its results are displayed on the same screen.

Neither the uploaded audio data nor the generated transcription text is stored by the service.[[File:ReferenceConceptTranscriptionsAppServiceTranscriptionsApp.png|thumb|/ReferenceConceptTranscriptionsAppServiceTranscriptionsApp.png|/ReferenceConceptTranscriptionsAppServiceTranscriptionsApp.png]]

== Troubleshooting ==

To troubleshoot this App Service, you need the traceflags ''App'', ''Database'', ''HTTP-Client'' in your App instance.

== Limitations ==

* Limitations such as maximum audio size, supported languages, or handling multilingual audio mainly depend on the selected model and provider, and may vary based on the user’s provider choice.
* Differences in response structure can also occur. These responses are forwarded unchanged, since they may contain important metadata for the client, such as timestamps.
* The service does not validate the selected model. Choosing a suitable model is therefore the user’s responsibility.
* Transcriptions may contain misheard words or spelling inaccuracies, especially in cases of background noise or strong accents.

== Related Articles ==
* [https://sdk.innovaphone.com/16r1/web1/com.innovaphone.transcriptions/com.innovaphone.transcriptions.htm SDK Documentation - Transcriptions API]
* [[Reference16r1:Apps/PbxManager/App_myApps_Transcriptions]]

Howto13r1:Installation Scenarios

2026-01-28T10:33:19Z

Tfu: /* Scenario - proxy-secured internet access */

__toc__


Before starting your Version 13 Installation you have to check the customer network and his requirements first.

You can install a Version 13 setup in different ways, so we will give you an overview and a best practice for your specific case.

==Applies To==
This information applies to

* Firmware Version 13 onwards

== IP/DNS-Installation scenarios ==

=== Decision Matrix ===

On the left side you can choose the needs and conditions of your customer. Then you will see which solutions are possible or recommended.

Some information to understand the conditions in the table:
;Reverse Proxy
:Needed if you want connect with external phones (e.g. Smartphones or HomeOffices) to your internal PBX or Application Platform. The requirements are an official domain and access to the router configuration to configure port forwardings. If you do not have a domain, you have to rent one. If you do not have access to the router, your customer must use a Cloud Solution.
;Local DNS server
:All applications can work with DNS Names. You have to configure some internal subdomains with the private IP addresses of your gateways
:Example PBX: <code>pbx.domanin.tld => 192.168.2.10</code>
:Example Ap Platform: <code>ap.domanin.tld => 192.168.2.11</code>
;External DNS server
:In combination with the reverse proxy you can offer some subdomains from your external domain name with the external IP or the NAT-IP of your Reverse Proxy
:Example PBX: <code>pbx.domanin.tld => 1.2.3.4</code>
:Example Ap Platform: <code>ap.domanin.tld => 1.2.3.4</code>

=== Reverse Proxy is needed ===

Please check on the vertical lines the starting conditions on your customer site. After that you can check on the right columns possible scenarios for your customer.

{| class="wikitable"
|   || style="background-color: #EAECF0;text-align:center"|Cloud || style="background-color:#B3B7FF"|  || colspan="4" style="background-color: #EAECF0;text-align:center"| On Premise
|-
|- style="background-color: #FAEBA3"
! / !!  innovaphone Cloud  !! style="background-color:#B3B7FF"| !!  internal DNS Server  !!  external NAT Hairpinning  !!  new DNS Server with a innovaphone Box  !!  use only IP addresses 
|-
| style="font-weight:bold;background-color: #FAEBA3"| • local DNS server exists || style="color:green;text-align:center;"|✔✔✔ || style="background-color:#B3B7FF"| || style="color:green;text-align:center"|✔✔✔ || style="color:green;text-align:center"|✔ || style="color:green;text-align:center"|✔ || style="color:red;text-align:center;font-weight:bold;"|X
|-
| style="font-weight:bold;background-color: #FAEBA3"| • no local DNS server exists || style="color:green;text-align:center"|✔✔✔ || style="background-color:#B3B7FF"| || style="color:red;text-align:center;font-weight:bold;"|X || style="color:green;text-align:center"|✔ || style="color:green;text-align:center"|✔ || style="color:red;text-align:center;font-weight:bold;"|X
|}

=== Reverse Proxy is not needed ===

Please check on the vertical lines the starting conditions on your customer site. After that you can check on the right columns possible scenarios for your customer.

{| class="wikitable"
|   || style="background-color: #EAECF0;text-align:center"|Cloud || style="background-color:#B3B7FF"|  || colspan="4" style="background-color: #EAECF0;text-align:center"| On Premise
|-
|- style="background-color: #FAEBA3"
! / !!  innovaphone Cloud  !! style="background-color:#B3B7FF"| !!  internal DNS Server  !!  external NAT Hairpinning  !!  new DNS Server with a innovaphone Box  !!  use only IP addresses 
|-
| style="font-weight:bold;background-color: #FAEBA3"| • local DNS server exists || style="color:green;text-align:center;"|✔✔✔ || style="background-color:#B3B7FF"| || style="color:green;text-align:center"|✔✔✔ || style="color:green;text-align:center"|✔ || style="color:green;text-align:center"|✔ || style="color:green;text-align:center"|✔✔
|-
| style="font-weight:bold;background-color: #FAEBA3"| • no local DNS server exists || style="color:green;text-align:center"|✔✔✔ || style="background-color:#B3B7FF"| || style="color:red;text-align:center;font-weight:bold;"|X || style="color:green;text-align:center"|✔ || style="color:green;text-align:center"|✔ || style="color:green;text-align:center"|✔✔
|}

*✔✔✔ means that we recommend it
*✔✔ means that you can do it, and it works fine
*✔ means that you can do it, it works fine but you should do some local network adjustment
*O means that you can do it, but we don't recommended it
*X means that you should not do it, otherwise you may run into problems

We recommend to take a look [[Courseware:IT Advanced - 06 Public Access to PBX Resources (theory) - optional|into our training books]] to decide how to setup the whole network.

=== Scenario - innovaphone Cloud ===
Refer to [[Howto:MyApps Cloud - Installation|respective article]].

=== Scenario - internal DNS Server ===
You can use your existing DNS Server to setup your DNS names to resolv it to the correct internal IP addresses.

Example:
* pbx.example.com => 192.168.2.10
* apps.example.com => 192.168.2.11

=== Scenario - external NAT Hairpinning ===
If you have no internal DNS Server and your NAT router support ''[https://en.wikipedia.org/wiki/Hairpinning Hairpinning]'' you can use external DNS entries with a record to your external IP-Address.

Your internal client should resolve ''pbx.example.com'' to your public IP address of your own router. If you configure needed NAT rules to your internal IP, your router will accept the package from inside and forward it back to the internal IP from your NAT rule.

In this scenario no separate internal dns server are required and your internal client (eg. 192.168.3.5) can talk with your PBX (eg. pbx.example.com -> 1.2.3.4) with a mapping to the internal IP (eg. 192.168.3.10)

The most used NAT Rules are:
// H.323/TLS
[from outside] tcp/1300 => [internal IP of your Reverse Proxy]

// LDAPS
[from outside] tcp/636 => [internal IP of your Reverse Proxy]

// HTTPS
[from outside] tcp/443 => [internal IP of your Reverse Proxy]

// TURN
[from outside] tcp/udp/3478 => [internal IP of your Reverse Proxy]

During the install process you have to set up a temporary internal DNS first and to configure your PC and the innovaphone Gateway to use them, which provides the local addresses. Only during the install you have to distribute the internal DNS by DHCP in your router to the Clients. If everything is finished, you can turn off the local DNS.
If you have no Hardware/Software for a temporary DNS Server you can use a innovaphone Box which is described [[Howto:V13 Installation Scenarios#Scenario - new DNS Server with a innovaphone Box|here]].

If you cannot setup temporary DNS records the installer will automatic activate the [[Reference13r1:PBX/Config/General|Operation without DNS]] mode, to communicate via IP address. You have to deactivate the mode after setup the correct DNS entries.

=== Scenario - new DNS Server with a innovaphone Box ===
If you decided to setup an internal DNS than you can do that as described here:

First choose Manual Installation

[[Image:SetupInternerDNS-Part1.png|setupinternerdns-part1.png/]]

Than enable the DNS Server and create A Records

[[Image:SetupInternerDNS-Part2.png|setupinternerdns-part2.png/]]

Afterwards it looks like that:

[[Image:SetupInternerDNS-Part3.png|setupinternerdns-part3.png/]]

In the next step you should provide the IP of this box as DNS server to all of you phones.
Therefore you could use your own DHCP Server.

Now you can go back to the normal installation process of the box.
Therefore just ....

=== Scenario - use only IP addresses ===
You can use static IP addresses in the installations process. So no DNS is needed.

Example:
*PBX DNS Name => 192.168.2.10
*AP DNS Name => 192.168.2.11

=== Scenario - proxy-secured internet access ===
If Internet access is only possible via a proxy server, a local store can be used for installation.
For details refer to the [[Special:Search/intitle:offline incategory:"Step-by-Step"|offline installation articles]].

== Possible scenarios if port 443 is already in use ==
Sometimes the HTTPS (tcp/443) or HTTP (tcp/80) is already in use by other systems like Webmail or Webserver on the customers side. To use your myApps Clients externally the myApps Client need to connect also via Port 443 to the customer network.

There are some possible solutions to resolve that conflict.

=== Use an innovaphone Cloud Setup ===
If you don't want to or can't change the network on customers side you can use an [https://www.innovaphone.com/en/cloud/rent-buy-or-move-to-the-cloud.html innovaphone Cloud Setup].

=== Separate IP Address for Reverse Proxy ===
The best way is to have more than one public IP-Addresses. In this scenario you use a separate IP-Address for a specific server/service. In this way you can use different IP-Addresses on your Firewall and route the traffic to the different servers/services.

=== Distribute traffic based on hostname ===
If you only have a single IP-Address you have to decide which is the target system for an incoming tcp/443 packet. For this, you can use a system that forwards the request based on the hostname in the GET Request and forward the packet to the correct service.

==== Use existing firewall ====
Most of the Next-Gen firewalls support features like ''Load-Balancer'', ''Reverse Proxy'' or something similar that can do the forwarding.

''Note: Please consult your firewall vendor or system admin if you need help to configure this.''

==== Use innovaphone's Reverse Proxy ====
The Reverse Proxy can do the forwarding to [[Courseware:IT Advanced - 06 Public Access to PBX Resources (theory) - optional#Service Name Definition|configured destination IP-addresses]] too.
With this setup you route or NAT (depending from your Firewall) all incoming Traffic based on tcp/443 to the Reverse Proxy.
The Reverse Proxy distributes it to the appropriate system (eg. for "''webmail.domain.tld''" to the local Exchange IP and traffic for "''apps.domain.tld''" to the innovaphone AP-Platform).

''Note: the reverse proxy can [[Courseware:IT Advanced - 06 Public Access to PBX Resources (theory) - optional#Reverse Proxy and Certificates|handle a single SSL-Certificate]] only. You have to use a wildcard (*.domain.tld) certificate therefore.''

=== Separate WAN Uplink ===
You can book a separate internet connection to get a second public IP-Address and forward the Traffic to your Reverse Proxy.

== Related Articles ==
* [[Reference13r1:Install]]
* [[Howto:Firmware_Upgrade]]

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

Reference16r1:Concept App Service Connector for Microsoft 365

2025-11-05T09:54:23Z

Tfu: /* Technical Overview */

{{FIXME|reason=This article is still work in progress}}

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 16r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).
It is also possible to search for your own contacts.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V16r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure_Calendar_Presence_Sync_by_Connector_for_Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PXB presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

=== Contact Search ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 16r1 the Connector for Microsoft 365 will offer a possibility to search for your own contacts (Teams, Exchange online) via the Graph API.

When the configuration of the connector for Microsoft 365 Contact Search is complete, the app connects to Microsoft to receive a token with the contact search app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, the user can search with the Phone App, for example (a myApps search provider will be provided for all apps looking using search providers looking up contacts). The search string is made available to the Connector for Microsoft 365 via the microsoft365-api. The results are sent to the consumer, e.g. the Phone App and presented there. 
 
A user subscription is started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 

* User subscriptions are renewed every 60 minutes.
* License Check is made every hour.

'''Be aware:''' Since the Connector for Microsoft 365 is an app in the Scope of myApps App Platform, IP Phones and other services not using Apps cannot benefit from this search service.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* Database
* HTTP client
* TLS
* TCP
* App WebSocket
* Config
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 5 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Contact Search by Connector for Microsoft365]]

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

Reference16r1:Concept App Service Connector for Microsoft 365

2025-11-05T09:53:06Z

Tfu: /* Technical Overview */

{{FIXME|reason=This article is still work in progress}}

[[Category:Concept|Apps]]
== Applies To ==

* Connector for Microsoft 365 from Version 16r1

= Overview =

Connector for Microsoft 365 synchronizes Microsoft Teams presences with the innovaphone PBX and back, and optionally additionally Calendar presence from Exchange Online (part of the Microsoft 365 Cloud Services).
It is also possible to search for your own contacts.

== Requirements ==

* innovaphone PBX
* innovaphone Application Platform (minimum version 120004)
* V16r1
* App(Connector for Microsoft 365)
* PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009

== Concept ==

=== User Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure User Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API.
A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.

* User subscriptions are renewed every 60 minutes.
* Presence subscriptions are renewed every 10 minutes.
* License Check is made periodically.

The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days.
The lifetimes are described [https://learn.microsoft.com/en-us/graph/api/presence-setuserpreferredpresence?view=graph-rest-1.0&tabs=http here]

'''Please be aware:''' The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes.
After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed.
The subscription will then be renewed in the above-mentioned time interval to receive further live updates.

===== User Matching =====
You now can choose the fields used for user matching on either side from the following options:
* PBX
** CN (Long Name property from the PBX user object)
** h323 (Name property from the PBX user object)
* Azure Portal
** displayName
** mail
** mailNickname
** onPremisesDistinguishedName
** onPremisesSamAccountName
** onPremisesUserPrincipalName
** userPrincipalName

Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content. 
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.

===== Mapping Table =====

{| class="wikitable"
|-
! Teams Presence
! PBX Presence
|-
| Away
| away
|-
| BeRightBack
| away
|-
| Busy
| busy
|-
| DoNotDisturb
| dnd
|-
| InACall
| on-the-phone
|-
| InAMeeting
| meeting
|-
| Inactive
| online
|-
| PresenceUnknown
| online
|-
| Available
| online
|-
| Offline
| online
|-
| Offwork
| online
|-
| OutOfOffice
| away
|-
| UrgentInterruptionsOnly
| dnd
|-
| Presenting
| on-the-phone
|-
| InAConferenceCall
| on-the-phone
|}

The value "online" unsets the Teams presence in the PBX.

===== Master/Slave =====

For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.

=== Calendar Presence ===

==== Configuration ====
Please have a look into our [[Howto15r1:Configure_Calendar_Presence_Sync_by_Connector_for_Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 15r1 the Connector for Microsoft 365 will offer a possibility to sync Azure Portal calendar events (Teams, Exchange online) via the Graph API with the PXB presence. 
For now the [https://wiki.innovaphone.com/index.php?title=Reference13r3:Concept_App_Service_Calendar Calendar App] is (along with other functions) also capable of syncing calendar events, but using the old EWS mechanism, which Microsoft announced as end of life starting from 2026. 
'''Warning:''' Please make sure to not use both apps for syncing calendar events in parallel, this is not supported and will most likely lead to conflicts and unexpected behaviours. 
 
When the configuration of the connector for Microsoft 365 Calendar Presence Sync is complete, the app connects to Microsoft to receive a token with the calendar app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, a subscription for calendar events is created at Microsoft to receive event changes in Microsoft Calendar for these users. 
 
A user subscription is also started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 
If a calendar event has been started or ended, it is forwarded to the PBX. 

* User subscriptions are renewed every 60 minutes.
* Event subscriptions are renewed every day.
* License Check is made every hour.

=== Contact Search ===

==== Configuration ====
Please have a look into our [[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365|Howto guide for basic configuration aid]].

==== Technical Overview ====
Introduced in 16r1 the Connector for Microsoft 365 will offer a possibility to search for your own contacts (Teams, Exchange online) via the Graph API.

When the configuration of the connector for Microsoft 365 Contact Search is complete, the app connects to Microsoft to receive a token with the contact search app registered in the Azure portal. 
With the token, the app can pick up the users from the Azure portal. 
These are matched against the users in the PBX, based on the configured "User Assignment" settings. 
For each matched user with a valid Connector for Microsoft 365 licence applied, the user can search with the Phone App, for example (a myApps search provider will be provided for all apps looking using search providers looking up contacts). The search string is made available to the Connector for Microsoft 365 via the microsoft365-api. The results are sent to the consumer, e.g. the Phone App and presented there. 
 
A user subscription is started to receive user changes (add, delete or update). 
If a user has changed, the users are retrieved again. 
 

* User subscriptions are renewed every 60 minutes.
* License Check is made every hour.

'''Be aware:''' Since the Connector for Microsoft 365 is an app in the Scope of myApps App Platform, IP Phones and other services not using Apps cannot benefit from this search service.

== Related Articles ==

=Known Limitation=

== General ==
''Applies to the User Presence and the Calendar Presence''

=== Synchronization Delay ===
In the official Graph-API documentation, Microsoft is providing an overview about expected latencies for change notifications. 
You can find a whole overview table here: 
https://learn.microsoft.com/en-us/graph/change-notifications-overview#latency 
 
For the user presences the resource "presence" is used and an average latency of 10 seconds but a maximum up to 1 minute is provided. 
Such a delay in syncing changed presences from Teams down to the PBX are considered normal and are caused by the Microsoft Graph-API. 
 
In case of calendar events the average is provided as "less than 1 minute" and the maximum to 3 minutes. 

== User Presence ==
=== Line states set by the PBX does not block calls in Teams ===
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently '''only for display purpose and do not block new calls''' in Teams. 
 
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957 
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
=== Maximum number of supported users ===
The connector now supports multiple Microsoft Teams communication users, which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:

*3 configured communication users x 650 licensed users = 1950 users can be subscribed
'''Please be aware''': Each communication user must have a Teams license applied.

This limitation is caused by Microsoft. 
In the documentation of the Graph-API you will find a hint to this limitation: 
https://learn.microsoft.com/en-us/graph/changenotifications-for-presence#subscribe-to-multiple-users-presence 
Trying to subscribe more than 650 users (with one communication user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested. 

=== Communication User (UserSynctoPbx) ===
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.

=== Multiple sites / instances require multiple communication users ===
Each instance or each site must have separate communication users, as Microsoft only allows one concurrent subscription per communication user. (otherwise an HTTP 409 conflict will occur)

This means that if you want to subscribe to the same Azure Portal backend from two different sites (or instances), you will need to have multiple communication users (each with an applied Teams licence) in order to be able to subscribe from all endpoints.

=== Subscription Timeout ===

==== Situation ====
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription. 
As you can see in the [https://learn.microsoft.com/en-us/graph/api/subscription-delete?view=graph-rest-1.0&tabs=http|documentation of the current Graph API (1.0)] the “Delete subscription” chapter does not include presence subscriptions. 
It is also not possible to have multiple subscription in parallel. 

To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database. 
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes. 
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription. 

==== Impact ====
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup. 
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid. 
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription. 

The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future. 

=Troubleshooting=
== General ==

===Creating an app trace===
For further analysis and creating a support ticket it will be useful to have a suitable app trace. 
Before creating the trace please make sure the following trace flags are activated for the app instance:
* App
* Database
* HTTP client
* TLS
* TCP
* App WebSocket
* Config
* Webserver

After setting the config flags, please make sure to
* stop the instance
* deleting the current instance log
* start the instance
'''Now please wait at least 5 Minutes before you save the log''', otherwise we could not have the whole picture in the trace.

The restart and deletion of the the old log is useful the see the complete initialization process right away.

===SSL Certificate for notification URL===
It also is useful to make sure the notification URL has a valid and public signed certificate. 
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html 
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.

===Correctness of notification URL===
You can try to open the notification URL in your Browser 
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content. 
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app. 
 
What you can find out by trying to open the URL in your browser are the two following things: 
* If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
* If the URL is modified and the used build number is added, an app has answered your request
** Example: <code>https://public.dns/your.domain/microsoft365/subscriptions</code> is modified to <code>https://public.dns/your.domain/microsoft365/1510411/subscriptions</code>
** If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)

'''Be aware:''' The URL-Recognition in the Application Platform is '''case sensitive'''.

== User Presence ==
===GUI Feedback===
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems. 
Sometimes it needs a little bit time until the states are changed. 
If the states remain, it is mandatory to enable logs on the app platform and check for more information. 
([[Howto13r3:Configure Connector for Microsoft365#Creating an app trace|Concept App Service Connector for Microsoft 365: Creating an app trace]])

====No connection to Master PBX====
Check the MasterPBX name. 
The field must only contain the name [pbx], '''not the full domain''' [pbx.domain.tld]. ([[Howto13r3:Configure Connector for Microsoft365#Synchronization from Teams to the PBX|Synchronization from Teams to the PBX - Master PBX field]])

====Presence subscription failed====
There are many reasons why the "Presence subscription failed" message could be displayed. 
We try to list the most common reasons:
* The permission for the registered app in the Azure portal are not correctly set ([[Howto13r3:Configure Connector for Microsoft365#Create an App for syncing Teams to PBX|Howto: Create an App for syncing Teams to PBX]])
* The Notification URL is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The App service is not reachable from the internet ([[Reference13r3:Concept App Service Connector for Microsoft 365#Correctness of notification URL|Concept App Service Connector for Microsoft 365: Correctness of notification URL]] )
* The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed ([[Reference13r3:Concept App Service Connector for Microsoft 365#SSL Certificate for notification URL|Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL]])
* The user from PBX and the Azure Portal cannot be matched ([[Reference13r3:Concept App Service Connector for Microsoft 365#User Matching|Concept App Service Connector for Microsoft 365: User Matching]])
* The App Platforms clock time is wrong ([[Reference13r3:Concept App Service Connector for Microsoft 365#App Platform clock time is wrong|Concept App Service Connector for Microsoft 365: App Platform clock time is wrong]])
* No user has a valid Connector for Microsoft 365 App license ([[Reference13r3:Concept App Service Connector for Microsoft 365#Requirements|Concept App Service Connector for Microsoft 365: Requirements]])

===Teams License for communication user===
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user. 
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access). 
''Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)''

= Known Issues =
== Special Characters In Password ==
If you are using special characters (*, &, (, ), etc.) in your password you could run into a problem with the authentication of the communication user. 
The authentication failed status is being displayed. 
For the moment the only workaround is to eliminate special characters from your password.

==App Platform clock time is wrong==
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365. 
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired. 
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired. 

A wrong clock time will lead to false expiration times and thus
* the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
* the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)

If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the <code>date</code> command to check the current time. 
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.

==Geoblocking==
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector. 
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.

= Related Articles =
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Contact Search by Connector for Microsoft365]]

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

Howto16r1:Firmware Upgrade V15r1 V16r1

2025-10-10T16:18:43Z

Tfu: /* Connector for Microsoft 365 */

== Applies To ==
This information applies to:

* All 16r1 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 16r1, see [[Howto:Firmware Upgrade]]
== Licenses ==
In case of cloud or rental model, don't worry about licenses.

If the system is licensed on premise, you'll need to regenerate the license file for v16 in https://portal.innovaphone.com/ and load into the system before upgrade (The system needs to have the SSC up to date).

== Migration Policy ==
Before you begin, be sure that your whole installation is running the latest 15r1 service release. 

=== TechAssist Upgrade Helper ===
* Before you start, make sure that all TechAssist tests (you will receive the required tests in the last update in the previous major version) labelled <code>Pre Upgrade: xy</code> are positive, if available
* When you are finished, make sure that all TechAssist tests (you will receive new tests with the upgrade) are positive

=== New TLS Profile ===
Please note that we have changed our TLS profiles ([[Reference16r1:IP4/General/TLS]]). The new ''Normal'' setting, which is the default value, now only allows TLS 1.3 and TLS 1.2.

== Changes visible to the end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a upgrade, as the change will be visible/audible in the behaviour of the application/device.

* ''Nothing''

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

=== Connector for Microsoft 365 ===
If you plan to use the new '''Contact Search''' feature of the Connector for Microsoft 365, you need to perform two manual Steps:
# Create the '''microsoft365-api''' app object by using the Settings template
# Assign the '''microsoft365-api''' app object to every user who should be able to use the new Contact Search feature. (Of cause, you can use a template for that)
 
For a more detailed guide, please refer to the how-to article: [[Howto16r1:Configure Contact Search by Connector for Microsoft365#Creating the PBX app object using the PBX Manager Plugin]]

== New Apps ==
New Apps will not be installed automatically by the upgrade. The installation description of new apps is usually in the concept article. Please rate per app whether you want to install/use the new app and configure it manually.

* App Polls: [[Reference16r1:Concept App Polls]]
* App Service Conference Transcriptions [[Reference16r1:Concept_App_Service_myApps_Assistant]]

== Removed ==
The following software is no longer included.

* IP110A (can still be used with 15r1 firmware on current PBX versions)
* IP240A (can still be used with 15r1 firmware on current PBX versions)
* CA on CF card feature

== Deprecated ==
The following software is based on legacy technology, with no further development and limited maintenance and support.

* ''Nothing''

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

* ''Nothing''

==Known Problems==
===Long Update-duration===
When you update, it can be up to 10 minutes before you have access to your app platform again.

== Related Articles ==
*[[Howto:Firmware_Upgrade]]
* [[Howto15r1:Firmware_Upgrade_V14r2_V15r1]]
[[Category:Howto|{{PAGENAME}}]]

Howto16r1:Firmware Upgrade V15r1 V16r1

2025-10-10T14:05:49Z

Tfu: /* Connector for Microsoft 365 */

== Applies To ==
This information applies to:

* All 16r1 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 16r1, see [[Howto:Firmware Upgrade]]
== Licenses ==
In case of cloud or rental model, don't worry about licenses.

If the system is licensed on premise, you'll need to regenerate the license file for v16 in https://portal.innovaphone.com/ and load into the system before upgrade (The system needs to have the SSC up to date).

== Migration Policy ==
Before you begin, be sure that your whole installation is running the latest 15r1 service release. 

=== TechAssist Upgrade Helper ===
* Before you start, make sure that all TechAssist tests (you will receive the required tests in the last update in the previous major version) labelled <code>Pre Upgrade: xy</code> are positive, if available
* When you are finished, make sure that all TechAssist tests (you will receive new tests with the upgrade) are positive

=== New TLS Profile ===
Please note that we have changed our TLS profiles ([[Reference16r1:IP4/General/TLS]]). The new ''Normal'' setting, which is the default value, now only allows TLS 1.3 and TLS 1.2.

== Changes visible to the end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a upgrade, as the change will be visible/audible in the behaviour of the application/device.

* ''Nothing''

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

=== Connector for Microsoft 365 ===
If you plan to use the new '''Contact Search''' feature of the Connector for Microsoft 365, you need to perform two manual Steps:
# Create the '''microsoft365-api''' app object by using the settings template
# Assign the '''microsoft365-api''' app object to every user who should be able to use the new Contact Search feature. (Of cause, you can use a template for that)
 
For a more detailed guide, please refer to the how-to article: [[Howto16r1:Configure Contact Search by Connector for Microsoft365#Creating the PBX app object using the PBX Manager Plugin]]

== New Apps ==
New Apps will not be installed automatically by the upgrade. The installation description of new apps is usually in the concept article. Please rate per app whether you want to install/use the new app and configure it manually.

* App Polls: [[Reference16r1:Concept App Polls]]
* App Service Conference Transcriptions [[Reference16r1:Concept_App_Service_myApps_Assistant]]

== Removed ==
The following software is no longer included.

* IP110A (can still be used with 15r1 firmware on current PBX versions)
* IP240A (can still be used with 15r1 firmware on current PBX versions)
* CA on CF card feature

== Deprecated ==
The following software is based on legacy technology, with no further development and limited maintenance and support.

* ''Nothing''

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

* ''Nothing''

==Known Problems==
===Long Update-duration===
When you update, it can be up to 10 minutes before you have access to your app platform again.

== Related Articles ==
*[[Howto:Firmware_Upgrade]]
* [[Howto15r1:Firmware_Upgrade_V14r2_V15r1]]
[[Category:Howto|{{PAGENAME}}]]

Howto16r1:Firmware Upgrade V15r1 V16r1

2025-10-10T13:55:25Z

Tfu: /* Manual steps needed after upgrade */

== Applies To ==
This information applies to:

* All 16r1 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 16r1, see [[Howto:Firmware Upgrade]]
== Licenses ==
In case of cloud or rental model, don't worry about licenses.

If the system is licensed on premise, you'll need to regenerate the license file for v16 in https://portal.innovaphone.com/ and load into the system before upgrade (The system needs to have the SSC up to date).

== Migration Policy ==
Before you begin, be sure that your whole installation is running the latest 15r1 service release. 

=== TechAssist Upgrade Helper ===
* Before you start, make sure that all TechAssist tests (you will receive the required tests in the last update in the previous major version) labelled <code>Pre Upgrade: xy</code> are positive, if available
* When you are finished, make sure that all TechAssist tests (you will receive new tests with the upgrade) are positive

=== New TLS Profile ===
Please note that we have changed our TLS profiles ([[Reference16r1:IP4/General/TLS]]). The new ''Normal'' setting, which is the default value, now only allows TLS 1.3 and TLS 1.2.

== Changes visible to the end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a upgrade, as the change will be visible/audible in the behaviour of the application/device.

* ''Nothing''

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

=== Connector for Microsoft 365 ===
If you plan to use the new '''Contact Search''' feature of the Connector for Microsoft 365, you need to perform two manual Steps:
# Create the '''micrsofot365-api''' app object by using the settings template
# Assign the '''microsoft365-api''' app object to every user who should be able to use the new Contact Search feature. (Of cause, you can use a template for that)
 
For a more detailed guide, please refer to the how-to article: [[Howto16r1:Configure Contact Search by Connector for Microsoft365#Creating the PBX app object using the PBX Manager Plugin]]

== New Apps ==
New Apps will not be installed automatically by the upgrade. The installation description of new apps is usually in the concept article. Please rate per app whether you want to install/use the new app and configure it manually.

* App Polls: [[Reference16r1:Concept App Polls]]
* App Service Conference Transcriptions [[Reference16r1:Concept_App_Service_myApps_Assistant]]

== Removed ==
The following software is no longer included.

* IP110A (can still be used with 15r1 firmware on current PBX versions)
* IP240A (can still be used with 15r1 firmware on current PBX versions)
* CA on CF card feature

== Deprecated ==
The following software is based on legacy technology, with no further development and limited maintenance and support.

* ''Nothing''

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

* ''Nothing''

==Known Problems==
===Long Update-duration===
When you update, it can be up to 10 minutes before you have access to your app platform again.

== Related Articles ==
*[[Howto:Firmware_Upgrade]]
* [[Howto15r1:Firmware_Upgrade_V14r2_V15r1]]
[[Category:Howto|{{PAGENAME}}]]

Howto16r1:Configure Contact Search by Connector for Microsoft365

2025-10-10T13:41:12Z

Tfu: /* Creating the PBX app object using the PBX Manager Plugin */

{{FIXME|reason=This article is still work in progress}}

==Applies To==
This information applies to
Connector for Microsoft 365 from version 16r1

==More Information==

This article outlines a configuration scheme for Connector for Microsoft365 functionality. 
In preparation, you first will need to configure one Application in your Azure Portal. 
After that, you will install the App in your Application Platform, and configure everything.

===System Requirements===

* Licenses '''innovaphone Connector for Microsoft 365''' per user who wants to use the innovaphone myApps Connector for Microsoft 365.
* '''account in Azure Portal of Microsoft''' (for each of the technical communication users, no permission role needed) 
* Must have access from the internet to your App Platform
** This can be done by using a reverse proxy or other firewall
* The public endpoint '''must have ''' a '''valid, public signed certificate''' (in order to make a trusted SSL connection from the Azure cloud to the Application Platform possible)
** A valid certificate is required in all involved network entities - at least in the App Platform and if used in the Reverse Proxy; to ensure transmission of MS365 HTTPS POST requests to the app service in order to send notifications.
* Admin account for Azure Portal (only necessary for granting needed permission for registered app during setup)

==Installation==

===Configuration in Azure Portal===

====Create an App to search for contacts====
* '''In the Azure Portal of Microsoft you have to add an app registration'''
* '''You only have to give a name for the app'''

[[Image:App_Registration_Connector_for_Microsoft365.png|thumb|none|600px|App Registration|app_registration_connector_for_microsoft365.png/]]

* '''Switch to Certificates & Secrets on the left'''
* '''You only have to configure a client secret and save the value for the configuration of the app'''

[[Image:Authentication_Connector_for_Microsoft365_Calendar.png|thumb|none|600px|authentication_connector_for_microsoft365_calendar.png/]]

* '''Switch to api permissions on the left'''
* '''You have to configure application permission (Contacts.Read) and (User.Read.All) as shown in the picture'''
* '''Grant access to the api permissions, if not possible you have to ask an admin'''

[[Image:Azure_Select_Api-Permission.png|thumb|none|600px|azure_select_api-permission.png/]]
[[Image:Azure_Select_Api-Permission_Application.png|thumb|none|600px|azure_select_api-permission_application.png/]]
[[Image:APIPermission Connector for Microsoft365 ContactSearch.png|thumb|none|600px|APIPermission Connector for Microsoft365 ContactSearch/]]

===Installing and configuring App Platform and PBX===
====Installing the connector app====
* First you need to install the connector app from the App Store:
[[Image:Microsoft365_install_app_1.png|thumb|none|600px|microsoft365_install_app_1.png/]]
* Install the app by selecting
# All apps
# innovaphone AG
# innovaphone myApps Connector for Microsoft 365
# select the current Version
# Click install
[[Image:Microsoft365_install_app_2.png|thumb|none|600px|microsoft365_install_app_2.png/]]
====Creating an instance for the connector app====
* For creating an Instance, in the AP Manager you need to
# select '''innovaphone myApps Connector for Microsoft 365'''
# click '''add'''
[[Image:Microsoft365_create_instance_1.png|thumb|none|600px|microsoft365_create_instance_1.png/]]
* Insert the following information and save
# The technical Instance Name (we suggest microsoft365)
# Your Domain (This should be the domain you have already configured in your PBX and your Application Platform)
# define a password for the communication between the PBX and the app instance
# define a password for the communication between the app instance and the database
''All other fields should be filled automatically''
[[Image:Microsoft365_create_instance_2.png|thumb|none|600px|microsoft365_create_instance_2.png/]]

====Creating the PBX app object using the PBX Manager Plugin====
* Open the PBX Manager and
# select the '''AP <code>InstanceName</code>''' Tile
# Click '''Add an app'''
# Click '''Microsoft365 App'''
[[Image:Microsoft365_pbx_manager_1.png|thumb|none|600px|microsoft365_pbx_manager_1.png/]]
* Specify the '''Name''' and the '''SIP''' (We suggest using '''<code>microsoft365</code>''' for this technical names)
[[Image:Microsoft365_pbx_manager_2.png|thumb|none|600px|microsoft365_pbx_manager_2.png/]]

'''Important:''' Please also add the '''microsoft365-api''' to a suitable Config-Template: Every user who should be able to search via the Connector for Microsoft 365 has to have access to the '''microsoft365-api'''.

====Creating the API object using the PBX Manager Plugin====
* Open the PBX Manager and
# select the '''AP <code>InstanceName</code>''' Tile
# Click '''Add an app'''
# Click '''Microsoft365 API'''
[[Image:Microsoft365_pbx_manager_1.png|thumb|none|600px|microsoft365_pbx_manager_1.png/]]
* The '''Name''' and '''SIP''' has to be '''<code>microsoft365-api</code>'''
[[Image:Microsoft_365_Settings_API.png|thumb|none|600px|microsoft_365_Settings_API.png/]]

====Add the admin app to a user or a template====
To be able to configure the connector app, you need users to have access to the admin app. 
You can achieve this by adding the app to a user, or to a template. 
In this Howto - as an example - we will add the app to the <code>Config Admin</code> template. 
* In the PBX Manager
# select the <code>Templates</code> tile
# click on the <code>Config Admin</code> template
[[Image:Microsoft365_template_1.png|thumb|none|600px|microsoft365_template_1.png/]]
* In the <code>Config Admin</code> template
# open Apps
# Check the <code>app name</code> checkbox
# Save the changes
[[Image:Microsoft365_template_2.png|thumb|none|600px|microsoft365_template_2.png/]]

====Configure the connector with the admin app====
Now your admins (designated groups or configured user) should have access to the connector admin app. 
* A user with access to the app can now see a new tile in the '''All Apps''' area
* The name depends on the configured <code>app name</code> from the PBX Manager plugin
[[Image:Microsoft365_admin_app_1.png|thumb|none|600px|microsoft365_admin_app_1.png/]]

=====Configuration of the Contact Search=====
* For the contact search you select '''Configuration for Contact Search''' in the admin app
# '''ClientIDContactSearch''' - Please insert the Application ID (Client ID) from Azure Portal from the in preparation created Contact Search app
# '''TenantContactSearch''' - Please insert the Directory ID (Tenant) from Azure Portal from the in preparation created Contact Search app
# '''ClientSecretContactSearch''' - Please insert the shared secret from the in preparation created Contact Search app
# '''NotificationURL''' - You need to specify the address Microsoft can send presence updates to
## You need to make sure that you define a URL where you can reach your App Platform from the public internet <code>public.dns</code>
## Next you need the domain you have configured in the app instance before (3.2.2) <code>your.domain</code>
## Next you need the name of the instance you have configured before (3.2.2) <code>microsoft365</code>
## The URL will always be terminated by <code>subscriptions</code>
##* <code>https://public.dns/your.domain/microsoft365/subscriptions</code>

==Related Articles==
[[Reference16r1:Concept App Service Connector for Microsoft 365|Concept App Service Connector for Microsoft 365]] 
[[Howto16r1:Configure User Presence Sync by Connector for Microsoft365]] 
[[Howto16r1:Configure Calendar Presence Sync by Connector for Microsoft365]] 

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

Reference16r1:Apps/PbxManager/App RemoteControl

2025-10-10T10:23:04Z

Tfu: Created page with "The Remote Control PBX Manager plug-in can be used to create and configure the required App object. In addition, the App object can be assigned to specific configuration templates, if any exist. Services licences can also be configured == Add an App == ;Name :The ''name'' displayed for the App object which must be unique. ''(The field is prefilled with "Remote Control", you can leave it as it is)'' ;SIP :The ''sip'' of the App object which must be unique.The sip-id for..."

The Remote Control PBX Manager plug-in can be used to create and configure the required App object. In addition, the App object can be assigned to specific configuration templates, if any exist. Services licences can also be configured

== Add an App ==
;Name
:The ''name'' displayed for the App object which must be unique. ''(The field is prefilled with "Remote Control", you can leave it as it is)''

;SIP
:The ''sip'' of the App object which must be unique.The sip-id for the App Object, which must be unique. ''(The field is prefilled with "remotecontrol", you can leave it as it is)''

;Config templates
:If config templates exist, they will be listed with a checkbox. Tick the template of your choice to deploy the application.

;Licences
:Number of purchased licences to configure (leave empty if no licenses purchased)

==Related Articles==
* [[{{NAMESPACE}}:Concept App Remote Control]]

[[Category:Concept App Remote Control]]

Reference16r1:Concept App Remote Control

2025-10-10T09:37:44Z

Tfu: Created page with "Apps Category:Concept App Remote Control == Applies to == * innovaphone PBX from version 15r1 == Requirements == * innovaphone PBX * innovaphone Application Platform (minimum version 130006) * V15r1 * myApps for Windows. * Remote Control Client for external participants '''Note : in v15r1 the Remote Control Client is only available for Windows''' == Overview == Remote Control is an application to access a remote PC. The application can be..."

[[Category:Concept|Apps]]
[[Category:Concept App Remote Control]]
== Applies to ==
* innovaphone PBX from version 15r1
== Requirements ==
* innovaphone PBX
* innovaphone Application Platform (minimum version 130006)
* V15r1
* myApps for Windows.
* Remote Control Client for external participants '''Note : in v15r1 the Remote Control Client is only available for Windows'''

== Overview ==
Remote Control is an application to access a remote PC.
 The application can be used by the IT department to provide remote support or it could also be used as a collaborative tool for remote work.

== Licensing ==

* For the [[Reference15r1:Concept_App_Remote_Control#Features|licensed features]] you will need to order the '''Service(innovaphone-remotecontrol)''' license, order number : ''02-00050-015''
* '''The application includes one session by default'''

== Installation ==
=== For new v15r1 installation ===
The Remote Control App is automatically installed by the installer and will be deployed in the '''Config User''' template
=== With the Settings App - AP app installer plug-in ===
[[File:Ap_app_installer.png]]

Go to the Settings App 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 '''"remote control"''' and click on it
* Select the proper firmware version, here '''"v15"''' 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 coloured AP plugin
* Click on the '''"AP remotecontrol"''' and click on '''" + Add an App"'''
* The '''"Name"''' display name field ''(all characters allowed)'' and the '''"SIP"''' administration field ''(no spaces, no capital letters)'' are prefilled, you can leave them as they are.
* Tick the appropriate template to distribute the App
* Enter the amount of purchased licenses
* Click OK to save the settings and a green check mark will be shown to inform you that the configuration is good

== Apps ==
=== Remote Control (remotecontrol) ===
This is the standard UI App for Remote Control.
Parameters:
;Websocket: Connection between the PBX and the App Platform. the App Platform receives the number of licences via this connection.
;PbxSignal: Protocol to register to the PBX and do signalling with the JSON signalling protocol (necessary to retrieve the TURN server data from the PBX)
;PbxApi: App notification and presence monitoring of in-app user list

== Concept ==
[[Image: Rcrounded.png]]

A user (viewer) sends a request to another user (sharer) to access the sharer's PC, the sharer accepts the session and begins to share their desktop with the viewer.
 The viewer is also automatically given control of the mouse and keyboard. Remote sessions are also possible between companies using myApps or not.

=== Features ===

Here are the features available in the Remote Control App

;Included features
:
* App notification to start a session
* Multiple monitor support: Viewers can switch between desktops by clicking on the monitor icons
* Direction of control: Change the direction of sharing, a viewer would become a sharer
* Screen scaling: Two different views of the remote desktop, original size or resized
* Notifications: On the remote PC, if the sharer does not have the remote control open or is busy with another session, the person requesting a session will be notified within the Remote Control App
* Text copy & paste support in both directions
* Support for different keyboard layouts

;Licensed features
:
* Support with participants outside your organisation
** Between 2 different myApps installation using Remote Control App ''(e.g 2 different companies)'' via a session link.
** Without myApps with the [[Reference15r1:Concept_App_Remote_Control#With_the_Remote_Control_Client_msi_application|Remote Control Client]].
* Share/Join session
** Generate a session link from Remote Control App and share it
** Join a session by entering a link
* Multiple sessions:
**If you need more than one session (e.g many viewers for one sharer, more than one parallel session)

=== Remote Control with participants outside your organisation ===
====With the Remote Control Client external application====
The Remote Control Client allows you to establish a remote session with people who are not part of your myApps environment. ''E.g. : external participants such as your customers''. External participants see the myApps user's screen sharing.
* Client compatible with Windows only
* Easy to install, download client via a session link:
**Open the shared session link in a web browser and get the ''remoteControl.exe''
**Open the previously downloaded file on your computer
**Enter your name, info and session link ''(same link that is used to download the client)''
**Click on Join Session
''Note : from 15r1sr2 we introduced a new, lighter client that requires less effort to install and use. The new client also offers a new possibility of joining sessions with elevated admin rights for users who are not admins on their computers. ''

====With your myApps Remote Control App====
It is possible to establish a remote session between 2 organisations using myApps and having the Remote Control App installed. In the App you can also join/share a session with a link.
*Compatible only between myApps Windows clients
*Easy to use:
**User A from company "xyz.com" opens his Remote Control App in myApps and clicks on '''Share session'''
**User A copies the link and sends it to User B
**User B from company "abc.com" opens his Remote Control App in myApps, clicks on '''Join session''' and pastes the link received from User A into the '''Session link text field'''
**User A will receive a Join Session notification to accept
**User A will see User B shared session

=== Technical overview ===
[[Image:Remote-control_technical-overview.png]]
*Note: SCTP packets are routed through the TURN server and therefore the transmission is not peer-to-peer if the TURN server is selected from the ICE candidate.

=== Technical data ===
* The maximum bitrate is 1.2Mbits for the users who is sending its desktop UI. The viewer just sends mouse and keyboards events
* Remote Control App is using the SCTP protocol with a fix UDP port range between [https://wiki.innovaphone.com/index.php?title=Howto:What_Ports_are_used_for_Signaling_and_Voice_Traffic_in_SIP_and_H.323%3F#Application_Sharing_(RTP)| 50200-50299] within the myApps client. Same range as the Application Sharing feature
*Same port range is used by the Remote Control Client msi application

== Troubleshooting ==
When you open a support ticket, you will be asked to provide us with debugging data of your issue. You can also send us screenshots/videos of the behavior you are reporting. Do not forget to send us also the PBX default configuration file.

=== Trace flags of the App instance on the App Platform ===
Select the corresponding App instance of the Remote Control App service and click on the '''Diagnostics button'''. Tick the following trace flags:
*App
*Database

=== Trace flags of the myAPPS Client ===
Go to the myApps '''Burger menu''', click on '''more''', and then click the '''magnifying glass'''. Tick the following trace flag:
*AppSharing

=== Trace of the Remote Control Client ===
Do a right click on the app try icon and click on ''open trace folder'' (''default path C:\Users\[YourUser]\AppData\Local\innovaphone\RemoteControl''), get the whole content in a zip file.

==Known issues==
*Push notifications on sharer's smartphone : if a viewer wants to start a remote session with a sharer who does not have the Remote Control App open on their PC, a push notification is triggered on the sharer's myApps mobile phone (if installed).

==Related Articles==
* [[{{NAMESPACE}}:Apps/PbxManager/App RemoteControl]]
[[Category:Apps/PbxManager/App RemoteControl]]

Howto16r1:Configure OAuth2 E-Mail

2025-10-09T13:34:16Z

Tfu: /* General Information */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}

The innovaphone PBX and apps can be configured to send E-Mails for various subjects and purposes. Major E-Mail providers intent to discontinue the username/password authentication schemes in favour of OAuth2. PBX and Apps version 16r1 does support OAuth2 authentication for SMTP. Here is a step by step guide how to set up OAuth2 support in Microsoft 365 through the Azure Portal and how to set it up on a Google Gmail account in the Google Cloud Console.

== General Information ==
Most of the large email providers offer the possibility to define an app that is allowed to gain access of a certain scope like SMTP. 
It assigns a Client ID / Client Secret. 
 
Authorization for sending from the mail account needs to be given one time either: 
* By providing resource owner username/password. Sending this to the token endpoint results in an access token and long term refresh token.
* By interactive authorization via a popup dialogue that is loaded from the authorization endpoint. After the credentials are verified, the dialogue redirects to the redirect URI with an authorization code that is traded to an access token and refresh token.
 
The access token is sent for authentication in SMTP. It needs regular refresh, which will be done automatically.

=== Modes ===

* '''Exchange''': Microsoft, with interactive authorization
* '''Microsoft 365''': Microsoft, without interactive authorization (Resource owner and password has to be filled)
* '''Gmail''': Google, with interactive authorization
* '''Google Service Account''': Google, without interactive authorization (Client e-mail, Private Key ID and Private Key of the service account must be provided)
* '''Client secret post''': Generic configuration where all parameters of the client secret post OAuth2 flow can be set.
* '''Private key jwt''': Generic configuration where all parameters of the private key jwt OAuth2 flow can be set.

=== Example Redirect URIs ===

* '''PBX''': <nowiki>https://example-pbx.domain.com/OAUTH2-CLIENT/auth.htm</nowiki>
* '''Reporting''': <nowiki>https://example-ap.domain.com/domain.com/reporting/auth.htm</nowiki>
* '''Fax''': <nowiki>https://example-ap.domain.com/domain.com/fax/auth.htm</nowiki>
* '''Users''': <nowiki>https://example-ap.domain.com/domain.com/usersapp/auth.htm</nowiki>
* '''Connect''': <nowiki>https://example-ap.domain.com/domain.com/messages/auth.htm</nowiki>
* '''AP Manager''': <nowiki>https://example-ap.domain.com/manager/auth.htm</nowiki>

== Microsoft 365 ==
=== Azure Portal ===
Log in to Microsoft Azure Portal (https://portal.azure.com) and go to Microsoft Entra ID.
[[File:AzureMicrosoftEntraID.png|none|thumb|600x600px|/AzureMicrosoftEntraID.png|/AzureMicrosoftEntraID.png]]
Add a new app registration to create client credentials.
[[File:AzureAddAppRegistration.png|none|thumb|600x600px|/AzureAddAppRegistration.png|/AzureAddAppRegistration.png]]
Register the application and maybe already fill in the redirect URI for Web based application type to path OAUTH2-CLIENT/auth.htm at the PBX.
[[File:AzureRegisterAnApplication.png|none|thumb|600x600px|/AzureRegisterAnApplication.png|/AzureRegisterAnApplication.png]]
App registration is complete. Client ID and tenant needs to be configured at the PBX and every app that will be sending e-mails.
[[File:AzureApp.png|none|thumb|600x600px|/AzureApp.png|/AzureApp.png]]
Create a client secret. Note that expiry is limited to no longer than 2 years. The client secret must be renewed before expiry and the new secret configured and interactive authorisation carried out again to ensure continuous operation.
[[File:AzureAddClientSecret.png|none|thumb|600x600px|/AzureAddClientSecret.png|/AzureAddClientSecret.png]]
Copy the client secret. It also needs to be configured at the PBX and every app that will be sending e-mails.
[[File:AzureCopyClientSecret.png|none|thumb|600x600px|/AzureCopyClientSecret.png|/AzureCopyClientSecret.png]]
Add permissions located in APIs my organization uses.
[[File:AzureAddApiPermissionMyOrganization.png|none|thumb|600x600px|/AzureAddApiPermissionMyOrganization.png|/AzureAddApiPermissionMyOrganization.png]]
More precisely located in Office 365 Exchange Online.
[[File:AzureAddApiPermissionExchange.png|none|thumb|600x600px|/AzureAddApiPermissionExchange.png|/AzureAddApiPermissionExchange.png]]
And there in the application permissions.
[[File:AzureAddApiExchangeApplication.png|none|thumb|600x600px|/AzureAddApiExchangeApplication.png|/AzureAddApiExchangeApplication.png]]
Namely SMTP Mail.Send.
[[File:AzureAddApiSendMailAsUser.png|none|thumb|600x600px|/AzureAddApiSendMailAsUser.png|/AzureAddApiSendMailAsUser.png]]
Grant admin permission for Mail.Send.
[[File:AzureGrantApiPermissions.png|none|thumb|600x600px|/AzureGrantApiPermissions.png|/AzureGrantApiPermissions.png]]
API permissions are now granted.
[[File:AzureApiPermissionsGranted.png|none|thumb|600x600px|/AzureApiPermissionsGranted.png|/AzureApiPermissionsGranted.png]]
Tell all redirect URIs that the PBX and the apps will be using during interactive authorization.
[[File:AzureRedirectUris.png|none|thumb|600x600px|/AzureRedirectUris.png|/AzureRedirectUris.png]]
Allow public client flows of OAuth2. Resource Owner Password Credentials Flow has the advantage that it doesn't need interactive authorization.
[[File:AzureAllowPublicClientFlows.png|none|thumb|600x600px|/AzureAllowPublicClientFlows.png|/AzureAllowPublicClientFlows.png]]

=== Microsoft 365 admin center ===
Log in to the Microsoft 365 admin center (https://admin.cloud.microsoft).
[[File:MS365AdminCenter.png|none|thumb|600x600px|/MS365AdminCenter.png|/MS365AdminCenter.png]]
Make sure that Microsoft 365 licenses are assigned to your user.
[[File:MS365UserLicenses.png|none|thumb|600x600px|/MS365UserLicenses.png|/MS365UserLicenses.png]]
Set your user active.
[[File:MS365ActiveUsers.png|none|thumb|600x600px|/MS365ActiveUsers.png|/MS365ActiveUsers.png]]
Locate the Mail tab of your user.
[[File:MS365UserEMail.png|none|thumb|600x600px|/MS365UserEMail.png|/MS365UserEMail.png]]
Allow authenticated SMTP.
[[File:MS365AuthenticatedSMTP.png|none|thumb|600x600px|/MS365AuthenticatedSMTP.png|/MS365AuthenticatedSMTP.png]]

=== Exchange admin center ===
Login to the Exchange admin center (https://admin.exchange.microsoft.com).
[[File:ExchangeAdminCenter.png|none|thumb|600x600px|/ExchangeAdminCenter.png|/ExchangeAdminCenter.png]]
Remove deactivation of the SMTP AUTH protocol.
[[File:ExchangeRemoveDeavtivatedOAuth2.png|none|thumb|600x600px|/ExchangeRemoveDeavtivatedOAuth2.png|/ExchangeRemoveDeavtivatedOAuth2.png]]

=== PBX Example configuration ===
With this Microsoft setup the OAuth2 configuration for the resource owner password credentials flow can be filled in as follows.
[[File:OAuth2ResourceOwnerPasswordCredentials.png|none|thumb|600x600px|/OAuth2ResourceOwnerPasswordCredentials.png|/OAuth2ResourceOwnerPasswordCredentials.png]]
For interactive authorization this is the OAuth2 configuration. Authorize e-mail access one time and send a test mail to verify everything went well.
[[File:OAuth2InteractiveAuthorization.png|none|thumb|600x600px|/OAuth2InteractiveAuthorization.png|/OAuth2InteractiveAuthorization.png]]

== Gmail ==
=== Preparations ===
Login to the Google Cloud Console (https://console.cloud.google.com), select a project, New project.
[[File:GoogleSelectProject.png|none|thumb|600x600px|/GoogleSelectProject.png|/GoogleSelectProject.png]]
Create the project.
[[File:GoogleCreateProject.png|none|thumb|600x600px|/GoogleCreateProject.png|/GoogleCreateProject.png]]
Client credentials will be created in this project.
[[File:GoogleProjectCreated.png|none|thumb|600x600px|/GoogleProjectCreated.png|/GoogleProjectCreated.png]]
From the library specify the APIs needed to access.
[[File:GoogleApisServicesFromLibrary.png|none|thumb|600x600px|/GoogleApisServicesFromLibrary.png|/GoogleApisServicesFromLibrary.png]]
These are in the Gmail API.
[[File:GoogleApisServicesApiLibrary.png|none|thumb|600x600px|/GoogleApisServicesApiLibrary.png|/GoogleApisServicesApiLibrary.png]]
Choose the Gmail API and enable it.
[[File:GoogleGmailApis.png|none|thumb|600x600px|/GoogleGmailApis.png|/GoogleGmailApis.png]]
Credentials need to be created.
[[File:GoogleGmailApiAdded.png|none|thumb|600x600px|/GoogleGmailApiAdded.png|/GoogleGmailApiAdded.png]]
Invoke the help me choose wizard.
[[File:GoogleCreateCredentialsHelpMeChoose.png|none|thumb|600x600px|/GoogleCreateCredentialsHelpMeChoose.png|/GoogleCreateCredentialsHelpMeChoose.png]]
User data access is needed.
[[File:GoogleCredentialsUserData.png|none|thumb|600x600px|/GoogleCredentialsUserData.png|/GoogleCredentialsUserData.png]]
Configure the consent screen of the interactive authorization.
[[File:GoogleOAuthConsentScreen.png|none|thumb|600x600px|/GoogleOAuthConsentScreen.png|/GoogleOAuthConsentScreen.png]]
Specify the permissions that need to be authorized by the user.
[[File:GoogleOAuthScopes.png|none|thumb|600x600px|/GoogleOAuthScopes.png|/GoogleOAuthScopes.png]]
Its mail.google.com in general.
[[File:GoogleScopeMailGoogleCom.png|none|thumb|600x600px|/GoogleScopeMailGoogleCom.png|/GoogleScopeMailGoogleCom.png]]
And its to send email on the users behalf.
[[File:GoogleScopeAuthGmailSend.png|none|thumb|600x600px|/GoogleScopeAuthGmailSend.png|/GoogleScopeAuthGmailSend.png]]
These are the scopes needed.
[[File:GoogleScopes.png|none|thumb|600x600px|/GoogleScopes.png|/GoogleScopes.png]]
Ask client credentials for Web type application.
[[File:GoogleOAuthClientID.png|none|thumb|600x600px|/GoogleOAuthClientID.png|/GoogleOAuthClientID.png]]
Tell all redirect URIs that the PBX and the apps will be using during interactive authorization.
[[File:GoogleRedirectURIs.png|none|thumb|600x600px|/GoogleRedirectURIs.png|/GoogleRedirectURIs.png]]
Download the credentials. This json file contains all information for OAuth2 configuration.
[[File:GoogleClientCredentialsDownload.png|none|thumb|600x600px|/GoogleClientCredentialsDownload.png|/GoogleClientCredentialsDownload.png]]
Customize the OAuth consent screen
[[File:GoogleOAuthConsentScreenSettings.png|none|thumb|600x600px|/GoogleOAuthConsentScreenSettings.png|/GoogleOAuthConsentScreenSettings.png]]
Start the customization wizard.
[[File:GoogleConsentScreenWizard.png|none|thumb|600x600px|/GoogleConsentScreenWizard.png|/GoogleConsentScreenWizard.png]]
Choose which users may authorize.
[[File:GoogleAudienceExternal.png|none|thumb|600x600px|/GoogleAudienceExternal.png|/GoogleAudienceExternal.png]]
Google workspace users may choose internal audience. Users not in Google workspace proceed with external.
[[File:GoogleContactInformation.png|none|thumb|600x600px|/GoogleContactInformation.png|/GoogleContactInformation.png]]
Add a test user.
[[File:GoogleTestUserAdded.png|none|thumb|600x600px|/GoogleTestUserAdded.png|/GoogleTestUserAdded.png]]

=== PBX Example configuration ===
The OAuth2 parameters can be filled in with the information from the json file downloaded above. Authorize e-mail access one time and send a test mail to verify everything went well.
[[File:OAuth2InteractiveGmail.png|none|thumb|600x600px|/OAuth2InteractiveGmail.png|/OAuth2InteractiveGmail.png]]

== Generic ==

For other e-mail providers the client secret post OAuth2 flow may be configured in a generic way. Details need to be supplied by the e-mail provider.

For the Microsoft 365 setup above it would be as follows with Token endpoint ''<nowiki>https://login.microsoftonline.com/af326a34-169c-469e-946b-1ef57925306b/oauth2/v2.0/token</nowiki>'' Authorization URL ''<nowiki>https://login.microsoftonline.com/af326a34-169c-469e-946b-1ef57925306b/oauth2/v2.0/authorize?scope=https://outlook.office.com/SMTP.Send</nowiki> offline_access'' The configuration appends ''&response_type=code&prompt=consent&login_hint=...&redirect_uri=...&client_id=...'' automatically.[[File:OAuth2ClientSecretPost.png|none|thumb|600x600px|/OAuth2ClientSecretPost.png|/OAuth2ClientSecretPost.png]]
For the Gmail example above the generic confguration would be like this with Token endpoint ''<nowiki>https://oauth2.googleapis.com/token</nowiki>'' Authorization URL ''<nowiki>https://accounts.google.com/o/oauth2/auth?access_type=offline&scope=https://mail.google.com/</nowiki>'' The configuration appends ''&response_type=code&prompt=consent&login_hint=...&redirect_uri=...&client_id=...'' automatically.
[[File:OAith2ClientSecretPostGmail.png|none|thumb|600x600px|/OAith2ClientSecretPostGmail.png|/OAith2ClientSecretPostGmail.png]]
The private key jwt OAuth2 flow can be configured generically as well.[[File:OAuth2PrivateKeyJWT.png|none|thumb|600x600px|/OAuth2PrivateKeyJWT.png|/OAuth2PrivateKeyJWT.png]]

== Related Articles ==
* [[Reference16r1:PBX/Config/Authentication]]
* [[Reference16r1:Apps/PbxManager/Email]]
* [[Reference16r1:Concept App Connect#E-Mail configuration]]
* [[Reference16r1:Concept App Service Fax#Mail Configuration (SMTP_Server)]]
* [[Reference16r1:Concept App Service Reports#Configuration]]
* [[Reference16r1:Concept App Service Users#Users Admin App (innovaphone-usersadmin)]]
* [[Reference16r1:Concept App Platform#SMTP]]