--- layout: default title: Getting Started --- # 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](https://robotframework.org/) test or task suites with the [Operaton](https://operaton.org/) BPM engine. ## Prerequisites `purjo` requires Python 3.10 or newer, and relies on [`uv`](https://github.com/astral-sh/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. ```console $ 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: ```console $ 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: ```console $ 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: ```console $ 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 ```console $ pur run ``` Replace `` with the path to your BPMN file. ### Example Let's assume you have a `hello.bpmn` file in your project. ```console $ 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 ```console $ 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: ```console $ 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.