Skip to content

System Operations

System operations in Raikoo are built-in, programmatic operations that perform specific functions without requiring AI models. They handle tasks such as file manipulation, code execution, format conversion, and other utility functions. This guide provides a comprehensive overview of the available system operations and how to use them effectively.

Introduction to System Operations

Unlike AI-based operations that leverage language models for dynamic content generation, system operations perform defined, deterministic tasks. They are particularly useful for:

  • File format conversions
  • Code execution in various languages
  • Data manipulation and transformation
  • File system operations
  • Web content interaction
  • External process management

System operations are typically used alongside AI operations in workflows to handle technical tasks where precise, predictable execution is required.

Document Operations

Create PDF Operation

Converts markdown content to a PDF document.

Configuration:

  • Request: Path to the markdown content you want to convert to PDF
  • Parameters: None required
  • Output: The generated PDF document

Example Use Case: Creating professional documentation or reports from markdown content generated by AI operations.

PDF to Markdown

Converts a PDF document to Markdown format.

Configuration:

  • Request: A base64 encoded PDF document
  • Parameters: None required
  • Output: The markdown representation of the PDF content

Example Use Case: Extracting content from PDF documents for analysis or editing in workflows.

Word to Markdown

Converts a Word document (.docx) to Markdown format.

Configuration:

  • Request: A base64 encoded data URI representing a Word (.docx) file
  • Parameters:
    • File (optional): A workspace input reference to a Word document (takes precedence over request body)
  • Output: The markdown representation of the Word document

Example Use Case: Converting existing Word documents into a format that can be easily processed by AI operations.

Word to HTML

Converts a Word document (.docx) to HTML format.

Configuration:

  • Request: A base64 encoded data URI of a Word (.docx) document
  • Parameters: None required
  • Output: The HTML content generated from the Word document

Example Use Case: Converting Word documents into web-ready format for publishing or further processing.

DOCX Files from Markdown

While not a single operation, Raikoo provides functionality to generate Word (.docx) files from Markdown using the Execute JavaScript operation. The system offers two functions:

  1. raikoo.markdownToDocxAsync(): Simple conversion with no templating
  2. raikoo.renderDocxTemplateAsync(): DOCX template file + Markdown content

Both functions support placeholder variables using {{My_Placeholder_Name}} syntax.

Example Use Case: Generating customized reports, contracts, or other formal documents that require Word format.

Spreadsheet Operations

Sheet to CSV

Converts an Excel spreadsheet (XLSX) to CSV format.

Configuration:

  • Request: A data URI containing a spreadsheet file (XLSX)
  • Parameters:
    • File (optional): A workspace input reference to the spreadsheet file
    • SheetNameOrIndex (optional): Name or index of the sheet to convert
  • Output: A CSV string representation of the specified sheet

Example Use Case: Converting spreadsheet data to a simpler format for data processing or import into other systems.

Sheet to HTML

Converts an Excel spreadsheet (XLSX) to HTML format.

Configuration:

  • Request: A base64 encoded XLSX spreadsheet data URI
  • Parameters: None required
  • Output: The HTML representation of the input spreadsheet

Example Use Case: Creating web-viewable tables from spreadsheet data.

Sheet to JSON

Converts an Excel spreadsheet (XLSX) to JSON format.

Configuration:

  • Request: A base64 encoded XLSX spreadsheet provided as a data URI
  • Parameters: None required
  • Output: A JSON object representation of the provided spreadsheet

Example Use Case: Converting spreadsheet data to a structured format for easier processing in workflows.

Sheet to Markdown

Converts an Excel spreadsheet (XLSX) to Markdown table format.

Configuration:

  • Request: A base64 encoded data URI representing an XLSX spreadsheet file
  • Parameters: None required
  • Output: A markdown representation of the input spreadsheet

Example Use Case: Converting spreadsheet data to markdown tables for inclusion in documentation or reports.

HTML Operations

Get HTML

Retrieves the HTML content of a specified URL.

Configuration:

  • Request: The URL you wish to get the HTML of
  • Parameters:
    • Format (optional): Set to true to format the HTML using Prettier
  • Output: The HTML content of the specified URL

Example Use Case: Fetching web content for analysis or transformation in workflows.

HTML to Text

Extracts raw text content from HTML, discarding any tags or formatting.

Configuration:

  • Request: The HTML content you wish to convert
  • Parameters:
    • Format (optional): Set to true to format the extracted text using Prettier
  • Output: The extracted raw text from the input HTML

Example Use Case: Cleaning web content for processing by AI operations that work better with plain text.

Select HTML

Extracts specific HTML elements from an HTML document using CSS selectors.

Configuration:

  • Request: The CSS selector to use (optional if "Selector" parameter is set)
  • Parameters:
    • HTML: The HTML document to select from
    • Selector: The CSS selector to use (takes precedence over request)
    • Format (optional): Set to true to format the extracted HTML
  • Output: An array of HTML elements matching the specified selector

Example Use Case: Targeted extraction of specific content from web pages, such as article bodies, tables, or navigation elements.

Code Execution Operations

Execute JavaScript

Executes JavaScript or TypeScript code within the context of your workspace.

Configuration:

  • Request: JavaScript or TypeScript code to execute
  • Parameters: None required
  • Output: The result of the executed code as a string

Example Use Case: Performing custom data transformations, calculations, or integration with external services via APIs.

Execute Python

Executes Python code within the context of your workspace.

Configuration:

  • Request: Python code to execute
  • Parameters: None required
  • Output: The result of the last evaluated expression

Example Use Case: Leveraging Python libraries for data analysis, scientific computing, or machine learning tasks.

E2B: Execute Commands

Executes a series of POSIX commands within an isolated E2B sandbox Linux virtual machine.

Configuration:

  • Request: POSIX commands to be executed
  • Parameters:
    • Commands (required): The POSIX commands to execute
    • Timeout (optional): Maximum execution time in milliseconds
    • WorkspacePath (optional): Path to a workspace directory within the sandbox
  • Output: Standard output of the executed commands and workspace changes

Example Use Case: Running shell scripts or command-line tools in a controlled environment for tasks like data processing or system operations.

E2B: Execute Node.js

Executes Node.js code within an E2B sandbox environment.

Configuration:

  • Request: Node.js code to execute
  • Parameters:
    • Code (required): The Node.js code to execute
    • Timeout (optional): Execution timeout in milliseconds
    • NPMModules (optional): Comma-separated list of npm modules to install
    • WorkspacePath (optional): Working directory for execution
  • Output: Standard output from the Node.js process and workspace changes

Example Use Case: Executing Node.js scripts that require specific npm packages or complex JavaScript operations.

E2B: Execute Python

Executes Python code within an isolated E2B sandbox Linux virtual machine.

Configuration:

  • Request: Python code to execute
  • Parameters:
    • Code (required): The Python code to execute
    • Timeout (optional): Maximum execution time in milliseconds
    • PIPPackages (optional): Comma-separated list of pip packages to install
    • WorkspacePath (optional): Working directory for execution
  • Output: Standard output of the Python code and workspace changes

Example Use Case: Running Python scripts that require specific pip packages or isolation from the main environment.

File Operations

Delete File

Deletes a file from the workspace.

Configuration:

  • Request: The path to the file you wish to delete
  • Parameters: None required
  • Output: Success message or empty message if file doesn't exist

Example Use Case: Cleaning up temporary files or removing files that are no longer needed.

Merge Workspace Items

Combines multiple items from your workspace into a single, new item.

Configuration:

  • Parameters:
    • Separator: The separator to use between merged items
  • Output: A new workspace item containing the merged content

Example Use Case: Combining multiple generated text fragments into a single document or concatenating files.

Split Workspace Item

Divides a single workspace item into multiple items based on a specified separator.

Configuration:

  • Request: A workspace input reference to the document you wish to split
  • Parameters:
    • Separator: The separator used to split the item
  • Provided Parameters:
    • Current: The current split iteration (number)
  • Output: Multiple files, using the operation parameter "Current" to output multiple workspace files

Example Use Case: Breaking large documents into smaller sections for parallel processing.

Git Operations

Git Add

Adds files to the Git staging area.

Configuration:

  • Request: Files to add (optional if "All" parameter is true)
  • Parameters:
    • GitPath (required): Path to the Git repository
    • All (optional): If true, all changed files are added
  • Output: Updated workspace reflecting the staging changes

Example Use Case: Staging changes as part of a Git workflow automation.

Git Checkout

Checks out a specified branch or ref in a Git repository.

Configuration:

  • Request: The branch or ref to checkout
  • Parameters:
    • GitPath (required): Path to the Git repository
  • Output: Updated workspace files reflecting the checkout operation

Example Use Case: Switching branches in automated testing or deployment workflows.

Git Clone Repository

Clones a Git repository from a specified URL into the workspace.

Configuration:

  • Request: The URL of the Git repository to clone
  • Parameters:
    • GitPath (required): Path within the workspace for the cloned repository
  • Output: The cloned Git repository in the workspace

Example Use Case: Pulling external code or content repositories into a workflow for processing.

Git Commit

Commits changes in a Git repository.

Configuration:

  • Request: The commit message
  • Parameters:
    • GitPath (required): Path to the Git repository
    • Name (required): Author name for the commit
    • Email (required): Author email for the commit
    • Message (optional): Commit message (if not provided in request)
  • Output: Updated workspace reflecting the committed changes

Example Use Case: Automating version control as part of content generation or code modification workflows.

Git Init

Initializes a new Git repository in a specified directory.

Configuration:

  • Request: Path to initialize the repository (optional if GitPath is set)
  • Parameters:
    • GitPath (optional): Path to initialize the repository
    • DefaultBranch (optional): Name of the default branch (defaults to "main")
    • Bare (optional): Whether to create a bare repository
  • Output: Newly initialized Git repository

Example Use Case: Setting up version control for newly generated projects or content.

Git Pull

Pulls changes from a specified remote repository.

Configuration:

  • Request: Path to the Git repository
  • Parameters:
    • GitPath (required): Path to the Git repository
    • Remote (optional): Remote repository to pull from (defaults to "origin")
    • Branch (optional): Local branch to pull into (defaults to current branch)
    • RemoteBranch (optional): Remote branch to pull from
  • Output: Updated workspace reflecting the pulled changes

Example Use Case: Updating local content from a remote repository before processing.

Git Push

Pushes commits from a local Git repository to a remote repository.

Configuration:

  • Request: A workspace containing the Git repository
  • Parameters:
    • GitPath (required): Path to the Git repository
    • Remote (required): Name of the remote repository
    • Branch (required): Name of the local branch to push
    • RemoteBranch (optional): Name of the remote branch to push to
  • Output: Updated workspace reflecting any changes from the push operation

Example Use Case: Publishing generated content or code modifications to a remote repository.

Git Reset Hard

Performs a hard reset of a Git repository to the HEAD commit.

Configuration:

  • Request: Path to the Git repository
  • Parameters:
    • GitPath (required): Path to the Git repository
  • Output: Updated workspace reflecting the repository state after reset

Example Use Case: Reverting to a clean state when operations need to start fresh.

Workflow Control Operations

Run Workflow

Executes a specific workflow defined within a Workflow.

Configuration:

  • Request: The ID of the workflow to execute
  • Parameters:
    • Parallel (optional): Whether to run the workflow in parallel
    • Other parameters are passed as workflow parameters
  • Output: The nested workflow's results are added to the workspace

Example Use Case: Creating modular workflows where a main workflow calls sub-workflows for specific tasks.

Best Practices for System Operations

Error Handling

  • Validate Inputs: Ensure inputs match the expected format before processing
  • Handle Operation Failures: Add checks after system operations to handle potential errors
  • Provide Fallbacks: Where possible, include alternative paths if operations fail

Performance Optimization

  • Minimize Large File Operations: Be careful with operations that process large files
  • Use Parallel Execution: For independent operations, consider running them in parallel
  • Cache Results: For expensive operations, store results in the workspace for reuse

Security Considerations

  • Sandbox Execution: Use E2B operations for untrusted code or commands
  • Validate External Resources: When fetching from URLs, validate the source and content
  • Review Generated Code: Inspect code before executing it with Execute operations

Integration Strategies

  • Chain Operations: Use system operations to prepare data for AI operations and process their outputs
  • Create Utility Workflows: Build reusable workflows for common system tasks
  • Combine with Iterators: Use system operations within iterator operations for batch processing

Conclusion

System operations provide the technical backbone for your Raikoo workflows, handling file manipulations, code execution, and other programmatic tasks. By combining these operations with AI-based operations, you can create powerful, end-to-end solutions that leverage both deterministic processes and artificial intelligence.