9 Synchronizing the Calendar Domain

This chapter describes how BDSS synchronizes Calendar domain records.

This chapter includes the following topics:

Overview of Calendar Synchronization Support
Transforming Custom Calendar Fields
Supporting Calendar Synchronization in Hub Schema
Creating Custom Calendar Fields
Data Side Effects Caused by Synchronizing ICAL Fields

9.1 Overview of Calendar Synchronization Support

With the exception of the record data format- and attendee-related processing, the Calendar domain synchronizes in the same way as any other domains. However, the record data format for the Calendar domain is different than the record data format of other domains. That is, the other domains represent a domain record as a XML document where each field of the record is represented as a node in the XML document. For the Hub Calendar domain, a record is still a XML document, but instead of each field being a separate node in the document, there is a single node whose value is a iCalendar (ICAL) message (see RFC 2445: Internet Calendaring and Scheduling Core Object Specification, located at http://www.ietf.org/rfc/rfc2445.txt). The embedded ICalendar message contains the individual field names and values.

Note:

While ICAL is the widely accepted standard for exchanging calendar data, it is not defined in terms of XML and, to date, there are no standards that map ICAL-to-XML (see the IETF draft for XCAL at http://www.ietf.org/old/2009/proceedings/02mar/I-D/draft-ietf-calsch-many-xcal-01.txt).

9.1.1 Transforming Calendar Records

The Hub Calendar domain has only one field, ICalBody. The value for ICalBody is VCALENDAR content that conforms to RFC 2445. The Hub-to-PIM and PIM-to-Hub XSL files map this field.

Example 9-1 Hub XML

<?xml version="1.0" encoding="windows-1252" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://xmlns.oracle.com/bdss/hub/CalendarDomain"
targetNamespace="http://xmlns.oracle.com/bdss/hub/CalendarDomain"
elementFormDefault="qualified">
<xsd:element name="HubCalendarDomain">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="ICalBody" type="xsd:string" minOccurs="1"
maxOccurs="1" nillable="false"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

Note:

This document refers to an XML document containing a field whose value is an ICAL message as Embedded-ICAL.

As with all other domains, it is a connector implementation detail regarding what the XSL transformation produces when translating between the Hub and PIM XML forms if the transformation satisfies the two XSDs.

When transforming a Hub XML record to PIM XML record, connectors perform a Embedded-ICAL-to-XML or a Embedded-ICAL-to-Embedded-ICAL transformation. Similarly, when transforming a PIM XML record to Hub XML record, connectors most likely perform an XML-to-Embedded-ICAL or an Embedded-ICAL-to-Embedded-ICAL transformation. For example, when transforming XML from Hub to PIM format, one connector's XSL implementation may transform the Hub ICalBody field to the XML-equivalent form of ICAL while another connector may keep the ICalBody as an ICAL message. In both cases, the resulting PIM XML must be parsed and converted to a form usable by the PIM API when creating or updating a record in the targeted PIM. For connectors that transform the Hub ICalBody field to the XML-equivalent form of ICAL, the PIM API conversion routines obtain the ICAL from the transformed XML, parse the ICAL, and build PIM API constructs. For connectors that retain the ICalBody as an ICAL message, the PIM API conversion parses the ICAL-like XML and build the PIM API constructs.

9.2 Transforming Custom Calendar Fields

It is a connector implementation detail regarding how to perform field mapping customization, or if the connector implementation even allows customization. As described in Chapter 8, "Mapping Connector Fields to Hub Fields," connectors use XSD and XSLT to translate between Hub and PIM XML representations of a record. This is also true for the Calendar domain.

Because the calendar data flows through the system as an XML document with Embedded-ICAL, customizing field mappings between the Hub and PIM Calendar pose mappings that are more complicated than those described in Chapter 8, "Mapping Connector Fields to Hub Fields").

If a connectors' XSLT can transform ICAL-to-XML to XML-to-ICAL, then you can modify the XSL to customize the field mapping. This XSLT field mapping may be more complex than other domain XSLTs, however.

9.2.1 Transformations Through Secondary Translation

If a connectors' XSLT does not transform Embedded-ICAL-to-XML or XML-to-Embedded-ICAL, a connector implementation might provide a mapping customization capability by defining a separate set of PIM XSD and XSLT files that represent a template of a PIM calendar record (called a template in this document because it represents a calendar record containing a subset of fields but no recurrence properties). One XSD could contain a subset of the ICAL field names (that is, the fields of a single VEVENT and perhaps not all fields are listed in the XSD) that would be mappable. The other XSD would contain the PIM field names. As the connector parses and processes a given VEVENT form the ICAL message provided by the Hub, it can build a XML message for the VEVENT using the ICAL data and then use the XSL to transform the data and thereby get the ability to customize the mappings. The connector can then perform the PIM API translation using the resulting XML. This document refers to this method as the secondary-translation method.

Figure 9-1 is a graphical representation of the XSD and XSLT. As the connector processes an ICAL VEVENT, it builds an XML message conforming to exchangevirtualcalendar.xsd. It would then use the XSL to transform the XML to one that conforms to the exchange2007calendar.xsd. The customization depicted in Figure 9-1 is that the LOCATION is not mapped for synchronization.

Figure 9-1 Customized Field Mapping

9.2.1.1 Enabling Custom Fields for the Exchange 2007 Connector

You can add custom fields to a set of XSDs that are not exposed to the Hub using the secondary translation method. To enable a connector to synchronize with the Hub, you must create the following XSD files:

An XSD file that defines the field definitions for a connector
An XSD file that defines the ICAL counterparts of the field definitions
An XSLT file that transforms the connector's field definitions into ICAL definitions
An XSLT file that transforms the ICAL field definitions into the connector's definitions

These files are considered secondary files because they are never exposed to the Hub. For the Exchange 2007 connector, you can enable the synchronization of custom calendar fields by updating the secondary translation XSD and XSLT files. For more information, see Appendix E, " Custom Field XSLTs and XSDs."

9.2.2 Translations Through Java-Based Connectors

Java-based connectors that leverage the BDSS Generic Connector components could use the Transformer API to perform this transformation. This translation is transparent to the Hub and the BDSS Generic Connector HubTransport component.

Note:

The advantages to synchronization using the secondary translation method include:

A simpler XSLT to maintain. The XSLT would be similar to that of other domains.
You do not have to know the specifics of ICAL
Customizing field mappings is simpler

9.3 Supporting Calendar Synchronization in Hub Schema

Synchronization support in the Hub schema is restricted to the VEVENT, VTIMEZONE, VALARM calendar components.

Note:

In Oracle Fusion Middleware 11g release 1, BDSS does not support calendar synchronization for the VTODO, VJOURNAL, and VFREEBUSY components.

The Hub also requires the following:

The METHOD property must always be REQUEST.
A single ICAL message must represent a PIM calendar record. If the calendar record contains a recurrence pattern that has exceptions, the ICAL message must contain multiple VEVENT components, such that the first VEVENT component of the ICAL message is the master record of the pattern and each subsequent VEVENT component represents an exception.
All ICAL messages that describe a meeting must have the same meeting ID. Identical meetings may present a problem on extraction if records from different system key fields match each other. If they match, then the records have different meeting IDs. When the Hub matches the records based on the configured key fields, it treats the match as a Create/Create Conflict and pushes an update to the loosing connector. The losing connector then performs an update operation to ensure that its record data matches the winning connectors' record.

Updating the MeetingId in the target system may present problems to the calendaring system. Connectors should be careful when changing the MeetingId. For example, Exchange uses the MeetingId to correlate meeting update and meeting invitation e-mails across all attendees of the meeting. If the Exchange connector modifies the MeetingId, it breaks the Exchange normal meeting processing and the e-mails would no longer function the way they should (that is, when attendee reads a meeting invitation and accepts it, it creates a calendar record. When an attendee reads a meeting update e-mail, the corresponding calendar record is updated, and so on).

9.4 Creating Custom Calendar Fields

As described in RFC 2445, Section 4.8.8.1: Non-Standard Properties, the ICAL standard allows for custom fields in the form of properties whose name begins with X- . For example, X-ORACLE-BDSS-EXCHANGE-F1 and X-ORACLE-BDSS-BPEL-F1 are examples of valid custom field names. Further, custom fields and custom field values may differ for each exception to a recurring calendar record. To enable successful synchronization of the Calendar domain across all of the connectors that synchronize the Calendar domain, developers must implement connectors to allow custom fields through secondary translation or by including ICAL and custom fields in the Hub calendar definition.

If a connector opts to use the secondary-translation mechanism, you can define the custom fields in the PIM-specific XSDs and define the mappings. The custom fields remain in the ICAL message provided by the Hub.

If a connector opts not to use the secondary-translation option, you can define a Hub data type in the Hub type library XSD, and define the custom Hub and PIM fields to be of this type in the respective XSDs. You can then map them in the PIM-To-Hub and Hub-To-PIM XSLT files. The connectors would place custom field data outside of the ICalBody. The data type definition must allow multiple values so that connectors can specify different custom properties and values for each exception (perhaps something similar to the HubTokens data type). With this approach, there is a danger of data loss because it would be possible for a ICAL custom field in a source connector to be mapped to a regular ICAL field on the target connector. For more information, see Section 9.5.2, "Mapping a Custom ICAL Field to a Regular ICAL Field."

9.5 Data Side Effects Caused by Synchronizing ICAL Fields

Data loss can occur because of:

Failed Synchronization of Any ICAL Field
Mapping a Custom ICAL Field to a Regular ICAL Field

9.5.1 Failed Synchronization of Any ICAL Field

As mentioned in Section 9.2, "Transforming Custom Calendar Fields," there is the danger of data loss if any ICAL field is not synchronized. Therefore, connectors should attempt to synchronize every ICAL field using hidden custom fields if the target calendar system does not support a given field.

If the connectors' PIM Server does not support hidden custom fields, a connector implementation must devise a method to persist and retrieve the field data. Data loss can occur even with this approach. In the case of an XSL that converts Embedded-ICAL to XML, if the XSL omits a ICAL field then data loss can occur because the target connector does not write a value to the field. If the connector uses the secondary-translation approach, the same problem occurs if a mapping of a ICAL field is not made. In both cases, this can be remedied by ensuring each ICAL field is mapped. A connector may appear as though a field is not synchronizing if it synchronizes the field to a custom PIM field that the client applications do not display by default. If the connectors' system does not support custom hidden fields, then the connector must devise a method to persist the field data so it can be provided back to the Hub during extractions.

If a connector cannot translate Embedded-ICAL to XML, or opts not to do the secondary-translation method, it may not support field mapping customization and rely on a natural map of ICAL field names to PIM field names. In this case, there would be no support for field definition or mapping customizations.

9.5.2 Mapping a Custom ICAL Field to a Regular ICAL Field

As noted in Section 9.4, "Creating Custom Calendar Fields," a connector that places field data outside of the ICalBody may result in an ICAL custom field in a source connector to be mapped to a regular ICAL field on the target connector. For example, suppose the BPEL calendar has a field called HTTP Link that, when clicked, navigates the BPEL user to a page in the BPEL application that provides information associated with the calendar record. Further, assume that the administrator wants to synchronize this field to a field in Exchange. Since there is no ICAL field that can represent this field, define a custom ICAL field, such as X-ORACLE-BDSS-BPEL-HTTP-LINK. You then modify the Hub XSD to have a ICAL X- field, such as X-ORACLE-BDSS-HUB-HTTP-LINK, and then map the two fields in the Hub-To-PIM and PIM-To-Hub XSLs used by the BPEL Task Connector. To synchronize the field to Exchange, define an Exchange custom ICAL field, such as ORACLE-BDSS-EXCHANGE-HTTP-LINK and map it to the ORACLE-BDSS-HUB-HTTP-LINK field in the Hub-to-PIM and PIM-to-Hub XSL used by the Exchange connector.

When defining the Exchange custom field in the Exchange XSD, you can define it as an extended field or an unindexed field. Writing the HTTP Link to the Location field on the Exchange calendar, define the field as the Exchange unindexed field Location. Because this unindexed field is naturally mapped to the ICAL LOCATION field, the connector uses the ORACLE-BDSS-EXCHANGE-HTTP-LINK value instead of the ICAL LOCATION value to update the Location field, the BPEL Task Connector overwrites the field during subsequent synchronization sessions to which it naturally maps the ICAL LOCATION field with the link if the change comes from Exchange. If the connector uses the ICAL LOCATION field and ignores the ORACLE-BDSS-EXCHANGE-HTTP-LINK value to update the Location field, then a subsequent session results in the BPEL Task Connector deleting the HTTP Link field value if the change originates from Exchange.

If you defined the field as an Extended Field that specifies a custom field (that is, it would remain hidden unless you define an Outlook custom form that would expose the field in the Outlook UI), then this form of data loss would not occur.

Note:

In this example, the BPEL Task Connector would not hard-code this customization by specifying the HTTP Link value as the LOCATION field value when it builds the ICAL that is sent to the Hub.