Deploying and Invoking Rule Chains

The visual editor (RuleGo-Editor) is optional. Rule chains can be deployed and executed entirely through file placement or the REST API, making it easy to integrate with third-party systems and CI/CD pipelines.

# How It Works

When RuleGo-Server starts, it scans the data directory to load rule chains:

data/
├── workflows/                          # User workspace
│   └── admin/                          # Username (default_username in config.conf)
│       ├── rules/                      # Rule chain files
│       │   ├── index                   # Index file (auto-generated)
│       │   ├── iot-router.json         # Each .json file = one rule chain
│       │   └── data-pipeline.json
│       ├── components/                 # Custom component configurations
│       └── runs/                       # Run logs
└── system/
    └── agents/                         # System agents
        └── _assistant/
            ├── _assistant.json
            └── AGENTS.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14

File name (without .json extension) becomes the rule chain ID
Each user has an independent workflows/{username}/rules/ directory
An index file (index) is auto-generated for fast listing queries

If you manually add or remove .json files while the server is running, you need to restart RuleGo-Server for changes to take effect. Alternatively, use the API for hot deployment without restarting.

# Method 1: Manual File Deployment

Place the rule chain JSON file directly into the rules directory. The file name becomes the rule chain ID.

# Step 1: Create the Rule Chain JSON File

For example, create data/workflows/admin/rules/iot-router.json — an IoT temperature filtering rule chain:

{
  "ruleChain": {
    "id": "iot-router",
    "name": "Temperature Filter and Push",
    "root": false,
    "debugMode": false,
    "disabled": false,
    "additionalInfo": {
      "description": "Filter specific devices, convert temperature, push to backend API"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [
      {
        "id": "s1",
        "type": "jsFilter",
        "name": "Device Filter",
        "configuration": {
          "jsScript": "return msg.deviceId=='sensor-001' || msg.deviceId=='sensor-002';"
        }
      },
      {
        "id": "s2",
        "type": "jsTransform",
        "name": "Temperature Convert",
        "configuration": {
          "jsScript": "msg.temperature = msg.temperature / 10;\nreturn {'msg':msg,'metadata':metadata,'msgType':msgType};"
        }
      },
      {
        "id": "s3",
        "type": "restApiCall",
        "name": "Push Data",
        "configuration": {
          "restEndpointUrlPattern": "http://backend-service:9099/api/iot/data",
          "requestMethod": "POST"
        }
      },
      {
        "id": "node_end",
        "type": "end",
        "name": "End"
      }
    ],
    "connections": [
      {"fromId": "s1", "toId": "s2", "type": "True"},
      {"fromId": "s2", "toId": "s3", "type": "Success"},
      {"fromId": "s3", "toId": "node_end", "type": "Success"},
      {"fromId": "s3", "toId": "node_end", "type": "Failure"},
      {"fromId": "s1", "toId": "node_end", "type": "False"}
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

The file name iot-router.json determines the rule chain ID as iot-router.

# Step 2: Delete the Index File

If the index file exists, delete it so RuleGo-Server rebuilds it on startup:

rm data/workflows/admin/rules/index

# Step 3: Start (or Restart) RuleGo-Server

./server -c="./config.conf"

On startup, you'll see the rule chain loaded:

[rule] admin number of rule chains loaded: 1

# Step 4: Execute the Rule Chain via API

curl -X POST http://localhost:9090/api/v1/rules/iot-router/execute/msgData \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"sensor-001","temperature":265}'

1
2
3

Synchronous execution waits for the rule chain to complete and returns the result.

# Method 2: REST API Deployment

Use the REST API to deploy rule chains without touching the file system. Changes take effect immediately without restarting.

# Deploy a Rule Chain

curl -X POST http://localhost:9090/api/v1/rules/iot-router \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d" \
  -d '{
  "ruleChain": {
    "id": "iot-router",
    "name": "Temperature Filter and Push",
    "root": false,
    "disabled": false,
    "additionalInfo": {
      "description": "Filter specific devices, convert temperature, push to backend API"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [
      {
        "id": "s1",
        "type": "jsFilter",
        "name": "Device Filter",
        "configuration": {
          "jsScript": "return msg.deviceId==\"sensor-001\" || msg.deviceId==\"sensor-002\";"
        }
      },
      {
        "id": "s2",
        "type": "jsTransform",
        "name": "Temperature Convert",
        "configuration": {
          "jsScript": "msg.temperature = msg.temperature / 10;\nreturn {\"msg\":msg,\"metadata\":metadata,\"msgType\":msgType};"
        }
      },
      {
        "id": "s3",
        "type": "restApiCall",
        "name": "Push Data",
        "configuration": {
          "restEndpointUrlPattern": "http://backend-service:9099/api/iot/data",
          "requestMethod": "POST"
        }
      },
      {
        "id": "node_end",
        "type": "end",
        "name": "End"
      }
    ],
    "connections": [
      {"fromId": "s1", "toId": "s2", "type": "True"},
      {"fromId": "s2", "toId": "s3", "type": "Success"},
      {"fromId": "s3", "toId": "node_end", "type": "Success"},
      {"fromId": "s3", "toId": "node_end", "type": "Failure"},
      {"fromId": "s1", "toId": "node_end", "type": "False"}
    ]
  }
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

The rule chain is saved to the file system and loaded into the engine immediately.

# List Rule Chains

curl http://localhost:9090/api/v1/rules \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

1
2

# Get a Rule Chain

curl http://localhost:9090/api/v1/rules/iot-router \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

1
2

# Deploy / Undeploy a Rule Chain

# Deploy (start)
curl -X POST http://localhost:9090/api/v1/rules/iot-router/operate/start \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

# Undeploy (stop)
curl -X POST http://localhost:9090/api/v1/rules/iot-router/operate/stop \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

1
2
3
4
5
6
7

# Delete a Rule Chain

curl -X DELETE http://localhost:9090/api/v1/rules/iot-router \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d"

1
2

# Executing Rule Chains

Once deployed, rule chains can be executed through multiple API endpoints:

# Synchronous Execution

Waits for the rule chain to complete and returns the result:

curl -X POST http://localhost:9090/api/v1/rules/iot-router/execute/msgData \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d" \
  -d '{"deviceId":"sensor-001","temperature":265,"humidity":60}'

1
2
3
4

# Asynchronous Execution

Fires and forgets — does not wait for the result. Suitable for high-throughput scenarios:

curl -X POST http://localhost:9090/api/v1/rules/iot-router/notify/msgData \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d" \
  -d '{"deviceId":"sensor-001","temperature":265,"humidity":60}'

1
2
3
4

# OpenAI Compatible Chat Endpoint

For AI Agent rule chains (containing ai/agent nodes), the OpenAI-compatible endpoint is automatically available:

POST /api/v1/rules/{ruleChainId}/v1/chat/completions

For Agent API calling examples, see Creating an Agent Tutorial.

# Authentication

When require_auth = true in config.conf, API requests need authentication. There are two methods:

# API Key

Configure an API key for the user in config.conf:

[users]
admin = admin,2af255ea5618467d914c67a8beeca31d

1
2

Then include it in requests:

# Via X-API-Key header
curl -H "X-API-Key: 2af255ea5618467d914c67a8beeca31d" ...

# Or via Authorization header
curl -H "Authorization: Bearer 2af255ea5618467d914c67a8beeca31d" ...

1
2
3
4
5

# JWT Token

# Login to get JWT token
TOKEN=$(curl -s -X POST http://localhost:9090/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.token')

# Use JWT token
curl -H "Authorization: Bearer $TOKEN" ...

1
2
3
4
5
6
7

When require_auth = false (default), all requests use the default user identity and no authentication is needed.

For detailed authentication and permissions, see Authentication and Authorization.

# CI/CD Integration Example

Deploy rule chains via CI/CD pipeline:

#!/bin/bash
# deploy-rule-chain.sh
RULE_CHAIN_ID=$1
JSON_FILE=$2
SERVER_URL="http://localhost:9090"
API_KEY="2af255ea5618467d914c67a8beeca31d"

# Deploy rule chain via API (hot update, no restart needed)
curl -X POST "${SERVER_URL}/api/v1/rules/${RULE_CHAIN_ID}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${API_KEY}" \
  -d @"${JSON_FILE}"

if [ $? -eq 0 ]; then
  echo "Rule chain ${RULE_CHAIN_ID} deployed successfully"
else
  echo "Failed to deploy rule chain ${RULE_CHAIN_ID}"
  exit 1
fi

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Usage:

./deploy-rule-chain.sh iot-router ./rule-chains/iot-router.json

# Directory Structure Reference

data/                                  # data_dir in config.conf
├── workflows/                         # User workspaces
│   └── {username}/                    # Per-user directory
│       ├── rules/                     # Rule chain JSON files
│       │   ├── index                  # Auto-generated index file
│       │   ├── chain-a.json           # Rule chain, ID = "chain-a"
│       │   └── chain-b.json           # Rule chain, ID = "chain-b"
│       ├── components/                # Custom component configs
│       └── runs/                      # Execution run logs
├── system/
│   └── agents/                        # System agents (deployed on startup)
│       └── {agent-id}/
│           ├── {agent-id}.json        # Agent rule chain JSON
│           └── AGENTS.md              # System prompt (optional)
├── skills/                            # Global skills (skill_path in config.conf)
├── js/                                # Global JS scripts (loaded as UDF)
└── plugins/                           # Global plugins (.so files)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# API Summary

Method	Path	Description
GET	`/api/v1/rules`	List rule chains
GET	`/api/v1/rules/{id}`	Get rule chain JSON
POST	`/api/v1/rules/{id}`	Save and deploy rule chain
DELETE	`/api/v1/rules/{id}`	Delete rule chain
POST	`/api/v1/rules/{id}/operate/start`	Deploy (start)
POST	`/api/v1/rules/{id}/operate/stop`	Undeploy (stop)
POST	`/api/v1/rules/{id}/execute/{msgType}`	Execute synchronously
POST	`/api/v1/rules/{id}/notify/{msgType}`	Execute asynchronously
POST	`/api/v1/rules/{id}/v1/chat/completions`	OpenAI compatible chat endpoint (AI agents only)

For complete API documentation, see REST API Reference.

Overview and Quick Start — Server overview and quick start
REST API Reference — Complete API documentation
Authentication and Authorization — JWT, API Key, permission system
Creating an Agent Tutorial — Visual agent creation with OpenAI API integration
AI Agent Framework Overview — Rule chain as agent concepts
Quick Start — Rule engine core concepts introduction

Edit this page on GitHub

Last Updated: 2026/05/30, 11:18:53

← Extension Development Visual Editor→