Creating tasks

This guide explains how to create tasks that can be orchestrated by purjo using either traditional Robot Framework keyword libraries or a more advanced pure Python approach.

Basic task (Robot Framework)

The most common way to define tasks in purjo is by using Robot Framework keyword libraries. This involves creating a Python file with your custom keywords and a .robot file to define the task suite.

Example: The “Hello” task

Here is a basic illustration.

Hello.py (Keyword library)

from robot.api.deco import keyword
from robot.api.deco import library


@library()
class Hello:
    @keyword()
    def hello(self, name: str) -> str:
        return f"Hello {name}!"

This Python file defines a simple Robot Framework library named Hello with one keyword: hello. This keyword takes a name and returns a greeting string.

hello.robot (Task suite)

*** Settings ***
Library    Hello

*** Tasks ***
My Task in Robot
    ${greeting}=    Hello    World
    Log To Console    ${greeting}

The hello.robot file imports the Hello library and defines a task named “My Task in Robot”. This task calls the hello keyword, passes “World” as the name, and logs the returned greeting to the console.

hello.bpmn (BPMN process)

Your BPMN process would then include an external service task that references this Robot Framework task. For instance, a service task with Topic “My Topic in BPMN” might be configured to execute “My Task in Robot” from hello.robot.

Configuration

To map the BPMN topic to the Robot Framework task, you need to configure pyproject.toml.

[tool.purjo.topics."My Topic in BPMN"]
name = "My Task in Robot"
on-fail = "ERROR"
process-variables = true
pythonpath = ["./libs", "./modules"]
task-metadata = ["activityId", "createTime", "businessKey"]
  • [tool.purjo.topics."<Topic Name>"]: Defines the configuration for a specific BPMN topic.

  • name: The name of the Robot Framework task (or Python function) to execute.

  • on-fail: Determines the behavior when the task fails (e.g., “ERROR”, “FAIL”). See Variables of a failed task for what a failed task leaves behind.

  • process-variables: If true, process variables are passed to the task. If false, only task scope variables are passed to the task.

  • pythonpath: (Optional) A list of additional paths to add to Robot Framework’s --pythonpath. This allows importing custom libraries and modules from specified directories.

  • task-metadata: (Optional) A list of string LockedExternalTaskDto field names to expose as Robot variables named TASK_METADATA_<FIELD_IN_SCREAMING_SNAKE>, such as ${TASK_METADATA_ACTIVITY_ID}. See available metadata selections and their Robot variable names. The DTO’s variables map is not selectable. Omit the option or use an empty list to disable metadata variables; null, unknown names, and duplicate names are invalid.

The TASK_METADATA_ prefix is reserved for these variables; do not use it for BPMN inputs or secret names. Selected null values remain available as Robot None values, and nested values such as extensionProperties remain dictionaries. A BPMN input that collides with a metadata variable after Robot’s case/space/underscore normalization fails the task before Robot runs. Collision handling follows on-fail: FAIL and COMPLETE produce a technical task failure (COMPLETE does not suppress the collision), while ERROR produces a BPMN error.

For example, if a process is started with a known businessKey, the topic can expose it and copy it to a distinct BPMN process variable:

$ pur run process.bpmn --variables '{"businessKey": "invoice-42"}'
*** Test Cases ***
Keep Business Key
    Should Be Equal    ${TASK_METADATA_BUSINESS_KEY}    invoice-42
    VAR    ${metadata_business_key}    ${TASK_METADATA_BUSINESS_KEY}    scope=${BPMN:PROCESS}

Advanced task (Pure Python)

purjo also supports defining tasks directly in Python, allowing for more complex logic and direct integration with Python’s type hinting and data validation features like Pydantic. This approach can replace the need for a separate .robot file for simple tasks.

Example: A pure Python task

This approach is demonstrated below.

tasks.py (Pure Python task)

from pydantic import BaseModel
from robot.api import logger
from robot.libraries import BuiltIn
from typing import Literal
import json


VariableScope = Literal["BPMN:TASK", "BPMN:PROCESS"]


class InputVariables(BaseModel):
    name: str = "John Doe"


class OutputVariables(BaseModel):
    message: str


def get_variables() -> InputVariables:
    library = BuiltIn.BuiltIn()
    return InputVariables(**library.get_variables(no_decoration=True))


def set_variables(
    variables: OutputVariables, scope: VariableScope = "BPMN:PROCESS"
) -> None:
    library = BuiltIn.BuiltIn()
    try:
        if scope == "BPMN:TASK":
            for name, value in variables.model_dump().items():
{% raw %}
                library._variables.set_bpmn_task(f"${{{name}}}", value)
        else:
            for name, value in variables.model_dump().items():
                library._variables.set_bpmn_process(f"${{{name}}}", value)
{% endraw %}
    except AssertionError:
        logger.info(json.dumps(variables.model_dump(), indent=2))


def main():
    variables = get_variables()
    set_variables(OutputVariables(message=f"Hello, {variables.name}!"))


if __name__ == "__main__":
    from purjo import PythonParser
    from robot import run

    run(__file__, parser=PythonParser("tasks.main"))

Key features:

  • Pydantic Models (InputVariables, OutputVariables): These models enforce strict typing and validation for variables exchanged with the BPMN engine, making your task more robust.

  • get_variables() and set_variables(): Helper functions to easily retrieve input variables from the BPMN process and set output variables back to it.

  • main() Function: Encapsulates the core logic of your task. It retrieves variables, performs operations, and sets new variables.

  • if __name__ == "__main__": Block: This block enables the Python script to be executed directly as a Robot Framework task using purjo’s PythonParser. This means you can specify tasks.main as the Robot Framework task to be executed by your BPMN process, without needing a separate .robot file.

This advanced approach is particularly useful for tasks that are primarily Python-based, requiring minimal or no Robot Framework specific syntax beyond what purjo provides for variable handling.

Configuration

To map the BPMN topic to the Pure Python task, you need to configure pyproject.toml.

[tool.purjo.topics."My Topic in BPMN"]
name = "tasks.main"
on-fail = "FAIL"
process-variables = true
  • name: The name of the Python function to execute, in the format module.function. In this example, tasks.main refers to the main function in tasks.py.

Adding dependencies

When your tasks require external Python libraries (e.g., requests, pandas, PyPDF2), add them to your project’s runtime dependencies. Task execution installs runtime dependencies only; dependency groups such as dev are not installed. purjo uses uv for dependency management.

To add a dependency, use the uv add command:

$ uv add requests

This command updates your pyproject.toml file and the uv.lock file, ensuring that the dependency is available when your tasks are executed.

Packaging

Once your tasks are ready, you can package them into a robot.zip file using the pur wrap command.

$ pur wrap

This command creates a robot.zip file containing your project files, excluding those specified in .wrapignore (and default exclusions like .git, __pycache__, etc.). This zip file can be deployed to an external worker or used for distribution.

Creating BPMN resources

purjo provides a convenient way to create new BPMN, DMN, and Form files using the pur operaton create command.

$ pur operaton create my-process.bpmn
$ pur operaton create my-decision.dmn
$ pur operaton create my-form.form

This generates template files with unique IDs, ready for editing in any bpmn.io-compatible modeler.