The use of fields has grown in scale and complexity over the years, and we’ve witnessed increased scalability and reliability issues. For that, our team has been working on an architectural refresh that will allow Jira admins to better control the fields used in their projects.
Those changes will only affect team-managed projects.
Publish: Oct 16, 2024
Discuss: through early access ETA 8th Nov 2024
Resolve: TBC end of early access
Problem
By default, all global custom fields are considered associated with all team-managed projects. Given that our APIs return much of the issue’s data by default, the payloads returned by our APIs are getting bigger, to the point where we see OOM (out of memory) errors on the Jira Cloud platform. The growing payloads are impacting the reliability of all of the systems involved. For example, it can increase response time when calling endpoints and result in rate limiting.
The scope of API changes in this RFC is to address the reliability, performance, and scalability concerns outlined above. Please read on and give us feedback on the proposed API changes
Proposed Solution
A new page will allow project admins to manage the fields available in each of their team-managed projects. The list of fields on that page specifies which fields are associated with a given project and issue type.
Affected APIs
The following APIs providing the fields parameter will be affected, with all and navigable field sets being narrowed down to only those fields that are explicitly added to the project.
Similar changes will be applied to webhooks, with the issue data that is sent by the webhook limited to the fields explicitly added to the project.
When these changes are rolled out, your app will need to:
Be able to handle receiving a partial list of fields that can differ between projects and between project/issue-types depending on the custom fields the admin has configured for each project and issue type
Be prepared for an admin potentially removing access to a required custom field from a project or project+issue type in which the app is used, at any time
Early access and feedback
We will be running an early access program for those changes so that you can test them ahead of time and provide your feedback.
What happens if I specify a field in the fields parameter which is not added to the project (anymore)? The ideal behavior in my eyes would be to ignore this field and return the rest of the information. I think this is more robust than returning an error.
Could you also please offer an API to apps which return all configured fields for a project? This way, apps can proactively know which fields they can expect which also helps when showing field lists to users in an app so that they configure details for it. That request could look like the get fields endpoint with an additional project query parameter added to it.
Even better would be if the API works for team-managed and company-managed projects, but maybe I’m dreaming too much
I don’t see any issues with the proposed solution for our plugin.
What would be great addition is the 2nd Point of Matthias. We have a project configuration within our plugin where the user can select a list of fields and we prefer to only display fields that are related to this project. Currently we need to iterate over all issue types within the team managed project (one request per issue type) to get all fields that are available.
returning an error for issue search fields parameters would be very bad from my apps perspective, as these are pre-configured, so a user would have to change the configuration in the app immediately once a field is removed from the project scope.
an easier way to get all editable fields per project would also be appreciated
What happens if I specify a field in the fields parameter which is not added to the project (anymore)?
It’s a bit complicated topic to be honest, we are currently considering 2 outcomes:
in the worst case such fields will be ignored and the rest of the data will be returned as requested
in the majority of cases the data for such field will be returned, provided the user has the necessary permissions
Could you also please offer an API to apps which return all configured fields for a project ?
Yes, we are aware of this gap and we are planning to address it. While I can’t provide a specific timeline right now, it’s something we’re likely to include in this project.
We are considering extending Get fields paginated endpoint to provide more options for filtering results.
And yes, such API will work for all projects, yet results for company-managed projects will likely to include way more fields.
Thanks for reaching out! Could you provide a bit more context on how those fields are being utilized on your end? It’s worth noting that fields becoming unavailable for a specific project is a known scenario since Jira admins have the ability to restrict certain fields. Have you encountered similar issues in the past?
On the topic of team-managed projects and custom fields, the only way to have a custom field apply to those projects is to create a global context: neither Jira’s “Modify configuration scheme context” page nor the API let you pick individual team-managed projects, whereas company managed projects are available to be selected.
This is sort of a problem for some apps, for example for JMCF we either have to calculate fields on every single issue on an instance (aka: a lot of unnecessary work) or we can’t support team-managed projects.
The same also applies to adding a custom field to a screen: it’s not possible through the API and the user has to manually go in the project settings and add the field, which breaks their flow.
What happens if I specify a field in the fields parameter which is not added to the project (anymore)?
Either way of the two solutions you outlined would be fine for our app.
Could you also please offer an API to apps which return all configured fields for a project ?
Yes, we are aware of this gap and we are planning to address it. While I can’t provide a specific timeline right now, it’s something we’re likely to include in this project.
This statement makes my day. I’d love to finally have this API - happy to provide feedback to a possible API any time. Please make sure that you don’t need admin permissions for this, “administer project” or even better “browse project” permissions should be enough in my eyes.
The app (Advanced Story Maps) is using the configured fields in two ways:
Users can customize the look of their issue cards, which is similar to how Jira Agile boards do it.
story maps can display cards based on swimlanes, with custom field options defining those swimlanes
Because of this, the selected field will need to be added to the issue search field parameter. If the issue search handles the missing field gracefully, we can also do so, making it easier for users to re-configure their map if needed.
neither Jira’s “Modify configuration scheme context” page nor the API let you pick individual team-managed projects
Yes, that’s a well-known problem and this project is a first step towards fixing it. We are planning to make a lot of changes for how fields are configured, as the current experience is often confusing and inconvenient.
we either have to calculate fields on every single issue on an instance (aka: a lot of unnecessary work) or we can’t support team-managed projects.
Am I right and what you want is “get a list of fields applicable to a given project” and the only way to achieve this at the moment is to look at every issue in a team-managed project?
If that’s the case, then our changes should make it easier for you, as there will be an API that returns a list of fields that were associated with the project by the admin.
The same also applies to adding a custom field to a screen
Yes, that’s another gap in our public APIs. Unfortunately, it’s not something that we could provide at the moment, as “screens” are not really applied to team-managed projects.
Overall, we are moving towards replacing “screens” with “issue layouts” and as a part of that work we will also provide new rest APIs to manage them. Unfortunately, I can’t share any timeline on this one at the moment.
Hi @matthias, I am working on the new API that would return all configured fields to a project. I would like to understand your requirements, namely: will you use this API to fetch one project at a time, or multiple? If multiple, how many projects will you need to fetch in one HTTP call?
Our requirement right now is to only fetch one project at a time.
Depending if you want to design it for one or multiple projects, I’d follow the same behavior as some of the existing endpoints:
