Jira Tips: I See You're Using the Term "Global" Pretty Loosely

I attended ServiceRocket's weekly Atlassian tech discussion a couple of weeks ago, and one of the things that we talked about was field contexts in Atlassian Jira. We talked about what you can and cannot do with field contexts. There are some quirks to be aware of and thanks to encouragement from Matt Doar, I did some investigating, and here are few things about field context you should be aware of in Jira.

A Field is Not (Necessarily) Just A Field in Jira

Field contexts are used for custom fields. They're a way of defining different ways to use that field for different Issue Types and different Projects. For example, perhaps you are a 15th century European trader, and you're using Jira to track your trade operations. You've created a 'select list' type custom field called Shipping Method and your options are donkey, ox, camel, and yak.

So far, so good.

But perhaps you would like to use that field for maritime shipping options as well. No problem! You can just create a new field context for sea trading and change the options to galley, cog, caravel, and carrack! You can choose which context to use for which Jira Projects. You can also use field contexts to limit where a field appears. Do you only want to use the Shipping Method field for trade related Issue Types? Then only assign it context for those Issue Types and it won't show up for any other Issue Types!

Field contexts seem fantastic until you start to uncover their limitations. I'll include a quote from Atlassian's Jira documentation:

"A custom field can only have one context per Jira project. So you cannot have multiple contexts for different issue types in the same project."

They really mean that and there's no way around it. This gets confusing when you have multiple, seemingly overlapping field contexts in Jira. The problem stems from the fact that when Jira says it is assigning a "global" context it's sort of lying. Let's put together an example to flush out Jira's quirky ways.

For this example we'll use three Projects:

And four Issue Types:

We'll now create a new custom field to use called Shipping Method, which will be a Select List with the options Donkey, Ox, Camel, and Yak, and we'll assign this new field to the Default Screen that is being used by all Projects and Issue Types in Jira. The field now shows up for all Issue Types and Projects in Jira, and we are all thoroughly unsurprised.

Now let's shake things up a little bit, go into the configuration for the Shipping Method field, and change the default context to only apply to "Fur Trade" and "Spice Trade" Issue Types (leaving the Project context as "Global").

So that it looks like this:

- Shipping Method field shows up using Land context options

- Shipping Method field does not show up

That all seems appropriate. Nothing earthshaking there. We've limited our context for all Projects to just those two Issue Types, so the "Ivory Trade" and "Silk Trade" Issue Types will not include our field.

Now let's go ahead and add in a new context (called Sea) for all Issue Types in Trade Project Beta. When we do this, notice that the "Global Context" option has disappeared. We can only use it once. If we wanted to add in a new "Global Context" for a different Issue Type, we would find that we cannot do so. We only get one context per Project, and one Global Context.

Once we add in the new options (different boats instead of different animals) for our new context, it will look like this:

So our "Global" context wants us to use the Land options for the "Fur Trade" and "Spice Trade" Issue Types, but our new context wants us to use the Sea options for all Issue Types in "Trade Project Beta"! Who wins in each situation?

- Shipping Method field shows up using Land context options

- Shipping Method field shows up using Sea context options

- Shipping Method field does not show up

The Alpha and Gamma Projects remain unchanged, while Project Beta ignores the "Global Context" completely now that it has its own context. What we learn from this is that a "Global" context is more like a default context. Jira will use a "Global" context for all Projects that don't have their own unique context.

But what happens when a Project-specific context doesn't interfere with the Global Context? We're going to add in a new "Air" context here for "Ivory Trade" Issue Types in Trade Project Gamma. Notice that both the "Global Context" and "Trade Project Beta" options are gone from the context select window.

And once we add in our different flight options to the new context, it will look like this:

So what Issue Types in "Trade Project Gamma" use the Shipping Method field, and which context do they use?

- Shipping Method field shows up using Land context options

- Shipping Method field shows up using Sea context options

- Shipping Method field shows up using Air context options

- Shipping Method field does not show up

Yep. Project Gamma doesn't care about the "Global Context" that says to use Land options for "Fur Trade" and "Spice Trade." It has its own context now that excludes those Issue Types. It only uses the Shipping Method field where it is specified to do so, which is in the "Ivory Trade" Issue Type.

The lesson here is that "Global Context" in this case is synonymous with "all undefined Projects." To determine what context a Project will use, see if it has a specific context in the configuration. If it does, only pay attention to that context. If it doesn't, see if there is a "Global Context," because that is the one it will use. If it doesn't have a specific context and there is no "Global Context" then that Project won't use that field regardless of what the Screens say.

On a related note, how do you get a Project to use different contexts for different Issue Types? You don't. But you can just create another custom field with the second context that you wanted to use.