Reference13r1:Concept App Service Calendar: Difference between revisions
No edit summary |
|||
| (19 intermediate revisions by 5 users not shown) | |||
| Line 9: | Line 9: | ||
== Apps == | == Apps == | ||
=== innovaphone- | === Calendar Admin App (innovaphone-calendar-admin) === | ||
(Still experimental) Gives some administrative options and can be used to get the current status. | (Still experimental) Gives some administrative options and can be used to get the current status. | ||
| Line 19: | Line 16: | ||
== Concepts == | == Concepts == | ||
The calendar will get a list of all users available in the PBX. This list will be used to figure out the users available in Exchange (which means, that a user, that isn't available in PBX won't be synchronized by the calendar). Finally, all appointments of the users Exchange calendar will be synchronized to the calendars database and used to update the users presence. The calendar also registeres himself to Exchange to get notified | The calendar will get a list of all users available in the PBX. This list will be used to figure out the users available in Exchange (which means, that a user, that isn't available in PBX won't be synchronized by the calendar). Finally, all appointments of the users Exchange calendar will be synchronized to the calendars database and used to update the users presence. The calendar also registeres himself to Exchange to get notified about changes in a users calendar. | ||
=== Synchronization === | === Synchronization === | ||
The way how the calendar receives the data from Exchange in 13r1 had been changed compared to the Exchange Sync Connector of previous version. The calendar now synchronizes all appointments for all users with it's own database. To activate the synchronization, use the PBX manager to edit the settings for the calendar. There, only the email address and the password for the impersonation user must be given. Exchange 2010 or newer is supported. This includes Exchange 365. Please note that not all Office 365 plans offers access to an Exchange 365 server - but an Exchange server is obligatory. An Office 365 plan without Exchange 365 won't work. More information can be found at [http://www.office.com Microsoft Office365 homepage]. | |||
=== Communication with Exchange === | |||
The calendar uses a standard HTTP or HTTPS connection to communicate with Exchange. There is no additional port setup necessary like it was with the old Exchange Sync Connector. Two HTTP(S) connections will be used to communicate with the Exchange. The first is for requesting appointment data and only will be active during data exchange. The other will be used to have some kind of open streaming connection to get informed about changes on Exchange side. This is a non-stop connection (well, actually it will be reestablished each 30 minutes). If HTTP or HTTPS will be used depends on the Exchange configuration. However, HTTPS is highly recommended. | |||
=== PBX Settings === | |||
The calender will replicate the users of the PBX to check if they can be synchronized with Exchange. Because there can be multiple PBX available, the calendar will only accept one. This one must be set in the calendar settings of the PBX manger by giving the name of the master PBX (Only the PBX Name, not the full DNS Name). Note that "master" don't mean that only a master PBX will be accepted. Also the name of a slave PBX can be entered. Master in that case means, that this will be the master for the calendar, the only PBX the calendar accepts a connection from. | |||
=== Impersonation user === | === Impersonation user === | ||
To synchronize all appointments from all users with Exchange, an Exchange user must exist with the Application Impersonation right. Impersonation means, that this user communicates with Exchange in the name of another user. So the calendar uses that user to synchronize every other user reported from the PBX and with an available mailbox in Exchange. Be aware of who has access to the impersonation users mail address and password, because that user has all rights to read, modify and add appointments, emails, tasks, etc. in Exchange for every other user. The calendar itself must save the password, but it will be stored in encrypted form to the database. For more information about impersonation user, ask your Exchange administrator. An example how to add this right to an existing user can be found here: [https://www.techieshelp.com/exchange-2013-configuring-impersonation-applications/ Exchange 2013 and 2016 Configuring Impersonation For Applications]. For other version of Exchange, please look to the proper documentation offered by Microsoft (or ask google). | |||
=== Autodiscover === | === Autodiscover === | ||
The calendar uses autodiscover to | The calendar uses autodiscover to get the Exchange Server version used as well as the address to use for synchronizing (which is done using the Exchange Web Services). Because of this, the impersonation user must have a valid mailbox, or autodiscover for that user will fail and the calendar won't be able to get the required information. It could be that Autodiscover it must be activated first. The Calendar searches for the server by taking the domain name of the given user (because of this, the complete email adress of the user must be given) and combinig it with autodiscover related URIs. The calendar then will test it at first with HTTPS and after that with HTTP. For example, if the email adress of the impersonation user is "myuser@example.com", the calendar will look for the autodiscover server at "https://autodiscover.example.com", "https://example.com", "http://autodiscover.example.com" and finally "http://example.com". Generally, one of the points will send a redirect request which will lead to the correct autodiscover URL, which will be used by the calendar. If there is no redirect and none of the URLs tested will work, autodiscover failed. You can get more information about autodiscover from the [https://docs.microsoft.com/en-us/exchange/architecture/client-access/autodiscover?view=exchserver-2019 Microsoft homepage] (even if it is for the latestes Exchange version, it is nearly the same for older ones), or your Exchange Administrator. | ||
You can test your autodiscover [https://testconnectivity.microsoft.com here]. | |||
=== Users and primary SMTP address === | === 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. This must be done | 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. This must be done to be able to synchronize the user. So make sure that the email information given to the users object in the PBX contains at least one address that also exists in Exchange, or the resolving will fail. Note that multiple addresses can given to the users object seperated by semicolon. | ||
== Presence == | == Presence == | ||
| Line 37: | Line 42: | ||
=== Presence string format === | === Presence string format === | ||
The format of the presence string created by the calendar | The format of the presence string created by the calendar. This description is for developer that whant to implement the display of the current presence in an own client and maybe adjust the values for a special timezone or date-time format. The format string the calendar will send canot be changed (except for language releated values that will depend on the "default presence language" and "default presence timezone" settings): | ||
Presence = "Free" / "Free until " Date-Time Next-Appointment / Appointment-Info "until " Date-Time [Next-Appointment] | |||
Date-Time = [Date] [Time] ; Must be at least one of them | |||
Date = Day ("." / "/") Month ("." / "/") Year ; Real format depends on localization settings | |||
Day = 2DIGIT ; 01-31 | |||
Month = 2DIGIT ; 01-12 | |||
Year = 4DIGIT ; e. g. 2017 | |||
Time = Hour ":" Minute ["a.m." / "p.m."] ; Real format depends on localization settings | |||
Hour = 2DIGIT ; 01-12 or 00-23 | |||
Minute = 2DIGIT | |||
Next-Appointment = "(" ["Busy: " / "Away: "] Appointment-Info ")" | |||
Appointment-Info = Title | "Private" ; | |||
Title = ; Well - any string in UTF8 Format that can include what ever you whant... | |||
After the presence string, a couple of hash-tags will be added (if Presence is not only "Free"). This tags will | After the presence string, a couple of hash-tags will be added (if Presence is not only "Free"). This tags will | ||
| Line 72: | Line 61: | ||
following rules (note that the order of the tags is not variable): | following rules (note that the order of the tags is not variable): | ||
Tags = "" / "#" Activity " " [Info-Len " "] Date-Time " " [Whole-Day " "] [Next-Activity " " Next-Appointment] | Tags = "" / "#" Activity " " [Info-Len " "] Date-Time " " [Whole-Day " "] [Next-Activity " " Next-Appointment] | ||
Activity = "free" / "busy" / "away" | Activity = "free" / "busy" / "away" | ||
Info-Len = "#len:" DIGIT ":" DIGIT ; The first DIGIT is the number of characters (UTF-8 conform) and the second the number of bytes | Info-Len = "#len:" DIGIT ":" DIGIT ; The first DIGIT is the number of characters (UTF-8 conform) and the second the number of bytes | ||
of the len of the Appointment-Info. This tag only exists if the presence starts with Appointment-Info. | |||
Date-Time = "#until:" DIGIT; DIGIT = Date-Time in sec as 64bit value. | Date-Time = "#until:" DIGIT; DIGIT = Date-Time in sec as 64bit value. | ||
Whole-Day = "#whole-day" ; Only if the appointment or the following one (depending on the case) or next is a | Whole-Day = "#whole-day" ; Only if the appointment or the following one (depending on the case) or next is a | ||
whole-day appointment. In that case, until should only print the date | |||
Next-Activity = "#next-activity" Activity ; Only, if there is a next is the start of the next appointment (see above). | Next-Activity = "#next-activity" Activity ; Only, if there is a next is the start of the next appointment (see above). | ||
Next-Appointment = "#next:" DIGIT ":" DIGIT ":" DIGIT ":" DIGIT ; | Next-Appointment = "#next:" DIGIT ":" DIGIT ":" DIGIT ":" DIGIT ; | ||
Where the first DIGIT is the position of the next activities Appointment-Info inside the presence | |||
string and the second DIGIT the Appointment-Info length. Those values are given in number of charactes (UTF-8 conform). | |||
The third DIGIT has the same meaning as the first, so that it is given in number of bytes, while the last DIGIT | |||
has the meaning of the second one, but also in bytes. | |||
=== Additional Notes === | |||
* The presence starts with "Free until", if there is an upcoming appointment. | |||
* If the presence starts with Appointment-Info, Date-Time will be the end of that appointment or the start of the next appointment, if the next appointment starts at or before the current one ends. | |||
* Date-Time will be time-only, if the is the same day as when the precense text will be build, date only, if the appointment (or Next-Appointmant in case that next is a appointment start) is a whole-day appointment. | |||
* Next-Appointment only will be written, if the presence won't start with an Appointment-Info. | |||
=== Example presence strings === | === Example presence strings === | ||
Latest revision as of 18:00, 18 November 2022
The App Service Calendar is an App Service which can be installed on an innovaphone App Platform. It is used to synchronize the exchange calendar of the users that have been added to the PBX. For now, the synchronized appointments will be used to update the presence of the users. Doing this, the calendar replaces the previous exchange connector.
Applies To
- innovaphone PBX from version 13r1
Apps
Calendar Admin App (innovaphone-calendar-admin)
(Still experimental) Gives some administrative options and can be used to get the current status.
PBX Manager Plugins
With the calendar plugin, apps can be created and deleted. Also the calendar can be configured.
Concepts
The calendar will get a list of all users available in the PBX. This list will be used to figure out the users available in Exchange (which means, that a user, that isn't available in PBX won't be synchronized by the calendar). Finally, all appointments of the users Exchange calendar will be synchronized to the calendars database and used to update the users presence. The calendar also registeres himself to Exchange to get notified about changes in a users calendar.
Synchronization
The way how the calendar receives the data from Exchange in 13r1 had been changed compared to the Exchange Sync Connector of previous version. The calendar now synchronizes all appointments for all users with it's own database. To activate the synchronization, use the PBX manager to edit the settings for the calendar. There, only the email address and the password for the impersonation user must be given. Exchange 2010 or newer is supported. This includes Exchange 365. Please note that not all Office 365 plans offers access to an Exchange 365 server - but an Exchange server is obligatory. An Office 365 plan without Exchange 365 won't work. More information can be found at Microsoft Office365 homepage.
Communication with Exchange
The calendar uses a standard HTTP or HTTPS connection to communicate with Exchange. There is no additional port setup necessary like it was with the old Exchange Sync Connector. Two HTTP(S) connections will be used to communicate with the Exchange. The first is for requesting appointment data and only will be active during data exchange. The other will be used to have some kind of open streaming connection to get informed about changes on Exchange side. This is a non-stop connection (well, actually it will be reestablished each 30 minutes). If HTTP or HTTPS will be used depends on the Exchange configuration. However, HTTPS is highly recommended.
PBX Settings
The calender will replicate the users of the PBX to check if they can be synchronized with Exchange. Because there can be multiple PBX available, the calendar will only accept one. This one must be set in the calendar settings of the PBX manger by giving the name of the master PBX (Only the PBX Name, not the full DNS Name). Note that "master" don't mean that only a master PBX will be accepted. Also the name of a slave PBX can be entered. Master in that case means, that this will be the master for the calendar, the only PBX the calendar accepts a connection from.
Impersonation user
To synchronize all appointments from all users with Exchange, an Exchange user must exist with the Application Impersonation right. Impersonation means, that this user communicates with Exchange in the name of another user. So the calendar uses that user to synchronize every other user reported from the PBX and with an available mailbox in Exchange. Be aware of who has access to the impersonation users mail address and password, because that user has all rights to read, modify and add appointments, emails, tasks, etc. in Exchange for every other user. The calendar itself must save the password, but it will be stored in encrypted form to the database. For more information about impersonation user, ask your Exchange administrator. An example how to add this right to an existing user can be found here: Exchange 2013 and 2016 Configuring Impersonation For Applications. For other version of Exchange, please look to the proper documentation offered by Microsoft (or ask google).
Autodiscover
The calendar uses autodiscover to get the Exchange Server version used as well as the address to use for synchronizing (which is done using the Exchange Web Services). Because of this, the impersonation user must have a valid mailbox, or autodiscover for that user will fail and the calendar won't be able to get the required information. It could be that Autodiscover it must be activated first. The Calendar searches for the server by taking the domain name of the given user (because of this, the complete email adress of the user must be given) and combinig it with autodiscover related URIs. The calendar then will test it at first with HTTPS and after that with HTTP. For example, if the email adress of the impersonation user is "myuser@example.com", the calendar will look for the autodiscover server at "https://autodiscover.example.com", "https://example.com", "http://autodiscover.example.com" and finally "http://example.com". Generally, one of the points will send a redirect request which will lead to the correct autodiscover URL, which will be used by the calendar. If there is no redirect and none of the URLs tested will work, autodiscover failed. You can get more information about autodiscover from the Microsoft homepage (even if it is for the latestes Exchange version, it is nearly the same for older ones), or your Exchange Administrator.
You can test your autodiscover here.
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. This must be done to be able to synchronize the user. So make sure that the email information given to the users object in the PBX contains at least one address that also exists in Exchange, or the resolving will fail. Note that multiple addresses can given to the users object seperated by semicolon.
Presence
The calendar will create a presence string for the appointments and send it to the PBX. The language and timezone of that presence can be defined in the calendar settings. However, the string also contains some information seperated by hashtags a client can use to rebuild the presence string for its own language and timezone settings (like it will be done by the innovaphone devices). Note that the appointment title itself won't be translated!
Presence string format
The format of the presence string created by the calendar. This description is for developer that whant to implement the display of the current presence in an own client and maybe adjust the values for a special timezone or date-time format. The format string the calendar will send canot be changed (except for language releated values that will depend on the "default presence language" and "default presence timezone" settings):
Presence = "Free" / "Free until " Date-Time Next-Appointment / Appointment-Info "until " Date-Time [Next-Appointment]
Date-Time = [Date] [Time] ; Must be at least one of them
Date = Day ("." / "/") Month ("." / "/") Year ; Real format depends on localization settings
Day = 2DIGIT ; 01-31
Month = 2DIGIT ; 01-12
Year = 4DIGIT ; e. g. 2017
Time = Hour ":" Minute ["a.m." / "p.m."] ; Real format depends on localization settings
Hour = 2DIGIT ; 01-12 or 00-23
Minute = 2DIGIT
Next-Appointment = "(" ["Busy: " / "Away: "] Appointment-Info ")"
Appointment-Info = Title | "Private" ;
Title = ; Well - any string in UTF8 Format that can include what ever you whant...
After the presence string, a couple of hash-tags will be added (if Presence is not only "Free"). This tags will be sent so that a client can re-build with the cleint's localization settings. The tags will be added with the following rules (note that the order of the tags is not variable):
Tags = "" / "#" Activity " " [Info-Len " "] Date-Time " " [Whole-Day " "] [Next-Activity " " Next-Appointment]
Activity = "free" / "busy" / "away"
Info-Len = "#len:" DIGIT ":" DIGIT ; The first DIGIT is the number of characters (UTF-8 conform) and the second the number of bytes
of the len of the Appointment-Info. This tag only exists if the presence starts with Appointment-Info.
Date-Time = "#until:" DIGIT; DIGIT = Date-Time in sec as 64bit value.
Whole-Day = "#whole-day" ; Only if the appointment or the following one (depending on the case) or next is a
whole-day appointment. In that case, until should only print the date
Next-Activity = "#next-activity" Activity ; Only, if there is a next is the start of the next appointment (see above).
Next-Appointment = "#next:" DIGIT ":" DIGIT ":" DIGIT ":" DIGIT ;
Where the first DIGIT is the position of the next activities Appointment-Info inside the presence
string and the second DIGIT the Appointment-Info length. Those values are given in number of charactes (UTF-8 conform).
The third DIGIT has the same meaning as the first, so that it is given in number of bytes, while the last DIGIT
has the meaning of the second one, but also in bytes.
Additional Notes
- The presence starts with "Free until", if there is an upcoming appointment.
- If the presence starts with Appointment-Info, Date-Time will be the end of that appointment or the start of the next appointment, if the next appointment starts at or before the current one ends.
- Date-Time will be time-only, if the is the same day as when the precense text will be build, date only, if the appointment (or Next-Appointmant in case that next is a appointment start) is a whole-day appointment.
- Next-Appointment only will be written, if the presence won't start with an Appointment-Info.
Example presence strings
Free Free until 10:30 (Busy: Meeting with Caption Sparrow) #free #until:12345 #next-activity:busy #next:24:28:48:28 Meeting with Caption Sparrow until 12:30 #busy #len:28:28 #until:12345 Free until 24.12.2017 (Busy: Christmas) #free #until:54321 #whole-day #next-activity:busy #next:29:9:29:2 Christmas until 27.12.2017 #busy #len:9 #until:42424242 #whole-day Sleeping until 22.08.2017 07:00 #away #len:8 #until:3333333