packages

Executable Packages

1. Overview

An executable package is your automation packaged within a single ZIP file. It is intended to be:

  • Self contained. It contains all your automation code (scripts, workitems, template images), your data (for example MS Excel sheets), configuration file and anything else needed to execute the automation.
  • Executable out of the box. To run your automation simply unzip it and execute the start script or pass the package to an installed Robot instance. For automation on clean environments the package may even contain its own Robot instance and Java.
  • Secure. You may encrypt the automation code to hide sensitive information.
  • Redistributable and manageable. You may distribute packages to other users to perform the automation or may have a RAP system to do it for you. Even if you don't have RAP you may still use the RAP Agent to manage the packages on your local machine.

Executable packages are supported since Robot release 7.

2. Creating a Package

As of release 7.0 packages are read-only snapshots of your automation environment. Editing of an existing package is not supported. You may only create it anew. This may change in the future.

To create a package open the Build Executable Package wizard using one of the following options:

  • Press Ctrl+E in the main Robot GUI
  • Select the Script→Build executable package menu item
  • The menu item is also present in right click context menus of a script or workitem.


The first screen selects the script (.tpr, .java) or a workitem (.xml) to be executed by the package:

Do not worry if your script or workitem depends on other scripts or workitems within the same project. The wizard always packages the whole project save for a few folders containing runtime data, such as reports and Image Doctor data. This has a few important consequences:

  • Keep your projects small. Use separate projects for different automated tasks.
  • If your code depends on external data such as for example MS Excel sheets, store the file(s) in your project and update your code to access them using a relative path.
  • Consider encryption if there is anything sensitive in your project.

Since the 7.0.2 release this screen checks for file based portability issues. If the selected script or workitem uses absolute file paths or relies on a file located outside the project a warning is displayed. It is recommended to resolve such issues prior to creating the package.

The second screen sets input parameters of the selected workitem or script:

  • Workitems declare their parameters in the Workitem Editor.
  • Scripts do not declare parameters. The screen will however list names of variables declared by the script through the Var command and you may optionally override their values. This will have the same effect as fixing the values through the -v/--variable CLI option.

Next screen defines the package type:

  • Lightweight packages contain the project only. They are typically very small because their size is subject to the volume of your code, component images and data. They can be executed only on machines with Robot properly installed and configured. There's no need to tell the package where Robot is - it will look it up by reading the Robot configuration file which is at a well known location. The disadvantage of this package type is that if your automation relies on an optional component such as a plugin or a custom Java library you must install it on the target machine the same way.
  • Full packages contain a copy of your Robot instance. If you installed a plugin or saved some files into its installation folder they will be packaged as well. A Java instance may be optionally added too to create a package for machines without Java installed. The disadvantage of this solution is size - a full package with Robot, Java and a bulky plugin such as Chromium may easily exceed 500 MB. As Java and some plugins such as Chromium are OS specific the package will also works on one OS only.

The screen offers a few additional settings. You may optionally encrypt the project inside the package. The Robot configuration file can be also added to ensure that the target Robot instance will behave the same way as the source one.

Version 7.0.2 performs checks for portability issues and preselects the best fitting options.

Next screen populates the package attributes:

 There are obvious fields such as the package display name, description, author and version. There are a few optional flags allowing to restrict the target environment such as the minimum Robot version and the operating systems the package may execute on.

  • Minimum Robot version is typically enforced when the automation relies on a certain feature delivered in the specified release. It's safer to set it on if you are not sure. If you select the Full package type later the flag will be ignored anyway because a Robot instance will be included in the package.

If the selected type is Full the next screen will be Java:

It is possible to package only Java which was installed as a Robot plugin. If you haven't installed it select Install. Installation of Java for packaging purposes doesn't require restart so you will be able to go back to the wizard.

The last screen specifies the target package file:

If you have the RAP Agent installed the screen will suggest you to put it to the agent storage. This will make it instantly available for sharing and execution in the agent window.

The package will be created after you hit Finish. If you peek inside the zip file it will look like this:

The files are as follows:

  • Your project is stored in the project.zip file which may be encrypted.
  • The Robot instance including Java is in the robot/ folder.
  • The package.properties file stores the package attributes.
  • The rap/ folder is an internal stuff to ensure compatibility with the RAP system.
  • The start.bat and start.sh files are start scripts.

3. Executing a Package

The package can be executed in three ways:

  • Unzip the package on your hard drive and run the start.bat script (MS Windows) or start.sh (Mac OS, Linux/Unix). The script will look up the Robot instance depending on the package type (internal/external) and pass it all the necessary parameters.
  • Pass the ZIP file to an already installed Robot instance through the -r/--run CLI option. If the package is of the Full type the Robot and Java instances contained inside will be ignored.
  • Execute the package through the RAP Agent.