Compare CIM Models Effectively: A Guide to Using cim-compare Tool

[GitHub Repo]

The cim-compare project is a powerful command-line tool designed for generating comprehensive CIM (Common Information Model) model comparison reports. This tool is invaluable for anyone needing to track changes and understand differences between versions of CIM models. For a practical example of the output, you can explore a sample report at comparison-report.html.

[](#table-of-contents)

Latest Release

[](#latest-release)

1.3.0

Overview: CIM Model Comparison Reports

[](#overview-cim-model-comparison-reports)

cim-compare specializes in generating detailed model comparison reports between two distinct points in time, making it easy to Compare Cim models. It helps users identify exactly what has changed within their CIM models over different versions or development stages.

To facilitate clear understanding, the tool uses specific terminology. The “destination” model refers to the current version or the latest working copy of a CIM model that is the primary focus of the comparison. Conversely, the “baseline” model represents the historical model against which the “destination” model is compared. This baseline serves as the reference point to determine all modifications, additions, and deletions in the newer “destination” model.

While Enterprise Architect (Corporate Edition and above) offers model comparison features, their utility is limited because the results are typically exported as XML files. These XML files are not easily readable or user-friendly for most users. cim-compare overcomes this limitation by producing output in an easily digestible format.

The primary output of cim-compare is a self-contained HTML comparison report. This report meticulously details all changes between the “baseline” and “destination” models. The generated report is compatible with all standard web browsers, including Firefox, Chrome, Edge, and IE, ensuring broad accessibility. Furthermore, the HTML report includes a search function, allowing users to quickly find specific CIM classes or elements within the comparison.

To enhance visual clarity and understanding, the reports employ a color-coding system to represent different types of changes. New elements are highlighted in green, signifying additions to the model. Deleted items are shown in red, indicating removals from the baseline. Elements that have been relocated within the model are marked in yellow, helping to track structural changes. Blue is used to denote items that have been modified in some way, highlighting changes to properties or configurations. Finally, violet indicates items that remain unchanged between the two models, providing a clear view of what has stayed consistent.

Color representations in cim-compare reports for identifying changes in CIM models.

As illustrated below, comparison reports generated by cim-compare can also include UML diagrams that have been added, removed, or modified. This feature provides a visual dimension to the comparison, especially useful for understanding structural and design changes within the CIM models. To include diagrams in your comparison reports, you need to use specific command-line procedures which are detailed further in this document.

UML diagram comparison feature in cim-compare reports, showing visual differences between model diagrams.

For enhanced readability, changes to class and attribute descriptions are visualized using a text difference visualization. This approach makes it easy to identify specific modifications in textual descriptions, which are often crucial for understanding the semantic evolution of the CIM models.

Text difference visualization in cim-compare reports, highlighting specific changes in class and attribute descriptions.

Setup & Configuration

[](#setup–configuration)

Java Technical Requirements

[](#java-technical-requirements)

cim-compare is distributed as a fully self-contained executable jar file, which simplifies deployment and eliminates concerns about external dependencies. This design choice ensures that users can run the tool without needing to manage additional libraries or components.

Given the nature of CIM model files, which can be quite large, and the potentially large comparison reports generated, memory management is critical. Running cim-compare with default Java heap (memory) settings may lead to OutOfMemory exceptions. To prevent these issues and ensure smooth operation, it’s essential to adjust the Java heap size according to the following guidelines.

For users running a 32-bit JRE (Java Runtime Environment), it is strongly recommended to specify a maximum heap size of at least 1GB (i.e., 1024m), provided your system resources allow it. While a 1GB heap can be sufficient, it’s important to note that execution speed might be slower compared to using a larger heap. The theoretical maximum heap limit for a 32-bit JVM (Java Virtual Machine) is 4GB. However, practical limitations due to factors like available swap space, kernel address space usage, memory fragmentation, and VM overhead often reduce this limit. On most modern 32-bit Windows systems, the maximum achievable heap size typically ranges from 1.4GB to 1.6GB.

To apply this setting, use the following command structure when running cim-compare:

java -mx1G -jar **cim-compare-1.3.0.jar** iec61970cim16v26a.xmi iec61970cim17v16.xmi D:\reports

For systems using a 64-bit JRE, it is recommended to increase the maximum heap size to a minimum of 2GB (i.e., 2048m). Allocating even more memory, if available, can further improve performance, especially when working with larger CIM models. Practical observations indicate that 2GB is minimally adequate for handling the size of CIM models commonly encountered in real-world scenarios. The example below demonstrates allocating 4GB of heap space, which is advisable for enhanced performance and stability.

For 64-bit JREs, the command would look like this:

java -mx4G -jar **cim-compare-1.3.0.jar** iec61970cim16v26a.qea iec61970cim17v16.qea D:\reports

For users needing to download Java, freely available downloads are provided by Azul Systems. You can download Azul JDKs from their official download site: Download Azul JDKs. Azul Zulu builds of OpenJDK are a reliable and readily accessible option for running cim-compare.

Download 32-bit Java 17

[](#download-32-bit-java-17)

If your workflow involves comparing .eap files, it’s necessary to use 32-bit Java. For a direct download of 32-bit Java 17, click on the image below:

Download 64-bit Java 17

[](#download-64-bit-java-17)

For comparing .qea files, 64-bit Java is required. To directly download a 64-bit Java 17, please click the image below:

Important Setup Considerations

[](#important-setup-considerations)

The cim-compare command-line option that processes Enterprise Architect .EAP or .QEA project files as input (described in detail in the section Option #1: Enterprise Architect .EAP or .QEA Project Files as Input) relies on EA’s COM automation API. Therefore, if you intend to use this option, you must have a licensed version of Sparx Enterprise Architect (EA) installed. The COM automation API is essential for cim-compare to interact with EA project files directly. The EA API and the eaapi.jar file serve as interfaces to the Enterprise Architect application. The following points clarify this dependency:

Dependency on Sparx Enterprise Architect Application:

The EA COM API and eaapi.jar are fundamentally dependent on the backend functionality of the Enterprise Architect software. They act as a bridge, enabling interaction with models, diagrams, and repositories managed within EA.

Without the Enterprise Architect application installed, the API lacks a core functionality and data source to connect to, rendering it non-operational for cim-compare in this context.

Enterprise Architect COM Object:

The SSJavaCOM.dll and SSJavaCOM64.dll are COM interface wrappers that require Enterprise Architect’s COM objects to function correctly. These COM objects are installed as part of the standard Enterprise Architect installation process.

Licensing Requirements:

Sparx Enterprise Architect is a commercial licensed product. The API’s functionality is contingent upon a valid EA license to access its full range of features. Without a licensed installation of Enterprise Architect, API calls will either fail or be severely restricted, impacting cim-compare‘s ability to process EA project files.

Runtime Dependency:

When utilizing the COM automation interface, cim-compare initiates communication with an active EA process at runtime. The underlying API calls interact directly with the installed Enterprise Architect software to perform necessary operations, such as exporting .xmi files from an .eap or .qea project file. This dynamic interaction underscores the real-time dependency on a functioning EA installation for cim-compare to effectively utilize this input option.

The COM interface wrappers are included with every installation of Sparx EA and are typically located in a directory similar to:

%WINDOWS_PROGRAM_FILES%Sparx SystemsEAxxJava API (e.g. "C:Program FilesSparx SystemsEA16Java API")

The specific purpose of each DLL file is as follows:

SSJavaCOM.dll – This is the 32-bit COM Module DLL (Dynamic Linked Library). cim-compare links to this DLL when a 32-bit Java JVM/JRE is used to run cim-compare-1.3.0.jar from the command line. It is essential when processing 32-bit .EAP project files.

SSJavaCOM64.dll – This is the 64-bit COM Module DLL. cim-compare links to SSJavaCOM64.dll when a 64-bit Java JVM/JRE is used to run cim-compare.jar. This is required when processing 64-bit .QEA project files.

cim-compare dynamically selects and communicates with the appropriate COM Module DLL based on whether a 32-bit or 64-bit JVM is being used at the command line. The determination of which DLL COM interface wrapper to load and link to is made at runtime, ensuring compatibility with the specific Java environment in use.

A crucial setup step is ensuring that these two DLL COM interface wrappers are accessible to Java during runtime. This accessibility is configured via the command line by specifying the directory location using the -Djava.library.path JVM parameter. This parameter tells Java where to look for native libraries, including the COM DLLs required by cim-compare to interface with Enterprise Architect.

For systems that have both 32-bit and 64-bit Sparx EA installations (e.g., EA 15.x and EA 16.x), a configuration similar to the example below is recommended. This setup facilitates the use of cim-compare with different EA versions and bit architectures by isolating the necessary DLL files for each EA installation.

C:cim-compare
├── cim-compare-1.3.0.jar (the latest downloaded from https://cim-compare.ucaiug.io)
├── cim-compare-1.3.0.bat (example batch file for execution)
├── ea15
│   ├── SSJavaCOM.dll (copied from "C:Program Files (x86)Sparx SystemsEA15Java API")
│   └── SSJavaCOM16.dll (copied from "C:Program Files (x86)Sparx SystemsEA15Java API")
├── ea16
│   ├── SSJavaCOM.dll (copied from "C:Program FilesSparx SystemsEA16Java API")
│   └── SSJavaCOM16.dll (copied from "C:Program FilesSparx SystemsEA16Java API")
├── cim17v40.eap
├── cim18v02.eap
├── cim18v12.qea
└── cim18v13.qea

C:Program Files (x86) (32-bit JVM installation required for processing 32-bit .eap files)
└── Zulu
    └── zulu-17
        └── bin
            └── java.exe

C:Program Files (64-bit JVM installation required for processing 64-bit .qea files)
└── Zulu
    └── zulu-17
        └── bin
            └── java.exe
...

The key aspect of this configuration is that each EA installation’s set of DLL files is placed in its own dedicated directory (e.g., ea15, ea16). This directory separation is crucial as it allows you to specify exactly where Java should look for its COM Modules based on the specific version of Sparx EA being used. This isolation prevents conflicts and ensures that the correct COM libraries are loaded for each EA version, especially when dealing with projects from different EA versions or bit architectures.

Below are command-line examples based on the directory structure and configuration outlined above. The first example shows how to generate a comparison report for 32-bit .eap files, and the second demonstrates the process for 64-bit .qea files. These examples highlight how to correctly specify the Java executable and library paths for each scenario.

"C:Program Files (x86)Zuluzulu-17binjava.exe" -mx1G -Djava.library.path="D:cim-compareea15" 
-jar cim-compare-1.3.0.jar cim17v40.eap cim18v02.eap comparison-report.html 
--include-diagrams --image-type=JPG --minimal

The 32-bit command line example components are detailed below:

"C:Program Files (x86)Zuluzulu-17binjava.exe": Specifies the path to a 32-bit Java 17 JRE/JVM. This ensures that the 32-bit version of Java is used, which is necessary for processing .eap files.
-mx1G: Sets the maximum heap size to 1GB (1024m). This is configured using -mx1G or -mx1024m and is crucial for managing memory when processing potentially large .eap files.
-Djava.library.path="D:cim-compareea15": Directs Java to load the 32-bit COM DLL from the "D:cim-compareea15" directory. This is essential for Java to interface with the 32-bit Enterprise Architect API.
cim-compare-1.3.0.jar: Specifies the cim-compare executable jar file.
cim17v40.eap: Indicates cim17v40.eap as the input baseline model. The .eap extension signifies that it is a 32-bit EA project file.
cim18v02.eap: Specifies cim18v02.eap as the input destination model, also a 32-bit EA project file.
comparison-report.html: Sets the name of the generated HTML report file.
--include-diagrams: Includes diagram images in the generated report. This flag tells cim-compare to incorporate diagrams in the comparison output.
--image-type=JPG: Specifies JPG as the image type for the diagrams.
--minimal: Includes only changed elements in the report, creating a more concise output by excluding identical elements.

"C:Program FilesZuluzulu-17binjava.exe" -mx4G -Djava.library.path="D:cim-compareea16" 
-jar cim-compare-1.3.0.jar cim17v40.qea cim18v02.qea comparison-report.html 
--include-diagrams --image-type=JPG --minimal

The 64-bit command line example components are as follows:

"C:Program FilesZuluzulu-17binjava.exe": Specifies the path to a 64-bit Java 17 JRE/JVM. This ensures that the 64-bit version of Java is used, which is required for processing .qea files.
-mx4G: Sets the maximum heap size to 4GB (4096m). Configured via -mx4G or -mx4096m, this larger heap size is recommended for 64-bit Java to handle potentially larger .qea files and improve performance.
-Djava.library.path="D:cim-compareea16": Directs Java to load the 64-bit COM DLL from the "D:cim-compareea16" directory. This is crucial for enabling Java to interface with the 64-bit Enterprise Architect API.
cim-compare-1.3.0.jar: Specifies the cim-compare executable jar file.
cim17v40.qea: Designates cim17v40.qea as the input baseline model. The .qea extension indicates that it is a 64-bit EA project file.
cim18v02.qea: Specifies cim18v02.qea as the input destination model, also a 64-bit EA project file.
comparison-report.html: Defines the filename for the generated HTML report.
--include-diagrams: Includes diagram images in the report output.
--image-type=JPG: Sets the image type for diagrams to JPG, ensuring diagrams are included in the specified format.
--minimal: Generates a report that excludes identical elements, focusing only on changes for a more streamlined analysis.

Warning: Potential Configuration Pitfalls

[](#warning-potential-configuration-pitfalls)

A common mistake users encounter is using an incorrect bit-wise version of Java when processing project files with cim-compare. Specifically, when working with .eap project files, it is imperative to use 32-bit Java. Conversely, for .qea files, 64-bit Java must be used. Mismatched Java bit-wise versions are a frequent cause of errors and operational failures.

In the command-line examples provided earlier, note that the java executable is explicitly qualified as either "C:Program Files (x86)Zuluzulu-17binjava.exe" (for 32-bit) or "C:Program FilesZuluzulu-17binjava.exe" (for 64-bit). This explicit qualification is a recommended practice to ensure the correct Java version is used, thereby preventing bit-wise mismatch errors. While not strictly required, it is a robust method to avoid this common pitfall.

If you opt to simplify the command line by using the default Java installation, such as:
java -mx4G -Djava.library.path="D:cim-compareea16" -jar cim-compare-1.3.0.jar ...
…it is highly advisable to verify the bit-wise version of your default Java installation. You can do this by running the command java -version. The output from this command should indicate whether your default Java installation is 32-bit or 64-bit. For 32-bit versions, the output may explicitly state “32-Bit”, or the installation directory path may include C:Program Files (x86).... For many recent Java releases, if the architecture is not explicitly stated as 32-bit, it is generally implied to be 64-bit, as illustrated in the example output below:
C:>java -version
openjdk version "17.0.13" 2024-10-15 LTS
OpenJDK Runtime Environment Zulu17.54+21-CA (build 17.0.13+11-LTS)
OpenJDK Client VM Zulu17.54+21-CA (build 17.0.13+11-LTS, mixed mode, emulated-client)
If command line execution results in an error message similar to the following, it typically indicates a bit-wise mismatch between the Java executable being used and the project files being input:
java.lang.Exception: Internal application error.
 at org.sparx.Repository.comGetModels(Native Method)
 at org.sparx.Repository.GetModels(Repository.java:805)
 at org.cimug.compare.app.CIMModelComparisonGenerator.parseFileArguments(CIMModelComparisonGenerator.java:492)
 at org.cimug.compare.app.CIMModelComparisonGenerator.main(CIMModelComparisonGenerator.java:107)
ERROR: Terminating XMI export processing for EA project file [CIMMarket04v16a.eap] due to an unexpected exception.
Lastly, be aware that even if you initially configure a bit-wise compliant Java version and successfully generate reports, cim-compare might stop working later. This can occur if software installations on your system, as part of their setup process, install a newer 64-bit version of Java and set it as the default. This update can happen without explicit notification, potentially changing your default Java version and causing bit-wise mismatches for subsequent cim-compare executions. Therefore, if cim-compare unexpectedly stops functioning, verifying the default Java version and its bit-wise compatibility with your project files should be among the first troubleshooting steps.

Command Line Usage

[](#command-line-usage)

The cim-compare utility offers three distinct command-line options for generating comparison reports, each tailored to different input types and user scenarios. These options provide flexibility in how you compare cim models, accommodating various workflows and data formats.

Option #1: Enterprise Architect .EAP or .QEA Project Files as Input

[](#option-1-enterprise-architect-eap-or-qea-project-files-as-input)

The recommended and most straightforward method is to directly provide two Enterprise Architect *.eap or *.qea files as input for the “baseline” and “destination” models. Using these file types simplifies the process significantly by eliminating the need to manually export XMI and diagrams from EA, which is required for other options. When using .eap or .qea files, it’s crucial to ensure that both the “baseline” and “destination” files are of the same bit-type: either both 32-bit (*.eap) or both 64-bit (*.qea). It’s worth noting that processing 64-bit *.qea files generally offers better performance.

The command-line syntax for this option is as follows:

java [<jvm-parameter-1>]...[<jvm-parameter-n>] -jar cim-compare-1.3.0.jar 
<baseline-model-file> <destination-model-file> [<output-directory-or-html-file>] 
[--package=<package-name>] [--minimal] [--include-diagrams] [--image-type=<image-file-extension>] 
[--zip] [--cleanup]

Parameter Details:

[<jvm-parameter-x>] (Optional): JVM (Java Virtual Machine) parameters can be included as needed for execution tuning. These parameters configure the JVM’s behavior at runtime and are used to manage settings like memory allocation (-mx1096m, -mx4G) or character encoding (-Dfile.encoding=UTF-8). JVM parameters influence memory usage, garbage collection, system properties, debugging, and overall performance. They are passed as command-line arguments when starting a Java application and must be placed first in the command-line arguments, before cim-compare-1.3.0.jar. This order is important to prevent cim-compare from attempting to process JVM parameters as part of its own command-line arguments, which should always come after cim-compare-1.3.0.jar. For Option #1, the -Djava.library.path= JVM parameter is essential and will be detailed later.

<baseline-model-file> (Required): This specifies the Enterprise Architect baseline model file, which can be either a .eap or .qea file. If the file path is not absolute, cim-compare assumes the file is located in the directory from which the command is executed.

<destination-model-file> (Required): This is the Enterprise Architect destination model file, also either a .eap or .qea file. Similar to the baseline file, if an absolute path is not provided, cim-compare looks for the file in the current execution directory.

[<output-directory-or-html-file>] (Optional): Defines the output location for the generated report. This can be either a directory or a specific HTML file. If a directory is specified and does not exist, cim-compare will create it. The same applies to the parent directory of a specified HTML file. If you provide an HTML filename, it can be an absolute path or just the filename, in which case the report is generated in the current directory. If this option is omitted, cim-compare automatically generates an HTML file named based on the input file names.

[--package=<package-name>] (Optional): This parameter allows you to specify a root package within the models to start the comparison report from. When used, it should appear at the end of the command line, after all file and directory specifications, and the package name must exist in both the baseline and destination models. Examples include --package=IEC61970, --package=Grid, --package=IEC61968, --package=IEC62325, or --package=CIM. If no package name is specified, the report is generated from the root package of both models.

[--minimal] (Optional): When included, this flag instructs cim-compare to exclude all “Identical” elements (packages, classes, attributes, links, diagrams, etc.) from the generated report. This is particularly useful when you need to focus your analysis solely on the changes between models, providing a more concise and focused report.

[--include-diagrams] (Optional): This option specifies that diagram images should be exported from EA and included in the comparison report. To define the image format for the exported diagrams, you should also use the --image-type option. If --image-type is not specified, the default image format is JPG.

[--image-type=<image-file-extension>] (Optional): This parameter sets the image file format for diagrams exported from EA. Supported formats are JPG, GIF, PNG, BMP, and EMF. If you are using JPG images, this option can be omitted as JPG is the default. This option is only effective when --include-diagrams is also specified in the command.

[--zip] (Optional): When this option is used, cim-compare packages the generated report and any associated diagram images into a single ZIP archive. This is especially helpful for distributing reports, particularly when diagrams are included, as it consolidates all output files into one easily manageable file.

[--cleanup] (Optional): If specified, cim-compare will automatically delete all intermediate files and directories created during the report generation process, except for the final ZIP archive (if --zip is also used). This option is primarily relevant when --zip is also included in the command line, helping to keep the output directory clean by removing temporary files after creating the ZIP archive.

Note that in the command line examples below, any directory or file paths that contain spaces are enclosed in quotes to ensure they are correctly interpreted by the command line.

Command Line Examples:
`java -mx1096m -Djava.library.path="D:cim-compareea15" -jar cim-compare-1.3.0.jar "C:\exports\15v33.eap" "C:\exports\CIM16v26a.eap" "C:\"`
`java -mx4096m -Djava.library.path="D:cim-compareea16" -jar cim-compare-1.3.0.jar "C:\exports\15v33.qea" "C:\exports\CIM16v26a.qea" "C:\"`
`java -mx1096m -Djava.library.path="D:cim-compareea15" -jar cim-compare-1.3.0.jar "C:\exports\15v33.eap" "C:\exports\CIM16v26a.eap" --package=IEC61970 --minimal`
`java -mx1096m -Djava.library.path="D:cim-compareea15" -jar cim-compare-1.3.0.jar CIM15v33.eap CIM16v26a.eap C:\ --minimal`
`java -mx1096m -Djava.library.path="D:cim-compareea15" -jar cim-compare-1.3.0.jar CIM15v33.eap CIM16v26a.eap C:\ --minimal --include-diagrams --zip`
`java -mx4096m -Djava.library.path="D:cim-compareea16" -jar cim-compare-1.3.0.jar CIM15v33.qea CIM16v26a.qea C:\CIM15v33_CIM16v26a_ComparisonReport.html`
`java -mx1096m -Djava.library.path="D:cim-compareea15" -jar cim-compare-1.3.0.jar CIM15v33.eap CIM16v26a.eap CIM15v33_CIM16v26a_ComparisonReport.html --minimal`
`java -mx1096m -Djava.library.path="D:cim-compareea15" -jar cim-compare-1.3.0.jar CIM15v33.eap CIM16v26a.eap --package=IEC62325 --minimal --include-diagrams --image-type=GIF --zip --cleanup`
`java -mx4096m -Djava.library.path="D:cim-compareea16" -jar cim-compare-1.3.0.jar CIM15v33.qea CIM16v26a.qea --package=Grid --minimal --include-diagrams --image-type=GIF --zip --cleanup`

NOTE: The command line examples above demonstrate the use of both .eap and .qea EA files as input. When .eap files are used as input, it is assumed that 32-bit Java is used to execute the .jar file. Similarly, for .qea files, it is assumed that 64-bit Java is being used.

Option #2: XMI Baseline and Destination Models as Input

[](#option-2-xmi-baseline-and-destination-models-as-input)

The second usage option involves directly specifying two XMI 1.1 compliant files that represent the “baseline” and “destination” models. These XMI files should be exported from Enterprise Architect following the procedures detailed in Enterprise Architect XMI Export Procedures. This method is useful when you prefer to handle the export process manually or need to work with XMI files for other reasons. The command-line syntax for this option is:

java [<jvm-parameter-1>]...[<jvm-parameter-n>] -jar cim-compare-1.3.0.jar 
<baseline-model-xmi-file> <destination-model-xmi-file> [<output-directory-or-html-file>] 
[--package=<package-name>] [--minimal] [--include-diagrams] [--image-type=<image-file-extension>] [--zip] [--cleanup]

Parameter Details:

[<jvm-parameter-x>] (Optional): As in Option #1, you can include JVM parameters at the beginning of the command for performance tuning or system configurations. These parameters are optional but can be crucial for optimizing memory usage and handling large models.

<baseline-model-xmi-file> (Required): This parameter specifies the path to the XMI 1.1 compliant baseline model file that has been exported from Enterprise Architect. If the path is not absolute, the tool assumes the file is in the current working directory.

<destination-model-xmi-file> (Required): This parameter specifies the path to the XMI 1.1 compliant destination model file, also exported from EA. Like the baseline file, a non-absolute path implies the file is located in the current directory.

[<output-directory-or-html-file>] (Optional): This is the output directory or the HTML file name for the comparison report. If a directory path is given and it doesn’t exist, it will be created. Similarly, for an HTML file, its parent directory will be created if necessary. If this parameter is omitted, cim-compare will automatically name the HTML report based on the input XMI filenames.

[--package=<package-name>] (Optional): This allows you to specify a root package for the comparison within the XMI models. The specified package must exist in both the baseline and destination models. If not provided, the comparison starts from the root package of the models.

[--minimal] (Optional): Using this option will exclude all “identical” elements from the comparison report, focusing the output only on differences between the models.

[--include-diagrams] (Optional): When specified, this option indicates that diagram images should be included in the generated comparison report. However, unlike Option #1, this option does not automatically export diagrams from EA. Instead, it expects that the diagram images have been manually exported as part of the XMI export process and are located in folders named /Image-baseline and /Image-destination. These folders should be in the same directory where you are running cim-compare. It’s crucial to prepare these folders and images before running the tool with this option.

IMPORTANT: Unlike Option #1, this command line option does not automatically export diagrams. It requires that diagrams are exported manually as part of the XMI export process from EA. These exported images should be placed in folders named /Image-baseline and /Image-destination, respectively, in the same directory from which you are running cim-compare. This preparation must be completed before executing cim-compare. Refer to the “Enterprise Architect XMI Export Procedures” section in this README for detailed instructions on how to export XMI and diagrams manually.

[--image-type=<image-file-extension>] (Optional / Conditionally Required): This parameter specifies the image file type (e.g., JPG, GIF, PNG, BMP, or EMF) of the diagram images that are included in the report. It is conditionally required when you use the --include-diagrams option and your diagram images are not in JPG format. If your images are JPGs and you use --include-diagrams, you can omit this option as JPG is the default.

[--zip] (Optional): If used, cim-compare will compress the generated report and any included diagram images into a single ZIP archive, simplifying distribution and storage.

[--cleanup] (Optional): This option, when specified, will delete all temporary files and directories created during report generation, except for the final ZIP archive (if --zip is used). It helps maintain a clean output directory.

As with Option #1, remember to enclose any directory or file paths containing spaces in quotes in the command line examples below.

Command Line Examples:
`java -mx2048m -jar cim-compare-1.3.0.jar "C:\XMI exports\15v33.xmi" "C:\XMI exports\CIM16v26a.xmi" "C:\"`
`java -mx2048m -jar cim-compare-1.3.0.jar "C:\XMI exports\15v33.xmi" "C:\XMI exports\CIM16v26a.xmi" --package=IEC61970 --minimal`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33.xmi CIM16v26a.xmi C:\ --minimal`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33.xmi CIM16v26a.xmi C:\ --minimal --include-diagrams --image-type=gif --zip --cleanup`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33.xmi CIM16v26a.xmi C:\CIM15v33_CIM16v26a_ComparisonReport.html`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33.xmi CIM16v26a.xmi CIM15v33_CIM16v26a_ComparisonReport.html --minimal`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33.xmi CIM16v26a.xmi CIM15v33_CIM16v26a_ComparisonReport.html --package=IEC62325 --include-diagrams --image-type=JPG --zip`

Option #3: EA Model Comparison Logs as Input

[](#option-3-ea-model-comparison-logs-as-input)

The third option to compare cim models is by using an EA model comparison log file as input. To use this option, you must first generate a comparison XML log file from within Enterprise Architect. Detailed instructions on how to generate XML Compare Logs from Enterprise Architect are available in the EA Comparison Log Procedures. It’s important to note that EA’s comparison log feature does not support UML diagram comparisons. Consequently, diagrams are not included in reports generated using Option #3. This option is best suited for text-based comparisons of model elements and their properties.

The command-line usage for Option #3 is as follows:

java [<jvm-parameter-1>]...[<jvm-parameter-n>] -jar cim-compare-1.3.0.jar 
<comparison-results-xml-file> [<output-directory-or-html-file>] [--package=<package-name>] [--minimal] 
[--zip] [--cleanup]

Parameter Details:

[<jvm-parameter-x>] (Optional): Similar to the previous options, you can include JVM parameters at the beginning of the command line for configuration and optimization purposes.

<comparison-results-xml-file> (Required): This parameter specifies the path to the model comparison XML file generated by Enterprise Architect. If the path is not absolute, the tool assumes the file is located in the directory from which cim-compare is executed.

[<output-directory-or-html-file>] (Optional): Defines the output directory or the HTML report file name. If a directory is specified and doesn’t exist, it will be created. The same applies to the parent directory of an HTML file. If this option is omitted, cim-compare will generate an HTML report with a default name based on the input XML file.

[--package=<package-name>] (Optional): Allows you to specify a root package for the comparison report. The specified package must be present in both the baseline and destination models used to generate the comparison log. If this option is not used, the report will cover the entire model comparison from the root package.

[--minimal] (Optional): When included, this option will exclude all “Identical” elements from the generated report, focusing only on the changes detected in the EA comparison log.

[--zip] (Optional): If specified, cim-compare will package the generated report into a ZIP archive. Note that since Option #3 does not support diagram comparisons, only the HTML report itself will be included in the ZIP archive.

[--cleanup] (Optional): If used, cim-compare will delete all temporary files and directories created during report generation, except for the ZIP archive (if created). This helps to keep the output directory clean.

Again, in the command line examples below, directory or file paths that contain spaces should be enclosed in quotes.

Command Line Examples:
`java -mx2048m -jar cim-compare-1.3.0.jar "C:\CIM XMI Exports\CIM15v33_CIM16v26a_EA_Comparison_Report.xml" "C:\Reports"`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33_CIM16v26a_EA_Comparison_Report.xml "C:\Comparison Reports" --minimal`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33_CIM16v26a_EA_Comparison_Report.xml "C:\Comparison Reports" --package=IEC61968 --include-diagrams`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33_CIM16v26a_EA_Comparison_Report.xml ComparisonReport_CIM15v33_CIM16v26a.html`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33_CIM16v26a_EA_Comparison_Report.xml`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33_CIM16v26a_EA_Comparison_Report.xml --package=IEC61970`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33_CIM16v26a_EA_Comparison_Report.xml --package=IEC61970 --minimal`
`java -mx2048m -jar cim-compare-1.3.0.jar CIM15v33_CIM16v26a_EA_Comparison_Report.xml --package=IEC61970 --minimal --zip --cleanup`

Enterprise Architect XMI Export Procedures

[](#enterprise-architect-xmi-export-procedures)

To use Option #2 for compare cim models, you need to export your EA models to XMI 1.1 format. The following steps outline the procedure for exporting both baseline and destination models from Enterprise Architect as XMI 1.1 compliant files. These screenshots are taken from EA v15.1, but the process is similar in other versions.

First, in Enterprise Architect, load the “baseline” (or older) model. Select the top-level package of your model in the Project Browser. This package will be the root from which the XMI export will be generated.

Selecting the root package of the CIM model in Enterprise Architect for XMI export.
Once the root package is selected, navigate to the “Publish” menu in EA’s main toolbar. From the “Publish” dropdown menu, choose the “Other Formats…” option. This will open the “Publish Model Package to Other Formats” dialog.

Accessing the “Other Formats” export option in Enterprise Architect’s Publish menu.
In the “Publish Model Package to Other Formats” dialog, you need to configure the export settings. Select “UML 1.3 (XMI 1.1)” as the XML export type from the dropdown list. This specific format, UML 1.3 (XMI 1.1), is the only export format supported by cim-compare for model comparison reports. Ensure that the “Unisys/Rose Format” option is not checked, as this format is incompatible. If you wish to include UML diagrams in your comparison report, you can optionally select this now by checking both the “Export Diagrams” and “Generate Diagram Images” checkboxes. When including diagrams, also select an image type (e.g., JPG, GIF, PNG, etc.) from the “Diagram Image Format” dropdown to specify the format for the exported diagram images. Note that if you choose to include UML diagrams as part of the export, EA will automatically create a directory named “Images” in the export location and place all exported image files into this directory. If you choose an image type other than JPG, you must use the --image-type command line option as described in the Command Line Usage section when running cim-compare.

Configuring the export settings in Enterprise Architect for UML 1.3 (XMI 1.1) export, including diagram export options.
Specify a target directory and a filename for the exported XMI file in the “Filename” field. Choose a location where you want to save the XMI file and give it a descriptive name that identifies it as the baseline model.
Click the “Export” button to start the export process. Be aware that the export process might take a considerable amount of time to complete, especially for large models. The duration depends on the size and complexity of your CIM model.
If you included UML diagrams in the export, once the export process is complete, navigate to the directory where you saved the exported files. You will find a directory named “Images” created by EA, containing the exported diagram images. Rename this directory from “Images” to “Images-baseline”. This naming convention is crucial and must be exactly as specified, including case sensitivity, for cim-compare to correctly recognize and use these images for the baseline model in the comparison report.
After exporting the baseline model, close the baseline model in Enterprise Architect. Then, load the “destination” model into EA and repeat Steps 1 through 6. This time, ensure you enter a different, unique name in the “Filename” field for the destination XMI file to distinguish it from the baseline XMI file. When exporting diagrams for the destination model, upon completion, rename the “Images” directory created by EA to “Images-destination”.
After completing these steps for both baseline and destination models, you should have an export directory containing two image directories, “Images-baseline” and “Images-destination” (if you exported diagrams), and two distinct XMI files representing your baseline and destination models. These files are now ready to be used as input for cim-compare using Option #2.

License

[](#license)

Distributed under the MIT license. See LICENSE for more information.

Compare CIM Models Effectively: A Guide to Using cim-compare Tool

Table of Contents

Latest Release

Overview: CIM Model Comparison Reports

Setup & Configuration

Java Technical Requirements

Download 32-bit Java 17

Download 64-bit Java 17

Important Setup Considerations

Warning: Potential Configuration Pitfalls

Command Line Usage

Option #1: Enterprise Architect .EAP or .QEA Project Files as Input

Option #2: XMI Baseline and Destination Models as Input

Option #3: EA Model Comparison Logs as Input

Enterprise Architect XMI Export Procedures

License

Comments

Leave a Reply Cancel reply