Skip to content

Commit 37b4438

Browse files
akoclaude
ako
and
claude
committed
docs: add migration guide to docs site
Five-phase migration workflow: assessment, transformation plan, generation, data migration, and validation/handoff. Covers available skills (assess-migration, platform-specific guides, data import) and the SQL CONNECT / IMPORT FROM / GENERATE CONNECTOR pipeline. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent bf6b1a0 commit 37b4438

File tree

8 files changed

+477
-15
lines changed

8 files changed

+477
-15
lines changed

‎docs-site/src/SUMMARY.md‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,18 @@
3232

3333
---
3434

35-
# Part II: The MDL Language
35+
# Part II: Migration
36+
37+
- [Migration Guide](migration/README.md)
38+
- [Assessment](migration/assessment.md)
39+
- [Transformation Plan](migration/transformation.md)
40+
- [Generation](migration/generation.md)
41+
- [Data Migration](migration/data-migration.md)
42+
- [Validation and Handoff](migration/validation.md)
43+
44+
---
45+
46+
# Part III: The MDL Language
3647

3748
- [MDL Basics](language/basics.md)
3849
- [Lexical Structure](language/lexical-structure.md)
@@ -86,7 +97,7 @@
8697

8798
---
8899

89-
# Part III: Project Tools
100+
# Part IV: Project Tools
90101

91102
- [Code Navigation](tools/code-navigation.md)
92103
- [SHOW CALLERS / CALLEES](tools/callers-callees.md)
@@ -131,7 +142,7 @@
131142

132143
---
133144

134-
# Part IV: IDE Integration
145+
# Part V: IDE Integration
135146

136147
- [VS Code Extension](ide/vscode.md)
137148
- [Installation](ide/vscode-installation.md)
@@ -150,7 +161,7 @@
150161

151162
---
152163

153-
# Part V: Go Library
164+
# Part VI: Go Library
154165

155166
- [Quick Start](library/quickstart.md)
156167
- [Installation](library/installation.md)
@@ -167,7 +178,7 @@
167178

168179
---
169180

170-
# Part VI: MDL Statement Reference
181+
# Part VII: MDL Statement Reference
171182

172183
- [Connection Statements](reference/connection/README.md)
173184
- [OPEN PROJECT](reference/connection/open-project.md)
@@ -255,7 +266,7 @@
255266

256267
---
257268

258-
# Part VII: Architecture & Internals
269+
# Part VIII: Architecture & Internals
259270

260271
- [System Architecture](internals/architecture.md)
261272
- [Layer Diagram](internals/layers.md)
@@ -277,7 +288,7 @@
277288

278289
---
279290

280-
# Part VIII: Appendixes
291+
# Part IX: Appendixes
281292

282293
- [MDL Quick Reference](appendixes/quick-reference.md)
283294
- [Data Type Mapping Table](appendixes/data-type-mapping.md)

‎docs-site/src/migration/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Migration Guide
2+
3+
mxcli and MDL enable AI-assisted migration of existing applications to the Mendix platform. An AI coding agent (Claude Code, Cursor, Windsurf) investigates the source application, maps its elements to Mendix concepts, generates MDL scripts, and validates the result -- all from the command line.
4+
5+
This part covers the five-phase migration workflow and the skills that support each phase.
6+
7+
## Why mxcli for Migration?
8+
9+
Traditional migrations require deep Mendix expertise and manual work in Studio Pro. With mxcli:
10+
11+
- **AI agents do the heavy lifting** -- the agent reads source code, proposes a transformation plan, and generates MDL scripts
12+
- **Skills provide guardrails** -- platform-specific migration skills guide the agent with correct mappings, naming conventions, and patterns
13+
- **Validation is automated** -- `mxcli check`, `lint`, `docker check`, and `test` catch errors before anyone opens Studio Pro
14+
- **The process is repeatable** -- MDL scripts can be version-controlled, reviewed, and re-run
15+
16+
## The Five Phases
17+
18+
```
19+
Phase 1 Phase 2 Phase 3 Phase 4 Phase 5
20+
┌──────────┐ ┌───────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────┐
21+
│ Assess │──▶│ Propose │──▶│ Generate │──▶│ Test │──▶│ Finish │
22+
│ Source │ │ Transform │ │ Mendix App │ │ & Lint │ │ in Studio│
23+
└──────────┘ └───────────┘ └──────────────┘ └──────────┘ │ Pro │
24+
└──────────┘
25+
```
26+
27+
| Phase | What Happens | Key Skills |
28+
|-------|-------------|------------|
29+
| [Assessment](assessment.md) | Investigate source application, produce inventory | `assess-migration`, platform-specific skills |
30+
| [Transformation](transformation.md) | Map source elements to Mendix, plan module structure | Assessment output as input |
31+
| [Generation](generation.md) | Generate domain model, microflows, pages, security | `generate-domain-model`, `write-microflows`, `create-page`, `manage-security` |
32+
| [Data Migration](data-migration.md) | Import data from source databases | `demo-data`, `database-connections` |
33+
| [Validation and Handoff](validation.md) | Test, lint, and hand off to Studio Pro | `check-syntax`, `assess-quality` |

‎docs-site/src/migration/assessment.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Phase 1: Assessment
2+
3+
The first step is a thorough investigation of the source application. The AI agent examines the codebase and produces a structured migration inventory.
4+
5+
## The assess-migration Skill
6+
7+
The `assess-migration` skill provides a 6-step investigation framework that works with any technology stack -- Java, .NET, Python, Node.js, PHP, Ruby, or any other platform. It guides the agent through:
8+
9+
1. **Technology stack** -- build files, frameworks, runtime versions
10+
2. **Data model** -- ORM entities, database schema, relationships
11+
3. **Business logic** -- service classes, stored procedures, validation rules
12+
4. **User interface** -- pages, templates, navigation structure
13+
5. **Integrations** -- REST/SOAP clients, message queues, file feeds
14+
6. **Security** -- authentication, authorization, role definitions
15+
16+
## What to Extract
17+
18+
| Category | What to Document | Where to Look |
19+
|----------|-----------------|---------------|
20+
| **Data model** | Entities, attributes, relationships, constraints | JPA entities, Django models, EF DbContext, DB schema |
21+
| **Business logic** | Validation rules, calculations, workflows | Service classes, stored procedures, triggers |
22+
| **Pages / UI** | Screens, forms, dashboards, navigation | React components, Razor views, JSP templates |
23+
| **Integrations** | APIs consumed/exposed, file feeds, queues | REST clients, SOAP services, Kafka topics |
24+
| **Security** | Authentication, roles, data access rules | Spring Security, RBAC policies, row-level security |
25+
| **Scheduled jobs** | Background tasks, timers, batch processing | Cron jobs, Quartz schedulers, Celery tasks |
26+
27+
## Platform-Specific Skills
28+
29+
For common source platforms, dedicated skills provide deeper guidance with precise element mappings:
30+
31+
| Source Platform | Skill | Key Mappings |
32+
|----------------|-------|-------------|
33+
| **Oracle Forms** | `migrate-oracle-forms` | Form -> Page, Block -> Snippet, PL/SQL -> Microflow, LOV -> Enumeration |
34+
| **K2 / Nintex** | `migrate-k2-nintex` | SmartForm -> Page, SmartObject -> Entity, Workflow -> Microflow chain |
35+
| **Any stack** | `assess-migration` | Generic framework for any technology |
36+
37+
## Assessment Output
38+
39+
The assessment produces a structured report with:
40+
41+
- **Executive summary** -- technology stack, application size, complexity rating
42+
- **Categorized inventory** -- counts and details for each category
43+
- **Mendix mapping** -- how each source element maps to Mendix concepts
44+
- **Migration risks** -- complex stored procedures, custom UI components, real-time integrations
45+
- **Recommended phases** -- suggested order of migration work
46+
47+
## Example: Starting an Assessment
48+
49+
Point the AI agent at the source codebase and ask it to assess for migration:
50+
51+
```
52+
Assess the application in /path/to/source for migration to Mendix.
53+
Use the assess-migration skill.
54+
```
55+
56+
The agent will investigate build files, ORM models, service classes, UI templates, security configuration, and API clients. The resulting assessment report becomes the input for Phase 2.

‎docs-site/src/migration/data-migration.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Data Migration
2+
3+
mxcli can connect directly to external databases to explore schemas, import data, and generate database connector code. This is useful for migrating reference data, seeding test data, or setting up ongoing integrations with legacy systems.
4+
5+
## Key Skills
6+
7+
| Skill | Purpose |
8+
|-------|---------|
9+
| `demo-data` | Mendix ID system, association storage, direct PostgreSQL insertion |
10+
| `database-connections` | External database connectivity from microflows (Database Connector module) |
11+
| `patterns-data-processing` | Loop patterns, batch processing, list operations |
12+
13+
## Connect to the Source Database
14+
15+
mxcli supports PostgreSQL, Oracle, and SQL Server:
16+
17+
```sql
18+
-- Connect to the legacy database
19+
SQL CONNECT postgres 'host=legacy-db port=5432 dbname=crm user=readonly password=...' AS legacy;
20+
21+
-- Explore the schema
22+
SQL legacy SHOW TABLES;
23+
SQL legacy DESCRIBE customers;
24+
```
25+
26+
## Import Data
27+
28+
The `IMPORT FROM` statement reads from the source database and inserts into the Mendix application's PostgreSQL database:
29+
30+
```sql
31+
-- Import customers
32+
IMPORT FROM legacy
33+
QUERY 'SELECT name, email, phone, active FROM customers'
34+
INTO CRM.Customer
35+
MAP (name AS Name, email AS Email, phone AS Phone, active AS IsActive)
36+
BATCH 500;
37+
38+
-- Import with association linking
39+
IMPORT FROM legacy
40+
QUERY 'SELECT order_number, order_date, total, customer_email FROM orders'
41+
INTO Sales.Order
42+
MAP (order_number AS OrderNumber, order_date AS OrderDate, total AS TotalAmount)
43+
LINK (customer_email TO Sales.Order_Customer ON Email)
44+
BATCH 500;
45+
```
46+
47+
The import pipeline handles:
48+
49+
- **Mendix ID generation** -- creates valid 64-bit object IDs
50+
- **Batch insertion** -- respects PostgreSQL parameter limits
51+
- **Association linking** -- looks up related entities by attribute value
52+
- **Optimistic locking** -- sets `MxObjectVersion` if the entity uses it
53+
54+
## Generate Database Connectors
55+
56+
For ongoing integration (not one-time import), generate Database Connector entities and microflows:
57+
58+
```sql
59+
-- Auto-generate non-persistent entities and query microflows
60+
SQL legacy GENERATE CONNECTOR INTO Integration
61+
TABLES (customers, orders, products);
62+
```
63+
64+
This creates:
65+
66+
- Non-persistent entities with mapped attributes
67+
- Constants for connection strings (JDBC URL, username, password)
68+
- `DATABASE CONNECTION` definitions with query microflows
69+
70+
## Credential Management
71+
72+
Database credentials should never be hardcoded. mxcli supports:
73+
74+
- **Environment variables** -- set `MXCLI_SQL_<ALIAS>_DSN`
75+
- **YAML config file** -- `~/.mxcli/sql.yaml` with per-alias DSN entries
76+
- **Credential isolation** -- credentials are never exposed to the AI agent or logged

‎docs-site/src/migration/generation.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Phase 3: Generation
2+
3+
With the transformation plan in hand, the agent generates the Mendix application using MDL scripts. Skills guide the agent toward correct, idiomatic MDL.
4+
5+
## Key Skills
6+
7+
| Skill | Purpose |
8+
|-------|---------|
9+
| `generate-domain-model` | Entity, association, and enumeration syntax with naming conventions |
10+
| `write-microflows` | Microflow syntax, 60+ activity types, common patterns |
11+
| `create-page` | Page and widget syntax for 50+ widget types |
12+
| `overview-pages` | CRUD page patterns (list + detail) |
13+
| `master-detail-pages` | Master-detail page layouts |
14+
| `manage-security` | Module roles, user roles, GRANT/REVOKE, demo users |
15+
| `manage-navigation` | Navigation profiles, menu items, home pages |
16+
| `organize-project` | Folder structure, MOVE command, project conventions |
17+
18+
## Generation Workflow
19+
20+
```bash
21+
# 1. Create a new Mendix project in Studio Pro (or use an existing one)
22+
# 2. Execute MDL scripts in dependency order
23+
mxcli exec domain-model.mdl -p app.mpr
24+
mxcli exec microflows.mdl -p app.mpr
25+
mxcli exec pages.mdl -p app.mpr
26+
mxcli exec security.mdl -p app.mpr
27+
28+
# Or work interactively in the REPL
29+
mxcli -p app.mpr
30+
```
31+
32+
## Example: Domain Model
33+
34+
```sql
35+
-- Enumerations first (referenced by entities)
36+
CREATE ENUMERATION Sales.OrderStatus (
37+
Draft 'Draft',
38+
Pending 'Pending',
39+
Confirmed 'Confirmed',
40+
Shipped 'Shipped',
41+
Delivered 'Delivered',
42+
Cancelled 'Cancelled'
43+
);
44+
45+
-- Entities
46+
/** Customer master data */
47+
@Position(100, 100)
48+
CREATE PERSISTENT ENTITY CRM.Customer (
49+
Name: String(200) NOT NULL ERROR 'Customer name is required',
50+
Email: String(200) UNIQUE ERROR 'Email already exists',
51+
Phone: String(50),
52+
IsActive: Boolean DEFAULT TRUE
53+
)
54+
INDEX (Name)
55+
INDEX (Email);
56+
/
57+
58+
/** Sales order */
59+
@Position(300, 100)
60+
CREATE PERSISTENT ENTITY Sales.Order (
61+
OrderNumber: String(50) NOT NULL UNIQUE,
62+
OrderDate: DateTime NOT NULL,
63+
TotalAmount: Decimal DEFAULT 0,
64+
Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft'
65+
)
66+
INDEX (OrderNumber)
67+
INDEX (OrderDate DESC);
68+
/
69+
70+
-- Associations
71+
CREATE ASSOCIATION Sales.Order_Customer
72+
FROM CRM.Customer TO Sales.Order
73+
TYPE Reference OWNER Default;
74+
/
75+
```
76+
77+
## Example: Microflow
78+
79+
```sql
80+
CREATE MICROFLOW Sales.ACT_Order_CalculateTotal
81+
BEGIN
82+
DECLARE $Order Sales.Order;
83+
RETRIEVE $Lines FROM Sales.OrderLine
84+
WHERE [Sales.OrderLine_Order = $Order];
85+
DECLARE $Total Decimal = 0;
86+
LOOP $Line IN $Lines
87+
BEGIN
88+
SET $Total = $Total + $Line/Price * $Line/Quantity;
89+
END;
90+
CHANGE $Order (TotalAmount = $Total);
91+
COMMIT $Order;
92+
END;
93+
/
94+
```
95+
96+
## Example: Page
97+
98+
```sql
99+
CREATE PAGE CRM.Customer_Overview (
100+
Title: 'Customers',
101+
Layout: Atlas_Core.Atlas_Default
102+
) {
103+
DATAGRID2 ON CRM.Customer (
104+
COLUMN Name { Caption: 'Name' }
105+
COLUMN Email { Caption: 'Email' }
106+
COLUMN Phone { Caption: 'Phone' }
107+
COLUMN IsActive { Caption: 'Active' }
108+
SEARCH ON Name, Email
109+
BUTTON 'New' CALL CRM.Customer_NewEdit
110+
BUTTON 'Edit' CALL CRM.Customer_NewEdit
111+
BUTTON 'Delete' CALL CONFIRM DELETE
112+
)
113+
};
114+
/
115+
```
116+
117+
## Validation Between Steps
118+
119+
Validate after each script to catch errors early:
120+
121+
```bash
122+
# Syntax check (fast, no project needed)
123+
mxcli check domain-model.mdl
124+
125+
# Reference validation (checks entity/microflow names exist)
126+
mxcli check pages.mdl -p app.mpr --references
127+
```

0 commit comments

Comments
 (0)