Ticket Calendar Sync - edmozley/freeitsm GitHub Wiki

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. Tasks can go too, either the slot you set aside for one or its due date. There are three ways to get any of it there, and this page explains which one to pick and what each one needs.

The page keeps its name for the sake of existing links. It covers tickets and tasks; tasks are section 4.

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.

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

Subscription link (iCalendar) Microsoft 365 (Graph) CalDAV server
Works with any calendar app Exchange / Microsoft 365 mailboxes Nextcloud, BaΓ―kal, Radicale, iCloud, Fastmail and other CalDAV servers
Admin setup none a connection, once the server address, once
Analyst setup paste a link one click sign in and pick a calendar
How fast whenever your calendar app refreshes β€” often hours immediately when the ticket changes immediately when the ticket changes
Marks you busy no β€” a read-only overlay yes β€” a real appointment yes - a real appointment
Direction out of FreeITSM only both ways, if enabled both ways, if enabled
Edit in your calendar no yes β€” move it and the ticket follows yes - on the next scheduled check
Needs network access only your calendar app β†’ FreeITSM FreeITSM β†’ Microsoft FreeITSM β†’ your calendar server

All three 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. Connections β†’ Add β†’ Microsoft 365. 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.

3b. A CalDAV server - instead of Microsoft, or as well

The same real, two-way appointments, in a calendar on Nextcloud, BaΓ―kal, Radicale, SOGo, iCloud, Fastmail or any other CalDAV server. Asked for in #133.

Any number of connections

A system can have as many calendar connections as it needs: Microsoft 365 for most people and a Nextcloud for a few, several CalDAV servers, or more than one Microsoft tenant. Each analyst picks which one their work goes to, under Which calendar in Preferences. With only one connection there is nothing to pick. The analyst table on System β†’ Calendar sync shows who is on which.

What an administrator does, once

System β†’ Calendar sync β†’ Connections β†’ Add, choose A CalDAV server, then enter the server's DAV address (not its web page):

Server Address
BaΓ―kal https://server/dav.php/
Nextcloud https://server/remote.php/dav/
Radicale https://server/

Leave the sign-in method on Automatic: a standard BaΓ―kal wants Digest, and a server sent the wrong scheme answers exactly as if the password were wrong. Test checks the address is a calendar server; type a username and password into its optional boxes and it also lists the calendars that person would be offered. That sign-in is used for the test only and is not saved.

πŸ”‘ There is no password on the connection. Microsoft lets one approved app write into everybody's calendar. A CalDAV server has no such thing, because each calendar belongs to its owner, so FreeITSM signs in as each analyst. That is also why the Which mailbox is whose table does not apply: nobody but the analyst has the password that reaches their calendar, so only they can choose it.

What each analyst does

Preferences β†’ General β†’ My work calendar β†’ Add to my calendar opens a sign-in form. If the system has more than one connection, pick yours under Which calendar first.

  1. Enter your calendar username and password and press Find. Use an app password where your server offers them - Nextcloud, iCloud and Fastmail all do - so it can be withdrawn without changing your main one.
  2. Choose a calendar and press Save. Only calendars your account can add events to, on the server your administrator entered, are listed.
  3. Anything already scheduled from the last week onwards is added straight away, exactly as with Microsoft.

Change moves your work to another calendar or account (the old appointments are taken out first). Picking a different connection under Which calendar does the same across connections: a Microsoft 365 one moves straight away once your mailbox is confirmed, and a CalDAV one waits until you have signed in there, so nothing is taken out until the new calendar works. Forget takes them all out and forgets your sign-in. Off takes them out but keeps the sign-in, so turning it back on is one click. The password is stored encrypted and never shown again.

What is different from Microsoft

  • Changes you make in the calendar come back on the scheduled job only. CalDAV servers send no notifications, so there is nothing faster; every five minutes is sensible.
  • Your own additions are kept. Add a reminder or a note to one of these appointments and it survives the next change to the ticket: FreeITSM rewrites only the time, the title, the description and the link.
  • Changing a connection between Microsoft and CalDAV, moving it to a different CalDAV server, or deleting it, takes that connection's appointments back out of calendars and switches calendar sync off for the analysts using it, after telling the administrator how many there are. Those analysts then set it up again. Analysts on other connections, and subscription links, are not affected.

4. Tasks

Tickets are not the only thing that can reach your calendar. A task can put two different things there, and they are not the same kind of fact β€” so you choose which you want.

Preferences β†’ General β†’ My work calendar β†’ Tasks in this calendar. It appears once you have chosen Add to my calendar, and starts at None.

Choice What appears
None nothing β€” the default
When I plan to do it the task's work window, as an ordinary timed appointment
When it is due the task's due date, as an all-day entry titled Due: …
Both both, so a task with both dates appears twice

πŸ”‘ Why this is a choice and not a switch. A work window is a plan; a due date is a commitment. Most tasks only ever get the second β€” so syncing only the work window, the way tickets do, would put nothing in most people's calendars at all. Equally, somebody who wants their deadlines in front of them does not necessarily want every half-hour they have blocked out.

Only tasks assigned to you. A task assigned to a team is never added to anyone's calendar: there is no single diary it belongs in, and writing it into everybody's would fill several calendars with an entry nobody owns.

Completed tasks are removed, as closed tickets are. So are the entries for a task you reassign, a due date you clear, or a kind you stop asking for.

Changing a task from your calendar

Both entries are editable, and they change different things:

  • Move the appointment and the task's work window moves.
  • Move the Due: … entry to another day and the due date itself changes.

Every change made from a calendar is written to the task's history, naming the mailbox it came from. Tasks had no history at all before this; a deadline that can be moved from outside needs a record of who moved it.

⚠️ This only works if the scheduled job is running (section 6). Without it the sync is one-way and a task you drag in Outlook will quietly snap back the next time FreeITSM touches it. It is the commonest reason a change appears not to have worked.

⚠️ A due date is a promise to somebody. Dragging that entry is not a private note to yourself β€” it changes the deadline the rest of your organisation sees. If that is not what you want, choose When I plan to do it and leave due dates out.

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

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

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

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