When designing solutions in Jira, it is important to make sure that they are friendly and easy to use for the end users. In this episode I will show you one of a little known ways to show some additional instructions to users.
Why on-screen instructions are important for Jira users?
When you put additional instructions on a transition screen, this helps your users notice what you expect them to do eg. select a value in a dropdown list or fill in a mandatory text field. For the purpose of illustrating this, I will use an issue type Story with a simple ToDo -> InProgress -> Done workflow.
In this use case scenario, I want to make sure that when a user transitions this Story to status 'In Progress', on the transition screen there will be an additional notification reminding a user to set the Fix Version field. At the same time, on this workflow transition we can configure a validator that will not let the user continue the status transition unless one of the fix versions has been selected.
Good practice
It is very annoying for users to receive a notification that a field is required only after they try to transition it by pressing the transition button. Jira Administrator should notify a user on a screen (the Create screen or Transition screen) that a field is required. This can be achieved with as little as a red asterisk next to a field (as a result of field configuration) or a dedicated instructional custom field.
In this solution, before I notify a user with a workflow validator that the transition cannot be completed, I put an extra notification that setting up the Version field is mandatory. See below the notification in the yellow(ish) box
Free plug-in for on-screen instructions
In order to be able to put this special notification on a transition screen, you can use a free plugin Toolkit Plugin for Jira. It is available only for the Server version of Jira.
When you install the plugin, there will be a few additional custom fields available in your Jira instance. Go to Jira Administration / Issues / Custom Fields / Advanced and add a new custom field of type Message Custom Field (for edit)
On-screen instructions configuration
In my example I created a new custom field named ‘Note’. You can use the same name if you want.
When you create your custom field, go to its configuration (custom field menu Configure) and click on the link ‘Edit Default value’. You do not need to have a dedicated custom field context as I have in my example.
Whatever content you put in this Default value field, now this can be displayed on a transition screen. If you want your warning message to look like mine in this example, simply copy this code below and modify your warning message:
<div class="aui-message aui-message-warning">
<p class="title"><strong>Bad login information</strong></p>
<p>Adding Version on this transition is very important because in this way you are ensuring that this task will be placed in a proper <strong>Release.</strong></p>
</div>
When you finish editing, press the button ‘Set Default’ below the default value field.
Now, the last thing to do is to put the new custom field Note on the transition screen, which needs to be associated with the workflow transition.
Go to Jira Administration / Screens and find the screen on which you want the on-screen instructions to appear.
Lastly, all you have to do is to add the field as the first field on your transition screen.
If you have not associated this transition screen with a workflow transition, go to Jira Administration / Workflows and find the workflow you want to modify. Then select the transition and associate it with the screen from the previous step. If you are not sure how to do it, go to the article about protecting screen fields without a plugin, where I discuss this in detail.
Before you go…
I hope you will agree that this solution is easy to use and easy to implement. Please remember that the plugin I used is only available for Jira Server.
Jira got popular in recent years because it is a very flexible tool and user requirements can be achieved in more than one way. However some options are limited when you work in the Cloud environment and this is just one of them.
