Set Up Command Orchestration

Note about who can administer Container Service features
As of Container Service version 3.7.0+ and XNAT version 1.9.2+, Site Admin can no longer administer features of Container Service. A user with Container Manager Role and Privileged Role can administer the Container Service. These roles can be additionally granted to the Site Admin to be able to administer Container Service.

What is Command Orchestration?

A command orchestration enables a user to set off a chain of commands that will operate in sequence, starting from any existing command. Each command must operate on the same data type (i.e. at the subject, session, or scan level) but does not necessarily need to operate on the same piece of data.

Defining a Command Orchestration

In order set up command orchestration, you need to first Add a Command in your XNAT and then Enable a Command in Your Project.

To set up orchestration, navigate to Administer → Plugin Settings. In the Command Orchestration tab, click the Set up orchestration button.

In the modal that comes up, provide a name for your orchestration, and select the commands you wish to orchestrate. The first command is going to define the context of the orchestration, meaning the type of XNAT object on which the commands run (project, subject, session, scan, etc.).

Whichever command is set as the first command of a command orchestration will always run the full orchestration in any project where this orchestration is enabled. As a best practice, we encourage Container Administrators to add a custom command definition to act as the first step in an orchestration, which allows for independent operation of any other command that you want to orchestrate.

For now, you can only orchestrate commands with a common context, so commands with a context that differs from that of your first selection will be disabled. Commands that have not been enabled on the site will also be disabled.

Starting with Container Service version 3.7.0, a flag haltOnCommandFailurehas been added as part of the Orchestration setup. This flag is set to true by default, that is, for an ordered sequence of commands which constitute an orchestration, if any command fails, none of the remaining commands downstream are executed.

You can click the "Add command" button to add additional commands, and use the "X" to remove a command. Note that you need at least two commands to constitute an orchestration. 

You may also click and drag commands to change their order in the orchestration.

When you are satisfied with your orchestration, click the "Save" button.

Managing Command Orchestrations

You may add as many orchestrations as you would like, and you may disable or delete orchestrations to temporarily or forever prevent use. Doing either will remove the orchestration from any project that has selected it. If you later re-enable an orchestration from site level, you will need to re-add it to any projects.

If you edit an orchestration, you will need to retain the common context. If you try to swap, you won't be able to save:

An orchestration must have at least two commands as part of the orchestration.

If you disable a command that is used in an enabled orchestration, the orchestration will be disabled and removed from any projects.

However, if you re-enable the orchestration, the commands it needs will automatically be re-enabled as well.

Once you have set up orchestrations at the site level, you (or any project owner) may add them to a project.