Options Architecture - Kodexa Developer Portal

The Options system is a foundational feature in Kodexa that enables developers to define flexible, type-safe configuration interfaces throughout the platform. Options provide a declarative way to capture custom information from users while maintaining consistency across all components.

What Are Options?

Options are configuration parameters that allow you to:

Capture user input in a structured, validated way
Define custom properties for components (assistants, modules, steps)
Add configurable fields to taxonomies (data elements)
Create dynamic form interfaces without writing UI code
Enable users to configure components directly in the platform UI

Think of options as a schema language for user configuration - you describe what you need, and Kodexa automatically generates the appropriate UI controls and validation.

The Options Flow

Developer defines options → Platform generates UI → User configures → Values passed to code
     (in metadata)           (automatically)         (in UI)          (at runtime)

Example: Simple Assistant with Options

Developer defines (in assistant metadata):

options:
  - name: hostname
    type: string
    label: SFTP Hostname
    description: The hostname of the SFTP server
    required: true
  - name: port
    type: number
    label: Port
    description: Port number for SFTP connection
    default: 22

Platform generates: Text input field + numeric input field with validation User configures: Enters “sftp.example.com” and “2222” Code receives: {'hostname': 'sftp.example.com', 'port': 2222}

Where Are Options Used?

Options appear throughout the Kodexa platform:

1. Assistants

Define configuration parameters for assistant behavior:

- slug: data-publisher
  type: assistant
  options:
    - name: schedule
      type: string
      label: Publication Schedule
    - name: format
      type: select
      possibleValues:
        - label: JSON
          value: json
        - label: CSV
          value: csv

2. Modules

Configure inference and training behavior:

metadata:
  type: module
  inferOptions:
    - name: confidence_threshold
      type: number
      label: Confidence Threshold
      default: 0.85
      description: Minimum confidence score for predictions
  trainOptions:
    - name: epochs
      type: number
      label: Training Epochs
      default: 10

3. Taxonomies (Data Definitions)

Add custom properties to data elements:

taxons:
  - label: Invoice
    path: /invoice
    options:
      - name: required
        type: boolean
        label: Required Field
        default: false
      - name: validation_rule
        type: select
        label: Validation Rule
        possibleValues:
          - label: None
            value: none
          - label: Numeric Only
            value: numeric
          - label: Date Format
            value: date

When users label documents, they can set these properties on each labeled instance.

4. Actions

Configure executable actions:

- slug: send-email
  type: action
  options:
    - name: recipient
      type: string
      label: Email Recipient
      required: true
    - name: subject
      type: string
      label: Subject Line

5. Pipeline Steps

Configure processing steps in pipelines:

steps:
  - stepRef: normalize-text
    options:
      - name: lowercase
        type: boolean
        default: true
      - name: remove_punctuation
        type: boolean
        default: false

Core Option Structure

Every option has this basic structure:

- name: option_name           # Key used to access the value in code
  type: string                # Option type (determines UI control)
  label: Display Name         # Shown to users
  description: Help text      # Explains what this option does
  required: false             # Whether value is mandatory
  default: default_value      # Pre-filled value

Required Fields

name: Unique identifier for the option (used in code to access the value)
type: Determines which UI control to render and how to validate input
label: User-facing display name
description: Help text explaining the purpose and usage

Optional Fields

required: Boolean indicating if the option must be set (default: false)
default: Pre-filled value shown to users
possibleValues: Array of allowed values (for dropdowns/selects)
showIf: Conditional visibility based on other option values
developerOnly: Only show to users with developer privileges
featureFlag: Gate option behind a feature flag
properties: Additional metadata for option behavior (e.g., collapsible: true)

Option Types Overview

Kodexa supports 24+ option types organized into categories:

Basic Input Types

string / text: Single or multi-line text input
number: Numeric input with optional min/max constraints
boolean: Checkbox or toggle switch
select: Dropdown selection from predefined values

Code & Script Types

code: Full code editor with syntax highlighting
script: Script input (supports multiple languages)

Platform-Specific Types

documentStore: Select a document store
moduleStore: Select a module store
tableStore: Select a data store
taxonomyStore: Select a taxonomy (data definition)
document: Search and select a specific document
workspace: Select a workspace

Taxonomy Types

taxon: Select a taxonomy element
taxon_label: Select a taxonomy label
taxon_with_properties: Select taxonomy + configure properties
taxon-lookup: Hierarchical taxonomy search

Status & State Types

documentStatus: Select document status
attributeStatus: Select attribute status
taskStatus: Select task status

Advanced Types

cloud-model: Select cloud-based AI model (with caching)
cloud-embedding: Select embedding model
pipeline: Configure entire pipeline
pipelineModuleOptions: Configure multiple modules in pipeline
data-form: Select data form configuration

Display Types

alert: Display informational message
article: Embed knowledge base article

Nested Options (Option Groups)

Options can be nested into groups for better organization:

options:
  - name: connection_settings
    type: object
    label: Connection Settings
    description: Database connection configuration
    properties:
      collapsible: true  # Can be collapsed in UI
    groupOptions:
      - name: host
        type: string
        label: Database Host
        required: true
      - name: port
        type: number
        label: Database Port
        default: 5432
      - name: use_ssl
        type: boolean
        label: Use SSL
        default: true

This creates a collapsible section containing three related options.

Conditional Visibility

Use showIf to show/hide options based on other values:

options:
  - name: use_custom_endpoint
    type: boolean
    label: Use Custom Endpoint
    default: false

  - name: endpoint_url
    type: string
    label: Custom Endpoint URL
    showIf: "this.use_custom_endpoint === true"
    # Only shown when use_custom_endpoint is checked

The showIf field accepts JavaScript expressions evaluated against the current option values.

Possible Values (Constrained Choices)

Limit user input to predefined choices:

- name: output_format
  type: string
  label: Output Format
  description: Format for exported data
  possibleValues:
    - label: JSON
      value: json
    - label: CSV
      value: csv
    - label: XML
      value: xml

Renders as a dropdown with only these three options.

Developer-Only Options

Hide advanced options from regular users:

- name: debug_mode
  type: boolean
  label: Enable Debug Logging
  developerOnly: true  # Only visible to users with "Show Developer Tools" enabled

Accessing Option Values in Code

In Python (Assistants/Modules)

class MyAssistant:
    def __init__(self, options):
        # Options are passed as a dictionary
        self.hostname = options.get('hostname')
        self.port = options.get('port', 22)  # With default
        self.use_ssl = options.get('use_ssl', False)

    def run(self, context):
        # Use the configured values
        connection = connect(
            host=self.hostname,
            port=self.port,
            ssl=self.use_ssl
        )

In Metadata (Other Components)

Options can reference each other or be used in expressions:

pipeline:
  steps:
    - stepRef: process-documents
      options:
        input_store: ${parent.options.source_store}  # Reference parent option

Best Practices

1. Provide Clear Labels and Descriptions

# Good
- name: retry_count
  label: Maximum Retry Attempts
  description: Number of times to retry failed operations before giving up

# Poor
- name: retry_count
  label: Retry Count
  description: Retries

2. Use Appropriate Types

# Good - type matches the data
- name: port
  type: number

# Poor - storing number as string
- name: port
  type: string

3. Set Sensible Defaults

- name: timeout
  type: number
  label: Request Timeout (seconds)
  default: 30  # Most users won't need to change this

- name: email_settings
  type: object
  label: Email Configuration
  groupOptions:
    - name: smtp_host
      type: string
    - name: smtp_port
      type: number
    - name: use_tls
      type: boolean

5. Use `required` Judiciously

Only mark options as required if the component truly cannot function without them.

- name: api_key
  type: string
  label: API Key
  required: true  # Component cannot work without this

- name: log_level
  type: select
  label: Log Level
  required: false  # Has a reasonable default
  default: info

6. Leverage Conditional Visibility

Keep the UI clean by hiding irrelevant options:

- name: use_proxy
  type: boolean
  label: Use HTTP Proxy

- name: proxy_url
  type: string
  label: Proxy URL
  showIf: "this.use_proxy === true"

- name: proxy_auth
  type: boolean
  label: Proxy Requires Authentication
  showIf: "this.use_proxy === true"

How Options Enable Custom Information Capture

The Options system is powerful because it provides declarative configuration:

No UI Code Required: Define options in YAML, get a UI automatically
Type Safety: Platform validates input based on option type
Consistency: Same option types look and behave the same everywhere
Discoverability: Users see configuration options in context
Versioning: Options are part of component metadata (versioned with the component)

Example: Custom Data Capture

Suppose you’re building a custom invoice extraction module. You want users to configure:

Which fields are required
Validation rules per field
Output format preferences

Without options, you’d need to:

Build a custom UI
Handle validation
Store configuration somewhere
Pass configuration to your module code

With options, you simply:

metadata:
  type: module
  inferOptions:
    - name: required_fields
      type: taxon_with_properties
      label: Required Fields
      description: Mark which invoice fields must be present

    - name: validation_rules
      type: object
      label: Validation Rules
      groupOptions:
        - name: validate_dates
          type: boolean
          default: true
        - name: validate_amounts
          type: boolean
          default: true

    - name: output_format
      type: select
      label: Output Format
      possibleValues:
        - label: JSON
          value: json
        - label: Structured CSV
          value: csv

Kodexa generates the UI, validates input, and passes the configuration to your module.

Next Steps

Working with Options: Complete reference of all option types
Advanced Options Features: Deep dive into grouping, conditionals, and complex patterns
Defining an Assistant: See options in action for assistants

Summary

The Options system is Kodexa’s declarative configuration language. By defining options in metadata, you:

Enable users to configure your components without code changes
Provide a consistent, validated configuration experience
Capture custom information tailored to your use case
Keep configuration co-located with component definitions

Options turn configuration from a UI development task into a metadata declaration, allowing you to focus on building functionality rather than forms.

​What Are Options?

​The Options Flow

​Example: Simple Assistant with Options

​Where Are Options Used?

​1. Assistants

​2. Modules

​3. Taxonomies (Data Definitions)

​4. Actions

​5. Pipeline Steps

​Core Option Structure

​Required Fields

​Optional Fields

​Option Types Overview

​Basic Input Types

​Code & Script Types

​Platform-Specific Types

​Taxonomy Types

​Status & State Types

​Advanced Types

​Display Types

​Nested Options (Option Groups)

​Conditional Visibility

​Possible Values (Constrained Choices)

​Developer-Only Options

​Accessing Option Values in Code

​In Python (Assistants/Modules)

​In Metadata (Other Components)

​Best Practices

​1. Provide Clear Labels and Descriptions

​2. Use Appropriate Types

​3. Set Sensible Defaults

​4. Group Related Options

​5. Use required Judiciously

​6. Leverage Conditional Visibility

​How Options Enable Custom Information Capture

​Example: Custom Data Capture

​Next Steps

​Summary