Common use cases of Calendar Sync

This page explains how to combine the Calendar Sync for Jira features to solve some common problems.

The principle behind all of them is the same: an administrator configures the feeds once, and many users get ready-to-use calendars they can subscribe to from their own calendar applications. That makes access control an important part of the design. Without it, every user could potentially see work items they should not have access to, or simply a great deal they are not interested in.

Give a team its own calendar

The most common request. One feed, scoped by the query, restricted by group.

1. Basic Info - name the feed something the team will recognise on their My Calendars page, for example, Platform team deadlines. Set the Calendar Title to what you want showing in Outlook or Google Calendar.

2. Event Date & Time - choose the Time Type and the date field that should drive the events. For deadline calendars, All day with Due date as the Start Date Field is usually right.

3. JQL Query - write the query, or copy it from a saved filter, so it returns exactly the team's work. For example:

   project = PLAT AND duedate is not EMPTY AND duedate >= -365d
   

4. Security - choose Users in specific group(s) and name the team's group.

5. Save, and tell the team to look at My Calendars in about an hour.

Everyone in the group sees one calendar containing the team's work. Nobody outside it sees the feed at all.

Restrict a calendar by project role

Useful when the people who should see a calendar are defined by what they do on a project rather than by which group they are in.

On the Security tab, choose Users with specific role(s) and add one rule per project-and-role pair - for example PLAT + Developers, and WEB + Developers.

A user sees the feed if they hold any one of the roles you have named, in the project it is paired with.

Calendars with "my own" work items

Giving every user a calendar containing only their own work is a natural thing to want, and worth being clear about how to approach it today.

Roadmap note Automatic per-user calendars - one calendar generated for each assignee from a single feed - are not available in this release. They are planned for a future update. Until then, use one of the approaches below.

The approach that does not work

Do not write assignee = currentUser() in the query and expect each user to see their own work. Calendar Sync for Jira runs every feed query as the app, not as the person looking at it, so currentUser() matches nothing and the calendar comes back empty.
See The currentUser() JQL function.

What to do instead

For a small, stable group of people - create one feed per person, naming them in the query:

assignee = "alex@example.com" AND duedate is not EMPTY

Then set that feed's Security to a group containing just that person, so only they see it. Duplicating a feed and changing two fields makes this quick, but it does not scale - plan on this being a handful of feeds, not a hundred.

For a large team, give the whole team one shared calendar, as in Give a team its own calendar above, and let people filter or colour-code it in their own calendar application. Most users find a single team calendar they can toggle on and off more useful than a personal one anyway.

Let managers see everything, and everyone else see less

Create two feeds over the same underlying work:

• All work - the broad query, Security set to Users in specific group(s) naming your managers or administrators group.

• Teamwork - a narrower query, Security set to the wider team group.

Both appear on My Calendars only for the people entitled to them, and each person subscribes to whichever calendars they can see. Feeds are independent, so you can give them different date mappings and different event contents too - a manager's calendar might show the assignee in the summary, where a team calendar does not need to.

Put useful detail into the event itself

Calendar applications show very little by default, so what you put in the summary matters.

On the Event Contents tab, build the Summary from the fields that let someone identify the work at a glance in a crowded calendar grid - for example, the work item key, a short separator, and the summary text, which is the default. Adding the assignee or the priority is often worthwhile on a shared team calendar.

Keep the Description for the things people need once they have opened the event: the Issue URL is in the default set for exactly this reason, since it lets someone jump straight from the calendar into Jira.

Reduce the load a feed puts on Jira

Always bound your queries by date. A query like: created >= -365d AND type = Epic is faster to run, produces a smaller calendar, and does not lose you anything visible.

This also keeps you comfortably inside the 2,000 work item limit per feed.
See Troubleshooting and limitations.