Reference13r3:Apps/PbxManager/App Calendar
The PBX Manager Plugin for the Calendar App allows you to create two kinds of app objects. One is the Calendar Admin, which is just a simple overview of what's going in. The other is the Calendar App itself. Please note that even if the app is named "Calendar", it isn't a calendar like it is known. For now, it's just a tool to synchronize the Outlook / Exchange Calendar with the innovaphone PBX to set the presence of the user to the active or upcomming appointments.
Applies To
innovaphone PBX from version 13r1 (Exchange 365 using OAuth2 needs 13r2 beta 2 or newer).
Supported Exchange Versions
- Exchange 2013 or newer
- Exchange 365
Configuration
In order go get the current users presence synchronized with Exchange, the calendar must be configured. This includes two parts: the configuration for the communication with the PBX and the configuration for the communication with Exchange Server.
PBX & Presence
The following configuration can be set for the PBX communication:
- Master PBX Name: This is the name of the main PBX. Even if several PBXs are used in your setup, the calendar supports communication with only one of them, usually the main PBX. The name must be specified, even if you use only one.
- Presence language: The language the Calendar uses for presence. This is not necessarily the one that is displayed in myApps or on the phone, since the presence is translated there into the respective language.
- Presence timezone: The time zone in which the time of presence is calculated. As with the language, this is not necessarily the time that is displayed in myApps or on the phone, since the time zone set there is used.
- Subject: Define whether the subject of an appointment should be visible in the presence or not.
- Prioritized appointments need to contain in title: Appointments whose title contains a word from this comma-separated list have priority over simultaneous other appointments (e.g. vacation)
- Prioritized appointments must not contain in title: Appointments whose titles contain a word from this comma-separated list do NOT have priority over concurrent other appointments (e.g. home office)
Exchange Sync
- Sync-Type: Select the type of connection to your Exchange server. On-Premises is to be used for local Exchange installations. Here, the calendar connects to Exchange via NTLM authentication. Cloud is for Exchange 365 (formerly Exchange Online), where AOtuh2 is used for the connection.
- User: The username to use for the authentication. This use must have the Application Impersonation right and should also have a mailbox, since the user will be used to autodetect the Exchange settings, too. For more information about impersonation right (see below).
- Password: (Only available when Sync-Type is On-Premises) The password to use for the connection to Exchange.
- Autodiscover Server URL: The URL of the Exchange Autodiscover server. For more information, see the section autodiscover below. This value is optional.
- Exchange-Server to use: The Exchange Server can report two addresses through which it can be reached: an internal and an external one. Normally it is not a problem to use the external address. However, depending on the local network setup, this may not work. In this case it is recommended to use the internal address.
- User for name resolving: Execute name resolution by either the impersonation user or various user names the calendar can create with the information received from the PBX (see also release note).
- Max subscriptions per connection: limit number of concurrent query requests vs Exchange. Also crosscheck settings at Exchange!
- EWS debugging protocol: de/activate debug output generation for troubleshooting.
Exchange Sync for Exchange 365
For this sync type you have some additional configuration steps. When connecting to Exchange 365, Calendar authenticates itself via OAuth2. In order to use this, the Calendar app must first be set up within Azure Active Directory. A description for this setup can be found in the howto article Setting up Calendar with OAuth2
Presence mapping
Here you can set how the presence values from Exchange should be mapped to the PBX. The only presence that can't be mapped is free (appointments with presence free will never show up in the presence), busy or away. The options you have in this sections are:
- Tentative exceptions: An email address for a user who can create appointments setting the presence to tentative. This can be used for example by the human relations department. If a colleague is sick, an appointment with "sick" and presence set to tentative can be entered into the calendar of that colleague by someone at humen relations. This makes humen relations to be the organizer and the mapping for that appointment will be different as the mapping for normal tentative appointments.
The mappings to set are:
- Busy: Mapping of appointments that are set to Busy in Exchange.
- Tentative: Mapping of appointments that are set to Tentative in Exchange.
- Tentative exceptions: Mapping of appointments that are set to Tentative in Exchange created by the user defined in the tentative exceptions organizer field.
- Out of office: Mapping of appointments that are set to Out of Office in Exchange.
- Working elsewhere: Mapping of appointments that are set to Working elsewhere in Exchange.
- No data: Mapping of appointments that don't have any presence information. Should never happen.
Values you can set the mapping to
- Available: The appointment is handled as free but still be shown as presence (instead of an appointment that is set to free in exchange). Normally, if there is no appointment, available will be shown. If a presence is mapped to free, the format of the presence is like a free presence but with the title of the appointment. For example: the appointment instead of "Available until 2pm (Busy: Meeting)" it will be "Homeoffice until 2pm (Busy: Meeting)", if the appointment with mapped presence has the title "Homeoffice".
- Busy: Presence will be mapped to busy.
- Away: Presence will be mapped to away.
- Do not disturb: Presence will be mapped to do not disturb.
- Ignore for presence: The appointment with a presence mapped to this value will not be shown for the presence (default for tentative appointments which won't be triggered by the tentative exception rule).
Additional information
Impersonation user
In order to query the appointments of all Exchange users, the user used to connect to Exchange (On-Premise) or to authenticate the connection (OAuth2) must have the Application Impersonation right. This means that this user can act on behalf of all other users. For this reason and the rights associated with this impersonation user, the credentials of this user should be kept highly confidential! The Calendar itself stores the user's password in encrypted form in the AppPlatform database (on-premise only). Since the user is also used to determine Exchange server settings, the user may need to have its own mailbox. An example of how the Application Impersonation right can be assigned to a user can be found here: Exchange 2013 and 2016 Configuring Impersonation For Applications. Instructions for other Exchange versions or further information about Application Impersonation can be found in the Exchange documentation.
Autodiscover
The calendar uses autodiscover to determine the server address, the Exchange version used and other user-relevant information. Normally, the calendar automatically determines the address of Exchange's autodiscover service based on the TLD of the impersonation user. For example, if the impersonation user's TLD is "example.com", the calendar will look for the Autodiscover service at "https://autodiscover.example.com", "https://example.com", "http://autodiscover.example.com" and "http://example.com". Depending on the configuration, at least one of these URLs should be the correct one. However, under certain circumstances, this auto-detection may go wrong. Therefore, the address of the autodiscover service can be configured for the calendar. The exact address depends on your Exchange configuration. For Exchange 365 e.g. https://autodiscover-s.outlook.com or https://outlook.office365.com are possibilities. Additional information can be found in the Autodiscover service in Exchange Server Knowledgebase
Users and primary SMTP address
The calendar will get a list of users available in the PBX. After that, he tries to resolve the primary SMTP address for each user to be able to get the users appointments. The calendar tries to use username@pbx-domain. If that isn't the users email address, you can add additional addresses to each user object in the PBX. This may help in case that a user can't be resolved.