Skip to main content

ICAL datasource

ICAL datasources allow you to fetch and display calendar events from iCalendar (.ics) format feeds. This enables you to integrate external calendar systems like Google Calendar, Outlook, Apple Calendar, or any other service that provides iCalendar feeds into your widgets and templates for dynamic event displays.

Prerequisites​

Before creating an ICAL datasource, ensure you have:

  • A valid iCalendar (.ics) URL from a calendar service
  • Proper network access to the calendar source
  • Understanding of the time zone and date format requirements
  • Knowledge of how many days of calendar data you need to display
  • Authentication credentials if the calendar is private or restricted

Supported Calendar Features​

The ICAL datasource supports various calendar formats and features:

Supported Calendar Sources:

  • Google Calendar (public and private with proper authentication)
  • Microsoft Outlook/Office 365 calendars
  • Apple iCloud calendars
  • CalDAV servers
  • Custom iCalendar (.ics) files hosted on web servers

Supported Event Data:

  • Event titles, descriptions, and locations
  • Start and end times with timezone support
  • All-day events and multi-day events
  • Recurring events (daily, weekly, monthly, yearly)
  • Event categories and custom properties

Limitations:

  • Maximum recommended range: 365 days for optimal performance
  • Complex recurring patterns may have limitations
  • Private calendar access requires proper authentication setup
  • Very large calendars (1000+ events) may impact refresh performance

Create datasource​

Go to Datasources > Click Add new in the External datasource tab > Choose the ICAL type.

Basic Configuration​

1. Update Schedule Decide how your datasource updates from the original calendar source:

  • Select a Refresh Frequency for regular intervals (every minute, hour, day, etc.)
  • Specify a Cron Expression for custom scheduling
Example Cron Expressions for Calendars
  • 0 */30 * * * * - Every 30 minutes (recommended for active calendars)
  • 0 0 */4 * * * - Every 4 hours (suitable for less dynamic calendars)
  • 0 0 6 * * * - Daily at 6:00 AM (for daily event summaries)
ICAL Refreshing

For more information about external datasource refresh options, see the External Datasource Refreshing documentation.

2. Calendar URL In the URL field, enter the iCalendar feed URL. The URL must:

  • Point to a valid .ics file or iCalendar endpoint
  • Be accessible from your server
  • Use HTTP or HTTPS protocol
  • Return proper iCalendar format data
Valid iCalendar URL Examples
  • https://calendar.google.com/calendar/ical/example@gmail.com/public/basic.ics
  • https://outlook.live.com/calendar/published/12345/calendar.ics
  • https://your-server.com/calendars/events.ics

Google Calendar Public URL:

https://calendar.google.com/calendar/ical/your-calendar-id/public/basic.ics

Outlook Calendar URL:

https://outlook.live.com/owa/calendar/00000000-0000-0000-0000-000000000000/your-calendar-id/cid-ABCD1234/calendar.ics

Calendar Display Settings​

3. Date and Time Configuration Configure how calendar events are processed and displayed:

  • Date format: Specify the format for displaying event dates (e.g., "YYYY-MM-DD", "MM/DD/YYYY", "DD-MM-YYYY")
  • Time format: Set the format for event times (e.g., "HH:mm", "h:mm A", "HH:mm:ss")
  • Generate calendar for days: Enter the number of days (from today) to include in the calendar data. Recommended: 7-30 days for most use cases
Date/Time Format Examples

Date Formats:

  • YYYY-MM-DD → 2024-03-15
  • MM/DD/YYYY → 03/15/2024
  • DD/MM/YYYY → 15/03/2024

Time Formats:

  • HH:mm → 14:30 (24-hour)
  • h:mm A → 2:30 PM (12-hour)
  • HH:mm:ss → 14:30:00 (with seconds)

4. Timezone and Week Settings Configure regional and display preferences:

  • Time zone: Select the timezone for displaying events. This should match your display location or target audience
  • First day of the week: Choose whether the week starts on Sunday or Monday, affecting weekly calendar displays

Advanced Configuration Options​

5. Datasource Settings Configure datasource behavior:

  • Active: Enable/disable the datasource without deleting the configuration
  • Ignore Error counter: Continue operation even if temporary errors occur during calendar fetching

6. Editor Settings Configure how the system processes calendar data:

  • Cache external resources: Store external content (images, attachments) referenced in calendar events locally for faster access
  • Remove broken external resource references: Automatically clean up invalid links found in event data
  • Rotate cache on every update: Clear and rebuild cache with each data refresh to ensure current calendar information
  • Exchange internal resource references: Update internal file paths when content is moved or reorganized
  • Request settings: Configure HTTP headers, authentication, timeout, and other request parameters for private calendars

7. Array Processing Enable Randomize arrays to shuffle the order of calendar events each time the datasource updates. This is useful for:

  • Rotating through different events in displays
  • Creating varied event presentations
  • Highlighting different calendar entries on each refresh

Authentication for Private Calendars​

For private calendars requiring authentication:

  1. Click on Request settings to expand advanced options
  2. Configure authentication methods:
    • Basic Auth: Username and password for CalDAV servers
    • Bearer Token: Access tokens for API-based calendar services
    • Custom Headers: API keys or authentication headers
  3. Set appropriate timeout values for calendar server responses
  4. Configure SSL/TLS settings if using HTTPS calendar feeds
Private Calendar Access

For Google Calendar private feeds:

  • Use service account credentials
  • Configure proper OAuth scopes
  • Ensure the calendar is shared with the service account

8. Save Configuration Once all settings are configured according to your calendar requirements, click Save to create the datasource.

Using Calendar Data in Widgets​

After creating the ICAL datasource, you can bind calendar event data to widgets:

Event Properties Access:

  • data.events[0].title - Event title
  • data.events[0].start - Event start date/time
  • data.events[0].end - Event end date/time
  • data.events[0].location - Event location
  • data.events[0].description - Event description

Date/Time Examples:

  • Current event: data.events[0].title at data.events[0].start
  • Today's events: Filter by current date
  • Next meeting: data.events[0].location - data.events[0].start

Multi-Event Display:

  • Event count: data.events.length
  • All today's events: Loop through data.events array
  • Upcoming events: Sort by start time

Common Use Cases​

Meeting Room Displays: Show current and upcoming meetings for conference rooms
Event Schedules: Display public events, conferences, or organizational calendars
Personal Calendars: Show individual schedules on personal displays or dashboards
Resource Booking: Display equipment, venue, or resource availability
Corporate Communications: Show company-wide events, holidays, and announcements
Educational Institutions: Class schedules, exam dates, academic calendar events

Calendar Integration Best Practices

For optimal performance, limit the "Generate calendar for days" setting to your actual needs. For meeting rooms, 1-7 days is usually sufficient. For monthly overviews, 30-45 days works well.