Page History

To import an executable as an external tool to UGENE one should create A custom tool can be integrated into the UGENE GUI as a workflow element in the Workflow Designer - a UGENE component that allows joining tools into workflows.

As described in the "Custom Elements with External Tools" chapter of the Workflow Designer documentation, there are two options when one creates such workflow element:

• Set a local executable path
• Set an integrated external tool

The first option is intended for cases when a quick temporary integration of a tool into a workflow is enough.

The second option although requires additional configuration steps provides a more close integration with UGENE. It can be used by more advanced users for providing a tool for their colleagues.

Below the preparatory configuration steps for the second option are described.

Create an XML configuration file for custom external tool

Create an XML file with the custom external tool description. It should be matched by The file should match the following XML schema:

<?xml version = "1.0" encoding = "UTF-8"?>
<xs:schema xmlns:xs = "http://www.w3.org/2001/XMLSchema">

<xs:element name = "ugeneExternalToolConfig">
    <xs:complexType>
        <xs:sequence>
            <xs:element name = "name" type = "xs:string" />
            <xs:element name = "path" type = "xs:string" minOccurs ="0" />
            <xs:element name = "description" type = "xs:string" minOccurs ="0" />
            <xs:element name = "toolkitName" type = "xs:string" minOccurs ="0" />
            <xs:element name = "version" type = "xs:string" minOccurs ="0" />
            <xs:element name = "launcherId" type = "xs:string" minOccurs ="0" />
            <xs:element name = "dependencies" type = "xs:string" minOccurs ="0" />
            <xs:element name = "binaryName" type = "xs:string" />
        </xs:sequence>
        <xs:attribute name = "version" type = "xs:string" use="required" />
    </xs:complexType>
</xs:element>

</xs:schema>

...

There XML elements have the following meaning:

• name - the external tool name as you like to see it in UGENE. Mandatory elementit should be displayed in the UGENE GUI. This XML element is mandatory.
• binaryName - a file the name of the imported tool executable file (with the file extension, if it existsis present). UGENE will search the tool for this file in some well-known places locations during the UGENE start, if the tool path is not defined for some reasons. Mandatory This XML element is mandatory.
• path - a path to the external tool. It can be relative to the current config file location or absolute. You can set it in UGENE Application Settings later. Optional  This XML element is optional.
• description - a detailed description of the external tool. Optional This XML element is optional.
• toolkitName - a name of the toolkit to group external tools. If it is not defined or empty, then the external tool name will be used as the toolkit name. Optional  This XML element is optional.
• version - a version of the imported tool executable. Optional  This XML element is optional.

• launcherId - if the tool is supposed to be run with some script interpreter or it is a java application, then this element should contain an appropriate ID. Currently, UGENE supports the following launchers IDs: PYTHON2, PERL, RSCRIPT, JAVA. If the launcher is specified, it would be added to the launch command explicitly whenever you try to launch the external tool. The path to the launcher will be taken from the UGENE "Application Settings" (see the corresponding tools in the "Supported tools" group). If the element is not specified or it is empty, no additional launcher would will be added to the launch command . Optional elementthat will run the tool. This XML element is optional.

• dependencies - a comma-separated list of other external tool IDs the imported new tool is dependent from. If the dependency is not satisfied, then the dependent tool is marked as "not valid" in the UGENE. Optional  This XML element is optional.

...

See also the following examples:

1. A minimalistic config: 

   Code Block
   <?xml version = "1.0" encoding = "UTF-8"?> <ugeneExternalToolConfig version = "1.0"> <name>An imported custom tool</name> <binaryName>my_tool.py</binaryName> </ugeneExternalToolConfig>

   This config describes only a tool name and a tool binary name. After the import the path will be empty, the tool won't have any dependencies, its version will be "unknown".

2. A config without dependencies and a launcher:

   Code Block
   <?xml version = "1.0" encoding = "UTF-8"?> <ugeneExternalToolConfig version = "1.0"> <name>RAxML</name> <path>raxmlHPC</path> <description>RAxML - Randomized Axelerated Maximum Likelihood</description> <version>8.2.12</version> <binaryName>raxmlHPC</binaryName> </ugeneExternalToolConfig>

   This config describes an external tool with a description and a version. Path to the tool executable is relative: it is supposed that the executable is in the same folder as the config file is.

3. A config with a dependecy and a launcher:

   Code Block

   <?xml version = "1.0" encoding = "UTF-8"?> <ugeneExternalToolConfig version = "1.0"> <name>HISAT2</name> <path>d:\work\hisat2.1\hisat2</path> <description>HISAT2 is a fast and sensitive alignment program for mapping next-generation sequencing reads (both DNA and RNA) to a population of human genomes (as well as to a single reference genome).</description> <toolkitName>HISAT2</toolkitName> <version>2.1.0</version> <launcherId>PERL</launcherId> <dependencies>PERL</dependencies> <binaryName>hisat2</binaryName> </ugeneExternalToolConfig>

   This config describes a tool that is supposed to be run by the Perl interpreter. There is no Perl by default on Windows, but the UGENE installer provides a possibility to install Perl. The tool can notify UGENE that it should be launched by Perl, so UGENE will add a path to Perl to the launch command.command that runs the tool.

Prepare a package with the XML configuration tool and the tool

The easiest way to "pack" the custom external tool is to:

• create a new folder with all files required for running the tool,
• specify a relative path in the XML configuration file described above,
• put the XML configuration in the same folder as the main tool executable.

This "package" can be shared with other users, if required.

Import the tool in UGENE

To add the custom external tool one need to import its XML configuration file in the "Custom tools" group on the "External Tools" page of the "Application Settings" dialog.