Once you have uploaded an image containing your tool to the Seven Bridges Image Registry using Docker, you should provide a description of the tool's interface. The interface includes details of the tool's input and output ports, its command options, and the CPU and memory resources it requires. Providing this information writes a Common Workflow Language tool description, and allows your tool to be connected arbitrarily in workflows on the Seven Bridges Platform.
There are two ways to enter a description of the tool's interface:
- All of the features of a tool's interface can be described using the graphical tool editor on the Seven Bridges Platform, which you can use in the browser.
- Alternatively you can supply your own description of the tool in accordance with the Common Workflow Language. Read more on instructions on the protocol for the Common Workflow Language.
To create a new tool description using the tool editor:
- Navigate to your project.
- Click the Apps tab and select +Add App.
The Add apps window will be displayed.
- Click Create New App.
- Click Create a Tool.
- Give your tool a name, as shown below, and click Create.
The tool editor is used to capture the interface of a tool, so that it can be be used in conjunction with other imported tools, and with existing workflows on the Seven Bridges Platform.
The way the tool editor works is to build up a command that looks like the command you would enter in your terminal to run the tool, using variables in place of specific filenames or parameter values. Its use will become clearer with examples, given in the general introduction to the editor on this page, and in the extended example given in the SDK Tutorial, Worked example of uploading SamTools Sort.
The tool editor uses the terminology of the Common Workflow Language to refer to the syntax of a command line utility. The terms map onto syntax items as follows:
Example command syntax
Tool editor terminology
The base command of a command line tool is the first part of any command, before any arguments are specified. It is the utility name, together with any subcommand of the utility, in the case that the utility has multiple subcommands (for example, as a tool package will). If you need to specify a path to the utility, then the full path constitutes the base command.
The following are all examples of base commands:
grep (no subcommand)
The prefixes of a command line tool roughly correspond to its options, or flags, which are the single characters, such as
-X that follow the base command and are modified by option arguments. However, the notion of a prefix is slightly wider than the notion of an option. Specifically, if a tool requires option arguments to be passed in such a way that the option argument is not separated by a space from the option argument, but instead by some non-empty string, such as '=' then this separator is also part of the prefix.
The following are all examples of prefixes:
The following are all examples of values:
The tool editor consists of five tabs, corresponding to different parts of the tool description, some additional details used to label the tool in graphical interfaces, and a tab on which you can test the correctness of a tool description.
Information on the tabs is provided in the following five pages:
In the tool editor, you will be prompted to describe a tool's inputs. Inputs in this sense include data, such as files, as well as parameters, such as integers, or arrays..
The way that you specify the arguments of the subcommand being described depends on the argument type:
- Arguments related to inputs (files and parameter settings) are described on the Inputs tab.
- Arguments that are not related to any specific input—such as those based on resources allocated to the job—can be entered in the Arguments field on the General Information tab.
- The executable name of the subcommand, and any other part of the command that you want to fix for every execution of the tool is entered in the field Base Command on the General Information tab.
Once you have described a tool in the tool editor, you can access its Common Workflow Language description as a JSON object. If you want to familiarize yourself with writing CWL by hand, inspecting these automatically generated files can be helpful.
To access the CWL description of your tool from the tool editor, select Export Tool from the ellipsis menu in the top right hand corner.
Alternatively, you can use the Seven Bridges API to download the CWL description of your tool. See the documentation on the API for details.