Last updated Mar 22, 2024

Jira templates and JSPs

If you wish to change Jira's behaviour by modifying the JSPs or Velocity templates, you can do so simply by changing files in the Jira distribution. Jira will pick up changes to its JSPs the next time that page is displayed: restarting isn't necessary. On the other hand, you will need to restart Jira in order to see changes to the Velocity templates.

However, keep in mind that the next time you upgrade Jira - or need a new installation for any reason - you will have to manually copy any changes you have made to the JSPs or templates into the new installation of Jira. If the JSPs or templates have changed in the newer version, you will have to port your customization into them.

Velocity templates

Velocity is a server-side templating language used by Jira to render page content. Velocity allows Java objects to be called alongside standard HTML. The following table lists the Velocity contexts available for use in the XML descriptor and Velocity views.

Name

Description

user

Currently logged in user.

Type: User.

helper

Convenient class which holds information such as the current request and selected project.

Type: JiraHelper.

xmlutils

Utilities for basic XML reading.

Type: XMLUtils.

textutils

Utilities for common String manipulations.

Type: TextUtils.

urlcodec

Utility for encoding a string.

Type: JiraUrlCodec.

outlookdate

Class to give a nice String representation of a date.

Type: OutlookDate.

authcontext

User locale dependant utility class. Can get the current user, locale, I18nBean (for internationalisation) and OutlookDate.

Type: JiraAuthenticationContext.

dateutils

Utilities for displaying date/time.

Type: DateUtils.

externalLinkUtil

A simple utility class that lets you resolve external links that may need to change, because of partner sites and such.

Type: ExternalLinkUtil.

requestContext

A context that allows for different implementations depending on whether it is running in the scope of a web request, or via email.

Type: VelocityRequestContext.

req

current request

Type: HttpServletRequest.

baseurl

The base URL for this instance (velocityRequestContext.getBaseUrl()).

Type: String.

Contents of the Velocity context

The contents of the Velocity context used to process web templates and email templates is listed below.

Web templates

This is the listing of the contents of the Velocity context used to process web templates.

Velocity variable & Jira Object/Value

Description

As of Version 

 Condition

constantsManager

com.atlassian.jira.config .ConstantsManager

 Manager for issue types, statuses, priorities and resolutions.

 3.4

 always present

projectManager

com.atlassian.jira.project .ProjectManager

 Implementations of this interface are responsible for all management of project entities within Jira.

 3.4

 always present

customFieldManager

com.atlassian.jira.issue .CustomFieldManager

 Functions for working with CustomFields

 3.5

 always present

applicationProperties

com.atlassian.jira.config.properties .ApplicationProperties

 provides access to Jira properties stored in the DB

 3.4

 always present 

 jirautils 

com.atlassian.jira.util.JiraUtils

 Miscellaneous utility methods.

 3.4

 always present

 jirakeyutils

com.atlassian.jira.util.JiraKeyUtils

 utilities to determine the validity of Jira project/issue keys

 3.4

 always present 

 buildutils

com.atlassian.jira.util.BuildUtils

 provides information on the running version of Jira

 3.4

 always present 

 velocityhelper

com.atlassian.jira.util .JiraVelocityHelper

 A simple class store methods we want to expose to velocity templates

 3.4

 always present

 userutils

com.atlassian.core.user.UserUtils

 A utility class for operating on users.

 3.4

 always present

 textutils

com.opensymphony.util.TextUtils

 lots of utility methods for manipulating text

 3.4

 always present 

 params

java.util.Map

 parameters of the IssueEvent that triggered this email notification 

 3.4

 always present

 issue

org.ofbiz.core.entity .GenericValue

 a GenericValue representing the issue which triggered this email notification 

 3.4

 always present

 issueObject

com.atlassian.jira.issue .MutableIssue

an Issue object representing the issue which triggered this email notification

 3.5.2

 always present

 remoteUser

com.opensymphony.user.User

 the logged in user if they exist 

 3.4

 remoteUser != null 

 renderedDescription

java.lang.String

 the rendered description field, it a renderer has been specified 

 3.4

 renderer specifed for issue and field 

 renderedEnvironment

java.lang.String

 the rendered environment field, it a renderer has been specified 

 3.4

 renderer specifed for issue and field

 timeoriginalestimate

java.lang.String

The DateUtils .getDurationPretty value of timeoriginalestimate from issue or "None" if null

 3.4

 always present

 timeestimate

 java.lang.String

 The DateUtils .getDurationPretty value of timeestimate from issue or "None" if null

 3.4

 always present

 timespent

java.lang.String

 The DateUtils .getDurationPretty value of timespent from issue or "None" if null

 3.4

 always present

 duedate

 java.sql.Timestamp

 Duedate from the issue

 3.4

 always present

 versions

List( org.ofbiz.core.entity .GenericValue )

 A list of GenericValues representing the Affected Versions of the issue

 3.4

 always present

 fixfors

List( org.ofbiz.core.entity .GenericValue )

 A list of GenericValues representing the Fix Versions of the issue

 3.4

 always present

 components

List( org.ofbiz.core.entity .GenericValue )

 A list of GenericValues representing the Components of the issue

 3.4

 always present

 assignee

com.opensymphony.user.User

 The assignee of the issue

 3.4

 assignee != null 

 reporter

com.opensymphony.user.User

 The reporter of the issue

 3.4

 reporter != null

 renderedComment

java.lang.String

 the rendered comment field, it a renderer has been specified. The comment is the comment associated with the change

 3.4

 renderer specifed for issue and field and comment created

 comment

org.ofbiz.core.entity .GenericValue

 generic value representing the comment associated with the change

 3.4

 comment created

 commentauthor

 com.opensymphony.user.User

 the author of the comment

 3.4

 comment created

 timelogged

 java.lang.String

 The DateUtils .getDurationPretty value of timelogged from issue or "None" if null

 3.4

 always present

 changelog

org.ofbiz.core.entity .GenericValue

 generic value representing the changelog associated with the change

 3.4

 changelog != null

 changelogauthor

com.opensymphony.user.User

 The change log author of the issue

 3.4

 changelog != null

 visibilitylevel

java.lang.String

 The security level of the comment

 3.4

 comment created

 i18n

com.atlassian.jira.util.I18nHelper

 Bean that searches for i18n text in JiraWebActionSupport .properties

 3.4

 always present

 dateutils

com.atlassian.core.util.DateUtils

methods for working with dates

 3.4

 always present

 attachments

List( org.ofbiz.core.entity .GenericValue )

 list of generic values that represents the attachments associated with the issue

 3.4

 always present

 security

org.ofbiz.core.entity .GenericValue

 generic value representing the security level, if any, associated with this issue

 3.4

 if( isEnterpriseEdition ) 

mailPluginsHelper

com.atlassian.jira.mail .JiraMailPluginsHelperImpl

provides access to isPluginModuleEnabled()

3.7

always present

Email templates

This is the listing of the contents of the Velocity Context used to process email templates.

  • The TemplateContext provides access to some general object references for use in the templates - e.g. Utilities,  Change Log details, etc.
  • The TemplateIssue provides access to the Issue object - further extended by helper methods for displaying information in rendered HTML format (i.e. environment, description and comments) and users who may not exist in the system. All issue related details can be retrieved from the TemplateIssue.

The following tables lists other objects that are also available within the context:

Velocity Variable &

Jira Object/Value

Description

userutils

com.atlassian.core.user .UserUtils

collection of utility methods for querying, creating, and removing users

velocityhelper

com.atlassian.jira.util .JiraVelocityHelper

a collection of miscellaneous methods (e.g. urlencode, indentTextBlock, printChangelog

textutils

com.opensymphony.util .TextUtils

collection of utility functions for manipulating text

constantsManager

com.atlassian.jira.config .ConstantsManager

Jira's constants for priorities, resolutions, issue types, statuses

projectManager

com.atlassian.jira.project .ProjectManager

management of project entities (e.g. getProjectByName, getComponents, getCategories)

customFieldManager

com.atlassian.jira.issue .CustomFieldManager

functions for working with custom fields

applicationProperties

com.atlassian.jira.config.properties .ApplicationProperties

access Jira's application properties

jirautils

com.atlassian.jira.util .JiraUtils

a handful of miscellaneous utility methods (e.g. isPublicMode, isSetup)

jirakeyutils

com.atlassian.jira.util .JiraKeyUtils

methods for working with project keys

buildutils

com.atlassian.jira.util .BuildUtils

buildutils is no longer available within the context. build variable should be used instead (see below)

build

com.atlassian.jira.util .BuildUtilsInfo

Since Jira 6.1 Jira build and edition information

jiraUserUtils

com.atlassian.jira.user.util .UserUtil

user level operations (e.g. getActiveUserCount, getDisplayableNameSafely, addUserToGroup)

mailPluginsHelper

com.atlassian.jira.mail .JiraMailPluginsHelperImpl

method for checking whether plugins are enabled

userformat

com.atlassian.jira.plugin.profile .UserFormatManager

formatting user names

context

com.atlassian.jira.mail .TemplateContext

The Template Context object itself

issue

com.atlassian.jira.mail .TemplateIssue

An Issue object with extended helper methods for display - this is the issue for which the email notification event was triggered

params

java.util.Map

Parameters of the IssueEvent that triggered this email notification

remoteUser

com.opensymphony.user.User

The user who has triggered this event

stringUtils

org.apache.commons.lang .StringUtils

Utility object providing formatting methods

padSize

java.lang.Integer

Used in text emails for padding the display

timeSpentFieldId

java.lang.String

The Id of the TimeSpentField - used in changelog for work logged notifications

attachments

Collection( org.ofbiz.core.entity.GenericValue )

Collection of Generic Values that represents the attachments associated with the issue

htmlComment

java.lang.String

The comment associated with this event as a rendered HTML formatted string. A basic string is returned if the comment cannot be rendered correctly - including links for any referenced Jira issues.

comment

com.atlassian.jira.issue.comments .Comment

The comment associated with this event. The body of the comment will be the raw unprocessed comment as entered by the user (e.g. the raw wiki markup)

commentauthor

com.opensymphony.user.User

The author of the comment 

roleVisibilityLevel

java.lang.String

The comment's project role level (overwritten by worklog)

groupVisibilityLevel

java.lang.String

The comment's group level (overwritten by worklog)

originalhtmlComment

java.lang.String

 

originalcommentauthor

com.opensymphony.user.User

 

originalroleVisibilityLevel

 

comment (overwritten by worklog)

originalgroupVisibilityLevel

 

comment (overwritten by worklog)

worklog

com.atlassian.jira.issue.worklog .Worklog

 

timeSpentUpdated

java.lang.Boolean

 

startDateUpdated

java.lang.Boolean

 

commentUpdated

java.lang.Boolean

 

visibilityUpdated

java.lang.Boolean

 

originalworklog

com.atlassian.jira.issue.worklog .Worklog

 

changelog

org.ofbiz.core.entity.GenericValue

The Generic value representing the changelog associated with the change

changelogauthor

com.opensymphony.user.User

The change log author

security

org.ofbiz.core.entity.GenericValue

The Generic value representing the security level, if any, associated with this issue

rendererManager

com.atlassian.jira.issue .RendererManager

Allows use of renderers such as wiki renderer. (e.g. $rendererManager.getRenderedContent("atlassian-wiki-renderer", "bold wiki", $issue.getIssueRenderContext()))

recipient

com.opensymphony.user.User

The recipient of the email

i18n

com.atlassian.jira.utilI .I18nHelper

i18n translation helper for the current recipient

dateformatter

com.atlassian.jira.web.util .OutlookDate

Date and time formatter for the current recipient's locale

eventTypeName

java.lang.String

Available from Jira 4.1. The localised event type name. (For example, for the Issue Assigned event, the key mail.event.type.issueassigned.name will be used.) If a translation is not available, the event type name will be used

attachmentsManager

com.atlassian.jira.mail.util .MailAttachmentsManager

Available from Jira 7.0.3. If this object is present, the mail attachments manager can be used to add attachments to an email and generate Content-IDs for those attachments.

The following tutorials provide guidelines and give examples of how to modify Jira's JSPs and templates:

Rate this page: