As many users seem to use the icalendar plugin as replacement for caldav and some just need some basic help where to start i thought a small guide could help.
What is iCalendar and for what this binding could be used?
The iCalendar-standard is normally a offline-to-use standard file format for describing calendars. It has itself many features and allows to describe events, appointments, away times etc. The icalendar binding focuses on events and uses only a small subset of the whole standard. The standard does not define how to transmit a calendar (caldav does), as the web uses literally everywhere http, it’s here done also.
For which use-cases icalendar can be used?
• Getting a simple overview about some events like garbage collections
• Switching items based on events
For all previous caldav-users: Please note that it is not fully possible to replace all caldav-personal features using this plugin (and also it’s not intended to). E.g. the recording feature is technically not possible as the convention (in fact there is no real registered standard for transmitting calendars outside of DAV) only implements read-only access. Also there is no code shared between caldav and icalendar – so they are simply completely different.
How to
First of all, you need the iCal-URL. It‘s a http(s) URL where an iCalendar is retrievable. Using different sources, different methods are available for getting the URL.
URL in Nextcloud
A simple example is Nextcloud. For retrieving the URL a way is to get the download link from inside the web interface (desktop browser typically support to copy the link by right-clicking on it). Use your login as authentication data. You can also create an app-specific password inside the user settings for more secure access.
URL in SOGo
Another example is SOGo. Retrieve the URL use the menu and there „Links to this Calendar“ and then copy the WebDAV-ICS-URL (either public or private as you prefer). Using the private URL, the authentication is done by your normal login data.
URL in iCloud
iCloud also allows to share a calendar, but only without authentication.
Your calendar solution may gives you an URL beginning with „webcal://“ (like iCloud). In that case, just try to get a result in your browser by replacing „webcal://“ with „https://“ or „http://“ and use the working URL. Comparing to a caldav-URL, most cases the URLs are quite similar e.g. Nextcloud just adds an „?export“ in most cases (not always).
Configuring icalendar Bridge
Next step is to enter the information to iCalendar Binding. Using the GUI, this can look as follows:
Please think about the retrieval interval. Some cloud providers seem to limit the interval and also, there is no need to poll the calendar every minute if you usually enter items a day before begin into the calendar. E.g. It might be sufficient if the interval is once a day for garbage collection calendars as this is no usual subject of change. If you don‘t trust the source fully, use a random authorization code to ensure, potential unwanted commands are not executed.
Create items using the Bridges channels (here done with „Create Points from Thing“):
The bridge only supports a presence switch and shows begin, end and subject of the current and next event.
Configuring event filters
You can also retrieve other events begin, end and subject by using event filters. For using them, the icalendar bridge must already exist. Create a new thing and select the calendar as bridge. First, think about how much results you expect and how often the result set needs to be updated. After that use the text or time based filter to get only some events. You can combine both (but both filters have to match).
The time-based filter allows to get only events in a specific time frame. Note that zero is „now“ or the rounded value of „now“. If you select „round to unit“ the begin and end will be rounded down to the selected unit. E.g. if unit is day and begin is set to 0, the timeframe to search from would be today at 0:00. Disabling the selection it would be exactly now. Here is a example where tomorrows events are retrieved:
If the date filter is not set, the earliest events in your calendar are shown!
The text filter allows to retrieve events by their contents. The easier mode is to use the simple text filter. If the event contains in the selected field your text, it will be shown. Here you can also use regular expressions. Note that if you use regular expressions, your expression has to match the whole string. Here is an example for specially titled events:
I hope this guide, which is now longer than it has been planned, is a good start. Please feel free to comment further cool things you have done with it.
