System Operators

System operators are built-in, pre-configured operators on the GeniSpace platform, centrally managed by platform administrators, providing users with ready-to-use functionality. This document provides a detailed overview of the system operator concept, usage methods, and configuration management.

Concept Introduction

What Are System Operators

System operators are pre-configured by platform administrators in the backend, with the following characteristics:

• Pre-configured: Include complete feature definitions and default configurations
• Centrally Managed: Maintained and updated by platform administrators
• Ready to Use: Users can start using them immediately after enabling
• Configuration Separation: System configuration (hidden) is separated from user configuration (visible)

System Operators vs Custom Operators

Feature	System Operators	Custom Operators
Creation Method	Created by platform administrators	Created by users
Configuration Management	System configuration is hidden; user configuration is editable	Fully configurable
Maintenance and Updates	Centrally maintained and updated	Maintained by the user
Ease of Use	Low barrier; simply enable	High barrier; requires configuration
Customization Level	Limited customization	Fully customizable

Configuration Structure

Dual-Layer Configuration Design

System operators use a dual-layer configuration design:

{
  "systemConfiguration": {
    "schema": {
      "type": "object",
      "properties": {
        "apiKey": {
          "type": "string",
          "title": "API Key",
          "sensitive": true
        },
        "serverUrl": {
          "type": "string",
          "title": "Server URL",
          "default": "https://api.example.com"
        }
      }
    },
    "values": {
      "apiKey": "admin-configured-key",
      "serverUrl": "https://api.example.com"
    }
  },
  "configuration": {
    "schema": {
      "type": "object",
      "properties": {
        "timeout": {
          "type": "number",
          "title": "Timeout",
          "default": 30000,
          "minimum": 1000,
          "maximum": 60000
        },
        "enableCache": {
          "type": "boolean",
          "title": "Enable Caching",
          "default": true
        }
      }
    }
  }
}

Configuration Type Descriptions

systemConfiguration (System Configuration)

• Not visible to users
• Contains sensitive information (API keys, internal configurations, etc.)
• Configured and maintained by platform administrators
• Includes both schema and values sections

configuration (User Configuration)

• Visible and editable by users
• Contains user-customizable parameters
• Users fill in specific values when enabling the operator
• Contains only schema; values are filled in by the user

Operator Types

API Type Operators

Suitable for calling external REST API services:

{
  "executionType": "api",
  "systemConfiguration": {
    "schema": {
      "properties": {
        "baseUrl": {
          "type": "string",
          "title": "Base URL"
        },
        "authentication": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": ["bearer", "apikey", "basic"]
            },
            "credentials": {
              "type": "string",
              "sensitive": true
            }
          }
        }
      }
    }
  },
  "configuration": {
    "schema": {
      "properties": {
        "timeout": {"type": "number", "default": 30000},
        "retries": {"type": "number", "default": 3}
      }
    }
  }
}

Example System Operators:

• WeChat API Operator
• DingTalk API Operator
• SendGrid Email Operator
• Alibaba Cloud OSS Operator

Worker Type Operators

Suitable for background task processing:

{
  "executionType": "worker",
  "systemConfiguration": {
    "schema": {
      "properties": {
        "queueConfig": {
          "type": "object",
          "properties": {
            "maxConcurrency": {"type": "number"},
            "priority": {"type": "string"}
          }
        }
      }
    }
  },
  "configuration": {
    "schema": {
      "properties": {
        "batchSize": {"type": "number", "default": 100},
        "processingMode": {
          "type": "string", 
          "enum": ["parallel", "sequential"],
          "default": "parallel"
        }
      }
    }
  }
}

Example System Operators:

• Data Cleansing Operator
• File Conversion Operator
• Batch Processing Operator

MCP Type Operators

Suitable for Model Context Protocol integration:

{
  "executionType": "mcp",
  "systemConfiguration": {
    "schema": {
      "properties": {
        "serverConfig": {
          "type": "object",
          "properties": {
            "command": {"type": "string"},
            "args": {"type": "array"},
            "env": {"type": "object"}
          }
        }
      }
    }
  },
  "configuration": {
    "schema": {
      "properties": {
        "model": {
          "type": "string",
          "enum": ["gpt-4", "claude-3", "gemini-pro"],
          "default": "gpt-4"
        },
        "temperature": {
          "type": "number",
          "minimum": 0,
          "maximum": 2,
          "default": 0.7
        }
      }
    }
  }
}

Example System Operators:

• GPT Dialogue Operator
• Claude Analysis Operator
• Code Generation Operator

Container Type Operators

Suitable for containerized tasks:

{
  "executionType": "container",
  "systemConfiguration": {
    "schema": {
      "properties": {
        "image": {"type": "string"},
        "registry": {
          "type": "object",
          "properties": {
            "url": {"type": "string"},
            "username": {"type": "string"},
            "password": {"type": "string", "sensitive": true}
          }
        },
        "resources": {
          "type": "object",
          "properties": {
            "memory": {"type": "string", "default": "512Mi"},
            "cpu": {"type": "string", "default": "0.5"}
          }
        }
      }
    }
  },
  "configuration": {
    "schema": {
      "properties": {
        "environment": {
          "type": "object",
          "title": "Environment Variables"
        },
        "command": {
          "type": "string",
          "title": "Execution Command"
        }
      }
    }
  }
}

Example System Operators:

• Python Script Executor
• Database Backup Operator
• Image Processing Operator

Method Configuration

Method-Level System Configuration

Each method can also have its own system configuration:

{
  "methods": [
    {
      "name": "Send Email",
      "identifier": "send-email",
      "systemConfiguration": {
        "schema": {
          "properties": {
            "smtpConfig": {
              "type": "object",
              "properties": {
                "host": {"type": "string"},
                "port": {"type": "number"},
                "secure": {"type": "boolean"}
              }
            }
          }
        },
        "values": {
          "smtpConfig": {
            "host": "smtp.gmail.com",
            "port": 587,
            "secure": true
          }
        }
      },
      "configuration": {
        "schema": {
          "properties": {
            "template": {
              "type": "string",
              "enum": ["plain", "html"],
              "default": "html"
            },
            "priority": {
              "type": "string",
              "enum": ["low", "normal", "high"],
              "default": "normal"
            }
          }
        }
      }
    }
  ]
}

User Workflow

1. Browse System Operators

Browse available system operators in the operator marketplace:

{
  "systemOperators": [
    {
      "id": "wechat-api",
      "name": "WeChat API",
      "description": "Provides WeChat Official Account and Mini Program API interfaces",
      "category": "communication",
      "tags": ["WeChat", "API", "Communication"],
      "version": "1.2.0",
      "status": "ACTIVE"
    }
  ]
}

2. Enable System Operators

Select and enable the desired system operator:

POST /api/operators/system/{operatorId}/enable

Enabling creates a user operator instance:

{
  "userOperator": {
    "id": "user-wechat-001",
    "systemOperatorId": "wechat-api",
    "userId": "user123",
    "status": "ENABLED",
    "configuration": {
      "values": {
        "timeout": 30000,
        "enableCache": true
      }
    }
  }
}

3. Configure User Parameters

Fill in user-configurable parameters:

{
  "configuration": {
    "values": {
      "timeout": 45000,
      "enableCache": false,
      "retryCount": 5
    }
  }
}

4. Use in Workflows

Add the enabled operator to a workflow:

{
  "nodes": [
    {
      "id": "node1",
      "type": "operator",
      "operatorId": "user-wechat-001",
      "methodId": "send-message",
      "config": {
        "inputs": {
          "message": "Hello World",
          "to": "user456"
        }
      }
    }
  ]
}

Management and Maintenance

System Configuration Management

Administrators can manage system operator configurations through the backend:

Edit System Configuration

PUT /admin/operators/system/{operatorId}/system-configuration
Content-Type: application/json

{
  "systemConfiguration": {
    "schema": {
      "properties": {
        "newField": {
          "type": "string",
          "title": "New Field"
        }
      }
    },
    "values": {
      "newField": "default-value"
    }
  }
}

Update Operator Version

POST /admin/operators/system/{operatorId}/versions
Content-Type: application/json

{
  "version": "1.3.0",
  "changelog": "Added batch processing feature",
  "migration": {
    "required": false,
    "instructions": "Automatic upgrade, no manual action required"
  }
}

User Configuration Management

Users can manage the configuration of operators they have enabled:

Update User Configuration

PUT /api/operators/custom/{userOperatorId}/configuration
Content-Type: application/json

{
  "configuration": {
    "values": {
      "timeout": 60000,
      "enableCache": true
    }
  }
}

Method Configuration

PUT /api/operators/custom/{userOperatorId}/methods/{methodId}/configuration
Content-Type: application/json

{
  "configuration": {
    "values": {
      "template": "html",
      "priority": "high"
    }
  }
}

Monitoring and Diagnostics

Usage Statistics

View system operator usage statistics:

{
  "statistics": {
    "totalUsers": 1250,
    "activeUsers": 890,
    "totalExecutions": 156780,
    "successRate": 98.5,
    "avgResponseTime": 450
  }
}

Performance Monitoring

{
  "performance": {
    "qps": 125.5,
    "errorRate": 0.02,
    "p95ResponseTime": 800,
    "p99ResponseTime": 1200
  }
}

Error Diagnostics

{
  "errors": [
    {
      "type": "configuration_error",
      "message": "Invalid API key format",
      "count": 15,
      "lastOccurred": "2024-01-15T10:30:00Z"
    }
  ]
}

Best Practices

System Operator Design Principles

1. Configuration Separation: Clearly separate system and user configurations
2. Security First: Keep sensitive information in system configuration only
3. Backward Compatibility: Maintain interface compatibility during upgrades
4. Complete Documentation: Provide detailed usage documentation

User Usage Recommendations

1. Configure Appropriately: Adjust parameters based on actual needs
2. Update Regularly: Upgrade to new versions promptly
3. Monitor Usage: Pay attention to operator execution metrics
4. Backup Configuration: Back up important configurations promptly

Administrator Maintenance Guide

1. Version Management: Follow semantic versioning conventions
2. Change Notifications: Notify users in advance of major changes
3. Performance Optimization: Regularly optimize operator performance
4. Security Audits: Periodically review security configurations

FAQ

Q: What is the difference between system operators and custom operators?

A: System operators are pre-configured by the platform, and users can only configure a subset of parameters. Custom operators are entirely created and managed by users.

Q: Can I modify system operator system configurations?

A: No, system configurations can only be modified by platform administrators. Users can only modify the user configuration portion.

Q: Will system operator upgrades affect existing workflows?

A: Typically not. System operator upgrades maintain backward compatibility. If there are breaking changes, advance notice and migration guides will be provided.

Q: How do I know when a system operator has a new version?

A: The system displays update notifications in the operator list. You can also enable version update notifications in your settings.

Related Documentation

• Custom Operators - Learn how to create and manage custom operators
• Operator Overview - Basic operator concepts and types
• Workflow Integration - Using operators in workflows
• API Overview - API interface overview