Using CIMTool - UCAIugcimug.ucaiug.org/Meetings/Milan2010/Presentations... · Instances: for CIM XML instance files in RDF format with a .xml extension ... the UML model Schemas must

Systems Integration Specialists Company, Inc.

The Standards Based IntegrationCompany

© Copyright 2008 SISCO, Inc.

Using CIMTool

Margaret Goodrich, Manager, Systems EngineeringSISCO, Inc.6605 19½ Mile RoadSterling Heights, MI 48314 USATel: +1-903-477-7176Fax: +1-903-489-0063E-Mail: [email protected]

© Copyright 2008 SISCO, Inc.2

Introduction

The purpose of this presentation is to describe the useof CIMTool

Some of the uses of CIMTool include:

Definition of information exchange profiles – messages orfiles

Development of XSD Schemas

Development of RDF Schemas

Validation of full CIM XML instance files

Validation of incremental CIM XML files


Contents

1. CIMTool Installation2. Creating a CIMTool Project3. Importing a Schema4. Creating and Editing a Profile5. Importing a Profile (Several Methods)6. Generating XSD Schemas7. Generating RDF Schemas8. Importing a Model9. Validating a Model10. Importing and Validating an Incremental Model11. Updating a Schema12. Miscellaneous


CIMTool Installation


What is CIMTool?

CIMTool is an Eclipse plugin It provides the means to:

Define profiles from a UML model

Import profiles from a spreadsheet

Validate profiles

Validate instance files against a profile

Validate incremental files against an instance file and a profile

Generate XSD schemas from a profile

Generate RDF schemas from a profile

… and more


Preparation for Installation

You should have a PC running a recent version ofWindows, Linux or Mac OS, with at least 1GB memory

Recommend at least 2GB free disk space (much moreis recommended if you will be working with large CIMnetwork models)

You need an internet connection, noting that there maybe 200MB of downloads required for installation

You need a Java runtime environment (JRE)

Java 5 JRE is currently recommended

If you don’t have one you can download from http://java.com

http://java.com/


CIMTool Installation

Go to http://cimtool.org

Version 1.8.5 is currently available for download

Download a zip file with Eclipse and CIMTool (fullinstallation package)

Following the directions on the screen

http://cimtool.org/


Starting CIMTool

Click on the Eclipse icon The Eclipse startup dialog will

appear Define a ‘workspace’ directory

when prompted The workbench view will then

appear


Eclipse/CIMTool Workbench

Initial default viewbefore anyprojects arecreated

Default installationsupports Javadevelopment


CIMTool/Eclipse Hints and Tips

Files, Packages and Workspaces:

It is important that you never add, modify or delete anything insidea workspace directory with tools other than Eclipse

If there is ever a ‘resource out of sync’ problem, you can usuallycorrect by using the ‘refresh’ option

Other problems may be corrected using the Project>Clean option

You may however safely read files directly from the workspacefolder if needed


Creating a CIMTool Project


CIMTool Projects

Each project has a named folder in the workspace directory Each CIMTool project will have four sub-folders:

Incremental: for CIM XML incremental files in RDF format with a .xmlextension

Instances: for CIM XML instance files in RDF format with a .xmlextension

Profiles: for profile definitions, where

Profile definitions are stored in an XSD, OWL & RDFS formats

Log files, which may identify errors, are text files with a .log extension

Depending upon the usage of CIMTool, there may also be HTML, XML andXSD files

Schema: for the CIM model in XMI format with a .xmi extension(Generated using the UML model from the EA Tool)

Folders and files that have errors may include a red X on theirassociated icon


Creating a New CIMTool Project

Select ‘File> New >Project’

Select‘CIMToolProject’option

Click ‘Next’


Creating a New CIMTool Project

Name it –e.g. ‘AEP--’

Click ‘Finish’ This will

create anew folderin yourworkspacedirectory


Browsing the Project

Click on arrowto the left ofthe desiredproject namein the ProjectExplorer toexpand it

See thatproject hasthe 4 set offolders

Expand sub-folders to seecontents


Importing a Schema


Importing a Schema

Schemas describe the classes, attributes andrelationships defined by a UML model

Anything defined by a profile MUST be described withinthe UML model

Schemas must be in a suitable XMI format for import The XMI files are typically generated from the CIM UML

model created/maintained using Enterprise Architect Schemas will be stored in the ‘Schema’ folder of the

project There is typically one schema for a project, although

there are cases where there may be more than one


Schema in a UML Tool

18


Exporting UML Model as XMI

In EnterpriseArchitectselect thetop-levelpackage

SelectProject >Import/Export> ExportPackage toXMI


Exporting XMI from UML Tool

Use exportoptions shown

Export asUML 1.4

Unselect‘Enable fullEA Roundtrip’

Select‘Unisys/Roseformat’ option

Enter filename for XMIfile

Click onExport button


Schema Import within CIMTool

Schemas are imported when creating a new CIMToolproject

Schemas can also be added to supplement an existingschema

Schemas can also replace an existing schema, as inthe case of a new CIM version


Initial Schema Import

1. Select ‘File > Import’2. Note the different import options under

CIMTool3. Select ‘Import Schema’ option4. Click ‘Next’


Initial Schema Import

Browse to findthe XMI file toimport

Check theproject for theimport

Don’t edit theNamespace

Click “Finish”


Creating and Editing a Profile


Creating a New Profile

There are four ways to create a new profile:

1. Create it from scratch within CIMTool

2. Import an OWL profile previously constructed using CIMTool

3. Import the profile from a data dictionary spreadsheet

4. Copy and paste an existing profile within CIMTool

Once created, profiles are stored in the ‘Profiles’ folder ofthe project

A project may have many profiles Each profile will have a namespace This following slides describe the creation of a new profile

using the edit capabilities within CIMTool



1. Select‘File >New >Other…’



1. Select‘CIMToolProfile’option

2. Click‘Next’



Click on checkbox forthe desired project

Determine a uniquename for the profile thatwill not conflict withother profile names,then using the name:

Set the profile name

Set namespace URI

Set envelope elementname

Click ‘Finish’


Browsing the Project

Click on arrows inProject Explorerto expand folders

Double click onthe .owl profile filename in the toopen it

Click on theprofile name inthe Outlinewindow

In the ProjectExplorer frameyou can alwaysright click on a filename to seeoptions


Adding Classes to Profile

Browsethroughmodel on theright side ofAdd/Removetab

Select one ormore classeson right sideAdd/removetab

Classes aremoved byclicking on <


Adding a Property (Attribute) to Profile

Click on aclass in theOutline

Properties areshown on theright side of theProfileAdd/Removetab

Click onproperty nameon right side

Click on ‘<‘ tomove propertyto left side


View After Adding a Property to profile

New profileproperty isseen onOutline viewand the leftside of theAdd/Removetab

You canremoveproperties byusing the >button


Adding Properties to Profile

Can movemore thanoneproperty ata time


Importing a Profile


Importing a Profile

Sometimes it is desirable to use another profiledefinition as a starting point for a profile definition

CIMTool saves profile definitions in an OWL format Profile definitions from another project or

workspace can be imported to create new profiles


Importing Profiles into CIMTool

Select ‘File > Import’ Note the different import

options under CIMTool On ‘Import’ dialog select

‘CIMTool – Import Profile’option

Check the project to importinto

Browse to find the file toimport

Click ‘Next’


Importing Profile from DataDictionary


Importing Profiles

Some products can generate a Data Dictionary in theform of an Excel spreadsheet

The spreadsheet can define one or more profiles Note that the spreadsheet can be maintained

independently of any particular product The Data Dictionary defines the classes, attributes and

relationships that comprise one or more profiles This can be imported into CIMTool to define a profile


Data Dictionary

An Excelspreadsheetthat describesthe contents ofone or moreprofiles

Tabs exist forClasses,Attributes,Associations,Data types,Enumerationsand Units


Importing Spreadsheet

Can importthe DataDictionaryspreadsheetas a profile

File>Import Select ‘Import

Spreadsheetas Profile’option



Thespreadsheetmay identifyone or moreprofiles

Can selectwhich profilesto construct

Can onlyconstruct oneat a time



Need toidentify theproject inwhich theprofile will becreated

The name ofthe profile isset by default,but can bemodified



New profile(.owl file) iscreated ifthere are nofatal errors

A log file iscreated thatidentifies anyerrors



A log file (.log)is generatedwith the profileto identifyerrors, if any

The log fileidentifies whatcould not befound forinclusion intothe profiledefinition


Extending the Spreadsheet

You can also create a new profile definition in thespreadsheet for import into CIMTool using the followingsteps:

1. Insert new profile columns into the ‘Classes’, ‘Attributes’ and‘Associations’ tabs

2. Provide the same profile name on row one of each of the addedcolumns

3. Set the value of each new cell to ‘TRUE’ or ‘FALSE’4. Run the spreadsheet import process as described previously5. Look for errors in the log file


Creating a Profile using theCopy/Paste Function


Create a Profile Using Copy/Paste

Select the Profile you wish to copy Right click on the .Owl file and select ‘Copy’ Right click again and select ‘Paste’ Enter the name of the new Profile to be created in the

Dialog The set of Profile files will be generated Right click on the new .Owl file and select Properties Enter the new Profile namespace in the dialog This method will be demonstrated after the

presentation


Generating RDF Schemas



Load thedesired profile

Select the‘Summary’ tab



Check ‘Builderfor legacy-rdfs’

Check anyother desiredbuilder options

Click on‘File>Save’


Generated RDF Schema

To view theactual RDFS,right click filename in ProjectExplorer

Then select‘Open With >Text Editor’option


XML Schema Design


XML Schema Options

XML Schemas are key to message-based integration IEC 61968 leverages the CIM for message-based

integration Given a profile definition, there are a variety of options that

may be used to control the generation of an XML Schema:

Envelope name for the profile

Definition of ‘concrete’ classes (to generate an XML element)

Restrictions on cardinalities

Associations implemented either ‘by value’ or ‘by reference’

Also can create a stylesheet to customize the format ofgenerated XSDs


Associations

Associations may be realized either nested inline‘by value’, or ‘by reference’

Default is ‘by value’ A check box is used to select ‘by reference’ option

on the Add/Remove tab In the ‘by reference’ case a ‘ref’ attribute is

generated to point to an instance elsewhere in theXML

Typically an mRID value should be used for thevalue of the ‘ref’ attribute


Associations ‘By Reference’

ReadingType isused within thedefinitionReading

Arrow shows thatit will be realized‘by reference’

ReadingTypeinstances areinstantiatedelesewhere inthe profiledefinition


Selecting XSD Generation

XSDgenerationmust beselected onthe Summarytab for theprofile

Other optionssuch asHTMLgenerationmay beselectedconcurrently


Generating XSD Schemas



Load thedesired profile

Select the‘Summary’ tab



Check ‘Builderfor XSD’

Check anyother desiredbuilder options

Click on‘File>Save’


Generated XSD Schema

To view theactual XSDSchema, rightclick file namein ProjectExplorer

Then select‘Open With >Text Editor’option


CIMTool Output Options

CIMTool can generate several ‘styles’ of outputs for profile definitions,including:

XSD

SQL

XML

HTML

CIMTool can generate several ‘styles’ of RDF or OWL as outputs forprofile definitions, including:

Legacy RDFS (currently the most commonly used)

Legacy nested RDFS

Simple OWL

Simple nested OWL

CIMTool can also generate Java Both the form of XSDs and HTML generated can be controlled by

stylesheets


HTML Documentation

HTML optiongenerates a singleHTML file withdescription of allclasses

Hyperlinks allownavigation betweenclass descriptions andtype definitions

Free tools exist forHTML to Wordconversion


Importing a Model


Importing a Model

In order to validate a model, it must first be imported Model files to be imported are in a CIM/XML RDF

format with a .xml extension Model files can be very large, as much as 2GB in size The import process can take many minutes The resulting model is placed in the ‘Instances’ folder

of the project


Importing a Model

Select ‘File > Import’ On ‘Import’ dialog select

‘Import Model (CIM/XMLfile)’ option

Click ‘Next’ Check the project to import

into Browse to find the file to

import Select an appropriate

profile Click ‘Next’

OR

Select the Model ImportICON on the toolbar andcomplete the screen shown


Importing a Model That Already Exists

Change the file name ifyou wish to save to adifferent sub folder

Check ‘Replace existingmodel’ if you wish tooverwrite

Click ‘Finish’ Wait for the import to

complete, as it may takeseveral minutes (up toan hour for a very largemodel)

Watch the progress iconat the bottom of CIMToolwhere it says ‘Importingmodel …’


Imported Model

The imported RDF model is stored within the Instancesfolder of the project

Errors are recorded in log files A folder is created to store the model in typically many

smaller files that have a .ttl extension The .ttl files are in Terse RDF Triple Language format

(more compact than CIM XML)


Validating a Model


Validating a Model

Validation of the model occurs when a model isimported

Errors are identified in log files in the ‘Instances’ folderof the project with a name in the form <profile>.log

If errors exist, a diagnostic file is created which can bebrowsed

CIMTool has a default set of validation rules, wherethe rule file is named <profile>.split-rules

Rules can be edited and extended


Example Validation Errors

Undefined classes Undefined properties Instantiation of abstract classes Illegal cardinality on an association (e.g. more or less

associations than expected) Range violation for a data item Illegal domain of a property Base voltages for conducting equipment connected at a

connectivity node do not agree Isolated nodes Untyped objects Missing or extra terminal Duplicate properties Unexpected loop


Browsing Diagnostic File

71


Importing and Validating anIncremental Model


Importing Incremental CIM/XML

First step is toimport anincrementalCIM/XML fileusing File >Import andselectCIMTool/ImportIncrementalCIM/XML file(or use theToolBar ICON)


Importing Incremental CIM/XML

Must haveimported a baseinstance modelBEFOREattempting this

Need to browseto select file

Need to selectthe appropriatebase model

Errors will bereported in a logfile


Validating an Incremental Model

Validation occurs when the model is imported Errors are identified in log files in the ‘Incremental’

folder of the project with a name in the form<profile>.log

If errors exist, a diagnostic file is created which can bebrowsed


Browsing Diagnostic File


Updating a Schema


Updating a Schema in CIMTool

From time to time, there may be updates to the UMLmodel. These updates will result in a revised XMI file

You should not directly replace a file in the CIMToolworkspace directory

You should instead, using CIMTool File menu options:

1. Delete the old schema

2. Import the new schema

Be sure that the correct namespace is entered Profiles with errors will be flagged with a red X

78


Namespaces

A commonly used namespace ishttp://iec.ch/TC57/CIM-generic#

If namespaces do not match between schema, profilesand the model files errors may be encountered

Default namespaces to be used by CIMTool can bechanged using Window > Preferences and selectingCIMTool option

Most problems encountered in CIMTool surround thenamespace.

It is best to use the default (defined above) for allproject files

79

http://iec.ch/TC57/CIM-generic


Changing Namespaces

Namespaces can bechanged by rightclicking on a filename in the ProjectExplorer and thenselecting ‘properties’

The namespace isshown on theCIMTool propertydialog

Namespaces can bechanged as desired

Note that this mayimpact existingprofile definitions


Miscellaneous


Exporting a Project

It is oftennecessary toexport a projectfor use byothers, or touse on othercomputers

Use File >Export

Select ArchiveFile option

Select Next


Exporting a Project

Need toselect outputformat, ZIP isusually best

Need toselect outputfile name

Project canbe laterimportedback intoEclipse usingFile > Import


Switching Workspaces

Sometimes it isnecessary tomove or changethe location ofyour workspacefolder, or usemultipleworkspaces

To point Eclipseto the newworkspace folderuse File > SwitchWorkspace

Select the desiredworkspace folder

The settings willbe updated andEclipse will restart


Renaming Resources

Sometimes it is necessary to rename projects, folderswithin a project or files within a folder

It is important to do this using Eclipse, instead ofdirectly making changes to the resource outside ofEclipse

To rename, right click on the desired resource in theProject Explorer and select ‘Rename’

Now you can change the name of the resource


Changing CIMTool Preferences

Preferencescan bechanged usingWindow >Preferencesand selectingCIMTool option

Select ‘Apply’and ‘OK’ afterediting to save


Diagnostics

Errors will be written to ‘.diagnostic’ files These are often the consequence of changes in the CIM that

have eliminated used classes, relationships or attributes Profiles can then be edited to correct the problems


Backing Up a Project

Easy way …

Easiest way to back up a project directory is to use WinZip ora similar archive tool

Using WinZip (or similar tool), simply create an archive file ofthe project folder within the workspace

Using a source repository …

Many commercial source repositories options exist thatintegrate with Eclipse

Plugins can be found for:

CVS

Visual Source Safe

Clear Case


Importing a Project

Select File >Import > Toimport projectsinto Workspace

Click Next Browse to

identify a projectdirectory

Can use ‘Copyprojects intoworkspace’ tomake a copy ofthe directoryinstead ofworking directlyout of the chosendirectory


Deleting a Project

Right clickon name ofproject inthe ProjectExplorer

Files willonly bedeleted ifthe ‘Alsodeletecontentsunder …’option isselected

Click ‘Yes’


CIMTool Updates

TO obtainupdates toEclipse andCIMTool

Use Help >SoftwareUpdates >CIMTool

Select ‘Searchfor NewFeatures toInstall’ option


Where Do I Get …

CIMTool and Eclipse:

http://eclipse.org

http://cimtool.org

CIM:

http://www.ucaiug.org/CIMug

IEC Standards:

http://www.iec.ch

http://eclipse.org/

http://cimtool.org/

http://www.ucaiug.org/CIMug

http://www.iec.ch/


Acknowledgements

Not possible without the efforts of Arnold DeVos,the developer of CIMTool

Thanks to those companies that also helped tofund CIMTool development

Thanks to the CIM model managers that havehelped to advance the CIM:

Kurt Hunter, Siemens (WG13)

Kendall Demaree, Areva (WG13)

Lars-Ola Osterlund, ABB (WG13)

Tatjana Kostic, ABB (WG14)

Margaret Goodrich, SISCO (WG16)


More Information

Eclipse web site: http://eclipse.org CIMTool web site: http://cimtool.org E-mail: [email protected]

Screen Shots Compliments of UISOL and ScottNeumann

http://eclipse.org/

http://cimtool.org/

Documents

Using CIMTool - UCAIugcimug.ucaiug.org/Meetings/Milan2010/Presentations... · Instances: for CIM XML instance files in RDF format with a .xml extension ... the UML model Schemas must