Bamboo Engine

LAZY variables (represented by the pipeline.core.data.var.LazyVariable class) are an extension of SPICE variables. They allow you to define relationships between variables and, crucially, perform custom logic on the results of variable references.

While SPICE variables handle basic referencing, LAZY variables allow you to intercept the resolved value and apply further processing or transformations before the value is used in the workflow.

The bamboo-engine is the core engine that defines the basic engine model, workflow execution core, and the engine runtime interface. To use the engine in a project, you must use a runtime that implements the bamboo_engine.eri.interfaces.EngineRuntimeInterface.

Currently, the available runtime is:

• bamboo-pipeline: A runtime based on Django and Celery.

Developers interact with the engine by providing a specific runtime instance to the engine's APIs.

Bamboo Engine is an event-driven workflow engine based on directed graphs. The fundamental building blocks are:

• Pipeline (流程): A directed graph that starts with a specific node and ends with a specific node.
• Nodes (节点): The elements within a pipeline (excluding edges). A pipeline itself is considered a node.
• Sequence Flow (顺序流): The directed edges that connect nodes in a pipeline.
• ID: A unique identifier for every pipeline, node, and sequence flow in the system.

SPLICE variables allow you to declare relationships and references between variables, enabling complex data interactions within a workflow.

Key Rules:

• Use the syntax ${xxxx} to declare a reference to a variable in the data context.
• In the data context, only variables whose keys are in the ${xxxx} format can be referenced by SPLICE variables.
• SPLICE variables are lazy: they are not parsed when created. Instead, the engine resolves them just before a node (component) executes.
• The engine performs recursive resolution: if param_1 references ${constant_1}, and ${constant_1} references ${constant_2}, the engine will resolve the entire chain to find the final value.

This mechanism allows for direct references, chained references, and multi-variable references.

Once elements are instantiated, they must be connected to define the execution path. The builder provides the following methods for establishing relationships between nodes:

• extend: Chains the current element to the next one in a linear sequence.
• connect: Establishes a connection between elements.
• converge: Used to merge multiple incoming flows.
• to: Specifies a target for a connection.

The pipeline runtime provides several Django signals that act as hooks throughout the workflow execution lifecycle.

⚠️ Warning: Because Django signals are a synchronous mechanism, do not execute long-running or time-consuming logic within a signal handler, as this will degrade the overall execution efficiency of the engine.

You can use these signals to trigger custom logic when specific events occur, such as state changes or service executions.

bamboo-engine is a core workflow engine that defines the logic for parsing, executing, and scheduling tasks. It does not include a built-in runtime. To use it, you must provide a runtime that implements the bamboo_engine.eri.interfaces.EngineRuntimeInterface.

A common runtime provided is bamboo-pipeline, which is based on Django and Celery.

The Flow Builder provides several types of elements to define the components of a workflow:

Events

• EmptyStartEvent: Represents the starting point of a workflow.
• EmptyEndEvent: Represents a simple termination point.
• ExecutableEndEvent: Represents an end point that may involve execution logic.

Activities

• ServiceActivity: Executes a specific component identified by component_code.
• SubProcess: Represents a nested workflow within the main flow.

Gateways

• ParallelGateway: For parallel execution paths.
• ExclusiveGateway: For branching logic where only one path is taken.
• ConditionalParallelGateway: For conditional parallel execution.
• ConvergeGateway: For merging multiple paths back into one.

Data

• Data, Var, NodeOutput, RewritableNodeOutput, Params, DataInput: Used to manage state and data flow between nodes.

All interactions with bamboo_engine.api return an EngineAPIResult object. This object provides a standardized way to check the success of an operation and retrieve associated data or error information.

Fields:

• result (bool): Indicates if the operation was successful.
• message (str): Additional message; focus on this if result is False.
• exc (Exception, optional): The exception object if an error occurred.
• data (Any, optional): Associated data returned by the operation.

class EngineAPIResult:
    def __init__(
        self,
        result: bool,
        message: str,
        exc: Optional[Exception] = None,
        data: Optional[Any] = None,
    ):
        self.result = result
        self.message = message
        self.exc = exc
        self.data = data