Getting started

This guide explains how to start a new purjo project using the pur init command and outlines the purpose of the files generated.

purjo (/ˈpurjo/) is an experimental command line tool for orchestrating Robot Framework test or task suites with the Operaton BPM engine.

Prerequisites

purjo requires Python 3.10 or newer, and relies on uv for Python package and environment management. Ensure uv is installed and available in your system PATH.

Initializing a new project

To begin a new purjo project, navigate to your desired project directory and use the pur init command. This command sets up the basic structure required for purjo to function.

$ mkdir my-purjo-project
$ cd my-purjo-project
$ uv run --with=purjo -- pur init
Adding .python-version
Adding pyproject.toml
Adding README.md
Adding Hello.py
Adding hello.robot
Adding uv.lock
Adding hello.bpmn

This process creates a set of files and directories that form the foundation of your purjo project.

Robot Framework Tasks vs. Tests

By default, pur init creates templates using Robot Framework’s *** Test Cases *** section. If you prefer to use Robot Framework’s *** Tasks *** section (for RPA workflows), use the --task flag:

$ uv run --with=purjo -- pur init --task

The task template uses:

  • *** Tasks *** instead of *** Test Cases ***

  • Task Template instead of Test Template

  • Run Robot Task keyword instead of Run Robot Test

Guidance for coding agents

If you develop your automation package with the help of an LLM coding agent, use the --agents flag to also generate an AGENTS.md in the project root:

$ uv run --with=purjo -- pur init --agents

The generated AGENTS.md describes the package for an agent: the file layout, the topic-to-task mapping in pyproject.toml, the input and output variable conventions, failure semantics, secrets handling, the available commands, and how to test the package. It matches the flavour you initialized, so combine it with --task when you want the *** Tasks *** variant:

$ uv run --with=purjo -- pur init --task --agents

AGENTS.md is developer-facing documentation only. It is listed in .wrapignore, so it is not included in the robot.zip built by pur wrap.

The --agents flag is not supported together with --python, because the pure Python template is still experimental.

Project structure overview

Here’s a breakdown of the key files generated by pur init:

  • .python-version: Specifies the Python version to be used with uv.

  • pyproject.toml: Configuration file including dependencies and project metadata.

  • README.md: A basic README file for your project.

  • Hello.py: (Example-specific) A Python file typically containing a Robot Framework keyword library.

  • hello.robot: (Example-specific) A Robot Framework test or task suite.

  • uv.lock: A lock file managed by uv to ensure consistent dependency resolution.

  • hello.bpmn: A BPMN (Business Process Model and Notation) file that defines the workflow orchestrating your Robot Framework tasks.

  • test_hello.robot: An integration test that runs hello.robot locally, without a BPM engine.

  • Makefile: Convenience targets for the package. Run make help to list them.

  • .wrapignore: Specifies files to exclude when packaging the robot with pur wrap.

  • AGENTS.md: (Only with --agents) Guidance for LLM coding agents working on the package.

Running a BPMN process

The pur run command allows you to deploy a BPMN process definition to the Operaton BPM engine and immediately start a new instance of that process.

Usage

$ pur run <process.bpmn>

Replace <process.bpmn> with the path to your BPMN file.

Example

Let’s assume you have a hello.bpmn file in your project.

$ uv run --with=purjo -- pur run hello.bpmn
Started: http://localhost:8080/operaton/app/cockpit/default/#/process-instance/36228e79-e97e-11ef-a0ec-52f4bfd829ae/runtime

The output provides a URL to the Operaton Cockpit, where you can monitor the execution of your newly started process instance.

Serving tasks

Once a BPMN process is running, it may encounter “external service tasks” that need to be executed by an external worker. The pur serve command turns your purjo project into such a worker, long-polling for these tasks, executing them using Robot Framework, and reporting the results back to the Operaton engine.

Usage

$ pur serve [OPTIONS] ROBOTS...

You typically run pur serve . to serve all Robot Framework task suites found in the current directory.

Example

Continuing from the pur run example, if your hello.bpmn process has an external task, you would serve it like this:

$ uv run --with=purjo -- pur serve .
... | DEBUG | ... | Waiting for 1 pending asyncio task: ['My Topic in BPMN:3622b58f-e97e-11ef-a0ec-52f4bfd829ae'].
==============================================================================
Tmpdlb85Jrp
==============================================================================
Tmpdlb85Jrp.Hello
==============================================================================
My Task in Robot                                                      | PASS |
------------------------------------------------------------------------------
Tmpdlb85Jrp.Hello                                                     | PASS |
1 task, 1 passed, 0 failed
==============================================================================
Tmpdlb85Jrp                                                           | PASS |
1 task, 1 passed, 0 failed
==============================================================================
Output:  /tmp/nix-shell-49641-0/tmp2721mpez/output.xml
Log:     /tmp/nix-shell-49641-0/tmp2721mpez/log.html
Report:  /tmp/nix-shell-49641-0/tmp2721mpez/report.html
... | INFO | ... | Completing My Topic in BPMN:3622b58f-e97e-11ef-a0ec-52f4bfd829ae.

The output shows purjo connecting to the Operaton engine, picking up a task (“My Topic in BPMN”), executing the corresponding Robot Framework task (“My Task in Robot”), and then completing the external task in the BPMN process.