Reference10:Concept Exchange Calendar Connector
Usage
You can use the innovaphone Exchange Calendar Connector application to set the presence of a PBX user according to the Outlook calendar of the user.
If the user has e.g. a meeting, the presence will be set to busy and the presence note to the subject of the calendar item (see Presence Note and Activity).
Requirements
innovaphone PBX
The PBX must be V10 or higher.
innovaphone Linux Application Platform
It is needed to use the same version of installed application platform and Exchange Calendar Connector.
Microsoft Exchange Server
The innovaphone Exchange Calendar Connector application supports the Microsoft Exchange Server 2010 SP1, SP2 and SP3, 2013 and Office 365!
Field experience shows that Microsoft Exchange Server 2016 standalone setups seems to work fine if you select "Exchange 2013" in connector configuration.
Enabled Windows Authentication
As we use NTLM for authentication towards the Exchange Server, you'll have to enable the Windows Authentication in your IIS of the Exchange Server on the folder EWS: http://technet.microsoft.com/en-us/library/cc754628%28v=ws.10%29.aspx
If you right click on the Windows Authentication entry, you can select "Providers". Make sure, that the NTLM provider is active here!
The Anonymous Authentication must be also active, just for the IUSR, not everybody!
Basic Authentication
The Exchange Calendar Connector now also support Basic authentication since v10 sr11. If you disable HTTPS (just needed for debugging) towards the Exchange server, your password will be insecure!
This feature was introduced to support Office 365 since it uses Basic authentication and doesn't support NTML Authentication.
If your Exchange Server supports Basic authentication, you may have to add your domain to your configured user name, like domain\user.
Office 365
It's possible to configure innovaphone Exchange Connector with Office 365 solution more information at: Office 365 Testreport
Outlook / Permissions
Each Outlook user has to grant read access to the calendar user, which is configured under Exchange in the Account property.
Open the Outlook options, go to Calendar in the left menu and open the "Free/... options" (Frei/Gebucht-Optionen in german).
There you have to add new permissions for the calendar user. You can select the predefined selection Reviewer (Prüfer):
- no writing rights
- read Full Details (needed to establish a subscription, otherwise it won't work!)
- no delete items permission
- Folder visible under Other
Alternative setup will be add the user, which is configured under Exchange in the Account property, to a Group in AD and also include all other users/members that wish to share their calender to this group then you do the step described before but you add the "Group" to each user/member in outlook instead of the calender user used in the "Account" property.
It is also possible to grant permissions using Exchange Management Shell (grant permissions to to User innoconnector rights to see calendar of User user.alias):
Add-MailboxFolderPermission -Identity user.alias:\calendar -User innoconnector -Accessrights Reviewer http://technet.microsoft.com/en-en/library/dd298062%28v=exchg.140%29.aspx
You may have to localise the name of the calendar folder, e.g. calendar -> Kalender (german)
Sheduled script
You can use the windows taskplaner to shedule a job for the script innovaphone_calendar_rights_starter.cmd to set the correct calendar rights for all users.
The script innovaphone_calendar_rights_starter.cmd will trigger the powershell script with the needed environment.
- $innovaphone_user
- Please insert the correct SamAccountName of your innovaphone AD-user
- $disabled_users
- If needed you can maintain a blacklist of users that calendar items will not be reachable for the innovaphone user
- innovaphone_calendar_rights_starter.cmd
PowerShell.exe -command ". 'C:\Program Files\Microsoft\Exchange Server\V15\bin\RemoteExchange.ps1'; Connect-ExchangeServer -auto; .\innovaphone_calendar_rights.ps1"
- innovaphone_calendar_rights.ps1
- configuration ###
- SamAccountName of the lookup user
$innovaphone_user = 'innoconnector';
- disabled users
$disabled_users = @('john_doe', 'jane_doe');
- dont change below this line ###
get-mailbox | foreach {
$user = $_.Alias
$calendar = (Get-MailboxFolderStatistics -Identity $user -FolderScope Calendar | Select-Object -First 1).Name
$path=$user+ ":\" + $calendar
if ($disabled_users -contains $_.SamAccountName) {
Remove-MailboxFolderPermission -identity $path -User $innovaphone_user -Confirm:$false
} else {
Add-MailboxFolderPermission –identity $path -User $innovaphone_user -Accessrights reviewer
Set-MailboxFolderPermission -identity $path -User $innovaphone_user -Accessrights reviewer
}
}
Note: This is an example and was tested on Exchange Server 2013 (v15). If this is not work anymore or doesn't work for you, then you should configured like recommended above using the Outlook Client.
Email Addresses
The Exchange Calendar Connector needs the SMTP address of an exchange user. Therefor the E-Mail field of a PBX user object is used and each email address is tried to be resolved to the SMTP address.
If your system name of your PBX has the Use as domain option checked, the h323 name is also tried with h323@systemname and this is also done with further configured aliases of the E-Mail field, which have no domain.
So you may have the following Exchange User with multiple email addresses:
- test@innovaphone.com
- test@innovaphone.de
- Test.Tester@innovaphone.com (primary SMTP address)
The PBX (system name innovaphone.com with Use as domain) user object:
- h323 test (used with system name -> test@innovaphone.com)
- E-Mail test@innovaphone.de (this would also work without Use as domain)
- E-Mail Test.Tester (used with system name -> Test.Tester@innovaphone.com)
All three possibilities are successfully resolved, as each email address exists for an Exchange User.
A user object with no H323 name will be always ignored!
Installation
Download the latest version of innovaphone Exchange Calendar Connector.
Log into the application platform, go to the Applications tag, click on Upload/Update and upload the downloaded file. The installation will start automatically and the page will refresh every two seconds showing the installation process. If there is no error during the installation you will see at the end "Installation was succesfull". Otherwise, you will get "installation failed" and the reason why it went wrong.
Hotfix
If you have already installed the latest version of the exchange application, simply download the Exchange...HotfixIncremental for your platform (VM or IPxx10) or if you have missed some hotfixes, download the Exchange...HotfixCumulative archive, which contains all hotfixes since hotfix1.
Upload this hotfix archive here.
Configuration
Device
See Email Addresses.
Servers
You can configure multiple PBX/Exchange pairs on one Linux Application Platform.
There are three steps to configure on server:
Server
- Name: a name for a PBX/Exchange pair, which you can choose yourself
- Description: a description
- Calendar Note Language: strings like Away and Free until are translated into this language
- Presence Update Interval: the interval, in which the calender presence will be updated inside the pbx and PBX user objects are tracked
- Trace: enable/disable tracing
PBX
- IP Address: the IP address of your PBX
- Port: the HTTP(s) port of your PBX
- Account: the account, which reads the users from the PBX via SOAP, must have at least the right "Viewer"
- Password: password for the account
- Dyn-PBX-ID: for a Dynamic PBX
- HTTPS: use HTTPS for the communication with the PBX
- Domain Filter: Optionally enter a comma separated list of domains. PBX users without a matching email address are ignored.
Exchange
- Server: the IP address or DNS name of your Microsoft Exchange Server
- Account: the exchange user account, which has sufficient access to the monitored user calendars (see Outlook for how to grant these permissions). The account also needs to have a mailbox configured inside the Exchange server.
- Password: the password of the user
- Omit Subject: Omits the subject of a calendar entry from the presence note (presence status itself will be transmitted). Moreover, presentation of any presence on phone upon alert can be activated generally - see PBX Config General : Presence with Alert
- Omit Date and Time in presence note: Omits the date and time inside the presence note.
- Status Frequency (minutes): the subscriptions of user calendars are kept alive by dummy events, which are sent by the Exchange Server in this frequency
- Availability Timespan (hours): the timespan for which calendar items are retrieved
- Email(s): See Tentative calendar items
- Exchange Version: SP1 or SP2 of the Microsoft Exchange Server 2010 or Microsoft Exchange Server 2013. For Microsoft Exchange Server 2010 SP3 please use the setting 2010 SP2.
- Use HTTPS: If set, the Exchange Server uses HTTPS to communicate with the Linux AP (HTTP connections from Exchange Server to Linux AP, ie: updates for calender entries)
- Linux DNS Name (optional): You can optionally set the DNS name of your Linux AP, which will be used by the Exchange server for HTTP requests.
- Linux NAT IP:
- Linux NAT Port: If your Linux AP is behind a NAT router in the view of your Exchange server, you have to configure a reachable Linux IP/Linux Port. This IP address has to be reachable from inside your Exchange server!
Connection Test
The connection test just tests the SOAP connection towards the Exchange Server. The SOAP connection from the Exchange Server to the Linux AP is not tested!
Database
The exchange application creates the innovaphone-exchange database to store users from the PBX. PostgreSQL is also available for other applications and any of them could create its own database.
Password
The exchange application creates the database user innovaphone-exchange with default password exchange. This password may be changed at the innovaphone Exchange Calendar Connector page under Config/Database.
Remote Access
There are tools (PgAdmin III) that allow to connect to application databases remotely. It is first needed to configure the IP you are connecting from under Config/Database at the innovaphone Exchange Calendar Connector page.
Diagnostics
Logs
Download/View logs of the innovaphone Exchange Calendar Connector application.
Exchange Database
Select either All Servers or a specific server to list users or calendar items.
List users
List all monitored users and their current subscription state.
List calendar items
List all retrieved calendar items.
Note about "PBX Status" values:
Status 0: unsignaled towards PBX Status 1: signaled with note but without activity (Free until...) Status 2: signaled with note and activity (Busy until) Status 3: note and activity removed
Backup and Restore
You can both manually and automatically backup the database and configuration files for the exchange application under Administration/Backup in the application platform.
Configuration details for the update server can be found here.
Configuration Files
saveinnovaphone-exchangecfgs is the command used to automatically save configuration files with the Command File.
Data
saveinnovaphone-exchangedb is the command to automatically backup the whole innovaphone Exchange Calendar Connector database with the Command File.
As the database contains your server configuration, a backup might be usefull!
Logs
saveinnovaphone-exchangelogs to save log files with the Command File.
Appendix
How it works
For each server the following steps are done after the configured interval (some steps only once):
- All users from the PBX are retrieved via SOAP
- The primary SMTP address inside the Microsoft Exchange Server is retrieved for all users with a valid h323 name or E-Mail field
- A subscription for calendar events is established toward the Microsoft Exchange Server for all users with a primary SMTP address via SOAP EWS with the configured user who has read access to the calendars of the other users
- The calendar items for the next e.g. 36 hours are retrieved for each new user (this step is only done once or if a new calendar event is received with the established subscription)
- The presence is set according to the calendar items of a user
- The established subscriptions monitor all changes inside the users calendars
- After the configured interval, the PBX users are compared to the already existing ones and if needed added/removed/renamed etc.
The first time after you have successfully configured the PBX and the Exchange Server, all user subscriptions are established and all calendar items are retrieved. This may take some minutes, according to the user count.
Presence Note and Activity
The settings of a calendar item determine the presence activity and note.
A calendar item is ignored, if its busy type is free or tentative (see Tentative calendar items).
The subject of a calendar item is ignored, if the calendar item is private.
The activity is only set, if the calendar item has already started! Otherwise just the note is set. If just the note is set, the merged presence, received by the PBX, will prefer presences with an activity. If there is no presence with an activity, the note is shown e.g. on the phone/in myPBX.
An all-day calendar item is e.g. from 25/05/2013 00:00 until 26/05/2013 00:00 and it's also displayed.
Tentative calendar items
A tentative calendar item is neither free nor away, so it is ignored by default.
But if the organizer of a calendar item is one of the configurable email addresses, the item is treated as away!
Activity
The activity is set accordingly to the busy type of a calendar item:
Calendar Item Busy Type | Presence Activity |
Free | ignored |
Tentative | ignored or Away |
Busy | Busy |
Out of office | Away |
Working Elsewhere | Away |
Note
The note of a not yet started calendar item contains the following parts:
- the string Free until
- the date if the start date of the calendar item is not today
- the start time (Hours:Minutes) (if Hours:Minutes is '00:00' and the decreased date is not today, the time is cut and the date decreased by one day instead)
- the string Away if the activity is away
- the subject of the calendar item or if the calendar item is private, the string Private
e.g.
Free until 28.07.2012 12:20 (Away: Vacation) Free until 28.07.2012 12:20 (Meeting with boss) Free until 12:20 (Away: Meeting with customer) Free until 12:20 (Away: Private)
The note of an already started calendar item:
- the subject of the calendar item or if the calendar item is private, the string Private
- the string until
- the date if the end date of the calendar item is not today
- the end time (Hours:Minutes) (if Hours:Minutes is '00:00' and the decreased date is not today, the time is cut and the date decreased by one day instead)
e.g.
Vacation until 23.12.2012 Meeting until 23.12.2012 12:45
Microsoft Exchange Web Services
For communication with the Microsoft Exchange Server, its Exchange Web Services are used.
Installed Debian Packages
The following packages (and their dependencies) are installed with the innovaphone Exchange Calendar Connector:
- php5-mcrypt
Configuration Files
- pg_hba.conf is the client authentication configuration file and controls which hosts are allowed to connect, how clients are authenticated, which PostgreSQL user names they can use and which databases they can access.
- postgresql.conf is the PostgreSQL configuration file
- exchange.conf contains one configuration option
Data Files
If you backup the innovaphone Exchange Calendar Connector database, you'll get a gz archiv, which contains the whole innovaphone-exchange database.
Database Structure
servers
The configured servers.
users
Users retrieved from the configured PBX.
calendar_items
Calendar items for the users retrieved from the Microsoft Exchange Server.
Tools
NetDrive
NetDrive is a usefull webdav client, which can be used to access webdav of the innovaphone application platform.
PGAdmin
PGAdmin is an administration tool for PostgreSQL databases.
Putty
Putty is SSH client to connect to the linux application platform.
Known Issues
Use HTTPS for Exchange Notifications
If you have to use HTTPS for Exchange Notifications, your Linux AP needs to have a signed certificate which contains the IP address of your Linux AP or its dns-name (since V10SR38)!
On your Exchange Server, you also have to trust the root certificate of your signed Linux AP-certificate .
- certificate of your Linux AP must contain its IP address or its dns-name ( Option: Linux DNS Name (optional) in Exchange Connector settings)
- the Linux AP certificate must be trusted on the Exchange server, by ensuring that the root certificate is installed inside the certificate store "trusted root certification authorities"
- the usage of self-singed certificates by the Linux AP was not tested successfully. We recommend therefore to use a Linux AP certificate signed by an CA authority trusted by the Exchange server.
Pay attention if you have set the Force HTTPS flag on your Linux AP! In this case requests of the Exchange Server are redirected to a HTTPS location and your Linux AP must meet the conditions from above!
A user doesn't get calendar updates after configuration changes
The Exchange Calendar Connector establishes a subscription for every user with the exchange server. If such a subscription request fails (e.g. calendar permissions are wrong/not set), the next retry is not done until 2 hours later. This has been implemented to reduce the system load for systems with many PBX users, where such a fail is expected.
If an administrator now tries to correct user settings, it might last up to 2 hours until the changes take effect.
An administrator can still click through the Exchange Calendar Connector configuration to enforce new subscriptions for every user (but this may take much time for the first run).
Don´t use "Hide from LDAP" for user object that get the presence from the exchange
In this case the user object will not get presence from exchange (fixed in #29761 - Calendar Synchronization did not work for PBX Objects with "Hide from LDAP" set).
Not all user calendars may be synchronized with Exchange365
Exchange may limit the number of concurrent subscriptions for calendar updates. This is under control of the EWSMaxSubscriptions policy. We have seen this set to 20 in Exchange365 installations.
To work around this issue
- connect to the Linux Application Platform your Exchange Calendar Connector is installed on using SFTP (e.g. using WinSCP)
- change directory to /var/www/innovaphone/apps/innovaphone-exchange
- edit the file exchange.php
- find the line
const noSubscriptions = false;
- change it to
const noSubscriptions = true;
- modify the connector's configuration
- set Presence Update Interval to a small value (say, 2)
- set Status Frequency to half of the the desired maximum delay for presence updates (say 5)
In this configuration, presence updates will not be done on the fly when changes occur. Instead, a full replication will occur every 10 minutes if Status Frequency is set to 5. To make sure the connector is not overloaded, have a look at the log file in Diagnostics/Logs/innovaphone Exchange Calendar Connector/View. The time in minutes between the log entries date time: ITW ExOn: EWS initialized
and date time: ITW ExOn: PBX presence updated
must be less than your Status Frequency setting.
This fix is available from V10 Service Release 47.
Exchange Loadbalancer
If you use a load balancer in front of multiple Exchange workers, the connector configuration might say "connection works", but no calendar items will be synced.
As a workaround you can use an Exchange-Worker-IP directly.
Trouble shooting
Wireshark trace without SSL
You'll have to temporarily deactivate SSL in your Microsoft Exchange IIS server:
Then activate RPCAP on your Linux Application Platform under Diagnostics->RPCAP. Start a Wireshark-Trace for your Linux IP on both interfaces LO and ETHO.
Walk through your Exchange Connector configuration, add :80 to your ip address or dns name of your Exchange Server, e.g. 172.16.17.18:80 and commit the changes.
Save the wireshark trace after about 10 minutes.
Keep in mind, that with Basic authentication (used with Office 365), your password will be transferred in plain text if you disable SSL!