30 Using the iSchedule Channel to Handle iMIP Messages

Oracle Communications Messaging Server is capable of posting a calendar event received in an iMIP (iCalendar Message-Based Interoperability Protocol) message to Calendar Server by using the iSchedule protocol. This capability enables "internal" users to automatically process calendar invitations from "external" users. To enable this interoperability between calendaring systems, you configure a Messaging Server "iSchedule" channel to process the iMIP messages. For additional information, see the discussion on enabling the iSchedule channel to handle iMIP messages in the Calendar Server System Administrators Guide.


Inviting Users on Internal and External Calendar Systems Background

Calendar Server meetings often have multiple invitees. These invitees can be both internal users, who reside on the same Calendar Server deployment, or external users, who reside either on a different Calendar Server deployment administered by a separate group, or on an outside calendaring system, such as Exchange, Google Calendar, and so on. For "internal" invitees, Calendar Server automatically adds the meeting request to their calendars (referred to as implicit scheduling) and also sends them email notification about the meeting request. All "external" invitees are sent an iMIP (iCalendar Message-Based Interoperability Protocol) email with the meeting request as an attachment. External invitees must manually process these messages to add the invite to their calendars.

Manually Accepting External Invitations

Meeting invitations from external organizers are sent to the user's mailbox. Mail clients, such as Outlook or Thunderbird, enable users to process these invitations and add the invitation to their calendar. How the invitation is added to the user's calendar depends on the specific mail client, but the invitation is not added until the user has manually read the email and accepted the meeting request.

Automatically Accepting External Invitations

You can configure your Calendar Server deployment to automatically process invitations coming from external calendar systems. To users, handling an external invite then appears just like an internal invite.

This capability involves an intermediary in the form of Messaging Server. You configure the Messaging Server MTA to process the calendar invite email (which is an iMIP message), extract the pertinent calendar information, then use the iSchedule protocol to add the invite to the attendee's calendar database. As a consequence, external event invitations automatically appear in the user's calendar without the need for a manual intervention, even when using a "non-calendar" aware client.

Once you have configured your deployment accordingly, users have a choice on how to process invitations. Users can either accept the "external" meeting invite directly from their calendar client (either desktop or mobile iOS CalDAV clients) or they can still accept it from their email client. That is, CalDAV clients now receive iMIP messages in their scheduling-inbox, and are able to process them just like regular CalDAV-based invitations and replies. Because the invitation is already in the user's calendar, invitation replies and cancel are also merged automatically. Thus, based upon the user accepting or rejecting the request, the calendar client merely has to update the attendee status in the invitation. That status change also enables Calendar Server to send a response to the organizer indicating the disposition of the meeting request. As the response is sent directly by Calendar Server, it does not matter how the user accepted the invitation (whether from a calendar client on a mobile device, desktop, or from an email client). Finally, because of the addition of meta data to the email message, the Convergence (web-based) client is able to display a scheduling-specific form to users that enables them to accept, decline, or indicate a "maybe" to meeting invitations directly from their email without having to switch to the calendar client.

Message Server iMIP Configuration Overview

A Messaging Server MTA channel (an "iSchedule" channel) handles automatic processing of external calendar invites by:

  1. Intercepting incoming emails containing an iMIP message An iMIP message has an iCalendar attachment of type 'text/calendar' with a method=<action> option in the 'Content-Type:' header.

  2. Injecting the corresponding iTIP message into the regular calendar server workflow

  3. Adding meta-data (email X- headers) to the iMIP email before delivering it to its recipients

  4. Posting the invitation request to a calendar iSchedule URL

The Calendar Server then consumes the invitation from the iSchedule URL just as it would have done if an external calendar server had posted an invitation to one of its users. On the Calendar Server side, an iSchedule database, which is a separate table from the Calendar Server database, acts as the global inbox and outbox for external invites.

Administering the iMIP configuration involves:

  • Enabling or disabling iMIP messaging processing

  • Configuring the iSchedule service URL

  • Configuring the criteria for messages to be selected for processing

You should configure the iSchedule channel on the message store systems if you are not using LMTP. If you are using LMTP, configure the iSchedule on the MTAs.

For more information on the iCalendar Message-Based Interoperability Protocol, see RFC 6047 (http://www.faqs.org/rfcs/rfc6047.html). For more information on iCalendar Transport-independent Interoperability Protocol (iTIP), see RFC 5546 (http://www.faqs.org/rfcs/rfc5546.html).

Configuring the iSchedule Channel for iMIP Messages in Unified Configuration

You can use a Messaging Server Unified Configuration recipe to automate the configuration process or you can manually perform the necessary configuration. After completing the configuration, you also need to verify the Calendar Server configuration, as described in "Verifying the Calendar Server Configuration."

You do not need to perform any additional Convergence configuration for Convergence to automatically process invitations coming from external calendar systems. If you have configured Messaging Server and Calendar Server correctly, Convergence users see a UI form that they use to reply to external invites.

Topics in this section:

Using the iSchedule Recipe to Automate Configuring the iSchedule Channel in Unified Configuration

Unified Configuration provides a recipe language and some stock recipes to automate certain configuration tasks (see "Using Recipes"). To set up the iSchedule channel, you can use a recipe called iSchedule.rcp, which automatically sets up the channel definition, job controller configuration, channel options, Sieve rule, and CONVERSION mapping.

To use the iSchedule.rcp recipe:

  1. Run the msconfig command with the recipe name.

    /opt/sun/comms/messaging64/bin/msconfig run iSchedule.rcp
  2. Respond to the prompts, for example:

    HTTP URL for iSchedule server: http://host1.example.com:8080/dav/ischedule/
    Destination channel for messages to check (<RET> if no more): ims-ms

    Use the iSchedule URL and destination channels based on your deployment.


    Be sure to add the trailing forward slash (/) in the iSchedule URL, otherwise you will receive the error message "HTTP Error 401 Unauthorized."
  3. If you are using a compiled configuration, recompile the configuration.

    /opt/sun/comms/messaging64/bin/imsimta cnbuild
  4. Restart Messaging Server.

  5. Verify the Calendar Server configuration. See "Verifying the Calendar Server Configuration."

Manually Configuring the iSchedule Channel in Unified Configuration

The high-level steps to manually configure the iSchedule channel by using the msconfig command involve:

  • Adding the channel

  • Configuring the conversion mapping

  • Specifying messages to be processed by iSchedule

To manually configure the iSchedule Channel, job controller master command, include_conversiontag MTA option, and conversion mapping:

  1. Use the msconfig command in interactive mode to configure the iSchedule channel, the job controller master command for the channel, the include_conversiontag MTA option if you want to have a TAG= clause included in your conversion mapping probes, and the conversion mapping.

    msconfig> set channel:ischedule.official_host_name ischedule-daemon
    msconfig# set channel:ischedule.options.handle-imip 1
    msconfig# set channel:ischedule.options.ischedule-url http://<host>:<port>/dav/ischedule/
    msconfig# set instance.job_controller.channel_class:ischedule.master_command IMTA_BIN:ischedule
    msconfig# set mapping:conversion.rule "IN-CHAN=ischedule;OUT-CHAN=*;TAG=*;CONVERT" NO
    msconfig# set mapping:conversion.rule "IN-CHAN=*;OUT-CHAN=*;TAG=ISCHEDULE;CONVERT" "YES,CHANNEL=ischedule"
    msconfig# set include_conversiontag 2
    msconfig# write

    Use the host name and alternately the port for the Calendar Server configured for the iSchedule database.


    Be sure to add the trailing forward slash (/) in the ischedule-url, otherwise you will receive the error message "HTTP Error 401 Unauthorized."
  2. Edit the filters block to specify messages to be processed by iSchedule.

    msconfig> edit filter

    The filter block appears in the editor that is the default configured for your login.

  3. Add the following lines to create a filter that selects all the messages that have "text/calendar" MIME as an attachment:

    require ["mime", "environment"];
    if allof(environment :is "vnd.sun.destination-channel" ["ims-ms"],
    header :mime :anychild :contenttype :is "content-type" "text/calendar",
    NOT header :contains "X-Oracle-CS-iSchedule-Ignore" "Yes") {
    addconversiontag "ISCHEDULE";

    iMIP messages generated by Calendar Server contain a "X-Oracle-CS-iSchedule-Ignore: Yes" header to indicate that the event was already added to the user's calendar. So, the Sieve rule should ignore those iMIP messages by not tagging them with an ISCHEDULE conversion tag. Failing to do so results in an iSchedule post of the event that is already present in the user's calendar.

  4. Write the configuration and exit the msconfig interactive mode.

    msconfig# write
    msconfig> exit
  5. If you are using a compiled configuration, recompile the configuration.

    /opt/sun/comms/messaging64/bin/imsimta cnbuild
  6. Restart Messaging Server.

  7. Verify the Calendar Server configuration. See "Verifying the Calendar Server Configuration."

Verifying the Calendar Server Configuration

To ensure that your Calendar Server configuration is setup properly, use the following steps to verify SMTP settings and iMIP email notifications. iMIP email notifications need to also be configured for internal users, that is, users on the same Calendar Server host. If necessary, restart the GlassFish Server container on which Calendar Server is deployed.

  1. Check the SMTP configuration for the following settings.

    cd CalendarServer_home/sbin
    davadmin config list|grep smtp
  2. Check the email notifications configuration.

    davadmin config modify -o notification.dav.smtpstarttls -v false
    Enter Admin password:
    davadmin config list|grep imip
    davadmin config modify -o notification.dav.enableimipemailnotif -v true
    Enter Admin password:
  3. Check the whitelist configuration for the iSchedule port. The service.dav.ischedulewhitelist configuration option prevents denial of service attacks on the iSchedule port. See the discussion on enabling the iSchedule channel to handle iMIP messages in the Calendar Server System Administrators Guide for more information.

  4. If necessary, restart GlassFish Server. For example:

    /opt/SUNWappserver/bin/asadmin stop-domain domain1
    /opt/SUNWappserver/bin/asadmin start-domain domain1

Modifying iSchedule Channel Options

After you have configured the iSchedule channel, you might need to change iSchedule channel options as described in this section.

Topics in this section:

To Enable or Disable iMIP Message Processing

  • Use the msconfig command to enable or disable iMIP message processing by setting the handle-imip option to 1 or 0 respectively. For example, the following command disables iMIP message process:

    msconfig> set instance.channel:ischedule.options.handle-imip 0
    msconfig# write
    msconfig> exit

To Modify the iSchedule Service URL

  • Use the msconfig command to modify the iSchedule URL by editing the ischedule-url option. For example:

    msconfig> set instance.channel:ischedule.options.ischedule-url http://<host>:<port>/dav/ischedule/
    msconfig# write
    msconfig> exit

Configuring the iSchedule Channel in Legacy Configuration

This section describes how to configure the iSchedule channel for Messaging Server in legacy configuration (that is, Messaging Server 7 Update 5 and greater but you either did not convert an existing deployment to Unified Configuration, or choose to install a fresh deployment using Unified Configuration.)

  1. Create the iSchedule channel.

    1. Add following lines to the MessagingServer_home/config/imta.cnf file:

    2. Add the following lines to the MessagingServer_home/config/job_controller.cnf file:

  2. Configure CONVERSION mapping by adding the following lines to the MessagingServer_home/config/mappings file:

     IN-CHAN=ischedule;OUT-CHAN=*;TAG=*;CONVERT NO
  3. Enable or disable iMIP message processing. To enable or disable iMIP message processing, create a channel options file, MessagingServer_home/config/ischedule_option, and add the following line:

    handle-imip=1 (to enable)
    handle-imip=0 (to disable)
  4. Configure the iSchedule service URL. In the channel options file, specify the iSchedule Service URL as follows:

  5. Configure the include_conversiontag MTA option if you want to have a {TAG=}} clause included in your conversion mapping probes by adding the following line to the MessagingServer_home/config/option.dat file:

  6. Specify messages to be processed by iSchedule. Run the following Sieve script to select all the messages that have text/calendar MIME as an attachment. This script should be placed in the location of your system-wide scripts.

    require ["mime", "environment"];
    if allof(environment :is "vnd.sun.destination-channel" ["ims-ms"],
    header :mime :anychild :contenttype :is "content-type" "text/calendar",
    NOT header :contains "X-Oracle-CS-iSchedule-Ignore" "Yes") {
    addconversiontag "ISCHEDULE";
  7. If you are using a compiled configuration, recompile the configuration.

    /opt/sun/comms/messaging64/bin/imsimta cnbuild
  8. Restart Messaging Server.

  9. Verify the Calendar Server configuration. See "Verifying the Calendar Server Configuration."

Troubleshooting the iSchedule Configuration

Use the following information to troubleshoot your iSchedule configuration:

  • All messages processed through the iSchedule channel have a "Received:" header containing ischedule-daemon.host.domain. This is true whether handling iMIP is enabled or not. If iMIP handing is enabled, the iMIP messages have an extra header, "X-Oracle-CS-iSchedule-Status:," which contains the HTTP status code sent by the iSchedule service in response to the posted iSchedule message.

  • The iSchedule channel log files are located in MessagingServer_home/log/ischedule_master.log.*

  • Use the MessagingServer_home/bin/imsimta qm counters command to list the number of messages processed by the iSchedule channel.

  • One common misconfiguration is to specify a wrong destination channel in the Sieve rule. If you do not see the "X-Oracle-CS-iSchedule-Status:" header in iMIP e-mails, or do not see the iSchedule counters increase when you use the imsimta qm counters command, check if the destination channel that you specified in the Sieve rule matches the destination channel that you have configured for that user.