Syncing with Outlook Calendar

HappenBoard Pro can keep your events and an Outlook or Microsoft 365 calendar in step. Events you publish on your site appear in Outlook, and events added in Outlook arrive on your site as drafts for you to review.

With the same setup, each person who takes appointments can connect their own Outlook calendar, so the times they are busy are not offered for booking.

Outlook Calendar sync needs HappenBoard Pro. See what Pro adds.

Before you start

• HappenBoard Pro installed and active.
• A Microsoft account that can edit the calendar you want to use and sign in to the Microsoft Entra admin center.
• A site served over https. Microsoft does not accept a plain http address for the connection.
• An administrator account. The Integrations screen is for users with the integrations permission, administrators by default (see roles and permissions).

Register an app with Microsoft

HappenBoard talks to Microsoft through an app you register, once, in Microsoft Entra.

1. Go to HappenBoard → Integrations and click Configure on the Outlook Calendar (Pro) card. Keep this tab open.
2. In the card, click Register a new app in Entra ID (Azure AD). Microsoft opens the form to register an application.
3. Give the app a Name. Under Supported account types, choose the option that accepts any organisation and personal Microsoft accounts. It works with Outlook.com and work accounts alike.
4. Click Register. On the Overview page, copy the Application (client) ID.
5. Open Authentication, add a redirect URI for the Web platform, paste the redirect URI shown in step 3 of the card (see below) and click Configure.
6. Open Certificates & secrets, click New client secret, choose the longest expiry offered and click Add. Copy the Value at once: Microsoft never shows it again. The Secret ID next to it is not what you need. Note the expiry date: the sync stops when the secret expires, until you paste a new one (see below).
7. Open API permissions, click Add a permission, then Microsoft Graph and Delegated permissions. Tick Calendars.ReadWrite, offline_access and User.Read. If hosts will connect their own calendars, tick Calendars.ReadBasic too. Click Add permissions.

The card shows the exact redirect URI to register. Copy it from there: Microsoft compares addresses character by character. It is your site address followed by /wp-json/happenboard/v1/pro/calendar/outlook/callback:

https://example.com/wp-json/happenboard/v1/pro/calendar/outlook/callback

If Settings → Permalinks is set to Plain, it is https://example.com/index.php?rest_route=/happenboard/v1/pro/calendar/outlook/callback instead.

Connect your Microsoft account

1. Back in the Outlook Calendar (Pro) card, paste the Application (client) ID and the Client secret (the value you copied).
2. Leave Tenant on common. If you chose an app for your own organisation only in step 3 above, type your organisation’s domain or its Directory (tenant) ID instead.
3. Click Save credentials.
4. Click Authorize with Microsoft, sign in with the account that owns the calendar and accept.
5. Microsoft sends you back to the card. A message confirms Outlook connected. and the card shows Connected as with the account’s address.

If you decline, or Microsoft returns an error, the message says so. Connecting sends nothing yet.

Change the credentials or renew the secret

Once the credentials are saved, the card hides their fields. Two links let you change them:

• Replace client secret: paste the Value of a new secret and click Save secret. The other values and the connection stay as they are. Do it before the current secret expires: in Entra, open Certificates & secrets, click New client secret and copy its Value.
• Reset credentials: after you confirm, removes the saved Application (client) ID and secret, puts Tenant back to common, and the card asks for them again. This link shows while no account is connected. To change the app of a connected site, click Disconnect first.

Hosts who connected their own calendar (see below) have to connect it again if you switch to another app.

Choose the calendar and turn sync on

Use a calendar kept for your site rather than your main one: what you add to the target calendar comes back to your site as drafts.

What syncs, and when

From your site to Outlook:

• An event is sent each time you save it while it is published and has no password. Drafts and private events stay on your site.
• Events published before you turned sync on are sent the next time you save them.
• Outlook gets the title, the description with a link back to your event page, the place, the dates and, for a recurring event, its repeat rule. A date you skip or move in a series is not sent: Outlook still shows it at its usual time.
• Moving an event to the trash marks its Outlook copy as cancelled. Deleting the event for good removes the copy.
• If Outlook cannot take a change because of a temporary problem, such as no answer or a busy server, HappenBoard tries again 5, 15, 60 and 240 minutes later. Other errors are not retried: fix the cause, then save the event again.

From Outlook to your site, every 15 minutes:

• A new event arrives as a draft on the Events screen. The first check covers 90 days back to about two years ahead.
• A recurring series arrives as one event with its repeat rule. Single dates edited in Outlook are not imported.
• Events marked private in Outlook are never imported.
• An edit made in Outlook updates the matching event, without publishing or unpublishing it.
• An event cancelled or deleted in Outlook is marked as cancelled on your site, not deleted.

When an event changed on both sides between two checks, the most recent edit wins.

Check that the sync works

Once sync is on, the card shows a Sync activity section: the last check and how many changes it brought, or its error. Changes that failed after every retry are listed there; saving the event again tries once more.

• Pull now checks Outlook straight away.
• Force full resync reads the whole calendar again on the next check. Keep it for when the two sides look out of step.

Disconnect Outlook

Click Disconnect at the bottom of the card and confirm. HappenBoard deletes the access it stored, stops the sync and forgets which Outlook event matches which of your events. Events already in Outlook stay there but are no longer updated.

Microsoft does not let HappenBoard withdraw the access itself. To remove it on Microsoft’s side too, remove the app from the app permissions of your Microsoft account.

If you reconnect the same calendar later, HappenBoard does not recognise the old copies: delete them in Outlook first, or pick another calendar.

Let hosts block their busy times

If you take appointments, each host can connect their own Outlook calendar, read only. The booking page then stops offering the times when they are busy. This needs the Calendars.ReadBasic permission from step 7 above.

1. The host opens their own profile (Users → Profile) and finds the Booking calendar section.
2. Next to Microsoft Outlook, they click Connect and accept.

HappenBoard reads only the start, end and availability of the host’s events, never their subject. An event shown as free or as working elsewhere does not block a slot.

Use Google and Outlook together

You can run Google Calendar sync at the same time: each integration has its own app, account and calendar. With both on, a published event is sent to both. A host can connect both too: busy times in either one block the slot.

If something goes wrong

• AADSTS50011: the redirect URI registered in Entra differs from the one HappenBoard sends. The card shows the right one under Authorize with Microsoft: copy it into Authentication in Entra.
• Sync activity says Last pull failed and nothing syncs any more: the client secret may have expired. Create a new one in Entra and paste it with Replace client secret.
• Microsoft asks for an administrator’s approval: your organisation restricts apps. An administrator opens API permissions in Entra and clicks Grant admin consent.
• An event is missing in Outlook: check that it is published without a password, then save it again.
• Nothing comes back from Outlook: the checks rely on WordPress scheduled tasks. See Health and maintenance.

Next steps

• The iCal feed: let people subscribe to your events without connecting any account.
• Setting your availability: the hours that a host’s connected calendar then narrows down.
• The admin Calendar screen: see the events that came from Outlook next to your own.
• Calendar sync, webhook and check-in hooks: for developers who want to change what is sent.