User Guide - Rule Engine

Overview

The Beas Rule Engine is a high-performance rule evaluation system that allows you to define, manage, and execute complex business rules using MVEL (MVFLEX Expression Language). It provides a RESTful API for rule evaluation, comprehensive caching mechanisms, and robust security features.

Key Capabilities

Dynamic Rule Execution: Execute rules on-the-fly with parameterized inputs
Caching System: Multi-level caching for improved performance
Security: OAuth2 integration with Keycloak for authentication
Scalability: Asynchronous processing and MongoDB persistence
Extensibility: Plugin-based architecture for custom functions and helpers

Features

Core Features

🚀 High Performance: Optimized rule compilation and execution
🔄 Caching: Intelligent caching of compiled rules and variables
🔒 Security: OAuth2 authentication and authorization

📊 Monitoring: Comprehensive logging and metrics
🔧 Flexibility: Support for custom functions and helper classes
⚡ Scalability: Horizontal scaling capabilities

Technical Features

Java 17: Latest LTS version with modern language features
Spring Boot 3.3.4: Latest stable Spring Boot version
MongoDB: NoSQL database for flexible data storage

MVEL: Powerful expression language for rule definition
Swagger/OpenAPI: Interactive API documentation
Docker: Containerized deployment support

Architecture

The Beas Rule Engine follows a layered architecture pattern:

System Architecture Layers

Presentation Layer

Controllers, DTOs, Validation

Business Layer

Services, Engine, Cache

Data Layer

Repositories, Models, MongoDB

Core Components

Controllers: REST API endpoints for rule operations
Services: Business logic and rule management
Engine: Rule compilation and execution engine
Cache: Multi-level caching system
Models: Data entities and DTOs
Repositories: Data access layer

Prerequisites

Required Software

Java 17 or higher
Maven 3.6 or higher
MongoDB 5.0 or higher
Keycloak (for authentication - optional for development)

System Requirements:

Memory: Minimum 2GB RAM, Recommended 4GB+
Storage: Minimum 1GB free space
Network: Port 8070 available (configurable)

Installation

1. Clone the Repository

git clone https://github.com/BEAS-Software-Solutions/BEASRE.git
cd BeasRuleEngine

2. Build the Project

mvn clean install

3. Run the Application

Option A: Using Maven

mvn spring-boot:run

Option B: Using JAR

java -jar target/rule-engine-0.0.1.jar

Option C: Using Docker

docker build -t beas-rule-engine .
docker run -p 8070:8070 beas-rule-engine

Configuration

Application Properties

The main configuration file is located at src/main/resources/application.yaml:

# Rule Engine Configuration
rule:
  container:
    name: general

# Cryptography Configuration
cryptography:
  key: "your-encryption-key"
  iv: "your-iv-vector"

# Spring Configuration
spring:
  application:
    name: beasre
  data:
    mongodb:
      host: localhost
      port: 27017
      database: beasre
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://keycloak.beassolution.com/realms/beas-rule-engine

# Server Configuration
server:
  port: 8070
  servlet:
    context-path: /beasre/v1

Environment Variables

You can override configuration using environment variables:

export SPRING_DATA_MONGODB_HOST=your-mongodb-host
export SPRING_DATA_MONGODB_PORT=27017
export SERVER_PORT=8070
export CRYPTOGRAPHY_KEY=your-key

Usage

Starting the Application

After installation, the application will be available at:

Base URL: http://localhost:8070/beasre/v1
Swagger UI: http://localhost:8070/beasre/v1/swagger-ui.html
Health Check: http://localhost:8070/beasre/v1/actuator/health

Rule Evaluation

Basic Rule Evaluation:

curl -X POST "http://localhost:8070/beasre/v1/rule-engine/evaluate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-jwt-token" \
  -d '{
    "ruleName": "discount-rule",
    "parameters": {
      "orderAmount": 1000,
      "customerType": "PREMIUM"
    },
    "payload": {
      "orderId": "12345",
      "items": ["item1", "item2"]
    }
  }'

API Documentation

Interactive Documentation

Access the interactive API documentation through Swagger UI:

Swagger UI: http://localhost:8070/beasre/v1/swagger-ui.html
OpenAPI JSON: http://localhost:8070/beasre/v1/v3/api-docs

For detailed API documentation, see our API Documentation Guide.

Testing

Running Tests

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=RuleEngineServiceTest

# Run tests with coverage
mvn test jacoco:report

Deployment

Docker Deployment

# Build Docker image
docker build -t beas-rule-engine .

# Run container
docker run -d \
  --name beas-rule-engine \
  -p 8070:8070 \
  -e MONGODB_HOST=mongodb \
  -e CRYPTO_KEY=your-key \
  -e CRYPTO_IV=your-iv \
  beas-rule-engine

Production Deployment

For production deployment, consider:

Using a reverse proxy (nginx, Apache)
Setting up SSL/TLS certificates
Configuring proper logging
Setting up monitoring and alerting
Using a process manager (systemd, PM2)

Rule Engine

Quick Navigation