Summary

SOAP to REST APIs

Many of Jira's remote APIs (SOAP APIs) that have been used historically in the Jira CLI will be removed from Jira 7.0. Replacement remote APIs (REST APIs) are available in Jira 7.0.

The Jira Server version of Jira 7.0 is expected to be released by Atlassian later this year. However, Jira Cloud has already been updated.

Little to no impact after both updates

This notice is let Jira CLI customers know that they will be able to move to Jira 7.0 with little or no impact, as our ongoing Jira CLI updates will adapt to the new interfaces under the covers. In fact, over the past years, some interfaces have already been converted to the new APIs or new functions have been implemented using the new APIs.

In some cases the API implementation used is based on the release level of the Jira instance being accessed. This technique will continue to be used as some of the replacement APIs are only available on Jira 7.0 and higher.

In most cases, CLI usage will continue to work the same with only minor differences. In some advanced scripting scenarios, some adjustments may be needed to scripts. Details follow. 

If You Use Jira Server

If you are using Jira Server, you can choose to move to CLI 4.5 release at any time as you normally would do for other upgrades. Of course, if you have installed Jira 7.0, you will need to upgrade to access that server. If you are still on Jira 6.x, you will only minimally impacted from the changes indicated below. Most of the potential incompatibilities discussed below are specific to the CLI support switching over to REST APIs for issue related actions and that switch-over is affects Jira 7.0 server interactions. The existing issue related APIs are used for Jira 6.x servers. This will change with Release Notes 5.0 when issue actions will default to REST APIs even for Jira 6.4 servers. The Legacy Support section below goes into more details.

Potential Incompatibilities

While we strive to maintain upward compatibility of the interfaces by hiding many of the differences in the underlying Jira APIs, some incompatibilities may surface. Here's a quick list of some things to be on the lookout for: 

1. Text of error messages may be different. In some cases, the error message from the underlying API is surfaced directly and these have been changed by Atlassian. In other cases, we are issue our own messages and these may have changed.

2. The class of error may have changed. If your script is sensitive to the exact return value (-1 versus 3 exit codes for example) then your script may need to be updated. Some errors formerly resulting from Jira errors (error code -3) may now be intercepted and sent from the client (error code -1) likely with some additional information.

3. Additional enforcement of correct behavior. The legacy APIs often silently ignored incorrect input. The new APIs are much stronger in enforcing rules. For instance, trying to update a field that is not available for update on appropriate screen will now result in a error. Previously the field was just ignored. Update: For the specific error of the field not being available on the screen, you can now use --continue to IGNORE the field and continue with the update or transition.

4. getIssueList format of fields will be slightly different compared to legacy support. Note: legacy support will still be used on Jira 6.x with release 4.5.

   • Format will be the new JQL based output format introduced with the jql parameter a few releases ago.

   • Custom fields based on option values will now be their string representation instead of the option id. Use withId to have the string value augmented with the internal id.

   • Array fields will be a comma separated list of string values (unquoted) and without separating spaces.

5. Custom fields will be alphabetically ordered (natural ordering) on getIssue and getIssueList.

6. getIssue has some changes

   • Re-organized fields - a few fields are moved for better display. And custom field ordering as noted in the bullet above.

   • Some new fields have been added.

   • Will now return the custom field string value followed, by default, by the internal id. Use suppressId if ids are not wanted just like for other fields.

   • User fields will now default to show the internal user key. Use suppressId if ids are not wanted just like for other fields.

7. Date custom fields will now be expected in the format specified on the dateFormat parameter (or client default format) just like other Jira date fields.

8. For create issue, Jira defaults will now be used instead of CLI specific defaults when the parameter is not provided. This is for fields like priority, assignee, and similar.

9. getCustomFieldList output format will be like getFieldList. To get the legacy format, use –columns id,name. 

10. deleteProject will now report an error if the project does not exist. Use --continue to revert to the previous behavior to ignore a not found error.

11. Some actions will be deprecated. Some are no longer available with the REST APIs and others have better replacement actions based on the newer support. 

    • login and logout actions

    • progressIssue is deprecated, new support is available using transitionIssue

    • getAvailableSteps is deprecated, new support is available using getTransitionList

12. Some parameters are deprecated (ignored) when used with the new issue support.

    • asVersion

    • asComponent

    • asCascadeSelect

    • login

    • loginFromStandardInput

13. Work (worklog) actions like removeWork now require an issue key along with the work log id.

14. For issues, Jira has adopted the term remaining estimate and so the CLI will be changing current estimate to remaining estimate.

15. Jira 7.0 has changed the project creation defaults and behavior - see Project Creation Default Changes.

16. For the addUser action, email notifications have changed. Prior to Jira 7.0, an email was automatically sent to the user. For Jira 7.0 and higher, specify notify to send an email, otherwise the default is to not send an email.

17. getProjectList adds 2 new columns to all outputFormats - Default Assignee and Project Type. 

Legacy Support

For CLI release 4.5, most issue support will continue to use the legacy SOAP APIs for customers on Jira 6.1.x - 6.4.x. REST APIs will be used for Jira 7.0 and higher.

For CLI release 5.0, issue support will default to the new REST APIs for customers on Jira 6.4.x. For a limited time, legacy issue support will continue to be available for these Jira releases by adding the legacy parameter to the action. This parameter should only be used if you have a specific need for the older behavior. This is provided to make it easier to migrate scripts. Where necessary, the Jira CLI will continue to use a legacy API in cases where the newer API is not available for the Jira release of the instance.

Additional Details

Atlassian Issues

Testing has uncovered some issues with the Jira REST API support. We are working with Atlassian to resolve or mitigate these to minimize impact to customers through this transition. This includes leaving some of the legacy support active for a period of time as discussed above.

Watch This Page

Watch this page for updates as more information becomes available.