Skip to main content

Modern Issue Templates for Jira - User Guide

Introduction​

Modern Issue Templates for Jira is a powerful Forge app that helps Jira administrators create, manage, and automatically apply issue templates across projects. With support for rich text formatting, multi-source imports (JSON, Markdown, GitHub), and automatic template application, you can standardize issue creation and improve team productivity.

Editions​

Modern Issue Templates is sold in two editions on the Atlassian Marketplace. Cloud per-user pricing — free up to 10 users, then a per-user monthly rate that scales down as the team grows (see pricing.csv for the full tier breakdown).

CapabilityStandard (incl. Free ≤10u)Advanced
Template CRUD, rich-text editor, inline editing✓✓
GitHub / Markdown / JSON import + export✓✓
Starter Template Library (22 templates)✓✓
Variables ({{currentUser}}, {{today+7d}}, etc.) + inline validation✓✓
Single + multi-project assignment, conflict detection, re-enable✓✓
Multi-field pre-fill (labels, due date, components, customfield_*)—✓
Full application log (last 50, status filter, CSV export)—✓
{{customfield.X}} variables (roadmap — see issue #5)—planned

Pricing (representative per-user rates — full tiers on the Marketplace listing):

User tierStandardAdvanced
0–10FreeFree
1–100$0.40/user$0.88/user
101–250$0.30/user$0.77/user
1001–2500$0.15/user$0.53/user

Standard users keep all currently-shipped features except multi-field pre-fill config and the full app log depth. Standard preserves existing field configs on templates (they round-trip through the editor unchanged) but does not auto-apply them at create time.

Advanced users see everything. The Advanced lozenge in the UI marks gated sections.

Development / unlicensed installs (e.g., forge tunnel) behave as Advanced — all features available. Real enforcement happens at the Marketplace listing level, not client-side.

Getting Started​

Accessing the Template Manager​

  1. Navigate to your Jira site
  2. Click on the Apps menu in the top navigation
  3. Select Modern Issue Templates from the dropdown
  4. You'll see the template management interface with a table of all your templates

Understanding the Interface​

The template manager displays your templates in a table with the following columns:

  • Checkbox: Select templates for bulk export
  • Name: The template's display name
  • Summary: The template text for the issue summary field (editable inline)
  • Description: A preview of the template description (editable inline)
  • Projects: Project keys where this template is assigned
  • Actions: Quick action buttons (Edit, Clone, Delete, Assign)

Creating Templates​

Quick Start: Starter Template Library​

New installs can skip authoring from scratch by importing from the curated Starter Template Library: 22 pre-built templates across 5 categories (Software Engineering, Operations, Product, Team & People, General). Every template ships with summary + description pre-filled and uses variables like {{currentUser}}, {{today}}, and {{projectKey}} to demonstrate the variable system out of the box.

  1. Click Starter Library in the template manager toolbar (visible in both the empty state and the table view)
  2. Filter by category using the buttons at the top, or browse all 22 templates
  3. Select the templates you want — use Select all visible to grab an entire category
  4. Click Import N templates
  5. Imported templates appear in your table with no project or issue-type assignments — assign them as needed

Imported templates are fully editable. Treat them as a starting point, not a finished product.

Method 1: Create from Scratch​

  1. Click the Create Template button in the top-right corner
  2. Fill in the template details:
    • Template Name: A descriptive name for your template
    • Summary: The text that will pre-fill the issue summary field
    • Description: Rich text content for the issue description
  3. Use the rich text editor toolbar to format your description:
    • Bold, italic, strikethrough text
    • Headings (H1-H6)
    • Bullet and numbered lists
    • Code blocks with syntax highlighting
    • Links and more
  4. Click Save to create the template

Method 2: Import from File​

You can import templates from JSON or Markdown files:

  1. Click the Import Templates button
  2. Select the From File tab
  3. Click Choose File and select your .json or .md file
  4. The app will parse the file and create templates automatically
  5. Templates with duplicate names will be renamed with a number suffix (e.g., "Bug Report (2)")

Supported Formats:

  • JSON: Export files from this app or custom JSON with template structure
  • Markdown: Standard markdown files with optional YAML frontmatter

Method 3: Import from GitHub​

Import templates directly from GitHub. A single From GitHub URL tab handles both repository files and Gists — the app detects the URL type automatically.

  1. Click Import Templates
  2. Select the From GitHub URL tab
  3. Paste a URL:
    • Repository file — e.g. https://github.com/username/repo/blob/main/.github/ISSUE_TEMPLATE/bug_report.md (imports that single file)
    • Gist — e.g. https://gist.github.com/username/abc123def456 (imports all markdown files in the Gist)
  4. Click Fetch to import

GitHub Template Features:

  • Automatically extracts YAML frontmatter metadata
  • Converts markdown formatting to rich text
  • Supports GitHub issue template format
  • Handles multiple files in a single Gist

Editing Templates​

Quick Inline Editing​

For fast updates, you can edit templates directly in the table:

Edit Summary​

  1. Click on any summary cell in the table
  2. The text becomes editable
  3. Make your changes
  4. Press Enter or click outside to save

Edit Description​

  1. Click on any description cell in the table
  2. A rich text editor appears
  3. Make your formatting changes using the toolbar
  4. Click outside the editor to save

Full Template Editor​

For comprehensive edits:

  1. Click the Edit button (pencil icon) in the Actions column
  2. The template modal opens with all fields
  3. Edit the name, summary, and description
  4. Click Save to apply changes

The modal closes immediately while saving happens in the background for a smooth experience.

Managing Templates​

Clone a Template​

To create a copy of an existing template:

  1. Click the Clone button (copy icon) in the Actions column
  2. A duplicate template is created with "(Copy)" appended to the name
  3. Edit the cloned template as needed

Delete a Template​

To remove a template:

  1. Click the Delete button (trash icon) in the Actions column
  2. Confirm the deletion in the dialog
  3. The template is permanently removed

Select All Templates​

Use the checkbox in the table header to quickly select or deselect all templates for bulk operations.

Assigning Templates to Projects​

Templates must be assigned to projects and issue types to work automatically.

Assign a Template​

  1. Click the Assign to Project button (link icon) in the Actions column
  2. In the assignment dialog:
    • Select Projects: Choose one or more projects from the dropdown
    • Select Issue Types: Choose which issue types should use this template
  3. Click Save

View Assignments​

Assigned projects appear as colored badges in the Projects column. If a template is assigned to more than 3 projects, you'll see "+N more" indicator.

How Assignment Works​

When a user creates an issue:

  • The app checks the selected project and issue type
  • If a matching template exists, it automatically pre-fills the summary and description
  • Users can still edit the pre-filled content before creating the issue

Conflict Detection & Re-enable​

Each project × issue-type context can be owned by exactly one template's auto-apply. When you assign a template to a context another template already owns:

  1. Conflict dialog opens listing every conflicting template with the specific contexts at stake
  2. On confirm, the losing template's assignment is marked as disabled (the prior UIM is deleted; a disabledAssignments entry is recorded pointing at the winner)
  3. The winning template takes over auto-apply immediately

Disabled templates surface in three places:

  • Row tint — templates with at least one disabled assignment get a subtle warning background in the table
  • Re-enable button in the Actions column (refresh icon) — only enabled when the template has disabled assignments; tooltip lists every disabled context with the template that replaced it
  • Filter dropdown (top-left of the toolbar) — switch between All, Active only, and Has disabled when at least one disabled assignment exists

Re-enable flow is symmetric to assign: clicking the re-enable button runs the conflict check again. If a new conflict is found (someone else still owns one of the contexts), the dialog shows it. On confirm, all the template's disabled entries clear and auto-apply resumes.

Automatic cleanup: if a winning template is deleted, every disabledAssignments entry pointing at it cascades clear — the prior losers silently become active again without needing a manual re-enable. Editing a template's projects/issue-types also auto-clears disabled entries for contexts that are no longer in its assignment matrix.

Exporting Templates​

Export Selected Templates​

  1. Select templates using the checkboxes in the first column
  2. The Export Selected (N) button appears showing the count
  3. Click the button to download a JSON file
  4. The file is named templates-export-{timestamp}.json
  5. Use this file to back up templates or share with other Jira instances

Markdown and Formatting​

Markdown Support​

When importing markdown files, the app converts markdown syntax to rich text:

  • **bold** → bold text
  • *italic* → italic text
  • ~~strikethrough~~ → strikethrough text
  • `code` → inline code
  • # Heading → Heading levels 1-6
  • - item or * item → Bullet lists
  • 1. item → Numbered lists
  • ```code``` → Code blocks with syntax highlighting
  • [text](url) → Clickable links
  • > quote → Blockquotes

YAML Frontmatter​

GitHub issue templates often include YAML frontmatter at the top:

---
name: Bug Report
title: "Bug: "
labels: ["bug"]
assignees: ["maintainer"]
---

## Description
Describe the bug...

The app automatically extracts:

  • name → Template name
  • title → Summary template
  • labels → Mapped to issue types when possible
  • assignees → Stored as metadata

Template Variables​

Templates support dynamic variables using {{variable}} syntax. Variables are substituted at apply time — when a user creates an issue, the variable placeholders are replaced with real values.

Supported Variables​

VariableDescriptionExample output
{{currentUser}}Display name of the current userAlice Lee
{{currentUserEmail}}Email of the current useralice@example.com
{{currentUserKey}}Atlassian account ID5abc123
{{today}}Today's date (YYYY-MM-DD)2026-06-25
{{now}}Current timestamp (ISO)2026-06-25T12:30:45Z
{{date}}Today's date (locale format)6/25/2026
{{time}}Current time (locale format)12:30:45 PM
{{projectKey}}Project key of the issue being createdENG
{{projectName}}Project name of the issue being createdEngineering
{{issueType}}Issue type nameBug
{{issueKey}}Issue key (available on edit, not create)ENG-42
{{reporter}}Reporter's display nameBob
{{reporterEmail}}Reporter's emailbob@example.com

Date Offsets​

Date variables support arithmetic offsets for due dates and SLA windows:

SyntaxEffectExample
{{today+7d}}Add 7 days2026-07-02
{{today-1d}}Subtract 1 day2026-06-24
{{today+2w}}Add 2 weeks2026-07-09
{{today-1M}}Subtract 1 month2026-05-25
{{today+1y}}Add 1 year2027-06-25

Supported units: d (days), w (weeks), M (months), y (years). Offsets work on today, date, and now.

Variable Validation​

The template editor provides real-time validation:

  • Description editor — invalid variables get a red wavy underline. Hover for details and "Did you mean?" suggestions.
  • Summary field — a SectionMessage error appears below the field showing the first issue.

Common mistakes the validator catches:

MistakeFix
{{todiya}} (typo)Suggests {{today}}
{{today+7x}} (bad unit)"Invalid unit 'x' (use d, w, M, or y)"
{{today+7}} (missing unit)"Offset needs a unit (d/w/M/y)"
{{currentUser+7d}} (offset on non-date)"Variable does not support date offsets"

At apply time, any unresolved variable renders as ⚠️[unknown:name] in the issue fields so failures are visible.

HTML Comments​

HTML comments (<!-- -->) and &nbsp; entities are automatically stripped during import to ensure clean template content.

Template Fields (Multi-Field Pre-Fill)​

Advanced edition only. Standard users can read existing field configs but the editor section is hidden, and templates do not auto-apply fields at create time. Standard's Summary + Description auto-apply still works unchanged. Existing field configs are preserved on the template record (no data destruction on downgrade).

In addition to summary and description, templates can declare a fields map that pre-fills other Jira fields at create time. This is how the Sprint Retro Action Item starter template sets its 7-day due date, and how Bug Report auto-tags issues with the bug label.

The Fields editor in the template modal pairs a field picker (filtered to unused IDs) with a value input. Each row shows a hint explaining what to enter — option fields (priority, components) take a name resolved via Jira lookup; accountId fields (assignee, reporter) take an accountId or {{currentUserKey}}; direct fields (duedate, labels) take the literal value.

Supported Field Types​

FieldExample valueBehavior
labels['bug', 'frontend']Tag-picker UI with Jira label suggestions; direct setValue — string array
duedate'{{today+7d}}'Variable-resolved to yyyy-MM-dd, direct setValue
environment'Production'Direct setValue — free text
priority'High'Name → ID lookup, then setValue (Classic projects only)
components, fixVersions, versions['API', 'UI']Name → ID lookup (project-scoped), then setValue (Classic only)
assignee, reporter'{{currentUserKey}}'AccountId setValue; named values trigger a user search
customfield_*anyDirect setValue; user must know the custom field ID

Variables in field values use the same {{...}} syntax as summary/description and are resolved at apply time.

Project-Type Differences​

The apply loop is project-type-agnostic — it tries to setValue every declared field and silently skips any that don't exist in the current create dialog. In practice:

  • Team-managed projects: priority, components, fixVersions, versions, environment are not exposed by the UI Modifications API. Templates declaring them still work — those fields are skipped, and the rest apply normally.
  • Classic projects: all supported fields are available.

This means a single template (e.g. Bug Report with labels: ['bug'] + priority: 'High') works across both project types without per-type configuration.

Platform-Blocked Fields​

Some fields visible in the Create Issue dialog cannot be set via UI Modifications — Jira's API rejects the write. Templates should not declare these:

  • parent (sub-task context only)
  • startdate (Team-managed next-gen)
  • attachment (requires multipart upload — no setValue path)
  • issuelinks / Linked work items
  • team, issue color
  • status (takes a transitionId, not settable on Global Create)

Starter Templates with Fields​

Nine starter library templates ship with fields pre-configured:

TemplateFields
Bug Reportlabels: ['bug']
Feature Requestlabels: ['feature-request']
RFClabels: ['rfc']
Tech Debt Itemlabels: ['tech-debt']
Incident Reportlabels: ['incident', 'postmortem']
Sprint Retro Action Itemduedate: '{{today+7d}}', labels: ['retro', 'action-item']
Onboarding Tasklabels: ['onboarding']
Offboarding Tasklabels: ['offboarding']
PTO Requestlabels: ['pto']

Importing these from the Starter Library is the easiest way to see multi-field pre-fill in action. Authoring custom fields on new templates is currently JSON-only — a guided authoring UI is on the roadmap.

Automatic Template Application​

How It Works​

Once templates are assigned to projects and issue types:

  1. User opens the issue creation screen
  2. Selects a project and issue type
  3. The app automatically finds a matching template
  4. Summary, description, and any declared fields (labels, due date, etc.) are pre-filled
  5. User can edit the content before creating the issue

When Templates Apply​

Templates apply when:

  • A matching project and issue type combination exists
  • The summary, description, and declared fields are empty (no user-entered content) or still hold the template's last-applied values (idempotency check)

When Templates Don't Apply​

Templates are skipped (and the skip is logged) when:

  • No matching template exists for the project/issue type
  • The user has already typed content into the summary or description
  • The template was already applied to this dialog instance (idempotency — prevents clobbering edits on cancel-and-reopen)

Note: Changing the issue type or project after the initial auto-apply does not re-trigger the template. To apply a different template, the user must cancel and reopen the create-issue dialog.

Sub-task Creation Limitation​

Auto-apply does not fire when creating sub-tasks. Jira Cloud's global Create dialog only lists top-level issue types (Epic, Task, Story) — sub-tasks are created inline from a parent issue or via issue conversion, neither of which opens the create dialog that UI Modifications can intercept. This is a Jira platform constraint, not an app configuration issue, and cannot be worked around.

Application Log​

Depth is Advanced-gated. Standard users see the most recent 10 entries (status only). Advanced users see the most recent 50 entries plus status filter and CSV export. The plan indicator at the top of the modal shows which tier's view is active.

Admins can audit template behavior via the Application Log button on the template manager:

  1. Open the template manager (Apps → Modern Issue Templates)
  2. Click Application Log in the toolbar
  3. Each entry shows:
    • Template name
    • Status: applied (green), skipped (blue), or failed (red)
    • Timestamp
    • Project key and issue type
    • Reason for the decision (e.g., "Field(s) already contain user-entered content")

The log retains up to 7 days of history, capped at 50 entries (FIFO) on read for Advanced users. Standard users see the 10 most recent entries. Use it to debug "why didn't my template apply?" or audit template usage across the team.

A failed status with a reason like setValue rejected for: labels or setValue rejected for: description means Jira refused one of the field writes (typically a FIELD_VALIDATION_FAILED error — e.g. a label that doesn't exist yet, or an option name that doesn't match). The browser console will show the specific field ID that rejected the write, and the full Field apply result: diagnostic breaks down every declared field as applied / failed / skipped.

Storage Reconcile Banner​

In rare cases (typically after a reinstall or a partial data loss), the template records in Forge storage can drift from the Jira-side UI Modification entries that actually drive auto-apply. On page load the app cross-references the two and surfaces a reconcile banner at the top of the template table when mismatches are detected.

The banner explains what was found (orphan UIMs whose template no longer exists, or template records whose UIM is missing) and offers a one-click action to clean up the orphaned side. This is the third layer of orphan prevention — the read path is self-healing (Layer 1), the write path deletes overlaps before creating new entries (Layer 2), and the reconcile banner catches anything that slipped through (Layer 3).

Graceful Degradation​

If anything fails during auto-apply (network error, malformed template, resolver exception), the app logs the failure and lets the user continue creating their issue normally. Template errors never block the issue creation flow.

Tips and Best Practices​

Template Naming​

  • Use clear, descriptive names like "Bug Report" or "Feature Request"
  • Avoid special characters that might cause issues
  • Keep names concise for better table display

Summary Templates​

  • Keep summaries short and focused
  • Use placeholders like Bug: [describe issue] to guide users
  • Avoid overly long summary templates

Description Templates​

  • Use headings to structure the template
  • Include clear instructions for each section
  • Use bullet points for checklists
  • Add code blocks for technical templates
  • Keep formatting simple and readable

Project Assignment​

  • Assign templates to specific projects for better organization
  • Use different templates for different issue types
  • Review and update assignments regularly

Import Best Practices​

  • Test imports with a single file first
  • Review imported templates before assigning to projects
  • Use GitHub imports to leverage community templates
  • Export templates regularly as backups

Troubleshooting​

Template Not Applying Automatically​

Check:

  • Is the template assigned to the correct project?
  • Is the template assigned to the correct issue type?
  • Have you deployed the latest version of the app?

Import Fails from GitHub​

Common Issues:

  • 404 Error: Check the URL is correct and the file exists
  • 403 Error: The repository might be private or require authentication
  • Rate Limiting: GitHub API has rate limits; wait a few minutes and try again
  • Invalid URL: Ensure you're using a direct file URL, not a directory

Formatting Lost After Import​

  • Markdown conversion preserves most formatting
  • Some complex HTML in markdown may not convert perfectly
  • Edit the template after import to adjust formatting

Duplicate Template Names​

  • The app automatically adds (1), (2), etc. to duplicate names during import
  • Rename templates after import if needed
  • Use unique names when creating templates manually

Advanced Features​

Batch Operations​

  • Select multiple templates with checkboxes
  • Export selected templates in one operation
  • Use select all checkbox for bulk selection

Template Versioning (Manual)​

This app does not have built-in version history. To preserve previous versions of a template:

  • Export templates to JSON before making major changes
  • Keep backup JSON files of important templates
  • Clone templates to create variations before editing

GitHub Integration​

  • Import community templates from public repositories
  • Share your templates via GitHub Gists
  • Keep templates in version control alongside your code

Known Limitations​

The following are not currently supported. If you need them, please raise an issue.

  • Parent/epic context in templates — {{parent.*}} variables are not supported. Jira Cloud's Create dialog doesn't expose sub-task creation, so templates cannot read parent-issue fields at apply time. See "Sub-task Creation Limitation" above.
  • Custom field variables ({{customfield.X}}) — not yet implemented. Tracked in issue #5; planned as a Cycle 6 Advanced anchor.
  • Live preview — there is no rendered preview pane while editing a template.
  • Bulk apply to existing issues — templates only apply to new issues created via the standard create-issue screen.
  • Template version history — see "Template Versioning (Manual)" above.
  • Hierarchy templates — generating epic → story → subtask structures from a single template is not supported.
  • REST API / webhooks — templates cannot be applied from external automation tools.
  • Re-trigger on field change — changing the project or issue type after the first auto-apply does not re-apply a different template.
  • Data Center / Server — Cloud-only.

Auto-Apply Context​

The auto-apply UI Modification registers one context per project × issue-type pair. Selecting a project in the assignment modal is required before issue types can be selected — the issue-type list is fetched per project.

Support and Feedback​

If you encounter issues or have suggestions:

  1. Check this guide for troubleshooting steps
  2. Review the app logs in Forge CLI if you're a developer
  3. Contact your Jira administrator for assistance
  4. Report bugs or request features through your organization's support channels

Version: 1.5 Last Updated: July 2026