Issue Templates & Create Defaults documentation

Templates for new Jira issues, and defaults that fill in Jira's own Create dialog. What administrators set up, what people see, and what the app keeps.

Documentation for Mermaid Studio Recurring Requests Issue Templates

The app fills in a new issue's summary, description, checklist, labels and priority from a template. People pick a template from a gallery, or Jira's Create dialog starts from one by itself for the issue types you choose. Once someone writes their own summary or description, the app writes nothing more to that form.

It adds no custom fields, and it never changes an issue after it has been created.

On this page

• Getting started
• Making a template
• Automatic defaults in the Create dialog
• The Templates gallery
• Save as template
• Who can do what
• The health check
• The daily check and the alert issue
• Version history
• Recently deleted
• Usage counts
• Limits, and where defaults do not apply
• Licensing
• Your data, and uninstalling

Installing the app changes nothing in the Create dialog. Until a template is set to fill in automatically, the app only adds its pages and its daily check. The pages are a Templates page in each project, the same gallery under Apps, Save as template in each issue's ••• menu, and the pages where templates are managed. The daily check looks at your templates once there are any; see The daily check.

Templates are managed in two places:

• Jira settings → Apps → Issue Templates & Create Defaults — every template on the site. Only Jira administrators can open it.
• Project settings → Templates — the templates used in that project. Project administrators manage their own project's templates here without needing a Jira administrator.

A first template:

• Choose New template. Give it a name, choose the projects it can be used in (on a project's settings page it is for that project), and the issue types it is for.
• Under Fill in automatically when creating, choose the issue types that should start from this template. Leave it empty for a template people pick by hand.
• Fill in what new issues should start with, and choose Save template. The Create dialog in those projects is updated as you save.
• Try it: press Create in one of those projects and choose that issue type. The fields fill in after a few seconds.
• Under Will every template work?, press Check now. It tells you whether each template works in every project it is for.

The quickest start is often an issue you already like. Open it, choose Save as template from its ••• menu, and tick the box to fill in that issue type automatically. See Save as template.

The editor has these parts.

A template needs at least one thing to fill in: a summary, a description, a checklist, labels or a priority. Text over a length limit is cut to fit, and items over a count limit are left off, when the template is saved. A site can hold up to 200 templates.

Saving updates the Create dialog. When you save or delete a template, the app rewrites the Create dialog settings of each project it is in. If a project cannot be updated, the page says which one and why. Rebuild Create dialog settings, below the list of templates, does the same when you ask: for every project a template is used in, from the Jira admin page, or for one project from its settings page.

Delete asks you to click again before it deletes. A deleted template can be restored for 30 days; see Recently deleted.

When someone opens Jira's Create dialog in a project and chooses an issue type that has an automatic default, the app fills in the summary, the description with its checklist, the labels and the priority from that template. It runs again when the person changes the issue type or moves to another project that has automatic defaults, and after each issue created with Create another ticked. A form opened from the gallery is different; see The Templates gallery.

Filling takes a few seconds. Jira shows the dialog first and runs the app once it has loaded, with a small spinner next to each field the app may fill. Until the app has finished, the fields show as they were.

What it writes, and when it stops

• An empty form is filled from the issue type's default.
• Changing the issue type swaps the default. While the form still holds only what a default wrote, switching from Bug to Task replaces Bug's text with Task's default. If Task has no default, the app clears what Bug's default wrote. Jira may keep the summary when the app empties it. If Bug's summary is still there, delete it by hand. The app still knows it is Bug's text, so switching back to Bug fills the form again. A rare exception in a tab that used the gallery is under Limits.
• Typing makes the form the person's. Once the words in the summary or the description differ from what a default writes, the app writes nothing more to that form, whichever issue type is chosen. When the issue type changes after that, it also takes its notes off the form. It compares the words, and the images, @mentions, emoji, dates, status lozenges and link cards in the description, so pasting a screenshot counts as the person's work too. A change to formatting alone still counts as the template's text and can be replaced when the issue type changes. That includes making text bold, ticking a checklist item, or adding spaces at the end of the summary. Emptying a field is not writing either: a summary or description cleared by hand still counts as the app's, and can be filled again when the issue type changes.
• Moving to another project. The app recognises only the defaults of the project now chosen. Text that the other project's default wrote counts as someone's work there, so it is not replaced. The exception is a template that is also a default in the new project: its text is recognised there and can be replaced.
• Labels are judged on their own. Even while the summary and description are still the app's, labels are replaced only while they are empty, or exactly the labels of one of the project's defaults.
• Only four fields. Summary, Description, Labels and Priority. Nothing else on the form is touched, and a field that is not on the form is skipped.

Priority

The app sets a template's priority only while the priority on the form is the project's default priority, or the one set by the template whose text is showing. When the person switches to an issue type whose default sets no priority, or that has no default, the app puts the project's default priority back, as long as the priority is still the one the previous template set.

A known limit. If someone picks, by hand, exactly the project's default priority, or exactly the priority of the template whose text is showing, the app cannot tell that pick from its own. It can be replaced on the next issue type change. Labels set by hand to exactly a template's labels, or cleared by hand, behave the same way.

The app reads each project's default priority from Jira when it rebuilds the Create dialog settings. If Jira's default changes later, the health check says so. If the app could not read Jira's priority schemes at the last rebuild, it cannot tell the default apart: it then sets a template's priority whenever it fills the form, and does not put the default back.

The note on each field

On every field it fills, the app adds a note that says where the value came from. For a template called "Bug report":

• Summary and description: Filled from the "Bug report" template. Write your own, and it steps back. When the person changes the field, the note becomes Edited by you: the template leaves this form alone now.
• Labels: Filled from the "Bug report" template. When the person changes them, the note becomes Edited by you.
• Priority: Filled from the "Bug report" template. The note is removed when the person picks another priority.

A field the person empties loses its note. In text fields the note changes when the person leaves the field, not on every keystroke.

After an issue type change. Jira starts the app afresh each time the issue type or the project changes, so the app cannot tell which fields the person changed before. Edited by you appears only for a change the app sees after that. If the person has written their own summary or description, the app takes all its notes off the form and adds none while they go on editing. If the form is still the app's and the new issue type has a default, only the fields that hold that default's values get a Filled from note.

Each note speaks for its own field. Only the summary and the description decide whether the form is the person's. Changing labels or priority alone does not make it theirs: if the issue type then changes, the summary and description can still be swapped. For when picked labels or a picked priority can still be replaced, see Priority.

Where the note shows depends on the dialog. In Jira's compact Create dialog it sits behind the small (i) icon next to the field's name. In the full Create dialog it shows under the field. If an administrator already wrote help text for the field, that text stays, and the note is added after it.

Each project gets a Templates page. In current Jira it appears as a tab in the project's navigation. It lists that project's templates, whether or not they fill in automatically. The same gallery, for every project the person can see that has templates, is under Apps in Jira as Issue Templates & Create Defaults.

Each template shows its name and summary, how many checklist items and which labels it has, and which issue types it fills in automatically. Choose the issue type if more than one fits, then Create.

Create opens Jira's own Create dialog with the summary, description, checklist, labels and priority filled in. The person can change anything before creating. Jira then does what it always does: its permissions, required fields and workflow apply, and the app never creates the issue itself. Afterwards the gallery shows the keys of the issues created.

A template picked in the gallery is left as picked, even if the issue type is changed, and the app adds no notes to that form. Once the person edits the summary or description, the form is theirs, as in any other Create dialog. The few cases where a pick is not recognised are listed under Limits.

Anyone who can see a project can open its gallery. Only issue types the person can see are offered, and subtask types never are. Creating the issue still needs Jira's Create issues permission. With no templates to show, the page says No templates here yet and explains who can add them.

Open an issue and choose Save as template from its ••• menu. It makes a template from the issue's description and labels, and its priority if you choose. The issue itself is not changed.

Jira administrators can use it on any issue, and project administrators on issues in their project. Anyone else who opens it is told who can.

• Template name starts as the issue's summary, cut to 80 characters.
• Summary new issues start with is empty until you fill it in, for example "Bug: ". The issue's own summary is not used for new issues.
• Use this issue's description, with its formatting is on. A preview shows what will be kept.
• Labels is on and Priority is off, when the issue has them.
• Fill in every new Bug in KEY with this automatically is off. Tick it to make the template the automatic default for that issue type in that project.

The template is made for the issue's project and issue type. If the issue is a subtask, the template is for any issue type in the project, and it cannot fill in automatically.

What is kept, and what is left out

Kept: paragraphs, headings, bullet and numbered lists, code blocks, quotes, dividers, panels, tables, action items (unticked again), decisions, expands, emoji, status lozenges, dates and link cards, with bold, italic, underline, strikethrough, code, links, subscript, superscript, text colour and highlight.

Left out, and counted in a Left out: line under the preview:

• @mentions, because they identify people.
• Attachments and images, because the files belong to that issue.
• Links to a person's profile, email links, and email addresses in the text. A text link keeps its words and loses only the link. An address in the text is replaced with "[email removed]".
• Content from other apps, such as their macros.
• Anything else a template cannot carry, such as layout columns, which are left out together with what is in them.

The alignment and indentation of paragraphs and headings, and any other formatting not listed above, are not kept either, and are not counted.

Read it before saving. The cleaning finds mentions, profile links and email addresses, and it runs only on a description saved from an issue. Nothing else is scanned: not the template name, summary, checklist or labels, and not a plain description typed in the editor. A name written as ordinary words stays, and the template name starts as the issue's summary. If either names a person, change it.

A very long formatted description is refused, with a message asking you to shorten it on the issue or use a plain description.

Before it opens a management page or changes a template or a setting, the app asks Jira what the person may do. Two roles matter: Jira administrators, who have Jira's Administer Jira permission, and project administrators, who have Administer projects in that project.

A shared template is one used in more than one project. Sharing is changed only on the Jira admin page. A template a project administrator makes belongs to their project alone.

A project's settings page shows only templates used in that project, and its health check looks at that project only. It does not show a project administrator the names or keys of other projects a shared template is used in, only their numeric project ids.

Everyone else: anyone who can see a project can use its gallery, and anyone with Jira's Create issues permission there gets the automatic defaults in the Create dialog.

Below the templates, Will every template work? → Check now tests each template in each project it is for. It only reads; nothing is changed. Each template is marked works, check or broken, with a line for each problem and its usage counts.

On the Jira admin page it covers every template, in up to 60 projects per check; if there are more, the page says so, and the daily check covers up to 1,000. On a project's settings page it covers that project.

What it can report, and what to do:

It does not check whether a template's priority is in the project's priority scheme, or whether the create screen has a Summary field.

After adding an issue type to a project that has automatic defaults, press Rebuild Create dialog settings. The app runs for the issue types a project had when its settings were last rebuilt, and rebuilding adds the new one, so switching to it is handled like any other type without a default.

Once a day the app runs the same check by itself, across up to 1,000 projects. It cannot be switched off, but it pauses without an active licence (see Licensing). It changes nothing in your Jira configuration, and it records nothing about who uses the app. With the alert switched on, it also creates one issue when it finds something new; see The alert issue.

When it finds a problem that was not there at the previous check, it lists it under Daily check → Recent findings at the bottom of the Jira admin page, and a banner at the top of the page says so until someone chooses Dismiss. A problem is reported once, and not again while it stays the same. If it clears and later comes back, it is reported again. The first check reports every problem that already exists, once, as its starting point.

If Jira was busy or failing during a check, that check records nothing, and the next one compares with the last complete check.

Run the daily check now runs it straight away, so you can see the result without waiting a day. It counts as a check: what it finds is not reported again the next day.

The alert issue

Off by default. To be told in Jira as well:

• Switch on Also create a Jira issue when something stops working.
• Choose the Project for alert issues and an Issue type. Pick a type that needs nothing but a summary and a description, because those are the only fields the app fills.
• Choose Save, then Send a test alert. It creates an issue called "Issue Templates: test alert (nothing is wrong)", so you can see where alerts will land. Its description only explains that it is a test. Delete it afterwards.

A real alert is called, for example, "Issue Templates: 2 templates stopped working", counting the templates affected. Its description lists each template with a Broken or Check line for each problem, and says where to fix them. It holds template names, project names and keys, and issue type names, and nothing about who uses the app. The app creates the issue as itself.

An alert issue is created only when a check finds something new that has stopped working, and a check creates at most one. That includes a check started with Run the daily check now. If Jira refuses to create it, for example because the issue type needs another field, the reason is shown under Recent findings and those problems are not sent again. That is why the test alert is worth sending first.

Alert issues are the only issues the app ever creates. It never edits or deletes an issue.

History on a template lists its saved versions, newest first: the version number, the date and time it was saved, and what changed, such as "changed summary, labels" or "restored version 3". Who saved it is not recorded.

Show displays a version. Restore this version saves it again as the newest version, so going back loses nothing: the version you left stays in the list. A restore goes through the same checks as any save. For example, it is refused if another template has since become the automatic default for the same issue type.

The last 50 versions of each template are kept. A save that changes nothing adds no version. History is open to whoever may edit the template.

A deleted template stops filling in straight away and appears under Recently deleted for 30 days. Restore brings it back with its history and usage counts, and puts it back into the Create dialog. After 30 days it can no longer be restored, and it is removed together with its history and counts.

The Jira admin page lists every deleted template. A project's settings page lists, for its project administrators, the ones that belonged to that project alone.

Each template, in the list of templates and in the health check, shows a line such as Used: filled in automatically 12 times, created from the gallery 3 times · last 22 Sep 2026, or Not used yet. These are numbers and a date. Nothing records who used a template.

• Filled in automatically goes up each time the Create dialog wrote the template's own summary or description. Refills count too, such as switching back to the issue type or creating another issue with Create another ticked, so it counts fills, not issues created. Clearing another default's text is not counted, and a default that sets only labels or a priority is never counted.
• Created from the gallery goes up once each time someone pressed Create on the template in the gallery and created at least one issue from that dialog.
• Counts can come out slightly low, because two uses at the same moment may be counted as one.

Only in Jira's Create dialog. The app fills in the Create dialog, and the gallery opens that same dialog filled in. Issues created any other way are not filled: inline on a board, backlog or list, by email, through the REST API or Automation rules, by import or cloning, from the mobile apps, or from a service project's portal.

Atlassian lists these ways into the Create dialog: the Create button, the c keyboard shortcut, and an app's own Create button, like the gallery's. Add a child issue and Create subtask open it only when the issue type requires a summary and at least one other field.

• Four fields. Summary, Description with the checklist, Labels and Priority. Not assignee, components, due date or custom fields.
• No subtasks. Subtask issue types are never filled in automatically or offered in the gallery.
• Project types. Atlassian documents the Create dialog support this app uses for company-managed and team-managed software and business projects. Service projects and Jira Product Discovery are not on that list, and we have not tested them.
• A few seconds. The form fills a few seconds after the dialog opens. Until then it shows as it was.
• A priority or labels picked by hand can be replaced. A priority picked by hand that is exactly the project's default, or the priority of the template whose text is showing, looks like the app's own. So do labels set by hand to exactly a template's labels, or cleared. They can be replaced on the next issue type change. If the app could not read Jira's priority schemes at the last rebuild, any priority picked by hand can be replaced by a template's priority on the next issue type change. See Priority.
• Jira may keep a summary the app empties. When the app clears a default's text, the summary can stay on the form. Delete it by hand.
• Formatting-only edits count as the template's text. The app compares words, and the images, @mentions, emoji, dates and link cards in the description, not formatting. So making text bold, ticking a checklist item or adding spaces at the end of the summary does not make the form the person's, and neither does emptying the summary or the description. The template's text can still be replaced when the issue type changes.
• Gallery picks. The gallery marks its pick in that browser tab, and a Create dialog in another tab never sees the mark. If the browser blocks site storage for apps, a pick is not recognised: a picked template that is also an automatic default is treated as that default, gets notes, and can be swapped or cleared as soon as the dialog opens on an issue type it is not the default for, or when the issue type changes. The same can happen on an issue type change more than two hours after the pick. A template with only labels or a priority is not recognised as a pick, so an automatic default for that issue type fills in around it. Rarely, in the same tab, for up to two hours after a gallery dialog that Jira did not report closing, a Create dialog showing exactly that template's text is treated as the pick and left alone.
• Fields someone has hidden. A field a person hid with Show fields in the Create dialog is not passed to the app, so it is not filled.
• Other apps. Up to five apps can change the Create dialog at once. If two change the same field, the one that finishes last wins.
• Issue types are matched by name. If you rename an issue type, edit the templates that name it. The health check lists them.
• The checklist is Jira's own action items in the description, not a separate checklist field.
• Numbers. 200 templates per site. 50 projects and 30 issue types per template. One automatic default per issue type per project. Project lists and the Apps gallery show up to 500 projects. The priority list shows up to 50 priorities. A check from the page covers up to 60 projects, the daily check up to 1,000.
• One project's defaults together must fit in Jira's limit of 50,000 characters for Create dialog settings. If they do not, the template is still saved, but that project's Create dialog is not updated and keeps its previous settings. The page lists the project with The default templates for this project are too long for Jira to carry.

Without an active licence, for example after a subscription ends:

• Templates cannot be saved, restored, or made from an issue.
• The gallery shows This app needs an active licence.
• The Create dialog is not filled, and no notes are added.
• The daily check does not run on its schedule.

Your templates are kept. The admin and project pages still open, with a warning, so you can see your templates and their history, delete them, and run the health check.

The app records nothing about the people who use it. It keeps templates and numbers. It never records who made, changed, used, restored or deleted a template, or anyone's account ID. A template holds whatever your administrators type into it or copy from an issue, so it holds personal data only if someone puts it there. See Save as template for what is taken out of a copied description.

Not kept anywhere:

• Who created, edited, restored, deleted or used a template. The app adds no account IDs, names or email addresses of its own. A template holds them only if someone types them in or copies them from an issue. From a copied formatted description, Save as template removes @mentions, attachments, other apps' content, profile and email links, and email addresses. A name written as ordinary words stays (see Save as template).
• What people type in the Create dialog. The app looks at it in the browser only to tell its own text from theirs.
• Which issue a template was saved from. Its key is not kept, only what you chose to copy into the template. The keys of issues created from the gallery are not kept either.

Nothing is sent outside Atlassian. The app declares no outside connections, and every request it makes goes to your own Jira site or to the app's own functions on Atlassian's platform.

Data residency

In scope: everything the app keeps in Forge storage. That is templates, their versions, deleted templates, usage counts, and the daily check's settings and findings.

Out of scope: the Create dialog settings, which Jira stores through its UI modifications feature, and alert issues, which are ordinary issues in your Jira project. Neither is kept in the app's storage. Nor are the error log lines, or the picked template's text that the gallery keeps in the person's browser tab while its Create dialog is open. Both are listed in the table above.

Uninstalling

Once the app is uninstalled, the Create dialog is no longer filled, and its pages, the gallery and the daily check are gone. Alert issues stay, because they are ordinary issues in your project.

The app has no step of its own that erases data when it is uninstalled. Its Forge storage belongs to its installation on your site, and what happens to it afterwards follows Atlassian's rules for Forge apps.

To take the Create dialog settings out of Jira before you uninstall, clear Fill in automatically when creating on every template, or delete the templates. The app removes a project's record as soon as the project has no automatic defaults.

More in our privacy policy.

Email [email protected] with the template name, the project key and issue type, and what you expected to happen. What the health check says helps too. Response targets are in our service level agreement.