RFC-41: Bulk Edit & Bulk Move REST APIs

General Request for Comments (RFC)
,
1

Summary of Project:

We’ve built Bulk Edit API and are building Bulk Move API (Bulk Ops REST APIs) to enable the customers to create their own use cases by consuming these APIs and perform the changes involving Editing and moving issues in bulk and be independent of our Front end.

We’re initiating an Early Access Program (EAP), where certain limitations with APIs (such as max no. of issues and fields which can be changed) will be present. It’s crucial to emphasize that this stage involves preliminary testing and doesn’t reflect the final state of Bulk Ops APIs.

Throughout this process, we anticipate numerous adjustments based on feedback and what we’ve learned over time. We’re especially interested in hearing your inputs regarding any potential impacts of Bulk Ops APIs on apps that we might have overlooked.

The RFC schedule is:

  • Publish: 14th March 24
  • Discuss: 28th March 24
  • Resolve: 4th April 24

Problem

Bulk Edit and Bulk Move operations are quite frequently used by our customers to edit and move issues in bulk. Presently, customers rely on the front end to execute these actions, limiting them to the use cases available within our front-end interface.

There are many customers who have asked for the dedicated APIs for performing the operations like Bulk editing and Bulk move on issues in Jira Software.

The proposed solution will enable the customers to consume API and build their own use cases. More than 850 customers have asked for these APIs to be built.

Proposed Solution

We’ve built Bulk Edit API and are building Bulk Move REST API for users to consume and build their use cases. The customers will not be dependent on our front end.

Bulk Edit API Features
Get Fields API 1. Search for fields
2. Return paginated results
3. Default fields(based on most used fields)
4. Returns an unavailable message when a field in not bulk editable to indicate the reason.
Submit API 1. Ability to edit field values for multiple field types
2. Clear field values
3. Versions, Labels and Component fields (Cascading FieldTypes) have additional options:
3a. Replace with given value
3b. Clear field
3c. Add to existing
3d. Find and remove values
Get Progress API 1. Progress of the bulk operation in percentage
2. Successfully edited issues(issueIds)
3. Failed Issues
4. Failure reasons(if any)
Bulk Move API Features
API INPUTS
1. Issue ID
2. Target Project keys
3. Target Issue Type
4. subtasks ↔︎ parent map [Optional] (Only needed if subtasks are moved or issue is converted into a subtask)
5. Target Issue Status
Submit API * Move Issue(s) from Single Source Project to Single Target Project
* Move Issue(s) from Single Source Issue Type to Single Target Issue Type
* Ability to specify values for mandatory fields in target project
* Ability to specify values for status transition in target project
* Document defaults?
Get Progress API 1. Progress of the bulk operation in percentage
2. Successfully edited issues(issueIds)
3. Failed Issues
4. Failure reasons(if any)

Limitations

As this will be an Early Access Program, there will be some limitation on the number of issues and the number of fields which can be operated at once.

Implementation/API consumption

These APIs will have REST endpoints for which we’ll release an API document near to the start of EAP.

Asks

We’re trying to learn through RFC about:

  1. Any feedback you have to this RFC even if it’s simply giving it a supportive “Agree, no serious flaws”.
  2. What do you think about the flexibility of building your own use cases with consumption of these APIs?
  3. Are there other ways this may impact that we haven’t anticipated?
  4. What other feedback do you have to make API consumption better in the future?

We would love to have a 1:1 conversation with Partners. You can go ahead and book a slot from my Google calendar.

Sign up for the Partner Early Access Program if you’re interested in accessing these Bulk Ops REST APIs in the EAP environment.

6 Likes
2

Hi @MandeepSingh1,

Thank you for sharing this.

It looks like this will be a very valuable feature for us.

We don’t see any flaws with this and this will enable us to implement several important features.

In particular, we are keen to be able to use the API to:

  • copy values from one custom field to another
  • move issues from a team-managed project to a company-managed one
2 Likes
3

@MandeepSingh1 this is not an RFC, this is an EAP announcement. If you want input from partners with regard to the problem space, please create an RFC prior to building the proposed solution.

CC: @ibuchanan @Anthony

10 Likes
4

Hi, will the fields API return details about allowable values. At the moment, it is only possible to get this from create and edit meta APIs. It would be nicer if I didn’t have to iterate over every project asking for the allowable values.

Regards
Paul

1 Like
5

Will the Bulk Move API only allow movement of an issue to a project of the same type (ie. move from a company managed project to another company managed project) or will it facilitate ‘crossing’ the project types? (ie move from company managed project to team managed project and vice-versa)?

6

@MandeepSingh1 Do you have any details on what the additional options for components, version, etc will be?

7

This looks like something that will be of use for us in our application!

Getting info about allowable values, as mentioned by @paul, is important for us too, so that we can prevent users from trying to modify issues a head of the operation instead of reporting failure.

Thanks,
Fredrik

1 Like
8

Hi @MandeepSingh1,

I cannot access the EAP signup form. Looks like the permission is limited to Atlassian org.

9

Hello,

Thanks for the RFC.

At the moment we don’t have a real use case in any of our apps related to it but, have you taken into account how webhooks/listeners will react to issue edit or move operations in bulk?

Have a nice day!

10

Hi Paul,
The details about allowable values will be available with Bulk Edit API.

1 Like
11

You will be able to move multiple issues, but they must all be moved to and from a single project & issue type.

12

Can you elaborate more on this?
Do you mean adding/removing/replacing the values on the fields?

13

Hi chhantyal,

Could you pls use the EAP form https://forms.gle/eQDeG42sLdFKvWKV8

14

@MandeepSingh1 since versions and components are only for a project I was wondering how the interface handles this. Do you specify mappings from one to the other (Comp 1 in proj X maps to comp 3 in proj Y).

15

Would it be possible while using the bulk edit API to pass different field values for different issue ids?

There are plenty of possible use cases: bump by one step the priority of a list of issues, add a comment that contains the summary of the issue (or the assignee, or whatever, any dynamic data)…

Of course I don’t expect Jira to provide built-in scripting to calculate the values for each issue, but something like

type NewValuePayload = string

interface BulkEditFieldsRequest {
  issues: IssueId[]
  fields: Array<{
    action: 'edit' | 'clear' | 'replace' | 'add' | 'remove'
    value: NewValuePayload | Record<IssueId, NewValuePayload>
  }>
}

Would let us calculate everything on our end and submit a single API call instead of having to make one for each issue

1 Like
16

Hi @paul

Consider this small snippet from the Bulk Move API:

{
  "targetToSourcesMapping": {
        // standard issue input.
        "MTCJ,10007": {
            "issueIdsOrKeys": ["MTCJS-2"],
            "inferFieldDefaults": false,
            "inferStatusDefaults": false,
            "inferSubtaskTypeDefault": true,
            "targetMandatoryFields": [
                {
                    "fields": {
                        "fixVersions": {
                            "value": ["10008"]
                        },
                        "description": {
                            "retain": true
                        },
                        "customfield_10000": {
                            "value": ["value-1", "value-2"],
                            "retain": false
                        }
                    }
                }
            ]
        }
  }
}

Currently, we don’t support separate mappings for separate version types when moving from source project to target project. You can only specify a single value which will replace all the field values of source issues. Components also work in a similar way.
If Retain: true, it means issues which have fields already populated will retain the field value provided it is valid in the target project.

We’ll also release Bulk Edit API in a few weeks, which will support ‘Add’, ‘Delete’ , ’Replace’ & ‘ReplaceAll’ etc. for fields in a list of issues.

17

Currently, we do not support this use case. You would need to make separate API calls for each issue.

18

Thanks for the community feedback and your patience as we learn how to best navigate RFCs & EAPs. We didn’t hear anything in the RFC feedback that would indicate we should halt the EAP. As such, we continue to appreciate your participation and feedback. If you haven’t already, please sign up for the EAP, and provide your feedback.