How to configure iCal

iCal is the calendar format that booking sites, Google Calendar and Apple Calendar all understand. The Solidres iCal plugin uses it in both directions: it publishes a calendar feed for each of your room types, so another site can see which dates are taken in Solidres, and it reads the feeds other sites publish, so dates sold elsewhere are closed in Solidres.

This guide covers installing the plugin, publishing a feed, importing feeds by hand and on a schedule, and what to check when the dates do not arrive.

PREREQUISITES:

Joomla 6.x, PHP 8.3+
Solidres 4.3.0 or later
A paid Solidres subscription, at any level. It carries the iCal and Limit Booking downloads
The Limit Booking plugin, installed and enabled, if you want to import. Exporting works without it
A working cron job for Joomla's Task Scheduler, if you want imports to run on their own. See How to set up Joomla CRON for the Task Scheduler

What iCal sync does, and what it does not

A calendar feed is a list of periods that are taken. That is all it carries, and it is worth knowing before you rely on it:

It moves dates only. No prices, no minimum stay, no guest details. A booking made on another site reaches Solidres as a blocked period, not as a reservation you can check in.
It is not instant. Each side reads the other's feed on its own schedule. Between two reads, both sides can sell the same night.
It works per room type, not per room. One imported event closes every room of the room type. See How an import treats your rooms.

iCal or a channel manager?

Both keep your website and the booking sites from selling the same night twice. A channel manager does it with more information and less delay:

	iCal	Solidres Channel Manager
What is sent to the booking sites	Dates that are taken	Availability, nightly rates, minimum and maximum stay, stop sell
Rooms of the same type	One booking closes the whole room type	Availability is counted from your real rooms, so the other rooms stay on sale
A booking made on a booking site	Arrives as a blocked period, without the guest or the price	Arrives as a normal reservation, with the guest, the dates, the rooms and the per-night prices
Changes and cancellations	Picked up at the next import, as dates that change	Applied to the reservation automatically
Delay	Until each side next reads the other's feed, which can be hours	Channel bookings reach your site within seconds
Prices on the booking sites	Typed in by hand on each site	Sent from your Solidres rate plans

iCal is a good fit for whole units let one at a time, such as a holiday apartment or a cottage, on one or two booking sites. If you sell several rooms of the same type, change prices often, take last-minute bookings or sell on more than two sites, a channel manager is the better tool. The Solidres Channel Manager is a subscription of its own, on top of your Solidres subscription: see what the Solidres Channel Manager does and what it costs, or read How to configure Solidres Channel Manager to see how it is set up.

Installation

Download Solidres iCal from your Download page on solidres.com.
In your Joomla administrator, go to System → Install → Extensions and upload the package.

The package installs two plugins and enables both for you: Solidres - iCal plugin, which adds the iCal tab to your room types, and Task - Solidres iCal, which runs the scheduled import. You do not need to download or enable them one by one.

IMPORTANT Importing needs the Limit Booking plugin, because imported dates close your rooms through it. If it is missing or disabled, the installer tells you, and the scheduled import stops until you enable it.

Exporting a room type's calendar

Every room type has its own feed address. To find it, go to Solidres → Room types, open a room type, and select the iCal tab.

Export settings
Field	What it does
Number of months from now	How far ahead the feed looks. Reservations that start within this many months are listed. The default is 6.
Filter by reservation states	Which reservations are listed. Leave it on All, or pick the states that really hold a room for you, for example confirmed and checked-in.
Include checkout date	By default a stay from 1 May to 5 May is listed as 1 May to 4 May, so the day of departure stays free for the next arrival. Set it to Yes only if the site that reads your feed expects the departure day to be included.
iCal URL	The feed address. Copy it into the other site's calendar import screen.

Then:

Save the room type once. The feed address is created on the first save after the plugin is installed.
Open the iCal tab again and copy the iCal URL.
Paste it into the calendar import screen of the booking site or calendar application. Each site calls this something slightly different: import calendar, sync calendar or add calendar by URL.

NOTE The iCal URL stays empty until the room type has something to publish: at least one reservation in the states you selected, or one blocked period that has not ended yet. Make a test reservation or add a limit booking, then open the tab again.

What the feed contains

The feed lists the room type's reservations and its blocked periods from Solidres → Limit bookings. A reservation appears with its dates, its reservation code, the room type name and the property name. The guest's name, contact details and the price are not in the feed.

IMPORTANT The address contains a secret token, and anyone who has the address can read the feed. Give it only to the sites that need it, and do not publish it.

Importing calendars from other sites

Importing is set up in the same iCal tab, under Import settings. You choose a format once, then import by hand, on a schedule, or both.

Import format

Import format	What an imported event becomes	When to use it
Limit Booking (default)	A blocked period under Solidres → Limit bookings, with a title that starts with `[iCAL]`	Almost always. The dates are closed and your reservation list holds only real reservations.
Reservation	A confirmed reservation with the origin ics, the guest name ICS and no price	Only if you need the imported stays to appear in your reservation list. They are placeholders: the guest and the amount are still on the site where the booking was made.

NOTE Every import replaces the previous one. Solidres removes what it imported for the room type last time and creates it again from the feed, which is how a booking cancelled on the other site reopens its dates. For the same reason, do not edit an imported limit booking or reservation: your change is gone at the next import. Blocked periods you created yourself are never touched, as long as their title does not start with [iCAL].

Automatic import

On the other site, find the address of the calendar it exports for this unit and copy it.
In the room type's iCal tab, paste it into Source iCal URLs. To import from several sites, enter one address per line.
Save the room type.
Go to System → Scheduled Tasks, select New and choose the task type Solidres - iCal. One task covers every room type on your site.
Set how often it runs. Once an hour is a sensible start.

The task only runs when something triggers Joomla's scheduler. On a live site that should be a real cron job: How to set up Joomla CRON for the Task Scheduler walks through it.

At each run, the task downloads every address of a room type before it changes anything. If one of them cannot be downloaded or is not a calendar, the dates imported last time stay closed, the task is marked as failed, and the reason is written to the scheduler log. Your rooms are not reopened because another site was unreachable for an hour.

NOTE Your schedule is only half of the delay. The other site reads your feed on its own schedule, which you cannot change. Its help pages say how often.

Manual import

To import once, without a schedule:

Download the calendar from the other site as an .ics file.
In the room type's iCal tab, choose the file under Upload .ics file.
Save the room type. Solidres lists the limit bookings it created.

A manual import replaces earlier imports for the room type in the same way a scheduled one does. If the room type also has source addresses and a scheduled task, the next run replaces what you uploaded, so use one method per room type.

How an import treats your rooms

A calendar event says that a period is taken. It cannot say which room, or how many. Solidres therefore closes every room of the room type for the dates of each imported event.

Your room type	What one imported booking does	Is iCal a good fit?
One apartment, one room	Closes the apartment for those dates	Yes
Six identical double rooms	Closes all six for those dates	No. Use the Channel Manager, which works with the number of rooms left

If you let several similar apartments, create one room type per apartment, each with a single room, and give each its own feed on the other site.

NOTE If you also run the Solidres Channel Manager, a period closed by an import is sent on to your channels like any other blocked date.

Calendars for experiences

With the Experience plugin installed, each experience has an iCal tab of its own. It exports only: the feed lists the bookings of that experience, so you or your guide can subscribe to it in a calendar application. Save the experience once to create the address.

Here, Number of months looks back, not ahead: the feed lists the bookings that were made in the last so many months.

Checking that it works

The export. Open the iCal URL in a browser. A file named calendar- followed by today's date is downloaded. Open it in a text editor: each reservation is a block that starts with BEGIN:VEVENT.
The import. In System → Scheduled Tasks, run the Solidres - iCal task by hand, then open Solidres → Limit bookings. The imported periods are the ones whose title starts with [iCAL].
The schedule. Come back after the interval you set. If Last Run has not moved, the task is fine and the cron job is not firing.

Troubleshooting

Symptom	Cause and fix
There is no iCal tab on the room type	The Solidres - iCal plugin is disabled. Enable it under System → Plugins.
The iCal URL is empty	The room type has not been saved since the plugin was installed, or it has nothing to publish yet. Save it, make sure it has a reservation in the selected states or a current limit booking, and open the tab again.
The other site rejects the address, or the browser shows "You are not authorised"	The address is incomplete. Copy it again from the iCal tab, including everything after `token=`.
The other site shows the departure day as free, or as taken, when it should not	Change Include checkout date and let the other site read the feed again.
Nothing is imported and the task has never run	No task of the type Solidres - iCal exists, or nothing triggers the scheduler. Create the task and set up the cron job.
The task fails	Limit Booking is disabled, or a source address could not be downloaded or read. Open `joomla_scheduler.php` in your site's log folder: it names the room type, the address (shortened, so the secret part is not logged) and the reason. An address that was reset on the other site has to be copied into Source iCal URLs again.
One booking on the other site closed the whole room type	That is how a calendar feed works. See How an import treats your rooms.
A change made to an imported limit booking disappears	Every import replaces the previous one. Make the change on the site the booking came from.
"Invalid upload file"	The file must have the extension `.ics` and be a calendar file. Download it again from the other site without opening and re-saving it.
A long import is cut short	Raise Task Timeout (seconds) in the Scheduled Tasks options, and check your PHP `max_execution_time`.

Still on Joomla 3?

Everything above describes the current version. The Joomla 3 version of the plugin has no scheduled task, and imports automatically in one of two ways instead:

CLI cron job. Enter the address in the room type's Import ICAL URL field, then set up a cron job that runs JOOMLA_ROOT/cli/ical.php.
Web cron job. Enter the address in the same field, then edit the iCal plugin under Extensions → Plugins, fill in Cron token and save. Use the address shown in Web CRON URL for your web cron service.

Exporting and the manual .ics upload work the same way as described above.