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.

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 calendar user is a so called party crasher. 1. Let's assume you actually add the party crasher to the appointment. 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. 2. Let's assume you declined the participation of the party_crasher. The server will generated a [CANCEL] message to the unknown calendar user based on the information of the REPLY message, avoiding any data leakage.

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

A user is working "on behalf of" another user whenever * the user is updating or deleting an existing appointment that is not organized by herself * the user is creating an appointment in a shared calendar not owned by her

When working on behalf, the relationship is reflected in outgoing iTIP mails. On one hand side, change descriptions in the outgoing mail will contain "on behalf of" phrasing, like You have been invited to an appointment by Anton on behalf of Berta. On the other hand, fields in generated iCAL files and sent mails are added, like the sent-by field in iCAL.

On behalf management of incoming iMIP messages

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 latter 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 acting user whom the calendar AND INBOX was shared to is working on behalf of the sharing user, permissions to the underlying mail folder and the calendar folders will be checked. Processing is only possible if enough permissions in both folders exist. Scheduling messages sent by the acting user will be announced as on behalf. For example, a new appointment created by the acting user will lead to a message to the sharing user, who is the organizer, saying that the acting user sent an invitation on your behalf. Attendees for that invitation will receive a mail saying that the acting user created an event on behalf of the sharing user. Both mails will be sent using the sharing users' mail account.

Administrator notes

In some casses, the acting calendar users is a guest user, e.g. using the federated sharing feature. Guest users don't neccesarrily have access to the calendar owner's mail account. Therefore generally, whenever a guest user initializes the iTIP workflow, the no-reply account is used to send scheduling messages. Please note that mail headers on the scheduling message will be set using the calendar users data, because iMIP is pretty strict towards validation of mail headers. E.g. the FROM header will be filled with the calendar owner's mail address, the SENDER header with the acting user's mail address.

Further reading

1. RFC 5546 Section 2.1.3
2. com.openexchange.noreply* properties

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.

Suppress Scheduling Messages

After group-scheduled events have been created, modified or deleted through a client request via CalDAV or the HTTP API, the server does auto-scheduling, which includes the update of scheduling object resources stored on the server, as well as the generation and transport of all necessary scheduling messages to the affected recipients via email - both regular iMIP messages as well as notification messages without iCalendar attachment for internal recipients. However, there are some options for clients to suppress the transport of these emails under certain circumstances.

"Schedule-Reply" Header

CalDAV clients may include the request header Schedule-Reply with a value of F to disable the generation of scheduling messages, e.g. when the user wants to delete an unsolicited invitation (i.e. Spam) from his calendar without sending a CANCEL message to the organizer. The header is supported via CalDAV only, as per RFC 6638, section 8.1.

"Scheduling" Header or Parameter

Similarly as Schedule-Reply, the header Scheduling can be used by CalDAV clients to influence if and which scheduling messages should be sent in a more flexible way. This setting is aligned to the proposed, yet stalled standards extension caldav-scheduling-controls.

The header accepts the following values: * all: Instructs the server to follow the behavior in RFC 6638, section 3.2 * none: Instructs the server to perform no scheduling at all, and to just store the event (useful for restoring from backup). * internal-only: Instructs the server to update the events in other calendars within its system where that can be done silently, but not to send visible notifications to users (where permitted by policy). This is useful when importing multiple related calendars into a new system without flooding external parties with notifications. * external-only: Instructs the server to import the data without updating local calendars, but to send notifications to external attendees so they are aware of the event. This is useful when migrating calendar events to a new system where external parties need to have a way to update their participation status in the new system.

Clients using the HTTP API like App Suite UI can supply these values via the parameter scheduling on all modifying operations in the chronos module. See HTTP API documentation for further details.

Schedule-Agent Parameter

As per RFC 6638, section 7.1, the parameter SCHEDULE-AGENT can be specified on ORGANIZER or ATTENDEE properties of scheduling object resources. By default, SERVER is assumed, i.e. the server handles generation and transport of scheduling messages.

If a value different from SERVER is set by CalDAV client, no scheduling messages to the corresponding calendar user are generated and sent by the server, as it was either forcibly disabled (i.e. value NONE), or it is assumed that the client takes care on his own (value CLIENT).

However, as implicit auto-scheduling is performed by the server by default, primarily for clients accessing the HTTP API, this parameter is only effective within the context of the actual CalDAV operation, and is not persisted within the ORGANIZER/ATTENDEE properties of the calendar object resource stored on the server. That means that clients would have to set this parameter repeatedly on subsequent rescheduling operations on their own to prevent scheduling messages being sent by the server again.

Since a value for SCHEDULE-AGENT is extracted but not persisted, it is also allowed for clients to set this parameter value on properties they are normally not allowed to change, i.e. beyond allowed attendee changes (RFC 6638, section 3.2.2). For example, a client that would like to prevent to send a REPLY to the organizer after changing its participation status could still add SCHEDULE-AGENT=CLIENTon the ORGANIZER property and put the updated scheduling object resource to the server without running into the CALDAV:allowed-attendee-scheduling-object-change precondition code.

Alternatively, the Schedule-Reply or Scheduling headers can always be set to control the generation and transport of scheduling messages.

Exclusions

• For appointments that end in the past, no notifications or iMIP messages are sent.
• During manual import of iCalendar files, no messages are generated.
• Whether a message to a context-internal user is sent can be configured via the notification settings of the recipient.

References / further reading

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