Using the iSchedule Channel to Handle iMIP Messages

Skip to end of metadata
Go to start of metadata

Using the iSchedule Channel to Handle iMIP Messages

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 Enabling the iSchedule Channel to Handle iMIP Messages.

This capability was introduced in Communications Suite 7 Update 4 (Messaging Server 7 Update 5 and Calendar Server 7 Update 3).

Topics:

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

In Calendar Server 7 Update 2, 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. In Calendar Server 7 Update 2, automatically accepting external invitations is not possible.

Automatically Accepting External Invitations

Starting with Calendar Server 7 Update 3 (in conjunction with Messaging Server 7 Update 5), 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> parameter 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 2447. For more information on iCalendar Transport-independent Interoperability Protocol (iTIP), see RFC 5546.

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

    Note
    Be sure to add the the trailing forward slash (/) in the iSchedule URL, otherwise you receive the error message "HTTP Error 401 Unauthorized."
  3. If you are using a compiled configuration, recompile the configuration.
  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:

  1. Use the msconfig command in interactive mode to edit the available channels.

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

  2. Add the following lines.
    ischedule
    ischedule-daemon
    ==
    ischedule-url=http://<host>:<port>/dav/ischedule/
    handle-imip=1
    

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

    Note
    Be sure to add the the trailing forward slash (/) in the ischedule-url, otherwise you receive the error message "HTTP Error 401 Unauthorized."
  3. Save your changes and exit the editor.
    You are returned to the msconfig prompt, which changes to a pound-sign.
  4. Write the configuration and remain in msconfig interactive mode.
  5. Configure the job controller master command for the iSchedule channel, write the change, and remain in interactive mode.
  6. Edit the mappings block to add a conversion mapping.

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

  7. Add the following lines:
    CONVERSION
      IN-CHAN=ischedule;OUT-CHAN=*;TAG=*;CONVERT  NO
      IN-CHAN=*;OUT-CHAN=*;TAG=ISCHEDULE;CONVERT  YES,CHANNEL=ischedule
    
  8. Save your changes and exit the editor.
    You are returned to the msconfig prompt, which changes to a pound-sign.
  9. Write the configuration and remain in msconfig interactive mode.
  10. Edit the filters block to specify messages to be processed by iSchedule.

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

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

  12. Write the configuration and exit the msconfig interactive mode.
  13. If you are using a compiled configuration, recompile the configuration.
  14. Restart Messaging Server.
  15. 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.
  2. Check the email notifications configuration.
  3. Check the whitelist configuration for the iSchedule port.
    The service.dav.ischedulewhitelist configuration parameter prevents denial of service attacks on the iSchedule port. See Enabling the iSchedule Channel to Handle iMIP Messages for more information.
  4. If necessary, restart GlassFish Server.
    For example:

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:

To Modify the iSchedule Service URL

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

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 msg-svr-base/config/imta.cnf file:
      ischedule
      ischedule-daemon
      
    2. Add the following lines to the msg-svr-base/config/job_controller.cnf file:
      [CHANNEL=ischedule]
      master_command=IMTA_BIN:ischedule
      
  2. Configure CONVERSION mapping by adding the following lines to the msg-svr-base/config/mappings file:
    CONVERSION
    
      IN-CHAN=ischedule;OUT-CHAN=*;TAG=*;CONVERT  NO
      IN-CHAN=*;OUT-CHAN=*;TAG=ISCHEDULE;CONVERT  YES,CHANNEL=ischedule
    
  3. Enable or disable iMIP message processing.
    To enable or disable iMIP message processing, create a channel options file, msg-svr-base/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:
    ischedule-url=http://<host>.<domain>:<port>/<path>
    
  5. 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";
    }
    
  6. If you are using a compiled configuration, recompile the configuration.
  7. Restart Messaging Server.
  8. 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 msg-svr-base/log/ischedule_master.log.*
  • Use the msg-svr-base/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.
Labels:
messagingserver messagingserver Delete
unifiedconfig unifiedconfig Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Mar 12, 2014

    Don't forget to set INCLUDE_CONVERSIONTAG=2 in option.dat. 

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.