{"__v":42,"_id":"5637e95797666c0d008656ba","category":{"__v":11,"_id":"5637e8b2fbe1c50d008cb078","pages":["5637e95797666c0d008656ba","5637ea64ee0ee60d0024ec0e","5637f110daf0840d0011dcd5","563d423e9799fb0d0004779b","5640ba77b9c4dd0d0097c827","5640bad42b14f70d0039b8cd","5640bae32b14f70d0039b8cf","5640bb0ceaede117005c99d8","565f6b770dc99e1900f24c73","56cc9eab8fa8b01b00b81f5a","56ddcb9ab4ac273200457c82"],"project":"55faf11ba62ba1170021a9a7","version":"55faf11ba62ba1170021a9aa","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-02T22:50:26.865Z","from_sync":false,"order":14,"slug":"describe-your-tool","title":"DESCRIBE YOUR TOOL"},"parentDoc":null,"project":"55faf11ba62ba1170021a9a7","user":"554290cd6592e60d00027d17","version":{"__v":37,"_id":"55faf11ba62ba1170021a9aa","project":"55faf11ba62ba1170021a9a7","createdAt":"2015-09-17T16:58:03.490Z","releaseDate":"2015-09-17T16:58:03.490Z","categories":["55faf11ca62ba1170021a9ab","55faf8f4d0e22017005b8272","55faf91aa62ba1170021a9b5","55faf929a8a7770d00c2c0bd","55faf932a8a7770d00c2c0bf","55faf94b17b9d00d00969f47","55faf958d0e22017005b8274","55faf95fa8a7770d00c2c0c0","55faf96917b9d00d00969f48","55faf970a8a7770d00c2c0c1","55faf98c825d5f19001fa3a6","55faf99aa62ba1170021a9b8","55faf99fa62ba1170021a9b9","55faf9aa17b9d00d00969f49","55faf9b6a8a7770d00c2c0c3","55faf9bda62ba1170021a9ba","5604570090ee490d00440551","5637e8b2fbe1c50d008cb078","5649bb624fa1460d00780add","5671974d1b6b730d008b4823","5671979d60c8e70d006c9760","568e8eef70ca1f0d0035808e","56d0a2081ecc471500f1795e","56d4a0adde40c70b00823ea3","56d96b03dd90610b00270849","56fbb83d8f21c817002af880","573c811bee2b3b2200422be1","576bc92afb62dd20001cda85","5771811e27a5c20e00030dcd","5785191af3a10c0e009b75b0","57bdf84d5d48411900cd8dc0","57ff5c5dc135231700aed806","5804caf792398f0f00e77521","58458b4fba4f1c0f009692bb","586d3c287c6b5b2300c05055","58ef66d88646742f009a0216","58f5d52d7891630f00fe4e77"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-02T22:53:11.556Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Once you have uploaded an image containing your tool to the  [The CGC Image Registry](doc:the-cgc-image-registry) using the [Rabix Command Line Interface](sdk-overview), 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 CGC.\n\nThere are two ways to enter a description of the tool's interface:\n  * All of the features of a tool's interface can be described using the graphical tool editor on the CGC, which you can use in the browser.\n  * 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](doc:advanced-features-of-the-tool-editor#section-upload-your-own-cwl-tool-description). \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"On this page:\",\n  \"body\": \"* [Add a tool description with the tool editor](#section-add-a-tool-description-with-the-tool-editor)\\n* [Using the tool editor](#section-using-the-tool-editor)\\n   * [Basic principles](#section-basic-principles)\\n   * [Terminology](#section-terminology)\\n   * [The tool editor layout](#section-the-tool-editor-layout)\\n   * [A note on tool inputs](#section-a-note-on-tool-inputs)\\n   * [A note on arguments](#section-a-note-on-arguments)\\n   * [Dynamic expressions](#section-dynamic-expressions)\\n\\n* [Access the tool description as a JSON object](#section-access-the-tool-description-as-a-json-object)\"\n}\n[/block]\n##Add a tool description with the tool editor\nTo create a new tool description using the tool editor:\n1. [Navigate to your project](view-a-project).\n2. Click the **Apps** tab and select **+Add App**.\n3. Click **Create Tool**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f0KHBQTQVyYTjNqcx4Tw_create-a-tool-ed1.jpg\",\n        \"create-a-tool-ed1.jpg\",\n        \"815\",\n        \"491\",\n        \"#c29233\",\n        \"\"\n      ],\n      \"border\": true,\n      \"caption\": \"Create a tool\"\n    }\n  ]\n}\n[/block]\n4. Give your tool a name, and click the green Create button.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/k03zxDFkRLCPOKzA5IUy_Screenshot%202015-11-11%2014.37.58.png\",\n        \"Screenshot 2015-11-11 14.37.58.png\",\n        \"920\",\n        \"528\",\n        \"#366d4e\",\n        \"\"\n      ],\n      \"border\": true,\n      \"caption\": \"Name your tool\"\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Using the tool editor\n###Basic principles\nThe 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 CGC.\n\nThe 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](doc:install-and-run-samtools-sort).\n\n###Terminology\nThe 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:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"\",\n    \"0-0\": \"**Example command syntax**\",\n    \"0-1\": \"`cmd`\",\n    \"0-2\": \"`[-a]`\",\n    \"0-3\": \"`[num]`\",\n    \"0-4\": \"`[-f]`\",\n    \"0-5\": \"`[binary file]`\",\n    \"1-0\": \"**Tool editor terminology**\",\n    \"1-1\": \"base command\",\n    \"1-2\": \"prefix\",\n    \"1-3\": \"value\",\n    \"1-4\": \"prefix\",\n    \"1-5\": \"value\"\n  },\n  \"cols\": 6,\n  \"rows\": 2\n}\n[/block]\nThe **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**.\n\nThe following are all examples of **base commands**:\n  * `grep (no subcommand)`\n  * `bin/my-script.sh`\n  * `samtools sort`\n  * `bwa index`\n\nThe **prefixes** of a command line tool roughly correspond to its options, or flags, which are the single characters, such as `-f` or `-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**.\n\nThe following are all examples of **prefixes**:\n  * `-f`\n  * `-X`\n  * `INPUT=`\n\nThe **values** of the command line tool roughly correspond to its option arguments. However, there is an important difference between the two. The **value** can be either a literal that passed in as the option argument or an expression that resolves to the option argument. For the latter case, you may enter a JavaScript expression given in terms of features of the tool execution as a **value** of the tool; the value of this expression will be treated as the option argument for the **prefix** preceding it. Information on how to enter an expression in place of a literal is given in the documentation on [dynamic expressions in tool descriptions](doc:dynamic-expressions-in-tool-descriptions).\n\nThe following are all examples of **values**:\n  * `myfile.ext`\n  * `9`\n  * `$job.allocatedResources.cpu`\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n###The tool editor layout\nThe 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.\n\nInformation on the tabs is provided in the following five pages:\n\n  * [The tool's General Information](doc:general-tool-information) \n  * [The tool Input ports](doc:tool-input-ports) \n  * [The tool Output ports](doc:tool-output-ports) \n  * [Additional Tool Information](doc:additional-tool-information) \n  * [A Test tab](doc:test-the-tool-description) \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Pkr7NDkES6uUnTLdj1NJ_te3.png\",\n        \"te3.png\",\n        \"1350\",\n        \"934\",\n        \"#74a4c4\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n###A note on tool inputs\nIn 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..\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n###A note on arguments\nThe way that you specify the arguments of the subcommand being described depends on the argument type:\n  * Arguments related to inputs (files and parameter settings) are described on the **Inputs** tab.\n  * 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.\n  * 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. \n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n###Dynamic expressions\nThe icon **</>** in a field indicates that you can enter an expression in that field; i.e., rather than giving a literal value, you can specify that the value is a function of something else. Expressions are entered in JavaScript. See the page on [dynamic expressions in tool descriptions](doc:dynamic-expressions-in-tool-descriptions) for details of hardcoded variables that are available in these expressions, and examples of their use.\n\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Access the tool description as a JSON object\n\n\n\nOnce 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.\n\nTo access the CWL description of your tool from the tool editor click the ellipsis menu in the top right hand corner and select **Export Tool.** \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4f8fb09-export-a-tool-cgc-2.jpg\",\n        \"export-a-tool-cgc-2.jpg\",\n        706,\n        300,\n        \"#eef0f0\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\nAlternatively, you can use the API to download the CWL description of your tool. See the [documentation on the API for details](doc:get-details-of-an-app).\n\n<div align=\"right\"><a href=\"#top\">top</a></div>","excerpt":"<a name=\"top\"></a>Specify the interface of your tool","slug":"the-tool-editor","type":"basic","title":"The Tool Editor"}

The Tool Editor

<a name="top"></a>Specify the interface of your tool

Once you have uploaded an image containing your tool to the [The CGC Image Registry](doc:the-cgc-image-registry) using the [Rabix Command Line Interface](sdk-overview), 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 CGC. 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 CGC, 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](doc:advanced-features-of-the-tool-editor#section-upload-your-own-cwl-tool-description). [block:callout] { "type": "warning", "title": "On this page:", "body": "* [Add a tool description with the tool editor](#section-add-a-tool-description-with-the-tool-editor)\n* [Using the tool editor](#section-using-the-tool-editor)\n * [Basic principles](#section-basic-principles)\n * [Terminology](#section-terminology)\n * [The tool editor layout](#section-the-tool-editor-layout)\n * [A note on tool inputs](#section-a-note-on-tool-inputs)\n * [A note on arguments](#section-a-note-on-arguments)\n * [Dynamic expressions](#section-dynamic-expressions)\n\n* [Access the tool description as a JSON object](#section-access-the-tool-description-as-a-json-object)" } [/block] ##Add a tool description with the tool editor To create a new tool description using the tool editor: 1. [Navigate to your project](view-a-project). 2. Click the **Apps** tab and select **+Add App**. 3. Click **Create Tool**. [block:image] { "images": [ { "image": [ "https://files.readme.io/f0KHBQTQVyYTjNqcx4Tw_create-a-tool-ed1.jpg", "create-a-tool-ed1.jpg", "815", "491", "#c29233", "" ], "border": true, "caption": "Create a tool" } ] } [/block] 4. Give your tool a name, and click the green Create button. [block:image] { "images": [ { "image": [ "https://files.readme.io/k03zxDFkRLCPOKzA5IUy_Screenshot%202015-11-11%2014.37.58.png", "Screenshot 2015-11-11 14.37.58.png", "920", "528", "#366d4e", "" ], "border": true, "caption": "Name your tool" } ] } [/block] <div align="right"><a href="#top">top</a></div> ##Using the tool editor ###Basic principles 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 CGC. 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](doc:install-and-run-samtools-sort). ###Terminology 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: [block:parameters] { "data": { "h-0": "", "0-0": "**Example command syntax**", "0-1": "`cmd`", "0-2": "`[-a]`", "0-3": "`[num]`", "0-4": "`[-f]`", "0-5": "`[binary file]`", "1-0": "**Tool editor terminology**", "1-1": "base command", "1-2": "prefix", "1-3": "value", "1-4": "prefix", "1-5": "value" }, "cols": 6, "rows": 2 } [/block] 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)` * `bin/my-script.sh` * `samtools sort` * `bwa index` The **prefixes** of a command line tool roughly correspond to its options, or flags, which are the single characters, such as `-f` or `-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**: * `-f` * `-X` * `INPUT=` The **values** of the command line tool roughly correspond to its option arguments. However, there is an important difference between the two. The **value** can be either a literal that passed in as the option argument or an expression that resolves to the option argument. For the latter case, you may enter a JavaScript expression given in terms of features of the tool execution as a **value** of the tool; the value of this expression will be treated as the option argument for the **prefix** preceding it. Information on how to enter an expression in place of a literal is given in the documentation on [dynamic expressions in tool descriptions](doc:dynamic-expressions-in-tool-descriptions). The following are all examples of **values**: * `myfile.ext` * `9` * `$job.allocatedResources.cpu` <div align="right"><a href="#top">top</a></div> ###The tool editor layout 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: * [The tool's General Information](doc:general-tool-information) * [The tool Input ports](doc:tool-input-ports) * [The tool Output ports](doc:tool-output-ports) * [Additional Tool Information](doc:additional-tool-information) * [A Test tab](doc:test-the-tool-description) [block:image] { "images": [ { "image": [ "https://files.readme.io/Pkr7NDkES6uUnTLdj1NJ_te3.png", "te3.png", "1350", "934", "#74a4c4", "" ] } ] } [/block] <div align="right"><a href="#top">top</a></div> ###A note on tool inputs 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.. <div align="right"><a href="#top">top</a></div> ###A note on arguments 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. <div align="right"><a href="#top">top</a></div> ###Dynamic expressions The icon **</>** in a field indicates that you can enter an expression in that field; i.e., rather than giving a literal value, you can specify that the value is a function of something else. Expressions are entered in JavaScript. See the page on [dynamic expressions in tool descriptions](doc:dynamic-expressions-in-tool-descriptions) for details of hardcoded variables that are available in these expressions, and examples of their use. <div align="right"><a href="#top">top</a></div> ##Access the tool description as a JSON object 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 click the ellipsis menu in the top right hand corner and select **Export Tool.** [block:image] { "images": [ { "image": [ "https://files.readme.io/4f8fb09-export-a-tool-cgc-2.jpg", "export-a-tool-cgc-2.jpg", 706, 300, "#eef0f0" ], "border": true } ] } [/block] Alternatively, you can use the API to download the CWL description of your tool. See the [documentation on the API for details](doc:get-details-of-an-app). <div align="right"><a href="#top">top</a></div>