# iCal - Import/export and synchronization

![ical-menu-item.png](./attachments/ical-menu-item.png)

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.

> [!INFO]
> 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.

* * *

<a id="what-is-exactly-the-ical-synchronization"></a>

## 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](https://maestrel.atlassian.net/wiki/spaces/KB/pages/31129618/Can+I+sync+HBook+with+AirBnb+Expedia+VRBO+booking.com+TripAdvisor+Agoda+etc...) of our knowledgebase to see a non-exhaustive list of platforms, OTA, agendas... that accept the iCal synchronization.

* * *

<a id="presentation-of-ical-synchronization-table"></a>

## Presentation of iCal synchronization table

> [!INFO]
> 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.

![sync-table.png](./attachments/sync-table.png)

<a id="manual-update-last-synchronized"></a>

### 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.

<a id="export-calendars"></a>

### 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.

> [!INFO]
> 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.

<a id="query-parameters-added-to-the-url"></a>

#### Query parameters added to the URL

The HBook iCal export URL is structured with the `accom_id` and `accom_num` parameters.

By default, for new HBook installation, we enable automatically a **random key** that is added as well to the export URL. You will see a parameter named `key` when you get the export URL. This is done to secure access to your HBook iCal feeds, which would otherwise be easily accesible.

> [!INFO]
> For older installation, you will see a setting “Add a random key to HBook iCal URL” in the [Export settings](#ical-export-settings) section of **HBook > iCal sync**.

<a id="available-additional-query-parameters"></a>

#### Available additional query parameters

HBook provides different parameters that can be added at the end of the export URL. This can be usefult for the following cases:

- when you need a different format for a specific export: by default, HBook exports the reservations as dates, but you may need to export with date and time. This is generally the case when exporting to an agenda (Google Calendar, etc.).
- when you wish to override the default behavior set in **HBook > iCal sync > Export settings**.

You can add up to 4 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](../hbook-documentation/plugin-customization.md#filters-ical-sync).
- **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](../hbook-documentation/plugin-customization.md#filters-ical-sync).
- **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.
- **website\_only**: by default, it is set to "no". You will pass it to "yes" if you have set that you wish to include all resrevations (not only reservations from the website) in the export (in **HBook > iCal sync > Export settings**) but wish to override the setting for a calendar where you wish to export only reservations from the website.

> [!NOTE]
> **Examples of HBook iCal URL with additional parameters**
> - https://web-dom.com/?feed=hbook-calendar.ics&accom\_id=102&accom\_num=1&agenda=yes
> - https://web-dom.com/?feed=hbook-calendar.ics&accom\_id=102&accom\_num=1&agenda=yes&reservations\_only=yes
> - https://web-dom.com/?feed=hbook-calendar.ics&accom\_id=102&accom\_num=1&website\_only=yes
> - https://website.com/?feed=hbook-all-calendars.ics&future\_only=no
> - https://website.com/?feed=hbook-all-calendars.ics&&key=KBDEHAOEY25RPNO&agenda=yes

<a id="import-calendars"></a>

### 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.

<a id="synchronize-with-your-external-calendars"></a>

### 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.

> [!INFO]
> 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.

* * *

<a id="presentation-of-ical-synchronization-settings"></a>

## 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:

<a id="notifications-settings"></a>

### Notifications settings

HBook can record and display notifications regarding the synchronization.

![settings-ical-notif.png](./attachments/settings-ical-notif.png)

1. Set if you wish to **keep records** of the [notifications](#understanding-notifications-reservations). 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.

<a id="prices-settings"></a>

### Prices settings

When editing a reservation in the [Reservation list](../hbook-documentation/reservations/reservation-list.md), HBook automatically update the price of the reservation. In this section you will find settings to fine tune the price update for reservations imported from an iCal calendar.

![settings-ical-prices.png](./attachments/settings-ical-prices.png)

1. You can **disable** the price update for reservations imported from an external calendar.

2\. If you have enabled the price update, you can select the **fees/taxes** to be included in the price calculation.

<a id="import-settings"></a>

### Import settings

![settings-ical-import-1.png](./attachments/settings-ical-import-1.png)

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.

> [!INFO]
> 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).

<a id="additional-settings-for-ical-import-window"></a>

#### **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:

![settings-ical-import-2.png](./attachments/settings-ical-import-2.png)

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

<a id="export-settings"></a>

### Export settings

![settings-ical-export.png](./attachments/settings-ical-export.png)

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](../hbook-documentation/list-of-variables.md) 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](../hbook-documentation/list-of-variables.md) to customize it. Some external calendar show the Description but not all of them.

> [!INFO]
> 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.

* * *

<a id="understanding-the-notifications-displayed-in-the-reservations-page"></a>

## 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.

* * *

<a id="resources-step-by-step-guides-troubleshooting"></a>

## 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:

- [Step-by-step by platform - iCal](https://maestrel.atlassian.net/wiki/spaces/KB/pages/216989724/Step-by-step+by+platform+-+iCal)
- [Troubleshooting - iCal](https://maestrel.atlassian.net/wiki/spaces/KB/pages/216629270/Troubleshooting+-+iCal).

Do not hesitate to email us via the contact page [here](https://maestrel.atlassian.net/servicedesk/customer/portal/3). We will be delighted to help if needed!