Organize Project

Project Organization: Folders and Moving Documents

This skill covers organizing Mendix project documents (pages, microflows, snippets, nanoflows) into folders and moving them between folders and modules.

When to Use This Skill

Use this skill when:

• Organizing documents into folder hierarchies within a module
• Moving documents between folders
• Moving documents between modules
• Restructuring a project for better maintainability
• Setting up folder conventions for a new module

Folder Conventions

Organize by functional grouping — keep all artifacts for a feature together, not separated by document type. This way, a developer working on "Customer" finds everything in one place: pages, microflows, snippets, and validation logic.

Recommended folder structure within a module:

CRM/
├── Customer/
│   ├── Customer_Overview        -- Overview page
│   ├── Customer_NewEdit         -- Edit page
│   ├── CustomerCard             -- Snippet
│   ├── ACT_Customer_Save        -- Save microflow
│   ├── ACT_Customer_Delete      -- Delete microflow
│   ├── ACT_Customer_New         -- New microflow
│   ├── VAL_Customer             -- Validation microflow
│   └── DS_Customer_Filter       -- Data source microflow
├── Order/
│   ├── Order_Overview
│   ├── Order_NewEdit
│   ├── ACT_Order_Save
│   └── VAL_Order
└── Shared/                      -- Cross-cutting concerns
    ├── SUB_SendNotification
    └── Navigation_Snippet

Why functional grouping over type grouping:

• All related artifacts are in one place — easier to navigate and review
• Adding or removing a feature is a single folder operation
• Naming prefixes (ACT_, VAL_, SUB_, DS_) already indicate document type
• Mirrors how developers think: "I'm working on Customer" not "I'm working on microflows"

Adapt to your project's conventions. The key is consistency across modules.

Creating Documents in Folders

Microflows

Use the folder keyword after the return type, before begin:

mdl 1;
create microflow MyModule.ACT_ProcessOrder ($Order: MyModule.Order)
returns boolean as $success
folder 'Order'
begin
  commit $Order;
  return true;
end;

Pages

Use the folder property inside the page properties:

mdl 1;
create page MyModule.Customer_Overview folder 'Customer'
(
  title: 'Customer Overview',
  layout: Atlas_Core.Atlas_Default
)
{
  -- widgets
};

Snippets

mdl 1;
create snippet MyModule.CustomerCard folder 'Customer'
{
  -- widgets
};

Nested Folders

Use / to create nested folder paths. Missing folders are created automatically:

mdl 1;
-- Creates 'Order', then 'Order/Batch' if they don't exist
create microflow MyModule.ACT_BatchProcess ($list: list of MyModule.Order)
folder 'Order/Batch'
begin
  loop $Order in $list begin
    commit $Order;
  end loop;
  return;
end;

Reading the Layout Back

list folders shows the folder layout of a module and what is in each folder. This is the counterpart to move: move puts a document somewhere, list folders shows where everything actually is.

-- One module
list folders in MyModule;

-- Every module in the project
list folders;

MyModule
  (module root)  [1]
    Microflow ACT_Unfiled
  Api  [0]
  Api/Published  [1]
    ODataService PublicApi
  Support  [1]
    JavaAction Helper

(3 folder(s), 3 document(s))

Three things about the output are deliberate:

• Empty folders are listed (Api [0]), so the listing is the whole layout and can be diffed against an intended one.
• Documents still at the module root appear under (module root) — what is not filed yet is the thing you most want to notice.
• Ordering is stable, so a diff between two runs shows only real movement.

Use the CLI's --json flag for a row per document (Module, Folder, Kind, Document) when comparing against a checked-in layout.

Do not reach for describe structure here: it groups by document type at every depth and never shows which folder a document sits in.

Moving Documents

The move command relocates existing documents between folders and modules.

Move to a Folder (Same Module)

mdl 1;
move page MyModule.CustomerEdit to folder 'Customer';
move microflow MyModule.ACT_ProcessOrder to folder 'Order';
move snippet MyModule.NavigationMenu to folder 'Shared';
move nanoflow MyModule.NAV_OpenCustomer to folder 'Customer';
move enumeration MyModule.OrderStatus to folder 'Shared';

Move to Module Root (Out of Folder)

mdl 1;
move page MyModule.CustomerEdit to MyModule;

Move Across Modules

mdl 1;
-- Move to another module's root
move page OldModule.CustomerPage to NewModule;

-- Move to a folder in another module
move page OldModule.CustomerPage to folder 'Pages' in NewModule;

Cross-Module Move Warning

Cross-module moves change the qualified name (e.g., OldModule.CustomerPage becomes NewModule.CustomerPage). This breaks by-name references such as:

• Microflows calling show page OldModule.CustomerPage
• Other microflows calling call microflow OldModule.SomeMicroflow
• Widget actions referencing the old qualified name

Always check impact before cross-module moves:

mdl 1;
list impact of OldModule.CustomerPage;
-- Review the output, then move if safe:
move page OldModule.CustomerPage to NewModule;

Folder Rules

• Folder names are case-sensitive
• Use / as separator for nested folders: 'Parent/Child/Grandchild'
• Folders are created automatically if they don't exist
• Moving to a folder that doesn't exist creates it
• Empty folders are preserved in the project