iCal - Import/export and synchronization

HBook allows you to import, export and synchronize calendars using iCal feeds or files. HBook synchronizes by default hourly with the calendars added. This can be modified up to every 5 minutes.

A recommended practice is to have HBook as your main calendar and to set two-ways synchronization between HBook and other iCal calendars. You should not set any synchronization between two other calendars, if they already are synchronized with HBook.

What is exactly the iCal synchronization?

iCal is a handy format to exchange calendars. It is used by:

• Agenda/Calendar applications : iCal, Google Calendar, Outlook Calendar...

• Booking platforms and OTA: AirBnb, booking.com , TripAdvisor, Expedia, VRBO, HomeAway, etc...

What is called iCal synchronization is in fact an import of the iCal feed of the calendars that are "synced" made at a regular frequency by each calendar/booking software. Here is what happens:

• Every hour (or at a custom frequency set in HBook > iCal sync > iCal sync settings), HBook checks the iCal feeds from all the calendars you have entered in HBook > iCal sync > Synchronized calendars. You can refresh the calendars manually by clicking on "Update calendars" button. Any new reservation will be imported into HBook and appear in the list of reservation. 

• At their own frequency, the external calendars (AirBnb, TripAdvisor, booking.com, HomeAway, Expedia, VRBO, etc...) do the same and check the HBook iCal feeds you have entered in their iCal sync settings. They will import the event (Google or iCal or any calendar software) or block the dates (AirBnb, TripAdvisor, booking.com, HomeAway or any booking platform). Some calendar software or booking platform have a refresh button/link to run the "sync".

You can check this article of our knowledgebase to see a non-exhaustive list of platforms, OTA, agendas... that accept the iCal synchronization.

Presentation of iCal synchronization table

If you have a "Coming soon/Maintenance" plugin, you need to deactivate it for the synchronization to work. Else, your iCal URLs are not reachable.

Manual update - Last synchronized

1. You can manually trigger the update of HBook calendars with your external calendars, by clicking on “Update calendars”.

2. Here you can see the date and time of the last update.

Export calendars

3. Download an .ics file of HBook calendar for that accommodation.

4. Click here to get the export URL of the calendar. You can copy it and paste it to provide the URL of HBook calendar for that accommodation.

If you need to get an URL containing all reservations within one calendar, you can click on “Get url of the calendar containing all HBook calendars in one”. This link is located below the iCal sync table.

You can add up to 3 query parameters to the URL:

• agenda: by default, it is set to "no". You will pass it to "yes" for agendas (Google Calendars, etc.). With this parameter set to "yes", the date is formatted with an additional time information (by default, 3pm for check-in and 11am for check-out). This is useful for agendas, so you can see the reservation across the days. You can modify the default values for check-in and check-out, using HBook filters.

• future_only: by default, it is set to "yes". You will pass it to "no" if you wish to have all past reservations/blocked dates included in the export (by default, up to 2 years in the past). You can modify the default value for the number of years of history to include, using HBook filters.

• reservations_only: by default, it is set to "no". You will pass it to "yes" if you have set that you wish to include blocked dates in the export (in HBook > iCal sync > Export settings) but wish to override the setting for a calendar where you wish to export only the reservations.

Import calendars

5. Click on Upload .ics file

6. Give a name to this imported calendar. It will be displayed in the reservation details.

7. Select the .ics file to be imported. All future events of that calendar will be processed. A notice message will appear to inform you of the result of the import.

Synchronize with your external calendars

8. To synchronize HBook calendar with an external iCal calendar, click on Sync with a new calendar

9. Enter the Name you wish to give to the calendar you will synchronize with. It will be displayed in the reservation details.

10. Enter the URL of the calendar

11. Click Sync. All future events of that calendar will be processed. A notice message will appear to inform you of the result of the import.

Synchronized calendars
The list of the calendars which are synchronized with HBook appears in the last column

12. Click Edit to change the name or the URL of the calendar

13. Click Delete if you wish to stop synchronizing HBook calendar with this calendar.

Note that as iCal is aimed at synchronizing calendars only, it does not update the information regarding payment, customer details or number of adults/children. You will have to edit these in the reservation list.

Presentation of iCal synchronization settings

To be able to deal with the diversity of external calendars supporting iCal and to offer you synchronization options, you will find the following settings:

Notifications settings

HBook can record and display notifications regarding the synchronization.

1. Set if you wish to keep records of the notifications. We recommend enabling this at least when setting up the iCal sync and when doing debug.

2. Set if you wish to display the notifications which will appear in Reservations page at the top of the page.

Import settings

1. Set the sync frequency. Please note that this impact only the frequency at which HBook checks the external calendars. It does not have any effect on the frequency of calendar updates on the external calendars (AirBnb, booking.com, Expedia...)

2. If the dates of a reservation has been modified in the external calendar, they can be updated automatically in HBook. This option is to be disabled if your external calendar does not follow iCal standards.

3. If a reservation has been cancelled in your external calendar, HBook can automatically update the status in HBook, and free the accommodation for these dates. This option is to be disabled if your external calendar does not follow iCal standards.

4. By default, HBook does not import blocked dates set as unavailable in your external calendars. You can modify this setting, and in such case, you should check the additional settings for iCal import window.

For the sync to work correctly, we recommend using HBook as main calendar and therefore, adding any dates unavailable for booking directly in HBook > Reservations > Block accommodation. This is not for reservations, but for dates that you wish to manually block and set as unavailable (for example, if there are painting work planned).

Additional settings for iCal import window

You might need in some circumstances to prevent HBook from importing some dates that are included in the export of an external calendar. This is usually the case with external calendars who add to their exports dates that are blocked due to settings of their own.

This can be for examples when there are no rates set for a future period, when some days are unavailable due to a booking window or an advanced notice setting. This will typically create "fake" or "phantom" reservations imported in your reservation list. You will use the following settings to set the iCal import window:

5. Indicate the number of months ahead from current date to set a maximum date.

6. Indicate the number of days from current date to set a minimum date.

7. If you do not accept one night reservations in any of your external calendars, you can set it here. HBook will ignore any 1-night event during the iCal import

Export settings

1. You can choose to include blocked dates (as added in Reservations > Block accommodation) in the export or not.

2. You can choose to include the dates blocked as "Preparation time" in the export or not.

3. You can choose to include only the reservations with status "Confirmed" in the export or not.

4. The Summary is a short description for the reservation. You can use the available variables to customize it. Some external calendar show the Summary to help you identify the reservation.

5. The Description is a more detailed description for the reservation. You can use the available variables to customize it. Some external calendar show the Description but not all of them.

HBook is coded to deal with the most possible options iCal synchronization can offer, as updating the dates or status of a reservation automatically, customizing the summary and description. However, not all external calendars create the iCal feed to work to its most. Therefore, you might need to disable some of these functionalities to make it work properly.

Understanding the notifications displayed in the Reservations page

Once set up, the iCal sync is completely automated. It still requires regular checks to verify that everything is running well. We display notifications on top of the Reservations page when there are any sync errors..

These messages are here to help you to monitor the sync. It can be:

• a connection error: this simply means that HBook could not communicate with the external calendar. As the sync is run by default again 1h later (or at your own frequency), you can ignore it unless it is repeateadly showing up at every sync. In that case, you should check with your host provider why access is refused by the external calendar when request is done by your server.

• a reservation could not be imported: you should check why it is not available on HBook. Dates are given to help you check this further.

• a reservation has been modified: you should check if it is possible to modify the reservation on HBook and update accordingly.

• a signature error: HBook checks the “signature” of the calendar returned upon calling the external calendar URL. A signature error indicated that the check was not successful. You should contact us in such case.

Resources : step by step guides, troubleshooting

Since the iCal sync is involving connections between HBook and other platforms/agenda, the set up can be tricky. We have written a variety of articles in our knowledgebase to help you with the set up and to troubleshot frequent issues.

Do not hesitate to email us via the contact page here. We will be delighted to help if needed!