innovaphone wiki - User contributions [en]

Howto:DE - Deutsche Telekom - CompanyFlex TLS SIP-Provider (2020)

2025-07-14T09:53:30Z

Bsiegwald: /* Configuration */ addition of path to technical guidelines

== Summary ==
{{Template:SIP_TEST_STATUS_complete|update=November 19th, 2020|url=https://geschaeftskunden.telekom.de/internet-dsl/tarife/festnetz-internet-dsl/companyflex|productname=CompanyFlex_TLS|providername=Deutsche_Telekom}}
<internal>Provider SBC: BroadWorks</internal>

=== {{SIP_TEST_ISSUES_MR_TITLE}} ===
{{SIP_TEST_ISSUES_MR_INTRO}}
; CLIR : {{SIP_TEST_FACT_CLIR}}
; EARLY MEDIA INBOUND : {{SIP_TEST_FACT_EARLY MEDIA INBOUND}}
; FAX T38 ONNET : {{SIP_TEST_FACT_FAX T38 ONNET}}
; FAX T38 : {{SIP_TEST_FACT_FAX T38}}
; FAX T38ANDAUDIO : {{SIP_TEST_FACT_FAX T38ANDAUDIO}}
; SDP VIDEO : {{SIP_TEST_FACT_SDP VIDEO}}
; SIP INFO : {{SIP_TEST_FACT_SIP INFO}}

{{SIP_TEST_FACTS_LIST}} [[Template:SIP TEST FACT DESCRIPTION TEST 180 RINGING FAILS|180_RINGING]], [[Template:SIP TEST FACT DESCRIPTION TEST BASIC CALL FAILS|BASIC_CALL]], [[Template:SIP TEST FACT DESCRIPTION TEST CLIR FAILS|CLIR]], [[Template:SIP TEST FACT DESCRIPTION TEST CLNS ONNET FAILS|CLNS_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST CLNS FAILS|CLNS]], [[Template:SIP TEST FACT DESCRIPTION TEST CONN NR DIFF FAILS|CONN_NR_DIFF]], [[Template:SIP TEST FACT DESCRIPTION TEST CONN NR INCOMING FAILS|CONN_NR_INCOMING]], [[Template:SIP TEST FACT DESCRIPTION TEST CONN NR FAILS|CONN_NR]], [[Template:SIP TEST FACT DESCRIPTION TEST DTMF FAILS|DTMF]], [[Template:SIP TEST FACT DESCRIPTION TEST EARLY MEDIA INBOUND FAILS|EARLY_MEDIA_INBOUND]], [[Template:SIP TEST FACT DESCRIPTION TEST FAX AUDIO FAILS|FAX_AUDIO]], [[Template:SIP TEST FACT DESCRIPTION TEST FAX T38 ONNET FAILS|FAX_T38_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST FAX T38 FAILS|FAX_T38]], [[Template:SIP TEST FACT DESCRIPTION TEST FAX T38ANDAUDIO FAILS|FAX_T38ANDAUDIO]], [[Template:SIP TEST FACT DESCRIPTION TEST G711A ONNET FAILS|G711A_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST G711A FAILS|G711A]], [[Template:SIP TEST FACT DESCRIPTION TEST G711U ONNET FAILS|G711U_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST G711U FAILS|G711U]], [[Template:SIP TEST FACT DESCRIPTION TEST G722 ONNET FAILS|G722_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST G722 FAILS|G722]], [[Template:SIP TEST FACT DESCRIPTION TEST G729 ONNET FAILS|G729_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST G729 FAILS|G729]], [[Template:SIP TEST FACT DESCRIPTION TEST HOLD RETRIEVE FAILS|HOLD_RETRIEVE]], [[Template:SIP TEST FACT DESCRIPTION TEST IP FRAGMENTATION FAILS|IP_FRAGMENTATION]], [[Template:SIP TEST FACT DESCRIPTION TEST LARGE SIP MESSAGES FAILS|LARGE_SIP_MESSAGES]], [[Template:SIP TEST FACT DESCRIPTION TEST MOBILITY FAILS|MOBILITY]], [[Template:SIP TEST FACT DESCRIPTION TEST OPUS NB FAILS|OPUS_NB]], [[Template:SIP TEST FACT DESCRIPTION TEST OPUS WB FAILS|OPUS_WB]], [[Template:SIP TEST FACT DESCRIPTION TEST RALERT DISC FAILS|RALERT_DISC]], [[Template:SIP TEST FACT DESCRIPTION TEST REDIR 302 FAILS|REDIR_302]], [[Template:SIP TEST FACT DESCRIPTION TEST REDIR DIVHDR FAILS|REDIR_DIVHDR]], [[Template:SIP TEST FACT DESCRIPTION TEST REDIR HISTHDR FAILS|REDIR_HISTHDR]], [[Template:SIP TEST FACT DESCRIPTION TEST REVERSE MEDIA FAILS|REVERSE_MEDIA]], [[Template:SIP TEST FACT DESCRIPTION TEST SDP ICE FAILS|SDP_ICE]], [[Template:SIP TEST FACT DESCRIPTION TEST SDP RTCP MUX FAILS|SDP_RTCP_MUX]], [[Template:SIP TEST FACT DESCRIPTION TEST SDP VIDEO FAILS|SDP_VIDEO]], [[Template:SIP TEST FACT DESCRIPTION TEST SIP INFO FAILS|SIP_INFO]], [[Template:SIP TEST FACT DESCRIPTION TEST SRTP INCOMING FAILS|SRTP_INCOMING]], [[Template:SIP TEST FACT DESCRIPTION TEST SRTP INTERNAL FAILS|SRTP_INTERNAL]], [[Template:SIP TEST FACT DESCRIPTION TEST SRTP OUTGOING FAILS|SRTP_OUTGOING]], [[Template:SIP TEST FACT DESCRIPTION TEST SUBSCRIBER NR FAILS|SUBSCRIBER_NR]], [[Template:SIP TEST FACT DESCRIPTION TEST XFER BLIND FAILS|XFER_BLIND]], [[Template:SIP TEST FACT DESCRIPTION TEST XFER CONS ALERT FAILS|XFER_CONS_ALERT]], [[Template:SIP TEST FACT DESCRIPTION TEST XFER CONS EXT FAILS|XFER_CONS_EXT]], [[Template:SIP TEST FACT DESCRIPTION TEST XFER CONS FAILS|XFER_CONS]]

== Test Results ==
{{SIP_TEST_TESTRESULT_ONLYMR_INTRO}}
=== {{SIP_TEST_RESULTS_MR_TITLE}} ===
; Registration : {{Template:SIP_Profile_Test_Registration_TCP_no_UDP}}

; NAT Traversal : {{Template:SIP_Profile_Test_NAT_a_no_c}}

; DTMF (RFC2833) : {{Template:SIP_Profile_Test_DTMF_RFC2833_yes}}

; Session Timer : {{Template:SIP_Profile_Test_EXPIRES_yes}}

; Redundancy : {{Template:SIP_Profile_Test_REDUNDANCY_no}}

; Correct signalling of Ringing-state : {{Template:SIP_Profile_Test_RINGING_yes}}

; CLIR : {{Template:SIP_Profile_Test_CLIR_no}}

; Clip No Screening (CLNS) : {{Template:SIP_Profile_Test_CLNS_yes}} {{Template:SIP_Profile_Test_CLNS_clns_302_not_recommended}}

; COLP : {{Template:SIP_Profile_Test_COLP_out_yes_in_yes}} {{Template:SIP_Profile_Test_COLP_diff_no}}

; Early-Media : {{Template:SIP_Profile_Test_EARLY_MEDIA_INBOUND_no}}

; Fax : {{Template:SIP_Profile_Test_AUDIOFAX_PSTN_yes}}
: {{Template:SIP_Profile_Test_T38_PSTN_no_onnet_no_fallback_no}}

; Codecs : supported to/from PSTN: G711A
: supported onnet (VoIP to VoIP): G711A, G711U and G722

; IP-Fragmentation : {{Template:SIP_Profile_Test_FRAGMENTATION_yes}}

; Large SIP messages : {{Template:SIP_Profile_Test_LARGE_MESSAGES_yes}}

; Reverse Media Negotiation : {{Template:SIP_Profile_Test_REV_MEDIA_NEG_yes}}

; Mobility Calls : {{Template:SIP_Profile_Test_MobilityCall_no_with_MediaRelay}}

; SRTP : {{Template:SIP_Profile_Test_SRTP_yes}}

; Dialing of Subscriber Numbers : {{Template:SIP_Profile_Test_SUBSCRIBER_NR_no}}

; Call Transfer : {{Template:SIP_Profile_Test_CALL_TRANSFER_ok}}

==Configuration==
Use profile ''DE-Deutsche_Telekom-CompanyFlex_TLS'' in ''Gateway/Interfaces/SIP'' to configure this SIP provider.

Please note the following configuration hints:
* If you intend to use SIPS (SIP/TLS) registration, you need to add the ' T-TeleSec GlobalRoot Class 2' ([https://hilfe.companyflex.de/de/endgeraete/ueberblick#_182050 Hardware von Drittherstellern & Verschlüsselung am Fremdanschluss], [https://www.telekom.de/hilfe/geraete/service/umwelt/schnittstellenbeschreibung-downloads?wt_mc=alias_1254_schnittstellenbeschreibungen&samChecked=true 1TR119]) certificate to the trust list of your SBC
* <nowiki>Dialling of subscriber numbers not possible, 'Dialing Location' must be configured without 'Area Code'</nowiki>

: {{SIP_TEST_V12_HINT}}

==Multi Location==
It's possible to have different MSNs and DDIs from different locations on the same trunk. But this is limited to 60 number objects. A number object is an MSN or the first DDI digit. So a complete DDI block from 0 to 9 (0-99 or 0-999) is counted as 10 number objects.
==SIP Redundancy==
In case of SIP redundancy the username should be in the format "+49199296000000XXXXXX@tel.t-online.de" so the feature "Call Routing for redundant SIP-Trunks" works correctly.
== Sending non 100 replies==
The Telekom CompanyFlex has a default supervision timer of 3 seconds to receive a response to their INVITE with an 18x message, if this timer expires the call can be canceled. The supervision timer can be configured per trunk group in the CompanyFlex portal.
This timer can be triggered in cases where a receiving endpoint takes too long to give an alert message, ie: myAPPS running on a smartphone device that takes longer to "wake up" or a mobility call via GSM that has more delay than the GSM network.
Source: Page 25 of the Technical Specification of the SIP Trunking Interface for CompanyFlex of Deutsche Telekom - 1TR119 - Version 1.12.0 - 28. November 2022
== Correct DNS Server==
To operate CompanyFlex is necessary to use a correct DNS Server either provided by Telekom connection or with special feature required if not an ISP connection from Telekom to avoid issues with SIP Registration. More information can be found [https://hilfe.companyflex.de/de/grundlagen/systemvoraussetzungen here].

== Using Endpoints without Encryption in the PBX==
In case we operate a 3rd Party SIP endpoint that don't support Encryption, so the flag Media-relay+No SRTP is enabled on the User Object of that endpoint is recommended to switch the Protocol used for the internal registration of the SIP Trunk from H.323 to SIP to avoid media negotiation issues in some specific call scenarios like CFNR.

== Disclaimer ==
{{SIP_TEST_PREFACE}}

[[Category:Compat|{{PAGENAME}}]]
[[Category:3rdParty SIP Provider|{{PAGENAME}}]]

Howto:DE - Deutsche Telekom - CompanyFlex TLS SIP-Provider (2020)

2025-07-14T09:34:22Z

Bsiegwald: /* Configuration */ Update needed certificate for trust list + source

== Summary ==
{{Template:SIP_TEST_STATUS_complete|update=November 19th, 2020|url=https://geschaeftskunden.telekom.de/internet-dsl/tarife/festnetz-internet-dsl/companyflex|productname=CompanyFlex_TLS|providername=Deutsche_Telekom}}
<internal>Provider SBC: BroadWorks</internal>

=== {{SIP_TEST_ISSUES_MR_TITLE}} ===
{{SIP_TEST_ISSUES_MR_INTRO}}
; CLIR : {{SIP_TEST_FACT_CLIR}}
; EARLY MEDIA INBOUND : {{SIP_TEST_FACT_EARLY MEDIA INBOUND}}
; FAX T38 ONNET : {{SIP_TEST_FACT_FAX T38 ONNET}}
; FAX T38 : {{SIP_TEST_FACT_FAX T38}}
; FAX T38ANDAUDIO : {{SIP_TEST_FACT_FAX T38ANDAUDIO}}
; SDP VIDEO : {{SIP_TEST_FACT_SDP VIDEO}}
; SIP INFO : {{SIP_TEST_FACT_SIP INFO}}

{{SIP_TEST_FACTS_LIST}} [[Template:SIP TEST FACT DESCRIPTION TEST 180 RINGING FAILS|180_RINGING]], [[Template:SIP TEST FACT DESCRIPTION TEST BASIC CALL FAILS|BASIC_CALL]], [[Template:SIP TEST FACT DESCRIPTION TEST CLIR FAILS|CLIR]], [[Template:SIP TEST FACT DESCRIPTION TEST CLNS ONNET FAILS|CLNS_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST CLNS FAILS|CLNS]], [[Template:SIP TEST FACT DESCRIPTION TEST CONN NR DIFF FAILS|CONN_NR_DIFF]], [[Template:SIP TEST FACT DESCRIPTION TEST CONN NR INCOMING FAILS|CONN_NR_INCOMING]], [[Template:SIP TEST FACT DESCRIPTION TEST CONN NR FAILS|CONN_NR]], [[Template:SIP TEST FACT DESCRIPTION TEST DTMF FAILS|DTMF]], [[Template:SIP TEST FACT DESCRIPTION TEST EARLY MEDIA INBOUND FAILS|EARLY_MEDIA_INBOUND]], [[Template:SIP TEST FACT DESCRIPTION TEST FAX AUDIO FAILS|FAX_AUDIO]], [[Template:SIP TEST FACT DESCRIPTION TEST FAX T38 ONNET FAILS|FAX_T38_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST FAX T38 FAILS|FAX_T38]], [[Template:SIP TEST FACT DESCRIPTION TEST FAX T38ANDAUDIO FAILS|FAX_T38ANDAUDIO]], [[Template:SIP TEST FACT DESCRIPTION TEST G711A ONNET FAILS|G711A_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST G711A FAILS|G711A]], [[Template:SIP TEST FACT DESCRIPTION TEST G711U ONNET FAILS|G711U_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST G711U FAILS|G711U]], [[Template:SIP TEST FACT DESCRIPTION TEST G722 ONNET FAILS|G722_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST G722 FAILS|G722]], [[Template:SIP TEST FACT DESCRIPTION TEST G729 ONNET FAILS|G729_ONNET]], [[Template:SIP TEST FACT DESCRIPTION TEST G729 FAILS|G729]], [[Template:SIP TEST FACT DESCRIPTION TEST HOLD RETRIEVE FAILS|HOLD_RETRIEVE]], [[Template:SIP TEST FACT DESCRIPTION TEST IP FRAGMENTATION FAILS|IP_FRAGMENTATION]], [[Template:SIP TEST FACT DESCRIPTION TEST LARGE SIP MESSAGES FAILS|LARGE_SIP_MESSAGES]], [[Template:SIP TEST FACT DESCRIPTION TEST MOBILITY FAILS|MOBILITY]], [[Template:SIP TEST FACT DESCRIPTION TEST OPUS NB FAILS|OPUS_NB]], [[Template:SIP TEST FACT DESCRIPTION TEST OPUS WB FAILS|OPUS_WB]], [[Template:SIP TEST FACT DESCRIPTION TEST RALERT DISC FAILS|RALERT_DISC]], [[Template:SIP TEST FACT DESCRIPTION TEST REDIR 302 FAILS|REDIR_302]], [[Template:SIP TEST FACT DESCRIPTION TEST REDIR DIVHDR FAILS|REDIR_DIVHDR]], [[Template:SIP TEST FACT DESCRIPTION TEST REDIR HISTHDR FAILS|REDIR_HISTHDR]], [[Template:SIP TEST FACT DESCRIPTION TEST REVERSE MEDIA FAILS|REVERSE_MEDIA]], [[Template:SIP TEST FACT DESCRIPTION TEST SDP ICE FAILS|SDP_ICE]], [[Template:SIP TEST FACT DESCRIPTION TEST SDP RTCP MUX FAILS|SDP_RTCP_MUX]], [[Template:SIP TEST FACT DESCRIPTION TEST SDP VIDEO FAILS|SDP_VIDEO]], [[Template:SIP TEST FACT DESCRIPTION TEST SIP INFO FAILS|SIP_INFO]], [[Template:SIP TEST FACT DESCRIPTION TEST SRTP INCOMING FAILS|SRTP_INCOMING]], [[Template:SIP TEST FACT DESCRIPTION TEST SRTP INTERNAL FAILS|SRTP_INTERNAL]], [[Template:SIP TEST FACT DESCRIPTION TEST SRTP OUTGOING FAILS|SRTP_OUTGOING]], [[Template:SIP TEST FACT DESCRIPTION TEST SUBSCRIBER NR FAILS|SUBSCRIBER_NR]], [[Template:SIP TEST FACT DESCRIPTION TEST XFER BLIND FAILS|XFER_BLIND]], [[Template:SIP TEST FACT DESCRIPTION TEST XFER CONS ALERT FAILS|XFER_CONS_ALERT]], [[Template:SIP TEST FACT DESCRIPTION TEST XFER CONS EXT FAILS|XFER_CONS_EXT]], [[Template:SIP TEST FACT DESCRIPTION TEST XFER CONS FAILS|XFER_CONS]]

== Test Results ==
{{SIP_TEST_TESTRESULT_ONLYMR_INTRO}}
=== {{SIP_TEST_RESULTS_MR_TITLE}} ===
; Registration : {{Template:SIP_Profile_Test_Registration_TCP_no_UDP}}

; NAT Traversal : {{Template:SIP_Profile_Test_NAT_a_no_c}}

; DTMF (RFC2833) : {{Template:SIP_Profile_Test_DTMF_RFC2833_yes}}

; Session Timer : {{Template:SIP_Profile_Test_EXPIRES_yes}}

; Redundancy : {{Template:SIP_Profile_Test_REDUNDANCY_no}}

; Correct signalling of Ringing-state : {{Template:SIP_Profile_Test_RINGING_yes}}

; CLIR : {{Template:SIP_Profile_Test_CLIR_no}}

; Clip No Screening (CLNS) : {{Template:SIP_Profile_Test_CLNS_yes}} {{Template:SIP_Profile_Test_CLNS_clns_302_not_recommended}}

; COLP : {{Template:SIP_Profile_Test_COLP_out_yes_in_yes}} {{Template:SIP_Profile_Test_COLP_diff_no}}

; Early-Media : {{Template:SIP_Profile_Test_EARLY_MEDIA_INBOUND_no}}

; Fax : {{Template:SIP_Profile_Test_AUDIOFAX_PSTN_yes}}
: {{Template:SIP_Profile_Test_T38_PSTN_no_onnet_no_fallback_no}}

; Codecs : supported to/from PSTN: G711A
: supported onnet (VoIP to VoIP): G711A, G711U and G722

; IP-Fragmentation : {{Template:SIP_Profile_Test_FRAGMENTATION_yes}}

; Large SIP messages : {{Template:SIP_Profile_Test_LARGE_MESSAGES_yes}}

; Reverse Media Negotiation : {{Template:SIP_Profile_Test_REV_MEDIA_NEG_yes}}

; Mobility Calls : {{Template:SIP_Profile_Test_MobilityCall_no_with_MediaRelay}}

; SRTP : {{Template:SIP_Profile_Test_SRTP_yes}}

; Dialing of Subscriber Numbers : {{Template:SIP_Profile_Test_SUBSCRIBER_NR_no}}

; Call Transfer : {{Template:SIP_Profile_Test_CALL_TRANSFER_ok}}

==Configuration==
Use profile ''DE-Deutsche_Telekom-CompanyFlex_TLS'' in ''Gateway/Interfaces/SIP'' to configure this SIP provider.

Please note the following configuration hints:
* If you intend to use SIPS (SIP/TLS) registration, you need to add the ' T-TeleSec GlobalRoot Class 2' ([https://hilfe.companyflex.de/de/endgeraete/ueberblick#_182050 Hardware von Drittherstellern & Verschlüsselung am Fremdanschluss]) certificate to the trust list of your SBC
* <nowiki>Dialling of subscriber numbers not possible, 'Dialing Location' must be configured without 'Area Code'</nowiki>

: {{SIP_TEST_V12_HINT}}

==Multi Location==
It's possible to have different MSNs and DDIs from different locations on the same trunk. But this is limited to 60 number objects. A number object is an MSN or the first DDI digit. So a complete DDI block from 0 to 9 (0-99 or 0-999) is counted as 10 number objects.
==SIP Redundancy==
In case of SIP redundancy the username should be in the format "+49199296000000XXXXXX@tel.t-online.de" so the feature "Call Routing for redundant SIP-Trunks" works correctly.
== Sending non 100 replies==
The Telekom CompanyFlex has a default supervision timer of 3 seconds to receive a response to their INVITE with an 18x message, if this timer expires the call can be canceled. The supervision timer can be configured per trunk group in the CompanyFlex portal.
This timer can be triggered in cases where a receiving endpoint takes too long to give an alert message, ie: myAPPS running on a smartphone device that takes longer to "wake up" or a mobility call via GSM that has more delay than the GSM network.
Source: Page 25 of the Technical Specification of the SIP Trunking Interface for CompanyFlex of Deutsche Telekom - 1TR119 - Version 1.12.0 - 28. November 2022
== Correct DNS Server==
To operate CompanyFlex is necessary to use a correct DNS Server either provided by Telekom connection or with special feature required if not an ISP connection from Telekom to avoid issues with SIP Registration. More information can be found [https://hilfe.companyflex.de/de/grundlagen/systemvoraussetzungen here].

== Using Endpoints without Encryption in the PBX==
In case we operate a 3rd Party SIP endpoint that don't support Encryption, so the flag Media-relay+No SRTP is enabled on the User Object of that endpoint is recommended to switch the Protocol used for the internal registration of the SIP Trunk from H.323 to SIP to avoid media negotiation issues in some specific call scenarios like CFNR.

== Disclaimer ==
{{SIP_TEST_PREFACE}}

[[Category:Compat|{{PAGENAME}}]]
[[Category:3rdParty SIP Provider|{{PAGENAME}}]]

Howto13r2:Setting up Calendar with OAuth2

2025-03-30T14:27:39Z

Bsiegwald: Reference to impersonation deprecation and alternative with app-only authentication

= How-to setup the Calendar for OAuth2 =
This tutorial shows you, how to setup an Azure Active Directory App to let the calendar work with Microsoft 365 and OAuth2. Please note, that this is not a complete administration guide. Instead, it is a simply step-by-step tutorial which should work but maybe not the most accurate administration of your Azure AD – it’s just the way how we managed to use it. It is highly recommended to ask your Azure Administrator for details and / or read the Microsoft documentation. It is expected, that you have an Exchange user with the Application Impersonation right. More information about how to assign this role to a user can be found in the Microsoft documentation.

'''''Note:''''' The screenshot and labels may change because of updates done by Microsoft. The following steps had been made with the version with the Azure portal from August 2021. Note also that the images are scaled. If you need a sharper image, just click on it to see it in full size

== Preparation ==
During the creation of an app, you need some information provided by the configuration of the CalendarApp and also add some information given by Azure. Because of that it is recommended to open the PBX Manager / AP Calendar in myApps (click on Configure and select “Cloud (Exchange Online)” as Sync Type) and the Azure Portal in your browser at the same time. You also have to login to the Azure Portal with an admin user to be able to add an application registration as well as to configure it.

If you get stuck or you need additional information, or if you are unsure if the way describe here is the best solution for your company, be free to use all the documentation and help links Microsoft provides in the Azure portal.

= Registering the Calendar app to the Azure Active Directory =
== Open the Azure Portal Active Directory ==
[[Image:AD_SelAD.png|thumb|upright=5.0|right|Azure Portal]]
[[Image:AD_Overview.png|thumb|Azure Active Directory Overview]]
* Go to the [https://portal.azure.com Azure Portal homepage] and sign in with your admin user
** Select “Manage Azure Active Directory” or click on one of the “Azure Active Directory” links.
** You will be redirected to the Azure Active Directory Overview
 
 
 
 
 
 
 
 
 
 
 
 
 
 

== Add a new App registration ==
[[Image:AD_CreateAppRegistration.png|thumb|Add new app registration]]
[[Image:AD_RegisteredAppOverview.png|thumb|Registered app overview]]
* Create an app registration
** Click on “+ Add” and select “App registration” (alternatively click on “App Registration” on the side bar and add an App registration by clicking on “New registration”)
** Set a name for the registration (e. G. innovaphone Calendar)
** Select the supported account type (see note below).
** Select "Web" in the dropdown list under "Redirect URI" (just enter the URI that you can find in the "Redirect URI" field of the PBX Manager / Calendar configuration).
** Click "Register" to save the App Registration. On success, you should see the overview page for the registered app.
 
 
'''Note:''' The account type should be either “Accounts in this organizational directory only (YourCompanyName only - Single tenant)” (which is recommended) or “Accounts in any organizational directory (YourCompanyName - Multitenant)”. If you go with the single tenant, you have to select “My organization only” in as “Selected account types” for the Calendar configuration. If you select multitenant, “Multiple organizations” have to be configured.

 
 
 
 
 
== Configure the client secret ==
[[Image:AD_CreateClientSecret2.png|thumb|Create client secret]]
[[Image:AD_CreateClientSecretDone.png|thumb|Client secret list]]
* Click on “Certificates & Secrets” in the list on the left
** Then click on “New client secret” under the “Client secrets” section
** Define an expiration date (the client secret itself will be randomly created)
** Optional: add a description
** Click on "Add" - the secret should be visible in the list
** Copy the value (click in the icon beside the value) and insert it to the "Client secret" field in the Calendar configuration

Note: after a couple of minutes, the Value of the client secret will be grayed out by Azure and you can’t copy it anymore. If that happens, just delete the old, create a new one and copy the value.
 
 
 
 
 
 
 
 
 
 

== Configure the first permissions - the manifest ==
[[Image:AD_Manifest2.png|thumb|Manifest file]]
* Click on “Manifest” in the sidebar
** Scroll down the Manifest-File until you see the “requiredResourceAccess” property
** Add the data block from box below (including the ',')
** Click on save - the manifest should similar to the one in the screenshot

'''Note:''' If you want, you can replace the existing part with in the manifest with the block below (in that case without the comma after the closing ‘}’ bracket). This will remove the Users.Read right, which isn’t used anyways (but it also won’t hurt, if the right still exist).

{
"resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
"resourceAccess": [
{
"id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40",
"type": "Role"
}
]
},
 
 

== Configure the second permissions - Microsoft Graph ==
[[Image:AD_APIPermissionsList2.png|thumb|Exchange Online - Full access as app]]
[[Image:AD_APIPermissions_EWS.png|thumb|EWS - Access all user]]

* Click on API permissions on the right
** Due the changes in the manifest an entry "Office 365 Exchange Online" with the subitem "full_access_as_app" should be visible
** Click on “Add a permission”.
** In the following dialog click on “Microsoft Graph”
** Click on “Delegate permissions”
** Type “EWS” into the search field
** Click on the arrow before "EWS" and select “EWS.AccessAsUser.All”
** Click on "Add permission"
** You should see "EWS.AccessAsUser.All" under the "Microsoft Graph" section of the list
 
 
 
 
 
 
 
== Configure permission - set rights ==
[[Image:AD_APIPermissionsList.png|thumb|Permissions not granted]]
[[Image:AD_APIPermissions_AdminCosentGranted2.png|thumb|Permissions granted]]
* The permissions should may have the status "Not granted..." or no status at all.
** Click on "Grant admin consent for...." button above the list
** Confirm the question shown by a message box
** All premissions should now have the status "Granted for..."
 
The Calendar app registration is now successfully completed.
 
 
 
 
 
 
 
 
 
 

= Setting up the Calendar configuration on the App Platform =
* Open the PBX Manager in myApps, click on Calendar and then on "Configre" (if not already done)
** Set the fields like shown in the table below
** Click on "Authenticate" and follow the instructions
** On success, the Calendar OAuth2 configuration is completed
 
{| cellpadding="2"
| '''Field'''
| '''Value'''
|-
|Sync-Type:
|Cloud (Exchange online)
|-
|User:
|The user with the Application Impersonation right in Exchange
|-
|Autodiscover URL:
|https://autodiscover-s.outlook.com
|-
|Exchange server to use:
|Either external or internal, depending on your configuration. However, external should be fine for most Exchange 365 installations.
|-
|Client ID:
|The Application (client) ID from you AD app registration
|-
|Supported account:
|“My organization only” or “Multiple organization”, depending what you configured during app registration (see above).
|-
|Redirect URI:
|Nothing to change here - leave it unchanged
|-
|Scopes:
|https://outlook.office365.com/.default
|-
|Client Secret:
|The value of the client secret you from your application registration (see above).
|}
 
 

= Troubleshooting =
== Authenticating error with Autodiscover ==
If you run into authentication problems with the Autodiscover server, it can be that the default security settings are enabled for your Active Directory (which probably will be the case for new Exchange Online Setups). In that case, configure the security settings to allow access to the Autodiscover server or disable the default security settings, like described here:

https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/concept-fundamentals-security-defaults

== Finding an alternative Autodiscover server ==
You can also try to find an alternative Autodiscover server by using the Microsoft Autodiscover V2 API. To do so, just enter the following URL to your browser (replacing the email address placeholder first): https://outlook.office365.com/autodiscover/autodiscover.json/v1.0/<Email-Address-Of-Your-Impersonation-User>?Protocol=AutodiscoverV1

If your impersonation user has the email address impersonation@mycompany.com, the URL will be: https://outlook.office365.com/autodiscover/autodiscover.json/v1.0/impersonation@mycompany.com?Protocol=AutodiscoverV1

You should receive a simple text message that may be similar to the following:

"Protocol":"AutodiscoverV1","Url":"https://outlook.office365.com/autodiscover/autodiscover.xml"}

Your Autodiscover server will be the part from https to the first /autodiscover part (in this example https://outlook.office365.com)

== Using On-Premises as fallback ==
If because of some configuration on the Exchange / Active Directory side or whatever reason the above guide won’t help, you still should be able to switch to On-Premises connection even with Exchange Online. Just configure the Calendar using the PBX Manager as follows:

{| cellpadding="2"
| '''Field'''
| '''Value'''
|-
|Sync-Type:
|On-Premises (local network)
|-
|User:
|The user with the Application Impersonation right in Exchange
|-
| Password:
| The password of the user
|-
|Autodiscover URL:
|https://autodiscover-s.outlook.com
|-
|Exchange server to use:
|Either external or internal, depending on your configuration. However, external should be fine for most Exchange 365 installations.
|}

If the connection to the Autodiscover server failed, you can use the above way to get an alternative server and / or disable the default security settings for your AD.

= Related Articles =
[[Support:Calendar App 13r3/14r1/14r2 - Exchange Online Impersonation Deprecation]] 
[[Howto13r3:Setting up the Calendar App with OAuth2 and app-only authentication]] 
[[Howto15r1:Configure Calendar Presence Sync by Connector for Microsoft365]]

Howto:Firmware Upgrade V12r1 V12r2

2024-03-04T17:43:04Z

Bsiegwald: Related Article linked to correct Howto category

== Applies To ==
This information applies to:


* All PBX devices
* All DECT devices
* Linux Application Platform

== Configuration Changes ==

=== Changed Semantics of conditional Call Forward ===
From the beginning, phone numbers used as a condition in an E.164 setup needed to be configured as full numbers starting from the root node. This is obviously wrong so that it has been fixed for v12r2 (see fix ''13402 - PBX use adjusted number for checking numbers on call forward'').

=== Apply updated SIP Provider Profiles ===
SIP provider profiles create a particular configuration once you save the it from the profile's configuration dialogue. They do not change "under the hood", even if you install a new firmware that may include updated settings. To apply such updated settings, you need to open the provider's configuration dialogue and apply it using the ''OK'' button.

The SIP profile creates also automatically routing-table entries from and to the respective SIP-interface. An update of the SIP-profile by the OK button, will therefore also recreate these routing entries. As a result, modifications (e.g. CDPN-maps) of the profile-created-routes must be redone after updating the profile. To circumvent this problem, it is recommended to not modify the routes created by the profile but create additional routes for the own modifications.

==Hardware Restrictions==
For a list of devices with no/restricted support in 12r2, see the [[Howto:Firmware_Upgrade#Version_12r2 | Firmware Upgrade article]].

== Software Requirements ==
myPBX now requires .NET 4.5.2 (v12r1 only required .NET 4).

==Known Problems==
=== Main Memory (RAM) Considerations ===
New firmware always has more features which in turn requires more resources. Growing firmware will thus consume both more flash and RAM for sure. A given system configuration will run flawlessly after a firmware largely only if there is still enough memory left after boot. As a rough rule of thumb, a v12r2 release will consume ~ 1 MB RAM and 0.4 MB flash more compared to a v12r1 firmware.

Standard configurations which are according [[Howto:How_to_implement_large_PBXs#Technical_data_and_recommended_number_of_users_supported | to spec ]] will run on all supported hardware. However, unusual configurations may not. It is a good idea to examine both flash and RAM memory left on high load situations in your existing configuration to see if there is enough resources left for an upgrade. Please find details in [[Reference:Device Health Check]].

=== Flash Memory Considerations ===
New firmware comes with new code for new features which consumes more flash memory for the firmware image. For this reason, devices may run out of flash memory during upgrade to v12r2. Here is the recommended procedure for upgrade on such devices:

* save entire configuration
* reset to factory defaults
* load saved configuration (this will reorganize flash memory usage)
* upgrade to new firmware

When there is still not enough flash memory available to store the new firmware, the web GUI will issue a ''Firmwareupdate failed:no space'' during firmware upload. If the firmware upload is done using the update client, a ''Error 0x00130001 Major FLASHMAN0 no space'' event will occur.

With the new firmware, the amount of flash memory allocatable for the LDAP directory (that is, PBX config and call lists) is less than before to accommodate for the larger requirements. See <code>http://x.x.x.x/!mod%20cmd%20FLASHMAN0%20info%20state</code> for details (after upgrade).

On older IP110, IP200a, IP230 and IP240 phones, the SIP module has been removed from the firmware.

== Related Articles ==
*[[Howto:Guideline V5 to V6 upgrade]]
*[[Howto:Upgrade Issues V5 to V6]]
*[[Howto:Firmware Upgrade V6 V7]]
*[[Howto:Firmware Upgrade V7 V8]]
*[[Howto:Firmware Upgrade V8 V9]]
*[[Howto:Firmware Upgrade V9 V10]]
*[[Howto:Firmware Upgrade V10 V11r1]]
*[[Howto:Firmware Upgrade V11r1 V11r2]]
*[[Support:Special_Precaution_required_when_upgrading_IPxx11_Gateways_from_pre-SR14_Firmware_Versions]]
* [[Howto:Firmware Upgrade V11r2 V12r1]]
* [[Howto13r1:Firmware_Upgrade_V12r2_V13r1]]
[[Category:Howto|{{PAGENAME}}]]

Reference8:TAPI Service Provider

2023-12-14T16:58:51Z

Bsiegwald:

The ''innovaphone PBX V8.0 based TAPI Service Provider'' (TSP) is an enhanced version of the [[ Reference7:Unified Win32 and x64 TAPI Service Provider | previous TSP version ]] that takes advantage of the [[ Reference8:SOAP API | new SOAP features ]] provided with version 8 PBX firmware. It implements - like the previous versions - TAPI Version 3.0 without MSP (Media Service Provider).

The [[Reference7:Unified Win32 and x64 TAPI Service Provider| previous TSP ]] still must be used for V7 PBX systems.

This article describes how to install and use it as well how to configure the PBX in order for the TSP to work properly.

==Applies To==
This information applies to
* innovaphone PBX V8.0 based TAPI Service Provider, Build 8001 and later
* innovaphone PBX V8 and later (that is, this Service Provider runs with PBX Firmware V8 and later)

==More Information==

=== Enhancements ===
; Support for V8 firmware [[Reference8:Administration/PBX/Objects#Devices | devices]] : Each user object device is represented as a TAPI line (all sharing an identical address, the objects extension a.k.a. ''Number'' property). This now allows to select individual registration devices when multiple devices are registered with the same PBX. Please note that in V8, [[ Reference8:Administration/PBX/Objects/Edit_Forks | mobility devices ]] are not shown and thus not represented by TAPI line device. This was introduced in V9 only.
; Support for presence based lines : These are TAPI lines shown which reflect the users presence state. Presence state ''open'' is mapped to a TAPI device status ''in service''. Presence activity ''on-the-phone'' is mapped to a virtual call in state ''connected''.
: '''NB''': V8 PBX Firmware did set presence activity ''on-the-phone'' for each user object having a call. Unfortunately, as this does create performance issues, this behaviour has been removed from V9 PBX Firmware. The ''presence line'' feature may be useless with V9 PBX when the application did rely on this particular V8 PBX behaviour.

===System Requirements===
The TSP will install on any Windows 32bit and x64 platform down to Windows XP/Server 2003. For older systems, you must use a deprecated [[Reference7:TAPI_Service_Provider | previous TSP version]]. For systems running PBX firmware version 6 or earlier, you must use the even older [[Reference:TAPI_Service_Provider | version 5 based TSP]]. Note that there is no x64 version of the version 5 TSP!

The TSP needs to maintain parallel connections to each individual PBX in the system. For larger systems (i.e. systems with a huge number of PBXs), this may create substantial load to the underlying windows machine. The number of parallel activities scheduled by the TSP is thus limited as a function of the available main memory and number of processors. In particular, a maximum of 20 activities per available processor is allowed (up to build 8088, the limit is 60/processor for later builds). If this limit is exceeded, the TSP will issue performance warnings of class WARNINGS in the TSP log file and system TAPI performance will be poor. Use a more capable machine then.

Microsoft Windows operating system version for desktop clients (as opposed to server systems) limit the number and performance of TCP/IP connections. This may lead to bad performance or occasional request failures. We generally recommend to use server operating systems for 3rd party TAPI installations thus.

No special PBX licenses are required to use the innovaphone TSP.

=== Download ===
The TSP will be available on the tab ''Software'' in the [https://store.innovaphone.com/ Store].

===Installation===
Windows cannot run a Win32 TSP on an x64 platform (although it can run Win32 applications on such platforms). This is why there are 2 versions of the setup, the x64 installer (<code>setup64-release.msi</code>) and the Win32 installer (<code>setup32-release.msi</code>.

The ''release'' setup packages provided will install the retail version. This is recommended for production purposes but provides no debug options whatsoever. To track down possible problems, support may instruct you to install the debug version.

The TSP may be installed on each machine where a desired TAPI based
application is to be run. If for example, Outlook is to be used, then
each client PC running Outlook may have the TSP installed. Although
this is typical for a 1st party configuration, all clients may have full
3rd party functionality, that is, they may control all existing lines.

As an alternative, the TSP can be installed on a single machine and a
3rd party TAPI server product (such as the IXI-Call Server available as
a separate product) may be used to provide the network clients with a
TAPI interface. Also, Microsoft’s Remote TAPI Server should work but is not being tested, so you use it on your own risk.

To install,
* select and download the <code>setup32-release.msi</code> install packages on 32bit platforms or the <code>setup64-release.msi</code> install package on 64bit platforms.
* double-click the install package to launch the installer
[[Image:Unified Win32 and x64 TAPI Service Provider - zipcontent.png]]
* accept the license agreement
* select the target folder
* complete the installer

When the installer has copied all files to the target machine, you need to add the TSP to the machine's TAPI system
* open the ''Telephone and Modem'' control panel
* Switch to the rightmost tab (''Extras'')
* Click on the ''Add...'' button
[[Image:Unified Win32 and x64 TAPI Service Provider - Control Panel Add.png]]
* Select the innovaphone TAPI provider driver
* Fill out the configuration dialogue
* Install the provider by clicking ''OK''

==== File Organization ====
Windows forces all TAPI service provider files to reside in Windows' ''System Folder''. This is the <code>system32</code> folder in your windows install directory (usually <code>C:\windows\system32</code>), even if you are running an x64 platform! The installer will thus copy these files (<code>tsp8.tsp</code> and <code>tsp8UI.dll</code>) in to this directory. All other files however will be copied to the <code>innovaphone AG\innovaphone® PBX V8 TAPI Service Provider</code> folder underneath your systems ''Program Files Folder''.

The subdirectories <code>Debug</code> and <code>Logs</code> are created. <code>Debug</code> contains the driver's debug version, <code>Logs</code> will receive the log files when a debug version is used.

On x64 platform systems, the Win32 version of the configuration DLL (<code>tsp8UI.dll</code>) will be installed to the windows ''Windows on Windows64 System Folder'' (<code>SysWOW64</code>).

====Upgrading to a newer Version====
When you attempt to upgrade the TSP from a previous version, the Windows
installer will first remove any previous installation. When the new
software is installed then, the TSP will be installed again into the
TAPI system.

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

====Upgrading from the old Win32-only Version====
If you upgrade from the older Win32-only versions of the TSP (soap-appl/tapi/7.00 or soap-appl/tapi/5.00), you must first remove the old TSP from ''telephone and modem'' control panel and uninstall the old product from the ''Software'' (or ''Programs and Functions'') control panel.

When you upgrade from the old V7 64-bit TSP (soap-appl/tapi/7.00-64), you should first update this older version to the latest build available.

This procedure ensures that during the upgrade your TAPI lines retain their internal identifiers and thus their meaning in your TAPI application's configuration.

==== Uninstalling the TSP ====
To uninstall the TSP proceed as follows
* Remove the TAPI driver from the TAPI system using ''Telephony and Modem Control Panel''
* close ''Telephony and Modem Control Panel''
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* remove the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

You will notice that Windows may fail to remove the driver files from the ''Windows System Directory''. To clean up remove <code>tsp8.tsp</code> and <code>tsp8UI.dll</code> from the <code>system32</code> folder as well as - on x64 systems - from the <code>SysWOW64</code> folder.

Also, if you did file tracing, any remaining debug files in the <code>Logs</code> folder are left over and need to be removed manually.

The TSP will create some entries in the windows registry which will not be removed on uninstall. It is recommended to leave these entries as is. Only if you are sure you will never install the TSP again on this system or you are sure you will never use it with the PBX installation you used so far, you may want to delete them from the registry.

==== Rolling out First Party TSPs to multiple PCs ====
Normally, when multiple users require CTI and hence TAPI functionality, the best way is to use a server based, multi-client 3rd party CTI application. This will share all functions among all client PCs. If this is not an option, e.g. because the TAPI application in use does not support it, you may want to consider using Microsoft's TAPI Server and remote TSP. See Microsoft's [http://technet.microsoft.com/en-us/library/cc786297%28v=ws.10%29.aspx Telephony service providers overview] and [http://technet.microsoft.com/en-us/library/cc770373.aspx Manage Telephony Servers] documents.

If you still want to use the native innovaphone TSP on a number of PCs (instead of once on a server), you can roll out the TSP using some of the [http://support.microsoft.com/kb/816102/EN-US software deployment schemes Microsoft Server provide]. In such a case, you will likely want to deploy identical configurations to all these PCs. While this theoretically can be done by distributing registry settings, there will be a problem with the PBX access credentials. These are stored in encrypted format in the registry and can only be decrypted on the PC on which they have been set. That is, deploying such registry settings to other PCs will result in a non-functional setup.

To work around this problem, you may store the credentials in clear text in the registry. To do so, you would put the ''Password'' in a REG_SZ value named <code>admin1-free</code> and the ''Account'' into a REG_SZ value named <code>admin2-free</code>. If such a value is found in the proper place in the registry, the values configured using the telephony control panel are ignored.

[[Image:TAPI Service Provider-tsp8-nocrypt.png]]

'''Keep in mind that having credentials in clear in the registry presents a security risk!'''

This feature is available in build 8079 and later.

=== Upgrade from Build 8164 or earlier ===
From build 8165, the TAPI configuration has been moved to a different registry location. This has been done because latest windows versions (namely, Windows 10) do not allow the TSP to access registry information in the location used so far (<code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>). To work around this issue, it is now stored in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>.

The TSP configuration dialogue however runs with user privileges (as opposed to the TSP which runs with limited service privileges). It can therefore read the old configuration information and copy it to the new location. From build 8165, the configuration dialogue will thus copy any old configuration information to the new location when it is opened. When you upgrade an existing installation and open the configuration dialogue, you will see no change. However, when the configuration is saved, it is then present in the new location.

'''To upgrade an installation from build 8164 or earlier (that is TAPI 'V8 TAPI Service Provider (32 and 64bit) - hotfix14'' available in the ''V8 applications hotfix20'' package or earlier), proceed as follows:'''
* stop the telephony service (e.g. <code>net stop tapisrv</code>)
* install the new TSP
* open the TSP configuration dialogue
* verify the configuration data
* save the configuration
* (re) start your TAPI application

If you fail to migrate the configuration as described, the TSP will start, but not work!

===Configuration===
The TSP configuration dialogue looks like this:

[[Image:Unified Win32 and x64 TAPI Service Provider - Config UI.png]]

* The ''VERIFY'' button will verify the configuration. Note that the ''Username'' drop down list will only be populated after a successful verify.
* The ''OK'' button will save the configuration.
* The ''CANCEL'' button will quit the configuration without saving any changes. If it is the initial configuration while you add the TSP via the telephone and modem control panel, the TSP will not be added

TAPI talks to the PBX using [[Reference7:SOAP_API | SOAP ]] which in turn uses HTTP for communication. Both secure (https) and non-secure (http) communication is supported. In any case, HTTP basic authentication is used.
To be able to connect to the PBX, the TSP needs to know proper credentials to use during HTTP authentication. These are referred to as ''PBX Account'' and ''PBX Password''. Also, a suitable ''TAPI User'' must be selected.

==== Controlling the Line Devices handled by TAPI ====

TAPI connects to your PBX as a PBX user referred to as ''TAPI User''. It will see all PBX objects that are members of groups in which the ''TAPI User'' is an active member. If the ''TAPI User'' is not an active member in any group, TAPI will see the ''TAPI User'' object only. This may be useful in a [http://en.wikipedia.org/wiki/Telephony_Application_Programming_Interface 1st party TAPI scenario]. PBX objects are represented as TAPI lines.

The PBX object you use as ''TAPI User'' needs to have at least ''Viewing only'' [[Reference:Administration/PBX/Objects/Edit Rights | PBX user rights]]. Its ''Long Name'' property is used as ''TAPI User Username'', its ''Name'' property as ''PBX Account'' and the password as ''PBX Password''. This is why the PBX object used as ''TAPI User'' must have a password configured.

===== 1st Party Configuration =====
In a 1st party scenario, the TSP will only work on a single PBX object. This will typically be a user's phone and thus the user itself will be used as the ''TAPI User''.

[[Image:Unified Win32 and x64 TAPI Service Provider - FirstParty.png ]]

In such a configuration the TSP is typically installed on the users PC and the CTI software is accessing TAPI directly (such as e.g. Microsoft Outlook does).

The TSP configuration dialogue will check for the number of lines seen. If it is only one, then it will issue a warning message:

[[Image:Unified Win32 and x64 TAPI Service Provider - OnlyOne.png]]

This is because 3rd party configurations are much more common and this situation often indicates a configuration problem. In a first party configuration, you can safely ignore this message.

===== 3rd Party Configuration =====
In a 3rd party configuration, the TSP will work with multiple PBX objects.

[[Image:Unified Win32 and x64 TAPI Service Provider - ThirdParty.png]]

Typically, you will share a single TSP instance on a server system for use by several users on their desktop PCs. This is done by virtue of a ''TAPI Server''. There are various TAPI server products available on the market, including but not limit to the Estos ProCall product and the remote TAPI server included in Microsoft Windows server operating systems.

In this scenario, it is recommended to create a pseudo PBX user object for use as the ''TAPI User''. This pseudo user is often called <code>_TAPI_</code>. You would create a dedicated group to control the list of PBX objects the TSP creates a line device for. This group is often called <code>tapi</code>.

==== Selective Call Forwards ====
Many CTI applications support distinct call forwards for internal and/or external calls. The TSP will translate such requests to a call forward on the PBX which has the [[Reference7:Administration/PBX/Objects/Edit_CFs | ''Only'' or ''Only not'' property]] set to the number of the trunk line. For this to work, it needs to know this number. To know the number, the trunk line PBX object must be seen by the TSP (see above). If this is not the case, the TSP configuration dialogue will issue a warning:

[[Image:Unified Win32 and x64 TAPI Service Provider - NoTrunk.png]]

In a vanilla first party scenario, this is obviously not the case. If you don't care, you can safely ignore this issue. Attempts to set such call forward will be rejected then as ''operation unavailable''.

In a Master/Slave PBX scenario where there is no Trunk Line object on the Master PBX, but only on the Slave PBXs, a workaround is required to suppress the warning and enable selective call forwarding on the Slave PBXs. In this case, create a dummy "Trunk Line" object on the Master PBX with the same extension number used by the "Trunk Line" objects on the Slave PBXs (usually 0).

==== Multi Site Configuration ====
In a system with multiple PBXs, the TSP needs to connect to each of the individual PBXs.

[[Image:Unified Win32 and x64 TAPI Service Provider - MultiSite.png]]

In this case, you would specify your master PBX as ''PBX Master''. There is no need to configure the complete PBX tree to the TSP as it is determined dynamically on runtime by analysing the PBX/Node objects in the master PBX and their registration status. If a registered PBX is found, this PBX is added to the list of active PBXs and a new connection is established. The PBX tree is built and maintained dynamically. A reconfiguration or restart of the TSP is not required on changes thus.
For this to work

* the PBX object used as ''TAPI User'' must exist in each PBX with same properties (including name and the password). You may want to use <code>_TAPI_</code> as ''Name''/''Long Name''. This object must be ''active'' member in a group (which you may want to call <code>tapi</code>). A password must be set. The object must have at least ''Viewing only'' rights
* the slave PBX-objects (or in older firmware versions the slave PBX Node-objects) must be visible to the TSP (that is, must be non-active member of the group the ''TAPI User'' object is an active member of, e.g. <code>tapi</code>) so that the slaves are made known to the TSP.

In a replicated scenario, you would create a ''TAPI user'' as recommended above and [[Reference8:Administration/PBX/Objects#Objects_with_empty_node_or_PBX | leave the ''PBX'' and ''Node'' properties empty ]]. This user should then be used as both ''PBX Account'' and ''TAPI User Username'' in the TAPI configuration dialog.

''Further relevant settings'':

You can disable slave detection by checking ''Do not monitor slaves'' property in the TSP configuration dialogue.

TAPI maintains an ''address'' property per line device. This usually is the lines extension. In a multi site configuration, the address property will be set to the ''Number'' property of the node the respective PBX object is configured in, plus the ''Number'' property of the object itself. So if an object has ''Number'' <code>42</code> and lives in node <code>801</code>, then its correspondence line device will have address <code>80142</code>. By checking the ''Use pure node extensions'' property in the TSP configuration dialogue, you change the algorithm so that only the objects own ''Number'' is used (<code>42</code> in our example).

==== Standby Configurations ====
In a system with standby PBX for the master PBX, you need to specify the ''PBX Standby'' IP address. This will be connected if the master is unavailable. Note that there is no need to explicitly configure slave-standby PBXs.

==== Working with multiple, unrelated PBXs ====
When working with multiple, unrelated PBXs (that is, PBXs that do ''not'' form a PBX tree as slaves and masters do), the TSP cannot derive the list of PBXs to track from the registration status. To support such a configuration, you will need to configure the extraneous master PBXs manually using regedit. Please note that using regedit may harm your system and may even cause inability to boot!

To find and edit the right registry entries, proceed as follows:

* open the key <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>
* open its subkey <code>Device</code>''n'' where ''n'' is the provider id of the installed innovaphone TSP (for builds before 8164 only)
* Open the <code>FQDN</code> key and add all extra PBXs
* For those PBXs that have a standby PBX, add a value to the <code>StandbyFQDN</code> key (please note: these are parallel lists. So master and standby need to have the same respective index in the <code>FQDN</code> and <code>StandbyFQDN</code> value lists)

The standard configuration UI will not show these extra values. However, it will also not touch them. So even if you use the standard UI to edit, only the first value in the lists will be changed and the remainder left unchanged. You can thus safely use the standard UI to edit all other values. As with multi site configurations, all PBXs need to be accessible using the same ''TAPI User''.

Please note that this method is deprecated and will likely be removed from future versions of the TSP.

==== Setting the Line Device Name ====
The TSP will derive the line device's name from the properties of the respective PBX object. By default the name will be the objects ''Long Name'' followed by the name of the PBX the user ought to register with in parentheses. So if the users ''Long Name'' is <code>Foo Bar</code> and the registration PBX is <code>branch1</code>, the line device will be called <code>Foo Bar [branch1]</code>. You can specify a different pattern by changing the ''TAPI Line Names'' property of the TSP configuration dialogue. The following replacement characters are available:

{|
|+
| Meta || Replacement
|+
| %c || The objects ''Long Name'' (cn)
|+
| %C || The objects ''Long Name'' (cn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Long Name''
|+
| %d || The objects ''Display Name'' (dn)
|+
| %D || The objects ''Display Name'' (dn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Display Name''
|+
| %h || The objects ''Name'' (h323 alias)
|+
| %H || The objects ''Name'' (h323 alias) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Name''
|+
| %t || The ''Name'' of the ''Device'' the line represents
|+
| %T || The ''Hardware Id'' of the ''Device'' the line represents (from build 8181)
|+
| %e || The objects extension (e164)
|+
| %E || The objects extension (e164) prefixed with the objects node number
|+
| %N || The line address as reported to TAPI
|+
| %n || host name (of master pbx)
|+
| %p || ''':'''''port-number'' (of master pbx's http access, empty if 80)
|+
| %P || raw port number of master pbx
|+
| %u || url-like user name ('''''user''@''host''''')
|+
| %U || user url as per draft-levin-iptel-h323-url-scheme-04 ('''h323:://''user''@''host'':''port''''')
|+
| %X || the PBX name the user is registered with (note that using this pattern may result in a change of the name when a standby situation occurs)
|+
| %x || the PBX name the user is reported by (note that using this pattern may result in a change of the name when the users ''PBX'' attribute changes)
|}

The default pattern is <code>%C (%x)</code>.



==== Miscellaneous Flags ====
; Show full E164 Numbers : when set, the TSP will announce the full calling number from the root when indicated by the PBX in the TAPI ''calling party name'' attribute. The number will be appended to the calling name with a <code>@</code>.
; Do not show parked Calls : will hide parked calls from the TAPI application (as some get confused and don't know how to handle them)
; Map PBX Devices to Lines : if set, the TSP will create one TAPI line for each individual [[Reference9:PBX/Objects#Devices|PBX device]] configured in a user object. See [[#Enhancements]] above. If you do not set this flag, see [[Support:How should TAPI line device be registered?]]
; Map Presence Status to TAPI Lines : if set, the TSP will create one extra TAPI line for each PBX device object. See [[#Enhancements]] above.
; No special Disconnect Behaviour : normally, lines monitored by TAPI will behave slightly different when a call is terminated. With no TAPI on the line, the call will be disconnected immediately (from a PBX point of view). In cases where the phone would play some tones after termination of the call (e.g. a busy tone when the call has never been connected to the far end), this state is simulated by the phone and not visible to TAPI. Therefore, it is not possible to use TAPI functions on this call any more (as it in reality does not exist any more). When this flag is set, monitored lines will not be treated specially. Available from hotfix 6. To prevent the IP-Phone to play any tones after the call is disconnected, the phone preferences option '''Go onhook if final call is released by remote side even if handset is lifted''' can be activated. This is the feature of the IP-Phone is useful in a e.g. call center at agent phones and can be configured here [[Reference11r1:Phone/Preferences]].
: To prevent an innovaphone IP-Phone from playing any tones after a call is disconnected, the phone preferences option '''Go onhook if final call is released by remote side even if handset is lifted''' can be activated. This feature is useful for agent phones in a call center for example and can be configured in [[Reference11r1:Phone/Preferences]]

===Trouble Shooting===
The TSP will (from build 8095) write messages of type INFO (''informational messages'') or WARNING (''Warnings/Errors'') to the windows event log. Such events are always logged to the application log and event source is the provider name (''innovaphone® PBX V8 TAPI Service Provider'').

==== Turning on Debugging ====
There are 2 versions of the TSP, debug and retail, which are both copied to the machine during setup. The retail version is installed into the system directories, whereas the debug version is stored in a separate directory. This is available through a short cut in the Start menu.

The TSP can produce a number of debugging messages which can be helpful to debug issues (in both ''retail'' and ''debug'' builds). By default, debug messages are written to the systems debug buffer mechanism (using OutputDebugString()). Such messages can be examined using standard debugging tools, such as for example <code>dbgview</code> which is [http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx available from Microsoft].

Debug messages have a class associated with it and the amount of messages written can be controlled by enabling or disabling specific classes. This is done by setting a bitmask in the registry value <code>TraceLevel</code> in the <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/> key.

The easiest way to set the TSP's debug level is with the ''TSP Control'' utility (''tsptray.exe'') which is installed with the TSP.

The available classes include

{|
| Bit in <code>TraceLevel</code> || Class
|-
| 0x00000001 || Minimum tracing
|-
| 0x00000002 || TAPI api traces
|-
| 0x00000020 || Basic telephony object creation/destruction
|-
| 0x00000040 || Thread creation/destruction
|-
| 0x00000080 || Request creation/destruction
|-
| 0x00000100 || call related messages
|-
| 0x00000200 || Call id map
|-
| 0x00000400 || Warnings/Errors
|-
| 0x00000800 || Worker thread execution
|-
| 0x00001000 || Full lock/unlock notifications
|-
| 0x00002000 || Win32 Critical section create/destroy
|-
| 0x00004000 || Agent proxy support
|-
| 0x00008000 || constructor/destructor debug
|-
| 0x00010000 || development debugs
|-
| 0x00100000 || verbose debugging
|-
| 0x00200000 || SOAP trace
|-
| 0x00400000 || SOAP message dumps
|-
| 0x01000000 || ATL debug
|-
| 0x02000000 || line related messages
|-
| 0x04000000 || informational messages
|-
| 0x10000000 || dump call infos
|-
| 0x20000000 || dump PBX infos
|-
| 0x80000000 || output log messages to file
|}

If <code>TraceLevel</code> is not set, it defaults to (hex) <code>04000400</code> in retail builds and to (hex) FFFFFFFF in debug builds. A nice value to use is (hex) <code>92200580</code>. The <code>TraceLevel</code> can be changed during runtime of the provider (it may take up to 10 seconds though for the setting to take effect). In normal scenarios there is no need to install the debug version.

Both ''informational messages'' and ''Warnings/Errors'' are always turned on (from build 8095).

: A problem has been reported on Server 2008 x64 systems which may also apply to others. On such systems, the value of <code>TraceLevel</code> may be reset to its default every 10 seconds. A workaround is to change the account the Telephony service is running in from its default (usually ''Network Service'') to e.g. ''Local System''.

===== Crash Dumps =====
From build 8063 the TSP will write crash dumps to the log directory (usually something like <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8 TSP\Logs</code>) in case of a trap. In release installs, these are not very useful. For debug builds though, they include helfpul information. Please provide these files (the can be zipped to a great extent) to support if requested. A crash dump file will be called something like <code>TSP8build-hour#minute-day.month#seqnr.dmp</code>.

===== Forcing a Crash Dump =====
In rare cases, it may be useful to force a TAPI crash for debug reasons. This can be done by issueing a <code>lineMakeCall</code> with called number <code>0815</code>, called-subaddress <code>4711</code> and called-name <code>!crash!</code> or simply calling <code>0815|4711^!crash!</code> from phone.exe.

==== Saving Log Messages to a File ====
The <code>0x80000000</code> value is special, as it does not denote a message class. Instead, it turns on log file writing, both in retail and debug versions. For this to work, the registry value <code>DoTraceFile</code> must be set to <code>1</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/> when the TSP starts. If this value is not present, it defaults to <code>1</code> in both retail and debug builds. Setting it to 0 disables log file writing regardless of any other setting. This may save some CPU cycles for installations with a real large number of lines.

The TSP will keep 24 log files (a days worth) by default. This value can be changed using the <code>NumLogFiles</code> value in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>. Older log files will be removed. Also, when the TSP shuts down, it by default will remove all log files it created so far. However, any TSP will only remove log files created by itself. This ensures that if the TSP or the system terminates prematurely, the log files will be kept even if a new instance is started and terminated later on. Form TSP V8 hotfix 8 on, this behaviour can be tweaked by setting the DWORD registry value <code>KeepLogFiles</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>:
{|
| 0 || default || remove all log files on termination
|-
| 1 || || keep the last ''n'' log files (depending on <code>NumLogFiles</code>) on termination
|-
| 2 || || keep all log files
|}

Larger systems (500 monitored lines and more) can slow down considerably when using the debug drivers.

==== Installing the Debug Version ====
To install the debug version, you first install the retail version as outlined above. You then copy the debug driver files from the <code>Debug</code> directory to your windows system directory <code>system32</code>. You may want to use the shortcut to the <code>Debug</code> folder which has been installed to the start menu for convenience.

For the copy to work, proceed as follows
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* copy the debug driver files to your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>.(if the copying fails, we recommend to deactivate the telephony service. But don’t forget to reset it to automatically if you are done copying). Overwrite the existing files: <code>installer.dll, installer.pdb, TSP8.pdb, TSP8.tsp</code>
* if the copy does not succeed or the debug driver is not shown n the modem control panel after, it might be that a TAPI application re-starts the windows telephony before you actually to the copy. If so, you can set the ''Startup type'' of the Windows ''Telephony'' service to <code>Disabled</code> instead of ''Manual'' in the services control panel (''services.msc''). You can then ''Stop'' the services, copy the file and finally set the services mode back to <code>Manual</code>

When you open ''Telephony and Modem Control Panel'' again, you should notice that the TSP driver name has changed to the debug version.

==== Switching back to the Retail Version ====
To go back from the debug to the release version, proceed as follows:
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* delete the debug driver files from your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>
* repair the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

Please note that simply re-installing the driver from the original .msi without removing it from the system directory will not work.

===References===
The test applications provided with this setup comes from [http://www.julmar.com Julmar Technology Inc].

=== Limitations ===

Please note that there currently is a limitation to 2000 users being in
all active groups of a particular user. Thus, you cannot configure more
than 2000 users to be handled by TAPI on a single PBX. This is a PBX
limitation (and applies for all PBX groups).

TAPI has a flat line model. That is, all line numbers (aka
''extensions'') are considered to live in a single name space. As a
result, lines with identical numbers cannot be distinguished in TAPI
(although they can exist). All extensions in all nodes of a PBX
numbering tree are represented as TAPI lines. When the TSP works with a
PBX that implements a hierarchical numbering tree, then some lines may
receive identical numbers (their node-local extension which may overlap
between nodes depending on the setting of the ''Use pure node extensions'' property). When a TAPI application uses these numbers to initiate
calls to such lines, the call will work or not work depending on the
calling lines position in the numbering tree (that is, lines within the
same node as the called line will be fine, others may fail).

The PBX's SOAP interface (on top of which the TSP is built) has no primitives to initiate a directed call pick-up based on a target number. The TSP will reject such requests with ''Operation not available''. Pickup by name (which is understood as a group name) or unspecific is supported though.

==== Citrix Environments ====
What happens is that all Citrix sessions share the same TAPI driver. This allows all users in the Citrix sessions to select "their" line from the set of all TAPI lines. Then everything works as desired. It is important to note that theoretically one user can select the line of another user.
You can use the "Microsoft Remote TAPI Server", to implement access rights for lines for separate Citrix sessions.

===Known Problems===

* The TSP is not tested with Microsoft’s Remote Tapi Server. While some installation have reported this to work fine, others have encountered problems. This scenario is not supported by innovaphone
* The TSP will read its configuration when it is loaded by the system. Thus, configuration changes require a re-load of the TSP. Unfortunately, there is no reliable way to force the system to unload the TSP, so you may have to reboot the system for changes to take effect. See the [[ Howto:Troubleshooting_the_TAPI_service_provider | TAPI trouble shooting article ]] for details
* The TSP will use HTTP basic authentication to talk the PBX. So if you disable basic authentication in the PBX's configuration, the TSP will not work. It is recommended to use HTTPS
* TAPI requires the TSP to assign a unique id to each line device. This ID must not change between re-boots of the system or between upgrades of the TSP. This is done by keeping a persistent table in the windows registry (in the <code>lineGUIDs</code> subkey of <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>) that maps the PBX's line GUID to a fixed integer value (known as ''permanent line id'' in TAPI speak). This key is retained even on uninstall. To get rid of it, you must remove it manually
* Microsoft installer fails to remove driver files installed to the windows system folder. This is why the TSP driver files are still present after an uninstall of the software. To get rid of them, remove <code>TSP8.tsp</code> and <code>TSP8UI.dll</code> from both ''%windir%''<code>\system32</code> and ''%windir%''<code>\sysWOW64</code>
* From Version 9, hotfix 1, the PBX firmware will not list objects tagged as [[Reference9:PBX/Objects#General_Object_Properties | ''hide from LDAP'' ]] in the result of a [[Reference9:Concept_SOAP_API#UserInfo.5B.5D_FindUser.28string_v501.2C_string_v700.2C_string_v800.2C_string_cn.2C_string_h323.2C_string_e164.2C_integer_count.2C_integer_next.29 | FindUser() ]] call. As a result, such objects will not be shown in the TAPI configuration dialogue ''Username'' drop-down. If you want to use such an object as ''TAPI User'' you can simply type in the name without selecting it from the drop down.
* Sometimes, setting configuration with ''TSP Control'' (not the telephone control panel dialogue) does not work due to windows' ''User Access Control (UAC)'', see [[Howto:TAPI_TSP_Control_Windows7]] for Details
* Various users have reported that first party TSP installations do not work reliably with Microsoft Outlook. Symptoms reported are spurious error pop-ups from Outlook although there was no real problem. We do not recommend first party installations anyway (see [[#Rolling_out_First_Party_TSPs_to_multiple_PCs]] for a reasoning), but these issues are related to Microsoft Outlook only. No such problems have been reported with other first party TAPI applications. Consider using solutions like Estos ProCall instead.
* The number of parallel threads used within the TSP is limited to max. 60 per CPU. As each connected PBX (amongst other things) is handled by a separate thread, if you have a large number of PBXs connected and only have a single CPU, you may run out of threads, resulting in a WARNING messages ''about to spawn new workerthread (n requests, m threads) -- but limit l exceeded''. This usually happens when you run the TSP on a virtualized platform such as vmWare and only dedicate a single CPU. Ignoring this warning results in sluggish behaviour.
* The TSP can work with dynamic PBXs too. However, the TSP needs to determine the slave PBXs IP addresses from the master. If the slave is a dynamic PBX and it is hosted on the same device as the master and it is registered to the master using 127.0.0.1, the TSP will only learn the 127.0.0.1 as the slave's IP address. Of course, connection to the slave PBX will fail then.

==== TAPI Operation with 3rd party Phones or innovaphone Phones registered with SIP ====
Various TAPI functions rely on use of the [[Reference:Remote Control Facility|Remote Control Facility]] message. This message is not supported in 3rd party phones and also not fully supported in innovaphone Phones when they are registered to the PBX using SIP. Full TAPI functionality is thus only available for innovaphone phones registered to the PBX using H.323.

Known Limitations:
* Accepting an incoming call (lineAnswer)
* Automatic initiation of an outgoing call in handsfree mode (instead, the calling phone first rings and starts the outgoing call upon of-hook)
* toggle between 2 calls active on a phone (lineSwapHold)
* initiation and termination of a 3PTY (lineCompleteTransfer with mode LINETRANSFERMODE_CONFERENCE, lineDrop on a conference call)

==== TAPI on Windows8 / Server 2012 ====

Windows8 doesn't let you disable ''User Access Control'' (UAC) completely. This has the disadvantage that ''TSP Control'' (tsptray.exe) cannot change system registry entries, which it needs to do to e.g. change debug settings for the TSP.

There are 2 ways around it:
# use the hidden ''Administrator'' account on Windows 8
# elevate the tsptray.exe application

To use the elevated ''Administrator'' account on Windows 8 you first need to un-hide it:
* log in to an account with administrator rights
* use the ''Windows-Key+X'' shortcut and select ''Command Prompt (Administrator)'' (''Eingabeaufforderung (Administrator)''). An elevated cmd prompt appears
* type <code>net user administrator /active:yes</code>
* the fully elevated ''Administrator'' account is now available and you can log-in to this account as usual
* '''Please make sure the account has a password set - by default, it does not!!'''

To elevate the tsptray.exe application;
* log in to an account with administrator rights
* start a windows explorer
* change directory to <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8-x64 TSP</code>
* right click on <code>tsptray.exe</code> and open the ''properties'' (''Eigenschaften'') menu
* switch to the ''Compatibility'' (''Kompatibilität'') tab
* tick the ''Run as administrator'' (''Program als Administrator ausführen'') check mark
* save the settings

Please note that Windows 8 will not let you run any "Metro App" in elevated mode!

===== HTTPS =====
The TSP will not be able to talk to the PBX using HTTPS with Windows8 or Server2012. This [[Reference8:Release_Notes_TAPI_V8#3722_-_HTTPS_SOAP_connections_did_not_work_on_Windows8_.2F_Server_2012|has been fixed]] with V8 TAPI Service Provider (32 and 64bit) - hotfix10.
===== .Net 3.5 missing on Server 2012 =====
Server 2012 has no support for .Net 3.5 by default. Even more, it cannot be installed just by downloading it. Instead, the ''NetFX3 Feature'' needs to be enabled. Here is how:

Microsoft Windows [Version 6.2.9200]
(c) 2012 Microsoft Corporation. Alle Rechte vorbehalten.

C:\Users\Administrator>dism /online /enable-feature /featurename:NetFX3 /all /Source:''<path to windows setup, e.g. d:>''\sources\sxs /LimitAccess

See also
* [http://blogs.technet.com/b/aviraj/archive/2012/08/04/windows-8-enable-net-framework-3-5-includes-net-2-0-and-3-0-i-e-netfx3-feature-in-online-amp-offline-mode.aspx?PageIndex=2 Windows 8: Enable .NET Framework 3.5]
* [http://msdn.microsoft.com/en-us/library/hh506443.aspx Installing the .NET Framework 3.5 on Windows 8]

==== TAPI dialer fails from Outlook when Lync client was/is installed ====
We have received reports that 1st-party TAPI dial-out from Outlook does not work anymore when a Lync client was installed. Some users report that this phenomenon occurred only after an upgrade to Windows 8. Reportedly, this can be [http://support.microsoft.com/kb/959625/en-us fixed by setting a registry key as outlined in Microsoft's knowledge-base]. You may want to give this a try. However, we have not seen this issue ourselves and thus can't comment on it further.

==== Slow Network Performance ====
TAPI is pretty sensitive to slow network performance. While the TSP is multi-threaded, some internal locking must be done so that slow requests to a PBX my block other pending requests, resulting in unpleasant performance. The TSP will create ''Windows Event Log'' entries of type ''slow SOAP call performance'' if this is detected. You should inspect your event log regularly and resolve the reason for such network performance.

Long PBX request round-trips may have a number of reasons:

; slow WAN performance : of course, if the WAN is slow or unstable, bad performance is the result
; inappropriate QoS : SOAP is using HTTP/HTTPS. In a QoS enabled network, call signalling and RTP may work fine, whereas HTTP/HTTPS is considered to be of no importance. You need to keep in mind that such QoS policy may lead to bad TAPI performance, as the SOAP traffic used by the TSP (being based on HTTP/HTTPS) may be delayed. You should assign SOAP traffic a similar priority as you do for VoIP signalling
; overloaded PBX : HTTP traffic is treated on a low priority level in the PBX. If the PBX runs near to 100% CPU load, while all RTP and VoIP signalling will work well still, HTTP traffic may get severely delayed. You should make sure your PBX runs well under 100% CPU load to get good TAPI performance. See [[Reference:Device Health Check]] for more details

==== TAPI on Windows 10 ====
In Windows 10, the TSP is not allowed any longer to read/write its own registry tree. For this reason, it is not possible to store or read the configuration. As a result, the TSP will not work. To fix this, you need to modify the registry access rights so that the TSP has read/write access to <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>.

Note on windows registry paths<ref name="regkey">
Due to a change in ''Windows Registry Access Rights'' in Windows 10, from Build 8165, the configuration is stored in
: <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>
(a place that is suitable for Windows 10 too). Before, the configuration was stored in
: <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>

See [[#Upgrade_from_Build_8164_or_earlier| Upgrade from Build 8164 or_earlier ]] above for more details.
</ref>:
<references/>

=== Tweaks ===
There are a few configuration options which should be used rarely. They can be enabled by setting an appropriate registry key.

Since Hotfix 15 the location to set the interop tweaks has been changed to <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>:

; ProcessorMask : REG_DWORD. If set, the TSP will use <code>SetProcessAffinityMask(GetCurrentProcess(), set)</code> to limit TSP execution to one or more of the existing processors. Set to <code>0xff</code> by default.

; LineTimeOut : REG_DWORD. Can be set to a number of seconds the TSP should wait for the determination of lines to finish (default 90). On a large PBX, or a PBX with slow slaves, the determination might not finish in the default time frame. If this happens, TAPI applications may show ''Line unnamed'' line entries in their line list. If this is a problem, set it to a larger value (e.g. <code>120</code>).

; IgnoreDevStatus : REG_DWORD. Some applications get confused if TAPI reports line to be disconnected or out-of-service dynamically. Setting this to a non-zero value will disable any such notification.

; ClearFwdOnSet : REG_DWORD. If set to a non-zero value, the TSP will clear all current call forward settings before a lineForward request is executed. This implies that all call forward settings are ''replaced'' by the new settings. Standard behaviour is to only modify the settings, that is, replace all current settings of the same type with the settings found in the lineForward request (for example, if there is only one setting in the request that defines a CFU, then the current CFU settings are replaced by the new one provided. All others, such as e.g. CFNR settings, are left untouched).

: Tapi spec is pretty clear on how this should work: ''The provider should "unforward everything" prior to setting the new forwarding instructions''. Even though, for historical reasons, ClearFwdOnSet=0 has been the default in all TAPI versions prior to V8 hotfix 6, from hotfix 6 on, the default changes to 1, as this has turned out to be the widely accepted interpretation.

; No3PTY : REG_DWORD. See [[Reference8:TAPI_Service_Provider#Notes_on_3PTY_Conferences | Notes_on_3PTY_Conferences]] below.

; HiddenRecordingNumber: REG_SZ. Active recording in an innovaphone PBX is implemented as an implicit 3PTY conference with the recording sink as one of the parties. These will be shown as usual in the TAPI callstate. However, some applications get confused as this results in a situation, where a normal endpoint (read: phone) has more than one active (i.e. ''not on hold'') call. To suppress such calls in the TAPI call states, you can set this tweak to the number of the recording sink as configured in the phone's recording configuration tab. If so, any outgoing call from an endpoint that is registered with a PBX user object with a called number that equals the setting of this tweak, will be suppressed. So if your recording sink has the number <code>44</code>, you would set this registry value to <code>44</code> (this is available from TAPI V8 hotfix 8). Please note that this feature actually suppresses any call info for such calls, however, it does not revert previously announced call infos. So if the call is initiated using ''overlapped dialling'', all call states will be shown until the called number matches the value of <code>HiddenRecordingNumber</code> and all subsequent call states will be suppressed. This will probably leave the call shown in ''dialling'' state. The feature should be used for destinations which are called using ''block dialling'' only thus.

; SilentHold : REG_DWORD. When a call is put on hold using <code>lineHold</code>, the held party will hear ''music on hold'' emitted by the PBX. The hold-initiator will hear a dialling tone (PBX firmware v11r2 and up, with older versions the initiator would hear ''music on hold''). When <code>SilentHold</code> is set to a non-zero value, the initiating party will hear silence - i.e. no dialling tone (this is available from TAPI V8 hotfix 8).



; NoDuplicateConnectedCalls : REG_DWORD. If set to 1, the TSP will never show more than one call per line to be active. Extra active calls will be shown as ''on-hold''. The situation occurs e.g. when a user initiates a 3PTY conference on the phone. This essentially is a bug fix for Microsoft's OCS client which forces any extra active call on-hold, thereby disturbing the 3PTY function. If your are using [http://www.estos.de/download/software/eccg.htm ESTOS' Call Control Gateway]: from version ''2.0.1.1474 - 05.11.2008'' there is a fix for this same problem available. This option thus is deprecated.

; UseFirstLeg2 : REG_DWORD. TAPI allows only for a single leg-2 info (redirection information in case of a call forward). If a call is forwarded mutliple times, by default the last redirection is shown in TAPI. If <code>UseFirstLeg2</code> is set to 1 however, the first redirection is shown.

; UseNameForDeviceGuid : REG_DWORD. The TSP will create a TAPI line for each ''Device'' of each PBX object (if ''MapDevices'' is set). The internal unique identifier includes the ''Hardware Id'' found in the ''Device''. If this changes, the TAPI line representing the ''Device'' is considered new and a new TAPI ''permanent line id'' is allocated. This may be annoying cause when a device serial number (e.g. for a telephone) is used as ''Hardware Id'', replacing the device creates a new TAPI line. If ''UseNameForDeviceGuid'' is set to 1, the TSP will use the ''Device''s ''Name'' instead (which usually not changes). While this might be more convenient, be aware that you ''must'' make sure that no PBX object has duplicate ''Name''s! Otherwise, TAPI will get confused. Available from build 8178

; ShowConfGUID : REG_DWORD. If set and not 0, the TSP will implicitly set each call's CallData to a string such as "<code>conf-guid:</code>''call-guid''". ''call-guid'' is a 66-byte Unicode16 string (32 hex characters plus terminating 0). Note that this will interfere with an application's use of the lineSetCallData function (tapi.h) and is therefore disabled by default. Available from build 8190

===List of supported TSPI functions===

The TSP supports the following TAPI Service Provider Interface Functions. Note that these do not map one to one with TAPI user functions. For more information, see the Microsoft TAPI documentation.

*TSPI_lineAnswer
*TSPI_lineBlindTransfer
*TSPI_lineClose
*TSPI_lineCloseCall
*TSPI_lineCompleteTransfer
*TSPI_lineDevSpecific
*TSPI_lineDevSpecificFeature
*TSPI_lineDial
*TSPI_lineDrop
*TSPI_lineForward
*TSPI_lineGenerateDigits
*TSPI_lineGetAddressCaps
*TSPI_lineGetAddressID
*TSPI_lineGetAddressStatus
*TSPI_lineGetCallAddressID
*TSPI_lineGetCallHubTracking
*TSPI_lineGetCallIDs
*TSPI_lineGetCallInfo
*TSPI_lineGetCallStatus
*TSPI_lineGetDevCaps
*TSPI_lineGetExtensionID
*TSPI_lineGetID
*TSPI_lineGetLineDevStatus
*TSPI_lineGetNumAddressIDs
*TSPI_lineHold
*TSPI_lineMakeCall
*TSPI_lineNegotiateExtVersion
*TSPI_lineNegotiateTSPIVersion
*TSPI_lineOpen
*TSPI_linePark
*TSPI_linePickup
*TSPI_lineRedirect
*TSPI_lineSelectExtVersion
*TSPI_lineSendUserUserInfo
*TSPI_lineSetAppSpecific
*TSPI_lineSetCallData
*TSPI_lineSetCallHubTracking
*TSPI_lineSetCallParams
*TSPI_lineSetCurrentLocation
*TSPI_lineSetDefaultMediaDetection
*TSPI_lineSetMediaMode
*TSPI_lineSetStatusMessages
*TSPI_lineSetupTransfer
*TSPI_lineSwapHold
*TSPI_lineUnhold
*TSPI_lineUnpark

*TSPI_providerConfig
*TSPI_providerCreateLineDevice
*TSPI_providerEnumDevices
*TSPI_providerGenericDialogData
*TSPI_providerInit
*TSPI_providerInstall
*TSPI_providerRemove
*TSPI_providerShutdown
*TSPI_providerUIIdentify
=====Notes on Consultation Calls=====
This TSP supports the <code>lineSetupTransfer</code> function. However, strictly speaking, this function is not needed and should not be used. It is merely intended for applications which do not offer a consultation call interface to the user when this function is not available. Instead, <code>TSPI_lineMakeCall</code> can be used where <code>lineSetupTransfer</code> would be otherwise. The notion of a special ''consultation call'' is an idiosyncrasy forced by legacy PBX technologies which were not able to transfer two arbitrary calls. In these scenarios, a potentially to-be-transferred call needed to be linked to the primary call. The PBX can transfer two arbitrary calls and thus there is no need for <code>lineSetupTransfer</code>. This ability is indicated by the <code>LINEADDRCAPFLAGS_TRANSFERMAKE</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE </code> flags. The transfer is then requested by using <code>TSPI_lineCompleteTransfer</code>.

=====Notes on 3PTY Conferences=====
The TSP supports the management of 3PTY conferences. These can be initiated by using <code>TSPI_lineCompleteTransfer</code> with <code>LINETRANSFERMODE_CONFERENCE</code> instead of <code>LINETRANSFERMODE_TRANSFER</code>. This is indicated by the flags <code>LINEADDRCAPFLAGS_CONFERENCEHELD</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE</code>. The 3PTY function is actually implemented by the innovaphone IP phones (such as IP2xx). Therefore, these capabilities are only advertised if the line is based on a PBX user object. Still, some lines where the capabilities are advertised cannot do 3PTY (such as e.g. DECT lines, analogue lines, 3rd party devices, ...). So the call to <code>TSPI_lineCompleteTransfer</code> will succeed but the conference will not be initiated and the subsequent call states will not indicate a conference (as there is no).

Also, if non-telephone devices are registered with a PBX user object and these device have multiple concurrent calls (e.g. a call center connected with a multi-channel XCapi), these will be viewed as 3PTY calls (as this is the way such calls appear to the TAPI: a line with more than one non-held call). If these calls are in fact no 3PTY, this may lead to confusing call indications from TAPI. It is better to register such objects as a PBX gateway object. Special treatment of 3PTY calls can be disabled by setting the registry flag <code>No3PTY</code> (from build 8087 onwards).

A 3PTY conference will create a new call handle for the conference. The only operation available for such a handle is <code>TSPI_lineDrop</code>. This will terminate the conference and restore the state active before the conference was initiated (that is, the phone that implemented the conference will now have 2 calls, one active and one on hold). This is indicated by not setting <code>LINEADDRCAPFLAGS_CONFDROP</code>.

A <code>lineDrop()</code> on one of the 2 ''real'' calls involved will of course cancel this call and thus remove the 3PTY.

======Notes on Intrusion Calls======
A special case of 3PTY is an intrusion call initiated by a [[Reference9:Phone/User/Function-Keys/Partner | partner function key]]. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the intrusion call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is an intrusion call).

======Notes on Recording Calls======
A special case of 3PTY is a recording call. This effectively creates an user-invisible 3PTY on the phone. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the recording call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is a recording call).

Recording calls are shown as normal conferences (unless <code>No3PTY</code> is set). This might be confusing to applications and/or users. See the <code>HiddenRecordingNumber</code> tweak above for a method to hide such calls.

=====Notes on parked Calls=====
The PBX can park calls from and to any existing PBX object, e.g. by virtue of [[Reference8:Configuration/Registration/Function-Keys/Park | specific feature keys]]. They are parked to/from a numeric ''park position''. In SOAP however, calls are parked to an object by providing the objects '''UserInitialize()''' handle and a park position. Parked calls are then reported as straight calls with a distinct signalling state (8). The park position is not conveyed as part of the '''CallInfo''' record. To unpark, '''[[Reference8:SOAP_API#integer_UserPickup.28int_user.2C_string_cn.2C_integer_call.2C_string_group.2C_int_reg.2C_InfoArray_info.29 | UserPickup]]''' can be used providing the parked calls call handle as '''call''' argument.

The TAPI specification is unclear on how the address information required to '''lineUnpark()''' a call can be obtained by an application (except that it is returned from '''linePark()''' if the call was parked using TAPI). The TSP thus indicates parked calls on a line with a call reason <code>LINECALLREASON_PARKED</code>. The caller id information is set to the parked calls call handle. This way, the application can take the caller id information and provide it to '''lineUnpark()''' to unpark a call. If the appication does not support this mode of operation but supports '''lineUnpark()''' and lets the user input the park identifier, the user can just provide the caller id information.

Some applications do not care for parked calls (by examining the call reason) and just blindly report these calls like ordinary connected calls (thereby confusing the user). To work around this problem, reporting parked calls can be turned off in the TSP configuration dialogue.

=====Notes on sending User to User Information =====
The TAPI specification for sending UserUserInfo closely resembles the way ISDN defines this service. Although the innovaphone PBX supports this service both with H.323 and SIP, it is ''not'' supported in this TSP. Instead, sending user to user information is implemented using H.323/SIP messaging. However, there are some important deviations and limitations caused hereby:
* data is ''not transparent''. That is, the TSP only allows for null-terminated unicode to be sent. The data must be of even length and the last two bytes must be null.
* data is ''not sent within the call'', but by initiating a separate call. This implies that the target number used to send the message carrying the data to is 'guessed' from the available call data. For example, if the call is in a connected state and a connected number is known, the message is sent to the connected number. If the call is in the ringback state, then either the called number or - if available - the redirection number is used and so forth.
* message calls are not indicated by the SOAP CallInfo records. As a result, messages (that is, user to user information) cannot be received with TAPI and ''lineReleaseUserUserInfo is not supported''

=====Notes on sending proprietary innovaphone Remote Control Facilities =====
The SOAP [[Reference8:SOAP_API#UserRc.28integer_call.2C_integer_rc.29|UserRc]] function allows to send various [[Reference:Remote Control Facility|facility messages]] to an innovaphone phone device. In some cases, it is useful to be able to invoke this function through a standard TAPI mechanism. This can be achieved by using the TAPI '''lineBlindTransfer''' function. If the ''called party name'' provided as destination for the ''lineBlindTransfer'' (in ''lpszDestAddress'') has the magic value <code>USERRC</code>, then the ''called subaddress'' is converted to an integer and the result is sent as remote control facility to the call the blind transfer is applied for. For details on how to code the ''called party name'' and the ''called subaddress'' into ''lpszDestAddress'' see [http://msdn.microsoft.com/en-us/library/windows/desktop/ms726017%28v=vs.85%29.aspx Microsoft's ''Canonical Address'' specification]. This works from TAPI8 hotfix 4.

For example, initiating a blind transfer to <code>|16^USERRC</code> (empty address, subaddress 16 (that is, [[Reference:Remote Control Facility|''change to handset mode'']]), called name <code>USERRC</code>) will switch the phone having the call to be transferred into handset mode (and <code>|18^USERRC</code> will switch it back to handsfree mode). Of course, no actual transfer will happen in these cases (''lineBlindTransfer'' is merely used as a vehicle to send the facility to the proper call).

Such proprietary facility message can also be sent with ''lineMakeCall'' (that is, in SOAP's [[Reference8:SOAP_API#integer_UserCall.28integer_user.2C_string_cn.2C_string_e164.2C_string_h323.2C_int_reg.2C_InfoArray_info.2C_int_rc.2C_string_srce164.29|UserCall]] function). For example, setting up a call to <code>123|21^USERRC</code> will send an intrusion call to extension 123 and intrude any call that might be active there. This works from TAPI8 hotfix 6. Please note that the innovaphone TAPI service provider does not support TAPI's ''lineCompleteCall'' function with <code>LINECALLCOMPLMODE_INTRUDE</code> though (as TAPI's call model here does not fit with the PBX's call model). Please also note that intrusion calls look like 3PTY calls to TAPI (see [[#Notes_on_Intrusion_Calls|notes on intrusion calls]] above).

Remote control facilities are implemented by the telephone devices, so these functions are subject to the phone firmware in use.

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

== Related Articles ==
* [[Howto:Troubleshooting the TAPI service provider]]
* [[Reference8:Release Notes TAPI]]

Howto:Config or Password Recovery

2023-03-13T15:58:27Z

Bsiegwald: Highlighting of command to send config, minor rephrasing for clarification, added related articles

This article describes approaches to recover devices with lost admin password.

==Applies To==
This information applies to:

*IP3000, boot 320
*IP400, boot 319
*IP21, boot 326
*IP200, boot 338
*IP800, boot 405
*IP6000, boot 132
*IP22,IP24,IP302,IP305, boot 357

earlier boot code versions may not work or have different command names.

==More Information==

===Problem Details===
In case you have lost the password for an innovaphone device and there is no recent config backup available, you are still able to recover the device config.

There are two possible solutions, depending on given requirements:

*[[Howto:Config_or_Password_Recovery#Update_Server|Update Server approach]]
*[[Howto:Config_or_Password_Recovery#TFTP|TFTP approach]]

The prefered approach is to use an Update Server. The last resort is to use TFTP mode to download the device config.

===System Requirements===

Update Server approach:
*Update Server URL need to be configured '''before''' you have lost the password

TFTP approach:
*appropriate boot code version need to be installed on device
*gwload.exe
*TFTP client

===Update Server===
If you know that there is an [[Reference:Update_Server|Update Server]] URL configured on the device and you have access to the web server with an update script on it, you can change the polled update script as follows to reset the admin password on the device.

# reset password
config change CMD0 /name mydevicehostname /log on /user admin,ip6000
config write
# encrypt it
config activate
# remove from visible config
config change CMD0 /name mydevicehostname /log on
# done

In case one of ETH interfaces is configured as DHCP client, you can provide [[Reference:Update_Server|Update Server]] URL to device via DHCP.

===TFTP===
If the prefered usage of the Update Server approach is not possible you have to get the device configuration via TFTP as a last resort. Make sure you have read articles about [[Howto:How_to_Reset_IPXXX_%2C_factory_default%2C_led_behaviour%2C_tftp_mode%2Cclear_config%2Cgwload|Factory Reset]] and [[Howto:How_to_use_gwload|Gwload Utility]], before you start to recover the device configuration via TFTP.

====Set device to TFTP mode====
Setting the device in TFTP mode is made by pressing reset button on gateway for ca. 1,5-2 sec (active LED must blink 3 times). Be careful cause if you press reset button too long, it will perform a factory reset, which means the config is lost.
====Set IP adress of device with gwload====
Once set to TFTP mode, the device is without IP address so you have to set it with gwload:

gwload /gwtype 6000 /i 192.168.0.1 /setip

====Download config from device using TFTP-Client====
Now you can use any TFTP client to download the config from device. There two different versions of boot code, so config file on device can be called <code>c</code> or <code>config</code>.

Open shell of your operating system and type:

tftp -i 192.168.0.1 GET config config.txt

or if you have device with older boot code version:

tftp -i 192.168.0.1 GET c config.txt

Now you'll have a file with config text repeated several times in it, so you have to search for latest config that was saved in this ring buffer.

This config can be changed to a known password ( e.g. config change CMD0 /user admin,ip6000 ). After sending this config to the device:

gwload /gwtype 6000 /i 192.168.0.1 /setip /cfg config.txt

the new config is effective.
On the first start of the firmware the user/password definition is copied from the commandline to a crypted var.

This procedure keeps the configuration and the flashdir (ldap) directory because no long reset is done.

===Known Problems===
The <code>config.txt</code> file recovered with TFTP only includes the partial configuration (lines starting with <code>config change</code>). No <code>vars</code>, no <code>FLASHDIR</code>.


== Related Articles ==
[[Howto:How to use gwload]]

[[Howto:How_to_Reset_IPXXX_%2C_factory_default%2C_led_behaviour%2C_tftp_mode%2Cclear_config%2Cgwload | How to reset a IPxxx.]]

[[Howto:Change the default admin password in the config file?]]

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

Reference13r3:Concept App Platform

2022-09-02T17:22:33Z

Bsiegwald: RPCAP

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

== 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:
** /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).

= 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:
** /dev/sda1 ext2: 350MB (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

= 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.
* 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
* ## 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: your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: your_domain_name.key)
-----END RSA PRIVATE 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/11/auth-pg-hba-conf.html

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

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

= App Platform replication =

== Requirements ==

* 13r3 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.
* 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

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

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

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

== Reboot after an image update doesn't start as update is already running ==

If it happens, that the App Platform doesn't want to start an update because one is already running, 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.

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

== Resizing the disk of a Virtual machine ==

* 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
/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

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 CDRs (or other data written to a DB) won't be received 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 (user: root, pw: 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. (user: root, pw: 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

Reference13r2:Concept App Platform

2022-09-02T17:21:18Z

Bsiegwald: RPCAP

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

== 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:
** /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 AP (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 AP in a specific scenario, we see that in a real life environment an AP 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).

= 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:
** /dev/sda1 ext2: 350MB (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

= 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.
* 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
* ## 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: your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: your_domain_name.key)
-----END RSA PRIVATE 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/11/auth-pg-hba-conf.html

== 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 AP 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 AP 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 AP 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 AP 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 APs (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 AP is active at a time.

* One database, multiple APs (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 AP for one customer
* One AP for many customers
* Many APs for one customer
* Many APs for many customers

Attention: The V13 installer can only configure the scenario "''One AP 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 APs.

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

== 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'':
* ''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'': obsolete, use the Devices App for backups!

== Security ==
* ''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)

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

== Registered Access Domains ==

= Known Issues =

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

If it happens, that the AP 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 AP booted the ramdisk. 
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 AP should boot and run the already updated image.

== Reboot after an image update doesn't start as update is already running ==

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

The AP now either applies the image update or it reboots into the old image. Try the image update afterwards 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 AP 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 AP 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 AP ==
To retrieve files from the AP which can not be retrieved via the AP manager UI, you can connect to the AP 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 AP (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 AP)
* use the ''DNS'' name or IP address of your AP (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 AP. 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
* 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 AP ===
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]] 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 AP 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]]

== Resizing the disk of a Virtual machine ==

* 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 AP 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
/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

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 CDRs (or other data written to a DB) won't be received 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 AP Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the AP-Plattform.

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

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 (user: root, pw: 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
** 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]]

Reference12r2:Concept myPBX

2017-12-18T10:29:10Z

Bsiegwald: Added info on which table the configuration info for the msi package should be placed in.

[[Category:Concept|myPBX]]
= Overview =
myPBX is the UC client of the innovaphone PBX. It is intended for assisting typical phone users with their everyday tasks. It consists of two parts:
* A '''web application''' that runs in any modern web browser. It provides the functionality needed for audio telephony, instant messaging, monitoring peoples statuses and more.
* The '''myPBX launcher''' is a Windows application that integrates the myPBX web application into the Windows desktop and adds some interesting additional features like video telephony and Outlook integration.

== Web application ==
The main user interface is an HTML5 application that runs in a web browser. It communicates with the PBX using HTTP-Requests (AJAX). The actual session logic is implemented inside the PBX.

The picture shows how call control is done. The myPBX session has access to the phone registration as they are both located in the same PBX. Thus it can monitor and create or modify calls.

[[Image:Mypbx_overview.png]]

The web application also includes a [[{{NAMESPACE}}:Concept myPBX WebRTC Softwarephone|WebRTC Softwarephone]] that works with some browsers.

== myPBX launcher ==
The launcher is a tool for integrating myPBX into the Windows desktop. It is not needed in order to use myPBX but it adds some convenient functions that are not available otherwise.
* Automatically open the myPBX web application on startup.
* Desktop notifications.
* Integrating external applications.
* [[{{NAMESPACE}}:Concept_myPBX_Video|Video telephony]]
* [[{{NAMESPACE}}:Concept myPBX Application Sharing|Application sharing]]
* [[{{NAMESPACE}}:Concept myPBX Office Integration|Office Integration]]
* Hotkey for dialing numbers out of any Windows application.
* Set the status depending on user activity.
* Switch to a standby PBX if the main PBX is down.
* Write trace files.

== Requirements ==
===PBX===
* myPBX license
* Reporting installation (for seeing recent calls in the history), although no reporting license is needed (as opposed to V9)

===Launcher===
* Windows 7 32bit/64bit or higher
* .NET 4.5.2
* Microsoft Visual C++ 2013 Redistributable (x86)

===Web browser===

If the myPBX is started inside the launcher, an embedded browser is used, so there are no special requirements.

If myPBX is started in a web browser that is installed on the local system, the browser must fulfill the following requirements:

* Current browser version
* JavaScript enabled
* HTML5 XMLHttpRequest (AJAX) enabled
* HTML5 Web Storage (DOMStorage) enabled
* HTML5 Cross-document messaging (postMessage) enabled

''Note: For IE the minimum supported version is IE 10.''

===Email addresses===
myPBX builds an email address of a user with the name (H323) and the System Name of the PBX. 
So if the System Name is '''innovaphone.com''' and the name (H323) of the user is '''test''', the resulting email address is '''test@innovaphone.com'''. 
So for every user an email address with this combination should exist. 
 
This email address should be the primary SMTP address in your Exchange Server. 
If this can't be done, make sure, that there is a SIP address on your Exchange user, which matches this email address.

See [[{{NAMESPACE}}:Configure_Active_Directory_Replication#Notes_on_replicating_the_new-in-V10_email_User_Attribute]] for details on replicating the email attribute from ''Active Directory''.

== Related technology ==
* myPBX uses the [[{{NAMESPACE}}:Concept_Reporting|innovaphone Reporting]] as a database for call lists. Alternatively the local [[{{NAMESPACE}}:Services/Call-Lists|call list service]].
* The [[{{NAMESPACE}}:Concept_Exchange_Calendar_Connector|Exchange Calendar Connector]] sets the presence of PBX users depending on their Exchange Calendar. myPBX can display that presence.
== Features ==
For a feature overview refer to [[Reference12r1:Concept_myPBX_derviates_and_features|myPBX derivates and features]].

= Configuration =

== PBX ==
''' Basic configuration '''
* Make sure you have installed the appropriate licenses.
** ''myPBX'' for the web application.
** ''Video'' for video telephony.
* Activate the licenses for the inidiviual user objects (''License'' tab). This can also be done using config templates.
* Enable myPBX on the page ''PBX/Config/myPBX''.
* To support call lists at the client, configure the ''Call List Service'' in [[{{NAMESPACE}}:PBX/Config/myPBX#Call_List_Service|''PBX/Config/myPBX'']]
''' Additional hints '''
* Only users with a password can login to myPBX.
* There should be a dedicated device configured at the user object for each phone registration.
* To use mobile phones, the mobility device must have a name in the fork config at the user object.
* The LDAP configuration is taken from the phone config at the user object.
* The dialling location has to be configured at the phone config of the user object.
* Phones should be registered using the PBX password so that user can change their login password without affecting the phone registrations.
* If federation is used ("use as domain" checked), the user names and the PBX system name should match the email addresses of people.

== Launcher ==
myPBX supports various ''MSI parameters'' which can be modified using Microsoft's ''Orca'' tool for individually tailored deployment (see the [https://support.microsoft.com/en-us/help/255905/how-to-use-the-orca-database-editor-to-edit-windows-installer-files respective Microsoft Knowledge Base Article] for details on using Orca). You can then roll-out myPBX using your favourite software deployment tool (or, if you don't have one, using Windows Policies, see [https://support.microsoft.com/en-us/help/816102/how-to-use-group-policy-to-remotely-install-software-in-windows-server this Microsoft Microsoft Knowledge Base Article on ''Group Policies''] for details).

''' Basic configuration '''
* The configuration dialog is located in the context menu of the tray icon.
* Configure the ''URL'' in the myPBX tab (e.g. <code>http://x.x.x.x/PBX0/MY/client.htm</code>).
* From v10 beta1 to beta4 the URL was <code>http://x.x.x.x/PBX0/MY/mypbx10.htm</code>. From v10 beta5 the normal URL (<code>client.htm</code>) is used.

''' Deployment '''
* Administrators can specify a default configuration using MSI parameters within the table '''Property''' when deploying the software.
** <code>URL</code> - The primary URL.
** <code>URL2</code> - The secondary URL (standby PBX).
** <code>TRACE</code> - Write trace files (<code>true</code> or <code>false</code>).
** <code>OFFICETRACE</code> - Enable Office Presence Logging (<code>true</code> or <code>false</code>).
** <code>AUTOSTART</code> - Autostart myPBX (<code>true</code> or <code>false</code>).
** <code>AUTOAPPEAROFFLINE</code> - Detect user activity on the computer in order to set the IM status (<code>true</code> or <code>false</code>, or the number of minutes).
** <code>APPNAME</code> - The display name of the external application.
** <code>APPPATH</code> - The path to the executable or the URI of the external application (may contain placeholders).
** <code>APPPARAMS</code> - The command line parameters for the external application (may contain placeholders).
** <code>APPAUTOSTART</code> - Start automatically on call.

* Additional parameters from V10 SR3:
** <code>SHOWINTASKBAR</code> - Show the myPBX launcher in the Windows Task Bar (<code>true</code> or <code>false</code>).
** <code>STARTMINIMIZED</code> - Start the myPBX launcher minimized (<code>true</code> or <code>false</code>).
** <code>DOCKING</code> - The docking mode of the launcher window (<code>none</code> or <code>left</code> or <code>right</code>).
** <code>HOTKEY</code> - The hotkey number (see registry of configured launcher).
** <code>HOTKEYMOD</code> - The hotkey modifier number (see registry of configured launcher).
** <code>HOTKEYACTION</code> - (<code>copy</code> or <code>show</code>).
** <code>VIDEO</code> - Enable video telephony and application sharing (<code>true</code> or <code>false</code>).
** <code>VIDEOPROXY</code> - Proxy server for the video websocket connection.
** <code>NOTIFICATIONS</code> - Turns desktop notification on or off (<code>true</code> or <code>false</code>).
** <code>SOUNDS</code> - Turns notification sounds on or off (<code>true</code> or <code>false</code>).
** <code>LANG</code> - A two-letter language code.

* Additional parameters from V10 SR6:
** <code>OFFICEPROVIDER</code> - Set office presence provider (default <code>myPBX</code>, empty string none, otherwise e.g. <code>Communicator</code>).

* Additional parameters from V10 SR7:
** <code>OFFICEPRESENCE</code> - false: removes the office presence provider feature from myPBX (default <code>true</code>, <code>true</code> or <code>false</code>).

* Additional parameters from V11:
** <code>SOFTWAREPHONEAUTOSTART</code> - If "true", the Softwarephone will be started and stopped together with myPBX. Also, the PBX and User Parameters (GK IP-Address, GK-ID, Username and Password) are copied from the myPBX Client into the SoftwarePhone (<code>true</code> or <code>false</code>).

* Additional parameters from 12r2:
** <code>CONFIGHIDEMASK</code> - With that parameter the administrator can hide certain parts of the configuration dialog. To calculate the hide mask add the desired values:
*** 1 - Tab "myPBX"
*** 4 - Tab "Office integration"
*** 8 - Tab "Video and application sharing"
*** 16 - Tab "External application"
*** 32 - Link "Open trace folder"
** <code>DEFAULTUSERNAME</code> - The default username for the login
** <code>DEFAULTPASSWORD</code> - The default password for the login
** <code>DEVTOOLS</code> - If "true", the context menu of the browser will show the "Inspect element" function that opens the developer tools.
** <code>OUTLOOKCONTACTSEARCH</code> - If "true", the search for outlook is set.

''' Command line parameters '''
* The following command line parameters can be used to specify special options for running the launcher. For example the parameters are useful for starting many instances on the same computer for demonstration purposes.
** <code>/url [URL]</code> - Overrides the URL from the configuration
** <code>/user [USER NAME]</code> - Starts the web application with the given user name
** <code>/password [PASSWORD]</code> - Starts the web application with the given password
** <code>/multi</code> - '''This parameter is for testing purposes, only. Do not use in a productive environment.''' It allows to start multiple instances of the launcher. You may want to combine this option with other configuration options such as <code>/url</code> to use different configurations without the need to re-configure. The parameter also disables saving the configuration to the registry. So changing the configuration in the configuration dialog does not work.

''' Type of Service (ToS) '''
* The settings of the ToS values for video RTP and signalling packets can be done using Policy-based Quality of Service (QoS), as described in this wiki article:
** [[Howto:Set Type of Service %28ToS%29 DiffServ DSCP Values for innovaphone Windows Applications %28SoftwarePhone%2C myPBX_Video%29]]

''' Registry Paths '''

myPBX stores its settings at the following locations:
* <code>HKEY_LOCAL_MACHINE\Software\innovaphone\myPBX</code>
* <code>HKEY_CURRENT_USER\Software\innovaphone\myPBX</code>

Note: The acutal location where windows stores the settings may vary due to windows conventions and settings.

See also: [[Reference10:Concept_myPBX_Office2010_Integration#Outlook_doesn.27t_recognize_myPBX_as_presence_provider]]

== Web application ==
When started in a web browser, the following URL parameters can be used to do a basic configuration.
* <code>lang=fr</code> - Give a two-letter language code to change the language of the user interface
* <code>touch=false</code> - Loads the version for use with mouse and keyboard.
* <code>touch=true</code> - Loads the version for touch devices.
* <code>phys=</code>''location'' - Forces the PBX to assume the physical location of the WebRTC client used in this instance has the specified [[{{NAMESPACE}}:PBX_Locations#The_physical-location | physical location ]]

= Details =
== Login ==

=== PBX stored password ===

* The short name (H.323-ID) of the user object is used as the login user name.
* The password of the user object is used as the login password.
* Users without a password cannot use myPBX.
* The local session information is stored in the DOMStorage of the web browser. It is deleted when the user logs out.

In a multi PBX scenario myPBX must be connected to the same PBX as the phone. Therefore after login the user is redirected like follows:
* PBXes accept the login if they are in charge.
* Slaves redirect to the master if they are not in charge.
: Note: redirection requires previous authentication. The user must be known to the redirecting slave PBX thus.
* The master redirects to the slave that is in charge.
* Inactive standby PBXes redirect to the master.
* Active standby PBXes accept the login.
Additionally you can configure an alternative URL in the myPBX launcher that shall be used when myPBX can't connect to the primary URL.

=== Netlogon ===

See [[Reference12r1:Concept_Netlogon_and_myPBX_Windows_Authentication]]

== Devices ==
The different phones of the user are addressed by the device of the user object where they are registered at. Therefore there should be no more than a single registration per device. Mobile phones can be integrated using the mobility object. It is mandatory that the mobility has a device name in the fork configuration.

== SIP URIs ==
* The ''use as domain'' checkmark on the page ''PBX/Config/General'' enables addressing users across PBXes using SIP URIs.
** The system name of the PBX is used as the domain-part.
** The short name (H.323-ID) of the user object is used as the local-part.
* The constructed URI looks like an email address (user@example.com) and it should only contain characters that would also be allowed for email addresses.
* In myPBX the URI can be used for telephony and instant messaging. For local users the domain-part can be omitted (<code>user</code> instead of <code>user@example.com</code>).

== Presence ==
* In the innovaphone PBX there are different possible sources of user presence, called ''contacts''.
** <code>tel:</code> - Phone presence
** <code>calendar:</code> - Presence set by the Exchange Calendar Connector
* myPBX sets the presence for the <code>tel:</code> contact.
* The displayed user presence is a mixed presence that is derived from the indiviual presence sources by the PBX. It consists of the following information:
** Acitivty (<code>available</code>, <code>away</code>, <code>busy</code>, <code>lunch</code>, <code>vacation</code>, <code>dnd</code>)
** Note
** Phone status (<code>open</code> or <code>closed</code>, sometimes displayed as <code>online</code> or <code>offline</code>)
** IM status (<code>open</code> or <code>closed</code>, sometimes displayed as <code>online</code> or <code>offline</code>)
* The activity <code>dnd</code> (do not distrurb) has a special meaning. If it is set, myPBX rejects all incoming chat messages. The phones can also be configured to reject incoming calls, if <code>dnd</code> is set.

== Visibility ==
For presence and dialog monitoring access rights (visibility rules) have to be configured at the individual user objects. The admin can do that in the "Access" dialog. Templates can be used to configure rights at many user objects at a time. In myPBX users can change the values given by the administrator and add their own rules.

'''Rules refer to'''
* A user (by name, <code>alice</code> or <code>alice@example.com</code>).
* All users of a domain (by domain suffix, <code>@example.com</code>).
* or all active users of a group (by group name). Group rules can only be added by the administrator.

'''Rules turn the following rights on or off'''
* Online status (phone and IM status, see chapter Presence)
* Presence (activity and note, see chapter Presence)
* Busy state (if the user has phone calls or not)
* IDs (the remote name and number of phone calls)

If a user is member of a group, all active members of that group have implicit access rights. These rights can be configured as the "Group Default Visibility" at the PBX. If there is no matching rule (implicit or explicit) the monitoring party does not see any information.

Administrators should configure default visibility rules that match the companies privacy policy. Typical users should not have to change the visibility settings. It is recommended to use a template that defines at least a rule for the local domain. If users shall be able to configure the visibility for certain groups, a default rule for each of that groups should also be added.

== Favourites ==
The user can add up to 32 phone numbers or SIP URIs as favourites. The favourites appear in myPBX for quick access. Also the presence and the calls are monitored and displayed, if possible. The user can create multiple lists of favourites and switch between them.

== Directory search ==
Users can search for phone numbers and other information in an internal and an external LDAP directory. The directories are configured in the phone config that is stored at the user object in the PBX. Templates can be used to share the same configuration across multiple users.

The directory is also used for resolving the names of external callers.

Some LDAP servers do not return any results if non-existing name or number attributes are configured. Attribute names are case sensitive.

== Instant messaging ==
myPBX is a chat client that can handle live chats between users. The PBX does not store chat messages, so both users have to be online at the same time.

Chat conferences can be started by adding more people. In this case received text messages are relayed to the other participants. Also the list of participants is transmitted to each endpoint.

'''Smileys'''

myPBX displays emoticons in the text of chat messages as smileys. Here are the text codes that are supported.

[[Image:Emo happy.png]] happy :-) :) (-: (:
[[Image:Emo normal.png]] normal :-| :| |-: |:
[[Image:Emo sad.png]] sad :-( :( )-: ):
[[Image:Emo mixed.png]] mixed :-/ :/ :-\ :\ \-: \:
[[Image:Emo twinkle.png]] twinkle ;-) ;) (-; (;
[[Image:Emo lol.png]] lol :-D :D
[[Image:Emo tongue.png]] tongue :-p :p :-P :P q: q-:

'''Typing indications'''

myPBX transmits a notification when a user is typing a chat message. This can be seen by the other participants of the chat session.

'''Starting a related phone call'''

If there is a single other participant in a chat session, the chat windows shows a call button to start a phone call to the other person. The call button is hidden if the own phone is not registered.

== Application sharing ==
Support for external application sharing is deprecated, since we now have integrated [[{{NAMESPACE}}:Concept myPBX Application Sharing|Application sharing]] in the myPBX launcher.

== Apps ==

From v12r2 there is a new ''Home'' button. It opens a new third area (in addition to the ''buddies'' and ''call history'') where is possible to start ''PBX apps''.

PBX apps available in v12r2:
*[[{{NAMESPACE}}:PBX/Objects/Boolean|Boolean]] (activation, deactivation, timer)
*[[{{NAMESPACE}}:PBX/Objects/Conference|Conference]] (caller list, mute, exclusive speakermode, disconnect participants)
*User [[{{NAMESPACE}}:PBX/Objects/Settings|Settings]] for dynamic group membership

For configuration refer to object specific reference articles.

=== Activation===
*Restart myPBX
*select home symbol at bottom
*select right sided pen
*select apps to be used & store settings

[[Image:Mypbx_activate_apps.png]]

== History ==
The history shows recent calls. The calls are retrieved from an instance of the [[{{NAMESPACE}}:Concept_Reporting|innovaphone Reporting]] service or alternatively the local [[{{NAMESPACE}}:Services/Call-Lists|call list service]]. The call details include the call flow before and after the user was connected. When a user calls someone back from the history, the call is marked as answered in the reporting database. As this is done using the conference ID of the call even other users can see who called back at what time.

When using [[{{NAMESPACE}}:Concept_Reporting|innovaphone Reporting]] history shows the last 20 calls that were made and when we click in the "arrow" button the next 20 calls are appended to the list, if we use the local [[{{NAMESPACE}}:Services/Call-Lists|call list service]] the number calls displayed it's set on the configuration menu.

== Tracing and logging ==
myPBX can write session information to the syslog of the PBX. Check the "myPBX" checkmark on the page Maintenance/Diagnostics/Logging in order to turn it on.

If the checkmark "Write trace" is enabled in the launcher configuration, the launcher writes a rotation of trace files to the folder <code>C:\Users\[UserName]\AppData\Roaming\innovaphone\myPBX</code>.

= Interfaces for integration =
The myPBX launcher has a number of generic interfaces that can be used to integrate it with other applications.

== Protocol handlers ==
During installation myPBX registers protocol handlers for the following URI types:
;tel: start a phone call
;sip: start a phone call
;sips: start a phone call
;phone: start a phone call
;im: start a chat

They can be used to start calls and chats in myPBX from external applications.

=== Dialing from the Windows command prompt ===
Execute the following command to dial the number 012345.
start tel:012345

Execute the following command to call user@example.com.
start sip:user@example.com

Execute the following command to start a chat with user@example.com
start im:user@example.com

=== Dialing from a web page ===
This HTML link dials the number 012345, when clicked.
<a href="tel:012345">012345</a>

This HTML link calls user@example.com, when clicked.
<a href="sip:user@example.com">user@example.com</a>

This HTML link starts a chat with user@example.com, when clicked.
<a href="im:user@example.com">user@example.com</a>

== Hotkey ==
A hotkey can be configured that copies selected phone numbers from most applications to myPBX. There is can be used for dialing, call transfer and so on.

When the hotkey is pressed, myPBX will simulate a CTRL-C key which should instruct the current foreground application to copy whatever is selected in to the Windows clipboard. If the clipboard content changes due to this, myPBX will use it as ''number-to-dial''.

== Starting an external application for a call ==
myPBX can start an external application for an incoming call. Both web applications and applications that are installed on the client PC can be configured. This configuration can be done in the launcher in the tab "External application" or using MSI parameters during installation.

The following settings can be done:
* <code>Name</code> - The name of the application as it should appear in myPBX.
* <code>Path</code> - The path of the applicaiton. This can be an URL (<code>http://crm.example.com/customer-by-number/$n</code>) or the path to a local application (<code>C:\crm\application.exe</code>).
* <code>Parameters</code> - The command line parameters of the application. This field can be left empty for web applications.

The <code>Path</code> and the <code>Parameters</code> may contain placeholders that are replaced by phone call information.
* <code>$n</code> - phone number of the caller as seen
* <code>$N</code> - phone number of the caller, normalized to national number format, e.g. 070317300988
* <code>$I</code> - phone number of the caller, normalized to international number format, e.g. +4970317300988
* <code>$u</code> - uri of the caller
* <code>$d</code> - display name of the caller
* <code>$c</code> - conference ID (a global ID for the call)

If <code>Name</code> and <code>Path</code> are configured, an additional button will appear in myPBX at phone calls that starts the application.

= Troubleshooting =
== Connection problems / Refreshes ==
Symptom: When in idle state, the myPBX web application reloads every 30 seconds.
 
This might be a problem with the [http://msdn.microsoft.com/en-us/library/aa918417.aspx TCP/IP settings of the PC]. You should set <code>ReceiveTimeOut</code> and <code>KeepAliveTimeout</code> to the default settings if they have been changed to smaller values. Please note that the values must be specified in milliseconds!

== Loss of DOM Storage Information ==
Symptom: myPBX is asking for username and password each time it is started.
 
See [[Howto:MyPBX and roaming Profiles (e.g. Citrix) - myPBX forgetting login info]] for a possible resolution.

= Appendix =

== Known Limitations==
Since V12r2, myPBX allow to use WebRTC technology as softwarephone client. In this case, audio and thus headset handling is done by the browser. Please note that headset physical buttons and its functions such as "onhook/offhook" will not be supported by the browser and hence not by myPBX running the WebRTC endpoint.

== Known Issues ==

===Office application crashes===
If you have Lync installed and installed myPBX afterwards and you wanted to use Lync/Communicator as Office presence provider, an office application might have crashed. 
The MSI parameter OFFICEPRESENCE allows you to disable all office presence related installation, so a Lync installation won't be broken. You can't use myPBX as presence provider anymore in this case, but Lync will still work correctly. 
If your installation is already broken, you can simply repair your Lync installation and Office won't crash anymore. 
If you want to use myPBX as presence provider, reinstall myPBX without the MSI parameter.

Update: Latest hotfix (November 2017) for SFB/Lync client fixes the issue of the crash with the Outlook-Plugin or issues with the search on the Lync client, so with this newer version both CTI clients could be installed on the same PC without problems.

== CPU usage ==
Connected myPBX sessions need additional resources on the PBX. When all extensions die myPBX, you can have approximately a 1/3 the amount of users per box than without using it.

== Network traffic ==
In idle state the web application needs an empty message exchange every 30 seconds in order to keep the session alive. This messages take about 800 bytes. So per session the minimum network traffic is approximately:
* 1600 B/min
* 94 kB/h
* 2.2 MB/d

== Included open source software ==
The myPBX web application contains the following open source software:

'''rc4.js'''
* RC4 symmetric cipher encryption/decryption
* Copyright (c) 2006 by Ali Farhadi.
* released under the terms of the Gnu Public License.
* see the GPL for details.
*
* Email: ali[at]farhadi[dot]ir
* Website: http://farhadi.ir/

'''sha1.js'''
* Secure Hash Algorithm (SHA1)
* http://www.webtoolkit.info/

Howto:Create Conference facility

2011-04-13T16:27:23Z

Bsiegwald: /* Problems with inbound dialing and access from trunk line */

{{Template:3rd Party Input}}
==Applies To==
This information applies to

* IP 6000, V6 SR2
* IP 800, V6 SR2
* IP 305, V6 SR2

NB: this solution will work with V6, V7 and V8 firmware only as the [[Reference9:Gateway/Interfaces#Conferencing_interface_.28CONF.29 | CONF interface behaviour has changed with V9]].



==More Information==
Conference facilities can be created direct on the innovaphone gateway. There are two possibilities to create a conference:

1) Manually inbound dialed to the conference room

2) Broadcast dialed out to a specified group. When the group members pick up the phone, they are in the conference room.

In both cases you need to activate the CONF interface and register this to a user object. If you also want to the Broadcast possibilitiy, please see the [[Reference:Administration/PBX/Objects/Call_Broadcast_Conference|Call Broadcast Object]].

==Conference Interface==
Go to '''Gateway - Interfaces''' and open '''CONF'''. Create a registration on a PBX.

[[Image:CONF_Interface.PNG]]

Go to '''PBX - Objects''' and create an '''User Object'''. Give it the same name / number as the CONF Interface. See that the object is registered.

[[Image:CONF_object.PNG]]

==Using the Conference room - inbound dialing==

The users have to agree about which conference ID they want to use (0...9). More than one conference can run on the same time when they have different ID. The users call the number for the Conference user object + ID + #.

In our sample the object has no 87 and we use ID 0:
870#

All users dialing 870# come into the same conference room.

===Problems with inbound dialing and access from trunk line===

In some countries, the number of digits in a call number is fixed. (ex Norway 8 digits). In this case the add on ID digit and # is blocked in the network, and because of the connection is not fulfilled, the additional digits are not sent as DTMF.

====Solution 0: Route the incoming call to the conference====

In this case, you have to use a Number Map object in the PBX. So when you are calling from outside e.g. '''22446686''', you reach the internal Number Map object '''86''', that maps the call to '''870#''' thus reaching the conference room.

====Solution 1: Check who is calling====

The problem with the previous solution is that everybody from outside also can reach this conference room. A solution is to call a '''Waiting Queue''' from outside and use a Call Forward (CFU) dependent on caller ID. In the following example, Waiting Queue '''86''' is forwarded to '''872#''' (conference room ID 2#) if outside caller 90909090 or 91919191 is calling. If users from outside caller 225566xx are calling, they are transferred to room 3. All other callers will hear the innovaphone internal waiting music, or the Waiting Queue voice message if such is specified. Here you can give a message to the caller.

[[Image:Conference Facility Boolean CFU.png]]

It is also possible to "open" and "close" the conference room, setting the Boolean Object '''konf switch''' True and False, and activate / deactivate the Call Forward depended on Boolean status. You can set it True and False with a function key on your phone.

====Solution 2: Ask for a PIN-code====

Another solution would be to route the calls for the Conference to a Waiting Queue.
In this Waiting Queue a message is played: "Welcome to ... Please enter your PIN-code to enter the Conference...".

With the DTMF-possibilities of the Waiting Queue-object, you can check whether the caller knows the correct PIN...

First create a new Waiting Queue-object:

'''Long Name''': Conference CheckPin

'''Name''': Conference CheckPin

'''Number''': 500

[[Image:WQ_Conf_1.gif]]

Second configure the announcement when this Waiting Queue is called:

'''Queue -> First Announcement -> URL''': http://127.0.0.1/DRIVE/CF0/Announcements/checkPin.$coder?coder=g711a,g711u,g729&repeat=true

'''Queue -> Alert TimeOut''': 0

With these two options the 'checkPin'-file (which is located on the local CF-card and contains the text "Welcome... Please enter you PIN-Code...") is played directly (TimeOut = 0) whenever this Waiting Queue is called and this announcement is repeated constantly ($repeat=true).

Finally, the different PIN-codes to access the Conference-room have to be configuered:

'''Queue -> DTMF''': 1230 (this is the PIN-Code the caller has to enter)

'''Queue -> DTMF -> Dest. No''': 870# (this is the combination of the Conference-object ('87') and Conference-ID (0#)).

So when the caller presses 1230 he or she enters the Conference with ID 0...
(You can add more PIN-codes for different or the same Conference-room (see screenshot))

[[Image:WQ_Conf_2.gif]]

== Related Articles ==

[[Category:Howto|{{PAGENAME}}]]
* [[Reference:Administration/Gateway/Interfaces#Conferencing_interface_.28CONF.29|Administration/Gateway/Interfaces]]
* [[Reference:Administration/PBX/Objects/Call_Broadcast_Conference|Administration/PBX/Objects/Call Broadcast Conference]]
* [[Reference7:Administration/PBX/Objects/Call_Broadcast_Conference|Reference7:Administration/PBX/Objects/Call Broadcast Conference]]
* [[Reference9:Gateway/Interfaces]]