e-terrasource Metamodel Guide

This document provides information about e-terrasource metadata

modeling.

Software Version: e-terrasource 2.0

Document Date: May 8, 2012

Copyright and Proprietary Information

Copyright © 2011, 2012 ALSTOM Grid Inc. or Affiliate. All Rights Reserved.

NOTE: CONTAINS PROPRIETARY INFORMATION OWNED BY ALSTOM GRID INC.

AND/OR ITS AFFILIATES. DO NOT COPY, STORE IN A RETRIEVAL SYSTEM,
TRANSMIT OR DISCLOSE TO ANY THIRD PARTY WITHOUT PRIOR WRITTEN
PERMISSION FROM ALSTOM GRID INC.
__________________________________________________________________

Trademarks

“ESCA” and “HABITAT” are registered trademarks of ALSTOM Grid Inc. “eterra” is a
registered trademark and/or service mark of E-Terra, LLC, licensed for use by
ALSTOM Grid Inc. in connection with its e-terra family of products and services.

Other product and company names in these materials may be trademarks or registered
trademarks of other companies, and are the property of their respective owners. They are
used only for explanation and to the respective owners’ benefit, without intent to infringe.
Contents

About This Document............................................................................. vii

Purpose of This Document .......................................................................................... vii
Who Should Use This Document................................................................................. vii
Structure of This Document ......................................................................................... vii
For More Information ................................................................................................... vii
Conventions ................................................................................................................ viii
Change Summary .........................................................................................................ix

1. Metadata Overview ............................................................................... 1

1.1 Terminology ............................................................................................................ 1
1.2 Categories of Metadata........................................................................................... 3
1.3 Versioning ............................................................................................................... 4
1.4 Metadata at Installation........................................................................................... 5
1.5 Upgrading Metadata................................................................................................ 6
1.6 More on CIM ........................................................................................................... 8

2. Metamodel Components .................................................................... 11

2.1 Metamodel Overview ............................................................................................ 11
2.2 Metamodel Schema .............................................................................................. 12
2.2.1 Business Model Schema ................................................................................. 12
2.2.1.1 metaNamespaceAuthority .......................................................................... 15
2.2.1.2 metaSchemaNamespace ........................................................................... 16
2.2.1.3 metaSchema .............................................................................................. 17
2.2.1.4 metaSchemaVersion .................................................................................. 18
2.2.1.5 metaEntity................................................................................................... 19
2.2.1.6 metaEntityVersion....................................................................................... 21
2.2.1.7 metaEntityGroup......................................................................................... 23
2.2.1.8 metaSchemaVerEntityVer .......................................................................... 24
2.2.1.8.1 To Remove an Entity from a Schema.................................................... 24
2.2.1.8.2 To Add an Entity to a Schema............................................................... 24
2.2.1.8.3 To Modify an Entity in a Schema ........................................................... 24
2.2.1.9 metaEntityInheritance ................................................................................. 25
2.2.1.10 metaProperty ............................................................................................ 27
2.2.1.10.1 Range Expressions.............................................................................. 31
2.2.1.10.2 Regular Expressions............................................................................ 32
2.2.1.11 metaRelationship ...................................................................................... 33
2.2.1.12 metaEnumType ........................................................................................ 40
2.2.1.13 metaEnumMember ................................................................................... 40
2.2.1.14 metaPropertyGroup .................................................................................. 42

Proprietary – See Copyright Page iii

 2.2.1.15 metaPropertyCondition ............................................................................. 43
2.2.1.16 metaComputation ..................................................................................... 44
2.2.1.17 metaEntityKey........................................................................................... 48
2.2.1.18 metaEntityKeyProperty ............................................................................. 49
2.2.2 Validation Schema ........................................................................................... 50
2.2.2.1 metaValModule........................................................................................... 52
2.2.2.2 metaValSequence ...................................................................................... 53
2.2.2.3 metaValSeqModule .................................................................................... 54
2.2.2.4 metaValPrerequisite ................................................................................... 55
2.2.2.5 metaValRule Editor..................................................................................... 55
2.2.2.6 metaValRule ............................................................................................... 59
2.2.2.7 metaValCheck ............................................................................................ 60
2.2.2.8 metaValVariable ......................................................................................... 62
2.2.2.9 metaMsgDef ............................................................................................... 65
2.2.2.10 metaMsgDefText ...................................................................................... 65
2.2.3 Deep Copy Schema......................................................................................... 66
2.2.3.1 metaDeepCopy........................................................................................... 67
2.2.3.2 metaExcludeProperty ................................................................................. 68
2.2.3.3 metaRecursiveCopy ................................................................................... 69
2.2.4 CIM Profile Schema ......................................................................................... 70
2.2.4.1 metaCIMProfile ........................................................................................... 71
2.2.4.1.1 Import .................................................................................................... 73
2.2.4.1.2 Export .................................................................................................... 74
2.2.4.2 metaCIMCustomTableMap......................................................................... 75
2.2.4.3 metaCIMCustomColumnMap ..................................................................... 76
2.2.4.4 metaCIMProfileProperty ............................................................................. 76
2.2.4.5 metaCIMProfileRelationship ....................................................................... 76

3. Metamodel Validation......................................................................... 77

4. Metamodel Exports............................................................................. 79
4.1 Exporting an Upgrade Script ................................................................................. 79
4.2 Exporting an Installation Script.............................................................................. 82
4.3 Exporting a Validation Script ................................................................................. 85
4.4 Exporting Metamodel HTML Documentation ........................................................ 88
4.5 Dumping a Metamodel Project.............................................................................. 91
4.6 Dumping a Metamodel Workspace....................................................................... 93

5. Script Execution ................................................................................. 97

5.1 Structure ............................................................................................................... 97
5.2 Stored Procedure Calls ......................................................................................... 97
5.3 Error Reporting...................................................................................................... 98

Proprietary – See Copyright Page iv

 5.4 Solutions to Common Problems ........................................................................... 98

Figures
Figure 1: Metadata at Installation .................................................................................... 5
Figure 2: Upgrading the Metadata................................................................................... 7
Figure 3: CIM Model and Profiles.................................................................................... 8
Figure 4: CIM Import Process ......................................................................................... 9
Figure 5: Business Model Schema................................................................................ 13
Figure 6: metaNamespaceAuthority Property Sheet..................................................... 15
Figure 7: metaSchemaNamespace Property Sheet...................................................... 16
Figure 8: metaSchema Property Sheet ......................................................................... 17
Figure 9: metaSchemaVersion Property Sheet Showing Deep Copy ........................... 18
Figure 10: metaEntity Property Sheet ........................................................................... 20
Figure 11: metaEntityVersion Property Sheet Showing Deep Copy ............................. 22
Figure 12: Nested Groups in Tables Explorer ............................................................... 23
Figure 13: metaEntityGroup Property Sheet ................................................................. 23
Figure 14: metaSchemaVerEntityVer Property Sheet................................................... 25
Figure 15: metaEntityInheritance Property Sheet ......................................................... 26
Figure 16: Example Use of Enumeration Property........................................................ 27
Figure 17: metaProperty Property Sheet....................................................................... 28
Figure 18: Relationship Modeling.................................................................................. 34
Figure 19: Database Representation ............................................................................ 34
Figure 20: Transformation Object Representation ........................................................ 34
Figure 21: Duplicate/Conflicting Relationship Model..................................................... 35
Figure 22: Non-Conflicting Relationship Model ............................................................. 35
Figure 23: metaRelationship Property Sheet ................................................................ 36
Figure 24: metaEnumType Property Sheet................................................................... 40
Figure 25: metaEnumMember Property Sheet.............................................................. 41
Figure 26: metaPropertyGroup Property Sheet............................................................. 42
Figure 27: metaPropertyCondition Property Sheet ....................................................... 43
Figure 28: metaComputation Property Sheet................................................................ 44
Figure 29: metaEntityKey Property Sheet ..................................................................... 48
Figure 30: metaEntityKeyProperty Property Sheet........................................................ 49
Figure 31: Validation Schema ....................................................................................... 50
Figure 32: metaValModule Property Sheet ................................................................... 52
Figure 33: metaValSequence Property Sheet............................................................... 53
Figure 34: metaValSeqModule Property Sheet............................................................. 54
Figure 35: metaValPrerequisite Property Sheet............................................................ 55
Figure 36: Validation Rule Editor................................................................................... 55
Figure 37: Validation Rule Property Sheet .................................................................... 59
Figure 38: Validation Check Property Sheet ................................................................. 60
Figure 39: Validation Variable Property Sheet .............................................................. 62
Figure 40: metaMsgDef Property Sheet........................................................................ 65
Figure 41: metaMsgDefText Property Sheet................................................................. 65
Figure 42: Deep Copy Schema ..................................................................................... 67

Proprietary – See Copyright Page v

Figure 43: metaDeepCopy Property Sheet ................................................................... 68
Figure 44: metaExcludeProperty Property Sheet .......................................................... 69
Figure 45: metaRecursiveCopy Property Sheet ............................................................ 69
Figure 46: CIM Profile Schema ..................................................................................... 70
Figure 47: metaCIMProfile Property Sheet ................................................................... 72
Figure 48: metaCIMCustomTableMap Property Sheet ................................................. 75
Figure 49: metaCIMCustomColumnMap Property Sheet .............................................. 76
Figure 50: Workspace Validation .................................................................................. 77
Figure 51: Validation Messages .................................................................................... 77
Figure 52: Metamodel HTML Document – Contents..................................................... 88
Figure 53: Metamodel HTML Document – Entity Details .............................................. 89

Tables
Table 1: Business Model Schema Tables..................................................................... 14
Table 2: Validation Tables............................................................................................. 51
Table 3: Deep Copy Tables .......................................................................................... 67
Table 4: CIM Profile Tables........................................................................................... 70

Proprietary – See Copyright Page vi

About This Document
This document is supplied as a part of Alstom Grid’s e-terrasource
product.

Purpose of This Document

This document has two main purposes:
• To provide an overview of the metadata used by e-terrasource
• To explain step-by-step instructions on metadata modeling

Who Should Use This Document

This document is intended for administrative and expert users of
e-terrasource who want to modify the business model schema. It
assumes that you are already familiar with the content of the
e-terrasource User’s Guide.

Structure of This Document

This document is structured in the following manner:
• Chapter 1 provides an overview of how metadata is used by
e-terrasource.
• Chapter 2 provides details of each component of the metadata.
• Chapter 3 discusses validation of the metamodel.
• Chapter 4 discusses export of metamodel installation and upgrade
scripts.
• Chapter 5 discusses execution of metadata installation and upgrade
scripts.

For More Information

For more information about e-terrasource, refer to the following:
• e-terrasource Release Notes – Installation information about and
requirements for the current e-terrasource release.
• e-terrasource Software Installation and Maintenance Guide –
Information about installation and maintenance of e-terrasource.
• e-terrasource Metamodel Quick Start Guide – Provides a quick
overview of the steps needed to modify metadata.

Proprietary – See Copyright Page vii

 • e-terrasource User’s Guide – Provides instructions on using the user
interface.
• e-terrasource Schema – A PDF document that provides an entity-
relationship diagram of the e-terrasource database schema, including
run-time metadata tables.

Conventions
The following conventions are used throughout this document.
Commands that are particular to an operating system are shown with the
corresponding prompt symbol.

Command Prompts
Operating Prompt Description
System
Linux % All commands preceded by a percent sign prompt
(%) are issued from a Linux terminal window.
Note that all Linux commands are case-sensitive.
Windows > All commands preceded by a greater than sign
prompt (>) are issued from the Windows
command-line window.
All Operating The absence of any prompt character before a
Systems command indicates that the command is valid on
all operating systems.

Command Strings
Operating Delimiter Description
System
Linux Italics Text in italics indicates information you must
supply. (*)
Linux [] Text enclosed in square brackets “[ ]” indicates
optional qualifiers, arguments, or data. (*)
All Operating Select When used in command strings, the term “Select”
Systems means placing the pointer over the specified item
and pressing the left (default) mouse button.
(*) Note: All Linux commands are case-sensitive and must be typed exactly as
shown.

Proprietary – See Copyright Page viii

Change Summary
This is a new document for e-terrasource 2.0.

Proprietary – See Copyright Page ix

1. Metadata Overview
e-terrasource is a highly configurable modeling tool. Rather than having a
hard-coded business model schema, e-terrasource uses metadata at run
time to determine which entities belong to the schema, as well as their
properties and relationships to other entities.
This document is intended to be used by administrators of e-terrasource
tasked with modifying the business model schema. It explains the various
categories of metadata and provides detailed descriptions of how
metadata is used by e-terrasource. After reading this document, you
should have a good understanding of how metadata affects the
appearance of the user interface and the behavior of the application.
A quick step-by-step checklist of the metadata management process can
be found in the e-terrasource Metamodel Quick Start Guide.
A detailed e-terrasource schema diagram that depicts the run-time
metadata tables can be found in the e-terrasource Schema PDF
document.

1.1 Terminology
The following terminology is used throughout this document:
• Business model schema – This is a representation of a modeling
domain, such as a power system, organization chart, or solar system.
In the context of this document, the business model schema is
expressed as a set of entities, attributes, and relationships between
entities — very similar to a Unified Modeling Language (UML) static
model diagram or class diagram. In other contexts, the term “domain
model” is sometimes used, although this document purposely avoids
that term.
• Common Information Model (CIM) – CIM is an industry standard
power system model, expressed in UML. The specific standard is
International Electrotechnical Committee (IEC) 61970, which includes
documents related to power system control and communication.
Although e-terrasource can be used to express virtually any business
model, it is delivered with metadata that supports a CIM-based power
system model, with extensions to support Alstom Grid’s e-terra family
of products.
• Common Power System Model (CPSM) – This is an industry
standard CIM “profile” used for model exchange, for the purposes of
running power flow and state estimation applications.

Proprietary – See Copyright Page 1 Metadata Overview

e-terrasource Metamodel Guide
 • Deep copy – This term refers to the copying of a hierarchy of records.
Deep copy metadata determines which attributes and children records
should be included when a record is copied.
• Entity – This is a component that represents an object type in the
business model. In a UML static model or class diagram, an entity is
represented by a class. In a database, an entity is typically
represented by a table; for example, CIM defines a “substation”
entity/class/table.
• Inheritance – Inheritance is a useful organizational feature in business
models that allows an entity to “inherit” properties or relationships from
another entity (or entities). For example, ACLineSegment and
DCLineSegment are types of conductors, so both of them inherit the
properties and relationships of a conductor. ACLineSegment can also
define its own specific properties and relationships that are not
relevant to DCLineSegments.
The following terms are also used when discussing inheritance:
− Abstract Entity – An abstract entity is one that other entities
usually inherit properties and relationships from. In the previous
example, Conductor is an abstract entity. Abstract entities can also
inherit properties and relationships from other abstract entities.
Abstract entities are never actually created in the resulting business
model.
− Concrete Entity – A concrete entity is one that inherits from zero
or more abstract entities. In the previous example, ACLineSegment
and DCLineSegment are concrete entities.
If you draw a tree diagram depicting inheritance between entities,
the leaf (outermost) entities are typically the concrete entities, and
the non-leaf entities are typically abstract entities. There is one
exception to this case, which is discussed in section
2.2.1.9 metaEntityInheritance.
• Metadata – The common definition of metadata is that it is “data about
data”. Throughout this document, a distinction is made between the
“data about data” used at run time versus metamodeling time. The
term “metadata” is used when discussing the e-terrasource tables that
are used to hold run-time metadata.
• Metamodel – This term is used to describe metadata at modeling
time. The e-terrasource “metamodel” workspace is used to manipulate
the metamodel. When the metamodel changes are complete and
validated, they are exported to the metadata tables to be used at run
time.

Proprietary – See Copyright Page 2 Metadata Overview

e-terrasource Metamodel Guide
 • Profile – In terms of CIM, a profile is a set of classes, attributes, and
associations that are of interest for a particular system, application, or
other purpose. A profile defines a subset of the full CIM model, and
can define additional modeling details or restrictions. An example of a
profile is the Common Power System Model (CPSM) profile.
• Property – A property defines an attribute of an entity. For example,
an entity can have a “Name” property, which is a string. In a UML static
model or class diagram, a property is represented by an “attribute”. In
a database, a property is typically represented by a column in a table.
• Relationship – A relationship defines a connection between two
entities. In UML static model or class diagrams, this is represented by
an “association”. In a database, a relationship is typically represented
by a column that is a “foreign key” to another table.
• Run time – In this document, a distinction is made between the
timeframes at which metadata is used. At “modeling time”, the
e-terrasource administrator can make changes to the business model
schema. In order for the changes to come into effect and be used by
the UI, they must be exported to the e-terrasource tables that are used
at run time.
• Unified Modeling Language (UML) – This is a widely used language
for creating many types of models. The UML family of models includes
organizational diagrams, use case diagrams, activity diagrams, etc.
The most commonly used diagram is the static model or class
diagram, which models classes, attributes, and associations. CIM is a
UML representation of a power system model.
• Versioning – The schema of a business model is rarely static. The set
of entities, properties, and relationships is usually modified over time.
An important feature of e-terrasource is that it supports the tracking of
versions of a business model schema as it changes. e-terrasource
allows models created in an older schema version to be retrieved into
a newer schema version, while minimizing data loss.

1.2 Categories of Metadata

In the scope of this document, the metadata can be broken into several
categories:
• Business model metadata – This is metadata that defines a business
model schema. The schema contains entities that have properties and
relationships to other entities.
• Validation metadata – This is metadata that defines validation
sequences, modules, and individual validation rules and their
corresponding error messages.

Proprietary – See Copyright Page 3 Metadata Overview

e-terrasource Metamodel Guide
 • Deep copy metadata – This is metadata that defines the deep copy
operations that are available to modelers on the user interface tree
views.
• CIM profile metadata – This metadata is used to define the CIM
profiles that are configured in your e-terrasource installation.
The remaining types of metadata are managed in the Administrative
Explorer of the e-terrasource user interface. The metadata covered by the
Administrative Explorer includes:
• Import/export metadata
• Model types, model authority set types
• Custom attribute types
• States and state transitions
For more information about the Administrative Explorer, refer to the
e-terrasource User’s Guide.

1.3 Versioning
There are three main reasons that the business model schema changes
over time:
• New versions of industry standard models – As new versions of CIM
are released by the IEC, schema changes may need to be reflected in
the e-terrasource metamodel.
• New versions of Alstom Grid products – Since e-terrasource is the
modeling tool for the e-terra family of products, new product versions
may result in changes to the business model schema to support new
modeling requirements.
• Customer extensions – During deployment of a new system, or as
business requirements change over time, there are frequently
customer-specific changes to the business model schema.
e-terrasource is designed to accommodate changes to the business
model schema by supporting versioning of the schema over time. As
entities, properties, and relationships are added, removed, and modified,
e-terrasource fully supports evolution of the schema by handling
migration of model data from version to version.

Proprietary – See Copyright Page 4 Metadata Overview

e-terrasource Metamodel Guide
1.4 Metadata at Installation
When the e-terrasource database tier is installed, the installation
procedure populates the run-time metadata tables with an initial set of
metadata (from the csm_metadata_install.sql file). The metadata
delivered with the e-terrasource product creates a business model
schema that supports CIM, as well as Alstom Grid Energy Management
Systems. For this reason, the schema is named “CIM/EMS”.

e-terrasource

Metadata
Master Model
Tables
Tables
(Run Time)

Business Model MetaModel

Workspaces Workspace
(e.g., CIM/EMS) (Modeling Time)

Metadata
Installation
Script
(*.sql)

Figure 1: Metadata at Installation

Figure 1 depicts the use of metadata at installation time. The installation
process executes a metadata installation script that populates the run-
time metadata tables with version 1 of the CIM/EMS business model
schema. The information in the run-time metadata tables is used to
generate the master model tables (for holding model authority set data),
as well as workspace tables that implement CIM/EMS schema version 1.
At this point, there is usually a phase where customer extensions are
made to the business model schema. This typically includes such things
as adding entities, properties, or relationships, or even cosmetic changes
such as reordering properties, or changing their labels or descriptions.
During this initial phase (before any modeling work has begun), these

Proprietary – See Copyright Page 5 Metadata Overview

e-terrasource Metamodel Guide
 changes are made to version 1 of CIM/EMS in the metamodel. When the
initial phase of customer extensions is complete, an installation script is
exported and re-installation of the e-terrasource database tier is
performed. At this point, the business model schema CIM/EMS version 1
contains the standard product schema plus customer extensions. Now
workspaces can be created and modeling work can begin.
For a step-by-step description of updating installation metadata, refer to
the e-terrasource Metamodel Quick Start Guide.
It is important to note that, once a schema version has been installed
(generated), modifications to it are not allowed. Instead, a new schema
version must be created, as described in section 1.5 Upgrading Metadata.
For further details regarding the installation process, refer to the
e-terrasource Software Installation and Maintenance Guide.

1.5 Upgrading Metadata

Once modeling work has begun, it is clearly not desirable to re-install the
database tier to introduce new changes to the business model schema. At
this point, modifications to the schema require that a new schema version
be created (e.g., CIM/EMS version 2). It is not possible to make physical
changes to a schema version once it has been generated, so creation of a
new schema version is necessary.
When the business model schema requires modification (for example, you
want to add a new attribute), the technique for making changes to the
business model schema is virtually the same as making changes to your
business model:
1. Open a workspace and load the latest model authority set into it.
In this case, open a special metamodel workspace, which requires the
UseMetaModelWorkspace privilege.
2. Create a new project for your metamodel changes.
3. Modify the metamodel as desired.
Usually, this involves creating a new schema version by deep copying
the current schema version as the starting point.
4. After validating your changes, export them, creating an upgrade script.
Executing the upgrade script applies the changes to the run-time
metadata tables. You may want to test the upgrade script against a
development copy of e-terrasource prior to upgrading a production
system.

Proprietary – See Copyright Page 6 Metadata Overview

e-terrasource Metamodel Guide
 Note: Generally speaking, it is not allowed to modify fields in the run-time
metadata that are used for identification purposes. If you want to make
such a change, you must first create a new record (by using a copy/paste
or clone operation) and then delete the old record. An error appears if you
attempt to modify such a field.

e-terrasource

Metadata
Master Model
Tables
Tables
(Run Time)

Business Model MetaModel

Workspaces Workspace
(e.g., CIM/EMS) (Modeling Time)

Metadata
Upgrade
Script
(*.sql)

Figure 2: Upgrading the Metadata

Figure 2 depicts the changes in the metamodel workspace with a green
“delta” triangle to represent the project. After successful validation, an
export is performed to create a metadata upgrade script. Execution of this
script updates the run-time metadata tables and master model tables as
necessary — usually creating a new business model schema version.
Now workspaces can be created (or re-created) to use the new schema
version. Models that were built on older schema versions can be loaded
into the new workspaces.
For a step-by-step description of updating metadata for an installed
system, refer to the e-terrasource Metamodel Quick Start Guide.
For more information about the modeling process, including workspaces,
projects, model authority sets, and the import/export process, refer to the
e-terrasource User’s Guide.

Proprietary – See Copyright Page 7 Metadata Overview

e-terrasource Metamodel Guide
1.6 More on CIM
Most uses of e-terrasource involve the representation of a power system
model, which means that CIM is at the core of the business model
schema. Although a detailed description of CIM is not in the scope of this
document, it is useful to know more about how the CIM UML model
relates to the e-terrasource metadata.

Figure 3: CIM Model and Profiles

Proprietary – See Copyright Page 8 Metadata Overview

e-terrasource Metamodel Guide
 Figure 3 indicates that the official CIM UML model is maintained by the
CIM working group as a *.eap file used by the Enterprise Architect UML
modeling tool. Although there are many UML modeling tools available, at
the time of this writing, Enterprise Architect is the tool of choice for the
working group.
The full CIM model is quite extensive, and only portions of the model are
relevant to specific applications. CIMTool (http://www.cimtool.org) is an
open source tool that, among other things, can be used to create
“profiles”, or subsets that conform to the larger CIM model. One of the
most commonly used profiles is called “Common Power System Model”
(CPSM), which defines the portions of CIM that are used for power
system model exchange for the purpose of supporting state estimation
and power flow applications.
Additional profiles can be created as needed. For example, if your system
configuration requires e-terrasource to export subsets of the model to a
variety of other applications, you may want to create additional profiles so
that only the required data is sent.

Figure 4: CIM Import Process

Proprietary – See Copyright Page 9 Metadata Overview

e-terrasource Metamodel Guide
 Figure 4 shows that, during the import process, the e-terrasource CIM
import/export server reads the desired profile as well as the run-time
metadata. This information is used to filter the contents of the CIM/XML
file so that only the entities, attributes, and relationships that are specified
in the profile and are also present in the run-time metadata are imported.
During CIM/XML exports, the bold arrows are reversed. The profile and
run-time metadata are used to filter the set of data that is exported from
the workspace to the CIM/XML file.

Proprietary – See Copyright Page 10 Metadata Overview

e-terrasource Metamodel Guide
2. Metamodel Components
2.1 Metamodel Overview
This chapter describes the metamodel in detail. It explains each
component and how it is used by e-terrasource.
When changes are required to the business model schema, use the same
techniques to modify it that you use to modify the business model itself:
1. Load the latest MetaModel model authority set into a metamodel
workspace.
You must have the UseMetaModelWorkspace privilege.
2. Create a project to hold your metamodel changes.
3. In most cases, make a deep copy of the latest schema version and
create a new schema version. Also, for each entity you want to modify,
make a deep copy of the latest entity version and create a new entity
version.
4. Modify the entities of the new schema version as desired using
e-terrasource tree views, grid views, and property sheets.
5. Validate the model and correct any validation errors.
6. Export the changes to create a metadata upgrade script.
7. Execute the upgrade script to apply the changes to the run-time
metadata tables, usually creating a new schema version. Then
(re)create workspaces referencing the new version.
8. Create a new MetaModel model authority set.
You should always have a MetaModel model authority set that
matches your run-time metadata tables.
In the figures of property sheets in the following sections, required fields
are marked with an asterisk (*) following the label (e.g., “ID*” indicates that
entry of the ID field is required).

Proprietary – See Copyright Page 11 Metamodel Components

e-terrasource Metamodel Guide
2.2 Metamodel Schema
As mentioned in section 1.2 Categories of Metadata, the metamodel is
broken into several types:
• Business model metadata
• Validation metadata
• Deep copy metadata
• CIM profile metadata

2.2.1 Business Model Schema

The business model schema portion of the metamodel is where the
majority of the modeling occurs. This is where the entities, properties, and
relationships that make up your business model schema are defined.

Proprietary – See Copyright Page 12 Metamodel Components

e-terrasource Metamodel Guide
 Figure 5: Business Model Schema

Proprietary – See Copyright Page 13 Metamodel Components

e-terrasource Metamodel Guide
 Figure 5 depicts the metamodel tables used to define the business model
schema. Explanations of the purpose of each table are shown in Table 1.

Table 1: Business Model Schema Tables

Table Purpose
metaNamespaceAuthority This table is used to specify the
organizations with authority to define the
business model or a portion of it. A
metaNamespaceAuthority owns one or more
metaSchemaNamespace records.
metaSchemaNamespace This table is used to separate entities,
properties, relationships, computations, and
enumerations into logical groupings based
on the organization that defines them. For
example, the CIM/EMS business model has
a namespace for CIM and a namespace for
Alstom Grid extensions.
metaSchema This table tracks each business model
schema and gives it an identifier, such as
“CIM/EMS”.
metaSchemaVersion This table is used to track new versions of a
business model schema over time. New
schema versions are created whenever the
structure of the schema changes — for
example, when adding, modifying, or
removing entities, properties, relationships,
and enumerations.
metaEntity This table is used to define an entity or object
type in the business model schema.
metaEntityVersion This table is used to track versions of entities
as the properties and relationships change
over time.
metaEntityGroup This table is used to organize entities into
logically related groups.
metaSchemaVerEntityVer This table is used to track which entity
versions belong to which schema versions.
metaEntityInheritance This table is used to define the parent
entities that a child entity inherits properties
and relationships from.
metaProperty This table is used to define properties on
entity versions.

Proprietary – See Copyright Page 14 Metamodel Components

e-terrasource Metamodel Guide
 Table Purpose
metaRelationship This table is used to define relationships
between two entities.
metaEnumType These tables are used to define
metaEnumMember enumerations (picklists) and their contents.
metaPropertyGroup This table is used to group related properties
together.
metaPropertyCondition This table is used to identify properties
whose enterability is conditional on another
property.
metaComputation This table is used to define the computations
that are referenced by computed properties.
metaEntityKey These tables are used to define the
metaEntityKeyProperty properties that are identifiers or keys for a
particular entity version.

2.2.1.1 metaNamespaceAuthority
The metaNamespaceAuthority table is used to specify organizations that
have authority to build the business model, or portions of it. Information
from this table does not appear in the e-terrasource UI.

Figure 6: metaNamespaceAuthority Property Sheet

The fields on this property sheet are:
• ID – This required field is the identifier for the organization that defines
the business model, or a portion of it.
• Description – This is an optional description field.

Proprietary – See Copyright Page 15 Metamodel Components

e-terrasource Metamodel Guide
2.2.1.2 metaSchemaNamespace
The metaSchemaNamespace table is used to separate entities,
properties, relationships, and enumerations into logical groupings based
on the organization that defines them. Information from this table does not
appear in the e-terrasource UI.

Figure 7: metaSchemaNamespace Property Sheet

The fields on this property sheet are:
• ID – This required field identifies the namespace.
• Description – This optional field can be used to provide a description
of the namespace.
• Sort order – This required field is used to control the order in which
the properties and relationships are listed on the database table
underlying each entity.
• Enabled/Disabled – If the namespace is disabled, none of the
entities, properties, or relationships referencing it are created in the
business model.
• Namespace authority – This required field identifies the parent
namespace authority that defines/controls the namespace.

Proprietary – See Copyright Page 16 Metamodel Components

e-terrasource Metamodel Guide
2.2.1.3 metaSchema
The metaSchema table is used to track information about each business
model schema. It is possible to create as many schemas as you like, but
keep in mind the following:
• Objects in one schema cannot reference objects in another schema.
For example, an entity in the schema “Solar System” cannot reference
anything in the schema “Organization Chart”.
• Entities must have names that are unique across all schemas. The
“Solar System” and “Organization Chart” schemas cannot both contain
an entity with the same name.
• A workspace references exactly one schema version. For example, a
workspace can reference only “Solar System version 3” or
“Organization Chart version 7”. If you want to change a workspace to
follow “Solar System version 4” instead of version 3, you must delete
the workspace and then re-create it, referencing “Solar System
version 4”.

Figure 8: metaSchema Property Sheet

The fields on this property sheet are:
• ID – This required field lets you provide an identifier for the business
model schema. If you load the schema provided by the e-terrasource
installation, the schema name is “CIM/EMS”. Once you have
generated a schema, you cannot change its ID. Instead, you can copy
it and rename the copy.
The ID of the schema appears in the e-terrasource UI in several
places, including the property sheets for workspaces, model types,
model authority set types and model authority sets, snapshots,
projects, templates, attribute types, states, import/export sequences,
and validation sequences.

Proprietary – See Copyright Page 17 Metamodel Components

e-terrasource Metamodel Guide
 • Description – The description is optional and does not appear in the
main e-terrasource UI.
• Privilege – This required field identifies the e-terrasource privilege
that is needed in order to modify the run-time schema. It does not
appear in the main e-terrasource UI. Users without this privilege
cannot perform tasks such as creating new versions of the schema.
Typically, this privilege should be granted only to superusers or
administrators. If no privilege is entered here, the “ReplaceSchema”
privilege is checked before allowing modifications to the run-time
schema.
2.2.1.4 metaSchemaVersion
The metaSchemaVersion table is used to track the versions of a business
model schema that are created over time.
e-terrasource does not allow a schema version to be modified after it has
been generated. Therefore, virtually all business model schema changes
require a new metaSchemaVersion to be created. Failure to do so results
in an error when you attempt to execute your upgrade script:
“Table <%table> version <%version> cannot have any physical
characteristics modified because it has already been generated”.
Creating a new schema version is easily achieved by performing a deep
copy/paste of the previous schema version.

Figure 9: metaSchemaVersion Property Sheet Showing Deep Copy

The fields on this property sheet are:
• Full name – This is the computed full name of the schema version.
• Schema – This is the metaSchema record that the
metaSchemaVersion is a child of.

Proprietary – See Copyright Page 18 Metamodel Components

e-terrasource Metamodel Guide
 • Schema version – The schema version is an integer version number.
Typically, you simply enter the next sequential integer when you create
a new version (e.g., 1, 2, 3...).
• Description – The description is optional and does not appear in the
main e-terrasource UI.
The schema ID and version appear together in the e-terrasource UI to
identify a business model schema version in several places, including the
property sheets for workspaces, model authority sets, and snapshots.
2.2.1.5 metaEntity
The metaEntity table is used to define entities in the business model. An
entity corresponds to a UML class in CIM. Entities “own” properties (UML
attributes) and can have relationships (UML associations) with other
entities.
An entity can be abstract, meaning that it is not intended to be physically
created. Instead, other entities are expected to inherit properties and
relationships from abstract entities. Database tables are created for each
non-abstract entity, and columns are created for each of its properties and
relationships.
e-terrasource does not allow an entity version to be modified after it has
been generated. Therefore, most changes to metaEntity records require a
new metaEntityVersion to be created. Failure to do so results in an error
when you attempt to execute your upgrade script:
“Table”<%table> version <%version> cannot have any physical
characteristics modified because it has already been generated”.
The fields that can be modified without creating a new entity version are
tagged below with “[Modifiable]”. If you change any other fields, a new
schema version must be created.

Proprietary – See Copyright Page 19 Metamodel Components

e-terrasource Metamodel Guide
 Figure 10: metaEntity Property Sheet
The fields on this property sheet are:
• ID – This is the identifier for the entity. This required string is used as
the e-terrasource table ID, so it appears in the UI wherever a table is
identified, such as in the Tables Explorer.
• Description – This is an optional description for the entity. It appears
in the UI as a tool tip when the cursor hovers over the entity/table in
the Tables Explorer. [Modifiable]
• Schema namespace – This required field is the namespace that
defines the entity. It does not appear in the e-terrasource UI, but it is
used to annotate the database table for the purpose of indicating the
source of the table.
• Package – This optional field can be used to provide additional
information about the source of the entity. In particular, the CIM model
is partitioned into packages of logically related entities. It is not used in
the e-terrasource UI. [Modifiable]
• Database table name – This field is required for non-abstract tables
and it contains the physical database table name. This name must not
be an Oracle or SQL Server reserved word. It is not used in the
e-terrasource UI.

Proprietary – See Copyright Page 20 Metamodel Components

e-terrasource Metamodel Guide
 • Abstract – If Yes, this entity is not physically created in the business
model. Instead, other child entities are expected to inherit its properties
and relationships. It is not used in the e-terrasource UI.
• Enabled/Disabled – If the entity is disabled, it is treated as if it was
not present in the business model. It is not used in the e-terrasource
UI.
• Auto query – This flag can be set to Yes or No, to indicate if the
e-terrasource UI should automatically query this table at startup or
when the workspace is opened. Typically, this is set to Yes only for
tables used by metaPropertyConditions. [Modifiable]
• Security type – An entity can use either row-level security or table-
level security. For further details on data security issues, refer to the
e-terrasource User’s Guide. [Modifiable]
• Entity group – Each entity can be grouped with other logically related
entities by assigning them to the same entity group. On the
e-terrasource UI, the entity is shown in the specified entity group on
the Tables Explorer. [Modifiable]
2.2.1.6 metaEntityVersion
The metaEntityVersion table is used to track the versions of an entity over
time as properties and relationships are added, removed, and modified.
e-terrasource does not allow an entity version to be modified after it has
been generated. Therefore, most changes require a new
metaEntityVersion to be created. Failure to do so results in an error when
you attempt to execute your upgrade script:
“Table <%table> version <%version> cannot have any physical
characteristics modified because it has already been generated”.
The fields that can be modified without creating a new entity version are
tagged below with “[Modifiable]”. If you change any other fields, a new
schema version must be created.
Creating a new entity version is easily achieved by performing a deep
copy/paste of the previous entity version.

Proprietary – See Copyright Page 21 Metamodel Components

e-terrasource Metamodel Guide
 Figure 11: metaEntityVersion Property Sheet Showing Deep Copy
A database table is created in the e-terrasource master schema for each
entity version. The table name is in the form
<tablename>_<entityversion>; for example, “ACLineSegment_2”.
The fields on this property sheet are:
• Full name – This is the computed full name of the entity version.
• Entity – This is the metaEntity record that the metaEntityVersion is a
child of.
• Entity version – The entity version is an integer version number.
Typically, you simply enter the next sequential integer when you create
a new version (e.g., 1, 2, 3...).
• Description – The description is optional. [Modifiable]
None of these fields appears in the main e-terrasource user interface.

Proprietary – See Copyright Page 22 Metamodel Components

e-terrasource Metamodel Guide
2.2.1.7 metaEntityGroup
The metaEntityGroup table is used to define logical groups to which
individual entities may be assigned. The groups can be nested within
other groups. The groups are used only for organizing the entities/tables
on the Tables Explorer in the e-terrasource UI, as shown below:

Figure 12: Nested Groups in Tables Explorer

The metaEntityGroup property sheet is shown below:

Figure 13: metaEntityGroup Property Sheet

The fields on this property sheet are:
• ID – This is the identifier for the entity group. This required string is
used as the label for the entity group on the Tables Explorer.
• Description – This is an optional description for the entity. It is not
used in the e-terrasource UI.

Proprietary – See Copyright Page 23 Metamodel Components

e-terrasource Metamodel Guide
 • Sort order – This field indicates the relative order of the entity group in
relation to other groups on the e-terrasource UI Tables Explorer. You
can manipulate the sort order value to change the ordering of entity
groups in the e-terrasource UI.
• Parent entity group – If the entity group should be nested under a
parent entity group, you can specify the parent entity group here.
• For Network – Set this field to Yes if the entity group is related to the
network subsystem.
• For SCADA – Set this field to Yes if the entity group is related to the
SCADA subsystem.
• For Generation – Set this field to Yes if the entity group is related to
the generation subsystem.
• For DTS – Set this field to Yes if the entity group is related to the DTS
subsystem.
2.2.1.8 metaSchemaVerEntityVer
The metaSchemaVerEntityVer table is an important table that identifies
which particular entity versions belong to each schema version. This is a
key table for tracking changes across schema versions.
It is important to remember to update this table when you want to modify,
add, or remove entities (tables) in a schema version.
2.2.1.8.1 To Remove an Entity from a Schema
1. Make a deep copy of the latest schema version to create a new
schema version.
2. Remove the metaSchemaVerEntityVer record for the entity in the new
schema version.
2.2.1.8.2 To Add an Entity to a Schema
1. Make a deep copy of the latest schema version to create a new
schema version.
2. Add a metaSchemaVerEntityVer record to connect the new entity
version to the new schema version.
2.2.1.8.3 To Modify an Entity in a Schema
1. Make a deep copy of the latest schema version to create a new
schema version.
2. Make a deep copy of the desired entity version to create a new entity
version.

Proprietary – See Copyright Page 24 Metamodel Components

e-terrasource Metamodel Guide
 3. Modify the metaSchemaVerEntityVer record to connect the new entity
version to the new schema version.

Figure 14: metaSchemaVerEntityVer Property Sheet

The fields on this property sheet are:
• Full name – This is the computed full name of the record.
• Schema version – This is the parent schema version that the entity
version belongs to.
• Entity version – This is the entity version that belongs to the parent
schema version.
Of course, it is possible for the same entity version to belong to multiple
schema versions if there are no changes to the entity. For example, the
ACLineSegment v1 entity version shown above can also belong to
schema version CIM/EMS v2 if there are no changes affecting
ACLineSegment.
None of these fields appears in the main e-terrasource UI.
2.2.1.9 metaEntityInheritance
The metaEntityInheritance table is used to specify a parent entity that a
child entity inherits properties and relationships from.
For example, Figure 15 shows that version 1 of the ACLineSegment entity
inherits from the Conductor entity. It is allowable for an entity to inherit
from multiple parent entities.
If the abstract entity Conductor defines attribute Attr1 and relationship
Rel1, and ACLineSegment defines attribute Attr2 and relationship Rel2,
the resulting business model contains an ACLineSegment table with
attributes Attr1 and Attr2 and relationships Rel1 and Rel2.

Proprietary – See Copyright Page 25 Metamodel Components

e-terrasource Metamodel Guide
 Figure 15: metaEntityInheritance Property Sheet
The fields on this property sheet are:
• Full name – This is the computed full name of the record.
• Entity version – This is the child entity version.
• Inherits from entity – This is the parent entity version that the child
inherits properties and relationships from.
• Enumeration property in parent entity – This field is typically null.
Refer to the information below about this field.
The parent entity must be part of the schema version that the child entity
version belongs to. So, in the example above, there must be both an
ACLineSegment and Conductor entity version in the schema version.
None of these fields appears in the main e-terrasource UI.
When upgrading a business model schema, e-terrasource currently does
not support modification of metaEntityInheritance records. If you want to
modify the inheritance of an entity, delete any unnecessary
metaEntityInheritance records and add any new ones that are needed.
Keep in mind that, if you modify an abstract entity, you should create new
versions of its child entities that inherit from the new abstract entity. For
example, if you create Conductor version 2, you should also create
ACLineSegment version 2 that inherits from Conductor version 2.
Normally, in an inheritance hierarchy, the concrete entities are the
outermost “leaf” entities. However, there are some cases where it is useful
to have abstract classes that are subtypes of a parent concrete class. An
example in the CIM/EMS model is the Switch entity and its subentities
(Breaker, Fuse, Disconnector, GroundDisconnector, Jumper,
LoadBreakSwitch). In this case, Switch is modeled as a concrete entity,
and each of the six subentities is modeled as an abstract class that

Proprietary – See Copyright Page 26 Metamodel Components

e-terrasource Metamodel Guide
 inherits from Switch. Furthermore, the inheritance “points” to a Switch
property that identifies the subentity’s type.

Figure 16: Example Use of Enumeration Property

In Figure 16, the inheritance specifies that Breaker version 1 (an abstract
entity) inherits from Switch version 1 (a concrete entity), and the
Switch.SwitchType property is used to identify the type of the Switch.
2.2.1.10 metaProperty
The metaProperty table is used to define the properties that belong to an
entity. These correspond to class attributes in UML and columns of a
database table.
e-terrasource does not allow an entity version to be modified after it has
been generated. Therefore, most changes to metaProperty records
require a new metaEntityVersion to be created. Failure to do so results in
an error when you attempt to execute your upgrade script:
“Table <%table> version <%version> cannot have any physical
characteristics modified because it has already been generated”.
The fields that can be modified without creating a new entity version are
tagged below with “[Modifiable]”. If you change any other fields, a new
schema version must be created.

Proprietary – See Copyright Page 27 Metamodel Components

e-terrasource Metamodel Guide
 Figure 17: metaProperty Property Sheet

Proprietary – See Copyright Page 28 Metamodel Components

e-terrasource Metamodel Guide
 The fields on this property sheet are:
• Full name – This is the computed full name of the property.
• ID – This required field is the identifier of the property. It is not used in
the e-terrasource UI.
• Entity version – This required field is the entity version to which the
property belongs. It is not used in the e-terrasource UI.
• Package – This optional field can be used to provide information
about the source of the property. In particular, the CIM model is
partitioned into packages of logically related entities and attributes. It is
not used in the e-terrasource UI. [Modifiable]
• Enabled/Disabled – If the property is disabled, it is treated as if it was
not present in the business model schema. It is not used in the
e-terrasource UI.
• Schema namespace – This required field is the namespace that
defines the property. It does not appear in the e-terrasource UI, but it
is used to annotate the database column for the purpose of indicating
the source of the property.
• UI label – This field is the label for the property. It is used in the
e-terrasource UI in property sheets and grid displays to label the
property. [Modifiable]
• Description – This field is the optional description of the property. It is
used in the e-terrasource UI property sheet displays as a tool tip for
the property. It is also used to annotate the database column.
[Modifiable]
• Default value – This optional field can be used to provide a default
value for the property. When new records are inserted, the
e-terrasource UI fills the property with a default value if one is
specified. [Modifiable]
• Unit of measure – This optional field indicates the units in which the
value should be entered (e.g., seconds, kilometers, ohms). It is used
on the e-terrasource UI property sheets and grid displays. [Modifiable]
• Required – This field indicates if entry of a non-null value for the
property is required or not. If a property is marked as “required”, the
e-terrasource UI displays an asterisk (“*”) after the property’s label.
When validation is performed, errors are reported if required properties
have not been entered. [Modifiable]

Proprietary – See Copyright Page 29 Metamodel Components

e-terrasource Metamodel Guide
 • Include when copying – This field can be set to Copy or Do Not Copy
to determine if the attribute should be included when a record is copied
or cloned in the e-terrasource UI. [Modifiable]
• User entry allowed – This field indicates whether entry of this
property from the e-terrasource UI is allowed or not. [Modifiable]
• Public access – This field indicates whether the property should be
made visible to users who otherwise have no access to the record. For
more information, refer to the Data Security section of the
e-terrasource User’s Guide. [Modifiable]
• Property group – This field indicates the name of the property group
that the property belongs to on e-terrasource UI property sheet
displays. If it is not provided, the property appears under the General
property group. [Modifiable]
• Sort order – This integer field indicates the relative order of the
property in relation to other properties in the same property group on
e-terrasource UI property sheet displays and grid displays. You can
manipulate the sort order value to change the ordering of properties in
the e-terrasource UI. If this field is set to 0, the property is not shown
on the UI.
Note that the sort order is relative to all of the properties and
relationships that are in the table, including inherited
properties/relationships. Therefore, you may need to review inherited
properties and relationships before deciding a sort order value. If
multiple properties/relationships in the same table have the same sort
order, a warning is logged during metamodel installation. It is
recommended that you leave gaps between sort order values, to avoid
renumbering sort order values if new properties/relationships are
added in the future. [Modifiable]
• Editor style – This field indicates that a non-default UI control should
be used for the property on the e-terrasource UI property sheet
display. [Modifiable]
• Database column name – This field is required for non-abstract
tables and contains the physical database column name. This name
must be a valid Oracle or SQL Server identifier, and it must not be a
reserved word. It is not used in the e-terrasource UI.
• Data type – This required field indicates the data type of the property.
• Enumeration type – This optional field indicates the name of a
metaEnumType record that should be used to limit the allowable user
entries for this property. This is used by the e-terrasource UI to
provide a picklist on property sheet and grid displays.

Proprietary – See Copyright Page 30 Metamodel Components

e-terrasource Metamodel Guide
 • Uses computation – This optional field indicates that the property is
computed, rather than entered by the user. For computed properties, it
contains a reference to a metaComputation record that provides the
computed value.
• String length – If the property’s data type is String, this field indicates
the maximum string length. Note that, for Oracle, the maximum string
length is 4000. If a String property is computed, you must still provide
a string length that specifies the largest expected computed value.
• Index type – This required field indicates whether a database index
should be created for the property or not for performance reasons.
Allowed values are:
− None – No index should be created.
− Unique – A unique constraint should be created, and each record
must have a unique value.
− NonUnique – An index should be created, but records can have
duplicate values.
• Validation expression – You can optionally provide a range
expression or regular expression that is used to validate user entry of
this attribute. Range expressions are used for numeric data types, and
regular expressions are used for character data types. [Modifiable]
2.2.1.10.1 Range Expressions
Allowable range expressions are:
Range Expression Meaning
[0–100] Matches values between 0 and 100 inclusive
(0–100) Matches values between 0 and 100 exclusive
(0–100] Matches values greater than 0 and less than or
equal to 100
[0–100) Matches values greater than or equal to 0 and
less than 100
1, 3, 5 Matches a specific comma-separated list of
values
The expressions support both integer and decimal values. Also, the
different types of range expressions can be combined.
For example, the following is a valid range expression:
1,3.14159,5,(6–11],(15–20],99.9

Proprietary – See Copyright Page 31 Metamodel Components

e-terrasource Metamodel Guide
2.2.1.10.2 Regular Expressions
A complete discussion of regular expressions is beyond the scope of this
document. Many resources to describe regular expressions are available
on the Internet. A brief description and some examples are given here.
A regular expression is used for pattern matching of strings. A regular
expression can contain literals and metacharacters.
Metacharacter Definition Example Sample Match
Pattern
^ Start of a string ^abc abc, abc123
$ End of a string abc$ abc, 123abc
. Any character a.c aac, abc, acc
| Alternation ab | cd ab, cd
{…} Explicit quantifier ab{4}c abbbbc
[…] Explicit character set a[bB]c abc, aBc
(…) Grouping of part of an (abc){2} abcabc
expression
* 0 or more of previous ab*c ac, abc, abbc,
expression abbbc
+ 1 or more of previous ab+c abc, abbc,
expression abbbc
? 0 or 1 of previous ab?c ac, abc
expression
\ Preceding one of the a\+c a+c
above, makes it a literal
instead of a
metacharacter

Useful escape characters are listed here:

Escape Character Description
\t Matches a tab
\r Matches a carriage return
\n Matches a new line
\040 Matches octal 040 (space). Any three octal
digits can be specified.
\x20 Matches hex 20 (space)
\u0020 Matches a four-digit Unicode character

Proprietary – See Copyright Page 32 Metamodel Components

e-terrasource Metamodel Guide
 Examples of character classes are listed here:
Character Class Description
. Matches any single character except \n
[aeiou] Matches any single character included in the set
within the brackets
[^aeiou] Matches any single character not included in the
set within the brackets
[0-9a-zA-Z] A hyphen can be used to specify a contiguous
range of characters
\w Matches any word character
\W Matches any non-word character
\s Matches any whitespace character
\S Matches any non-whitespace character
\d Matches any decimal digit
\D Matches any non-digit

2.2.1.11 metaRelationship
The metaRelationship table is used to define relationships between
entities. These generally correspond to class associations in UML and
foreign keys with referential constraints in a database.
If a relationship field does not point to a valid entity, a referential
constraint violation occurs. For more information about constraint
violations, refer to the e-terrasource User’s Guide.
e-terrasource does not allow an entity version to be modified after it has
been generated. Therefore, most changes to metaRelationship records
require a new metaEntityVersion to be created. Failure to do so results in
an error when you attempt to execute your upgrade script:
“Table <%table> version <%version> cannot have any physical
characteristics modified because it has already been generated”.
The fields that can be modified without creating a new entity version are
tagged below with “[Modifiable]”. If you change any other fields, a new
schema version must be created.
When creating a relationship between two entities, it is important to model
it correctly, to avoid potential conflicts with other relationships in both the
resulting database model and the transformation subsystem’s object
model.

Proprietary – See Copyright Page 33 Metamodel Components

e-terrasource Metamodel Guide
 Figure 18: Relationship Modeling
The figure above shows a parent entity (A) and a child entity (B). Assume
that an A can have zero or more B children. This scenario should be
modeled as a single metaRelationship under metaEntity B. Relationships
are always shown under the child entity on the Metamodel tree view.
In the resulting database model:
• Table A is created with a primary key column called “CSMMRID”.
• Table B is created with a primary key column called “CSMMRID”.
• Table B has a column called “MYPARENTAMRID” that is a foreign key
to Table A.

Figure 19: Database Representation

In the resulting transformation object model:
• Object A has a member called “MyChildBs” that is a collection of
references to its B children. The naming convention is
<EntityA>.<RoleB> (i.e., “A.MyChildBs”).
• Object B has a member called “MyParentA” that is a reference to its
A parent. The naming convention is <EntityB>.<RoleA> (i.e.,
“B.MyParentA”).

Figure 20: Transformation Object Representation

During metamodel validation, and when importing a new metamodel into
the transformation subsystem, checks are performed to ensure that the
metaRelationships that are modeled do not result in duplicate/conflicting
representations in either the database or the object representation.

Proprietary – See Copyright Page 34 Metamodel Components

e-terrasource Metamodel Guide
 In most cases, conflicts are caused by having multiple relationships that
result in duplicate <EntityA>.<RoleB> or <EntityB>.<RoleA>.
For example, the following is an improper model for the two VoltageLevel
records that an ACLineSegment is related to:

Figure 21: Duplicate/Conflicting Relationship Model

The model above results in two VoltageLevel.ACLineSegment members
and two ACLineSegment.VoltageLevel members.
By adjusting the RoleA and RoleB information on the two relationships, a
proper, non-conflicting representation can be modeled.

Figure 22: Non-Conflicting Relationship Model

The model above results in the following non-conflicting object
representation:
• VoltageLevel.Near_ACLineSegment
• VoltageLevel.Far_ACLineSegment
• ACLineSegment.NearVoltageLevel
• ACLineSegment.FarVoltageLevel

Proprietary – See Copyright Page 35 Metamodel Components

e-terrasource Metamodel Guide
 Figure 23: metaRelationship Property Sheet
The fields on this property sheet are:
• Relationship ID – This computed field uniquely identifies a
relationship between two entities.
• Description – This field is the optional description of the relationship.
It is used in the e-terrasource UI property sheets as a tool tip for the
relationship. It is also used to annotate the database column.
[Modifiable]
• Package – This optional field can be used to provide additional
information about the source of the relationship. In particular, the CIM

Proprietary – See Copyright Page 36 Metamodel Components

e-terrasource Metamodel Guide
 model is partitioned into packages of logically related entities and their
attributes and associations. It is not used in the e-terrasource UI.
[Modifiable]
• Entity A – This required field identifies one of the entities in the
relationship. In hierarchical relationships, entity A is the parent
metaEntity. The entity can be abstract or concrete.
If concrete child entity B has a relationship with abstract parent entity A
(which is inherited by concrete entities A1, A2, and A3), in the resulting
schema, entity B has a relationship with A1, A2, and A3, but validation
ensures that only one of the three is filled.
If abstract child entity B (which is inherited by concrete entities B1, B2,
and B3) has a relationship with concrete parent entity A, then B1, B2,
and B3 all have a relationship with entity A.
• Entity B – This required field identifies one of the entities in the
relationship. In hierarchical relationships, entity B is the child
metaEntityVersion. When the business model schema is generated,
the relationship is represented by a “foreign key” column from the child
entity B to the parent entity A. The entity can be abstract or concrete.
• Role A name – This used to describe entity A’s relationship with
entity B. The role A name is used as the unique column ID for the
foreign key column on the child table. It is not used in the
e-terrasource UI, but it plays an important role in the transformation
subsystem.
• Role B name – This is used to described entity B’s relationship with
entity A. It is not used in the e-terrasource UI, but it plays an important
role in the transformation subsystem. [Modifiable]
• Schema namespace – This required field is the namespace that
defines the relationship. It does not appear in the e-terrasource UI, but
it is used to annotate the database column for the purpose of
indicating the source of the relationship.
• Enabled/Disabled – If the relationship is disabled, it is treated as if it
was not present in the business model. It is not used in the
e-terrasource UI.
• UI label – This field is the label for the relationship. It is used in the
e-terrasource UI in property sheet and grid displays to label the
relationship. [Modifiable]
• Required – This field indicates if the entry of a non-null value for the
relationship is required or not. If a relationship is marked as “required”,
the e-terrasource UI displays an asterisk (“*”) after the relationship’s

Proprietary – See Copyright Page 37 Metamodel Components

e-terrasource Metamodel Guide
 label. When validation is performed, errors are reported if required
relationships have not been filled. [Modifiable]
• Include when copying – This field can be set to Copy or Do Not Copy
to determine if the relationship should be included when a record is
copied or cloned in the e-terrasource UI. [Modifiable]
• User entry allowed – This field indicates whether entry of this
relationship from the e-terrasource UI is allowed or not. [Modifiable]
• Property group – This field indicates the name of the property group
that the relationship belongs to on e-terrasource UI property sheet
displays. If it is not provided, the relationship appears under the
General property group. [Modifiable]
• Sort order – This field indicates the relative order of the relationship in
relation to other relationships in the same property group on
e-terrasource UI property sheet displays and grid displays. You can
manipulate the sort order value to change the ordering of relationships
in the e-terrasource UI. If this field is set to 0, the relationship is not
shown on the UI.
Note that the sort order is relative to all of the properties and
relationships that are in the table, including inherited
properties/relationships. Therefore, you may need to review inherited
properties and relationships before deciding a sort order value. If
multiple properties/relationships in the same table have the same sort
order, a warning is logged during metamodel installation. It is
recommended that you leave gaps between sort order values, to avoid
renumbering sort order values if new properties/relationships are
added in the future. [Modifiable]
• Database column name – This required field contains the physical
database column name. This name must be a valid Oracle or
SQL Server identifier, and it must not be a reserved word. It is not
used in the e-terrasource UI.
• Cardinality A – This field indicates the cardinality of entity A in the
relationship. It is not used in the e-terrasource UI. Choices are “One”
or “Zero or One”. [Modifiable]
• Cardinality B – This field indicates the cardinality of entity B in the
relationship. It is not used in the e-terrasource UI. Choices are “One”,
“One or More”, or “Zero or More”. [Modifiable]
• Delete action A – This indicates what action should be performed on
entity B when entity A is deleted. Choices are:

Proprietary – See Copyright Page 38 Metamodel Components

e-terrasource Metamodel Guide
 − Cascade – This choice indicates that, if parent entity A is deleted,
all child entity B records that point to entity A are deleted. This
option should be chosen if there is a hierarchical relationship
between A and B. For example, if entity B is a child of entity A (say,
on a tree view), you should set this field to “Cascade”. If you
choose “Restrict” instead, then an attempt to delete entity A fails if
there are any entity B children referencing it.
− Restrict – This indicates that parent entity A cannot be deleted if
there are any child entity B records that reference it. This option is
typically chosen if entity A is a reference table. In such a case, you
do not want the user to be able to delete an entity A if there are any
entity Bs referencing it.
− Set Null – This indicates that, if parent entity A is deleted, all child
entity B records that point to it have their pointer set to null. This is
typically used for peer-to-peer relationships, where it is valid for
entity A to exist without entity B, and vice versa.
• Delete action B – This indicates what action should be performed on
entity A when entity B is deleted.
− No Action – This indicates that, if child entity B is deleted, no action
is taken on parent entity A records. This is the only supported
action at this time. [Modifiable]
• Index type – This required field indicates whether a database index
should be created for the relationship or not for performance reasons.
Allowed values are:
− None – No index should be created.
− Unique – A unique constraint should be created, and each record
must have a unique value.
− NonUnique – An index should be created, but records can have
duplicate values.

Proprietary – See Copyright Page 39 Metamodel Components

e-terrasource Metamodel Guide
2.2.1.12 metaEnumType
The metaEnumType table is used to define enumeration types (picklists)
for the business model. Enumeration types can be referenced by
properties in order to constrain the entry of a property to a specified list of
allowable values.

Figure 24: metaEnumType Property Sheet

Enumerations result in the creation of database check constraints on
columns (properties) that reference them. Therefore, if you modify the
members of an enumeration, you must create a new version of every
entity that has a metaProperty that references the metaEnumType.
The fields on this property sheet are:
• ID – This is the identifier for the enumeration type. It is not used in the
e-terrasource UI.
• Description – This is a description of the enumeration type. It is not
used in the e-terrasource UI.
• Schema namespace – This required field is the namespace that
defines the enumeration type. It does not appear in the
e-terrasource UI.
2.2.1.13 metaEnumMember
The metaEnumMember table is used to list the members of an
enumeration type. The members of the enumeration type are used to
create a database check constraint on any properties (columns) that
reference the enumeration type. Therefore, if you add or remove
members of an enumeration, you must create a new version of every
entity that has a metaProperty that references the metaEnumType.

Proprietary – See Copyright Page 40 Metamodel Components

e-terrasource Metamodel Guide
 The fields that can be modified without creating a new entity version are
tagged below with “[Modifiable]”. If you change any other fields, a new
schema version must be created.
If a property referencing an enumeration has a value that does not match
any enumeration member, a check constraint violation occurs. For more
information about constraint violations, refer to the e-terrasource User’s
Guide.

Figure 25: metaEnumMember Property Sheet

The fields on this property sheet are:
• Full name – This computed field displays the full name of the
enumeration member.
• Enumeration type – This required field is the enumeration type to
which the member belongs.
• UI label – This required field is the label for the member that appears
on the e-terrasource UI in picklist controls. [Modifiable]
• Value – This is the value that is stored in the database, which may be
different from the UI label.
• Sort order – This field can be used to control the display order of the
enumeration members on the e-terrasource UI. If the sort order is not
provided, the members are sorted by the UI label. [Modifiable]
• Description – This optional field is a description of the enumeration
member. It is not used in the e-terrasource UI. [Modifiable]

Proprietary – See Copyright Page 41 Metamodel Components

e-terrasource Metamodel Guide
2.2.1.14 metaPropertyGroup
The metaPropertyGroup table is used to organize related sets of
properties. The set of properties and relationships that belong to a
property group controls the appearance of property sheet displays and
grid displays in the e-terrasource UI.

Figure 26: metaPropertyGroup Property Sheet

The fields on this property sheet are:
• ID – The identification of the property group. This is shown on the
entity’s property sheet display in the e-terrasource UI.
• Description – This is an optional description of the property group. It
is not used in the e-terrasource UI.
• Sort order – This field indicates the relative order of the property
group in relation to other property groups on e-terrasource UI property
sheet displays and grid displays. You can manipulate the sort order
value to change the ordering of property groups in the
e-terrasource UI. If this field is set to 0, the property group and all
properties/relationships within it are not shown on the UI.
• Parent property group – This field should be filled in if the property
group should be nested beneath a parent property group. The property
sheets on the e-terrasource UI allow property groups to be nested to
an arbitrary depth.
• For Network – Set this field to Yes if the property group is related to
the network subsystem.
• For SCADA – Set this field to Yes if the property group is related to
the SCADA subsystem.

Proprietary – See Copyright Page 42 Metamodel Components

e-terrasource Metamodel Guide
 • For Generation – Set this field to Yes if the property group is related
to the generation subsystem.
• For DTS – Set this field to Yes if the property group is related to the
DTS subsystem.
2.2.1.15 metaPropertyCondition
The metaPropertyCondition table is used to make the entry of a property
conditional on the value of another property. This feature is supported
only on property sheets in the e-terrasource user interface.

Figure 27: metaPropertyCondition Property Sheet

The fields on this property sheet are:
• Full name – This computed field displays the full name of the property
condition.
• Conditional property – This is the property for which data entry
should be conditional.
• Conditional on – This is the property that controls whether the
conditional property is enterable or not.
• Validation expression – This is the range expression or regular
expression that is applied to the “Conditional on” property value, to
determine if the Conditional property should be enterable or not.
In the example above, the ArchiveDirectory property can only be entered if
the EnableArchiving property has a value of 1.
For further information about range expressions and regular expressions,
refer to section 2.2.1.10 metaProperty.

Proprietary – See Copyright Page 43 Metamodel Components

e-terrasource Metamodel Guide
2.2.1.16 metaComputation
The metaComputation table is used to define SQL computations for a
variety of purposes. Most commonly, metaComputation is used to
compute a property’s value, as opposed to having a user enter its value.
Information from metaComputation is not directly used in the
e-terrasource UI.
The expression property of metaComputation must contain a valid Oracle
or SQL Server select statement that performs the computation (refer to
the examples shown below).

Figure 28: metaComputation Property Sheet

The fields on this property sheet are:
• ID – This required field is the identifier of the computation.
• Description – This is an optional description for the computation.
• Entity – This is the name of the entity that the computation applies to.
• Schema namespace – This is the namespace that defines or owns
the computation.
• Computation type – There are four computation types:
− Path name – This type of query returns the e-terrasource MRID
and corresponding “path name” for the records in a table.

Proprietary – See Copyright Page 44 Metamodel Components

e-terrasource Metamodel Guide
 The form of this query is:
select a.csmmrid, a.name || ‘ ‘ || b.name as
pathname from <%schema>.a join <%schema>.b on
a.bmrid = b.csmmrid
The tables that are part of the path name are joined, and the
<%schema> proxy is substituted with the workspace schema
name. The query must return exactly two columns: the
e-terrasource MRID and the computed path name. The MRID is
required to allow the result of this query to be joined to the rest of
the data in the table. A column alias must be used to name the
second column (e.g., “as pathname”).
− Other – This type of computation is used in several ways. When
used to support a calculated property, the computation must return
both the e-terrasource MRID and the calculated value. In this case,
it is virtually identical to the “Path name” computation type in that it
always returns two columns: the e-terrasource MRID and the
computed value, which must have a column alias.
The following example computes the “winding count” for a
transformer. It returns the e-terrasource MRID, and the second
column is the number of transformer winding children records
aliased as “windingcount”.
select pt.CsmMRID, count(tw.CsmMRID) as
windingcount from <%schema>.PowerTransformer pt
left outer join <%schema>.TransformerWinding tw on
nvl(tw.PowerTransformerMRID, 'null') = pt.CsmMRID
group by pt.CsmMRID
Another use for “Other”-type computations is to perform auto-
filtering on the Foreign Key (FK) editor in the e-terrasource user
interface.
Normally, when the FK editor is displayed, it lists all choices in the
target table because the filter defaults to “*” (asterisk).

Proprietary – See Copyright Page 45 Metamodel Components

e-terrasource Metamodel Guide
 With the auto-filter feature, the FK editor automatically sets the
filter to a computed value, which can be useful for limiting the list to
a relevant set of records.

When the FK editor is displayed, the user interface searches for

the existence of a calculated property whose ID is in the form
“ETSFKFilter_<rel>”, where <rel> is the relationship ID. If such a
property exists, its (calculated) value is used to initialize the filter
field on the FK editor.
You can search the metamodel for properties with IDs such as
“ETSFKFilter*” for working examples.
Another use is to support conditional records or calculated
properties for templates. For example, a template record could
reference the following calculation as its “Create QueryId”:
select <%controllable> from dual

Proprietary – See Copyright Page 46 Metamodel Components

e-terrasource Metamodel Guide
 The “<%controllable>” proxy refers to a template parameter
provided by the user. If the query evaluates to 1, the template
record is created. If the query evaluates to 0, the template record is
not created.
A template property may be calculated using a QueryId Reference,
as shown below:
select <%rating>*0.9 from dual
In this case, the “<%rating>” proxy refers to a template parameter
provided by the user. The user’s entry is multiplied by 0.9 and
returned as the resulting value for the calculated property.
For more information about using queries in templates, refer to the
e-terrasource User Guide.
− MRID from Path – This type of computation assumes that the
components of a record’s path name are provided, and it returns
the e-terrasource MRID of the record.
The form of this query is:
Select a.csmmrid from <%schema>.a join <%schema>.b
on a.bmrid = b.csmmrid where a.name=’<%1>’ and
b.name=’<%2>’
The tables that are part of the path name are joined, and the <%n>
proxies are substituted with the individual components of the path
name. The <%schema> proxy is substituted with the workspace
schema name.
MRIDFromPath queries are needed when a table is being queried
and for a single parent or child record, and that record is being
identified by its path name instead of an MRID. The user interface
does not require this ability, but it is possible that a WSDL client
might.
− Path from MRID – This type of query assumes that an
e-terrasource MRID is provided, and it returns the components of
the path name (as separate columns).
The form of this query is:
Select a.name, b.name from <%schema>.a join
<%schema>.b on a.bmrid = b.csmmrid where
a.csmmrid=’<%1>’
The tables that are part of the path name are joined, and the <%1>
proxy is substituted with the e-terrasource MRID. The <%schema>
proxy is substituted with the workspace schema name.
• Oracle Expression – This is the SQL expression that implements the
computation on Oracle. It should follow the pattern described above.

Proprietary – See Copyright Page 47 Metamodel Components

e-terrasource Metamodel Guide
 The computations should be tested for accuracy because a poorly
formed computation causes run-time errors when the table is
displayed on the e-terrasource UI.
• SQL Server Expression – This is the SQL expression that
implements the computation on SQL Server. It should follow the
pattern described above. The computations should be tested for
accuracy because a poorly formed computation causes run-time errors
when the table is displayed on the e-terrasource UI.
2.2.1.17 metaEntityKey
The metaEntityKey table is used to define the properties that make up a
key field for an entity.
The e-terrasource UI uses the “default long” entity key when displaying
the full name of an entity on displays such as grid views and the Foreign
Key editor.

Figure 29: metaEntityKey Property Sheet

The fields on this property sheet are:
• Full name – This is the computed full name of the entity key.
• Entity – This is the parent entity to which the key belongs.
• Key type – There are four key types:
− Default long – The default long key is the property that fully
identifies each record uniquely. The default long key is used as the
left-most column in grid displays, as well as the Foreign Key editor.
Also, the records in the table are ordered by the default long
identifier. Each entity should have one default long entity key,
which can be a computed property.

Proprietary – See Copyright Page 48 Metamodel Components

e-terrasource Metamodel Guide
 − Default short – The default short key may not identify a record
uniquely, but it does identify a child record uniquely under its
parent. The default short key is typically used on tree views so that
children records are uniquely identified under a parent.
− Long – This key type is used to define a key that fully identifies a
record uniquely but is not the default long key.
− Short – This key type is used to define a key that identifies a child
record uniquely under a parent but is not the default short key.
• Description – This is an optional description of the entity key.
2.2.1.18 metaEntityKeyProperty
The metaEntityKeyProperty table identifies the specific properties that
make up an entity key.

Figure 30: metaEntityKeyProperty Property Sheet

The fields on this property sheet are:
• Full name – This is the computed full name of the entity key property.
• Entity key – This required field is the parent entity key that the key
property belongs to.
• Property – This required field is the key property.
• Rank – This required field is the rank or order of the key property
within the key. If a key is made up of several properties, this field ranks
or orders the properties. Currently, e-terrasource supports only a
single metaEntityKeyProperty per metaEntityKey.

Proprietary – See Copyright Page 49 Metamodel Components

e-terrasource Metamodel Guide
2.2.2 Validation Schema
Figure 31 depicts the metamodel tables used to define validation
sequences, modules, and rules. Although the sequences and modules are
defined using traditional e-terrasource tree views, grid views, and property
sheets, a customized editor is used to model validation rules.

Figure 31: Validation Schema

Proprietary – See Copyright Page 50 Metamodel Components

e-terrasource Metamodel Guide
 Table 2: Validation Tables
Table Purpose
metaValSequence This table is used to define a validation
sequence. A validation sequence is made up
of a list of validation modules.
metaValModule This table is used to define a validation
module, which is a group of related validation
rules.
metaValSeqModule This table is used to define which modules
belong to which validation sequences. A
module can belong to more than one
sequence.
metaValPrerequisite This table is used to track modules that
cannot execute until a prerequisite module
completes.
metaValRule These tables are used to define an individual
metaValCheck validation rule.
metaValVariable
metaValEntity
metaMsgDef Used to define validation error messages
metaMsgDefText that are associated with validation rules.

Proprietary – See Copyright Page 51 Metamodel Components

e-terrasource Metamodel Guide
2.2.2.1 metaValModule
The metaValModule table is used to define validation modules. These
modules consist of a set of validation rules, and they can be a part of one
or more validation sequences.

Figure 32: metaValModule Property Sheet

The fields on this property sheet are:
• ID – This required field is the unique identifier of the validation module.
It appears on the Validation History display in the e-terrasource UI.
• Description – This optional field describes the module. It is not used
in the e-terrasource UI.
• Workspace only – If Yes, this module is performed only during
workspace validation.
• Project only – If Yes, this module is performed only during project
validation.
• Maximum error count – This field specified the maximum error count
before module validation is prematurely terminated.
• Method type – If the validation module is implemented by a C# .NET
method or database stored procedure, this picklist is used to identify
the type. The choices are Microsoft C# .NET, Microsoft Transact-SQL,
and Oracle PL/SQL.

Proprietary – See Copyright Page 52 Metamodel Components

e-terrasource Metamodel Guide
 • Method name – If the validation module is implemented by a C# .NET
method or database stored procedure, this field specifies the name of
the method or procedure.
2.2.2.2 metaValSequence
The metaValSequence table is used to define validation sequences. A
validation sequence is made up of a set of validation modules that are
executed, where each module consists of a set of validation rules. This
design promotes modularity of validation rules by allowing different
validation sequences to reuse modules.

Figure 33: metaValSequence Property Sheet

The fields on this property sheet are:
• ID – This required field is the unique identity of the validation
sequence. It appears in the Validation dialog box in the
e-terrasource UI.
• Description – This is an optional description of the validation
sequence. It appears in the Validation dialog box in the
e-terrasource UI.
• Schema – This identifies the business model schema that the
sequence applies to. It is not allowable to have a validation sequence
span multiple business model schemas. This field is used to filter the
Validation dialog box in the e-terrasource UI so only sequences
relevant to the workspace’s business model schema are shown.

Proprietary – See Copyright Page 53 Metamodel Components

e-terrasource Metamodel Guide
2.2.2.3 metaValSeqModule
The metaValSeqModule table is used to list the modules that belong to a
sequence. Information from this table is not directly used in the
e-terrasource UI.

Figure 34: metaValSeqModule Property Sheet

The fields on this property sheet are:
• Full name – This is the computed full name of the sequence and
module.
• Sequence – This required field is the parent validation sequence.
• Module – This required field is the name of the module that should
execute as part of the sequence.
• Discontinue on failure – If Yes, the validation sequence terminates if
this module produces any validation errors.
• Enabled/Disabled – If Disabled, the module is skipped when this
sequence is executed.
• Check required fields – If Yes, execution of this module also includes
a check to ensure that all required fields contain non-null values.

Proprietary – See Copyright Page 54 Metamodel Components

e-terrasource Metamodel Guide
2.2.2.4 metaValPrerequisite
The metaValPrerequisite table is used to list the prerequisites for a
particular validation module. A module does not execute until its
prerequisite modules have completed execution.

Figure 35: metaValPrerequisite Property Sheet

The fields on this property sheet are:
• Full name – This is the computed full name of the prerequisite
module.
• Sequence module – This is the sequence and module to which the
prerequisite applies.
• Prerequisite module – This is the prerequisite module. This module
must complete before the module identified by “Sequence module”
executes.
2.2.2.5 metaValRule Editor
The metaValRule table and its child tables (metaValCheck and
metaValVariable) are used to define validation rules. In order to provide a
more-intuitive user interface for defining validation rules, the e-terrasource
UI provides a validation rule editor that is tailored for managing the
information in these three tables.

Figure 36: Validation Rule Editor

Proprietary – See Copyright Page 55 Metamodel Components

e-terrasource Metamodel Guide
 In each row of the editor, there is a selection button that allows display
of the property sheet of each associated record.
The fields on this property sheet are:
• (Rule ID) – The rule editor shows the rule name in the upper left hand
corner of the Rule Editor display.
• Table – This required field identifies the modeled table (entity name) to
be associated with this validation rule. The property sheet button can
be clicked to display all of the attributes of the Validation Rule record.
The validation rule is considered to be violated when the rule is evaluated
as True. The “If” “Then” groupings are shown to provide a visual reminder.
A validation rule can have zero or more child Validation Check records.
The property sheet button at the end of each row can be clicked to display
all of the attributes of the Validation Check record. A separate line is
shown for each Validation Check record, displaying the following
information:

• The Expand button can be clicked to expand each validation check

entry to show detailed variable information.
• The check type can be toggled between Syntax, Compare, or Custom
Logic:
− A Syntax check is generally applied to a rule that only has a child
primary variable.
− A Compare check is generally applied to a rule with both a primary
and a secondary child variable record, and it identifies the type of
comparison to be made between the two variables.
− The number of variables expected for each Custom logic check is
dependent on the associated custom validation code and can have
zero, one, or two child variables.
Note: If the Custom logic check type is selected, the Validation
Check property sheet must be opened to specify the method name
to be used for processing of the rule. The form of this method
name is “class.function”, where class identifies the C# class name
(defaults to “CustomBusinessRules”) and function identifies the
member function of that class to be called for evaluating the rule.

• Use to toggle between null and left parentheses, to provide control

over the order in which AND and OR functions are evaluated.

• Use to negate the results of this check.

Proprietary – See Copyright Page 56 Metamodel Components

e-terrasource Metamodel Guide
 • Each validation check can have zero, one, or two child validation
variables defined for it. The first variable is defined as the “primary”
variable and the second, if it exists, is defined as the “secondary”
variable. A symbol and text box are shown to identify information from
the primary variable. The symbols can be one of:

− Value

− Column

− Reference

− Collection

− Column List

• Use the combo box to identify the type of comparison to

perform.
• A symbol and text box are also shown to identify information from the
secondary variable, if it exists.

• Use to toggle between null and right parentheses, to provide

control over the order that AND and OR functions are evaluated.

− Use to toggle between And, Or, and Null, to provide control

over the conjunction of the Boolean results of validation checks.
• A validation check can have zero, one, or two child Variable records.
The first is referred to as the “primary variable” and the second, if it
exists, is referred to as the “secondary variable”. The property sheet
buttons on the expanded variable form can be selected to display all of
the attributes of the Validation Variable record. A separate definition
box is shown for each Validation Variable record, displaying the
following information for each:
− “Primary” or “secondary” – The first variable should always be of
type “primary”, and the second variable should always be of type
“secondary”, if it exists.
− Modifier – Toggle between:
∗ Null

Proprietary – See Copyright Page 57 Metamodel Components

e-terrasource Metamodel Guide
 ∗ CountOfChildren – The value of the variable is an integer
representing the number of children records of the selected
type.
∗ RecordCount – The value of the variable is an integer
representing the number of records of the associated table or
entity in the database.
∗ StringLength – The value of the variable is the number of
characters in the text field identified by the column name.
− Allow Null – Toggle to True if the value of the variable is allowed to
be null.
− Variable Type – Toggle between:
∗ Value – The value of the variable is a defined numeric value.
∗ Column – The value of the variable is that provided in the
identified column attribute.
∗ Reference – The value of the variable is that provided in the
identified column of a parent or other referenced entity.
∗ Collection – The variable represents an array of values of child
records.
∗ Column List – The variable represents an array of values from
multiple columns of the associated table.
− Operator – The value field is followed by a variable operator (*, **,
+, -, or /) that defines an arithmetic operation to be performed on
the resulting value, using the associated operand value.
− Operand – Defines the value to be used for performing an
additional arithmetic operation on the resulting value of the variable
before evaluating the rule. For example, “/ 2” divides the resulting
value by 2 before performing the evaluation.
• The validation rule references a metaMsgDef record for use in creating
the text of the resulting error message if the rule evaluates as True
(violated).

Proprietary – See Copyright Page 58 Metamodel Components

e-terrasource Metamodel Guide
2.2.2.6 metaValRule
The metaValRule property sheet can be displayed in addition to the rule
editor for displaying all of the attributes in a property sheet form.

Figure 37: Validation Rule Property Sheet

The fields on this property sheet are:
• ID – This required field is the unique identifier of the validation rule. It
appears on the Validation History display in the e-terrasource UI.
• Description – This optional field describes the rule. It is not used in
the e-terrasource UI.
• Module – This required field is the parent validation module.
• Entity – This required field is the entity name (modeled table name) to
be associated with this validation rule.
• Message definition – This required field is the message definition to
be used for reporting errors associated with this rule.
• Enabled/Disabled – If Disabled, the rule is skipped when the module
is executed.
• Maximum error count – The maximum number of errors incurred by
this rule before terminating validation of this rule and continuing on to
processing of the next rule.

Proprietary – See Copyright Page 59 Metamodel Components

e-terrasource Metamodel Guide
2.2.2.7 metaValCheck
The metaValCheck table is used to define a single validation check
belonging to an encompassing validation rule.

Figure 38: Validation Check Property Sheet

The fields on this property sheet are:
• Full name – This is the computed full name of the validation check.
• Rule – This required field is the parent validation rule.
• Sort Order – This required field identifies the sort order for the
Validation Check records under the parent rule.
• Enabled/Disabled – If Disabled, the validation check is skipped when
the rule is executed.
• Check Type – Toggle between Syntax, Compare, or Custom Logic.
A Syntax check is generally applied to a rule that only has a child
primary variable.
A Compare check is generally applied to a rule with both primary and
secondary child variable records, and it identifies the type of
comparison to be made between the two variables.

Proprietary – See Copyright Page 60 Metamodel Components

e-terrasource Metamodel Guide
 The number of variables expected for each Custom Logic type
validation check is dependent on the associated custom validation
code and may have zero, one, or two child variables.
• Left paren – Toggle between null and left parentheses, to provide
control over the order that AND and OR functions are evaluated.
• Right paren – Toggle between null and right parentheses, to provide
control over the order that AND and OR functions are evaluated.
• Negate – Negate the results of this validation check for determining
the True or False status of this validation check.
• Conjunction – Toggle between And, Or, and Null, to provide control
over the conjunction of Boolean results of validation checks.
• Method Name – If the Custom Logic type is selected, the method
name is used to identify the C# class and member function to call to
perform the processing for evaluating this validation check. The form
of this method name is “class.function”, where class identifies the C#
class name (defaults to “CustomBusinessRules”) and function
identifies the member function of that class.
• Trigger Once – Special processing for a Custom Logic type validation
check. If this flag is set, the underlying code is presumed to iterate
through every row of the associated table and is called only once,
rather than once per row.

Proprietary – See Copyright Page 61 Metamodel Components

e-terrasource Metamodel Guide
2.2.2.8 metaValVariable
The metaValVariable table is used to define a single variable of a parent
validation check. Each validation check can have zero, one, or two
variables defined for it.

Figure 39: Validation Variable Property Sheet

The fields on this property sheet are:
• Full name – This required field is the unique identifier of the validation
variable. It appears on the Validation History display in the
e-terrasource UI.
• Check – This required field is the parent validation check.
• Precedence – Toggle between primary (always for the first variable)
and secondary (for the second variable, if it exists).
• Variable Type – Toggle between Value, Column, Reference,
Collection, or Column List:
− Value – This required field is the message definition to be used for
reporting errors associated with this rule.
− Column – The value of the variable is that provided in the identified
column attribute.

Proprietary – See Copyright Page 62 Metamodel Components

e-terrasource Metamodel Guide
 − Reference – The value of the variable is provided in the identified
column of a parent or other referenced entity. The reference
definition may encompass multiple individual references in the
format: Table1.Reference>Table2.Reference>…
− Collection – The variable represents an array of values of child
records.
− Column List – The variable represents an array of values from
multiple columns of the associated table.
• Type Modifier – Toggle between null, CountOfChildren, RecordCount,
or StringLength:
− CountOfChildren – The value of the variable is an integer
representing the number of children records of the selected type.
− RecordCount – The value of the variable is an integer representing
the number of records of the associated table or entity in the
database.
− StringLength – The value of the variable is the number of
characters in the text field identified by the column name.
• Property – The value to enter in this field is dependent on the variable
type setting. Following is a description of what value to enter based on
the following variable type settings:
− Value – The property field should be left blank or null.
− Column – The property field should contain the name of the column
of the associated table from which the value should be extracted.
− Reference – The property field should contain the name of a
column of a parent or other referenced entity from which the value
should be extracted.
− Collection – The property field should contain the string
“CSMMRID” to identify the column on the local table that is
referenced by children records.
− Column List – The property field should contain a comma-
separated list of column names on the associated table.
• Reference Property – The value to enter in this field is dependent on
the variable type setting. Following is a description of what value to
enter based on the following variable type settings:
− Value, Column, or ColumnList – The reference property field
should be left blank or null.

Proprietary – See Copyright Page 63 Metamodel Components

e-terrasource Metamodel Guide
 − Reference – The reference property field should contain a list of
references to a parent or referenced table in the form
“table1.columnreference>table2.columnreference>…”, where table
is the name of the referenced table, and columnreference is the
name of the column on the local table that references the parent or
referenced table. For example, a reference from a BusBarSection
to the Area1 attribute of the associated PermissionArea referenced
by the parent SubgeographicalArea would be defined as:
∗ Reference Property: BusBarSection.EquipmentGroup>
∗ EquipmentGroup.Substation>Substation.SubgeographicalRegion>
∗ SubgeographicalRegion.AreaOfResponsibility
∗ Property: Area1
− Collection – The reference property field should contain the name
of the reference in the form “childtable.parentcolumnreference”,
where childtable is the name of the child table to include in the
collection array, and parentcolumnreference is the name of the
column on that child record that references the associated table as
a parent.
• Operator – Toggle between null, *, **, +, -, or /. This defines an
arithmetic operation to be performed on the resulting value, using the
associated operand value.
• Operand – Defines the value to be used for performing an additional
arithmetic operation on the resulting value of the variable before
evaluating the rule. For example, “/ 2” divides the resulting value by 2
before performing the evaluation.
• Value – If the variable type is set to “Value”, this field contains the
numeric or string value of this variable.
• Substring start – If the resulting variable value is a string, this
attributes identifies an optional starting value for extracting a substring.
• Substring end – This attribute identifies an optional ending value for
extracting a substring.
• Allow null – Toggle to True if the value of the variable is allowed to be
null.

Proprietary – See Copyright Page 64 Metamodel Components

e-terrasource Metamodel Guide
2.2.2.9 metaMsgDef
The metaMsgDef table is used to define messages used for reporting
validation errors.

Figure 40: metaMsgDef Property Sheet

The field on this property sheet is:
• ID – This required field is the unique identity of the message.
2.2.2.10 metaMsgDefText
The metaMsgDefText table is used to define the localized message text
for validation errors. It is possible for the same message to have text
localized for different languages.

Figure 41: metaMsgDefText Property Sheet

The fields on this property sheet are:
• Full name – This is the computed full name of the message text.
• Message definition – This is the parent message definition that the
text belongs to.
• Language – This is the language to which the message text applies.
• Text – This is the actual message text, localized to the language. The
message text can contain certain proxy strings that are substituted as
follows:

Proprietary – See Copyright Page 65 Metamodel Components

e-terrasource Metamodel Guide
 <%table> Table name associated with this validation rule
<%pathname> Path name of the record (Data Row) being
evaluated against this rule
<%mrid> GUID value of the record (Data Row) being
evaluated against this rule
<%[n]action> Action value of nth (1 based) Validation Check
record
<%[n]checktype> Check Type of nth (1 based) Validation Check
record
<%[n]classname> Class Name of nth (1 based) Validation Check
record
<%[n]functionname> Function Name of nth (1 based) Validation
Check record
<%p[n]value> Value of primary variable of nth (1 based)
Validation Check record
<%p[n]column> Column name of primary variable of nth
(1 based) Validation Check record
<%p[n]table> Child or reference table name of primary
variable of nth (1 based) Validation Check
record
<%s[n]value> Value of secondary variable of nth (1 based)
Validation Check record
<%s[n]column> Column name of secondary variable of nth
(1 based) Validation Check record
<%s[n]table> Child or reference table name of secondary
variable of nth (1 based) Validation Check
record

2.2.3 Deep Copy Schema

Deep copy metadata is used to determine how hierarchical copy
operations should behave in the e-terrasource user interface.
In order to set up deep copy for a hierarchy of entities, first define a
metaDeepCopy for every entity in the hierarchy. Then, under the top-level
entity in the hierarchy, create one or more metaRecursiveCopy records to
copy its children. Then create metaRecursiveCopy records under the
children to copy grandchildren, repeating this process to the desired
depth.

Proprietary – See Copyright Page 66 Metamodel Components

e-terrasource Metamodel Guide
 By default, all properties and relationships are copied. To exclude a
particular property from being copied, you can set “Include when copying”
to No on the metaProperty, or create a metaExcludeProperty record under
the metaDeepCopy record.
Figure 42 depicts the deep copy metamodel tables.

Figure 42: Deep Copy Schema

Table 3: Deep Copy Tables

Table Purpose
metaDeepCopy This table is used to define a deep copy
operation for a particular entity.
metaExcludeProperty This table is used to specify which properties
should not be copied when a record is
copied in a deep copy operation.
metaRecursiveCopy This table is used to specify which children
records should be recursively copied in a
deep copy operation.

2.2.3.1 metaDeepCopy
The metaDeepCopy table is used to define the deep copy operations for
an entity.
In order to set up deep copy for a hierarchy of entities, first define a
metaDeepCopy for every entity in the hierarchy. Then, under the top-level
entity in the hierarchy, create one or more metaRecursiveCopy records to
copy its children. Then create metaRecursiveCopy records under the
children to copy grandchildren, repeating this process to the desired
depth.

Proprietary – See Copyright Page 67 Metamodel Components

e-terrasource Metamodel Guide
 The deep copy operations are available on tree views. Right-click a record
and choose Deep Copy to see a list of available deep copy operations for
the record.

Figure 43: metaDeepCopy Property Sheet

The fields on this property sheet are:
• ID – This required field is the unique identity of the deep copy
operation. It is shown on the context menu of e-terrasource UI tree
views under Deep Copy.
• Description – This is an optional description of the deep copy
operation. It is not used in the e-terrasource UI.
• Entity – This is the entity to which the deep copy operation applies.
• Show on UI – If Yes, this deep copy operation is made available on
the e-terrasource UI. This is typically set to No for recursive deep copy
operations that should not be available on the UI.
2.2.3.2 metaExcludeProperty
The metaExcludeProperty table identifies the properties that should not
be copied when a deep copy operation is performed. The information on
this table is not shown in the e-terrasource UI.
It is not necessary to create metaExcludeProperty records for
metaProperties that have “Include when copying” set to No. Such
properties are not copied during deep copy operations.

Proprietary – See Copyright Page 68 Metamodel Components

e-terrasource Metamodel Guide
 Figure 44: metaExcludeProperty Property Sheet
The fields on this property sheet are:
• Full name – This is the computed full name of the record.
• Deep copy – This is the name of the parent deep copy operation.
• Property – This is the name of the property that should not be copied
during the deep copy operation.
2.2.3.3 metaRecursiveCopy
The metaRecursiveCopy table identifies which children records should be
included when a deep copy operation is performed.
In order to set up deep copy for a hierarchy of entities, first define a
metaDeepCopy for every entity in the hierarchy. Then, under the top-level
entity in the hierarchy, create one or more metaRecursiveCopy records to
copy its children. Then create metaRecursiveCopy records under the
children to copy grandchildren, repeating this process to the desired
depth.
The information on this table is not shown in the e-terrasource UI.

Figure 45: metaRecursiveCopy Property Sheet

Proprietary – See Copyright Page 69 Metamodel Components

e-terrasource Metamodel Guide
 The fields on this property sheet are:
• Full name – This is the computed full name of the recursive copy.
• Deep copy – This is the parent deep copy that this child recursive
copy belongs to.
• Recursive deep copy – This is the deep copy that should be
recursively performed.
• Recursive relationship – This identifies the relationship between the
parent deep copy record and the child recursive deep copy record that
should be used when copying the children.

2.2.4 CIM Profile Schema

The metadata associated with CIM profiles is depicted below. For an
overview of CIM profiles, refer to section 1.6 More on CIM.

Figure 46: CIM Profile Schema

Table 4: CIM Profile Tables

Table Purpose
metaCIMProfile This table is used to define the
available CIM profiles.
metaCIMCustomTableMap This table is used to define non-
standard mappings between CIM
classes and e-terrasource entities.

Proprietary – See Copyright Page 70 Metamodel Components

e-terrasource Metamodel Guide
 Table Purpose
metaCIMCustomColumnMap This table is used to define non-
standard mappings between CIM
attributes/associations and
e-terrasource properties/relationships.
metaCIMProfileProperty Not currently used
metaCIMProfileRelationship Not currently used

2.2.4.1 metaCIMProfile
The metaCIMProfile table is used to define CIM profiles. Generally
speaking, a new CIM profile is created for the purposes of:
• Filtering the entities, properties, and relationships that should be
included in the CIM/XML file.
• Defining custom mapping for entities, properties, and relationships.
For this reason, it is typical to define a new CIM profile for each type of
external system that e-terrasource sends CIM/XML data to, or receives
CIM/XML data from.

Proprietary – See Copyright Page 71 Metamodel Components

e-terrasource Metamodel Guide
 Figure 47: metaCIMProfile Property Sheet
The fields on this property sheet are:
• ID – This required field must uniquely identify the profile.
• CIM version – This field holds a version string for the profile.
• Date of CIM version – This field holds the date that the profile version
was created.
• Profile type – The profile type can be CIM or ETS. ETS profiles are
used specifically for sending and receiving model data to and from the
transformation subsystem.
• Description – Enter an optional description of the profile.
• Metamodel file name – Enter the name of the RDFS file that defines
the entities, properties, and relationships that are included in the
profile.

Proprietary – See Copyright Page 72 Metamodel Components

e-terrasource Metamodel Guide
 • Metamodel base URI – Enter the URI that is used for the CIM/XML
namespace (e.g., xmlns:cim=”<Metamodel base URI>”).
• Metamodel language – Enter the language used for the metamodel
file name. Only RDF/XML is currently supported.
• Include comments – If Yes, CIM/XML exports include comments.
• XML encoding – Enter the XML encoding for the file (e.g., “utf-8”).
• Include metadata on full export – Full exports should include
metadata in the file header section. For information about how to
configure the namespace URI and prefix used for this metadata
information, refer to the e-terrasource Software Installation and
Maintenance Guide.
• Include metadata on incremental export – Incremental exports
should include metadata in the file header section. For information
about how to configure the namespace URI and prefix used for this
metadata information, refer to the e-terrasource Software Installation
and Maintenance Guide.
• All resources typed on incremental export – The standard CIM/XML
difference model requires that changes be untyped (i.e., rdf:type
omitted). This flag allows one to override this, and have type included
for all resources, including for changes.
• Serialize null values / Serialize default values – These flags are
used only if the profile type is “ETS”; they are ignored if the profile type
is “CIM”. Since the ETS profile type is used exclusively for sending
data to and receiving data from the transformation subsystem, these
flags should not need to be changed. The purpose of the flags is to
reduce the size of the ETS files for improved performance.
2.2.4.1.1 Import
On import, “Serialize null values” does not apply. The following table
explains the handling of “Serialize default values” on import.
Serialize Value in ETS File Result
Default
Values
Yes Not present The file does not reference the
property. If the property has a
default value, the default value is
inserted into the workspace.
Yes Null value The file explicitly contains a null
value, so a null value is inserted into
the workspace.

Proprietary – See Copyright Page 73 Metamodel Components

e-terrasource Metamodel Guide
 Serialize Value in ETS File Result
Default
Values
Yes Other value The file explicitly contains a non-null
value, so it is inserted into the
workspace.
No Null value The file explicitly contains a null
value, so a null value is inserted into
the workspace.
No Other value The file explicitly contains a non-null
value, so it is inserted into the
workspace.

2.2.4.1.2 Export
On export, both “Serialize default values” and “Serialize null values” are
considered as follows:
Serialize Serialize Value in Result
Default Null Workspace
Values Values
Yes Yes Null value The value is not exported to
the ETS file.
Yes Yes Default value The value is not exported to
the ETS file.
Yes Yes Other value The value is exported to the
ETS file.
Yes No Null value The null value is exported to
the ETS file.
Yes No Default value The value is not exported to
the ETS file.
Yes No Other value The value is exported to the
ETS file.
No No Null value The null value is exported to
the ETS file.
No No Default value The default value is exported
to the ETS file.
No No Other value The value is exported to the
ETS file.
No Yes Null value The value is not exported to
the ETS file.

Proprietary – See Copyright Page 74 Metamodel Components

e-terrasource Metamodel Guide
 Serialize Serialize Value in Result
Default Null Workspace
Values Values
No Yes Default value The default value is exported
to the ETS file.
No Yes Other value The value is exported to the
ETS file.
• Load at startup – If Yes, the profile is loaded when the CIM/XML
import/export service starts.
2.2.4.2 metaCIMCustomTableMap
The metaCIMCustomTableMap table is used to define non-standard
mappings between CIM classes and e-terrasource entities. In some
cases, the name of a class in the CIM/XML file does not exactly match the
e-terrasource entity ID, so a mapping must be defined.

Figure 48: metaCIMCustomTableMap Property Sheet

The fields on this property sheet are:
• Full name – This is the computed full name of the record.
• Profile ID – This is the profile for which the mapping is defined.
• CIM class – Enter the name of the CIM class.
• metaEntity – Enter the name of the corresponding e-terrasource
entity.
• Description – Enter an optional description of the mapping.

Proprietary – See Copyright Page 75 Metamodel Components

e-terrasource Metamodel Guide
2.2.4.3 metaCIMCustomColumnMap
The metaCIMCustomColumnMap table is used to define non-standard
mappings between CIM attributes/associations and e-terrasource
properties/relationships. In some cases, the name of an attribute or
association in the CIM/XML file does not exactly match the e-terrasource
property or relationship, so a mapping must be defined.

Figure 49: metaCIMCustomColumnMap Property Sheet

The fields on this property sheet are:
• Full name – This is the computed full name of the record.
• Profile ID – This is the profile for which the mapping is defined.
• CIM class – Enter the name of the CIM class.
• CIM attribute – Enter the name of the CIM attribute/association.
• Entity ID – Enter the name of the corresponding e-terrasource entity.
• Property/Relation ID – Enter the name of the corresponding
e-terrasource property/relationship.
• Description – Enter an optional description of the mapping.
2.2.4.4 metaCIMProfileProperty
The metaCIMProfileProperty table is not currently used.
2.2.4.5 metaCIMProfileRelationship
The metaCIMProfileRelationship table is not currently used.

Proprietary – See Copyright Page 76 Metamodel Components

e-terrasource Metamodel Guide
3. Metamodel Validation
After making changes to the metamodel, workspace validation should be
performed using the Validation toolbar button in the e-terrasource user
interface, as shown in Figure 47.

Figure 50: Workspace Validation

Validation errors are reported in the Validation Progress dialog box.
Clicking on a validation error message displays the property sheet of the
offending record so the error can be easily corrected. For more
information about model validation, refer to the e-terrasource User’s
Guide.

Figure 51: Validation Messages

Proprietary – See Copyright Page 77 Metamodel Validation

e-terrasource Metamodel Guide
 It is important to note that passing validation in the metamodel workspace
does not guarantee that the resultant installation or upgrade script
executes successfully (for more information, refer to chapter 5 Script
Execution).

Proprietary – See Copyright Page 78 Metamodel Validation

e-terrasource Metamodel Guide
4. Metamodel Exports
After successful validation of metamodel changes, a metadata installation
or upgrade script can be exported. It is important to note the differences
between the two.
• An upgrade script should be exported if you have model data in an
existing e-terrasource installation that you want to preserve. For
example, if you have model data in e-terrasource and you need to
modify the business model schema, you:
− Use the metamodel workspace to create a new schema version
(e.g., CIM/EMS version 2).
− Make your changes to the new schema version.
− Validate the changes.
− Export an upgrade script.
• An installation script should be exported if you do not have model data
that you need to preserve, and you plan to re-install the e-terrasource
database tier. In this case, you:
− Use the metamodel workspace to make changes to the existing
schema version (e.g., CIM/EMS version 1).
− Validate the changes.
− Export an installation script.
− Re-install the e-terrasource database tier using the new installation
script.

4.1 Exporting an Upgrade Script

The purpose of an upgrade script is to use the e-terrasource database
API to apply your business model schema customizations to the run-time
metadata tables. In most cases, this involves creating a new schema
version.
Before exporting an upgrade script, you should ensure that you have the
desired MetaModel model authority set and projects loaded into your
currently open workspace. Also, you should have successfully passed
metamodel validation.
It is important to note that a single upgrade script is created that
represents the changes in all of the projects in the workspace. For
example, if your workspace contains projects A, B, and C, where project A

Proprietary – See Copyright Page 79 Metamodel Exports

e-terrasource Metamodel Guide
 creates a record, project B modifies it, and project C deletes it, then the
upgrade script will be empty because the net effect of the three projects is
that there are no changes.
To export an upgrade script:
1. Select Export Workspace from the Export toolbar button.

2. Choose Metadata Upgrade Script, and click Next.

3. Choose the File or Local File export target.

The File target creates the script in the e-terrasource server export
directory. The Local File target creates the script on your local PC.

Proprietary – See Copyright Page 80 Metamodel Exports

e-terrasource Metamodel Guide
 4. Click the Edit button to view or change the file name parameters.

5. After clicking Finish, the Import/Export Progress dialog box is

displayed, as shown below.

If the export completes successfully, the upgrade script can be found

in the directory you specified in the Export dialog box.

Proprietary – See Copyright Page 81 Metamodel Exports

e-terrasource Metamodel Guide
4.2 Exporting an Installation Script
The purpose of an installation script is to use the e-terrasource database
API to load your business model schema (including customizations) into
the run-time metadata tables during installation of the e-terrasource
database tier. After exporting the installation script, you replace the
originally delivered metadata installation script and then re-install the
database tier.
Before exporting an installation script, you should ensure that you have
the desired MetaModel model authority set and projects loaded into your
currently open workspace. Also, you should have successfully passed
metamodel validation.
To export an installation script:
1. Select Export Workspace from the Export toolbar button.

2. Choose Metadata Installation Script, and click Next.

Proprietary – See Copyright Page 82 Metamodel Exports

e-terrasource Metamodel Guide
 3. Choose the File or Local File export target.
The File target creates the script in the e-terrasource server export
directory. The Local File target creates the script on your local PC.

Proprietary – See Copyright Page 83 Metamodel Exports

e-terrasource Metamodel Guide
 4. Click the Edit button to view or change the file name parameters.

5. After clicking Finish, the Import/Export Progress dialog box is

displayed, as shown below.

If the export completes successfully, the created installation script can

be found in the directory you specified in the Export dialog box.

Proprietary – See Copyright Page 84 Metamodel Exports

e-terrasource Metamodel Guide
 6. Finally, replace the csm_metadata_install.sql file that was delivered
with the e-terrasource product with the newly exported installation
script.
It must be called “csm_metadata_install.sql” in order for the installation
to use your new file.

4.3 Exporting a Validation Script

It is possible to completely replace the e-terrasource validation metadata
by exporting a metamodel validation script and executing it. Doing so
allows you to easily update the run-time validation metadata to apply or
test changes to validation rules. The script deletes all of the existing
validation metadata and then loads the new metadata using the
e-terrasource database API.
Before exporting a validation script, you should ensure that you have the
desired MetaModel model authority set and projects loaded into your
currently open workspace. Also, you should have successfully passed
metamodel validation.
To export a validation script:
1. Select Export Workspace from the Export toolbar button.

Proprietary – See Copyright Page 85 Metamodel Exports

e-terrasource Metamodel Guide
 2. Choose Metadata Validation Script, and click Next.

3. Choose the File or Local File export target.

The File target creates the script in the e-terrasource server export
directory. The Local File target creates the script on your local PC.

Proprietary – See Copyright Page 86 Metamodel Exports

e-terrasource Metamodel Guide
 4. Click the Edit button to view or change the file name parameters.

5. After clicking Finish, the Import/Export Progress dialog box is

displayed, as shown below.

If the export completes successfully, the created validation script can

be found in the directory you specified in the Export dialog box.

6. Finally, execute the SQL script in the e-terrasource master schema to

update the run-time validation metadata.

Proprietary – See Copyright Page 87 Metamodel Exports

e-terrasource Metamodel Guide
 7. After the update is complete, open the Services applet in the Windows
Control Panel, and restart the “e-terrasourceValidation” service.

4.4 Exporting Metamodel HTML Documentation

e-terrasource can produce an HTML document that describes a business
model schema version.
Before exporting the HTML document, you should ensure that you have
the desired MetaModel model authority set and projects loaded into your
currently open workspace. Also, you should have successfully passed
metamodel validation.
The HTML document can be viewed in any Web browser. The top portion
contains information about the schema and schema version. Then a list of
all entity versions that are part of the schema version is displayed.

Figure 52: Metamodel HTML Document – Contents

Clicking the name of an entity navigates to the section of the document
that contains detailed information about the entity version, as well as its
properties and relationships. For each property and relationship, the prefix
indicates the name of the entity where it originated. This makes it easy to
identify both the native and inherited properties and relationships on the
entity.

Proprietary – See Copyright Page 88 Metamodel Exports

e-terrasource Metamodel Guide
 Figure 53: Metamodel HTML Document – Entity Details
To export an HTML document:
1. Select Export Workspace from the Export toolbar button.

2. Choose Metadata HTML Document, and click Next.

Proprietary – See Copyright Page 89 Metamodel Exports

e-terrasource Metamodel Guide
 3. Choose the File or Local File export target.
The File target creates the script in the e-terrasource server export
directory. The Local File target creates the script on your local PC.

4. Click the Edit button to view or change the file name, schema name, or
schema version.

5. After clicking Finish, the Import/Export Progress dialog box is

displayed, as shown below.

Proprietary – See Copyright Page 90 Metamodel Exports

e-terrasource Metamodel Guide
 If the export completes successfully, the created HTML document can
be found in the directory you specified in the Export dialog box.

4.5 Dumping a Metamodel Project

Any projects that modify the standard product metamodel delivered with
e-terrasource should be dumped and stored for safekeeping purposes. In
fact, doing so is strongly recommended.
By doing so, if you install a new e-terrasource release in the future, you
can simply load the MetaModel project(s) to easily re-implement your
business model schema customizations.
To dump a Metamodel project, perform the following steps:
1. Locate the project on either the Loaded Projects section of the Home
Page or the Projects View.
2. Right-click the project, and choose Export from the context menu.

Proprietary – See Copyright Page 91 Metamodel Exports

e-terrasource Metamodel Guide
 3. Choose Dump Metamodel Project, and click Next.

4. Choose the File or Local File export target.

The File target creates the script in the e-terrasource server export
directory. The Local File target creates the script on your local PC.

5. Click the Edit button to view or change the file name.

Proprietary – See Copyright Page 92 Metamodel Exports

e-terrasource Metamodel Guide
 6. After clicking Finish, the Import/Export Progress dialog box is
displayed, as shown below.

If the dump completes successfully, the XML dump can be found in

the directory you specified in the Export dialog box.

4.6 Dumping a Metamodel Workspace

The contents of a MetaModel workspace can be dumped to an XML file
for several reasons:
• Safekeeping – The XML file can be stored in a source code repository
for safekeeping.
• Updating the transformation subsystem – If you have made changes to
your business model schema that affect the import/export of data
through the transformation subsystem, then you must dump the
metamodel in order to update the transformation subsystem.

Proprietary – See Copyright Page 93 Metamodel Exports

e-terrasource Metamodel Guide
 Before dumping the metamodel, you should ensure that you have the
desired MetaModel model authority set and projects loaded into your
currently open workspace. Also, you should have successfully passed
metamodel validation.
To dump the metamodel workspace:
1. Select Export Workspace from the Export toolbar button.

2. Choose Dump MetaModel, and click Next.

3. Choose the File or Local File export target.

The File target creates the script in the e-terrasource server export
directory. The Local File target creates the script on your local PC.

Proprietary – See Copyright Page 94 Metamodel Exports

e-terrasource Metamodel Guide
 4. Click the Edit button to view or change the parameters.

5. After clicking Finish, the Import/Export Progress dialog box is

displayed, as shown below.

If the export completes successfully, the created installation script can

be found in the directory you specified in the Export dialog box.

Proprietary – See Copyright Page 95 Metamodel Exports

e-terrasource Metamodel Guide
Proprietary – See Copyright Page 96 Metamodel Exports
e-terrasource Metamodel Guide
5. Script Execution
This chapter discusses the structure of the metadata upgrade and
installation scripts that are exported from the metamodel workspace. It
also describes common error conditions and how to avoid them.
It is educational to review the scripts so that you are familiar with how they
work and how errors are reported.
Scripts for Oracle are designed to be executed in the SQL*Plus utility by
typing “@<scriptname>” at the SQL*Plus prompt.

Caution: Alstom Grid strongly recommends testing installation and

upgrade scripts in a non-production copy of the e-terrasource database,
to ensure that the scripts work as expected.

5.1 Structure
A metadata upgrade script is structured so that it first creates all new
metadata objects, then modifies existing objects, and finally deletes
obsolete objects. The script also takes care to:
• Create parent objects before creating children objects
• Delete children objects before deleting parent objects
A metadata installation script is structured so that it creates all metadata
objects, taking care to create all parent objects before creating children
objects.

5.2 Stored Procedure Calls

The upgrade and installation scripts use the database stored procedure
API to modify the run-time metadata tables. Therefore, a typical script is
nothing but a sequential list of calls to stored procedures to create,
modify, or remove metadata.
In the case of upgrade scripts, each stored procedure is called with the ID
of the user that exported the script. Therefore, it is recommended that the
user have the “superuser” role in order to avoid failures related to
insufficient privileges.
For installation scripts, all stored procedure calls use the “superuser” user
because, during the installation process, no other users are present on
the system.

Proprietary – See Copyright Page 97 Script Execution

e-terrasource Metamodel Guide
5.3 Error Reporting
Each stored procedure called by the scripts returns a status code and a
localized error message. If a stored procedure returns anything other than
a successful status code, the error message is printed and the script is
immediately terminated without committing any changes. The error
message also indicates the line number in the script at which the error
occurred.
If all stored procedures are executed successfully, the changes are
committed.

5.4 Solutions to Common Problems

Table <table> version <ver> cannot have any physical characteristics
modified because it has already been generated
This error indicates that an upgrade script is attempting to make a
physical change to a table that has already been generated. To avoid this
problem, you must create a new schema version and a new entity version
for this table.
Modifying an abstract entity can be particularly error-prone. Suppose an
abstract entity “P” is inherited by three concrete entities: P1, P2, and P3.
If you add a new metaProperty to P, you must create new entity versions
of P1, P2, and P3, as well as P.
Taking this example a step further, suppose abstract parent entity “P” is
inherited by P1, P2, and P3, and abstract child entity “C” is inherited by
concrete entities C1 and C2. If a metaRelationship is added from entity C
to entity P, you must create new entity versions of C1 and C2, as well
as C.
User <user> does not have <priv> privilege
This error indicates that the user ID that was passed in the stored
procedure does not have the required privilege to modify the metadata. To
avoid this problem, users that export metadata upgrade scripts should
have the “superuser” role.
Customizations did not take effect
The most common reason that customizations do not take effect is
because the new entity version is not linked to the new schema version.
For example, users typically do remember to use deep copy to create a
new metaSchemaVersion “CIM/EMS version 2” and a new
metaEntityVersion “ACLineSegment version 2” — but they frequently
forget to update the metaSchemaVerEntityVer that links

Proprietary – See Copyright Page 98 Script Execution

e-terrasource Metamodel Guide
 metaEntityVersion ACLineSegment version 2 with metaSchemaVersion
CIM/EMS version 2.

Proprietary – See Copyright Page 99 Script Execution

e-terrasource Metamodel Guide