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

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

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 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	field	The field parameter covers both field and value with a key = value syntax

Changed Output Formats

Clients	Action	Change	Reason

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

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.

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/acli-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 ... "

Appfire Command Line Interface (CLI)

Special Compatibility Notice for CLI Version 9.x