Feedback for Bulk Ops APIs (Beta)

[Mandeep Singh]

Hello Atlassian Community,

While Bulk Ops APIs are currently slated to release in Q3 2024, we are inviting all Atlassian users to join the Beta program right now! Participants in the Beta will experience firsthand how these APIs can streamline your workflows, save you time, and improve organizational productivity.

This is a great opportunity to provide tailored feedback that will help us refine feature capabilities over time, making it even more valuable to you.

Please share your valuable feedback on Bulk Ops APIs in this group.

Some of the topics on which you can provide us the feedback are:

1. Please explain your use case of bulk operation

2. How do you perform these use cases currently?

3. What do you think could be improved?

4. Did you encounter any difficulties while integrating or consuming our API?

5. Did you encounter any error messages?

6. Were the error messages helpful in troubleshooting issues?

7. Is there any additional functionality you would like to see?

8. Did you find our API documentation comprehensive and easy to follow?

9. Did you face any difficulty in authentication & permissions?

10. Did you experience any downtime or latency issues?

11. Are there any other specific pain points or areas that you think need should be addressed?

12. How would you rate your overall experience using our API?

You can either give your feedback in this article via comments or join me for a video call.

I would love to chat with you and take your feedback on Bulk Ops APIs. You can book a slot with me here - https://calendly.com/msingh_11/30min

Thanks,

Mandeep Singh

Sr. Product Manager - Bulk Ops APIs

[Jack Hunter [HeroCoders]]

Hello Mandeep Singh,

We need a bulk update to allow us to set different values on the given field for different issues. Several other vendors raised the same requirement in the comments on the corresponding Jira ticket. 

Cheers,
Jack

[Mandeep Singh]

Hey @Jack Hunter [HeroCoders] , for the use case you mentioned, it is not possible currently. But you can call the APIs multiple times to make those desired changes.

[Brent Jenkins]

Hi @Mandeep Singh this is wonderful news!  Perfect timing - I expect to be able to make use of this immediately.

One question:  is this API accessible via Jira Cloud?  I cannot access this URL:

https://<my-domain>.atlassian.net/rest/api/3/bulk/issues/fields

(where <my-domain> is replaced with my actual Jira Cloud domain name in the URL above)

[Mandeep Singh]

Hey @Brent Jenkins , ideally it should work.

Can you share the screenshot with us about the error you're facing while consuming the APIs.

Otherwise you can book a 30 mins slot with me so that we can understand the problem in a better way. Here is my Calendly to book.

[Brent Jenkins]

Thanks @Mandeep Singh it is indeed working now.  Must have been down when I tried on July 12th.  I can't remember the exact error, but it was as if the API endpoint didn't exist.

[Tom Hudgins]

Hi,

Very timely. I need to automate moving an issue (a Service Desk request actually) from one project to another. 

I'm just starting to look at the bulk move API (very familiar with using the API in general) and I'm a little confused on the targetMandatoryFields portion. There is a retain field which can be either true or false. A true values says 'will try to retain original non-null issue field values on move'. That sounds great but you also have type and value which are required. If I set retain to true, I still have to supply a value. Will the value I specify only be used if the original value can't be used for some reason? 

For example, I want to copy the Description field from the source issue to the new one. I want to set retain to true but do I need to also get the current value of Description and send it (as ADF) in the value field? 

[Mandeep Singh]

Hi @Tom Hudgins 

Here is the use case which explains the above query:

Let say you're moving 10 issues. For 4/10 issues, 'description' field has value (or text) and the other 6/10 issues do not have any value in 'description' field.

Now you're moving these 10 issues together with 2 cases:

1. Retain value set as True

In this case, the 4 issues with description already filled, they will carry the original value and rest 6 issues will get new value which is entered by the user.

2. Retain value set as False

In this case, all 10 issues will get new value which is entered by the user.

I would highly encourage you to try these APIs and give us the feedback. Here is the calendly to book a 30 mins session with me.

[Tom Hudgins]

Thanks for the explanation Mandeep.

So, sounds like if I KNOW the issues I'm moving have a value in the description field and I want to keep it, I can supply a dummy value in the value parameter and it won't be used.

I just want to avoid having to make API calls to read the value of the description field for all the issues I'm moving if I know I'm keeping the current value.

[Tom Hudgins]

I've got this working for my use case: single issue, between JSM projects. I retain the Summary and Description fields and just set the Request Type for the target project. If it helps anyone, here's a script I run in my Scriptrunner script console to test.

import org.slf4j.Logger
import org.slf4j.LoggerFactory

class Jira {
    Logger logger
    def Jira() {
        logger = LoggerFactory.getLogger(Jira.class);
    }
    
    def moveIssue(String issueKey, String newProject, String newIssueTypeId, Map fieldInfo){
        Map payload = [
            sendBulkNotification: true,
            targetToSourcesMapping: [
                "${newProject},${newIssueTypeId}": [
                    inferClassificationDefaults: true,
                    inferFieldDefaults: false,
                    inferStatusDefaults: true,
                    inferSubtaskTypeDefault: true,
                    issueIdsOrKeys: [issueKey],
                    targetMandatoryFields: [[fields: fieldInfo]]
                ]
            ]
        ]
        //return payload

        def result = post("/rest/api/3/bulk/issues/move")
            .header('Content-Type', 'application/json')
            .body(payload)
            .asObject(Map)
        
        if (result.status == 201){
            return result.body
        } else {
            logger.info("Failed to move issue: Status: ${result.status} ${result.body}")
            return null
        }        
    }
}

String issueKey = 'HELP-56591'
String targetProject = "BIZAPPS"
String targetRequestId = "322"
String targetIssueTypeId = "12107"

Jira jira = new Jira()

Map dummyADF = [content: [ [ content:[ [text:"dummy",type:"text"]],type:"paragraph"]], type:"doc",version:1]

Map fieldInfo = [
    "description":[type:"adf", retain: true, value: dummyADF],
    "summary":[type:"raw", retain: true, value: ["dummy"]],
    "customfield_10500":[type: "raw", retain: false, value: [targetRequestId]]
]

def result = jira.moveIssue(issueKey,targetProject,targetIssueTypeId,fieldInfo)

[Suraj Goel]

Hello @Tom Hudgins 

Just an additional detail, if all the issues you are moving have the mandatory field in the target project already filled in - then you keep

'inferFieldDefaults' as true and no need to provide 'targetMandatoryFields' mapping

[Tom Hudgins]

Thanks but in my use case, I keep the value of Summary and Description but set a new value for Request Type. So it seems like I can't set InferFieldDefaults to true right?

[Suraj Goel]

Hello @Tom Hudgins ,

That's correct. If you want to provide a new value for any field for any issue that do not have that field filled in and the field is mandatory in target project - you will have to provide a valid targetMandatoryFields object - for which `inferFieldDefaults` will have to be kept false

[Brent Jenkins]

It appears this API does not support modifying the sprint field?  "Sprint" does not appear in the fields listed by the GET editable fields call.  When I try to POST a request to edit the sprint, anyway, it returns an error:

"Invalid request payload. Refer to the REST API documentation and try again."

I've tried using the multipleSelectFields and singleSelectFields properties, but both return the same error.

It would be really great if this were supported because, e.g. bulk edit is the only way currently to add a ticket to a sprint that has already been closed (not a best practice I understand, but sometimes necessary to correct mistakes).

Another use case is everybody gets spammed every time we're moving a lot of tickets between sprints during planning, and the only way to avoid that is to create custom notification schemes.  Using bulk edit, I can simply disable the notification sent when the sprint changes.

[Mandeep Singh]

Hey @Brent Jenkins , the sprint field is editable and it should appear. Could you pls share the screenshot of the issue you're facing?

[Brent Jenkins]

Thanks @Mandeep Singh , that is good news.  It appears then I'm struggling with something else.  I am not sure what I am doing wrong, but I cannot figure out how to set an option on single or multiple select fields.

For example, this request body works to successfully clear all options on a custom multi-select field:

{
"editedFieldsInput": {
"multipleSelectFields": [
{
"fieldId": "customfield_12345",
"options": []
}
]
},
"selectedActions": [
"customfield_12345"
],
"selectedIssueIdsOrKeys": [
"PROJECT-1234"
],
"sendBulkNotification": false
}

However, this request body produces the "Invalid request payload" response when trying to add an option: 

{
"editedFieldsInput": {
"multipleSelectFields": [
{
"fieldId": "customfield_12345",
"options": [33333]
}
]
},
"selectedActions": [
"customfield_12345"
],
"selectedIssueIdsOrKeys": [
"PROJECT-1234"
],
"sendBulkNotification": false
}

I've used the GET API to verify I am entering the correct number for the option Id. 

Similarly, I also get "Invalid request payload" when simply trying to clear the value for a single select field using this request body:

{
"editedFieldsInput": {
"singleSelectFields": [
{
"fieldId": "customfield_23456",
"option": -1
}
]
},
"selectedActions": [
"customfield_23456"
],
"selectedIssueIdsOrKeys": [
"PROJECT-1234"
],
"sendBulkNotification": false
}

Alternatively, I am able to change other fields successfully, such as Priority, a  custom single line of text field, etc.  Any ideas?

[Tom Hudgins]

I haven't tried this but it looks like you need to supply an array of objects not just an array of optionIds. 

This part of the example:

 "multipleSelectFields": [ 
   { "fieldId": "<string>", 
     "options": [ 
       {} 
     ] 
   } 
], 

shows the '{}' in the options array. I would try something like this:

"multipleSelectFields": [ 
{ "fieldId": "<string>", 
"options": [ 
{"optionId": 33333} 
] 
} 
], 

[Brent Jenkins]

Thanks, @Tom Hudgins !  I haven't had a chance to try your suggestion out, either, but I suspect you are right.

[Brent Jenkins]

Jira Automation does not have a "Move" action, so we are now using this new bulk API along with a Web Request action in an automation rule.  Thus, not a "bulk" move, but much simpler for moving single tickets!

Here's our use case:

We have an "INBOX" project where people create tickets to be triaged to different development groups.  We then hold regular triage calls with representatives from each of those groups to decide to which group to assign each new ticket.  Each group has its own project in Jira, so we move tickets from the "INBOX" project to the respective group's project as assignments are made during the triage calls.

Using the Move command available in Jira from the pop out menu on each ticket is burdensome because it takes way too many clicks to simply move a ticket that is going to another project that shares the exact same schema.  It also fills up the browser navigation history with every step of the Move wizard.  That means we lose the "Return to Search" and Previous/Next buttons on the ticket's page and we have to click Back in the browser several times to get back to where we were at triaging a list of tickets one by one.  When doing this for a dozen tickets one by one it eats up valuable time for a bunch of busy people having to sit and watch all of these clicks.

Yes, I'm aware there are various ways to do this all differently that could be more efficient, but regardless the tools as they have existed up until now have been frustrating.

My automation rule has a manual trigger so that is appears under the "Actions" menu on every ticket.  It takes user input as to which project to move the current ticket.  Below is a screenshot of the web request.  You can see I am able to utilize smart values from the automation rule in the request body, namely the destination project selected on the user input, the destination issue type I've defined by a variable, and the trigger issue: i.e.:  {{userInputs.newProject}}, {{typeID}}, and {{issue.key}}.

This saves a ton of clicks and I can refresh the page to see the ticket assigned to the new project without losing the "Return to Search" button.

[Suraj Goel]

Hello @Brent Jenkins Glad to hear the APIs are helping you saving valuable time !

[Ricardo Martinez]

Hi

Is it possible to transition in Bulk?

[Suraj Goel]

Hello @Ricardo Martinez

There are not APIs to bulk transition but you can use the backlog of any project to bulk transition issues from the UI - this was released a while back. 

Let me know if that works for you

[Brent Jenkins]

@Mandeep Singh I'm a little confused about why some non-mandatory fields are retained during a move while others are not, and whether there is some way to retain all of them.  If I understand the documentation correctly, the "inferFieldDefaults" property when set to true is only intended to retain values of fields that are mandatory in the destination project. 

I've noticed "Fix Versions" and "Components" are not retained, while "Labels" and other fields I've tested are retained.  None of these fields are mandatory in the destination project.  Regardless, I have set "inferFieldDefaults" to "true."  The same choice of Fix Versions, Components, and Labels exist in both projects.

Questions:

1. Is there some way to configure the payload such that ALL fields are retained, when possible, even those that are non-mandatory?

2. If not, is there some way to specify in the payload the values to set in the destination for non-mandatory fields?  The documentation appears to suggest that the "targetMandatoryFields" property only works with mandatory fields.

3. What determines which non-mandatory fields are retained vs. not?

4. Is there some way to enumerate all fields that will not be retained between given projects, e.g. by using the Get bulk editable fields API or parsing the Bulk move API's response?

[Suraj Goel]

Is there some way to configure the payload such that ALL fields are retained, when possible, even those that are non-mandatory?

So "inferFieldDefaults" is not used for retaining the field value but trying to provide default values for mandatory fields (in destination project) that are empty in the issues you are moving.

For actual retaining you have to set "retain" boolean in each field group. The issues that have that value already filled in will not change to the new value

 If not, is there some way to specify in the payload the values to set in the destination for non-mandatory fields?

This is not supported. You can not set values for "non-mandatory" fields in bulk move because that is not the main use case of bulk move. It just fill gaps for fields which are missing in issues you are moving and are mandatory in destination project.

Also one caveat - if every issue you are moving have the mandatory field value filled in - it will not matter if you provide "retain" as true or not - but the API won't pick up the new value that you provided because all the issues already have those values filled in

What determines which non-mandatory fields are retained vs. not?

I hope the answer to this is clear from above.

Is there some way to enumerate all fields that will not be retained between given projects, e.g. by using the Get bulk editable fields API or parsing the Bulk move API's response?

The bulk move API should be giving you an error response when it needed a value for a field but was not provided.

For your question of "Fix versions" and "Components" not being retained - these fields are project scoped and hence even if they have same text value - underneath they are different fields altogether between different projects

[Brent Jenkins]

@Suraj Goel 

For your question of "Fix versions" and "Components" not being retained - these fields are project scoped and hence even if they have same text value - underneath they are different fields altogether between different projects

Thanks, that's what I suspected.  This might be something you want to consider adding to the documentation to save others some head scratching.  The interactive bulk move in Jira does not have this limitation.

Since I'm calling the move API from a Jira Automation web request action, I am able to follow that web request with an action to simply copy the Components and Fix Version fields from the trigger issue to itself.  This works because the automation has preserved those values in memory even though they were removed from the actual ticket by the move API.

Most importantly, I'm able to identify we have no other project scoped fields I'm aware of, so I don't need to worry about doing this with any other non-mandatory fields.

[umits2009]

Hi @Mandeep Singh  Is bulk operation available in JIRA DC or only for jira cloud? If yes for JIRA DC, can you point me to the documentation?