Configuration
Configuration is available to Jira administrators.
To open the configuration screen, click the "Configure" button in add-on management in Jira administration.
The configuration can also be opened from the "My Calendars" page (under user profile).
Feeds
The Feeds page displays a comprehensive list of all calendar feeds, along with their current status.
It includes the following columns:
Name - the name of the feed.
Last edit - when the feed configuration was last edited.
Status - status of the last export.
Last export - date and time of the last export.
Time to export - how long the export took, in minutes and seconds.
Events - how many events (Jira issues) were exported. Please note that Calendar Sync for Jira currently limits each feed to 5,000 issues.
The following actions are available:
Create new feed (button below the grid) - creates a new feed starting with a clean slate.
Edit feed - click feed name to review and update its configuration.
Duplicate - creates a new feed using an existing one as the starting point.
Delete - permanently remove the feed.
If the feed is working as expected, the status column displays a green "OK" label. Otherwise it shows a red "ERROR" badge. If the feed is being exported at the moment, the status column also includes a pair of arrows forming a circle.
An error means that the feed could not be exported. Older versions of the export may still be available for download (if it was successful in the past). Errors may occur for a number of reasons, including problems with reaching Jira, feed misconfiguration or internal problems within Calendar Sync for Jira.
Click the "ERROR" badge to find out more about the problem. In the example pictured below, the error occurred because the JQL query in the feed configuration was invalid.
Editing feeds
To create a feed, click the "Create new feed" button in the feeds page. To modify an existing feed, click its name on that same page. The feeds are created and edited using the same set of screens, which is documented below.
Name tab
The Name tab defines the feed name (used in configuration screens) as well as title and organization name of the generated calendar.
Each feed is given a unique Feed name. This name will only be used as a label on the Calendar Sync pages.
Calendar title is also copied as is to the exported calendar. It should be displayed as the calendar name in any calendar application. The title may also be configured to include group name (see Grouping tab for more information).
The Organization name is copied as is to the organization name in exported calendar.
Query
The Query tab defines the Jira query, which determines what issues will be exported.
The Query determines what Jira issues will be included in the feed. The easiest way to enter the query is to select an existing filter.
The query can also be typed directly using the Jira Query Language (JQL). Tip: to obtain a ready-to-use query without creating a filter, you can use the Jira issue search and click the "Advanced" link to get the corresponding JQL clause.
With manual JQL input, you can test the query using the Test button. It will display the total number of matching issues or an error message if the query is invalid.
Event date/time tab
The Event date/time tab determines how Calendar Sync for Jira calculates event date and time from Jira issue fields.
Begin the configuration by selecting the Time type (all day, date with time or date range) and date field(s). If the date field(s) are empty on any (or all) issues matching the query, these issues will be omitted from calendar feeds.
All-day events
The "All day" configuration includes the following fields:
Date - a date or date/time field in Jira that will be the event date.
Default time zone (if date/time field is selected) - because a date and time may fall on different dates depending on the time zone, it's necessary to define the time zone to put the event on the correct day.
Time zone (if date/time is selected) - if there is a Jira field to specify time zone for each issue, it can be used here to supersede the default.
Events with date with time - based on a date/time field
When you select a date/time field for event date, Calendar Sync will use the date and time from that field for event start.
The end time can be determined by:
Adding a fixed number of minutes to the start time.
Adding a varying number of minutes to start time (based on a Jira field which holds duration in minutes).
Using another date/time field.
Events with date with time - based on a date-only field
When you select a date-only field for event date, it will be necessary to configure event start time. It's necessary to provide Default start time. You may also select a Jira field for the Start time, which will should have values like "7" or "7:30" ("hh:mm" format).
The end time can be determined by:
Adding a fixed number of minutes to the start time.
Using a fixed end time.
Adding a varying number of minutes to start time (based on a Jira field which holds duration in minutes).
Using another time field (also in "hh:mm" format).
In this case it's also necessary to configure the time zone in order for Calendar Sync to generate events in the desirable time zone.
Date range
In the "Date range" configuration, Calendar Sync will export events with start and end date corresponding to selected date fields. It is intended for use with events that can span multiple days, and for this reason it ignores the time component.
This configuration includes the following fields:
Start date and End date - date or date/time fields in Jira that will be the event start and end date.
Default time zone (if date/time field is selected) - because a date and time may fall on different dates depending on the time zone, it's necessary to define the time zone to put the event on the correct day.
Time zone (if date/time is selected) - if there is a Jira field to specify time zone for each issue, it can be used here to supersede the default.
Repetition
Calendar Sync for Jira supports events that repeat on consecutive days. Use the Number of days entry to select the Jira field which determines how many days the event should be repeated on. The field should be left empty for configuration without recurring events.
Event contents tab
Use Event contents tab to specify which Jira issue fields to include in the event summary and description.
Use the Summary and Description fields to configure contents of event summary and description. In a typical calendar application, summary (and possibly a part of description) is displayed in the calendar, and full description is available in a detailed view after expanding the event.
The configuration for these two fields is very similar in Calendar Sync for Jira. Use the Add field/text button to add a new "chunk" to the respective field. Each chunk can contain value of a Jira field or static text. They will be appended in the configured order. In case of summary, they are joined as is in a single line of text. Description will print each chunk in a separate line, putting field name before the value.
Below you can see an example of how the summary and description are represented in Google Calendar.
Grouping tab
The Grouping tab can be used to make Calendar Sync group issues by user or some other field and put them in separate calendars.
The following grouping options are available:
No grouping - Calendar Sync will generate one calendar containing all events. Use the Access control tab to determine who has access to this calendar.
By user - generating a calendar for every user based on some specific fields such as assignee or creator. If a Jira issue matches more than one user based on the fields selected in this step, it will be included in calendars of all those users. This option enables access control configuration that lets every user see only his or her events.
By some other field - generating a calendar for every distinct value in that field. Use the Access control tab to determine who has access to these calendars.
When grouping by user or some other field, you may also configure Calendar Sync to create an additional calendar containing all of the events. It will be created when you provide the "All" group label. This group will only be available to users who have access to all calendars.
Use the Access control tab to determine who has access to this calendar.
Access control tab
Calendar Sync for Jira offers customizable settings that allow administrators to control user visibility of calendars and the specific events displayed. It seamlessly integrates with Jira's built-in security features, including user groups and roles, as well as issue assignments.
Access to all calendars
Firstly, you may configure which users have access to all calendars. The following options are available.
No one can access all calendars
This option is only available when the feed is configured to group by user. When selected, all users will be able to see calendars with their own issues, and no-one will have access to anyone else's events.
All Jira users can access all calendars
With this option everyone in your Jira instance will be able to see all calendars and events generated for this feed.
Users in specific group(s) can access all calendars
Use this option to allow only users in specific groups to see all calendars.
Users in specific role(s) can access all calendars
Use this option to allow only users in specific roles to see all calendars. It also determines what events each calendar contains.
In Jira, each project maintains its own role assignments to groups and users. A user may be a "Developer" in one project and a "Manager" in another. However, a calendar feed may be configured to cross many projects. Calendar Sync for Jira will only show the calendars to users who have the configured roles in any project, but each calendar will only contain events for projects where this user indeed has the required role.
For example, consider three Jira projects: A, B and C. The calendar feed query matching issues in projects A and B, with role access for Developers.
If a user belongs to Developers in any project (even C), he will see the calendar on his list.
When he downloads the calendar, he will only see the events from projects where he actually belongs to Developers. If he's only a Developer in project A, the calendar will not contain any events from project B.
Access to each user's specific calendar
In addition to the above, when the feed is grouping by user, it may also be configured to allow each user to see only his own events. Users in groups or roles allowed to see all calendars will always be able to see all calendars. However, users who do not have a matching group or role will still have access to their own events.
If the calendar feed is configured in a way that makes some Jira issues match more than one user (e.g. based on two or more user fields), then these issues will be included in calendars of all those users. In other words a single event may be visible to more than one user.
Testing the configuration
At the bottom of the form, you will find a Test button that allows you to review the export results before finalizing any changes. This button becomes available as soon as the form is valid, meaning all required fields have been completed.
For performance optimization, the export will utilize a sample of all issues that match the query. However, the resulting calendars will maintain the same structure as those that will be exported once the configuration is saved. If the issue field designated for the calendar event date is empty for any (or all) issues matching the query, those issues will be excluded from the calendar feed.
