From 4add6ea3f38c550485762396b5a235c3eb803525 Mon Sep 17 00:00:00 2001 From: Mikita Haurykau Date: Thu, 4 Jun 2026 15:38:00 +0200 Subject: [PATCH 1/4] Refguide Package management foundation --- .../app-explorer/modules/module-settings.md | 71 ++++++++++++++++++- .../modules/updating-marketplace-modules.md | 46 ++++++++++++ 2 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 content/en/docs/refguide/modeling/app-explorer/modules/updating-marketplace-modules.md diff --git a/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md b/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md index 7253e1a348a..18d0f140198 100644 --- a/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md +++ b/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md @@ -25,6 +25,10 @@ Select the **Export** tab: {{< figure src="/attachments/refguide/modeling/app-explorer/modules/module-settings/module-settings-export.png" class="no-border" >}} +## Configure + +Configure section contains basic settings of the module. + ### Module Type {#module-type} There are three types of modules, and the choice of type depends on the purpose of the module. You can choose one the following: @@ -62,16 +66,79 @@ When the module is set as the solution module, it gets the letter **S** as an ic ### Module Version {{% alert color="info" %}} -This setting is available only for add-on and solution module types. -{{% /alert %}} +From Studio Pro 11.12 and above version is available for all module types. For earlier versions of Studio Pro version is available only for Add-on and Solution module types. +{{% /alert %}} This is the version number of the module. The version should be a semantic version (meaning, it should consist of at least three parts: major, minor, and patch version). For more information on semantic versions, see [Semantic Versioning](https://semver.org/). Mendix recommends setting a new version every time changes are made to the module. +## Package {#package} + +{{% alert color="info" %}} +This section is available from Studio Pro 11.12 and above. +{{% /alert %}} + +Studio Pro 11.12 introduces improved package management to enable reliable module tracking and updates. + +For more information on how to use package management when updating modules, see [Updating Marketplace Modules](https://github.com/mendix/docs/blob/development/refguide/updating-marketplace-modules). + +The key improvements are delivered through new module properties and a new `manifest.json` file format in module packages (*.mpk* files): + +- **Package identification** – Each module receives a Module ID that uniquely identifies it throughout all versions. This allows Studio Pro to reliably track modules across updates, even if the module name changes. +- **Package integrity** – Each package includes a checksum (SHA-256 hash) that is used to verify the integrity of the package itself and of the imported module in the App. +- **Metadata tracking** – The manifest includes information about the package name, version (following semantic versioning), type, and the Mendix metamodel version used to create it. + +The **Package** section on the **General** tab shows package identification information for the module. Studio Pro uses this information to track modules across versions, which is the foundation for more reliable module updates. + +### Module ID {#module-id} + +The **Module ID** is a unique identifier for the module that stays the same across all versions of the module. It is used to determine whether two module packages represent the same module, and is therefore the basis for module update compatibility: if two modules share the same Module ID, Studio Pro can update one with the other; if the IDs differ, Studio Pro treats them as distinct modules. + +#### Automatic Module ID Assignment + +The Module ID is assigned automatically and is stable across devices, so multiple developers working on the same module independently end up with the same value: + +* For a module imported from the Marketplace, the Module ID is derived from the Marketplace component ID. +* For any other module, the Module ID is derived from the App ID and the module name. This ensures the ID remains consistent across devices when multiple developers work independently. + +When you open an existing app in Studio Pro 11.12 or above, every module that does not yet have a Module ID receives one automatically. No action is required from you. + +#### Manual Module ID override + +In some cases you might want to override the automatically assigned Module ID. To change it, click the pencil icon next to it. A dialog opens where you can enter a new value. + +{{% alert color="warning" %}} +Changing the Module ID may break existing installations that depend on this module. Only override this value if you know what you are doing. +{{% /alert %}} + +### Checksum {#checksum} + +The **Checksum** is a read-only SHA-256 hash that uniquely identifies a specific version of the module package. It serves two purposes: + +* **Integrity** – This checksum is a hash of the contents of the original module package that StudioPro can use to detect if there were any user modifications after the module was imported. +* **Version identification** – Lets you compare two module packages for equality without inspecting their contents. + +The checksum is shown only for modules that were imported from a module package. For modules created directly in your app, the checksum is calculated when you export the module and is not displayed in the **Package** section. + +### Package Manifest {#package-manifest} + +When you export a module package (an *.mpk* file), Studio Pro 11.12 and above adds a `manifest.json` file to the package alongside the existing metadata. The manifest contains: + +* The Module ID and Module name +* The Module version +* The Checksum of the package +* The Mendix metamodel version used to create the package +* The list of files included in the package + +The legacy `package.xml` metadata file is still included for backward compatibility. + + + ## Read More * [Modules](/refguide/modules/) +* [Update modules](refguide/updating-marketplace-modules) * [Configure Add-on and Solution Modules for Publishing](/refguide/configure-add-on-and-solution-modules/) * [Applying Intellectual Property Protection](/appstore/creating-content/sol-ip-protection/) * [Creating Solutions](/appstore/creating-content/sol-solutions-guide/) diff --git a/content/en/docs/refguide/modeling/app-explorer/modules/updating-marketplace-modules.md b/content/en/docs/refguide/modeling/app-explorer/modules/updating-marketplace-modules.md new file mode 100644 index 00000000000..dfc9f4511ef --- /dev/null +++ b/content/en/docs/refguide/modeling/app-explorer/modules/updating-marketplace-modules.md @@ -0,0 +1,46 @@ +--- +title: "Updating Marketplace Modules" +url: /refguide/updating-marketplace-modules/ +weight: 40 +description: "Describes how to update Marketplace modules while retaining your customizations using three-way merge." +--- + +## Introduction + +Previously, when you wanted to update a Marketplace module to a newer version, you had to fully replace the module. This meant losing any customizations you had made, such as modified microflows or added functionality. If you had customized a module, you had to choose between keeping your changes or getting the latest updates from the publisher. + +Studio Pro 11.12 changes this by enabling module updates that retain your customizations. Now, when you update a module, Studio Pro performs a three-way merge that intelligently combines your customizations with the publisher's updates. This means you can both keep your changes and benefit from bug fixes and new features in the updated module. + +{{% alert color="info" %}} +Studio Pro 11.12 introduces improved package management with package IDs and document GUID mappings that make updates more reliable. However, updates with customization retention also work for older modules without package IDs through name-based mapping. For more information on package management, see [Module Settings](/refguide/module-settings/#package). +{{% /alert %}} + +## Updating Modules with Three-Way Merge + +### Three-Way Merge Process + +To retain your customizations when updating a module, Studio Pro performs a three-way merge. This process requires three versions: + +1. **Original version** – The version of the Marketplace module that you originally imported +2. **Current version** – The version currently in your app, which may include your modifications +3. **Target version** – The new version of the Marketplace module that you want to upgrade to + +You must manually provide both the original and target versions. If the mapping of documents succeeds, the merge begins. If mapping fails, you cannot upgrade while keeping your customizations, and you must fully overwrite the module. + +During the merge, conflicts may occur if you and the publisher both modified the same element (for example, the same microflow). For information on resolving conflicts, see [Combining Changes and Resolving Conflicts](/refguide/resolving-conflicts/). + +### Document Mapping + +To successfully merge your customizations with the updated module, Studio Pro needs to match documents between the old and new versions. The method Studio Pro uses depends on whether the module has package identification: + +* **Modules with package IDs** – Studio Pro uses the embedded GUID mapping information to match documents by GUID. This is more reliable because documents can be matched even if they have been renamed. +* **Modules without package IDs** – Studio Pro attempts to map documents by name. This works well as long as document names have not changed between versions. + +For more information on package IDs and how they are assigned, see [Module Settings](/refguide/module-settings/#package). + +## Read More + +* [Modules](/refguide/modules/) +* [Module Settings](/refguide/module-settings/) +* [Consuming Add-on Modules and Solutions](/refguide/consume-add-on-modules-and-solutions/) +* [Combining Changes and Resolving Conflicts](/refguide/resolving-conflicts/) From e94948be6f934aa95d2d17ac40e1469184ec05ca Mon Sep 17 00:00:00 2001 From: Mikita Haurykau Date: Tue, 16 Jun 2026 10:29:25 +0200 Subject: [PATCH 2/4] Added warnign about publishing is impossible with ModuleID from another Publisher --- .../refguide/modeling/app-explorer/modules/module-settings.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md b/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md index 18d0f140198..df429672011 100644 --- a/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md +++ b/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md @@ -110,6 +110,9 @@ In some cases you might want to override the automatically assigned Module ID. T {{% alert color="warning" %}} Changing the Module ID may break existing installations that depend on this module. Only override this value if you know what you are doing. + +Marketplace will not allow you to publish a module with ModuleID that is already used by another publisher. + {{% /alert %}} ### Checksum {#checksum} From 3e8457ba6a228314f7b9f6f69160a1a515d5de82 Mon Sep 17 00:00:00 2001 From: Mikita Haurykau Date: Tue, 16 Jun 2026 10:33:00 +0200 Subject: [PATCH 3/4] Added mention of package.xml NOT being included in manifest.json, but included in the package --- .../refguide/modeling/app-explorer/modules/module-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md b/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md index df429672011..c32cc1c4578 100644 --- a/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md +++ b/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md @@ -134,7 +134,7 @@ When you export a module package (an *.mpk* file), Studio Pro 11.12 and above ad * The Mendix metamodel version used to create the package * The list of files included in the package -The legacy `package.xml` metadata file is still included for backward compatibility. +The legacy `package.xml` metadata file is NOT mentioned in the `manifest.json` but is still included in the package for backward compatibility. From b6cf2c724e80050091a906aa3ce58c5852308cc7 Mon Sep 17 00:00:00 2001 From: Quinn Tracy <142489060+quinntracy@users.noreply.github.com> Date: Thu, 18 Jun 2026 11:41:22 +0200 Subject: [PATCH 4/4] Review --- .../app-explorer/modules/module-settings.md | 58 +++++++++---------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md b/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md index c32cc1c4578..8abb3e9d48a 100644 --- a/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md +++ b/content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md @@ -27,7 +27,7 @@ Select the **Export** tab: ## Configure -Configure section contains basic settings of the module. +The **Configure** tab contains the module's basic settings. ### Module Type {#module-type} @@ -66,52 +66,52 @@ When the module is set as the solution module, it gets the letter **S** as an ic ### Module Version {{% alert color="info" %}} -From Studio Pro 11.12 and above version is available for all module types. For earlier versions of Studio Pro version is available only for Add-on and Solution module types. +Version is available for all module types for Studio Pro 11.12 and above. In earlier versions of Studio Pro, version is available only for add-on and solution module types. {{% /alert %}} -This is the version number of the module. The version should be a semantic version (meaning, it should consist of at least three parts: major, minor, and patch version). For more information on semantic versions, see [Semantic Versioning](https://semver.org/). +This is the version number of the module. The version should be a semantic version, consisting of at least three parts: major, minor, and patch version. For more information on semantic versions, see [Semantic Versioning](https://semver.org/). -Mendix recommends setting a new version every time changes are made to the module. +Mendix recommends setting a new version every time you make changes to the module. ## Package {#package} {{% alert color="info" %}} -This section is available from Studio Pro 11.12 and above. +Improved package management is available for [Studio Pro 11.12](/releasenotes/studio-pro/11.12/) and above. {{% /alert %}} Studio Pro 11.12 introduces improved package management to enable reliable module tracking and updates. For more information on how to use package management when updating modules, see [Updating Marketplace Modules](https://github.com/mendix/docs/blob/development/refguide/updating-marketplace-modules). -The key improvements are delivered through new module properties and a new `manifest.json` file format in module packages (*.mpk* files): +Key improvements are delivered through new module properties and a new `manifest.json` file format in module packages (*.mpk* files): -- **Package identification** – Each module receives a Module ID that uniquely identifies it throughout all versions. This allows Studio Pro to reliably track modules across updates, even if the module name changes. -- **Package integrity** – Each package includes a checksum (SHA-256 hash) that is used to verify the integrity of the package itself and of the imported module in the App. -- **Metadata tracking** – The manifest includes information about the package name, version (following semantic versioning), type, and the Mendix metamodel version used to create it. +* **Package identification** – Each module receives a [Module ID](#module-id) that uniquely identifies it across all versions. This allows Studio Pro to reliably track modules across updates, even if the module name changes. +* **Package integrity** – Each package includes a checksum (SHA-256 hash) that verifies the integrity of the package itself and the imported module in the app. +* **Metadata tracking** – The manifest includes information about the package name, version (following semantic versioning), type, and the Mendix metamodel version used to create it. -The **Package** section on the **General** tab shows package identification information for the module. Studio Pro uses this information to track modules across versions, which is the foundation for more reliable module updates. +The **Package** section on the **General** tab displays package identification information for the module. Studio Pro uses this information to track modules across versions, which is the foundation for more reliable module updates. ### Module ID {#module-id} -The **Module ID** is a unique identifier for the module that stays the same across all versions of the module. It is used to determine whether two module packages represent the same module, and is therefore the basis for module update compatibility: if two modules share the same Module ID, Studio Pro can update one with the other; if the IDs differ, Studio Pro treats them as distinct modules. +The module ID is a unique identifier for the module that remains the same across all versions. It determines whether two module packages represent the same module and is therefore the basis for module update compatibility. If two modules share the same module ID, Studio Pro can update one with the other. If the IDs differ, Studio Pro treats them as distinct modules. #### Automatic Module ID Assignment -The Module ID is assigned automatically and is stable across devices, so multiple developers working on the same module independently end up with the same value: +The module ID is assigned automatically and is stable across devices, so multiple developers working on the same module independently receive the same value. -* For a module imported from the Marketplace, the Module ID is derived from the Marketplace component ID. -* For any other module, the Module ID is derived from the App ID and the module name. This ensures the ID remains consistent across devices when multiple developers work independently. +* For modules imported from the Marketplace, the module ID is derived from the Marketplace component ID. +* For all other modules, the module ID is derived from the app ID and the module name. This ensures the ID remains consistent across devices when multiple developers work independently. -When you open an existing app in Studio Pro 11.12 or above, every module that does not yet have a Module ID receives one automatically. No action is required from you. +When you open an existing app in Studio Pro, every module that does not yet have a module ID receives one automatically. No action is required. -#### Manual Module ID override +#### Manual Module ID Override -In some cases you might want to override the automatically assigned Module ID. To change it, click the pencil icon next to it. A dialog opens where you can enter a new value. +In some cases, you may want to override the automatically assigned module ID. To change it, click {{% icon name="pencil" %}} to open a dialog where you can enter a new value. {{% alert color="warning" %}} -Changing the Module ID may break existing installations that depend on this module. Only override this value if you know what you are doing. +Changing the module ID may break existing installations that depend on this module. Only override this value if you understand the implications. -Marketplace will not allow you to publish a module with ModuleID that is already used by another publisher. +Marketplace does not allow you to publish a module with a module ID that is already used by another publisher. {{% /alert %}} @@ -119,24 +119,24 @@ Marketplace will not allow you to publish a module with ModuleID that is already The **Checksum** is a read-only SHA-256 hash that uniquely identifies a specific version of the module package. It serves two purposes: -* **Integrity** – This checksum is a hash of the contents of the original module package that StudioPro can use to detect if there were any user modifications after the module was imported. -* **Version identification** – Lets you compare two module packages for equality without inspecting their contents. +* **Integrity** – It is a hash of the contents of the original module package that Studio Pro uses to detect any user modifications after the module was imported. +* **Version identification** – It allows you to compare two module packages for equality without inspecting their contents. -The checksum is shown only for modules that were imported from a module package. For modules created directly in your app, the checksum is calculated when you export the module and is not displayed in the **Package** section. +The checksum is displayed only for modules imported from a module package. For modules created directly in your app, the checksum is calculated when you export the module and is not displayed in the **Package** section. ### Package Manifest {#package-manifest} -When you export a module package (an *.mpk* file), Studio Pro 11.12 and above adds a `manifest.json` file to the package alongside the existing metadata. The manifest contains: +When you export a module package (a *.mpk* file), Studio Pro adds a `manifest.json` file to the package alongside the existing metadata. The manifest contains the following: -* The Module ID and Module name -* The Module version -* The Checksum of the package +* The module ID and module name +* The module version +* The checksum of the package * The Mendix metamodel version used to create the package * The list of files included in the package -The legacy `package.xml` metadata file is NOT mentioned in the `manifest.json` but is still included in the package for backward compatibility. - - +{{% alert type="info" %}} +The legacy `package.xml` metadata file is not mentioned in `manifest.json` but is still included in the package for backward compatibility. +{{% /alert %}} ## Read More