jCleanCim introduction
June 2010
tatjana.kostic@ch.abb.com
1
What is jCleanCim and where to find it?

What:
–
jCleanCim is an open source tool

–
–
Developed to support validation and documentation generation
from Enterprise Architect CIM UML models*
A Java application, but platform dependent due to usage of
applications available on MS Windows only:


–

Copyright is provided on the download site, as heading in each source
file, and as link from every javadoc page
Enterprise Architect
MS Word
A console application, currently without any GUI
Where:
–
Hosted by the CIM Tools group on the CIM Users Group web site
for the CIM users community
http://cimug.ucaiug.org/Groups/Tools/Shared%20Documents/Forms/AllItems.aspx
2
jCleanCim
June 2010
* And also IEC61850 UML model that ABB donated to IEC TC57 in October 2009
jCleanCim directory @ CIMug
Use
latest
version
3
jCleanCim
June 2010
Who should use jCleanCim and when?

Who:
–
Primarily those who edit CIM UML and publish its documentation, thus:



When:
–
If you are already a user of the excellent CIMTool, you may wonder where
within the process of CIM development and maintenance the jCleanCim
fits:


4
jCleanCim
June 2010
Official IEC CIM model editors, responsible for maintaining the CIM information
model (UML) and for generating official IEC documents, and,
Those who define custom non-standard CIM extensions who want to ensure they
have followed standard CIM rules and who want to generate documentation for
those extensions.
You would first use jCleanCim to validate correctness of the CIM information
model (UML), and if required, to generate the information model documentation
in MS Word format, as required by IEC process.
You would then use CIMTool to create CIM profiles (XSD, RDF, OWL) and their
documentation (HTML) from the imported CIM UML model, and to validate
instance files created based on those profiles.
Documentation


Start from readme.html
available at the SharePoint
Once you unzip a jCleanCim
distribution (or import the
eclipse-dependent one as
eclipse project), full
documentation is available:
–
–
–
5
jCleanCim
June 2010
As javadoc in
doc/api/index.html
For binary distribution, also as
pdf (auto-generated from the
javadoc)
For source distributions, also
build targets dependencies
Selecting distribution

-bin
–

-eclipse
–

jCleanCim
June 2010
For jCleanCim
developer,
packager and user,
with eclipse IDE
-src
–
6
For jCleanCim user
For jCleanCim
developer,
packager and user,
with Apache ant
Note for CIMTool users


CIMTool is an eclipse-based application with a GUI, while jCleanCim only
uses eclipse for development and building (it is a simple console
application, without GUI)
The most comfortable way to use jCleanCim is however with –eclipse.zip
distribution, because:
–
–


If you develop in Java with eclipse, you already have what is needed
If you have downloaded the CIMTool that contains an eclipse runtime:
–
–
–
7
jCleanCim
June 2010
You click to run jCleanCim instead of typing commands in the console window
Eclipse gives a nice console output (you can copy/paste and scroll it easily)
Using that installation of eclipse (runtime) is not sufficient, because it is only
runtime, without support for Java code development
You must have an SDK (software development kit) to automatically build the
jCleanCim application from sources
On eclipse download site, the minimum required distribution is “Eclipse IDE for
Java developers”. (you can then install CIMTool plug-in in this version of eclipse)
jCleanCim functions



jCleanCim first creates in-memory representation of the whole content
of UML from .eap file
On the fly, it analyses the model and calculates a bunch of things,
including effective dependencies and logs that all into log files under
log directory, automatically created on the first run
After that, depending on what is set in properties (see next slide), one
or more of the following gets executed and logged:
–
Validation of a UML model provided in an .eap file



–
–
–
Calculation and printing of statistics of the UML model
Generation of MS Word documentation from the UML model
(deprecated) Bulk updating of the UML model

8
jCleanCim
June 2010
UML of standard IEC CIM, base and extensions
UML of IEC61850 donated to IEC TC57
Custom extensions of any of these

Was necessary for model cleanup after moving from Rational Rose to Enterprise
Architect in 2008
Likely to be removed soon
jCleanCim configuration



9
jCleanCim
June 2010
Use file
config/config.properties
Minimum configuration for
CIM* validation and stats:
Minimum configuration for
CIM* doc generation:
model
= base-small.eap
validate = true
statistics = true
scope
=
model = base-small.eap
docgen = true
inTemplate = base-small-template.doc
outDocument = base-small.doc
analysePlaceholders = true
* UML of IEC61850 needs more than this, see doc in config.properties file
jCleanCim input files



For any function, you need at least an .eap model file
For MS Word document generation, you also need an MS Word
template (regular .doc file) with particular jCleanCim placeholders
All distributions contain two sets of files in the project’s input directory:
–
–

10
jCleanCim
June 2010
base-small – small subset of base CIM with lots of buggy constructs, on
purpose, to show DON’T’s
noScl-small – small subset of UML of IEC61850 that validates
You should copy your own .eap and .doc files in the project’s input
directory
Recommended UML model structure (1/2)

One root (“Model”)
–

Any number of model packages
under the root
–
–

11
jCleanCim
June 2010
(example from basesmall.eap, does not
reflect the full model,
just small part of it)
Currently, jCleanCim ignores
everything but the first root in the .eap
project
Each with either CIM on NON_CIM
nature
NON_CIM nature must be explicitly
specified in config.properties, with
nonCimNature property
Any number of top-level packages
(per WG owner) under the model
package
–
A top-level package expected to
contain a version class with correct
name
nonCimNature = IEC61850_SCL_mappings, MyNonCimExtensions
Recommended UML model structure (2/2)

Rationale
–
–
Preserves the current standard CIM
“place” in the .eap project
Clearly separates CIM and non-CIM
models

–
Clearly separates standard UML and
non-standard extensions


12
jCleanCim
June 2010
(example from basesmall.eap, does not
reflect the full model,
just small part of it)
–
Nature need not be encoded in UML,
but in properties file
Easy to evolve/update/merge standard
model as it evolves
Easy to independently
evolve/update/merge variations of
custom extensions, without interfering
with the standard UML
Top-level packages may be
associated with IEC TC57 WGs (or to
projects, for custom extensions)
Standard UML top-package owners

WG13
WG16
–

WG10*

(example from basesmall.eap, does not
reflect the full model,
just small part of it)
13
jCleanCim
June 2010
* potentially
Currently, jCleanCim encodes the
mapping of top-level packages and
IEC TC57 owners:
WG13, WG14, WG16, WG10, WG19
All other UML packages and
elements get assigned the owner
“OTHER”
If more flexibility needed, we have to
redesign this in jCleanCim
Functionality
- validation & stats, doc generation -
14
Validation:
Minimum configuration


You must specify the UML model file name
and enable validation
Copy your own model file(s) into the project’s
input directory
model
= base-small.eap
validate = true
15
jCleanCim
June 2010
* UML of IEC61850 needs more than this, see doc in config.properties file
Validation:
Overview (1/2)

Validators for 7 kinds of UML elements
–
–
–
–
–
–
–

Validators deal with:
–
–
–
–
16
jCleanCim
June 2010
Associations
Attributes
Classes
Packages
Diagrams
Dependencies (hand-drawn in UML), and
Operations (for UML of IEC61850 only)
–
Model consistency
CIM UML design rules
Potential model editor errors
Identifying remains from Rose
Illegal/redundant UML constructs (that EA allows…)
Validation:
Overview (2/2)

Each validator is a class
–
–
–

Full list of validators currently implemented is on the next two
slides, with a couple of annotated examples for class validators
–
–
–
17
jCleanCim
June 2010
Inheriting from a common abstract class, and implementing an
interface
Javadoc in package org.iec.tc57.jcleancim.validation provides
guidelines on how to add a validator
It is easy to add a new validator on need!
List is copied from the javadoc of the package
org.iec.tc57.jcleancim.validation
Javadoc also contains UML for all the classes (not shown below)
Some validators apply in general, some apply to CIM models only,
and some to UML of IEC61850 only
Validation:
Associations, attributes and classes
Model
inconsiste
ncies
Remain
s from
Rose
CIM
rules
EA
allows
for this
18
jCleanCim
June 2010
Editor’s
error
Validation:
Dependencies (hand-drawn), diagrams,
operations, packages
UML of
IEC61850
only
19
jCleanCim
June 2010
Validation:
Console logging

Extract from validation log with base-small.eap UML model
–
–

In some future release, we could implement storing this in a csv
file, to enable loading into a spreadsheet and sorting for
analysis
–
20
jCleanCim
June 2010
ERROR 2 classes with <diagnosis>
Next 2 lines identify classes with error/warning and details of
error/warning
Or, if we keep our std CIM UML clean, this may not be necessary!
Validation:
Fine tuning

If you leave scope property empty,
the full content of the UML will be
validated
–
–
–

Sub-options for validation, to select
only kind of UML element to validate
–
21
jCleanCim
June 2010
To validate only some top level
packages (per IEC WG), specify them
in a comma-separated list
Example is for validating IEC61970
and IEC61968, everything else does
not get validated
Recommendation: Before releasing
std model, do full validation, to ensure
nothing has been broken
Example for validating only
associations involving WG13 and
WG14 packages
model
= base-small.eap
validate = true
statistics = true
scope
= WG13, WG14
# ---------------------------# Validation sub-options make sense
# only if validate = true. To disable
# validation for certain UML element
# types, set the ones to ignore to false
# or leave them blank.
# ---------------------------validatePackages =
validateClasses =
validateAssociations = true
validateAttributes =
validateOperations =
validateDependencies =
validateDiagrams =
Statistics:
Minimum configuration


You must specify the UML model file name
and enable statistics
Copy your own model file(s) into the project’s
input directory
model
= base-small.eap
statistics = true
22
jCleanCim
June 2010
* UML of IEC61850 needs more than this, see doc in config.properties file
Statistics:
Overview

Currently, two main kinds of statistics get logged to the console:
–
–
23
jCleanCim
June 2010
On CIM-specific constructs
On actual (direct and derived) dependencies
Statistics:
On CIM-specific constructs

24
jCleanCim
June 2010
Example of CIM-specific constructs from base-small.eap:
Statistics:
On actual dependencies

On actual (direct and derived)
dependencies among top-level packages
(i.e., among WG owners), through:
–
–
–
–
–

Inheritance from IdentifiedObject and
dependency on stereotyped types from
Domain package not shown on purpose:
–
25
jCleanCim
June 2010
Inheritance (e.g., from
PowerSystemResource)
Type of attribute (e.g., usage of
datatypes, enums, primitives,
compounds)
Associations
Hand-drawn package and class
dependencies
Class’ operation parameters and
exceptions (UML of IEC61850 only)
To show them as well, set the two ignore*
properties to false, or leave them empty
ignoreIdObjectInheritance =
ignoreDomainClassAttributes =
Statistics:
TODOs



Filtering per WG not fully implemented
IEC61850-specific statistics not implemented
Note:
–
–
–
26
jCleanCim
June 2010
As previously said, the in-memory representation of the UML from .eap file
contains a lot of analysed information about the model
It all gets logged with DEBUG level (i.e., stored in the log file at each run) – see
examples below for ConnectivityNode, ApparentPower, BasicIntervalSchedule
If needed, better structured presentation can be provided and stored
2010-06-06 14:05:21,984 [main] DEBUG UmlModel - (796) WG13 CIM class Topology::ConnectivityNode, 1
superclasses=[IdentifiedObject], 4 associations; associated classes (bi-directional):
asTarget=[Topology::BusNameMarker, Core::Terminal] asSource=[Core::ConnectivityNodeContainer,
Topology::TopologicalNode]
…
2010-06-06 14:05:21,984 [main] DEBUG UmlModel - (616) WG13 CIM Datatype <<Datatype>>
Domain::ApparentPower, 3 attributes; afferent classes: byAttr=[BasePower];; efferent classes:
byAttr=[Float, UnitMultiplier, UnitSymbol]
…
2010-06-06 14:05:21,984 [main] DEBUG UmlModel - (865) WG13 CIM class Core::BasicIntervalSchedule, 1
superclasses=[IdentifiedObject], 2 subclasses=[IrregularIntervalSchedule, RegularIntervalSchedule], 5
attributes; efferent classes: byAttr=[AbsoluteDateTime, UnitMultiplier, UnitSymbol]
afferent = depends on me
efferent = I depend on
Doc generation:
Minimum configuration



You must specify the UML model file name and enable doc
generation
You must specify also the input (template) and the output
(result) MS Word file names
Copy your own model file(s) and template(s) into the project’s
input directory
model = base-small.eap
docgen = true
inTemplate = base-small-template.doc
outDocument = base-small.doc
analysePlaceholders = true
27
jCleanCim
June 2010
See slide “File and package placeholders”
* UML of IEC61850 needs more than this, see doc in config.properties file
Doc generation:
Overview

The template file is a regular MS Word document (not Word template with
.dot extension)
–
–

When generating documentation, jCleanCim will:
–
–
–

–
jCleanCim
June 2010

Copy your template file into the projects output directory, created
automatically the first time you run the document generation,
Rename the copied file as given in the properties file, and
Fill it with the contents from the EA model.
You can safely run document generation several times with the same
name of the output file, without overwriting existing output files
–
28
You put in that template jCleanCim-recognised placeholders (see next slide)
They control what should be picked from the UML model and printed into MS
Word document
If the output file exists, jCleanCim will rename it by appending a system
nanosecond time
The disadvantage is that you will need to delete those discarded files from the
output directory from time to time, but at least nothing gets lost without your
control
Resulting file is available in the project’s output directory
Doc generation:
Placeholders

The tokens enclosed in curly braces are the names of
UML elements designating what needs to be inserted
in place of the whole placeholder.
startUmlDiagram.{packageName}.{diagramName}.endUml
Inserts diagram
startUmlAttribute.{className}.{attributeName}.endUml
Inserts value of attribute (for version classes)
startUmlFile..endUml
Inserts name of .eap file
startUmlDocPackage.{packageName}.endUml
startUmlDataIndex.{packageName}.endUml
Inserts recursively given package and all of its
sub-packages
(IEC 61850-7-4,-3) Inserts data semantics tables
startUmlSpecialPackage.{packageName}.endUml
(IEC 61850-7-4) Inserts Domain61850 tables
startUmlPackage.{packageName}.endUml
29
jCleanCim
June 2010
(IEC 61970-301) Inserts package doc only
- may be removed in the future
Doc generation:
Attribute and diagram placeholders


30
jCleanCim
June 2010
Placeholder
from template
gets replaced
with some
content
If placeholder is
not recognised
or has typos,
error gets
printed instead
of content
template
result
Doc generation:
File and package placeholders


If problem with the
placeholder for package
(in the heading
paragraph), only error
gets printed instead of
the package content
Doc generation (in
particular for UML
package content,
recursively) takes long
–
–
–
31
jCleanCim
June 2010
To ensure you have
correct placeholders
for packages, set
property
analysePlaceholders=
true
This will skip (time
consuming) printing of
the full content of
packages
After debugging the
template, leave
analysePlaceholders
empty to get the full
content
template
result
Doc generation:
Data index placeholder

Required for IEC61850 documents
–
–

–
jCleanCim
June 2010
If needed, (named) association ends
could be added
For this to work, you must specify the
desired package name (or multiple
comma-separated package names) in
the property packagesWithDataIndex
–
32
From base-small.eap example:
attribute basePower used in classes
BaseVoltage and BasePower
Currently, only attributes
–

template
Prints all usages of a name for
attribute
–

Can be handy for CIM series as well,
and for custom extensions
Can be used for “model debugging”
and consistency check
For this base-small.eap example, we
have set packagesWithDataIndex =
Core
To print this index for base CIM, set
packagesWithDataIndex = IEC61970
result
Doc generation:
Automatically added items (1/2)

Sub-clause
“General”
–

Figure reference
and text, and figure
caption
–
33
jCleanCim
June 2010
To avoid hanging
paragraphs (i.e., text
without containing
clause)
Automatically
numbered,
consistent with
existing figures in
the template
Doc generation:
Automatically added items (2/2)

Table
reference and
text for
attributes and
association
ends
–
34
jCleanCim
June 2010
Automatically
numbered,
consistent
with existing
figures in the
template
Doc generation:
MS Word styles considerations


IEC templates contain IEC-specific styles
For custom extensions, you need not use these
–

Essential:
–
–
–
–
35
jCleanCim
June 2010
jCleanCim tries to use IEC styles, and if those are not defined, it uses default
MS Word styles – see next slide
Use correct styles for paragraphs containing figure and table captions in
the template
jCleanCim must deduce the number of figures and tables already existing in
the template to calculate on the fly the correct numbering for new figures and
tables (when inserting/appending the documentation for the UML model
elements and diagrams)
If jCleanCim throws an exception during document generation, it is very likely
that the MS Word threw exception due to wrong/inexisting/negative number for
the figure or table caption
Note: We cannot check those numbers from within the code, because the MS
Word automation API does not provide reliable access to them. In the worst
case, when we catch an exception from MS Word, we attempt to gracefully
exit, after closing both the MS Word document and the EA model file.
Doc generation:
IEC styles mappings to MS Word defaults

36
jCleanCim
June 2010
Extract from the code:
static {
STYLES.put(Style.para,
STYLES.put(Style.fig,
STYLES.put(Style.figcapt,
STYLES.put(Style.tabcapt,
STYLES.put(Style.tabhead,
STYLES.put(Style.tabcell,
STYLES.put(Style.h1,
STYLES.put(Style.h2,
STYLES.put(Style.h3,
STYLES.put(Style.h4,
STYLES.put(Style.h5,
STYLES.put(Style.h6,
STYLES.put(Style.h7,
STYLES.put(Style.h8,
STYLES.put(Style.h9,
}
IEC styles
new
new
new
new
new
new
new
new
new
new
new
new
new
new
new
StyleInfo("PARAGRAPH",
StyleInfo("Picture",
StyleInfo("FIGURE-title",
StyleInfo("TABLE-title",
StyleInfo("TABLE-col-heading",
StyleInfo("TABLE-cell",
StyleInfo("Heading 1",
StyleInfo("Heading 2",
StyleInfo("Heading 3",
StyleInfo("Heading 4",
StyleInfo("Heading 5",
StyleInfo("Heading 6",
StyleInfo("Heading 7",
StyleInfo("Heading 8",
StyleInfo("Heading 9",
MS Word defaults
wdStyleNormal));
wdStyleNormal));
wdStyleCaption));
wdStyleCaption));
wdStyleNormalTable));
wdStyleNormalTable));
wdStyleHeading1));
wdStyleHeading2));
wdStyleHeading3));
wdStyleHeading4));
wdStyleHeading5));
wdStyleHeading6));
wdStyleHeading7));
wdStyleHeading8));
wdStyleHeading9));
Doc generation:
Misc

For IEC61850 document generation, more properties
need to be set
–

See comments in config.properties file
jCleanCim doc generation design
–
The UML packages content to be printed in MS Word actually
gets calculated and stored in in-memory objects before
interacting with MS Word, on purpose


–
37
jCleanCim
June 2010
This processing is very fast
Except for diagram printing (from clipboard, through EA API), this
is also detached from the .eap file
If needed, it would be relatively easy and fast to implement
writing to another format (instead of MS Word)
Instead of conclusion
38
Time considerations

Each function ends with time elapsed logged to the
console
[main] INFO built model(s) 'IEC61970_IEC61968_combined CIM, IEC61850_SCL_mappings
NON_CIM, MyCimExtensions CIM, MyNonCimExtensions NON_CIM' in 0:00:11.


Java APIs to COM (for Enterprise Architect and for MS
Word) are terribly slow
On ThinkPad T60p:
–
Full standard CIM UML building (from .eap) takes ~2 min

–
–
39
jCleanCim
June 2010

With UML of IEC61850 and mappings to CIM: ~4 min
Doc generation of DCIM (IEC61968, ~100 classes and ~20
additional figures) takes ~20 min
Java processing for validation and stats is below 1sec for
each, despite fully enabled logging
So, plan your coffee and lunch breaks 
Known issues

Related to doc generation only – due to troubles with
MS Word automation API
–
With some IEC templates, automatic update of tables of
contents/tables/figures does not work properly

–
Word pop-up window "memory insufficient. Do you want to
continue?“

–
40
jCleanCim
June 2010
Workaround: Before doc generation, in the input template, disable
spell checking and change tracking
Exceptions when using localised versions of MS Word, due to
style names


Workaround: After doc generation, do manual update of all TOCs
Workaround: Define IEC document styles, or at least regular
English styles Normal and Caption
If acceptable by IEC, we may want to try docbook for
editing (http://www.docbook.org/)
Success stories

We have successfully generated:
–
–
41
jCleanCim
June 2010
IEC 61970-301 Ed.4 (base CIM14), and
IEC 61968-11 Ed.1 (DCIM10)
Want more features?


jCleanCim is being developed on volunteering basis
Consequently:
–
The policy is to first support the immediate needs of official IEC
TC57 UML models’ editors, for their tasks of UML model
management:


–
This includes:



42
jCleanCim
June 2010
For the IEC process, and,
For the user community.
Bug fixes
New features that are easy to add (e.g., new validators, improved
logging, better validation filtering and such)
If you want more advanced features (like GUI):
–
Get involved – any help is welcome !
Credits

Lars-Ola Osterlund (ABB, Sweden) encouraged development of
documentation generation for IEC 61850 UML model donated to IEC
TC 57, to illustrate at least one benefit of using UML in WG10.

Kendall Demaree (Areva, US), while being CIM model manager in
2008, developed open source CIMinEA application that helped us
move standard CIM from Rational Rose to Enterprise Architect, and
which allowed document generation for IEC 61970-301, Ed. 3. That
work inspired some of the functionality related to document generation
in jCleanCim. Kendall has also been the first known user of jCleanCim
and actively provided feedback on features. He indeed encouraged the
move from CIMinEA to jCleanCim for doc generation, since:
–
–
43
jCleanCim
June 2010
jCleanCim also has validation and statistics functions, and
jCleanCim is written in Java (CIM community, including developers, could
thus easier contribute to further development and maintenance of
jCleanCim).