MES Model Examiner® (MXAM)
New to MXAM?
Get to know MXAM & evaluate
How to migrate to a newer MXAM version?
This guide helps toolchain managers migrate to a newer MXAM version while preserving customizations and minimizing migration risks.
Migrating to a newer MXAM version is strongly recommended to keep up with the industry standards and prevent your toolchain from using obsolete guidelines for static model analysis. Also, you benefit from features such as new checks and guidelines, robust signal tracing and automatic, assisted and safe repair of findings.
To make migration easier, MXAM now includes features like the Guideline Document Update Wizard since v11.2.0 and improved project migration validation markers since v12.0.0. MXAM can open projects and annotations created in older versions of MXAM.
Please use the checklist down below for a smooth and successful migration of MXAM.
Pre-Migration Considerations
These considerations are not mandatory for the migration to function, but may prevent surprises later:
MATLAB Compatibility: Verify that your MATLAB version is supported by the target MXAM version. The MXAM compatibility table is available here.
License Configuration: Verify node-locked or floating license availability and server configuration.
Review release notes and the compatibility considerations mentioned in them.
Identify custom checks, hooks, libraries, and project files.
Note: If you maintain custom libraries with custom documents, guidelines or checks, it is recommended to save these libraries outside of the MXAM installation directory.
Download and install the new MXAM version.
Do not apply patches received for an older MXAM version in the new installation. The fixes will already be present in the new MXAM version.
Do not migrate checks developed by MES to the new version. They will already be present in the new MXAM version.
Annotations (.mxma files): MXAM automatically migrates annotation files when migrating to a new MXAM version, i.e., they can be reused. However, some annotations may not map any longer as findings may have changed in the new MXAM version. This may happen due to the exchange of checks or changes in the reported findings. Annotations related to linked Stateflow elements may become unmapped due to the introduction of integration model paths replacing library paths in reports since v11.3.0. Annotations created with MXAM versions older than 4.1.0 are no longer supported since v11.2.0.
Migrate Guideline Documents (.mxmd files)
Ensure that the custom guideline documents (. mxmd) are available in MXAM, either by adjusting the library settings or by opening the respective project with additional libraries. The custom documents should then be inspected in the Guideline Document editor. For example, guidelines and checks displayed in red color indicate that the referenced content is obsolete and no longer available in the new MXAM version.
Obsolete Guidelines: Certain guidelines may become obsolete and are then removed in the latest MXAM version. These are marked in red in the guideline document. Please update the guideline documents that contain these guidelines automatically with the Update Guideline Document Wizard . Right-click the top node of the guideline document and select “Update Guideline Document…”. Review the replacements/removals. Update the document by overwriting it or creating a new version of it. For more information on the deleted guidelines, you can refer to the release notes.
Refresh Check References: Guideline references should be refreshed in your custom guideline document as the guidelines might be updated with new checks. To do this, open the guideline document from the Guideline Documents Library. Right-click the top node of the guideline document, and click on ‘Refresh References’.
Update Check Parameters
Check parameters: Customized check parameter settings are automatically migrated. The only exception is where a check reference or a check parameter itself is changed. In this case, replaced guidelines’ check parameters must be reconfigured. The guidelines where check parameters need to be reviewed are indicated in the Guideline Document Update Wizard
Project Migration (.mxmp files)
The customized projects (.mxmp files) may have items that are no longer available in the new version and they need to be migrated to the new MXAM version.
Validation Markers: Please check the Validation Markers on the right-hand panel or under View → Validation Markers to get information on items that need attention during the project migration. After all the referenced guideline documents are updated, MXAM automatically migrates the project when you open it in the new MXAM version. If any referenced guideline document is not up-to-date, an error validation marker is shown in the Validation View and must be resolved before the project can be migrated. You can then review and confirm the migration by saving the project or make further changes as required.
Transfer Tool Customizations
MATLAB Path: Update permanently added MXAM folders in MATLAB to the new version.
Custom Documents, Guidelines, Checks or Parameters: Check <user directory>\MXAM\<MXAM_version>\libraries for custom content and ensure its moved to the new MXAM version folder.
Advanced Setup Considerations
Apply the following steps only when needed:
Note: Do not copy the below configuration files from the old MXAM installation to the new MXAM installation. Instead use a file comparison tool to make sure all settings are migrated as needed to the new version or if new properties introduced in the new MXAM version need additional setup.
Java Configuration (`mxam.ini`): Review Java version, heap size, executable path, and JVM arguments in the tool installation folder in the mxam.ini.
MATLAB Adapter (`com.modelengineers.mxam.tooladapter.matlab.ini`): Review MATLAB port, startup behavior, and connection settings.
Eclipse Configuration: Review <MXAM_INSTALLATION>\configuration\config.ini file for any custom runtime, plugin, or logging settings. If a custom log level was configured for debugging, ensure that it is reapplied after the migration. Do not copy the entire config.ini file from an older MXAM installation to a newer version. The file contains internal configuration settings that may change between releases, and reusing an outdated version can lead to unexpected behavior.
Transfer Check Parameter Customization Files: If you want to use one of the following configurations, it is strongly recommended to keep them in a separate repository outside the MXAM installation, and make them accessible to MXAM, i.e., make sure they are on the MATLAB path during the execution, and ensure that relevant check parameters contain the correct path.
MXRAY Configuration: <MXAM_INSTALLATION>\libraries\utilityMatlabTooladapter\mxray\configuration
MXAM Color Configuration: <MXAM_INSTALLATION>\libraries\checks\MATLAB_MES\functions\MATLAB\mxam_colorSchema.m
Check Parameter Excel Files: <MXAM_INSTALLATION>\libraries\checks\MATLAB_MES\functions\MATLAB
Batch Script Migration: Please review the release notes for any changes as we document this and also in the batch examples found at <MXAM_INSTALLATION>\doc\examples. Please update the projects or artifact paths, etc where needed.
Verify Element Matching (only relevant if you migrate from a version below 11.2): Starting from MXAM 11.2, the element matching setting used for annotation mapping and element identification during repair is part of the project (.mxmp files). Please verify the new setting under Project Settings → General → Element Matching.
Hook Functions: Ensure that any customized hook scripts are also made available in the new MXAM version and verify that their interface is compatible with the hook templates provided in <MXAM_INSTALLATION>\doc\hooks of the latest version. From MXAM v11.0.0, to programmatically determine the analyzed system during runtime, use the new hook mxam_hookSelectSubsystems instead of mxam_hookPreArtifact.
Migration Check list
Migrate Guideline Documents (.mxmd files)
☐ Obsolete guidelines reviewed
☐ Guideline documents refreshed
Update Check Parameters
☐ Check parameters updated where required
Project Migration (.mxmp files)
☐ Customized projects migrated
Transfer Tool Customizations
☐ MATLAB path updated
☐ Custom guideline content migrated
Advanced Setup Considerations
☐ Java configuration reviewed
☐ MATLAB adapter configuration reviewed
☐ Eclipse configuration reviewed
☐ Check parameter customization files transferred
☐ Batch scripts migrated
☐ Element matching settings reviewed
☐ Hook functions transferred
Quick Contact to the MXAM Developer- and Support Team
Here you can ask us all questions regarding the MES Model Examiner® (MXAM). Please also use this form to be kept up to date on MES tool updates and release notes (quarterly tool update newsletter). You can also send us a detailed support request.
