<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                         "http://docbook.org/xml/4.4/docbookx.dtd">
<chapter>
    <title>Launch Settings</title>
    <sect1>
        <title>Synopsis</title>
        <para>Add a launch setting for the tool, which defines the tool’s location and version.
            Also, define the working directory for the tool execution and clean up settings.</para>
    </sect1>
    <sect1>
        <title>Folder structure</title>
        <para>There are different option variations of the structure of the folders (working dir, tool dir, etc.):<itemizedlist>
        	<listitem>
                <para>“Use a new working directory on each run” <emphasis role="bold">not</emphasis> selected</para>
                <para>“Do not copy tool” selected</para>
                <para><inlinegraphic fileref="../../images/Folderstructure_1.png"/></para>
            </listitem>
            <listitem>
                <para>“Use a new working directory on each run” <emphasis role="bold">not</emphasis> selected</para>
                <para>“Copy tool to working directory once” selected</para>
                <para><inlinegraphic fileref="../../images/Folderstructure_2.png"/></para>
            </listitem>
            <listitem>
                <para>“Use a new working directory on each run” selected</para>
                <para>“Copy tool to working directory once” selected</para>
                <para><inlinegraphic fileref="../../images/Folderstructure_3.png"/></para>
            </listitem>
            <listitem>
                <para>“Use a new working directory on each run” selected</para>
                <para>“Copy tool to working directory on each run” selected</para>
                <para><inlinegraphic fileref="../../images/Folderstructure_4.png"/></para>
            </listitem>
        </itemizedlist>
        </para>
    </sect1>
    <sect1>
        <title>Usage</title>
        <para>With the launch settings, you define which tool is used and how it is used.</para>
        <para>Required fields:<itemizedlist>
                <listitem>
                    <para><emphasis role="bold">One set of launch settings:</emphasis> In the table
                        on the top, the list of already defined launch settings will be shown.
                        Currently, exactly one setting is supported. When clicking on “Add”, the
                        following fields for the definition of a set are available:<itemizedlist>
                            <listitem>
                                <para><emphasis role="bold">Tool Directory:</emphasis> This is the
                                    path to the actual tool. The path is chosen from your local disk
                                    and must be existent every time the component is executed.
                                    Please note: If the integration is transferred to another
                                    machine, this path must be adapted.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Version:</emphasis> The version is to
                                    identify your tool. If other components with the same name were
                                    integrated by other users, they can be distinguished by the
                                    version (which is shown in brackets behind the tool name in the
                                    workflow palette). Please note: To prevent inconsistencies, make
                                    sure there are never two tools with the same name and same
                                    version published by two different machines.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Working directory:</emphasis> You can
                                    choose where you want to execute the tool from and where
                                    temporary files are written. You can either define a custom path
                                    to a directory of your choice here or check "Create arbitrary
                                    directory in RCE temp directory" to use a default directory
                                    within the RCE temp directory.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Limit parallel executions
                                        (optional):</emphasis> Here you can limit the number of
                                    parallel executions of this tool. If this number is reached any
                                    further call of the tool will wait until a prior call is
                                    finished. This can be useful when you have restricted licenses
                                    for a specific tool or ressource restriction is desired.</para>
                            </listitem>
                        </itemizedlist><note>
                            <para>If you use relative paths for the Tool Directory, the root path
                                used for this (".") is always the RCE installation folder.</para>
                        </note></para>
                </listitem>
            </itemizedlist></para>
        <para>Optional fields:<itemizedlist>
                <listitem>
                    <para><emphasis role="bold">Use a new working directory on each run:</emphasis>
                        You can choose whether your tool should have new input and configuration
                        folders on each run or if they will only be created once.</para>
                </listitem>
                <listitem>
                    <para><emphasis role="bold">Tool Copying Behavior:</emphasis> On the bottom left
                        there are some choices regarding the copying of the integrated tool:<itemizedlist>
                            <listitem>
                                <para><emphasis role="bold">Do not copy tool:</emphasis> The tool
                                    remains in its directory. The variable "Tool dir" contains the
                                    absolute path.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Copy tool to working directory
                                        once:</emphasis> The tool will be copied into the working
                                    directory on workflow start. Note: This is not possible, if the
                                    tool has hard coded dependencies or is too big to be
                                    copied.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Copy tool to working directory on each
                                        run:</emphasis> This option is only available, if the “Use a
                                    new working directory on each run” option above is checked. The
                                    tool will be copied into a directory within the working
                                    directory for each run. Note: This is not possible, if the tool
                                    has hard coded dependencies or is too big to be copied.</para>
                            </listitem>
                        </itemizedlist></para>
                </listitem>
                <listitem><para><emphasis role="bold">Clean up choices for working directory(ies) in workflow
                            configuration:</emphasis> On the bottom right there are some options for
                        the behavior of temp directory deletion. The choice you make here is not
                        final, but gives the user the possibility to choose the behavior for
                        her/himself when editing a workflow. At least one of the options must be selected.<itemizedlist>
                            <listitem>
                                <para><emphasis role="bold">Never delete working
                                        directory(ies):</emphasis> If this is checked, every single
                                    file that was created during the components run is left in the
                                    temp directory. This can be a good option to debug the tool
                                    integration.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Delete working directory(ies) when
                                        workflow is finished:</emphasis> Here, the created files are
                                    deleted when the entire workflow is finished. If some files are
                                    needed in multiple runs, this can be good as they are not copied
                                    every time. Check <emphasis role="bold">"Keep in case of failed workflow run"</emphasis> to
                                    prevent the deletion in case of failure. This can be useful for
                                    debugging, in particular.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Delete working directory(ies) after each
                                        run of the tool:</emphasis> This option is only available,
                                    if the “Use a new working directory on each run” box is checked.
                                    With this, after each run the iteration directory is deleted.
                                    Check <emphasis role="bold">"Keep in case of failed tool
                                        run"</emphasis> to prevent the deletion in case of failure.
                                    This can be useful for debugging, in particular.</para>
                            </listitem>
                        </itemizedlist></para></listitem>
            </itemizedlist></para>
    </sect1>
</chapter>
