RFC-103: Jira Field Configuration Overhaul: Admin Experience and API Changes

General Request for Comments (RFC)
, , ,
21

@MikhailBogdanov
I’ll add an example to Jeff response to make sure these changes won’t disrupt our apps.

Let’s say a user created a new JMCF field CF1, by selecting project PR1 and issue type IT1, with the current implementation we are creating a new context targeting PR1 and IT1 as an outcome of this, the new field is visible only in that project and for that issue type.
We also have logic to update/recalculate values and we use the same logic, if we need to update CF1: we get the context, we retrieve issues based on the context (so in this case issues in project PR1 with issue type IT1) and we update the value for those issues.

Now, if i understood correctly, with the proposed solution contexts will no longer be used to restrict fields, does that mean that field CF1 will now be visible in every project and for every issue type?
If that’s the case:

  • This will break all our fields using non global contexts and the logic we use to identify issues to recalculate.
  • We will need to change all the logic to create and restrict fields replacing the calls to the context api to the new api if we want to preserve the current functionalities
  • Will the introduction of the new proposal immediately change how contexts work? Will fields migrated the new structure take into account the visibility restrictions from contexts? Or there will be some period that we can use to fix our configurations
1 Like
22

Hey @diegorillosi ,

if i understood correctly, with the proposed solution contexts will no longer be used to restrict fields

You’ve got it exactly right. The aim is to simplify and clarify how field configuration works in Jira. Here’s how things will look under the new model:

  • Configuration context will be the single source of truth for how a field is configured in a given context.

  • Field scheme will define which fields are available and whether they’re required in a given context.

  • Screen/layout will determine how issues are displayed.

We will need to change all the logic to create and restrict fields replacing the calls to the context api to the new api if we want to preserve the current functionalities

Correct. Under the new model you can provide customers with 2 options:

  • select a scheme to associate the field with
  • select a project → get the scheme associated with a given project → inform customers about other projects that will be impacted (if any) → add a field

Will the introduction of the new proposal immediately change how contexts work? Will fields migrated the new structure take into account the visibility restrictions from contexts? Or there will be some period that we can use to fix our configurations

We’re still shaping the rollout plan and will adjust based on early access feedback. Right now, we’re aiming for a six-month transition period where customers can choose to move some projects to the new model or stick with the old one:

  • Projects still using the old model will continue to respect configuration contexts, and their logic will remain unchanged.

  • Projects moved to the new model will ignore configuration contexts and use the new scheme-based approach.

After the transition period, we’ll automatically migrate any remaining projects to the new model. When this happens, we’ll create new field association schemes based on the existing configuration context data, so that the original setup is preserved as closely as possible. In some cases, this might mean splitting a single old scheme into several new ones to maintain the same restrictions.

23

Hi @MikhailBogdanov ,

Our app also relies heavily on the “old” contextId. I have read all the previous posts and answers, but I am still far from understanding the new way it will work.

Will there still be a contextId or will there be a newly introduced field scheme ID that will somehow do almost the same?

Currently we use APIs like these to get and work on options of a context e.g. Project1:

/rest/api/3/field/${customfieldId}/context/${contextId}/option?maxResults=2&startAt=0

Other use case is: we get all contexts of a field and show it to the user with associated workItems and projects:

/rest/api/3/field/${customfieldId}/context

So can you outline which new APIs would need to be queried to get all “contexts” as before?

It is a little hard to understand how all RFC-70,103,104 work together …

Thanks a lot,

Bernhard

24

Hey @clouless ,

Contexts aren’t going away. They’ll remain for defining field configurations, including things like option lists, default values, and more, for a given context.

So can you outline which new APIs would need to be queried to get all “contexts” as before

Could you share a bit more about your use case? Understanding how you’ll use this info will help me recommend the best API.

25

Hi @MikhailBogdanov ,

Ok that is good to hear. My uses cases are as follows:

  • Display to a user which custom fields “exist” in a Project
    • Only show appropriate contexts assigned to project (with info on workType, project name)
  • Then allow the user to perform edit options, set default options a.s.o

Of course there is an app specific permissions scheme in place where a Jira admin allows editing on custom field options to certain people based on contexts or project roles.

Will I need to make some kind of distinction between the old configured fields and the newly configured fields here? Or can I use the “old” contextId approach for both old/new way?

Thanks,

Bernhard

1 Like
27

Hey @clouless ,

For now, the old configuration context API will work as it does today. Looking ahead, we plan to evolve context management:

  • There will always be a default (what is now called global) context applied by default - users and apps won’t be able to remove it.

  • Users will be able to set project and issue type overrides, similar to today’s project context, but with more flexibility, e.g. allowing multiple configurations for a single project

Display to a user which custom fields “exist” in a Project

Ideally, fields should be shown based on their association with a project. Even if a field has context for a project, it won’t be available unless it’s actually associated with that project.

Then allow the user to perform edit options, set default options a.s.o

This will stay the same for now, until we implement the changes I’ve mentioned above.

1 Like
28

Hi Mikhail,

Ok still sounds a little cloudy for me :sweat_smile: but once there will be API documentation and a functionality we can test, then it will surely be better understandable :slight_smile:

Will all these feature rollouts be made simultaneously for “normal Jira” and “AGC Jira”?

I am looking forward to it :rocket:

Cheers,

Bernhard

29

Hey @clouless

Will all these feature rollouts be made simultaneously for “normal Jira” and “AGC Jira”?

There is likely going to be a bit of a delay for AGC clients. But the overall timeline should be somewhat similar.

1 Like
30

I have another question regarding app migration. Since #CHANGE-3019 is now public.

Currently we can use `jira/classic:customFieldConfigScheme` from the mappings: https://developer.atlassian.com/platform/app-migration/mappings/

What will be the future equivalent?

I am missing the "contextId” mapping of server to cloud. Will there be any updates on this topic?

thanks

31

Hi @clouless

jira/classic:customFieldConfigScheme will be still supported from server migration mapping as new field scheme model is only going to be applied to Cloud, not in Server.

However, in the future, there will be new entity type that represents effective field scheme that you can use to figure out field’s association information that is being migrated from server to cloud.

Can you please help me to understand what you mean by

I am missing the "contextId” mapping of server to cloud. Will there be any updates on this topic?

Also would be great to know how you are using these migration mapping data for your app too as this will help us to how to plan the work to change the entity type mapping for server migration.

Thanks

Leanne

32

Hi Leanne,

Thanks for asking. First of all our app does not need the customFieldConfigScheme mapping, I was just curios because of the impacts of the RFC and the CHANGE-3019. What we really miss is the contextId mapping.

Our app provides delegated administration features so that normal users can work on custom field contexts and edit/delete/update options.

Therefore we actually do not care on which screens the custom field appears in, since we provide the user a direct list of fields+contexts. When the user clicks on the field he sees the field contexts which he has permissions for. And then he can click on the context he wants to edit and work on the options.

To achieve this we implemented our own app permissions. We can grant to users or groups to work on the entire field (global field permission) or to work only on single contexts (context permissions).

We basically store for example to grant user bob with userId=155 to field with fieldId=10064 and context X with contextId=12108 that has projectY with id=10008 and projectZ with id=10009

contextPermission => { fieldId=10064, contextId=12108, userId=155 }

When it comes to cloud migrations we can successfully map :green_square: these things:

  • userIds/userKeys
  • groupNames
  • fieldIds

But we cannot map :red_square: (because the mapping is missing)

  • contextIds

—-

I am currently working on a workaround where I use projects to map 1:1 with contexts and handle the global context differently.

:open_book: /rest/api/3/field/customfield_10064/context/projectmapping

{
  "maxResults": 100,
  "startAt": 0,
  "total": 84,
  "isLast": true,
  "values": [
    { "contextId": "10198", "isGlobalContext": true },
    { "contextId": "10476", "projectId": "10072" },
    ...
    { "contextId": "10553", "projectId": "10149" },
🩵  { "contextId": "12108", "projectId": "10008" },
🩵  { "contextId": "12108", "projectId": "10009" },
    { "contextId": "12109", "projectId": "10002" }
  ]
}

The workaround currently maps the server projectId to a cloud projectId. Per custom field I then have to get the projectmapping and match the contexts by projectId. Which is a lot of work and could be error prone. I need special handling for global context and maybe some workItem based contexts.

:fairy: My wish is simply to get a direct 1:1 server custom field contextId to cloud custom field contextId mapping. Or is the jira/classic:customFieldConfigScheme mapping really the contextId mapping already? And will it map to the cloud contextId even after the CHANGE-3019 changes?
Please clarify thanks.

that would be awesome :slight_smile:

1 Like
33

Hi @clouless,

The contextId will continue to work as it does today as part of this change. Technically the contextId maps to the field config scheme ID in Jira cloud so you maybe be able to use jira/classic:customFieldConfigScheme as a workaround. But important to note that the ID is not necessarily the same between server and cloud.

However as part of #CHANGE-3019 the role contexts play is changing slightly. They will no longer be used to restrict availability of fields to certain project and issue types, but they will continue to inform configurations like default values and options for fields. It sounds like your app handles managing options so will continue to use contexts.

One more thing, we are exploring future changes to contexts and how they’re mapped between server and cloud to try simplify that experience. I would recommend considering that when determining your approach for handling contexts, for example using jira/classic:customFieldConfigScheme may be a reasonable short term solution to unblock your use case until something more robust is available.

1 Like
34

Hi @JamesPetty ,

Thanks for the clarification. Is there any “contextId-Mapping Jira WorkItem” I can track to keep me up to date?

Thanks,

Bernhard

35

Hi @clouless,

There’s no ticket specifically for the contextId mapping. Changes to that would likely happen under broader changes to contexts. So I recommend following the jira cloud rest API tag and also keep an eye on the Jira platform change log.