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 have the application platform installed and running with Hotfix13.
Microsoft Exchange Server
The innovaphone Exchange Calendar Connector application supports the Microsoft Exchange Server 2010 SP1 and SP2 and 2013!
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!
Outlook
Each Outlook user has to grant read access to the calendar user, which is configured under Exchange.
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
- no delete items permission
- Folder visible under Other
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)
Email Addresses
The Exchange Calendar Connector needs the primary SMTP address of an exchange user. Therefor the E-Mail field of a PBX user object is used and each email adress is tried to be resolved to the primary 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.
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 "Groups/Call Forwards only"
- Password: password for the account
- Dyn-PBX-ID: for a Dynamic PBX
- HTTPS: use HTTPS for the communication with the PBX
Exchange
- Server: the IP address or DNS name of your Microsoft Exchange Server
- Account: the exchange user account, which has read access to the user calendars, which shall be monitored (see Outlook ). The account also needs to have 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
- 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
- Use HTTPS: If set, the Exchange Server uses HTTPS to communicate with the Linux AP
- On your Exchange Server you have to trust the SSL certificate of your Linux AP. Otherwise the connection will fail (HowTo).
- 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.
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.