Improving issue creation with a Jira description template

Issue Template

August 15, 2024
·
8 min

It’s much easier to work on a Jira issue if the person who’s created it has provided all the required information. Too often, a team will open a Jira ticket and not have everything they need to progress it.

Here are some examples of the sort of information you might want in the Jira description field on a ticket:

If the ticket is for a bug, the reporter should describe what systems it’s affecting, and what steps the IT team need to take to reproduce it, so that they can isolate the problem.
If the ticket is a request for new hardware/software, the reporter needs to explain what they need and why they need it so that the IT team can process the order.
If the ticket relates to a new employee, details about why the employee is needed and how the recruitment contributes to the company’s goals will help the HR team justify the hire to senior management.
If the ticket is a user story, it should include acceptance criteria so that the software team know exactly what they need to do to meet the user’s expectations.

To make sure all this information is provided, it would be helpful if the description field in Jira had a bit of default text that displays when you’re creating the issue. In other words, a template. That way you could guide the user to fill out the description properly.

Sadly, standard Jira doesn’t let you add a default description to the issue create screen in a company-managed project. This is because the description is a system field that can’t be changed or customized.

So let’s explore the options available to you if you’re looking for a Jira description template.

The Jira automation workaround

One way of pre-populating the Jira description field is with Jira automation, i.e. you could create an automation rule that adds a default description to particular issue types. However, your default description won’t display live on the issue create screen because the trigger for the automation rule will be the creation of the issue. Therefore, the default text will only appear after the issue is created, and you’d need to edit the issue post-creation to see the text and change it.

That’s not to mention the complexity of Jira automation or the fact that only admins can configure automation rules.

The Jira custom fields workaround

Out of the box, the closest thing you can do to pre-populating the Jira description field on the issue create screen to create a custom field instead. You’d need to set up the field configuration to have a wiki-style renderer before adding a default description to it. Then you’d need to create a context for the field and add it to screens. Finally you’d need to hide the system field so that you don’t end up with two descriptions on your tickets. And if you want to continue working with the system field, you’d need to use a post-function that copies the text from the custom field to the system field before deleting it.

As you can see, this workaround is basically a nightmare, requiring some complex configuration and wasting a ton of time. What you really need is a way of manipulating the built-in description field. No one wants to add and manage new custom fields unnecessarily.

Changing how Jira fields behave

Jira allows you to define the behavior of all fields – system fields and custom fields – using field configurations.

But the standard field configurations only go so far. They allow you to:

Change the description that appears under the field when the issue is created or edited, aka ‘help text’, and customize them for different issue types
Hide or show the field on different issue types
Set a field to be optional or mandatory; mandatory means that the user must give the field a value
Change a field’s renderer, which control the style in which the content of a Jira field is displayed

As you can see, the native field configurations don’t allow you to add default text to the Jira description field. They only allow you to put some help text beneath it.

However, there are apps on the Atlassian Marketplace that give you added control over fields in Jira. These apps allow you to create behaviors for your fields to help users fill out tickets correctly and comprehensively.

Two apps that offer Jira behavior customization

One of the most popular apps for creating behaviors for Jira fields is ScriptRunner. You can do a lot of things with ScriptRunner behaviors, including setting default field values.

The problem with ScriptRunner behaviors is that you need to do a bunch of coding. Count me out then! Personally, I wouldn’t touch a coding app with a very long barge pole. Even Jira Query Language (JQL) is too much for me.

Another app, which is better for non-technical users and coding-phobes like me, is Templating.app for Jira. Templating.app allows you to build templates for Jira issues, Jira issue create screens, hierarchies of Jira issues, and Jira projects.

You can build templates for Jira issue create screens with Templating.app’s behaviors feature, which is very similar to ScriptRunner’s. It allows you to customize Jira field behaviors for different projects, issue types, job roles, and more. Where it differs from ScriptRunner is that you don’t have to write a single script or line of code.

With Templating.app’s behaviors feature, you can:

Change field names, including system fields such as summary and description
Change field descriptions/helper text and customize them for different job roles, components, priorities, and other field inputs – not just issue type
Show/hide fields according to job role and other field inputs – not just issue type
Set default field values

If you want to make Jira description templates so that your users provide the same information each time they make a ticket, it’s this last behavior you’re going to care about.

How to make a Jira description template with Templating.app

You can use Templating.app to make a Jira description template in a few clicks, using only dropdowns and free text. Let’s look at creating one for a bug.

First, go into the behavior builder feature in the app and click Add template. You’ll be presented with a screen that lets you specify the field behaviors for the issue create screen across whichever projects and issue types you select.

Let’s say you’ve selected the bug issue type, so that your predefined description appears when a user creates a bug. You could then specify conditions such as the default description only appearing when a user selects “Highest” as the priority, so that you’re gathering the most detailed information about critical bugs only.

Then you simply add the modifications that you want to appear on the issue create screen when that condition is met. The modification in this case is “Set field value”. You select the field, “Description”, and add the text you want to appear by default on the ticket. For example:

You could add additional modifications such a default assignee, to make sure the right person handles the most important bugs. And you can add alternative modifications, e.g. if the priority is not set as “Highest”, the field automatically changes to “Lowest” and the predefined description and assignee change along with it. You could have a shorter default description because the same level of detail isn’t needed, and the default assignee could be someone in charge of distributing low-priority bugs among team members.

Have a watch of our step-by-step guide to creating templates for your Jira issue create screens for more detail.

To summarize (TL;DR)

Out of the box, you cannot have default text in the Jira description in a company-managed project.
As a workaround, you could create a custom field with a default value, and then delete the built-in description field, but this is complex and requires a lot of configuration.
There are two apps on the Atlassian Marketplace that offer enhanced control over Jira fields and allow you to create custom issue create screen templates: ScriptRunner for Jira and Templating.app for Jira.
ScriptRunner’s behaviors feature requires the user to write code to customize how fields behave.
Templating.app’s behaviors feature is code-free.
With Templating.app, you can create a default description template that appears when certain conditions are met, e.g. the user selects “Bug” as the issue type and “Highest” as the priority.
You can also show/hide fields and change field names and helper text according to any number of conditions, including job role and component.

If you want to create Jira description templates or customize other fields on the issue create screen, book a personal demo of Templating.app or try the app for free on the Atlassian Marketplace.

Save time on repetitive tasks in Jira

Templating.app is your all-in-one Jira project management tool for custom Jira Issue templates, subtask templates & project templates

Let's get in touch 👋

Verschlagwortet mitIssue Template