Continue Protocol

Description

For script writers, error handling is an important consideration. Whether you are writing automation scripts in your favorite scripting language or constructing CLI scripts, it is important to know what is going to happen on error conditions so they can be handled appropriately. Each CLI client follows strict error handling protocol described in Atlassian CLI Error Handling

The CLI goes further in implementing enablers to make it easier to ignore or handle various error situations and minimize scripting. This is where the continue parameter comes in.

Continue for Run Actions

The CLI provide common run actions like runrunFromCsv, runFromSql, and runFromList. More importantly, the are many client specific runFrom... actions. Each of these actions takes advantage of the continue parameter to cover 2 different use cases:

  1. Stop running actions as soon as the first one fails - this is the default behavior for run actions.
  2. Continue running actions even if there are failures and just report a failure summary at the end - this is covered by add --continue to the run action.

Continue for Specific Actions

There is also a case for some specific actions to deal nicely with certain error conditions. Usually, this fails in the category of ignoring errors that I don't care about. There are a class errors that are commonly ignored by script writers and the CLI wants to make it easy in those cases while, at the same time, making sure normal errors will surface for other use cases. For this reason, we have defined a protocol that certain action should implement. We continue to implement this protocol where it make sense and where historical support may not have followed the protocol. Only actions specifically stating they support the continue parameter have implemented the protocol.

The errors covered by this are:

  1. Trying to add or create an entity that already exists - for many scripting cases, the script only cares that the entity exists one way or the other
  2. Trying to remove or delete an entity that does not exist - many clean-up activities only care about things not being there

Other examples are add users to groups, removing users from groups, and similar.

In these cases, we only want those specific errors to be ignored but still want to be informed about more general (less common) errors that still need to be handled in a script or by manual intervention. By using the continue parameter on those actions we can easily ignore the errors and spend our time on other things