Upgrading the Mendix Version of an App
Upgrading the Version of Your Mendix App
Upgrading a Mendix app can take two forms;
- Upgrading inside the major version
- Upgrading to a new Major Version
Mendix releases a new major version every year. When picking a version of Mendix to build you app in, make sure it will be released in a MTS or LTS version of Mendix. You can see the current LTS and MTS versions here on the LTS/MTS tab (https://marketplace.mendix.com/link/studiopro/) and the release schedule for them here (https://docs.mendix.com/releasenotes/studio-pro/lts-mts/).
Upgrading Inside of a Major Version
This should be fairly simple. Download the Mendix Modeler for the version you want to upgrade to. Open your app in this version and there should be no issues. If there are any issues: it will give you prompts on what to do.
NOTE: If you upgrade the app version, you will not be able to edit the project in the older version of the modeler. This will matter if there are multiple individuals on the same project. Mendix Project version and Modeler version are tied together.
Upgrading To a New Major Version
When Mendix releases a new major version, they create a guide for how to upgrade your app. Look for similar guides when upgrading to new releases after this tutorial is out of date.
Version 8 to 9:
https://docs.mendix.com/refguide/moving-from-8-to-9/
Version 9 to 10:
https://docs.mendix.com/refguide10/upgrading-from-9-to-10/
Version 10 to 11:
https://docs.mendix.com/refguide/upgrading-from-10-to-11/
Upgrade Tips
Make time for the upgrade
Ideally, stop other development while you upgrade. Set aside at least a full day for the upgrade, maybe more, depending on how complex the app is and how many versions behind you are.
An upgrade from 10.6.x to 10.18.3 will take far less time than one from 9.12.x.
If you can help it, do not create associations to entities in modules managed by Mendix, or any modules downloaded from the Mendix Marketplace like BYU Account, because it drastically complicates module upgrades. It is possible to preserve those associations after an upgrade, but it requires a lot of extra work.
Close all branches that are no longer needed. It will be difficult to update those branches from the upgraded Main branch.
Migrate version control to Git from SVN
Mendix Version 10 and later uses Git for version control, so an upgrade from Version 9 to a newer version will require Git Migration. It should be noted that migration can only be initiated by someone with the SCRUM Master role for a Mendix App.
See Mendix documentation here.
https://docs.mendix.com/developerportal/general/migrate-to-git/
Work on a feature branch from Main
Create a feature branch from Main and do your upgrade there. When everything is done and the app is working, you can merge back to Main.
Upgrade modules
Upgrading modules is usually the best way to resolve errors. You will probably have to upgrade several modules, but it is best practice to upgrade all marketplace modules regularly, so take the time necessary to make the upgrades. After reimporting a module that fixes a bunch of errors, it’s a good idea to save progress by making a copy of the application directory. The goal is progress, not perfection.
If an app uses the old Email Template Module, it needs to be updated to the new Email Connector Module. (See more info in the known issues section)
Run the application and resolve errors
Once all the errors caused by module dependencies are fixed and you no longer see errors in the Studio Pro console, you may see errors when you try to run the application. Studio Pro compiles Java (and SASS) when it builds and runs. You may run into Java compile errors. These issues tend to be the most difficult to resolve. It is recommended that you save a copy of your app directory locally before attempting to remove any of the problematic .jar files. Once you have a copy made, follow the file path given in the error, remove the file, clean the deployment directory, and run the app again.
Known Issues
SAML Module Encryption
When you upgrade the SAML module, it enables encryption by default. We don’t use encryption with BYU CAS. CAS Single sign-on will not work if you enable encryption. After upgrading the SAML module, you will probably have to manually modify the IdP Configuration for BYU CAS and turn off encryption.
Go to the SAML module, select the IdP Configuration tab, and edit the BYU CAS (or whatever it’s named) settings. Select the Encryption Settings tab and make sure Enable Better Security For App is not on.
See BYU CAS Single Sign-On at mendix.byu.edu for how to update the settings.
Userlib and vendorlib
In 10.3, Mendix introduced managed Java (.jar) dependencies. They are now in the /vendorlib directory. The /userlib directory after 10.3 should only have any custom dependencies you add.
Deep links, page and microflow links
In 10.6, a breaking change was introduced for links to pages. If the application uses deep links, or page an microflow links, and the version is older than 10.6, the links won’t work if you aren’t signed in. If you are not signed in, a direct link will take you to SSO to sign in, then lands on the main page. It won’t go to the linked page. To have it go to the page in the link after signing in, you’ll have to change the link URL you send to others, usually in an automatically generated email. Replace /link/ in the URL with /SSO/login?cont=link in the URL.
If the link you send in an email looks like this:
https://samplewebsite.mendixcloud.com/link/form/312
change it to this:
https://samplewebsite.mendixcloud.com/SSO/login?cont=link/form/312
Mimic/Proxy Issues
The AutoCompeteForMendix widget does not work in Mendix 10. Instead, use the Autocomplete Multiselect widget. For examples on how to use, you may look at the BYUAccount module application code. After converting, test every mimic/proxy search page, making sure the person search works, as well as making sure selecting the person works correctly, and the proxy succeeds. Make sure to search the code for all occurrences of AutoCompleteForMendix and replace them with the ‘Autocomplete Multiselect’ widget and new microflows if needed. (See examples in BYUAccount module).
PDF Document Generation module
The latest DocumentGeneration module (v1.10.3) to generate PDF documents needs the Combo Box widget in its Snip_AppRegistration snippet. If you update DocumentGeneration and get the error “Could not find widget 'Combo box' in the 'widgets' directory,” install the Combo box widget (v1.7.1). After installing it, you’ll see the error “The definition of this widget has changed. Update this widget by right-clicking it and selecting ‘Update widget’, or select ‘Update all widgets’ to update all widgets in the app.” Open the Snip_AppRegistration snippet, right-click on the Combo box widget and select ‘Update widget’ or ‘Update all widgets’.
After upgrading you may encounter errors because the page layout that was used before no longer exists. It is not necessary to use the DocumentLayount layout from the DocumentGeneration module in the most recent versions. It was required in the earliest versions. From the documentation Generating Documents for the Current User:
Create a page that you want to export as a document. In the properties of the page, set the design property Enable PDF export to Yes. As the layout of the page, you can use your own layout or the DocumentGeneration_Default layout from the _UseMe > Layouts folder.
When fixing the errors:
- Set the Page Design Property Enable PDF export to Yes.
- Set the Page Layout to whatever, or use DocumentGeneration_Default from DocumentGeneration.
See the Mendix PDF Document Generation documentation for details of its setup and use.
Email Template module must migrate to Email Connector module
First, while still on 9.x, update the EmailTemplate module (“E-mail module with templates”) by MxLabs to the latest version, 11.2.0.
OR just install the Email Connector module and recreate the templates by hand. The drawback is that you will lose all your previous emails that were sent, if you care about that kind of thing.
Then you’ll have to install the Email Connector module and Email Connector migration utility from the Mendix Marketplace.
Instructions here:
Email
Email: Migrating from Another Module
EmailConnectorMigrationUtility Instructions