j Clean Cim introduction June 2010 1 tatjana

j. Clean. Cim introduction June 2010 1 tatjana. kostic@ch. abb. com

What is j. Clean. Cim and where to find it? l What: – j. Clean. Cim is an open source tool l – – 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: l l – l 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%20 Documents/Forms/All. Items. aspx 2 j. Clean. Cim June 2010 * And also IEC 61850 UML model that ABB donated to IEC TC 57 in October 2009

j. Clean. Cim directory @ CIMug Use latest version 3 j. Clean. Cim June 2010

Who should use j. Clean. Cim and when? l Who: – Primarily those who edit CIM UML and publish its documentation, thus: l l l When: – If you are already a user of the excellent CIMTool, you may wonder where within the process of CIM development and maintenance the j. Clean. Cim fits: l l 4 j. Clean. Cim 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 j. Clean. Cim 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 l l Start from readme. html available at the Share. Point Once you unzip a j. Clean. Cim distribution (or import the eclipse-dependent one as eclipse project), full documentation is available: – – – 5 j. Clean. Cim 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 l -bin – l -eclipse – l j. Clean. Cim June 2010 For j. Clean. Cim developer, packager and user, with eclipse IDE -src – 6 For j. Clean. Cim user For j. Clean. Cim developer, packager and user, with Apache ant

Note for CIMTool users l l CIMTool is an eclipse-based application with a GUI, while j. Clean. Cim only uses eclipse for development and building (it is a simple console application, without GUI) The most comfortable way to use j. Clean. Cim is however with –eclipse. zip distribution, because: – – l l 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 j. Clean. Cim June 2010 You click to run j. Clean. Cim 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 j. Clean. Cim 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)

j. Clean. Cim functions l l l j. Clean. Cim 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 l l l – – – 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 l 8 j. Clean. Cim June 2010 UML of standard IEC CIM, base and extensions UML of IEC 61850 donated to IEC TC 57 Custom extensions of any of these l Was necessary for model cleanup after moving from Rational Rose to Enterprise Architect in 2008 Likely to be removed soon

j. Clean. Cim configuration l l l 9 j. Clean. Cim 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 in. Template = base-small-template. doc out. Document = base-small. doc analyse. Placeholders = true * UML of IEC 61850 needs more than this, see doc in config. properties file

j. Clean. Cim input files l l l 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 j. Clean. Cim placeholders All distributions contain two sets of files in the project’s input directory: – – l 10 j. Clean. Cim June 2010 base-small – small subset of base CIM with lots of buggy constructs, on purpose, to show DON’T’s no. Scl-small – small subset of UML of IEC 61850 that validates You should copy your own. eap and. doc files in the project’s input directory

Recommended UML model structure (1/2) l One root (“Model”) – l Any number of model packages under the root – – l 11 j. Clean. Cim June 2010 (example from basesmall. eap, does not reflect the full model, just small part of it) Currently, j. Clean. Cim ignores everything but the first root in the. eap project Each with either CIM on NON_CIM nature must be explicitly specified in config. properties, with non. Cim. Nature 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 non. Cim. Nature = IEC 61850_SCL_mappings, My. Non. Cim. Extensions

Recommended UML model structure (2/2) l Rationale – – Preserves the current standard CIM “place” in the. eap project Clearly separates CIM and non-CIM models l – Clearly separates standard UML and non-standard extensions l l 12 j. Clean. Cim 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 TC 57 WGs (or to projects, for custom extensions)

Standard UML top-package owners l WG 13 WG 16 – l WG 10* l (example from basesmall. eap, does not reflect the full model, just small part of it) 13 j. Clean. Cim June 2010 * potentially Currently, j. Clean. Cim encodes the mapping of top-level packages and IEC TC 57 owners: WG 13, WG 14, WG 16, WG 10, WG 19 All other UML packages and elements get assigned the owner “OTHER” If more flexibility needed, we have to redesign this in j. Clean. Cim

Functionality - validation & stats, doc generation - 14

Validation: Minimum configuration l l 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 j. Clean. Cim June 2010 * UML of IEC 61850 needs more than this, see doc in config. properties file

Validation: Overview (1/2) l Validators for 7 kinds of UML elements – – – – l Validators deal with: – – 16 j. Clean. Cim June 2010 Associations Attributes Classes Packages Diagrams Dependencies (hand-drawn in UML), and Operations (for UML of IEC 61850 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) l Each validator is a class – – – l Full list of validators currently implemented is on the next two slides, with a couple of annotated examples for class validators – – – 17 j. Clean. Cim June 2010 Inheriting from a common abstract class, and implementing an interface Javadoc in package org. iec. tc 57. 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. tc 57. 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 IEC 61850 only

Validation: Associations, attributes and classes Model inconsiste ncies Remain s from Rose CIM rules EA allows for this 18 j. Clean. Cim June 2010 Editor’s error

Validation: Dependencies (hand-drawn), diagrams, operations, packages UML of IEC 61850 only 19 j. Clean. Cim June 2010

Validation: Console logging l Extract from validation log with base-small. eap UML model – – l In some future release, we could implement storing this in a csv file, to enable loading into a spreadsheet and sorting for analysis – 20 j. Clean. Cim 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 l If you leave scope property empty, the full content of the UML will be validated – – – l Sub-options for validation, to select only kind of UML element to validate – 21 j. Clean. Cim June 2010 To validate only some top level packages (per IEC WG), specify them in a comma-separated list Example is for validating IEC 61970 and IEC 61968, 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 WG 13 and WG 14 packages model = base-small. eap validate = true statistics = true scope = WG 13, WG 14 # --------------# 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. # --------------validate. Packages = validate. Classes = validate. Associations = true validate. Attributes = validate. Operations = validate. Dependencies = validate. Diagrams =

Statistics: Minimum configuration l l 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 j. Clean. Cim June 2010 * UML of IEC 61850 needs more than this, see doc in config. properties file

Statistics: Overview l Currently, two main kinds of statistics get logged to the console: – – 23 j. Clean. Cim June 2010 On CIM-specific constructs On actual (direct and derived) dependencies

Statistics: On CIM-specific constructs l 24 j. Clean. Cim June 2010 Example of CIM-specific constructs from base-small. eap:

Statistics: On actual dependencies l On actual (direct and derived) dependencies among top-level packages (i. e. , among WG owners), through: – – – l Inheritance from Identified. Object and dependency on stereotyped types from Domain package not shown on purpose: – 25 j. Clean. Cim June 2010 Inheritance (e. g. , from Power. System. Resource) 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 IEC 61850 only) To show them as well, set the two ignore* properties to false, or leave them empty ignore. Id. Object. Inheritance = ignore. Domain. Class. Attributes =

Statistics: TODOs l l l Filtering per WG not fully implemented IEC 61850 -specific statistics not implemented Note: – – – 26 j. Clean. Cim 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 Connectivity. Node, Apparent. Power, Basic. Interval. Schedule If needed, better structured presentation can be provided and stored 2010 -06 -06 14: 05: 21, 984 [main] DEBUG Uml. Model - (796) WG 13 CIM class Topology: : Connectivity. Node, 1 superclasses=[Identified. Object], 4 associations; associated classes (bi-directional): as. Target=[Topology: : Bus. Name. Marker, Core: : Terminal] as. Source=[Core: : Connectivity. Node. Container, Topology: : Topological. Node] … 2010 -06 -06 14: 05: 21, 984 [main] DEBUG Uml. Model - (616) WG 13 CIM Datatype <<Datatype>> Domain: : Apparent. Power, 3 attributes; afferent classes: by. Attr=[Base. Power]; ; efferent classes: by. Attr=[Float, Unit. Multiplier, Unit. Symbol] … 2010 -06 -06 14: 05: 21, 984 [main] DEBUG Uml. Model - (865) WG 13 CIM class Core: : Basic. Interval. Schedule, 1 superclasses=[Identified. Object], 2 subclasses=[Irregular. Interval. Schedule, Regular. Interval. Schedule], 5 attributes; efferent classes: by. Attr=[Absolute. Date. Time, Unit. Multiplier, Unit. Symbol] afferent = depends on me efferent = I depend on

Doc generation: Minimum configuration l l l 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 in. Template = base-small-template. doc out. Document = base-small. doc 27 j. Clean. Cim June 2010 analyse. Placeholders = true See slide “File and package placeholders” * UML of IEC 61850 needs more than this, see doc in config. properties file

Doc generation: Overview l The template file is a regular MS Word document (not Word template with. dot extension) – – l When generating documentation, j. Clean. Cim will: – – – l – j. Clean. Cim June 2010 l 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 j. Clean. Cim-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, j. Clean. Cim 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 l 29 j. Clean. Cim June 2010 The tokens enclosed in curly braces are the names of UML elements designating what needs to be inserted in place of the whole placeholder. start. Uml. Diagram. {package. Name}. {diagram. Name}. end. Uml Inserts diagram start. Uml. Attribute. {class. Name}. {attribute. Name}. end. Uml Inserts value of attribute (for version classes) start. Uml. File. . end. Uml Inserts name of. eap file start. Uml. Doc. Package. {package. Name}. end. Uml (IEC 61970 -301) Inserts package doc only - may be removed in the future start. Uml. Package. {package. Name}. end. Uml start. Uml. Data. Index. {package. Name}. end. Uml Inserts recursively given package and all of its sub-packages (IEC 61850 -7 -4, -3) Inserts data semantics tables start. Uml. Special. Package. {package. Name}. end. Uml (IEC 61850 -7 -4) Inserts Domain 61850 tables

Doc generation: Attribute and diagram placeholders l l 30 j. Clean. Cim 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 l l 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 j. Clean. Cim June 2010 To ensure you have correct placeholders for packages, set property analyse. Placeholders= true This will skip (time consuming) printing of the full content of packages After debugging the template, leave analyse. Placeholders empty to get the full content template result

Doc generation: Data index placeholder l Required for IEC 61850 documents – – l Prints all usages of a name for attribute – l – j. Clean. Cim 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 packages. With. Data. Index – 32 From base-small. eap example: attribute base. Power used in classes Base. Voltage and Base. Power Currently, only attributes – l 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 packages. With. Data. Index = Core To print this index for base CIM, set packages. With. Data. Index = IEC 61970 template result

Doc generation: Automatically added items (1/2) l Sub-clause “General” – l Figure reference and text, and figure caption – 33 j. Clean. Cim 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) l Table reference and text for attributes and association ends – 34 j. Clean. Cim June 2010 Automatically numbered, consistent with existing figures in the template

Doc generation: MS Word styles considerations l l IEC templates contain IEC-specific styles For custom extensions, you need not use these – l Essential: – – 35 j. Clean. Cim June 2010 j. Clean. Cim 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 j. Clean. Cim 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 j. Clean. Cim 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 l 36 j. Clean. Cim June 2010 Extract from the code: static { STYLES. put(Style. para, STYLES. put(Style. figcapt, STYLES. put(Style. tabhead, STYLES. put(Style. tabcell, STYLES. put(Style. h 1, STYLES. put(Style. h 2, STYLES. put(Style. h 3, STYLES. put(Style. h 4, STYLES. put(Style. h 5, STYLES. put(Style. h 6, STYLES. put(Style. h 7, STYLES. put(Style. h 8, STYLES. put(Style. h 9, } IEC styles new new new new Style. Info("PARAGRAPH", Style. Info("Picture", Style. Info("FIGURE-title", Style. Info("TABLE-col-heading ", Style. Info("TABLE-cell", Style. Info("Heading 1", Style. Info("Heading 2", Style. Info("Heading 3", Style. Info("Heading 4", Style. Info("Heading 5", Style. Info("Heading 6", Style. Info("Heading 7", Style. Info("Heading 8", Style. Info("Heading 9", MS Word defaults wd. Style. Normal)); wd. Style. Caption)); wd. Style. Normal. Table)); wd. Style. Heading 1)); wd. Style. Heading 2)); wd. Style. Heading 3)); wd. Style. Heading 4)); wd. Style. Heading 5)); wd. Style. Heading 6)); wd. Style. Heading 7)); wd. Style. Heading 8)); wd. Style. Heading 9));

Doc generation: Misc l For IEC 61850 document generation, more properties need to be set – l See comments in config. properties file j. Clean. Cim 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 l l 37 j. Clean. Cim 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 l Each function ends with time elapsed logged to the console [main] INFO built model(s) 'IEC 61970_IEC 61968_combined CIM, IEC 61850_SCL_mappings NON_CIM, My. Cim. Extensions CIM, My. Non. Cim. Extensions NON_CIM' in 0: 00: 11. l l Java APIs to COM (for Enterprise Architect and for MS Word) are terribly slow On Think. Pad T 60 p: – Full standard CIM UML building (from. eap) takes ~2 min l – – 39 j. Clean. Cim June 2010 l With UML of IEC 61850 and mappings to CIM: ~4 min Doc generation of DCIM (IEC 61968, ~100 classes and ~20 additional figures) takes ~20 min Java processing for validation and stats is below 1 sec for each, despite fully enabled logging So, plan your coffee and lunch breaks

Known issues l 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 l – Word pop-up window "memory insufficient. Do you want to continue? “ l – 40 j. Clean. Cim 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 l l 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 l We have successfully generated: – – 41 j. Clean. Cim June 2010 IEC 61970 -301 Ed. 4 (base CIM 14), and IEC 61968 -11 Ed. 1 (DCIM 10)

Want more features? l l j. Clean. Cim is being developed on volunteering basis Consequently: – The policy is to first support the immediate needs of official IEC TC 57 UML models’ editors, for their tasks of UML model management: l l – This includes: l l 42 j. Clean. Cim June 2010 l 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 l 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 WG 10. l Kendall Demaree (Areva, US), while being CIM model manager in 2008, developed open source CIMin. EA 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 j. Clean. Cim. Kendall has also been the first known user of j. Clean. Cim and actively provided feedback on features. He indeed encouraged the move from CIMin. EA to j. Clean. Cim for doc generation, since: – – 43 j. Clean. Cim June 2010 j. Clean. Cim also has validation and statistics functions, and j. Clean. Cim is written in Java (CIM community, including developers, could thus easier contribute to further development and maintenance of j. Clean. Cim).