Robot structure & configuration

What is the robot structure, and why to configure?

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 file 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 Robocorp Cloud as you can see and selected 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 Robocorp Cloud).
  • 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 does 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

Robocorp Lab and the Robocorp VS Code extension provide the latest templates for the robot structures so the easiest way is to start there. You can also check out our example robots at robocorp/example-activities.

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

Minimal structure

If your robot is small and simple, doesn't have many libraries or tasks you will get by just 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 robots that are a bit bigger, have 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 # In bigger & open-source project it is always to write-up the license boilerplate early rather than late
├── 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 when running the robot in Robocorp Lab and the Robocorp VS Code extension

When run in Robocorp Cloud Container, Robocorp Workforce Agent or Robocorp Assistant, the robots have access to a set of default environment variables that are 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 Robocorp Cloud UI.

To support the development and local running of the robots, environment variables can also be set locally: typical use cases are in combination with the RPA.Robocloud.Items or the RPA.Robocloud.Secrets 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 Lab and the Robocorp VS Code extension.