diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml deleted file mode 100644 index 4a36c25..0000000 --- a/.github/workflows/ci.yml +++ /dev/null @@ -1,15 +0,0 @@ -name: ci -on: - push: - branches: - - master -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-python@v2 - with: - python-version: 3.x - - run: pip install mkdocs-material - - run: mkdocs gh-deploy --force \ No newline at end of file diff --git a/.github/workflows/generate-pdf.yml b/.github/workflows/generate-pdf.yml index 78d5f39..2281347 100644 --- a/.github/workflows/generate-pdf.yml +++ b/.github/workflows/generate-pdf.yml @@ -1,32 +1,23 @@ name: Generate CIM Modeling Guide PDF -on: - push: - release: - types: [published] - pull_request: - branches: [ "master" ] +on: workflow_dispatch jobs: build: runs-on: ubuntu-latest steps: - name: Checkout this repository - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Install/setup Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: - python-version: 3.x - - name: Install mkdocs documentation tool - run: pip install mkdocs-material - - name: Install PDF export plugin dependency (Pango) - run: sudo apt install libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0 - - name: Install PDF export plugin for mkdocs - run: pip install mkdocs-pdf-export-plugin + python-version: 3.9 + - name: Install mkdocs documentation tool and plugins + run: pip install -r requirements.txt - name: Build the documentation including PDF run: mkdocs build env: ENABLE_PDF_EXPORT: 1 - name: Upload CIM Modeling Guide PDF as artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: CIM_Modeling_Guide.pdf - path: site/CIM_Modeling_Guide.pdf \ No newline at end of file + path: site/pdf/CIM_Modeling_Guide.pdf \ No newline at end of file diff --git a/.github/workflows/publish-site.yml b/.github/workflows/publish-site.yml new file mode 100644 index 0000000..9483a72 --- /dev/null +++ b/.github/workflows/publish-site.yml @@ -0,0 +1,27 @@ +name: Publish website +on: workflow_dispatch +permissions: + contents: write +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout this repository + uses: actions/checkout@v4 + + - name: Install/setup Python + uses: actions/setup-python@v5 + with: + python-version: 3.9 + + - name: Install mkdocs documentation tool and plugins + run: pip install -r requirements.txt + + - name: Configure Deploy + run: | + git config --global user.name "Admin CIMug" + git config --global user.email "cimug.dev@gmail.com" + git fetch origin gh-pages --depth=1 + + - name: Build Docs Website + run: mike deploy --branch gh-pages --remote origin --push 1.1 \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9b72d31 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +site/ +venv/ \ No newline at end of file diff --git a/README.md b/README.md index 576da38..9ec0577 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,72 @@ # CIM Modeling Guide -UCAIug CIM Modeling Guide, © 2019 - 2023. All rights reserved by the UCA International CIM Users Group + +![image](docs/images/media/image-header-1.png) + +UCAIug CIM Modeling Guide, © 2019 - 2024. All rights reserved by the UCA International CIM Users Group This repository hosts the publically available **CIM Modeling Guide** made available by the UCA International CIM Users Group. This official guide is managed and maintained by the CIM Model Management Team and can be viewed online [here](https://cim-mg.ucaiug.io/). +The final documentation published online is generated using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material). + +## CIM Modeling Guide Discussion Forums + +For general questions or discussions related to this UCAIug publication or specific rules therein please post directly to the [CIM Modeling Guide Discussion](https://github.com/cimug-org/cim-modeling-guide/discussions) forums for this repository. + +## Submitting Issues +For any identified issues with this **CIM Modeling Guide** please submit them via the [CIM Modeling Guide Issues](https://github.com/cimug-org/cim-modeling-guide/issues) tracker. Be sure to add an appropriate "version" label on your issue (e.g. v1.1) corresponding to the publication version of the modeling guide. + ## Contributing -CIM Modeling Guide is documented using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material). If you need to do work on the CIM Modeling Guide you can do so by editing the files directly in the `docs` folder of this repo. +To run the site locally use [Python](https://www.python.org/). This is cleanest if you use a Python virtual environment as shown below to install the dependencies. +```cmd +python -m venv venv +venv\Scripts\activate +pip install mkdocs-material mkdocs-with-pdf mike mkdocs-enumerate-headings-plugin +``` +For exact (known working) versions of dependencies, run `pip install -r requirements.txt` instead. + +Once installed, you can then run the documentation site locally with `mkdocs serve` +```cmd +mkdocs serve +``` +You can view the site by navigating to http://localhost:8000 in your browser. -## Offline Viewing -There are two options for offline viewing of the latest CIM Modeling Guide. You can download the latest release of the PDF of the CIM Modeling Guide at [releases](https://github.com/cimug-org/cim-modeling-guide/releases). +This project also publishes a PDF version of the site. The easiest way to generate the PDF is with the [Generate CIM Modeling Guide PDF](https://github.com/cimug-org/cim-modeling-guide/actions/workflows/generate-pdf.yml) GitHub Action. However, if you need to run it locally, first set the `ENABLE_PDF_EXPORT` environment variable then run the build command. -Alternatively, to serve the modeling guide locally as a live-reloading web page, use [Docker](https://www.docker.com/) or [Python](https://www.python.org/). +```cmd +set ENABLE_PDF_EXPORT=1 +mkdocs build +``` +The output will indicate the PDF file location. -For Docker, do `docker pull squidfunk/mkdocs-material` then `mkdocs serve` is default command so you can just do the following from repo root to start the site: +## Publishing +This project uses the [mike](https://github.com/jimporter/mike) plugin to publish multiple versions of the documentation to the https://cim-mg.ucaiug.io site. Under the hood it is using [GitHub Pages](https://pages.github.com/) to host the site which effecitvely just stores the site content in a dedicated git branch called `gh-pages`. - docker run --rm -it -p 127.0.0.1:8000:8000/tcp -v %CD%:/docs squidfunk/mkdocs-material +You can push new versions using the `mike deploy [version]` command. This will replace the existing version of the documentation on the `gh-pages` branch with whever the currently checkout version is and give it a label of `[version]`. So for example to publish a new version of 1.0 you first want to pull the latest published changes down from the remote site +```cmd +git remote add origin https://github.com/cimug-org/cim-modeling-guide +git fetch origin +git switch gh-pages +git pull origin gh-pages +``` +Then switch to the branch you want to update and run the deploy command giving it the name you want, for example let's say we're going to publish version "1.0" which is in branch "v1.0". +```cmd +git switch v1.0 +mike deploy 1.0 +``` -For Python, do `pip install mkdocs-material` then once installed, the basic commands are: +When you need to update which version is considered the "latest" (e.g. when going from 1.0 to 2.0) run the following +```cmd +mike deploy 2.0 latest --update-aliases +``` +Note that mike will always update the version and any aliases (latest) when you run a `mike deploy [version]` command. So you only need to do the `mike deploy -u [version] latest` when the latest version is changed. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site (for deployment). -* `mkdocs -h` - Print help message and exit. +To view the site locally before publishing it to https://cim-mg.ucaiug.io, run +```cmd +mike serve +``` +Then to publish it to https://cim-mg.ucaiug.io, you will want to push your local `gh-pages` branch to the remote https://github.com/cimug-org/cim-modeling-guide repo using +```cmd +mike deploy 1.0 --push +``` -Once you have it running with either Docker or Python, you can view it by navigating to http://localhost:8000 on your browser. +Refer to [mike documentation](https://github.com/jimporter/mike) for more information. \ No newline at end of file diff --git a/docs/images/media/image2.jpeg b/docs/images/media/image2.jpeg index 76a3e9e..f5af660 100644 Binary files a/docs/images/media/image2.jpeg and b/docs/images/media/image2.jpeg differ diff --git a/docs/index.md b/docs/index.md index 5a09251..6193739 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,34 +8,36 @@ **13-February-2021** +The PDF release of v1.1 of the CIM Modeling Guide is made available [here](https://cimug.org/cimdocs/model-manager-documents/?wpcp_link=JTdCJTIyc291cmNlJTIyJTNBJTIyNjVmNzM0NTkyN2U5OTk1YjliZDI0YzlmOTBjNWJhMWMlMjIlMkMlMjJhY2NvdW50X2lkJTIyJTNBJTIyMTg2MDYxNzEwNTYlMjIlMkMlMjJsYXN0Rm9sZGVyJTIyJTNBJTIyMzA3OTY4MzMwMzc0JTIyJTJDJTIyZm9sZGVyUGF0aCUyMiUzQSUyMld5SXpNRGM1Tmpnek16QXpOelFpWFElM0QlM0QlMjIlMkMlMjJmb2N1c19pZCUyMiUzQSUyMjE3ODA3MjMwMjYzMjElMjIlN0Q%3D) at the UCAIug SharePoint site. !!! Note When referencing an offline PDF version of this guide note that it may not correspond to the latest publicly available guide. To reference the latest visit [https://cim-mg.ucaiug.io](https://cim-mg.ucaiug.io). + The PDF release of v1.1 of the CIM Modeling Guide is made available [here](https://cimug.ucaiug.org/Model%20Manager%20Documents/Public/CIM%20Modeling%20Guide_v1.1.pdf) at the UCAIug SharePoint site or [here](https://github.com/cimug-org/cim-modeling-guide/releases/download/v1.1/CIM_Modeling_Guide_v1.1.pdf) at the UCAIug's official Github site. + **UCA International Users Group** +### RIGHT TO DISTRIBUTE AND CREDIT NOTICE -> **RIGHT TO DISTRIBUTE AND CREDIT NOTICE** -> -> This material was created by the UCA International Users Group CIM Model Managers and is available for public use and distribution. Please include credit in the following manner, “UCAIug CIM Modeling Guide, Version 1.1, © November 2021. All rights reserved by the UCA International Users Group”. +> This material was created by the UCA International Users Group CIM Model Managers and is available for public use and distribution. Please include credit in the following manner, “UCAIug CIM Modeling Guide, Version 1.1, © February 2021. All rights reserved by the UCA International Users Group”. -DISCLAIMER OF WARRANTIES AND LIMITATION OF LIABILITIES +### DISCLAIMER OF WARRANTIES AND LIMITATION OF LIABILITIES > THIS DOCUMENT is a work product of THE UCA International Users Group. it was prepared by the CIM Model Managers and approved by the UCA International Users Group leadership. NEITHER the CIM Model Managers, the UCA International Users Group leadership, the CIM users group, NOR ANY PERSON ACTING ON BEHALF OF ANY OF THEM: > -> \(A\) MAKES ANY WARRANTY OR REPRESENTATION WHATSOEVER, EXPRESS OR IMPLIED, (I) WITH RESPECT TO THE USE OF ANY INFORMATION, APPARATUS, METHOD, PROCESS, OR SIMILAR ITEM DISCLOSED IN THIS DOCUMENT, INCLUDING MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, OR (II) THAT SUCH USE DOES NOT INFRINGE ON OR INTERFERE WITH PRIVATELY OWNED RIGHTS, INCLUDING ANY PARTY'S INTELLECTUAL PROPERTY, OR (III) THAT THIS DOCUMENT IS SUITABLE TO ANY PARTICULAR USER'S CIRCUMSTANCE; OR +> (A) MAKES ANY WARRANTY OR REPRESENTATION WHATSOEVER, EXPRESS OR IMPLIED, (I) WITH RESPECT TO THE USE OF ANY INFORMATION, APPARATUS, METHOD, PROCESS, OR SIMILAR ITEM DISCLOSED IN THIS DOCUMENT, INCLUDING MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, OR (II) THAT SUCH USE DOES NOT INFRINGE ON OR INTERFERE WITH PRIVATELY OWNED RIGHTS, INCLUDING ANY PARTY'S INTELLECTUAL PROPERTY, OR (III) THAT THIS DOCUMENT IS SUITABLE TO ANY PARTICULAR USER'S CIRCUMSTANCE; OR > -> \(B\) ASSUMES RESPONSIBILITY FOR ANY DAMAGES OR OTHER LIABILITY WHATSOEVER (INCLUDING ANY CONSEQUENTIAL DAMAGES, EVEN IF the UCA International Users Group OR ANY UCA International Users Group REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES) RESULTING FROM YOUR SELECTION OR USE OF THIS DOCUMENT OR ANY INFORMATION, APPARATUS, METHOD, PROCESS, OR SIMILAR ITEM DISCLOSED IN THIS DOCUMENT. +> (B) ASSUMES RESPONSIBILITY FOR ANY DAMAGES OR OTHER LIABILITY WHATSOEVER (INCLUDING ANY CONSEQUENTIAL DAMAGES, EVEN IF the UCA International Users Group OR ANY UCA International Users Group REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES) RESULTING FROM YOUR SELECTION OR USE OF THIS DOCUMENT OR ANY INFORMATION, APPARATUS, METHOD, PROCESS, OR SIMILAR ITEM DISCLOSED IN THIS DOCUMENT. > -> \(C\) Reference herein to any specific commercial process, or service by its trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the UCA International Users Group. +> (C) Reference herein to any specific commercial process, or service by its trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the UCA International Users Group. -THIRD PARTY INTELLECTUAL PROPERTY +### THIRD PARTY INTELLECTUAL PROPERTY -> The CIM standards are a set of International Electrotechnical Committee (IEC) standards and are the Intellectual Property of the IEC. the UCA International Users Group has a liaison d relationship with the iec that provides access rights to the cim standards for software development. the common information model (CIM) is Open Source and is rendered in the Unified Modeling Language. +> The CIM standards are a set of International Electrotechnical Committee (IEC) standards and are the Intellectual Property of the IEC. The UCA International Users Group has a Liaison D relationship with the IEC that provides access rights to the CIM standards for software development. The Common Information Model (CIM) is Open Source and is rendered in the Unified Modeling Language. -Acknowledgements +## Acknowledgements In preparing this specification, the UCAIug recognizes the special contributions of the following CIM Subcommittee and their organizations. @@ -55,11 +57,11 @@ In preparing this specification, the UCAIug recognizes the special contributions - Tatjana Kostic - *ABB* -Abstract +## *Abstract* > *This document specifies the rules and recommendations on how to use the UML to create and maintain a standardized Common Information Model (CIM) of the electric grid and other related business domains. Such models are called Domain Models. The primary goal of this document is to facilitate communication and understanding among people working with the CIM domain models. The primary goal of the rules is to specify the structure and modeling constraints applied to the CIM. The primary goal of the recommendations is to provide guidelines on how to extend the CIM as more of the model is elaborated by working groups within the International Electrotechnical Commission (IEC) and by the CIM user community. The intent of the recommendations is to facilitate the incorporation of new model elements into the CIM.* -Foreword +## Foreword Exchanging power systems data between utility companies is always problematic when proprietary formats are used. In the past a company would traditionally use a single software system, whether it is a custom in-house solution, or purchased from a large software company, and there would be a single proprietary data standard and format used. With the deregulation of the power industry and the emergence of smarter grids, there is now a greater need to be able to share such power system data between companies and systems. @@ -67,7 +69,7 @@ The increase in choice provided by the number of power system software vendors a The Common Information Model (CIM) is an open standard for representing power system components originally developed by the Electric Power Research Institute (EPRI) in North America. The CIM provides the basis of a series of standards developed under the auspices of the International Electrotechnical Commission (IEC). The CIM standard was started as part of the Control Centre Application Programming Interface (CCAPI) project at EPRI with the aim of defining a common definition for the components in power systems for use the Energy Management System (EMS) Application Programming Interface (API). The EMS API is now maintained by IEC Technical Committee 57 Working Group 13 as IEC 61970-301. The format has been adopted by the major EMS vendors to allow the exchange of data between their applications, independent of their internal software architecture or operating platform.[^1] -About the UCA International CIM Users Group +## About the UCA International CIM Users Group The UCA International Users Group (UCAIug) is a not-for-profit corporation focused on assisting users and vendors in the deployment of standards for real-time applications for several industries with related requirements. The UCAIug does not write standards, however it works closely with those bodies that have primary responsibility for the completion of standards (notably IEC TC 57: *Power Systems Management and Associated Information Exchange*). diff --git a/docs/revision-history.md b/docs/revision-history.md new file mode 100644 index 0000000..5d204ec --- /dev/null +++ b/docs/revision-history.md @@ -0,0 +1,7 @@ +# Revision History + +| **Rev. #** | **Rev Date** | **Author** | **Description** | +|------------|--------------|------------|-----------------| +| 1.0 | 25-Nov-2019 | H. Dotson, et al. | Initial Release | +| 1.1 | 13-Feb-2021 | H. Dotson, et al. | Update to Rule 197 | + diff --git a/docs/section1-introduction.md b/docs/section1-introduction.md index 69a2282..08d9113 100644 --- a/docs/section1-introduction.md +++ b/docs/section1-introduction.md @@ -1,6 +1,6 @@ -# Section 1 - Introduction +# Introduction -## 1.1 Document Overview +## Document Overview The CIM has been growing and more groups are extending it with new functionality. Currently the following IEC TC57 working groups are working with the CIM: @@ -12,13 +12,13 @@ The CIM has been growing and more groups are extending it with new functionality Initially only WG13 and WG14 were working with the CIM. Each group worked with a local copy of the UML model file and the two copies were synchronised as needed. With three working groups the synchronisation process becomes more complex. This document describes how to manage CIM across multiple working groups and provides best practices for applications wanting to extend the CIM. -### 1.1.1 Document Purpose +### Document Purpose The purpose of this document is to provide guidance to individuals working with the CIM UML on how to modify the CIM in accordance with the CIM modeling rules and CIM change management. The rules and process are maintained and enforced by the CIM model managers. The goals of this document are to: 1) facilitate communication and understanding among individuals working with CIM domain models; and 2) streamline the incorporation of new content into the CIM UML. -### 1.1.2 Document Scope +### Document Scope The scope of this document includes providing: @@ -36,7 +36,7 @@ The scope of this document includes providing: 7) A description of the UML tool (Sparx EA) used for CIM Management. -### 1.1.3 What this Document Does Not Cover +### What this Document Does Not Cover *This Document Does Not Cover All UML Concepts* @@ -58,7 +58,7 @@ The detailed tool procedures used to accomplish CIM Management tasks are not in The tools used to create CIM Profiles are not in the purview of CIM Management. This document does provide rules and recommendations for transforming the CIM UML (a semantic information model) into a canonical data model that can then be used as input to a tool to create CIM Profiles. -### 1.1.4 Who this Document Is For +### Who this Document Is For This document has the following intended audience: @@ -84,7 +84,7 @@ This document has the following intended audience: - Researchers interested in learning about the CIM UML and conducting CIM UML research. -## 1.2 How this Document Is Organized +## How this Document Is Organized This document begins with Sections 1, 2, and 3 providing introductory content, references, and definitions, respectively. @@ -102,7 +102,7 @@ Section 9 identifies and describes the artifacts under CIM Management. This incl Section 10 discusses the tools used for CIM UML model management. Tools include Enterprise Architect, jCleanCIM, and the CIMug Website. -## 1.3 Symbols, Figures, and Style Conventions +## Symbols, Figures, and Style Conventions **Conventions** @@ -128,7 +128,7 @@ The Unified Modeling Language is used 2. Square brackets (\[ \]) are used as delimiters for referenced works cited in this document. -## 1.4 Document Control +## Document Control This document will be reviewed periodically by the CIM Model Managers and updated as needed. Lessons learned will be captured with each CIM UML update and used to improve this document. If the document is written in an older format, the document should be revised into the latest CIM Users Group template format. diff --git a/docs/section10-cim-management-tools.md b/docs/section10-cim-management-tools.md index 80fbbec..a9015ee 100644 --- a/docs/section10-cim-management-tools.md +++ b/docs/section10-cim-management-tools.md @@ -1,18 +1,22 @@ -# Section 10 - CIM Management Tools +# CIM Management Tools This section gives a brief description of the software tools used to help carry out the responsibilities of CIM Management. -## 10.1 Sparx Enterprise Architect +## Sparx Enterprise Architect Sparx Systems Enterprise Architect modeling tool is the tool used to maintain the CIM UML. CIM Management leverages the tool support for partitioning a model into several model files, which allows working groups to develop top-level package model content separately, and then merge the model changes into a complete version of the CIM UML. Enterprise Architect can also be used to generate CIM Profiles with its Schema Composer tool. -## 10.2 jCleanCIM +## CIMTool + +CIMTool is an open source tool for working with the CIM to produce design artifacts such as database schemas, RDF Schema, XSD Schema, JSON Schema, source code classes, reference documentation, etc. from a contextual profile. + +## jCleanCim jCleanCim is a Java application that is used to auto generate draft model standards from the CIM UML. It uses a Word document template, a configuration file, and a CIM UML project file to create the 61970-301, 61968-11, and 62325-301 model documents. -## 10.3 CIMug Website +## CIMug Website The CIMug website serves as the tool that provides online access to artifacts under CIM Management. The CIMug website provides unrestricted access to the CIM UML and controlled access (security credentials required) to artifacts that fall under the Liason D relationship UCA has with the IEC. diff --git a/docs/section2-references.md b/docs/section2-references.md index 9def986..b19601c 100644 --- a/docs/section2-references.md +++ b/docs/section2-references.md @@ -1,6 +1,6 @@ -# Section 2 - References +# References -## 2.1 Normative References +## Normative References The following IEC documents, and the other identified references herein contain information which, through reference in this text, constitute normative provisions of this document. At the time of publication, the editions indicated were valid. All IEC documents, and other normative references are subject to revision. All users of this document are therefore encouraged to investigate the possibility of applying the most recent edition of the references listed below. @@ -12,7 +12,7 @@ The following IEC documents, and the other identified references herein contain | TC57-Glossary | IEC TC57 Glossary | | UML-2.5.1 | Unified Modeling Language Specification Version 2.5.1. Object Management Group December 2017 | -## 2.2 Informative References +## Informative References The following documents referenced herein contain information which is not binding and does not constitute provisions of this document. The information referenced in this text is informative and supportive information intended to enhance the comprehension of this document. diff --git a/docs/section3-definitions.md b/docs/section3-definitions.md index 8eb46a2..4ebf660 100644 --- a/docs/section3-definitions.md +++ b/docs/section3-definitions.md @@ -1,5 +1,5 @@ -# Section 3 - Definitions +# Definitions For the purposes of this document the following definitions apply: diff --git a/docs/section4-cim-overview.md b/docs/section4-cim-overview.md index e966916..05d4f48 100644 --- a/docs/section4-cim-overview.md +++ b/docs/section4-cim-overview.md @@ -1,4 +1,4 @@ -# Section 4 - CIM Overview +# CIM Overview **Background** @@ -25,7 +25,7 @@ In order to achieve these two goals, the UCAIug leadership has decided that the For the past two years the IEC TC57 CIM working groups have emphasized the importance (to their productivity) of having access to documented rules and recommendations for creating new CIM content. Up until the release of this document, CIM management guidelines resided in draft documents owned by CIM Model Managers. -## 4.1 CIM UML Scope +## CIM UML Scope The CIM UML is semantic information model that represents real-world physical electric grid objects and information entities. The CIM UML is the basis for data that is exchanged between systems to: @@ -74,11 +74,11 @@ The CIM UML is semantic information model that represents real-world physical el -## 4.2 CIM Management Business Context +## CIM Management Business Context CIM Management is a business function performed by the CIM Subcommittee of the UCAIug Technical Oversight Committee (see Figure 4‑1). -http://www.ucaiug.org/aboutucaiug/ucaiugorg.jpg +![](images/media/image2.jpeg) Figure 4‑1. UCA International Users Group Organization Chart @@ -122,42 +122,41 @@ The CIM Technical Subcommittee is responsible for handling all technical and mai - Maintain repositories for sample CIM/XML/RDF power system model files -## 4.3 CIM Management Functions +## CIM Management Functions -### 4.3.1 Model Change Management +### Model Change Management Model change management (MCM) is the ongoing process of identifying and managing CIM UML change requests. A model change management plan (MCMP) is developed to define, document and track the information required to effectively manage change requests throughout the CIM UML development life cycle. -### 4.3.2 Model Change Validation +### Model Change Validation Model change validation (MCV) is the ongoing process of ensuring proposed CIM UML changes are in compliance with CIM modeling rules. -### 4.3.3 Model Change Implementation +### Model Change Implementation Model change implementation (MCI) is the ongoing process of making changes to an existing CIM UML baseline to create a new CIM UML baseline. -### 4.3.4 Configuration Management +### Configuration Management Configuration management (CM) is the ongoing process of identifying and managing changes to the CIM UML and other work products. A configuration management plan (CM Plan) is developed to define, document, control, implement, account for, and audit changes to the various CIM configuration items. The CM Plan provides information on the requirements and procedures necessary for CMP activities and establishes the methodology for configuration identification and control of releases and changes to configuration items. It also describes the process for maintaining status accounting and verifying the completeness and correctness of configuration items throughout the CIM UML development life cycle. -### 4.3.5 Model Distribution +### Model Distribution Model distribution (MD) is the ongoing process of distributing CIM UML baselines to official repositories and authorized consumers of the CIM UML. -### 4.3.6 Continuous Process Improvement +### Continuous Process Improvement Continuous process improvement (CPI) is the ongoing process of improving the CIM management processes through incremental and breakthrough improvements. The goal of CPI is to improve the quality of the CIM UML or the efficiency of the CIM management processes. -### 4.3.7 CIM Management Function Mappings +### CIM Management Function Mappings Mapping of the CIM management functions includes two (2) mappings of the CIM management functions. The first shows the mapping between CIM management functions and CIM management responsibilities assigned to the CIM Subcommittee with the UCAIug. The second shows the mapping between CIM management functions and the CIM management processes that realize those functions. The first mapping is shown in Figure 4‑2. The second mapping is discussed in Section 4.4 and shown in Figure 4‑9 - - +![](images/media/image3.png) Figure 4‑2. CIM Management Functions-to-UCA CIM Responsibilities Mapping -## 4.4 CIM Management Processes +## CIM Management Processes CIM management processes are the realization of CIM management functions. There are five (5) CIM management processes. The CIM management processes are shown in Figure 4‑3. A list of the processes and their descriptions are provided in Table 4‑2. @@ -179,7 +178,7 @@ CIM management processes are the realization of CIM management functions. There Figure 4‑4. Model Development Process Flow - +![](images/media/image6.png) Figure 4‑5. Change Management Process @@ -195,31 +194,31 @@ CIM management processes are the realization of CIM management functions. There Figure 4‑8. Continuous Process Improvement Process Flow -### 4.4.1 CIM Management Process Mappings +### CIM Management Process Mappings The mapping between CIM management functions and the CIM management processes are shown in Figure 4‑9. - +![](images/media/image10.png) Figure 4‑9. CIM Management Process-to-CIM Management Functions Mapping The CIM Model Managers perform most of the tasks within the CIM management processes. There are however, other roles within the CIMug and IEC working groups that also perform CIM management tasks. The following table provides a description of each role and its mapping to CIM management processes. | **Role** | **Role Description** | **MDP** | **CMP** | **DGP** | **ADP** | **CPIP** | -|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|---------|---------|---------|----------| -| CIMug Focus Community | This group role consists of individual CIMug members and IEC CIM Working Group members dedicated to developing CIM extensions that deal with a specific area of focus. | Image result for check mark | | | | | -| CIMug Project Team | This group role consists of individual CIMug members and IEC CIM Working Group members working on projects that are jointly funded by participating utilities or vendor companies. | Image result for check mark | | | | | -| CIMug Working Group | This group role consists of individual CIMug members working on issues of common interest to CIM Users. | Image result for check mark | | | | | -| IEC CIM Working Group | This group role consists of individuals appointed by their respective IEC National Committee (technical experts) that take part in the drafting of IEC standard working documents. | Image result for check mark | | Image result for check mark | | | -| IEC Working Group Project Leader | This individual role performed by an IEC Working Group member has overall responsibility for leading the development of a new edition of an international standard from the IEC proposal stage through to the IEC publication stage. | Image result for check mark | | Image result for check mark | | | -| IEC Working Group Convener | This individual role performed by an IEC Working Group member is responsible for arranging and leading face-to-face IEC Working Group meetings and providing working group oversight. | | Image result for check mark | | | Image result for check mark | -| Model Manager | This individual role performed by an individual that is a member of both the CIMug and an IEC Working Group has overall responsibility for artifacts under CIM management. | Image result for check mark | Image result for check mark | Image result for check mark | Image result for check mark | Image result for check mark | +|----------|----------------------|---------|---------|---------|---------|----------| +| CIMug Focus Community | This group role consists of individual CIMug members and IEC CIM Working Group members dedicated to developing CIM extensions that deal with a specific area of focus. | **X** | | | | | +| CIMug Project Team | This group role consists of individual CIMug members and IEC CIM Working Group members working on projects that are jointly funded by participating utilities or vendor companies. | **X** | | | | | +| CIMug Working Group | This group role consists of individual CIMug members working on issues of common interest to CIM Users. | **X** | | | | | +| IEC CIM Working Group | This group role consists of individuals appointed by their respective IEC National Committee (technical experts) that take part in the drafting of IEC standard working documents. | **X** | | **X** | | | +| IEC Working Group Project Leader | This individual role performed by an IEC Working Group member has overall responsibility for leading the development of a new edition of an international standard from the IEC proposal stage through to the IEC publication stage. | **X** | | **X** | | | +| IEC Working Group Convener | This individual role performed by an IEC Working Group member is responsible for arranging and leading face-to-face IEC Working Group meetings and providing working group oversight. | | **X** | | | **X** | +| Model Manager | This individual role performed by an individual that is a member of both the CIMug and an IEC Working Group has overall responsibility for artifacts under CIM management. | **X** | **X** | **X** | **X** | **X** | Table 4‑3. Role-to-CIM Management Process Mapping -## 4.5 CIM Management Process Integration with the IEC Standards Process +## CIM Management Process Integration with the IEC Standards Process -### 4.5.1 IEC Standards Development Process +### IEC Standards Development Process As IEC standards, the CIM standards must go through the IEC international standards development process to be published. An IEC International Standard is the result of an agreement between the National Committees of the IEC. The IEC standard development process and the documents created in the process are shown in Figure 4‑10. A description of the IEC stages is provided in Table 4‑4. @@ -275,7 +274,7 @@ As IEC standards, the CIM standards must go through the IEC international standa -### 4.5.2 Process Integration Points +### Process Integration Points The CIM management processes integrate with the IEC standards development process because the CIM UML provides the basis for IEC CIM standards. There are two types of integration points between the two processes: 1) draft standards preparation; and 2) draft standards submission. @@ -284,16 +283,16 @@ A mapping between the applicable IEC standards development stages and the CIM Ma Table 4‑5. CIM Management Processes-to-IEC Standard Development Stage Mappings | | Proposal Stage | Preparatory Stage | Committee Stage | Enquiry Stage | Approval Stage | Publication Stage | -|-------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| -| Model Development Process | Image result for check mark | Image result for check mark | Image result for check mark | Image result for check mark | Image result for check mark | | -| Change Management Process | Image result for check mark | Image result for check mark | Image result for check mark | Image result for check mark | Image result for check mark | | -| Document Generation Process | | | Image result for check mark | Image result for check mark | Image result for check mark | | -| Artifact Distribution Process | | Image result for check mark | Image result for check mark | Image result for check mark | Image result for check mark | Image result for check mark | +|-|----------------|-------------------|-----------------|---------------|----------------|-------------------| +| Model Development Process | **X** | **X** | **X** | **X** | **X** | | +| Change Management Process | **X** | **X** | **X** | **X** | **X** | | +| Document Generation Process | | | **X** | **X** | **X** | | +| Artifact Distribution Process | | **X** | **X** | **X** | **X** | **X** | -#### 4.5.2.1 Draft Standards Preparation +#### Draft Standards Preparation The intermediate draft standards submitted to the IEC are produced during the execution of the Model Development process and the Document Generation process. CIM UML changes are incorporated to form the basis of the draft standards. Therefore, the Change Management process is also part of draft standards preparation. -#### 4.5.2.2 Draft Standards Submission +#### Draft Standards Submission The submission of the draft standards to the IEC takes place during the Artifact Distribution process. The IEC is considered one of the subscribers for the draft standards in the process. diff --git a/docs/section5-cim-uml-modeling-rules-and-recommendations.md b/docs/section5-cim-uml-modeling-rules-and-recommendations.md index 2921e45..e07fedd 100644 --- a/docs/section5-cim-uml-modeling-rules-and-recommendations.md +++ b/docs/section5-cim-uml-modeling-rules-and-recommendations.md @@ -1,6 +1,6 @@ -# Section 5 - CIM UML Modeling Rules and Recommendations +# CIM UML Modeling Rules and Recommendations -## 5.1 Overview +## Overview This section describes rules and recommendations on how to use the UML to model electric utility domain information. The UML does not include a step-by-step model development process. It is a general-purpose modeling language that all modelers can use. The primary goal behind CIM UML modeling rules and recommendations is to ensure a well-formed, consistent semantic information model is maintained in order to facilitate communication and understanding among people working with the CIM. @@ -12,25 +12,25 @@ Due to the evolving nature of the CIM, there are notable rule exceptions through - special circumstances warrant the need for an exception -### 5.1.1 UML Concepts Used in the CIM +### UML Concepts Used in the CIM The CIM uses a very small subset of UML concepts. UML concepts and models can be grouped into the following concept areas: 1) static structure; 2) dynamic behavior; 3) implementation constructs; 4) model organization; and 5) extensibility mechanisms. The CIM only uses UML concepts in the static structure and model organization concept areas. -### 5.1.2 UML Static Structure Concepts +### UML Static Structure Concepts The CIM uses UML concepts that model utility domain concepts, their internal properties, and their relationships to each other. Utility domain concepts are modeled as classes, each of which describes a set of discrete objects that hold information. Utility domain concept properties are modeled as class attributes. The relationships between utility domain concepts are modeled as class associations or generalisations. Many classes share common structure using generalisation. Static structure concepts are viewed using class diagrams. -### 5.1.3 UML Model Organization Concepts +### UML Model Organization Concepts The CIM uses UML packages to organize modeling information. Packages are general-purpose hierarchical organizational units of UML models. The purpose of packages in the CIM is mainly for controlling working group ownership, with sub-packages mainly representing conceptual organization. This usage of the package structure allows for relatively easy movement of classes among packages without impacting concrete implementations. It also defines the area of responsibility for model managers. The CIM also uses UML dependencies among packages to impose an overall model architecture. The contents of the packages must conform to the package dependencies and to the imposed model structure. -## 5.2 Model Structure Rules +## Model Structure Rules Model structure rules address UML metamodel rules, and the structure, dependencies, and assembly of CIM packages. -### 5.2.1 UML Metamodel Rules +### UML Metamodel Rules @@ -69,7 +69,7 @@ Model structure rules address UML metamodel rules, and the structure, dependenci
-### 5.2.2 Package Structure Rules +### Package Structure Rules Overview @@ -141,7 +141,7 @@ Both the legacy and new top-level package structure are shown in Figure 5‑1 an -### 5.2.3 Package Dependency Rules +### Package Dependency Rules The concept of package dependencies is critical to both the understanding of model ownership among working groups and the practical integration or assembly of packages from different owners. An additional package is maintained outside of the IEC working group packages to describe the dependencies among the packages of each working group. This package, named “PackageDependencies” contains a figure illustrating these dependencies as shown in Figure 5-3 UML package dependencies (for illustration, not official CIM standard). As such the PackageDependencies package is itself dependent upon all the other major packages @@ -217,7 +217,7 @@ Types used for attributes in a class introduce dependencies that must be coordin Figure 5‑3. Top-level CIM (formerly TC57CIM) Package Dependencies -### 5.2.4 Package Assembly Rules +### Package Assembly Rules Each working group edits what it owns and merges what others own. With three working groups this results in six possible ways to exchange portioned model files between the groups as shown in Figure 5-4. @@ -308,7 +308,7 @@ The best practice is to always import and work with the standard packages upon w -## 5.3 Package Rules +## Package Rules The purpose of packages in the CIM model is mainly for controlling working group ownership, with sub-packages mainly representing conceptual organization. This usage of the package structure allows for relatively easy movement of classes among packages without impacting concrete implementations. @@ -392,7 +392,7 @@ Package names start with upper case (UpperCamelCase rule). Package names must be -### 5.3.2 Package Specification Rules +### Package Specification Rules | **RuleID** | **Description** | |------------|-----------------| @@ -400,7 +400,7 @@ Package names start with upper case (UpperCamelCase rule). Package names must be | Rule036 | “Doc” packages should be specified as “private” packages in Enterprise Architect package properties, so they can be filtered out of diagrams showing the sub-packages. | | Rule037 | “DetailedDiagram” packages should be specified as “private” packages in Enterprise Architect package properties, so they can be filtered out of diagrams showing the sub-packages. | -## 5.4 Class Rules +## Class Rules The following UML class features are used in CIM: @@ -444,7 +444,7 @@ Classes should be ordered alphabetically or in order of importance or by logical | Rule047 | CIM classes with a stereotype other than **<<deprecated>>** shall only be used as datatypes for attributes. | | Rule048 | CIM classes should be ordered alphabetically or in order of importance or by logical grouping within a package. | -## 5.5 Attribute Rules +## Attribute Rules The following UML attribute features (i.e. available in the "Properties" Pane in Sparx EA) are used in CIM: @@ -531,7 +531,7 @@ The attribute order should normally be alphabetical unless there is some clear r -## 5.6 Association Rules +## Association Rules Associations describe how classes are related. Only classes describing domain objects, i.e. classes without data type stereotypes such as **<<enumeration>>**, **<<Primitive>>**, **<<Compound>>**, or **<<CIMDatatype>>**, may participate in associations. @@ -669,7 +669,7 @@ Multiplicities shall be chosen to specify what can be expected in the domain. Mu -## 5.7 Enumeration Rules +## Enumeration Rules Enumeration literals are attributes within an **<<enumeration>>** type. The following UML attribute features are used in CIM: @@ -761,7 +761,7 @@ There is no ordering required or reinforced; the order found in the UML model wi -## 5.8 Diagram Rules +## Diagram Rules The following UML diagram features are used in CIM: @@ -791,7 +791,7 @@ Diagrams should be placed inside of packages (the normal case) or classes (e.g. | Rule102 | Diagrams should be placed inside of packages (the normal case) or classes (e.g. in Dynamics package). | | Rule103 | The order of diagrams in the package should be from most general to most specific. | -## 5.9 Element Description Rules +## Element Description Rules Make sure to add a description to the UML elements (package, diagram, class, attribute, association ends etc.) when creating them. The description shall explain the meaning of the entity as clearly as possible. It is often useful to search dictionaries and the web for good descriptions. @@ -870,7 +870,7 @@ Avoid using mark-up in the documentation (e.g., bold, lists, superscripts). Note -## 5.10 Inheritance Rules +## Inheritance Rules Inheritance is used to specialise an existing class. The inheriting class is more specific than the base class. Inheritance is the strongest possible dependency; it is often misused and should be used with care (note: everything that can be expressed through inheritance could also be expressed through composition). @@ -888,9 +888,9 @@ Inheritance should never create situations where attribute names or role names a | Rule118 | Inheritance should never create situations where attribute names or role names are duplicated or “override” within the inheritance lineage. | | Rule119 | Inheritance shall not be used with stereotyped classes. | -## 5.11 Stereotype Rules +## Stereotype Rules -### 5.11.1 General and **<<Deprecated>>** Stereotype Rules +### General and **<<Deprecated>>** Stereotype Rules This stereotype is recognised by the CIM UML validation and document generation tool and can be applied to any of the UML concepts defined below. The typical usage of the **<<deprecated>>** stereotype is for the purpose of preserving backwards compatibility for the normative, already published content, during a release or two, while indicating to the users that the item is likely to actually be removed in the future. This is a graceful means of phasing out obsolete or re-factored elements, and leaving some time to the users to provide implementation in terms of the new features replacing those marked with **<<deprecated>>**. @@ -907,13 +907,13 @@ The **<<deprecated>>** strereotype may be used on attributes, associ | Rule124 | Usage of the **<<deprecated>>** stereotype should be for the purpose of preserving backwards compatibility for normative, already published content. | | Rule125 | The **<<deprecated>>** stereotype should be used for no more than two (2) releases of the CIM. | -### 5.11.2 Package Stereotype Rules +### Package Stereotype Rules | **RuleID** | **Description** | |------------|-----------------| | Rule126 | A package stereotype may be used temporarily to describe the development state of the package, e.g. **<<Work in progress>>**. Once the package is fully incorporated in the model the stereotype shall be removed. | -### 5.11.3 Class Stereotype Rules +### Class Stereotype Rules | **RuleID** | **Description** | |------------|-----------------| @@ -923,7 +923,7 @@ The **<<deprecated>>** strereotype may be used on attributes, associ | Rule130 | The **<<enumeration>>** stereotype shall be used to extend the semantics of the UML class element to represent a data type whose instances form a list of named literal values. | | Rule131 | A CIM class that represents a domain object that participates in inheritance and / or association relationships shall not use a stereotype with the exception of the **<<deprecated>>** stereotype specified in \[Rule 124\]. | -## 5.12 Namespace Rules +## Namespace Rules Namespaces are specified at level of packages in the CIM UML model. The namespaces apply to classes, attributes, association ends, data types (**<<CIMDatatype>>**, **<<Compound>>**, **<<Primitive>>**, and **<<enumeration>>**) and enums. Namespaces are useful for marking the source of CIM models for either standards or extensions. @@ -1068,7 +1068,7 @@ nsuri=http://iec.ch/TC57/2015/CIM17 -## 5.13 Documentation Rules +## Documentation Rules | **RuleID** | **Description** | |------------|-----------------| diff --git a/docs/section6-cim-uml-extension-rules-and-recommendations.md b/docs/section6-cim-uml-extension-rules-and-recommendations.md index 7e233f1..728badf 100644 --- a/docs/section6-cim-uml-extension-rules-and-recommendations.md +++ b/docs/section6-cim-uml-extension-rules-and-recommendations.md @@ -1,16 +1,16 @@ -# Section 6 - CIM UML Extension Rules and Recommendations +# CIM UML Extension Rules and Recommendations -## 6.1 Overview +## Overview The CIM UML is an ever-evolving semantic information model. It is extended periodically based on work performed by the IEC TC57 working groups 13, 14, 16 and 21, and work performed by the CIMug through its various focus communities, projects, and working groups. CIM extensions originating from IEC TC57 working group are classified as “Standard” CIM extensions. CIM extensions originating from the CIMug are classified as “User-Defined” CIM extensions. -### 6.1.1 Application of CIM UML Extension Rules and Recommendations +### Application of CIM UML Extension Rules and Recommendations Work on Standard CIM extensions is started with the full understanding that the extensions are intended to become part of the standard CIM and ultimately to be used to as the basis of new standard CIM profiles. Whereas work on User-Defined extensions is started because the CIM needs to be extended to address the needs and constraints of a particular user’s instance of the CIM. All User-Defined CIM extensions will not become part of the standard CIM. User-Defined CIM extensions must be evaluated to see if they can also be applied in the broader CIM user community as is or with some modifications. For the reasons presented above, some extension rules and recommendations apply only to Standard CIM extensions; some only to User-Defined CIM extensions; and some to all CIM extensions. The language of the rules and recommendations is intended to be unambiguous so the users of this document will know to which class of CIM extensions each rule and recommendation applies. -### 6.1.2 Custom CIM Extensions +### Custom CIM Extensions The objective of these recommendations is to allow for clear modularization of extensions such that they can be readily identified as extensions and migrated more easily to updated versions of the standard CIM, @@ -50,7 +50,7 @@ Figure Example UML model for association extensions to standard CIM classes An extension class should be used only one time within a namespace. The extension class should have the **<<CIMExtension>>** generalization pointing to a standard CIM class of the same name. A particular extension is an extension to the one and only standard CIM class. A standard CIM class may have any number of **<<CIMExtension>>** generalization relationships where each should be from an extension class of the same name but with unique namespaces. The possiblity exists for extension classes extending other extension classes, though it is preferred to extend the standard CIM class if it exits. -## 6.2 General Extension Rules +## General Extension Rules General rules for IEC TC57, available in “TC57 CIM Naming_Rules_Draft_R00_2008-05-16v3.doc”, give the overall guidelines for naming conventions of UML models at any abstraction level. The rules defined in this technical report, dedicated to CIM UML information model, take precedence over the rules in the above document in case the rules differ. @@ -81,7 +81,7 @@ It is discouraged to distinguished names by upper and lower case changes alone. | Rule169 | UML packages shall be used to structure CIM extensions into manageable and logical model parts. | | Rule170 | Before creating a new model element, the CIM should be searched to see if an element similar to the intended extension element already exists. If it does exist, it may influence the extension to the model. | -## 6.3 Package Extension Rules +## Package Extension Rules Package names start with upper case (UpperCamelCase rule). Package names must be unique across the whole CIM. @@ -154,7 +154,7 @@ Package names start with upper case (UpperCamelCase rule). Package names must be -## 6.4 Class Extension Rules +## Class Extension Rules Class names start with upper case (UpperCamelCase rule). Class names should use singular form. Class names must be unique across the whole CIM. Be aware there is a potential conflict of profile names and class names that may occur from the 62361-100 NDR standard for XSD naming rules, so the choice of profile names and class names should be made with this consideration. @@ -169,7 +169,7 @@ Class names start with upper case (UpperCamelCase rule). Class names should use | Rule190 | User-Defined CIM extension class names may include an underscore character. | | Rule191 | Relationships between User-Defined CIM extension classes and standard CIM classes should be generalisations whenever possible. | -## 6.5 Attribute Extension Rules +## Attribute Extension Rules Attribute names start with lower case (lowerCamelCase rule). Attribute names should use singular form. Attribute names are unique within a classifier. Inherited attribute names should be unique @@ -180,13 +180,13 @@ Attribute names start with lower case (lowerCamelCase rule). Attribute names sho | Rule194 | User-Defined CIM extension attributes that are part of a User-Defined CIM extension class shall not be stereotyped. | | Rule195 | User-Defined CIM extension attributes that are part of a standard CIM class shall be stereotyped. | -## 6.6 Association Extension Rules +## Association Extension Rules -### 6.6.1 Association names +### Association names Association names are not used and should be left empty. -### 6.6.2 Association end names +### Association end names Association end names are mandatory at both sides for an association. @@ -222,7 +222,7 @@ Inherited association ends should have unique names. Figure 6‑3. Allowed duplication of association end names -## 6.7 Enumeration Extension Rules +## Enumeration Extension Rules Enumeration literal names should follow the same rules as attribute names (5.4.7), except in case some established conventions exist, e.g. SI unit symbols or currencies. diff --git a/docs/section7-cim-uml-transformation-rules-and-recommendations.md b/docs/section7-cim-uml-transformation-rules-and-recommendations.md index a0be5d5..eec3f68 100644 --- a/docs/section7-cim-uml-transformation-rules-and-recommendations.md +++ b/docs/section7-cim-uml-transformation-rules-and-recommendations.md @@ -1,6 +1,6 @@ -# Section 7 - CIM UML Transformation Rules and Recommendations +# CIM UML Transformation Rules and Recommendations -## 7.1 Overview +## Overview The CIM UML is a semantic information model (also referred to as a conceptual data model). It is a conceptual model of utility objects and their relationships with each other. It is application independent, but defines all the concepts needed for any application. It essentially provides the vocabulary (sometimes referred to as a data dictionary) to be used when utility domain data is exchanged between systems. @@ -8,7 +8,7 @@ Since the CIM UML is a conceptual model, it cannot be used as is for data exchan This section specifies the rules and recommendations for transforming a subset of the CIM UML into a contextual data model. The contextual data model can then be used to derive implementation models which define the data and the structure of the data required to exchange information between two systems to execute a single interaction in a System Use Case. -## 7.2 General Transformation Rules and Recommendations +## General Transformation Rules and Recommendations | **RuleID** | **Description** | |------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -16,7 +16,7 @@ This section specifies the rules and recommendations for transforming a subset o | Rule208 | In instances where CIM extensions have been added to the CIM UML, the extensions may be part of a contextual data model derived from the CIM UML. | | Rule209 | A class diagram that contains all candidate classes and associations should be created, which may be used as a reference diagram, for each contextual data model. | -## 7.3 Package Transformation Rules and Recommendations +## Package Transformation Rules and Recommendations | **RuleID** | **Description** | |------------|-----------------| @@ -24,14 +24,14 @@ This section specifies the rules and recommendations for transforming a subset o | Rule211 | Transformation of an entire package shall not be required to create a contextual data model (i.e. classes, attributes, and associations within a package may be left out of a contextual data model if they are not needed). | | Rule212 | A single top-level package for contextual data models that exists outside of the top-level CIM (formerly TC57CIM) package should be created at the root-level of the CIM. | -## 7.4 Class Transformation Rules and Recommendations +## Class Transformation Rules and Recommendations | **RuleID** | **Description** | |------------|-----------------| | Rule213 | A contextual data model shall contain at least one concrete class. | | Rule214 | A contextual data model may contain abstract classes. | -## 7.5 Attribute Transformation Rules and Recommendations +## Attribute Transformation Rules and Recommendations | **RuleID** | **Description** | |------------|-----------------| @@ -41,7 +41,7 @@ This section specifies the rules and recommendations for transforming a subset o | Rule218 | A contextual data model should contain the attributes necessary to execute a System use case interaction. | | Rule219 | A contextual data model should not contain attributes not used in a System use case interaction (i.e. not all class attributes must be included in a contextual data model). | -## 7.6 Association Transformation Rules and Recommendations +## Association Transformation Rules and Recommendations | **RuleID** | **Description** | |------------|-----------------| diff --git a/docs/section8-cim-uml-version-control-rules.md b/docs/section8-cim-uml-version-control-rules.md index ab60140..bb2132c 100644 --- a/docs/section8-cim-uml-version-control-rules.md +++ b/docs/section8-cim-uml-version-control-rules.md @@ -1,6 +1,6 @@ -# Section 8 - CIM UML Version Control Rules +# CIM UML Version Control Rules -## 8.1 Overview +## Overview After the top-level CIM packages have been synchronized and deployed as the complete CIM UML for use by either working groups or into the public domain, profiles will naturally be developed that have dependencies on it. When the need arises to make changes to the CIM UML, an impact assessment needs to be made to determine: @@ -24,11 +24,11 @@ These issues result in the need for versioning. How versioning is implemented an The remaining subsections of this overview address these questions and provide a set of options for solving common versioning problems. -### 8.1.1 The Scope of a Version +### The Scope of a Version We have established that the CIM UML is partitioned into three top-level packages that must be merged and synchronized before being deployed for use. So, when a new version of the CIM UML is created, exactly what is being referring to must be defined. -### 8.1.2 Versioning and Compatibility +### Versioning and Compatibility The number one concern when developing and deploying a new version of the CIM UML is the impact it will have on users that will develop CIM Profiles that have dependencies on it. The measure of impact is directly related to how compatible the new CIM UML is with the old version(s) of the CIM UML. @@ -43,17 +43,17 @@ This subsection establishes the fundamental types of compatibility that relate t Table 8‑1. Compatibility Types -### 8.1.3 Version Identifiers +### Version Identifiers Version identifiers always follow some version identification pattern. The version identification pattern used must not only express the version number at the CIM UML level, but right down to the lowest level changeable element or element property. The version identification patterns for the CIM UML are specified in section 8.2.3, Version Identification. -### 8.1.4 Versioning Strategies +### Versioning Strategies There is no one versioning strategy that is right for everyone. Because versioning represents a governance-related phase in the overall lifecycle of the CIM UML, it is a practice that is subject to conventions, preferences, and requirements that are distinct to CIM Management. Even though there is no de facto versioning strategy for UML models, a number of advocated versioning strategies have emerged, each with its own benefits and tradeoffs. This sub-section will cover the three known versioning strategies considered for the CIM UML. -#### 8.1.4.1 The Strict Strategy +#### The Strict Strategy The Strict Strategy is the simplest approach to CIM UML versioning. Any compatible or incompatible changes result in a new version of the CIM UML. This approach is commonly implemented by changing the target namespace value. In effect, namespaces are used for version identification instead of a version attribute because changing the namespace value automatically forces a change in all CIM Profiles that need to access the new version of the CIM UML. @@ -67,7 +67,7 @@ On the downside, by forcing a new namespace upon the CIM UML with each change, i Therefore, this strategy will increase the governance burden on users of the CIM UML and will require careful transitioning strategies. Having two or more version of the CIM UML at the same time can become a common requirement for which a supporting infrastructure will need to be prepared. -#### 8.1.4.2 The Flexible Strategy +#### The Flexible Strategy A common strategy used to balance practical considerations with an attempt at minimizing the impact of changes to the CIM UML is to allow compatible changes to occur without forcing a new CIM UML version, while not attempting to support forwards compatibility at all. @@ -81,7 +81,7 @@ The primary advantage to this strategy is that it can be used to accommodate a v However, when compatibility changes are made, these changes become permanent and cannot be reversed without introducing an incompatible change. Therefore, a governance process is required during which each proposed change is evaluated to ensure CIM Profiles do not become overly bloated or convoluted. -#### 8.1.4.3 The Loose Strategy +#### The Loose Strategy As with the previous two strategies, this strategy requires that incompatible changes result in a new version of the CIM UML. The difference is the changes are modeled in the CIM UML to be intrinsically extensible so that the CIM UML remains able to support a broad range of future, unknown data exchange requirements. Since the CIM UML is, by definition, a semantic information model, it is structured to be intrinsically extensible. @@ -89,7 +89,7 @@ As with the previous two strategies, this strategy requires that incompatible ch The fact that all attributes are optional and most associations have an undefined upper range provides a constant opportunity to further expand the CIM UML. On the other hand, there is a governance process required during which each proposed change is evaluated to ensure CIM Profiles do not become overly bloated or convoluted. -#### 8.1.4.4 Summary Table +#### Summary Table Table 8‑2 broadly summarizes how the three strategies compare based on three fundamental characteristics. @@ -110,27 +110,27 @@ The three characteristics used in this table to form the basis of this compariso Table 8‑2. A general comparison of the three versioning strategies. -## 8.2 Version Control Strategy +## Version Control Strategy The version control strategy is expressed as a set of rules that address version scope, version compatibility, and version identification. The following sub-sections address each area, respectively. **NOTE**: The versioning strategy presented here is still under discussion amongst the CIM managers and is subject to change once discussions are completed. The versioning strategy will then be updated to reflect any changes. -### 8.2.1 Version Scope +### Version Scope | **RuleID** | **Description** | |------------|-----------------| | Rule225 | A new version of a top-level package shall be created when the contents of the top-level package (which includes any of its normative sub-packages) has been changed, and the change has been verified by the appropriate CIM model manager. | | Rule226 | A new version of the CIM UML shall be created when a new version of a top-level package has been created. | -### 8.2.2 Version Compatibility +### Version Compatibility | **RuleID** | **Description** | |------------|-----------------| | Rule227 | A new version of the CIM UML shall be considered backwards-compatible if it continues to support CIM Profiles designed to work with the old version of the CIM UML (i.e. the changes incorporated in the new version of the CIM UML are compatible changes). | | Rule228 | A new version of the CIM UML shall be considered not backwards-compatible if it does not support CIM Profiles designed to work with the old version of the CIM UML. | -### 8.2.3 Version Identification +### Version Identification Version identification rules are based on the needs of the CIM UML users. There are two types of CIM UML users: 1) working group members involved in the development of standards; and 2) the broader CIM community (end users). Each type of user has different requirements for version identification. diff --git a/docs/section9-artifacts-under-cim-management.md b/docs/section9-artifacts-under-cim-management.md index d292d3f..507aa22 100644 --- a/docs/section9-artifacts-under-cim-management.md +++ b/docs/section9-artifacts-under-cim-management.md @@ -1,10 +1,10 @@ -# Section 9 - Artifacts Under CIM Management +# Artifacts Under CIM Management -## 9.1 Overview +## Overview Artifacts under CIM Management consist of: 1) model artifacts (CIM Artifacts); 2) draft standards; 3) CIM Schemas; 4) CIM Management documents and records; and 5) tool customizations. These artifacts are described in this section. -### 9.1.1 Draft Standards Artifacts +### Draft Standards Artifacts As IEC standards, the CIM standards must go through the IEC standards development process to be published (see Section 8.1). This process results in the creation of several draft standard artifacts as intermediate work products. The types IEC draft standard artifacts under CIM management are listed below. The description of each type of draft standard is provided in Section 8.1. @@ -16,7 +16,7 @@ As IEC standards, the CIM standards must go through the IEC standards developmen 4. Final Draft International Standard FDIS) -## 9.2 CIM Artifacts +## CIM Artifacts CIM Artifacts are model artifacts that are maintained in the Sparx Systems Enterprise Architect modeling tool. CIM Artifacts are stored in four (4) file formats: 1) as an EA project file in the native EA file format (\*.eap or \*.eapx); 2) in the ZIP compressed file format (\*.zip); 3) in the XML Metadata Interchange file format (\*.xmi); and 4) as a collection of web pages in HyperText Markup Language file format (\*.html). The EA project file is also exported and maintained as a Web Ontology Language project file (\*.owl). The CIM Artifacts under CIM Management are listed and described in Table 9‑1. @@ -28,7 +28,7 @@ CIM Artifacts are model artifacts that are maintained in the Sparx Systems Enter Table 9‑1. CIM Artifacts Under CIM Management -## 9.3 Model Documents +## Model Documents Model documents are CIM standards that are derived from the CIM UML using the CIM document generation tool jCleanCim. Draft versions of the CIM standard model documents under CIM Management are listed and described in Table 9‑2. @@ -41,7 +41,7 @@ Model documents are CIM standards that are derived from the CIM UML using the CI Table 9‑2. Model Documents Under CIM Management -## 9.4 CIM Profiles +## CIM Profiles A CIM Profile is a subset of the full CIM UML that is derived to define data exchanges required between systems. Each profile is a collection of classes, attributes and references along with additional restrictions such as making attributes mandatory or restricting the cardinalities on associations. Draft versions of CIM standard profiles are artifacts under CIM Management. Also included as a CIM Profile is 61968-1 which is not a subset of the CIM UML; it is a reference to be used in the development of CIM Profiles. The CIM Profiles under CIM Management are listed and described in Table 9‑3. @@ -179,9 +179,9 @@ A CIM Profile is a subset of the full CIM UML that is derived to define data exc **Table 9‑3. CIM Profiles Under CIM Management (Cont’d)** -## 9.5 CIM Schemas +## CIM Schemas -### 9.5.1 Background +### Background XML, the eXtensible Markup Language, is a “universal format for structured documents and data” which is quickly becoming the standard for storing machine-readable data in a structured, extensible format that is accessible over the Internet. XML uses *tags* to denote the elements within XML documents. @@ -191,7 +191,7 @@ CIM Schemas provide the constraints on the structure and contents of CIM based X The following subsections list and describe the CIM Schemas under CIM Management. Some of the CIM Schemas are IEC International Standards and some are schemas derived from CIM Profiles. -### 9.5.2 RDF Schemas +### RDF Schemas The RDF schemas under CIM management are listed and described in Table 9‑4. @@ -206,7 +206,7 @@ The RDF schemas under CIM management are listed and described in Table 9‑4. **Table 9‑4. RDF Schemas Under CIM Management (Cont’d)** -### 9.5.3 XML Schemas +### XML Schemas The XML schemas under CIM management are listed and described in Table 9‑5. @@ -266,7 +266,7 @@ The XML schemas under CIM management are listed and described in Table 9‑5. **Table 9‑5. XML Schemas Under CIM Management (Cont’d)** -### 9.5.4 Hybrid Schemas +### Hybrid Schemas The Hybrid schemas under CIM management are listed and described in Table 9‑6. @@ -292,13 +292,13 @@ The Hybrid schemas under CIM management are listed and described in Table 9‑6. -## 9.6 CIM Management Documents and Records +## CIM Management Documents and Records CIM management documents are electronic or paper objects that contain instructions for tasks, requirements for how and when to perform a task or function, and logs the task execution and decisions. CIM management documents can communicate and share information and knowledge. Examples of CIM management documents include procedures, protocols, methods, and specifications. CIM records are a subset of CIM management documents that provide evidence that actions were taken and decisions were made in keeping with procedures; they can serve as evidence of the Working Group’s activity and compliance with IEC processes and procedures. -### 9.6.1 CIM Management Documents +### CIM Management Documents Table 9‑7 is a list and description of CIM Management Documents maintained by CIM model managers. @@ -313,7 +313,7 @@ Table 9‑7 is a list and description of CIM Management Documents maintained by | **Model Manager Checklist** | The Model Manager Checklist is a list of tasks that need to be completed as a matter of course in implementing a model change request. Currently there is a Model Manager Checklist maintained for each working group. | | **Working Group Issues List** | The working group issues list is a collection of issues raised by a working group concerning the CIM UML contained in their respective top-level CIM package. The issues on these lists can be resolved without involving other working groups. | -### 9.6.2 CIM Records +### CIM Records Table 9‑8 is a list and description of CIM Records managed by CIM model managers. @@ -333,7 +333,7 @@ Table 9‑8 is a list and description of CIM Records managed by CIM model manage **Table 9‑8. CIM Records (Cont’d)** -## 9.7 Tool Customizations +## Tool Customizations Tool customizations are artifacts that facilitate or help automate tasks performed by CIM Model Mangers in conjunction with a software tool. Table 9‑9 is a list and description of Tool customizations managed by CIM Model Managers. diff --git a/mkdocs.yml b/mkdocs.yml index bf4a34a..e80b904 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,11 +4,12 @@ theme: palette: primary: white logo: images/media/logo-gray.png + favicon: images/media/logo-white.png name: material features: - content.code.copy - navigation.footer -copyright: Copyright © 2019 - 2023. All rights reserved by the UCA International CIM Users Group +copyright: Copyright © 2019 - 2024. All rights reserved by the UCA International CIM Users Group extra_css: - stylesheets/extra.css markdown_extensions: @@ -18,19 +19,47 @@ markdown_extensions: - pymdownx.details plugins: - search - - pdf-export: + - enumerate-headings: + toc_depth: 6 + exclude: + - index.md + - revision-history.md + - with-pdf: + author: UCA International Users Group + copyright: © Copyright 2021, UCA International Users Group, All rights reserved + cover: true + cover_title: CIM Modeling Guide + cover_subtitle: Version 1.1, 13-February-2021 + toc_title: Table of Contents + heading_shift: true + ordered_chapter_level: 0 + toc_level: 3 + show_anchors: true enabled_if_env: ENABLE_PDF_EXPORT - combined: true - combined_output_path: CIM_Modeling_Guide.pdf + output_path: pdf/CIM_Modeling_Guide.pdf + # This 'mike' plugin is for publishing multiple versions see https://github.com/jimporter/mike + - mike: + alias_type: symlink + redirect_template: null + deploy_prefix: '' + canonical_version: null + version_selector: true + css_dir: css + javascript_dir: js +extra: + version: + provider: mike nav: + # If adding a new markdown file that you do not want included with sections numbers exclude it under -enumerate-headings - 'index.md' - - 'section1-introduction.md' - - 'section2-references.md' - - 'section3-definitions.md' - - 'section4-cim-overview.md' - - 'section5-cim-uml-modeling-rules-and-recommendations.md' - - 'section6-cim-uml-extension-rules-and-recommendations.md' - - 'section7-cim-uml-transformation-rules-and-recommendations.md' - - 'section8-cim-uml-version-control-rules.md' - - 'section9-artifacts-under-cim-management.md' - - 'section10-cim-management-tools.md' + - 'revision-history.md' + - '1. Introduction': 'section1-introduction.md' + - '2. References': 'section2-references.md' + - '3. Definitions': 'section3-definitions.md' + - '4. CIM Overview': 'section4-cim-overview.md' + - '5. CIM UML Modeling Rules and Recommendations': 'section5-cim-uml-modeling-rules-and-recommendations.md' + - '6. CIM UML Extension Rules and Recommendations': 'section6-cim-uml-extension-rules-and-recommendations.md' + - '7. CIM UML Transformation Rules and Recommendations': 'section7-cim-uml-transformation-rules-and-recommendations.md' + - '8. CIM UML Version Control Rules': 'section8-cim-uml-version-control-rules.md' + - '9. Artifacts Under CIM Management': 'section9-artifacts-under-cim-management.md' + - '10. CIM Management Tools': 'section10-cim-management-tools.md' \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..baa1ed7 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,52 @@ +Babel==2.14.0 +beautifulsoup4==4.12.3 +Brotli==1.1.0 +certifi==2024.2.2 +cffi==1.16.0 +charset-normalizer==3.3.2 +click==8.1.7 +colorama==0.4.6 +cssselect2==0.7.0 +fonttools==4.51.0 +ghp-import==2.1.0 +html5lib==1.1 +idna==3.7 +importlib-metadata==7.1.0 +importlib-resources==6.4.0 +Jinja2==3.1.3 +libsass==0.23.0 +Markdown==3.6 +MarkupSafe==2.1.5 +mergedeep==1.3.4 +mike==2.0.0 +mkdocs==1.5.3 +mkdocs-enumerate-headings-plugin==0.6.1 +mkdocs-material==9.5.17 +mkdocs-material-extensions==1.3.1 +mkdocs-with-pdf==0.9.3 +packaging==24.0 +paginate==0.5.6 +pathspec==0.12.1 +pillow==10.3.0 +platformdirs==4.2.0 +pycparser==2.22 +pydyf==0.9.0 +pygments==2.17.2 +pymdown-extensions==10.7.1 +pyparsing==3.1.2 +pyphen==0.14.0 +python-dateutil==2.9.0.post0 +PyYAML==6.0.1 +pyyaml-env-tag==0.1 +regex==2023.12.25 +requests==2.31.0 +six==1.16.0 +soupsieve==2.5 +tinycss2==1.2.1 +urllib3==2.2.1 +verspec==0.1.0 +watchdog==4.0.0 +weasyprint==61.2 +webencodings==0.5.1 +zipp==3.18.1 +zopfli==0.2.3 \ No newline at end of file diff --git a/templates/styles.scss b/templates/styles.scss new file mode 100644 index 0000000..6c22a6f --- /dev/null +++ b/templates/styles.scss @@ -0,0 +1,11 @@ +article h1 { + border-bottom: 2px solid #009dab; +} + +article h2 { + border-bottom: 1px solid #009dab; +} + +.md-typeset a { + color: #0b57d0; +} \ No newline at end of file