DTRules
Documentation Menu

Quick Start (Java)

The original Java implementation with full Excel-to-XML compilers and testing framework.

Prerequisites

  • Java 8+
  • Apache Maven 3.x

Step 1: Clone and Build

git clone https://github.com/dtrules/dtrules.git
cd DTRules
mvn clean install

This builds all modules:

  • dtrules-engine - Core rules engine
  • compilerutil - Excel to XML compiler utilities
  • dsl - Domain Specific Language implementations (EL, EBL)
  • sampleprojects - Example projects

Step 2: Run a Sample Project

The easiest way to understand DTRules is to run one of the sample projects.

CHIP Example (Health Insurance Eligibility)

cd sampleprojects/CHIP

# First, compile the Excel decision tables to XML
mvn exec:java -Dexec.mainClass="com.dtrules.samples.chipeligibility.CompileChip"

# Then run the tests
mvn exec:java -Dexec.mainClass="com.dtrules.samples.chipeligibility.TestChip"

Step 3: Explore the Sample Project Structure

sampleprojects/CHIP/
├── DecisionTables/           # Excel files with business rules
│   └── ChipEligibility_dt.xls
├── edd/                      # Entity Definition Documents
│   └── ChipEligibility_edd.xls
├── xml/                      # Compiled XML rule files (generated)
├── repository/               # Packaged rules for deployment
├── testfiles/                # Test case input files
├── DTRules.xml               # Project configuration
└── src/main/java/            # Java code
    └── CompileChip.java      # Compiles Excel → XML
    └── TestChip.java         # Runs test cases

How It Works

1. Define Your Data Model (EDD)

Create an Entity Definition Document in Excel (*_edd.xls) that defines:

  • Entities (data objects)
  • Attributes and their types
  • Relationships between entities

2. Write Decision Tables

Create Decision Tables in Excel (*_dt.xls) with:

  • Conditions - Boolean expressions in EL syntax
  • Actions - Operations to perform when conditions match
  • Columns - Each column represents a rule

3. Compile to XML

Excel2XML compiler = new Excel2XML(path, "DTRules.xml", "RuleSetName");
compiler.compileRuleSet(path, "DTRules.xml", "RuleSetName", "repository", maps, 5);

4. Execute Rules

// Load the rules
RulesDirectory rd = new RulesDirectory(path, "DTRules.xml");
RuleSet rs = rd.getRuleSet("RuleSetName");
IRSession session = rs.newSession();

// Load input data
session.loadXml(inputStream, "mapping");

// Execute a decision table
session.execute("DecisionTableName");

// Get results
session.printEntityReport(output, session.getState(), "results", ...);

Configuration

Each project has a DTRules.xml configuration file:

<DTRules>
  <compiler>EL</compiler>

  <RuleSet name="MyRules" source="file">
    <RuleSetFilePath>/xml</RuleSetFilePath>
    <WorkingDirectory>/temp</WorkingDirectory>

    <DTExcelFolder>/DecisionTables/</DTExcelFolder>
    <EDDExcelFolder>/edd/</EDDExcelFolder>

    <Entities        name="MyRules_edd.xml" />
    <Decisiontables  name="MyRules_dt.xml"  />
    <Map             name="MyRules_map.xml" />
  </RuleSet>
</DTRules>

Sample Projects

Project Description Type
TestProject Minimal template for new projects Rule Set
SyntaxTests Comprehensive EL language feature examples Reference
CHIP Health insurance eligibility determination Rule Set
KidAid Child assistance program eligibility Rule Set
ChipApp Multi-threaded CHIP application wrapper Application
KidAid_Application Simple KidAid integration example Application

Recommended Learning Path

  1. TestProject - Understand the minimal project structure
  2. SyntaxTests - Learn EL language features
  3. CHIP - See a real-world eligibility example
  4. ChipApp - Learn application integration patterns

Creating a New Project

  1. Copy sampleprojects/TestProject/ as a template
  2. Rename and update pom.xml with your project details
  3. Create your Entity Definition Document in edd/
  4. Create your Decision Tables in DecisionTables/
  5. Update DTRules.xml with your file names
  6. Create compile and test Java classes

Running Tests

# Run all tests
mvn test

# Run EL compiler tests (128 parameterized tests)
cd dsl/el
mvn test

# Run sample project tests
cd sampleprojects/CHIP
mvn exec:java -Dexec.mainClass="com.dtrules.samples.chipeligibility.TestChip"

Next Steps