Advanced Options Features - Kodexa Developer Portal

This guide covers advanced patterns, complex configurations, and expert techniques for working with the Kodexa Options system. Once you’re comfortable with basic options, these patterns will help you build sophisticated, user-friendly configuration interfaces.

Multi-Level Option Nesting

Options can be nested multiple levels deep to create hierarchical configuration structures:

options:
  - name: data_pipeline
    type: object
    label: Data Pipeline Configuration
    properties:
      collapsible: true
    groupOptions:
      - name: input_settings
        type: object
        label: Input Configuration
        properties:
          collapsible: true
        groupOptions:
          - name: source_type
            type: select
            label: Source Type
            possibleValues:
              - label: Database
                value: database
              - label: File System
                value: filesystem
              - label: API
                value: api

          - name: database_config
            type: object
            label: Database Configuration
            showIf: "this.data_pipeline.input_settings.source_type === 'database'"
            groupOptions:
              - name: connection_string
                type: string
                label: Connection String
                required: true
              - name: query
                type: code
                label: SQL Query
                language: sql
                height: 200px

          - name: filesystem_config
            type: object
            label: File System Configuration
            showIf: "this.data_pipeline.input_settings.source_type === 'filesystem'"
            groupOptions:
              - name: directory
                type: string
                label: Directory Path
                required: true
              - name: file_pattern
                type: string
                label: File Pattern
                default: "*.txt"

      - name: processing_settings
        type: object
        label: Processing Configuration
        properties:
          collapsible: true
        groupOptions:
          - name: transform_script
            type: code
            label: Transform Script
            language: python
          - name: validation_rules
            type: code
            label: Validation Rules
            language: python

Best Practices for Nesting

Limit depth to 3 levels - Deeper nesting becomes hard to navigate
Use collapsible groups - Allow users to focus on relevant sections
Clear naming hierarchy - Use consistent naming patterns (e.g., config, settings)
Document the structure - Provide examples showing the full path access

Dynamic Option Dependencies

Create complex conditional relationships between options:

Example: Conditional Chains

options:
  - name: deployment_mode
    type: select
    label: Deployment Mode
    possibleValues:
      - label: Development
        value: dev
      - label: Staging
        value: staging
      - label: Production
        value: prod

  - name: enable_monitoring
    type: boolean
    label: Enable Monitoring
    default: false
    showIf: "this.deployment_mode === 'staging' || this.deployment_mode === 'prod'"

  - name: monitoring_level
    type: select
    label: Monitoring Level
    showIf: "this.enable_monitoring === true"
    possibleValues:
      - label: Basic
        value: basic
      - label: Detailed
        value: detailed
      - label: Debug
        value: debug

  - name: sampling_rate
    type: number
    label: Sampling Rate (%)
    showIf: "this.enable_monitoring === true && this.monitoring_level !== 'debug'"
    min: 1
    max: 100
    default: 10

  - name: debug_output_path
    type: string
    label: Debug Output Path
    showIf: "this.monitoring_level === 'debug'"
    required: true

Complex Conditional Logic

# Show option when multiple conditions are met
- name: advanced_feature
  type: boolean
  label: Enable Advanced Feature
  showIf: "this.user_level === 'expert' && (this.environment === 'staging' || this.environment === 'dev') && !this.simplified_mode"

# Show option based on array membership
- name: cloud_config
  type: object
  label: Cloud Configuration
  showIf: "['aws', 'azure', 'gcp'].includes(this.cloud_provider)"

# Show option based on numeric comparison
- name: batch_size_warning
  type: alert
  markdown: "⚠️ Large batch sizes may impact performance"
  type: warning
  showIf: "this.batch_size > 1000"

Dynamic Possible Values

Generate dropdown options dynamically based on other selections:

options:
  - name: data_store_type
    type: select
    label: Store Type
    possibleValues:
      - label: Document Store
        value: document
      - label: Module Store
        value: module
      - label: Data Store
        value: data

  # This would require custom component, but shows the pattern
  - name: specific_store
    type: select
    label: Select Store
    # In real implementation, possibleValues would be filtered dynamically
    # based on data_store_type

Pattern: Hierarchical Selection

options:
  - name: country
    type: select
    label: Country
    possibleValues:
      - label: United States
        value: us
      - label: United Kingdom
        value: uk
      - label: Canada
        value: ca

  - name: region
    type: select
    label: Region
    showIf: "this.country !== undefined"
    # In practice, possibleValues would be filtered based on country
    possibleValues:
      - label: East Coast
        value: east
      - label: West Coast
        value: west

Validation Patterns

Built-in Validation

options:
  - name: email
    type: string
    label: Email Address
    description: Must be a valid email format
    required: true
    # Add custom validation in your component code

  - name: port_number
    type: number
    label: Port Number
    description: Valid port range: 1-65535
    min: 1
    max: 65535
    required: true

  - name: percentage
    type: number
    label: Percentage
    description: Value between 0 and 100
    min: 0
    max: 100
    step: 0.1
    default: 50

Custom Validation in Code

class MyAssistant:
    def __init__(self, options):
        # Validate email format
        email = options.get('email')
        if email and '@' not in email:
            raise ValueError("Invalid email format")

        # Validate URL format
        api_endpoint = options.get('api_endpoint')
        if api_endpoint and not api_endpoint.startswith(('http://', 'https://')):
            raise ValueError("API endpoint must be a valid URL")

        # Validate file path exists
        config_path = options.get('config_path')
        if config_path and not os.path.exists(config_path):
            raise ValueError(f"Config file not found: {config_path}")

        # Cross-field validation
        min_value = options.get('min_value', 0)
        max_value = options.get('max_value', 100)
        if min_value >= max_value:
            raise ValueError("min_value must be less than max_value")

Password and Secret Management

Organization Secrets Integration

The string option type with password: true integrates with organization secrets:

options:
  - name: api_key
    type: string
    label: API Key
    description: Your API key or select from organization secrets
    password: true
    required: true

User Experience:

Users can either type the password directly
Or select from a dropdown of organization secrets
Secret references are stored as ${secret.secretName}
At runtime, Kodexa resolves the reference to the actual secret value

Benefits:

Centralized secret management
No hardcoded credentials in configurations
Easy rotation without updating all references
Secure storage and access control

Tab-Based Organization

For components with many options, organize them into tabs:

options:
  - name: general_settings
    type: object
    label: General
    tab: general
    groupOptions:
      - name: name
        type: string
        label: Name
      - name: description
        type: string
        label: Description
        lines: 3

  - name: connection_settings
    type: object
    label: Connection
    tab: connection
    groupOptions:
      - name: host
        type: string
        label: Host
      - name: port
        type: number
        label: Port

  - name: advanced_settings
    type: object
    label: Advanced
    tab: advanced
    properties:
      developerOnly: true
    groupOptions:
      - name: timeout
        type: number
        label: Timeout
      - name: retry_count
        type: number
        label: Retry Count

Real-World Examples

Example 1: SFTP Publishing Assistant

options:
  - name: connection
    type: object
    label: SFTP Connection
    properties:
      collapsible: false
    groupOptions:
      - name: hostname
        type: string
        label: Hostname
        description: SFTP server hostname or IP address
        required: true

      - name: port
        type: number
        label: Port
        description: SFTP server port
        default: 22
        min: 1
        max: 65535

      - name: username
        type: string
        label: Username
        description: SFTP username
        required: true

      - name: auth_method
        type: select
        label: Authentication Method
        possibleValues:
          - label: Password
            value: password
          - label: SSH Key
            value: ssh_key
        default: password

      - name: password
        type: string
        label: Password
        password: true
        showIf: "this.connection.auth_method === 'password'"
        required: true

      - name: ssh_key
        type: code
        label: SSH Private Key
        height: 200px
        showIf: "this.connection.auth_method === 'ssh_key'"
        required: true

  - name: transfer_settings
    type: object
    label: Transfer Settings
    properties:
      collapsible: true
    groupOptions:
      - name: remote_directory
        type: string
        label: Remote Directory
        description: Target directory on SFTP server
        default: "/upload"

      - name: file_naming
        type: select
        label: File Naming Convention
        possibleValues:
          - label: Original Name
            value: original
          - label: Timestamp Prefix
            value: timestamp
          - label: Custom Pattern
            value: custom

      - name: custom_pattern
        type: string
        label: Custom File Name Pattern
        description: Use {name}, {date}, {time} placeholders
        showIf: "this.transfer_settings.file_naming === 'custom'"
        default: "{name}_{date}_{time}"

      - name: overwrite_existing
        type: boolean
        label: Overwrite Existing Files
        default: false

  - name: data_options
    type: object
    label: Data Options
    properties:
      collapsible: true
    groupOptions:
      - name: format
        type: select
        label: Output Format
        possibleValues:
          - label: JSON
            value: json
          - label: CSV
            value: csv
          - label: Excel
            value: xlsx

      - name: include_header
        type: boolean
        label: Include Header Row
        showIf: "this.data_options.format === 'csv'"
        default: true

      - name: excel_options
        type: object
        label: Excel Options
        showIf: "this.data_options.format === 'xlsx'"
        groupOptions:
          - name: sheet_name
            type: string
            label: Sheet Name
            default: "Data"
          - name: freeze_header
            type: boolean
            label: Freeze Header Row
            default: true

Example 2: Machine Learning Module Configuration

metadata:
  type: module
  trainOptions:
    - name: training_data
      type: object
      label: Training Data
      groupOptions:
        - name: data_store
          type: tableStore
          label: Training Data Store
          required: true

        - name: split_ratio
          type: object
          label: Train/Test Split
          groupOptions:
            - name: train_percentage
              type: number
              label: Training Set (%)
              min: 50
              max: 95
              default: 80
            - name: validation_percentage
              type: number
              label: Validation Set (%)
              min: 0
              max: 30
              default: 10

    - name: hyperparameters
      type: object
      label: Hyperparameters
      properties:
        collapsible: true
      groupOptions:
        - name: learning_rate
          type: number
          label: Learning Rate
          min: 0.0001
          max: 1.0
          step: 0.0001
          default: 0.001

        - name: epochs
          type: number
          label: Epochs
          min: 1
          max: 1000
          default: 100

        - name: batch_size
          type: number
          label: Batch Size
          min: 1
          max: 512
          default: 32

        - name: optimizer
          type: select
          label: Optimizer
          possibleValues:
            - label: Adam
              value: adam
            - label: SGD
              value: sgd
            - label: RMSprop
              value: rmsprop
          default: adam

    - name: advanced
      type: object
      label: Advanced Settings
      properties:
        collapsible: true
        developerOnly: true
      groupOptions:
        - name: early_stopping
          type: boolean
          label: Enable Early Stopping
          default: true

        - name: patience
          type: number
          label: Patience (epochs)
          showIf: "this.advanced.early_stopping === true"
          min: 1
          max: 100
          default: 10

        - name: checkpoint_frequency
          type: number
          label: Checkpoint Every N Epochs
          min: 1
          max: 100
          default: 10

  inferOptions:
    - name: confidence_threshold
      type: number
      label: Confidence Threshold
      description: Minimum confidence score for predictions
      min: 0.0
      max: 1.0
      step: 0.01
      default: 0.85

    - name: batch_inference
      type: boolean
      label: Enable Batch Inference
      description: Process multiple documents in batches
      default: false

    - name: batch_size
      type: number
      label: Batch Size
      showIf: "this.batch_inference === true"
      min: 1
      max: 100
      default: 10

Example 3: Data Taxonomy with Properties

taxons:
  - label: Invoice
    path: /invoice
    options:
      - name: validation_rules
        type: object
        label: Validation Rules
        groupOptions:
          - name: required
            type: boolean
            label: Required Field
            default: false

          - name: data_type
            type: select
            label: Expected Data Type
            possibleValues:
              - label: Any
                value: any
              - label: Text
                value: text
              - label: Number
                value: number
              - label: Date
                value: date
              - label: Currency
                value: currency

          - name: format_validation
            type: string
            label: Format Pattern (RegEx)
            description: Regular expression to validate format
            showIf: "this.validation_rules.data_type === 'text'"

          - name: min_value
            type: number
            label: Minimum Value
            showIf: "this.validation_rules.data_type === 'number' || this.validation_rules.data_type === 'currency'"

          - name: max_value
            type: number
            label: Maximum Value
            showIf: "this.validation_rules.data_type === 'number' || this.validation_rules.data_type === 'currency'"

      - name: extraction_hints
        type: object
        label: Extraction Hints
        properties:
          collapsible: true
        groupOptions:
          - name: typical_location
            type: select
            label: Typical Location in Document
            possibleValues:
              - label: Header
                value: header
              - label: Body
                value: body
              - label: Footer
                value: footer
              - label: Variable
                value: variable

          - name: nearby_keywords
            type: string
            label: Nearby Keywords
            description: Comma-separated list of keywords typically found near this field
            lines: 2

          - name: ocr_preprocessing
            type: select
            label: OCR Preprocessing
            possibleValues:
              - label: None
                value: none
              - label: Denoise
                value: denoise
              - label: Deskew
                value: deskew
              - label: Both
                value: both

Performance Optimization

Lazy Loading for Option Dropdowns

For options that fetch data from APIs (like cloud-model, document-lookup): Built-in features:

Caching: cloud-model implements 3-minute localStorage caching
Pagination: Results are paginated to avoid overwhelming the UI
Search: Live search filters results as users type

Best practices:

Use showIf to delay loading heavy options until needed
Group related API-backed options to batch requests
Set sensible page sizes (default: 50 for cloud models)

Conditional Loading Pattern

options:
  - name: use_cloud_models
    type: boolean
    label: Use Cloud-Based Models
    default: false

  # This option only loads API data when the checkbox is checked
  - name: cloud_model
    type: cloud-model
    label: Select Cloud Model
    showIf: "this.use_cloud_models === true"

Accessibility and User Experience

Clear Labeling

# Good
- name: max_retries
  label: Maximum Retry Attempts
  description: Number of times to retry failed operations before giving up. Set to 0 to disable retries.

# Poor
- name: max_retries
  label: Retries
  description: Retries

Progressive Disclosure

Start simple, reveal complexity only when needed:

options:
  # Simple options first
  - name: enabled
    type: boolean
    label: Enable Feature
    default: true

  # Advanced options hidden by default
  - name: advanced
    type: object
    label: Advanced Configuration
    properties:
      collapsible: true
      collapsed: true  # Start collapsed
    groupOptions:
      # Complex configuration here

Helpful Defaults

- name: timeout
  type: number
  label: Request Timeout (seconds)
  default: 30  # Sensible default for most use cases
  min: 1
  max: 300

- name: log_level
  type: select
  label: Log Level
  default: info  # Not debug, which is too noisy
  possibleValues:
    - label: Error
      value: error
    - label: Warning
      value: warning
    - label: Info
      value: info
    - label: Debug
      value: debug

Contextual Help

- name: batch_size
  type: number
  label: Batch Size
  description: Number of documents to process in each batch. Larger batches use more memory but can be faster. Recommended: 10-50 for most cases.
  default: 20
  min: 1
  max: 100

Testing and Debugging

Validating Option Definitions

def validate_options_schema(options):
    """Validate options follow best practices"""
    for opt in options:
        # Check required fields
        assert 'name' in opt, f"Option missing name: {opt}"
        assert 'type' in opt, f"Option {opt['name']} missing type"
        assert 'label' in opt, f"Option {opt['name']} missing label"
        assert 'description' in opt, f"Option {opt['name']} missing description"

        # Check for common mistakes
        if opt.get('required') and 'default' not in opt:
            print(f"Warning: {opt['name']} is required but has no default")

        if opt.get('type') == 'number':
            if 'min' not in opt or 'max' not in opt:
                print(f"Warning: {opt['name']} is a number but missing min/max")

        # Check showIf syntax
        if 'showIf' in opt:
            try:
                # Basic validation (in real code, parse the expression)
                assert 'this.' in opt['showIf'], f"showIf should reference 'this': {opt['showIf']}"
            except:
                print(f"Warning: Invalid showIf in {opt['name']}: {opt['showIf']}")

Testing Option Interactions

def test_option_visibility():
    """Test conditional visibility logic"""
    config = {
        'use_authentication': True,
        'username': 'admin'
    }

    # Test that dependent options appear
    assert should_show_option('password', config) == True

    # Test that options hide when dependency is false
    config['use_authentication'] = False
    assert should_show_option('password', config) == False

Migration and Versioning

Adding New Options (Backward Compatible)

# Version 1.0
options:
  - name: hostname
    type: string

# Version 1.1 - Add new option with default
options:
  - name: hostname
    type: string

  - name: port  # New option
    type: number
    default: 22  # Default ensures backward compatibility

Deprecating Options

options:
  - name: old_setting
    type: string
    label: Old Setting (Deprecated)
    description: "⚠️ DEPRECATED: Use 'new_setting' instead. This option will be removed in version 2.0."
    showIf: "false"  # Hide from UI but keep for backward compatibility

  - name: new_setting
    type: string
    label: New Setting
    description: Replacement for old_setting

Handling Migration in Code

class MyAssistant:
    def __init__(self, options):
        # Handle deprecated option with migration
        if 'old_setting' in options and 'new_setting' not in options:
            logger.warning("old_setting is deprecated. Migrating to new_setting.")
            options['new_setting'] = options['old_setting']

        # Use new option
        self.setting = options.get('new_setting')

Summary

Advanced options features enable:

Complex configurations through multi-level nesting
Dynamic behavior with conditional visibility and dependencies
User-friendly interfaces with progressive disclosure and clear guidance
Secure credential management with organization secrets integration
Performance optimization through lazy loading and caching
Backward compatibility through careful versioning and migration strategies

Master these patterns to create professional, flexible configuration interfaces that scale from simple to enterprise-complex requirements.

Options Architecture: Understanding the options system
Working with Options: Complete option type reference
Defining an Assistant: Using options in assistants

Introduction

Activity Plans

Task Templates

Data Definitions

Scripting

Scheduled Jobs

Intakes

Formulas

Project Templates

Data Forms

Working with Claude Code

Reference

Documentation Index

​Multi-Level Option Nesting

​Best Practices for Nesting

​Dynamic Option Dependencies

​Example: Conditional Chains

​Complex Conditional Logic

​Dynamic Possible Values

​Pattern: Filter Options Based on Selection

​Pattern: Hierarchical Selection

​Validation Patterns

​Built-in Validation

​Custom Validation in Code

​Password and Secret Management

​Organization Secrets Integration

​Tab-Based Organization

​Real-World Examples

​Example 1: SFTP Publishing Assistant

​Example 2: Machine Learning Module Configuration

​Example 3: Data Taxonomy with Properties

​Performance Optimization

​Lazy Loading for Option Dropdowns

​Conditional Loading Pattern

​Accessibility and User Experience

​Clear Labeling

​Progressive Disclosure

​Helpful Defaults

​Contextual Help

​Testing and Debugging

​Validating Option Definitions

​Testing Option Interactions

​Migration and Versioning

​Adding New Options (Backward Compatible)

​Deprecating Options

​Handling Migration in Code

​Summary

​Related Documentation