Robot structure & configuration

What is the robot structure, and why configure it?

These guidelines on software robot project structure make maintaining and sharing robots easier.

The robot structure described here is a solid starting point. We prefer convention over configuration. We also realize that "one ring to rule them all" does not always apply to real-world cases. For this reason, we have configuration support via the robot.yaml file. The YAML file enables you to control the structure and works as the anchor point for execution.

We recommend keeping individual robots small. However, the configuration file still allows you to develop more than one task inside your robot.

This enables, for example, the use of shared libraries inside the robot. One robot should always work in one execution environment. For this reason, the conda configuration and environment setups are always common inside a robot.

The configuration also simplifies usage in Control Room as you can see and select directly from robots and their tasks and don't have to define the commands separately.

Robot configuration file (robot.yaml)

The robot.yaml configuration file should be placed in the root directory of your robot. For a more technical specification and examples on the format, see the robot YAML format.

With the configuration file, you can:

  • Define the directory for your outputs (that Robocorp Workforce Agent and Robocorp Assistant will push to Control Room).
  • Define what directories in your robot are set to PATH and PYTHONPATH during executions.
  • Define the command to execute without platform dependencies or scripts. The command is broken into an argument list so that empty spaces and different OS handling do not cause errors.
  • Define the location of your conda configuration file.
  • Control which files are ignored when packaging your robot (.gitignore files)

File and folder structure recommendations

The Robocorp Code for VS Code and RCC provide the latest templates for the robot structure. You can also check out our Portal for example robots.

The following examples describe the recommended robot structures for the simplest and more extensive robots.

Minimal structure

If your robot is small and simple and doesn't have many libraries or tasks, you will get by fine with a very minimal structure.

โ”œโ”€โ”€ conda.yaml โ”œโ”€โ”€ .gitignore โ”œโ”€โ”€ output โ”‚ โ””โ”€โ”€ # Having a standard place for outputs is always good โ”œโ”€โ”€ robot.yaml โ””โ”€โ”€ tasks.robot

Structure for a bigger robot

For bigger robots that use more libraries and shared items, a bit of folder structuring goes a long way in the maintenance phase.

โ”œโ”€โ”€ bin โ”‚ โ””โ”€โ”€ # Place your external binaries & executable here โ”œโ”€โ”€ config โ”‚ โ””โ”€โ”€ conda.yaml โ”œโ”€โ”€ devdata โ”‚ โ”œโ”€โ”€ env.json โ”‚ โ””โ”€โ”€ # A place for your development phase test data โ”œโ”€โ”€ .gitignore โ”œโ”€โ”€ libraries โ”‚ โ””โ”€โ”€ # Collect your library files here โ”œโ”€โ”€ LICENSE โ”œโ”€โ”€ output โ”‚ โ””โ”€โ”€ # Having a standard place for outputs is always good โ”œโ”€โ”€ # Mark-down readme in the root is a good place to describe what the thing does. โ”œโ”€โ”€ resources โ”‚ โ””โ”€โ”€ #A common style in Robot Framework is to place your keyword implementations in one location โ”œโ”€โ”€ robot.yaml # The must-have configuration file in the root โ”œโ”€โ”€ tasks โ”‚ โ””โ”€โ”€ # Another common style in Robot Framework is to place your robot task implementations in one location โ”œโ”€โ”€ temp โ”‚ โ””โ”€โ”€ # Always good to have one standard place for temp files โ””โ”€โ”€ variables โ””โ”€โ”€ # A place for your variable definitions makes these easy to find and manage

Specifying environment variables in local development environment

When run in Control Room Container, Robocorp Workforce Agent, or Robocorp Assistant, the robots have access to a set of default environment variables needed for the correct functioning of the robot. Additionally, a user can specify additional environment variables to configure the behavior of the robot using the Control Room UI.

To support the development and local running of the robots, environment variables can also be set locally: typical use cases combine the RPA.Robocorp.WorkItems or the RPA.Robocorp.Vault libraries, which require additional setup to be used locally.

You can set locally any environment variable by:

  • creating a devdata directory in the root of the robot, and
  • creating an env.json JSON file in the devdata directory.

The JSON file follows this format:

{ "VARIABLE1_NAME": "Variable1 value", "VARIABLE2_NAME": "Variable2 value" }

The variables specified in the JSON file will then be picked up during local runs by Robocorp Code for VS Code.

Last edit: December 17, 2021