Team Calendar documentation
Documentation for Multi-Project Team Calendar for Jira. Publish at https://greatwork.company/apps/team-calendar/docs (the listing's Documentation URL) and mirror into the support portal's knowledge base.
Get started
- Install Multi-Project Team Calendar for Jira from the Atlassian Marketplace (Jira admin). Sites of up to 10 users pay a flat $5 a month, and every site gets a 30-day free trial.
- Open Apps > Team Calendar in the top navigation, or Team Calendar in any project's sidebar.
- The first time, Welcome to Team Calendar offers four starting points. Pick one and your calendar opens right away:
- Due dates: every open issue on its due date, colored by status.
- Team plan: issues stretched from Start date to Due date, one color per person.
- My work: everything assigned to you across all projects. Private to you.
- Start from scratch: choose projects, write JQL, and pick any date fields and color rules.
Opened from a project sidebar, the presets start with that project. You can change projects, dates, colors and filters at any time with Edit.
Team Calendar appears in three places: Apps > Team Calendar, the Team Calendar page in each project's sidebar, and the Team Calendar dashboard widget.
Using the calendar
- Pick a calendar from the Calendar list at the top.
- Move through time with the arrows and Today, and switch between Month, Week (with times), Agenda, Quarter (3 months side by side) and Year.
- Type in Filter: name, status, person to narrow what is shown.
- Click an issue to open it in Jira.
- The Colors legend shows what each color means.
Drag to reschedule
- Drag an issue to another day to move it. In a calendar with a start and an end date, both move by the same number of days.
- Drag the end of a multi-day issue to change only its end date.
- Date-time fields show as timed events in Week with times.
- Every change is saved to Jira as you, so your Jira permissions and the issue history apply.
Fields Jira doesn't let you edit, such as Created or Resolved, are shown but can't be dragged. If a date field is not on the issue's edit screen, Jira refuses the change; the event snaps back and a message explains why.
Schedule undated work
The Unscheduled list shows open issues in the calendar that have no date. Drag one onto a day to set its dates. It then leaves the list and appears on that day.
Create and edit a calendar
Choose New, or Edit on the current calendar. The calendar behind the editor updates as you change settings ("Preview updates as you type"). Then Save calendar.
| Setting | What it does |
|---|---|
| Name | The calendar's name in the list |
| Who can see it | Everyone on this Jira site (team calendar) or Only me. People only see issues they already have permission to view in Jira. |
| Projects | Search and add any number of projects (up to 50) |
| Filter with JQL (optional) | Combined with the projects above. Jira checks it as you type and shows "JQL is valid." or the error; a calendar with invalid JQL can't be saved. Date filtering is added for you, and any ORDER BY is ignored. |
| Dates | One date per issue, or Start and end (issues span days). Pick any date or date-time field for each, including custom fields. |
| Event title | What each event shows. Default {key} {summary}. You can also use {assignee}, {status}, {project}, {type} and {priority}. |
| Color by | Status category, Assignee (one color per person), Project, Issue type, Priority, or My own rules (any field) |
| Opens in | Month, Week with times, Agenda (month), Agenda (week), Quarter (3 months) or Year |
| Week starts on | Each person's Jira language setting, Sunday or Monday |
| Show | Weekends, Week numbers, Unscheduled issues list (drag onto a day to schedule), Release dates of the selected projects, Team events and time off |
Duplicate copies the current calendar as "
Color rules
With My own rules (any field), add rules under Color rules (first match wins). Each rule is a field, a condition and a color:
- Fields: Status, Priority, Issue type, Assignee, Labels, Project, Components, Fix versions, Summary, or Other field (by id) for any custom field, for example
customfield_10020. - Conditions: is, is not, is one of (comma separated values), contains, is empty, is set.
Example: "Priority is Highest" in red, then "Labels is one of security" in purple. Anything that matches no rule gets the default color. With assignee or project colors, each person or project gets its own distinct color, and text color adjusts for readability.
Team events and time off
With Team events and time off turned on, choose Add team event, or select a range of days on the calendar. Give it a Title, a Type (Event, Time off or Milestone), Who for time off, From and To (inclusive) dates and a color. Time off shows striped. Click an event to edit or delete it.
Team events belong to the calendar and are visible to everyone who can open it. Time off takes a typed name, not a Jira user.
Releases
With Release dates of the selected projects on, each project's release (version) dates appear on the calendar.
Export
- Export CSV downloads what is shown as a spreadsheet.
- Export .ics downloads what is shown as an .ics file you can import into Google Calendar or Outlook.
Both export a snapshot of the current view. They do not keep a live sync. If your browser blocks the download, the file contents are copied to your clipboard instead and a message says so.
Dashboard widget
Add the Team Calendar widget to a Jira dashboard. In its settings, choose a Calendar and a Layout (Month, Week, Agenda (this week) or Agenda (this month)), then save the dashboard. The widget shows the calendar read-only.
The same calendar is also available as a gadget on classic Jira dashboards, with the same settings. Atlassian removes gadgets from classic dashboards on 17 May 2027. Before then, add the Team Calendar widget to a new Jira dashboard and pick the same calendar and layout; your saved calendars are not affected.
Who can do what
| Who | Can |
|---|---|
| Anyone on the site | See team calendars and create their own |
| Anyone who can see a team calendar | Edit it and add team events |
| The person who created a calendar, or a Jira admin | Delete a team calendar |
| Only the owner | See and edit an Only me calendar |
Moving an issue always needs permission to edit that issue in Jira.
Licensing and trials
Team Calendar is paid through Atlassian: $5 a month for up to 10 users, billed per user above that, with a 30-day free trial. In the last 7 days of the trial a banner shows how many days are left.
If the site has no active license, Team Calendar is read-only: calendars still show, but drag, resize, creating and editing calendars, and team events are turned off until a Jira admin starts a free trial or subscribes from Manage apps. Your saved calendars are kept.
Permissions and data handling
Team Calendar runs on Atlassian's Forge platform and is built for Runs on Atlassian. It makes no calls outside Atlassian, has no outside servers and no tracking.
- Issues are read live from Jira as you and are never stored by the app.
- Saved calendars, team events and your preferences are stored in Atlassian's Forge storage for your site.
- Team Calendar asks Jira only to read and write work items (search issues, read fields and versions, update date fields when you drag) and for app storage. It does not read user profiles.
Limits and known gaps
- Up to 1,000 issues per visible date range. Beyond that a banner says "Showing the first 1000 issues"; narrow the calendar with projects or JQL.
- The Unscheduled list shows up to 100 issues.
- Up to 50 projects and 50 color rules per calendar.
- Export is a one-time file, not a live calendar subscription.
- Sprints are not shown on the calendar.
- If a plotted date field is deleted in Jira, the calendar shows a message with an Edit calendar button so you can pick another field.
FAQ
I installed it. Where is it? Under Apps in the top navigation, in each project's sidebar, and as a dashboard widget.
Can a bad JQL query break my calendar? No. Jira checks your JQL before the calendar can be saved, and every project and value is quoted for you. A saved calendar always opens and can always be edited or deleted.
Will it show all my issues, or only the most recent? Up to 1,000 issues for the dates on screen, and it tells you when it stops. Nothing is dropped silently.
Can I drag issues instead of opening each one? Yes. Drag to move, drag the edge to change the end date, and drag undated issues from the Unscheduled list onto a day.
Can I use times, not just whole days? Yes. Date-time fields show as timed events in Week with times.
Can I tell people apart by color? Yes. Assignee (one color per person) gives every person a distinct color, and color rules work on any field, including custom fields.
Can I get a list of a month's events? Switch to the month and choose Export CSV.
Can I copy a calendar? Yes, with Duplicate.
Does it sync with Google Calendar or Outlook? It exports an .ics file you can import. It does not claim a live sync, because that would mean sending your Jira data outside Atlassian.
Jira already has a calendar. Why this one? Jira's calendar shows one space and only Start date and Due date. Seeing several projects together needs a Premium plan, still with only those two fields. Team Calendar puts any projects on one calendar on every plan, plots any date field, colors by any field, and adds team events, time off, week numbers and export.
Uninstalling and your data
When the app is uninstalled, Atlassian deletes Team Calendar's storage for your site (saved calendars and team events). Issue dates you changed are your Jira data and stay as they are.
Support
Open a request in the Great Work help center (linked from the Marketplace listing) or email hello@greatwork.company. We answer within one business day (Monday to Friday, 9:00 to 17:00 US Central).