From ad2c9a6b9b28c70d991e36a5c27deab8d12c23da Mon Sep 17 00:00:00 2001 From: Mikita Haurykau Date: Thu, 25 Jun 2026 10:13:40 +0200 Subject: [PATCH 1/6] Remove module updates part From 5e79d54f3aecffdcf957bc7b97f636aaa9bca1a2 Mon Sep 17 00:00:00 2001 From: Marks Troicins Date: Wed, 15 Jul 2026 13:08:20 +0200 Subject: [PATCH 2/6] Revert "Remove module updates part" This reverts commit 252104352493d973cb546a13d8c9a241867e2962. --- .../app-explorer/modules/module-settings.md | 3 ++ .../modules/updating-marketplace-modules.md | 46 +++++++++++++++++++ 2 files changed, 49 insertions(+) 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 6e69b4a6894..b693834c51a 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 @@ -85,6 +85,8 @@ Improved package management is available for [Studio Pro 11.12](/releasenotes/st 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). + 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](#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. @@ -143,6 +145,7 @@ The legacy `package.xml` metadata file is not mentioned in `manifest.json` but i ## 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 4895992a748e475a858b11b31df12a63c8e5b944 Mon Sep 17 00:00:00 2001 From: Marks Troicins Date: Wed, 15 Jul 2026 13:59:34 +0200 Subject: [PATCH 3/6] Fixed links in module settings --- .../refguide/modeling/app-explorer/modules/module-settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 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 b693834c51a..476987a6411 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 @@ -85,7 +85,7 @@ Improved package management is available for [Studio Pro 11.12](/releasenotes/st 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). +For more information on how to use package management when updating modules, see [Updating Marketplace Modules](/refguide/updating-marketplace-modules/). Key improvements are delivered through new module properties and a new `manifest.json` file format in module packages (*.mpk* files): @@ -145,7 +145,7 @@ The legacy `package.xml` metadata file is not mentioned in `manifest.json` but i ## Read More * [Modules](/refguide/modules/) -* [Update modules](refguide/updating-marketplace-modules) +* [Updating Marketplace 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/) From 50b5547ad81770298649926484f7bf8a6141b784 Mon Sep 17 00:00:00 2001 From: Quinn Tracy <142489060+quinntracy@users.noreply.github.com> Date: Thu, 16 Jul 2026 12:08:06 +0200 Subject: [PATCH 4/6] Review --- .../modules/updating-marketplace-modules.md | 34 +++++++++++-------- 1 file changed, 19 insertions(+), 15 deletions(-) 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 index dfc9f4511ef..4823e19f565 100644 --- 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 @@ -2,39 +2,43 @@ 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." +description: "How to update Marketplace modules in Studio Pro 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). +This feature requires Studio Pro 11.12 or above. {{% /alert %}} -## Updating Modules with Three-Way Merge +Previously, when you wanted to update a Marketplace module to a newer version, you had to fully replace it, losing any customizations such as modified microflows or added functionality. + +Studio Pro 11.12 changes this by enabling module updates that retain your customizations. When you update a module, Studio Pro performs a three-way merge that combines your customizations with the publisher's updates. You can keep your changes and benefit from bug fixes and new features in the updated module. + +## How Module Updates Work ### Three-Way Merge Process -To retain your customizations when updating a module, Studio Pro performs a three-way merge. This process requires three versions: +To retain your customizations when updating a module, Studio Pro performs a three-way merge using 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 +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. +You must manually provide both the original and target versions. If document mapping succeeds, the merge begins. If mapping fails, you cannot upgrade while keeping your customizations and must fully replace the module instead. 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: +To merge your customizations with the updated module, Studio Pro matches documents between the old and new versions. The method depends on whether the module has package IDs: -* **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. +* Modules with package IDs – Studio Pro uses embedded GUID mapping 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 maps documents by name. This works well as long as document names have not changed between versions. + +{{% alert color="info" %}} +Studio Pro 11.12 introduced package IDs and document GUID mappings to make updates more reliable. Updates with customization retention also work for older modules without package IDs through name-based mapping. +{{% /alert %}} For more information on package IDs and how they are assigned, see [Module Settings](/refguide/module-settings/#package). From dd7715b2525a9537737013acd00aca6de90d4015 Mon Sep 17 00:00:00 2001 From: Quinn Tracy <142489060+quinntracy@users.noreply.github.com> Date: Thu, 16 Jul 2026 12:09:33 +0200 Subject: [PATCH 5/6] Move line --- .../refguide/modeling/app-explorer/modules/module-settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 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 476987a6411..cb845841767 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 @@ -85,8 +85,6 @@ Improved package management is available for [Studio Pro 11.12](/releasenotes/st 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](/refguide/updating-marketplace-modules/). - 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](#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. @@ -95,6 +93,8 @@ Key improvements are delivered through new module properties and a new `manifest 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. +For more information on how to use package management when updating modules, see [Updating Marketplace Modules](/refguide/updating-marketplace-modules/). + ### Module ID {#module-id} 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. From a1f4fc8312e517c257c2ce4bfdbb7da28a8ea86b Mon Sep 17 00:00:00 2001 From: Marks Troicins Date: Thu, 16 Jul 2026 14:34:54 +0200 Subject: [PATCH 6/6] Unreleased feature --- .../app-explorer/modules/updating-marketplace-modules.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 4823e19f565..7554dbdf920 100644 --- 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 @@ -34,10 +34,9 @@ During the merge, conflicts may occur if you and the publisher both modified the To merge your customizations with the updated module, Studio Pro matches documents between the old and new versions. The method depends on whether the module has package IDs: * Modules with package IDs – Studio Pro uses embedded GUID mapping 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 maps documents by name. This works well as long as document names have not changed between versions. {{% alert color="info" %}} -Studio Pro 11.12 introduced package IDs and document GUID mappings to make updates more reliable. Updates with customization retention also work for older modules without package IDs through name-based mapping. +Studio Pro 11.12 introduced package IDs and document GUID mappings to make updates more reliable. {{% /alert %}} For more information on package IDs and how they are assigned, see [Module Settings](/refguide/module-settings/#package).