Skip to content

Commit d71ae5d

Browse files
authored
Merge pull request #989 from ako/fix/987-message-definition-documents
feat: Mendix 11.15 message definition documents (MessageDefinition2) (#987)
2 parents 98cde3c + b5246ce commit d71ae5d

50 files changed

Lines changed: 1501 additions & 45 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/fix-issue/findings/mdl-executor.jsonl‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -865,3 +865,4 @@
865865
{"area": "mdl/executor", "date": "2026-10-04", "symptom": "ako/mxcli#980: describe navigation printed a menu item whose action was a nanoflow call / open link / create object with no OnClick, and exec of that description stored Forms$NoAction — TestApp's 'Item 4' (Forms$CallNanoflowClientAction) lost its action at exit 0", "cause": "create or modify navigation / menu is a full menu rebuild from the spec; the reader kept only page/microflow/sign-out, so the spec had no way to say 'keep what is stored' and the writer fell through to NoAction", "file": "`mdl/executor/cmd_navigation.go` convertMenuItemDefs (pairs items by caption path, KeepAction), `mdl/executor/cmd_menus.go` menuItemsFromAST, writers `navigation_write.go` navMenuAction / `menu_write.go` menuActionToGen", "insight": "A full-rebuild writer needs the stored element at hand to carry what the language cannot spell — the same carry offline CompatibilityMode already had. Pair by caption path (first unused sibling with that caption); carry only when the script states no action so an explicit action still wins. The reader must keep the raw action bytes (element.Raw()), not a projection of it", "refs": ["#980"]}
866866
{"area": "mdl/executor", "date": "2026-10-04", "symptom": "ako/mxcli#980: describe navigation printed call nanoflow / open link / create object items with no action and a call microflow without its progress bar, confirmation, async and form-validation settings; exec of the description stored NoAction / the defaults", "cause": "navigation had its own three-action model (Page/Microflow/SignOut) in reader, describe (printMenuMDL), grammar (navMenuAction) and writer (navMenuAction), parallel to the full widget client-action stack pages already had", "file": "`mdl/executor/cmd_navigation.go` printMenuMDL / menuItemActionMDL / menuActionBuilder, `mdl/backend/modelsdk/menu_action_write.go`, `MDLParser.g4` navMenuAction -> actionExprV3", "insight": "Same fix shape as #959 for navigation-list items: keep the raw action, describe it with renderClientActionMDL, parse actionExprV3, build with pageBuilder.buildClientActionV3, serialize with clientActionToGen. Then the round trip only needs the serializer to match Studio Pro's shape — measured gaps were Forms$CallNanoflowClientAction.OutputMappings, Forms$NoAction.DisabledDuringExecution and Menus$MenuItem AlternativeText/Items. For what the expression cannot spell (TitleOverride, LinkType, NumberOfPagesToClose2) keep the stored action when the built one equals it modulo $IDs and those keys. Prove it with a harness test that injects one Studio Pro-shaped item per kind and renames captions to force a build without carry", "refs": ["#980", "#959"]}
867867
{"area": "mdl/executor", "date": "2026-10-04", "symptom": "ako/mxcli#980: check --references refused describe navigation's own output on TestApp — `Icon: image System.Images.Save` gave \"unknown image collection System.Images\"", "cause": "validate_icon_refs resolves against the project's image collections; the System module (and its Images collection) is the platform's and is not stored in the project", "file": "`mdl/executor/validate_icon_refs.go` iconIndex.check / isSystemCollection", "insight": "A reference into the virtual System module can never be in a project listing; skip it rather than refuse (mxbuild resolves it). The member list is not in mxbuild's files in a readable form, so 'resolve' means 'do not judge'", "refs": ["#980"]}
868+
{"area": "mdl/executor", "date": "2026-10-05", "symptom": "On Mendix 11.15, `TestMxCheck_DoctypeScripts/40-message-definition-examples.mdl` fails with CE0270 \"No root element could be found in the schema\" at MsgTest.IMM_Order. On a converted or Studio Pro 11.15 project, `list message definition collections` finds nothing, and `describe import mapping` prints no source", "cause": "Mendix 11.15 replaced `MessageDefinitions$MessageDefinitionCollection` with one `MessageDefinitions$MessageDefinition2` document per definition. `mx convert` turns the collection into a `Projects$Folder` with the same unit ID and name, and the ExposedEntity tree is byte-identical apart from $IDs. mxcli read and wrote only collections, so on 11.15 there was nothing to resolve a mapping against", "file": "`mdl/backend/modelsdk/messagedefinition_document.go` (read/write, reusing the collection's exposedNodeFromGen/messageNodeToGen), `mdl/executor/cmd_messagedefinition_documents.go` (create/describe/drop/list + version refusals), `mdl/executor/mapping_messagedefinition.go` (`findMessageDefinition(ctx, ref)` returns the stored reference), `cmd_messagedefinitions.go` (alter target resolution, association-drop guard), grammar `createMessageDefinitionStatement` / `DROP|DESCRIBE MESSAGE DEFINITION` / `LIST MESSAGE DEFINITIONS`", "insight": "**`mx convert` is the oracle for a storage change.** Converting a known 11.14 project gives a Studio Pro-authored 11.15 reference for the new shape and for how references move, so no guessing is needed. **Under the revert, 11.15 fails earlier than CE0270.** A two-part name written into the old `MessageDefinition` key makes mxbuild refuse to load the project (`StorageLoadException: ... is not a valid OldMessageDefinitionIdentifier`). The old key is typed as a three-part identifier even though 11.15 no longer reads it. The doctype script uses `-- @version: ..11.14` / `11.15+` sections, and the 11.15 mapping needs a different name from the older section's, because a plain `check` sees both sections and reports MDL-DUPDEF", "refs": ["ako/mxcli#987"]}

‎.claude/skills/mendix/json-structures-and-mappings/SKILL.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,22 @@ target entity** — the stored cardinality follows the direction of traversal an
183183
the association's type, so a `Reference` gives a single object one way and a list
184184
the other, while a `ReferenceSet` is a list both ways.
185185

186+
**Mendix 11.15 removed collections.** Each definition is its own document, and
187+
a mapping names it in two parts. The collection form is refused on 11.15, and
188+
the document form below 11.15:
189+
190+
```sql
191+
mdl 1;
192+
create message definition Sales.OrderMessage for Sales.Order as 'Orders' {
193+
OrderId,
194+
Sales.Order_Customer/Sales.Customer { FirstName }
195+
};
196+
create import mapping Sales.IMM_Order with message definition Sales.OrderMessage
197+
{
198+
create Sales.Order { OrderId = OrderId }
199+
};
200+
```
201+
186202
The full vocabulary, the ALTER statements, inherited attributes and what mxcli
187203
deliberately does not guess:
188204
[reference/message-definitions.md](reference/message-definitions.md).

‎.claude/skills/mendix/json-structures-and-mappings/reference/message-definitions.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,36 @@ CE0295 (`Association '...' is not allowed`) on any mapping element bound to it.
5151
the entity that declares it, which is what Mendix stores; qualifying one against
5252
the entity that merely uses it is CE1613.
5353

54+
### Mendix 11.15: one document per definition
55+
56+
Mendix 11.15 removed the collection. Each definition is a separate document,
57+
and Studio Pro's converter turns a collection into a folder of the same name
58+
holding one document per definition. The statement is the collection's
59+
`definition` entry on its own:
60+
61+
```sql
62+
mdl 1;
63+
create message definition Sales.OrderMessage
64+
folder 'Messages/MD_Order'
65+
for Sales.Order as 'Orders' {
66+
OrderId,
67+
Sales.Order_Customer/Sales.Customer { FirstName }
68+
};
69+
alter message definition Sales.OrderMessage add member LastName in Customer;
70+
list message definitions in Sales;
71+
describe message definition Sales.OrderMessage;
72+
drop message definition Sales.OrderMessage;
73+
```
74+
75+
A mapping names it in **two** parts (`with message definition Sales.OrderMessage`).
76+
A three-part name from an older script (`Sales.MD_Order.OrderMessage`) still
77+
resolves on a converted project and is stored as the two-part one.
78+
79+
Which form applies depends on the project version. On 11.15 the collection
80+
statements are refused with a hint to use the document form. Below 11.15 the
81+
document form is refused with a hint to use the collection. Use `list message
82+
definitions` on 11.15 and `list message definition collections` before it.
83+
5484
### Editing one without restating it
5585

5686
Real definitions nest deeply, so a whole-document rewrite is a poor tool for

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
155155

156156
### Added
157157

158+
- **Message definitions on Mendix 11.15: `create message definition`** (ako/mxcli#987). Mendix 11.15 replaced the message definition collection with one document per definition, and Studio Pro's converter turns a collection into a folder of that name holding the documents. The new statements cover the document form: `create [or modify] message definition M.Name [folder '…'] for M.Entity [as '…'] { members }` (the collection's `definition` entry on its own), `describe message definition`, `drop message definition`, `list message definitions [in M]` and `alter message definition M.Name add|drop|set member …`. A mapping names the document as `with message definition M.Name`. A three-part `M.Collection.Definition` from an older script still resolves on a converted project and is stored as `M.Name`. **Version-dependent:** the document form is refused below 11.15 with a hint to use the collection, and on 11.15 the collection statements are refused with a hint to use the document form. `list message definition collections` on 11.15 points to `list message definitions`. `describe` prints the document form, so describe → exec round-trips. Before this, 11.15 projects showed no message definitions, and a mapping over one failed `mx check` with CE0270. This is an addition, so `mdl 1` scripts are unaffected.
158159
- **`check` notes a locale-less `formatDecimal` in hand-built JSON** (ako/mxcli#982) — **MDL-JSONNUM01** (info) for `formatDecimal(x, '0.00')` inside a `+` concatenation whose string literals contain `{` or `":`, which writes `12,50` for a Dutch user. Use `toString(round(x, 2))` or pass a hyphenated locale. A display string (`'Total: ' + formatDecimal(…)`) is not flagged.
159160
- **`mxcli fix hashes` verifies and repairs the MPR v2 ContentsHash index** (ako/mxcli#972) — every `Unit.ContentsHash` in the `.mpr` is compared with `base64(SHA-256)` of its `.mxunit`, and mismatches, missing files and orphan files are reported; the command exits 1 when any remain. `--repair` rewrites the mismatched hashes from the files in one transaction, under the same Studio Pro open-project guard as every write. Restoring a unit with `git checkout` leaves the index stale and `mx check` does not notice; measured on a TestApp copy, an entity added by `exec` and then reverted with a byte-level restore is reported as one `DomainModels$DomainModel` mismatch, and after `--repair` the verify is clean and `mx check` reports 0 errors. `exec` and `docker check` print a one-line warning when the index disagrees (about 0.2 s on 900 units). An MPR v1 project has no index, and the command says so.
160161
- **Warnings for git states that crash Studio Pro** (ako/mxcli#972) — Studio Pro 11.13 fails to open a project ("Unable to find 'system' property in 'system'") when its git branch has no upstream or git reports "detected dubious ownership". `docker check`, `run --local` and the new `mxcli diag -p app.mpr` project section warn with the remedy (`git push -u origin <branch>`; `git config --global --add safe.directory <path>` on the Studio Pro machine). Never fatal, and silent outside a git repository, on a detached HEAD, under `CI`, or with `MXCLI_NO_GIT_WARNINGS=1`. See the new "Working Outside Studio Pro" page.

‎cmd/mxcli/lsp_completions_gen.go‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs-site/src/SUMMARY.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -272,6 +272,8 @@
272272
- [OData and Integration Statements](reference/odata/README.md)
273273
- [Integration Statements](reference/integration/README.md)
274274
- [CREATE JSON STRUCTURE](reference/integration/create-json-structure.md)
275+
- [CREATE MESSAGE DEFINITION COLLECTION](reference/integration/create-message-definition-collection.md)
276+
- [CREATE MESSAGE DEFINITION](reference/integration/create-message-definition.md)
275277
- [CREATE IMPORT MAPPING](reference/integration/create-import-mapping.md)
276278
- [CREATE EXPORT MAPPING](reference/integration/create-export-mapping.md)
277279
- [CREATE DATA TRANSFORMER](reference/integration/create-data-transformer.md)

‎docs-site/src/reference/integration/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ These document types support moving data between Mendix entities and external da
1010
|-----------|-------------|
1111
| [CREATE JSON STRUCTURE](create-json-structure.md) | Define the shape of a JSON document from a sample snippet |
1212
| [CREATE MESSAGE DEFINITION COLLECTION](create-message-definition-collection.md) | Define a mapping source as a selection over the domain model |
13+
| [CREATE MESSAGE DEFINITION](create-message-definition.md) | One message definition as its own document (Mendix 11.15+) |
1314
| [CREATE IMPORT MAPPING](create-import-mapping.md) | Map incoming JSON/XML to Mendix entities |
1415
| [CREATE EXPORT MAPPING](create-export-mapping.md) | Map Mendix entities to outgoing JSON/XML |
1516
| [CREATE DATA TRANSFORMER](create-data-transformer.md) | Transform raw JSON or XML with JSLT/XSLT steps |

‎docs-site/src/reference/integration/create-message-definition-collection.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@ CREATE [ OR MODIFY ] MESSAGE DEFINITION COLLECTION module.Name
1515
);
1616
```
1717

18+
**Mendix 10 to 11.14.** Mendix 11.15 removed collections: each definition is
19+
its own document, created with
20+
[CREATE MESSAGE DEFINITION](create-message-definition.md). On an 11.15 project
21+
the collection statements are refused with a hint to use that form.
22+
1823
## Description
1924

2025
Creates a message definition collection — one of the four sources an import or
Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# CREATE MESSAGE DEFINITION
2+
3+
## Synopsis
4+
5+
```text
6+
CREATE [ OR MODIFY ] MESSAGE DEFINITION module.Name
7+
[ FOLDER 'folder_path' ]
8+
FOR module.Entity [ AS 'ExposedName' ] {
9+
AttributeName [ AS 'ExposedName' ] [ EXAMPLE 'text' ],
10+
module.Association/module.TargetEntity [ AS 'ExposedName' ] { ... },
11+
...
12+
};
13+
```
14+
15+
**Mendix 11.15 and later.** Below 11.15 the statement is refused; a message
16+
definition is then an entry of a
17+
[message definition collection](create-message-definition-collection.md).
18+
19+
## Description
20+
21+
Creates one message definition as its own document. Mendix 11.15 removed the
22+
message definition collection and stores each definition as a separate
23+
document. Studio Pro's converter turns a collection into a folder with the
24+
collection's name, holding one document per definition, so `MD_Order` with the
25+
definition `OrderMessage` becomes the folder `MD_Order` with the document
26+
`OrderMessage` in it.
27+
28+
The body is the collection's `DEFINITION` entry: the same members, the same
29+
rules for attributes and associations, the same derived cardinality. See
30+
[CREATE MESSAGE DEFINITION COLLECTION](create-message-definition-collection.md#members).
31+
32+
A mapping refers to the document by its two-part name:
33+
34+
```sql
35+
mdl 1;
36+
create message definition Sales.OrderMessage
37+
folder 'Messages/MD_Order'
38+
for Sales.Order as 'Orders' {
39+
OrderId,
40+
Total as 'GrandTotal',
41+
Sales.OrderLine_Order/Sales.OrderLine as 'Lines' { Sku, Quantity },
42+
Sales.Order_Customer/Sales.Customer { FirstName, Address example 'Kerstraat 5' }
43+
};
44+
45+
create import mapping Sales.IMM_Order
46+
with message definition Sales.OrderMessage
47+
{
48+
create Sales.Order { OrderId = OrderId }
49+
};
50+
```
51+
52+
On 11.15 a mapping stores this reference in `MessageDefinition2`. A script
53+
written for an older version can still name a converted definition in three
54+
parts (`Sales.MD_Order.OrderMessage`): it resolves to the document in the folder
55+
`MD_Order`, and the mapping stores the two-part name.
56+
57+
## Editing one without restating it
58+
59+
```sql
60+
mdl 1;
61+
alter message definition Sales.OrderMessage add member LastName in Customer;
62+
alter message definition Sales.OrderMessage set member Total as 'GrandTotal';
63+
alter message definition Sales.OrderMessage drop member Sku in Lines;
64+
```
65+
66+
These are the collection's member edits, addressed by the document's two-part
67+
name.
68+
69+
## Other statements
70+
71+
```text
72+
LIST MESSAGE DEFINITIONS [ IN module ];
73+
DESCRIBE MESSAGE DEFINITION module.Name;
74+
DROP MESSAGE DEFINITION [ IF EXISTS ] module.Name;
75+
```
76+
77+
`DESCRIBE` writes this statement, so describe and exec round-trip. Dropping a
78+
definition that a mapping still uses is refused, and the mappings are named.
79+
80+
On 11.15 the collection statements (`CREATE`, `ALTER`, `DESCRIBE` and `DROP
81+
MESSAGE DEFINITION COLLECTION`) are refused with a hint to use this form, and
82+
`LIST MESSAGE DEFINITION COLLECTIONS` points to `LIST MESSAGE DEFINITIONS`.
83+
84+
## See Also
85+
86+
[CREATE MESSAGE DEFINITION COLLECTION](create-message-definition-collection.md), [CREATE IMPORT MAPPING](create-import-mapping.md), [CREATE EXPORT MAPPING](create-export-mapping.md)

0 commit comments

Comments
 (0)