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