CREATE IMPORT MAPPING

Synopsis

CREATE [ OR MODIFY ] IMPORT MAPPING module.Name
    [ FOLDER 'folder_path' ]
    [ WITH JSON STRUCTURE module.JsonStructure ]
    [ WITH XML SCHEMA module.XmlSchema ]
{
    { CREATE | FIND | FIND OR CREATE } module.Entity {
        Attribute = jsonField [ KEY ],
        ...
        [ { CREATE | FIND | FIND OR CREATE } Assoc/module.ChildEntity = nestedKey {
            ChildAttr = childField [ KEY ],
            ...
        } ]
    }
};

Description

Creates an import mapping that reads JSON or XML data and creates or finds Mendix entity objects from it.

An import mapping is invoked in a microflow using IMPORT FROM MAPPING module.Mapping($json). The result is the root entity object populated from the parsed data.

Object Handling

Each entity block specifies one of three strategies:

Marking an attribute with KEY designates it as the lookup key for FIND and FIND OR CREATE.

Requirements for FIND

An element that searches has two requirements, both refused by mxcli check and by exec rather than left to the build:

Persistability is taken from the generalization chain, not the entity’s own setting: an entity declared with plain CREATE ENTITY that extends a non-persistent parent is still not searchable.

An element with a custom handler (FIND module.Entity BY module.Microflow(...)) is exempt from both — the microflow is the find.

MDL-MAP02 needs no project. MDL-MAP03 resolves the entity from the script when the script creates it, and from the project otherwise; an entity it cannot resolve is left alone rather than assumed non-persistable.

Nested Objects and Arrays

Child entities are nested inside the parent’s { } block using the association path:

AssociationName/module.ChildEntity = jsonKey { ... }

The association must be defined such that the child entity owns the foreign key (FROM child TO parent). Arrays in the JSON sample automatically map to multiple child objects.

OR MODIFY

If OR MODIFY is specified and the mapping already exists, it is updated in place. The document UUID is preserved, which protects runtime microflow references that call IMPORT FROM MAPPING.

Parameters

module.Name

The qualified name of the import mapping.

FOLDER 'folder_path'

Optional. Places the document in the named module folder, creating missing folders in the path. On CREATE OR MODIFY this moves an existing document; omitting the clause leaves placement alone rather than returning the document to the module root. See MOVE.

WITH JSON STRUCTURE module.JsonStructure

Associates the mapping with the named JSON structure. The structure defines the JSON shape.

WITH XML SCHEMA module.XmlSchema

Associates the mapping with the named XML schema instead of a JSON structure.

The reference is resolved against the project: a name that matches no XML schema is refused by mxcli check -p and by exec, naming the schemas that exist. mxbuild otherwise reports it as CE1613 “The selected XML schema ‘X’ no longer exists” at the end of a build.

A project holding no XML schemas disables the check rather than refusing every mapping — there is no CREATE XML SCHEMA in MDL, so an XML schema is only ever something imported into the project by hand, and having none is the ordinary case. The same resolution applies to WITH JSON STRUCTURE.

CREATE | FIND | FIND OR CREATE

Object handling strategy for each entity block.

Attribute = jsonField [ KEY ]

Maps the JSON field jsonField to entity attribute Attribute. KEY marks this attribute for FIND lookups.

AssociationName/module.ChildEntity = nestedKey

Maps a nested JSON object or array element to a child entity via the named association.

Examples

Simple flat mapping

CREATE IMPORT MAPPING MyModule.IMM_Pet
    WITH JSON STRUCTURE MyModule.JSON_Pet
{
    CREATE MyModule.PetResponse {
        PetId = id,
        Name  = name,
        Status = status
    }
};

Upsert by key attribute

CREATE IMPORT MAPPING MyModule.IMM_UpsertPet
    WITH JSON STRUCTURE MyModule.JSON_Pet
{
    FIND OR CREATE MyModule.PetResponse {
        PetId = id KEY,
        Name  = name,
        Status = status
    }
};

Nested JSON with child entity

CREATE IMPORT MAPPING MyModule.IMM_Order
    WITH JSON STRUCTURE MyModule.JSON_Order
{
    CREATE MyModule.OrderResponse {
        OrderId = orderId,
        CREATE MyModule.CustomerInfo_OrderResponse/MyModule.CustomerInfo = customer {
            Name  = name,
            Email = email
        },
        CREATE MyModule.OrderItem_OrderResponse/MyModule.OrderItem = items {
            Sku      = sku,
            Quantity = quantity,
            Price    = price
        }
    }
};

Idempotent update

CREATE OR MODIFY IMPORT MAPPING MyModule.IMM_Pet
    WITH JSON STRUCTURE MyModule.JSON_Pet
{
    CREATE MyModule.PetResponse {
        PetId  = id,
        Name   = name,
        Status = status
    }
};

Notes

• The child entity must own the FK (FROM child TO parent). Using the wrong association direction causes validation errors at runtime.
• Arrays in the JSON sample map directly to child entity objects — there is no intermediate container entity (unlike export mappings).
• Import and export of the same JSON typically require different entity structures because of the FK direction difference.

Inherited attributes

Mendix inheritance is multi-table: all of a parent’s attributes are members of the child, so an entity declared with EXTENDS can map them. Name an inherited attribute exactly like one of the entity’s own; mxcli resolves each to the entity that declares it.

CREATE PERSISTENT ENTITY Docs.DocumentBase (DocName: String(200), Confidential: Boolean);
CREATE PERSISTENT ENTITY Docs.Contract EXTENDS Docs.DocumentBase (ContractNumber: String(50));

CREATE IMPORT MAPPING Docs.IMM_Contract
  WITH JSON STRUCTURE Docs.JSON_Contract
{
  create Docs.Contract {
    ContractNumber = contractNumber,
    DocName        = docName,
    Confidential   = confidential
  }
};

Referencing an inherited attribute against the entity being mapped rather than its declaring entity is Mendix CE1613 “The selected attribute … no longer exists”, and Studio Pro shows the field unmapped.

See Also

CREATE JSON STRUCTURE, CREATE EXPORT MAPPING