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.
For more details about the iCalendar file format, refer to the RFC2445 and RFC2446 specifications.
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 |
| Title | SUMMARY* |
| Start | DTSTART* |
| Duration | DURATION |
| End | DTEND |
| - | UID* |
| Repeats | RRULE |
| Description | DESCRIPTION |
In addition to standard event fields: Title, Location, Start Date, Start Time, Description, and Web Link, the events you're importing may include custom fields; for example: Audience, Category, or Event Created By.
To successfully import events with custom fields, Trumba must be able to match the custom fields in the iCal file you're importing with corresponding fields in Trumba, as described below.
Tip Alternatively, you may find it easier (especially for a one-time transfer) to import the events into Trumba without the custom fields, create the custom fields in the template associated with your calendar, and then add the values manually.
How do I create new custom fields?
For example, you might need a single-line-of-text field called Event Created By that contains a person's name or a list-of-choices field called Audience that contains a list of audience values, such as Seniors, Adults, Teens, and Children.
Each custom field is preceded by "X-TRUMBA-CUSTOMFIELD," such as the following:
Note If you're uploading iCal files programmatically, skip to step 8.
Ensure that every line representing a custom field in the iCal file you're importing uses the same exact code as its corresponding custom field in the file you exported from Trumba -- while retaining the actual value applied on the original event.
For example, you'd replace this row (for a custom field named, Comments) in the iCal file you're importing:
With the following, based on the example in step 6:
If your database contains a field called Comments, such as in step 6, in the connector program, you'd use code example described in step 7.
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.
I'd like to know more about copying images into Trumba servers.
The following URL points to an image stored on the Trumba servers.
How do I find the URL for 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 BEGIN:VEVENT and END:VEVENT lines).
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.
Can I delete events I imported previously?
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.
How do I delete events in Trumba?
How do I delete events using HTTP PUT?
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.
I'd like information about adding events to Trumba calendars.
BEGIN:VCALENDAR and end with the line END:VCALENDAR.BEGIN:VEVENT and ends with the line END:VEVENT.BEGIN:VCALENDAR and 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.
What's the difference between repeating, multi-day, and ongoing events?
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.