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 objects to interoperate with other calendaring systems". 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.

Components

The iTIP protocol allows to synchronize following components

  • VEVENT
  • VFREEBUSY
  • VTODO
  • VJOURNAL

Currently the Open-Xchange Server will only handle the VEVENT component.

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.

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.

Automatic processing of incoming messages

Starting with v7.10.6 of the Open-Xchange server, an automatical processing of incoming scheduling messages is possible. Thus, the user interaction is reduced to a minimum. Cases outlined above however still needs user interaction.

Automatic 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.

Automatic 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 an iTIP/iMIP mail.

Independently of how automatic processing of an incoming scheduling mail is triggered, there are certain sanity and consistency checks in place so that only valid messages are applied automatically that are not already outdated compared to the currently stored appointment copy. Also, one should mention that when automatically importing incoming scheduling requests, this feature could be abused by spammers that would be able to flood the user's calendars with unsolicited appointments once they've bypassed the anti-spam filter of the mail server. Therefore, a new user property was introduced, which is available and modifiable through the JSLob (API). The new property is called autoProcessIMip which will be available under the chronos section in the io.ox/calendar properties.

The property has three values:

  1. always - to always apply changes from iMIP mails, if applicable (again cases outlined above still needs user interaction)

  2. known - For either lookup against

    1. attendees in an already existing events
    2. known contacts of the user in all her visible address books in case the event is unknown

  3. never - to never automatically apply data. This reflects the handling of iTIP/iMIP mails in previous versions (<=7.10.5)

The initial value can be set through property com.openexchange.calendar.autoProcessIMip, and defaults to known.

Mail Listener

To activate and 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 it 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.

The Mail Listener integrates into the regular mail fetching logic of the middleware, and so is implicitly triggered through actions the user actively does in clients. For example, when the Inbox folder is opened, a certain amount of emails is retrieved from the mail server to be displayed in a list in App Suite. Then, when data of these mails is retrieved anyway, the mails are processed and analyzed on the fly, and, once an iMIP message is detected and was not processed before, it is applied to the user's calendar automatically based on the indicating scheduling method (REQUEST, REPLY, CANCEL etc.).

In order to do this additional processing without negatively impacting the user experience through increased response times, and without generating additional load on the mail server backend, it is important that suitable indexes are in place on the mail server for the `IMAP BODYSTRUCTURE´ response, which describes what the message’s MIME structure looks like. For Dovecot, see Mail Cache Settings for further details.

Also, in order to remember that an email message has already been processed by App Suite, support for storing user flags is required.

Push via REST API

Besides the MailListener based approach outlined above, the middleware also exposes a REST endpoint to push iMIP Mails to the server, which will then be processed. The API endpoint is accessible via the URL

http://appsuite.example.com/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 ..."
}

Authentication is done via basic auth, as configured via com.openexchange.rest.services.basic-auth.login. The endpoint will return HTTP 200 OK on success. Detailed documentation of the API endpoint can be found here.

The following sections describe how to configure the automated iMIP processing via push, both for the middleware, and Dovecot.

Middleware 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. The 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 <userid>@<contextid> notation.
  • 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 <username>@<loginmapping> notation and resolved through corresponding login mappings.

The basic idea here is to resolve a specific string containing the user information 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 separated by an @ sign. These identifier are easy to understand and check for existence for the server.

mailLogin uses a dedicated 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 separated 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.

If the push endpoint is used for automated iMIP processing, the MailListener based approach is still useful to also cover iMIP mails that were not yet pushed to the middleware, e.g. because they exceed a maximum size, or if the targeted calendar user could not be determined properly. Proper sequencing and timestamp checks are always in place so that a scheduling message is still only applied once to the user's calendar, even if it is processed by both the push endpoint and the mail listener.

Dovecot Configuration

Dovecot can be used as the mail backend to send push notifications to the Middleware. Therefore, the dovecot-ee-chronos-push-notification-plugin is required, which is available since v2.3.20 / v3.0.0. After the plugin has been installed, it needs to be enabled:

mail_plugins = $mail_plugins chronos_push_notificationn

Furthermore, the Open-Xchange push endpoint needs to be configured in the plugin configuration section:

plugin {
    push_notification_driver = chronos:url=http://<user>:<password>@appsuite.example.com:8009/chronos/v1/itip/pushmail
}

The user and password needs to match the following Middleware properties:

  • com.openexchange.rest.services.basic-auth.login
  • com.openexchange.rest.services.basic-auth.password

More details about the Dovecot plugin can be found here.

References / further reading

  1. RFC 5545 iCalendar
  2. RFC 5546 iTIP
  3. RFC 6047 iMIP