‍

‍

In my last article for Jira Software, Jira Work Management, and Jira Core, we discussed creating custom screen templates to reduce the number of screens in your application and ensure consistency between Jira projects.

This time, we’ll discuss creating similar request templates in Jira Service Management (JSM).

Good to Know

For this article, I’ll use a JSM company-managed project created with a built-in IT service management template in Jira Cloud. However, the concepts in this article apply to any JSM project in any deployment type, regardless of its specific settings or how it was created.

‍

Important Terms

Before we dive into creating templates, here are some JSM-specific terms to know.

An issue is an individual item in all types of Jira. Each time you create an item, you create a new issue with a unique key to identify it. An issue is any individual record in the Jira database.

‍

‍

A request is how Jira issues are represented to Jira Service Management customers and end users on the self-service portal. In other words, a request is a simplified view of issue data.

‍

‍

Issue vs. Request

Here’s an example trouble report for a problem with a database server.

‍

‍

‍

The unique key for this trouble report is IT-6, and that ID is shown at the top of both views. Both screenshots show the same information, but how it is displayed differs for different audiences. The comprehensive view on the left is intended for use by support team members, while the simplified view on the right is intended for customers or end users. There’s only one unique record in the database for this trouble report.

What is a ticket?

A ticket is simply another word for a “request” created by a customer or end user in Jira Service Management. Users of other popular services and ticketing software often call records created by end users “tickets.” For the purpose of this templating article, you can think of a Jira ticket template as the same thing as a Jira request template.

‍

‍

JSM Request Types

In the previous article, we built custom templates for creating, editing, and viewing Jira issues. Let’s apply the same concept to building templates for the related request types in JSM.

A Jira Service Management project has the same issue type screen scheme, screen scheme(s), and screen(s) as a Jira Software or Jira Work Management project.

‍

‍

These screens control how issues look to support team members fulfilling requests.

Additionally, JSM projects have request types to determine how issues look to end users in the customer portal. To access them, visit the project’s settings area and click the “Request types” link in the left sidebar. Note: If your service project was created using an ITSM template, the request types may be organized in an additional
“Work Categories” menu, as shown in the screenshot. For this example, I’ve selected the “Incidents” menu option, which contains two request types.

‍

‍

‍

Screen and Request Type Analysis

As usual, we should compare the default settings before making changes. It is important to understand what already exists before customizing or adding additional elements. This article will use the incident issue type as an example.

The incident screen scheme contains two screens: “IT: Jira Service Management: Incident View/Edit Screen” and “IT: Jira Service Management: Incident View/Edit Screen.”

‍

The create and view/edit screens both contain the same twenty-two fields, including Summary, Issue Type, Components, Attachment, Description, Reporter, Linked Issues, Assignee, Priority, Labels, Request Participants, Approvers, Organizations, Affected Services, Affected Hardware, Urgency, Impact, Severity, Pending Reason, Source, Product Categorization, and Operational Categorization.

‍

‍

If users plan to report incidents within Jira, twenty-two fields are way too many for a create screen! But since most incidents are reported in the Jira Service Management portal, I’ll leave the create screen as is.

Next, let’s compare the fields on the Jira issue create screen to the fields on the “Report a system problem” portal request form. Luckily, the request form is simplified and less intimidating for the end user to complete.

Here’s the configuration page of the request form. It contains only six fields, including: Summary, Description, Affected Services, Attachment, Urgency, and Impact.

‍

‍

Next, I recommend reviewing all the fields on your application’s request forms and removing any that aren’t necessary for issue creation. For example:

• Does the requestor have enough knowledge to select the correct affected service?
  
• Would the requestor know whether the impact of the incident is localized or widespread?

If the answers to these questions are usually “no,” I’d remove these fields and have a support team member select their values later in the issue’s life cycle.

Additionally, is there any other information that should be collected but isn’t? Sometimes, I create a custom date field called “Needed by” to collect a user's requested response or completion date. This date is often different from the Jira standard “Due Date” field. “Needed by” represents a wish, and “Due Date” reflects reality.

Build a Jira Ticket Template

Now that we’ve reviewed an example of fields on a default JSM incident request form let’s build our own template for our organization’s needs and to reuse it for additional incident reports or between projects.

For Jira Cloud

Build a Form

Login as a Jira application administrator or a project administrator with JSM “agent” permissions. Then, visit the “Request types” page in the project settings area. Create a new blank form by clicking the “Create request type” button on the top right.

‍

‍

I’ll name the new request form Custom default: Incident request form, which matches the naming format I use for my custom default screens.

Tip: Decide on a common naming format that helps fellow Jira administrators and JSM agents understand the purpose of request forms and settings.

‍

‍

The form’s “Name” and “Description” are customer-facing, but I’ll change them later when creating a new request form from this template. For now, I’ll just provide helpful information for the admin audience. To the right of the “Description” field is the form’s icon. I either choose an image representing the request type or one that signifies that this form is a template. The “Portal group” field determines which category the form is displayed in in the portal. For Jira projects built with an ITSM template, the selections are “Common Request,” “Computers,” “Logins and Accounts,” “Applications,” and “Servers and Infrastructure.” In other JSM projects, the groups may be “General,” “Hide from portal,” or other custom portal groups. Depending on the number of forms in your project, you can display zero, one, or many portal groups. The last field, called “Issue type,” is used to associate a JSM request form with a Jira issue type.

Important: Make sure to select the correct issue type. Unfortunately, you cannot change it later. I hope this feature will be developed in the future.

Add Fields to the Form

Next, add a small number of fields to collect the initial incident information. I’ll add: Summary, Description, Attachment, Urgency, and a custom field called Scope. Here is what each field does, why I selected it, and any related tips.

Summary

This field holds the request and issue’s “title.” Jira and JSM require it. Encourage users to provide meaningful, keyword-rich information that conveys purpose and helps them find the issue again later.

Description

This field collects the request’s details. Consider making this field required so you receive actionable information. You also may need to add some example copy to suggest what level of detail to provide.

Attachment

Used for additional non-text information like screenshots, forms, diagrams, etc. This field is best used as a supplement to the description when necessary. Don’t require this field unless a file is needed for every use case.

Urgency

This JSM standard field is similar to the Jira standard “Priority” field, except it contains selections like low, medium, high, and critical. I use this field to collect the requestor’s urgency perception and the “Priority” field to collect the support agent’s perception, which sometimes differs.

Scope

This custom field lists all the types of users who may be impacted. The end user might not know the complete scope of the incident, so I generally don’t require this field. A support team member can complete the field or correct it later. I find this information useful for calculating incident impact.

Field Settings

Click the down arrow next to each field to customize its settings.

‍

‍

Tips

Sometimes, Jira field names are confusing to end users. The portal provides the ability to display your own user-friendly language instead. Customizing field names, descriptions, and workflow status names on the portal side does not impact the same data on the Jira side. As such, in the portal:

• I change the title of the “Summary” field to something like “How can we help?” “What incident occurred?” or simply “Incident title.” I also provide a display description when it’s helpful.
  
• I like Atlassian’s suggested title of “Describe what happened and how it occurred” for the “Description” field, so I added it. I also added a custom display suggestion to remind users to include attachments when applicable.
  
• I made the “Description” field required by clicking the checkbox at the bottom right.

‍

‍

Instructions Feature

Jira Service Management has many opportunities to provide information, reminders, and alerts in the portal. In addition to portal-wide welcome text, a project-specific announcement banner, the request’s description, and field-level descriptions, there is also form-level instruction text.

The “Request type description” field appears anywhere requests forms are listed. The “Instructions” field, however, appears at the top of each individual form.

‍

‍

Tips

• Some fields, like “Instructions,” accept wiki markup formatting. In the example screenshot, the words “internal” and “vendor” are bolded using asterisks. The URL is enclosed in brackets, making it clickable.
  
• Remember to save your changes. There’s a single save button for all form settings at the bottom of the request form. (It's not pictured.)

Hide the Template

Once the request form template is built, you’ll want to hide it from end users. Go back to the list of request forms, click the ellipses to the right of the form, and select the “Edit” option under the “Portal groups” header.

‍

‍

In the “Assign to Portal Groups” overlay, uncheck all groups. Request forms not in any portal groups are automatically hidden from the portal. The form is also moved to the bottom of the list in the request types configuration area.

Apply a Jira Ticket Template

The ticket template makes it easy to use the next time you need a new incident request form. Simply copy it by clicking the ellipses icon and selecting the “Duplicate” option. Then, update the form’s name, request type description, portal group, and any other settings as desired.

‍

‍

For Jira Data Center

Build a Document

Unfortunately, Jira Data Center does not have a request form duplication feature. Instead, I document all the needed template settings, which still saves time and provides a consistent structure.

Here’s an example request template documentation page in Confluence.

‍

‍

Final Result

Here’s how the templates look to administrators.

In Cloud

‍

‍

In Data Center

‍

‍

‍

Here’s how the templates would look if unhidden in the customer-facing portal:

‍

In Cloud

‍

‍

In Data Center

‍

‍

Don’t forget to view the request forms from an end user’s perspective to ensure they look and function as intended.

Activities to Try

Now it’s your turn! Build a custom request form for a common use case in your organization.

Ideas

• Build a template for ITSM uses, like service requests, changes, incidents, or problems.
• Build a template for other types of customer support, like requesting a beneficiary change from the HR department or requesting new office furniture from the Facilities department.
• Build a template for other common requests from employees, consultants, customers, external vendors, etc.

Next time you create a new Jira Service Management project, use your custom request templates instead of the default settings.

‍

Resources

• Use forms in Jira Service Management — https://support.atlassian.com/jira-service-management-cloud/docs/use-forms-in-jira-service-management/ 
• Confluence wiki markup (for styling text in JSM request forms) — https://support.atlassian.com/confluence-cloud/docs/insert-confluence-wiki-markup/

‍