Programmatically upload iCal files

If your organization's event data is stored and maintained in a database, you can create a connector program that periodically outputs that data to iCalendar (.ics) files. Then, through an HTTP PUT operation, you can programmatically upload the iCal files to your Trumba® calendars.

Note This topic assumes that you are familiar with programming languages, the http protocol, and how URL parameters work, and that you can easily find your way around HTML or other web programming code.

Overview

The iCalendar (.ics) import allows events to be created, updated, and deleted on a Trumba calendar by sending an iCalendar (RFC 2445) format file to the Trumba server through an HTTP PUT operation.

To update previously imported events, you can modify data in the original iCal file and reimport the file without altering unchanged event data or duplicating events.

Because each iCal file you send through an HTTP PUT operation can contain only a single VCALENDAR component, you must initiate a separate operation to delete events. Learn more.

Sending a file to the Trumba server requires HTTP BASIC authentication. The password is sent via clear text so we recommended (but do not require) that you perform the HTTP PUT operation via a secure https connection.

URL format

The HTTP PUT operation requires a URL. The example shown below represents the base URL. For the last portion of the URL, you must use the calendar's web name.

What is a calendar's web name?

Example URL for a calendar with the web name Foobar: https://www.trumba.com/service/Foobar.ics

The URL can also include the following query string parameter:

Parameter	Description	Allowed Values	Default Value
delta	The delta parameter controls whether the incoming feed is considered to be a full feed of data or only changes. When the value is false, the system imports the events in the feed and deletes any events that exist in Trumba but do not exist in the feed. When the value is true, the system will only delete events if an explicit CANCEL method is specified in the iCalendar file.	false true	false

Customized UID values

You can assign any event ID (UID) values you want to the events you're importing as long as each event UID added to a Trumba calendar or any of its sub-calendars is unique.

If you export calendar data from another program before importing it into Trumba, that program typically generates a unique ID for each event.

Although you can use the same UIDs for events in different calendars, we recommend that you implement a method that generates unique event IDs across all of your calendars.

For recommendations on UID formats, refer to RFC2445.

Deleting events

Delete an event from your Trumba calendar by using an HTTP PUT operation to upload an iCal file that specifies the CANCEL method and supplies only the event UID. For example:

BEGIN:VCALENDAR
METHOD:CANCEL
VERSION:2.0
PRODID:-//Company Name//Product//Language
BEGIN:VEVENT
UID:D70C88D5-E5A1-48EC-84A4-D05DBD5CD8F6-99
END:VEVENT
END:VCALENDAR

Response values

The response to the HTTP PUT operation contains an XML structure with a root "Response" node and one or more "ResponseMessage" nodes providing information and validation feedback. The following messages may be returned. Response messages may include the UID of the related event and a line number in the feed file where appropriate.

Response Codes and Descriptions

Code	Description	Level
1101	Event added	Information
1102	Event modified	Information
1103	Event deleted	Information
2101	Property not recognized	Warning
2102	Content line is invalid	Warning
2103	DateTime is invalid	Warning
2104	UTC offset is invalid	Warning
2105	Duration is invalid	Warning
3101	ICS file must contain a single VCALENDAR	Error

Examples

This section provides a simple code snippet that performs an HTTP PUT of a .ics file. For brevity, it intentionally does not use error handling logic that would be present in most programs.

The sample code will not work unmodified. Various parameters (in CAPS in this example), such as authentication information and the path to the .ics file, must be updated to reflect your account and published calendar name.

byte[] request; // request content as byte array
using (StreamReader sr = new StreamReader(@"YOUR_ICS_FILE.ics")) { request = new ASCIIEncoding().GetBytes(sr.ReadToEnd()); }
string UriStr = "https://www.trumba.com/service/YOUR_CALENDAR_WEBNAME.ics?delta=true";
CredentialCache MyCredentialCache = new CredentialCache();
NetworkCredential creds = new NetworkCredential("TRUMBA_ACCOUNT_EMAIL_ADDR", "TRUMBA_ACCOUNT_PASSWORD", "");
MyCredentialCache.Add(new Uri(UriStr), "Basic", creds);
HttpWebRequest Request = (HttpWebRequest) HttpWebRequest.Create(UriStr);
Request.Credentials = MyCredentialCache;
Request.Method = "PUT";
Request.ContentLength = request.Length;
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
Stream requestStream = Request.GetRequestStream();
requestStream.Write(request, 0, request.Length); // file sizes > 2048 bytes may need chunking
requestStream.Close();
WebResponse Response = Request.GetResponse();
Stream ResponseStream = Response.GetResponseStream();
StreamReader responseReader = new StreamReader(ResponseStream);
string responseString = responseReader.ReadToEnd();
Console.Write(responseString);
ResponseStream.Close();
Response.Close();

The resultant xml response stream output to the console might look like this:

<?xml version="1.0"?>
<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ResponseMessage Code="1101" Description="Event added" Level="Information"
UID="D70C88D5-E5A1-48EC-84A4-D05DBD5CD8F6-99" />
</Response>