JiBrok message field Message field

đŸ”„Dynamic templates

The dynamic templates allow you to render the message using data from the issue and issue screens (creation, editing, etc.) that can be changed in real time. In templates, you can use conditions, use the Jira Java API, or do some calculations before displaying the message. You can change the display parameters of the message - title, body, type, and location. This functionality works in Jira Core/Software/Service Desk.

In previous versions of the application you could change messages dynamically only using JavaScript. Many cases can now be done by using the dynamic templates(velocity templates (HTML + Java API) + real-time render).

Jira create issue form showing Priority field set to Medium without any visible message banner

How to do this?

To enable templates, you need to set Velocity render ‘On’ in the field config. Velocity render toggle set to On with template variables documentation and code editor

Special variables will be available in the template for working with data. Links lead to Java doc with descriptions of available methods.

Note: Some variables marked with ⚠ are available only for non-delegated settings.

  • $baseUrl
    • This variable contains the base URL of the Jira instance.
  • $issue
    • This variable contains the issue data stored in the database.
    • This variable is not defined on the creation screen($context == “CREATE”).
  • $form
    • JSON serialization of the form.
    • Variable that contains information entered by the user on the screen (Create, Edit issue, etc.) without additional processing.
    • The data in the variable is updated in real time.
    • Variable value is entered data (without any validation).
    • You can get values by the name of the property.
  • $formIssue - đŸ”„Recommended for use.
    • The variable combines data from $issue and $form.
    • Data from the screen ($form) takes priority.
    • The data from the screen ($form) undergoes additional validation and processing. Invalid values return null.
    • The data in the variable is updated in real time.
  • $fieldDisplayConfig
    • The variable contains information about the display of the message (message type, location, etc.).
    • The message will be recreated when this information changes. JavaScript won’t run again.
  • $context - Can have one of the following values:
    • “CREATE” - Issue create screen
    • “EDIT” - Issue edit screen
    • “TRANSITION” - Issue transition screens. Additional variables are accessed in this context:
      • $transitionId - number
      • $transitionName - string
    • “VIEW_ISSUE” - Issue view screen
    • “CREATE_SD” - Service desk create screen
    • “VIEW_SD” - Service desk view screen
  • $currentUser
    • The user who is viewing the message.
  • $locale
    • A Locale object represents a specific geographical, political, or cultural region of currentUser
  • $language
    • Returns the language code of currentUser. (String)
  • $country
    • Returns the country code of currentUser. (String)
  • $timeZone
    • Returns the timeZone of currentUser.
  • $currentDateTime
    • The current date time (server time zone).
  • $nowInUserTimeZone
    • The current date time (user time zone).
  • $dateOfLastTransition
    • The date of the last transition.
  • $secAfterLastTransition
    • How many seconds have passed since the last transition.
  • $previousStatusId
    • Number ID of previous status.
  • $previousStatusName
    • Name of previous status.
  • $transitionId
    • Number of current transition.
    • Only available on transition screens.
  • $transitionName
    • Name of current transition.
    • Only available on transition screens.
  • $cfValues
    • Utility object for getting custom field value from $issue and $formIssue.
  • ⚠ $links
    • Utility object for getting issue links or linked issues.
    • Only for non-delegated settings.
  • $linksWithCheckPermissions
    • Utility object for getting issue links or linked issues with permission checks.
  • ⚠ $jqlService
  • $jqlServiceWithCheckPermissions
    • Utility object for getting JQL results with permission checks.
  • ⚠ $issueFieldRender
    • Utility object for rendering issue fields values as HTML.
    • Only for non-delegated settings.
  • $issueFieldRenderWithCheckPermissions
    • Utility object for rendering issue fields values as HTML with permission checks.
  • $JSON
    • Utility object for parse string to JSONObject.
  • ⚠ $ComponentAccessor
    • Provides static methods for accessing JIRA’s managed components.
    • Only for non-delegated settings.
  • $mathTool
    • Mathematical operations tool for Velocity templates.
  • ⚠ $permissionHelper
    • Tool for checking permissions.
    • Only for non-delegated settings.
    • Example: $permissionHelper.hasPermission(“BROWSE_PROJECTS”, $issue.reporter) - checking that the reporter of the issue has access to the project of the current issue.
    • Permissions: ADD_COMMENTS, ADMINISTER_PROJECTS, ARCHIVE_ISSUES, ASSIGNABLE_USER, ASSIGN_ISSUES, BROWSE_ARCHIVE, BROWSE_PROJECTS, CLOSE_ISSUES, CREATE_ATTACHMENTS, CREATE_ISSUES, DELETE_ALL_ATTACHMENTS, DELETE_ALL_COMMENTS, DELETE_ALL_WORKLOGS, DELETE_ISSUES, DELETE_OWN_ATTACHMENTS, DELETE_OWN_COMMENTS, DELETE_OWN_WORKLOGS, EDIT_ALL_COMMENTS, EDIT_ALL_WORKLOGS, EDIT_ISSUES, EDIT_OWN_COMMENTS, EDIT_OWN_WORKLOGS, EDIT_SPRINT_NAME_AND_GOAL_PERMISSION, LINK_ISSUES, MANAGE_SPRINTS_PERMISSION, MANAGE_WATCHERS, MODIFY_REPORTER, MOVE_ISSUES, RESOLVE_ISSUES, RESTORE_ISSUES, SCHEDULE_ISSUES, SET_ISSUE_SECURITY, START_STOP_SPRINTS_PERMISSION, TRANSITION_ISSUES, VIEW_DEV_TOOLS, VIEW_READONLY_WORKFLOW, VIEW_VOTERS_AND_WATCHERS, WORK_ON_ISSUES
  • ⚠ $cast
    • Utility for converting Integer, Long, String types into each other.
    • Only for non-delegated settings.
    • Examples: $cast.toLong(“1”), $cast.toInteger($cfValues.getFromForm(“customfield_10200”).optionId), $cast.toString(1)
  • ⚠ $userGroupService
    • Service for retrieving users by username and checking group membership.
    • Only for non-delegated settings.
    • Examples: $userGroupService.getUserByName(“john.doe”), $userGroupService.isUserInGroup(“john.doe”, “jira-administrators”), $userGroupService.isUserInGroup($currentUser, “developers”)

Parameters for demonstration

You can click Show Demo to test the display of a message.

Template testing interface with Issue key TEST-7, JSON form data, and context selection dropdown

You can see how your message will look for the specified issue and execution context.

Conditions for displaying message and Permissions are not checked during this demonstration.

  • Issue key - The message will be generated for this issue.
  • Form data (JSON) - Text information from the issue screen presented in JSON format.
    • To collect test data:
      • Open the issue screen (create, edit, etc.).
      • Open your browser console.
      • Execute the following code (Running JavaScript): JSON.stringify(MESSAGE_FIELD_OBJECT.getDataFromDefaultForm (), undefined, 4)
      • Paste its result in the box above, except for the first and last quotes.

      Browser console showing JSON form data collection code and colorized JSON output

  • Context - The message will be generated for this issue context.
    • “CREATE” - Issue create screen
    • “EDIT” - Issue edit screen
    • “TRANSITION” - Issue transition screens
    • “VIEW_ISSUE” - Issue view screen
    • “CREATE_SD” - Service desk create screen
    • “VIEW_SD” - Service desk view screen

You can see usage examples.

Related Docs

JiBrok message field Message field
rss
rss
rss