Special Compatibility Notice for CLI Version 9.x

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.

Removed Actions

ClientsRemovedReplacementDiscussion
jiragetLoginInfogetUserSimilar information is part of the getUser action for the current user (default with no parameters)
jiraprogressIssuetransitionIssueTerminology change made in 4.x
jiragetAvailableStepsgetTransitionListTerminology change made in 4.x
jiracreateBoardagile client

With delegated support, there should be no impact as a jira request is automatically routed to the agile client

jiradeleteBoardagile clientWith delegated support, there should be no impact as a jira request is automatically routed to the agile client
jiragetBoardListagile clientWith delegated support, there should be no impact as a jira request is automatically routed to the agile client
upmaddAddonaddAppAtlassian terminology change from addon to app.
upmdisableAddondisableAppAtlassian terminology change from addon to app.
upmenableAddonenableAppAtlassian terminology change from addon to app.
upm, confluencegetAddongetAppAtlassian terminology change from addon to app.
upmgetAddonListgetAppListAtlassian terminology change from addon to app.
upm, confluenceinstallAddoninstallAppAtlassian terminology change from addon to app.
upmrunFromAddonListrunFromAppListAtlassian terminology change from addon to app.
bamboocreateOrUpdatePlancreatePlanBetter options are now available on createPlan to cover use cases.

Removed Parameters

ClientsRemovedReplacementDiscussion
confluence-t short flag for titletitleCLI standards are to use -t short flag for token, so Confluence needed to change to be consistent.
upm, confluenceaddonappAtlassian terminology change from addon to app.
jiraboardagile clientWith 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

  • field1/value1 and field2/value2 were kept as is to lessen impact and as an alternative for some cases

servicedesk,

bamboo

value3, value4, value5,

value6, value7, value8

fieldThe field parameter covers both field and value with a key = value syntax

Changed Output Formats

ClientsActionChangeReason
jiragetProjectRoleActorListSee JCLI-1562Add more user fields important for Cloud
jiragetProjectRoleActorByUserListSee JCLI-1562Add more user fields important for Cloud
confluencegetUserListSee CSOAP-1105Switch to more standard CSV format by default
confluencegetGroupListSee CSOAP-1105Switch to more standard CSV format by default
confluencegetBlogListSee CSOAP-1105Switch to more standard CSV format by default
bitbucketgetRepositoryListSee SCLI-137Terminology change from Slug to Repository
bitbucketcloudgetRepositoryListSee BCCLI-17Terminology 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.

ClientsDeprecatedReplacementDiscussion
jiracustomfieldIt 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

fieldNo longer needed with the use of multiple field parameters.
servicedeskfieldsfieldIt is a better practice to use multiple field parameters instead of a comma separated list and thus avoid quoting and delimiter complexities. 
servicedeskfield1, field2, value1, value2fieldNo 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.
Example - jira.bat
java -jar "%dirPath%"/lib/jira-cli-8.8.0.jar %*
 
change to 

java -jar "%dirPath%"/lib/acli-9.0.0.jar jira %*
Example - jira.sh
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.

Example - atlassian.sh
callString="jira-cli-${cliVersion}.jar ... "

change to 

callString="acli-${cliVersion}.jar jira ... "