External command

The sections under the External command editor tab (figure 13.4) are:

External application name
The name seen in the CLC Workbench Toolbox menu and given to the corresponding workflow element for this external application. This name is also used as the basis of the name to use to launch the external application using the CLC Server Command Line Tools.
Command line
The command run when the external application is launched. The information to provide differs for standard external applications and containerized external applications, and is described in more detail below for each case.

Parameters values that should be substituted at run time are written within {curly brackets}. This includes parameters that should be configurable by the end user. Other parameters and values are written as normal in this field.

General configuration
Parameter values specified in {curly brackets} in the Command line field will have a corresponding entry in the General configuration area. There, these values are configured, including specifying their type, and for some types, configuring the values to use or to be offered to end users to select from. The description of a parameter can be configured by clicking the tooltip icon (Image external_app_edit_tooltip) next to the parameter. The description will be displayed in clients, for example as a tooltip when running the external application from the CLC Workbench, or in the help listed for this application via the CLC Server Command Line Tools.

External application type
External applications can be "Standard (non-containerized)", or "Containerized: Docker". Standard external applications are executed directly on a server system. Containerized external applications are run from within containers.

To run containerized external applications, the containerized execution environment must be enabled and configured, as described in Configuring the containerized execution environment.

Command lines for standard external applications

The Command line field should contain the path to the application and all parameters to be passed to that application. For illustration, a simple example of the cp (copy) command with 2 positional parameters is shown in figure 13.4.

Command lines for containerized external applications

The Command line field should contain only the parameters to send to docker that are not already configured for the containerized execution environment, described in Configuring the containerized execution environment. These will usually be aspects of the command specific to running the individual external application.

For example, for a container with a command that takes one argument, the information written in this field could take the form:

<image-identifier> <command-to-run-from-image> <parameter>

The full docker command executed when an external application is launched combines the information configured for the containerized execution environment with the information provided in the Command line field. So, for example, if the default configuration settings for the containerized execution environment were used, the full docker command run when this external application is launched would take the form:

 docker run -v <import-export-dir>:<mount-point-in-image> \
    <image-identifier> <command-to-run-from-image> <parameter>

In figure 13.5, the command for a containerized external application running the alignment program MAFFT is shown as an example. That example is described in more detail in MAFFT example section.

Image external_app_containerized_command_line
Figure 13.5: The command line for a containerized external application contains an reference to the image, here the repository and tag have been used, but it could also be the image identifer, followed by the command to run from the container and the parameters to provide to that command. Here there is a single parameter, written in curly brackets, indicating that the value will be substituted at run time.

Parameter value types

Details of parameter value types are outlined below. A brief description is also provided in the web administrative interface when a value type is selected and the mouse cursor is hovered over it. Particularly important types for external application configurations are User-selected input data (CLC data location), which is the usual choice for parameters specifying input data, and Output file from CL, which is the usual choice for specifying results generated by the underlying application.

A very simple configuration illustrating parameter configuration is shown in figure 13.4 for the cp command. In the General configuration area, the Sequences to copy parameter is set to User-selected input data (CLC data location) meaning that the end user will specify the data to be copied from a CLC File Location. That data will be exported to a fasta format file. The Copied sequences parameter is set to type Output file from CL, indicating that this is the output from the command, and the standard fasta importer was selected for importing the results into the CLC Server.

A tip for exploring how many files an exporter will generate

A simple way to explore how many files an exporter will generate with a given configuration is to set up an external application using the echo command and a single parameter linked to the exporter of interest. Configure the "Standard out handling" option, selecting the "Plain text" option, described in Stream handling. The output from such an external application is a file, which is re-imported into the CLC Server as a text file. This file contains the full paths to the files the exporter created.

If an exporter is configured in a way that will lead to multiple output files, then the full path to each output file will be substituted in the command at runtime. The external application itself must be able to handle the outputs generated.


Configurable export parameters were introduced with CLC Genomics Server 10.0.