Prepare iCal files for import
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.
Basic iCal file for a single event
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.
SUMMARY:Happy New Year!
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.
Standard and required iCal fields used by Trumba Connect
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|
* Required field
Importing events with custom fields in iCal files
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 to import events with custom fields
- Export the events from their source location to an iCal (.ics) file, and identify any custom fields.
Where can I find tips for exporting and preparing files?
- In Trumba, create a custom field that corresponds to each custom field in the iCal file you're importing.
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.
- In the Trumba editing environment, add the new custom fields to the default event template or create a new template that contains the fields.
How do I modify or create event templates?
- Still in Trumba, select the calendar into which you want to import events, and then click Settings. Follow these instructions to assign the appropriate template to the calendar.
- Create a test event on the calendar, providing values for each of the custom fields.
- Export the calendar as an iCal (.ics) file, open the exported file in a text editor (such as Notepad or Wordpad), and then locate the custom fields.
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.
- If you're importing a single iCal file into Trumba:
- In a text editor, open the iCal file you're importing.
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:
COMMENTS: Actual value in the iCal file you're importing
With the following, based on the example in step 6:
X-TRUMBA-CUSTOMFIELD;NAME="Comments";ID=10899;TYPE=MultiLine:Actual value in the iCal file you're importing
- Repeat the previous step for each custom field in the file you're importing.
- When all custom field identifiers are updated, save the iCal file (in .ics format).
- Import the file into Trumba.
- If you're uploading iCal files programmatically, use your connector program to associate the event custom fields from your database with the custom fields you created in Trumba.
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.
Sample import files
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:
- To escape commas (,) and semicolons (;), precede them with a backslash(\).
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.
- To include a backslash (\) in a field's text, escape the backslash with another backslash.
For example, to include a backslash in Description field text, you type: Use the backslash (\\) as the escape character.
- To include an intentional formatted text line break, such as in the first sample's multiLine text field, type a backslash followed by the letter "n".
For example: This is line 1\nThis is line 2.
SUMMARY:Sample Event 1
LOCATION:1200 Fifth Ave\, Seattle WA 98101
DESCRIPTION:Event Notes: This event starts at 8:00 a.m. PT on Jan 1\, 2010.
X-TRUMBA-CUSTOMFIELD;NAME="Event Type";ID=21;TYPE=Number:Contains all Custom Field Types
X-TRUMBA-CUSTOMFIELD;NAME="my single line of text";ID=12295;TYPE=SingleLine:This is a single line of text
X-TRUMBA-CUSTOMFIELD;NAME="my multiple lines of text";ID=12296;TYPE=MultiLine:This is line 1\nThis is line 2
X-TRUMBA-CUSTOMFIELD;NAME="my list of choices";ID=12297;TYPE=CustomAsset:my choice 2
X-TRUMBA-CUSTOMFIELD;NAME="my yes or no";ID=12298;TYPE=Boolean:Yes
X-TRUMBA-CUSTOMFIELD;NAME="my web link";ID=12301;TYPE=Url:http://www.trumba.com/calendars/icstest
X-TRUMBA-CUSTOMFIELD;NAME="my email address";ID=12302;TYPE=Email:firstname.lastname@example.org
X-TRUMBA-CUSTOMFIELD;NAME="my phone number no ext";ID=12303;TYPE=PhoneUS:206-696-7200
X-TRUMBA-CUSTOMFIELD;NAME="my international phone number";ID=12304;TYPE=PhoneInt:+011-206-696-7200
SUMMARY:Sample Event 2 - Repeating
DESCRIPTION:Enjoy group cycling on stationery bikes designed for all lev
els. Instructor will guide you through a unique strength and cardiovascu
lar workout. A variety of methods will be used including visualization\,
interval training\, watts and distance as you cycle to music.
X-TRUMBA-CUSTOMFIELD;NAME="Event Template";ID=21;TYPE=Number:Group Exerc
X-TRUMBA-CUSTOMFIELD;NAME="Type of Exercise";ID=23893;TYPE=CustomAsset:I
X-TRUMBA-CUSTOMFIELD;NAME="Cost";ID=23895;TYPE=SingleLine:Free to member
s\, $15 for non members
Update events you already imported
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:
SUMMARY:Happy New Year!
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:
SUMMARY:Start the Year With a Bang!
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.
Tips for resolving import problems
- Become familiar with the overall iCal file structure. For example:
- Each iCal file must begin with the line
BEGIN:VCALENDAR and end with the line
- Each individual event described by the file begins with the line
BEGIN:VEVENT and ends with the line
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.
- It's not unusual for iCal files you export from other programs to contain their own X- fields (such as X-Microsoft). Such fields are not part of the iCalendar specification and Trumba ignores them during import.
For more information about iCal file structure, properties, and parameters, refer to RFC2445, the iCalendar specification.
- Try importing one event at a time. Start with the first event and work your way through the file.
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.
- In Trumba Connect, manually add to a calendar a few of the events you're trying to import. Among the events you're adding, it's a good idea to include some of the more complex ones, such as the repeating, multi-day, and ongoing events.
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.
How do I export events?