Overview
Conditionals allow you to control whether pipeline steps execute based on runtime context, enabling dynamic workflow behavior without modifying the pipeline structure itself.
How Conditionals Work
Each step in a Kodexa pipeline can include an optional conditional
property containing a Python expression. When the pipeline runs, this expression is evaluated against the current execution context to determine if the step should execute.
Basic Syntax
{ "ref": "your-org/your-step", "conditional": "context.project.environment == 'production'", "options": {...} }
Available Context
Conditionals have access to the execution context through the context
variable, which contains:
Project Properties
When running within an assistant project, all project options/properties are automatically available under context.project
:
# Access project-level configuration "context.project.processing_mode == 'advanced'" # Check environment settings "context.project.environment == 'production'" # Validate against project thresholds "context.project.min_confidence_threshold <= 0.85" # Check feature flags "context.project.enable_ocr == True"
Runtime Context
Data from previous steps
Document metadata
Custom variables set during execution
Pipeline state information
Example Expressions
# Use project configuration to control flow "context.project.document_type == 'invoice'" # Combine project and runtime context "context.project.processing_enabled and context.page_count > 5" # Environment-specific processing "context.project.environment != 'development'" # Feature flags from project settings "context.project.enable_ml_extraction == True"
Behavior
True Result: Step executes normally
False Result: Step is marked as "SKIPPED" and pipeline continues
Evaluation Error: Step is skipped with error logging
Important Notes
Project Properties: All properties defined in your project's options are automatically available under
context.project
- no additional setup requiredDocument Preservation: When a step is skipped, any existing document is automatically passed to the next step in the pipeline
Final Step Handling: If the last step is skipped but has a document, the document is still uploaded as output
Safe Evaluation: Conditionals use
simpleeval
for secure expression evaluation - only basic Python operations are allowedError Handling: Failed conditional evaluations don't stop the pipeline; they skip the step and log the error
Best Practices
Use Project Properties for Configuration: Leverage project properties for environment-specific behavior
# Define in project options: # { "skip_validation": false, "environment": "staging" } # Use in conditional: "not context.project.skip_validation"
Check for Property Existence: Verify project properties exist before accessing
# Safe access to optional project properties "'custom_threshold' in context.project and context.project.custom_threshold > 0.9"
Environment-Based Logic: Use project properties to differentiate environments
# Different behavior for production "context.project.environment == 'production' and context.project.strict_mode == True"
Common Use Cases
Environment-Specific Processing
Skip expensive operations in development:
"context.project.environment == 'production'"
Feature Toggles
Enable/disable features via project configuration:
"context.project.features.advanced_extraction == True"
Customer-Specific Logic
Different processing based on project configuration:
"context.project.customer_tier == 'enterprise'"
Quality Thresholds
Use project-defined thresholds:
"context.confidence_score >= context.project.min_confidence"
Multi-Tenant Processing
Route based on project settings:
"context.project.region == 'eu' and context.project.gdpr_mode == True"
Setting Up Project Properties
Project properties that become available in context.project
are configured at the project level in your assistant configuration. These properties are automatically injected into the execution context when the pipeline runs.
Example project configuration:
{ "options": { "properties": { "environment": "production", "min_confidence": 0.85, "enable_ocr": true, "customer_tier": "enterprise", "processing_mode": "advanced" } } }
Troubleshooting
Project Properties Not Available:
Ensure your assistant is configured with a project
Verify project options/properties are properly set
Check that you're accessing via
context.project
not justcontext
Step Always Skips:
Verify your project properties match expected values
Check conditional logic with your actual project configuration
Review logs for evaluation errors
Conditional Not Evaluating:
Ensure the expression is valid Python
Check for typos in property names
Verify nested properties exist before accessing
This feature enables sophisticated workflow control through project-level configuration, making it ideal for multi-environment deployments and customer-specific processing requirements without code changes.