xCal and iCalendar Conversion Service (com.ibi.agents.XDXCalAgent)

Topics:

Syntax:

com.ibi.agents.XDXCalAgent

iIT Service Object:

format: Converts between iCalendar and xCal

Description:

This service converts iCalendar to xCal and vice-versa. iCalendar is a format specification for the exchange of calendaring and scheduling data. A common example is an email message containing an iCalendar attachment for a meeting request. iCalendar is defined in the RFC 5545 specification. xCal is the XML format for iCalendar, and is defined in the RFC 6321 specification.

xCal is designed to support the round trip from iCalendar to xCal back into iCalendar without losing semantic information. This allows the application query to update the information in the more convenient XML format, with no loss of information.

Parameters:

Parameter

Description

Operation

Determines which of the following conversions should be performed:

  • iCalendar to xCal
  • xCal to iCalendar

Edges:

The following table lists the available line edges for the xCal and iCalendar Conversion Service (com.ibi.agents.XDXCalAgent).

Line Edge

Description

OnError

Error

OnSuccess

Success

OnFailure

Failure

OnCustom

  • OnError
  • OnSuccess
  • OnFailure
  • fail_parse: an iFL expression could not be evaluated.
  • fail_operation: the operation could not be completed successfully.

This service requires iCalendar input to be stored as bytes or lines, directly within the input document. As a result, you may require the execution of the Attachment to Document service (com.ibi.agents.XDAttachmentToDocAgent) or the SMIME Unpacker service (com.ibi.agents.XDSMIMEUnpackerAgent) on your input.

xCal input must be stored as parsed XML format within the input document. This service stores iCalendar output as lines, and xCal output as parsed XML within the output document.

An iCalendar stream is composed of one or more VCALENDAR components. In xCal, this is represented by an <icalendar> element containing one or more <vcalendar> elements. iCalendar is mostly case-insensitive, but xCal requires lower-case formatting. For example:

<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vcalendar>

  </vcalendar>
</icalendar>

Each component consists of optional properties and optional sub-components. A sub-component has the same structure as a component. In xCal, a component maps to an element of the same name. When present, the properties are grouped within the <properties> element. Similarly, when present, the sub-components are grouped within the <components> element. The <properties> and <components> elements are omitted when empty. For example:

<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vcalendar>
    <properties>

    </properties>
    <components>

    </components>
  </vcalendar>
</icalendar>

A property has optional parameters and a value. In xCal, a property maps to an element of the same name. When present, the parameters are grouped within the <parameters> element. The <parameters> element is omitted when empty.

A parameter is a name-value pair. A parameter is converted to an element of the same name.

In general, a property value becomes an element that is named based on the value type, with the textual value as contents. This approach is used because many properties accept values of multiple types. For some specific structured types, the value is converted to named sub-elements instead. A parameter value is treated similarly, but it is always textual.

The following is an example of the tzid parameter within the dtstart property.

<properties>
  <dtstart>
    <parameters>
      <tzid><text>US/Eastern</text></tzid>
    </parameters>
    <date-time>2006-01-02T12:00:00</date-time>
  </dtstart>
</properties>

iCalendar defines a folding algorithm to limit the line length to under 75 octets. It also defines an escape mechanism for some characters. This service automatically unfolds and unescapes when parsing iCalendar input. Conversely, this service automatically folds and escapes when generating iCalendar output.

Example 1

This example shows how a calendar request can be converted to xCal. These instructions describe how to configure a process flow to handle iCalendar attachments in an email message.

Richard Smith is organizing a meeting with John Doe and Jane Roe. It is scheduled for March 4, 2014 and runs weekly for another 5 weeks. He used a calendar application to send this calendar request to the attendees. The multipart/alternative message, is composed of two parts:

  • A text or plain description.
  • A text or calendar part.
From: "Smith, Richard" <Richard_Smith@ibi.com>
To: "Doe, John" <John_Doe@ibi.com>,
	"Roe, Jane" <Jane_Roe@ibi.com>
Date: Mon, 3 Mar 2014 16:59:17 -0500
Subject: group meeting
Content-Type: multipart/alternative;
	boundary="_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_"
MIME-Version: 1.0
Return-Path: Richard_Smith@ibi.com
--_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: base64
V2hlbjogT2NjdXJzIGV2ZXJ5IFR1ZXNkYXkgZnJvbSAxMDowMCBBTSB0byAxMTowMCBBTSBlZmZl
Y3RpdmUgMy80LzIwMTQgdW50aWwgNC8xLzIwMTQuIFRoZXJlIGFyZSA1IG1vcmUgb2NjdXJyZW5j
ZXMuIChHTVQtMDU6MDApIEVhc3Rlcm4gVGltZSAoVVMgJiBDYW5hZGEpDQpXaGVyZTogbGFyZ2Ug
Y29uZmVyZW5jZSByb29tDQoNCip+Kn4qfip+Kn4qfip+Kn4qfioNCg==
--_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_
Content-Type: text/calendar; charset="utf-8"; method=REQUEST
Content-Transfer-Encoding: base64
QkVHSU46VkNBTEVOREFSDQpNRVRIT0Q6UkVRVUVTVA0KUFJPRElEOk1pY3Jvc29mdCBFeGNoYW5n
ZSBTZXJ2ZXIgMjAwNw0KVkVSU0lPTjoyLjANCkJFR0lOOlZUSU1FWk9ORQ0KVFpJRDpFYXN0ZXJu
IFN0YW5kYXJkIFRpbWUNCkJFR0lOOlNUQU5EQVJEDQpEVFNUQVJUOjE2MDEwMTAxVDAyMDAwM
A0KVFpPRkZTRVRGUk9NOi0wNDAwDQpUWk9GRlNFVFRPOi0wNTAwDQpSUlVMRTpGUkVRPVlFQVJMWTtJ
TlRFUlZBTD0xO0JZREFZPTFTVTtCWU1PTlRIPTExDQpFTkQ6U1RBTkRBUkQNCkJFR0lOOkRBWUxJ
R0hUDQpEVFNUQVJUOjE2MDEwMTAxVDAyMDAwMA0KVFpPRkZTRVRGUk9NOi0wNTAwDQpUWk9GRlNF
VFRPOi0wNDAwDQpSUlVMRTpGUkVRPVlFQVJMWTtJTlRFUlZBTD0xO0JZREFZPTJTVTtCWU1PTlRI
PTMNCkVORDpEQVlMSUdIVA0KRU5EOlZUSU1FWk9ORQ0KQkVHSU46VkVWRU5UDQpPUkdBTklaRVI7
Q049IlNtaXRoLCBSaWNoYXJkIjpNQUlMVE86UmljaGFyZF9TbWl0aEBpYmkuY29tDQpBVFRFTkRF
RTtST0xFPVJFUS1QQVJUSUNJUEFOVDtQQVJUU1RBVD1ORUVEUy1BQ1RJT047UlNWUD1UUlVFO0NO
PSJEb2UsIEpvaG4NCiAiOk1BSUxUTzpKb2huX0RvZUBpYmkuY29tDQpBVFRFTkRFRTtST0xFPVJF
US1QQVJUSUNJUEFOVDtQQVJUU1RBVD1ORUVEUy1BQ1RJT047UlNWUD1UUlVFO0NOPSJSb2UsIEph
bmUNCiAiOk1BSUxUTzpKYW5lX1JvZUBpYmkuY29tDQpERVNDUklQVElPTjtMQU5HVUFHRT1lbi1V
UzpXaGVuOiBPY2N1cnMgZXZlcnkgVHVlc2RheSBmcm9tIDEwOjAwIEFNIHRvIDExOjANCiAwIEFN
IGVmZmVjdGl2ZSAzLzQvMjAxNCB1bnRpbCA0LzEvMjAxNC4gVGhlcmUgYXJlIDUgbW9yZSBvY2N1
cnJlbmNlcy4gKEdNVA0KIC0wNTowMCkgRWFzdGVybiBUaW1lIChVUyAmIENhbmFkYSlcbldoZXJl
OiBsYXJnZSBjb25mZXJlbmNlIHJvb21cblxuKn4qfip+DQogKn4qfip+Kn4qfip+KlxuDQpSUlVM
RTpGUkVRPVdFRUtMWTtDT1VOVD01O0lOVEVSVkFMPTE7QllEQVk9VFU7V0tTVD1TVQ0KU1VNTUFS
WTtMQU5HVUFHRT1lbi1VUzpncm91cCBtZWV0aW5nDQpEVFNUQVJUO1RaSUQ9RWFzdGVybiBTdGFu
ZGFyZCBUaW1lOjIwMTQwMzA0VDEwMDAwMA0KRFRFTkQ7VFpJRD1FYXN0ZXJuIFN0YW5kYXJkIFRp
bWU6MjAxNDAzMDRUMTEwMDAwDQpVSUQ6MDQwMDAwMDA4MjAwRTAwMDc0QzVCNzEwMUE4MkUwMDgw
MDAwMDAwMDM2RDU1NkQyMkIzN0NGMDEwMDAwMDAwMDAwMDAwMDANCiAwMTAwMDAwMDAyMEFGO
DMwMjVEMjA1RDQ4QjY3OTNCMzhBNzFGQ0JCQg0KQ0xBU1M6UFVCTElDDQpQUklPUklUWTo1DQpEVFNU
QU1QOjIwMTQwMzAzVDIxNTkxNloNClRSQU5TUDpPUEFRVUUNClNUQVRVUzpDT05GSVJNRUQNClNF
UVVFTkNFOjANCkxPQ0FUSU9OO0xBTkdVQUdFPWVuLVVTOmxhcmdlIGNvbmZlcmVuY2Ugcm9vbQ0K
WC1NSUNST1NPRlQtQ0RPLUFQUFQtU0VRVUVOQ0U6MA0KWC1NSUNST1NPRlQtQ0RPLU9XTkVSQVBQ
VElEOjIxMTIwMzUzODINClgtTUlDUk9TT0ZULUNETy1CVVNZU1RBVFVTOlRFTlRBVElWRQ0KWC1N
SUNST1NPRlQtQ0RPLUlOVEVOREVEU1RBVFVTOkJVU1kNClgtTUlDUk9TT0ZULUNETy1BTExEQVlF
VkVOVDpGQUxTRQ0KWC1NSUNST1NPRlQtQ0RPLUlNUE9SVEFOQ0U6MQ0KWC1NSUNST1NPRlQtQ0RP
LUlOU1RUWVBFOjENCkJFR0lOOlZBTEFSTQ0KQUNUSU9OOkRJU1BMQVkNCkRFU0NSSVBUSU9OOlJF
TUlOREVSDQpUUklHR0VSO1JFTEFURUQ9U1RBUlQ6LVBUMTVNDQpFTkQ6VkFMQVJNDQpFTkQ6VkVW
RU5UDQpFTkQ6VkNBTEVOREFSDQo=
--_002_9892EC6224DBC54598164D1F77721D757F4CE39BE7IBIUSMBSBibic_--

The email listener (com.ibi.edaqm.XDPop3Master) reads this email message and stores the main body part in the document. The base64 data is automatically decoded. The listener is configured to keep the document in flat format because it is not XML. The calendar part is not shown in this example because it is stored as an attachment in the document.

When: Occurs every Tuesday from 10:00 AM to 11:00 AM effective 3/4/2014 until 4/1/2014. There are 5 more occurrences. (GMT-05:00) Eastern Time (US & Canada)
Where: large conference room
*~*~*~*~*~*~*~*~*~*

The document attachments are processed one at a time with the help of the Attachment Iterator (com.ibi.agents.XDIterAttachments). The following table lists the parameter values that are used.

Parameter

Value

Start Index

0

Header Namespace

attns

Keep Document Flat

true

If the application knows there will always be one attachment and it will always be an iCalendar attachment, then it can extract it with the Attachment to Document service (com.ibi.agents.XDAttachmentToDocAgent) instead.

The base64 data is automatically decoded. For the first and only attachment, the result is an iCalendar request stored as bytes in the current document.

BEGIN:VCALENDAR
METHOD:REQUEST
PRODID:Microsoft Exchange Server 2007
VERSION:2.0
BEGIN:VTIMEZONE
TZID:Eastern Standard Time
BEGIN:STANDARD
DTSTART:16010101T020000
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=1SU;BYMONTH=11
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:16010101T020000
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
RRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=2SU;BYMONTH=3
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VEVENT
ORGANIZER;CN="Smith, Richard":MAILTO:Richard_Smith@ibi.com
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN="Doe, John
":MAILTO:John_Doe@ibi.com
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN="Roe, Jane
 ":MAILTO:Jane_Roe@ibi.com
DESCRIPTION;LANGUAGE=en-US:When: Occurs every Tuesday from 10:00 AM to 11:0
 0 AM effective 3/4/2014 until 4/1/2014. There are 5 more occurrences. (GMT
 -05:00) Eastern Time (US & Canada)\nWhere: large conference room\n\n*~*~*~
 *~*~*~*~*~*~*\n
RRULE:FREQ=WEEKLY;COUNT=5;INTERVAL=1;BYDAY=TU;WKST=SU
SUMMARY;LANGUAGE=en-US:group meeting
DTSTART;TZID=Eastern Standard Time:20140304T100000
DTEND;TZID=Eastern Standard Time:20140304T110000
UID:040000008200E00074C5B7101A82E0080000000036D556D22B37CF01000000000000000
 01000000020AF83025D205D48B6793B38A71FCBBB
CLASS:PUBLIC
PRIORITY:5
DTSTAMP:20140303T215916Z
TRANSP:OPAQUE
STATUS:CONFIRMED
SEQUENCE:0
LOCATION;LANGUAGE=en-US:large conference room X-MICROSOFT-CDO-APPT-SEQUENCE:0
X-MICROSOFT-CDO-OWNERAPPTID:2112035382
X-MICROSOFT-CDO-BUSYSTATUS:TENTATIVE
X-MICROSOFT-CDO-INTENDEDSTATUS:BUSY
X-MICROSOFT-CDO-ALLDAYEVENT:FALSE
X-MICROSOFT-CDO-IMPORTANCE:1
X-MICROSOFT-CDO-INSTTYPE:1
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:REMINDER
TRIGGER;RELATED=START:-PT15M
END:VALARM
END:VEVENT
END:VCALENDAR

The xCal and iCalendar service can convert this data into XML format for easier processing.

Since the attachment can be any type, a Switch object is required to check the Content-Type. The expression defined for the Switch object can be:

_lcase(_token(_sreg("attns.Content-Type"), ";"))

Notice the register namespace attns is the Header Namespace configured on the Attachment Iterator. The _token() function is just a convenient way to extract the MIME type without any parameters. The _lcase() function is needed to convert to lowercase format because MIME types are case-insensitive. For example, the following expression returns text/calendar for this Content-Type:

Content-Type: text/calendar; charset="utf-8"; method=REQUEST

The value of the Switch expression becomes the outgoing edge name.The Switch object is bound to the xCal and iCalendar service by an OnCustom edge called text/calendar.The OnDefault edge of the Switch object should also be bound to other services to handle attachments of other types.

The Operation parameter of the xCal and iCalendar service is set to iCalendar to xCal.The output is a parsed XML tree in the current document (indented for display purposes only):

<?xml version="1.0" encoding="ISO-8859-1" ?>
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vcalendar>
    <properties>
      <method>
        <text>REQUEST</text>
      </method>
      <prodid>
        <text>Microsoft Exchange Server 2007</text>
      </prodid>
      <version>
        <text>2.0</text>
      </version>
    </properties>
    <components>
      <vtimezone>
        <properties>
          <tzid>
            <text>Eastern Standard Time</text>
          </tzid>
        </properties>
        <components>
          <standard>
            <properties>
              <dtstart>
                <date-time>1601-01-01T02:00:00</date-time>
              </dtstart>
              <tzoffsetfrom>
                <utc-offset>-04:00</utc-offset>
              </tzoffsetfrom>
              <tzoffsetto>
                <utc-offset>-05:00</utc-offset>
              </tzoffsetto>
              <rrule>
                <recur>
                  <freq>YEARLY</freq>
                  <interval>1</interval>
                  <byday>1SU</byday>
                  <bymonth>11</bymonth>
                </recur>
              </rrule>
            </properties>
          </standard>
          <daylight>
            <properties>
              <dtstart>
                <date-time>1601-01-01T02:00:00</date-time>
              </dtstart>
              <tzoffsetfrom>
                <utc-offset>-05:00</utc-offset>
              </tzoffsetfrom>
              <tzoffsetto>
                <utc-offset>-04:00</utc-offset>
              </tzoffsetto>
              <rrule>
                <recur>
                  <freq>YEARLY</freq>
                  <interval>1</interval>
                  <byday>2SU</byday>
                  <bymonth>3</bymonth>
                </recur>
              </rrule>
            </properties>
          </daylight>
        </components>
      </vtimezone>
      <vevent>
        <properties>
          <organizer>
            <parameters>
              <cn>
                <text>Smith, Richard</text>
              </cn>
            </parameters>
            <cal-address>MAILTO:Richard_Smith@ibi.com</cal-address>
          </organizer>
          <attendee>
            <parameters>
              <role>
                <text>REQ-PARTICIPANT</text>
              </role>
              <partstat>
                <text>NEEDS-ACTION</text>
              </partstat>
              <rsvp>
                <boolean>true</boolean>
              </rsvp>
              <cn>
                <text>Doe, John</text>
              </cn>
            </parameters>
<cal-address>MAILTO:John_Doe@ibi.com</cal-address>
          </attendee>
          <attendee>
            <parameters>
              <role>
                <text>REQ-PARTICIPANT</text>
              </role>
              <partstat>
                <text>NEEDS-ACTION</text>
              </partstat>
              <rsvp>
                <boolean>true</boolean>
              </rsvp>
              <cn>
                <text>Roe, Jane</text>
              </cn>
            </parameters>
<cal-address>MAILTO:Jane_Roe@ibi.com</cal-address>
          </attendee>
          <description>
            <parameters>
              <language>
                <text>en-US</text>
              </language>
            </parameters>
            <text>When: Occurs every Tuesday from 10:00 AM to 11:00 AM effective 3/4/2014 until 4/1/2014. There are 5 more occurrences. (GMT-05:00) Eastern Time (US &amp; Canada)
Where: large conference room
*~*~*~*~*~*~*~*~*~*        </text>
          </description>
          <rrule>
            <recur>
              <freq>WEEKLY</freq>
              <count>5</count>
              <interval>1</interval>
              <byday>TU</byday>
              <wkst>SU</wkst>
            </recur>
          </rrule>
          <summary>
            <parameters>
              <language>
                <text>en-US</text>
              </language>
            </parameters>
            <text>group meeting</text>
          </summary>
<dtstart>
            <parameters>
              <tzid>
                <text>Eastern Standard Time</text>
              </tzid>
            </parameters>
            <date-time>2014-03-04T10:00:00</date-time>
          </dtstart>
          <dtend>
            <parameters>
              <tzid>
                <text>Eastern Standard Time</text>
              </tzid>
            </parameters>
            <date-time>2014-03-04T11:00:00</date-time>
          </dtend>
          <uid>
            <text>040000008200E00074C5B7101A82E0080000000036D556D22B37CF0100000000
000000001000000020AF83025D205D48B6793B38A71FCBBB</text>
          </uid>
          <class>
            <text>PUBLIC</text>
          </class>
          <priority>
            <integer>5</integer>
          </priority>
          <dtstamp>
            <date-time>2014-03-03T21:59:16Z</date-time>
          </dtstamp>
          <transp>
            <text>OPAQUE</text>
          </transp>
          <status>
            <text>CONFIRMED</text>
          </status>
          <sequence>
            <integer>0</integer>
          </sequence>
          <location>
            <parameters>
              <language>
                <text>en-US</text>
              </language>
            </parameters>
            <text>large conference room</text>
          </location>
<x-microsoft-cdo-appt-sequence>
            <unknown>0</unknown>
          </x-microsoft-cdo-appt-sequence>
          <x-microsoft-cdo-ownerapptid>
            <unknown>2112035382</unknown>
          </x-microsoft-cdo-ownerapptid>
          <x-microsoft-cdo-busystatus>
            <unknown>TENTATIVE</unknown>
          </x-microsoft-cdo-busystatus>
          <x-microsoft-cdo-intendedstatus>
            <unknown>BUSY</unknown>
          </x-microsoft-cdo-intendedstatus>
          <x-microsoft-cdo-alldayevent>
            <unknown>FALSE</unknown>
          </x-microsoft-cdo-alldayevent>
          <x-microsoft-cdo-importance>
            <unknown>1</unknown>
          </x-microsoft-cdo-importance>
          <x-microsoft-cdo-insttype>
            <unknown>1</unknown>
          </x-microsoft-cdo-insttype>
        </properties>
        <components>
          <valarm>
            <properties>
              <action>
                <text>DISPLAY</text>
              </action>
              <description>
                <text>REMINDER</text>
              </description>
              <trigger>
                <parameters>
                  <related>
                    <text>START</text>
                  </related>
                </parameters>
                <duration>-PT15M</duration>
              </trigger>
            </properties>
          </valarm>
        </components>
      </vevent>
    </components>
  </vcalendar>
</icalendar>

This document can be processed by more services (agents) according to the application requirements.

The various processing paths within the Attachment iterator loop must converge into a single Junction object. The loop edge points from the junction back to the iterator.

Example 2

This example explains how to read an iCalendar request from an email message stored in a file.

The email and HTTP listeners can automatically parse the multipart/alternative message because their underlying protocol requires the presence of headers. This step must also be added explicitly to the process flow of a File listener.

The File listener is configured to keep the document flat.

The first object of the process flow should be the S/MIME Unpacker service. This object can handle complex cryptographic messages, but also simple MIME messages like the multipart/alternative message in Example 1. The S/MIME KeyStore and S/MIME TrustStore providers are not used to parse simple MIME messages, but they must still be configured to satisfy the parameters that are required by the service. Any keystore provider is sufficient.

The Keep Message Flat parameter of the S/MIME Unpacker service must be set to false. This is required to parse the multipart message into the main body and its attachments. In the sample input message, the Content-Type of the main body is text/plain, therefore the service will not attempt to parse it as XML.

The remaining portions of the process flow can be configured as described in Example 1.