Configuring Feeds

Configuration is available to Jira administrators. Go to Jira settings → Apps → Calendar Sync Admin Page.

Calendar Feeds

The Calendar Sync Admin Page lists every calendar feed on the site along with the status of its most recent export.

The list refreshes itself every 30 seconds, so you can leave it open and watch a feed build.

Status values

An error means the feed could not be exported. The most common cause is an invalid or unrunnable JQL query. If a previous export succeeded, the calendar continues to serve that older data until a rebuild succeeds. See Troubleshooting and limitations.

Actions

• Create new Feed - the button below the grid. Starts a new feed with a clean slate.

• Edit - the pencil icon on a row. Opens the same form used to create a feed.

• Duplicate - the copy icon. Creates a new feed with identical settings and (Copy) appended to the name. The copy is queued for building immediately.

• Delete - the bin icon. You are asked to confirm. Deleting a feed permanently removes its calendars and events, and any subscription to it stops working.

• Global calendar configuration - the button beside the heading. Covered in Administration.

Creating and Editing feeds

Creating a feed and editing one use the same form, laid out across six tabs:

Basic Info → Event Date & Time → Event Contents → JQL Query → Security → Test Configuration

The order is deliberate: set up your date mapping before you write the query, so that when you test the query, you can see the mapped date values in the results.

Use Create Feed / Update Feed at the bottom of the form to save, or Cancel to discard. Validation errors from every tab are listed together at the bottom of the form, so a missing field on a tab you have not opened will still be reported.

Saving a feed queues it for rebuilding immediately.

Basic Info tab

Event Date & Time tab

This tab determines how Calendar Sync for Jira calculates each event's date and time from the fields on a work item.

Start by choosing the Time Type, then the date field or fields it needs.

Start Date Field (required, all time types) - the field that provides the event's start. Only date and date/time fields are offered.

All-day events

Date range

Exports events with a start and an end date taken from two fields. Intended for events that span multiple days.

Work items with a valid start but no readable end date are left out of the feed.

Date time

All events have the same duration - reveals Duration (minutes), a fixed duration applied to every event. Defaults to 60.

Calculate from a field with a duration (in minutes) - reveals Duration Field, a number field on the work item holding the event's length in minutes. Work items where that field is empty, zero, negative or unreadable are left out of the feed.

Use end time from a field - reveals End Time Field, a date/time field that provides the event's end directly.

Timezones

Times are written into the feed with an explicit timezone identifier, following the iCalendar standard, so calendar applications display them correctly in each viewer's own local time. If you do not choose one, UTC is used. All-day events carry no timezone, by design - a whole-day event is the same day everywhere.

Repetition

Calendar Sync for Jira supports events that repeat on consecutive days.

Leave it empty for a feed with no repeating events. Values should be positive integers; a value greater than 1 produces a daily repeat for that many days. Values of 1 or less, and values the app cannot read as a number, produce a single non-repeating event.

Event Contents tab

Specify which information appears in the Summary and the Description of each calendar event.

In a typical calendar application, the summary is what you see in the calendar grid, and the description is visible once you open the event.

Each of Summary and Description is an ordered list of items. An item is either:

• Free Text - static text you type, the same on every event

• Jira Field - the value of a field on the work item

Use Add Content to add an item, the arrow buttons to move an item up or down, and the row actions to edit or remove one. Reset fields restores the defaults. A live Summary preview and Description preview below each list show how the result will read.

How the items are joined:

• Summary items are joined into a single line, separated by spaces.

• Description items are printed one per line.

• A field that is empty on a given work item renders as (empty).

You can add up to 10 items to each of Summary and Description.

Which fields render usefully

Most Jira field types are converted into readable text, including:

plain text, numbers, dates, date/times, users, priority, single-select options, project, work item type, progress, time tracking, team, status, status category, votes, watchers, comment count, and multi-value fields such as labels or linked items.

Rich text fields - Description most notably - are converted to plain text, including @mentions, because calendar events cannot carry formatting.

Long values are shortened: a description is capped at 1,000 characters, and a summary is reduced to a single line.

JQL Query tab

Defines which work items are exported.

JQL Input Method offers two ways to supply the query:

• Manual JQL - type the query yourself. If you want a ready-made query without creating a filter, run a search in Jira, switch to JQL view, and copy the query it produces.

• Copy from filter - search for a saved filter by name, or leave the search empty to list all of them, including your favourites. Selecting one copies its JQL into the query field.

JQL Query (required) is the query itself. It defaults to created >= -30d order by created DESC.

Test Query runs the query and lists the matching work items, showing each one's key, summary and status alongside the actual values of the date, duration and repetition fields you mapped on the Event Date & Time tab. This is the fastest way to confirm your field mapping is picking up real values. If the query is invalid, the error from Jira is shown instead.

A panel at the top of the tab summarises your current date and time mapping and warns you if something required is not yet set.

created >= -365d and 'type' = 'Epic'

The currentUser() JQL function

In Jira you can use the currentUser() function to write queries that return different results depending on who is looking. Such queries should not be used with Calendar Sync for Jira.

Calendar Sync for Jira runs every feed query as the app itself, not as a person. Since the app has no work items assigned to it, currentUser() matches nothing, and the feed comes back empty.

This is deliberate, for performance and for security: the query runs once, not once per viewer. To give different people different calendars, use the Security tab rather than the query. See Common use cases.

Security tab

This tab controls who can see the feed and holds the key that protects its URL. It is covered in full on the Security page; the fields are:

Choose who can access the calendar feed and its calendars

Choosing Users in specific group(s) reveals a User Groups picker.

Choosing Users with specific role(s) reveals a Project Roles selector. Each rule names both a project and a role - you must specify both. A user sees the feed if they hold any one of the named roles in its paired project.

Auth Key (required) - the secret embedded in the feed's URL. Use the refresh button beside it to generate a new random key.

Test Configuration tab

At the end of the form, Test My Feed Configuration shows you the events the current settings would produce, before you commit them.

Each row shows the event's start, its end, whether it repeats, and the summary and description as they will appear. Dates are displayed in your own locale and timezone.

For speed, the preview uses a sample of at most 500 work items, but the events it produces have exactly the same structure as the real export. The preview is not saved anywhere, and it does not create or update a calendar - save the feed to do that, then collect the URL from My Calendars.

Work items with an empty or unreadable date field are excluded from the preview, just as they are from the real export.