iCal Feed Integrations

Christian Lewis

February 25, 2019 19:26

What is iCal?

iCalendar (iCal) is an open standard for exchanging calendar and scheduling information. iCal feeds enable RemoteLock to fetch or synchronize date and time-based data from another calendar application.

Applications which support iCal will provide a feed URL within their interface - usually, you can find these feed links in a calendar view. Once you have this feed link, it can be added here to share new calendar Events or Reservations with your RemoteLock account.

RemoteLock can then generate access automatically for these new Reservations and if an email/attendee is included with the Calendar Event, access information can be automatically emailed to your guests.

Getting Started

After clicking the "Add iCal Feed" button, a box should appear asking for a Name, URL, and Sync Interval. The Name can be anything you'd like, though keeping it short is best. The URL should be a full https:// or webcal:// link. Sync Interval determines how often the RemoteLock system will check the feed for new Events or changes to Events.

After adding the feed, you will have the ability to associate Doors/Locks by clicking "Add Door". This is an important step: You must associate all doors that you intend to use with this feed before activating the feed.

Once all doors have been associated, click the "Activate" button, and pay close attention to the confirmation message that will appear. This message will tell you what will happen immediately after activation:
- Number of Calendar Events that guest access will be automatically generated for
- Number of individual email addresses that will be notified with PINs and Access Instructions

When you're sure that these numbers are correct, click "Confirm". The feed will then "sync" for the first time.

iCal Feed technical details

The data provided in an iCal feed can be different with each feed provider. To make the most use of integrating with an iCal feed, it should supply a list of Events with Start and End times in the future. Within each Event should be a list of "Attendees", which would be email addresses of people attending the Event.

For feeds from a Vacation Rental provider, a Reservation would be represented by an iCal Event, and guests of that Reservation would be listed as Attendees.

Feed Syncing and changes to Events

The RemoteLock system will periodically check your feed for new Events and changes to Events, which is referred to as a "sync". The default is to sync every hour, though that amount of time can be changed in the feed's Settings.

New Events should result in new guest access being generated for all associated doors, for the time period of the Event. If the event contained Attendee email addresses, separate PINs will be created for each Attendee, and the PIN with Access Instructions will be automatically emailed to each Attendee.

The RemoteLock system will detect certain changes to Events:
- Changes to the start/end time
- Cancellation of the Event
Any automatically generated guest access will be automatically updated to reflect these changes.

Currently, these changes are not detected, but may be supported at a later time:
- Removal or addition of Attendees within the Event
- Removal or addition of Doors/Locks after guest access has been automatically generated for an Event
- Deletion/removal of an Event. To revoke guest access that has been automatically generated for an event, the Event must be explicitly "canceled". Simply removing the Event from the feed will not revoke guest access.

Other notes regarding syncing of feeds:
- Access for "All Day" Events will use your account's Default Guest Start/End Times
- Emails to guests will either be sent immediately or scheduled according to your account's Guest Message Times if any have been created

Common issues with Feeds

No Events

A feed may be added that does not contain any upcoming Events. This is not necessarily a problem - Events may still be added sometime later, and would automatically be detected by the RemoteLock system.

Events that do not contain Attendees

While the email addresses of Attendees are typically included in an Event, they can be optional, meaning that some Events may not include any Attendee email addresses.

By default, the RemoteLock system will still generate a guest access PIN for these Events, but without Attendee email addresses, the PIN and Access Instructions cannot be automatically emailed.

If you would like to change this behavior to only generate PINs for Events that do contain Attendee email addresses, this can be enabled in the Settings for a feed by checking the "Only generate guest access for events that contain attendees" box.

Feed contains duplicate events

This occurs when a feed is not correctly following the iCalendar specification. In this case, our system detected that the feed is not providing consistent ID values for Events, which are needed to track the Event over time.

Feeds with known issues

Google Calendar

Two separate iCal feeds are provided by Google Calendar - one Public, and one Secret. It is the Secret address that should be used here as it contains the full information for each event, including Attendee Email and All-Day events:

Screen_Shot_2019-03-05_at_4.36.45_PM.png

Note that the Secret address may be hidden for users of Google GSuite, and the GSuite administrator may need to grant permission to enable it.

Please ensure you are adding times in Google calendar and not just dates. For example, the entry in Google iCal should be: from 2 pm on the 6th Jan to 11 am on the 13th Jan to create an accurate end date on the 13th. Without the inclusion of times (if you only add dates) the reservation would be inappropriately extended until the 14th per Google's logic.

Lodgify

Feeds from this provider are known to result in the "duplicate events" error above. We are working with Lodgify to resolve the problem.

TripAdvisor

Feeds from this provider are known to result in the "duplicate events" error above. We are working with TripAdvisor to resolve the problem.

Booking.com

The feeds coming from booking.com do not currently support special characters as expected. Specifically, feeds from booking.com with international (UTF-8) characters will silently fail.

BookingSync

Some feeds from this provider are known to result in the "duplicate events" error above, while other feeds are known to be missing both Attendee Emails and descriptions of each guest.

We are working with BookingSync to resolve the problems.

Tokeet

Feeds from this provider are not compatible. Events appear to be missing their "status", therefore our system can't determine if an event is confirmed or canceled. Some events appear to be missing a unique ID also.

Deactivation

To stop using an integration or stop automatically generating guest access, the integration can be deactivated. Please see this article for more information.