<?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>Tool Properties</title>
    <sect1>
        <title>Synopsis</title>
        <para>Define properties for the tool, which can be used as parameters later in all scripts
            and can be configured when a workflow is set up.</para>
    </sect1>
    <sect1>
        <title>Usage</title>
        <para>Properties are a means to provide the user of the integrated tool some attributes for
            configuration the tool when using it in a workflow. For example, if the tool is able to
            run with multiple cores, a key “numCores”  can be defined and later added via a
            placeholder in your command execution script or pre/post execution script (e.g.
            “tool.exe ${prop:numCores}”). This key is then displayed in the properties view of the
            integrated component and the value can be set there.</para>
        <para>Properties have a display name that makes them more readable for others. Set a default
            value, to provide some useful presettings. A comment can be added to provide some useful
            information to the tool user.</para>
        <para>The use of properties is optional. </para>
        <para>Since RCE 8.0 it is possible to define properties as placeholders. With this option,
            which is activated in the properties view of the tool component, the user can define
            that the value for the selected property is not defined while editing the workflow, but
            at workflow start. </para>
        <para>While the use of properties allows a great amount of flexibility, they also easily
            lead to inadvertent security issues. Consider, e.g., a tool that copies some data to a
            configurable directory and removes that directory after its computation as part of
            cleanup. Malicious users may set the configuration directory to some vital system
            directory and cause the tool to remove that directory on termination. To prevent users
            from creating such security issues by accident, RCE does not allow the use of property
            values containing <code>\"</code>, ASCII-characters in the range
                <code>0x00</code>-<code>0x1f</code>, <code>\\</code>, <code>/</code>,
                <code>\*</code>, <code>\?</code>. Moreover, RCE prevents the use of <code>%</code>
            on Windows systems, and of <code>`</code> and <code>\$</code> on Linux systems.</para>
        <para>If you would like to allow your users to supply a configuration file or a
            configuration directory, please add this file as an explicit input to the component.
            Other options include, e.g., fixing a "whitelist" of safe configuration options and
            allowing the user a choice of these configuration options via properties.</para>
    </sect1>
    <sect1>
        <title>Groups</title>
        <para>Properties can be categorized in groups, for example for a specific context. </para>
        <para>Optionally, the property configurations can be stored at runtime in a file per group
            located in the “Config” folder in a temporary directory. These files contain the keys
            and the respective values. The file names can be adjusted. </para>
    </sect1>
</chapter>
