innovaphone wiki - User contributions [en]

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

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T23:58:11Z

Tfu: /* Related Articles */

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

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

Reference14r2:Concept App Platform

2025-10-08T23:58:03Z

Tfu: /* SMTP */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How to implement large PBXs#Technical data and recommended number of users supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App services and multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. Before version 130012, you must use ISA, as Virtio was not supported with older versions.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How to retrieve files from the AP| Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

=== Nightly database analyse ===

Every database is analysed at night to keep indexes in sync with the data. This triggers a ''vacuumdb -a -z'', which updates optimizer statistics, but does '''not''' shrink the physical size of the database. 
This must be done manually in the instance settings.

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13 Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

After the update has been downloaded and verified, your App Platform will reboot.
You can check the installation process after the reboot with the following URL: https://IP-of-AP/manager/ramdisk.log

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'': A timezone string which is used by the App Platform Manager to do certain jobs according to the configured timezone.
** Note that this doesn't change the timezone of the linux itself!
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': see [[#Backup_of_the_Apps| Backup of Apps]]

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

Starting with 16r1 you also can configure OAuth2 Authentications. You can have a look into our HowTo Article for assistance: [[Howto16r1:Configure OAuth2 E-Mail]]

== Replication ==
App Platform [[#App Platform replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
**Note: to ensure rapid recognition of the new DNS target, the definition of an appropriate TTL value is recommended
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

See also https://wiki.innovaphone.com/index.php?title=Howto14r2:Firmware_Upgrade_V14r1_V14r2#App_Platform_and_Apps

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== App Platform doesn't start after an update ==

=== Gateway ===
If it happens, that the App Platform doesn't want to start an update, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it 
* Set '''Kernel command line''' to '''/dev/ram0''' 
* Set '''Initrd file''' to '''ramdisk.ext2.xz''' 
* Set '''Ramdisk size''' to '''100000''' 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

Note: This process can take a while, after it's finished it reboots and automatically change the '''Kernel command line''' value.

=== Virtual Machine ===

Boot into the '''rescue''' partition.

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

=== It still doesn't start ===

If it still doesn't start, configure the App Platform to boot from /dev/sda3 (or inside a VM start the second boot loader entry) and login with SSH as root.
Then do a first check to verify that you have a specific error due to an incomplete update or a [[Howto15r1:Firmware Upgrade V14r2 V15r1#AP Upgrade to Image 130006|wrong update order]]:

* /etc/init.d/S92manager stop
* /apps/manager/manager
* if this outputs '''error while loading shared libraries: libcrypto.so.3:''' you have a manager version which cannot run on the current image.

In this case you must download an older build (14r1 1410593):

* /etc/init.d/S92manager stop
* wget --no-check-certificate -O /apps/manager/manager https://webbuild.innovaphone.com/1410593/arm/manager/manager
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* wget --no-check-certificate -O /apps/webserver/webserver https://webbuild.innovaphone.com/1410593/arm/webserver/webserver
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* chown root:root /apps/manager/manager
* chown root:root /apps/webserver/webserver
* chmod +x /apps/manager/manager
* chmod +x /apps/webserver/webserver
* echo 110000 > /mnt/sda1/label
** this allows the manager to perform an image update again
* /etc/init.d/S92manager start
* now perform an image update and '''afterwards''' update your apps again

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files|Reference14r2:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine|Reference14r2:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or '''130007''' and lower than '''130015''' or your data will be lost!
Please update your App Platform to version 130015 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root

=== All databases ===
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

=== single database ===
sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and the App database is not available during this time

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

== How to recover from a broken File System ==
Sometimes you may find messages in the ''messages'' log file (in ''var/log'') like

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

When the Linux file system is broken, you can try to repair it using some command line Linux tools.

If this doesn't fix your issue, you need to replace the SSD with a new one, re-install the App Platform and any applications and restore your backups.

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code>
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

== Move instance database to external database host ==

In case you want to use an external database server instead of the integrated:

* download a backup of the specific instance over the App Platform Manager
* create a postgresql database on the external host:
** createdb --encoding=UTF-8 exampledb
* restore the backup
** pg_restore -d exampledb backup-exampledb.dump
* change the ownership to a specific postgresql user (which you have to create yourself first)
** psql -d postgres -c "ALTER DATABASE exampledb OWNER TO exampleuser"
* configure the database host, name, user and password on the instance inside the App Platform Manager

Reference13r2:Concept App Service Users

2025-10-08T23:56:53Z

Tfu: /* Apps */

[[Category:Concept|Apps]]

The App Services Users is an App Service which can be installed on an innovaphone App Platform. It is used to administrate the users on a innovaphone PBX and also stores additional profile information. It provides Apps for users and for admins for various purposes.

== Applies To ==

* innovaphone PBX from version 13r1

==Technical Overview==
[[Image:concept_users.png]]
== Apps ==

=== Profile App (innovaphone-profile) ===
This is an App, where the user can edit his own profile data. Here the personal data, the profile picture, the privacy filters and the call forwarding can be edited. Also leave and join groups is possible from this app. The provisioning of Phones, Softphones and Hostdesking can be done too.

Parameters:

;Websocket: to establish the connection with the PbxAdminApi
;TableUsers: gives access to the replication of users from and to the PBX
;Admin: gives access to the PbxAdminApi, needed to get data from the PBX such as the config templates, the DNS name of the PBX, the current domain...
;Services: needed to use the Devices API (com.innovaphone.devices), so the phones can be provisioned
;Devices-API: gives access to the Devices App, which is needed for the provisioning of phones

=== Users App (innovaphone-users) ===
This is an App, where all the users on the App Service Database are displayed (except the ones that have unchecked the Visible attribute on Profile for the current domain).

=== Users Admin App (innovaphone-usersadmin) ===
This is the administation app for the App Service. There all the users and unverified users on the current App Service can be managed. The provisioning of Phones, Softphones and Hostdesking can also be done here for several users at once. The configuration parameters can also be set here (i.e. the password policy ''1.upper case letters | 2.lower case letters | 3.numeric digits | 4.special characters'', SMTP settings, privacy settings...). The verification link will only be valid for 24 hours, after that a new registration must be started.

Starting with 16r1 you also can configure OAuth2 Authentications. You can have a look into our HowTo Article for assistance: [[Howto16r1:Configure OAuth2 E-Mail]]

=== Users APIs (innovaphone-usersapis) ===
This is a hidden App, which provides the Search API (com.innovaphone.search) and the Avatar API (com.innovaphone.avatar). The Search API is used by Phone, Softphone and Chat to search users from the App Service Database. The Avatar API is used by myApps, Phone, Softphone, Chat, Users and Fax to obtain the profile pictures.

Parameters:

;Hidden: UsersAPIs must be a hidden App
;Websocket: to establish the authentication parameters for the Avatar API (com.innovaphone.avatar)

== PBX Manager Plugins ==

=== Users ===

With the Users plugin App objects can be created, edited and deleted for Users, UsersAdmin, UsersAPIs and Profile Apps on the PBX. Some configuration parameters can be edited here too on "Change Configuration". These are:

;Which Profile App use as default: if there is more than one Profile App, the one selected here will be linked to the "Edit Profile" button on myApps.
;Allow to create a user account using a web registration form: if this option is enable, on myApps Login the link to the registration form will be displayed.
;Allow users to reset the password using a web form: if this option is enable, on myApps Login the link to the password forgotten form will be displayed.
;Allow users to delete their own accounts: if this option is enable, a "Delete account" button will be displayed on Profile.

== Import/Export with CSV/XML on Users Admin App ==

=== CSV ===

The CSV import file expects a semicolon ; as field separator. The column/field association can be controlled by a special header line that starts with an ampersand &. In such a line, each column contains a designator which defines the field that the subsequent column values are assigned to. Here is the list of designators:

{| class="table" style="text-align: left;" border=1
|-
! Designator !! Field !! Example !! Remark
|-
| &n || ID || Mario Rossi || Must be unique
|-
| &h323 || Username || mro || Use as key, must be unique
|-
| &fn || First name || Mario ||
|-
| &ln || Last name || Rossi ||
|-
| &e164 || Extension || 13 || Must be unique within the node
|-
| &config || Config Template || Config User ||
|-
| &node || Node || root ||
|-
| &pbx || PBX Name || hq ||
|-
| pseudo/&type || Executive/Secretary || ||
|-
| &dn || Display Name || Dottore Mario Rossi ||
|-
| &em || E-Mail || mario.rossi.dvl-ckl2@class.local || Must be unique
|-
| grp/&name || Group name || group1 ||
|-
| grp/&mode || Group mode || active || Either "active" or "" (empty)
|-
| grp/&dyn || Dynamically in, out or static || in || Either "in" (user is currently in the group), "out" (user is currently off the group) or "" (empty, user is statically in the group)
|-
| grp/&active || Group active || true || Either "true" (active member), "false" (not active member) or "" (empty, same as "false")
|-
| device/&hw || Hardware Id || 0090333e407e ||
|-
| device/&text || Name || Phone IP112 ||
|-
| device/&app || App || phone ||
|-
| device/&admin || PBX Pwd || true || Either "true" (checked), "false" (not checked) or "" (empty, same as false)
|-
| device/&nofilter || No IP Filter || true || Either "true" (checked), "false" (not checked) or "" (empty, same as false)
|-
| device/&tls || TLS Only || true || Either "true" (checked), "false" (not checked) or "" (empty, same as false)
|-
| device/&nomob || No Mobility || true || Either "true" (checked), "false" (not checked) or "" (empty, same as false)
|-
| device/&trusted || Reverse Proxy || true || Either "true" (checked), "false" (not checked) or "" (empty, same as false)
|}

<pre>
&n;&h323;&e164;&config;&node;&pbx;pseudo/&type;&dn;&em;&fn;&ln
Mario Rossi;mro;13;Config User;root;hq;;Dottore Mario Rossi;mario.rossi.dvl-ckl2@class.local;Mario;Rossi
</pre>

=== XML ===

With the XML format, a more complete information of the users can be provided. When importing no validation of the data takes place.

==== User ====

{| class="table" style="text-align: left;" border=1
|-
! Attribute !! Field !! Example !! Remark
|-
| cn || ID || Mario Rossi || Must be unique
|-
| guid || GUID || ac47a659-8a81-4595-9e73-9afba80d9d31 || Must be unique
|-
| h323 || Username || mro || Use as key, must be unique
|-
| fn || First name || Mario ||
|-
| ln || Last name || Rossi ||
|-
| e164 || Extension || 13 || Must be unique within the node
|-
| pwdx || Encrypted password || ||
|-
| apps-my || List of apps attached to homescreen || "users,chat,phone" || Must be separeted by ,
|-
| config || Config Template || ConfigUser ||
|-
| node || Node || root ||
|-
| loc || PBX Name || master ||
|-
| dn || Display Name || Dottore Mario Rossi ||
|-
| email || E-Mail || mario.rossi.dvl-ckl2@class.local || Must be unique
|}

==== Device ====

{| class="table" style="text-align: left;" border=1
|-
! Attribute !! Field !! Example !! Remark
|-
| hw || Hardware ID || SwPh_mro_60929ce7 ||
|-
| text || Name || Softphone ||
|-
| app || App || softphone ||
|-
| admin || PBX Pwd || true || Either "true" (checked) or not displayed (not checked)
|-
| no-filter || No IP Filter || true || Either "true" (checked) or not displayed (not checked)
|-
| tls || TLS only || true || Either "true" (checked) or not displayed (not checked)
|-
| no-mob || No Mobility || true || Either "true" (checked) or not displayed (not checked)
|-
| trusted || Reverse Proxy || true || Either "true" (checked) or not displayed (not checked)
|}

==== Allow ====

{| class="table" style="text-align: left;" border=1
|-
! Attribute !! Field !! Example !! Remark
|-
| name || Name of the visibility filter || @test1.com ||
|-
| online || Online || true || Either "true" (checked) or not displayed (not checked)
|-
| visible || Visible || true || Either "true" (checked) or not displayed (not checked)
|-
| presence || Presence || true || Either "true" (checked) or not displayed (not checked)
|-
| otf || On the phone || true || Either "true" (checked) or not displayed (not checked)
|-
| note || Presence note || true || Either "true" (checked) or not displayed (not checked)
|-
| dialog || Calls || true || Either "true" (checked) or not displayed (not checked)
|-
| ids || Calls with Number || true || Either "true" (checked) or not displayed (not checked)
|}

==== Grp ====

{| class="table" style="text-align: left;" border=1
|-
! Attribute !! Field !! Example !! Remark
|-
| name || Name of the group || grp1 ||
|-
| mode || Active || active || Either "active" (checked) or not displayed (not checked)
|-
| dyn || Dynamically in, out or static || in || Either "in" (dynamically in), "out" (dynamically out) or not displayed (static)
|-
| active || Active || true || Either "true" (checked) or not displayed (not checked)
|}

==== Cd ====

{| class="table" style="text-align: left;" border=1
|-
! Attribute !! Field !! Example !! Remark
|-
| type || Call diversion type || cfu || Either "cfu" (always), "cfb" (busy) or "cfnr" (no response)
|-
| bool || Boolean || booltest ||
|-
| bool_not || Not || true || Either "true" (checked) or not displayed (not checked)
|-
| src || Filters applied || <src type="do"><ep e164="789" ext="true" fwd="clid"/></src> ||
|-
| ep || Name/Number to forward the call || 1234 || h323 or e164
|}

==== Fork ====

{| class="table" style="text-align: left;" border=1
|-
! Attribute !! Field !! Example !! Remark
|-
| hw || Hardware ID || Smartphone ||
|-
| bool || Boolean || booltest ||
|-
| bool_not || Not || true || Either "true" (checked) or not displayed (not checked)
|-
| e164 || Number || 1234 ||
|-
| h323 || Name || user0 ||
|-
| mobility || Mobility object || Mobility ||
|-
| delay || Delay || 30 ||
|-
| min || Min-Alert || 10 ||
|-
| max || Max-Alert || 20 ||
|-
| cw || Call-Waiting || true || Either "true" (checked) or not displayed (not checked)
|-
| off || Disable || 20 || Either "true" (checked) or not displayed (not checked)
|}

==== Example ====

<syntaxhighlight lang="html5">
<?xml version="1.0" encoding="utf-8"?>
<info>
<user cn="Mario Rossi" guid="ac47a659-8a81-4595-9e73-9afba80d9d31" h323="mro" fn="Mario" ln="Rossi" e164="13" pwd="********" pwdx="...87"
apps-my="users,chat,phone,dev%3ASwPh_mro_60929ce7" email="mario.rossi.dvl-ckl2@class.local" node="root" loc="master" config="ConfigUser">
<device hw="SwPh_mro_60929ce7" text="Softphone" app="softphone" admin="true" no-filter="true" tls="true" no-mob="true" trusted="true"/>
<allow name="@test1.com" visible="true" presence="true" otf="true" note="true" dialog="true"/>
<allow name="department" grp="true" visible="true" _online="true" dialog="true" ids="true"/>
<grp name="grp1" mode="active" dyn="in"/>
<grp name="grp2"/>
<cd type="cfu" bool="booltest" src="<src type="do"><ep e164="789" ext="true" fwd="clid"/></src>">
<ep e164="1234"/>
</cd>
<cd type="cfb">
<ep h323="user0"/>
</cd>
<fork hw="Smartphone" e164="1234" bool="booltest" mobility="Mobility" delay="20" min="20" max="20"/>
</user>
<user cn="User0" guid="ac47a659-8a81-4595-9e73-9afba80d9d31" h323="user0" e164="300" pwd="********" pwdx="...87" apps-my="apps,main,chat,users" node="root" loc="master">
</user>
</info>
</syntaxhighlight>

Reference14r1:Concept App Service Reports

2025-10-08T23:53:24Z

Tfu: /* Configuration */

[[Category:Concept|Apps]]

The App Service Reporting is an App Service which can be installed on an innovaphone App Platform. It is used to provide call lists in myApps and to create call reports.

== Applies To ==

* innovaphone PBX from version 13r1

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

== Apps ==

=== Reports App (innovaphone-reporting) ===
This is the Reporting UI App.

[[File:Reference14r1_Concept_App_Service_Reports_App.png|600px]]

Legend of used symbols:

[[Image:Reporting_symbol_legend.png]]

You can display all or filtered calls and sort them by time, name, call and alert duration.
The amount of displayed entries in the UI is limited to 10000.

Parameters:

;Websocket:

=== Call List App (innovaphone-calllist) ===
This is the Call list App.

Parameters:

;Websocket:

=== Call List API (innovaphone-calllist-api) ===
This is an App, which provides the Call list API (com.innovaphone.calllist). This API can be used to find the recent calls of a user.

Parameters:

;Websocket:

== PBX Manager Plugins ==

=== Reporting ===

With the Reporting plugin App objects can be created, edited and deleted for the provided Apps.

====Configuration====

Following configuration options are offered:

* CDR handling
** automatic deletion of CDRs
** deletion interval - default is 90 days. If configured, deletion is performed at 3 a.m. UTC.

* Account for CDR authentication

* Account for authentication for external apps (When username and password are defined external app will be able to fetch PDF,XML or CSV report with HTTP GET requests using HTTP Authentication.)

* SMTP Configuration
When reports should be send by email the SMTP Server address and the login credentials must be specified. An example configuration can be seen on the screen shot.
 
 
[[File:Reference14r1_Concept_App_Service_PBX-Manager-Plugin.png|400px|SMTP Configuration]]

Starting with 16r1 you also can configure OAuth2 Authentications. You can have a look into our HowTo Article for assistance: [[Howto16r1:Configure OAuth2 E-Mail]]

== Concepts ==
===Database Structure===

====cdrs====
The service receives CDRs in XML format at the URL http://AP-IP/DOMAIN/reporting/cdr . That URL must be configured at the PBX.

Each received cdr-xml is formed by a cdr tag and an undefined number of event and group tags.
(Refer to: [[Reference13r3:Concept_Call_Detail_Record_CDR_PBX|CDR]])

This section is composed by four tables: cdrs, events, groups and cdr_properties.
The first three tables contain the corresponding fields to store the information contained in the cdr, event and group tags. 
Each CDR represents the call in the view of one PBX object. So there might be multiple CDRs for one call if multiple PBX objects are used within the call.

* '''cdr fields:'''
** id
** guid
** user_guid
** conf
** sys
** pbx
** node
** phys
** device
** h323
** e164
** cn
** dn
** email
** dir
** external
** licensed
** more_calls: set inside the CDR XML if there are multiple calls for the same call and user (e.g. multiple registrations)
** conn_duration
** alert_duration
** call_duration
** billing_duration
** utc_stamp: unix timestamp in '''milliseconds''' since 1970
** cause
** remote_e164
** remote_h323
** remote_dn
** call_list: CDR which is suitable for calllist or report queries (this flag is set depending on data received inside a CDR)
** missed_call
** status: the final state of the CDR (co: connected, al: alerting, er: error, bu: busy)
** further: flag is set if CDR has been cancelled with cause 26 (non selected user clearing) indicating that there will be another more suitable CDR for the same call
** user_id
** callback_e164
** callback_h323
** callback_dn
** callback_time
** remote_clir: this flag is set if the remote side suppresses the calling information (number, name etc.)

* '''event fields:'''
** id
** cdr_id
** msg
** ext
** e164
** h323
** dn
** conf
** cause
** time: the kernel uptime of the sending gateway in seconds. Substract time from a newer event (higher id) of a previous event to get the elapsed seconds inbetween.
** clir

* '''group fields:'''
** id
** name
** active
** type
** cdr_id

'''id''' field is assigned by postgresql for each entry and has nothing to do with the information present in the cdr. It is different for each entry inside the table.

The events table has two additional fields, called cdr_id, to associate these events to the corresponding cdr entry and order_index to keep their position inside the cdr.
Groups table has also the cdr_id field to associate the group entries to the corresponding cdr and events entries.

The table cdrp_properties from version 10 has been removed. Most columns can be now found directly in the table cdrs.
If you need the callflow in a similar way, you can JOIN the events table (GROUP BY cdr_id) and run a query which creates an array string from the events table:

array_agg(array[ev.msg, COALESCE(ev.e164,''), COALESCE(ev.h323,''), COALESCE(ev.dn,'')] ORDER BY ev.id) AS callflow

====cdr_users====

This table contains a timestamp '''missed_calls_time''' for the last call list access by a user '''sip'''. It is used to retrieve information about missed calls since the last use of mypbx/myApps. 
The timestamp '''clear_report_time''' indicates the last clearance time. 

===Database query samples===

====Calllist query====

SELECT cdr.id, cdr.cn, cdr.conf, dir, external, alert_duration, call_duration, conn_duration, billing_duration,
sys, pbx, node, phys, cdr.cause, utc_stamp, status, further,
CASE WHEN remote_clir THEN <nowiki>''</nowiki> ELSE remote_e164 END,
CASE WHEN remote_clir THEN <nowiki>''</nowiki> ELSE remote_h323 END,
CASE WHEN remote_clir THEN <nowiki>''</nowiki> ELSE remote_dn END,
callback_e164, callback_h323, callback_dn, callback_time, cdr.e164, cdr.h323
FROM cdrs cdr
JOIN cdr_users cu ON cdr.user_id = cu.id
WHERE cu.cn NOT IN ('_ADMIN_','_KADMIN_','_EXTERN_','_UNKNOWN_','_MASTER_','_STANDBY_','_ACTIVE_','_MOH_','_HTTP_','_CONF_') AND (cu.sip = 'sip' OR cu.guid = '00000000000000000000000000000000')
AND cdr.call_list = true
AND (cu.clear_report_time IS NULL OR utc_stamp > cu.clear_report_time)
ORDER BY utc_stamp DESC, cdr.id DESC LIMIT '5' OFFSET '0'

====Reporting query====

WITH inp AS (SELECT 1611187200000::BIGINT AS from, 1611211143042::BIGINT AS to, 'sip'::VARCHAR AS sip, 'cn'::VARCHAR AS cn, 'TRUE'::BOOLEAN AS check_objects)
SELECT cdr.id, cdr.cn, cdr.conf, dir, external, alert_duration, call_duration, conn_duration,
billing_duration, sys, pbx, node, phys, cdr.cause, utc_stamp, status, further, remote_e164,
remote_h323, remote_dn, callback_e164, callback_h323, callback_dn, callback_time, cdr.e164,
cdr.h323, cdr.dn,
array_agg(array[ev.msg, COALESCE(ev.e164,<nowiki>''</nowiki>), COALESCE(ev.h323,<nowiki>''</nowiki>), COALESCE(ev.dn,<nowiki>''</nowiki>), 'false'] ORDER BY ev.id)
FROM inp, cdrs cdr
JOIN cdr_users cu ON cdr.user_id = cu.id
JOIN events ev ON ev.cdr_id = cdr.id
WHERE cdr.call_list = true
AND cdr.licensed = true
AND utc_stamp >= inp.from
AND utc_stamp < inp.to
AND (inp.check_objects=false OR LOWER(cu.sip) LIKE LOWER(inp.sip) OR LOWER(cu.cn) LIKE LOWER(inp.cn))
GROUP BY cdr.id
ORDER BY utc_stamp ASC
LIMIT 10000

=== Database access ===

You have to grant [[Reference14r1:Concept_App_Platform#Database|database access]] in the AP-Platform.
 
The database user and password can be configured for every Reporting instance inside the AP Manager if you edit the instance. 
These database credentials are just used internally and not e.g. inside the PBX App Objects.

==== Write an own app ====

Currently there can be two ways for an own App:

* You receive the CDRs from the CDR interfaces yourself and store them into your own database with your own structure.
* You hand the Reporting database credentials to your own App and connect directly to the Reporting database within your own App. This saves you the parsing and storing of the data, but you must maintain your queries if something in the Reporting database is changed. It is important, that you should just access this data '''readonly''' and that you do '''not modify''' table data!

Example for automatic download of existing CSV files:

#establish a web socket connection for reporting using [[Reference13r2:Concept_Talking_to_the_v13_Application_Platform_using_PHP | PHP ]]
#request the session key with { "mt": "Start" }
#receive the session key which e.g. looks like {"mt": "StartResult", "session": "189", "key": "552ca6fe05a19"}
#while the web socket connection is established, a GET request using received data can be sent like this:
#*<nowiki>http://AP-IP/DOMAIN/reporting/reports/report-20200408-1015.csv?session=189&key=552ca6fe05a19&lang=de&tz=Europe/Berlin&type=csv&sip=&from=1586304000000&to=1586333749607</nowiki>

==== Remote Interface ====

You can retrieve the PDF/XML/CSV report with a remote interface. After the configuration in the PBX Manager Plugin (Set user name and password under '''[[Reference14r1:Apps/PbxManager/App_Reports#Account_for_external_applications| Account for external applications]]''') make a GET HTTP request to http://AP-IP/DOMAIN/reporting/ext/ with the following parameters:

from : the from date/time as a local timestamp
to: the to date/time as a local timestamp
type: the return format, allowed values:
xml
pdf
csv
[anonymous]: anonymizes names and numbers ("true" or "false"), default is true

[filterNames]: use a filter with its name. You can use multiple filters inside of a filter array filterNames=[{"name":"filter1"},{"name":"filter2"},...]
[lang]: the language, e.g. "en" or "de"
tz: the time zone corresponding to the time stamp
[sip]: the SIP or Cn (Long Name) of the object you want to filter for

Parameters in [] are optional.

Example:

http://ap.innovaphone.com/innovaphone.com/reporting/ext/report.xml?lang=en&tz=Europe/Berlin&type=xml&sip=&from=1692136800000&to=1698056896320&filterNames=&anonymous=true

Gets all records between 2023-08-16 and 2011-10-23 in time zone Europe/Berlin.

http://ap.innovaphone.com/innovaphone.com/reporting/ext/report.xml?lang=en&tz=Europe/Berlin&type=xml&sip=&from=1692136800000&to=1698056896320&filterNames=[{"name":"Only Incoming Calls"}]&anonymous=true

Gets all "Incoming calls" records between 2023-08-16 and 2011-10-23 in time zone Europe/Berlin. (The filter must be defined beforehand)

===CSV, XML or PDF export===

There is no limit of entries anymore concerning the export as XML,CSV or PDF (Previously there was a limit of 20000 entries). But keep in mind, that the creation of large reports will take a considerable amount of time and load. Depending on your hardware the download of very large reports may take several minutes and currently no feedback is given by the service when a "Download report" request is made. (This will be added in future versions).

The field description applies to the '''CSV''' columns!

* time: the node contains a formatted time string of the local time
* object: the PBX object name (also called cn)
* conference id: the conference id of the call
* call: '''int''' (internal) or '''ext''' (external) call
* Original Called,: In case of Call flow; The original called device
* Diverting,: In case of Call flow; The diverting device
* Transferring,: In case of Call flow; The transferring device
* node: the node of the PBX object
* pbx: the pbx of the PBX object
* phys: physical location name of the pbx
* cause: the decimal disconnect reason of the call (see [[Reference:ISDN_Cause_Codes]])
* remote:
** outgoing calls -> dialed endpoint
** incoming calls -> first ep2 above entry event or entry event if this is the first one
** incoming calls with incoming transfer after entry event -> transfer target
* status:
** outgoing calls -> best found status in call flow
** incoming calls -> status of entry event
** '''co''' (connected)
** '''al''' (alert)
** '''er''' (error)
** '''bu''' (busy)
* type: the type of the entry event or, if not set, the type of the next event, if given
** empty: direct call
** '''ct''': call transfer
** '''cf''': call forward
** '''cct''': call transfer with consultation
** '''pu''': call pickup
* direction: '''o''' (outgoing) if the first event is the entry event and the caller is ep1
* direction: '''i''' (incoming) if not o
* alert-duration: alert time
*Billing Duration: the duration, a user must be billed for
** outgoing call -> duration from the first event until the last event in the flow
** incoming call -> duration from the first transfer/forward event until the last event in the flow
* call-duration/Call Duration (Total): duration of the whole call, e.g. with the duration of a subsequent transfer
* conn-duration/Call Duration (User): just the time, the user was connected. Duration from the entry event until the event, where the local endpoint isn't connected any more
* Further Registration: If more than one devices is registered to the same object, each device creates a CDR. This field identifies the additional CDRs for the same call
* Object Info: combination of object names and number
* Date: extracted date only from the time_string
* Time_2: extracted time only from the time_string

Note that a CSV export doesn't contain the whole call flow!

===Filters===

==== General ====

Filters are set up to create reports based on certain conditions. ( Attention must be taken as the filters are AND combined to the date filters '''From''' and '''To''' and the quick filter '''Name or SIP'''). A filter can have multiple conditions (Name, Number, Group, PBX Name. Time... ) and multiple filters can be combined on report creation. Multiple filters are OR combined. So in the following picture you would see all incoming calls plus all transferred calls plus all calls made on the PBX Berlin.
A filter has a unique name.

[[Image:Reference14r1_Concept_App_Service_Reports_Filters.png|600px]]

There are five or seven condition sections depending on what is selected under States. Conditions inside same section are OR associated while different sections are AND associated.

''(Name == Terra OR Name == Uranus) AND (PBX == sifi) AND (Number == 0049%)''

==== SQL Wildcard ====

Like seen in the previous line you may use the SQL wildcard "%" which matches everything (so Inn% matches Innovaphone, Inno, Innovahone Gmbh ...) and corresponds to the better known "*" wildcard.

==== Base filter ====

If you select another filter as base filter, the conditions of the base filter are implicitly AND conjuncted, when the current filter is used.
So if the base filter defines two PBX values, e.g. "Berlin" and "Hamburg" and the current filter defines one PBX value, e.g. "Berlin", only objects of the PBX "Berlin" will be filtered:

''(pbx="Berlin") AND (pbx="Berlin" OR pbx="Hamburg")''

'''Anonymous'''

If you check this flag, a report created with this filter or with a filter, where this filter is a base filter, will by anonymized.

'''Local'''

Define one ore more conditions for the local party, defined by:

Name or SIP: the cn/PBX object name/sip
Number: the number
Groups: a group of the PBX object

'''Remote'''

Define one or more conditions for the remote party, defined by:

Name: cn or sip
Number: the number
Remote display name: the display name

'''PBX'''

Define one ore more conditions for the PBX, defined by:

PBX: the PBX name
Node: the node name

'''States'''

No Response
Connected
Busy
No Channel

'''Directions'''

Incoming
Outgoing
Transfer: calls, which have been transferred to the current local party (calls which were initiated by a transfer action)
Call Forward: calls, which have been forwarded to the current local party

[[Image:Reference14r1_Concept_App_Service_Reports_Filters_Second_Part.png|300px|thumb|left|Filter Definition lower part]]

'''Call domain'''

Internal calls
External calls

'''Call Duration'''

Time the call was connected.

This condition will be AND with the others if all States are selected.
If Busy, No Channel or No Response is unselected, then the filter will search for Connected calls with connected time greater or smaller than Call Duration.

'''Alert Duration'''

Time the call was ringing independent of the status of the call afterwards.

This condition will be AND with the others if all States are selected.
If Busy, No Channel or Connected is unselected, then the filter will search only for Not Connected Calls that were ringing more or less time than Alert Duration.

'''Report times'''

Define the time where calls should be counted.
You can optionally define the weekday(s) of calls.

'''Using Patterns'''

You can use these PostgreSQL Patterns for every condition.

== Report Mails ==

You can send daily, weekly or monthly emails with attached reports and apply filters on them. There is no limit concerning the size of the reports but keep in mind, that your email provider might not allow attachments exceeding a certain size e.g. 20 MB.
The automatic report generation can be configured here:

[[Image:Reference14r1_Concept_App_Service_Reports_Email.png|300px|thumb|left|Report Email Settings]]

'''User reports'''

Creates for each matching user a separate report
Users are matched by Object (Long Name). A user report only contains calls for this user. The email address of the user is built by its H323 name and the System Name of its PBX (h323@systemname) or determined by the E-Mail field of the user

'''Name'''

Quick filter for the cn/sip

'''Filter'''

Applied filter to the report

'''Output Format'''

PDF,CSV,XML (CSV and XML can be gzip compressed)

'''Displayed Duration'''

used for PDF reports (call duration total/user, billing duration)

'''Interval'''

daily: Mail will be send daily with the automatic period "last day"
weekly: Mail will be send weekly with the automatic period "last week"
monthly: Mail will be send daily with the automatic period "last month"

'''Day'''

the day, at which the report is sent

'''E-mail adresse(s)'''

recipients of the report (comma separated)

'''Compress'''

compress the attachment or not

'''Language'''

language used for the report

'''Sorting'''

sort entries by time, name, call or alert duration

'''Send time'''

the time of a day, when the report is sent

'''Time zone'''

the time zone corresponding to the send time

== Simple Statistics ==

[[Image:Reference14r1_Concept_App_Service_Reports_Statistics.png|300px|thumb|left|Report Email Settings]] The Reports App as well as PDF Reports offer simple statistics where the number of incoming and outgoing calls are displayed as well as their respective total and average call and alert duration. Be aware that a transferred call with multiple participants may be counted multiple times as in fact CDRs are displayed.

==Troubleshooting==
Trace flags for App instance on App Platform:

*App
*App Database
*Webserver traffic (shows the communication with the PBX)
*App Websocket (shows the communication with the client in browser)

Trace flags for myAPPS Client:

*Browser Console

== Known issues ==

=== Missed calls query takes long ===
In some scenerios, the missed calls query takes quite long. 13r3 addresses this issue by adding a new combined index.
You can add this index yourself in earlier version through SSH (as root user):

psql -d reporting_db_name
CREATE INDEX cdrs_user_id_utc_stamp_index ON cdrs (user_id,utc_stamp);

Do not change the index name, as updates to 13r3 will create a second index otherwise!

Reference15r1:Concept App Service Fax

2025-10-08T23:50:53Z

Tfu: /* Mail Configuration (SMTP Server) */

[[Category:Concept|Apps]]

== Applies To ==
* innovaphone PBX from version 15r1

== Overview ==
The App Service Fax is an app service which can be installed on an innovaphone App Platform. It provides sending or receiving FAX documents with the innovaphone PBX and a user app to manage the documents.

== Features ==
* The App Service Fax sends PDF documents as FAX documents and converts received FAX documents to PDF.
* Cover page with user content for outgoing FAX documents.
* The Fax app can forward the received [[{{NAMESPACE}}:Apps/PbxManager/App_Fax|fax documents by mail]], as notification only or with the document in PDF.
* Transmission reports and error notifications
* Contact search by using myApps search API providers, inclusive removing number decorations
* PBX node support
* Using several fax interfaces
* Group fax accounts
* Automatic deletion of older fax documents
* Customized email texts
* Mail2Fax
* [[{{NAMESPACE}}:Apps/PbxManager/App_Fax#Default_settings_for_mail_notifications|Centralized setup]] of mailing notifications
* App API (HTTP Post)

== Requirements ==
* innovaphone App Platform
* Device with a [[{{NAMESPACE}}:Gateway/Interfaces#FAX_interface|FAX interface]]
* One port license to register the fax interface towards the fax object
* A UC or fax license for each PBX user which is allowed to receive or send personal fax documents
* A fax (or UC) license for each group fax account

== Apps ==
'''Fax App (innovaphone-fax)''' 
This app is provided for the users to send fax documents and view or download received documents. The app reads the argument mailbox=<sip name> to work with the given account instead of the user logged in. It uses the com.innovaphone.search API to search for contacts with FAX numbers.

== Technical Overview ==
[[Image:Concept fax.png|concept_fax.png/]]

== Technical Concept ==
The innovaphone fax feature needs three parts:
* An innovaphone PBX with one or more fax objects
* One or more FAX interface registered to fax objects
* The Fax app on the App Platform (AP)

The app service on the AP provides a user app. Users can upload and download PDF documents. The app service converts them from and to a fax protocol compatible file (SFF).
The app service controls calls between the FAX interface and an external remote party. To do this, it requires a websocket connection to the PBX. The FAX interface accesses the file with authenticated WebDAV.
The documents saved in the app service are available with WebDAV with the app instance name as user name and the app instance password as password and in the directories
* <app-web-path>/sff for the SFF files
* <app-web-path>/doc for the PDF files

==== Additional Information ====
* Files of deleted fax jobs are permanently deleted after two weeks.
* The myApps background picture (myapps.png) is also included in all HTML mail bodies with customized mail texts, if these texts contain the string "url(cid:myapps.png)".

== Configuration ==

==== PBX Manager Plugin ====
All possible configurations can be done with the [[{{NAMESPACE}}:Apps/PbxManager/App_Fax|PBX Manager plugin]] of the Fax App. The app service options can be set as well as the corresponding app objects in the PBX can be added, modified or deleted. Additionally, available devices with a fax interface can be found and configured. 
As with any app, the Fax App needs to be assigned to users and [[#Requirements| licensed accordingly]].

==== Mail Configuration (SMTP Server) ====
The fax service has a built-in SMTP server, which is needed for Mail2Fax. Here, you activate the mail reception for the fax service, enter the fax domain and configure the credentials for the authentication against the SMTP server. The mails can contain a subject and body for the cover page, and '''one PDF document can be appended as attachment'''. No cover page is added if both the subject and the mail content are empty. The destination number must be included in the recipient mail address in this format: <destination number>@<fax server domain>. The fax server domain is the app service domain or the configured domain if different. Recipient addresses do not match are discarded.

The supported charsets are UTF-8 and ISO 8859-1 (Latin 1).

As of 14r2 the SMTP server only listens on port 25. STARTTLS is possible.

For the Fax service to receive the mails in the first place, the mailserver needs to forward mails for the fax-domain to the APs IP address.

An example for an Exchange configuration can be found [[Howto14r2:Fax App - Mail2Fax with Exchange 2019|here]]

Starting with 16r1 you also can configure OAuth2 Authentications. You can have a look into our HowTo Article for assistance: [[Howto16r1:Configure OAuth2 E-Mail]]

==== Mail Configuration (SMTP Client) ====
The SMTP configuration is to be set in the Fax App PBX Manager plugin to make mail forwarding, transmission reports and notifications available. Only email addresses of the user configured in his PBX object are used and each user has to enable the several mails in the burger menu of the Fax app.
Available types of mails:
* Forwarding of a received document as PDF
* Incoming notifications without a document
* Error notifications for outgoing fax jobs
* Transmission confirmations
* Transmission reports for outgoing fax jobs as PDF

The mails are sent in the language the user set in myApps when the Fax app was last used, unless the language for mails was explicitly set within the app.

If a failure occurs and mails cannot be sent, the app service retries the mail transmission of a mail every 30 minutes, but no longer than two days.

==== PBX Node Configuration ====
The Fax app object can be assigned to a certain PBX node. If so, the node number is included within the user's fax number.

==== Group Fax Account ====
If a Group Fax app is configured, all users have the same group account with this app, and the same jobs. The mail addresses configured in this Group app are available and used instead of the user's mail addresses.

==== Sharing FAX Interfaces ====
FAX interfaces are normally registered to one app object. Other PBX Fax objects use these fax resources for calls if they are configured as external resource in the objects.

== App API ==
A document to be sent can be uploaded with the HTTP post command. The arguments within the HTTP URL sets the data of the new fax job. The job is created in the context of a user and is shown in the app. If the file is successfully saved, the job is directly queued for sending.

An API key must be configured to enable this feature and to authenticate the command.

Arguments of the HTTP post command in the URL:
* api-key: The configured authentication key. Mandatory.
* user-sip: The SIP of the user which sends the document. Mandatory.
* contact-name: An optional contact name shown in the app as contact (must be url-encoded).
* contact-number: The contact number used for sending the document. Mandatory.
* cover-page-subject: The subject of an optional cover page if should be created (must be url-encoded).
* cover-page-content: The content of an optional cover page if should be created (must be url-encoded).
* cover-page-content-html: If set to true, the cover page content is in HTML.
* app-object: The app object of the PBX used for sending. If not set, any is used.
* file-name: An optional file name of the uploaded file. Not used in the app.

Here an example:

curl -X POST "http://AP-DNS-name/DOMAIN/fax/?api-key=1234&user-sip=vgr&contact-number=00049703173009&cover-page-subject=Hello%20World&app-object=fax" -T testfax.pdf

== Troubleshooting ==
==== Log Files ====
The progress of fax jobs is reported in the log file:

Info job id 58, direction 0, progress 0, result 0

;direction
:0: incoming job
:1: outgoing job

;progress
:0: job created
:1: job queued
:2: job converted
:3: job finished

;result
:0: no error or successfully completed
:1: call aborted, repeating
:2: job stopped with an error
:3: job stopped caused by a conversion failure

==== App Service Log ====
*App
*App WebSocket
*Browser
*SMTP (only if the problem is related to mail forwarding etc.)

==== App Service Logs for Mail2Fax ====
*App
*Smtp
*TLS
*TCP
*DB files
-> Since these options creates huge logs, please just enable for tracing a current problem and deactivate afterward

== Known Issues ==
* '''Important:''' If using Mail2Fax, only '''ONE''' PDF attachment is allowed and can be handled by the Fax service. If multiple attachments are added to an E-Mail, the Faxservice will get in a broken status.
* Enabling of non-T.38 coder (audio-fax) is also possible for T.38-only capable devices.
: Has to be judged by the user himself, if selected fax interface features audio-fax.
* An IPVA is not capable of sending faxes with a non-T.38 coder (audio-fax coder, e.g. G.711A), because it has no DSPs which are needed for an audio-fax. Therefore, ''only'' T.38 faxes work on an IPVA FAX interface.
** '''Important:''' T.38 is to be enabled on ''all'' interfaces are used in the call flow, e.g. FAX, GW, SIP interface.
** '''Important:''' Often "exclusive" is activated on SIP interfaces. This prevents the renegotiation with the provider and T.38 can not be used. Therefore, the "exclusive" flag is to be disabled for such configurations.
* If the name (H.323) of an user is changed in the PBX, the data in the fax service are not accessible for this user and a new account is created for him in the service.
* With 14r1, faxes will be sent with 400dpi per default, and tried with a lower resolution again, if the remote side doesn't support 400dpi faxes. In a 13r3 fax app (no 400dpi support), you will see the first - non working - try, which is the normal behavior, since all faxes (working and non working) are shown in the fax app.

== Related Articles ==
* For a more detailed description about the configuration, please refer to [https://class.innovaphone.com/moodle2/course/view.php?id=1705&topic=0#section-2 the book about fax application setup] as part of our IT Plus Training.
* [[{{NAMESPACE}}:Apps/PbxManager/App_Fax|PBX Manager plugin]] for the Fax App
* [[Howto: Mail2Fax with Exchange 2019]]

Reference16r1:Concept App Connect

2025-10-08T23:47:11Z

Tfu: /* E-Mail configuration */

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

The Connect app is a social intranet tool, which can be used for organization internal collaboration and is part of the [[Reference16r1:Concept App Service Messages|App Service Messages]].

== Applies To ==
* innovaphone PBX from version 16r1

== Features ==
* Post Messages, Reply to Messages
* Integrated Chat
* File Attachments
* Emojis
* Visibility of Messages organized in Zones
* Feed for Messages addressed to you
* Badge Counts for Feed and Chat
* Private Zone
* Search in Messages, with many filter Options
* Like Posts
* Hashtags
* Definition of Channels, based on Zones and hashtags
* Follow (users, Zones, Hashtags, Discussions, Channels)
* Direct/private Posts
* Address Groups or all Users
* Notifications via email or Push Notifications
* Integrated Help
* Translations, automatically or based on Messages
* Welcome Messages
* User Management (set inactive, anonymize, …)
* Different Roles (user, moderator, administrator)
* UC Integration (Presence, initiate calls, initiate Chats)
* [[Reference16r1:Apps/PbxManager/Shared Services|Shared services integration]]
* Onboarding for new Connect users with a guided tour
* Surveys in Connect via [[Reference16r1:Concept_App_Polls|Polls App]]

== Requirements ==
* innovaphone AppPlatform with a running Messages app and valid ntp settings
* innovaphone myApps
* Connect app license for each PBX user, who should use connect

== Connect App UI concepts ==

The Connect UI consists of two major parts. On the left side there is the main navigation, which covers feed, your personal home area, search, chat and more. On the central is the stream. The stream can either show the content of a channel, or a single discussion, entered from the search or the feed.

For each button and icon in the UI, an [[#Integrated Help|Integrated Help]] can be used for better understanding of the corresponding function.

=== Feed ===

In your feed, you will see messages that are specific to you. These can be @ mentions or comments on posts that you follow or to which you have replied.

The feed is seperated into thre lists:
* Inbox
* Noted
* Checked

'''Inbox:''' all pending notifications for you. If your inbox is empty, a placeholder is shown, that there is no current notification. '''Noted:''' all notifications you marked as noted. '''Checked:''' all previously checked notifications

If you click on a notification in your feed, in the stream the message in the corresponding thread will be opened. Also you have three symbols under each notification: 
* star - the noticitation is marked as noted, so you can check it later
* speech bubble with checkmark - all notifications in your feed from the same thread, will be marked as checked
* checked - the particular notification will be marked as checked

=== Home ===

Here you can customize your personal home area with pinned channels, zones and hashtags. 
If there are new and unread meessages inside a pinned channel, zone or followed hashtag since your last visit, a number will be displayed, which indicate unread messages. 
Due to performance reasons, it can happen, that a dot-symbol is shown. If you click on a channel/hashtag/zone, the exact number of unread messages will be displayed.

=== Full text search ===

For all words in the message bodies, an index is built, so that words or sequences of words may be found efficiently.

For a search for multiple words, two modes are implemented. If the search entry is set in quotes, the exact sequence of the word must appear in the message for a message otherwise just all the words must be present.

=== Chat ===
The integrated [[Reference16r1:Concept Chat#Additional Features with license|persistent chat]] feature.
The old separate chat app won't be developed any further and new features and fixes will only be integrated in the connect chat.

If you're having problems with chat after install, make sure that the "Impersonation" option is activated at the connect app object. You find the option at the "App" tab and then at "Grant access to APIs".

To open chat in connect via the old chat icon, enter the app name, which should use app at the [[Reference16r1:PBX/Config/Chat|corresponding field]] on the PBX.

==== General information ====
Instant Messaging is a standard functionality of the innovaphone PBX. The messages are sent using instant messages calls with standard SIP method or proprietary H.323/H.450 facilities. The connect app provides a user interface for chat.
The PBX itself only provides the instant messaging calls and forwarding of the messages. No storing of the messages is provided.

To add additional functionality to chat like storing of chats, group chats or file attachments, the PBX provides an API with the Messages App Object, so that this functionality can be added by an additional App Service. Access to this functionality is also provided to the connect app by an API. Chat can detect the presence of this API. The use of this API must be enabled by a license.

For more technical details, see [[Reference16r1:Concept Chat|here]].

==== Chat Features ====

If the user has a chat license, additional features are available, which need the external Messages service:

;Storing of Chats: No need to the destination of a chat to be online. The message can be sent and read asynchronously
;Badge Count: A badge count is displayed for unread messages. To clear the badge count, the chats containing new messages must be opened
;Group Chats: Groups can be defined and messages sent to these groups. The own chat groups can be seen in the burger menu at "Chat Groups"
;Reactions: React with likes and emojis to chat messages
;Direct Answering: Send a direct answer to a specific message
;Forwarding: Forward chat messages to other chat user/groups
;File Attachments:
*File attachments can be added to chat messages. Sending of attachments can be prevented using the [[{{NAMESPACE}}:PBX/Config/General#Common|option "Chat no Attachments"]].: 
*When an attachment is downloaded, the user gets feedback that the download has been started and cannot start it again for 5 seconds. This prevents the user from clicking on it again and again because he might think it won't work. 
*If the attachment is a video (at the moment recognized by the file name extension .mp4, .avi, .mov, or .wmf), the videocam be played directly in connect and doesn't have to be downloaded first.
** '''Only''' in Browser Mode, since h264 is not implemented in the used Chromium on the native client and the iPhone App

==== The Badge Count ====

The badge count on the chat tab inside connect is used to indicate the number of unread incoming chat messages. A chat message is considered read if the chat discussion is already open and the input field for a new message has the focus when the chat message arrives or if the chat discussion is opened. If a discussion inside the chat tab is opened, all messages of this discussion are considered read. If the chat tab is opened, but the discussion with unread messages is not opened, the badge count will not be reset to make sure this message is not overlooked.
These rules result in the following sequences, when a chat message arrives:
;Chat tab closed: The chat tab is loaded (if connect is set as default chat app) and a badge count is set. When the chat tab in connect is opened, a badge count is displayed at the respective discussion. The badge count is cleared when the chat tab and the respective discussion inside the chat app is opened.
;The chat tab is opened with a different discussion: A badge count is set at the chat tab and at the respective discussion. The badge count is cleared when the discussion is opened.
;The chat tab is opened with the same discussion, but message input does not have focus: Badge Count is set at the chat tab and at the discussion. The badge count is reset as soon as the message input gets the focus
;The chat tab is opened with the same discussion and message input has focus: No badge count is set
;Chat message is read on a different device: Badge count is reset on chat tab and on the respective discussion

=== More ===
==== Channels ====
Lists all available channels. These can be selected and pinned on the home screen. 
Also new channels can be created.

===== Channel customizing =====
A Channel can be customized with a name, banner and a description. The image for the banner should be at least 1412 x 68 pixels in size so that it does not look pixelated on Full HD screens (preferably even twice as large for higher resolutions).

 But beware: The banner images are currently automatically cropped or duplicated depending on the available screen space (no matter how large the image is), which means that images are cut off (depending on the device on which the user sees the image). This is why color gradients or graphic seamless patterns work best. Text, photos of people or objects are therefore not recommended. However, landscape images (such as typical Windows backgrounds) seems to be fine.

==== Zones ====

Each App within the PBX, that has access to connect defines a zone within messages, named as the App Object. This way, each App has its private zone within Messages, so that a channel maybe defined especially for messages from this App. 
The access to these zones is defined by the access to the Apps. In addition, subzones to these zones may be defined. These subzones can be configured within the Messages App. For each subzone, it can be defined separately which users or groups of users have access. The groups defined in the PBX are used for this purpose.

==== Tags ====
Tags can be attached to messages for search and filter purposes. The user can assign tags in the form of hashtags within the message text. Tags are valid across zones. There are mechanisms to filter messages based on tags

==== User ====
List of all available connect user.

==== Groups ====
List of all available connect groups, which are active groups inside the PBX.

==== Following ====
List of hashtags, which the user follows and therefore get notifications in his feed.

==== Noted ====
All overall messages you marked as noted (not including noted messages in your feed).

==== Connect Tour ====
New users can familiarize themselves with Connect and its features through a guided tour of the app. A small tutorial with simple "tasks" that reflect real-world usage, similar to an introductory tutorial in a video game or certain apps. 

== The Stream ==

The central part of the UI is the main message stream. It displays the messages from the selected channel or from a specific discussion. It is used to post messages. When messages are posted, tags are assigned automatically so that the message fits to the selected channel or the message is added to the selected discussion. Unread messages are marked. A click from the user is needed to mark a message as read. A message marked as read in the context of one channel, it appears as read in all matching channels. 

The display of messages is organized in discussions. Initially, only the first message of a discussion is displayed. By click on the respective control, the discussion is expanded, so that all messages of the discussion are displayed.

Messages within a discussion are always displayed in their chronological order.

Messages can be posted in response to other messages. When a response is posted, it is always displayed at the end of the discussion, even if it was a response to an early message of the discussion. To identify to which message the response was posted, a control is provided at a displayed message to hide all messages of the discussion except the messages to which this message was a response.

If [[#Chat|chat]] is used, the central part is also used by chat for the chat messages. The list of available chats is listed on the left side, where the feed in connect is placed.

=== Integrated Help ===
In the top right corner is a question mark (?) visible. If clicked, question marks appear all over the UI. If you click on one of them, a popup with an explanation appears of what these sections are for.

To deactivate the integrated help, just click on the question mark in the upper right corner again.

=== myApps Assistant App ===
The myApps Assistant App can be integrated inside connect, to access a remote large language model (LLM). 
For more information, see [https://wiki.innovaphone.com/index.php?title=Reference16r1:Concept_App_Service_myApps_Assistant the corresponding concept article]

[[image:connect_button_assistant.png|connect_button_assistant.png/|connect_button_assistant.png/]]

=== Direct/Group Messages ===
To address a user directly, simply write a message a add an ''@<username>''. You will also get a list of users you can address to select from, after just writing an ''@''. If you've selected the user, just press enter. After the message is sent, the user will get a notification in his feed, and by clicking on that, connect will directly jump to that specific message. 
'''Important:'''So that a user can be tagged, the user has to open the Connect app at least once.

To address a whole group of users, you have to write ''@@'' and then select the listed group. The list of groups is the list of groups, which exist inside the PBX. The groups need the "active" option activated in the users' configuration, so it can be addressed. 
After sending the message, all users who are members of the tagged group, will get a notification in their feed inside Connect.

To address all connect users at once, simply add ''@@'' without selecting a group. 
This message will address all connect users.

=== Likes ===

User can add likes to messages. The likes are displayed in the notification area of the UI

=== E-Mail Notifications ===

An email connector can be configured within the messages app, which is used to send emails to notify a user of a new message. There are several conditions under which a notification is sent:
;Notify: If a user is notified within the message with @<user> an email notification is sent as well
;Reply: A message posted as reply to a message from the user results in a email notification. This happens for any posts to a discussion, the user has posted to regardless if the reply was to a message of the user directly or any other message of the discussion

== Configuration ==

==== PBX Settings Plugin ====
*open the PBX Settings plugin for the Messages app
*click on "add App"
*select "Connect"
*enter an appropriate (Long)Name and SIP name ("Connect" and "connect" for example)
*choose the config templates, which should distribute the app to the user, as well as grant administrator and moderator mode
*click on "OK"

The app object is now created in the PBX and automatically connected to the Messages app instance.

'''Important:''' If the app object for connect was created manually, make sure, to activate the following options in the ''App'' tab: '''Websocket''', '''PbxSignal''', '''PbxApi''' and '''Impersonation''' (for Chat)

==== Connect Admin-Mode ====
A user who has access to the admin mode of connect has the ability to set additional options in the burger menu:
* [[#Manage users|Manage users]]
* [[#Manage Groups|Manage groups]]
* [[#Zones 2|Zones]]
* [[Reference16r1:Apps/PbxManager/Shared Services|Federation Domains]]
* [[#E-Mail configuration|E-Mail configuration]]

To get the admin access mode, a user simply needs to get the ''connect~admin'' app granted in the user object.

[[image:connect_admin_mode.png|connect_admin_mode.png/|connect_admin_mode.png/]]

==== Connect Moderator-Mode ====
A user who has access to the moderator mode of connect has the ability to set additional options in the burger menu:
* [[#Hashtags|Hashtags]]
* [[#Welcome post|Welcome post]]
* [[#Manage users|Manage users]] (read only)
* [[#Manage groups|Manage groups]] (read only)

To get the moderator mode, a user simply needs to get the ''connect~moderator'' app granted in the user object.

[[image:connect_moderator_mode.png|connect_moderator_mode.png/|connect_moderator_mode.png/]]

==== connect admin-service mode ====
Used by other apps to be able to post to connect. For example, the [[Reference16r1:Concept App Service Projects|Projects App]].

Needs to be activated at the connect app object, and the app object which should post to connect.

==== Options in detail ====

===== Hashtags =====
Hashtags can be renamed and corrected. 
By doing this, all occurrences are changed. (This can lead to many feed entries, since all affected posts are edited) 
You can also combine two hashtags by renaming one to the same value as the other. 

[[image:Connect_moderator_hashtags_overview.png|thumb|none|300px|connect_moderator_hashtags_overview.png/|connect_moderator_hashtags_overview.png/]]
[[image:Connect_moderator_hashtags_detail.png|thumb|none|300px|connect_moderator_hashtags_detail.png/|connect_moderator_hashtags_detail.png/]]

===== Welcome post =====
Moderators can create automated private welcome posts with useful information for new users. These posts are sent as private messages to help users get started.

===== Manage users =====
All PBX users with configured access to the connect app can open it up. 
Inside the Connct app users are created, after they accessed it once. 
 
If users are deleted in the PBX, they also need to be deactivated in connect or else, they still can be addressed. (only possible in connect '''admin mode''') 
-> the same applies to '''groups'''. So if a group is deleted in the PBX, the group needs to be disabled in connect.
===== Manage groups =====
Groups can be defined in the PBX, which can then be used in connect to address multiple users at once. You must use @@<groupname> to do this. The user receiving such a message must be an active member of this group.

If groups are deleted in the PBX, they also need to be deactivated in connect or else, they still can be addressed. (only possible in connect '''admin mode''') 
-> the same applies to '''users'''. So if a user is deleted in the PBX, the user needs to be disabled in connect.

===== Zones =====
An administrator can define a zone that is only visible to a certain number of people. A good example of such a zone would be Human Resources or Management.

To create it, open ''Access Rights'' in the burger menu and click the + button. Configure a name and SIPid for this zone. While the name can be chosen freely, the SIPid must have a specific syntax. The SIPid must start with the Connect object name, followed by a question mark and then a short identifier. 
So for a "Human Ressources" Zone, the syntax could be: '''connect?human-ressources''' 
Please note that the normal rules for SIPid's apply here. A simple rule of thumb is to use only A-Z, a-z, 0-9, and . (period) and - (hyphen). However, the name must not start with a . (dot). Although it is not strictly required, we recommend not using uppercase letters.

[[image:connect_zones.png|connect_zones.png/|connect_zones.png/]]

After creating a zone, you can assign the zone to users or groups.

===== E-Mail configuration =====
For Connect to send E-Mails to tagged users/groups, you have to enter valid SMTP settings here.

'''Example:'''

[[image:connect_smtp_settings.png|connect_smtp_settings.png/|connect_smtp_settings.png/]]

''Client'': this entry will create a clickable link in the received mail, where after clicking, myApps will automatically open the conversation in the Connect app

''App URL'': This will create a web link, which jump to the conversation in your default browser

''OAuth2'': Alternatively OAuth2 credentials to authenticate for e-mail sending. See [[Howto16r1:Configure_OAuth2_E-Mail]].

== Troubleshooting ==
==== App Service Log ====
*App WebSocket
*Database

== Related Articles ==

[[Reference16r1:Concept App Service Messages]] 
[[Reference16r1:Concept Chat]] 
[[Reference16r1:Apps/PbxManager/App Messages]]

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T22:27:55Z

Tfu: /* Related Articles */

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

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

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T22:27:01Z

Tfu: /* Related Articles */

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

== 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 ==
* https://wiki.innovaphone.com/index.php?title=Reference16r1:PBX/Config/Authentication
* https://wiki.innovaphone.com/index.php?title=Reference16r1:Apps/PbxManager/Email

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T21:47:44Z

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)
* '''Google''': Google, with interactive authorization
* '''Google Service Account''': Google, without interactive authorization (previously generated Private Key ID and Private Key must be provided)
* '''Client secret post''':
* '''Private key jwt''':

== 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]]
The private key jwt OAuth2 flow can be configured generically as well.[[File:OAuth2PrivateKeyJWT.png|none|thumb|600x600px|/OAuth2PrivateKeyJWT.png|/OAuth2PrivateKeyJWT.png]]

== Related Articles ==
https://wiki.innovaphone.com/index.php?title=Reference16r1:PBX/Config/Authentication

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T21:34:18Z

Tfu: /* Principle */

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

== 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]]
The private key jwt OAuth2 flow can be configured generically as well.[[File:OAuth2PrivateKeyJWT.png|none|thumb|600x600px|/OAuth2PrivateKeyJWT.png|/OAuth2PrivateKeyJWT.png]]

== Related Articles ==
https://wiki.innovaphone.com/index.php?title=Reference16r1:PBX/Config/Authentication

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T14:38:49Z

Tfu: /* Exchange admin center */

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

== 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]]
The private key jwt OAuth2 flow can be configured generically as well.[[File:OAuth2PrivateKeyJWT.png|none|thumb|600x600px|/OAuth2PrivateKeyJWT.png|/OAuth2PrivateKeyJWT.png]]

== Related Articles ==
https://wiki.innovaphone.com/index.php?title=Reference16r1:PBX/Config/Authentication

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T14:38:24Z

Tfu:

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

== 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 (<nowiki>https://admin.exchange.microsoft.com</nowiki>).
[[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]]
The private key jwt OAuth2 flow can be configured generically as well.[[File:OAuth2PrivateKeyJWT.png|none|thumb|600x600px|/OAuth2PrivateKeyJWT.png|/OAuth2PrivateKeyJWT.png]]

== Related Articles ==
https://wiki.innovaphone.com/index.php?title=Reference16r1:PBX/Config/Authentication

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T14:03:08Z

Tfu: /* Microsoft 365 */

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

== Microsoft 365 ==
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]]
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]]
Login to the Exchange admin center (<nowiki>https://admin.exchange.microsoft.com</nowiki>).
[[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]]
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 ==
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]]
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]]
The private key jwt OAuth2 flow can be configured generically as well.[[File:OAuth2PrivateKeyJWT.png|none|thumb|600x600px|/OAuth2PrivateKeyJWT.png|/OAuth2PrivateKeyJWT.png]]

== Related Articles ==
https://wiki.innovaphone.com/index.php?title=Reference16r1:PBX/Config/Authentication

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T14:00:31Z

Tfu:

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

== Microsoft 365 ==
Log in to Microsoft Azure Portal (<nowiki>https://portal.azure.com</nowiki>) 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]]
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]]
Login to the Exchange admin center (<nowiki>https://admin.exchange.microsoft.com</nowiki>).
[[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]]
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 ==
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]]
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]]
The private key jwt OAuth2 flow can be configured generically as well.[[File:OAuth2PrivateKeyJWT.png|none|thumb|600x600px|/OAuth2PrivateKeyJWT.png|/OAuth2PrivateKeyJWT.png]]

== Related Articles ==
https://wiki.innovaphone.com/index.php?title=Reference16r1:PBX/Config/Authentication

Howto16r1:Configure OAuth2 E-Mail

2025-10-08T13:59:43Z

Tfu:

{{FIXME|reason=This product is in the beta phase and is not yet finished}}

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.

== Microsoft 365 ==
Log in to Microsoft Azure Portal (<nowiki>https://portal.azure.com</nowiki>) 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]]
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]]
Login to the Exchange admin center (<nowiki>https://admin.exchange.microsoft.com</nowiki>).
[[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]]
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 ==
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]]
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]]
The private key jwt OAuth2 flow can be configured generically as well.[[File:OAuth2PrivateKeyJWT.png|none|thumb|600x600px|/OAuth2PrivateKeyJWT.png|/OAuth2PrivateKeyJWT.png]]

== Related Articles ==
https://wiki.innovaphone.com/index.php?title=Reference16r1:PBX/Config/Authentication

Reference16r1:Services/Logging

2025-10-06T12:20:56Z

Tfu: /* Alarms and Errors as Email */

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
== Log Server ==
External '''logging''' is disabled by default (Off). You can still view log messages in real time (see [[Reference7:Administration/Diagnostics/Logging|Logging]]), but messages are not stored or sent to an external destination.

Available ''Type''s:

{|
|valign=top nowrap=true|'''Off:'''
| Logging is disabled.
|-
|valign=top nowrap=true|'''TCP:'''
| The device transmits the syslog entries using a TCP connection.
* In the '''Address''' field, the remote IP-address is entered.
* In the '''Port''' field, the remote port is specified.
|-
|valign=top nowrap=true|'''SYSLOG:'''
| The syslog entries are transmitted to a syslog recipient (also referred to as syslogd, syslog server or syslog daemon).
* In the '''Address''' field, the IP-address of the syslogd server is entered.
* In the '''Class''' field, the syslog message class for the syslog entries sent is entered. The class is a numeric value between 0 and 7, it will be used as ''Facility'' (0 => local0, ... 7 => local7). The ''Severity'' field will always be 6 (informational). See [http://de.wikipedia.org/wiki/Syslog wikipedia.org/wiki/Syslog] for details.
|-
|valign=top nowrap=true|'''HTTP:'''
| The syslog entries are transferred to a web server. Each individual syslog entry is transferred to the server as an individual request.
* In the '''Address''' field, the IP-address of remote server is entered.
* In the '''Path''' field, the relative URL to be used in the HTTP request is entered.
* The Method field selects the method used to send the request. There are 3 formats available:
{|
| Format || Request Type || URI || Description
|-
| Standard || POST || ''hardwired'' || This should be used to forward log messages to another innovaphone device, e.g. to store it on a central CF card
|-
| External(POST) || POST || as defined in the Path field || This is identical to the ''Standard'' method, except that you may specifiy the URI to be used
|-
| External(GET) || GET || as defined in the Path field || The log message will be coded into GET ''form data'' (a.k.a. ''query args''). This method is compatible to the method used in firmware versions 5.01 and 6.
|}
For more information on HTTP request formatting, see [[Reference7:HTTP Request Message Format]].

If the addressed Web server requires authentication, an ''Authenticated URL'' has to be configured on the [[Reference:Configuration/General/HTTP-Client|HTTP-Client]] Page. The ''URL'' constructed by the logger is shown right next to the ''Path'' field. It must be entered in exactly this format on the [[Reference:Configuration/General/HTTP-Client|HTTP-Client]] Page. The device has to be restarted after the ''Authenticated URL'' has been set.
|-
|valign=top nowrap=true|'''LOCAL:'''
| The syslog entries are saved to [[Reference:Administration/Diagnostics/CF|the local CF card]] into the '''/log''' directory, e.g. '''\\''ipaddr''\drive\CF0\log'''. Log files named '''LOG0.''n''''' are created, where '''''n''''' goes from 0 to 3. The next log file is created when either the '''Max File Size''' is reached or the '''Backup Time''' has passed. '''LOG0.0''' is the newest log file always.

To concentrate all syslog messages to a single CF card, you would use the '''HTTP Log Server Type''' in all but one boxes with '''Method''' set to '''Standard'''. '''Address''' must be set to the IP-address of the single box that has the CF card used for log message storage. '''Port''' must be set to the port configured for the [[Reference:Configuration/General/HTTP-Server|HTTP-Server]] of this box.

|-
|valign=top nowrap=true|'''LOCAL-AP:'''
|The logs are transmitted to the local Linux application platform. Logs are stored under \\AP-IP\webdav\log\ and alarms under \\AP-IP\webdav\alarm\
|-
|valign=top nowrap=true|'''REMOTE-AP:'''
|The logs are transmitted to a remote Linux application platform. Store path is the same as under LOCAL-AP.
* In the Address field, you enter the IP address of the remote Linux application platform.
* In the Port field, you specify the port to which the connection is set up.
Remark: Don't forget to enable access to \\AP-IP\ap\log.fcgi as [[Reference10:Concept_Linux_Application_Platform#Use_as_Log_or_Alarm_Server | required for use of LinAP as logserver]].
|-
|valign=top nowrap=true|'''REMOTE-AP-S:'''
|Same as REMOTE-AP, just a secure transmission is used.
|}

A second server may be configured as '''Log Server Shadow''' receiving the same records as the first server.

== Alarm and Event Handling ==
Alarm and event forwarding is configured independently from the handling of log messages.

If no '''Forward Server''' is configured in the '''Alarm and Event Forward Server''' area, alarms and events are stored locally as specified in the '''Local Alarm and Event Queues''' area below. Otherwise, alarms and events are additionally forwarded to the external server using HTTP requests. Each individual alarm or event entry is transferred to the server as an individual request. 
<code>SYSLOG</code> option is only available on Gateway devices. Phones should use HTTP to forward alarm/events to an innovaphone gateway which may forward the collected events to a syslog server.

* The '''Address''' is used to set the IP-address of an external HTTP server that will receive the forwarded alarms and events.
* The '''Port''' defines the TCP port the HTTP request is sent to.
* The '''Method''' selects the method used to send the the requests. The same methods as for the '''Log Server''' are available here. (only on gateways)

To collect all alarms and events in a single device card, you would use the '''Standard Method''' in all but one boxes. '''Address''' must be set to the IP-address of the central box. '''Port''' must be set to the port configured for the [[{{NAMESPACE}}:Configuration/General/HTTP-Server|HTTP-Server]] of this box. 
The collected alarms and events may further be forwarded to one or two SYSLOG server(s) as XML-encoded records.
This is achieved by configuring a '''Forward Server''' with '''Method''' SYSLOG, the server address under '''Address''' and the SYSLOG-Class under '''Class'''.

The '''Local Alarm and Event Queues''' area allows you to control the number of events and alarms that are kept in memory and stored in non-volatile memory during restarts.

== Alarms and Errors as Email ==
Definition of email target to send alarms and errors as email to.

* '''Sender Address''': email adress of sender
* '''Senders' Name''': alias of sender name
* '''Recipient Address''': email adress of recipient
* '''Recipients' Name''': alias of recipient name
* '''Email Server Address''': ip-adress or DNS name of smtp email server. TLS will be supported automatically, if demanded by the server.
* '''User''': user account at email server
* '''Password''': user password at email server
* '''OAuth2''': Alternatively OAuth2 credentials to authenticate for e-mail sending. See [[Howto16r1:Configure_OAuth2_E-Mail]].

== Handling of incoming Alarms/Events ==
{|
|valign=top nowrap=true|'''Authenticate:'''
| When enabled request HTTP Authentication for the incoming HTTP Alarms/Events messages. You must configure in the sender the HTTP credentials to be able to deliver the Alarms/Events.
|-
{|
== Local Alarm and Event Queues ==
{|
|valign=top nowrap=true|'''Memory Queue Entries:'''
| Maximum number of faults and alarms to hold in volatile memory (DRAM)(Default:100).
|-
|valign=top nowrap=true|'''Persistent Queue Entries:'''
| Maximum number of faults and alarms to keep in flash memory (Default:50).
|-
{|

== Catch trace on Event ==

Event codes (up to 4 different) may be configured, on which the tracing is stopped. The event codes can be copied from actual events displayed on Maintenance/Events. Hexadecimal values was converted and stored as Decimal values.

After the event has happend the trace was stopped, the trace can be read which hopefully contains what caused the event.

You can restart the logfile by emptying the [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing |buffer]].

Reference13r1:Services/Logging

2025-10-06T12:20:33Z

Tfu: Undo revision 78169 by Tmo (talk)

== Log Server ==
External '''logging''' is disabled by default (Off). You can still view log messages in real time (see [[Reference7:Administration/Diagnostics/Logging|Logging]]), but messages are not stored or sent to an external destination.

Available ''Type''s:

{|
|valign=top nowrap=true|'''Off:'''
| Logging is disabled.
|-
|valign=top nowrap=true|'''TCP:'''
| The device transmits the syslog entries using a TCP connection.
* In the '''Address''' field, the remote IP-address is entered.
* In the '''Port''' field, the remote port is specified.
|-
|valign=top nowrap=true|'''SYSLOG:'''
| The syslog entries are transmitted to a syslog recipient (also referred to as syslogd, syslog server or syslog daemon).
* In the '''Address''' field, the IP-address of the syslogd server is entered.
* In the '''Class''' field, the syslog message class for the syslog entries sent is entered. The class is a numeric value between 0 and 7, it will be used as ''Facility'' (0 => local0, ... 7 => local7). The ''Severity'' field will always be 6 (informational). See [http://de.wikipedia.org/wiki/Syslog wikipedia.org/wiki/Syslog] for details.
|-
|valign=top nowrap=true|'''HTTP:'''
| The syslog entries are transferred to a web server. Each individual syslog entry is transferred to the server as an individual request.
* In the '''Address''' field, the IP-address of remote server is entered.
* In the '''Path''' field, the relative URL to be used in the HTTP request is entered.
* The Method field selects the method used to send the request. There are 3 formats available:
{|
| Format || Request Type || URI || Description
|-
| Standard || POST || ''hardwired'' || This should be used to forward log messages to another innovaphone device, e.g. to store it on a central CF card
|-
| External(POST) || POST || as defined in the Path field || This is identical to the ''Standard'' method, except that you may specifiy the URI to be used
|-
| External(GET) || GET || as defined in the Path field || The log message will be coded into GET ''form data'' (a.k.a. ''query args''). This method is compatible to the method used in firmware versions 5.01 and 6.
|}
For more information on HTTP request formatting, see [[Reference7:HTTP Request Message Format]].

If the addressed Web server requires authentication, an ''Authenticated URL'' has to be configured on the [[Reference:Configuration/General/HTTP-Client|HTTP-Client]] Page. The ''URL'' constructed by the logger is shown right next to the ''Path'' field. It must be entered in exactly this format on the [[Reference:Configuration/General/HTTP-Client|HTTP-Client]] Page. The device has to be restarted after the ''Authenticated URL'' has been set.
|-
|valign=top nowrap=true|'''LOCAL:'''
| The syslog entries are saved to [[Reference:Administration/Diagnostics/CF|the local CF card]] into the '''/log''' directory, e.g. '''\\''ipaddr''\drive\CF0\log'''. Log files named '''LOG0.''n''''' are created, where '''''n''''' goes from 0 to 3. The next log file is created when either the '''Max File Size''' is reached or the '''Backup Time''' has passed. '''LOG0.0''' is the newest log file always.

To concentrate all syslog messages to a single CF card, you would use the '''HTTP Log Server Type''' in all but one boxes with '''Method''' set to '''Standard'''. '''Address''' must be set to the IP-address of the single box that has the CF card used for log message storage. '''Port''' must be set to the port configured for the [[Reference:Configuration/General/HTTP-Server|HTTP-Server]] of this box.

|-
|valign=top nowrap=true|'''LOCAL-AP:'''
|The logs are transmitted to the local Linux application platform. Logs are stored under \\AP-IP\webdav\log\ and alarms under \\AP-IP\webdav\alarm\
|-
|valign=top nowrap=true|'''REMOTE-AP:'''
|The logs are transmitted to a remote Linux application platform. Store path is the same as under LOCAL-AP.
* In the Address field, you enter the IP address of the remote Linux application platform.
* In the Port field, you specify the port to which the connection is set up.
Remark: Don't forget to enable access to \\AP-IP\ap\log.fcgi as [[Reference10:Concept_Linux_Application_Platform#Use_as_Log_or_Alarm_Server | required for use of LinAP as logserver]].
|-
|valign=top nowrap=true|'''REMOTE-AP-S:'''
|Same as REMOTE-AP, just a secure transmission is used.
|}

A second server may be configured as '''Log Server Shadow''' receiving the same records as the first server.

== Alarm and Event Handling ==
Alarm and event forwarding is configured independently from the handling of log messages.

If no '''Forward Server''' is configured in the '''Alarm and Event Forward Server''' area, alarms and events are stored locally as specified in the '''Local Alarm and Event Queues''' area below. Otherwise, alarms and events are additionally forwarded to the external server using HTTP requests. Each individual alarm or event entry is transferred to the server as an individual request. 
<code>SYSLOG</code> option is only available on Gateway devices. Phones should use HTTP to forward alarm/events to an innovaphone gateway which may forward the collected events to a syslog server.

* The '''Address''' is used to set the IP-address of an external HTTP server that will receive the forwarded alarms and events.
* The '''Port''' defines the TCP port the HTTP request is sent to.
* The '''Method''' selects the method used to send the the requests. The same methods as for the '''Log Server''' are available here. (only on gateways)

To collect all alarms and events in a single device card, you would use the '''Standard Method''' in all but one boxes. '''Address''' must be set to the IP-address of the central box. '''Port''' must be set to the port configured for the [[{{NAMESPACE}}:Configuration/General/HTTP-Server|HTTP-Server]] of this box. 
The collected alarms and events may further be forwarded to one or two SYSLOG server(s) as XML-encoded records.
This is achieved by configuring a '''Forward Server''' with '''Method''' SYSLOG, the server address under '''Address''' and the SYSLOG-Class under '''Class'''.

The '''Local Alarm and Event Queues''' area allows you to control the number of events and alarms that are kept in memory and stored in non-volatile memory during restarts.

== Alarms and Errors as Email ==
Definition of email target to send alarms and errors as email to.

* '''Sender Address''': email adress of sender
* '''Senders' Name''': alias of sender name
* '''Recipient Address''': email adress of recipient
* '''Recipients' Name''': alias of recipient name
* '''Email Server Address''': ip-adress or DNS name of smtp email server. TLS will be supported automatically, if demanded by the server.
* '''User''': user account at email server
* '''Password''': user password at email server

== Handling of incoming Alarms/Events ==
{|
|valign=top nowrap=true|'''Authenticate:'''
| When enabled request HTTP Authentication for the incoming HTTP Alarms/Events messages. You must configure in the sender the HTTP credentials to be able to deliver the Alarms/Events.
|-
{|
== Local Alarm and Event Queues ==
{|
|valign=top nowrap=true|'''Memory Queue Entries:'''
| Maximum number of faults and alarms to hold in volatile memory (DRAM)(Default:100).
|-
|valign=top nowrap=true|'''Persistent Queue Entries:'''
| Maximum number of faults and alarms to keep in flash memory (Default:50).
|-
{|

== Catch trace on Event ==

Event codes (up to 4 different) may be configured, on which the tracing is stopped. The event codes can be copied from actual events displayed on Maintenance/Events. Hexadecimal values was converted and stored as Decimal values.

After the event has happend the trace was stopped, the trace can be read which hopefully contains what caused the event.

You can restart the logfile by emptying the [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing |buffer]].

Reference16r1:Apps/PbxManager/Email

2025-10-06T11:01:51Z

Tfu: Created page with "{{FIXME|reason=This product is in the beta phase and is not yet finished}} This PBX Manager Plugin configures the E-Mail Account of all PBXes in the system. The same configuration can be found in the advanced UI of the individual PBXes at PBX/Config/Authentication. == Add Email Account == ; SMTP Server : Your SMTP Server ; Email Address : The used From Address ; Username : The username for the authorization ; Password : The..."

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
This PBX Manager Plugin configures the E-Mail Account of all PBXes in the system. The same configuration can be found in the advanced UI of the individual PBXes at [[Reference13r2:PBX/Config/Authentication|PBX/Config/Authentication]].

== Add Email Account ==
; SMTP Server
: Your SMTP Server

; Email Address
: The used From Address

; Username
: The username for the authorization

; Password
: The password for the authorization

; Sender's name
: The used Name in the From field

Reference16r1:Services/Logging

2025-10-06T11:01:19Z

Tfu: Created page with "{{FIXME|reason=This product is in the beta phase and is not yet finished}} == Log Server == External '''logging''' is disabled by default (Off). You can still view log messages in real time (see Logging), but messages are not stored or sent to an external destination. Available ''Type''s: {| |valign=top nowrap=true|'''Off:''' | Logging is disabled. |- |valign=top nowrap=true|'''TCP:''' | The device transmits the syslog..."

{{FIXME|reason=This product is in the beta phase and is not yet finished}}
== Log Server ==
External '''logging''' is disabled by default (Off). You can still view log messages in real time (see [[Reference7:Administration/Diagnostics/Logging|Logging]]), but messages are not stored or sent to an external destination.

Available ''Type''s:

{|
|valign=top nowrap=true|'''Off:'''
| Logging is disabled.
|-
|valign=top nowrap=true|'''TCP:'''
| The device transmits the syslog entries using a TCP connection.
* In the '''Address''' field, the remote IP-address is entered.
* In the '''Port''' field, the remote port is specified.
|-
|valign=top nowrap=true|'''SYSLOG:'''
| The syslog entries are transmitted to a syslog recipient (also referred to as syslogd, syslog server or syslog daemon).
* In the '''Address''' field, the IP-address of the syslogd server is entered.
* In the '''Class''' field, the syslog message class for the syslog entries sent is entered. The class is a numeric value between 0 and 7, it will be used as ''Facility'' (0 => local0, ... 7 => local7). The ''Severity'' field will always be 6 (informational). See [http://de.wikipedia.org/wiki/Syslog wikipedia.org/wiki/Syslog] for details.
|-
|valign=top nowrap=true|'''HTTP:'''
| The syslog entries are transferred to a web server. Each individual syslog entry is transferred to the server as an individual request.
* In the '''Address''' field, the IP-address of remote server is entered.
* In the '''Path''' field, the relative URL to be used in the HTTP request is entered.
* The Method field selects the method used to send the request. There are 3 formats available:
{|
| Format || Request Type || URI || Description
|-
| Standard || POST || ''hardwired'' || This should be used to forward log messages to another innovaphone device, e.g. to store it on a central CF card
|-
| External(POST) || POST || as defined in the Path field || This is identical to the ''Standard'' method, except that you may specifiy the URI to be used
|-
| External(GET) || GET || as defined in the Path field || The log message will be coded into GET ''form data'' (a.k.a. ''query args''). This method is compatible to the method used in firmware versions 5.01 and 6.
|}
For more information on HTTP request formatting, see [[Reference7:HTTP Request Message Format]].

If the addressed Web server requires authentication, an ''Authenticated URL'' has to be configured on the [[Reference:Configuration/General/HTTP-Client|HTTP-Client]] Page. The ''URL'' constructed by the logger is shown right next to the ''Path'' field. It must be entered in exactly this format on the [[Reference:Configuration/General/HTTP-Client|HTTP-Client]] Page. The device has to be restarted after the ''Authenticated URL'' has been set.
|-
|valign=top nowrap=true|'''LOCAL:'''
| The syslog entries are saved to [[Reference:Administration/Diagnostics/CF|the local CF card]] into the '''/log''' directory, e.g. '''\\''ipaddr''\drive\CF0\log'''. Log files named '''LOG0.''n''''' are created, where '''''n''''' goes from 0 to 3. The next log file is created when either the '''Max File Size''' is reached or the '''Backup Time''' has passed. '''LOG0.0''' is the newest log file always.

To concentrate all syslog messages to a single CF card, you would use the '''HTTP Log Server Type''' in all but one boxes with '''Method''' set to '''Standard'''. '''Address''' must be set to the IP-address of the single box that has the CF card used for log message storage. '''Port''' must be set to the port configured for the [[Reference:Configuration/General/HTTP-Server|HTTP-Server]] of this box.

|-
|valign=top nowrap=true|'''LOCAL-AP:'''
|The logs are transmitted to the local Linux application platform. Logs are stored under \\AP-IP\webdav\log\ and alarms under \\AP-IP\webdav\alarm\
|-
|valign=top nowrap=true|'''REMOTE-AP:'''
|The logs are transmitted to a remote Linux application platform. Store path is the same as under LOCAL-AP.
* In the Address field, you enter the IP address of the remote Linux application platform.
* In the Port field, you specify the port to which the connection is set up.
Remark: Don't forget to enable access to \\AP-IP\ap\log.fcgi as [[Reference10:Concept_Linux_Application_Platform#Use_as_Log_or_Alarm_Server | required for use of LinAP as logserver]].
|-
|valign=top nowrap=true|'''REMOTE-AP-S:'''
|Same as REMOTE-AP, just a secure transmission is used.
|}

A second server may be configured as '''Log Server Shadow''' receiving the same records as the first server.

== Alarm and Event Handling ==
Alarm and event forwarding is configured independently from the handling of log messages.

If no '''Forward Server''' is configured in the '''Alarm and Event Forward Server''' area, alarms and events are stored locally as specified in the '''Local Alarm and Event Queues''' area below. Otherwise, alarms and events are additionally forwarded to the external server using HTTP requests. Each individual alarm or event entry is transferred to the server as an individual request. 
<code>SYSLOG</code> option is only available on Gateway devices. Phones should use HTTP to forward alarm/events to an innovaphone gateway which may forward the collected events to a syslog server.

* The '''Address''' is used to set the IP-address of an external HTTP server that will receive the forwarded alarms and events.
* The '''Port''' defines the TCP port the HTTP request is sent to.
* The '''Method''' selects the method used to send the the requests. The same methods as for the '''Log Server''' are available here. (only on gateways)

To collect all alarms and events in a single device card, you would use the '''Standard Method''' in all but one boxes. '''Address''' must be set to the IP-address of the central box. '''Port''' must be set to the port configured for the [[{{NAMESPACE}}:Configuration/General/HTTP-Server|HTTP-Server]] of this box. 
The collected alarms and events may further be forwarded to one or two SYSLOG server(s) as XML-encoded records.
This is achieved by configuring a '''Forward Server''' with '''Method''' SYSLOG, the server address under '''Address''' and the SYSLOG-Class under '''Class'''.

The '''Local Alarm and Event Queues''' area allows you to control the number of events and alarms that are kept in memory and stored in non-volatile memory during restarts.

== Alarms and Errors as Email ==
Definition of email target to send alarms and errors as email to.

* '''Sender Address''': email adress of sender
* '''Senders' Name''': alias of sender name
* '''Recipient Address''': email adress of recipient
* '''Recipients' Name''': alias of recipient name
* '''Email Server Address''': ip-adress or DNS name of smtp email server. TLS will be supported automatically, if demanded by the server.
* '''User''': user account at email server
* '''Password''': user password at email server

== Handling of incoming Alarms/Events ==
{|
|valign=top nowrap=true|'''Authenticate:'''
| When enabled request HTTP Authentication for the incoming HTTP Alarms/Events messages. You must configure in the sender the HTTP credentials to be able to deliver the Alarms/Events.
|-
{|
== Local Alarm and Event Queues ==
{|
|valign=top nowrap=true|'''Memory Queue Entries:'''
| Maximum number of faults and alarms to hold in volatile memory (DRAM)(Default:100).
|-
|valign=top nowrap=true|'''Persistent Queue Entries:'''
| Maximum number of faults and alarms to keep in flash memory (Default:50).
|-
{|

== Catch trace on Event ==

Event codes (up to 4 different) may be configured, on which the tracing is stopped. The event codes can be copied from actual events displayed on Maintenance/Events. Hexadecimal values was converted and stored as Decimal values.

After the event has happend the trace was stopped, the trace can be read which hopefully contains what caused the event.

You can restart the logfile by emptying the [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing |buffer]].

Reference16r1:PBX/Config/Authentication

2025-10-06T06:55:57Z

Tfu: /* Related Articles */

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

The authentication for myApps and myPBX is configured on this page.

= Configuration =
== Authentication ==
* '''Two-factor authentication''' Requires users to additionally approve their logins using an existing session or by clicking a link sent via email. (myApps only)
* '''Authentication type''' (myApps and myPBX)
** '''PBX only''' Login is allowed with PBX user password only.
** '''Netlogon only''' Login is allowed with Windows password only.
** '''PBX and Netlogon''' Login is allowed with both PBX user password and Windows password.
** '''OAuth2 only''' Login is allowed with OpenID/OAuth2 only. (myApps only)
** '''PBX and OAuth2''' Login is allowed with both PBX user password and OpenId/OAuth2. (myApps only)
* '''OAuth2 provider name''' A user friendly name of the OAuth2 provider that shall be displayed on the login form, e.g. "Windows" or "Active Directory". (myApps only)
* '''OAuth2 domain''' This configuration is needed, if the OAuth2 user domain does not match the PBX domain. If a domain is configured, users of that domain will be treated like members of the PBX domain.
** Example: No domain configured. user@example.com -> user@example.com
** Example: example.com configured. user@example.com -> user

== Email verification ==
An email account that is used by the PBX for sending mails. It is used for:
* Sending verification emails for two-factor authentication.
* Emails from the voicemail object.
Configuration:
* '''SMTP server''' The IP address or DNS name of the SMTP server.
* '''Client host name''' The hostname or IP address for the EHLO message. Optional, defaulting to 127.0.0.1.
* '''Sender name''' A readable name that is used as the sender of the emails.
* '''Email address''' The email address for sending mails.
* '''Username''' The username of the email account.
* '''Password''' The password of the email account.
* '''OAuth2''' Alternatively OAuth2 credentials to authenticate for e-mail sending. See [[Howto16r1:Configure_OAuth2_E-Mail]].
* '''Verification link''' The link that is used for accepting or rejecting sessions. Configure <code>https://PBX-IP-or-DNS-name/PBX0/session.xml</code>

* '''Test''' Here you can send a test mail using the configured account.

==Related Articles==
[[Reference16r1:Concept OAuth2 Windows Authentication]] 
[[Howto16r1:Configure_OAuth2_E-Mail]]

Reference14r1:Apps/PbxManager/App Microsoft365

2025-10-02T11:51:54Z

Tfu: Reverted edit by The (talk) to last revision by Tfu

With the Connector for Microsoft 365 PBX-Manager plugin, the needed app object can be created and configured automatically.

== Add an app object ==

;name
:The ''name'' displayed for the app object which must be unique.

;SIP
:The ''sip'' from the app object which must be unique.