Addons & Actions

Built-in Actions
Logic Actions
Addon Configuration
Custom Addons

Built-in Actions

The workflow engine includes several built-in actions. Built-in

Utility Actions

builtin::delay - Add delays to workflow execution

{
  "id": "wait-step",
  "action": "builtin::delay",
  "parameters": {
    "seconds": 30
  }
}

builtin::log - Log messages with different levels

{
  "id": "log-step",
  "action": "builtin::log",
  "parameters": {
    "message": "Processing completed: {{result.status}}",
    "level": "info"
  }
}

builtin::transform - Transform data using templates

{
  "id": "transform-step",
  "action": "builtin::transform",
  "parameters": {
    "input": "{{api-response.output.data}}",
    "rules": {
      "processed_items": "{{input.items.map(item => item.name)}}",
      "total_count": "{{input.items.length}}"
    }
  }
}

builtin::content_transform - Transform content between different types

The content_transform action provides comprehensive content transformation capabilities including encoding/decoding, format conversions, text operations, and data extractions.

Basic Usage

{
  "id": "content-transform-step",
  "action": "builtin::content_transform",
  "parameters": {
    "content": "{{payload.content}}",
    "from_type": "text/plain",
    "to_type": "base64"
  }
}

Available Transformations

Encoding Transformations:

From Type	To Type	Description
`base64`	`text/plain`	Decode base64 to text
`text/plain`	`base64`	Encode text to base64
`base64`	`application/octet-stream`	Decode base64 to binary
`application/octet-stream`	`base64`	Encode binary to base64
`hex`	`text/plain`	Decode hex to text
`text/plain`	`hex`	Encode text to hex
`hex`	`application/octet-stream`	Decode hex to binary
`application/octet-stream`	`hex`	Encode binary to hex
`text/plain`	`url-encoded`	URL encode text
`url-encoded`	`text/plain`	URL decode text
`text/plain`	`url-encoded-plus`	URL encode with + for spaces
`url-encoded-plus`	`text/plain`	URL decode with + for spaces

Format Conversions:

From Type	To Type	Description
`application/json`	`text/plain`	Convert JSON to formatted text
`text/plain`	`application/json`	Parse text to JSON
`text/csv`	`application/json`	Parse CSV to JSON array
`application/json`	`text/csv`	Convert JSON array to CSV
`text/html`	`text/plain`	Strip HTML tags

Binary/Text Conversions (UTF-8):

From Type	To Type	Description
`application/octet-stream`	`text/plain-utf8`	Decode binary as UTF-8 text
`text/plain`	`application/octet-stream-utf8`	Encode text as UTF-8 binary
`text/plain`	`ascii-only`	Strip non-ASCII characters

Text Transformations:

From Type	To Type	Description
`text/plain`	`lowercase`	Convert to lowercase
`text/plain`	`uppercase`	Convert to UPPERCASE
`text/plain`	`titlecase`	Convert To Title Case
`text/plain`	`capitalize`	Capitalize first letter
`text/plain`	`trimmed`	Trim whitespace from both ends
`text/plain`	`ltrimmed`	Trim whitespace from left
`text/plain`	`rtrimmed`	Trim whitespace from right

Newline Normalization:

From Type	To Type	Description
`text/plain`	`unix-newlines`	Convert to Unix newlines (LF)
`text/plain`	`windows-newlines`	Convert to Windows newlines (CRLF)
`text/plain`	`mac-newlines`	Convert to Mac newlines (CR)

Data Extraction:

From Type	To Type	Description
`text/plain`	`numbers`	Extract all numbers
`text/plain`	`emails`	Extract email addresses
`text/plain`	`urls`	Extract URLs

Date/Time Conversions:

From Type	To Type	Description
`timestamp`	`iso8601`	Convert Unix timestamp to ISO 8601
`iso8601`	`timestamp`	Convert ISO 8601 to Unix timestamp

Examples

Base64 Encoding:

{
  "id": "encode-base64",
  "action": "builtin::content_transform",
  "parameters": {
    "content": "Hello World",
    "from_type": "text/plain",
    "to_type": "base64"
  }
}

CSV to JSON:

{
  "id": "csv-to-json",
  "action": "builtin::content_transform",
  "parameters": {
    "content": "name,age\nJohn,30\nJane,25",
    "from_type": "text/csv",
    "to_type": "application/json"
  }
}

Extract Emails:

{
  "id": "extract-emails",
  "action": "builtin::content_transform",
  "parameters": {
    "content": "Contact us at support@example.com or sales@example.com",
    "from_type": "text/plain",
    "to_type": "emails"
  }
}

Timestamp Conversion:

{
  "id": "timestamp-to-iso",
  "action": "builtin::content_transform",
  "parameters": {
    "content": "1609459200",
    "from_type": "timestamp",
    "to_type": "iso8601"
  }
}

URL Encoding:

{
  "id": "url-encode",
  "action": "builtin::content_transform",
  "parameters": {
    "content": "hello world & stuff",
    "from_type": "text/plain",
    "to_type": "url-encoded"
  }
}

Binary to UTF-8 Text:

{
  "id": "decode-binary",
  "action": "builtin::content_transform",
  "parameters": {
    "content": "{{binary_data}}",
    "from_type": "application/octet-stream",
    "to_type": "text/plain-utf8"
  }
}

Strip Non-ASCII Characters:

{
  "id": "ascii-only",
  "action": "builtin::content_transform",
  "parameters": {
    "content": "Hello 世界 World",
    "from_type": "text/plain",
    "to_type": "ascii-only"
  }
}

Note: HTML tag removal uses simple regex and may not handle complex HTML with nested tags or embedded scripts. For production use with complex HTML, consider using a dedicated HTML parsing addon.

builtin::content_validate - Validate content against its declared type

{
  "id": "content-validate-step",
  "action": "builtin::content_validate",
  "parameters": {
    "content": "{{payload.content}}",
    "type": "{{payload.type}}"
  }
}

builtin::chunk_text - Chunk text for RAG and embedding workflows

Split text into chunks using LlamaIndex SentenceSplitter, ideal for preparing documents for embeddings and RAG workflows.

{
  "id": "chunk-document",
  "action": "builtin::chunk_text",
  "parameters": {
    "text": "{{document.content}}",
    "chunk_size": 1024,
    "chunk_overlap": 200,
    "separator": " ",
    "paragraph_separator": "\n\n\n"
  }
}

Parameters:

text (required): The text content to chunk
chunk_size (optional, default: 1024): Maximum size of each chunk in characters
chunk_overlap (optional, default: 200): Number of characters to overlap between chunks
separator (optional, default: " "): Word separator for splitting
paragraph_separator (optional, default: "\n\n\n"): Paragraph boundary separator

Returns:

{
  "chunks": ["chunk1", "chunk2", "..."],
  "count": 5,
  "chunk_size": 1024,
  "chunk_overlap": 200,
  "success": true
}

Logic Actions

logic::if - Conditional logic evaluation

{
  "id": "conditional-step",
  "action": "logic::if",
  "parameters": {
    "condition": "{{user.premium}} == true",
    "then": "premium-processing",
    "else": "standard-processing"
  }
}

logic::loop - Iterate over collections

{
  "id": "loop-step",
  "action": "logic::loop",
  "parameters": {
    "items": "{{data.collection}}"
  }
}

Loop Variables Available:

{{loop_item}} - Current item being processed
{{loop_index}} - Current iteration index (0-based)

Loop Example:

{
  "id": "process-items",
  "action": "logic::loop",
  "parameters": {
    "items": ["item1", "item2", "item3"]
  }
}

Multiple Addon Instances

You can configure multiple instances of the same addon type with different configurations:

{
  "addons": [
    {
      "id": "openai-gpt4",
      "type": "openai",
      "name": "OpenAI GPT-4",
      "enabled": true,
      "config": {
        "model": "gpt-4",
        "temperature": 0.7
      },
      "secrets": {
        "api_key": "OPENAI_API_KEY"
      }
    },
    {
      "id": "openai-gpt35",
      "type": "openai",
      "name": "OpenAI GPT-3.5", 
      "enabled": true,
      "config": {
        "model": "gpt-3.5-turbo",
        "temperature": 0.3
      },
      "secrets": {
        "api_key": "OPENAI_API_KEY"
      }
    }
  ]
}

Using Addon Actions

Use the addon ID in action names to choose which addon instance to use:

{
  "id": "generate-creative-text",
  "action": "openai-gpt4::completion",
  "parameters": {
    "prompt": "Write a creative story about {{topic}}",
    "max_tokens": 500
  }
},
{
  "id": "generate-summary",
  "action": "openai-gpt35::completion", 
  "parameters": {
    "prompt": "Summarize: {{content}}",
    "max_tokens": 100
  }
}

Backward Compatibility

Legacy addon-type::action format still works but shows deprecation warnings:

{
  "id": "legacy-action",
  "action": "openai::completion"
}

Warning: If multiple instances of the same type exist, legacy format will use the last loaded instance.

Addon Configuration

Configure addons with secrets management:

{
  "addons": [
    {
      "id": "database-addon",
      "type": "postgres",
      "enabled": true,
      "config": {
        "host": "localhost",
        "port": 5432,
        "database": "myapp"
      },
      "secrets": {
        "username": "DB_USER",
        "password": "DB_PASSWORD",
        "api_key": "POSTGRES_API_KEY"
      }
    }
  ]
}

Set up environment variables or .env file, we will also make available differents vault later with a flow that will try various source to get your secrets safely.

# .env file
DB_USER=postgres_user
DB_PASSWORD=secure_password
POSTGRES_API_KEY=your_api_key_here

Custom Addons

To create custom addons, refer to the Rooms Template Package

Table of Contents​

Built-in Actions​

Utility Actions​

Basic Usage​

Available Transformations​

Examples​

Logic Actions​

Multiple Addon Instances​

Using Addon Actions​

Backward Compatibility​

Addon Configuration​

Custom Addons​

Table of Contents