Operaton Robot Playground

Welcome to this opinionated documentation for orchestrating Robot Framework test or task suites with Operaton BPM engine. The documentation was introduced for a workshop at RoboCon.io Helsinki 2025 and revised for 2026.

Getting started

To get started, pick any of the following options:

• Open this repository in GitHub Codespaces.

• Or clone this repository and open it using VSCode Dev Containers extension.

• Or clone this repository, and install GNU Make and devenv.sh.

• Or choose your own adventure by manually installing uv, purjo and Operaton or other compatible BPM engine.

Down the rabbit hole

Activate the playground by starting its built-in Operaton build with

$ make start
✔ Building shell in 6.2s.
• PID is 56105
• See logs:  $ tail -f /workspaces/operaton-robot-playground/.devenv/processes.log
• Stop:      $ devenv processes stop
✔ Starting processes in 6.2s.

Next, check if pur(jo) is already available

$ pur

If not, run make shell to manually activate the playground devenvshell with uv and pur(jo) pre-installed, and defauld Python virtualenv activated.

Hello World

Once you have entered the shell with either make start shell or separately make start and make shell, you should be able to try out the following example:

1. Create directory for your bot

   $ mkdir hello-world
   $ cd hello-world
   $ pur init
   Adding uv.lock
   Adding test_hello.robot
   Adding hello.robot
   Adding pyproject.toml
   Adding hello.bpmn
   Adding Makefile
   Adding README.md

2. Deploy and start the example process

   $ pur run hello.bpmn
   Started: http://localhost:8080/operaton/app/cockpit/default/#/process-instance

3. Serve the example bot

   $ pur serve .
   02-02-2025 14:39:49 | INFO | purjo.runner:267 | Subscription | name=My Task
   02-02-2025 14:39:49 | INFO | operaton.tasks.worker:263 | External task worker started.

Troubleshooting

VSCode & Podman

Local VSCode with Podman, might require the following .devcontainer.json:

{
  "containerUser": "vscode",
  "customizations": {
    "vscode": {
      "extensions": [
        "bbenoist.Nix",
        "be5invis.toml",
        "charliermarsh.ruff",
        "d-biehl.robotcode",
        "ms-vscode.makefile-tools",
        "/workspaces/operaton-robot-playground/resources/miranum-modeler.vsix"
      ]
    }
  },
  "image": "ghcr.io/cachix/devenv/devcontainer:v1.8.2",
  "containerEnv": {
    "HOME": "/home/vscode",
    "UV_LINK_MODE": "copy",
    "UV_PYTHON_DOWNLOADS": "never"
  },
  "overrideCommand": false,
  "runArgs": [
    "--userns=keep-id"
  ],
  "updateContentCommand": "devenv test"
}

Curious devenv errors

Very occasional and rare errors like the following have been seen:

operaton-robot-playground) vscode ➜ /workspaces/operaton-robot-playground (main) $ make start
devenv processes up -d
• Building processes ...
• Using Cachix: devenv, datakurre
don't know how to build these paths:
  /nix/store/4g8f25hp2yblrhnwd8frmcjfscklb1cc-devenv-up
error:
       error: build of '/nix/store/4g8f25hp2yblrhnwd8frmcjfscklb1cc-devenv-up'

This should be fixed by running the following cleanup command

$ make clean

and trying again. For example, rebuilding the local devcontainer.

License

This project is licensed under the European Union Public Licence v. 1.2 (EUPL-1.2).