iCalendar Transport-Independent Interoperability Protocol (iTIP) deprecated
This article will describe how the iTIP protocol was implemented, which parts of the protocol are missing and where the implementation differs from the standard. Furthermore, this article will describe internal handling
General
iTIP
iTIP is a standard. It defines "how calendaring systems use iCalendar RFC5545 objects to interoperate with other calendaring systems"1. So basically it's about how to organize, maintain and update calendar events across multiple systems.
Transport
The RFC does explicit not mention a specific transport mechanism for iTIP. The provider implementing the RFC is free to choose. Open-Xchange uses mail to realize the iTIP protocol, efficiently implementing iMIP, too.
Handled components
The iTIP protocol allows to synchronize following components
- VEVENT
- VFREEBUSY
- VTODO
- VJOURNAL
Currently the Open-Xchange Server will only handle the VEVENT component.
Implementation details
The iTIP protocol describes workflows for the calendar systems on how to handle calendar resources locally. Based on this workflow a calendar system might create, update or delete calendar resources and send scheduling messages to attendees or a organizer of a resources. Such messages are decorated with a designated method that indicates a certain workflow for the calendar system. The methods and their syntax are described below. The iTIP workflow on the Open-Xchange calendar system is fully controllable over the HTTP API. Incoming messages will be recognized and analyzed for the user, displaying human understandable descriptions about the messages content and indicating actions a user might want to perform in the calendar system base on the message.
User interaction
Even though the protocol is designed for calendar systems to interoperate, situations will arise in which the user must finally decide what to do. Such situation can be triggered due technical problems, such as a concurrent modification of a calendar resource from third party calendar agents over CalDAV, or simply when the calendar system can't decide in the name of the user. Later situation might differ from the role of the user.
As attendee
Whenever an attendee is invited to a new appointment the calendar system can't decide for the user if she wants to participate or not. Therefore the system will prompt to the user whether to accept, tentative accept or to decline the invitation. This is also the case when the user might is about to become a so called party crasher. Another user can simply forward an iMIP mail to someone else, maybe only with the lines "can you join the meeting for me". However, that user isn't part of the participant list, the organizer has created. So the organizer would receive an REPLY from a so called unwanted calendar user, or more frankly a "party crasher", in case the system just accepts such an mail. Again, to avoid some unwanted actions, the user is prompted to some actions. Another typical scenario for additional interaction from the attendee is when an already accepted appointment gets rescheduled. The attendee might have no other conflicting appointment in his calendar but the calendar system doesn't know about e.g. end of business times. So instead of auto-re-accepting the appointment the user has to decide about his participation.
As organizer
Event though the organizer is the single point of change regarding the events properties like description or location, she may will get a response which needs attention from her. Such a case is for example when an uninvited attendee responses to a invitation. This might be a legal response in case of a delegation but can also happen when an scheduling message(iMIP) is forwarded to third party, that replies. The calendar system however can't decide if this is a legal response and the uninvited attendee shall be added to the event (triggering subsequent scheduling messages) or if this message shall be ignored.
Working on behalf of
Starting with v7.10.6 of the Open-Xchange server the working "on behalf" of another user scenario was extended. Whenever a user decides to share her calendar AND her INBOX to another internal user the later is allowed to handle the iTIP workflow on behalf of the first. This is frankly speaking the secretary function where a manager leaves the calendar management to her secretary. When the secretary is working on behalf of the manager, permissions to the underlying mail folder and the calendar folders will be checked and processing is only possible if enough permissions in both folders exist. Scheduling messages sent by the secretary will be announced as "on behalf". For example a invitation created by the secretary will generate a message to the organizer saying that he "sent an invitation on your behalf". Attendees for that invitation will receive a mail saying that the secretary "created an event on behalf" of the manager. Both mails will be sent using the managers mail account.
Automatically processing of incoming messages
Starting with v7.10.6 of the Open-Xchange server automatically processing of incoming scheduling messages is possible. Thus, the user interaction is reduced to a minimum. Cases outlined above however still needs user interaction.
Automatically processing will be possible for e.g. replies of a known attendee to the organizer. In earlier versions an organizer had to "Apply changes" from the REPLY of the attendee to the master copy of the organizer's event. There was no other choice, expect to ignore the reply and have a wrong participant status for the replying attendee. Now, the participant status of the attendee will be updated in the event the moment the iMIP mail is processed. Thus, the organizer doesn't need to click any button anymore. Instead a message will be displayed to the organizer, informing her about the updated event.
Automatically processing can be trigger through two different mechanism. The first mechanism processes the mail whenever it passes the Middleware server through direct user interaction (e.g. the user opens the INBOX). This mechanism uses a so called MailListener. The second mechanism is a dedicated REST endpoint to which mails can be pushed to, whenever a mail backend recognizes a iTIP/iMIP mail. Later is described in a dedicates section below.
Configuration
To configure the MailListener based approach, two properties are available. The property com.openexchange.calendar.autoProcessIMipOnMailFetch defines whether the features is generally enabled or not. By default is enabled. The other is the com.openexchange.calendar.autoProcessIMipTimeframe property. It defines a maximum age for iTIP/iMIP mails in which they will be processed or not, based on the receive date of the mail. The property is necessary to avoid old iTIP/iMIP mails being automatically being processed. This becomes handy if you have for example an existing system with many mails in the users INBOX and update to a version >=7.10.6. The default value for the property is 4W representing four weeks. Values like e.g. 2D 1h 12ms (two days, one hour, twelve milliseconds) will be accepted, too.
Further, with automatically processing comes a new threat to the user. Attackers could spam the user with iITP/iMIP mails, flooding the calendar of the user. Therefore, a new user property was introduced. The property will be available and modifiable over the JSLob (API). The new property is called autoProcessIMip which will be available under the chronos section in the calendar properties.
The property has three values:
always- to always apply changes from iMIP mails, if applicable (again cases outlined above still needs user interaction)known- For either lookup against- attendees in an already existing events
- known contacts of the user in all her visible address books in case the event is unknown
never- to never automatically apply data. This reflects the handling of iTIP/iMIP mails in previous versions (<=7.10.5)
The default value is known.
API example
The property can be set using the JSLob API. Here is a short example
http://localhost/appsuite/api/jslob?action=set&id=io.ox/calendar&session=123
{
"interval": 30,
...
"chronos":
{
...
"autoProcessIMip": "known"
}
...
}
Methods
PUBLISH
The PUBLISH method isn't treated in any special way. A VENENT posted over PUBLISH is handled the same way as a REQUEST.
REQUEST
With the REQUEST method initial invites, updates, rescheduling and more is realized. Many of the functionality mentioned in the RFC is build into the software. Not supported is delegating an event to another CU or forwarding to an uninvited CU.
Subsequent scheduling
Please note that when an request is processed it is possible that further mails will be generated by the server and send back to the organizer of the event. This will normally happen if an attendee updates her status on the incoming event by e.g. accepting an invitation. See also the REPLY method.
REPLY
A REPLY normally should only transmit the replying attendee status. Nevertheless some calendaring systems edit other properties on the event replying to, too. To avoid e.g. a changed event title, the server will silently drop all changed properties that are not allowed to be changed as defined in the RFC 5546 and RFC 6047.
However changed parameters on the attendee object itself will be taken over. As long as the URI of the attendee doesn't change all other parameters can be edited.
Subsequent scheduling
Please note that when an reply is processed it is possible that further mails will be generated by the server. For example, let's assume an unknown calendar user answered to an event by accepting it and sending you, the organizer, a REPLY. This so called party crasher can be added to the event. Let's further assume you actually add the party crasher. Likewise a normal adding of an attendee, this action will generate a mail to (at least) external calendar users, informing them that a new participant is attending the event.
ADD
The ADD method is implemented as recommended by the RFC.
CANCEL
The CANCEL method is mostly implemented as recommended by the RFC.
Please note that following conditions slightly differs from the RFC and must also be met before a CANCEL is applied: * The sequence number of the transmitted event is equal or greater than the sequence number of the event known by the server * The sender of the mail is the organizer or someone acting on behalf of the organizer, announced by a set sent-by field in the corresponding organizer field
REFRESH
The REFRESH method is implemented as recommended by the RFC.
COUNTER
The COUNTER method is implemented as recommended by the RFC.
DECLINECOUNTER
The DECLINECOUNTER method is implemented as recommended by the RFC.
REST API
There is also a REST endpoint to push iMip Mails to the server, which will then be processed.
Endoint
The API ist accessible via the URL http://example.org/chronos/v1/itip/pushmail
The body consists of a json object: { "user": "2@123", "event":"messageNew", "folder":"INBOX", "body:"From: user@example.com\nTo: user2@example.com\nSubject: calendar\nContent-Type: text/calendar\n\nICAL CONTENT\n ..." }
HTTP 204 No content will be returned on success.
Authentication
The API can be accessed, when transmitting credentials via basic auth.
Configuration
Depending on the mail backend that sends the push mail, different scenarios on how the user information is transmitted to the Middleware are imaginable. Therefore, the service behind the endpoint is capable of using different modes which correspond to those scenarios. The modes can be set using com.openexchange.calendar.pushedIMipResolveMode. Following values are available: * recipientOnly: Only the email's recipient is considered and resolved through the configured MailResolver service. * synthetic: The push message's username is expected in mailLogin: The push message's username is the mail login, which is then resolved through a configured MailLoginResolver service. * loginInfo: The push message's username is expected in
The basic idea here is to resolve a specific string containing the user infomation to a system understandable user object. For the modus recipientOnly a so called Mailresolver is used. A resolver searches for a user by its mail addresses, thus it can be resolved to a user and context identifier. For further details on the resolvers please have a look at the Mail Resolver article. The modus synthetic expects a synthetically constructed string of a user and a context identifier seperated by an @ sign. These identifier are easy to understand and check for existence for the server. mailLogin uses a dedicates service which is able to resolve a mailbox owner or an IMAP ACL to a dedicated user. The mechanism is described in it own article, which can be found here at Mail Login Resolver Similar to the modus synthetic, the modus loginInfo expects a constructed string consisting of two different information seperated by an @ sign. In comparison to the other mode, it is expected that the string contains the user name and the login mapping for the context of the user. Both information will be checked and translated to a proper object by internal services.