jCleanCim readme

jCleanCim is an open source tool for validation and documentation generation from Enterprise Architect UML models of IEC TC57 CIM and IEC61850 UML models.

Up until end of 2015 it has been hosted by the CIM Methods & Tools for Enterprise Integration group on the CIM Users Group web site, with access limited to the CIM and IEC61850 users community members only.

To make it accessible also to non-CIMug members, since 2016, I decided to share it as a full open source tool and host it at my web space.

This is a non-GUI Java application and the Java code is fully platform independent. However, it unfortunately must be run on MS Windows machine due to the usage of Enterprise Architect and MS Word automation libraries (.dlls).

(Old release notes)


Once you unzip a jCleanCim distribution, doc directory contains the full documentation. The important parts of the source code are documented and that documentation is generated as so-called javadoc - namely, a set of web pages that allow for easy navigation.

Which distribution should I download?

jCleanCim is available in two distributions, depending on how you want to use it.

Even if you have a 64-bit Windows OS, ensure you install a 32-bit Java (JRE: runtime) or SDK (software development kit) and have it appear on your PATH before the potentially already installed 64-bit Java, because Enterprise Architect is still a 32-bit application and requires a 32-bit Java. See the commented text in the run.bat script.

Distribution User kind Prerequisites Installing
Binary distribution jCleanCim-[version]-bin.zip Run jCleanCim from the console (cmd.exe).
  • 32-bit Java 7+ runtime (JRE). To verify whether you already have it installed, open the console window and type java -version
  • Enterprise Architect build 834+ (version 7.1+)
  • (optional: to run doc generation) MS Word 2003+
Unzip the distribution anywhere on your file system; it will uncompress in its own directory tagged with the version so there is no danger of overwriting an older installation. For example, using WinZip, select "Extract to here" command.
Source distribution jCleanCim-[version]-src.zip Run jCleanCim from the console (cmd.exe) or from within eclipse.

Develop and build it with Apache ant or with eclipse.

  • 32-bit Java 7+ software development kit (SDK). To verify whether you already have it installed, open the console window and type javac -version
  • Something to compile the code and create executable, e.g.:
    • Apache ant 1.7.1+. To verify whether you already have it installed, open the console window and type ant -version.
    • or an IDE if you are already a Java developer.
  • Enterprise Architect build 834+ (version 7.1+)
  • (optional, runtime: to run doc generation) MS Word 2003+
  • (optional, during ant build: to build javadoc with UML for any distribution, and to document ant build targets dependencies graph) GraphViz application. To verify whether you already have it installed, open the console window and type dot -version

Same as for binary distribution (jCleanCim-[version]-bin.zip).

If used with eclipse, start eclipse SDK and after unzipping, use Import ->Existing project and browse to the unzipped directory.

Note: This is the most flexible option if you are developing, as you can have the eclipse project anywhere on your disk (not necessarily in an eclipse workspace).

Note for source distribution (and if you need to create the distribution yourself): Ant build file contains targets that invoke GraphViz application for creation of graphical elements for the documentation (UML-enhanced javadoc, and javadoc in pdf format). If you do not have GraphViz installed on your local system, these targets will be just skipped during the build (even if you get exceptions from the doclet, the javadoc gets generated, just without the UML diagrams). However, if you want to produce jCleanCim distributions, you should install GraphViz in order to have nicer documentation.


To be self-contained, jCleanCim distributions bundle relevant third party open source/distributable libraries. Java jars are in the project's lib directory, and MS Windows dlls are in the dlls directory.

The following libraries are packaged with all the distributions of jCleanCim:

The following libraries are packaged only with source distribution of jCleanCim:

Performance indicators

Since we talk to EA and to MS Word through their automation APIs, the model building (as a first step in the application) and the MS Word document generation (if enabled) take time:

Java processing - for validation, statistics calculation and documentation collection from in-memory model to pass to the actual writer (s), as well as XML document generation for web-access - takes a couple of seconds for all the models and scenarios tested.


Here items thay may be considered as issues (but will likely not be addressed soon) and performance-related advice, so please take them into account when running jCleanCim:


Starting with release 02v00, jCleanCim has been licensed under the terms of GNU LGPLv3 license and includes a modified copyright. The copyright as well as a reference to the license for this software is available at the download site, and is included in every distribution and in every java source file.

Have a look here for a relatively accessible comparison of licenses.

This software has been developed in my free time. The contained IP is not related in any way to my previous or current employer.

Release notes for jCleanCim-02v01, 2016-07-23

New home

Since 2016, jCleanCim has new home at my web space - which is accessible also to non-CIMug members.

New features

Hyperlinks in the Word document

Credit: Prototype by Laurent Guise (thanks!) has inspired the implementation in this release.

This (by IEC 61850 community) long awaited feature is in and it is controlled by a new configuration option, docgen.word.useHyperlinks . To not incure performance penalty, the default is 'disabled' (i.e., you need to set it to true explicitly .

The hyperlinks are introduced for those classes and enumeration literals that have been printed in the same document. For example:

New MS Word document placeholders

In this release, we have added three new placeholders for MS Word document generation:

We have also added examples in the base-small-template.docx to show how to use the new placeholders.

Support for EA Enumeration type (that discards class with "enumeration" stereotype)

In more recent versions of EA, on XMI import, EA refuses to import the original class with stereotype "enumeration", but transforms it automatically to the new Enumeration type. We found no way to force EA to keep enumeration stereotype imported through XMI. The result was that the enumeration classes were then not recognised in jCleanCim as enumerated types and one had to manually add enumeration stereotype.

This release provides proper handling for this case, as well - i.e., the EA Enumeration type is now recognised as enumerated type, the same way as a class with "enumeration" stereotype.

Performance changes in release 02v01

None. Note however that newer versions of Enterprise Architect seem to always be somewhat slower than the older ones (we noticed the slow down in diagram generation).

Potential backwards compatibility breaking changes for the application user

Potential forwards incompatibility for the application user: old jCleanCim with new EA

Other functional changes

Validation rules:

Bug fixes:

Known issues / limitations:

Implementation and packaging:


Built on 2016-07-23T22:39:05

Copyright License


Valid XHTML 1.0 Strict