preferences

Preferences Window

Contents:

1. Preferences Window Overview
2. Preference Categories
3. Setting Preferences
4. Security

1. Preferences Window Overview

Preferences window provides access to T-Plan Robot Enterprise configuration. To open the window select Edit -> Preferences in the main GUI menu. Many T-Plan Robot Enterprise components also provide a quick access to their configuration in context menus, for example customized command editor popup menus or status bar popup menu. The window consists of the following components:

  1. The Preference Tree is situated on the left. It represents a hierarchical structure of preferences organized by topics and T-Plan Robot Enterprise configurable objects. See the following chapter called Preference Categories for more.
  2. The Search field allows to search all dialog panels for the specified keyword.
  3. The "Show preference details tool tip" check box makes the window display internal properties for a preference, such as its key (ID) in the configuration file, the value type with optional list of acceptable values and the current stored value. To get it displayed set on the check box and hover the mouse pointer over the preference.

    This functionality maps config file preference keys and raw values to their visual representation in the Preferences window. It is intended to help those who either customize the configuration file manually or programmatically. See the Setting Preferences chapter for details.
  4. The Preference Panel displays preferences (configuration values) for the selected tree node. Each preference is represented by a graphical component, for example by a labeled text field, and generally allows to edit the preference value. 
  5. The Previous and Next buttons store the preference browsing history and navigate to the previous/next viewed panel (tree node).
  6. The OK button closes the window and saves the preference changes to the configuration file in the file system. The Cancel button closes the window and discards all the changes.

The preference values are loaded from the user configuration file when the application starts and they are held in the memory until it gets closed or an explicit save action is invoked (for example by this window). When T-Plan Robot Enterprise is installed to a clean machine, the tool initially loads the default preference file bundled with the product binaries and saves it to the <user_home>/tplanrobot.cfg file. See the Text And Data File List manual for the file details.

Be aware that there is no configuration file synchronization or lock mechanism. It means that if you run multiple instances of the tool on a single machine under one user, the file will be overwritten without checking whether another instance has changed it in between.

2. Preference Categories

The Preference Tree component organizes preference values into groups. A single tree node is usually associated with one particular object. Preferences are currently divided into four major categories:

  1. Appearance & Accessibility group contains preferences which affect GUI appearance and behaviour. The Menu & Tool Bar node allows to configure shortcut keys (hot keys) for often used the menu items. See also the Menu And Tool Bar Reference help topic. The Script Editor node defines editor preferences such as the syntax color scheme, editor short cut keys and behaviour of some editing. See also the Script Editor help topic. The Tool Panel node lists a few preferences of the Tool Panel component. The Web Browser node allows to customize web browser settings. Though T-Plan Robot Enterprise has an internal mechanism which looks for the most known web browsers, it may either fail or open an on certain configurations. This panel allows user to override the standard behaviour and specify a custom web browser start command.

  2. Scripting group configures preferences related to the scripting framework and its individual components such as general scripting language settings, script compilation and execution and conversion. The Language node allows to set default values of the output and template paths. It also defines a few flags allowing to switch on compatibility mode with legacy product versions. The Execution node defines general compilation and execution settings such as the start and shut down timeouts, compilation settings and behavior of GUI during execution and compilation of scripts. The Java Converter node contains just setting of preferred converter plugin. As there is currently one default converter, there's nothing to configure unless you install a plugin of another converter.

  3. Script Recorder preferences form a standalone group under the Scripting tree branch. They deal with settings of the Script Recorder as well as other GUI components which generate scripting code, such as the WaitFor Command Window. The Mouse node lists preferences of recording of mouse events. It allows to configure whether to record mouse moves, clicks and drags and it also enables to set the timeouts for multiple events such as double mouse click. The Keyboard node list defines how the script recorder processes input from the keyboard. There are options for multiple key handling as well as conditions for generation of the TypeLine command where text followed by an Enter key is detected. The Update and Bell Events nodes provide default values used by the WaitFor Command Window to generate WaitFor commands from the desktop update and bell events.

  4. Plugins tree branch is a preference group dynamically created from the installed plugins. As most standard features are delivered in form of internal plugins, the group is populated even when no custom plugins are installed. Each child of the Plugins node corresponds to a plugin group representing a particular exposed functional interface. Child nodes under the group represent individual plugins. The plugin group in fact shows preferences of any installed and enabled plugin which implements the Configurable interface. To get general information about plugins and their eventual configuration refer to the Plugin Framework manual. Description of preferences of a particular plugin is usually delivered in the plugin class JavaDoc documentation delivered either as part of the Java API Specification (internal plugins) or in form or external documentation (external/custom plugins). To find out documentation of a particular internal plugin first review the plugin map for the plugin class name and then select the appropriate class document in the Java API spec.




3. Setting Preferences

Besides the Preferences window described above one may set the preference values programmatically. To set a preference value you must first obtain the preference key (ID) and the value type it requires. You may find this information in the documentation of the particular functionality, through the "Show preference detail tool tip" feature described above or by looking at the copy of the default configuration file in the Java API documentation.

  1. Using the o/-option CLI option.
  2. Through the UserConfiguration class of the Java API. There are two options:
  3. Temporary setting using a raw String value to the override table. This overrides the preference value loaded from the configuration file. It gets applied to the current session only and the value never gets saved to the config file. This way behaves the same way as the o/-option CLI option. For example, to disable smooth mouse moves temporarily use: UserPreferences.getInstance().getOverrideTable().put("MouseCommand.enableSmoothMoves", "false");
  4. Permanent setting. This is equivalent to setting through the Preference window. The save() method will save the modified config file to the HDD:
    UserPreferences.getInstance().setBoolean("MouseCommand.enableSmoothMoves", false);
    UserPreferences.saveConfiguration();

4. Security

Starting with release 5.0.2 the sensitive data in the user configuration file gets encrypted using the AES algorithm (256-bit). The records to be encrypted are identified as follows:

  • There's an internal list of preferences known to contain sensitive data, such as passwords, connection URLs etc.
  • Any preference whose name contains "password" or "encrypted" in any letter case will be encrypted as well. This mechanism may be used by 3rd party extensions relying on the user configuration framework.

The encryption is transparent from the point of the GUI and the Java API. No changes are required in the existing Java code to work with the encrypted preferences.

The encryption is controlled by a preference (a check box) titled "Disable encryption of passwords in the config file (since 5.0.2)" in the Compatibility panel of the Preferences→Language screen (see category #2 above). When you set it on/off the data will get decrypted/encrypted instantly as soon as you save the preference change.

For example, if you need to downgrade your installation or migrate the configuration file to a version below 5.0.2 set on the check box and save with OK to produce a compatible plain text configuration file.