Release Notes

Contents:

1. Client System Requirements
    1.1 Java Requirements
    1.2 JDK Installation & Configuration
2. Server System Requirements
3. Installation
4. License
   4.1 License Server
   4.2 File Based License Keys
5. Upgrade And Migration
6. Uninstallation
7. Startup
8. Integration With T-Plan Professional
9. Optimizing Performance
10. Troubleshooting

1. Client System Requirements

Robot runs in a client-server scenario where the client system executes Robot and automates the server system for RPA (System Under Automation) (SUA), or Testing (System Under Test) (SUT), through one of the supported remote desktop technologies (such as RFB/VNC). As the client and server systems may be two fundamentally different platforms, we list the client system (discussed in this chapter) and server system requirements (the following chapter) separately. These are the requirements for the client system running Robot:

¹ Slower processors will result in slow performance of graphical operations, such as image comparison or OCR.
² The overall memory requirements depend on the desktop size, the nature of graphical operations performed by the script and the number of parallel automated processes where the suite is designed as a multithreaded one. If you experience errors with java.lang.OutOfMemoryError visible in the stack trace, raise the heap size allocated to the Java Virtual Machine (JVM) through the -Xmx option. The instructions are available in the Memory Adjustments chapter.

1.1 Java Requirements

Robot is a Java application and it will run on any system with Java 8 or higher installed. Whilst other Java producers exist, Robot is being developed on Java from Oracle, and we, therefore, recommend you to this vendor as long as your platform (OS) is supported (see the list of supported systems). Support of particular Java releases is listed in the table below.

To verify whether Java is installed on your machine open a terminal window (Unix/Linux) or a command line prompt (Windows) and run the following command:

java -version

If Java is present on your machine and its binaries are on the system path it displays its version. If Java is not present, you may download it for free from the following location:

• http://www.oracle.com/technetwork/java/javase/downloads/index.html

Java is being shipped in two distributions, the Java Runtime Environment (JRE) and Java Development Kit (JDK). JRE is a subset of JDK and doesn't contain the Java source code compiler and libraries needed for development. Robot runs with both but certain functionality requires JDK, such as development and on-the-fly execution of Java scripts and Java code blocks. If you plan on using this functionality, get a JDK. If you are used to Java development with NetBeans IDE, you may consider getting it from Oracle Inc. together with the JDK in one software bundle. Both components are open source and free. Installation of a JDK requires an update of the system path as is described in the following chapter.

1.2 JDK Installation & Configuration

If you plan on developing Java scripts or using the Java code blocks you will need to install JDK and configure Robot in one of the following two ways:

Alternative 1: Configure the JDK path through Robot preferences (v2.3.3 and newer):

1. Create a new Java script through the File->New Script->Java Script in the Robot GUI.
2. Right click the editor and select Compile.
3. Robot will search known paths for the installed JDK packages. If it finds a JDK the compilation succeeds and no error is reported. Otherwise it will display a message leading to the Preferences window where you may set the JDK installation path or location of the javac compiler manually.
4. Should you need to cancel the auto setting or to switch to another JDK you may reconfigure the path in Edit->Preferences->Java Script Interpret panel.

Alternative 2: Make Robot start using the java or javaw binary (all product versions). This method overrides the first alternative if both are set up.

Option 1: Put the <JDK_dir>\bin path to the system path. This will make your OS use the JDK as a default interpret for all Java applications.

MS Windows instructions:

1. 1. Start Windows Explorer, right click the Computer node and select Properties in the context menu.
   2. Navigate to the Advanced tab or item (depends on Windows version) and select Environment Variables.
   3. Edit the Path system variable and put path to your JDK's bin/ directory followed by a semicolon to the beginning of the path (typically "C:\Program Files\Java\jdk1.8.0_<version>\bin;").
   4. Save the variable and close all windows with OK. 
   5. Open a command prompt and type javac. The command must be found and print out the supported parameters.

Other systems:

1. • Installation of JDK on other systems may or may not configure the system to use the JDK binaries by default.
   • Refer to your OS documentation for information on how to adjust the system path list and/or associate Java applications with a particular Java distribution.

Option 2: Replace "java" in the Robot start command with absolute path to the JDK's "java" binary.

• For example, on MS Windows edit the robot.bat file, replace "java" with "C:\Program Files\Java\jdk1.8.0_<version>\bin\java" and use the batch file to start Robot.
• For information on how to modify the other start-up methods (Windows menu, starting from T-Plan Professional) see the Startup and Integration with T-Plan Professional chapters. 

To verify that Robot runs on top of the JDK restart Robot's GUI, select Help->About in the menu, switch to the System Information tab and make sure that the java.home property value points to the JDK install folder.

2. Server System Requirements

Server system requirements depend on the connection type (protocol) selected for the System being automated.

Robot by default supports these connections:

3. Installation

Robot is delivered in three forms:

1. Robot with Windows installer (an .exe or a ZIP file containing an .exe file). This package can be installed just on MS Windows and it will allow you to manage the software as a standard Windows program. It also associates Robot with the .tpr script file extension. The installer installs the tool into the C:\Program Files\T-Plan\Robot directory by default.
2. Robot packaged as Mac OS X application (a .dmg or a ZIP file containing a .dmg file). This package can be installed on Apple Mac OS X only. To install the product on Mac OS drag the TPlanRobot application to Applications after the system opens the downloaded file.
3. Robot ZIP file which is a self contained platform independent ZIP archive containing all necessary files. There's no installer. It can be used for all platforms including Windows and Mac OS. All you have to do is to unzip the file into a folder on your hard drive. The archive should contain at least the following files:

Robot also relies on:

• FFmpeg libraries version 3.0.1 (unmodified) which are distributed under GNU Lesser GPL (LGPL) v3. These are packaged inside the robot.jar file where they can be replaced with a newer version provided that the file names are preserved. The FFmpeg 3.0.1 source code is available at Zeranoe or at our site.
• FreeRDP libraries distributed under Apache License v2.0.

4. License

Robot requires a valid license to run. There are two supported mechanisms:

• License server
• File-based license key(s).

4.1 License Server

The license server is the default option starting with release 4.3. You typically receive a license ID (for example "196ba7d1-5a03-481a-8e84-86a77fa47e05", supported since 7.2.9) or the full License Server URL (for example "https://myserver.mydomain/licserver?lid=196ba7d1-5a03-481a-8e84-86a77fa47e05") from the T-Plan support or one of our partners.

There are two ways to pass it to Robot:

1. Through the Tools->License Key Manager window in the GUI. It will pop up on your first Robot start. This will store the server identification under the ls.address key to the user configuration file for permanent use. 
   
   
   
   
2. Another possibility is to specify the license through the --licenseserver CLI option.
   
   
3. Solutions integrating Robot into 3rd party Java frameworks and/or applications may specify the license key path or a list of semicolon separated paths through the robot.licenseServer system property (since v4.4). It must be done before the ApplicationSupport class gets instantiated. This option is available since v4.4.

Example:

System.setProperty("robot.licenseServer", "mymachine:8880");
...
ApplicationSupport robot = new ApplicationSupport();



Note: If you are about to switch from a file-based license key to the license server please read the instructions below.

IMPORTANT:

For compatibility reasons, Robot prefers file-based key settings to the server ones. If there's a file-based key setting (even an invalid one) Robot will not check for the server. If you are switching from a file-based key to the server please ensure that:

• All file-based keys (*.tlic) are removed from the Robot installation directory.
• Use the Tools->License Key Manager window to remove any keys referenced through the configuration file.
  
• Make sure not to use the --licensekey CLI option or populate the robot.licenseKey system property from your custom Java code.

4.2 File Based License Keys

File based keys are maintained for backward compatibility with Robot v4.2 and older. They are provided for trials or new contracts only, where the server is not suitable. The key is an encrypted file with the .tlic extension which contains details of your license, such as:

• Expiration date. The program is by default licensed for one year (annual license) or on a perpetual basis with time limited support. Trial licenses are available on request from the T-Plan Sales.
• Number of seats (users) and licensed connections. The product is licensed on a "per seat" basis.  For details see the Chapter 2 of the LICENSE.txt file located in the installation folder.

For security purposes, the license file(s) may be delivered to you separately from the product, for example, in an E-mail from a T-Plan sales representative. There are several options to install it:

1. Save the key file to the Robot installation directory (where the robot.jar file is located). As the tool checks the folder for any license key files on startup, it will be picked up right away. There might be any number of license files in the installation directory.
2. Alternatively save the key file to a custom location on your hard drive and take advantage of the License Key Manager to register it. To open the Manager start Robot in the GUI mode (with no custom CLI arguments).
   If you have no valid license installed, the tool will display a "No license" error message and it allows you to start the License Key Manager.
   
   If you already have a valid license installed, you may start the window through the Tools->License Key Manager menu item.
   
   Then add the file to the list of registered license keys. Be aware that the list of such files (meaning keys outside of the installation directory) is saved to a list in the user preferences, and it may get lost during migration unless you copy the user configuration file as well. Any change in license key configuration requires product restart.
3. Specify the key path(s) through the --licenseserver CLI option.
4. Solutions integrating Robot into 3rd party Java frameworks and/or applications may specify the license key path or a list of semicolon separated paths through the robot.licenseKey system property. It must be done before the ApplicationSupport class gets instantiated. This option is available from v4.0.3.
   Example:
   System.setProperty("robot.licenseKey", "C:\\MyData\\robot.tlic");
...
ApplicationSupport robot = new ApplicationSupport();

File-based keys may be freely combined. It means that you may have any number of license keys installed at a moment regardless of whether the files are in the installation folder or outside of it. The number of connections will be then equal to the sum of licensed connections of all installed valid licenses. This system allows you to purchase additional licenses and plug them into the product easily when you need to scale up.

5. Upgrade and Migration

To upgrade Robot v2.0 or higher with a new release follow these steps:

Alternative 1: Automatic Upgrade (v2.3 and higher)

Automatic upgrade offers a comfortable and reliable way of promoting your product to a newer version through the GUI. Unlike manual upgrade the automatic process is secured against file corruption (CRC32), detects customized/modified product files and it is able to restore the original product in case of update failure. Steps:

1. Select Tools->Update & Upgrade in the GUI. If Robot complains of insufficient write permissions, restart it with administrator privileges:
   • Windows:
     • Alternative 1: Log in as Administrator and restart Robot.
     • Alternative 2: If you are logged on as user who has admin privileges, right click on Accessories->Command Prompt in the Windows menu and select Run As Administrator. Then switch to the install folder in the command line and run Robot:
       • Windows 32-bit:
         cd "C:\Program Files\T-Plan\Robot\robot" robot
   1. 1. • Windows 64-bit:
           cd "C:\Program Files (x86)\T-Plan\Robot\robot" robot
   • Linux, Unix, Mac OS: Log in as root or run Robot with sudo ("sudo robot.sh")
2. Select the target release in the tree, hit Download & Install, leave the window with OK and restart the application. Details of the upgrade process are available in the Update & Upgrade help topic.

Alternative 2: Manual Upgrade (all versions)

1. Download the desired standalone cross-platform ZIP release. You may get it from any of these resources:
   • Download through the Download & Save button of the Update & Upgrade window.
   • Follow one of the download links published in the Robot Releases Support Forum.
   • For custom or private builds you may be sent a direct download link by the T-Plan staff.
2. If you have modified or customized any of the product files (such as for example the start scripts of robot.sh or robot.bat), make a back up and restore them after the update process. You don't need to back up scripts, template images or configuration files because they will not be affected.
3. Unzip the ZIP archive to the installation folder and say yes to overwrite the files. The install folder is the directory which contains the robot.jar file:
   • If you have installed the product using the Windows Installer (.exe release), unzip the archive to C:\Program Files\T-Plan\Robot (or to the custom directory you selected at the install time).
   • If you have installed the Mac OS X release (.dmg), unzip the archive to /Applications/TPlanRobot.app/Contents/Resources/Java 
   • If you are using the standalone cross-platform ZIP release, unzip the archive to the folder where you unzipped the previous one.

Migration of Robot is fairly straightforward. Standalone ZIP releases may be simply copied and moved across the file system or even to another machine or machines with different operating systems. If you migrate to another machine, copy also user specific configuration files to the user's home folder to keep any preference changes.

Migration of product installed by Windows Installer is possible only through reinstallation. You may however create a standalone cross-platform Robot instance by copying the product files from the installation folder to another location. Such a product may be then started through the robot.bat script or through a direct Java command as is described in the Startup chapter.

A Mac OS X release may be simply moved and/or copied as long as you copy the whole /Applications/TPlanRobot.app folder. You may also create a standalone cross-platform Robot instance by copying the product files from the /Applications/TPlanRobot.app/Contents/Resources/Java folder to another location. Such a product may be then started through the robot.sh script or through a direct Java command as is described in the Startup chapter.

Should you expect any unexpected start up or desktop connection errors after an upgrade or downgrade (migration to a lower version), perform the following steps to restore the factory settings:

• Rename or delete the configuration files <home>/.tplanrobot/tplanrobot.cfg and the legacy VNCRobot's one <home>/config.properties. This step resolves eventual incompatibility of user preference parameters.
• Rename or delete the plugin map file <home>/.tplanrobot/PluginMap.xml. This step resolves eventual downgrade errors caused by missing plugin classes

6. Uninstallation

If you installed Robot through the Windows installer, you may uninstall it through the Windows software manager (Control Panel->Add Or Remove Software on older Windows versions, Control Panel ->Programs And Features on Windows Vista).

To uninstall Robot installed from the ZIP file delete the files unzipped during installation. You may also delete the user configuration files. The tool doesn't create any other files or registry entries except automation outputs such as screenshots, template images and automated reports.

7. Startup

To start Robot:

MS Windows:

• If you installed Robot using the Windows Installer start Robot from the Windows Start menu (it will run the C:\Program Files\T-Plan\Robot\robot.bat file)
• If you are using the cross-platform build (unzip & run) switch to the install folder and run the robot.bat file
• Should you need to customize the Robot start command edit the robot.bat file and update the two java calls in there. Alternatively run the java command directly from the command prompt (see below). This may be required for example to enable the Android Over ADB connection on Java 9+.

Mac OS X:

• If you installed Robot for Mac (.dmg) run it from the Mac OS X menu. Alternatively run the /Applications/TPlanRobot.app/Contents/Java/robot.sh file.
• If you are using the cross-platform build (unzip & run) switch to the install folder and run the robot.sh file.
• Should you need to customize the Robot start command edit the robot.sh file and use it to start the tool. Alternatively run the java command directly from the command prompt (see below).

Linux/Unix:

• Switch to the cross-platform build folder and run the robot.sh file.

For help on CLI commands run robot.sh -h, resp. robot.bat --help. For a complete reference see the CLI Reference. If the tool fails to start, review the Troubleshooting chapter at the end of this document. The wrapper scripts actually just start Java with proper options. If you need to customize the Robot start command use the following syntax:

It is NOT RECOMMENDED to start the tool as "java –jar robot.jar" or through double clicking onto the robot.jar file. It fails to populate class path of the Java compiler. The tool may refuse to compile or even run the Java source code (such as Java scripts and Java code blocks embedded in regular scripts).

There are two modes:

• GUI Mode - Displays the graphical interface in your window system (MS Windows, X-Windows). This is the default mode when you start Robot without any CLI options.
• CLI Mode - No GUI is displayed. Robot starts in this mode only when invoked with the n or --nodisplay option. Use this way for automated execution of scripts. Other parameters like -r/-run must be supplied.

See the CLI Options Specification document available in the Robot Help or online.

Once the GUI is up and running, open Help for instructions on how to use Robot. There should be a complete documentation set included. All the documents/document collections are also available online.

Robot can be also used for offline image comparison through a simple CLI interface. To explore this feature either run one of the wrapper scripts imgcompare.sh (for Unix/Linux) or imgcompare.bat (for Windows) or invoke Java directly as follows:

8. Integration with T-Plan Professional

Robot may be on Windows tightly integrated with T-Plan Professional 7.0 or later. It means that T-Plan Professional offers in its GUI actions starting Robot. This integration is based entirely on the public CLI parameters described in the Robot's CLI reference. Integration principles are well described in the Integration Reference. There are two ways to configure how T-Plan Professional starts Robot:

1. To configure Robot installation path navigate to the Installed Extensions module of T-Plan Professional as is described in the T-Plan Professional Integration Overview chapter of the Integration Reference.
2. Should you need to modify the Robot base start command (for example in order to use a custom Java environment or to raise the amount of heap memory allocated by JVM), perform the following steps:
   1. Locate Robot's extension configuration file RobotExtn.ini. The file gets created when Robot is called for the first time from T-Plan Professional GUI. It is saved to the application data folder whose location depends on the Windows version and configuration. Typical paths are:
      • Windows XP:  C:\Documents and Settings\<user>\Local Settings\Application Data\T-Plan\Extensions\RobotExtn\RobotExtn.ini
      • Windows Vista:  C:\Users\<user>\AppData\Local\T-Plan\Extensions\RobotExtn\RobotExtn.ini
   2. Edit the file. It contains a bunch of command templates where each one corresponds to a specific action invoked from T-Plan Professional GUI, such as:
      Run=java -Xmx256m -cp "%1\robot.jar;%1\jh.jar;%1\activation.jar;%1\mail.jar;%1\poi-3.6-20091214.jar" com.tplan.robot.ApplicationSupport
   3. Adjust the commands to your needs. The %1 variable in the example above will be replaced with the product install path specified in the previous paragraph. Each command may contain additional variables which are populated with CLI option values by T-Plan Professional.
   4. Save the file and restart T-Plan Professional to pick up the changes.

9. Optimizing Performance

As Robot can be employed in various automated scenarios and environments, its performance may be significantly improved through fine tuning.

Memory Adjustments

As Robot performs memory intensive image processing, memory performance tweaking may be required on certain systems.

If a java.lang.OutOfMemoryError or java.lang.StackOverflowError stack trace is seen in the console window (command prompt on Windows), the first aid is to raise the amount of memory assigned to the Robot process:

1. Locate the Robot's java start command based on your start up preference:
   • If you call Java directly as is described in the Startup chapter, modify the command you use.
   • If you take advantage of the robot.sh, or robot.bat scripts to start Robot, edit the script and modify the startup java command in there.
   • If you start Robot from the Windows Start menu, update the command associated with the menu item.
   • If you start Robot from T-Plan Professional, refer to the Integration With T-Plan Professional chapter for the information on where to find the Windows INI file with the Robot start commands.
   • If you double click the robot.jar file to start Robot, start using the scripts instead. Starting of the JAR file makes the OS run the program with the default heap size of (usually 128MB).
2. If Robot fails with a java.lang.OutOfMemoryError you need to raise the heap size. The -Xmx parameter after the java  (or javaw) command indicates how much heap memory is your Java Virtual Machine allowed to use at a maximum. Raise this number to a higher value. For example, -Xmx512m allows the JVM heap to grow up to 512MB if needed. This limit doesn't mean that the memory is allocated immediately.
3. If Robot fails with a java.lang.StackOverflowError raise the stack size through the -Xss parameter. The syntax is the same as the -Xmx one. As the defauIt stack size is typically between 384k and 512k for x86 systems and 1MB for x64 ones it is usually sufficient to increase the stack memory to 1MB on x86 (-Xss1m) or to 2MB on x64 (-Xss2m).

Though Java is likely to accept any number up to the size of your RAM through the -Xmx switch, the behavior is further subject to the system architecture:

• Java is not able to allocate more than approx. 1GB of memory on 32-bit systems (x86). This is caused by two factors. Java requires contiguous (uninterrupted) chunk of memory for the heap. Most 32-bit systems are also not able to address directly more than 2GB of RAM. As the OS consumes a significant amount of memory on its own, the largest contiguous space that Java is able to allocate on such environment is typically about 1GB.
• Deployments requiring larger memory are recommended to be hosted on 64-bit systems (where both the OS and Java are 64-bit) with sufficient amount of physical RAM. Be aware that the Robot application takes up twice as much memory on a 64-bit JVM than on a 32-bit one. This is because all references (pointers) that occupy most of the memory are double size (64-bit opposed to 32-bit). From this point of view moving Robot from a 32-bit environment with 1GB of RAM to a 64-bit one with 2GB of RAM doesn't make much sense because the application will not be able to allocate any extra memory. In such a case it may be equal or even better to use the x64 system together with a 32-bit Java installation.

Tips to minimize the memory consumption:

• Keep the number of open script editors at a minimum. One usually doesn't need to edit tens of scripts at a time.
• Prefer the "search2" image comparison method for the search of components on the screen. It has much lower memory requirements than the legacy "search" one.
• If your script creates lots of output objects such as screen shots, logs, warnings or steps, move the Report call to the end of the script. It will make the it run much faster and consume less memory because it will avoid numerous generations of the result XML/HTML along the way. This step will have no effect on the final report content.
• The default "Graphite" Look And Feel (LAF) looks neat but it also consumes more CPU and RAM. You may see a decent performance gain if you go to the Appearance & Accessibility panel of the Preferences window and set the LAF to the first OS default  one (requires Robot restart).
• Robot by default stores data from up to 20 most recent script executions for the needs of the Result Manager and Export To T-Plan wizards. If you run a high number of larger scripts in the GUI mode over the day, setting this limit to a lower value through the "Limit the recent list to" preference of the Result Manager panel in the Preferences window may get you a bit of extra memory.
• It is recommended to run the production automation in the CLI mode. It avoids the GUI and it has very low memory requirements. For details see the -n CLI switch documentation.

If you experience memory problems that can't be resolved using the hints above, please get us a memory dump from the failing Robot process. You may create it through clicking onto the memory monitor at the bottom right corner of the Robot  3.1.1+ GUI. Alternatively start Robot with the -XX:HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=./java_pid<pid>.hprof switches after the java (javaw) command to make the process create the dump automatically. See the Oracle documentation for details.

Client Side Configuration

Robot supports a large number of configurable parameters which may improve performance of both the Robot application as well as the VNC connection. The following table lists the most important ones.

Server Side Configuration

There are several simple recommendations which may significantly improve performance of the client-server connection:

• Change the server desktop background to a solid color which can be efficiently compressed through encodings. Pictures or photographs significantly increase volume of image data transferred over the network.
• Remove all unnecessary dynamically updating objects from the desktop, such as clocks or gadgets showing pictures in a loop. These components are sources of frequent desktop updates and increase network traffic.
• Try servers from different producers if available. Some products come with custom video drivers or hook ups to boost performance.
• Use an appropriate remote desktop size (resolution). The volume of image data is linear to the desktop size.

10. Troubleshooting

This chapter is intended to document the most common install and set up errors. If you meet an issue which is not described in here, report it through the Enterprise contacts at http://www.t-plan.com/support.

Robot fails to start with a message "java: command not found"

There's no Java installed on your machine or path to the Java executable is not included in your OS path. Read chapter Client System Requirements of this document.

Robot fails to start with a message "Exception in thread "main" java.lang.NoClassDefFoundError: com/tplan/robot/ApplicationSupport"

This indicates that the Robot JAR (Java ARchive) file robot.jar is not correctly included in the Java class path.

• • Switch to the Robot installation directory and make sure that the robot.jar file is there and that you have permission to read it.
  • Re-run the robot.sh or robot.bat from this directory. Alternatively modify the java command to include this library in the -classpath argument.

Robot starts but prints out a message "JavaHelp libraries not found. Please make sure that file jh.jar is included in the Java class path."

This indicates that the JavaHelp JAR file jh.jar is not correctly included in the Java class path. The tool will run but you will not have access to the online help. Some links which open in a web browser may however work fine. As all the help documents are available online, you may switch to the online documentation and ignore this error. To resolve it:

• Switch to the Robot installation directory and make sure that the jh.jar file is there and that you have permission to read it.
• Re-run the robot.sh or robot.bat from this directory. Alternatively modify the java command to include this library in the -classpath argument.

Robot fails to start with a NoClassDefNotFoundError, NoSuchFieldError or any other severe Java error

Unless one of the cases listed above applies, these problems are typically experienced when you use Java of version lower than the required one. See the Client System Requirements chapter for required Java version and run java -version to find out which version you have installed.

Either the robot.sh or robot.bat script fails to pass some CLI options

The wrapper script can't handle more than 9 options. All options above this limit are ignored. You must run Java directly as is described in the Startup chapter.

Robot crashes with java.lang.OutOfMemoryError

Raise the memory limit as is described in the Memory Adjustments chapter.