Description

The CLI provides a large number of list actions. Actions like getIssueList, getProjectList, and getSpaceList to list a few. In many cases, the content of the list depends on the setting of the outputFormat parameter. This page describes what output formats are all about. Automation sensitive to application data changes should use the list support of output formats to achieve a good levels of upward compatibility. Data produced by non-list actions do not benefit from this approach and are subject to change . 

Why Output Formats?

There are a few important reasons for output formats:

1. Upward compatibility. Anybody who has written automation scripts knows that software upgrades can break automation! The CLI already shields automation from many Atlassian application changes over time. However, new application capabilities must also be supported as time goes on. One technique the CLI uses to minimize breakage is the use of output formats for list actions. This technique enables us to add support for new fields without breaking automation. When new fields need to be added, a new output format is used to expose the new fields for use cases that need the new information.
2. Performance. Many list actions can provide a wealth of information but may require additional processing in order to gather all the information. This can have an impact on both the client and server. The primary contributor to slower elapsed time and addition server load is having to make multiple remote requests to the server. For example, a list of summary data may be available with a single request from the server, but, more detail information may require a separate request for each entry in the list. For use cases that only need the summary information, this would be a unnecessary burden increasing elapsed time and server load. The CLI uses different output formats to manage this so that summary and detail use cases can both be handled.

What Output Formats are Available?

Output formats are unique to each list action. If an list action supports multiple output formats, they will be indicated in the Action Reference in the Output formats column. There is a default output format (1) so that the outputFormat parameter does not need to be provided for the simplest use cases. As a general rule, specifying --outputFormat 999 will result in all available fields being listed. The number of fields available may change on CLI upgrades. Don't use output format 999 in automation if your automation is sensitive the output data contents.  

The specific content of an output format is best determined by just running the action with the specified output format. In some cases, we have published example output. However, this does not cover all cases.

• JIRA CLI example output
• Confluence CLI example output

Controlling Output Data with the Columns Parameter

There is another technique automation can use to protect itself from upward compatibility issues as well as perhaps simplifying logic. The columns parameter is available on list actions - it will subset the columns available to only those listed. Furthermore, it allows the column order to be changed. Both of these features can simplify automation logic. The columns parameter is a comma separated list of column names (case insensitive) or column numbers (1-based). Ordering of the columns determines field ordering in the output data.