Reference10:Concept Exchange Calendar Connector: Difference between revisions

From innovaphone wiki
Jump to navigation Jump to search
Line 327: Line 327:


===Use HTTPs for Exchange Notifications===
===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!<br>
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([[Support:DVL-Roadmap_Exchange_Calendar_Connector_V10#13554_-_Add_DNS_name_for_Linux_in_Exchange_Calendar_Connector_configuration | since V10SR38]]) !<br>
You also have to trust the root certificate of your signed certificate on your Exchange Server.  
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  
* certificate of your Linux AP '''must''' contain its IP address or its dns-name ([[Reference10:Concept_Exchange_Calendar_Connector#Exchange | Option: ''Linux DNS Name (optional)'' in Exchange Connector settings]])
* a signed certificate must be trusted by ensuring that the root certificate is inside the certificate store "trusted root certification authorities"
* 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 LinuxAP was not tested successfully. We recommend therefore to use a LinuxAP 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!
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!

Revision as of 15:04, 13 February 2017

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 have the application platform installed and running with Hotfix13.

Tools clipart.png FIXME: required hotfix will change on release

Microsoft Exchange Server

The innovaphone Exchange Calendar Connector application supports the Microsoft Exchange Server 2010 SP1, SP2 and SP3, 2013 and Office 365!

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)

Note: A possible alternative to configure settings above via the Outlook Client is to use PowerShell Scripts. Here is an solution example. This was not tested by innovaphone. If this is not OK 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

Exchange server.jpg

  • 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

Exchange pbx.jpg

  • 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

Exchange ews.png

  • Server: the IP address or DNS name of your Microsoft Exchange Server
  • Account: the exchange user account, which has sufficiant access to the user calendars, which shall be monitored (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 LinuxAP was not tested successfully. We recommend therefore to use a LinuxAP 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).

Trouble shooting

Wireshark trace without SSL

You'll have to temporarily deactivate SSL in your Microsoft Exchange IIS server: Exchange iis.jpg

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!

Howto save and restore Linux AP data/database if the webgui is not available

See Troubleshooting Linux AP