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.
By sending an an iCalendar format file to the Trumba server through an HTTP PUT operation, you can modify existing events without duplicating them or altering other event data. Learn more.
Note For more details about the iCalendar file format, refer to the RFC2445 and RFC2446 specifications.
Basic iCal file that can be uploaded into Trumba Connect
Below is a minimal sample iCal file that can be uploaded to Trumba Connect.
SUMMARY:Happy New Year!
The UID is required in all cases. This allows for existing event data to be modified. It must be unique for new events.
By default, event metadata such as timezone is inherited from the target Trumba calendar. Timezone can optionally be specified at the event level using the appropriate iCal syntax (e.g DTSTART;TZID).
Standard and required iCal fields used by Trumba Connect
The iCal file you publish to Trumba Connect, must contain certain fields and can optionally contain other fields. The table below summarizes how Trumba Connect's event form fields map to the field definitions in the iCal file.
|Trumba Event Form||ICS File Field|
* Denotes required field.
Using Trumba Connect custom fields in iCal files.
You can import iCal files containing custom fields defined in Trumba Connect. Numeric identifiers are used for all event templates, custom fields and many built-in fields. This will ensure that values are imported into the correct fields even if the names of the fields change. This requires you to know the numeric identifiers of the fields you want to import from the iCal file. To get all of the numeric identifiers you need, you must perform sample exports of your existing data in the Trumba calendar.
Custom field import
Here are the steps needed to specify custom field values in events to be imported into Trumba Connect.
- Identify an existing calendar that contains all Trumba Connect event templates, images, and custom fields that are to be available for import. If no such calendar exists, create one for this purpose.
- Create events, one for each event template you want to eventually import. When you're finished, you should have events that specify values for all custom fields, event templates, and images.
- Export the calendar as an iCal (ICS) file. Inspect the resulting exported file. Construct a map of the Trumba Connect custom field ID numbers to the custom field values shown in the file. For example, the following line might appear in the exported iCal file.
To import the above custom field "Comments", you must specify ID=10899 in the iCal import file.
The iCal file being imported requires only the ID and value. The TYPE and NAME attributes are ignored. Hence, the import of the "Comments" custom field could look like this;
or be simplified as shown below.
X-TRUMBA-CUSTOMFIELD;ID=10899:My Comments Amended
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.
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
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.
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 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 ICS (iCalendar) 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?