External command

The sections under the External command editor tab (figure 15.8) 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. The parameter value types are described in detail further below.

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.

Image extapp-editor-mafft-1
Figure 15.8: The External command tab in the external application editor

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, an external application using the cp (copy) command with 2 positional parameters is shown in figure 15.9.

Image extappcopyseqsconfig
Figure 15.9: This simple external application includes the 2 arguments the cp command expects: the source and the destination.

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 15.10, the command for a containerized external application running the alignment program MAFFT is shown as an example.

Image extapp-editor-mafft-1
Figure 15.10: The command line for a containerized external application contains an reference to the image followed by the command to run from the container and the parameters to provide to that command. Parameters in curly brackets are substituted at run time.

Parameter value types

Details of parameter value types are provided below. Particularly important types for external application configurations are Data from CLC location, which is the usual choice for parameters specifying CLC data as input to be analyzed by the command line application, and Output from CL, which is the usual choice for specifying results generated by the underlying application.

To see a brief description while working in the web administrative interface, select a value type, and then hover the mouse cursor over it.

A very simple configuration illustrating parameter configuration is shown in figure [*] for the cp command. In the General configuration area, the Sequences to copy parameter is set to Data from CLC 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 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.

Output from CL

The Output from CL option is used for parameters that define an output of the command line application. This output can be a file or a folder containing files. When Output from CL is selected, a drop down list appears with options for how the output should be handled:

Setting default values and locking parameters

When configuring exports and imports, default settings can be configured, and you can control which values are editable when launching the external applications. Click on the Edit parameters button when available, and then click on the symbol of a lock image to open or lock that parameter (figure 15.11). Once unlocked, changes can be made. A parameter with an unlocked symbol beside it will be displayed to the end user and its value will be editable. Locked parameters are not shown when launching the external application and cannot be changed by end users.

Image extappexportparamconfig
Figure 15.11: Clicking on the "Edit parameters" button for the "Sequences to copy" parameter brings up a window with the editable parameters for the selected exporter. Parameters with a locked symbol beside them are not shown to, and are thus not configurable by, the end user.

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.