Description
We always are sensitive to upward compatibility of our offerings and specifically want to make sure CLI scripts are as upward compatible as possible at least with the respect to those aspects that are under our control. Most of our actions remain compatible across a wide range of Atlassian application releases and even to high degree across Server and Cloud environments. However, on a CLI version boundary, we do take the opportunity to remove previously deprecated support or make some changes especially where it will simplify new user experiences and remove clutter for users. This page describes some of the important changes to be aware of when upgrading to 9.x from 8.x or earlier.
Also, there were a few incompatibilities introduced at a later time. Script Compatibility Warnings for 9.3 and higher:
- JSON output changes - ACLI-1438 and ACLI-1453
- getIssue action - new project name field added to all output formats - see ACLI-1215
- findReplace and findReplaceRegex parameters - no longer supports comma separated values - see ACLI-917
Removed Actions
| Clients | Removed | Replacement | Discussion |
|---|---|---|---|
| jira | getLoginInfo | getUser | Similar information is part of the getUser action for the current user (default with no parameters) |
| jira | progressIssue | transitionIssue | Terminology change made in 4.x |
| jira | getAvailableSteps | getTransitionList | Terminology change made in 4.x |
| jira | createBoard | agile client | With delegated support, there should be no impact as a jira request is automatically routed to the agile client |
| jira | deleteBoard | agile client | With delegated support, there should be no impact as a jira request is automatically routed to the agile client |
| jira | getBoardList | agile client | With delegated support, there should be no impact as a jira request is automatically routed to the agile client |
| upm | addAddon | addApp | Atlassian terminology change from addon to app. |
| upm | disableAddon | disableApp | Atlassian terminology change from addon to app. |
| upm | enableAddon | enableApp | Atlassian terminology change from addon to app. |
| upm, confluence | getAddon | getApp | Atlassian terminology change from addon to app. |
| upm | getAddonList | getAppList | Atlassian terminology change from addon to app. |
| upm, confluence | installAddon | installApp | Atlassian terminology change from addon to app. |
| upm | runFromAddonList | runFromAppList | Atlassian terminology change from addon to app. |
| bamboo | createOrUpdatePlan | createPlan | Better options are now available on createPlan to cover use cases. |
Removed Parameters
| Clients | Removed | Replacement | Discussion |
|---|---|---|---|
| confluence | -t short flag for title | title | CLI standards are to use -t short flag for token, so Confluence needed to change to be consistent. |
| upm, confluence | addon | app | Atlassian terminology change from addon to app. |
| jira | board | agile client | With delegated support, there should be no impact as a jira request is automatically routed to the agile client |
servicedesk, bamboo | field3, field4, field5, field6, field7, field8 | field | The newer field parameter can be used multiple times and provides a better solution
|
servicedesk, bamboo | value3, value4, value5, value6, value7, value8 | field | The field parameter covers both field and value with a key = value syntax |
Changed Output Formats
| Clients | Action | Change | Reason |
|---|---|---|---|
| jira | getProjectRoleActorList | See JCLI-1562 | Add more user fields important for Cloud |
| jira | getProjectRoleActorByUserList | See JCLI-1562 | Add more user fields important for Cloud |
| confluence | getUserList | See CSOAP-1105 | Switch to more standard CSV format by default |
| confluence | getGroupList | See CSOAP-1105 | Switch to more standard CSV format by default |
| confluence | getBlogList | See CSOAP-1105 | Switch to more standard CSV format by default |
| bitbucket | getRepositoryList | See SCLI-137 | Terminology change from Slug to Repository |
| bitbucketcloud | getRepositoryList | See BCCLI-17 | Terminology change from Slug to Repository |
Deprecated Parameters
This is a notice that we have deprecated some other parameters so you can start migrating any scripts to the new support over time. It is likely these will be removed in a later version. This was part of an ongoing effort to simplify some usage scenarios and prune our interfaces to avoid confusion. As a related note, we now support multiple specifications for the findReplace and findReplaceRegex parameters and therefore are deprecating the older usage scenario of a comma separated list of colon separated pairs. This usage is still supported for compatibility at least for the near future, however, the legacy support only works if the action does not use the multiple support by using more than one of the parameters.
| Clients | Deprecated | Replacement | Discussion |
|---|---|---|---|
| jira | custom | field | It is a better practice to use multiple field parameters instead of a comma separated list and thus avoid quoting and delimiter complexities. |
| jira | field2,values, values2 | field | No longer needed with the use of multiple field parameters. |
| servicedesk | fields | field | It is a better practice to use multiple field parameters instead of a comma separated list and thus avoid quoting and delimiter complexities. |
| servicedesk | field1, field2, value1, value2 | field | No longer needed with the use of multiple field parameters. |
bamboo | fields | field | It is a better practice to use multiple field parameters instead of a comma separated list and thus avoid quoting and delimiter complexities. |
Start Scripts and Configuration
Since CLI 8.4, we have made significant improvements to ease user setup and configuration customization. More information on this is available with Getting Started with Configuration for Mac and Linux. This provided another option for users while maintaining existing support.
With CLI 9.x, we are discontinuing providing legacy start scripts in the distribution in favor a much simpler start script that optionally supports a saved configuration. Start scripts continue to be customizable and users can continue to use their existing customizations with only minor changes if they want or they can adopt the new start script layout and take advantage of the configuration options available with the new support. We strongly recommend adopting the acli style start script and configuration now available in the distribution.
Feedback
If you have feedback on this change or related areas, please add your comments to ACLI-760.
Migrating Legacy Start Scripts
Many people continue to use the original jira, confluence, or similar start scripts that have been in the distribution since the beginning. Some may have switched over to and customized the atlassian start script
- If you haven't customized the these, then the acli start script included in the distribution will most likely work out in a similar fashion right away.
- If you have customized the script, it will need a small change as indicated below. We will use jira as an example, but all the others are similar. In summary, we have changed the jar name to acli that works for all clients. It accepts an optional first value of the client name. If the client name is not provided as the first parameter, the CLI will look for the right client to use for your specific action and parameters.
java -jar "%dirPath%"/lib/jira-cli-8.8.0.jar %* change to java -jar "%dirPath%"/lib/acli-9.0.0.jar jira %*
java -jar `dirname $0`/lib/jira-cli-8.8.0.jar "$@" change to java -jar `dirname $0`/lib/jira-cli-9.0.0.jar jira "$@"
The Atlassian script may have one or more lines that reference the call string. Each reference will need to be changed.
callString="jira-cli-${cliVersion}.jar ... "
change to
callString="acli-${cliVersion}.jar jira ... "
