{"__v":13,"_id":"5637ea64ee0ee60d0024ec0e","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":"554340dfb7f4540d00fcef1d","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:57:40.083Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"* [Annotating output files with metadata](#section-annotating-output-files-with-metadata)\\n* [Custom input structures for tools](#section-custom-input-structures-for-tools)\\n* [Describing index files](#section-describing-index-files)\\n * [Attaching index files to data](#section-attaching-index-files-and-data-files) \\n* [Upload your own CWL tool description](#section-upload-your-own-cwl-tool-description)\\n* [Configure the log files for your tool](#section-configure-the-log-files-for-your-tool)\",\n  \"title\": \"On this page\"\n}\n[/block]\n##Annotating output files with metadata\n\nYou may want to annotate the files produced by a tool with metadata, which will then be used by other tools in a workflow. See the [metadata for your private data](doc:metadata-for-private-data) page for a list of  commonly used file metadata. You can choose the the name and type of these metadata by defining your own key-value pairs. Any keys can be used, but see this list for commonly used file metadata.\n\nTo enter key-value pairs that will be added to output files as metadata, click on any output port that you have listed on the Outputs tab. There is a field for **keys** and a field for **values**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/iD7nsOrORDS8jztuoeKn_Screen%20Shot%202015-05-29%20at%2013.15.59.jpeg\",\n        \"Screen Shot 2015-05-29 at 13.15.59.jpeg\",\n        \"1851\",\n        \"811\",\n        \"#526f8a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Using dynamic expressions to capture metadata:\",\n  \"body\": \"Metadata values can be string literals or dynamic expressions. For instance, the `$self` object can be used to refer to the path of the file being outputted. See the documentation on dynamic expressions in tool descriptions for more details.\"\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Custom input structures for tools\n\nCertain tools will require more complex data types as inputs than simply files, strings, and so on. In particular, you may need to input arrays of structures. This requires you to define a custom input structure that is essentially an input type that is composed of further input types. A common situation in which you'll need to use a complex data structure is to when the input to your bioinformatics tool is a genomic sample. This will consist of, say, a BAM file and a sample ID (string), or perhaps two FASTQ files and an insert size (int).\n\n**To define a custom input structure:**\n\n1. On the** Inputs** tab of the tool editor select the Data Type as **array** from the drop-down list.\n2. This will then prompt you for an **Item Type**; in this field, you should select '**record**' to define your own types. In the example shown below we have given the array the **ID** 'Custom_input'. You can give it any name you choose.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/OnZYZK4MSqLDCdVGlKeg_Screen%20Shot%202015-05-29%20at%2013.01.35.png\",\n        \"Screen Shot 2015-05-29 at 13.01.35.png\",\n        \"1784\",\n        \"314\",\n        \"\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\n3. Once you have created the input array and saved it (closing the window), you can define its inputs. To do this, click on the array in the list of inputs on the **Inputs** tab. This will bring up a button marked **+ **labeled **Click the plus button to define a field**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/SdwBWmFWQue1IVooEgEQ_Screen%20Shot%202015-05-29%20at%2013.03.11.png\",\n        \"Screen Shot 2015-05-29 at 13.03.11.png\",\n        \"3184\",\n        \"468\",\n        \"#415f6c\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\n4. The **+** button lets you define the individual input ports that the array is composed of. You define the input ports of an input array in the same way as you would usually define an input port for a tool. In our example, let's set the array data structure to take three inputs, two of which are FASTQ files, and the third of which is the insert size. We'll label the input ports with the **ID**s 'FASTQ_1', 'FASTQ_2' and 'Insert_size' respectively. We set the **Type** of the first two to **File**, and the **Type** of the third as** int**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/lZaH1VOATdafHmPVRkqR_Screen%20Shot%202015-05-29%20at%2012.57.21.png\",\n        \"Screen Shot 2015-05-29 at 12.57.21.png\",\n        \"2518\",\n        \"1034\",\n        \"#278ed1\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Describing index files\n\nSome tools generate index files, such as .bai, .tbx, .bwt files. Typically, you will want the CGC to treat indexes as attached to their associated data file, so that they will be copied and moved along with the data file in workflows. To represent the index file as attached to its data file you should make sure that:\n\n1. The index file has the same filename as the data file and is stored in the same directory as it.\n2. You have indicated in the tool editor that an index file is expected to be output alongside the data file. \n\nTo do this: \n\nOn the** Outputs** tab of the editor, enter the details of the data file as the output. Under **Secondary Files** enter the extension of the index file, modified according to the following convention:\n\nSuppose that the index file has extension '.ext'.\n  * If the index file is named by simply appending '.ext' onto the end of the extension of the data file, then simply enter .ext in the Secondary Files field. For example, do this if the data file is a .bam and the index extension is .bai (see example A).\n  * If the index file is named by replacing the extension of the data file with '.ext', then enter ^.ext in the the Secondary Files field. For example, when the data file is a fasta contig list and the index extension is .dict (see example B). \n\nIn example A, we have named the output port 'BAM' and set up globbbing to catch files whose names contain '.bam' to be designated as its outputs. We have also specified that a secondary file is expected, and that it should have the same name as the BAM file, but have extension '.BAI' appended to the file extension of the BAM file.\n[block:image]\n{\n  \"images\": [\n    {\n      \"caption\": \"Example A\",\n      \"image\": [\n        \"https://files.readme.io/oqDF6ejiRDi382B1atMn_Screen%20Shot%202015-05-29%20at%2013.20.18.png\",\n        \"Screen Shot 2015-05-29 at 13.20.18.png\",\n        \"1792\",\n        \"748\",\n        \"#1f87d6\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\nIn example B, the output port is named 'Reference' and it catches files whose names contain 'fasta'. We have specified that an index file is expected, and that it will have the same file name as the FASTA file but that the extension '.DICT' will replace the extension of the FASTA file.\n[block:image]\n{\n  \"images\": [\n    {\n      \"caption\": \"Example B\",\n      \"image\": [\n        \"https://files.readme.io/Uk1UvUoSiiZCuPx88lwi_Screen%20Shot%202015-05-29%20at%2013.27.30.png\",\n        \"Screen Shot 2015-05-29 at 13.27.30.png\",\n        \"1790\",\n        \"748\",\n        \"#1f87d6\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n###Attaching index files and data files\n\nSome tools ('indexers') only output index files for inputted data files; they do not output the data file and the index together. If your tool is one of these, then the index file will be outputted to the current working directory of the job, but the data file will not. This can make it difficult to forward the data file and index file together.\n\nIn this case, if you need to forward an input file with an attached index file, then you should copy the data file to the current working directory of the job (tool execution), since this is the directory to which the index file will be outputted. To copy the data file to the current working directory, select **copy **under Stage Inputs on the description of that input port.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/z6VkDKtCQk4Y3pY8qVN9_Screen%20Shot%202016-02-11%20at%2019.05.31.png\",\n        \"Screen Shot 2016-02-11 at 19.05.31.png\",\n        \"1040\",\n        \"320\",\n        \"#2f81e4\",\n        \"\"\n      ],\n      \"caption\": \"Stage Input\",\n      \"border\": true\n    }\n  ]\n}\n[/block]\n<div align=\"right\"><a href=\"#top\">top</a></div>\n\n##Upload your own CWL tool description\n\nAs an alternative to using the Tool Editor, you can upload your own description of your tools as JSON or YAML files in accordance with CWL. This method is useful if you already have these files for your tools.\n\nTo upload your own tool description:\n\n1. Click on the cog icon in the top right of the tool editor.\n2. Select Import.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/fdxTU1r5QEe8wGG47MWx_Screen%20Shot%202015-06-09%20at%2011.29.17.png\",\n        \"Screen Shot 2015-06-09 at 11.29.17.png\",\n        \"446\",\n        \"326\",\n        \"#0484dc\",\n        \"\"\n      ],\n      \"border\": true\n    }\n  ]\n}\n[/block]\n3. Copy and paste your CWL description into the pop-out window.\n\nAlternatively, you can use the API to upload CWL files describing your tools or workflows as JSON.\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"To get started writing CWL by hand, see <a href=\\\"https://github.com/ntijanic/common-workflow-language/blob/master/specification/draft-2/README.md\\\" target=\\\"blank\\\">this guide</a>. Alternatively, try inspecting the CWL descriptions of public apps by opening them in the tool editor, clicking the cog icon in the top right corner, and selecting </> Tool JSON.\"\n}\n[/block]\n\n\n##Configure the log files for your tool\nLogs are produced and kept for each job executed on the Platform. They are shown on the visual interface and via the API:\n  * To access a job's logs on the visual interface of the Platform, go to the [view task logs](doc:view-task-logs) page.\n  * To access a job's logs via the API, issue the API request to [get task execution details](doc:get-task-execution-details).\nYou can modify the default behavior so that further files are also presented as the logs for a given tool. This is done using a 'hint' specifying the filename or file extension that a file must match in order to be named as a log:\n\n1. Open your tool in the tool editor by clicking the pencil icon next to its name.\n2. Click the ellipses (**. . . **) menu on the right, as shown below:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ESo1uGnSCW1OJsnCbL49_glob3.jpg\",\n        \"glob3.jpg\",\n        \"623\",\n        \"299\",\n        \"#567fb2\",\n        \"\"\n      ],\n      \"caption\": \"Click the ellipses on the tool editor.\"\n    }\n  ]\n}\n[/block]\n3. Choose Settings.\nThe **Hints** window for configuring the log file will be displayed, as shown below.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/lc6SSJGRfyblC9UJxcSQ_glob2.jpg\",\n        \"glob2.jpg\",\n        \"649\",\n        \"502\",\n        \"#da9844\",\n        \"\"\n      ],\n      \"caption\": \"The Hints window.\"\n    }\n  ]\n}\n[/block]\n4. Click the plus button (**+**) to add a new hint, consisting of a key-value pair. To configure the log files for your tool, enter `sbg:SaveLogs` for the key, and a glob (pattern) for the value. Any filenames matching the glob will be reported as log files for jobs run using the tool.\nFor example, the glob `*.txt` will match all files in the working directory of the job whose extension is '.txt'. You can also enter a literal filename, such as `results.txt` to catch this file specifically.\n5. Click **Save** to save the changes. You can add values (globs) for as many log files as you like. A glob will only match files from the working directory of the job, without recursively searching through any subdirectories.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Note that the files shown as logs differ depending on whether you are viewing the logs of a job via the visual interface or via the API.\\n\\n  * By default, the [view task logs](doc:view-task-logs) page on the visual interface shows as logs any *.log files in the working directory of the job (including std.err.log and cmd.log) as well as job.json and cwl.output.json files. \\n  * By default, the API request to[get task execution details](doc:get-task-execution-details) shows as the log only the standard error for the job, std.err.log.\\n\\nConsequently, if you set the value of `sbg:SaveLogs` to `*.log` then this will change the files displayed as logs via the API, but will *not* alter the files shown as logs on the visual interface, since the visual interface already presented all .log files as logs. However, if you add a new value of `*.txt` for `sbg:SaveLogs`, then .txt files will be added to the log files shown via the visual interface and API.\",\n  \"title\": \"Differences between the API and visual interface\"\n}\n[/block]\n\n\n<div align=\"right\"><a href=\"#top\">top</a></div>","excerpt":"<a name=\"top\"/>","slug":"advanced-features-of-the-tool-editor","type":"basic","title":"Advanced features of the tool editor"}

Advanced features of the tool editor

<a name="top"/>

[block:callout] { "type": "warning", "body": "* [Annotating output files with metadata](#section-annotating-output-files-with-metadata)\n* [Custom input structures for tools](#section-custom-input-structures-for-tools)\n* [Describing index files](#section-describing-index-files)\n * [Attaching index files to data](#section-attaching-index-files-and-data-files) \n* [Upload your own CWL tool description](#section-upload-your-own-cwl-tool-description)\n* [Configure the log files for your tool](#section-configure-the-log-files-for-your-tool)", "title": "On this page" } [/block] ##Annotating output files with metadata You may want to annotate the files produced by a tool with metadata, which will then be used by other tools in a workflow. See the [metadata for your private data](doc:metadata-for-private-data) page for a list of commonly used file metadata. You can choose the the name and type of these metadata by defining your own key-value pairs. Any keys can be used, but see this list for commonly used file metadata. To enter key-value pairs that will be added to output files as metadata, click on any output port that you have listed on the Outputs tab. There is a field for **keys** and a field for **values**. [block:image] { "images": [ { "image": [ "https://files.readme.io/iD7nsOrORDS8jztuoeKn_Screen%20Shot%202015-05-29%20at%2013.15.59.jpeg", "Screen Shot 2015-05-29 at 13.15.59.jpeg", "1851", "811", "#526f8a", "" ] } ] } [/block] [block:callout] { "type": "success", "title": "Using dynamic expressions to capture metadata:", "body": "Metadata values can be string literals or dynamic expressions. For instance, the `$self` object can be used to refer to the path of the file being outputted. See the documentation on dynamic expressions in tool descriptions for more details." } [/block] <div align="right"><a href="#top">top</a></div> ##Custom input structures for tools Certain tools will require more complex data types as inputs than simply files, strings, and so on. In particular, you may need to input arrays of structures. This requires you to define a custom input structure that is essentially an input type that is composed of further input types. A common situation in which you'll need to use a complex data structure is to when the input to your bioinformatics tool is a genomic sample. This will consist of, say, a BAM file and a sample ID (string), or perhaps two FASTQ files and an insert size (int). **To define a custom input structure:** 1. On the** Inputs** tab of the tool editor select the Data Type as **array** from the drop-down list. 2. This will then prompt you for an **Item Type**; in this field, you should select '**record**' to define your own types. In the example shown below we have given the array the **ID** 'Custom_input'. You can give it any name you choose. [block:image] { "images": [ { "image": [ "https://files.readme.io/OnZYZK4MSqLDCdVGlKeg_Screen%20Shot%202015-05-29%20at%2013.01.35.png", "Screen Shot 2015-05-29 at 13.01.35.png", "1784", "314", "", "" ], "border": true } ] } [/block] 3. Once you have created the input array and saved it (closing the window), you can define its inputs. To do this, click on the array in the list of inputs on the **Inputs** tab. This will bring up a button marked **+ **labeled **Click the plus button to define a field**. [block:image] { "images": [ { "image": [ "https://files.readme.io/SdwBWmFWQue1IVooEgEQ_Screen%20Shot%202015-05-29%20at%2013.03.11.png", "Screen Shot 2015-05-29 at 13.03.11.png", "3184", "468", "#415f6c", "" ], "border": true } ] } [/block] 4. The **+** button lets you define the individual input ports that the array is composed of. You define the input ports of an input array in the same way as you would usually define an input port for a tool. In our example, let's set the array data structure to take three inputs, two of which are FASTQ files, and the third of which is the insert size. We'll label the input ports with the **ID**s 'FASTQ_1', 'FASTQ_2' and 'Insert_size' respectively. We set the **Type** of the first two to **File**, and the **Type** of the third as** int**. [block:image] { "images": [ { "image": [ "https://files.readme.io/lZaH1VOATdafHmPVRkqR_Screen%20Shot%202015-05-29%20at%2012.57.21.png", "Screen Shot 2015-05-29 at 12.57.21.png", "2518", "1034", "#278ed1", "" ], "border": true } ] } [/block] <div align="right"><a href="#top">top</a></div> ##Describing index files Some tools generate index files, such as .bai, .tbx, .bwt files. Typically, you will want the CGC to treat indexes as attached to their associated data file, so that they will be copied and moved along with the data file in workflows. To represent the index file as attached to its data file you should make sure that: 1. The index file has the same filename as the data file and is stored in the same directory as it. 2. You have indicated in the tool editor that an index file is expected to be output alongside the data file. To do this: On the** Outputs** tab of the editor, enter the details of the data file as the output. Under **Secondary Files** enter the extension of the index file, modified according to the following convention: Suppose that the index file has extension '.ext'. * If the index file is named by simply appending '.ext' onto the end of the extension of the data file, then simply enter .ext in the Secondary Files field. For example, do this if the data file is a .bam and the index extension is .bai (see example A). * If the index file is named by replacing the extension of the data file with '.ext', then enter ^.ext in the the Secondary Files field. For example, when the data file is a fasta contig list and the index extension is .dict (see example B). In example A, we have named the output port 'BAM' and set up globbbing to catch files whose names contain '.bam' to be designated as its outputs. We have also specified that a secondary file is expected, and that it should have the same name as the BAM file, but have extension '.BAI' appended to the file extension of the BAM file. [block:image] { "images": [ { "caption": "Example A", "image": [ "https://files.readme.io/oqDF6ejiRDi382B1atMn_Screen%20Shot%202015-05-29%20at%2013.20.18.png", "Screen Shot 2015-05-29 at 13.20.18.png", "1792", "748", "#1f87d6", "" ], "border": true } ] } [/block] In example B, the output port is named 'Reference' and it catches files whose names contain 'fasta'. We have specified that an index file is expected, and that it will have the same file name as the FASTA file but that the extension '.DICT' will replace the extension of the FASTA file. [block:image] { "images": [ { "caption": "Example B", "image": [ "https://files.readme.io/Uk1UvUoSiiZCuPx88lwi_Screen%20Shot%202015-05-29%20at%2013.27.30.png", "Screen Shot 2015-05-29 at 13.27.30.png", "1790", "748", "#1f87d6", "" ], "border": true } ] } [/block] <div align="right"><a href="#top">top</a></div> ###Attaching index files and data files Some tools ('indexers') only output index files for inputted data files; they do not output the data file and the index together. If your tool is one of these, then the index file will be outputted to the current working directory of the job, but the data file will not. This can make it difficult to forward the data file and index file together. In this case, if you need to forward an input file with an attached index file, then you should copy the data file to the current working directory of the job (tool execution), since this is the directory to which the index file will be outputted. To copy the data file to the current working directory, select **copy **under Stage Inputs on the description of that input port. [block:image] { "images": [ { "image": [ "https://files.readme.io/z6VkDKtCQk4Y3pY8qVN9_Screen%20Shot%202016-02-11%20at%2019.05.31.png", "Screen Shot 2016-02-11 at 19.05.31.png", "1040", "320", "#2f81e4", "" ], "caption": "Stage Input", "border": true } ] } [/block] <div align="right"><a href="#top">top</a></div> ##Upload your own CWL tool description As an alternative to using the Tool Editor, you can upload your own description of your tools as JSON or YAML files in accordance with CWL. This method is useful if you already have these files for your tools. To upload your own tool description: 1. Click on the cog icon in the top right of the tool editor. 2. Select Import. [block:image] { "images": [ { "image": [ "https://files.readme.io/fdxTU1r5QEe8wGG47MWx_Screen%20Shot%202015-06-09%20at%2011.29.17.png", "Screen Shot 2015-06-09 at 11.29.17.png", "446", "326", "#0484dc", "" ], "border": true } ] } [/block] 3. Copy and paste your CWL description into the pop-out window. Alternatively, you can use the API to upload CWL files describing your tools or workflows as JSON. [block:callout] { "type": "success", "body": "To get started writing CWL by hand, see <a href=\"https://github.com/ntijanic/common-workflow-language/blob/master/specification/draft-2/README.md\" target=\"blank\">this guide</a>. Alternatively, try inspecting the CWL descriptions of public apps by opening them in the tool editor, clicking the cog icon in the top right corner, and selecting </> Tool JSON." } [/block] ##Configure the log files for your tool Logs are produced and kept for each job executed on the Platform. They are shown on the visual interface and via the API: * To access a job's logs on the visual interface of the Platform, go to the [view task logs](doc:view-task-logs) page. * To access a job's logs via the API, issue the API request to [get task execution details](doc:get-task-execution-details). You can modify the default behavior so that further files are also presented as the logs for a given tool. This is done using a 'hint' specifying the filename or file extension that a file must match in order to be named as a log: 1. Open your tool in the tool editor by clicking the pencil icon next to its name. 2. Click the ellipses (**. . . **) menu on the right, as shown below: [block:image] { "images": [ { "image": [ "https://files.readme.io/ESo1uGnSCW1OJsnCbL49_glob3.jpg", "glob3.jpg", "623", "299", "#567fb2", "" ], "caption": "Click the ellipses on the tool editor." } ] } [/block] 3. Choose Settings. The **Hints** window for configuring the log file will be displayed, as shown below. [block:image] { "images": [ { "image": [ "https://files.readme.io/lc6SSJGRfyblC9UJxcSQ_glob2.jpg", "glob2.jpg", "649", "502", "#da9844", "" ], "caption": "The Hints window." } ] } [/block] 4. Click the plus button (**+**) to add a new hint, consisting of a key-value pair. To configure the log files for your tool, enter `sbg:SaveLogs` for the key, and a glob (pattern) for the value. Any filenames matching the glob will be reported as log files for jobs run using the tool. For example, the glob `*.txt` will match all files in the working directory of the job whose extension is '.txt'. You can also enter a literal filename, such as `results.txt` to catch this file specifically. 5. Click **Save** to save the changes. You can add values (globs) for as many log files as you like. A glob will only match files from the working directory of the job, without recursively searching through any subdirectories. [block:callout] { "type": "info", "body": "Note that the files shown as logs differ depending on whether you are viewing the logs of a job via the visual interface or via the API.\n\n * By default, the [view task logs](doc:view-task-logs) page on the visual interface shows as logs any *.log files in the working directory of the job (including std.err.log and cmd.log) as well as job.json and cwl.output.json files. \n * By default, the API request to[get task execution details](doc:get-task-execution-details) shows as the log only the standard error for the job, std.err.log.\n\nConsequently, if you set the value of `sbg:SaveLogs` to `*.log` then this will change the files displayed as logs via the API, but will *not* alter the files shown as logs on the visual interface, since the visual interface already presented all .log files as logs. However, if you add a new value of `*.txt` for `sbg:SaveLogs`, then .txt files will be added to the log files shown via the visual interface and API.", "title": "Differences between the API and visual interface" } [/block] <div align="right"><a href="#top">top</a></div>