Outlook Calendar

Overview

This page is for whoever runs the install. Outlook Calendar sync needs one app registration in Microsoft Entra ID and five environment variables, two of them optional. Once they are set, a schedule's owner can connect their Microsoft account and keep the schedule and one Outlook calendar in step, in one direction or both, through Microsoft Graph. Nothing is configured per schedule on the server.

Where It Lives in the App

Open full size

Open full size

Prerequisites

• A Microsoft Entra ID (Azure AD) tenant or an Azure account to register an application
• Access to the Azure Portal to create an app registration
• A redirect URI that matches your app registration exactly, so users can complete the OAuth sign-in
• The Laravel scheduler cron from Installation, which drives the inbound poll, the subscription renewals and the queue
• For near-real-time inbound sync, a publicly reachable HTTPS URL, because Microsoft Graph must be able to call the webhook endpoint on your server
• For near-real-time inbound sync, QUEUE_CONNECTION=database

The queue matters because inbound sync is dispatched to it, so that Microsoft Graph gets a fast response. On database, the scheduler's minutely queue worker runs the sync within about a minute; keep php artisan queue:work running as well only if you want it sooner. On the shipped sync connection the sync runs inside the webhook request, which can be slow enough that Graph deprovisions the subscription. Either way, the 15-minute poll catches anything a notification missed.

Setup Instructions

1. Azure App Registration

1. Go to the Azure Portal and open Microsoft Entra ID → App registrations → New registration
2. Enter a name for the application (for example, "Event Schedule")
3. Under Supported account types, choose "Accounts in any organizational directory and personal Microsoft accounts" (this matches MICROSOFT_TENANT=common)
4. Under Redirect URI, select the Web platform and enter: {APP_URL}/microsoft-calendar/callback
5. Click Register

2. API Permissions

Event Schedule requests delegated permissions only, so it acts as the signed-in user and never gains tenant-wide calendar access.

1. In the app registration, open API permissions → Add a permission → Microsoft Graph → Delegated permissions
2. Add these five delegated permissions: Calendars.ReadWrite, offline_access, openid, email and profile
3. If your tenant requires it, grant admin consent for the permissions

The scope list is fixed: Event Schedule always requests exactly these five. offline_access is the one that yields a refresh token, so without it users are pushed back through sign-in as soon as the access token expires.

3. Client Secret and Client ID

1. Open Certificates & secrets → New client secret, then copy the secret Value immediately (it is only shown once)
2. Open the Overview page and copy the Application (client) ID

4. Environment Configuration

Add the following environment variables to your .env file. .env.example carries the same five, commented out, in its "Outlook / Microsoft 365 calendar sync (optional)" block:

MICROSOFT_CLIENT_ID=your_application_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret_value
MICROSOFT_REDIRECT_URI=https://your-domain.com/microsoft-calendar/callback
MICROSOFT_TENANT=common
MICROSOFT_WEBHOOK_SECRET=a_long_random_string

If you cache your configuration, run php artisan config:cache after editing .env, or the new values will not be picked up.

Variable Reference

The webhook secret is the only authenticity check on a notification. Graph subscriptions cannot be created at all while MICROSOFT_WEBHOOK_SECRET is empty: the attempt is refused rather than made without a clientState. Once set, Graph echoes the value back on every change notification, and Event Schedule ignores any notification whose value does not match, answering 401 when none of them do.

Features

How Sync Works

Outlook Sync Uses the Schedule Owner's Account Only

The calendar selection, the Graph subscription, and every outbound and inbound sync run on the schedule owner's connected Microsoft account. Team members do not get their own Outlook sync, and the Outlook Calendar row only shows the settings to the owner: anyone else, and an owner who has not connected yet, sees a Connect Outlook Calendar button there instead. Per-member calendar sync is a Google Calendar feature.

Sync Direction

Each schedule picks one of four options under Sync Direction. Saving the schedule creates or removes the Graph subscription for you.

Event Information Synced

• Event name, as the Outlook subject
• Description. By default the event description is sent as plain text; if the schedule has a Calendar Description Template set under Integrations → Calendar text and feeds, the rendered template is sent instead (see the available variables). On an update with no template and an empty description, no body is sent at all, so notes you typed on the Outlook copy survive
• Start time in the schedule's timezone, and an end time calculated from the event duration: two hours when no duration is set, and an all-day entry when the duration is 0, which is how a one-day all-day Outlook entry is stored when it arrives here
• Location, taken from the venue's best available address
• Privacy: an unlisted event is marked Private in Outlook, everything else is normal
• A Microsoft Teams join link, for online events when the toggle is enabled

What Is Not Sent

• Drafts. A Draft or Internal event is never pushed by a save, so an event first appears in Outlook when you publish it
• Recurrence. Recurring events are sent as a single Outlook entry on the series start date rather than as an Outlook recurrence. Use the schedule's iCal feed when you need every date of a series in a calendar app

Microsoft Teams Meeting Links

Enable Create Teams meetings for online events in the schedule's Outlook Calendar row. Every event with no venue is then created in Outlook as a Teams for Business meeting, and the join link is written into the event's Event URL field, but only when that field is still empty so a link you entered yourself is never overwritten.

Personal Microsoft accounts usually cannot create Teams for Business meetings. When Graph rejects the request, Event Schedule retries immediately without the Teams flags, so you get a normal Outlook event and no join link rather than a failed sync.

Events That Arrive From Outlook

Inbound sync uses a Graph delta query over a window running from 30 days ago to 365 days ahead. On the first run, or after you switch calendars, the whole window is read; after that only changes are fetched. Events brought in this way:

• Arrive already approved and use the schedule's slug pattern and default category
• Take their name, description, start time and duration from the Outlook entry. The description is converted from HTML to Markdown
• Convert the Outlook location into a venue, reusing one of your existing venues when the name or address matches. An event that already has a venue keeps it
• Are matched to an existing event by name and start time when there is no stored mapping yet, so an event you pushed out does not come back as a duplicate
• Never overwrite an appointment booking. An event created by a booking is owned by Event Schedule: inbound sync does not rewrite its name, description or time, so moving the Outlook copy will not move a customer's booking

When an Event Is Deleted in Outlook

Schedules that import from Outlook also choose When an event is deleted in the connected calendar, under the sync direction. It is one setting for the schedule, shared with the Google Calendar integration, and it is shown in one place only: if you have also connected Google Calendar, it appears in the Google Calendar row instead of this one, and only while that row's own direction is From Google Calendar or Bidirectional Sync.

Only a real deletion in Outlook triggers this policy. An event that merely moves outside the sync window is left untouched. Marking an event cancelled this way does not notify anyone: the cancellation notice that Cancel event in the event editor can send to ticket buyers and to the event's interest list only goes out from there.

An event that belongs to more than one schedule is only detached from this schedule, never cancelled or deleted outright, unless this schedule is the one that owns it. The other schedules keep the event as it is.

Calendar Sync on an Event

Once a schedule has a calendar selected and a direction that includes To Outlook Calendar, the Listing tab of a saved event ends with Calendar sync, which has an Outlook Calendar line:

The status is the schedule owner's copy, while Sync Now and Remove act with the Microsoft account of whoever is signed in, so they are the owner's buttons to use. If a request fails, the reason is shown in the row.

Real-Time Sync and Polling Fallback

• Graph sends one notification per changed event; Event Schedule collapses them to at most one inbound sync per schedule per minute, then reads every pending change in a single delta request
• The 15-minute microsoft:sync command polls the schedules whose direction is From Outlook Calendar or Bidirectional Sync, and is the primary path when no public URL is available
• The daily microsoft:refresh-webhooks command extends any subscription due to expire within the next day, and recreates any that Graph has already dropped

Usage

Step by Step

Steps 1 and 2 turn sync on, and are done by the schedule's owner.

1. Connect Outlook Calendar

   1. Open Settings in the sidebar and choose the Integrations tab
   2. In Outlook Calendar, click Connect Outlook Calendar
   3. Authorize the application in the Microsoft sign-in flow. You come back to the same section, which now reads Outlook Calendar Connected

   If the section shows "Outlook Calendar is not configured on this server" instead of the button, MICROSOFT_CLIENT_ID is still missing from .env. Connecting is half of it: nothing syncs until a schedule is told to.

2. Choose a Calendar and Sync Direction

   1. Open the schedule, click Edit Schedule, choose the Integrations tab and open the Outlook Calendar row
   2. Pick which Outlook calendar to sync with under Select Outlook Calendar
   3. Choose the Sync Direction: To Outlook Calendar, From Outlook Calendar, Bidirectional Sync, or No Sync
   4. Click Save

   Only the schedule owner sees these controls.

3. Push Events to Outlook

   Create and publish events as usual. Every event published or edited from then on is pushed to the selected calendar automatically. Events that already existed when you turned sync on are not pushed in bulk, so add them one at a time with the next step.

4. Sync a Single Event by Hand

   Open the event's form and choose the Listing tab; Calendar sync is at its end. On the Outlook Calendar line, click Sync Now, or Remove to delete the Outlook copy. It only appears once a calendar is selected and the direction includes To Outlook Calendar.

5. Enable Teams Meeting Links

   In the schedule's Outlook Calendar row, turn on Create Teams meetings for online events and save. Events with no venue are created as Teams meetings, and the join link is saved to the event when it has no link yet.

Automatic Sync

Once the schedule owner has connected Outlook and the direction includes To Outlook Calendar, events are synced automatically when they are:

• Published, whether that is a new event or a draft you just published
• Edited, which updates the existing Outlook entry in place
• Deleted, cancelled or un-published, which removes the Outlook copy. Restoring a cancelled event puts it back

Inbound polling and subscription renewal run through the scheduled commands below, so the Laravel scheduler cron has to be active.

API Endpoints

These are the application's own session-authenticated routes, not part of the public REST API. "Signed in" means a signed-in user with a verified email address.

Scheduled Commands

These Artisan commands keep inbound sync and Graph subscriptions healthy:

These commands run through the Laravel scheduler, which requires the following cron entry:

* * * * * php artisan schedule:run

Troubleshooting

Common Issues

Pick the line that matches what you see.

Logs

Sync operations are logged in the application logs. Check storage/logs/laravel.log for detailed information about sync operations, and storage/logs/scheduler.log for the scheduled sync and subscription-renewal runs.

Security Considerations