Skip to main content

Conditionals in Steps

Understanding how to use a conditional in a step

Updated this week

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

  1. Project Properties: All properties defined in your project's options are automatically available under context.project - no additional setup required

  2. Document Preservation: When a step is skipped, any existing document is automatically passed to the next step in the pipeline

  3. Final Step Handling: If the last step is skipped but has a document, the document is still uploaded as output

  4. Safe Evaluation: Conditionals use simpleeval for secure expression evaluation - only basic Python operations are allowed

  5. Error Handling: Failed conditional evaluations don't stop the pipeline; they skip the step and log the error

Best Practices

  1. 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"
  2. 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"
  3. 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 just context

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.

Did this answer your question?