One of the event import file formats Trumba® supports is the iCalendar or iCal format. iCal files have an .ics extension. For example, an iCal file might be called myevents.ics.
You can import an iCal file directly into Trumba using the Import calendar events feature. Or, you can programmatically upload iCalendar format files to the Trumba server through an HTTP PUT operation.
This topic describes how to prepare iCal files for import regardless of which import approach you use.
Below is a minimal sample iCal file that can be imported to Trumba. It contains the three required fields (event title, start date, and unique ID) and creates an event titled Happy New Year that occurs on January 1, 2016.
Tip By default, time zone is inherited from the target Trumba calendar. Optionally, you can specify time zone at the event level using the appropriate iCal syntax: DTSTART;TZID.
Each imported event must have a unique ID (UID), which is how Trumba knows whether you're importing a new event or updating/deleting an existing event. Each calendar program may use a different UID format. When you import events from other calendars, your Trumba calendar retains the UIDs assigned by the original calendars.
You can also assign your own event UIDs. Read more about customized UID values.
The following table lists fields that are required in any iCal file you import. It also lists some commonly used optional fields. In addition, the table maps the iCal fields with corresponding fields in the Trumba add/edit event form.
|Trumba Event Form||ICS File Field|
The events you're importing may include custom fields. For example, in addition to the standard event fields, such as event name, start date, and start time, each event may include custom fields such as Audience, Category, or Event Created By.
In iCalendar files, each template and custom field is automatically assigned a numeric identifier. These numbers provide a unique way to identify templates and fields even when template and field names change.
To successfully import custom field data, the numeric identifier of each custom field in the iCal file you're importing must match the numeric identifier of a field that exists in Trumba.
To find the numeric identifiers of custom fields, follow the steps below to create a custom field in Trumba for each custom field you're importing. Add the fields to a template and assign the template to a calendar. Add an event to the calendar that includes the fields. Export the calendar that contains the event to an iCal file, and then examine the file, as described below, to find each custom field's numeric identifiers.
For example, you might create a single-line-of-text field called Event Created By that contains a person's name. Or, you might create a list-of-choices field called Audience that contains a list of audience values, such as Seniors, Adults, Teens, and Children.
Tip For the easiest import, make the custom field names in Trumba match the custom field names in the file you're importing.
For example, the following line might appear. The numeric identifier for a field called Comments is 10899.
The corresponding line in the iCal file you're importing might look like this (the numeric identifier is 5586).
In the iCal file you're importing, search for each occurrence of 5586 and replace it with 10899.
Based on the example described in step 7 above, if your database contains a field called Comments, in the connector program, associate that field with the numeric identifier 10899.
TipWhen custom fields are imported, Trumba requires only a numeric identifier and field value. Field type and name are ignored. In the iCal file you're importing, you can simplify the custom field lines so they look like this:
Images are specified by URL. This can be a URL to an external image on the internet or a URL to an image previously copied into the Trumba servers using the "manage images" feature.
The following URL points to an image stored on the Trumba servers.
Tip Images you import are added automatically to the calendar's images table. Learn more about images tables.
Below are two sample iCal files with custom fields. The files each contain a record for a single event (defined by the content between the
The files also include examples of a range of Trumba Connect custom field types and an event image. The NAME and TYPE attributes have been left in the file to provide contextual information.
The second sample file shows a record for a repeating group cycling event that started on Monday, September 10, 2012 and extends until Monday, December 15, 2014. The
RRULE property defines the repeating parameters.
Tip The sample files demonstrate the use of the backslash (\) escape character in the Location, Description, and MultiLine text fields:
For example, the Description field in the first file contains this text: This event starts at 8:00 a.m. PT on Jan 1\, 2010. The backslash guarantees that the comma following Jan 1 will be interpreted as a punctuation mark rather than a delimiter.
For example, to include a backslash in Description field text, you type: Use the backslash (\\) as the escape character.
For example: This is line 1\nThis is line 2.
After you import an iCal file into a Trumba calendar, you can update calendar events by importing a new iCal file that contains the updated fields.
To update events, create an iCal file that contains a record for each event that you want to update. The UID for each record must match the UID of an event you're updating. New information in any fields overwrites all of the old information.
For example, assume you originally imported this iCal file:
Then, the event title changes from "Happy New Year!" to "Start the Year With a Bang!" and the event needs updating. To update the event, import the following iCal file:
To delete an event you imported previously, you must either delete the event within Trumba or import an iCal file using an HTTP PUT operation.
The following example shows how an iCal file to delete a previously imported event should look. The file must include the CANCEL method and the UID in the file must match the UID of the event targeted for deletion.
Note that, because iCalendar files support a single VCALENDAR component per HTTP PUT operation, you can delete only a single event at a time.
Different programs output iCalendar files in different ways so it's not unusual for the iCal file you're trying to import to contain content that Trumba can't interpret.
By following these troubleshooting tips, you may be able to resolve the issues and import the file.
Tip Troubleshooting iCal files can be time consuming. If you can't quickly identify the blocking issues with a file you're trying to import, it may well be faster to add events manually in Trumba.
BEGIN:VCALENDARand end with the line
BEGIN:VEVENTand ends with the line
BEGIN:VCALENDARand the first occurrence of
BEGIN:VEVENT, most iCal files contain many lines of information related to time zone and standard and daylight savings time.
For more information about iCal file structure, properties, and parameters, refer to RFC2445, the iCalendar specification.
Going event-by-event, you may be able to isolate the event where the blocking problem originates.
Tip If your file includes a large number of events, you might want to try more of a divide-and-conquer approach. First, try importing half the file. If that fails, divide that section in half, and then try importing again. And so on.
When you finish adding the representative events, export them as an iCalendar (.ics) file. By comparing this exported file to your original, you may be able to determine which aspects of the original file are causing import errors.