You can use the Linked Calendars feature to sync with external calendars, or to do a one-time data transfer by adding the feed, then deleting it, but choosing to keep all events. See “Integrations” for step-by-step guides to finding the appropriate ICAL links for many popular services.

By default, LiveWhale will include events from -3 years to +1 year from now when importing and syncing Linked Calendars. However, using the following config option from the sample livewhale/client/private.config.php it can be edited for individual needs:

//$_LW->REGISTERED_MODULES['events']['custom']['since_linked_calendars']=93312000; // max age of items (in seconds) acknowledged in linked calendars (default: 93312000 i.e. 3 years)
//$_LW->REGISTERED_MODULES['events']['custom']['until_linked_calendars']=31536000; // max future date of items (in seconds) acknowledged in linked calendars (default: 31536000 i.e. 1 year)

Adding a Linked Calendar

Once you have an ICAL or RSS link from your external service, here’s how you plug it into LiveWhale Calendar to begin syncing. (We suggest avoiding RSS feeds, as they often don’t match up event data perfectly. If RSS is all you have, some custom code might help match it up better with the LiveWhale event fields.)

1. Access Linked Calendars from your Toolbox or the Events manager.
2. Click the Add a new calendar feed button.
3. To add events in a feed, enter the feed url in the text field labeled Paste an iCAL link here
4. Click the Test this feed button to make sure your feed is valid and sending information. A message will be display stating if your feed is valid with a number of items returned.
5. You can set defaults for all imported events by editing fields on the Linked Calendar itself. So, you can easily add an image or event type to all events from a feed. Or, you can override the description for all imported events, if what’s coming in from the feed isn’t useful.
6. Once you Save your Linked Calendar, events will appear in your event list and re-sync every hour.
7. You can add details to your imported events individually, such as a summary, images, contact information, related content, plot the location to a map, and rsvp. Certain information from the feed cannot be overwritten, like the title and date.
8. Note: Imported Calendars are automatically refreshed hourly.
9. When deleting a linked calendar, a pop-up box will appear asking if you want to Delete all events or Keep all events. Imported events from a linked calendar are stored in the LiveWhale database. To remove them from the calendar database choose, Delete all events. Else, if you want to keep the events that were previously imported click on the Keep all events button.

Supported iCal fields

If you are creating your own .ics feed to import into LiveWhale, here are the basic and custom fields you can use for richer event data.

Basic iCal fields

In addition to all the normal date, time, and repeat/recurrence arguments from the iCal specifications, you can use the following attributes:

Note: As of LiveWhale 2.20.2, iCal events with start and end times of midnight on different days will be imported as All Day events.

Image iCal Fields

Images referenced via iCal will be loaded to linked calendar events as an external image (i.e., LiveWhale will display it via URL, but can’t crop/resize it like native images). You can always override these external images with one from LiveWhale, either per-feed or per-event.

Online iCal Fields

These fields can be used to import and export online events via iCal in LiveWhale 1.7.1+.

Note: these fields will only be read into LiveWhale when an event is first created/imported, so if you want to add them to an existing Linked Calendar event, you’ll need to delete and re-import that event (or add them manually by logging in and using the LiveWhale “Edit Event” page).

Example:

X-LIVEWHALE-IS-ONLINE:1
X-LIVEWHALE-ONLINE-TYPE:1
X-LIVEWHALE-ONLINE-URL:https://www.mymeeting.com/1234
X-LIVEWHALE-ONLINE-BUTTON-LABEL:Join Meeting
X-LIVEWHALE-ONLINE-INSTRUCTIONS:Sign up for an <a href="#">account</a> and join the meeting.

CampusGroups iCal fields

If you’re importing a feed from CampusGroups, the following CampusGroups-specific feed variables are supported in LiveWhale 2.10.3+.

Example iCal event

BEGIN:VEVENT
DTSTART;VALUE=DATE:20211003
DTEND;VALUE=DATE:20211004
UID:1234567890-some-unique-identifier
SUMMARY:My Event
DESCRIPTION:This is our event!
X-ALT-DESC;FMTTYPE=text/html:<p>This is our <strong>event!</strong></p>
LOCATION:My Event Location
GEO:40.6892;74.0445
URL:http://my.website.edu/event-url
X-LIVEWHALE-CONTACT-INFO:My Contact Info
CATEGORIES:Student Life|Athletics|Arts & Performance
ATTACH:http://my.website.edu/my-image.jpg
X-LIVEWHALE-IMAGE-CAPTION:My Image Caption
X-LIVEWHALE-TAGS:Alumni Reunion|Homecoming
X-LIVEWHALE-COST:Suggested Donation
X-LIVEWHALE-HIDDEN:1
X-LIVEWHALE-VISIBILITY:3
X-LIVEWHALE-CUSTOM-REGISTRATION-LINK:http://my.website.edu/register/
END:VEVENT

To see an example of these fields in action, check out a sample iCal export from your own site at calendar.myschool.edu/live/ical/events.

Advanced: if you have your own custom fields attached to LiveWhale events, you can import iCal data into those custom fields using the X-LIVEWHALE-CUSTOM- prefix or with a custom module using the onAfterSync handler.

Using a CSV or JSON file as a Linked Calendar source

In LiveWhale 2.23+, you can use a CSV or JSON file as a Linked Calendar source, provided certain values are included as column headers or JSON variable names for each event.

To set this up, edit your livewhale/client/global.config.php to reference either a local file (using “path”) or a remote url (using “url”) where the file is kept:

$_LW->REGISTERED_APPS['feeds']['custom']['calendar_feeds']['sources']=[ // support CSV or JSON linked calendars
  'feed-name'=>[ // use as /live/calendar_feeds/feed-name
    'type'=>'csv',
    'url'=>'https://full/path/to/my.csv'
  ],
  'feed-name2'=>[ // use as /live/calendar_feeds/feed-name2
    'type'=>'json',
    'path'=>$_LW->WWW_DIR_PATH.'/local/path/to/my.json'
  ],
];

Once the above is configured, you can create a new Linked Calendar using /live/calendar_feeds/feed-name (with whatever name you gave the configuration) and it will sync every hour.

Here is the list of supported CSV column names. Note that uid, title, and date_start are required.

If your CSV or JSON file doesn’t have these precise headers, you can use the onMapToIcalFields custom module handler to filter and process each event before it gets rendered to ICAL for the Linked Calendar.