External applications integration: Basic configuration
Many aspects of configuring external tools in the CLC Science Server can be described as we set up a very simple command. We have chosen the cp command as will already be on your server.
The cp command requires at minimum two parameters, an input file and an output file. These parameters are positional: the first filename given after the command is the input file, the second is the output file. Here we will just copy a FASTA file from one place in the CLC Science Server to another. This is a very inefficient way of doing this task, but it will illustrate how to integrate a command line tool without requiring you to install additional software on your system.
Under the External Applications tab of the CLC Science Server administrative web interface, click on the New configuration button. This brings up a window like the one shown in figure 8.2. In the text box labeled External applications command name, enter a name for this command. This will be what the end-users see in the menu option that they will be presented with via the Workbench. In the text box labeled command line argument, provide the command line. Start with the command, and within curly brackets, include any parameter that needs to be configured by the user. The names of the parameters inside the curly brackets will become the labels of the choices offered to the end-user when they start up this external application via their Workbench. Figure 8.2 shows how this looks if we give the cp command two parameters: in and out.
Figure 8.2: Setting up the cp command as an external application.
Two drop-down menus have now appeared in the blue shaded area of the window in figure 8.2. These are dynamically generated. Each parameter you enter in curly brackets in the command text box area will have a drop-down menu created for it. The text you entered within the curly brackets is used to label the entries in the administrative interface, and are also the labels used in the end-user interface presented via the Workbench.
The administrator now chooses the type of data each parameter will refer to. The options are:
- Text - The users are presented with a text box allowing them to enter a parameter value. The administrator can provide a default value if desired.
- Integer - Allows the user to enter a whole number. The administrator can choose a number this option should be set to by default. If none is set, then 0 is the default.
- Double - Allows the user to enter a number. The administrator can choose a number this option should be set to by default. If none is set, then 0 is the default.
- Boolean text - This generates a checkbox in the end-user interface, labeled with the text you provide. If the user clicks in the box, the parameter is set to true; an empty box means the parameter is set to false.
- CSV enum - This allows the administrator to set a drop down list of parameter choices for the user.
- User-selected input data (CLC data location) - Users will be prompted to select an input file from those they have stored on the CLC Server.
- User-selected files (Import/Export directory) - Users will be prompted to select one ore more input files among those stored in an Import/Export directory on the CLC Server. This will typically be non .clc-files. Preselected files can be set.
- Output file from CL - Users will be prompted for a location to store a file that is created by the third-party application. An extra text box is also provided in the configuration so the administrator can specify a default name for the re-imported file. If no filename is provided by the administrator, the basename of the file from the system is used.
- File - Users can select an input file from their local machine's filesystem.
- Context substitute - This parameter is only for the Command Line and is not visible to the end user. The parameter results in substitution by a value in the context where the Command Line is run. Options are: CPU limit max cores: The configured limit at the server executing the Command Line. Name of user: The name of the user that has initiated the External Application.
- Boolean compound - This enables the creation of a checkbox, where if checked, the end-user is presented with another option (of your choice). If the check box is not checked, then that option will be grayed out. Here, the administrator can also choose if the box is to be checked or unchecked by default in the Workbench interface.
- Text - The users are presented with a text box allowing them to enter a parameter value. The administrator can provide a default value if desired.
- Integer - Allows the user to enter a whole number. The administrator can choose a number this option should be set to by default. If none is set, then 0 is the default.
- Double - Allows the user to enter a number. The administrator can choose a number this option should be set to by default. If none is set, then 0 is the default.
- Boolean text - This generates a checkbox in the end-user interface, labeled with the text you provide. If the user clicks in the box, the parameter is set to true; an empty box means the parameter is set to false.
- CSV enum - This allows the administrator to set a drop down list of parameter choices for the user. For an example of this, please see section External applications integration: Velvet on setting up Velvet as an external application.
- User-selected input data (CLC data location) - Users will be prompted to select an input file from those they have stored on the CLC Server.
- User-selected files (Import/Export directory) - Users will be prompted to select one ore more input files among those stored in an Import/Export directory on the CLC Server. This will typically be non .clc-files. Preselected files can be set.
- Output file from CL - Users will be prompted for a location to store a file that is created by the third-party application. An extra text box is also provided in the configuration so the administrator can specify a default name for the re-imported file. If no filename is provided by the administrator, the basename of the file from the system is used.
- File - Users can select an input file from their local machine's filesystem.
- Context substitute - This parameter is only for the Command Line and is not visible to the end user. The parameter results in substitution by a value in the context where the Command Line is run. Options are: CPU limit max cores: The configured limit at the server executing the Command Line. Name of user: The name of the user that has initiated the External Application.
- Boolean compound - This enables the creation of a checkbox, where if checked, the end-user is presented with another option (of your choice). If the check box is not checked, then that option will be grayed out. Here, the administrator can also choose if the box is to be checked or unchecked by default in the Workbench interface.
In the right hand side of figure 8.2 we set the parameters so that the input file to be sent to the system's copy command will be specified by the user, and we tell the system to export this file from the CLC Science Serveras a FASTA file. We then configure the import of output file from the copy command back into the CLC Science Server, and specify that we are importing a FASTA file. When configuring standard bioinformatics third party applications, you are able to choose from many standard formats to export from, and to import back into, the CLC Science Server.
Once the configuration is complete and has been saved, the external application should now appear in the list in the administrative web interface.
The small checkbox to the left of the external application name should be checked. This means it is will be accessible to those with the Workbench plugin installed. If a particular external application needs to be removed from end-user access for a while, this small box can just be unchecked.