7.2 Import & Export Mappings with JSON & XML

7.2 Import & Export Mappings with JSON & XML

Exam Focus: Mappings bridge the gap between external payload formats (JSON, XML) and the Mendix Domain Model. The Intermediate Developer certification frequently tests schema definition methods, the three ways an object is obtained ('Create an object', 'Find an object (by key)', 'Call a microflow') and the separate 'If no object was found' action, when and why to map into Non-Persistable Entities (NPEs) versus Persistable Entities, and techniques for serializing outbound payloads using Export Mappings.

In modern web architectures, data exchanges occur almost exclusively via structured JSON or XML payloads. Within Mendix, application logic does not manipulate raw JSON strings directly. Instead, Mendix utilizes Import Mappings to deserialize incoming hierarchical text streams into domain model entity instances, and Export Mappings to serialize entity instances back into compliant JSON or XML strings.

---

Schema Definition Sources in Studio Pro

Before an Import or Export Mapping can be constructed, Studio Pro requires a formal schema definition describing the shape, data types, and hierarchy of the data structure. Mendix supports three schema sources:

SCHEMA DEFINITION SOURCES
├── 1. JSON Snippet (Sample JSON text file analyzed by Studio Pro to infer structure)
├── 2. XML Schema / XSD (Formal W3C schema defining elements, types, and namespaces)
└── 3. Message Definition (Model-driven schema generated directly from Mendix domain entities)

1. JSON Snippets

• Created via Add Other > JSON snippet in Studio Pro.
• A developer pastes representative sample JSON (e.g., an actual API response payload).
• Studio Pro parses the text, recursively detects objects, arrays, and primitive fields (Strings, Numbers, Booleans), and generates a visual tree schema.
• Crucial Caution: JSON snippets infer data types from sample values. If a sample attribute contains null, Studio Pro cannot determine whether the value is an Integer, Decimal, or DateTime, defaulting it to String. Always provide realistic non-null sample values in JSON snippets.

2. XML Schemas (XSD)

• Created via Add Other > XML schema.
• Imports a formal .xsd file adhering to W3C standards.
• Enforces strict data types, element order, occurrence constraints (minOccurs, maxOccurs), and XML namespaces.

3. Message Definitions

• Created via Add Other > Message definition.
• Uses the Mendix Data Hub or local domain model to expose entities and associations as reusable schema contracts.

---

Import Mappings: From Raw Payloads to Mendix Entities

An Import Mapping document translates an incoming JSON or XML document into Mendix entity objects. In the visual mapping editor, the developer connects schema elements on the left to Mendix domain entities and attributes on the right.

[ JSON Payload Schema ] ────────► ( Import Mapping Rules ) ────────► [ Mendix Domain Model ]
{                                  - Match 'id' to OrderId          Order Entity
  "id": 101,                       - Match 'total' to TotalPrice      ├── OrderId (Integer)
  "total": 89.50,                  - Match array to association       └── TotalPrice (Decimal)
  "lines": [ ... ]                                                          │
}                                                                           ▼ (Association)
                                                                    OrderLine Entity

Mapping Arrays and Nested Hierarchies

• When the incoming schema contains a nested JSON object (e.g., "shippingAddress": { "street": "123 Main St" }), the mapping editor creates an associated child entity linked to the parent object via a 1-to-1 or 1-to-many association.
• When the schema contains a JSON array (e.g., "items": [ ... ]), the mapping creates a list of child entity instances and links each instance to the parent entity via a 1-to-many association.

---

Object Handling Options in Import Mappings

For every entity mapped in an Import Mapping, you configure how the object is obtained. Studio Pro offers exactly three ways:

The Separate "If no object was found" Setting

This is where candidates lose the mark. Find an object (by key) does not create anything on its own — what happens when the search comes back empty is a separate property with three actions:

Exam Trap: Find an object (by key) on its own is find, not upsert. Upsert is Find an object (by key) plus If no object was found = Create. And "Ignore" is one of the three no-match actions — it is not one of the ways an object is obtained.

Second Exam Trap: Choosing Create an object when synchronising external master data produces duplicate records on every run, because nothing is ever matched against existing data. Mark the natural key attribute (for example CustomerCode) as Key, obtain the object with Find an object (by key), and set If no object was found to Create.

Third Exam Trap: If the key is not actually unique in your data, Find an object (by key) throws an error the moment the XPath query returns more than one object. Enforce uniqueness — ideally with a database index and a before-commit validation — before you rely on it.

Persistable Entities vs. Non-Persistable Entities (NPEs) for Payloads

One of the most heavily tested architectural topics on the Intermediate Developer exam is the choice of target entity type in Import Mappings:

Why Map to Non-Persistable Entities (NPEs)?

1. Zero Database Disk I/O: Persistable entities trigger database sequences, locking, and physical disk writes. NPEs reside purely in runtime memory, achieving orders-of-magnitude faster deserialization.
2. Avoid Database Bloat: Integration payloads often contain dozens of metadata fields (e.g., pagination links, timestamps, raw status codes) that your application does not need to persist permanently.
3. Automatic Garbage Collection: Once the microflow finishes processing, uncommitted NPEs are automatically reclaimed by the Java Virtual Machine (JVM) garbage collector without requiring explicit Delete activities or database vacuuming.
4. Clean Transaction Boundaries: If an error occurs halfway through processing a multi-part payload, NPEs leave zero orphaned records in the SQL database, guaranteeing database consistency.

Recommended Architecture Pattern: The Staging NPE Pattern

[ External REST API ]
         │ (JSON Response)
         ▼
[ Call REST Service: Import to NPE Staging Objects ] (Fast, in-memory)
         │
         ▼
[ Microflow Business Logic ] ──► (Validates & Transforms data)
         │
         ▼
[ Create / Update Persistable Core Entities ] ──► (Commits only valid data to DB)

---

Export Mappings: Serializing Objects to JSON & XML

An Export Mapping performs the inverse operation of an Import Mapping: it traverses Mendix entity instances, reads their attributes and associated child objects, and generates a formatted JSON or XML string.

Configuring Export Mappings in Studio Pro

1. Select Schema Source: Select the target JSON snippet, XML schema, or Message Definition.
2. Select Root Element: Define the top-level entity that anchors the payload.
3. Map Attributes & Associations: Connect entity attributes to schema fields. Map reference associations to child elements or arrays.
4. Parameter Passing: In a microflow, the Export with mapping activity takes a Mendix entity (or list of entities) as an input parameter and outputs a String or System.FileDocument.

Handling Empty Values and Formatting Options

When serializing data, external APIs often have strict expectations regarding missing attributes:

• Send empty value as null: Produces "email": null in JSON.
• Do not send empty attributes: Completely omits the key from the JSON payload (e.g., omitting email entirely if the attribute is empty).
• Date and Number Formatting: Allows formatting DateTime attributes into standard ISO-8601 strings (e.g., yyyy-MM-dd'T'HH:mm:ss.SSSXXX) or formatting Decimals with fixed decimal precision.

---

Validation & Error Handling During Payload Deserialization

When consuming payloads from external systems, data formats may deviate from the agreed schema (e.g., receiving a string where an integer is expected, or missing mandatory elements).

Inline Mapping vs. Two-Step Mapping

• Inline Mapping (Inside 'Call REST service'): The Call REST service activity applies the Import Mapping directly to the incoming HTTP response stream. If the JSON is malformed or types mismatch, the activity throws a CoreException immediately.
• Two-Step Mapping Pattern (Recommended for Fault Tolerance):
  1. In Call REST service, select Response > Store in a string (e.g., $RawResponse).
  2. In the next microflow step, execute an Import with mapping activity passing $RawResponse.
  3. Configure a custom error handler on the Import with mapping activity.
  • Advantage: If deserialization fails, the application retains the exact raw payload in $RawResponse, allowing it to be logged to the database for developer troubleshooting without losing the error context.

---

Practical Exam Scenarios & Architecture Pitfalls

Scenario 1: Duplicate Records After Nightly Sync

An integration microflow runs every midnight to synchronize product catalog data from an ERP. After one week, the database contains seven duplicate records for every single product in the catalog.

• Root Cause: The Import Mapping had its Object Handling set to Create an object.
• Solution: Mark ProductSKU as a Key attribute, obtain the object with Find an object (by key), and set If no object was found to Create. Existing products are then matched and updated, and only genuinely new SKUs are inserted. Leaving the no-match action on Create is what makes it an upsert; on its own, Find an object (by key) only finds.

Scenario 2: Unexpected String Type in JSON Snippet

A developer creates a JSON snippet using an API response where the attribute "discountPercent": null. When building the domain model via the mapping editor, Studio Pro creates discountPercent as a String instead of a Decimal.

• Root Cause: Studio Pro cannot determine numeric data types from null values during schema inference.
• Solution: Update the JSON snippet text to contain a realistic decimal value (e.g., "discountPercent": 15.50) and re-synchronize the schema.