Working with Options - Kodexa Developer Portal

Options are a powerful feature in Kodexa that allow you to define configuration parameters for components, capture user input, and enable flexible customization of behavior. They provide a declarative way to create configuration interfaces without writing UI code.

Quick Start

Options appear throughout Kodexa in metadata definitions for assistants, models, taxonomies (data definitions), actions, and pipeline steps. Here’s a simple example:

options:
  - name: hostname
    type: string
    label: Server Hostname
    description: The hostname or IP address of the server
    required: true
  - name: port
    type: number
    label: Port Number
    description: The port number for the connection
    default: 22

This creates two configuration fields that users can fill in, and the values are passed to your code at runtime.

How Users Experience Options

Options create interactive configuration interfaces in several areas:

Assistant Configuration

When users add an assistant to their project, they can configure it through options you define:

Document Labeling Properties

When labeling documents, users can set properties on labels based on options defined in your taxonomy:

Options keep users focused on content while configuring the system to their needs.

Complete Option Types Reference

Kodexa supports 24+ option types organized into categories:

Basic Input Types

string / text

A text input field with optional multiline support.

options:
  - name: description
    type: string
    label: Description
    description: Enter a description
    placeholder: Type here...

Configuration:

lines (number): Number of lines for multiline input (default: 1)
password (boolean): Mask input as password field (default: false)
placeholder (string): Placeholder text when empty

Special Features:

Password fields integrate with organization secrets
Automatically switches between text input and textarea based on lines
Secret references stored as ${secret.secretName}

Example with multiline:

- name: notes
  type: string
  label: Notes
  description: Additional notes
  lines: 5
  placeholder: Enter detailed notes here

number

Numeric input with optional constraints.

options:
  - name: timeout
    type: number
    label: Timeout (seconds)
    description: Request timeout in seconds
    default: 30
    min: 1
    max: 300

Configuration:

min (number): Minimum allowed value
max (number): Maximum allowed value
step (number): Increment/decrement step (default: 1)

boolean

Checkbox or toggle switch for true/false values.

options:
  - name: enabled
    type: boolean
    label: Enable Feature
    description: Enable this feature
    default: false

Special Features:

View mode displays color-coded badges (green for true, gray for false)
Can specify custom labels for true/false states

select

Dropdown selection from predefined values.

options:
  - name: format
    type: select
    label: Output Format
    description: Choose the output format
    possibleValues:
      - label: JSON
        value: json
      - label: CSV
        value: csv
      - label: XML
        value: xml

Configuration:

possibleValues: Array of {label, value} objects
multiple (boolean): Allow multiple selections (default: false)

Code & Script Types

code

Full code editor with syntax highlighting.

options:
  - name: transform_script
    type: code
    label: Transform Script
    description: Python script to transform data
    language: python
    height: 400px
    default: |
      def transform(data):
          return data

Configuration:

language (string): Programming language for syntax highlighting (default: “python”)
height (string): Editor height (default: “300px”)

Special Features:

Full code editor experience
View mode renders as formatted <pre> block
Scrollable with max-height in view mode

script / pythonScript / javascript

Script input for code snippets.

options:
  - name: validation_script
    type: script
    label: Validation Script
    description: Script to validate data
    required: true
    default: |
      return {
        "valid": true
      }

Platform Resource Types

documentStore

Select a document store from the project.

options:
  - name: source_store
    type: documentStore
    label: Source Document Store
    description: Select the document store to process
    required: true

moduleStore

Select a module store from the project.

options:
  - name: module
    type: moduleStore
    label: Module Store
    description: Select the module to use
    required: true

tableStore

Select a data store from the project.

options:
  - name: output_store
    type: tableStore
    label: Output Data Store
    description: Select where to store extracted data
    required: true

taxonomyStore

Select a taxonomy (data definition) from the project.

options:
  - name: taxonomy
    type: taxonomyStore
    label: Data Definition
    description: Select the taxonomy to use
    required: true

workspace

Select a workspace from available workspaces.

options:
  - name: workspace
    type: workspace
    label: Workspace
    description: Select the target workspace
    required: true

Configuration:

showDescription (boolean): Show workspace description (default: true)

Document & Content Types

document

Search and select a specific document.

options:
  - name: template_document
    type: document
    label: Template Document
    description: Select a document to use as template
    required: true

Special Features:

Live search with autocomplete
Shows document path in results
Returns storeRef/documentId format
Configurable page size for results

data-form

Select a data form configuration from the project.

options:
  - name: form
    type: data-form
    label: Data Form
    description: Select the data form configuration
    required: true

Taxonomy & Label Types

taxon

Select a taxonomy element (data element).

options:
  - name: root_element
    type: taxon
    label: Root Data Element
    description: Select the root data element
    required: true

Configuration:

onlyGroups (boolean): Show only group taxons (default: false)
allowEmpty (boolean): Allow empty selection (default: true)
filterable (boolean): Enable filtering (default: true)

Special Features:

Hierarchical taxonomy navigation
Case-insensitive search across label and parent label
Custom dropdown item rendering

taxon_label

Select a taxonomy label.

options:
  - name: label_type
    type: taxon_label
    label: Label Type
    description: Select the label type to use
    required: true

taxon-lookup

Hierarchical taxonomy search with full path display.

options:
  - name: target_taxon
    type: taxon-lookup
    label: Target Data Element
    description: Search and select a data element
    taxonomyTypes:
      - CONTENT
      - MODEL
    showFullPath: true

Configuration:

taxonomyTypes (array): Types of taxonomies to include (default: [“CONTENT”, “MODEL”])
showFullPath (boolean): Show full taxonomy path (default: true)

Special Features:

Flattens taxonomy tree for search
Displays full path with parent labels
Chip-based display with custom styling
Excludes METADATA value paths

taxon_with_properties

Select a taxonomy element and configure its properties.

options:
  - name: field_config
    type: taxon_with_properties
    label: Field Configuration
    description: Select field and configure properties
    taxonomyTypes:
      - CONTENT
      - MODEL
    additionalOptions:
      - name: required
        type: boolean
        label: Required Field
      - name: validation
        type: select
        label: Validation Rule
        possibleValues:
          - label: None
            value: none
          - label: Numeric
            value: numeric

Configuration:

taxonomyTypes (array): Types of taxonomies to include
additionalOptions (array): Nested options for the selected taxon

Special Features:

Two-tier configuration (selection + properties)
Tabbed interface for additional options
Recursive option rendering
Stores both tag path and options object

Status Types

documentStatus

Select a document status from the project.

options:
  - name: target_status
    type: documentStatus
    label: Target Status
    description: Status to apply to documents
    required: true

attributeStatus

Select an attribute status from the project.

options:
  - name: attribute_status
    type: attributeStatus
    label: Attribute Status
    description: The attribute status to use
    required: true

Configuration:

clearable (boolean): Allow clearing the selection (default: true)

taskStatus

Select a task status from the project.

options:
  - name: task_status
    type: taskStatus
    label: Task Status
    description: Select the task status
    required: true

Special Features:

Color-coded badges with dynamic background colors
Contrasting text color based on background
Custom item rendering in dropdown

task-templates

Select a task template from the project.

options:
  - name: template
    type: task-templates
    label: Task Template
    description: Select a task template to apply
    required: true

Special Features:

Async data loading from project store
Reactive updates when templates change

Cloud AI Model Types

cloud-model

Select a cloud-based AI model.

options:
  - name: llm_model
    type: cloud-model
    label: Language Model
    description: Select the AI model to use
    showDescription: true
    showProvider: true

Configuration:

showDescription (boolean): Show model description as hint (default: true)
showProvider (boolean): Show provider in model name (default: true)

Special Features:

Local storage caching (3-minute expiry) to reduce API calls
Filters non-embedding active models
Combines model name + provider for display
Alphabetically sorted
Paginated results (pageSize: 50)

cloud-embedding

Select a cloud embedding model.

options:
  - name: embedding_model
    type: cloud-embedding
    label: Embedding Model
    description: Select the embedding model
    showDescription: true

Configuration:

showDescription (boolean): Show model description (default: true)

Special Features:

Filters for embedding models specifically
API integration with pagination
Dynamic loading state

Pipeline Types

pipeline

Configure an entire pipeline with steps.

options:
  - name: processing_pipeline
    type: pipeline
    label: Processing Pipeline
    description: Configure the document processing pipeline
    required: true

Special Features:

Visual pipeline editor
Drag-and-drop step ordering
Step configuration interface

pipelineModelOptions

Configure options for models within a pipeline.

options:
  - name: model_configs
    type: pipelineModelOptions
    label: Model Configurations
    description: Configure options for pipeline models
    showTabs: true

Configuration:

showTabs (boolean): Organize options in tabs (default: true)

Display Types

alert

Display an informational alert message.

options:
  - name: info_message
    type: alert
    label: Information
    markdown: |
      **Important:** This feature requires additional configuration.

      Please ensure you have set up the API credentials before proceeding.
    type: info

Configuration:

markdown (text): Markdown content to display
type (select): Alert style - info, warning, error, success

Special Features:

Renders markdown content
Dynamic styling based on alert type
Material Design icons

article

Display or reference a knowledge base article.

options:
  - name: help_article
    type: article
    label: Help Documentation
    articleId: "12345"
    slide: 1

Configuration:

articleId (string): ID of the article to display
text (text): Direct text content (alternative to articleId)
slide (number): Specific slide number to display

Special Features:

Integrates with knowledge base
Slide-based navigation support
Can display by ID or direct text

Specialized Types

chart

Select chart visualization type.

options:
  - name: visualization
    type: chart
    label: Chart Type
    description: Select how to visualize the data
    default: bar

Configuration:

type (select): Chart type - bar or pie

label

Select or enter a document label.

options:
  - name: classification
    type: label
    label: Document Label
    description: The label to apply
    multiple: false

Configuration:

multiple (boolean): Allow multiple label selection (default: false)

Special Features:

Fetches available labels from project
Custom item rendering
Supports future multi-select capability

simpleExpression

Enter a simple expression that can be evaluated.

options:
  - name: calculation
    type: simpleExpression
    label: Expression
    description: Enter a mathematical expression
    default: "3+5"

Special Features:

Single-line text input
Can be evaluated to compute a value

Working with Lists and Objects

Two of the most powerful option types are list and object, which allow you to define complex, structured data. Understanding how to use these properly is critical for building flexible configurations.

List Options

Lists allow you to define arrays of values, either simple strings or complex objects. Use type: list with the listType parameter to specify what kind of items the list contains.

String Lists

For lists of simple string values, use type: list with listType: string:

options:
  - name: allowed_prefixes
    type: list
    listType: string
    label: Allowed Prefixes
    description: List of allowed prefix strings
    default:
      - income_statement___
      - balance_sheet___
      - cash_flow___

Key points:

type: list indicates this is an array
listType: string specifies array items are strings
default should be an array of strings
Users can add/remove items through the UI

Resulting value in code:

allowed_prefixes = options.get('allowed_prefixes', [])
# ['income_statement___', 'balance_sheet___', 'cash_flow___']

Object Lists

For lists of complex objects, use type: list with listType: object and define the object structure using groupOptions:

options:
  - name: sections
    type: list
    listType: object
    label: Document Sections
    description: Configure sections to extract from documents
    default:
      - heading: Executive Summary
        required: true
        page_limit: 2
      - heading: Financial Data
        required: true
        page_limit: 5
    groupOptions:
      - name: heading
        type: string
        label: Section Heading
        description: The heading text to look for
        required: true

      - name: required
        type: boolean
        label: Required Section
        description: Whether this section must be present
        default: false

      - name: page_limit
        type: number
        label: Maximum Pages
        description: Maximum number of pages for this section
        min: 1
        max: 50
        default: 10

Key points:

type: list indicates this is an array
listType: object specifies array items are objects
groupOptions defines the schema for each object in the array
default should be an array of objects matching the schema
Each object in the default must conform to the groupOptions structure

Resulting value in code:

sections = options.get('sections', [])
# [
#   {'heading': 'Executive Summary', 'required': True, 'page_limit': 2},
#   {'heading': 'Financial Data', 'required': True, 'page_limit': 5}
# ]

for section in sections:
    heading = section.get('heading')
    is_required = section.get('required', False)
    page_limit = section.get('page_limit', 10)

Nested Lists in Objects

You can nest lists within objects for complex hierarchical structures:

options:
  - name: field_mappings
    type: list
    listType: object
    label: Field Mappings
    description: Define how to map source fields to target fields
    groupOptions:
      - name: source_field
        type: string
        label: Source Field Name
        required: true

      - name: target_field
        type: string
        label: Target Field Name
        required: true

      - name: transformations
        type: list
        listType: string
        label: Transformations
        description: List of transformations to apply
        default:
          - trim
          - lowercase

Resulting structure:

field_mappings = options.get('field_mappings', [])
# [
#   {
#     'source_field': 'CustomerName',
#     'target_field': 'customer_name',
#     'transformations': ['trim', 'lowercase', 'remove_special_chars']
#   }
# ]

Object Options

Objects allow you to group related options together. Use type: object with groupOptions to define the object’s properties.

Simple Object

options:
  - name: database_config
    type: object
    label: Database Configuration
    description: Database connection settings
    properties:
      collapsible: true
    groupOptions:
      - name: host
        type: string
        label: Database Host
        default: localhost
        required: true

      - name: port
        type: number
        label: Database Port
        default: 5432
        min: 1
        max: 65535

      - name: database_name
        type: string
        label: Database Name
        required: true

      - name: use_ssl
        type: boolean
        label: Use SSL Connection
        default: true

Key points:

type: object indicates this is a structured object
groupOptions defines the properties of the object
properties.collapsible: true makes the group collapsible in the UI
Each property in groupOptions follows the same option structure

Resulting value in code:

db_config = options.get('database_config', {})
host = db_config.get('host', 'localhost')
port = db_config.get('port', 5432)
database_name = db_config.get('database_name')
use_ssl = db_config.get('use_ssl', True)

Nested Objects

Objects can contain other objects for deep hierarchical structures:

options:
  - name: api_config
    type: object
    label: API Configuration
    groupOptions:
      - name: authentication
        type: object
        label: Authentication Settings
        groupOptions:
          - name: method
            type: select
            label: Auth Method
            possibleValues:
              - label: API Key
                value: api_key
              - label: OAuth 2.0
                value: oauth2

          - name: api_key
            type: string
            label: API Key
            password: true
            showIf: "this.api_config.authentication.method === 'api_key'"

          - name: oauth_settings
            type: object
            label: OAuth Settings
            showIf: "this.api_config.authentication.method === 'oauth2'"
            groupOptions:
              - name: client_id
                type: string
                label: Client ID
              - name: client_secret
                type: string
                label: Client Secret
                password: true

Best Practice: Limit nesting to 2-3 levels maximum for better user experience.

Default Value Structures

Default values must match the type structure:

Type	Default Value Structure	Example
`string`	Single string value	`default: "localhost"`
`text`	Single string (can be multiline)	`default: "Line 1\nLine 2"`
`number`	Single numeric value	`default: 5432`
`boolean`	Single boolean value	`default: true`
`select`	Single value from possibleValues	`default: "json"`
`list` (string)	Array of strings	`default: ["item1", "item2"]`
`list` (object)	Array of objects	`default: [{name: "val"}]`
`object`	Object with properties	`default: {host: "localhost"}`

Examples of Correct Default Values

# String - single value
- name: hostname
  type: string
  default: "localhost"

# Number - single value
- name: port
  type: number
  default: 5432

# Boolean - single value
- name: enabled
  type: boolean
  default: true

# Select - single value (must match a possibleValue)
- name: format
  type: select
  default: "json"
  possibleValues:
    - label: JSON
      value: json
    - label: CSV
      value: csv

# List of strings - array of strings
- name: tags
  type: list
  listType: string
  default:
    - production
    - verified
    - active

# List of objects - array of objects
- name: endpoints
  type: list
  listType: object
  default:
    - url: "https://api1.example.com"
      timeout: 30
    - url: "https://api2.example.com"
      timeout: 60
  groupOptions:
    - name: url
      type: string
    - name: timeout
      type: number

# Object - object with properties
- name: connection
  type: object
  default:
    host: "localhost"
    port: 5432
    ssl: true
  groupOptions:
    - name: host
      type: string
    - name: port
      type: number
    - name: ssl
      type: boolean

Anti-Patterns to Avoid

❌ DON’T: Use text fields for lists

# WRONG - Using multiline text for what should be a list
- name: allowed_values
  type: text
  lines: 5
  default: |
    - value1
    - value2
    - value3

✅ DO: Use proper list type

# CORRECT - Use type: list with listType
- name: allowed_values
  type: list
  listType: string
  default:
    - value1
    - value2
    - value3

Why this matters:

Lists provide structured data that’s easy to validate
Users get proper UI controls (add/remove buttons)
Code receives properly typed arrays, not strings that need parsing
Validation and error handling are automatic

❌ DON’T: Use text for structured data

# WRONG - Using text for object-like data
- name: config
  type: text
  default: |
    host: localhost
    port: 5432
    ssl: true

✅ DO: Use object type

# CORRECT - Use type: object with groupOptions
- name: config
  type: object
  groupOptions:
    - name: host
      type: string
      default: localhost
    - name: port
      type: number
      default: 5432
    - name: ssl
      type: boolean
      default: true

❌ DON’T: Mix default value structure with type

# WRONG - Default doesn't match list type
- name: items
  type: list
  listType: string
  default: "item1,item2,item3"  # Should be an array!

✅ DO: Match default structure to type

# CORRECT - Default is an array matching listType
- name: items
  type: list
  listType: string
  default:
    - item1
    - item2
    - item3

Real-World Example: Comprehensive Configuration

Here’s a complete example showing lists, objects, and nesting:

options:
  - name: processing_config
    type: object
    label: Processing Configuration
    groupOptions:
      # String list
      - name: allowed_file_types
        type: list
        listType: string
        label: Allowed File Types
        description: File extensions to process
        default:
          - pdf
          - docx
          - txt

      # Object with nested settings
      - name: validation_rules
        type: object
        label: Validation Rules
        properties:
          collapsible: true
        groupOptions:
          - name: min_file_size
            type: number
            label: Minimum File Size (KB)
            default: 1
            min: 0

          - name: max_file_size
            type: number
            label: Maximum File Size (MB)
            default: 50
            min: 1
            max: 500

      # List of objects
      - name: extraction_rules
        type: list
        listType: object
        label: Extraction Rules
        description: Define rules for extracting data
        default:
          - field_name: invoice_number
            pattern: "INV-\\d{6}"
            required: true
          - field_name: date
            pattern: "\\d{4}-\\d{2}-\\d{2}"
            required: true
        groupOptions:
          - name: field_name
            type: string
            label: Field Name
            required: true

          - name: pattern
            type: string
            label: Regex Pattern
            description: Regular expression pattern to match
            required: true

          - name: required
            type: boolean
            label: Required Field
            default: false

          - name: transformations
            type: list
            listType: string
            label: Transformations
            description: Post-extraction transformations
            default:
              - trim
              - uppercase

Accessing this in code:

def __init__(self, options):
    # Get the processing config object
    config = options.get('processing_config', {})

    # Get string list
    allowed_types = config.get('allowed_file_types', [])
    # ['pdf', 'docx', 'txt']

    # Get nested object
    validation = config.get('validation_rules', {})
    min_size = validation.get('min_file_size', 1)
    max_size = validation.get('max_file_size', 50)

    # Get object list
    extraction_rules = config.get('extraction_rules', [])
    for rule in extraction_rules:
        field = rule.get('field_name')
        pattern = rule.get('pattern')
        required = rule.get('required', False)
        transforms = rule.get('transformations', [])

        # Process each rule
        self.add_extraction_rule(field, pattern, required, transforms)

Option Groups

Options can be nested into groups for better organization and user experience:

options:
  - name: database_settings
    type: object
    label: Database Settings
    description: Configure database connection
    properties:
      collapsible: true
    groupOptions:
      - name: host
        type: string
        label: Database Host
        required: true
        default: "localhost"
      - name: port
        type: number
        label: Database Port
        default: 5432
      - name: database_name
        type: string
        label: Database Name
        required: true
      - name: use_ssl
        type: boolean
        label: Use SSL Connection
        default: true

Benefits of grouping:

Organizes related options together
Can be made collapsible to reduce UI clutter
Creates a hierarchy of configuration
Improves user experience for complex configurations

Properties for groups:

collapsible: true - Makes the group expandable/collapsible in the UI

Providing Possible Values

Limit user input to specific choices using possibleValues:

- name: output_format
  type: string
  label: Output Format
  description: The format of the exported data
  possibleValues:
    - label: JSON
      value: json
    - label: CSV
      value: csv
    - label: Excel Spreadsheet
      value: xlsx
    - label: XML
      value: xml
  default: json

This creates a dropdown with only these four options. Users cannot enter free-form text.

Conditional Visibility

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

options:
  - name: use_authentication
    type: boolean
    label: Require Authentication
    default: false

  - name: username
    type: string
    label: Username
    showIf: "this.use_authentication === true"

  - name: password
    type: string
    label: Password
    password: true
    showIf: "this.use_authentication === true"

The username and password options only appear when use_authentication is checked. showIf syntax:

JavaScript expression evaluated against current option values
Access other options via this.optionName
Supports boolean logic: &&, ||, !
Comparison operators: ===, !==, >, <, >=, <=

Complex example:

- name: deployment_type
  type: select
  label: Deployment Type
  possibleValues:
    - label: Cloud
      value: cloud
    - label: On-Premise
      value: on_premise

- name: cloud_region
  type: select
  label: Cloud Region
  showIf: "this.deployment_type === 'cloud'"
  possibleValues:
    - label: US East
      value: us_east
    - label: EU West
      value: eu_west

- name: server_address
  type: string
  label: Server Address
  showIf: "this.deployment_type === 'on_premise'"

Developer-Only Options

Hide advanced options from regular users:

- name: debug_logging
  type: boolean
  label: Enable Debug Logging
  description: Output detailed debug logs
  developerOnly: true
  default: false

Options marked with developerOnly: true are only visible to users who have enabled “Show Developer Tools” in their settings.

Feature Flags

Gate options behind feature flags:

- name: experimental_feature
  type: boolean
  label: Enable Experimental Feature
  description: Try out our new experimental feature
  featureFlag: experimental_features
  default: false

The option only appears if the specified feature flag is enabled for the project or organization.

Common Option Properties

All options support these common properties:

Property	Type	Description	Required
`name`	string	Unique identifier for the option	Yes
`type`	string	Option type (determines UI control)	Yes
`label`	string	User-facing display name	Yes
`description`	string	Help text explaining the option	Yes
`required`	boolean	Whether the value is mandatory	No (default: false)
`default`	any	Pre-filled default value	No
`possibleValues`	array	Allowed values (for select types)	No
`showIf`	string	JavaScript expression for conditional visibility	No
`developerOnly`	boolean	Only show to developers	No (default: false)
`featureFlag`	string	Feature flag that must be enabled	No
`properties`	object	Additional metadata (e.g., `collapsible`)	No

Best Practices

1. Provide Clear Labels and Descriptions

# 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: Max retries

2. Use Appropriate Types

Match the option type to the kind of data you’re collecting:

# Good
- name: port
  type: number
  min: 1
  max: 65535

# Poor
- name: port
  type: string

Important: For lists and structured data, use proper list and object types instead of text fields. See the Anti-Patterns section in “Working with Lists and Objects” for detailed examples.

3. Set Sensible Defaults

- name: timeout
  type: number
  label: Request Timeout (seconds)
  description: How long to wait for a response
  default: 30  # Most users won't need to change this
  min: 1
  max: 300

- name: connection_settings
  type: object
  label: Connection Settings
  properties:
    collapsible: true
  groupOptions:
    - name: host
      type: string
    - name: port
      type: number
    - name: timeout
      type: number

5. Use Required Judiciously

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

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

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

6. Leverage Conditional Visibility

Keep the UI clean by hiding irrelevant options:

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

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

- name: proxy_username
  type: string
  label: Proxy Username
  showIf: "this.use_proxy === true"

Using Options in Code

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)

        # Nested options from groups
        db_settings = options.get('database_settings', {})
        self.db_host = db_settings.get('host', 'localhost')
        self.db_port = db_settings.get('port', 5432)

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

Validation Example

def __init__(self, options):
    # Validate required options
    if 'api_key' not in options:
        raise ValueError("api_key is required")

    # Validate value ranges
    timeout = options.get('timeout', 30)
    if timeout < 1 or timeout > 300:
        raise ValueError("timeout must be between 1 and 300")

    self.api_key = options['api_key']
    self.timeout = timeout

Summary

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

Enable user configuration without writing UI code
Provide type-safe input with automatic validation
Create consistent experiences across all components
Capture custom information tailored to your needs
Keep configuration co-located with component definitions

The Options system supports 24+ different types, from simple text inputs to complex taxonomy selectors with nested properties. Master options to build flexible, user-configurable components that integrate seamlessly into the Kodexa platform.

Options Architecture: Deep dive into how the options system works
Advanced Options Features: Complex patterns and advanced techniques
Defining an Assistant: Using options in assistant definitions
Data Definitions: Using options to add properties to data elements

​Quick Start

​How Users Experience Options

​Assistant Configuration

​Document Labeling Properties

​Complete Option Types Reference

​Basic Input Types

​string / text

​number

​boolean

​select

​Code & Script Types

​code

​script / pythonScript / javascript

​Platform Resource Types

​documentStore

​moduleStore

​tableStore

​taxonomyStore

​workspace

​Document & Content Types

​document

​data-form

​Taxonomy & Label Types

​taxon

​taxon_label

​taxon-lookup

​taxon_with_properties

​Status Types

​documentStatus

​attributeStatus

​taskStatus

​task-templates

​Cloud AI Model Types

​cloud-model

​cloud-embedding

​Pipeline Types

​pipeline

​pipelineModelOptions

​Display Types

​alert

​article

​Specialized Types

​chart

​label

​simpleExpression

​Working with Lists and Objects

​List Options

​String Lists

​Object Lists

​Nested Lists in Objects

​Object Options

​Simple Object

​Nested Objects

​Default Value Structures

​Examples of Correct Default Values

​Anti-Patterns to Avoid

​❌ DON’T: Use text fields for lists

​✅ DO: Use proper list type

​❌ DON’T: Use text for structured data

​✅ DO: Use object type

​❌ DON’T: Mix default value structure with type

​✅ DO: Match default structure to type

​Real-World Example: Comprehensive Configuration

​Option Groups

​Providing Possible Values

​Conditional Visibility

​Developer-Only Options

​Feature Flags

​Common Option Properties

​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

​Using Options in Code

​Python (Assistants/Modules)

​Validation Example

​Summary

Quick Start

How Users Experience Options

Assistant Configuration

Document Labeling Properties

Complete Option Types Reference

Basic Input Types

string / text

number

boolean

select

Code & Script Types

code

script / pythonScript / javascript

Platform Resource Types

documentStore

moduleStore

tableStore

taxonomyStore

workspace

Document & Content Types

document

data-form

Taxonomy & Label Types

taxon

taxon_label

taxon-lookup

taxon_with_properties

Status Types

documentStatus

attributeStatus

taskStatus

task-templates

Cloud AI Model Types

cloud-model

cloud-embedding

Pipeline Types

pipeline

pipelineModelOptions

Display Types

alert

article

Specialized Types

chart

label

simpleExpression

Working with Lists and Objects

List Options

String Lists

Object Lists

Nested Lists in Objects

Object Options

Simple Object

Nested Objects

Default Value Structures

Examples of Correct Default Values

Anti-Patterns to Avoid

❌ DON’T: Use text fields for lists

✅ DO: Use proper list type

❌ DON’T: Use text for structured data

✅ DO: Use object type

❌ DON’T: Mix default value structure with type

✅ DO: Match default structure to type

Real-World Example: Comprehensive Configuration

Option Groups

Providing Possible Values

Conditional Visibility

Developer-Only Options

Feature Flags

Common Option Properties

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

Using Options in Code

Python (Assistants/Modules)

Validation Example

Summary