Preface

This documentation covers mxcli, a command-line tool for reading, querying, and modifying Mendix application projects, and MDL (Mendix Definition Language), the SQL-like language it uses. The material is organized into eight parts:

• Part I: Tutorial walks you through installation, exploring a project, making your first changes, and integrating with AI assistants.
• Part II: The MDL Language is a comprehensive guide to MDL syntax – domain models, microflows, pages, security, navigation, workflows, and business events.
• Part III: Project Tools covers code navigation, catalog queries, linting, testing, external SQL, and Docker integration.
• Part IV: IDE Integration describes the VS Code extension, LSP server, and mxcli init project setup.
• Part V: Go Library documents the Go API for programmatic access to Mendix projects.
• Part VI: MDL Statement Reference provides detailed syntax and examples for every MDL statement.
• Part VII: Architecture and Internals explains the MPR file format, parser pipeline, and catalog system for contributors.
• Part VIII: Appendixes includes quick reference tables, reserved words, error messages, and a glossary.

You can read the Tutorial sequentially or jump directly to the section relevant to your task. The Statement Reference (Part VI) is designed for lookup rather than linear reading.

What is mxcli?

mxcli is a command-line tool that enables developers and AI coding assistants to read, understand, and modify Mendix application projects. Mendix projects are stored in binary .mpr files that cannot be read or edited as text. mxcli bridges this gap by providing a text-based interface using MDL (Mendix Definition Language), a SQL-like syntax for querying and manipulating Mendix models.

How It Works

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Developer     │     │    mxcli     │     │ Mendix Project  │
│   or AI Agent   │────>│  (MDL REPL)  │────>│   (.mpr file)   │
│                 │ MDL │              │     │                 │
│ "Create a       │     │ Parses MDL   │     │ Creates actual  │
│  Customer       │     │ Validates    │     │ entities,       │
│  entity..."     │     │ Executes     │     │ microflows,     │
└─────────────────┘     └──────────────┘     │ pages, etc.     │
                                             └─────────────────┘

A developer or AI agent writes MDL statements. mxcli parses and validates them, then applies the changes directly to the .mpr project file. The modified project can then be opened in Mendix Studio Pro as usual.

Important: Do not edit a project with mxcli while it is open in Studio Pro. Studio Pro maintains in-memory caches that cannot be updated externally, and concurrent edits will cause errors. Close the project in Studio Pro first, run mxcli, then re-open the project.

Key Capabilities

• Project exploration – list modules, entities, microflows, pages; describe any element in MDL; full-text search across all strings and source definitions.
• Code navigation – find callers, callees, references, and impact analysis for any project element.
• Model modification – create and alter entities, microflows, pages, security rules, navigation, workflows, and more using MDL scripts.
• Catalog queries – SQL-based querying of project metadata (entity counts, microflow complexity, widget usage, cross-references).
• Linting and reports – 40+ built-in lint rules with SARIF output for CI; scored best-practices reports.
• Testing – test microflows using MDL syntax with javadoc-style annotations.
• AI assistant integration – works with Claude Code, Cursor, Continue.dev, Windsurf, and Aider. mxcli init sets up project configuration, skills, and a Dev Container for sandboxed AI development.
• VS Code extension – syntax highlighting, diagnostics, code completion, hover, go-to-definition, and context menu commands for .mdl files.
• External SQL – connect to PostgreSQL, Oracle, or SQL Server; query external databases; import data into a running Mendix application.

Supported Environments

What is MDL?

MDL (Mendix Definition Language) is a text-based, SQL-like language for describing and manipulating Mendix application models. It provides a human-readable representation of Mendix project elements – entities, microflows, pages, security rules, and more – at the same abstraction level as the visual models in Studio Pro.

Why a Text-Based Language?

Mendix projects are stored in a binary format (.mpr files containing BSON documents in SQLite). While Studio Pro provides a visual interface, there is no standard text format for Mendix models. This creates problems for:

• AI assistants that need to read and generate model elements
• Code review of changes to Mendix projects
• Scripting and automation of repetitive modeling tasks
• Documentation of project structure and design patterns

MDL addresses these problems by providing a syntax that is both human-readable and machine-parseable.

Characteristics of MDL

• SQL-like syntax – uses familiar keywords like CREATE, ALTER, DROP, SHOW, DESCRIBE, GRANT.
• Declarative – you describe what the model should look like, not how to construct it step by step.
• Complete – covers domain models, microflows, pages, security, navigation, workflows, and business events.
• Validated – mxcli can check MDL scripts for syntax errors and reference validity before applying them.

Token Efficiency

When working with AI coding assistants, context window size is a critical constraint. MDL’s compact syntax uses significantly fewer tokens than equivalent JSON model representations:

Fewer tokens means lower API costs, more application context fits in a single prompt, and AI assistants produce more accurate output because there is less noise in their input.

Example: JSON vs MDL

A simple entity definition illustrates the difference.

JSON representation (~180 tokens):

{
  "entity": {
    "name": "Customer",
    "documentation": "Customer master data",
    "attributes": [
      {"name": "Name", "type": {"type": "String", "length": 200}},
      {"name": "Email", "type": {"type": "String", "length": 200}}
    ]
  }
}

MDL representation (~35 tokens):

/** Customer master data */
CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200),
    Email: String(200)
);

The MDL version conveys the same information in roughly one-fifth the space, and its structure is immediately recognizable to anyone familiar with SQL DDL.

What MDL Covers

MDL provides statements for the following areas of a Mendix project:

See Part II (The MDL Language) for a complete guide, or Part VI (MDL Statement Reference) for detailed syntax of each statement.

Mendix Concepts for Newcomers

This page explains the core Mendix concepts you’ll encounter when using mxcli. If you’re familiar with web frameworks, relational databases, or backend development, most of these will map to things you already know.

The Big Picture

A Mendix application is a model-driven app. Instead of writing code in files, developers build applications visually in Studio Pro (the Mendix IDE). The entire application model – data structures, logic, UI, security – is stored in a single binary file called an MPR (Mendix Project Resource).

mxcli lets you read and modify that MPR file using text commands, without opening Studio Pro.

Modules

A module is the top-level organizational unit, like a package in Go or a namespace in C#. Each module has its own:

• Domain model (data structures)
• Microflows and nanoflows (logic)
• Pages (UI)
• Enumerations (constant sets)
• Security settings

A typical project has a few custom modules (Sales, Admin, Integration) plus system modules provided by the platform (System, Administration).

SHOW MODULES;

Domain Model

The domain model is the data layer of a module. If you know relational databases, the mapping is straightforward:

Entities

An entity defines a data type. There are several kinds:

• Persistent – stored in the database (the default and most common)
• Non-persistent – exists only in memory during a user session, useful for form state or temporary calculations
• View – backed by an OQL query, like a database view

CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200) NOT NULL,
    Email: String(200),
    IsActive: Boolean DEFAULT true
);

Associations

An association is a relationship between two entities. Think of it as a foreign key.

• Reference – many-to-one or one-to-one (a foreign key column on the “from” entity)
• ReferenceSet – many-to-many (a join table under the hood)

CREATE ASSOCIATION Sales.Order_Customer
    FROM Sales.Order TO Sales.Customer
    TYPE Reference;

Generalization

Entities can inherit from other entities using generalization (the EXTENDS keyword). The child entity gets all parent attributes. This is commonly used with system entities like System.Image (for file uploads) or System.User (for user accounts).

CREATE PERSISTENT ENTITY Sales.ProductImage EXTENDS System.Image (
    Caption: String(200)
);

Microflows and Nanoflows

Microflows are the server-side logic of a Mendix app. They’re visual flowcharts in Studio Pro, but in MDL they read like imperative code with activities:

• Retrieve data from the database
• Create, Change, Commit, Delete objects
• Call other microflows or external services
• If/Else branching, Loop iteration
• Show Page, Log Message, Validation Feedback

CREATE MICROFLOW Sales.CreateOrder(
    DECLARE $Customer: Sales.Customer
)
RETURN Boolean
BEGIN
    CREATE $Order: Sales.Order (
        OrderDate = [%CurrentDateTime%],
        Status = 'Draft'
    );
    CHANGE $Order (
        Sales.Order_Customer = $Customer
    );
    COMMIT $Order;
    RETURN true;
END;

Nanoflows are the client-side equivalent. They run in the browser (or native mobile app) and are useful for offline-capable logic and low-latency UI interactions. They have the same syntax but fewer available activities (no database transactions, no direct service calls).

Pages

Pages define the user interface. A page has:

• A layout – the outer frame (header, sidebar, footer) shared across pages
• Widgets – the UI components inside the page

Widgets are nested in a tree. Common widget types:

CREATE PAGE Sales.CustomerOverview
    LAYOUT Atlas_Core.Atlas_Default
    TITLE 'Customers'
(
    DATAGRID SOURCE DATABASE Sales.Customer (
        COLUMN Name,
        COLUMN Email,
        COLUMN IsActive
    )
);

Snippets

A snippet is a reusable page fragment. You define it once and embed it in multiple pages using a SnippetCall. Think of it as a component or partial template.

Security

Mendix uses a role-based access control model:

1. Module roles are defined per module (e.g., Sales.Admin, Sales.User)
2. User roles are defined at the project level and aggregate module roles
3. Access rules control what each module role can do with entities (CREATE, READ, WRITE, DELETE) and which microflows/pages they can access

CREATE MODULE ROLE Sales.Manager;

GRANT CREATE, READ, WRITE ON Sales.Customer TO Sales.Manager;
GRANT EXECUTE ON MICROFLOW Sales.CreateOrder TO Sales.Manager;
GRANT VIEW ON PAGE Sales.CustomerOverview TO Sales.Manager;

Navigation

Navigation profiles define how users move through the app. There are profiles for responsive web, tablet, phone, and native mobile. Each profile has:

• A home page (the landing page after login)
• A menu with items that link to pages or microflows

Workflows

Workflows model long-running processes with human tasks. Think of them as state machines for approval flows, onboarding processes, or multi-step procedures. A workflow has:

• User tasks – steps that require human action
• Decisions – branching based on conditions
• Parallel splits – concurrent paths

Workflows complement microflows: microflows handle immediate logic, workflows handle processes that span hours or days.

How It All Fits Together

Project
├── Module: Sales
│   ├── Domain Model
│   │   ├── Entity: Customer (Name, Email, IsActive)
│   │   ├── Entity: Order (OrderDate, Status)
│   │   └── Association: Order_Customer
│   ├── Microflows
│   │   ├── CreateOrder
│   │   └── ApproveOrder
│   ├── Pages
│   │   ├── CustomerOverview
│   │   └── OrderEdit
│   ├── Enumerations
│   │   └── OrderStatus (Draft, Active, Closed)
│   └── Security
│       ├── Module Role: Manager
│       └── Module Role: Viewer
├── Module: Administration
│   └── ...
└── Navigation
    └── Responsive profile → Home: Sales.CustomerOverview

In mxcli, you can explore this structure with:

SHOW STRUCTURE DEPTH 2;

What’s Next

• Part I: Tutorial – hands-on walkthrough
• Part II: The MDL Language – complete language guide
• Glossary – alphabetical reference of all terms

Document Conventions

This page describes the formatting and notation conventions used throughout this documentation.

Code Examples

MDL examples use sql code fencing because MDL’s syntax is SQL-like and this provides appropriate syntax highlighting:

CREATE PERSISTENT ENTITY MyModule.Customer (
    Name: String(200) NOT NULL
);

Go code examples use go code fencing:

reader, err := modelsdk.Open("/path/to/app.mpr")
defer reader.Close()

Shell commands use bash code fencing:

mxcli -p app.mpr -c "SHOW MODULES"

Syntax Notation

When describing the syntax of MDL statements, the following conventions apply:

For example, the notation:

CREATE [PERSISTENT] ENTITY module.name (
    attribute_name: type [NOT NULL] [, ...]
);

means: CREATE and ENTITY are required keywords; PERSISTENT is optional; module.name is a user-provided qualified name; each attribute has a name and type, with an optional NOT NULL constraint; and additional attributes may follow, separated by commas.

Cross-References

References to MDL statements link to their detailed pages in Part VI (MDL Statement Reference) using the format “See CREATE ENTITY” or “See GRANT”. References to conceptual explanations link to the relevant section in Part II (The MDL Language).

Terminology

Mendix-specific terms such as “entity”, “microflow”, “nanoflow”, “module”, and “domain model” follow standard Mendix terminology. See the Glossary for definitions.

Setting Up

Before you can start exploring and modifying Mendix projects from the command line, you need three things:

1. mxcli installed on your machine
2. A Mendix project (an .mpr file) to work with
3. A feel for the REPL, the interactive shell where you’ll spend most of your time

This chapter walks you through all three.

Installation methods

There are four ways to get started with mxcli:

• Playground – open the mxcli Playground in a GitHub Codespace. Zero install, runs in your browser with a sample Mendix project, tutorials, and example scripts. Best way to try mxcli for the first time.
• Binary download – grab a pre-built binary from GitHub Releases. Quickest path if you want to use mxcli on your own project.
• Build from source – clone the repo and run make build. Useful if you want the latest unreleased changes or plan to contribute.
• Dev Container (recommended for your own projects) – run mxcli init on your Mendix project, open it in VS Code, and reopen in the container. This gives you mxcli, a JDK, Docker-in-Docker, and Claude Code all pre-configured in a sandboxed environment. This is the recommended approach, especially when pairing with AI coding assistants.

The next few pages cover each method, then walk you through opening a project and using the REPL.

Alpha software warning. mxcli can corrupt your Mendix project files. Always work on a copy of your .mpr or use version control (Git) before making changes.

Installation

Pick whichever method suits your situation. If you just want to try mxcli without installing anything, start with the Playground. If you’re planning to use mxcli on your own project with an AI coding assistant, skip to the Dev Container section.

Playground (zero install)

The fastest way to try mxcli. The mxcli Playground is a GitHub repository with a pre-configured Mendix project, example scripts, and tutorials. Open it in a Codespace and start using mxcli immediately – nothing to install on your machine.

The Codespace comes with mxcli, a JDK, Docker-in-Docker, Claude Code, and a sample Mendix 11.x project ready to explore and modify. It includes:

• 5 example scripts – explore, create entities, microflows, pages, and security
• Step-by-step tutorials – from first steps through linting and testing
• AI tool configs – pre-configured for Claude Code, Cursor, Windsurf, Continue.dev, and Aider

Once the Codespace is running:

./mxcli -p App.mpr -c "SHOW STRUCTURE"          # Explore the project
./mxcli exec scripts/01-explore.mdl -p App.mpr   # Run an example script
./mxcli                                           # Start interactive REPL

When you’re ready to work on your own Mendix project, use one of the installation methods below.

Binary download

Pre-built binaries are available for Linux, macOS, and Windows on both amd64 and arm64 architectures.

1. Go to the GitHub Releases page.
2. Download the archive for your platform (e.g., mxcli_linux_amd64.tar.gz or mxcli_darwin_arm64.tar.gz).
3. Extract the binary and move it somewhere on your PATH:

# Example for Linux/macOS
tar xzf mxcli_linux_amd64.tar.gz
sudo mv mxcli /usr/local/bin/

On Windows, extract the .zip and add the folder containing mxcli.exe to your system PATH.

Build from source

Building from source requires Go 1.24 or later and Make. No C compiler is needed – mxcli uses a pure-Go SQLite driver.

git clone https://github.com/mendixlabs/mxcli.git
cd mxcli
make build

The binary lands at ./bin/mxcli. You can copy it to a directory on your PATH or run it directly:

./bin/mxcli --version

Dev Container (recommended)

The Dev Container approach is the recommended way to work with mxcli, particularly when using AI coding assistants. It creates a sandboxed environment so that agents can only access your project files, not the rest of your system.

Here’s how to set it up:

Step 1: Install mxcli using one of the methods above (you need it locally to run init).

Step 2: Run mxcli init on your Mendix project:

mxcli init /path/to/my-mendix-project

This creates a .devcontainer/ folder (along with skill files, agent configs, and other goodies) inside your project directory.

Step 3: Open the project folder in VS Code and click “Reopen in Container” when prompted (or use the Command Palette: Dev Containers: Reopen in Container).

VS Code will build and start the container. This takes a minute or two the first time.

What’s inside the Dev Container

The container comes with everything you need pre-installed:

Once the container is running, mxcli is ready to use – no further setup needed.

Specifying AI tools

By default, mxcli init configures for Claude Code. You can target other tools too:

# Cursor only
mxcli init --tool cursor /path/to/my-mendix-project

# Multiple tools
mxcli init --tool claude --tool cursor /path/to/my-mendix-project

# Everything
mxcli init --all-tools /path/to/my-mendix-project

Run mxcli init --list-tools to see all supported tools.

Verify your installation

Whichever method you used, confirm that mxcli is working:

mxcli --version

You should see version and build information printed to the terminal. If you get a “command not found” error, double-check that the binary is on your PATH.

You’re ready to open a project.

Opening Your First Project

mxcli works with Mendix project files – the .mpr files that Mendix Studio Pro creates. Let’s open one.

Back up first. mxcli is alpha software and can corrupt project files. Before you start, either make a copy of your .mpr file or make sure the project is under version control (Git). This isn’t just a disclaimer – take it seriously.

The -p flag

The most common way to point mxcli at a project is with the -p flag:

mxcli -p /path/to/app.mpr -c "SHOW MODULES"

This opens the project in read-only mode, runs the command, and exits. The -p flag works with all mxcli subcommands.

Opening in the REPL

You can also open a project from inside the interactive REPL:

# Start the REPL, then open a project
mxcli

OPEN PROJECT '/path/to/app.mpr';
SHOW MODULES;

Or pass -p when launching the REPL so it opens the project immediately:

mxcli -p /path/to/app.mpr

-- Project is already open, start working
SHOW MODULES;

When you provide -p, the project stays open for the duration of your REPL session. You don’t need to pass it again for each command.

Read-only vs read-write

By default, mxcli opens projects in read-only mode. This is safe for exploration – you can browse modules, describe entities, search through the project, and run catalog queries without risk.

When you execute a command that modifies the project (like CREATE ENTITY), mxcli automatically upgrades to read-write mode. You’ll see a confirmation message when this happens.

MPR format auto-detection

Mendix projects come in two formats:

• v1: A single .mpr SQLite database file (Mendix versions before 10.18)
• v2: An .mpr metadata file plus an mprcontents/ folder with individual documents (Mendix 10.18 and later)

You don’t need to worry about which format your project uses. mxcli detects the format automatically and handles both transparently. Just point it at the .mpr file either way.

Working in a Dev Container

If you’re using the Dev Container setup from the previous page, your project is already mounted in the container. The typical path is:

mxcli -p app.mpr

The Dev Container sets the working directory to your project root, so relative paths work naturally.

Quick sanity check

Once you have a project open, try listing the modules:

mxcli -p app.mpr -c "SHOW MODULES"

You should see a table of module names. If you see your project’s modules listed, everything is working and you’re ready to explore.

Next up: the REPL, where the real fun starts.

The REPL

The mxcli REPL is an interactive shell for working with Mendix projects, much like psql is for PostgreSQL or mysql for MySQL. You type MDL statements, press Enter, and see results immediately.

Starting the REPL

Launch it with or without a project:

# Start with a project already loaded
mxcli -p app.mpr

# Start without a project (you can open one later)
mxcli

You’ll see a prompt where you can start typing MDL:

mxcli>

Running commands

Type any MDL statement and press Enter:

SHOW MODULES;

Results are printed as formatted tables directly in the terminal.

Multi-line statements

MDL statements end with a semicolon (;). If you press Enter before typing a semicolon, mxcli knows you’re still writing and waits for more input:

CREATE ENTITY MyModule.Customer (
    Name: String(200) NOT NULL,
    Email: String(200),
    IsActive: Boolean DEFAULT true
);

The REPL shows a continuation prompt (.....>) while you’re in a multi-line statement. The statement executes when you type the closing ; and press Enter.

Getting help

Type HELP to see a list of available commands:

HELP;

This prints a categorized overview of all MDL statements – useful when you can’t remember the exact syntax for something.

Command history

Use the up and down arrow keys to scroll through previous commands, just like in any other shell. This is especially handy when you’re iterating on a query or tweaking a CREATE statement.

Exiting

When you’re done, type either:

EXIT;

or:

QUIT;

You can also press Ctrl+D to exit.

One-off commands with -c

You don’t always need an interactive session. The -c flag lets you run a single command and exit:

mxcli -p app.mpr -c "SHOW ENTITIES IN MyModule"

This is great for quick lookups and for scripting. The output is pipe-friendly, so you can chain it with other tools:

# Count entities per module
mxcli -p app.mpr -c "SHOW MODULES" | tail -n +2 | while read module; do
    echo "$module: $(mxcli -p app.mpr -c "SHOW ENTITIES IN $module" | wc -l) entities"
done

Running script files

For anything beyond a quick one-liner, you can put MDL statements in a .mdl file and execute the whole thing:

mxcli -p app.mpr -c "EXECUTE SCRIPT 'setup.mdl'"

Or from the REPL:

EXECUTE SCRIPT 'setup.mdl';

This is how you’ll typically apply larger changes – write the MDL in a file, check the syntax with mxcli check, then execute it.

The TUI (Terminal UI)

If you prefer a more visual experience, mxcli also offers a graphical terminal interface:

mxcli tui -p app.mpr

The TUI gives you a split-pane layout with a project tree, an MDL editor, and output panels. It’s built on top of the same REPL engine, so all the same commands work. This can be a nice middle ground between the bare REPL and opening Studio Pro.

What’s next

Now that you know how to install mxcli, open a project, and use the REPL, you’re ready to start exploring. The next chapter walks through the commands you’ll use most often: SHOW, DESCRIBE, and SEARCH.

Exploring a Project

Once you have a project open – whether through the REPL, a CLI one-liner, or a script file – the next step is to look around. What modules exist? What entities are defined? What does a particular microflow do?

mxcli provides three families of commands for exploration:

• SHOW commands list elements by type. SHOW ENTITIES lists all entities; SHOW MICROFLOWS IN Sales narrows the list to one module.
• DESCRIBE commands display the full MDL source for a single element, giving you the complete definition including attributes, associations, logic, and widget trees.
• SEARCH performs full-text search across every string in the project – captions, messages, expressions, documentation, and more.
• SHOW STRUCTURE gives you a compact tree view of the entire project or a single module, at varying levels of detail.

These commands are read-only. They never modify your project. You can run them freely to build a mental model of the application before making any changes.

What you will learn

In this chapter, you will:

1. List modules, entities, microflows, pages, and other elements with SHOW commands
2. Inspect the full definition of any element with DESCRIBE
3. Find elements by keyword with SEARCH
4. Get a bird’s-eye view of project structure with SHOW STRUCTURE

Prerequisites

You should have mxcli installed and know how to open a project. If not, work through the Setting Up chapter first.

The examples in this chapter assume you have a Mendix project open. You can follow along using either the REPL or CLI one-liners:

# REPL (interactive)
mxcli -p /path/to/app.mpr

# CLI one-liner
mxcli -p /path/to/app.mpr -c "SHOW ENTITIES"

If you do not have a Mendix project handy, the commands will still make sense – the output format and options are the same regardless of the project content.

SHOW MODULES, SHOW ENTITIES

The SHOW family of commands lists project elements by type. They are the fastest way to see what a project contains.

Listing modules

Every Mendix project is organized into modules. Start by listing them:

SHOW MODULES;

Example output:

MyFirstModule
Administration
Atlas_Core
System

By default, system and marketplace modules (like System and Atlas_Core) are included. The modules appear in the order they are defined in the project.

Listing entities

To see all entities across all modules:

SHOW ENTITIES;

Example output:

Administration.Account
MyFirstModule.Customer
MyFirstModule.Order
MyFirstModule.OrderLine

Each entity is shown as a qualified name – the module name and entity name separated by a dot.

Filtering by module

Most SHOW commands accept an IN clause to filter results to a single module:

SHOW ENTITIES IN MyFirstModule;

MyFirstModule.Customer
MyFirstModule.Order
MyFirstModule.OrderLine

This is typically what you want when working on a specific module.

Listing microflows

SHOW MICROFLOWS;

Administration.ChangeMyPassword
MyFirstModule.ACT_Customer_Save
MyFirstModule.ACT_Order_Process
MyFirstModule.DS_Customer_GetAll

Filter to a module:

SHOW MICROFLOWS IN MyFirstModule;

MyFirstModule.ACT_Customer_Save
MyFirstModule.ACT_Order_Process
MyFirstModule.DS_Customer_GetAll

Listing pages

SHOW PAGES;

Administration.Account_Overview
Administration.Login
MyFirstModule.Customer_Overview
MyFirstModule.Customer_Edit
MyFirstModule.Order_Detail

Filter to a module:

SHOW PAGES IN MyFirstModule;

MyFirstModule.Customer_Overview
MyFirstModule.Customer_Edit
MyFirstModule.Order_Detail

Other SHOW commands

The same pattern works for all major element types:

SHOW ENUMERATIONS;
SHOW ENUMERATIONS IN MyFirstModule;

SHOW ASSOCIATIONS;
SHOW ASSOCIATIONS IN MyFirstModule;

SHOW WORKFLOWS;
SHOW WORKFLOWS IN MyFirstModule;

SHOW NANOFLOWS;
SHOW NANOFLOWS IN MyFirstModule;

SHOW CONSTANTS;
SHOW CONSTANTS IN MyFirstModule;

SHOW SNIPPETS;
SHOW SNIPPETS IN MyFirstModule;

You can also list security-related elements:

SHOW MODULE ROLES;
SHOW MODULE ROLES IN MyFirstModule;

SHOW USER ROLES;

SHOW DEMO USERS;

And navigation:

SHOW NAVIGATION;

Using SHOW from the command line

Every SHOW command works as a CLI one-liner with -c:

mxcli -p app.mpr -c "SHOW ENTITIES"
mxcli -p app.mpr -c "SHOW MICROFLOWS IN MyFirstModule"
mxcli -p app.mpr -c "SHOW PAGES"

This is useful for quick lookups without entering the REPL, and for piping output to other tools:

# Count entities per module
mxcli -p app.mpr -c "SHOW ENTITIES" | cut -d. -f1 | sort | uniq -c

# Find all microflows with "Save" in the name
mxcli -p app.mpr -c "SHOW MICROFLOWS" | grep -i save

Summary of SHOW commands

Now that you can list elements, the next step is inspecting individual elements in detail with DESCRIBE and SEARCH.

DESCRIBE, SEARCH

While SHOW commands list elements by name, DESCRIBE gives you the full definition of a single element. SEARCH lets you find elements by keyword when you do not know the exact name.

DESCRIBE ENTITY

To see the complete definition of an entity, including its attributes, types, and constraints:

DESCRIBE ENTITY MyFirstModule.Customer;

Example output:

CREATE PERSISTENT ENTITY MyFirstModule.Customer (
  Name: String(200),
  Email: String(200),
  Phone: String(50),
  DateOfBirth: DateTime,
  IsActive: Boolean DEFAULT false
);

The output is valid MDL – you could copy it, modify it, and execute it as a CREATE OR MODIFY statement. This round-trip capability is one of the key design features of MDL.

DESCRIBE also shows associations and access rules when they exist:

DESCRIBE ENTITY MyFirstModule.Order;

CREATE PERSISTENT ENTITY MyFirstModule.Order (
  OrderNumber: AutoNumber,
  OrderDate: DateTime,
  TotalAmount: Decimal,
  Status: MyFirstModule.OrderStatus
);

CREATE ASSOCIATION MyFirstModule.Order_Customer
  FROM MyFirstModule.Order TO MyFirstModule.Customer
  TYPE Reference
  OWNER Default
  DELETE_BEHAVIOR DeleteRefSetOnly;

DESCRIBE MICROFLOW

To see the full logic of a microflow:

DESCRIBE MICROFLOW MyFirstModule.ACT_Customer_Save;

Example output:

CREATE MICROFLOW MyFirstModule.ACT_Customer_Save
  ($Customer: MyFirstModule.Customer)
  RETURNS Boolean
BEGIN
  IF $Customer/Name = empty THEN
    VALIDATION FEEDBACK $Customer/Name MESSAGE 'Name is required';
    RETURN false;
  END IF;

  COMMIT $Customer;
  RETURN true;
END;

This shows the parameters, return type, and the complete flow logic. For complex microflows, this can be quite long – but it gives you the full picture in one command.

DESCRIBE PAGE

Pages are shown as their widget tree:

DESCRIBE PAGE MyFirstModule.Customer_Edit;

Example output:

CREATE PAGE MyFirstModule.Customer_Edit
(
  Params: { $Customer: MyFirstModule.Customer },
  Title: 'Edit Customer',
  Layout: Atlas_Core.PopupLayout
)
{
  DATAVIEW dvCustomer (DataSource: $Customer) {
    TEXTBOX txtName (Label: 'Name', Attribute: Name)
    TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
    TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)

    FOOTER footer1 {
      ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
      ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
    }
  }
};

DESCRIBE ENUMERATION

DESCRIBE ENUMERATION MyFirstModule.OrderStatus;

CREATE ENUMERATION MyFirstModule.OrderStatus (
  Draft 'Draft',
  Submitted 'Submitted',
  Approved 'Approved',
  Rejected 'Rejected',
  Completed 'Completed'
);

Each value is followed by its caption (the display label shown to end users).

DESCRIBE ASSOCIATION

DESCRIBE ASSOCIATION MyFirstModule.Order_Customer;

CREATE ASSOCIATION MyFirstModule.Order_Customer
  FROM MyFirstModule.Order TO MyFirstModule.Customer
  TYPE Reference
  OWNER Default
  DELETE_BEHAVIOR DeleteRefSetOnly;

Other DESCRIBE targets

The same pattern works for other element types:

DESCRIBE WORKFLOW MyFirstModule.ApprovalFlow;
DESCRIBE NANOFLOW MyFirstModule.NAV_GoToDetail;
DESCRIBE SNIPPET MyFirstModule.CustomerCard;
DESCRIBE CONSTANT MyFirstModule.ApiBaseUrl;
DESCRIBE NAVIGATION;
DESCRIBE SETTINGS;

Full-text search with SEARCH

When you do not know the exact name of an element, use SEARCH to find it by keyword. This searches across all strings in the project – entity names, attribute names, microflow logic, page captions, messages, documentation, and more.

SEARCH 'validation';

Example output:

MyFirstModule.ACT_Customer_Save (Microflow)
  "VALIDATION FEEDBACK $Customer/Name MESSAGE 'Name is required'"

MyFirstModule.ACT_Order_Validate (Microflow)
  "VALIDATION FEEDBACK $Order/OrderDate MESSAGE 'Order date cannot be in the past'"

MyFirstModule.Customer_Edit (Page)
  "Validation errors will appear here"

Search is case-insensitive and matches partial words.

Search from the command line

The CLI provides a dedicated search subcommand with formatting options:

# Search with default output
mxcli search -p app.mpr "validation"

# Show only element names (no context)
mxcli search -p app.mpr "validation" --format names

# JSON output for programmatic use
mxcli search -p app.mpr "validation" --format json

The --format names option is useful for piping into other commands:

# Find all microflows mentioning "email" and describe each one
mxcli search -p app.mpr "email" --format names | while read name; do
  mxcli -p app.mpr -c "DESCRIBE MICROFLOW $name"
done

Combining SHOW, DESCRIBE, and SEARCH

A typical exploration workflow looks like this:

1. Start broad with SHOW to see what exists:

   SHOW MODULES;
   SHOW ENTITIES IN Sales;
   

2. Zoom in with DESCRIBE on interesting elements:

   DESCRIBE ENTITY Sales.Order;
   DESCRIBE MICROFLOW Sales.ACT_Order_Process;
   

3. Search when you need to find something specific:

   SEARCH 'discount';
   

This workflow mirrors how you would explore a project in Mendix Studio Pro – browsing the project explorer, opening documents, and using Find to locate things.

Next, learn how to get a compact overview of the entire project with SHOW STRUCTURE.

SHOW STRUCTURE

The SHOW STRUCTURE command gives you a compact, tree-style overview of a project. It is the fastest way to understand the overall shape of an application – what modules exist, what types of documents they contain, and how large each module is.

Default view

With no arguments, SHOW STRUCTURE displays all user modules at depth 2 – modules with their documents listed by type:

SHOW STRUCTURE;

Example output:

MyFirstModule
  Entities
    Customer (Name, Email, Phone, DateOfBirth, IsActive)
    Order (OrderNumber, OrderDate, TotalAmount, Status)
    OrderLine (Quantity, UnitPrice, LineTotal)
  Microflows
    ACT_Customer_Save ($Customer: Customer) : Boolean
    ACT_Order_Process ($Order: Order) : Boolean
    DS_Customer_GetAll () : List of Customer
  Pages
    Customer_Overview
    Customer_Edit ($Customer: Customer)
    Order_Detail ($Order: Order)
  Enumerations
    OrderStatus (Draft, Submitted, Approved, Rejected, Completed)
Administration
  Entities
    Account (FullName, Email, IsLocalUser, BlockedSince)
  Microflows
    ChangeMyPassword ($OldPassword, $NewPassword) : Boolean
  Pages
    Account_Overview
    Login

This gives you a bird’s-eye view without opening individual elements. Entity signatures show attribute names; microflow signatures show parameters and return types.

Depth levels

The DEPTH option controls how much detail is shown:

DEPTH 1 – Module summary

Shows one line per module with element counts:

SHOW STRUCTURE DEPTH 1;

MyFirstModule       3 entities, 3 microflows, 3 pages, 1 enumeration, 2 associations
Administration      1 entity, 1 microflow, 2 pages

This is useful for getting a quick sense of project size and where the complexity lives.

DEPTH 2 – Elements with signatures (default)

This is the default when you run SHOW STRUCTURE with no depth specified. It shows modules, their documents grouped by type, and compact signatures for each element. See the example under Default view above.

DEPTH 3 – Full detail

Shows typed attributes and named parameters:

SHOW STRUCTURE DEPTH 3;

MyFirstModule
  Entities
    Customer
      Name: String(200)
      Email: String(200)
      Phone: String(50)
      DateOfBirth: DateTime
      IsActive: Boolean DEFAULT false
    Order
      OrderNumber: AutoNumber
      OrderDate: DateTime
      TotalAmount: Decimal
      Status: MyFirstModule.OrderStatus
    OrderLine
      Quantity: Integer
      UnitPrice: Decimal
      LineTotal: Decimal
  Microflows
    ACT_Customer_Save ($Customer: MyFirstModule.Customer) : Boolean
    ACT_Order_Process ($Order: MyFirstModule.Order) : Boolean
    DS_Customer_GetAll () : List of MyFirstModule.Customer
  Pages
    Customer_Overview
    Customer_Edit ($Customer: MyFirstModule.Customer)
    Order_Detail ($Order: MyFirstModule.Order)
  Enumerations
    OrderStatus
      Draft 'Draft'
      Submitted 'Submitted'
      Approved 'Approved'
      Rejected 'Rejected'
      Completed 'Completed'
  Associations
    Order_Customer: Order -> Customer (Reference)
    OrderLine_Order: OrderLine -> Order (Reference)

Depth 3 is verbose but gives you the most complete picture without running individual DESCRIBE commands.

Filtering by module

Use IN to show only a single module:

SHOW STRUCTURE IN MyFirstModule;

This produces the same tree format but limited to one module. Combine with DEPTH for control over detail:

SHOW STRUCTURE DEPTH 3 IN MyFirstModule;

Including system modules

By default, system and marketplace modules are hidden. Add ALL to include them:

SHOW STRUCTURE DEPTH 1 ALL;

MyFirstModule       3 entities, 3 microflows, 3 pages, 1 enumeration, 2 associations
Administration      1 entity, 1 microflow, 2 pages
Atlas_Core          0 entities, 0 microflows, 12 pages
System              15 entities, 0 microflows, 0 pages

This is useful when you need to see system entities (like System.Image or System.FileDocument) or check what a marketplace module provides.

Using SHOW STRUCTURE from the command line

# Quick project overview
mxcli -p app.mpr -c "SHOW STRUCTURE DEPTH 1"

# Detailed view of one module
mxcli -p app.mpr -c "SHOW STRUCTURE DEPTH 3 IN Sales"

# Full project including system modules
mxcli -p app.mpr -c "SHOW STRUCTURE ALL"

When to use SHOW STRUCTURE vs SHOW + DESCRIBE

SHOW STRUCTURE is best for orientation – understanding the shape of the project at a glance. For detailed work on specific elements, switch to DESCRIBE.

What is next

Now that you can explore a project, you are ready to start making changes. Continue to Your First Changes to learn how to create entities, microflows, and pages using MDL.

Your First Changes

Now that you can explore a project with SHOW and DESCRIBE, it’s time to make changes. This chapter walks through the three most common modifications: creating an entity, a microflow, and a page.

Before you start

Always work on a copy. mxcli writes directly to your .mpr file. Before making changes, either:

• Copy the .mpr file (and mprcontents/ folder if it exists) to a scratch directory
• Use Git so you can revert with git checkout

# Make a working copy
cp app.mpr app-scratch.mpr
cp -r mprcontents/ mprcontents-scratch/   # only for MPR v2 projects

The workflow

Every modification follows the same pattern:

1. Write MDL – either directly on the command line with -c, or in a .mdl script file
2. Check syntax – run mxcli check to catch errors before touching the project
3. Execute – apply the changes to the .mpr file
4. Validate – use mxcli docker check for a full Studio Pro-level validation
5. Open in Studio Pro – confirm the result visually

# Step 1-2: Write and check syntax
mxcli check setup.mdl

# Step 3: Execute against the project
mxcli exec setup.mdl -p app.mpr

# Step 4: Full validation
mxcli docker check -p app.mpr

# Step 5: Open in Studio Pro and inspect

You can also skip the script file and execute commands directly:

mxcli -p app.mpr -c "CREATE PERSISTENT ENTITY MyModule.Product (Name: String(200) NOT NULL, Price: Decimal);"

What we’ll build

Over the next few pages, you’ll create:

The final page, Validating with mxcli check, covers the full validation workflow in detail.

Quick note on module names

Every MDL statement references a module. In these examples we use MyModule – replace it with whatever module exists in your project. You can check available modules with:

mxcli -p app.mpr -c "SHOW MODULES"

Idempotent scripts with OR MODIFY

If you plan to run a script more than once (common during development), use CREATE OR MODIFY instead of plain CREATE. This updates the entity if it already exists instead of failing:

CREATE OR MODIFY PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Price: Decimal,
    IsActive: Boolean DEFAULT true
);

The OR MODIFY variant is available for entities, enumerations, microflows, and pages. You’ll see it used throughout the tutorial.

Creating an Entity

Entities are the foundation of any Mendix application – they define your data model. In this page you’ll create a Product entity with several attributes, verify it, and then link it to another entity with an association.

Create a simple entity

The CREATE PERSISTENT ENTITY statement defines an entity that is stored in the database. Attributes go inside parentheses, separated by commas:

CREATE PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Price: Decimal,
    IsActive: Boolean DEFAULT true
);

Let’s break this down:

Run it from the command line:

mxcli -p app.mpr -c "CREATE PERSISTENT ENTITY MyModule.Product (Name: String(200) NOT NULL, Price: Decimal, IsActive: Boolean DEFAULT true);"

Or save it to a file and execute:

mxcli exec create-product.mdl -p app.mpr

Verify the entity

Use DESCRIBE ENTITY to confirm your entity was created correctly:

mxcli -p app.mpr -c "DESCRIBE ENTITY MyModule.Product"

This prints the full MDL definition of the entity, including all attributes and their types. You should see Name, Price, and IsActive listed.

Add an association

Associations link entities together. To connect Product to an existing Order entity, create a reference association:

CREATE ASSOCIATION MyModule.Order_Product
    FROM MyModule.Order TO MyModule.Product
    TYPE Reference;

This creates a many-to-one relationship: each Order can reference one Product. Use ReferenceSet instead of Reference for many-to-many.

The naming convention Order_Product follows Mendix best practices – the “from” entity name comes first, then the “to” entity.

Association types

Delete behavior

You can specify what happens when the “to” entity is deleted:

CREATE ASSOCIATION MyModule.Order_Product
    FROM MyModule.Order TO MyModule.Product
    TYPE Reference
    DELETE_BEHAVIOR PREVENT;

Options: PREVENT (block deletion if referenced), DELETE (cascade delete), or leave it out for the default behavior.

Using OR MODIFY for idempotent scripts

If you want to run the same script repeatedly without errors, use CREATE OR MODIFY:

CREATE OR MODIFY PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Price: Decimal,
    IsActive: Boolean DEFAULT true,
    Description: String(unlimited)
);

If the entity already exists, this updates it to match the new definition. If it doesn’t exist, it creates it. This is especially useful during iterative development.

More attribute types

Here’s a fuller example showing the attribute types you’ll use most often:

CREATE PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Description: String(unlimited),
    Price: Decimal,
    Quantity: Integer,
    Weight: Long,
    IsActive: Boolean DEFAULT true,
    CreatedDate: DateTime,
    Status: MyModule.ProductStatus
);

The last attribute references an enumeration (MyModule.ProductStatus). You’d create that separately:

CREATE ENUMERATION MyModule.ProductStatus (
    Active 'Active',
    Discontinued 'Discontinued',
    OutOfStock 'Out of Stock'
);

Extending a system entity

To create an entity that inherits from a system entity (like System.Image for file storage), use EXTENDS. Note that EXTENDS must come before the opening parenthesis:

-- Correct: EXTENDS before (
CREATE PERSISTENT ENTITY MyModule.ProductPhoto EXTENDS System.Image (
    PhotoCaption: String(200)
);

-- Wrong: EXTENDS after ( -- this will cause a parse error
CREATE PERSISTENT ENTITY MyModule.ProductPhoto (
    PhotoCaption: String(200)
) EXTENDS System.Image;

Common mistakes

String needs an explicit length. String alone is not valid – you must specify the maximum length:

-- Wrong
Name: String

-- Correct
Name: String(200)

-- For unlimited length
Description: String(unlimited)

EXTENDS must come before the parenthesis. See the example above. This is a common source of parse errors.

Module must exist. The module in the qualified name (e.g., MyModule in MyModule.Product) must already exist in the project. Check with SHOW MODULES.

Creating a Microflow

Microflows are the server-side logic of a Mendix application. They’re comparable to functions or methods in traditional programming. In this page you’ll create a microflow that accepts parameters, creates an object, commits it to the database, and returns it.

Create a simple microflow

This microflow takes a name and price, creates a Product object, commits it, and returns it:

CREATE MICROFLOW MyModule.CreateProduct(
    DECLARE $Name: String,
    DECLARE $Price: Decimal
)
RETURN MyModule.Product
BEGIN
    CREATE $Product: MyModule.Product (
        Name = $Name,
        Price = $Price,
        IsActive = true
    );
    COMMIT $Product;
    RETURN $Product;
END;

Let’s walk through each part:

Save this to a file (e.g., create-product-mf.mdl) and execute:

mxcli check create-product-mf.mdl
mxcli exec create-product-mf.mdl -p app.mpr

Verify the microflow

Use DESCRIBE MICROFLOW to see the generated MDL:

mxcli -p app.mpr -c "DESCRIBE MICROFLOW MyModule.CreateProduct"

This shows the full microflow definition, including parameters, activities, and the return type.

Understanding variables

All variables in MDL start with $. There are two contexts where you declare them:

Parameters (in the signature):

CREATE MICROFLOW MyModule.DoSomething(
    DECLARE $Customer: MyModule.Customer,
    DECLARE $Count: Integer
)

Local variables (inside BEGIN…END):

BEGIN
    DECLARE $Total: Integer = 0;
    DECLARE $Message: String = 'Processing...';
    DECLARE $Items: List of MyModule.Item = empty;
END;

For entity parameters, do not assign a default value – just declare the type:

-- Correct: entity parameter with no default
DECLARE $Customer: MyModule.Customer

-- Wrong: entity parameter with = empty
DECLARE $Customer: MyModule.Customer = empty

Retrieving objects

Use RETRIEVE to fetch objects from the database:

CREATE MICROFLOW MyModule.GetActiveProducts()
RETURN List of MyModule.Product
BEGIN
    RETRIEVE $Products: List of MyModule.Product
        FROM MyModule.Product
        WHERE IsActive = true;
    RETURN $Products;
END;

To retrieve a single object, add LIMIT 1:

RETRIEVE $Product: MyModule.Product
    FROM MyModule.Product
    WHERE Name = $SearchName
    LIMIT 1;

Conditional logic

Use IF ... THEN ... ELSE ... END IF for branching:

CREATE MICROFLOW MyModule.UpdateProductStatus(
    DECLARE $Product: MyModule.Product
)
RETURN Boolean
BEGIN
    IF $Product/Price > 0 THEN
        CHANGE $Product (IsActive = true);
        COMMIT $Product;
        RETURN true;
    ELSE
        LOG WARNING 'Product has no price set';
        RETURN false;
    END IF;
END;

Looping over a list

Use LOOP ... IN ... BEGIN ... END LOOP to iterate:

CREATE MICROFLOW MyModule.DeactivateProducts(
    DECLARE $Products: List of MyModule.Product
)
RETURN Boolean
BEGIN
    LOOP $Product IN $Products
    BEGIN
        CHANGE $Product (IsActive = false);
        COMMIT $Product;
    END LOOP;
    RETURN true;
END;

Note: the list $Products is a parameter. Never create an empty list variable and then loop over it – accept the list as a parameter instead.

Error handling

Add ON ERROR to handle failures on individual activities:

COMMIT $Product ON ERROR CONTINUE;

Options are CONTINUE (ignore the error and proceed), ROLLBACK (roll back the transaction and continue), or an inline error handler block:

COMMIT $Product ON ERROR {
    LOG ERROR 'Failed to commit product';
    RETURN false;
};

Organizing with folders

Place microflows in folders using the FOLDER keyword:

CREATE MICROFLOW MyModule.CreateProduct(
    DECLARE $Name: String,
    DECLARE $Price: Decimal
)
RETURN MyModule.Product
FOLDER 'ACT'
BEGIN
    CREATE $Product: MyModule.Product (
        Name = $Name,
        Price = $Price,
        IsActive = true
    );
    COMMIT $Product;
    RETURN $Product;
END;

This places the microflow in the ACT folder within the module, following the common Mendix convention of grouping microflows by type (ACT for actions, VAL for validations, SUB for sub-microflows).

Common mistakes

Every flow path must end with RETURN. If your microflow has IF/ELSE branches, each branch needs its own RETURN statement (or the return can come after END IF if both branches converge).

COMMIT is required to persist changes. CREATE and CHANGE only modify the object in memory. Without COMMIT, changes are lost when the microflow ends.

Entity parameters don’t use = empty. Declare them with just the type. Assigning = empty is for list variables inside the microflow body, not for parameters.

Creating a Page

Pages are the user interface of a Mendix application. In this page you’ll create an overview page that lists products in a data grid, and then an edit page with a form for modifying a single product.

Prerequisites

Before creating a page, you need two things:

1. An entity – the page needs data to display. We’ll use the MyModule.Product entity from the previous steps.
2. A layout – every page is placed inside a layout that provides the overall page structure (header, sidebar, content area). The layout must already exist in your project.

To see what layouts are available:

mxcli -p app.mpr -c "SHOW PAGES IN Atlas_Core"

Most Mendix projects based on Atlas UI have layouts like Atlas_Core.Atlas_Default (full page), Atlas_Core.PopupLayout (dialog), and others.

Create an overview page

An overview page typically shows a data grid that lists all objects of an entity:

CREATE PAGE MyModule.ProductOverview
    LAYOUT Atlas_Core.Atlas_Default
    TITLE 'Products'
(
    DATAGRID SOURCE DATABASE MyModule.Product (
        COLUMN Name,
        COLUMN Price,
        COLUMN IsActive
    )
);

Let’s break this down:

Execute it:

mxcli -p app.mpr -c "CREATE PAGE MyModule.ProductOverview LAYOUT Atlas_Core.Atlas_Default TITLE 'Products' (DATAGRID SOURCE DATABASE MyModule.Product (COLUMN Name, COLUMN Price, COLUMN IsActive));"

Or save to a file and run:

mxcli check create-pages.mdl
mxcli exec create-pages.mdl -p app.mpr

Verify the page

mxcli -p app.mpr -c "DESCRIBE PAGE MyModule.ProductOverview"

This prints the full page definition with all widgets and their properties.

Create an edit page

Edit pages use a DataView to display and edit a single object. The object is passed as a page parameter:

CREATE PAGE MyModule.Product_Edit
(
    Params: { $Product: MyModule.Product },
    Title: 'Edit Product',
    Layout: Atlas_Core.PopupLayout
)
{
    DATAVIEW dvProduct (DataSource: $Product) {
        TEXTBOX txtName (Label: 'Name', Attribute: Name)
        TEXTBOX txtPrice (Label: 'Price', Attribute: Price)
        CHECKBOX cbActive (Label: 'Active', Attribute: IsActive)

        FOOTER footer1 {
            ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
            ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
        }
    }
};

Key differences from the overview page:

Notice the two different page syntaxes: the overview page uses the compact syntax (LAYOUT and TITLE as keywords before parentheses), while the edit page uses the property syntax (properties inside a (Key: value) block followed by a { widget tree } block). Both are valid – use whichever fits better.

Widget reference

Here are the most commonly used widgets:

Input widgets

TEXTBOX txtName (Label: 'Name', Attribute: Name)
TEXTAREA txtDesc (Label: 'Description', Attribute: Description)
CHECKBOX cbActive (Label: 'Active', Attribute: IsActive)
DATEPICKER dpCreated (Label: 'Created', Attribute: CreatedDate)
COMBOBOX cbStatus (Label: 'Status', Attribute: Status)
RADIOBUTTONS rbType (Label: 'Type', Attribute: ProductType)

Display widgets

DYNAMICTEXT dynName (Attribute: Name)

Action buttons

ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
ACTIONBUTTON btnDelete (Caption: 'Delete', Action: DELETE, ButtonStyle: Danger)
ACTIONBUTTON btnProcess (Caption: 'Process', Action: MICROFLOW MyModule.ACT_ProcessProduct(Product: $Product))

Layout widgets

CONTAINER cntWrapper (Class: 'card') {
    -- child widgets go here
}

LAYOUTGRID lgMain {
    ROW r1 {
        COLUMN c1 (Weight: 6) { ... }
        COLUMN c2 (Weight: 6) { ... }
    }
}

Embedding a snippet

To reuse a page fragment, call a snippet:

SNIPPETCALL scProductCard (Snippet: MyModule.ProductCard)

The snippet must already exist in the project.

Common mistakes

Layout must exist in the project. If you specify a layout that doesn’t exist, the page will fail validation. Check available layouts with SHOW PAGES and look for documents of type Layout.

Widget names must be unique within a page. Every widget needs a name (e.g., txtName, btnSave), and these must not collide within the same page.

DataView needs a data source. A DataView must know where its data comes from – either a page parameter (DataSource: $Product), a microflow, or a nested context.

Validating with mxcli check

You’ve created entities, microflows, and pages. Before opening your project in Studio Pro, you should validate that everything is correct. mxcli provides three levels of validation, each catching different kinds of problems.

Level 1: Syntax check (no project needed)

The fastest check. It parses your MDL script and reports syntax errors without touching any .mpr file:

mxcli check script.mdl

This catches:

• Typos in keywords (CRETE instead of CREATE)
• Missing semicolons or parentheses
• Invalid attribute type syntax (String without a length)
• Anti-patterns like empty list variables used as loop sources
• Nested loops that should use RETRIEVE for lookups

You don’t even need a project file for this. It’s a pure syntax and structure check, so it runs instantly.

Checking inline commands

You can also check a single statement:

mxcli check -c "CREATE PERSISTENT ENTITY MyModule.Product (Name: String(200));"

Level 2: Syntax + reference validation

Add -p and --references to also verify that names in your script resolve to real elements in the project:

mxcli check script.mdl -p app.mpr --references

This catches everything Level 1 catches, plus:

• References to entities that don’t exist (MyModule.NonExistent)
• References to attributes that don’t exist on an entity
• Microflow calls to non-existent microflows
• Page layouts that don’t exist in the project
• Association endpoints pointing to missing entities

This is the check you should run before executing a script. It’s fast (reads the project but doesn’t modify it) and catches most mistakes.

Level 3: Full project validation with mx check

After executing your script, validate the entire project using the Mendix toolchain:

mxcli docker check -p app.mpr

This runs Mendix’s own mx check tool inside a Docker container. It performs the same validation that Studio Pro does when you open a project, catching issues that mxcli’s parser cannot detect:

• BSON serialization errors (malformed internal data)
• Security configuration problems (missing access rules, CE0066 errors)
• Widget definition mismatches (CE0463 errors)
• Missing required properties on widgets
• Broken cross-references between documents

The first time you run this, it will download the MxBuild toolchain for your project’s Mendix version. Subsequent runs reuse the cached download.

Without Docker

If you have mx installed locally (e.g., from a Mendix installation), you can run the check directly:

~/.mxcli/mxbuild/*/modeler/mx check app.mpr

Or use mxcli to auto-download and run it:

mxcli setup mxbuild -p app.mpr
~/.mxcli/mxbuild/*/modeler/mx check app.mpr

The recommended workflow

Here’s the workflow you should follow for every change:

Write MDL --> Check syntax --> Execute --> Docker check --> Open in Studio Pro

In practice:

# 1. Write your MDL in a script file
cat > changes.mdl << 'EOF'
CREATE OR MODIFY PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Price: Decimal,
    IsActive: Boolean DEFAULT true
);

CREATE OR MODIFY MICROFLOW MyModule.CreateProduct(
    DECLARE $Name: String,
    DECLARE $Price: Decimal
)
RETURN MyModule.Product
BEGIN
    CREATE $Product: MyModule.Product (
        Name = $Name,
        Price = $Price,
        IsActive = true
    );
    COMMIT $Product;
    RETURN $Product;
END;
EOF

# 2. Check syntax (fast, no project needed)
mxcli check changes.mdl

# 3. Check references (needs project, still fast)
mxcli check changes.mdl -p app.mpr --references

# 4. Execute against the project
mxcli exec changes.mdl -p app.mpr

# 5. Full validation
mxcli docker check -p app.mpr

# 6. Open in Studio Pro and verify visually

Previewing changes with diff

Before executing, you can preview what a script would change:

mxcli diff -p app.mpr changes.mdl

This compares the script against the current project state and shows what would be created, modified, or left unchanged. It does not modify the project.

What mxcli check catches automatically

Beyond basic syntax, mxcli check includes built-in anti-pattern detection:

Linting for deeper analysis

For a broader set of checks across the entire project (not just a single script), use the linter:

mxcli lint -p app.mpr

This runs 14 built-in rules plus 27 Starlark rules covering security, architecture, quality, and naming conventions. See mxcli lint --list-rules for the full list.

For CI/CD integration, output in SARIF format:

mxcli lint -p app.mpr --format sarif > results.sarif

Working with AI Assistants

mxcli is built from the ground up to work with AI coding assistants. The mxcli init command sets up your Mendix project with skills, configuration files, and a dev container so that AI tools can read and modify your project using MDL.

Why AI + MDL?

Mendix projects are stored in binary .mpr files. AI assistants cannot read or edit binary files directly. mxcli solves this by providing MDL – a text-based, SQL-like language that describes Mendix model elements. An AI assistant uses mxcli commands to explore the project, writes MDL scripts to make changes, validates them, and executes them against the .mpr file.

The result: you describe what you want in natural language, and the AI builds it in your Mendix project.

The token efficiency advantage

When working with AI APIs, context window size is a critical constraint. MDL’s compact syntax provides a significant advantage over JSON model representations:

Fewer tokens means lower API costs, more of your application fits in a single prompt, and the AI produces better results because there is less noise in the context.

Supported AI tools

mxcli supports five AI coding assistants out of the box, plus a universal format that works with any tool:

# List all supported tools
mxcli init --list-tools

How it works at a glance

The workflow is the same regardless of which AI tool you use:

1. Initialize – mxcli init creates config files, skills, and a dev container
2. Open in dev container – sandboxes the AI so it only accesses your project
3. Start the AI assistant – Claude Code, Cursor, Continue.dev, etc.
4. Ask for changes in natural language – “Create a Customer entity with name and email”
5. The AI explores – it runs SHOW, DESCRIBE, and SEARCH commands via mxcli
6. The AI writes MDL – guided by the skill files installed in your project
7. The AI validates – mxcli check catches syntax errors before anything is applied
8. The AI executes – the MDL script is run against your .mpr file
9. You review in Studio Pro – open the project and verify the result

The next pages cover each tool in detail, starting with Claude Code.

Claude Code Integration

Claude Code is the primary AI integration for mxcli. It gets the deepest support: a dedicated configuration directory, project-level context in CLAUDE.md, skill files that teach Claude MDL patterns, and slash commands for common operations.

Initializing a project

Claude Code is the default tool, so you don’t need to specify a flag:

mxcli init /path/to/my-mendix-project

This is equivalent to:

mxcli init --tool claude /path/to/my-mendix-project

What gets created

After running mxcli init, your project directory gains several new entries:

my-mendix-project/
├── CLAUDE.md                    # Project context for Claude Code
├── AGENTS.md                    # Universal AI assistant guide
├── .claude/
│   ├── settings.json            # Claude Code settings
│   ├── commands/                # Slash commands (/create-entity, etc.)
│   └── lint-rules/              # Starlark lint rules
├── .ai-context/
│   ├── skills/                  # MDL pattern guides (shared by all tools)
│   └── examples/                # Example MDL scripts
├── .devcontainer/
│   ├── devcontainer.json        # Dev container configuration
│   └── Dockerfile               # Container image with mxcli, JDK, Docker
├── mxcli                        # CLI binary (copied into project)
└── app.mpr                      # Your Mendix project (already existed)

CLAUDE.md

The CLAUDE.md file gives Claude Code project-level context. It describes what mxcli is, lists the available MDL commands, and tells Claude to read the skill files before writing MDL. This file is automatically read by Claude Code when it starts.

Skills

The .claude/skills/ directory (and .ai-context/skills/ for the universal copy) contains markdown files that teach Claude specific MDL patterns. For example, write-microflows.md explains microflow syntax, common mistakes, and a validation checklist. Claude reads the relevant skill before generating MDL, which dramatically improves output quality.

Commands

The .claude/commands/ directory contains slash commands that you can invoke from within Claude Code. These provide shortcuts for common operations.

Setting up the dev container

The dev container is the recommended way to work with Claude Code. It sandboxes the AI so it can only access your project files, and it comes pre-configured with everything you need.

What’s installed in the container

Opening the dev container

1. Open your project folder in VS Code
2. VS Code detects the .devcontainer/ directory and shows a notification
3. Click “Reopen in Container” (or use the command palette: Dev Containers: Reopen in Container)
4. Wait for the container to build (first time takes a few minutes)
5. Once inside the container, open a terminal

Starting Claude Code

With the dev container running, open a terminal in VS Code and start Claude:

claude

Claude Code now has access to your project files, the mxcli binary, and all the skill files. You can start asking it to do things.

How Claude works with your project

Claude follows a consistent pattern when you ask it to modify your Mendix project:

1. Explore

Claude uses mxcli commands to understand your project before making changes:

-- What modules exist?
SHOW MODULES;

-- What entities are in this module?
SHOW ENTITIES IN Sales;

-- What does this entity look like?
DESCRIBE ENTITY Sales.Customer;

-- What microflows exist?
SHOW MICROFLOWS IN Sales;

-- Search for something specific
SEARCH 'validation';

2. Read the relevant skill

Before writing MDL, Claude reads the appropriate skill file. If you ask for a microflow, it reads write-microflows.md. If you ask for a page, it reads create-page.md. The skills contain syntax references, examples, and validation checklists.

3. Write MDL

Claude generates an MDL script based on what it learned from the project and the skill files:

/** Customer master data */
@Position(100, 100)
CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200) NOT NULL,
    Email: String(200) NOT NULL,
    Phone: String(50),
    IsActive: Boolean DEFAULT true
);

4. Validate

Claude checks the script for syntax errors and reference issues:

./mxcli check script.mdl
./mxcli check script.mdl -p app.mpr --references

5. Execute

If validation passes, Claude runs the script against your project:

./mxcli -p app.mpr -c "EXECUTE SCRIPT 'script.mdl'"

6. Verify

Claude can run a full project check using the Mendix build tools:

./mxcli docker check -p app.mpr

Example interaction

Here is a typical conversation with Claude Code:

You: Create a Customer entity in the Sales module with name, email, and phone. Then create an overview page that shows all customers in a data grid.

Claude (explores the project):

./mxcli -p app.mpr -c "SHOW MODULES"
./mxcli -p app.mpr -c "SHOW ENTITIES IN Sales"
./mxcli -p app.mpr -c "SHOW PAGES IN Sales"

Claude (reads skills, writes MDL, validates, and executes):

/** Customer contact information */
@Position(100, 100)
CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200) NOT NULL,
    Email: String(200) NOT NULL,
    Phone: String(50),
    IsActive: Boolean DEFAULT true,
    CreatedAt: DateTime DEFAULT '[%CurrentDateTime%]'
);

/** Customer overview page with data grid */
CREATE PAGE Sales.Customer_Overview
(
  Title: 'Customers',
  Layout: Atlas_Core.Atlas_Default
)
{
  LAYOUTGRID mainGrid {
    ROW row1 {
      COLUMN col1 (DesktopWidth: 12) {
        DATAGRID dgCustomers (
          DataSource: DATABASE FROM Sales.Customer SORT BY Name ASC
        ) {
          COLUMN colName (Attribute: Name, Caption: 'Name')
          COLUMN colEmail (Attribute: Email, Caption: 'Email')
          COLUMN colPhone (Attribute: Phone, Caption: 'Phone')
          COLUMN colActive (Attribute: IsActive, Caption: 'Active')
        }
      }
    }
  }
}

Claude validates the script, executes it, and reports back. You can then open the project in Studio Pro to review the result.

Tips for working with Claude Code

• Be specific about module names. Say “Create a Customer entity in the Sales module” rather than just “Create a Customer entity.”
• Mention existing elements. If you want an association to an existing entity, name it: “Link Order to the existing Sales.Customer entity.”
• Let Claude explore first. If you’re asking for changes to an existing project, Claude will run SHOW and DESCRIBE commands to understand what’s already there. This leads to better results than trying to describe the current state yourself.
• Review in Studio Pro. After Claude makes changes, open the project in Studio Pro to verify everything looks right visually.
• Use mxcli docker check to catch issues that mxcli check alone might miss. The Mendix build tools perform deeper validation.

Next steps

If you use other AI tools alongside Claude Code, see Cursor / Continue.dev / Windsurf. To understand how skills work in detail, see Skills and CLAUDE.md.

Cursor / Continue.dev / Windsurf

Claude Code is the default integration, but mxcli also supports Cursor, Continue.dev, Windsurf, and Aider. Each tool gets its own configuration file that teaches the AI about MDL syntax and mxcli commands.

Initializing for a specific tool

Use the --tool flag to specify which AI tool you use:

# Cursor
mxcli init --tool cursor /path/to/my-mendix-project

# Continue.dev
mxcli init --tool continue /path/to/my-mendix-project

# Windsurf
mxcli init --tool windsurf /path/to/my-mendix-project

# Aider
mxcli init --tool aider /path/to/my-mendix-project

Setting up multiple tools

You can configure several tools at once. This is useful if different team members use different editors, or if you want to try several tools on the same project:

# Multiple tools
mxcli init --tool claude --tool cursor /path/to/my-mendix-project

# All supported tools at once
mxcli init --all-tools /path/to/my-mendix-project

Adding a tool to an existing project

If you already ran mxcli init and want to add support for another tool without re-initializing:

mxcli add-tool cursor
mxcli add-tool windsurf

This creates the tool-specific config file without touching the existing setup.

What each tool gets

Every tool gets the universal files that are always created:

On top of the universal files, each tool gets its own configuration:

Tool details

Cursor

Cursor reads its instructions from .cursorrules in the project root. The file mxcli generates contains a compact MDL syntax reference and a list of mxcli commands the AI can use. Cursor’s Composer and Chat features will reference this file automatically.

mxcli init --tool cursor /path/to/project

Created files:

• .cursorrules – MDL syntax, command reference, and conventions
• AGENTS.md – universal guide (Cursor also reads this)
• .ai-context/skills/ – shared skill files

To use: open the project in Cursor, then use Composer (Ctrl+I) or Chat (Ctrl+L) to ask for Mendix changes.

Continue.dev

Continue.dev uses a JSON configuration file with custom commands. The generated config tells Continue about mxcli and provides slash commands for common MDL operations.

mxcli init --tool continue /path/to/project

Created files:

• .continue/config.json – custom commands, slash command definitions
• AGENTS.md and .ai-context/skills/ – universal files

To use: open the project in VS Code with the Continue extension, then use the Continue sidebar to ask for changes.

Windsurf

Windsurf reads .windsurfrules from the project root. The generated file contains MDL rules and mxcli command documentation tailored for Codeium’s AI.

mxcli init --tool windsurf /path/to/project

Created files:

• .windsurfrules – MDL rules and command reference
• AGENTS.md and .ai-context/skills/ – universal files

To use: open the project in Windsurf, then use Cascade to ask for Mendix changes.

Aider

Aider is a terminal-based AI pair programming tool. The generated YAML config tells Aider about the project structure and available commands.

mxcli init --tool aider /path/to/project

Created files:

• .aider.conf.yml – Aider configuration
• AGENTS.md and .ai-context/skills/ – universal files

To use: run aider in the project directory from the terminal.

The universal format: AGENTS.md

Regardless of which tool you pick, mxcli always creates AGENTS.md and the .ai-context/ directory. These use a universal format that most AI tools understand:

• AGENTS.md is a comprehensive guide placed in the project root. It describes mxcli, lists MDL commands, and explains the development workflow. Many AI tools (GitHub Copilot, OpenAI Codex, and others) automatically read markdown files in the project root.
• .ai-context/skills/ contains the same skill files that Claude Code gets, but in the shared location. Any tool that can read project files can reference these.

This means even if your AI tool is not in the supported list, it can still benefit from mxcli init. The AGENTS.md file and skill directory provide enough context for any AI assistant to work with MDL.

Listing supported tools

To see all tools mxcli knows about:

mxcli init --list-tools

Next steps

To understand what the skill files contain and how they guide AI behavior, see Skills and CLAUDE.md.

Skills and CLAUDE.md

Skills are markdown files that teach AI assistants how to write correct MDL. Each skill covers a specific topic – creating pages, writing microflows, managing security – and contains syntax references, examples, and validation checklists. When an AI assistant needs to generate MDL, it reads the relevant skill first, which dramatically improves output quality.

Where skills live

Skills are installed in two locations:

Both directories contain the same files. The .claude/skills/ copy exists because Claude Code has a built-in mechanism for reading files from its .claude/ directory. The .ai-context/skills/ copy is the universal location that any AI tool can access.

Available skills

mxcli init installs the following skill files:

What a skill file contains

A typical skill file has four sections:

1. Syntax reference

The core MDL syntax for the topic, with all available options and keywords:

-- From write-microflows.md:
CREATE MICROFLOW Module.Name(
    $param: EntityType
) RETURNS ReturnType AS $result
BEGIN
    -- activities here
END;

2. Examples

Complete, working MDL examples that the AI can use as templates:

-- From create-page.md:
CREATE PAGE Sales.Customer_Overview
(
  Title: 'Customers',
  Layout: Atlas_Core.Atlas_Default
)
{
  DATAGRID dgCustomers (
    DataSource: DATABASE FROM Sales.Customer SORT BY Name ASC
  ) {
    COLUMN colName (Attribute: Name, Caption: 'Name')
  }
}

3. Common mistakes

A list of errors the AI should avoid. For example, write-microflows.md warns against creating empty list variables as loop sources, and create-page.md documents required widget properties that are easy to forget.

4. Validation checklist

Steps the AI should follow after writing MDL to confirm correctness:

# Syntax check (no project needed)
./mxcli check script.mdl

# Syntax + reference validation
./mxcli check script.mdl -p app.mpr --references

CLAUDE.md

The CLAUDE.md file is specific to Claude Code. It sits in the project root and is automatically read by Claude when it starts. It provides:

• Project overview – what the project is, which modules exist, and what mxcli is
• Available commands – a summary of mxcli commands Claude can use
• Rules – instructions like “always read the relevant skill file before writing MDL” and “always validate with mxcli check before executing”
• Conventions – project-specific naming conventions, module structure, etc.

Think of CLAUDE.md as the “system prompt” for Claude Code in the context of your project. It sets the tone and establishes guardrails.

AGENTS.md

AGENTS.md serves the same purpose as CLAUDE.md but in a universal format. It is always created by mxcli init, regardless of which tool you selected. AI tools that don’t have their own config format (or that read markdown files from the project root) will pick up AGENTS.md automatically.

Adding custom skills

You can create your own skill files to teach the AI about your project’s patterns and conventions. Add markdown files to .ai-context/skills/ (or .claude/skills/ for Claude Code):

.ai-context/skills/
├── write-microflows.md           # Built-in (installed by mxcli init)
├── create-page.md                # Built-in
├── our-naming-conventions.md     # Custom: your team's naming rules
├── order-processing-pattern.md   # Custom: how orders work in your app
└── api-integration-guide.md      # Custom: how to call external APIs

A custom skill file is just a markdown document. Write it the same way you would explain something to a new team member:

# Order Processing Pattern

When creating microflows that process orders in our application, follow these rules:

1. Always validate the order has at least one OrderLine
2. Use the Sales.OrderStatus enumeration for status tracking
3. Log to the 'OrderProcessing' node at INFO level
4. Send a confirmation email via Sales.SendNotification

## Example

\```sql
CREATE MICROFLOW Sales.ACT_Order_Submit($order: Sales.Order)
RETURNS Boolean AS $success
BEGIN
    -- validation, processing, notification...
END;
\```

The AI will read your custom skills alongside the built-in ones, learning your project’s specific patterns.

How the AI uses skills

The workflow is straightforward:

1. You ask for a change: “Create a page that shows all orders”
2. The AI determines which skill is relevant (in this case, create-page.md and overview-pages.md)
3. The AI reads the skill files
4. The AI writes MDL following the syntax and patterns in the skill
5. The AI validates with mxcli check
6. The AI executes the script

Skills act as a guardrail. Without them, AI assistants tend to guess at MDL syntax and get details wrong. With skills, the AI has a precise reference to follow, and the output is correct far more often.

Next steps

Now that you understand how skills guide AI behavior, see The MDL + AI Workflow for the complete recommended workflow from project initialization to review in Studio Pro.

The MDL + AI Workflow

This page walks through the complete recommended workflow for using mxcli with an AI assistant, from project setup to reviewing the result in Studio Pro.

The ten-step workflow

Step 1: Initialize the project

Start by running mxcli init on your Mendix project:

mxcli init /path/to/my-mendix-project

This creates the configuration files, skill documents, and dev container setup. If you use a tool other than Claude Code, specify it with --tool:

mxcli init --tool cursor /path/to/my-mendix-project

Step 2: Open in a dev container

Open the project folder in VS Code (or Cursor). VS Code will detect the .devcontainer/ directory and prompt you to reopen in a container. Click “Reopen in Container”.

The dev container provides a sandboxed environment where the AI assistant can only access your project files. It comes with mxcli, JDK, Docker, and your AI tool pre-installed.

Step 3: Start your AI assistant

Once inside the dev container, open a terminal and start your AI tool:

# Claude Code
claude

# Or use Cursor's Composer, Continue.dev's sidebar, etc.

Step 4: Describe what you want

Tell the AI what you need in plain language. Be specific about module names and mention existing elements:

“Create a Product entity in the Sales module with name, price, and description. Add an association to the existing Sales.Category entity.”

Better prompts lead to better results. A few tips:

• Name the module explicitly: “in the Sales module”
• Reference existing elements: “linked to the existing Customer entity”
• Describe the behavior, not the implementation: “a microflow that validates the email format” rather than “an IF statement that checks for @ and .”

Step 5: The AI explores your project

Before making changes, the AI uses mxcli to understand the current state of your project:

-- See what modules exist
SHOW MODULES;

-- Check what's already in the Sales module
SHOW STRUCTURE IN Sales;

-- Look at an existing entity for context
DESCRIBE ENTITY Sales.Category;

-- Search for related elements
SEARCH 'product';

This exploration step is important. The AI needs to know what entities, associations, and microflows already exist so it can write MDL that fits with your project.

Step 6: The AI writes MDL

Guided by the skill files and its exploration, the AI writes an MDL script:

/** Product catalog item */
@Position(300, 100)
CREATE PERSISTENT ENTITY Sales.Product (
    Name: String(200) NOT NULL,
    Description: String(0),
    Price: Decimal NOT NULL DEFAULT 0,
    IsActive: Boolean DEFAULT true
);

/** Link products to categories */
CREATE ASSOCIATION Sales.Product_Category
    FROM Sales.Product
    TO Sales.Category
    TYPE Reference
    OWNER Default;

Step 7: The AI validates

Before executing, the AI checks for errors:

# Check syntax
./mxcli check script.mdl

# Check syntax and verify that referenced elements exist
./mxcli check script.mdl -p app.mpr --references

If there are errors, the AI fixes them and re-validates. This cycle happens automatically – you don’t need to intervene.

Step 8: The AI executes

Once validation passes, the AI runs the script against your project:

./mxcli -p app.mpr -c "EXECUTE SCRIPT 'script.mdl'"

The changes are written directly to your .mpr file.

Step 9: Deep validation

For thorough validation, the AI can run the Mendix build tools:

./mxcli docker check -p app.mpr

This uses MxBuild (the same engine Studio Pro uses) to check the project for consistency errors, missing references, and other issues that mxcli check alone might miss.

Step 10: Review in Studio Pro

Open your project in Mendix Studio Pro to review the changes visually. Check that:

• Entities appear correctly in the domain model
• Pages render as expected
• Microflow logic looks right in the visual editor
• Security settings are correct

A complete example session

Here is what a full session looks like when you ask Claude Code to build a customer management feature:

You: “Create a customer management feature in the CRM module. I need a Customer entity with name, email, phone, and status. Create an overview page with a data grid and a popup edit form. Add a microflow that validates the email before saving.”

Claude Code:

1. Runs SHOW MODULES and SHOW ENTITIES IN CRM to understand the project
2. Reads generate-domain-model.md, overview-pages.md, and write-microflows.md skills
3. Writes a script with the entity, enumeration, pages, and microflow
4. Validates with mxcli check
5. Executes the script
6. Runs mxcli docker check to verify
7. Reports back with a summary of what was created

The entire interaction takes a few minutes. The equivalent work in Studio Pro would take considerably longer.

Tips for best results

Be specific about what exists

If you’re working with an existing project, mention the elements that are already there:

“Add a ShippingAddress field to the existing CRM.Customer entity and update the CRM.Customer_Edit page to include it.”

Let the AI explore

Don’t try to describe your entire project upfront. The AI is good at exploring. A prompt like “look at the Sales module and add a discount field to orders” is enough – the AI will figure out the entity name, existing fields, and page structure on its own.

Iterate

You don’t have to get everything right in one prompt. Start with the entity, review it, then ask for pages, then microflows. Small, focused requests tend to produce better results than one massive prompt.

Use mxcli docker check for final validation

mxcli check validates MDL syntax and references, but it doesn’t catch everything. The Mendix build tools (mxcli docker check) perform the same validation that Studio Pro does. Use it as a final gate before considering the work done.

Version control

Always work on a copy of your project or use version control. mxcli writes directly to your .mpr file. If something goes wrong, you want to be able to revert. For MPR v2 projects (Mendix 10.18+), the individual document files in mprcontents/ work well with Git.

Add custom skills for your project

If your project has specific patterns or conventions, write them down as skill files. For example, if every entity needs an audit trail (CreatedBy, CreatedAt, ChangedBy, ChangedAt), create a skill that documents this convention. The AI will follow it consistently.

MDL Basics

MDL (Mendix Definition Language) is a SQL-like language for reading and modifying Mendix application projects. It provides a text-based alternative to the visual editors in Mendix Studio Pro.

What MDL Looks Like

MDL uses familiar SQL-style syntax with Mendix-specific extensions. Here is a simple example that creates an entity with attributes:

CREATE PERSISTENT ENTITY Sales.Customer (
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  Name: String(200) NOT NULL,
  Email: String(200) UNIQUE,
  IsActive: Boolean DEFAULT TRUE
)
INDEX (Name);

Statement Termination

Statements are terminated with a semicolon (;) or a forward slash (/) on its own line (Oracle-style, useful for multi-line statements):

-- Semicolon terminator
CREATE MODULE OrderManagement;

-- Forward-slash terminator (useful for long statements)
CREATE PERSISTENT ENTITY Sales.Order (
  OrderId: AutoNumber NOT NULL UNIQUE,
  OrderDate: DateTime NOT NULL
)
INDEX (OrderDate DESC);
/

Simple commands such as HELP, EXIT, STATUS, SHOW, and DESCRIBE do not require a terminator.

Case Insensitivity

All MDL keywords are case-insensitive. The following are equivalent:

CREATE PERSISTENT ENTITY Sales.Customer ( ... );
create persistent entity Sales.Customer ( ... );
Create Persistent Entity Sales.Customer ( ... );

Identifiers (module names, entity names, attribute names) are case-sensitive and must match the Mendix model exactly.

Statement Categories

MDL statements fall into several categories:

Further Reading

• Lexical Structure – keywords, literals, and tokens
• Qualified Names – how elements are referenced
• Comments – comment syntax
• Script Files – running MDL from files

Lexical Structure

This page describes the tokens that make up the MDL language: keywords, literals, and identifiers.

Keywords

MDL keywords are case-insensitive. The following are reserved keywords:

ACCESS, ACTIONS, ADD, AFTER, ALL, ALTER, AND, ANNOTATION, AS, ASC,
ASCENDING, ASSOCIATION, AUTONUMBER, BATCH, BEFORE, BEGIN, BINARY,
BOOLEAN, BOTH, BUSINESS, BY, CALL, CANCEL, CAPTION, CASCADE,
CATALOG, CHANGE, CHILD, CLOSE, COLUMN, COMBOBOX, COMMIT, CONNECT,
CONFIGURATION, CONNECTOR, CONSTANT, CONSTRAINT, CONTAINER, CREATE,
CRUD, DATAGRID, DATAVIEW, DATE, DATETIME, DECLARE, DEFAULT, DELETE,
DELETE_BEHAVIOR, DELETE_BUT_KEEP_REFERENCES, DELETE_CASCADE, DEMO,
DEPTH, DESC, DESCENDING, DESCRIBE, DIFF, DISCONNECT, DROP, ELSE,
EMPTY, END, ENTITY, ENUMERATION, ERROR, EVENT, EVENTS, EXECUTE,
EXEC, EXIT, EXPORT, EXTENDS, EXTERNAL, FALSE, FOLDER, FOOTER,
FOR, FORMAT, FROM, FULL, GALLERY, GENERATE, GRANT, HEADER, HELP,
HOME, IF, IMPORT, IN, INDEX, INFO, INSERT, INTEGER, INTO, JAVA,
KEEP_REFERENCES, LABEL, LANGUAGE, LAYOUT, LAYOUTGRID, LEVEL, LIMIT,
LINK, LIST, LISTVIEW, LOCAL, LOG, LOGIN, LONG, LOOP, MANAGE, MAP,
MATRIX, MENU, MESSAGE, MICROFLOW, MICROFLOWS, MODEL, MODIFY, MODULE,
MODULES, MOVE, NANOFLOW, NANOFLOWS, NAVIGATION, NODE, NON_PERSISTENT,
NOT, NULL, OF, ON, OR, ORACLE, OVERVIEW, OWNER, PAGE, PAGES, PARENT,
PASSWORD, PERSISTENT, POSITION, POSTGRES, PRODUCTION, PROJECT,
PROTOTYPE, QUERY, QUIT, REFERENCE, REFERENCESET, REFRESH, REMOVE,
REPLACE, REPORT, RESPONSIVE, RETRIEVE, RETURN, REVOKE, ROLE, ROLES,
ROLLBACK, ROW, SAVE, SCRIPT, SEARCH, SECURITY, SELECTION, SET, SHOW,
SNIPPET, SNIPPETS, SQL, SQLSERVER, STATUS, STRING, STRUCTURE,
TABLES, TEXTBOX, TEXTAREA, THEN, TO, TRUE, TYPE, UNIQUE, UPDATE,
USER, VALIDATION, VALUE, VIEW, VIEWS, VISIBLE, WARNING, WHERE, WIDGET,
WIDGETS, WITH, WORKFLOWS, WRITE

Most keywords work unquoted as identifiers (entity names, attribute names). Only structural keywords like CREATE, DELETE, BEGIN, END, RETURN, ENTITY, and MODULE require quoting when used as identifiers.

Literals

String Literals

String literals use single quotes:

'single quoted string'
'it''s here'            -- doubled single quote to escape

The only escape sequence is '' (two single quotes) to represent a literal single quote. Backslash escaping is not supported.

Numeric Literals

42          -- Integer
3.14        -- Decimal
-100        -- Negative integer
1.5e10      -- Scientific notation

Boolean Literals

TRUE
FALSE

Quoted Identifiers

When an identifier collides with a reserved keyword, use double quotes (ANSI SQL style) or backticks (MySQL style):

"ComboBox"."CategoryTreeVE"
`Order`.`Status`
"ComboBox".CategoryTreeVE    -- mixed quoting is allowed

See Qualified Names for more on identifier syntax and the Module.Name notation.

Qualified Names

MDL uses dot-separated qualified names to reference elements within a Mendix project. This naming convention ensures elements are unambiguous across modules.

Simple Identifiers

Valid identifier characters:

• Letters: A-Z, a-z
• Digits: 0-9 (not as first character)
• Underscore: _

MyEntity
my_attribute
Attribute123

Qualified Name Format

The general format is Module.Element or Module.Entity.Attribute:

MyModule.Customer           -- Entity in module
MyModule.OrderStatus        -- Enumeration in module
MyModule.Customer.Name      -- Attribute in entity

Two-Part Names

Most elements use a two-part name: Module.ElementName.

Sales.Customer              -- entity
Sales.OrderStatus           -- enumeration
Sales.ACT_CreateOrder       -- microflow
Sales.Customer_Edit         -- page
Sales.Order_Customer        -- association

Three-Part Names

Attribute references use three parts: Module.Entity.Attribute.

Sales.Customer.Name         -- attribute on entity
Sales.Order.TotalAmount     -- attribute on entity

Quoting Rules

When a name segment is a reserved keyword, wrap it in double quotes or backticks:

"ComboBox"."CategoryTreeVE"
`Order`.`Status`

Mixed quoting is allowed – you only need to quote the segments that conflict:

"ComboBox".CategoryTreeVE
Sales."Order"

Identifiers that contain only letters, digits, and underscores (and do not start with a digit) never need quoting.

Usage in Statements

Qualified names appear throughout MDL:

-- Entity creation
CREATE PERSISTENT ENTITY Sales.Customer ( ... );

-- Association referencing two entities
CREATE ASSOCIATION Sales.Order_Customer
  FROM Sales.Customer
  TO Sales.Order
  TYPE Reference;

-- Enumeration reference in an attribute type
Status: Enumeration(Sales.OrderStatus) DEFAULT 'Active'

-- Microflow call
$Result = CALL MICROFLOW Sales.ACT_ProcessOrder ($Order = $Order);

See Also

• Lexical Structure – keywords and quoting
• Entities – entity qualified names
• Associations – association naming conventions

Comments and Documentation

MDL supports three comment styles for annotating scripts and attaching documentation to model elements.

Single-Line Comments

Use -- (SQL style) or // (C style) for single-line comments:

-- This is a single-line comment
SHOW MODULES

// This is also a single-line comment
SHOW ENTITIES IN Sales

Everything after the comment marker to the end of the line is ignored.

Multi-Line Comments

Use /* ... */ for comments that span multiple lines:

/* This comment spans
   multiple lines and is useful
   for longer explanations */
CREATE PERSISTENT ENTITY Sales.Customer (
  Name: String(200) NOT NULL
);

Documentation Comments

Use /** ... */ to attach documentation to model elements. Documentation comments are stored in the Mendix model and appear in Studio Pro:

/** Customer entity stores master customer data.
 *  Used by the Sales and Support modules.
 */
@Position(100, 200)
CREATE PERSISTENT ENTITY Sales.Customer (
  /** Unique customer identifier, auto-generated */
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,

  /** Full legal name of the customer */
  Name: String(200) NOT NULL,

  /** Primary contact email address */
  Email: String(200) UNIQUE
);

Documentation comments can be placed before:

• Entity definitions (becomes entity documentation)
• Attribute definitions (becomes attribute documentation)
• Enumeration definitions (becomes enumeration documentation)
• Association definitions (becomes association documentation)

Updating Documentation

You can also set documentation on existing entities with ALTER ENTITY:

ALTER ENTITY Sales.Customer
  SET DOCUMENTATION 'Customer master data for the Sales module';

Script Files

MDL statements can be saved in .mdl files and executed as scripts. This is the primary way to automate Mendix model changes.

File Format

• Extension: .mdl
• Encoding: UTF-8
• Statement termination: Semicolons (;) or forward slash (/) on its own line

A typical script file:

-- setup_domain_model.mdl
-- Creates the Sales domain model

CREATE ENUMERATION Sales.OrderStatus (
  Draft 'Draft',
  Pending 'Pending',
  Confirmed 'Confirmed',
  Shipped 'Shipped'
);

CREATE PERSISTENT ENTITY Sales.Customer (
  Name: String(200) NOT NULL,
  Email: String(200) UNIQUE
);

CREATE PERSISTENT ENTITY Sales.Order (
  OrderDate: DateTime NOT NULL,
  Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft'
);

CREATE ASSOCIATION Sales.Order_Customer
  FROM Sales.Customer
  TO Sales.Order
  TYPE Reference;

Executing Scripts

From the Command Line

Use mxcli exec to run a script against a project:

mxcli exec setup_domain_model.mdl -p /path/to/app.mpr

From the REPL

Use EXECUTE SCRIPT inside an interactive session:

CONNECT LOCAL '/path/to/app.mpr';
EXECUTE SCRIPT './scripts/setup_domain_model.mdl';

Syntax Checking

You can validate a script without connecting to a project:

# Syntax only
mxcli check script.mdl

# Syntax + reference validation (requires project)
mxcli check script.mdl -p app.mpr --references

Syntax checking catches parse errors, unknown keywords, and common anti-patterns before execution.

Comments in Scripts

Scripts support the same comment syntax as interactive MDL:

-- Single-line comment
/* Multi-line comment */
/** Documentation comment (attached to next element) */

Data Types

MDL has a type system that maps to the Mendix metamodel attribute types. Every attribute in an entity definition has a type that determines how values are stored and validated.

Type Categories

Quick Example

CREATE PERSISTENT ENTITY Demo.AllTypes (
  Id: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  Code: String(10) NOT NULL UNIQUE,
  Name: String(200) NOT NULL,
  Description: String(unlimited),
  Counter: Integer DEFAULT 0,
  BigNumber: Long,
  Amount: Decimal DEFAULT 0.00,
  IsActive: Boolean DEFAULT TRUE,
  CreatedAt: DateTime,
  BirthDate: Date,
  Attachment: Binary,
  Status: Enumeration(Demo.Status) DEFAULT 'Active'
);

No Implicit Conversions

MDL does not perform implicit type conversions. Types must match exactly when assigning defaults or modifying attributes.

Compatible type changes (when using CREATE OR MODIFY):

• String(100) to String(200) – increasing length
• Integer to Long – widening numeric type

Incompatible type changes:

• String to Integer
• Boolean to String
• Any type to AutoNumber (if data exists)

Further Reading

• Primitive Types – detailed reference for each type
• Constraints – NOT NULL, UNIQUE, DEFAULT
• Type Mapping – MDL to Mendix to database mapping
• Enumerations – enumeration type definitions

Primitive Types

This page documents each primitive type available for entity attributes in MDL.

String

Variable-length text data.

String              -- Default length (200)
String(n)           -- Specific length (1 to unlimited)
String(unlimited)   -- No length limit

Examples:

Name: String(200)
Description: String(unlimited)
Code: String(10)

Default value format:

Name: String(200) DEFAULT 'Unknown'
Code: String(10) DEFAULT ''

Integer

32-bit signed integer.

Integer

Range: -2,147,483,648 to 2,147,483,647

Quantity: Integer
Age: Integer DEFAULT 0
Priority: Integer NOT NULL DEFAULT 1

Long

64-bit signed integer.

Long

Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

FileSize: Long
TotalCount: Long DEFAULT 0

Decimal

High-precision decimal number with up to 20 digits total.

Decimal

Price: Decimal
Amount: Decimal DEFAULT 0
TaxRate: Decimal DEFAULT 0.21

Boolean

True/false value. Boolean attributes must have a DEFAULT value (enforced by Mendix Studio Pro).

Boolean DEFAULT TRUE
Boolean DEFAULT FALSE

IsActive: Boolean DEFAULT TRUE
Enabled: Boolean DEFAULT TRUE
Deleted: Boolean DEFAULT FALSE

DateTime

Date and time stored as a UTC timestamp.

DateTime

CreatedAt: DateTime
ModifiedAt: DateTime
ScheduledFor: DateTime

DateTime values include both date and time components. For date-only display, use Date instead.

Date

Date only (no time component). Internally stored as DateTime in Mendix, but the UI only shows the date portion.

Date

BirthDate: Date
ExpiryDate: Date

AutoNumber

Auto-incrementing integer, typically used for human-readable identifiers. The DEFAULT value specifies the starting number.

AutoNumber

OrderId: AutoNumber NOT NULL UNIQUE DEFAULT 1
CustomerId: AutoNumber

AutoNumber attributes automatically receive the next value on object creation. They are typically combined with NOT NULL and UNIQUE constraints.

Binary

Binary data for files, images, and other non-text content.

Binary

ProfileImage: Binary
Document: Binary
Thumbnail: Binary

File metadata (name, size, MIME type) is stored separately by Mendix. Maximum size is configurable per attribute.

HashedString

Securely hashed string, used for password storage. Values are one-way hashed and cannot be retrieved – comparison is done by hashing the input and comparing hashes.

HashedString

Password: HashedString

Enumeration Reference

References an enumeration type defined with CREATE ENUMERATION. See Enumerations for details.

Enumeration(<Module.EnumerationName>)

Status: Enumeration(Sales.OrderStatus)
Priority: Enumeration(Core.Priority) DEFAULT Core.Priority.Normal
Type: Enumeration(MyModule.ItemType) NOT NULL

Default value format:

-- Fully qualified (preferred)
DEFAULT Module.EnumName.ValueName

-- Legacy string literal form
DEFAULT 'ValueName'

See Also

• Data Types – type system overview
• Constraints – NOT NULL, UNIQUE, DEFAULT
• Type Mapping – MDL to Mendix to database mapping

Constraints

Constraints restrict the values an attribute can hold. They are specified after the type in an attribute definition.

Syntax

<name>: <type> [NOT NULL [ERROR '<message>']] [UNIQUE [ERROR '<message>']] [DEFAULT <value>]

Constraints must appear in this order:

1. NOT NULL (optionally with ERROR)
2. UNIQUE (optionally with ERROR)
3. DEFAULT

NOT NULL

Marks the attribute as required. The value cannot be empty.

Name: String(200) NOT NULL

With a custom error message displayed to the user:

Name: String(200) NOT NULL ERROR 'Name is required'

UNIQUE

Enforces that the value must be unique across all objects of the entity.

Email: String(200) UNIQUE

With a custom error message:

Email: String(200) UNIQUE ERROR 'Email already exists'

DEFAULT

Sets the initial value when a new object is created.

Count: Integer DEFAULT 0
IsActive: Boolean DEFAULT TRUE
Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft'
Name: String(200) DEFAULT 'Unknown'

Default value syntax varies by type:

Omitting the DEFAULT clause means no default value is set:

OptionalField: String(200)

Combining Constraints

All three constraints can be used together:

Email: String(200) NOT NULL ERROR 'Email is required'
                   UNIQUE ERROR 'Email already exists'
                   DEFAULT ''

More examples:

CREATE PERSISTENT ENTITY Sales.Product (
  -- Required only
  Name: String(200) NOT NULL,

  -- Required with custom error
  SKU: String(50) NOT NULL ERROR 'SKU is required for all products',

  -- Unique only
  Barcode: String(50) UNIQUE,

  -- Required and unique with custom errors
  ProductCode: String(20) NOT NULL ERROR 'Product code required'
                          UNIQUE ERROR 'Product code must be unique',

  -- Default only
  Quantity: Integer DEFAULT 0,

  -- No constraints
  Description: String(unlimited)
);

Validation Rule Mapping

Under the hood, constraints map to Mendix validation rules:

See Also

• Primitive Types – type reference
• Attributes – full attribute definition syntax
• ALTER ENTITY – modifying constraints on existing entities

Enumerations

Enumerations define a fixed set of named values. They are used as attribute types to restrict a field to a specific list of options.

CREATE ENUMERATION

[/** <documentation> */]
CREATE ENUMERATION <Module>.<Name> (
  <value-name> '<caption>' [, ...]
)

Each value has an identifier (used in code) and a caption (displayed in the UI):

/** Order status enumeration */
CREATE ENUMERATION Sales.OrderStatus (
  Draft 'Draft',
  Pending 'Pending Approval',
  Approved 'Approved',
  Shipped 'Shipped',
  Delivered 'Delivered',
  Cancelled 'Cancelled'
);

Using Enumerations in Attributes

Reference an enumeration type in an attribute definition with Enumeration(Module.Name):

CREATE PERSISTENT ENTITY Sales.Order (
  Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft',
  Priority: Enumeration(Core.Priority) NOT NULL
);

The default value is the name of the enumeration value (not the caption). The fully qualified form is preferred:

-- Fully qualified (preferred)
Status: Enumeration(Sales.OrderStatus) DEFAULT Sales.OrderStatus.Draft

-- Legacy string literal form
Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft'

ALTER ENUMERATION

Add or remove values from an existing enumeration:

-- Add a new value
ALTER ENUMERATION Sales.OrderStatus
  ADD VALUE OnHold 'On Hold';

-- Remove a value
ALTER ENUMERATION Sales.OrderStatus
  REMOVE VALUE Draft;

DROP ENUMERATION

Remove an enumeration entirely:

DROP ENUMERATION Sales.OrderStatus;

Dropping an enumeration that is still referenced by entity attributes will cause errors in Studio Pro.

See Also

• Primitive Types – all attribute types including enumeration references
• Data Types – type system overview
• Entities – using enumerations in entity definitions

Type Mapping

This page shows how MDL types correspond to Mendix internal types (BSON storage) and the Go SDK types used by modelsdk-go.

MDL to Backend Type Mapping

Note that Date and DateTime both map to the same underlying BSON type. The distinction is handled at the UI layer.

Default Value Mapping

Default values are stored in BSON as StoredValue structures:

All default values are serialized as strings in the BSON storage, regardless of the attribute type.

See Also

• Primitive Types – MDL type syntax and usage
• Data Types – type system overview

Domain Model

The domain model is the data layer of a Mendix application. It defines the entities (data tables), their attributes (columns), relationships between entities (associations), and inheritance hierarchies (generalizations).

Core Concepts

Module Scope

Every domain model element belongs to a module. Elements are always referenced by their qualified name in Module.Element format:

Sales.Customer           -- entity
Sales.OrderStatus        -- enumeration
Sales.Order_Customer     -- association

Complete Example

This example creates a small Sales domain model with related entities, an enumeration, and an association:

-- Enumeration for order statuses
CREATE ENUMERATION Sales.OrderStatus (
  Draft 'Draft',
  Pending 'Pending',
  Confirmed 'Confirmed',
  Shipped 'Shipped',
  Delivered 'Delivered',
  Cancelled 'Cancelled'
);

-- Customer entity
/** Customer master data */
@Position(100, 100)
CREATE PERSISTENT ENTITY Sales.Customer (
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  Name: String(200) NOT NULL ERROR 'Customer name is required',
  Email: String(200) UNIQUE ERROR 'Email already registered',
  Phone: String(50),
  IsActive: Boolean DEFAULT TRUE,
  CreatedAt: DateTime
)
INDEX (Name)
INDEX (Email);

-- Order entity
/** Sales order */
@Position(300, 100)
CREATE PERSISTENT ENTITY Sales.Order (
  OrderId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  OrderNumber: String(50) NOT NULL UNIQUE,
  OrderDate: DateTime NOT NULL,
  TotalAmount: Decimal DEFAULT 0,
  Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft',
  Notes: String(unlimited)
)
INDEX (OrderNumber)
INDEX (OrderDate DESC);

-- Association: Order belongs to Customer
CREATE ASSOCIATION Sales.Order_Customer
  FROM Sales.Customer
  TO Sales.Order
  TYPE Reference
  OWNER Default
  DELETE_BEHAVIOR DELETE_BUT_KEEP_REFERENCES;

Further Reading

• Entities – entity types and CREATE ENTITY syntax
• Attributes – attribute definitions and validation
• Associations – relationships between entities
• Generalization – entity inheritance
• Indexes – index creation
• Enumerations – enumeration types
• ALTER ENTITY – modifying existing entities

Entities

Entities are the primary data structures in a Mendix domain model. Each entity corresponds to a database table (for persistent entities) or an in-memory object (for non-persistent entities).

Entity Types

CREATE ENTITY

[/** <documentation> */]
[@Position(<x>, <y>)]
CREATE [OR MODIFY] <entity-type> ENTITY <Module>.<Name> (
  <attribute-definitions>
)
[INDEX (<column-list>)]
[;|/]

Persistent Entity

The most common type. Data is stored in the application database:

/** Customer entity */
@Position(100, 200)
CREATE PERSISTENT ENTITY Sales.Customer (
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  Name: String(200) NOT NULL ERROR 'Name is required',
  Email: String(200) UNIQUE ERROR 'Email must be unique',
  Balance: Decimal DEFAULT 0,
  IsActive: Boolean DEFAULT TRUE,
  CreatedDate: DateTime,
  Status: Enumeration(Sales.CustomerStatus) DEFAULT 'Active'
)
INDEX (Name)
INDEX (Email);

Non-Persistent Entity

Used for helper objects, filter parameters, and UI state that does not need database storage:

CREATE NON-PERSISTENT ENTITY Sales.CustomerFilter (
  SearchName: String(200),
  MinBalance: Decimal,
  MaxBalance: Decimal
);

View Entity

Defined by an OQL query. View entities are read-only:

CREATE VIEW ENTITY Reports.CustomerSummary (
  CustomerName: String,
  TotalOrders: Integer,
  TotalAmount: Decimal
) AS
  SELECT
    c.Name AS CustomerName,
    COUNT(o.OrderId) AS TotalOrders,
    SUM(o.Amount) AS TotalAmount
  FROM Sales.Customer c
  LEFT JOIN Sales.Order o ON o.Customer = c
  GROUP BY c.Name;

CREATE OR MODIFY

Creates the entity if it does not exist, or updates it if it does. New attributes are added; existing attributes are preserved:

CREATE OR MODIFY PERSISTENT ENTITY Sales.Customer (
  CustomerId: AutoNumber NOT NULL UNIQUE,
  Name: String(200) NOT NULL,
  Email: String(200),
  Phone: String(50)  -- new attribute added on modify
);

Annotations

@Position

Controls where the entity appears in the domain model diagram:

@Position(100, 200)
CREATE PERSISTENT ENTITY Sales.Customer ( ... );

Documentation

A /** ... */ comment before the entity becomes its documentation in Studio Pro:

/** Customer master data.
 *  Stores both active and inactive customers.
 */
CREATE PERSISTENT ENTITY Sales.Customer ( ... );

DROP ENTITY

Removes an entity from the domain model:

DROP ENTITY Sales.Customer;

See Also

• Attributes – attribute definitions within entities
• Indexes – adding indexes to entities
• Generalization – entity inheritance with EXTENDS
• ALTER ENTITY – modifying existing entities
• Associations – relationships between entities

Attributes and Validation Rules

Attributes define the fields on an entity. Each attribute has a name, a type, and optional constraints.

Attribute Syntax

[/** <documentation> */]
<name>: <type> [NOT NULL [ERROR '<message>']] [UNIQUE [ERROR '<message>']] [DEFAULT <value>]

Attribute Ordering

Attributes are listed in order, separated by commas. The last attribute has no trailing comma:

CREATE PERSISTENT ENTITY Module.Entity (
  FirstAttr: String(200),      -- comma after
  SecondAttr: Integer,         -- comma after
  LastAttr: Boolean DEFAULT FALSE  -- no comma
);

Validation Rules

Validation rules are expressed as attribute constraints. When validation fails, Mendix displays the error message (if provided) or a default message.

Example with Validation

CREATE PERSISTENT ENTITY Sales.Product (
  -- Required only
  Name: String(200) NOT NULL,

  -- Required with custom error
  SKU: String(50) NOT NULL ERROR 'SKU is required for all products',

  -- Unique only
  Barcode: String(50) UNIQUE,

  -- Required and unique with custom errors
  ProductCode: String(20) NOT NULL ERROR 'Product code required'
                          UNIQUE ERROR 'Product code must be unique',

  -- Optional field (no validation)
  Description: String(unlimited)
);

Documentation Comments

Attach documentation to individual attributes with /** ... */:

CREATE PERSISTENT ENTITY Sales.Customer (
  /** Unique customer identifier, auto-generated */
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,

  /** Full legal name of the customer */
  Name: String(200) NOT NULL,

  /** Primary contact email address */
  Email: String(200) UNIQUE
);

CALCULATED Attributes

An attribute can be marked as calculated, meaning its value is computed by a microflow rather than stored:

FullName: String(400) CALCULATED

Calculated attributes use a CALCULATED BY clause to specify the source microflow. See the MDL quick reference for details.

See Also

• Primitive Types – all available attribute types
• Constraints – NOT NULL, UNIQUE, DEFAULT in detail
• Entities – entity definitions that contain attributes
• ALTER ENTITY – adding and modifying attributes on existing entities

Associations

Associations define relationships between entities. They determine how objects reference each other and control behavior on deletion.

Association Types

CREATE ASSOCIATION

[/** <documentation> */]
CREATE ASSOCIATION <Module>.<Name>
  FROM <ParentEntity>
  TO <ChildEntity>
  TYPE <Reference|ReferenceSet>
  [OWNER <Default|Both|Parent|Child>]
  [DELETE_BEHAVIOR <behavior>]

Reference (Many-to-One)

A Reference association means each object on the FROM side can reference one object on the TO side. Multiple FROM objects can reference the same TO object.

/** Order belongs to Customer (many-to-one) */
CREATE ASSOCIATION Sales.Order_Customer
  FROM Sales.Customer
  TO Sales.Order
  TYPE Reference
  OWNER Default
  DELETE_BEHAVIOR DELETE_BUT_KEEP_REFERENCES;

ReferenceSet (Many-to-Many)

A ReferenceSet association allows multiple objects on both sides to reference each other:

/** Order has many Products (many-to-many) */
CREATE ASSOCIATION Sales.Order_Product
  FROM Sales.Order
  TO Sales.Product
  TYPE ReferenceSet
  OWNER Both;

Owner Options

The owner determines which side of the association can modify the reference.

Delete Behavior

Controls what happens when an associated object is deleted.

/** Invoice must be deleted with Order */
CREATE ASSOCIATION Sales.Order_Invoice
  FROM Sales.Order
  TO Sales.Invoice
  TYPE Reference
  DELETE_BEHAVIOR DELETE_CASCADE;

Naming Convention

Association names typically follow the pattern Module.FromEntity_ToEntity:

Sales.Order_Customer       -- Order references Customer
Sales.Order_Product        -- Order references Product
Sales.Order_Invoice        -- Order references Invoice

DROP ASSOCIATION

Remove an association:

DROP ASSOCIATION Sales.Order_Customer;

See Also

• Domain Model – overview of domain model concepts
• Entities – the entities that associations connect
• Generalization – inheritance (a different kind of relationship)

Generalization

Generalization (inheritance) allows an entity to extend another entity, inheriting all of its attributes and associations. The child entity can add its own attributes on top.

Syntax

CREATE PERSISTENT ENTITY <Module>.<Name>
  EXTENDS <ParentEntity>
(
  <additional-attributes>
);

Both EXTENDS (preferred) and GENERALIZATION (legacy) keywords are supported.

Examples

Extending System.User

The most common use of generalization is creating an application-specific user entity:

/** Employee extends User with additional fields */
CREATE PERSISTENT ENTITY HR.Employee EXTENDS System.User (
  EmployeeNumber: String(20) NOT NULL UNIQUE,
  Department: String(100),
  HireDate: Date
);

The HR.Employee entity inherits all attributes from System.User (Name, Password, etc.) and adds EmployeeNumber, Department, and HireDate.

Extending System.Image

For entities that store images:

/** Product photo entity */
CREATE PERSISTENT ENTITY Catalog.ProductPhoto EXTENDS System.Image (
  Caption: String(200),
  SortOrder: Integer DEFAULT 0
);

Extending System.FileDocument

For entities that store file attachments:

/** File attachment entity */
CREATE PERSISTENT ENTITY Docs.Attachment EXTENDS System.FileDocument (
  Description: String(500)
);

Common System Generalizations

Inheritance Rules

• A persistent entity can extend another persistent entity
• The child entity inherits all attributes and associations of the parent
• The child entity can add new attributes but cannot remove inherited ones
• Associations to the parent entity also apply to child objects
• Database queries on the parent entity include child objects

See Also

• Entities – entity types and CREATE ENTITY syntax
• Associations – relationships between entities
• Domain Model – domain model overview

Indexes

Indexes improve query performance for frequently searched or sorted attributes. They are defined after the attribute list in an entity definition.

Syntax

INDEX (<column> [ASC|DESC] [, <column> [ASC|DESC] ...])

Indexes are placed after the closing parenthesis of the attribute list:

CREATE PERSISTENT ENTITY Sales.Order (
  OrderId: AutoNumber NOT NULL UNIQUE,
  OrderNumber: String(50) NOT NULL,
  CustomerId: Long,
  OrderDate: DateTime,
  Status: Enumeration(Sales.OrderStatus)
)
-- Single column index
INDEX (OrderNumber)
-- Composite index with sort direction
INDEX (CustomerId, OrderDate DESC)
-- Another single column index
INDEX (Status);

Sort Direction

Each column in an index can specify a sort direction:

INDEX (Name)                    -- ascending (default)
INDEX (Name ASC)                -- explicit ascending
INDEX (CreatedAt DESC)          -- descending
INDEX (Name, CreatedAt DESC)    -- mixed: Name ascending, CreatedAt descending

Adding and Removing Indexes

Use ALTER ENTITY to add or remove indexes on existing entities:

-- Add an index
ALTER ENTITY Sales.Customer
  ADD INDEX (Email);

-- Remove an index
ALTER ENTITY Sales.Customer
  DROP INDEX (Email);

Guidelines

1. Primary lookups – index columns used in WHERE clauses
2. Foreign keys – index columns used in association joins
3. Sorting – index columns used in ORDER BY clauses
4. Composite order – put high-selectivity columns first in composite indexes

See Also

• Entities – entity definitions that contain indexes
• ALTER ENTITY – adding/removing indexes on existing entities

ALTER ENTITY

ALTER ENTITY modifies an existing entity’s attributes, indexes, or documentation without recreating it. This is useful for incremental changes to entities that already contain data.

ADD Attributes

Add one or more new attributes:

ALTER ENTITY Sales.Customer
  ADD (Phone: String(50), Notes: String(unlimited));

New attributes support the same constraints as in CREATE ENTITY:

ALTER ENTITY Sales.Customer
  ADD (
    LoyaltyPoints: Integer DEFAULT 0,
    MemberSince: DateTime NOT NULL
  );

DROP Attributes

Remove one or more attributes:

ALTER ENTITY Sales.Customer
  DROP (Notes);

Multiple attributes can be dropped at once:

ALTER ENTITY Sales.Customer
  DROP (Notes, TempField, OldStatus);

MODIFY Attributes

Change the type or constraints of existing attributes:

ALTER ENTITY Sales.Customer
  MODIFY (Name: String(400) NOT NULL);

RENAME Attributes

Rename an attribute:

ALTER ENTITY Sales.Customer
  RENAME Phone TO PhoneNumber;

ADD INDEX

Add an index to the entity:

ALTER ENTITY Sales.Customer
  ADD INDEX (Email);

Composite indexes:

ALTER ENTITY Sales.Customer
  ADD INDEX (Name, CreatedAt DESC);

DROP INDEX

Remove an index:

ALTER ENTITY Sales.Customer
  DROP INDEX (Email);

SET DOCUMENTATION

Update the entity’s documentation text:

ALTER ENTITY Sales.Customer
  SET DOCUMENTATION 'Customer master data for the Sales module';

Syntax Summary

ALTER ENTITY <Module>.<Entity>
  ADD (<attribute-definition> [, ...])

ALTER ENTITY <Module>.<Entity>
  DROP (<attribute-name> [, ...])

ALTER ENTITY <Module>.<Entity>
  MODIFY (<attribute-definition> [, ...])

ALTER ENTITY <Module>.<Entity>
  RENAME <old-name> TO <new-name>

ALTER ENTITY <Module>.<Entity>
  ADD INDEX (<column-list>)

ALTER ENTITY <Module>.<Entity>
  DROP INDEX (<column-list>)

ALTER ENTITY <Module>.<Entity>
  SET DOCUMENTATION '<text>'

See Also

• Entities – CREATE ENTITY syntax
• Attributes – attribute definition format
• Indexes – index creation and management
• Constraints – NOT NULL, UNIQUE, DEFAULT

Microflows and Nanoflows

Microflows and nanoflows are the primary logic constructs in Mendix applications. They define executable sequences of activities – retrieving data, creating objects, calling services, showing pages, and more. In MDL, you create and manage them with declarative SQL-like syntax.

What is a Microflow?

A microflow is a server-side logic flow. It executes on the Mendix runtime, has access to the database, can call external services, and supports transactions with error handling. Microflows are the workhorse of Mendix application logic.

Typical uses:

• CRUD operations (create, read, update, delete objects)
• Validation logic before saving
• Calling external web services or Java actions
• Batch processing and data transformations
• Scheduled event handlers

What is a Nanoflow?

A nanoflow is a client-side logic flow. It executes in the user’s browser (or on mobile devices), providing fast response times without server round-trips. Nanoflows have a more limited set of available activities – they cannot access the database directly or use Java actions.

Typical uses:

• Client-side validation
• Showing/closing pages
• Changing objects already in memory
• Calling nanoflows or microflows

Basic Syntax

Both microflows and nanoflows follow the same structural pattern in MDL:

CREATE MICROFLOW Module.ActionName
FOLDER 'OptionalFolder'
BEGIN
  -- parameters, variables, activities, return
END;

CREATE NANOFLOW Module.ClientAction
BEGIN
  -- activities (client-side subset)
END;

SHOW and DESCRIBE

List microflows and nanoflows in the project:

SHOW MICROFLOWS
SHOW MICROFLOWS IN MyModule
SHOW NANOFLOWS
SHOW NANOFLOWS IN MyModule

View the full MDL definition of an existing microflow or nanoflow (round-trippable output):

DESCRIBE MICROFLOW MyModule.ACT_CreateOrder
DESCRIBE NANOFLOW MyModule.NAV_ShowDetails

DROP

Remove a microflow or nanoflow:

DROP MICROFLOW MyModule.ACT_CreateOrder;
DROP NANOFLOW MyModule.NAV_ShowDetails;

OR REPLACE

Use CREATE OR REPLACE to overwrite an existing microflow or nanoflow if it already exists, or create it if it does not:

CREATE OR REPLACE MICROFLOW MyModule.ACT_CreateOrder
BEGIN
  -- updated logic
END;

Folder Organization

Place microflows and nanoflows into folders for project organization:

CREATE MICROFLOW Sales.ACT_CreateOrder
FOLDER 'Orders'
BEGIN
  -- ...
END;

Move an existing microflow to a different folder:

MOVE MICROFLOW Sales.ACT_CreateOrder TO FOLDER 'Orders/Actions';
MOVE NANOFLOW Sales.NAV_ShowDetail TO FOLDER 'Navigation';

Nested folders use / as the separator. Missing folders are created automatically.

Quick Example

CREATE MICROFLOW Sales.ACT_CreateOrder
FOLDER 'Orders'
BEGIN
  DECLARE $Order Sales.Order;
  $Order = CREATE Sales.Order (
    OrderDate = [%CurrentDateTime%],
    Status = 'Draft'
  );
  COMMIT $Order;
  SHOW PAGE Sales.Order_Edit ($Order = $Order);
  RETURN $Order;
END;

This microflow creates a new Order object with default values, commits it to the database, opens the edit page, and returns the new order.

Next Steps

• Structure – parameters, variables, return types, and the full CREATE MICROFLOW syntax
• Activity Types – all available activities (RETRIEVE, CREATE, CHANGE, COMMIT, DELETE, CALL, LOG, etc.)
• Control Flow – IF/ELSE, LOOP, WHILE, error handling
• Expressions – expression syntax for conditions and calculations
• Nanoflows vs Microflows – differences and nanoflow-specific syntax
• Common Patterns – CRUD, validation, batch processing, and anti-patterns to avoid

Structure

This page covers the structural elements of a microflow definition: the CREATE MICROFLOW syntax, parameters, variable declarations, return values, and annotations.

Full CREATE MICROFLOW Syntax

CREATE [OR REPLACE] MICROFLOW <Module.Name>
  [FOLDER '<path>']
BEGIN
  [<declarations>]
  [<activities>]
  [RETURN <value>;]
END;

The OR REPLACE modifier overwrites an existing microflow of the same name. The FOLDER clause organizes the microflow within the module’s folder structure.

Parameters

Parameters are declared with DECLARE at the top of the BEGIN...END block. They define the inputs to the microflow.

Primitive Parameters

DECLARE $Name String;
DECLARE $Count Integer;
DECLARE $IsActive Boolean;
DECLARE $Amount Decimal;
DECLARE $StartDate DateTime;

Supported primitive types: String, Integer, Long, Boolean, Decimal, DateTime.

Entity Parameters

Entity parameters receive a single object:

DECLARE $Customer MyModule.Customer;

Important: Do not use = empty or AS with entity declarations. The correct syntax is simply DECLARE $Var Module.Entity;.

List Parameters

List parameters receive a list of objects:

DECLARE $Orders List of Sales.Order = empty;

The = empty initializer creates an empty list. This is required for list declarations.

Parameter vs. Local Variable

In MDL, all DECLARE statements at the top of a microflow are treated as parameters. Variables created by activities (such as $Var = CREATE ... or RETRIEVE $Var ...) are local variables. If you need a local variable with a default value, use DECLARE followed by SET:

DECLARE $Counter Integer = 0;
SET $Counter = 10;

Variables and Assignment

Variable Declaration

DECLARE $Message String = 'Hello';
DECLARE $Total Decimal = 0;
DECLARE $Found Boolean = false;

Assignment with SET

Change the value of an already-declared variable:

SET $Counter = $Counter + 1;
SET $FullName = $FirstName + ' ' + $LastName;
SET $IsValid = $Amount > 0;

The variable must be declared before it can be assigned.

Variables from Activities

Activities like CREATE and RETRIEVE produce result variables:

$Order = CREATE Sales.Order (Status = 'New');
RETRIEVE $Customer FROM Sales.Customer WHERE Email = $Email LIMIT 1;
$Result = CALL MICROFLOW Sales.CalculateTotal (Order = $Order);

Return Values

Every flow path should end with a RETURN statement. The return type is inferred from the returned value.

Returning a Primitive

RETURN true;
RETURN $Total;
RETURN 'Success';

Returning an Object

RETURN $Order;

Returning a List

RETURN $FilteredOrders;

Returning Nothing

If the microflow returns nothing (void), you can omit the RETURN or use:

RETURN;

Annotations

Annotations are metadata decorators placed before an activity. They control visual layout and documentation in Mendix Studio Pro.

Position

Set the canvas position of the next activity:

@position(200, 100)
$Order = CREATE Sales.Order (Status = 'New');

Caption

Set a custom caption displayed on the activity in the canvas:

@caption 'Create new order'
$Order = CREATE Sales.Order (Status = 'New');

Color

Set the background color of the activity:

@color Green
COMMIT $Order;

Annotation (Visual Note)

Attach a visual annotation note to the next activity:

@annotation 'This step validates the input before saving'
VALIDATION FEEDBACK $Customer/Email MESSAGE 'Email is required';

Combining Annotations

Multiple annotations can be stacked before a single activity:

@position(300, 200)
@caption 'Validate and save'
@color Green
@annotation 'Final step: commit the validated order'
COMMIT $Order WITH EVENTS;

Complete Example

CREATE MICROFLOW Sales.ACT_ProcessOrder
FOLDER 'Orders/Processing'
BEGIN
  -- Parameters
  DECLARE $Order Sales.Order;
  DECLARE $ApplyDiscount Boolean;

  -- Local variable
  DECLARE $Total Decimal = 0;

  -- Retrieve order lines
  RETRIEVE $Lines FROM $Order/Sales.OrderLine_Order;

  -- Calculate total
  @caption 'Calculate total'
  $Total = CALL MICROFLOW Sales.SUB_CalculateTotal (
    OrderLines = $Lines
  );

  -- Apply discount if requested
  IF $ApplyDiscount THEN
    SET $Total = $Total * 0.9;
  END IF;

  -- Update order
  CHANGE $Order (
    TotalAmount = $Total,
    Status = 'Processed'
  );
  COMMIT $Order;

  RETURN $Order;
END;

Activity Types

This page documents every activity type available in MDL microflows. Activities are the individual steps that make up a microflow’s logic.

Object Operations

CREATE

Creates a new object of the specified entity type and assigns attribute values:

$Order = CREATE Sales.Order (
  OrderDate = [%CurrentDateTime%],
  Status = 'Draft',
  TotalAmount = 0
);

Attribute assignments are comma-separated Name = value pairs. The result is assigned to a variable.

CHANGE

Modifies attributes of an existing object:

CHANGE $Order (
  Status = 'Confirmed',
  TotalAmount = $CalculatedTotal
);

Multiple attributes can be changed in a single CHANGE statement.

COMMIT

Persists an object (or its changes) to the database:

COMMIT $Order;

Options:

• WITH EVENTS – triggers event handlers (before/after commit microflows)
• REFRESH – refreshes the object in the client after committing

COMMIT $Order WITH EVENTS;
COMMIT $Order REFRESH;
COMMIT $Order WITH EVENTS REFRESH;

DELETE

Deletes an object from the database:

DELETE $Order;

ROLLBACK

Reverts uncommitted changes to an object, restoring it to its last committed state:

ROLLBACK $Order;
ROLLBACK $Order REFRESH;

The REFRESH option refreshes the object in the client.

Retrieval

RETRIEVE from Database (XPath)

Retrieves objects from the database using an optional XPath-style WHERE clause:

-- Retrieve a single object
RETRIEVE $Customer FROM Sales.Customer
  WHERE Email = $InputEmail
  LIMIT 1;

-- Retrieve a list of objects
RETRIEVE $ActiveOrders FROM Sales.Order
  WHERE Status = 'Active';

-- Retrieve all objects of an entity
RETRIEVE $AllProducts FROM Sales.Product;

-- Retrieve with multiple conditions
RETRIEVE $RecentOrders FROM Sales.Order
  WHERE Status = 'Active'
  AND OrderDate > [%BeginOfCurrentDay%]
  LIMIT 50;

When LIMIT 1 is specified, the result is a single entity object. Otherwise, the result is a list.

RETRIEVE by Association

Retrieves objects by following an association from an existing object:

-- Retrieve related objects via association
RETRIEVE $Lines FROM $Order/Sales.OrderLine_Order;

-- Retrieve a single associated object
RETRIEVE $Customer FROM $Order/Sales.Order_Customer;

The association path uses the format $Variable/Module.AssociationName.

RETRIEVE from Variable List

Retrieves from an in-memory list variable:

RETRIEVE $Match FROM $CustomerList
  WHERE Email = $SearchEmail
  LIMIT 1;

Call Activities

CALL MICROFLOW

Calls another microflow, passing parameters and optionally receiving a return value:

-- Call with return value
$Total = CALL MICROFLOW Sales.SUB_CalculateTotal (
  OrderLines = $Lines
);

-- Call without return value
CALL MICROFLOW Sales.SUB_SendNotification (
  Customer = $Customer,
  Message = 'Order confirmed'
);

-- Call with no parameters
$Config = CALL MICROFLOW Admin.GetSystemConfig ();

CALL NANOFLOW

Calls a nanoflow from within a microflow:

$Result = CALL NANOFLOW MyModule.ValidateInput (
  InputValue = $Value
);

CALL JAVA ACTION

Calls a Java action:

$Hash = CALL JAVA ACTION MyModule.HashPassword (
  Password = $RawPassword
);

Java action parameters follow the same Name = value syntax.

UI Activities

SHOW PAGE

Opens a page, passing parameters:

SHOW PAGE Sales.Order_Edit ($Order = $Order);

The parameter syntax uses $PageParam = $MicroflowVar. Multiple parameters are comma-separated:

SHOW PAGE Sales.OrderDetail (
  $Order = $Order,
  $Customer = $Customer
);

An alternate syntax using colon notation is also supported:

SHOW PAGE Sales.Order_Edit (Order: $Order);

CLOSE PAGE

Closes the current page:

CLOSE PAGE;

Validation

VALIDATION FEEDBACK

Displays a validation error message on a specific attribute of an object:

VALIDATION FEEDBACK $Customer/Email MESSAGE 'Email address is required';
VALIDATION FEEDBACK $Order/TotalAmount MESSAGE 'Total must be greater than zero';

The syntax is VALIDATION FEEDBACK $Variable/AttributeName MESSAGE 'message text'.

Logging

LOG

Writes a message to the Mendix runtime log:

LOG INFO 'Order created successfully';
LOG WARNING 'Customer has no email address';
LOG ERROR 'Failed to process payment';

Log levels: INFO, WARNING, ERROR.

Optionally specify a log node name:

LOG INFO NODE 'OrderProcessing' 'Order created: ' + $Order/OrderNumber;
LOG ERROR NODE 'PaymentGateway' 'Payment failed for order ' + $Order/OrderNumber;

Database Query Execution

EXECUTE DATABASE QUERY

Executes a Database Connector query defined in the project:

-- Basic execution (3-part qualified name: Module.Connection.Query)
$Result = EXECUTE DATABASE QUERY MyModule.MyConn.GetCustomers;

-- Dynamic SQL query
$Result = EXECUTE DATABASE QUERY MyModule.MyConn.SearchQuery
  DYNAMIC 'SELECT * FROM customers WHERE name LIKE ?';

-- With parameters
$Result = EXECUTE DATABASE QUERY MyModule.MyConn.GetByEmail
  PARAMETERS ($EmailParam = $Email);

-- With runtime connection override
$Result = EXECUTE DATABASE QUERY MyModule.MyConn.GetData
  CONNECTION $RuntimeConnString;

The query name follows a three-part naming convention: Module.ConnectionName.QueryName.

Note: Error handling (ON ERROR) is not supported on EXECUTE DATABASE QUERY activities.

Summary Table

Control Flow

MDL microflows support conditional branching, loops, and error handling to control the execution path of your logic.

IF / ELSE

Conditional branching executes different activities based on a boolean expression.

Basic IF

IF $Order/TotalAmount > 1000 THEN
  CHANGE $Order (DiscountApplied = true);
END IF;

IF / ELSE

IF $Customer/Email != empty THEN
  CALL MICROFLOW Sales.SUB_SendEmail (Customer = $Customer);
ELSE
  LOG WARNING 'Customer has no email address';
END IF;

Nested IF

Since MDL does not support CASE/WHEN (switch statements), use nested IF...ELSE blocks:

IF $Order/Status = 'Draft' THEN
  CHANGE $Order (Status = 'Submitted');
ELSE
  IF $Order/Status = 'Submitted' THEN
    CHANGE $Order (Status = 'Approved');
  ELSE
    IF $Order/Status = 'Approved' THEN
      CHANGE $Order (Status = 'Shipped');
    ELSE
      LOG WARNING 'Unexpected order status: ' + $Order/Status;
    END IF;
  END IF;
END IF;

Complex Conditions

Conditions support AND, OR, and parentheses:

IF $Amount > 0 AND $Customer != empty THEN
  COMMIT $Order;
END IF;

IF ($Status = 'Active' OR $Status = 'Pending') AND $IsValid = true THEN
  CALL MICROFLOW Sales.ProcessOrder (Order = $Order);
END IF;

LOOP (FOR EACH)

Iterates over each item in a list:

LOOP $Line IN $OrderLines
BEGIN
  CHANGE $Line (
    LineTotal = $Line/Quantity * $Line/UnitPrice
  );
  COMMIT $Line;
END LOOP;

The loop variable ($Line) is automatically declared and takes the entity type of the list.

LOOP with Nested Logic

LOOP $Order IN $PendingOrders
BEGIN
  IF $Order/TotalAmount > 0 THEN
    CHANGE $Order (Status = 'Confirmed');
    COMMIT $Order;
  ELSE
    DELETE $Order;
  END IF;
END LOOP;

BREAK and CONTINUE

Use BREAK to exit a loop early, and CONTINUE to skip to the next iteration:

LOOP $Item IN $Items
BEGIN
  IF $Item/IsInvalid = true THEN
    CONTINUE;
  END IF;

  IF $Item/Type = 'StopSignal' THEN
    BREAK;
  END IF;

  CALL MICROFLOW Sales.ProcessItem (Item = $Item);
END LOOP;

WHILE Loop

Executes a block repeatedly as long as a condition remains true:

DECLARE $Counter Integer = 0;

WHILE $Counter < 10
BEGIN
  SET $Counter = $Counter + 1;
  LOG INFO 'Iteration: ' + toString($Counter);
END WHILE;

Caution: Ensure the condition will eventually become false to avoid infinite loops.

Error Handling

ON ERROR Suffix

Error handling is applied as a suffix to individual activities. There is no TRY...CATCH block in MDL. Instead, you specify error handling behavior on specific activities.

ON ERROR CONTINUE

Ignores the error and continues to the next activity:

COMMIT $Order ON ERROR CONTINUE;

ON ERROR ROLLBACK

Rolls back the current transaction and continues:

DELETE $Order ON ERROR ROLLBACK;

ON ERROR with Handler Block

Executes a custom error handling block when the activity fails:

COMMIT $Order ON ERROR {
  LOG ERROR 'Failed to commit order: ' + $Order/OrderNumber;
  ROLLBACK $Order;
};

The handler block can contain any activities – logging, rollback, showing validation messages, etc.

Error Handling Examples

-- Continue despite retrieval failure
RETRIEVE $Config FROM Admin.SystemConfig LIMIT 1 ON ERROR CONTINUE;

-- Custom error handler for external call
$Response = CALL MICROFLOW Integration.CallExternalAPI (
  Payload = $RequestBody
) ON ERROR {
  LOG ERROR NODE 'Integration' 'External API call failed';
  SET $Response = empty;
};

-- Rollback on commit failure
COMMIT $Order WITH EVENTS ON ERROR ROLLBACK;

Note: ON ERROR is not supported on EXECUTE DATABASE QUERY activities.

Unsupported Control Flow

The following constructs are not supported in MDL and will cause parse errors:

Complete Example

CREATE MICROFLOW Sales.ACT_ProcessBatch
FOLDER 'Batch'
BEGIN
  DECLARE $Orders List of Sales.Order = empty;
  DECLARE $SuccessCount Integer = 0;
  DECLARE $ErrorCount Integer = 0;

  RETRIEVE $Orders FROM Sales.Order
    WHERE Status = 'Pending';

  LOOP $Order IN $Orders
  BEGIN
    IF $Order/TotalAmount <= 0 THEN
      LOG WARNING 'Skipping order with zero amount: ' + $Order/OrderNumber;
      CONTINUE;
    END IF;

    @caption 'Process order'
    CALL MICROFLOW Sales.SUB_ProcessSingleOrder (
      Order = $Order
    ) ON ERROR {
      LOG ERROR 'Failed to process order: ' + $Order/OrderNumber;
      SET $ErrorCount = $ErrorCount + 1;
      CONTINUE;
    };

    SET $SuccessCount = $SuccessCount + 1;
  END LOOP;

  LOG INFO 'Batch complete: ' + toString($SuccessCount) + ' processed, '
    + toString($ErrorCount) + ' errors';
END;

Expressions

Expressions in MDL are used in conditions, attribute assignments, variable assignments, and log messages within microflows. They follow Mendix expression syntax.

Literals

String Literals

Strings are enclosed in single quotes:

'Hello, world'
'Order #1234'

To include a single quote within a string, double it:

'it''s here'
'Customer''s address'

Important: Do not use backslash escaping (\'). Mendix expression syntax requires doubled single quotes.

Numeric Literals

42          -- Integer
3.14        -- Decimal
-100        -- Negative integer
1.5e10      -- Scientific notation

Boolean Literals

true
false

Empty

The empty literal represents a null/undefined value:

DECLARE $List List of Sales.Order = empty;

IF $Customer = empty THEN
  LOG WARNING 'No customer found';
END IF;

Operators

Arithmetic Operators

String concatenation uses +:

SET $FullName = $FirstName + ' ' + $LastName;
LOG INFO 'Processing order: ' + $Order/OrderNumber;

Comparison Operators

Logical Operators

Parentheses control precedence:

IF ($Status = 'Active' OR $Status = 'Pending') AND $Amount > 0 THEN
  -- ...
END IF;

Attribute Access

Access attributes of an object variable with /:

$Order/TotalAmount
$Customer/Email
$Line/Quantity

This is used in conditions, assignments, and expressions:

IF $Order/TotalAmount > 1000 THEN
  SET $Discount = $Order/TotalAmount * 0.1;
END IF;

Date/Time Tokens

Mendix provides built-in date/time tokens enclosed in [% ... %]:

Usage in expressions:

$Order = CREATE Sales.Order (
  OrderDate = [%CurrentDateTime%],
  DueDate = [%EndOfCurrentDay%]
);

RETRIEVE $TodayOrders FROM Sales.Order
  WHERE OrderDate > [%BeginOfCurrentDay%];

String Templates

String concatenation with + is the primary way to build dynamic strings:

SET $Message = 'Order ' + $Order/OrderNumber + ' has been ' + $Order/Status;
LOG INFO NODE 'Orders' 'Total: ' + toString($Total) + ' for customer ' + $Customer/Name;

Type Conversion

Use built-in functions for type conversion in expressions:

toString($IntValue)           -- Integer/Decimal/Boolean to String

Enumeration Values

Reference enumeration values with their qualified name:

$Order = CREATE Sales.Order (
  Status = Sales.OrderStatus.Draft
);

IF $Order/Status = Sales.OrderStatus.Confirmed THEN
  -- process confirmed order
END IF;

Alternatively, enumeration values can be referenced as plain strings when the context is unambiguous:

$Order = CREATE Sales.Order (
  Status = 'Draft'
);

Expression Contexts

Expressions appear in several places within microflow activities:

In Conditions (IF, WHILE, WHERE)

IF $Order/TotalAmount > 0 AND $Order/Status != 'Cancelled' THEN ...
WHILE $Counter < $MaxRetries BEGIN ... END WHILE;
RETRIEVE $Active FROM Sales.Order WHERE Status = 'Active';

In Attribute Assignments (CREATE, CHANGE)

$Order = CREATE Sales.Order (
  OrderDate = [%CurrentDateTime%],
  Description = 'Order for ' + $Customer/Name,
  TotalAmount = $Subtotal + $Tax
);

In SET Assignments

SET $Counter = $Counter + 1;
SET $IsEligible = $Customer/Age >= 18 AND $Customer/IsActive;
SET $FullName = $Customer/FirstName + ' ' + $Customer/LastName;

In LOG Messages

LOG INFO 'Processed ' + toString($Count) + ' orders';
LOG ERROR NODE 'Validation' 'Invalid amount: ' + toString($Order/TotalAmount);

In VALIDATION FEEDBACK Messages

VALIDATION FEEDBACK $Customer/Email MESSAGE 'Please provide a valid email address';

Nanoflows vs Microflows

Nanoflows are client-side logic flows that execute in the user’s browser or on mobile devices. They share the same MDL syntax as microflows but have a different set of capabilities and restrictions.

Key Differences

When to Use Which

Use a microflow when you need to:

• Retrieve data from or commit data to the database
• Call external web services or REST APIs
• Execute Java actions
• Perform batch operations on large data sets
• Use transactions with rollback support

Use a nanoflow when you need to:

• Respond quickly to user actions without server delay
• Perform client-side validation
• Toggle UI state (show/hide elements)
• Navigate between pages
• Work offline on mobile devices

CREATE NANOFLOW Syntax

CREATE [OR REPLACE] NANOFLOW <Module.Name>
  [FOLDER '<path>']
BEGIN
  [<declarations>]
  [<activities>]
  [RETURN <value>;]
END;

The syntax is identical to CREATE MICROFLOW except for the keyword.

Supported Activities in Nanoflows

Object Operations

-- Create an object (in memory only)
$Item = CREATE Sales.CartItem (
  Quantity = 1,
  ProductName = $Product/Name
);

-- Change an object in memory
CHANGE $Item (Quantity = $Item/Quantity + 1);

Calling Other Flows

-- Call another nanoflow
$Result = CALL NANOFLOW Sales.NAV_ValidateCart (Cart = $Cart);

-- Call a microflow (triggers server round-trip)
$ServerResult = CALL MICROFLOW Sales.ACT_SubmitOrder (Order = $Order);

UI Activities

-- Show a page
SHOW PAGE Sales.CartDetail ($Cart = $Cart);

-- Close the current page
CLOSE PAGE;

Validation

VALIDATION FEEDBACK $Item/Quantity MESSAGE 'Quantity must be at least 1';

Logging

LOG INFO 'Cart updated with ' + toString($ItemCount) + ' items';

Control Flow

IF $Cart/ItemCount = 0 THEN
  VALIDATION FEEDBACK $Cart/ItemCount MESSAGE 'Cart is empty';
  RETURN false;
ELSE
  SHOW PAGE Sales.Checkout ($Cart = $Cart);
  RETURN true;
END IF;

Activities NOT Available in Nanoflows

The following activities are server-only and cannot be used in nanoflows:

• RETRIEVE ... FROM Module.Entity WHERE ... (database retrieval)
• COMMIT
• DELETE
• ROLLBACK
• CALL JAVA ACTION
• EXECUTE DATABASE QUERY
• ON ERROR { ... } (full error handler blocks)

SHOW and DESCRIBE

SHOW NANOFLOWS
SHOW NANOFLOWS IN MyModule
DESCRIBE NANOFLOW MyModule.NAV_ShowDetails

DROP

DROP NANOFLOW MyModule.NAV_ShowDetails;

Folder Organization

CREATE NANOFLOW Sales.NAV_OpenCart
FOLDER 'Navigation'
BEGIN
  SHOW PAGE Sales.Cart_Overview ();
END;

MOVE NANOFLOW Sales.NAV_OpenCart TO FOLDER 'UI/Navigation';

Example: Client-Side Validation

CREATE NANOFLOW Sales.NAV_ValidateOrder
FOLDER 'Validation'
BEGIN
  DECLARE $Order Sales.Order;
  DECLARE $IsValid Boolean = true;

  IF $Order/CustomerName = empty THEN
    VALIDATION FEEDBACK $Order/CustomerName MESSAGE 'Customer name is required';
    SET $IsValid = false;
  END IF;

  IF $Order/TotalAmount <= 0 THEN
    VALIDATION FEEDBACK $Order/TotalAmount MESSAGE 'Total must be greater than zero';
    SET $IsValid = false;
  END IF;

  RETURN $IsValid;
END;

Example: Page Navigation

CREATE NANOFLOW Sales.NAV_GoToOrderDetail
BEGIN
  DECLARE $Order Sales.Order;

  SHOW PAGE Sales.Order_Detail ($Order = $Order);
END;

Common Patterns

This page shows frequently used microflow patterns in MDL, including CRUD operations, validation, batch processing, and important anti-patterns to avoid.

CRUD Patterns

Create and Commit

CREATE MICROFLOW Sales.ACT_CreateCustomer
FOLDER 'Customer'
BEGIN
  DECLARE $Name String;
  DECLARE $Email String;
  DECLARE $Customer Sales.Customer;

  $Customer = CREATE Sales.Customer (
    Name = $Name,
    Email = $Email,
    CreatedDate = [%CurrentDateTime%],
    IsActive = true
  );
  COMMIT $Customer;

  SHOW PAGE Sales.Customer_Edit ($Customer = $Customer);
  RETURN $Customer;
END;

Retrieve and Update

CREATE MICROFLOW Sales.ACT_DeactivateCustomer
FOLDER 'Customer'
BEGIN
  DECLARE $Customer Sales.Customer;

  CHANGE $Customer (
    IsActive = false,
    DeactivatedDate = [%CurrentDateTime%]
  );
  COMMIT $Customer;
END;

Retrieve with Filtering

CREATE MICROFLOW Sales.ACT_GetActiveOrders
FOLDER 'Orders'
BEGIN
  RETRIEVE $Orders FROM Sales.Order
    WHERE Status = 'Active'
    AND OrderDate > [%BeginOfCurrentMonth%];

  RETURN $Orders;
END;

Delete with Confirmation

CREATE MICROFLOW Sales.ACT_DeleteOrder
FOLDER 'Orders'
BEGIN
  DECLARE $Order Sales.Order;

  -- Delete related order lines first
  RETRIEVE $Lines FROM $Order/Sales.OrderLine_Order;
  LOOP $Line IN $Lines
  BEGIN
    DELETE $Line;
  END LOOP;

  DELETE $Order;
END;

Validation Pattern

Validate an object before saving, showing feedback on invalid fields:

CREATE MICROFLOW Sales.ACT_SaveCustomer
FOLDER 'Customer'
BEGIN
  DECLARE $Customer Sales.Customer;
  DECLARE $IsValid Boolean = true;

  -- Validate required fields
  IF $Customer/Name = empty THEN
    VALIDATION FEEDBACK $Customer/Name MESSAGE 'Name is required';
    SET $IsValid = false;
  END IF;

  IF $Customer/Email = empty THEN
    VALIDATION FEEDBACK $Customer/Email MESSAGE 'Email is required';
    SET $IsValid = false;
  END IF;

  -- Check for duplicate email
  IF $IsValid THEN
    RETRIEVE $Existing FROM Sales.Customer
      WHERE Email = $Customer/Email
      LIMIT 1;
    IF $Existing != empty THEN
      VALIDATION FEEDBACK $Customer/Email MESSAGE 'A customer with this email already exists';
      SET $IsValid = false;
    END IF;
  END IF;

  -- Save only if valid
  IF $IsValid THEN
    COMMIT $Customer;
    CLOSE PAGE;
  END IF;
END;

Batch Processing Pattern

Process a list of items one at a time with error tracking:

CREATE MICROFLOW Sales.ACT_ProcessPendingOrders
FOLDER 'Batch'
BEGIN
  DECLARE $SuccessCount Integer = 0;
  DECLARE $ErrorCount Integer = 0;

  RETRIEVE $PendingOrders FROM Sales.Order
    WHERE Status = 'Pending';

  LOOP $Order IN $PendingOrders
  BEGIN
    CALL MICROFLOW Sales.SUB_ProcessOrder (
      Order = $Order
    ) ON ERROR {
      LOG ERROR NODE 'BatchProcess' 'Failed to process order: ' + $Order/OrderNumber;
      SET $ErrorCount = $ErrorCount + 1;
      CONTINUE;
    };

    SET $SuccessCount = $SuccessCount + 1;
  END LOOP;

  LOG INFO NODE 'BatchProcess' 'Batch complete: '
    + toString($SuccessCount) + ' succeeded, '
    + toString($ErrorCount) + ' failed';
END;

Sub-Microflow Pattern

Break complex logic into reusable sub-microflows:

-- Main microflow delegates to sub-microflow
CREATE MICROFLOW Sales.ACT_PlaceOrder
FOLDER 'Orders'
BEGIN
  DECLARE $Order Sales.Order;

  -- Validate
  $IsValid = CALL MICROFLOW Sales.SUB_ValidateOrder (Order = $Order);
  IF NOT $IsValid THEN
    RETURN false;
  END IF;

  -- Calculate totals
  CALL MICROFLOW Sales.SUB_CalculateOrderTotals (Order = $Order);

  -- Finalize
  CHANGE $Order (Status = 'Placed');
  COMMIT $Order WITH EVENTS;

  RETURN true;
END;

-- Reusable sub-microflow
CREATE MICROFLOW Sales.SUB_CalculateOrderTotals
FOLDER 'Orders'
BEGIN
  DECLARE $Order Sales.Order;
  DECLARE $Total Decimal = 0;

  RETRIEVE $Lines FROM $Order/Sales.OrderLine_Order;
  LOOP $Line IN $Lines
  BEGIN
    SET $Total = $Total + ($Line/Quantity * $Line/UnitPrice);
  END LOOP;

  CHANGE $Order (TotalAmount = $Total);
END;

Association Retrieval Pattern

Retrieve related objects through associations:

CREATE MICROFLOW Sales.ACT_GetOrderSummary
FOLDER 'Orders'
BEGIN
  DECLARE $Order Sales.Order;

  -- Retrieve related customer
  RETRIEVE $Customer FROM $Order/Sales.Order_Customer;

  -- Retrieve order lines
  RETRIEVE $Lines FROM $Order/Sales.OrderLine_Order;

  -- Use the retrieved data
  LOG INFO 'Order ' + $Order/OrderNumber
    + ' for customer ' + $Customer/Name
    + ' has ' + toString(length($Lines)) + ' lines';

  RETURN $Order;
END;

Lookup Pattern (List Search)

When you have a list and need to find a matching item, retrieve from the list variable:

CREATE MICROFLOW Import.ACT_MatchDepartments
FOLDER 'Import'
BEGIN
  DECLARE $Employees List of Import.Employee = empty;
  DECLARE $Departments List of Import.Department = empty;

  -- Retrieve all departments for lookup
  RETRIEVE $Departments FROM Import.Department;

  LOOP $Employee IN $Employees
  BEGIN
    -- O(N) lookup: retrieve from in-memory list
    RETRIEVE $Dept FROM $Departments
      WHERE Name = $Employee/DepartmentName
      LIMIT 1;

    IF $Dept != empty THEN
      CHANGE $Employee (Employee_Department = $Dept);
      COMMIT $Employee;
    END IF;
  END LOOP;
END;

Error Handling Pattern

Wrap risky operations with error handlers:

CREATE MICROFLOW Integration.ACT_SyncData
FOLDER 'Integration'
BEGIN
  DECLARE $Config Integration.SyncConfig;
  DECLARE $Success Boolean = false;

  RETRIEVE $Config FROM Integration.SyncConfig LIMIT 1;

  @caption 'Call external API'
  $Response = CALL MICROFLOW Integration.SUB_CallExternalAPI (
    Config = $Config
  ) ON ERROR {
    LOG ERROR NODE 'Integration' 'External API call failed';
    RETURN false;
  };

  IF $Response != empty THEN
    @caption 'Process response'
    CALL MICROFLOW Integration.SUB_ProcessResponse (
      Response = $Response
    ) ON ERROR {
      LOG ERROR NODE 'Integration' 'Failed to process response';
      RETURN false;
    };
    SET $Success = true;
  END IF;

  RETURN $Success;
END;

Anti-Patterns (Avoid These)

The following patterns are common mistakes that cause bugs, performance problems, or parse errors. The mxcli check command detects these automatically.

Never Create Empty List Variables as Loop Sources

Creating an empty list and then immediately looping over it is always wrong. If you need to process a list, accept it as a microflow parameter or retrieve it from the database.

-- WRONG: empty list means the loop never executes
DECLARE $Items List of Sales.Item = empty;
LOOP $Item IN $Items
BEGIN
  -- this code never runs!
END LOOP;

-- CORRECT: accept the list as a parameter
CREATE MICROFLOW Sales.ACT_ProcessItems
BEGIN
  DECLARE $Items List of Sales.Item = empty;  -- parameter, filled by caller

  RETRIEVE $Items FROM Sales.Item WHERE Status = 'Pending';  -- or retrieve from DB

  LOOP $Item IN $Items
  BEGIN
    -- process each item
  END LOOP;
END;

Never Use Nested Loops for List Matching

Nested loops are O(N^2) and cause severe performance problems with large data sets. Instead, loop over the primary list and use RETRIEVE ... FROM $List WHERE ... LIMIT 1 to find matches.

-- WRONG: O(N^2) nested loop
LOOP $Employee IN $Employees
BEGIN
  LOOP $Department IN $Departments
  BEGIN
    IF $Department/Name = $Employee/DeptName THEN
      CHANGE $Employee (Employee_Department = $Department);
    END IF;
  END LOOP;
END LOOP;

-- CORRECT: O(N) lookup from list
LOOP $Employee IN $Employees
BEGIN
  RETRIEVE $Dept FROM $Departments
    WHERE Name = $Employee/DeptName
    LIMIT 1;

  IF $Dept != empty THEN
    CHANGE $Employee (Employee_Department = $Dept);
  END IF;
END LOOP;

Use Append Logic When Merging, Not Overwrite

When merging data from multiple sources, append new values rather than overwriting existing ones:

-- WRONG: overwrites existing notes
CHANGE $Customer (Notes = $NewNotes);

-- CORRECT: append with guard
IF $NewNotes != empty THEN
  CHANGE $Customer (Notes = $Customer/Notes + '\n' + $NewNotes);
END IF;

Naming Conventions

Follow consistent naming patterns for microflows:

Validation Checklist

Before presenting a microflow to the user, verify these rules:

1. Every DECLARE has a valid type (String, Integer, Boolean, Decimal, DateTime, Module.Entity, or List of Module.Entity)
2. Entity declarations do not use = empty (only list declarations do)
3. Every flow path ends with a RETURN statement (or the microflow returns void)
4. No empty list variables are used as loop sources
5. No nested loops for list matching
6. All entity and microflow qualified names use the Module.Name format
7. VALIDATION FEEDBACK uses the $Variable/Attribute MESSAGE 'text' syntax

Run the syntax checker to catch issues:

mxcli check script.mdl
mxcli check script.mdl -p app.mpr --references

Pages

Pages define the user interface of a Mendix application. Each page consists of a widget tree arranged within a layout, with data sources that connect widgets to the domain model.

Core Concepts

CREATE PAGE

The basic syntax for creating a page:

CREATE [OR REPLACE] PAGE <Module>.<Name>
(
  [Params: { $Param: Module.Entity [, ...] },]
  Title: '<title>',
  Layout: <Module.LayoutName>
  [, Folder: '<path>']
)
{
  <widget-tree>
}

Minimal Example

CREATE PAGE MyModule.Home
(
  Title: 'Welcome',
  Layout: Atlas_Core.Atlas_Default
)
{
  CONTAINER cMain {
    DYNAMICTEXT txtWelcome (Content: 'Welcome to the application')
  }
}

Page with Parameters

Pages can receive entity objects as parameters from the calling context:

CREATE PAGE MyModule.Customer_Edit
(
  Params: { $Customer: MyModule.Customer },
  Title: 'Edit Customer',
  Layout: Atlas_Core.PopupLayout
)
{
  DATAVIEW dvCustomer (DataSource: $Customer) {
    TEXTBOX txtName (Label: 'Name', Attribute: Name)
    TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
    FOOTER footer1 {
      ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
      ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
    }
  }
}

Page Properties

Layouts

Layouts are referenced by their qualified name (Module.LayoutName). Common Atlas layouts include:

DROP PAGE

Removes a page from the project:

DROP PAGE MyModule.Customer_Edit;

Inspecting Pages

Use SHOW and DESCRIBE to examine existing pages:

-- List all pages in a module
SHOW PAGES IN MyModule;

-- Show the full MDL definition of a page (round-trippable)
DESCRIBE PAGE MyModule.Customer_Edit;

The output of DESCRIBE PAGE can be used as input to CREATE OR REPLACE PAGE for round-trip editing.

See Also

• Page Structure – layout selection, content areas, and data sources
• Widget Types – full catalog of available widgets
• Data Binding – connecting widgets to entity attributes
• Snippets – reusable page fragments
• ALTER PAGE – modifying existing pages in-place
• Common Patterns – list page, edit page, master-detail patterns

Page Structure

Every MDL page has three main parts: page properties (title, layout, parameters), a layout reference that defines the page skeleton, and a widget tree that fills the content area.

CREATE PAGE Syntax

CREATE [OR REPLACE] PAGE <Module>.<Name>
(
  [Params: { $Param: Module.Entity [, ...] },]
  Title: '<title>',
  Layout: <Module.LayoutName>
  [, Folder: '<path>']
  [, Variables: { $name: Type = 'expression' [, ...] }]
)
{
  <widget-tree>
}

Layout Reference

The Layout property selects the page layout, which determines the overall structure (navigation sidebar, top bar, popup frame, etc.). The widget tree you define fills the layout’s content placeholder.

CREATE PAGE MyModule.CustomerList
(
  Title: 'Customers',
  Layout: Atlas_Core.Atlas_Default
)
{
  -- Widgets here fill the main content area of Atlas_Default
  DATAGRID dgCustomers (DataSource: DATABASE MyModule.Customer) {
    COLUMN colName (Attribute: Name, Caption: 'Name')
    COLUMN colEmail (Attribute: Email, Caption: 'Email')
  }
}

Popup layouts are typically used for edit and detail pages:

CREATE PAGE MyModule.Customer_Edit
(
  Params: { $Customer: MyModule.Customer },
  Title: 'Edit Customer',
  Layout: Atlas_Core.PopupLayout
)
{
  DATAVIEW dvCustomer (DataSource: $Customer) {
    TEXTBOX txtName (Label: 'Name', Attribute: Name)
    FOOTER footer1 {
      ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
      ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
    }
  }
}

Page Parameters

Page parameters define entity objects that must be passed when the page is opened. Parameters use the $ prefix:

(
  Params: { $Customer: MyModule.Customer },
  ...
)

Multiple parameters are comma-separated:

(
  Params: { $Order: Sales.Order, $Customer: Sales.Customer },
  ...
)

Inside the widget tree, a DATAVIEW binds to a parameter using DataSource: $ParamName.

Page Variables

Page variables store local state (booleans, strings, etc.) that can control widget visibility or other conditional logic:

(
  Title: 'Product Detail',
  Layout: Atlas_Core.Atlas_Default,
  Variables: { $showDetails: Boolean = 'true' }
)

Data Sources

Data sources tell a container widget (DataView, DataGrid, ListView, Gallery) where to get its data.

Page Parameter Source

Binds to a page parameter. Used by DataView widgets for edit/detail pages:

DATAVIEW dvCustomer (DataSource: $Customer) {
  -- widgets bound to Customer attributes
}

Database Source

Retrieves entities directly from the database. Optionally includes an XPath constraint:

DATAGRID dgOrders (DataSource: DATABASE Sales.Order) {
  COLUMN colId (Attribute: OrderId, Caption: 'Order #')
  COLUMN colDate (Attribute: OrderDate, Caption: 'Date')
}

Microflow Source

Calls a microflow that returns a list or single object:

DATAVIEW dvDashboard (DataSource: MICROFLOW MyModule.DS_GetDashboardData) {
  -- widgets bound to the returned object's attributes
}

Nanoflow Source

Same as microflow source but calls a nanoflow (runs on the client):

LISTVIEW lvRecent (DataSource: NANOFLOW MyModule.DS_GetRecentItems) {
  -- widgets for each item
}

Association Source

Follows an association from a parent DataView’s object:

DATAVIEW dvCustomer (DataSource: $Customer) {
  LISTVIEW lvOrders (DataSource: ASSOCIATION Customer_Order) {
    -- widgets for each Order
  }
}

Selection Source

Binds to the currently selected item in another list widget:

DATAGRID dgProducts (DataSource: DATABASE MyModule.Product) {
  COLUMN colName (Attribute: Name)
}

DATAVIEW dvDetail (DataSource: SELECTION dgProducts) {
  TEXTBOX txtDescription (Label: 'Description', Attribute: Description)
}

Widget Tree Structure

The widget tree is a nested hierarchy. Container widgets hold child widgets within { } braces. Every widget requires a unique name:

{
  LAYOUTGRID grid1 {
    ROW row1 {
      COLUMN col1 {
        TEXTBOX txtName (Label: 'Name', Attribute: Name)
      }
      COLUMN col2 {
        TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
      }
    }
  }
}

Folder Organization

Use the Folder property to organize pages into folders within a module:

CREATE PAGE MyModule.Customer_Edit
(
  Params: { $Customer: MyModule.Customer },
  Title: 'Edit Customer',
  Layout: Atlas_Core.PopupLayout,
  Folder: 'Customers'
)
{
  ...
}

Nested folders use / separators: Folder: 'Pages/Customers/Detail'. Missing folders are auto-created.

See Also

• Pages – page overview and CREATE PAGE basics
• Widget Types – full catalog of widgets
• Data Binding – attribute binding with the Attribute property
• Common Patterns – list page, edit page, master-detail examples

Widget Types

MDL supports a comprehensive set of widget types for building Mendix pages. Each widget is declared with a type keyword, a unique name, properties in parentheses, and optional child widgets in braces.

WIDGET_TYPE widgetName (Property: value, ...) [{ children }]

Widget Categories

Layout Widgets

LAYOUTGRID

Creates a responsive grid with rows and columns. The primary layout mechanism for arranging widgets on a page:

LAYOUTGRID grid1 {
  ROW row1 {
    COLUMN col1 {
      TEXTBOX txtName (Label: 'Name', Attribute: Name)
    }
    COLUMN col2 {
      TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
    }
  }
  ROW row2 {
    COLUMN colFull {
      TEXTAREA txtNotes (Label: 'Notes', Attribute: Notes)
    }
  }
}

ROW

A row within a LAYOUTGRID. Contains one or more COLUMN children.

COLUMN

A column within a ROW. Contains any number of child widgets. Column width is determined by the layout grid system.

CONTAINER

A generic div container. Used to group widgets and apply CSS classes or styles:

CONTAINER cCard (Class: 'card mx-spacing-top-large') {
  DYNAMICTEXT txtTitle (Content: 'Section Title')
  TEXTBOX txtValue (Label: 'Value', Attribute: Value)
}

Properties:

CUSTOMCONTAINER

Similar to CONTAINER but used for custom-styled containers.

Data Widgets

DATAVIEW

Displays a single object. The central widget for detail and edit pages. Must have a data source:

DATAVIEW dvCustomer (DataSource: $Customer) {
  TEXTBOX txtName (Label: 'Name', Attribute: Name)
  TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
  COMBOBOX cbStatus (Label: 'Status', Attribute: Status)
  FOOTER footer1 {
    ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
    ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
  }
}

Data source options:

• DataSource: $ParamName – page parameter
• DataSource: MICROFLOW Module.MF_Name – microflow returning a single object
• DataSource: NANOFLOW Module.NF_Name – nanoflow returning a single object
• DataSource: SELECTION widgetName – currently selected item from a list widget
• DataSource: ASSOCIATION AssocName – follow an association from a parent context

DATAGRID

Displays a list of objects in a tabular format with columns, sorting, and pagination:

DATAGRID dgOrders (DataSource: DATABASE Sales.Order, PageSize: 20) {
  COLUMN colId (Attribute: OrderId, Caption: 'Order #')
  COLUMN colDate (Attribute: OrderDate, Caption: 'Date')
  COLUMN colAmount (Attribute: Amount, Caption: 'Amount', Alignment: right)
  COLUMN colStatus (Attribute: Status, Caption: 'Status')
  CONTROLBAR bar1 {
    ACTIONBUTTON btnNew (Caption: 'New', Action: MICROFLOW Sales.ACT_CreateOrder, ButtonStyle: Primary)
  }
}

DataGrid properties:

Column properties:

LISTVIEW

Displays a list of objects using a repeating template. More flexible than DataGrid for custom layouts:

LISTVIEW lvProducts (DataSource: DATABASE MyModule.Product) {
  CONTAINER cItem (Class: 'list-item') {
    DYNAMICTEXT txtName (Content: '{1}', Attribute: Name)
    DYNAMICTEXT txtPrice (Content: '${1}', Attribute: Price)
  }
}

GALLERY

A pluggable widget that displays items in a card/grid layout:

GALLERY galProducts (DataSource: DATABASE MyModule.Product) {
  CONTAINER cCard {
    DYNAMICTEXT txtName (Content: '{1}', Attribute: Name)
  }
}

Input Widgets

All input widgets share common properties:

TEXTBOX

Single-line text input. The most common input widget:

TEXTBOX txtName (Label: 'Name', Attribute: Name)
TEXTBOX txtEmail (Label: 'Email', Attribute: Email)

TEXTAREA

Multi-line text input for longer text:

TEXTAREA txtDescription (Label: 'Description', Attribute: Description)

CHECKBOX

Boolean (true/false) input:

CHECKBOX cbActive (Label: 'Active', Attribute: IsActive)

RADIOBUTTONS

Displays enumeration or boolean values as radio buttons:

RADIOBUTTONS rbStatus (Label: 'Status', Attribute: Status)

DATEPICKER

Date and/or time input:

DATEPICKER dpBirthDate (Label: 'Birth Date', Attribute: BirthDate)

COMBOBOX

Dropdown selection for enumeration values or associations. Uses the pluggable ComboBox widget:

COMBOBOX cbStatus (Label: 'Status', Attribute: Status)

REFERENCESELECTOR

Dropdown for selecting an associated object via a reference association:

REFERENCESELECTOR rsCategory (Label: 'Category', Attribute: Category)

Display Widgets

DYNAMICTEXT

Displays dynamic text content, often with attribute values:

DYNAMICTEXT txtGreeting (Content: 'Welcome, {1}', Attribute: Name)

IMAGE / STATICIMAGE / DYNAMICIMAGE

Display images on a page:

-- Static image from the project
STATICIMAGE imgLogo (Image: 'MyModule.Logo')

-- Dynamic image from an entity attribute (entity must extend System.Image)
DYNAMICIMAGE imgPhoto (DataSource: $Photo, Width: 200, Height: 150)

-- Generic image widget
IMAGE imgBanner (Width: 800, Height: 200)

Image properties:

Action Widgets

ACTIONBUTTON

A button that triggers an action. The primary interactive element:

ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
ACTIONBUTTON btnDelete (Caption: 'Delete', Action: DELETE, ButtonStyle: Danger)

Action types:

Button styles:

Microflow action with parameters:

ACTIONBUTTON btnProcess (
  Caption: 'Process',
  Action: MICROFLOW Sales.ACT_ProcessOrder(Order: $Order),
  ButtonStyle: Primary
)

LINKBUTTON

Renders as a hyperlink instead of a button. Same action types as ACTIONBUTTON:

LINKBUTTON lnkDetails (Caption: 'View Details', Action: PAGE MyModule.Customer_Detail)

Structure Widgets

HEADER

Header section of a DataView, placed before the main content:

DATAVIEW dvOrder (DataSource: $Order) {
  HEADER hdr1 {
    DYNAMICTEXT txtOrderTitle (Content: 'Order #{1}', Attribute: OrderId)
  }
  TEXTBOX txtStatus (Label: 'Status', Attribute: Status)
  FOOTER ftr1 { ... }
}

FOOTER

Footer section of a DataView. Typically contains save/cancel buttons:

FOOTER footer1 {
  ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
  ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
}

CONTROLBAR

Control bar for DataGrid widgets. Contains action buttons for the grid:

CONTROLBAR bar1 {
  ACTIONBUTTON btnNew (Caption: 'New', Action: MICROFLOW Module.ACT_Create, ButtonStyle: Primary)
  ACTIONBUTTON btnEdit (Caption: 'Edit', Action: PAGE Module.Entity_Edit)
  ACTIONBUTTON btnDelete (Caption: 'Delete', Action: DELETE, ButtonStyle: Danger)
}

SNIPPETCALL

Embeds a snippet (reusable page fragment) into the page:

SNIPPETCALL scNav (Snippet: MyModule.NavigationMenu)

Navigation Widgets

NAVIGATIONLIST

Renders a navigation list with clickable items:

NAVIGATIONLIST navMain {
  -- navigation items
}

Common Widget Properties

These properties are shared across many widget types:

See Also

• Pages – page overview and CREATE PAGE basics
• Page Structure – layout selection and data sources
• Data Binding – connecting widgets to attributes
• ALTER PAGE – modifying widgets in existing pages

Data Binding

Data binding connects widgets to entity attributes and data sources. In MDL, binding is configured through widget properties rather than a special operator.

Attribute Binding

Input widgets bind to entity attributes using the Attribute property. The attribute name is resolved relative to the containing DataView’s entity context:

DATAVIEW dvCustomer (DataSource: $Customer) {
  -- These attribute names are resolved against MyModule.Customer
  TEXTBOX txtName (Label: 'Name', Attribute: Name)
  TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
  CHECKBOX cbActive (Label: 'Active', Attribute: IsActive)
  DATEPICKER dpCreated (Label: 'Created', Attribute: CreatedDate)
  COMBOBOX cbStatus (Label: 'Status', Attribute: Status)
}

The SDK automatically resolves short attribute names to fully qualified paths. For example, Name is resolved to MyModule.Customer.Name based on the DataView’s entity context.

Data Sources

Data sources determine where a container widget gets its data. Different widget types support different data source types.

Page Parameter Source

The simplest binding – connects a DataView to a page parameter:

CREATE PAGE MyModule.Customer_Edit
(
  Params: { $Customer: MyModule.Customer },
  Title: 'Edit Customer',
  Layout: Atlas_Core.PopupLayout
)
{
  DATAVIEW dvCustomer (DataSource: $Customer) {
    TEXTBOX txtName (Label: 'Name', Attribute: Name)
  }
}

Database Source

Retrieves entities directly from the database. Works with list widgets (DataGrid, ListView, Gallery):

DATAGRID dgCustomers (DataSource: DATABASE MyModule.Customer) {
  COLUMN colName (Attribute: Name, Caption: 'Customer Name')
  COLUMN colEmail (Attribute: Email, Caption: 'Email')
}

Microflow Source

Calls a microflow to retrieve data. The microflow must return the appropriate type (single object for DataView, list for DataGrid/ListView):

-- Single object for a DataView
DATAVIEW dvStats (DataSource: MICROFLOW MyModule.DS_GetStatistics) {
  DYNAMICTEXT txtCount (Content: 'Total: {1}', Attribute: TotalCount)
}

-- List for a DataGrid
DATAGRID dgFiltered (DataSource: MICROFLOW MyModule.DS_GetFilteredOrders) {
  COLUMN colId (Attribute: OrderId)
}

Nanoflow Source

Same as microflow source but runs on the client side:

LISTVIEW lvRecent (DataSource: NANOFLOW MyModule.DS_GetRecentItems) {
  DYNAMICTEXT txtItem (Content: '{1}', Attribute: Name)
}

Association Source

Follows an association from a parent DataView to retrieve related objects:

DATAVIEW dvCustomer (DataSource: $Customer) {
  TEXTBOX txtName (Label: 'Name', Attribute: Name)

  -- Follow Customer_Order association to list orders
  LISTVIEW lvOrders (DataSource: ASSOCIATION Customer_Order) {
    DYNAMICTEXT txtOrderDate (Content: '{1}', Attribute: OrderDate)
    DYNAMICTEXT txtAmount (Content: '${1}', Attribute: Amount)
  }
}

Selection Source

Binds to the currently selected item in another list widget. Enables master-detail patterns:

-- Master: list of products
DATAGRID dgProducts (DataSource: DATABASE MyModule.Product) {
  COLUMN colName (Attribute: Name)
  COLUMN colPrice (Attribute: Price)
}

-- Detail: shows the selected product
DATAVIEW dvDetail (DataSource: SELECTION dgProducts) {
  TEXTBOX txtDescription (Label: 'Description', Attribute: Description)
  TEXTBOX txtCategory (Label: 'Category', Attribute: Category)
}

Nested Data Contexts

Widgets inherit the data context from their parent container. A DataView inside a DataView creates a nested context:

DATAVIEW dvOrder (DataSource: $Order) {
  TEXTBOX txtOrderId (Label: 'Order #', Attribute: OrderId)

  -- Nested DataView for the order's customer (via association)
  DATAVIEW dvCustomer (DataSource: ASSOCIATION Order_Customer) {
    -- Attributes here resolve against Customer
    DYNAMICTEXT txtCustomerName (Content: '{1}', Attribute: Name)
  }
}

Dynamic Text Content

The DYNAMICTEXT widget uses {1}, {2}, etc. as placeholders for attribute values in the Content property. The Attribute property specifies which attribute fills the first placeholder:

DYNAMICTEXT txtPrice (Content: 'Price: ${1}', Attribute: Price)

Button Actions with Parameters

Action buttons can pass the current data context to microflows and pages:

DATAVIEW dvOrder (DataSource: $Order) {
  ACTIONBUTTON btnProcess (
    Caption: 'Process Order',
    Action: MICROFLOW Sales.ACT_ProcessOrder(Order: $Order),
    ButtonStyle: Primary
  )

  ACTIONBUTTON btnEdit (
    Caption: 'Edit',
    Action: PAGE Sales.Order_Edit
  )
}

See Also

• Pages – page overview
• Page Structure – data source types in detail
• Widget Types – available widgets and their properties
• Common Patterns – master-detail and other binding patterns

Snippets

Snippets are reusable page fragments that can be embedded in multiple pages. They allow you to define a widget tree once and include it wherever needed, promoting consistency and reducing duplication.

CREATE SNIPPET

CREATE [OR REPLACE] SNIPPET <Module>.<Name>
(
  [Params: { $Param: Module.Entity [, ...] },]
  [Folder: '<path>']
)
{
  <widget-tree>
}

Basic Snippet

A snippet without parameters:

CREATE SNIPPET MyModule.Footer
(
  Folder: 'Snippets'
)
{
  CONTAINER cFooter (Class: 'app-footer') {
    DYNAMICTEXT txtCopyright (Content: '2024 My Company. All rights reserved.')
  }
}

Snippet with Parameters

Snippets can accept entity parameters, similar to pages:

CREATE SNIPPET MyModule.CustomerCard
(
  Params: { $Customer: MyModule.Customer }
)
{
  CONTAINER cCard (Class: 'card') {
    DATAVIEW dvCustomer (DataSource: $Customer) {
      DYNAMICTEXT txtName (Content: '{1}', Attribute: Name)
      DYNAMICTEXT txtEmail (Content: '{1}', Attribute: Email)
      ACTIONBUTTON btnEdit (
        Caption: 'Edit',
        Action: PAGE MyModule.Customer_Edit,
        ButtonStyle: Primary
      )
    }
  }
}

Using Snippets in Pages

Embed a snippet in a page using the SNIPPETCALL widget:

CREATE PAGE MyModule.Home
(
  Title: 'Home',
  Layout: Atlas_Core.Atlas_Default
)
{
  CONTAINER cMain {
    SNIPPETCALL scFooter (Snippet: MyModule.Footer)
  }
}

Inspecting Snippets

-- List all snippets in a module
SHOW SNIPPETS IN MyModule;

-- View full MDL definition
DESCRIBE SNIPPET MyModule.CustomerCard;

DROP SNIPPET

DROP SNIPPET MyModule.Footer;

ALTER SNIPPET

Snippets support the same in-place modification operations as pages. See ALTER PAGE / ALTER SNIPPET:

ALTER SNIPPET MyModule.CustomerCard {
  SET Caption = 'View Details' ON btnEdit;
  INSERT AFTER txtEmail {
    DYNAMICTEXT txtPhone (Content: '{1}', Attribute: Phone)
  }
};

See Also

• Pages – page overview
• Widget Types – available widgets including SNIPPETCALL
• ALTER PAGE – modifying snippets and pages in-place
• Common Patterns – patterns that use snippets

ALTER PAGE / ALTER SNIPPET

The ALTER PAGE and ALTER SNIPPET statements modify an existing page or snippet’s widget tree in-place, without requiring a full CREATE OR REPLACE. This is especially useful for incremental changes: adding a field, changing a button caption, or removing an unused widget.

ALTER operates directly on the raw widget tree, preserving any widget types that MDL does not natively support (pluggable widgets, custom widgets, etc.).

Syntax

ALTER PAGE <Module>.<Name> {
  <operations>
};

ALTER SNIPPET <Module>.<Name> {
  <operations>
};

Operations

SET – Modify Widget Properties

Change one or more properties on a widget identified by name:

-- Single property
ALTER PAGE Module.EditPage {
  SET Caption = 'Save & Close' ON btnSave
};

-- Multiple properties at once
ALTER PAGE Module.EditPage {
  SET (Caption = 'Save & Close', ButtonStyle = Success) ON btnSave
};

Supported SET properties:

SET – Page-Level Properties

Omit the ON clause to set page-level properties:

ALTER PAGE Module.EditPage {
  SET Title = 'Customer Details'
};

SET – Pluggable Widget Properties

Use quoted property names to set properties on pluggable widgets (ComboBox, DataGrid2, etc.):

ALTER PAGE Module.EditPage {
  SET 'showLabel' = false ON cbStatus
};

INSERT – Add Widgets

Insert new widgets before or after an existing widget:

-- Insert after a widget
ALTER PAGE Module.EditPage {
  INSERT AFTER txtEmail {
    TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)
    TEXTBOX txtFax (Label: 'Fax', Attribute: Fax)
  }
};

-- Insert before a widget
ALTER PAGE Module.EditPage {
  INSERT BEFORE btnSave {
    ACTIONBUTTON btnPreview (Caption: 'Preview', Action: MICROFLOW Module.ACT_Preview)
  }
};

The inserted widgets use the same syntax as in CREATE PAGE. Multiple widgets can be inserted in a single block.

DROP WIDGET – Remove Widgets

Remove one or more widgets by name:

ALTER PAGE Module.EditPage {
  DROP WIDGET txtUnused
};

-- Multiple widgets
ALTER PAGE Module.EditPage {
  DROP WIDGET txtFax, txtPager, btnObsolete
};

Dropping a container widget also removes all of its children.

REPLACE – Replace a Widget

Replace a widget (and its subtree) with new widgets:

ALTER PAGE Module.EditPage {
  REPLACE txtOldField WITH {
    TEXTAREA txtNotes (Label: 'Notes', Attribute: Notes)
  }
};

Page Variables

Add or remove page-level variables:

-- Add a variable
ALTER PAGE Module.EditPage {
  ADD Variables $showAdvanced: Boolean = 'false'
};

-- Remove a variable
ALTER PAGE Module.EditPage {
  DROP Variables $showAdvanced
};

Combining Operations

Multiple operations can be combined in a single ALTER statement. They are applied in order:

ALTER PAGE Module.Customer_Edit {
  -- Change button appearance
  SET (Caption = 'Save & Close', ButtonStyle = Success) ON btnSave;

  -- Remove unused fields
  DROP WIDGET txtFax;

  -- Add new fields after email
  INSERT AFTER txtEmail {
    TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)
    TEXTBOX txtMobile (Label: 'Mobile', Attribute: Mobile)
  };

  -- Replace old status dropdown with combobox
  REPLACE ddStatus WITH {
    COMBOBOX cbStatus (Label: 'Status', Attribute: Status)
  }
};

Workflow Tips

1. Discover widget names first – Run DESCRIBE PAGE Module.PageName to see the current widget tree with all widget names.

2. Use ALTER for small changes – For adding a field or changing a caption, ALTER is faster and safer than CREATE OR REPLACE, because it preserves widgets that MDL cannot round-trip (pluggable widgets with complex configurations).

3. Use CREATE OR REPLACE for major rewrites – When restructuring the entire page layout, a full replacement is cleaner.

Examples

Add a Field to an Edit Page

-- First, check what's on the page
DESCRIBE PAGE MyModule.Customer_Edit;

-- Add a phone field after email
ALTER PAGE MyModule.Customer_Edit {
  INSERT AFTER txtEmail {
    TEXTBOX txtPhone (Label: 'Phone Number', Attribute: Phone)
  }
};

Change Button Behavior

ALTER PAGE MyModule.Order_Edit {
  SET (Caption = 'Submit Order', ButtonStyle = Success) ON btnSave;
  SET Caption = 'Discard' ON btnCancel
};

Add a DataGrid Column

Since DataGrid columns are part of the widget tree, use INSERT to add columns:

ALTER PAGE MyModule.Customer_Overview {
  INSERT AFTER colEmail {
    COLUMN colPhone (Attribute: Phone, Caption: 'Phone')
  }
};

See Also

• Pages – page overview and CREATE PAGE basics
• Widget Types – widgets available for INSERT and REPLACE
• Snippets – ALTER SNIPPET uses the same operations
• Common Patterns – page layout patterns

Common Patterns

This page collects frequently used page patterns: overview/list pages, edit pages, and master-detail layouts. Each pattern is a complete, working example.

Overview / List Page

An overview page displays a list of entities with a control bar for creating, editing, and deleting records. Clicking a row opens the edit page.

CREATE PAGE MyModule.Customer_Overview
(
  Title: 'Customers',
  Layout: Atlas_Core.Atlas_Default,
  Folder: 'Customers'
)
{
  DATAGRID dgCustomers (DataSource: DATABASE MyModule.Customer, PageSize: 20) {
    COLUMN colName (Attribute: Name, Caption: 'Name')
    COLUMN colEmail (Attribute: Email, Caption: 'Email')
    COLUMN colStatus (Attribute: Status, Caption: 'Status')
    COLUMN colCreated (Attribute: CreatedDate, Caption: 'Created')
    CONTROLBAR bar1 {
      ACTIONBUTTON btnNew (
        Caption: 'New Customer',
        Action: MICROFLOW MyModule.ACT_Customer_New,
        ButtonStyle: Primary
      )
      ACTIONBUTTON btnEdit (Caption: 'Edit', Action: PAGE MyModule.Customer_Edit)
      ACTIONBUTTON btnDelete (Caption: 'Delete', Action: DELETE, ButtonStyle: Danger)
    }
  }
}

The “New Customer” button calls a microflow that creates a new Customer object and opens the edit page:

CREATE MICROFLOW MyModule.ACT_Customer_New
BEGIN
  DECLARE $Customer MyModule.Customer;
  $Customer = CREATE MyModule.Customer (
    IsActive = true
  );
  SHOW PAGE MyModule.Customer_Edit ($Customer = $Customer);
  RETURN $Customer;
END;

Edit Page (Popup)

An edit page displayed as a popup dialog. Receives the entity as a page parameter:

CREATE PAGE MyModule.Customer_Edit
(
  Params: { $Customer: MyModule.Customer },
  Title: 'Edit Customer',
  Layout: Atlas_Core.PopupLayout,
  Folder: 'Customers'
)
{
  DATAVIEW dvCustomer (DataSource: $Customer) {
    TEXTBOX txtName (Label: 'Name', Attribute: Name)
    TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
    TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)
    COMBOBOX cbStatus (Label: 'Status', Attribute: Status)
    CHECKBOX cbActive (Label: 'Active', Attribute: IsActive)
    FOOTER footer1 {
      ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
      ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
    }
  }
}

Detail Page (Full Page)

A full-page detail view with sections organized using layout grids:

CREATE PAGE MyModule.Customer_Detail
(
  Params: { $Customer: MyModule.Customer },
  Title: 'Customer Detail',
  Layout: Atlas_Core.Atlas_Default,
  Folder: 'Customers'
)
{
  DATAVIEW dvCustomer (DataSource: $Customer) {
    LAYOUTGRID grid1 {
      ROW rowBasic {
        COLUMN col1 {
          TEXTBOX txtName (Label: 'Name', Attribute: Name)
          TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
        }
        COLUMN col2 {
          TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)
          COMBOBOX cbStatus (Label: 'Status', Attribute: Status)
        }
      }
      ROW rowNotes {
        COLUMN colNotes {
          TEXTAREA txtNotes (Label: 'Notes', Attribute: Notes)
        }
      }
    }
    FOOTER footer1 {
      ACTIONBUTTON btnEdit (
        Caption: 'Edit',
        Action: PAGE MyModule.Customer_Edit,
        ButtonStyle: Primary
      )
      ACTIONBUTTON btnBack (Caption: 'Back', Action: CLOSE_PAGE)
    }
  }
}

Master-Detail Pattern

A master-detail page shows a list on one side and the selected item’s details on the other. The SELECTION data source connects the detail view to the list.

Side-by-Side Layout

CREATE PAGE MyModule.Product_MasterDetail
(
  Title: 'Products',
  Layout: Atlas_Core.Atlas_Default,
  Folder: 'Products'
)
{
  LAYOUTGRID gridMain {
    ROW rowContent {
      COLUMN colList {
        DATAGRID dgProducts (DataSource: DATABASE MyModule.Product, PageSize: 15) {
          COLUMN colName (Attribute: Name, Caption: 'Product')
          COLUMN colPrice (Attribute: Price, Caption: 'Price', Alignment: right)
          COLUMN colCategory (Attribute: Category, Caption: 'Category')
          CONTROLBAR bar1 {
            ACTIONBUTTON btnNew (
              Caption: 'New',
              Action: MICROFLOW MyModule.ACT_Product_New,
              ButtonStyle: Primary
            )
          }
        }
      }
      COLUMN colDetail {
        DATAVIEW dvDetail (DataSource: SELECTION dgProducts) {
          TEXTBOX txtName (Label: 'Name', Attribute: Name)
          TEXTBOX txtDescription (Label: 'Description', Attribute: Description)
          TEXTBOX txtPrice (Label: 'Price', Attribute: Price)
          COMBOBOX cbCategory (Label: 'Category', Attribute: Category)
          FOOTER footer1 {
            ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
          }
        }
      }
    }
  }
}

With Related Items

A master-detail pattern where selecting an entity also shows its related child entities via an association:

CREATE PAGE MyModule.Order_MasterDetail
(
  Title: 'Orders',
  Layout: Atlas_Core.Atlas_Default,
  Folder: 'Orders'
)
{
  LAYOUTGRID gridMain {
    ROW rowContent {
      COLUMN colOrders {
        DATAGRID dgOrders (DataSource: DATABASE MyModule.Order, PageSize: 10) {
          COLUMN colOrderId (Attribute: OrderId, Caption: 'Order #')
          COLUMN colDate (Attribute: OrderDate, Caption: 'Date')
          COLUMN colStatus (Attribute: Status, Caption: 'Status')
          COLUMN colTotal (Attribute: TotalAmount, Caption: 'Total', Alignment: right)
        }
      }
      COLUMN colDetail {
        DATAVIEW dvOrder (DataSource: SELECTION dgOrders) {
          DYNAMICTEXT txtOrderInfo (Content: 'Order #{1}', Attribute: OrderId)
          TEXTBOX txtStatus (Label: 'Status', Attribute: Status)

          -- Order lines via association
          DATAGRID dgLines (DataSource: ASSOCIATION Order_OrderLine) {
            COLUMN colProduct (Attribute: ProductName, Caption: 'Product')
            COLUMN colQty (Attribute: Quantity, Caption: 'Qty', Alignment: right)
            COLUMN colLineTotal (Attribute: LineTotal, Caption: 'Total', Alignment: right)
          }

          FOOTER footer1 {
            ACTIONBUTTON btnEdit (
              Caption: 'Edit Order',
              Action: PAGE MyModule.Order_Edit,
              ButtonStyle: Primary
            )
          }
        }
      }
    }
  }
}

CRUD Page Set

A complete set of pages for managing an entity typically includes:

1. Overview page – DataGrid with list of records + New/Edit/Delete buttons
2. Edit page (popup) – DataView with input fields + Save/Cancel
3. New microflow – Creates a blank object and opens the edit page

Here is a concise CRUD set for an Employee entity:

-- 1. Overview page
CREATE PAGE HR.Employee_Overview
(
  Title: 'Employees',
  Layout: Atlas_Core.Atlas_Default,
  Folder: 'Employees'
)
{
  DATAGRID dgEmployees (DataSource: DATABASE HR.Employee, PageSize: 20) {
    COLUMN colName (Attribute: FullName, Caption: 'Name')
    COLUMN colDept (Attribute: Department, Caption: 'Department')
    COLUMN colHireDate (Attribute: HireDate, Caption: 'Hire Date')
    CONTROLBAR bar1 {
      ACTIONBUTTON btnNew (
        Caption: 'New Employee',
        Action: MICROFLOW HR.ACT_Employee_New,
        ButtonStyle: Primary
      )
      ACTIONBUTTON btnEdit (Caption: 'Edit', Action: PAGE HR.Employee_Edit)
      ACTIONBUTTON btnDelete (Caption: 'Delete', Action: DELETE, ButtonStyle: Danger)
    }
  }
}

-- 2. Edit page (popup)
CREATE PAGE HR.Employee_Edit
(
  Params: { $Employee: HR.Employee },
  Title: 'Edit Employee',
  Layout: Atlas_Core.PopupLayout,
  Folder: 'Employees'
)
{
  DATAVIEW dvEmployee (DataSource: $Employee) {
    TEXTBOX txtName (Label: 'Full Name', Attribute: FullName)
    TEXTBOX txtDept (Label: 'Department', Attribute: Department)
    DATEPICKER dpHireDate (Label: 'Hire Date', Attribute: HireDate)
    TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
    FOOTER footer1 {
      ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE_CHANGES, ButtonStyle: Primary)
      ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL_CHANGES)
    }
  }
}

-- 3. New employee microflow
CREATE MICROFLOW HR.ACT_Employee_New
BEGIN
  DECLARE $Employee HR.Employee;
  $Employee = CREATE HR.Employee (
    HireDate = [%CurrentDateTime%]
  );
  SHOW PAGE HR.Employee_Edit ($Employee = $Employee);
  RETURN $Employee;
END;

Dashboard Page

A dashboard page using layout grids to arrange multiple data sections:

CREATE PAGE MyModule.Dashboard
(
  Title: 'Dashboard',
  Layout: Atlas_Core.Atlas_Default,
  Folder: 'Dashboard'
)
{
  LAYOUTGRID gridDash {
    ROW rowTop {
      COLUMN colRecent {
        CONTAINER cRecent (Class: 'card') {
          DYNAMICTEXT txtRecentTitle (Content: 'Recent Orders')
          DATAGRID dgRecent (DataSource: MICROFLOW MyModule.DS_RecentOrders, PageSize: 5) {
            COLUMN colOrderId (Attribute: OrderId, Caption: 'Order #')
            COLUMN colDate (Attribute: OrderDate, Caption: 'Date')
            COLUMN colStatus (Attribute: Status, Caption: 'Status')
          }
        }
      }
      COLUMN colStats {
        CONTAINER cStats (Class: 'card') {
          DATAVIEW dvStats (DataSource: MICROFLOW MyModule.DS_GetStatistics) {
            DYNAMICTEXT txtTotal (Content: 'Total Orders: {1}', Attribute: TotalOrders)
            DYNAMICTEXT txtRevenue (Content: 'Revenue: ${1}', Attribute: TotalRevenue)
          }
        }
      }
    }
  }
}

See Also

• Pages – page overview
• Page Structure – data sources and layout references
• Widget Types – available widgets
• ALTER PAGE – incremental modifications to existing pages
• Snippets – reusable page fragments

Security

Mendix applications use a layered security model with three levels: project security settings, role definitions, and access rules. MDL provides complete control over all three layers.

Security Levels

The project security level determines how strictly the runtime enforces access rules.

ALTER PROJECT SECURITY LEVEL PRODUCTION;

Security Architecture

Security in Mendix is organized in layers:

1. Module Roles – defined per module, they represent permissions within that module (e.g., Shop.Admin, Shop.Viewer)
2. User Roles – project-level roles that aggregate module roles across modules (e.g., AppAdmin combines Shop.Admin and System.Administrator)
3. Entity Access – CRUD permissions and XPath constraints per entity per module role
4. Document Access – execute/view permissions on microflows, nanoflows, and pages per module role
5. Demo Users – test accounts with assigned user roles for development

Inspecting Security

MDL provides several commands for viewing the current security configuration:

-- Project-wide settings
SHOW PROJECT SECURITY;

-- Roles
SHOW MODULE ROLES;
SHOW MODULE ROLES IN Shop;
SHOW USER ROLES;

-- Access rules
SHOW ACCESS ON MICROFLOW Shop.ACT_ProcessOrder;
SHOW ACCESS ON PAGE Shop.Order_Edit;
SHOW ACCESS ON Shop.Customer;

-- Full matrix
SHOW SECURITY MATRIX;
SHOW SECURITY MATRIX IN Shop;

-- Demo users
SHOW DEMO USERS;

Modifying Project Security

Toggle the security level and demo user visibility:

ALTER PROJECT SECURITY LEVEL PRODUCTION;
ALTER PROJECT SECURITY DEMO USERS ON;
ALTER PROJECT SECURITY DEMO USERS OFF;

See Also

• Module Roles and User Roles – defining roles
• Entity Access – CRUD permissions per entity
• Document Access – microflow, page, and nanoflow permissions
• GRANT / REVOKE – granting and revoking permissions
• Demo Users – creating test accounts

Module Roles and User Roles

Mendix security uses a two-tier role system. Module roles define permissions within a single module. User roles aggregate module roles across the entire project.

Module Roles

A module role represents a set of permissions within a module. Entity access rules, microflow access, and page access are all granted to module roles.

CREATE MODULE ROLE

CREATE MODULE ROLE <Module>.<Role> [DESCRIPTION '<text>'];

Examples:

CREATE MODULE ROLE Shop.Admin DESCRIPTION 'Full administrative access';
CREATE MODULE ROLE Shop.User DESCRIPTION 'Standard customer-facing role';
CREATE MODULE ROLE Shop.Viewer;

DROP MODULE ROLE

DROP MODULE ROLE Shop.Viewer;

Listing Module Roles

SHOW MODULE ROLES;
SHOW MODULE ROLES IN Shop;

User Roles

A user role is a project-level role assigned to end users at login. Each user role includes one or more module roles, granting the user the combined permissions of all included module roles.

CREATE USER ROLE

CREATE USER ROLE <Name> (<Module>.<Role> [, ...]) [MANAGE ALL ROLES];

The MANAGE ALL ROLES option allows users with this role to assign any user role to other users (typically for administrators).

Examples:

-- Administrator with management rights
CREATE USER ROLE AppAdmin (Shop.Admin, System.Administrator) MANAGE ALL ROLES;

-- Regular user
CREATE USER ROLE AppUser (Shop.User);

-- Read-only viewer
CREATE USER ROLE AppViewer (Shop.Viewer);

ALTER USER ROLE

Add or remove module roles from an existing user role:

ALTER USER ROLE AppAdmin ADD MODULE ROLES (Reporting.Admin);
ALTER USER ROLE AppUser REMOVE MODULE ROLES (Shop.Viewer);

DROP USER ROLE

DROP USER ROLE AppViewer;

Listing User Roles

SHOW USER ROLES;

Typical Setup

A common pattern is to create module roles first, then compose them into user roles:

-- 1. Module roles
CREATE MODULE ROLE Shop.Admin DESCRIPTION 'Full shop access';
CREATE MODULE ROLE Shop.User DESCRIPTION 'Standard shop access';
CREATE MODULE ROLE Reporting.Viewer DESCRIPTION 'View reports';

-- 2. User roles
CREATE USER ROLE Administrator (Shop.Admin, Reporting.Viewer, System.Administrator) MANAGE ALL ROLES;
CREATE USER ROLE Employee (Shop.User, Reporting.Viewer);
CREATE USER ROLE Guest (Shop.User);

See Also

• Security – overview of the security model
• Entity Access – granting CRUD permissions to module roles
• Document Access – granting microflow and page access
• GRANT / REVOKE – the GRANT and REVOKE statements
• Demo Users – creating test accounts with user roles

Entity Access

Entity access rules control which module roles can create, read, write, and delete objects of a given entity. Rules can restrict access to specific attributes and apply XPath constraints to limit which rows are visible.

GRANT on Entities

GRANT <Module>.<Role> ON <Module>.<Entity> (<rights>) [WHERE '<xpath>'];

The <rights> list is a comma-separated combination of:

Examples

Full Access

Grant all operations on all members:

GRANT Shop.Admin ON Shop.Customer (CREATE, DELETE, READ *, WRITE *);

Read-Only Access

GRANT Shop.Viewer ON Shop.Customer (READ *);

Selective Member Access

Restrict read and write to specific attributes:

GRANT Shop.User ON Shop.Customer (READ (Name, Email, Status), WRITE (Email));

XPath Constraints

Limit which objects a role can see or modify using an XPath expression in the WHERE clause:

-- Users can only access their own orders
GRANT Shop.User ON Shop.Order (READ *, WRITE *)
  WHERE '[Sales.Order_Customer/Sales.Customer/Name = $currentUser]';

-- Only open orders are editable
GRANT Shop.User ON Shop.Order (READ *, WRITE *)
  WHERE '[Status = ''Open'']';

Note that single quotes inside XPath expressions must be doubled (''), since the entire expression is wrapped in single quotes.

Multiple Roles on the Same Entity

Each GRANT creates a separate access rule. An entity can have rules for multiple roles:

GRANT Shop.Admin ON Shop.Order (CREATE, DELETE, READ *, WRITE *);
GRANT Shop.User ON Shop.Order (READ *, WRITE *) WHERE '[Status = ''Open'']';
GRANT Shop.Viewer ON Shop.Order (READ *);

REVOKE on Entities

Remove an entity access rule for a role:

REVOKE <Module>.<Role> ON <Module>.<Entity>;

Example:

REVOKE Shop.Viewer ON Shop.Customer;

This removes the entire access rule for that role on that entity.

Viewing Entity Access

-- See which roles have access to an entity
SHOW ACCESS ON Shop.Customer;

-- Full matrix across a module
SHOW SECURITY MATRIX IN Shop;

See Also

• Security – overview of the security model
• Module Roles and User Roles – defining the roles referenced in access rules
• Document Access – microflow and page access
• GRANT / REVOKE – complete GRANT and REVOKE reference

Microflow, Page, and Nanoflow Access

Document-level access controls which module roles can execute microflows and nanoflows or view pages. Without an explicit grant, a document is inaccessible to all roles.

Microflow Access

GRANT EXECUTE ON MICROFLOW

GRANT EXECUTE ON MICROFLOW <Module>.<Name> TO <Module>.<Role> [, ...];

Examples:

-- Single role
GRANT EXECUTE ON MICROFLOW Shop.ACT_ProcessOrder TO Shop.Admin;

-- Multiple roles
GRANT EXECUTE ON MICROFLOW Shop.ACT_ViewOrders TO Shop.User, Shop.Admin;

REVOKE EXECUTE ON MICROFLOW

REVOKE EXECUTE ON MICROFLOW <Module>.<Name> FROM <Module>.<Role> [, ...];

Example:

REVOKE EXECUTE ON MICROFLOW Shop.ACT_ProcessOrder FROM Shop.User;

Page Access

GRANT VIEW ON PAGE

GRANT VIEW ON PAGE <Module>.<Name> TO <Module>.<Role> [, ...];

Examples:

GRANT VIEW ON PAGE Shop.Order_Overview TO Shop.User, Shop.Admin;
GRANT VIEW ON PAGE Shop.Admin_Dashboard TO Shop.Admin;

REVOKE VIEW ON PAGE

REVOKE VIEW ON PAGE <Module>.<Name> FROM <Module>.<Role> [, ...];

Example:

REVOKE VIEW ON PAGE Shop.Admin_Dashboard FROM Shop.User;

Nanoflow Access

Nanoflow access uses the same syntax as microflow access:

GRANT EXECUTE ON NANOFLOW Shop.NAV_Filter TO Shop.User, Shop.Admin;
REVOKE EXECUTE ON NANOFLOW Shop.NAV_Filter FROM Shop.User;

Viewing Document Access

SHOW ACCESS ON MICROFLOW Shop.ACT_ProcessOrder;
SHOW ACCESS ON PAGE Shop.Order_Overview;

Typical Pattern

After creating documents, grant access as part of the same script:

-- Create the microflow
CREATE MICROFLOW Shop.ACT_CreateOrder
BEGIN
  DECLARE $Order Shop.Order;
  $Order = CREATE Shop.Order (Status = 'Draft');
  COMMIT $Order;
  RETURN $Order;
END;

-- Grant access
GRANT EXECUTE ON MICROFLOW Shop.ACT_CreateOrder TO Shop.User, Shop.Admin;

-- Create the page
CREATE PAGE Shop.Order_Edit (
  Params: { $Order: Shop.Order },
  Title: 'Edit Order',
  Layout: Atlas_Core.PopupLayout
) { ... }

-- Grant access
GRANT VIEW ON PAGE Shop.Order_Edit TO Shop.User, Shop.Admin;

See Also

• Security – overview of the security model
• Entity Access – CRUD permissions on entities
• GRANT / REVOKE – complete GRANT and REVOKE reference
• Module Roles and User Roles – defining the roles

GRANT / REVOKE

The GRANT and REVOKE statements control all permissions in a Mendix project. They work on three targets: entities (CRUD access), microflows (execute access), and pages (view access).

Entity Access

GRANT

GRANT <Module>.<Role> ON <Module>.<Entity> (<rights>) [WHERE '<xpath>'];

Where <rights> is a comma-separated list of:

Examples:

-- Full access
GRANT Shop.Admin ON Shop.Customer (CREATE, DELETE, READ *, WRITE *);

-- Read-only
GRANT Shop.Viewer ON Shop.Customer (READ *);

-- Selective members
GRANT Shop.User ON Shop.Customer (READ (Name, Email), WRITE (Email));

-- With XPath constraint (doubled single quotes for string literals)
GRANT Shop.User ON Shop.Order (READ *, WRITE *)
  WHERE '[Status = ''Open'']';

REVOKE

Remove an entity access rule entirely:

REVOKE <Module>.<Role> ON <Module>.<Entity>;

Example:

REVOKE Shop.Viewer ON Shop.Customer;

Microflow Access

GRANT EXECUTE ON MICROFLOW

GRANT EXECUTE ON MICROFLOW <Module>.<Name> TO <Module>.<Role> [, ...];

Example:

GRANT EXECUTE ON MICROFLOW Shop.ACT_ProcessOrder TO Shop.User, Shop.Admin;

REVOKE EXECUTE ON MICROFLOW

REVOKE EXECUTE ON MICROFLOW <Module>.<Name> FROM <Module>.<Role> [, ...];

Example:

REVOKE EXECUTE ON MICROFLOW Shop.ACT_ProcessOrder FROM Shop.User;

Page Access

GRANT VIEW ON PAGE

GRANT VIEW ON PAGE <Module>.<Name> TO <Module>.<Role> [, ...];

Example:

GRANT VIEW ON PAGE Shop.Order_Overview TO Shop.User, Shop.Admin;

REVOKE VIEW ON PAGE

REVOKE VIEW ON PAGE <Module>.<Name> FROM <Module>.<Role> [, ...];

Example:

REVOKE VIEW ON PAGE Shop.Admin_Dashboard FROM Shop.User;

Nanoflow Access

GRANT EXECUTE ON NANOFLOW <Module>.<Name> TO <Module>.<Role> [, ...];
REVOKE EXECUTE ON NANOFLOW <Module>.<Name> FROM <Module>.<Role> [, ...];

Workflow Access

GRANT EXECUTE ON WORKFLOW <Module>.<Name> TO <Module>.<Role> [, ...];
REVOKE EXECUTE ON WORKFLOW <Module>.<Name> FROM <Module>.<Role> [, ...];

OData Service Access

GRANT ACCESS ON ODATA SERVICE <Module>.<Name> TO <Module>.<Role> [, ...];
REVOKE ACCESS ON ODATA SERVICE <Module>.<Name> FROM <Module>.<Role> [, ...];

Complete Example

A typical security setup script:

-- Module roles
CREATE MODULE ROLE Shop.Admin DESCRIPTION 'Full access';
CREATE MODULE ROLE Shop.User DESCRIPTION 'Standard access';
CREATE MODULE ROLE Shop.Viewer DESCRIPTION 'Read-only access';

-- User roles
CREATE USER ROLE Administrator (Shop.Admin, System.Administrator) MANAGE ALL ROLES;
CREATE USER ROLE Employee (Shop.User);
CREATE USER ROLE Guest (Shop.Viewer);

-- Entity access
GRANT Shop.Admin ON Shop.Customer (CREATE, DELETE, READ *, WRITE *);
GRANT Shop.User ON Shop.Customer (READ *, WRITE (Email, Phone));
GRANT Shop.Viewer ON Shop.Customer (READ *);

GRANT Shop.Admin ON Shop.Order (CREATE, DELETE, READ *, WRITE *);
GRANT Shop.User ON Shop.Order (CREATE, READ *, WRITE *)
  WHERE '[Status = ''Open'']';
GRANT Shop.Viewer ON Shop.Order (READ *);

-- Microflow access
GRANT EXECUTE ON MICROFLOW Shop.ACT_ProcessOrder TO Shop.Admin;
GRANT EXECUTE ON MICROFLOW Shop.ACT_CreateOrder TO Shop.User, Shop.Admin;
GRANT EXECUTE ON MICROFLOW Shop.ACT_ViewOrders TO Shop.User, Shop.Admin, Shop.Viewer;

-- Page access
GRANT VIEW ON PAGE Shop.Order_Overview TO Shop.User, Shop.Admin, Shop.Viewer;
GRANT VIEW ON PAGE Shop.Order_Edit TO Shop.User, Shop.Admin;
GRANT VIEW ON PAGE Shop.Admin_Dashboard TO Shop.Admin;

-- Demo users
CREATE DEMO USER 'demo_admin' PASSWORD 'Admin123!' (Administrator);
CREATE DEMO USER 'demo_user' PASSWORD 'User123!' (Employee);

-- Enable demo users
ALTER PROJECT SECURITY DEMO USERS ON;
ALTER PROJECT SECURITY LEVEL PROTOTYPE;

See Also

• Security – overview of the security model
• Entity Access – details on entity CRUD permissions and XPath constraints
• Document Access – microflow, page, and nanoflow access patterns
• Module Roles and User Roles – creating and managing roles
• Demo Users – creating test accounts

Demo Users

Demo users are test accounts created for development and testing. They appear on the login screen when demo users are enabled, allowing quick access without manual user setup.

CREATE DEMO USER

CREATE DEMO USER '<username>' PASSWORD '<password>'
  [ENTITY <Module>.<Entity>]
  (<UserRole> [, ...]);

Examples

-- Basic demo user
CREATE DEMO USER 'demo_admin' PASSWORD 'Admin123!' (Administrator);

-- With explicit entity
CREATE DEMO USER 'demo_admin' PASSWORD 'Admin123!'
  ENTITY Administration.Account (Administrator);

-- Multiple roles
CREATE DEMO USER 'demo_manager' PASSWORD 'Manager1!'
  (Manager, Reporting);

-- Standard user
CREATE DEMO USER 'demo_user' PASSWORD 'User1234!' (Employee);

DROP DEMO USER

DROP DEMO USER '<username>';

Example:

DROP DEMO USER 'demo_admin';

Enabling Demo Users

Demo users only appear on the login screen when enabled in project security:

ALTER PROJECT SECURITY DEMO USERS ON;

To hide them:

ALTER PROJECT SECURITY DEMO USERS OFF;

Listing Demo Users

SHOW DEMO USERS;

Typical Setup

-- Enable demo users and set prototype security
ALTER PROJECT SECURITY LEVEL PROTOTYPE;
ALTER PROJECT SECURITY DEMO USERS ON;

-- Create demo accounts for each role
CREATE DEMO USER 'demo_admin' PASSWORD 'Admin123!'
  ENTITY Administration.Account (Administrator);
CREATE DEMO USER 'demo_user' PASSWORD 'User1234!'
  ENTITY Administration.Account (Employee);
CREATE DEMO USER 'demo_guest' PASSWORD 'Guest123!'
  ENTITY Administration.Account (Guest);

See Also

• Security – overview of the security model
• Module Roles and User Roles – defining the user roles assigned to demo users
• GRANT / REVOKE – complete permission management reference

Navigation and Settings

Navigation defines how users move through a Mendix application. Each device type has its own navigation profile with a home page, optional role-specific home pages, a login page, and a menu structure. Project settings control runtime behavior, configurations, languages, and workflows.

Navigation Overview

A Mendix application has one or more navigation profiles, each targeting a device type. MDL supports inspecting and replacing entire profiles.

Inspecting Navigation

-- Summary of all profiles
SHOW NAVIGATION;

-- Menu tree for a specific profile
SHOW NAVIGATION MENU Responsive;

-- Home page assignments across all profiles
SHOW NAVIGATION HOMES;

-- Full MDL output (round-trippable)
DESCRIBE NAVIGATION;
DESCRIBE NAVIGATION Responsive;

Navigation Profiles

See Navigation Profiles for full syntax.

Settings Overview

Project settings control runtime configuration, database connections, languages, and workflow behavior.

-- Overview of all settings
SHOW SETTINGS;

-- Full MDL output
DESCRIBE SETTINGS;

See Project Settings for the ALTER SETTINGS syntax.

See Also

• Navigation Profiles – creating and replacing navigation profiles
• Home Pages and Menus – home page assignments and menu structures
• Project Settings – runtime, configuration, and language settings

Navigation Profiles

A navigation profile defines the navigation structure for a specific device type. Each profile has a default home page, optional role-specific home pages, an optional login page, and a menu.

Profile Types

CREATE OR REPLACE NAVIGATION

Replaces an entire navigation profile:

CREATE OR REPLACE NAVIGATION <Profile>
  HOME PAGE <Module>.<Page>
  [HOME PAGE <Module>.<Page> FOR <Module>.<Role>]
  [LOGIN PAGE <Module>.<Page>]
  [NOT FOUND PAGE <Module>.<Page>]
  [MENU (
    <menu-items>
  )]

Full Example

CREATE OR REPLACE NAVIGATION Responsive
  HOME PAGE MyModule.Home_Web
  HOME PAGE MyModule.AdminHome FOR MyModule.Administrator
  LOGIN PAGE Administration.Login
  NOT FOUND PAGE MyModule.Custom404
  MENU (
    MENU ITEM 'Home' PAGE MyModule.Home_Web;
    MENU ITEM 'Orders' PAGE Shop.Order_Overview;
    MENU 'Administration' (
      MENU ITEM 'Users' PAGE Administration.Account_Overview;
      MENU ITEM 'Settings' PAGE MyModule.Settings;
    );
  );

Minimal Example

A profile only requires a home page:

CREATE OR REPLACE NAVIGATION Phone
  HOME PAGE MyModule.Home_Phone;

DESCRIBE NAVIGATION

View the current navigation profile in MDL syntax:

-- All profiles
DESCRIBE NAVIGATION;

-- Single profile
DESCRIBE NAVIGATION Responsive;

The output is round-trippable – you can copy it, modify it, and execute it as a CREATE OR REPLACE NAVIGATION statement.

See Also

• Navigation and Settings – overview of navigation and settings
• Home Pages and Menus – details on home page and menu configuration
• Project Settings – runtime and configuration settings

Home Pages and Menus

Each navigation profile has a default home page, optional role-specific home pages, and a menu tree. These determine what users see when they first open the application and how they navigate between pages.

Home Pages

Default Home Page

Every profile requires a default home page. This is shown to users whose role has no specific home page assignment:

CREATE OR REPLACE NAVIGATION Responsive
  HOME PAGE MyModule.Home_Web;

Role-Specific Home Pages

Use HOME PAGE ... FOR to direct users to different pages based on their module role:

CREATE OR REPLACE NAVIGATION Responsive
  HOME PAGE MyModule.Home_Web
  HOME PAGE MyModule.AdminDashboard FOR MyModule.Administrator
  HOME PAGE MyModule.ManagerDashboard FOR MyModule.Manager;

When a user logs in, the runtime checks their roles and redirects to the most specific matching home page. If no role-specific page matches, the default home page is used.

Login Page

The login page is shown to unauthenticated users:

CREATE OR REPLACE NAVIGATION Responsive
  HOME PAGE MyModule.Home_Web
  LOGIN PAGE Administration.Login;

Not Found Page

An optional custom 404 page:

CREATE OR REPLACE NAVIGATION Responsive
  HOME PAGE MyModule.Home_Web
  NOT FOUND PAGE MyModule.Custom404;

Menus

The MENU block defines the navigation menu as a tree of items and submenus.

Menu Items

A menu item links a label to a page:

MENU ITEM '<label>' PAGE <Module>.<Page>;

Submenus

Nest items inside a MENU '<label>' (...) block:

MENU '<label>' (
  <menu-items>
);

Complete Example

CREATE OR REPLACE NAVIGATION Responsive
  HOME PAGE Shop.Home
  LOGIN PAGE Administration.Login
  MENU (
    MENU ITEM 'Home' PAGE Shop.Home;
    MENU ITEM 'Products' PAGE Shop.Product_Overview;
    MENU ITEM 'Orders' PAGE Shop.Order_Overview;
    MENU 'Administration' (
      MENU ITEM 'Users' PAGE Administration.Account_Overview;
      MENU ITEM 'Roles' PAGE Administration.Role_Overview;
      MENU 'System' (
        MENU ITEM 'Logs' PAGE Administration.Log_Overview;
        MENU ITEM 'Settings' PAGE Shop.Settings;
      );
    );
  );

Inspecting Menus

-- View menu tree
SHOW NAVIGATION MENU;
SHOW NAVIGATION MENU Responsive;

-- View home page assignments
SHOW NAVIGATION HOMES;

See Also

• Navigation and Settings – overview of navigation concepts
• Navigation Profiles – profile types and CREATE OR REPLACE syntax
• Project Settings – runtime and configuration settings

Project Settings

Project settings control application runtime behavior, server configurations, language settings, and workflow configuration. MDL provides commands to inspect and modify all settings categories.

Inspecting Settings

-- Overview of all settings
SHOW SETTINGS;

-- Full MDL output (round-trippable)
DESCRIBE SETTINGS;

ALTER SETTINGS

Settings are organized into categories. Each ALTER SETTINGS command targets one category.

Model Settings

Runtime-level settings such as the after-startup microflow, hashing algorithm, and Java version:

ALTER SETTINGS MODEL <Key> = <Value>;

Examples:

ALTER SETTINGS MODEL AfterStartupMicroflow = 'MyModule.ACT_Startup';
ALTER SETTINGS MODEL HashAlgorithm = 'BCrypt';
ALTER SETTINGS MODEL JavaVersion = '17';

Configuration Settings

Server configuration settings like database type, URL, and HTTP port. Each configuration is identified by name (commonly 'default'):

ALTER SETTINGS CONFIGURATION '<Name>' <Key> = <Value>;

Examples:

ALTER SETTINGS CONFIGURATION 'default' DatabaseType = 'POSTGRESQL';
ALTER SETTINGS CONFIGURATION 'default' DatabaseUrl = 'jdbc:postgresql://localhost:5432/myapp';
ALTER SETTINGS CONFIGURATION 'default' HttpPortNumber = '8080';

Constant Overrides

Override a constant value within a specific configuration:

ALTER SETTINGS CONSTANT '<ConstantName>' VALUE '<value>' IN CONFIGURATION '<cfg>';

Example:

ALTER SETTINGS CONSTANT 'MyModule.ApiBaseUrl' VALUE 'https://staging.example.com' IN CONFIGURATION 'default';

Language Settings

Set the default language for the application:

ALTER SETTINGS LANGUAGE <Key> = <Value>;

Example:

ALTER SETTINGS LANGUAGE DefaultLanguageCode = 'en_US';

Workflow Settings

Configure workflow behavior such as the user entity and task parallelism:

ALTER SETTINGS WORKFLOWS <Key> = <Value>;

Examples:

ALTER SETTINGS WORKFLOWS UserEntity = 'Administration.Account';
ALTER SETTINGS WORKFLOWS DefaultTaskParallelism = '5';

See Also

• Navigation and Settings – overview of navigation and settings
• Navigation Profiles – navigation profile configuration
• Workflows – workflow definitions

Workflows

Workflows model long-running, multi-step business processes such as approval chains, onboarding sequences, and review cycles. Unlike microflows, which execute synchronously in a single transaction, workflows persist their state and can pause indefinitely – waiting for user input, timers, or external notifications.

When to Use Workflows

Workflows are appropriate when a process:

• Involves human tasks that require user action at specific steps
• Spans hours, days, or weeks rather than completing instantly
• Has branching logic based on user decisions (approve / reject / escalate)
• Needs a visual overview of progress for administrators

For immediate, transactional logic, use microflows instead. See Workflow vs Microflow for a detailed comparison.

Inspecting Workflows

-- List all workflows
SHOW WORKFLOWS;
SHOW WORKFLOWS IN MyModule;

-- View full definition
DESCRIBE WORKFLOW MyModule.ApprovalFlow;

Quick Example

CREATE WORKFLOW Approval.RequestApproval
  PARAMETER $Context: Approval.Request
  OVERVIEW PAGE Approval.WorkflowOverview
BEGIN
  USER TASK ReviewTask 'Review the request'
    PAGE Approval.ReviewPage
    OUTCOMES 'Approve' {
      CALL MICROFLOW Approval.ACT_Approve;
    } 'Reject' {
      CALL MICROFLOW Approval.ACT_Reject;
    };
END WORKFLOW;

See Also

• Workflow Structure – full CREATE WORKFLOW syntax
• Activity Types – all workflow activity types
• Workflow vs Microflow – choosing between the two
• GRANT / REVOKE – granting execute access on workflows

Workflow Structure

A workflow definition consists of a context parameter, an optional overview page, and a sequence of activities. Activities execute in order unless control flow elements (decisions, parallel splits, jumps) alter the sequence.

CREATE WORKFLOW

CREATE [OR MODIFY] WORKFLOW <Module>.<Name>
  PARAMETER $<Name>: <Module>.<Entity>
  [OVERVIEW PAGE <Module>.<Page>]
BEGIN
  <activities>
END WORKFLOW;

Full Example

CREATE WORKFLOW HR.OnboardEmployee
  PARAMETER $Context: HR.OnboardingRequest
  OVERVIEW PAGE HR.OnboardingOverview
BEGIN
  -- Parallel: IT setup and HR paperwork happen simultaneously
  PARALLEL SPLIT
    PATH 1 {
      USER TASK SetupLaptop 'Set up laptop and accounts'
        PAGE HR.IT_SetupPage
        OUTCOMES 'Done' { };
    }
    PATH 2 {
      USER TASK SignDocuments 'Sign employment documents'
        PAGE HR.DocumentSignPage
        OUTCOMES 'Signed' { };
    };

  -- After both paths complete, manager reviews
  DECISION 'Manager approval required?'
    OUTCOMES 'Yes' {
      USER TASK ManagerReview 'Review onboarding'
        PAGE HR.ManagerReviewPage
        OUTCOMES 'Approve' { } 'Reject' {
          CALL MICROFLOW HR.ACT_RejectOnboarding;
          END;
        };
    } 'No' { };

  CALL MICROFLOW HR.ACT_CompleteOnboarding;
END WORKFLOW;

DROP WORKFLOW

DROP WORKFLOW HR.OnboardEmployee;

Workflow Access

Grant or revoke execute access to control who can start a workflow:

GRANT EXECUTE ON WORKFLOW HR.OnboardEmployee TO HR.Manager, HR.Admin;
REVOKE EXECUTE ON WORKFLOW HR.OnboardEmployee FROM HR.Manager;

See Also

• Workflows – overview and when to use workflows
• Activity Types – details on each activity type
• Workflow vs Microflow – choosing the right construct

Activity Types

Workflow activities are the building blocks of a workflow definition. Each activity type serves a different purpose, from waiting for user input to calling microflows or branching execution.

User Task

A user task pauses the workflow until a user completes it. Each outcome resumes the workflow down a different path.

USER TASK <name> '<caption>'
  [PAGE <Module>.<Page>]
  [TARGETING MICROFLOW <Module>.<Microflow>]
  OUTCOMES '<outcome>' { <activities> } ['<outcome>' { <activities> }] ...;

Example:

USER TASK ReviewTask 'Review the request'
  PAGE Approval.ReviewPage
  TARGETING MICROFLOW Approval.ACT_GetReviewers
  OUTCOMES 'Approve' {
    CALL MICROFLOW Approval.ACT_Approve;
  } 'Reject' {
    CALL MICROFLOW Approval.ACT_Reject;
    END;
  };

Call Microflow

Execute a microflow as part of the workflow. Optionally specify a comment and outcomes:

CALL MICROFLOW <Module>.<Name> [COMMENT '<text>']
  [OUTCOMES '<outcome>' { <activities> } ...];

Example:

CALL MICROFLOW HR.ACT_SendNotification COMMENT 'Notify the applicant';

Call Workflow

Start a sub-workflow:

CALL WORKFLOW <Module>.<Name> [COMMENT '<text>'];

Example:

CALL WORKFLOW HR.BackgroundCheck COMMENT 'Run background check sub-process';

Decision

Branch the workflow based on a condition. Each outcome contains a block of activities:

DECISION ['<caption>']
  OUTCOMES '<outcome>' { <activities> } ['<outcome>' { <activities> }] ...;

Example:

DECISION 'Order value over $1000?'
  OUTCOMES 'Yes' {
    USER TASK ManagerApproval 'Manager must approve'
      PAGE Shop.ApprovalPage
      OUTCOMES 'Approved' { } 'Rejected' { END; };
  } 'No' { };

Parallel Split

Execute multiple paths concurrently. The workflow continues after all paths complete:

PARALLEL SPLIT
  PATH 1 { <activities> }
  PATH 2 { <activities> }
  [PATH 3 { <activities> }] ...;

Example:

PARALLEL SPLIT
  PATH 1 {
    USER TASK LegalReview 'Legal review'
      PAGE Legal.ReviewPage
      OUTCOMES 'Approved' { };
  }
  PATH 2 {
    USER TASK FinanceReview 'Finance review'
      PAGE Finance.ReviewPage
      OUTCOMES 'Approved' { };
  };

Jump To

Jump to a named activity elsewhere in the workflow (creates a loop or skip):

JUMP TO <activity-name>;

Example:

JUMP TO ReviewTask;

Wait for Timer

Pause the workflow until a timer expression evaluates:

WAIT FOR TIMER ['<expression>'];

Example:

WAIT FOR TIMER 'addDays([%CurrentDateTime%], 3)';

Wait for Notification

Pause the workflow until an external notification resumes it:

WAIT FOR NOTIFICATION;

End

Terminate the current workflow path:

END;

Typically used inside an outcome block to stop the workflow after a rejection or cancellation.

Summary Table

See Also

• Workflows – overview and when to use workflows
• Workflow Structure – CREATE WORKFLOW syntax
• Workflow vs Microflow – choosing between workflows and microflows

Workflow vs Microflow

Workflows and microflows are both used to express business logic, but they serve different purposes and have different execution models.

Comparison

When to Use a Microflow

Use a microflow when:

• The operation completes immediately (create, update, delete, calculate)
• No human decision points are needed
• The logic runs within a single database transaction
• You need fine-grained error handling with rollback

CREATE MICROFLOW Shop.ACT_ProcessPayment
BEGIN
  DECLARE $Order Shop.Order;
  RETRIEVE $Order FROM Shop.Order WHERE [OrderId = $OrderId] LIMIT 1;
  CHANGE $Order (Status = 'Paid', PaidDate = [%CurrentDateTime%]);
  COMMIT $Order;
  RETURN true;
END;

When to Use a Workflow

Use a workflow when:

• The process involves human approval or review steps
• The process spans multiple days or longer
• You need a visual overview of where each case stands
• Multiple steps should happen in parallel
• The process may wait for external events

CREATE WORKFLOW Shop.OrderApproval
  PARAMETER $Context: Shop.Order
  OVERVIEW PAGE Shop.OrderWorkflowOverview
BEGIN
  USER TASK ReviewOrder 'Review the order'
    PAGE Shop.OrderReviewPage
    OUTCOMES 'Approve' {
      CALL MICROFLOW Shop.ACT_ApproveOrder;
    } 'Reject' {
      CALL MICROFLOW Shop.ACT_RejectOrder;
      END;
    };
  CALL MICROFLOW Shop.ACT_FulfillOrder;
END WORKFLOW;

Combining Both

Workflows and microflows work together. A workflow orchestrates the process while microflows handle the actual logic at each step:

1. Workflow defines the process: who needs to act, in what order, with what outcomes
2. Microflows execute within workflow steps: create objects, send emails, update status
3. Pages provide the UI for user tasks

A common pattern is:

-- Microflow does the work
CREATE MICROFLOW Approval.ACT_Approve
BEGIN
  DECLARE $Request Approval.Request;
  RETRIEVE $Request FROM Approval.Request WHERE [id = $RequestId] LIMIT 1;
  CHANGE $Request (Status = 'Approved', ApprovedBy = '[%CurrentUser%]');
  COMMIT $Request;
END;

-- Workflow orchestrates the process
CREATE WORKFLOW Approval.ApprovalProcess
  PARAMETER $Context: Approval.Request
BEGIN
  USER TASK Review 'Review request'
    PAGE Approval.ReviewPage
    OUTCOMES 'Approve' {
      CALL MICROFLOW Approval.ACT_Approve;
    } 'Reject' {
      CALL MICROFLOW Approval.ACT_Reject;
      END;
    };
END WORKFLOW;

See Also

• Workflows – workflow overview
• Workflow Structure – CREATE WORKFLOW syntax
• Activity Types – workflow activity reference
• Microflows and Nanoflows – microflow overview

Business Events

Business events enable event-driven integration between Mendix applications. An application can publish events when something happens (e.g., an order is placed) and other applications can subscribe to those events and react accordingly.

Business events are organized into event services, each of which defines one or more messages with typed attributes.

Inspecting Business Events

-- List all business event services
SHOW BUSINESS EVENTS;
SHOW BUSINESS EVENTS IN MyModule;

-- View full definition
DESCRIBE BUSINESS EVENT SERVICE MyModule.OrderEvents;

Quick Example

CREATE BUSINESS EVENT SERVICE Shop.OrderEvents (
  Version: '1.0',
  Description: 'Events related to order lifecycle'
) {
  MESSAGE OrderPlaced (
    OrderId: String,
    CustomerName: String,
    TotalAmount: Decimal,
    OrderDate: DateTime
  )
  MESSAGE OrderShipped (
    OrderId: String,
    TrackingNumber: String,
    ShippedDate: DateTime
  )
};

See Also

• Event Services – CREATE and DROP syntax for event services
• Publishing and Consuming Events – event publishing and consumption patterns

Event Services

An event service is a named container for business event messages. It defines the contract between publishers and consumers: what events exist and what data each event carries.

CREATE BUSINESS EVENT SERVICE

CREATE BUSINESS EVENT SERVICE <Module>.<Name> (
  [Version: '<version>',]
  [Description: '<text>']
) {
  MESSAGE <MessageName> (
    <AttributeName>: <Type> [, ...]
  )
  [MESSAGE <MessageName> ( ... )]
};

Attribute Types

Message attributes support standard Mendix types:

Example

CREATE BUSINESS EVENT SERVICE HR.EmployeeEvents (
  Version: '2.0',
  Description: 'Employee lifecycle events'
) {
  MESSAGE EmployeeHired (
    EmployeeId: String,
    FullName: String,
    Department: String,
    StartDate: DateTime
  )
  MESSAGE EmployeeTerminated (
    EmployeeId: String,
    TerminationDate: DateTime,
    Reason: String
  )
};

DROP BUSINESS EVENT SERVICE

Remove an event service:

DROP BUSINESS EVENT SERVICE HR.EmployeeEvents;

Listing and Inspecting

-- List all services
SHOW BUSINESS EVENTS;

-- Filter by module
SHOW BUSINESS EVENTS IN HR;

-- Full MDL definition
DESCRIBE BUSINESS EVENT SERVICE HR.EmployeeEvents;

The DESCRIBE output is round-trippable – it can be copied, modified, and executed as a CREATE statement.

See Also

• Business Events – overview of business events
• Publishing and Consuming Events – event publishing and consumption patterns

Publishing and Consuming Events

Business events follow a publish-subscribe pattern. One application publishes events when significant actions occur, and other applications consume those events to trigger their own logic.

Publishing Events

A publishing application defines a business event service with its message types:

CREATE BUSINESS EVENT SERVICE Shop.OrderEvents (
  Version: '1.0',
  Description: 'Order lifecycle events'
) {
  MESSAGE OrderPlaced (
    OrderId: String,
    CustomerName: String,
    TotalAmount: Decimal,
    OrderDate: DateTime
  )
  MESSAGE OrderCancelled (
    OrderId: String,
    Reason: String,
    CancelledDate: DateTime
  )
};

The event service acts as a contract. Consuming applications rely on the message structure, so changes to attribute names or types should be accompanied by a version increment.

Consuming Events

A consuming application subscribes to events from another application’s event service. When an event is received, a configured microflow is triggered to handle it.

The consumption side is typically configured in Mendix Studio Pro by selecting the published event service and mapping each message to a handler microflow. The handler microflow receives the event attributes as parameters.

Handler Pattern

A typical handler microflow processes the incoming event data:

CREATE MICROFLOW Warehouse.ACT_HandleOrderPlaced
BEGIN
  -- Parameters: $OrderId (String), $CustomerName (String), etc.
  DECLARE $ShipmentRequest Warehouse.ShipmentRequest;
  $ShipmentRequest = CREATE Warehouse.ShipmentRequest (
    ExternalOrderId = $OrderId,
    CustomerName = $CustomerName,
    Status = 'Pending'
  );
  COMMIT $ShipmentRequest;
END;

Versioning

Event services include a version string to track contract changes:

CREATE BUSINESS EVENT SERVICE Shop.OrderEvents (
  Version: '2.0',
  Description: 'Order events - v2 adds ShippingAddress'
) {
  MESSAGE OrderPlaced (
    OrderId: String,
    CustomerName: String,
    TotalAmount: Decimal,
    OrderDate: DateTime,
    ShippingAddress: String
  )
};

When adding new attributes, increment the version so consuming applications know to update their handlers.

Use Cases

See Also

• Business Events – overview of business events
• Event Services – CREATE and DROP syntax

Image Collections

Image collections are Mendix’s way of bundling images (icons, logos, graphics) within a module. Each collection can contain multiple images in various formats (PNG, SVG, GIF, JPEG, BMP, WebP).

Inspecting Image Collections

-- List all image collections across all modules
SHOW IMAGE COLLECTION;

-- Filter by module
SHOW IMAGE COLLECTION IN MyModule;

-- View full definition including embedded images
DESCRIBE IMAGE COLLECTION MyModule.AppIcons;

The DESCRIBE output includes the full CREATE statement. If the collection contains images, they are shown with IMAGE 'name' FROM FILE 'path' syntax that can be copied and re-executed. In the TUI, images are rendered inline when the terminal supports it (Kitty, iTerm2, Sixel).

CREATE IMAGE COLLECTION

CREATE IMAGE COLLECTION <Module>.<Name>
  [EXPORT LEVEL 'Hidden'|'Public']
  [COMMENT '<description>']
  [(
    IMAGE <Name> FROM FILE '<path>',
    ...
  )];

The image format is detected automatically from the file extension. Relative paths are resolved from the current working directory. Supported formats: PNG, SVG, GIF, JPEG, BMP, WebP.

Examples

-- Minimal: empty collection
CREATE IMAGE COLLECTION MyModule.AppIcons;

-- With export level
CREATE IMAGE COLLECTION MyModule.SharedIcons EXPORT LEVEL 'Public';

-- With comment
CREATE IMAGE COLLECTION MyModule.StatusIcons
  COMMENT 'Icons for order and task status indicators';

-- With images from files
CREATE IMAGE COLLECTION MyModule.NavigationIcons (
  IMAGE home FROM FILE 'assets/home.png',
  IMAGE settings FROM FILE 'assets/settings.svg'
);

-- All options combined
CREATE IMAGE COLLECTION MyModule.BrandAssets
  EXPORT LEVEL 'Public'
  COMMENT 'Company branding assets' (
  IMAGE logo_dark FROM FILE 'assets/logo-dark.png',
  IMAGE logo_light FROM FILE 'assets/logo-light.png'
);

DROP IMAGE COLLECTION

Remove a collection and all its embedded images:

DROP IMAGE COLLECTION MyModule.StatusIcons;

See Also

• MDL Quick Reference – syntax summary table

Code Navigation

mxcli provides a suite of cross-reference navigation commands that let you explore relationships between elements in a Mendix project. These commands answer questions like “what calls this microflow?”, “what would break if I change this entity?”, and “what does this element depend on?”

Prerequisites

Cross-reference navigation commands require a full catalog refresh before use:

REFRESH CATALOG FULL

This populates the reference data needed for callers, callees, references, impact, and context queries. A basic REFRESH CATALOG only builds metadata tables and is not sufficient for cross-reference navigation.

Available Commands

CLI Subcommands

These commands are also available as CLI subcommands for scripting and piping:

mxcli callers -p app.mpr Module.MyMicroflow
mxcli callees -p app.mpr Module.MyMicroflow
mxcli refs -p app.mpr Module.Customer
mxcli impact -p app.mpr Module.Customer
mxcli context -p app.mpr Module.MyMicroflow --depth 3
mxcli search -p app.mpr "validation"

Typical Workflow

1. Refresh the catalog to ensure cross-reference data is current
2. Explore references to understand how elements are connected
3. Analyze impact before making changes
4. Use context to gather surrounding information for AI-assisted development

-- Step 1: Build the catalog
REFRESH CATALOG FULL;

-- Step 2: Understand what uses a microflow
SHOW CALLERS OF Sales.ACT_ProcessOrder;

-- Step 3: Check impact before renaming an entity
SHOW IMPACT OF Sales.Customer;

-- Step 4: Gather context for AI consumption
SHOW CONTEXT OF Sales.SubmitOrder;

How AI Assistants Use This

When you ask an AI assistant to modify an element, it uses these commands to:

1. Discover dependencies with SHOW CALLERS and SHOW REFERENCES
2. Assess risk with SHOW IMPACT before making changes
3. Gather context with SHOW CONTEXT for informed code generation
4. Find related elements with SEARCH to understand patterns

SHOW CALLERS / CALLEES

These commands trace the call graph of your Mendix project, showing what calls a given element and what that element calls.

Prerequisites

Both commands require a full catalog refresh:

REFRESH CATALOG FULL;

SHOW CALLERS OF

Shows all elements that call or reference a given element.

Syntax:

SHOW CALLERS OF <qualified-name>

Examples:

-- Find everything that calls a microflow
SHOW CALLERS OF Sales.ACT_ProcessOrder;

-- Find what references an entity
SHOW CALLERS OF Sales.Customer;

-- Find what uses a page
SHOW CALLERS OF Sales.CustomerOverview;

CLI Usage

# Basic caller lookup
mxcli callers -p app.mpr Module.MyMicroflow

# Transitive callers (full call chain)
mxcli callers -p app.mpr Module.MyMicroflow --transitive

The --transitive flag follows the call chain recursively, showing not just direct callers but also callers of callers.

SHOW CALLEES OF

Shows all elements that a given element calls or references.

Syntax:

SHOW CALLEES OF <qualified-name>

Examples:

-- Find what a microflow calls
SHOW CALLEES OF Sales.ACT_ProcessOrder;

-- Find what entities a microflow uses
SHOW CALLEES OF Sales.SubmitOrder;

CLI Usage

mxcli callees -p app.mpr Module.MyMicroflow

Use Cases

Before Refactoring

Check what calls a microflow before renaming or modifying it:

SHOW CALLERS OF Sales.ACT_OldName;
-- Review the list of callers before making changes

Understanding Dependencies

Trace the full call chain of a complex microflow:

SHOW CALLEES OF Sales.ACT_ProcessOrder;
-- Shows: Sales.ValidateOrder, Sales.UpdateInventory, Sales.SendConfirmation

Finding Dead Code

If SHOW CALLERS returns no results, the element may be unused:

SHOW CALLERS OF Sales.ACT_UnusedMicroflow;
-- Empty result = potentially dead code

SHOW REFERENCES / IMPACT

These commands provide broader reference tracking and impact analysis, helping you understand how changes propagate through a project.

Prerequisites

Both commands require a full catalog refresh:

REFRESH CATALOG FULL;

SHOW REFERENCES OF

Shows all references to and from a given element, combining both incoming and outgoing relationships.

Syntax:

SHOW REFERENCES OF <qualified-name>

Examples:

-- Find all references to/from an entity
SHOW REFERENCES OF Sales.Customer;

-- Find all references to/from a microflow
SHOW REFERENCES OF Sales.ACT_ProcessOrder;

-- Find all references to/from a page
SHOW REFERENCES OF Sales.CustomerOverview;

CLI Usage

mxcli refs -p app.mpr Module.Customer

Difference from CALLERS/CALLEES

While SHOW CALLERS and SHOW CALLEES focus on the call graph direction, SHOW REFERENCES combines both directions into a single view. It shows every element that either references or is referenced by the target element.

SHOW IMPACT OF

Performs impact analysis on an element, showing what would be affected if you changed or removed it.

Syntax:

SHOW IMPACT OF <qualified-name>

Examples:

-- Analyze impact of changing an entity
SHOW IMPACT OF Sales.Customer;

-- Analyze impact before removing a microflow
SHOW IMPACT OF Sales.ACT_CalculateTotal;

-- Check impact before moving an element
SHOW IMPACT OF Sales.CustomerOverview;

CLI Usage

mxcli impact -p app.mpr Module.Customer

Use Cases

Pre-Change Impact Assessment

Before modifying an entity, check what would be affected:

-- What depends on the Customer entity?
SHOW IMPACT OF Sales.Customer;

-- Review results: pages, microflows, associations, access rules
-- Then decide if the change is safe to make

Before Moving Elements

Moving elements across modules changes their qualified name and can break references:

-- Check impact before moving
SHOW IMPACT OF OldModule.Customer;

-- If impact is acceptable, proceed
MOVE ENTITY OldModule.Customer TO NewModule;

Finding All Usages of an Enumeration

SHOW REFERENCES OF Sales.OrderStatus;
-- Shows: entities with attributes of this type, microflows that use it, pages that display it

Dependency Mapping

Understand the full dependency web of a complex module:

SHOW REFERENCES OF Sales.Order;
SHOW REFERENCES OF Sales.OrderLine;
SHOW REFERENCES OF Sales.Order_Customer;

SHOW CONTEXT

The SHOW CONTEXT command assembles the surrounding context of an element within its module and project hierarchy. This is particularly useful for AI-assisted development, where an LLM needs to understand the neighborhood of an element to generate accurate code.

Prerequisites

Requires a full catalog refresh:

REFRESH CATALOG FULL;

Syntax

SHOW CONTEXT OF <qualified-name>

Examples

-- Show context of a microflow
SHOW CONTEXT OF Sales.ACT_ProcessOrder;

-- Show context of an entity
SHOW CONTEXT OF Sales.Customer;

-- Show context of a page
SHOW CONTEXT OF Sales.CustomerOverview;

CLI Usage

# Basic context retrieval
mxcli context -p app.mpr Module.MyMicroflow

# With depth control
mxcli context -p app.mpr Module.MyMicroflow --depth 3

The --depth flag controls how many levels of related elements are included in the context output. A higher depth gives a broader picture but produces more output.

What Context Includes

The context command gathers information about:

• The element’s own definition (MDL source)
• Elements that call it (callers)
• Elements it calls (callees)
• Related entities and associations
• Pages that display or edit the same data
• The module structure surrounding the element

Use Case: AI-Assisted Development

When an AI assistant needs to modify a microflow, it uses SHOW CONTEXT to understand:

1. What parameters the microflow expects
2. What entities and associations are involved
3. What other microflows it interacts with
4. What pages display the same data

This information allows the AI to generate code that fits naturally into the existing project structure.

# Gather context for an AI prompt
mxcli context -p app.mpr Sales.ACT_ProcessOrder --depth 2

Full-Text Search

The SEARCH command performs full-text search across all strings and source code in a Mendix project. It searches element names, documentation, captions, expressions, and other string content.

Syntax

SEARCH '<keyword>'

Examples

-- Search for a keyword
SEARCH 'validation';

-- Search for an entity name
SEARCH 'Customer';

-- Search for error messages
SEARCH 'cannot be empty';

-- Search for specific patterns
SEARCH 'CurrentDateTime';

CLI Usage

# Basic search
mxcli search -p app.mpr "validation"

# Quiet mode (no headers/formatting), suitable for piping
mxcli search -p app.mpr "validation" -q

# Output as names (type<TAB>name per line)
mxcli search -p app.mpr "validation" -q --format names

# Output as JSON array
mxcli search -p app.mpr "validation" -q --format json

Output Formats

The -q (quiet) flag suppresses headers and formatting, making output suitable for piping to other commands.

Piping Search Results

Search results can be piped to other mxcli commands for powerful workflows:

# Find the first microflow matching "error" and describe it
mxcli search -p app.mpr "error" -q --format names | head -1 | awk '{print $2}' | \
  xargs mxcli describe -p app.mpr microflow

What Gets Searched

The search command looks through:

• Element names (entities, microflows, pages, etc.)
• Documentation comments
• Attribute names and captions
• Expression strings in microflows
• Widget captions and labels
• Enumeration value captions
• Log message strings
• Validation feedback messages

Comparison with Catalog Queries

SEARCH provides quick keyword-based search, while catalog queries (SELECT FROM CATALOG.*) provide structured SQL-based queries with filtering, joining, and aggregation. Use SEARCH for quick discovery and catalog queries for precise analysis.

-- Quick search: find anything mentioning "Customer"
SEARCH 'Customer';

-- Precise query: find entities named Customer with their module
SELECT Name, ModuleName FROM CATALOG.ENTITIES WHERE Name LIKE '%Customer%';

Catalog Queries

The catalog is a SQLite-based query system that provides SQL access to project metadata. It indexes all elements in your Mendix project – entities, microflows, pages, associations, attributes, and more – into queryable tables that support standard SQL syntax.

How It Works

The catalog builds an in-memory SQLite database from the project’s MPR file. This database is cached in .mxcli/catalog.db next to the MPR file for fast subsequent access.

There are two levels of catalog refresh:

Quick Start

-- Build the catalog
REFRESH CATALOG;

-- See what tables are available
SHOW CATALOG TABLES;

-- Query entities in a module
SELECT Name, EntityType FROM CATALOG.ENTITIES WHERE ModuleName = 'Sales';

-- Find microflows that reference an entity
SELECT Name, ModuleName FROM CATALOG.MICROFLOWS
WHERE Description LIKE '%Customer%' OR Name LIKE '%Customer%';

Key Features

• Standard SQL syntax – SELECT, WHERE, JOIN, GROUP BY, ORDER BY, HAVING, UNION
• Multiple tables – Entities, attributes, associations, microflows, pages, and more
• Cross-reference data – Available after REFRESH CATALOG FULL
• Cached for performance – Stored in .mxcli/catalog.db next to the MPR file
• AI-friendly – Structured data that AI assistants can query programmatically

CLI Usage

# Refresh catalog
mxcli -p app.mpr -c "REFRESH CATALOG"
mxcli -p app.mpr -c "REFRESH CATALOG FULL"

# Query catalog
mxcli -p app.mpr -c "SELECT Name FROM CATALOG.MICROFLOWS LIMIT 10"
mxcli -p app.mpr -c "SHOW CATALOG TABLES"

Related Pages

• REFRESH CATALOG – Building and refreshing the catalog
• Available Tables – What tables are available
• SQL Queries – Query syntax and examples
• Use Cases – Practical analysis examples

REFRESH CATALOG

The REFRESH CATALOG command builds or rebuilds the catalog index from the current project state. The catalog must be refreshed before running catalog queries or cross-reference navigation commands.

Syntax

-- Basic refresh: builds metadata tables
REFRESH CATALOG

-- Full refresh: builds metadata + cross-references + source
REFRESH CATALOG FULL

-- Force rebuild: ignores cached catalog
REFRESH CATALOG FULL FORCE

Refresh Levels

Basic Refresh

REFRESH CATALOG;

Builds the core metadata tables: entities, attributes, associations, microflows, pages, enumerations, and other element types. This is sufficient for structural queries like “list all entities in a module” or “find pages with a specific URL.”

Full Refresh

REFRESH CATALOG FULL;

Builds everything in the basic refresh plus:

• Cross-reference data – Which elements reference which other elements
• Source content – Microflow activity content, expression strings, widget properties
• Call graph – Caller/callee relationships between elements

This level is required for:

• SHOW CALLERS OF
• SHOW CALLEES OF
• SHOW REFERENCES OF
• SHOW IMPACT OF
• SHOW CONTEXT OF
• SEARCH
• Full-text catalog queries

Force Rebuild

REFRESH CATALOG FULL FORCE;

Ignores the cached .mxcli/catalog.db file and rebuilds from scratch. Use this when the catalog appears stale or corrupt.

CLI Usage

# Quick refresh
mxcli -p app.mpr -c "REFRESH CATALOG"

# Full refresh with cross-references
mxcli -p app.mpr -c "REFRESH CATALOG FULL"

# Force rebuild
mxcli -p app.mpr -c "REFRESH CATALOG FULL FORCE"

Caching

The catalog is cached in .mxcli/catalog.db next to the MPR file. On subsequent refreshes, mxcli checks whether the project has changed and only rebuilds if necessary (unless FORCE is specified).

When to Refresh

• After opening a project – Run REFRESH CATALOG to enable queries
• Before cross-reference navigation – Run REFRESH CATALOG FULL to enable CALLERS/CALLEES/IMPACT
• After making changes – Refresh to update the catalog with new elements
• If results seem stale – Use REFRESH CATALOG FULL FORCE to force a rebuild