Excel Import/Export

DTRules provides CLI tools for converting between Excel spreadsheets and the XML format used by the rules engine. This enables a workflow where business analysts author rules in Excel while the engine consumes XML.

Go Go CLI tools. The CLI tools on this page are part of the Go implementation.

Overview

Four standalone CLI tools handle conversion in both directions:

Tool	Direction	Description
`dt2excel`	XML → Excel	Export decision tables to `.xlsx` files
`excel2dt`	Excel → XML	Import decision tables from `.xlsx` files
`edd2excel`	XML → Excel	Export the Entity Data Dictionary to `.xlsx`
`excel2edd`	Excel → XML	Import the Entity Data Dictionary from `.xlsx`

Installation

Build the tools from source (requires Go 1.21+):

# Build all four tools
go build -o dt2excel   ./cmd/dt2excel
go build -o excel2dt   ./cmd/excel2dt
go build -o edd2excel  ./cmd/edd2excel
go build -o excel2edd  ./cmd/excel2edd

# Or install to $GOPATH/bin
go install ./cmd/dt2excel ./cmd/excel2dt ./cmd/edd2excel ./cmd/excel2edd

Decision Table Excel Format

Two Excel layouts are supported. Both are recognized automatically by excel2dt on import.

Format 1 — dt2excel layout

This is the format produced by dt2excel. Each decision table is written to its own .xlsx file with a single sheet.

Row	Column A	Column B	Column C+
1	`Decision Table`	table name
2	`Table Number`	number
3	`Type`	FIRST \| ALL \| BEST
4	`Comments`	description

Initial Actions section
	`Initial Actions`
	description	postfix

Conditions section
	`Conditions`
	`#`	`Description`	`Col 1`, `Col 2`, ...
	1	condition text	Y / N / blank

Actions section
	`Actions`
	`#`	`Description`	`Col 1`, `Col 2`, ...
	1	action text	X / blank

Policy Statements section
	`Policy Statements`
	`Column 1`	description

Format 2 — Exporter layout

This is the format produced by the Go Exporter (used by the dtrules CLI and the sync system). Multiple tables are written as separate sheets inside a single .xlsx workbook.

Row	Column A	Column B	Column C	Column D+
1	`Name: Table Name` (merged across all columns)
2	`Type: FIRST` (merged)
3	`COMMENTS: ...` (merged)
4	`TABLE_NUMBER: 1` (merged)

Contexts
	`Contexts:`
	#	comment	expression (merged)

Initial Actions
	`Initial Actions:`
	#	comment	expression (merged)

Conditions
	`Conditions:`		DSL expression	1, 2, 3, ...
	#	comment	expression	Y / N / blank

Actions
	`Actions:`		DSL expression	1, 2, 3, ...
	#	comment	expression	X / blank

Policy
	`Policy:`			statement per column

Tip: The exporter format includes a third column (C) for the DSL expression or compiled postfix, while the dt2excel format puts the description in column B and decision columns starting at C.

EDD Excel Format

Two EDD layouts are also supported. excel2edd detects the format automatically.

Single-sheet format (Exporter)

The Go exporter writes a single sheet named EDD with all entities.

Column A	Column B	Column C	Column D	Column E	Column F	Column G	Column H
Entity	Attribute	Type	SubType	Default	Input	Access	Description
customer	(5 attributes)
	name	string				rw	Customer name
	age	integer			customer.age	rw

Entity header rows have the entity name in column A and the attribute count (e.g., (5 attributes)) in column B. Attribute rows leave column A blank and fill columns B through H.

Multi-sheet format (edd2excel)

The edd2excel tool writes one sheet per entity. Each sheet has this layout:

Row	Column A	Column B	C	D	E	F	G
1	`Entity`	entity_name
2	`Access`	rw
3	`Comment`	description
4	(blank)
5	Field Name	Type	Subtype	Access	Input	Default	Comment
6+	name	string		rw			Customer name

Supported types

Valid values for the Type column:

string — text value
integer / long — whole number
double — floating-point number
boolean — true/false
date — date value
array — ordered collection (use SubType for element type)
entity — reference to another entity (use SubType for entity name)

CLI Usage

dt2excel — Export Decision Tables to Excel

dt2excel -input <xml_file> -output <output_dir>

Reads a decision table XML file and writes one .xlsx file per table into the output directory. Files are named NNN_TableName.xlsx where NNN is a zero-padded sequence number.

# Export all decision tables
dt2excel -input xml/TaxReturn_dt.xml -output excel/

# Output files:
#   excel/001_Validate_Input.xlsx
#   excel/002_Calculate_Tax.xlsx
#   ...

excel2dt — Import Decision Tables from Excel

excel2dt -input <file_or_dir> -output <output.xml> [-v] [-sort]

Reads one or more .xlsx files and produces a single XML file.

Flag	Description
`-input`	Path to a single `.xlsx` file or a directory of files
`-output`	Path to the output XML file
`-v`	Verbose output (print each sheet as it is processed)
`-sort`	Sort tables by `TABLE_NUMBER` (default: true)

# Import from a directory of .xlsx files
excel2dt -input excel/ -output xml/TaxReturn_dt.xml -v

# Import from a single file
excel2dt -input tables.xlsx -output xml/Tables_dt.xml

edd2excel — Export EDD to Excel

edd2excel -input <edd.xml> [-output <output.xlsx>]

Reads an EDD XML file and writes one sheet per entity. If -output is omitted, the output filename is derived from the input by replacing the extension with .xlsx.

edd2excel -input xml/TaxReturn_edd.xml -output TaxReturn_edd.xlsx

excel2edd — Import EDD from Excel

excel2edd -input <file.xlsx> [-output <output.xml>]
excel2edd -dir <directory>   [-output <output.xml>]

Reads a single file or an entire directory of .xlsx files and merges all entities into one XML file.

Flag	Description
`-input`	Path to a single `.xlsx` file
`-dir`	Path to a directory of `.xlsx` files (cannot combine with `-input`)
`-output`	Path to the output XML file (derived from input if omitted)

# Import a single EDD file
excel2edd -input edd/TaxReturn_edd.xlsx -output xml/TaxReturn_edd.xml

# Import all EDD files from a directory
excel2edd -dir edd/ -output xml/TaxReturn_edd.xml

Round-Trip Workflow

A typical development cycle involves exporting XML to Excel for editing, then importing the modified spreadsheets back. This "round-trip" preserves all rule structure.

Step 1: Export to Excel

# Export decision tables
dt2excel -input xml/MyProject_dt.xml -output excel/dt/

# Export EDD
edd2excel -input xml/MyProject_edd.xml -output excel/MyProject_edd.xlsx

Step 2: Edit in Excel

Open the generated .xlsx files in Excel, LibreOffice, or Google Sheets and make changes. You can:

Add or remove condition and action rows
Change column values (Y/N for conditions, X for actions)
Edit descriptions and comments
Add new entities or attributes to the EDD

Important: Do not rename the section header cells (Decision Table, Conditions, Actions, etc.) or change the overall layout structure. The importer relies on these markers to parse the spreadsheet.

Step 3: Import back to XML

# Import decision tables
excel2dt -input excel/dt/ -output xml/MyProject_dt.xml -v

# Import EDD
excel2edd -input excel/MyProject_edd.xlsx -output xml/MyProject_edd.xml

Step 4: Validate

# Run your test suite to verify the imported rules
dtrules validate xml/
go test ./...

Combined Workbooks

A single .xlsx file can contain both decision table sheets and an EDD sheet. The Go WorkbookImporter detects sheet types automatically:

EDD sheet — a sheet named EDD, or whose first row has headers Entity, Attribute, Type, SubType, ...
DT sheet — a sheet whose cell A1 starts with Decision Table or Name:

The dtrules sync system uses combined workbooks to keep Excel and XML files synchronized. See Quick Start (Go) for sync workflow details.

Legacy Format

The original compiler expected four default columns in decision table spreadsheets:

number | comments | dsl | table

These map to the row number, a comment field, the DSL expression, and the column values respectively. The Go tools understand both the legacy format and the newer formats described above, so existing spreadsheets can be imported without changes.

Troubleshooting

"unrecognized Excel format"

The importer could not detect whether the sheet uses the dt2excel or exporter layout. Verify that:

Cell A1 contains exactly Decision Table (dt2excel format) or starts with Name: (exporter format)
Section headers (Conditions, Actions) are present
The file has a .xlsx extension (not .xls or .csv)

"no table name found"

The table name cell is empty. In dt2excel format, cell B1 must contain the table name. In exporter format, row 1 must read Name: Your_Table_Name.

"failed to open Excel file"

Make sure the file is a valid .xlsx (Office Open XML) file
Close the file in Excel if it is open — locked files cannot be read
Temporary files starting with ~$ are automatically skipped

Entities not detected from combined workbook

If the EDD sheet is not being recognized, verify:

The sheet is named EDD, or
The first row contains headers starting with Entity, Attribute
For the multi-sheet format, cell A1 must be Entity and A2 must be Access

Column values are missing after import

The importers treat empty cells and the value - (dash) as blank. Make sure condition values are Y, N, or another non-empty value, and action values use X or the desired value text.