Aspen Basic

Engineering V7.0

SmartPlant® Mapping
User's Guide
Version: V7.0
July 2008
Copyright © 2007 – 2008 Aspen Technology, Inc. All rights reserved.

AspenTech®, Aspen Basic Engineering, the aspen leaf logo, and Plantelligence are trademarks or registered
trademarks of Aspen Technology, Inc., Burlington, MA.

All other brand and product names are trademarks or registered trademarks of their respective companies.

This document is intended as a guide to using AspenTech's software. This documentation contains AspenTech
proprietary and confidential information and may not be disclosed, used, or copied without the prior consent of
AspenTech or as set forth in the applicable license.

This documentation contains AspenTech proprietary and confidential information and may not be disclosed, used,
or copied without the prior consent of AspenTech.

ASPENTECH MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WIT RESPECT TO

THIS DOCUMENTATION, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
PURPOSE.

Aspen Technology, Inc.

200 Wheeler Road
Burlington, MA 01803-5501
USA
Phone: (781) 221-4300
Toll free: (888) 996-7001
Website http://www.aspentech.com
Audience

This guide provides information on how Aspen Basic Engineering data relates
to the SmartPlant Schema through mappings and how they can be adjusted.
It does not provide information on using the appropriate data modeling tools
in Aspen Basic Engineering (see the Class Library Editor help for more
information) or the SmartPlant Schema Editor (see the appropriate Intergraph
help or documentation). This guide is intended for system administrators or
configuration users that are well versed in the tools available from either
Aspen Technology or Intergraph.
This guide describes the assumptions, rules, and limitations imposed by the
Aspen Basic Engineering adapter on schema mapping. It also describes the
structure of the tool schema and how it is used by the authoring tool
SmartPlant adapter in support of publish and retrieve operations. The guide
does not provide a list of the classes, properties, or enum lists that are
mapped by the delivered Aspen Basic Engineering tool schema. You can
obtain this information by viewing the tool schema directly. The guide does
not describe the user interface of The Engineering Framework Schema Editor.
It is assumed that you are already familiar with the Schema Editor.

SmartPlant® Mapping User's Guide

Contents

Audience .................................................................................................................3

Schema Mapping: An Overview ...............................................................................6

General Information About Schema Mapping ..........................................................7

Aspen Basic Engineering SmartPlant Adapter...................................................... 7
Mapping Configuration .................................................................................... 7
Tool Schema Location ..................................................................................... 8
Mapping Rules and Limitations ......................................................................... 8
Rules for Mapping Documents and SmartPlant Foundation Revisions ............ 8
Rules for Property Naming ..................................................................... 8
Limitations of the Framework Schema ..................................................... 9
Map File Location and Definition Restrictions ............................................ 9

Objects and Relationships .....................................................................................10

MapClass .................................................................................................... 10
General............................................................................................. 11
Tool Schema Relationships .................................................................. 11
Mapping Relationships......................................................................... 11
MapProperty................................................................................................ 12
General............................................................................................. 12
Tool Schema Relationships .................................................................. 13
Mapping Relationships......................................................................... 13
MapEnumList ............................................................................................... 13
General............................................................................................. 13
Tool Schema Relationships .................................................................. 13
Mapping Relationships......................................................................... 14
MapEnum.................................................................................................... 14
General............................................................................................. 14
Tool Schema Relationships .................................................................. 14
Mapping Relationships......................................................................... 14

SmartPlant® Mapping User's Guide

Tool Schema Data Model Diagram .........................................................................15

General Information..............................................................................................16
Related Documentation ................................................................................. 16

Technical Support .................................................................................................17

Online Technical Support Center..................................................................... 17
Phone and E-mail ......................................................................................... 18

SmartPlant® Mapping User's Guide 5

Schema Mapping: An
Overview

Before modifying the mapping for Aspen Basic Engineering, you must
understand:
• The Aspen Basic Engineering software
• The Aspen Basic Engineering data model
• The delivered mapping for Aspen Basic Engineering
• How the delivered mapping for Aspen Basic Engineering works
• Framework schema modeling
• The Schema Editor
• The To Do List feature of Aspen Basic Engineering
The following are terms that are frequently referenced by this guide:
• Tool schema — Defines the Aspen Basic Engineering objects to be
published and/or retrieved and how they map to objects in the Framework
schema. The tool schema implements a mapping between the objects in
the Aspen Basic Engineering data model and the objects in the Framework
schema. Users who customize either the Aspen Basic Engineering data
model or the Framework schema may also need to customize the mapping
contained in the tool schema.
• Framework schema — Defines The Engineering Framework data model.
• Adapter — The Aspen Basic Engineering code module that supports the
Framework commands.
When you publish Aspen Basic Engineering data, the adapter extracts data
from the Aspen Basic Engineering database and converts it into a set of
objects and relationships that are compatible with the Framework schema.
These objects and relationships are defined in an .xml file, which is sent to
SmartPlant for further processing.

SmartPlant® Mapping User's Guide 6

General Information About
Schema Mapping

Aspen Basic Engineering

SmartPlant Adapter
Each authoring tool such as Aspen Basic Engineering has an adapter that
processes information during the publish and retrieve operations. One of the
adapter's functions is to map information between SmartPlant and the
particular authoring tool. The Aspen Basic Engineering adapter is a
component that belongs to Aspen Basic Engineering and requires installation
of Aspen Basic Engineering. Any communication between SmartPlant and
Aspen Basic Engineering is performed via this adapter, which sends
information to SmartPlant through the Common User Interface where the
user is shown the appropriate user interface and data available.
The adapter does not handle schema files directly, but uses them indirectly.
The schema files are used to define the retrieve map file, which is then used
by the adapter. Direct use of the schema files would mean that the adapter
accessed them directly to do its work. Both retrieve and publish operations
only work through map files.

Mapping Configuration
The Aspen Basic Engineering adapter uses the tool schema map file and the
Schema Editor, delivered with the Framework Schema Component, to perform
mapping operations between the Aspen Basic Engineering object structure
and the structure of objects in the Framework schema. The map files are
installed with Aspen Basic Engineering Setup. These files include all objects
that are mapped for SmartPlant (not all objects that exist in Aspen Basic
Engineering, not all properties, only those that can be of any relevance for
other applications that use SmartPlant). In accordance with the Aspen Basic
Engineering data model, the Schema Editor knows what Aspen Basic
Engineering object to put a property on.

SmartPlant® Mapping User's Guide 7

Tool Schema Location
The name of the Aspen Basic Engineering tool schema files are:
• pidmap.xml. Aspen Basic Engineering uses this file for retrieving
documents.
• eqdmap.xml. Aspen Basic Engineering uses this file for publishing
datasheets.
• pfdmap.xml. Aspen Basic Engineering uses this file for publishing PFDs.
These files must exist in the installation home folder of Aspen Basic
Engineering under UserServices/bin/EF/mapping. The mapping files should
be treated as installation files. Although using the Schema Editor it is
possible to change the content of the mapping files, the file name must
remain same.

Mapping Rules and Limitations

Schema mapping in Aspen Basic Engineering has some important rules and
limitations.

Rules for Mapping Documents and

SmartPlant Foundation Revisions
In Aspen Basic Engineering, a document object has various properties but
only the document type property is mapped to a document category
enumeration list in SmartPlant. A list of Aspen Basic Engineering documents
that can be published and retrieved is defined in the Framework schema and
can be viewed in the Schema Editor.
Also, Aspen Basic Engineering adapter supports mapping of SmartPlant
Foundation revisions. Whenever a Aspen Basic Engineering user creates a
new revision, the Framework Client calls a common dialog box in which the
user defines the revision schema and the revision number, this number is
saved in SmartPlant Foundation and SmartPlant Foundation returns this
number to Aspen Basic Engineering via the adapter.

Rules for Property Naming

The names of the properties in the Aspen Basic Engineering tool schema must
exactly match the names of the properties in the Aspen Basic Engineering
data model, including the case.

SmartPlant® Mapping User's Guide 8

Limitations of the Framework Schema
The retrieve map is updated directly from the contents defined in the
Framework schema; therefore, the following restriction on the Framework
schema exists: in rare cases, if an entry is removed from the Framework
schema, you may need to edit the retrieve map file to remove the deleted
entry. You should use the Schema Editor delivered with the Framework
Schema Component for this purpose.

Map File Location and Definition

Restrictions
You cannot change the location of the map files installed in the Aspen Basic
Engineering home folder. During publish and retrieve operations, the adapter
looks for the map file only in the Aspen Basic Engineering home folder.
Although it is possible to change the content of the mapping files through the
Schema Editor, the file names must remain the same.

SmartPlant® Mapping User's Guide 9

Objects and Relationships

This topic describes objects and object relationships that are relevant to the
Aspen Basic Engineering tool schema. Relationship descriptions reference
names shown in a diagram that represents the data model of the Aspen Basic
Engineering tool schema. For details, see Tool Schema Data Model Diagram.

MapClass
The MapClass object corresponds to the IMapClassDef interface in the Tool
Schema Data Model diagram. In general, there is a MapClass object in the
tool schema for each Aspen Basic Engineering class (ItemType) that needs to
be published or retrieved. MapClass is referred to as SPMapClassDef in the
Schema Editor user interface. The properties and relationships for a MapClass
object can be viewed in the Edit Map Class Definition dialog box.

SmartPlant® Mapping User's Guide 10

General
Property Description
UID The property value is required, must be unique, and the UID of a map
class must be <ClassName>_ZYQ, where ClassName is the item type
name of a corresponding item type in Aspen Basic Engineering data
model. For example, UID of the Motor class would be Motor_ZYQ.

Name The property value is required. This property designates the internal
class name of the Aspen Basic Engineering item type, exactly as defined
in the Data Model.

Select Criteria Not used on publish.

On retrieve this property specifies the interface and property to match to
the required type of object. When an object is retrieved, for example
Equipment, then using the class inheritance the most specific equipment
type matching this property and the Process Criteria will be created in
Aspen Basic Engineering.

Process Criteria On publish this property can be used to specify the required enumerated
type, overloading the default enummetadata specified in the tool schema.
On retrieve this property specifies the value of the retrieved objects type
to be matched with the Select Criteria and if a match is found to create
an object in Aspen Basic Engineering of the type specified in the UID.

Generalizations This class definition is a generalization of the specified class definition.

This is used for both publish and retrieve. The effective hierarchy defined
by this property and the Specialization is traversed from the selected
object and all properties defined in the hierarchy are published or
retrieved.

Specializations This class definition is a specialization of the specified class definition.

Tool Schema Relationships

Relationship Description
Map Properties The map properties associated with the MapClass object must be defined
and related to the MapClass object. The relationship name in the
diagram is MapClassMapProperties

Mapping Relationships
Relationship Description
Publish to This relationship must be set to a class in the Framework schema if this
SmartPlant Class class is to be published. When this relationship is set, an instance of the
target class is published for each instance of the source class in the
document being published. The relationship name in the diagram is
MapClassToClass.

Retrieve from The list of interfaces from which properties are to be retrieved must be
SmartPlant set if this class is to be used for retrieval. The relationship name in the
interface diagram is ClassToMapClass. This is not needed if no properties are to be
retrieved on this class.

SmartPlant® Mapping User's Guide 11

MapProperty
The MapProperty object corresponds to the IMapPropertyDef interface in the
Tool Schema Data Model diagram. In general, there is a MapProperty object
in the tool schema for each Aspen Basic Engineering property that needs to
be published or retrieved. Properties need only be mapped at the most
common level in the Generalization/Specialization hierarchy as long as the
Retrieve from SmartPlant interface is set for any object from which properties
are to be retrieved. The properties and relationships for a MapProperty object
can be viewed in the Edit Map Property Definition dialog box.

General
Property Description
UID The property value is required, must be unique. Generally the UID of a
map property has followed the naming system of
<CLASSNAME>.<PROPERTYNAME>_ZYQ. For example, UID of
Motor.ItemTag property would be Motor.Itemtag_ZYQ.

Name The property value is required. This property must be the same as the
internal name of the Aspen Basic Engineering attribute, as defined in the
Data Model.

Process Criteria The Process criteria are used when publishing properties of Aspen Basic
Engineering to specify that the type of the property, e.g. Enum or Object
such as Nozzle or Material Flow Specification, etc.
If the Process Criteria is set to Object, then a Schema object of the same
class definition as the type of object at the mapped property will be
created during publishing. However, you can specify the type of Schema
object to create by appending the class definition name as:
Object:ClassDefName

On retrieve this property is set to the value of the type specified at the
Select Criteria. E.g. @ABCD.
If the select criteria is IEquipment.EqType1then any items who are
related to the current object being retrieved and have the interface
IEquipment with the property EqType1 set to @ABCD will be retrieved
and set against this property.

Select Criteria The select criteria is used to specify a particular property value setting
required for the case where Aspen Basic Engineering has different objects
which map to only one object in the SmartPlant schema which has a
property setting to distinguish the objects in Aspen Basic Engineering.
This property is set to the formula
Interface:property=value
See the example of PipingSystem_ZYQ in the eqdmap.xml for publishing
NormalFlow

On retrieve this property specifies the interface and property of the type
of Schema object to map to this property as:
Interface.Property – e.g. IEquipment.EqType1

SmartPlant® Mapping User's Guide 12

Tool Schema Relationships
Relationship Description
Exposed by Map Every MapProperty object must be related to a MapClass object. The
Classes relationship name in the diagram is MapClassMapProperties.

Scoped by If the data type of the property is enumerated, the MapProperty object
Enumeration must be related to a MapEnumList object. Otherwise, this relationship is
not needed. The relationship name in the diagram is
MapPropertyMapEnumList.

Mapping Relationships
Relationship Description
Map Property to This relationship defines the property in the Framework schema to which
Property this tool property is to be published. If this relationship is not defined,
the property will not be published. The relationship name in the diagram
is MapPropertyToProperty.

Property to Map This relationship defines the property in the Framework schema from
Property which this tool property is to be retrieved. If this relationship is not
defined, the property will not be retrieved. The relationship name in the
diagram is PropertyToMapProperty.

MapEnumList
The MapEnumList object corresponds to the IMapEnumListDef interface in the
Tool Schema Data Model diagram. In general, there is a MapEnumList object
in the tool schema for each Aspen Basic Engineering enumerated list
associated with a property that needs to be published or retrieved. The
properties and relationships for a MapEnumList object can be viewed in the
Edit Map Enumerated List Definition dialog box.

General
Property Description
UID The property value is required, must be unique, characters are not case-
sensitive. UID of an enumerated list must be <EnumListName>_ZYQ.
For example, UID of the YesNo enum list must be YesNo_ZYQ.

Name The value of this property is the name of the Aspen Basic Engineering
enum list.

Tool Schema Relationships

Relationship Description
Scoped Map A MapEnumList object must be related to the MapProperty objects that it
Properties scopes. The relationship name in the diagram is
MapPropertyMapEnumList.

Contains A MapEnumList object can contain a variable number of MapEnum

objects. The relationship name in the diagram is MapEnumListMapEnum.

SmartPlant® Mapping User's Guide 13

Mapping Relationships
Relationship Description
Maps To To support the publish operation, a MapEnumList object should be related
to the corresponding enum list in Framework schema by means of the
Maps To relationship. The relationship name in the diagram is
MapEnumListToEnumList.

Maps From To support the retrieve operation, a MapEnumList object should be

related to the corresponding enum list in Framework schema by means of
the Mapped From relationship. The relationship name in the diagram is
EnumListToMapEnumList.

MapEnum
The MapEnum object corresponds to the IMapEnumDef interface in the Tool
Schema Data Model diagram. In general, there is a MapEnum object in the
tool schema for each Aspen Basic Engineering enumerated list entry that
needs to be mapped. The properties and relationships for a MapEnum object
can be viewed in the Edit Map Enumerated List Definition dialog box (the
same dialog box is used for MapEnumList objects.)

General
Property Description
UID The property value must be unique. UID of an enumerated list entry
follows the form <EnumListName>_ZYQ. For example, UID of the Yes
entry of the YesNo enum list would be YesNo_ZYQ.

Name The value of this property is a text setting of the Aspen Basic Engineering
enum list entry.

Select Criteria This property value is required and must be set to the enumeration value,
usually the same as the name.

Tool Schema Relationships

Relationship Description
Contained In Every MapEnum object must be related to a MapEnumList object. The
relationship name in the diagram is MapEnumListMapEnum.

Mapping Relationships
Relationship Description
Maps To This relationship defines the Framework schema enum value to which this
Aspen Basic Engineering enum value is to be published. If this
relationship is not defined, the enum value will not be published. The
relationship name in the diagram is MapEnumToEnum.

Maps From This relationship defines the Aspen Basic Engineering enum value to
which the Framework schema enum value is to be retrieved. If this
relationship is not defined, the enum value will not be retrieved. The
relationship name in the diagram is EnumToMapEnum.

SmartPlant® Mapping User's Guide 14

Tool Schema Data Model
Diagram
The diagram below shows a representation of the objects and relationships
that are relevant to the Aspen Basic Engineering tool schema. The rectangles
on the left side of the diagram represent objects within the tool schema. The
rectangles on the right represent objects within the Framework schema. The
relationships that connect objects on the left with objects on the right are the
mapping relationships. The map file contains both the tool schema objects
and the mapping relationships.

SmartPlant® Mapping User's Guide 15

General Information

This section lists any other documentation related to this Aspen Basic
Engineering release.

Related Documentation
In addition to this document, the following documents are provided to help
users learn and use the Aspen Basic Engineering applications:

Title Content
What’s New This guide provides an overview of new features and functionality within
the Aspen Basic Engineering application set and describes how to work
with Aspen Basic Engineering Projects within Aspen Basic Engineering and
within The Engineering Framework (SmartPlant)

Administrator This manual contains advanced details of Aspen Basic Engineering

Reference Manual applications and functionality. Contents include details of the Aspen Basic
Engineering processes applicable to a user with Administrative rights. The
following sections/functions are covered:

• Generating datasheets, (and using the Datasheet Definer) including

preparing datasheets in Microsoft Excel 2000/XP

• Using the Graphics Definer (including defining symbols and labels,

with worked examples and extracting legacy symbols and labels

• Using the Class Library Editor application

• Using the Rules Editor (and Knowledge Bases)

• Using the Bridge application

This document is not in general added to between major releases.
Functionality is liable to change and you should always consult the on-line
help for the most up to date information.

On-line Help A comprehensive set of help systems are also provided with Aspen Basic
Engineering. Help within specific applications (for example Bridge Help) is
available from the Help menu of the open application
A generic, self-contained Help system (detailing all Aspen Basic
Engineering applications, their use and interaction) is available by clicking
on the Help icon within the windows Start | Programs | AspenTech |
Aspen Engineering Suite | Aspen Basic Engineering path

SmartPlant® Mapping User's Guide 16

Technical Support

Online Technical Support

Center
AspenTech customers with a valid license and software maintenance
agreement can register to access the Online Technical Support Center at:
http://support.aspentech.com
You use the Online Technical Support Center to:
• Access current product documentation.
• Search for technical tips, solutions, and frequently asked questions
(FAQs).
• Search for and download application examples.
• Search for and download service packs and product updates.
• Submit and track technical issues.
• Search for and review known limitations.
• Send suggestions.
Registered users can also subscribe to our Technical Support
e-Bulletins. These e-Bulletins proactively alert you to important technical
support information such as:
• Technical advisories.
• Product updates.
• Service Pack announcements.
• Product release announcements.

SmartPlant® Mapping User's Guide 17

Phone and E-mail
Customer support is also available by phone, fax, and e-mail for customers
who have a current support contract for their product(s). Toll-free charges are
listed where available; otherwise local and international rates apply.
For the most up-to-date phone listings; please see the Online Technical
Support Center at:
http://support.aspentech.com

Support Centers Operating Hours

North America 8:00 – 20:00 Eastern time

South America 9:00 – 17:00 Local time

Europe 8:30 – 18:00 Central European time

Asia and Pacific Region 9:00 – 17:30 Local time

SmartPlant® Mapping User's Guide 18