Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

Introducing Jira or JSD to a new environment

In a discussion thread about onboarding new users to JSD.  (Found here: A is for Activate: Share your top Jira Service Desk onboarding tips for new users!) We began to explore the ideas beyond just simple how-to guides and walk through tutorials, and move in to the realm of setup and design, and common framework of communicating about the products.  

In my work as an Atlassian administrator, I am often bringing the world of Jira to users outside of the development process, and to those unfamiliar with the toolset, it can be challenging to communicate why something may not be setup the way one expects or what problems a user is having with the product, without common language. 

Are they tickets?  Are they items? Are they cards? 
Oh, you mean the issue!  right, Jira calls the items issues. 
Oh, but they are records of the employees that are going through onboarding process. 
Yup! but it's easier to think of them as issues, since that is what you will click on in the menu to see all of them and filter for specific ones you want to see. 

Some times just getting everyone to settle in on the terms can cause the process to become daunting!  Then you get to items that I call "jiraisms".  Does this kind of conversation look familiar to any other experienced Admins? 

So I created a ticket (my internal brain translates to issue) and when I save the ticket (issue) not all of the fields show up. 
Do you mean you filled out all of the fields and there isn't anything showing up?   
No, I mean, I left some things blank, but I can't fill them out now. 
Ok, what happens when you select the edit button, are they on the form (...edit screen)? Yes!  but I saved and they disappeared again!!! 
It's ok,  Jira doesn't display custom fields that do not contain information.  It keeps the view clearer.  

It can certainly take the new users time to get use to this sort of behavior, and many feel like it is a negative thing, at first.  It can make it a bit easier, though to remember back to when you first started using Jira, and how confusing it was....and some times still is!  Most new users I have worked with take a month or two to become comfortable and a few more months past that to get to where they like using the tools.  

My biggest tips to ease new user/new environment pain points are:

1.  Keep it simple!
Are you implementing a new environment or replacing an existing one?  Don't get all complicated in your first build out.  Sit down with your teams and define the must haves, the nice to haves, and the can we haves.  Evaluate those lists and ask the hard questions about the must haves. 

We have to have these fields required and only people in this group can transition the issue!

Why are we worried about people not putting in the information?  Will they put in relevant information at this point, or will they just be selecting the first option, or typing N/A to get the issue opened.  Do we plan to do reports on that field?  Will we get the information needed for the report if we have people entering "junk" to get the issue opened?

Jira tracks the history of an issue, we can see who moves an issue thought the workflow in that history, do we really need to limit the group at this time or can we wait and see if it is a problem after we go live?  

Sometimes the answers to these questions are  we really do need them.  Like if an issue is opened by a team not doing the work.  You don't necessarily want them to accidentally move or close an issue and it makes sense to put the restrictions in, but really think about why you are making those choices at the start.

But we are doing it that way in some other tool!

This is a great time to address some of the things that might not have worked well for your team or company in that old tool.  Make sure that you don't bring those pain points into the new tool!  Were the forms long and complicated to fill out?  Check out using different screens for the create issue vs edit/view!  Especially if the person filling out the new issue won't be the one completing the work, or if at the time of opening the issue, you might not have all of the details. 

Example, your team plans events.  You know the event date and topic, but you might not know the location or food plans at the time you want to create the issue.  Don't include those fields on the create screens, place them on the edit/view screens so they are available after the issue is created, and streamlines the issue creation process..


2.  Keep things as consistent as possible across the environment.  This is easier if you keep things simple!  Don't get super specific in your workflow status name or your custom field names.  You can reuse them across the environment.  This makes it easier for you as an admin and for the users, because what they see in one project will be quite similar if they are working in another project.

We would like a status, Business Analyst Review.

"In Review" works just as well, and can be used for multiple work flows from Code/Development, to Company Blog postings.

Please add field Annual Conference Location to screen.

So long as "Location" isn't already a field being used on the screen, it should work just fine and can be used by other projects for Client Location, Asset Location, or Office Location.  Don't forget about being able to use Field Configurations, if you need other options for a drop down or select list for different projects!

Keeping these broad limits the number of items you need to manage, and helps with system performance!

3.  Don't be afraid of change.  If something really isn't working for you or your team, don't be afraid to rework a project.  It isn't uncommon for me to build a project and then talk with a team 3-6 month later and have some changes, maybe a field really should (or shouldn't be) required.  Maybe they added a step in their work flow.  Maybe the default notifications are too many, or don't go to enough people.  There shouldn't be this feeling that a project is a great stone monolith that should never be changed.  Make it work for you!


Questions?  Thoughts to add?  Experiences to share?  Leave a comment and lets Discuss!


Great tips @Kimberly Deal _Columbus ACE_! Common language is one of the biggest blockers to progress in my organization when it comes to JIRA/Confluence administration. 

I think the thing that has been most difficult for me personally has been surrounding #2 - My organization has always used an extreme level of detail in fields, screens, reporting, etc [in our mortgage LOS] so it was a huge change for them when I implemented generic status names and fields that are being used across multiple projects within JIRA. 

Still blows my mind to read about the sheer number of custom fields some orgs use. 

Thanks @Meg Holbrook!

It is very hard to work with when you inherit systems that have been in use for years, especially when users have had pretty open access to set everything up custom to themselves.  That's why I think it is a super important part of setting up a new installation.  Particular customizations can get out of hand super quick, if there isn't the idea of commonality & sharing configuration introduced early on.

Nice thoughts! With regards to the end of your point #2 I hold out hope that someday JRASERVER-6851 will be implemented. Currently, it is not possible to have multiple custom field contexts within the same project for different issue types. This would seriously cut down on some of our custom field bloat.

Good find on JRASERVER-6851 @Davin Studer I've added my vote!  The other thing I could wish for, in custom fields is a display name.  So the field behind the scenes could be Location, but on the screen it would list as Customer Location, and the like.  I believe there is functionality like that in the Customer Portal for JSD, but not in Jira itself.  Would be super handy!

@Kimberly Deal _Columbus ACE_You can fake it by by putting JavaScript in the field description to make the change. It's in the field configuration ... and then click edit next to the field to see the description box. Or if you have ScriptRunner you can do it as well with a field Behaviour. But yes, it would be better if it  were built in. You can also just put straight text in the description field which shows as helper text below the field name. I've done that before as well. For instance we have our server asset list in Jira and the summary field is the server name, but that doesn't make much sense. So, in the description box I put in "Asset Name". Not perfect but those entering the data know then that they need to put the server name in the summary field.

@Davin Studer

Those are some awesome tips! I do imagine that you are doing this on server though?  

I tend to try to stick with things that are straight out of the box, to keep our upgrades as smooth as possible, but I could see this making some things easier, if kept limited to specific, and well defined use cases.

Gary Barg Atlassian Team Sep 12, 2018

@Kimberly Deal _Columbus ACE_: I'm from Atlassian University. Wanted to chime in on your first topic about getting to a common vocabulary. We have a set of free tutorials, called Jira Basics, that can be a big help for an Admin in the situation you describe. Check them out here:     Let me know if you think they would help.

  • Awesome @Gary Barg!  I was just asked by one of my User Group members last night about how to train new users to work with Jira and how he built a vocabulary chart.  I can't wait to share this resource with him!


Log in or Sign up to comment

Atlassian Community Events