Task Packages

What is a Task Package, and why do I need to configure it?

These guidelines on software automation project structure make maintaining and sharing automations easier.

A task package is:

  • Your automation code (python files, resource files, etc.)
  • The environment configuration or dependencies your code needs (conda.yaml)
  • Task package configuration file (robot.yaml) ..all together a task package contains everything needed to run your automation on another machine.

The task package 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 task packages small. However, the configuration file still allows you to develop more than one task inside your task package.

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

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

Task package configuration file (robot.yaml)

The robot.yaml configuration file should be placed in the root directory of your task package. 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 task package 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 task package (.gitignore files)

File and folder structure recommendations

The Robocorp Code for VS Code and RCC provide the latest templates for the task package structure. You can also check out our Portal for examples.

The following examples describe the recommended task package structures for the simplest and more extensive automations.

Minimal structure

If your task package 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.py

Structure for a bigger automation

For bigger task packages 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 โ”œโ”€โ”€ devdata โ”‚ โ”œโ”€โ”€ env.json โ”‚ โ””โ”€โ”€ # A place for your development phase test data โ”œโ”€โ”€ libraries โ”‚ โ””โ”€โ”€ # Collect your library files here โ”œโ”€โ”€ output โ”‚ โ””โ”€โ”€ # Having a standard place for outputs is always good โ”œโ”€โ”€ variables โ”‚ โ””โ”€โ”€ # A place for your variable definitions makes these easy to find and manage โ”œโ”€โ”€ .gitignore โ”œโ”€โ”€ conda.yaml โ”œโ”€โ”€ LICENSE โ”œโ”€โ”€ README.md # Mark-down readme in the root is a good place to describe what the thing does. โ”œโ”€โ”€ robot.yaml # The must-have configuration file in the root โ””โ”€โ”€ tasks.py

Specifying environment variables in local development environment

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

To support the development and local running of the automations, 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 task package, 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, 2023