Good morning readers; I hope you are doing well this week! I have been playing around with a new gadget this past week, Flipper Zero. The firmware is still in early development, but the base hardware is competently designed and well built, so I have high hopes for the new tool. 

Anyways, today we will discuss an essential topic to administering Jira. That is the Object Diagram, which is a map of how different fields get associated with a particular project. Understanding what each part does and how it changes a project is essential to understand when and how a particular field is displayed to the end-user.  

While you might have an intuitive understanding of this, I find this an invaluable image to add to my documentation. Having it enables your users to understand how Jira works better, which can help them make better-informed requests, thus saving you time in the long run. 

This model is organized by layers, which shows how deep the configuration is – with the top-most being the most basic element, and the bottom-most is your final project. Similarly, each column – which are denoted by the color – shows how different schemes are linked.

Today I intend to talk about each Object, what they do, and how they link to the previous Object in the chain. So let’s dig into this!

Yellow Column: Fields

As noted, the yellow column dictates what fields exist, which ones are required, which ones are hidden, and how each is tied to different issue types. This column is the base where the rest of the model builds on and is one of few parts that determine whether a field is seen. 

Field

Oh, the humble Field, the cornerstone of Jira. I’m sure I’ve mentioned this before, but a field is just a space to store a bit of information within an issue. A field can be considered either a system field – one that comes prepackaged as part of Jira Core – or a Custom field – one that does not. But even this distinction is fuzzy, as the External Issue ID is generated by Jira Core but is considered a custom field. 

Each Field has a Type associated, which dictates what type of data it holds – whether it’s a result of a single select, radio button, checkbox, or text field. A word of caution, though – once you set a Custom Field’s type, it cannot be changed. So if you want to change it in the future, you will have to create a new Field with the new Field type then figure out some way to migrate the data to the new Field. Not. Fun. So I implore you: be sure your users understand what type they are asking for and impress on them that the pain in changing this in the future will be significant. 

Additionally, each Field can have one or more contexts. A context answers three things:

• What projects have access to this Field?
• What issue types have access to this Field?
• What options are available to that context?

 Using different contexts on the same Field, it’s entirely possible to have a single field have different options depending on which project or issuetype it’s attached to. This fact is one of my tricks to keep my custom field counts lower (See above).  

Field Configuration

A field configuration, when attached to an issue type via a Field Configuration Scheme, tells Jira three facts about each Field:

• Whether a Field is hidden or visible
• Whether a field is required or optional
• What is the Field’s Description for this configuration 

Looking at a Field Configuration, you will see a list of every Field – both custom and system – contained within your Jira instance. Unfortunately, that means for extra-large instances with many custom fields, this list becomes unruly FAST. 

Then, for each Field, you will then see a list of all screens that Field appears on. That means if your screens are appropriately labeled, it will tell you what projects the Field is expected to be used in. If you know the ultimate project for your Field Configuration, this can aid you in finding the Fields you need to modify.

After that, you will see some actions listed on the right side. There are up to five actions you can do on a field Configuration, but not all of them will show up for every Field Type. They are:

• Edit – Modify the Fields Description for this Configuration
• Show/Hide – Enables a Field to be seen with this Configuration. If the option says “Hide,” the Field is visible. If the option says “Show,” the Field is hidden.
• Required/Optional – Whether this Field is required or not. If it says “Required,” the Field is optional. If it says “Optional,” the Field is required. 
• Screens – opens up a Checklist to bulk add a field to screens
• Renderers – changes how the end-user selects the field options

I find that if a Field is missing that I would expect to see, about 75% of the time the problem is on the Field Configuration, with about 24% of the time it’s on a Field Context. Because Screens are the most visible part of the problem, they are not often why a Field is not displayed.

Field Configuration Scheme

A Field Configuration Scheme has one simple job: Map Field Configurations to Issue Types. This Object is how you can have different required and shown Fields per Issue Type within the same Project. That’s it, that’s all they do. Yet this is critical for the flexibility you have within a single project. 

Within a Field Configuration Scheme, you will have a Default line item. This entry is required for the Field Configuration Scheme and tells Jira what Field Configuration to map to any Issue Types not explicitly stated on the Scheme. After that, you can add Issue Types to the Scheme and state which Field Configuration the Issue Type is specifically configured to. 

Green Column: Screens

I would be willing to bet a Screen was probably one of the first things you learned to manipulate as a Jira Admin. That is because they have the most significant impact on how a given issue looks when viewed by a Jira User.

Screens

A Screen is a two-dimensional ordered list of Fields. The first dimension is Top to bottom, and Jira will display the Fields in the order you specify on the Screen.

Furthermore, you can optionally add Tabs to your Screen, which gives you a second dimension to play with. I have often advocated using Tabs to help organize your Fields to avoid the cluttered look some screens can get when they have too many fields. 

Screen Schemes

While a Screen is relatively basic in concept, a Screen Scheme is a bit more nuanced. What a Screen Scheme allows you to do is set a Screen to be displayed for one of three operations:

• Create Issue
• Edit Issue
• View Issue

As with the Field Configuration Schemes, a default must be included, and is used for any unmapped Operations. Otherwise, Jira will use the screen you specify for the operation you select.

By setting different screens to these three operations, you can dial in the user experience a bit. For example, you can set a different set of Fields to be visible when you create an issue and modify or view it. This arrangement can be useful for situations where you want to simplify making an issue, but much more information will be generated as the ticket is worked on. 

You can also use this to show fields that you only want to be modified by Automation. By excluding it from the Create and Edit operations but including it on the View operation, it’s only visible to users when they view the issue. 

Issue Type Screen Scheme

Like a Field Configuration Scheme, an Issue Type Screen Scheme allows you to map a given Screen Scheme to an issue type. For example, this Object allows you to display different screens for different issue types in a given field.  

Also, like a Field Configuration Scheme, a Default entry must exist for each Scheme. This will be the Screen Scheme mapped to all unspecified Issue Types. From there, you can add an association between a given Issue Type and Screen Scheme. 

One reason you might want to do this is to either emphasize or de-emphasize different Fields per issue type. For example, an Affects Version will be far more critical for a Bug than a Story, so maybe put it higher on the Screen for a Bug create operation. 

Blue Column: Workflows

What is this doing here? Let me explain by going directly into Workflows

Workflows

Workflows specify what steps an issue takes towards completion. So why show this on this model? Well, as a part of a transition (when an issue moves from one status to another), you can specify a Screen to be displayed. This is one way to use a screen that never touches a Screen Scheme, and can be pretty powerful. 

For example, I don’t like to put resolutions within a typical Screen Scheme, as it’s only relevant towards the end of the issue’s life. So instead, I like to either set it explicitly in a post function or Pop up a screen close to asking for it. Showing a screen on Close is especially powerful when combined with a Validator to say, “You cannot proceed without setting a Resolution.”

Workflow Schemes

Workflows schemes are very much like Field Configuration Schemes and Issue Type Screen Schemes, in that they map workflows to issue types. However, they look slightly different, though the intended behavior is the same. 

Each Workflow Scheme has a default Entry for Issue Type “All Unassigned Issue Types.” This entry is meant to act as the default and specifies a workflow for any Issue Types not explicitly mentioned in the Scheme. After that, you have any Workflows you have added, and the Issue Types associated with that workflow.  

The need for this should be obvious. It’s well within reason to think a Story would have a different workflow from a Request or Bug. This is the Object that allows you to tell that story.

Project

The Project is the final level to this Model, and is where the Workflow Scheme, Field Configuration Scheme, and Issue Type Screen Scheme are associated. By referencing these three schemes, and their related downstream objects, Jira can tell which fields are to be displayed, which are to be required, and what order to display them in. It can also tell what workflow to apply to different issues and show screens during transitions. 

Now it’s important to mention this, I’ve mentioned three separate places that determine whether the end user sees a Field. But to summarize, a Field must meet all of the following to be displayed:

• Its Field Context must include both the Issue Type and the Project.
• Its Field Configuration Entry must be set to “Show.”
• It must be present on the Screen associated with the operation and issue type.

If any of these are not met, your Field will fail to display. 

So, What do you think?

I try to include this in my internal documentation everywhere I work. Understanding this model helps you define useful configurations for your users. But it also helps users work better with you by allowing them to understand what you are doing.

As always, you can find my social media links on Linktree. Please be sure to follow, like, and comment on the posts on Social Media to help others discover this blog!  

You can also subscribe to get new posts delivered by mail! I’m not joking when I say I’ll get the email about a new blog post before WordPress even sends the notification it’s been published. It’s the fastest way to get new content from The Jira Guy.

But until next time, my name is Rodney, asking, “Have you updated your Jira issues today?”

---