Ticket Calendar Sync

Scheduled work in your own calendar

Schedule a ticket in FreeITSM and it appears in the calendar you actually look at — your phone, Outlook, Google, whatever you use. There are two ways to get it there, and this page explains which one to pick and what each one needs.

The developer guide is Scheduled work in your own calendar — Developer Guide.

Related: Tickets · Calendar · Mailbox Authentication · REST API — Calendar

---

1. What this is

When you schedule a ticket — Schedule work, either on the ticket or from the inbox right-click menu — FreeITSM records when you intend to do it, and draws it on Tickets → Calendar. Calendar sync puts that same information into your ordinary calendar, so your day lives in one place.

Two routes out. They are not really alternatives; they are different levels of ambition.

	Subscription link (iCalendar)	Microsoft 365 (Graph)
Works with	any calendar app	Exchange / Microsoft 365 mailboxes
Admin setup	none	one connection, once
How fast	whenever your calendar app refreshes — often hours	immediately when the ticket changes
Marks you busy	no — a read-only overlay	yes — a real appointment
Direction	out of FreeITSM only	both ways, if enabled
Edit in your calendar	no	yes — move it and the ticket follows
Needs internet access	only your calendar app → FreeITSM	FreeITSM → Microsoft

Both are per analyst, and each analyst chooses for themselves under Preferences → General → My work calendar. An administrator sets up what is possible; they never switch it on for somebody else.

🔑 The subscription link exists so that not being a Microsoft house still gets you something. The Graph route is better where it is available, but an organisation whose calendar FreeITSM does not support natively should not be left with nothing.

---

2. The subscription link — works with anything

Preferences → General → My work calendar → Subscribe link → Get my link. You get a private URL and a QR code; scanning the code is usually the quickest way onto a phone.

App	Where
New Outlook / Outlook on the web	Calendar → Add calendar → Subscribe from web
Google Calendar	Other calendars → + → From URL
Apple Calendar	File → New Calendar Subscription
iPhone	Settings → Calendar → Accounts → Add → Other → Add Subscribed Calendar

What to know

🔒 The link is a secret, not a login. Anyone holding the URL can read your scheduled work without signing in. Treat it like a password. Reset revokes every copy instantly — including devices you already set up, which stop updating until you give them the new link.

⚠️ If FreeITSM is not on HTTPS the link travels unprotected, every time your calendar refreshes, unattended, wherever the device happens to be. The page says so plainly. Do not use it outside a trusted network until HTTPS is on.

What it publishes is your choice: Ticket number and subject, or Ticket number only. The second exists so the shape of your day can leave the building without the detail of it.

An administrator can cap that for everyone under System → Calendar sync → Subscription links — allow subjects, restrict everybody to numbers, or switch links off entirely. Switching them off revokes existing links rather than just hiding the option.

⏱️ Refresh rate is up to your calendar app and is frequently slow. Outlook in particular can take several hours and gives you no way to hurry it. That is how calendar subscriptions work everywhere, not a FreeITSM limitation. If you need changes to show up promptly, that is what the Graph route is for.

---

3. Microsoft 365 — the richer route

Here FreeITSM writes real appointments into your Exchange mailbox. They block time, they sync to your phone, and they update the moment the ticket changes rather than whenever a calendar app next feels like it.

What an administrator does, once

System → Calendar sync.

1. Connection. Either Borrow the credentials from a mailbox — reusing the Azure app registration already set up for reading email, which is the normal answer — or Enter credentials for a separate tenant. The second only matters if the calendars live in a different tenant from your intake mailbox.
2. The Azure permission. Calendars.ReadWrite as an Application permission, with admin consent granted.
3. Test. The button answers two separate questions — do the credentials work, and can this particular mailbox be reached — so a failure points at its own fix.
4. Which mailbox each analyst syncs to. See below; this is the step most likely to be skipped.

⚠️ Application, not Delegated. Azure lists them separately and the Delegated list has a permission with the same name. Choosing the wrong list is the most common setup mistake by a distance: everything looks correct and nothing works.

🔴 Know what you are granting. Calendars.ReadWrite as an Application permission reaches every mailbox in the tenant, not only the analysts you list. That is how app-only permissions work. If that is broader than you want, restrict it in Exchange with an Application Access Policy scoped to a mail-enabled security group of just your analysts.

There is no sign-in for each analyst, no consent screen, and no per-person tokens to maintain.

Which mailbox is whose

FreeITSM assumes an analyst's calendar lives at the email address on their FreeITSM account. That is frequently wrong — an account created locally might be admin@local, a directory import might be keyed on a payroll address, and a sign-in name is often simply not a mailbox.

So the settings screen lists every active analyst and lets you set the real one. Addresses FreeITSM is merely assuming are greyed out; ones somebody actually chose are shown normally. That distinction is the point.

If a test says no calendar could be found for an address that plainly exists, try the mailbox's primary address rather than an alias.

What each analyst does

Preferences → General → My work calendar → Add to my calendar. FreeITSM tells you which mailbox it will write to before you commit.

🔑 Nobody can switch this on for you. Writing into somebody's personal calendar is not a decision an administrator should make on their behalf, so there is no way for them to do it.

Turning it on back-fills everything you already have scheduled. Turning it off takes it all back out rather than leaving a pile of entries to delete by hand.

From then on the appointment follows the ticket: move it and it moves, hand it to a colleague and it leaves your calendar and appears in theirs, close or unschedule it and it disappears. A calendar should say what you are going to do, not accumulate everything you have ever finished.

A calendar problem can never stop you scheduling a ticket. If Microsoft is unreachable the save still succeeds and the schedule is still recorded; the failure is reported on the settings screen rather than in your way.

---

4. Changes coming back from Outlook

Optional, and it needs a scheduled job running. With it, moving an appointment moves the ticket; and if an administrator enables it, deleting the appointment unschedules the ticket.

The case it was built for: you are on the train, you look at your phone, and a job turns out not to be needed. Delete it there, and by the time you reach your desk FreeITSM is already clean.

Accepting deletions is off by default — System → Calendar sync → Changes made in the calendar. Whether tidying a personal calendar should reach work the whole service desk can see is an organisation's decision, not ours. With it off, a deleted appointment simply reappears next time the ticket changes.

Three safeguards:

• It never acts on a check that lost its place. If the sync has to start over it re-learns where it is and changes nothing — an empty answer can mean everything was deleted or I have no idea what happened, and only one of those is safe to act on.
• An unusually large number of deletions at once is refused, not obeyed, and reported instead. That is far more likely to be a fault than an instruction.
• Every change is written to the ticket's history, naming the calendar it came from.

---

5. The scheduled job, and notifications

The most commonly misunderstood part, so plainly:

	Scheduled job	Notifications
How	FreeITSM asks Microsoft what changed	Microsoft calls FreeITSM when something changes
Speed	your cron interval — minutes	seconds
Needs a public address	no	yes — reachable HTTPS
Works behind a firewall	yes	no
Required?	yes	no

🔴 Notifications never replace the job. Two reasons and both matter. Subscriptions expire — Microsoft caps calendar subscriptions at about three days, and the job is what renews them; stop running it and notifications stop a few days later. And notifications go missing — dropped in transit, lost during a restart, or quietly stopped when a subscription lapsed. A gap in notifications looks exactly like nothing having changed. The job is the backstop; notifications just make the common case fast.

Leaving the Notification URL blank is a perfectly good answer, and for a FreeITSM the internet cannot reach it is the only one. Changes then arrive in minutes instead of seconds.

Set the job to run every five minutes:

*/5 * * * * /usr/bin/php /var/www/freeitsm/cron/calendar_sync_pull.php >> /var/log/freeitsm-calendar-sync.log 2>&1

On Windows, put it in a .bat and point Task Scheduler at that:

schtasks /Create /TN "FreeITSM Calendar Sync" /TR "C:\path\to\freeitsm-calendar-sync.bat" /SC MINUTE /MO 5 /RU SYSTEM /RL HIGHEST /F

⚠️ Not the command directly. schtasks parses /TR itself, and a command with both quoted paths and a redirect is exactly where its quoting quietly breaks — leaving a task that looks created and does nothing.

Not running the job costs you nothing you already had. The sync simply stays one-way, as it works without it.

---

6. Is it working?

System → Calendar sync answers this at the top of Changes made in the calendar.

Most faults here announce themselves. One does not: a scheduled job that has stopped is indistinguishable from a calendar in which nothing has changed, and it goes on looking healthy for weeks while every change made in Outlook is lost. So the screen reports how long since the calendars were last checked, and warns past half an hour — while saying that a deliberately slower schedule is fine, because FreeITSM cannot know what interval you chose.

Per analyst:

Pill	Meaning
Syncing	they have turned it on
Notified	Microsoft has a live subscription; hover for the renewal date
Not subscribed	an address is set but Microsoft has nothing to call for them — changes arrive only on the job
Subscription lapsed	it expired unrenewed, which usually means the job stopped
Last sync failed	hover it; the reason is in the tooltip

---

7. Troubleshooting

What you see	What it means
Credentials work but a mailbox cannot be found	Wrong address, or an alias rather than the primary address
Nothing appears in the calendar at all	Check the analyst actually chose Add to my calendar. An admin cannot do it for them, so it is easy to assume it was done
"Check the client secret has not expired"	Usually exactly that. Otherwise Calendars.ReadWrite is missing from Application permissions, or consent was never granted
"Subscription validation request failed"	Microsoft could not reach your Notification URL, or something in front of FreeITSM answered instead
Notifications worked then stopped	The job stopped renewing, or the public address changed. A tunnel handing out a new URL on restart does this silently
"baseline taken (nothing applied)"	Not a fault. The job re-learned where it is without changing anything
A lot of deletions were refused	The safety cap. Check what happened in the mailbox before overriding
"Calendars last checked" keeps growing	The job is not running. On Windows, security software blocking php.exe for a SYSTEM task is a common and silent cause
A deleted appointment came back	Working as intended unless "Deleting the appointment unschedules the ticket" is on

---

Where this is documented in-product

Tickets → Help → Calendar carries the same material as a guide, linked from the Calendar section.