To make integration more open and to support plug-and-play functionality, the set of document types that an authoring tool publishes and the set of document types that an authoring tool retrieves can be defined outside the tool adapter. Defining this metadata externally allows users to define new document types that the tool can publish and/or retrieve without triggering the need for software changes as long as the tool adapter already supports publishing or retrieving the types of data in the document types.
The following UML diagram includes the types of schema objects involved in externalizing this kind of tool metadata. The sections that follow describe these objects.
Class Definitions (ClassDef)
A class definition in the SmartPlant schema is the realization of a primary interface definition within a component schema.
Most applications use concrete class definitions to denote the existence of objects and use interface definitions (or abstract class definitions), if they are used at all, to identify the roles for the objects. The SmartPlant schema is based on a different approach where class definitions indicate that a primary interface definition (which identifies the existence of an object) is used by an authoring tool component (by a component schema).
As part of defining how the primary interface definition is used within a component schema, the class definition identifies the roles supported by a component schema for that object. The identification of the roles is done by the class definition realizing a subset of the interface definitions implied (directly or indirectly) by the primary interface definition. This set of realized interface definitions/roles defines the extent to which that object (primary interface definition) is supported by that software component (component schema).
The same primary interface definition, when used in a different component schema, can have a different class definition that realizes it.
Component Schemas (CompSchema)
A component schema is the subset of the overall SmartPlant schema that is supported by an application component (that is, an application or authoring tool that integrates with SmartPlant). An application that integrates with the framework may choose to have a single component schema that covers the entire set of data that application publishes or it may choose to break the data up into multiple component schemas.
The choice of a single component schema versus multiple component schemas is an application-specific decision. The factors that might lead to one decision versus the other are:
-
Whether the data has any seams (if no seams, then probably only one component schema)
-
Performance (smaller component schemas should result in better performance)
-
Manageability (smaller component schemas are individually more manageable – however, redundancy across component schemas may be management problem)
-
Documents produced (since data is published with documents)
After you make the required changes to the SmartPlant schema, you can use the Generate Component Schemas command to generate XML files of all component schemas, or use Generate Component Schema command to generate an XML file of a single component schema. When you select Tools > Schema > Generate Component Schemas, Schema Editor automatically begins generating all component schemas. To generate a single component schema, select Tools > Schema > Generate Component Schema, and then select the component schema you want to generate.
DocumentType Class Definition
The class definition associated with a publishable or retrievable document type.
EnumEnum Class Definition
Enumerated entry. Enumerated entries must be contained within an enumerated list and are always leaf nodes (do not contain other enumerations).
Enumerated Lists (EnumListType)
An enumerated list is a predefined list of possible values for a property. A simple list might contain a couple values (like Yes and No) whereas a complex list might have many values and may be part of a multi-level enumeration hierarchy.
Enumerated lists are property types, which means they can be used to scope property definitions. When an enumerated list scopes a property definition, that enumerated list defines the set of acceptable values for instances of that property definition (that is, for properties).
In the Schema Component, enumerated lists are instances of the EnumListType class definition and realize interface definition IEnumListType. Each enumerated list contains one or more enumerations (objects that realize IEnumEnum).
The enumerations for an enumerated list may be either enumerated entries (EnumEnum objects) or other enumerated lists. If enumerated lists are contained within other enumerated lists, the result is an enumeration hierarchy where the enumerated lists are branches in the hierarchy and the enumerated entries are leaf nodes within the hierarchy.
Since an enumerated list may be contained within another enumerated list, the EnumListType class definition not only realizes IEnumListType but also IEnumEnum.
The EnumListType class definition is shown in the diagram below.
Enumeration Hierarchies
When enumerated lists are contained within other enumerated lists, the result is an enumeration hierarchy. A typical enumeration hierarchy is show below.
Enumerated lists that are not part of enumeration hierarchies are considered to be single-level lists. An enumeration hierarchy is considered to be a multi-level list, where the number of levels is defined by the number of enumerated lists in the longest path through the hierarchy. For ConstructionStati, shown in the screen shot above, the number of levels is two (ConstructionStati and either Existing, Future, New or Undecided).
While most enumeration hierarchies in the SmartPlant schema are two or three levels deep, they can go much deeper. The equipment types hierarchy, for example, has seven levels.
The reasons for multi-level enumerated lists are:
-
To account for common semantics associated with branch nodes in the hierarchy
-
To allow for different tools having different levels at which they are able to specify the enumeration hierarchy.
The common semantics are illustrated by the Existing (branch) node in the ConstructionStati enumerated lists. All of the leaf nodes that branch from Existing are simply refinements of the semantics associated with Existing.
One tool may have only a semantic understanding of construction status at the “existing”, “new”, “future” level where another tool may differentiate between the different types of “existing.”
SPMapClassDef
Tool Class Definition
For every tool that integrates with SmartPlant, there should be one Tool object (an instance of the Tool class definition). This object and related objects are used to define the information specific to that tool, including the progID for the tool's adapter, the tool (map) schemas for that tool and the set of document types published and retrieved by that tool.
ToolSchema Class Definition
Every tool (map) schema file used to define mapping from the tool's schema to the SmartPlant schema and/or mapping from the SmartPlant schema to the tool's schema should be defined using an instance of the ToolSchema class definition.
Each ToolSchema object is related to the Tool object for its tool, to the DocumentType objects that are published and/or retrieved using the tool schema, and to each of the map class definitions (SPMapClassDef) for that tool schema.
InterfaceDef Instances
IClassDef Interface Definition
Primary interface definition for class definitions.
ICompSchema Interface Definition
Primary interface definition for component schemas
IDocumentType Interface Definition
For every class definition that corresponds to a type of document (that is published, retrieved and/or used for passing tombstones), there should be at least one DocumentType object. This DocumentType object should realize IDocumentType.
The IDocumentType interface definition is used to relate the document type to the tool schemas that are used for publishing and/or retrieving documents for this document type. While a document type may be related to multiple tool schemas for publishing and/or retrieving, it should be related to no more than one tool schema for a particular tool.
IEnumEnum Interface Definition
Primary interface for enumerated entries. Also realized by enumerated lists. Exposes properties and behavior of enumerations contained within an enumerated list.
IEnumMetadata Interface Definition
Class definitions that can be used to extend the definition of an enumerated entry or enumerated list should realize IEnumMetadata. This interface definition is used to relate the class definition to the enumeration by way of an EnumMetadata relationship.
IMapClassDef Interface Definition
Primary interface definition for tool’s (map) class and interface definitions.
ITool Interface Definition
For every tool that integrates with SmartPlant, there should be a Tool object that realizes the ITool interface definition.
This interface definition is used to:
-
Define the progID for the tool's adapter
-
Identify the tool schemas for that tool
-
Identify the tombstones document type
AdapterProgID Property Definition
The AdapterProgID property definition is used to identify the progID (for example, "MyApplication.MyAdapter") of the adapter for the Tool object. The software identified by this progID should support the required adapter interfaces (described elsewhere).
IToolSchema Interface Definition
For every tool schema that a particular tool supports, there should be one ToolSchema object. Each of these ToolSchema objects should realize IToolSchema.
The IToolSchema interface definition has relationships that identify:
-
The tool for the tool schema (ToolToolSchema)
-
The publishable document types that use the tool schema (PublishableDocTypes)
-
The retrievable document types that use the tool schema (RetrievableDocTypes)
-
The map class definitions for the tool schema (ToolInstantiates)
MenuCmd Instances
Generate Tool MetaDatas Command
The Generate Tool MetaDatas command is used to generate the metadata file for each Tool defined in the SmartPlant Schema. For each Tool defined, a file called <Tool>_Meta.xml is created (for example, SmartPlantPID_Meta.xml).
This file contains the <Tool> object as well as the <DocumentType> objects for the tool (one <DocumentType> object for each document type published and/or retrieved by the tool) and the <ToolSchema> objects for that tool. In addition, the <ClassDef> object for each document type and the <CompSchema> objects for those class definitions are also loaded into the generated file.
All of the relationships between these objects are also loaded into the generated XML file. However, although the EnumMetadata relationships between the <DocumentType> objects and the corresponding SmartPlant enumerations (<EnumEnum> or <EnumListType>) are included, the corresponding enumerations are not included. Likewise, the ToolInstantiates relationships between the <ToolSchema> objects and the <SPMapClassDef> objects are included, but the corresponding <SPMapClassDef> objects are not included.
Because the generated tool metadata file contains <ClassDef> and <CompSchema> objects, the tool metadata must be loaded into a container in a unique container composition and this container composition must be parented by the meta-schema container composition and not the schema container composition (in order to avoid UID conflict on the ClassDef and CompSchema objects - since those objects are loaded as part of the component schema).
Any IObject pointers to the <ClassDef> or <CompSchema> objects in the tool metadata container should not be passed to outside applications since these pointers are not the same as the corresponding objects in the schema container. For example, the <ClassDef> for PIDDrawing from the loaded SmartPlantPID_Meta.xml file will not have the same IObject pointer as the <ClassDef> for PIDDrawing from PIDComponent.xml.
The <ClassDef> and <CompSchema> objects are included in the Tool metadata file so that the SmartPlant Client can determine the component schema to load for a particular document type. The <EnumEnum>, <EnumListType> and <SPMapClassDef> objects are not included since the resolution of the relationships to these objects can be done after the component schema and tool schema have been loaded.
Menu Instances
Tools > Schema Menu
The Tools > Schema menu exposes the tool commands that apply to the Schema objects.
Tools Menu
The Tools menu exposes the various tool commands for each type of data supported by the Schema Editor (that is, MetaSchema, Schema, and so forth).
RelDef Instances
Componentization Relationship Definition
The Componentization relationship definition is used to tie a class definition (realizes IClassDef) to its component schema (realizes ICompSchema). Every class definition belongs to one and only one component schema. A component schema can contain an arbitrary number of class definitions.
Since a class definition can belong to only one component schema, the existence of a class definition depends on the component schema. If a new component schema is introduced, then every class definition for that component schema must be new and unique to that component schema.
Every class definition has one and only one primary interface (an interface definition, on the other hand, can be the primary interface for multiple class definitions). The many-to-one relationship definition between a class definition and a component schema and between a class definition and a component schema means that the class definition can be considered to be an intersection object between a primary interface and a component schema.
Although the cardinalities on the individual relationship definitions would allow an interface definition to be a primary interface for more than one class definition for a component schema, this is not allowed. Therefore, there can be only one class definition for a component schema that uses a particular interface definition as its primary interface.
DocTypeClassDef Relationship Definition
The DocTypeClassDef relationship definition relates a document type to the class definition used for documents of that document type. Each document type should be related to one and only one class definition and a particular class definition should not be related to more than one document type.
Document types are related to their enumerated entries using EnumMetadata relationships. A particular enumerated entry for a type of document can be related to multiple document types (for example, a P&ID document type enumeration can be related to multiple DocumentType objects). Therefore, the existence of a DocumentType object is driven by the existence of a class definition that is published/retrieved (that is, a DocTypeClassDef relationship), not by the existence of a document type enumerated entry.
EnumMetadata Relationship Definition
Enumerations (objects that realize IEnumEnum) can be described by other schema objects that realize IEnumMetadata.
An enumeration may be multiply-described by other schema objects or not described at all. Likewise, other schema objects may describe multiple enumerations or no enumerations.
The EnumMetadata relationship is used to extend the definition of an enumeration beyond the limited set of properties associated with the various enumeration property types. For example, this relationship, when it ends at an interface definition, defines the semantics that apply to the enumeration (for example, the enumeration Pump relates to IPump, which defines the property definitions and relationship definitions that make up a pump).
PublishableDocTypes Relationship Definition
The PublishableDocTypes relationship definition relates a tool schema to the document types that are published using that tool schema. A given tool schema can be used for publishing any number of document types, and documents of a given document type may be published using any of a number of different tool schemas (that is, the relationship definition is many-to-many).
While a document type may be related to multiple tool schemas for publishing, it should be related to no more than one tool schema for a particular tool.
RetrievableDocTypes Relationship Definition
The RetrievableDocTypes relationship definition relates a tool schema to the document types that are retrievable using that tool schema. A given tool schema can be used for retrieving any number of document types and documents of a given document type may be retrieved using any of a number of different tool schemas (that is, the relationship definition is many-to-many).
While a document type may be related to multiple tool schemas for retrieval, it should be related to no more than one tool schema for a particular tool.
ToolInstantiates Relationship Definition
The ToolInstantiates relationship definition is used to tie the map class definitions (SPMapClassDef) to their tool schema (ToolSchema). Every map class definition should belong to one and only one tool schema. A tool schema can be related to multiple map class definitions.
ToolTombstonesDocType Relationship Definition
When the command is executed that checks whether objects previously identified by a given tool as moved have been subsequently deleted, all objects and relationships that no longer exist result in tombstone objects being created. These tombstone objects are placed in a document of the type identified by the ToolTombstonesDocType relationship for that tool.
Every tool should have one and only one document type that is used for these moved and subsequently deleted objects and relationships. Likewise, a document type identified as being one tool's tombstone document type should not be used as another tool's tombstone document type (that is, each tool should have its own unique tombstone document type object).
Since multiple document type objects can be related to the same enumeration (by EnumMetadata relationships), multiple document type objects used as tombstone document types can be related to the same enumeration.
ToolToolSchema Relationship Definition
The ToolToolSchema relationship definition relates a tool to each of the tool schemas that it supports. A given tool schema belongs to one and only one tool, whereas a tool can support any number of tool schemas.