SmartPlant Foundation

How to Configure the Consolidated Data Warehouse

Version 2018 (7.0)
September 2017
Copyright
Copyright © 2012-2017 Hexagon AB and/or its subsidiaries and affiliates. All rights reserved.
Including software, documentation, file formats, and audiovisual displays; may be used pursuant to applicable software license
agreement; contains confidential and proprietary information of Intergraph and/or third parties which is protected by copyright law,
trade secret law, and international treaty, and may not be provided or otherwise made available without proper authorization from
Hexagon AB.
Portions of the user interface copyright 2012-2014 Telerik AD.

U.S. Government Restricted Rights Legend

Use, duplication, or disclosure by the government is subject to restrictions as set forth below. For civilian agencies: This was
developed at private expense and is "restricted computer software" submitted with restricted rights in accordance with
subparagraphs (a) through (d) of the Commercial Computer Software - Restricted Rights clause at 52.227-19 of the Federal
Acquisition Regulations ("FAR") and its successors, and is unpublished and all rights are reserved under the copyright laws of the
United States. For units of the Department of Defense ("DoD"): This is "commercial computer software" as defined at DFARS
252.227-7014 and the rights of the Government are as specified at DFARS 227.7202-3.
Unpublished - rights reserved under the copyright laws of the United States.
Intergraph Corporation
305 Intergraph Way
Madison, AL 35758

Documentation
Documentation shall mean, whether in electronic or printed form, User's Guides, Installation Guides, Reference Guides,
Administrator's Guides, Customization Guides, Programmer's Guides, Configuration Guides and Help Guides delivered with a
particular software product.

Other Documentation
Other Documentation shall mean, whether in electronic or printed form and delivered with software or on Intergraph Smart Support,
SharePoint, or box.net, any documentation related to work processes, workflows, and best practices that is provided by Intergraph
as guidance for using a software product.

Terms of Use
a. Use of a software product and Documentation is subject to the Software License Agreement ("SLA") delivered with the software
product unless the Licensee has a valid signed license for this software product with Intergraph Corporation. If the Licensee has
a valid signed license for this software product with Intergraph Corporation, the valid signed license shall take precedence and
govern the use of this software product and Documentation. Subject to the terms contained within the applicable license
agreement, Intergraph Corporation gives Licensee permission to print a reasonable number of copies of the Documentation as
defined in the applicable license agreement and delivered with the software product for Licensee's internal, non-commercial
use. The Documentation may not be printed for resale or redistribution.
b. For use of Documentation or Other Documentation where end user does not receive a SLA or does not have a valid license
agreement with Intergraph, Intergraph grants the Licensee a non-exclusive license to use the Documentation or Other
Documentation for Licensee’s internal non-commercial use. Intergraph Corporation gives Licensee permission to print a
reasonable number of copies of Other Documentation for Licensee’s internal, non-commercial use. The Other Documentation
may not be printed for resale or redistribution. This license contained in this subsection b) may be terminated at any time and
for any reason by Intergraph Corporation by giving written notice to Licensee.
Disclaimer of Warranties
Except for any express warranties as may be stated in the SLA or separate license or separate terms and conditions, Intergraph
Corporation disclaims any and all express or implied warranties including, but not limited to the implied warranties of merchantability
and fitness for a particular purpose and nothing stated in, or implied by, this document or its contents shall be considered or deemed
a modification or amendment of such disclaimer. Intergraph believes the information in this publication is accurate as of its
publication date.
The information and the software discussed in this document are subject to change without notice and are subject to applicable
technical product descriptions. Intergraph Corporation is not responsible for any error that may appear in this document.
The software, Documentation and Other Documentation discussed in this document are furnished under a license and may be used
or copied only in accordance with the terms of this license. THE USER OF THE SOFTWARE IS EXPECTED TO MAKE THE FINAL
EVALUATION AS TO THE USEFULNESS OF THE SOFTWARE IN HIS OWN ENVIRONMENT.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 2

Intergraph is not responsible for the accuracy of delivered data including, but not limited to, catalog, reference and symbol data.
Users should verify for themselves that the data is accurate and suitable for their project work.

Limitation of Damages
IN NO EVENT WILL INTERGRAPH CORPORATION BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL INCIDENTAL,
SPECIAL, OR PUNITIVE DAMAGES, INCLUDING BUT NOT LIMITED TO, LOSS OF USE OR PRODUCTION, LOSS OF
REVENUE OR PROFIT, LOSS OF DATA, OR CLAIMS OF THIRD PARTIES, EVEN IF INTERGRAPH CORPORATION HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
UNDER NO CIRCUMSTANCES SHALL INTERGRAPH CORPORATION’S LIABILITY EXCEED THE AMOUNT THAT
INTERGRAPH CORPORATION HAS BEEN PAID BY LICENSEE UNDER THIS AGREEMENT AT THE TIME THE CLAIM IS
MADE. EXCEPT WHERE PROHIBITED BY APPLICABLE LAW, NO CLAIM, REGARDLESS OF FORM, ARISING OUT OF OR IN
CONNECTION WITH THE SUBJECT MATTER OF THIS DOCUMENT MAY BE BROUGHT BY LICENSEE MORE THAN TWO (2)
YEARS AFTER THE EVENT GIVING RISE TO THE CAUSE OF ACTION HAS OCCURRED.
IF UNDER THE LAW RULED APPLICABLE ANY PART OF THIS SECTION IS INVALID, THEN INTERGRAPH LIMITS ITS
LIABILITY TO THE MAXIMUM EXTENT ALLOWED BY SAID LAW.

Export Controls
Intergraph Corporation’s commercial-off-the-shelf software products, customized software and/or third-party software, including any
technical data related thereto (“Technical Data”), obtained from Intergraph Corporation, its subsidiaries or distributors, is subject to
the export control laws and regulations of the United States of America. Diversion contrary to U.S. law is prohibited. To the extent
prohibited by United States or other applicable laws, Intergraph Corporation software products, customized software, Technical Data,
and/or third-party software, or any derivatives thereof, obtained from Intergraph Corporation, its subsidiaries or distributors must not
be exported or re-exported, directly or indirectly (including via remote access) under the following circumstances:
a. To Cuba, Iran, North Korea, the Crimean region of Ukraine, or Syria, or any national of these countries or territories.
b. To any person or entity listed on any United States government denial list, including, but not limited to, the United States
Department of Commerce Denied Persons, Entities, and Unverified Lists, the United States Department of Treasury Specially
Designated Nationals List, and the United States Department of State Debarred List
(https://build.export.gov/main/ecr/eg_main_023148).
c. To any entity when Customer knows, or has reason to know, the end use of the software product, customized software,
Technical Data and/or third-party software obtained from Intergraph Corporation, its subsidiaries or distributors is related to the
design, development, production, or use of missiles, chemical, biological, or nuclear weapons, or other un-safeguarded or
sensitive nuclear uses.
d. To any entity when Customer knows, or has reason to know, that an illegal reshipment will take place.
e. Any questions regarding export/re-export of relevant Intergraph Corporation software product, customized software, Technical
Data and/or third-party software obtained from Intergraph Corporation, its subsidiaries or distributors, should be addressed to
PPM’s Export Compliance Department, 305 Intergraph Way, Madison, Alabama 35758 USA or at
[email protected]. Customer shall hold harmless and indemnify PPM and Hexagon Group Company for any
causes of action, claims, costs, expenses and/or damages resulting to PPM or Hexagon Group Company from a breach by
Customer.
Trademarks
Intergraph®, the Intergraph logo, Intergraph Smart®, SmartPlant®, SmartMarine, SmartSketch®, SmartPlant Cloud®, PDS®,
FrameWorks®, I-Route, I-Export, ISOGEN®, SPOOLGEN, SupportManager®, SupportModeler®, SAPPHIRE®, TANK, PV Elite®,
CADWorx®, CADWorx DraftPro®, GTSTRUDL®, and CAESAR II® are trademarks or registered trademarks of Intergraph Corporation
or its affiliates, parents, subsidiaries. Hexagon and the Hexagon logo are registered trademarks of Hexagon AB or its subsidiaries.
Microsoft and Windows are registered trademarks of Microsoft Corporation. MicroStation is a registered trademark of Bentley
Systems, Inc. Other brands and product names are trademarks of their respective owners.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 3

Contents
Preface .......................................................................................................................................................... 6
Customer Support ................................................................................................................................... 6
SmartPlant Foundation Product Documentation .................................................................................... 6

Consolidated Data Warehouse Overview ................................................................................................. 8

Summary of the shared object technology ............................................................................................. 8
The consolidated data warehouse object ............................................................................................... 9
Migration from shared object to CDW ................................................................................................... 12
Mapping authoring relationships to the CDW ....................................................................................... 12

Consolidation Implementation and Customization ............................................................................... 14

Consolidation implementation basics ................................................................................................... 14
Authoring relationship processing ......................................................................................................... 15
Classification handling .......................................................................................................................... 15
Map functions ........................................................................................................................................ 16
CDW customization .............................................................................................................................. 17
Correlate by name ................................................................................................................................ 22
Auto-correlation rules ............................................................................................................................ 25
Correlating an object using auto-correlation rules .......................................................................... 26
Managing auto-correlation rules ..................................................................................................... 27

How to Configure the CDW....................................................................................................................... 28

Extending the CDW model and mapping .............................................................................................. 28
Creating your own CDW schema ................................................................................................... 28
Using the demonstration CDW model as a starting point .............................................................. 30
Configuring SmartPlant Foundation to use the CDW ........................................................................... 30
Configuration to expose consolidated data ........................................................................................... 30
Managing and using CDW precedence rules ....................................................................................... 31
CDW precedence rules .................................................................................................................. 32
Creating and updating CDW precedence rules .............................................................................. 32
Adding CDW precedence rules to a schema object ....................................................................... 33

Consolidated Data Warehouse Model ..................................................................................................... 34

Additional interfaces for published documents in a CDW environment ................................................ 34
CDW extensions to the SmartPlant Schema for published documents ......................................... 34
CDW object schema ............................................................................................................................. 35
Base CDW object schema ............................................................................................................. 36
Source domain ............................................................................................................................... 37
CDW mapping schema ......................................................................................................................... 38
Base CDW mapping ....................................................................................................................... 38
Map function model ........................................................................................................................ 40
Additional map filtering ................................................................................................................... 40

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 4

 Contents

Authoring relationship model .................................................................................................................. 41

CDW Demonstration Model ...................................................................................................................... 42

The model ............................................................................................................................................. 42
Mapping ................................................................................................................................................ 44
Exposing the CDW data ........................................................................................................................ 45
Enabling CDW consolidation ................................................................................................................ 45

Index ........................................................................................................................................................... 46

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 5

Preface
This document details how to configure a Consolidated Data Warehouse (CDW) in SmartPlant®
Foundation, and it is one of a set of "How To" guides that describe how to configure the various
components of SmartPlant Foundation and the details of the underlying data model. It can be
used as a training guide to explore the configuration of the system and as a model reference
document.
This document is intended for users who have a good familiarity with the SmartPlant Foundation
Desktop Client and have a high understanding of schema modeling techniques.

Customer Support
For the latest support information for this product, use a web browser to connect to
http://hexagonppm.com/ppm-support (http://hexagonppm.com/ppm-support). Also, you can
submit any documentation comments or suggestions you might have on our support site.

SmartPlant Foundation Product Documentation

SmartPlant Foundation documentation is available as Help and as PDF files. To view printable
guides for SmartPlant Foundation, click Help > SmartPlant Foundation Printable Guides in
the software.
Hexagon PPM gives its customers permission to print as many copies of the delivered PDF files
as they need for their non-commercial use. Do not print the PDF files for resale or redistribution.

Model Configuration Guides

 How to Configure the Authoring and Data Warehouse Models - Provides information for
system administrators on how to configure the authoring and data warehouse models in
SmartPlant Foundation and describes the underlying data model.
 How to Configure API Services - Provides information for system administrators on how to
configure API Services in SmartPlant Foundation and describes the underlying data model.
 How to Configure Classified Objects - Provides information for system administrators on
how to configure classified objects in SmartPlant Foundation and describes the underlying
data model.
 How to Configure the Consolidated Data Warehouse (CDW) - Provides information for
system administrators on how to configure the CDW in SmartPlant Foundation and
describes the underlying data model.
 How to Configure Concurrent Engineering - Provides information for system administrators
on how to configure concurrent engineering in SmartPlant Foundation and describes the
underlying data model.
 How to Configure the Data Sheet Model - Provides information for system administrators on
how to configure the data sheet model in SmartPlant Foundation and describes the
underlying data model.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 6

 Preface

 How to Configure Document Management - Provides information for system administrators

on how to configure document management in SmartPlant Foundation and describes the
underlying data model.
 How to Configure the GUI Model - Provides information for system administrators on how to
configure the graphical user interface (GUI) model in SmartPlant Foundation and describes
the underlying data model.
 How to Configure the Infrastructure Model - Provides information for system administrators
on how to configure the infrastructure model in SmartPlant Foundation and describes the
underlying data model.
 How to Configure the Line List Model - Provides information for system administrators on
how to configure the line list model in SmartPlant Foundation and describes the underlying
data model.
 How to Configure Performance - Provides information for system administrators on how to
enhance the performance of SmartPlant Foundation.
 How to Configure the Progress Model - Provides information for system administrators on
how to configure the progress model in SmartPlant Foundation and describes the underlying
data model.
 How to Configure Reports - Provides information for system administrators on how to
configure reporting in SmartPlant Foundation and describes the underlying data model.
 How to Configure the Security Model - Provides information for system administrators on
how to configure the security model in SmartPlant Foundation and describes the underlying
data model.
 How to Set Up and Configure SmartPlant Foundation - Provides information for system
administrators on how to set up and configure SmartPlant Foundation after install.
 How to Configure the Workflow Model - Provides information for system administrators on
how to configure the workflow model in SmartPlant Foundation and describes the underlying
data model.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 7

SECTION 1

Consolidated Data Warehouse Overview

The Consolidated Data Warehouse (CDW) capability was introduced in SmartPlant Foundation
2009 R3 SP2 and released with custom code for correlation. CDW links together all data
published by the tools and exposes that data in the data warehouse; it is an alternative to the
shared object technology.
CDW is optional and is delivered as a demonstration model. We recommend
that it is used only on new projects; however, the SmartPlant Foundation Reconsolidation Utility
is available to help migrate an existing shared object technology implementation to a new CDW
implementation. The SmartPlant Foundation Reconsolidation Utility can also be used to help
reconsolidate existing data in a CDW or shared object implementation because of any changes.
For more information on the delivery and implementation of CDW and the SmartPlant
Foundation Reconsolidation Utility, please consult your support representative.

Summary of the shared object technology

In order to understand how the CDW is different from the shared object technology, we must
first understand how the shared object technology works to store and display information for
published objects.
For details of how the published data is stored in separate domains and linked through the
shared objects, refer to the How to Configure the Authoring and Data Warehouse Models guide.
Those details can be summarized in the following:
 Each design tool publishes documents from which the object data is loaded into domains
that are specific just to that tool.
 When a published object is created for the first time in the database, it is created in the tool's
domain and a shared object is also created in the shared domain. The published object is
linked to the shared object with a ComprisedOf relationship.
 When this object is published by another tool, another object will be created in that tool's
domain and is also related to the same shared object.
 Only the name and description are stored on the shared object, which limits query
mechanisms to simple find by name or ad hoc reports.
 The information presented to the user is dynamically generated from the ComprisedOf
objects in each of the publish domains, as summarized by the following diagram:

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 8

 Consolidated Data Warehouse Overview

 For properties shared across multiple tools, this dynamic generation presents the latest
information to the user, with respect to the different objects published, and is known as the
last in wins presentation. This data is presented after the query by name or ad hoc report.
You cannot display these properties in list views for regular queries.

 You can navigate from the shared objects to the published objects to view them in detail.
 You can review the inconsistencies of the published data, either from the shared object, or
from inconsistency reports.

The consolidated data warehouse object

The limitations presented by the shared object are overcome with the introduction of the
consolidated data warehouse (CDW) object.
 The CDW object replaces the shared object by a configurable set of class definitions, which
are based on the shared object definition in the initial demonstration model.
 Each class definition has fully-modeled interfaces, properties, and relationships that are
used to store data, and they are consolidated from the published objects.
 The SmartPlant schema is mapped to the CDW schema to control which properties or
relationships from published objects are consolidated to the CDW objects.
 In the default implementation, consolidation is limited to display the last published value of a
property shared across multiple tools.
 Correlation is limited to data published with the Same As relationship. For example, when
using the retrieve and publish operation. The SmartPlant Foundation Auto-Correlate
functionality is available for CDW using correlation by name.
 The structure of the CDW objects can be summarized by the following diagram:

 Queries are fully supported and can be used to find the CDW object in the database
because the CDW object has direct access to the published data, unlike the shared object.
 Custom list view column sets for viewing CDW object data are fully supported.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 9

 Consolidated Data Warehouse Overview

 In addition to consolidating properties or relationships from published objects, the CDW

objects are classified and related to the classification tree.
 Relationship navigation is now easier, either individually or by edges, for example, from
CDW object to CDW object, such as instrument to pipeline.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 10

 Consolidated Data Warehouse Overview

 Navigation to the related published objects, viewing inconsistencies, and running

inconsistencies reports are exactly the same as when using the shared object technology.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 11

 Consolidated Data Warehouse Overview

 The CDW objects can be enhanced over and above the storage of published data. For
example, the CDW schema can be extended to store data for purchasing or for construction
status management information. This can be done by adding interfaces with properties or
relationships.

Migration from shared object to CDW

A Consolidated Data Warehouse (CDW) is not mandatory; the existing shared object technology
is supported in parallel to the new CDW technology.
 The CDW is optional.
 A demonstration model, based on the shared object definition, is available and delivered as
load files with SmartPlant Foundation version 2009 R3 SP3 and later.
 The SmartPlant Foundation Reconsolidation Utility is available to help migrate an existing
shared object technology implementation to a new CDW implementation. It can also be used
to help reconsolidate existing data in a CDW or shared object implementation because of
any changes.
 The reconsolidation operation is achieved by the SmartPlant Foundation Reconsolidation
Utility software remodeling and remapping the data, removing all existing CDW or shared
objects and their ComprisedOf relationships, extracting all the published documents in the
order they were originally published, and reconsolidating each of them one at a time.

Mapping authoring relationships to the CDW

SmartPlant Foundation can be used as a simple data repository, an integrated data warehouse,
and an authoring tool within an integrated enterprise system. When SmartPlant Foundation is
used as an authoring tool, it operates differently from other authoring tools, such as
SmartPlant® P&ID, because it has access to data that is common to other SmartPlant
Foundation authoring applications and the data warehouse. For example, SmartPlant
Foundation might be configured to author equipment lists, which might be related to folders or
suppliers.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 12

 Consolidated Data Warehouse Overview

After this equipment is published to the data warehouse, it might be useful to have the published
data related to the same folders and suppliers. It is possible to configure mapping within the
CDW to publish these relationships, without having to actually retrieve and publish the folders
and suppliers themselves. This is possible because the folders and suppliers are created in
what is referred to as a Common domain as shown in the diagram below.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 13

SECTION 2

Consolidation Implementation and

Customization
This section provides a detailed explanation of how the mapping and consolidation process
takes place.

Consolidation implementation basics

The consolidate process is split into two parts:

1. Mapping
2. Loading
The input published file and instructions attached to the published document are provided by the
tool adapter. The tool data and tombstone files are rearranged into tagged items, which are
groups of tags and instructions that can be logically grouped together and committed to the
database. These tagged items are then transformed, based on the mapping. Specific mapping is
used by the interpreter to relate the SmartPlant schema to the CDW schema. The interpreter
uses that mapping to create a data file in the CDW format that is used to load the data into
SmartPlant Foundation using the internal SmartPlant Foundation loader. The mapping function
consists of an input adapter, output adapter, mapping class, and an interpreter. The role of the
interpreter is to ask the input adapter to read the input schema, decide what relevant mapping is
required, and send it to the output adapter.
For more information, see the section CDW customization (on page 17), which describes the
customization possibilities in more detail, including suggestions on how to establish precedence.
For example, PID data takes precedence over the PFD data for the instruments or for particular
properties on the instrument.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 14

 Consolidation Implementation and Customization

Authoring relationship processing

When publishing from a SmartPlant Foundation authoring application, such as the Line List
application, the system looks for any relationships using the new meta-schema relationship
definition SPFAuthoringRelDefToCDWRelDef. If any are found, the objects being published are
analyzed to see if any of them have instances of the AuthoringRelDefToCDWRelDef
relationship.
If any relationships exist, a new fifth publish file is created with a new interface instantiated on
the file that is used in the code to identify the relationship. The new interface is called
ISPFTEFCommonRels, and a new method definition on this interface, ProcessAuthoringRels,
does the following:
1. Reads the data file to determine the source component schema.
2. Reads the common relationships file looking for any relationships. This is an item, such as a
supplier, that is visible to both the SmartPlant Foundation authoring application and the data
warehouse.
a. Queries for published items using End1 and End2 of any of the relationships.
b. Performs a bulk expansion to get the ComprisedOf relationships for all the published
items found.
c. Determines which end is the published item and finds the CDW object.
d. Creates a relationship using the mapping between the CDW item and the common item.

Classification handling
This describes the implementation for CDW classification relationships.
The type properties on the published item are used to determine what classification the object
should have. The system finds all the EnumListType and EnumListLevelType properties on the
CDW object and expands the SPFEnumEnumObjClass relationship.
If a classification is found as the result of the expansion, a relationship is created between the
CDW object and the classification (SPFPrimaryClassification).
The logic is implemented on the ISPFClassifiedItem interface, so the CDW object class
definition must realize that interface, as well as the ISPFCDWClassifiedItem interface.
Sometimes the type properties are set on the published data and sometimes they are not. This
means the ISPFClassifiedItem interface is not required, because when the software cannot find
a classification, it will throw an exception.
Therefore, a way to know when to add the ISPFClassifiedItem interface to the code is needed. A
specific map function, SPFClassificationFromTyping, was written just to address this issue. Map
functions are pieces of process logic that can be run when the CDW object is created. If this
mapping exists, the object is related to the classification tree based on the Enum – Class Tree
mappings.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 15

 Consolidation Implementation and Customization

Map functions
It is possible to create a map function and relate the map function to the property mapping
relationship. This allows you to write code for the map function using the Method override
technique, as described in the section on Mapping customization found in CDW customization
(on page 17).

OOTB map functions

Below is an example of the out-of-the-box map functions.
<SPFMapFunctionDef>
<IObject UID="MF_SPFClassificationFromTyping"
Name="SPFClassificationFromTyping" />
<ISPFMapFunctionDef
SPFMapFunctionToInvoke="SPFClassificationFromTyping" />
</SPFMapFunctionDef>
This is related to a property mapping in the ATP schema as follows:
<Rel>
<IObject
UID="InstrumentType.InstrumentType.PropertyDefToPropertyDef"/>
<IRel UID1="InstrumentType" UID2="InstrumentType"
DefUID="PropertyDefToPropertyDef" OrderValue="0" IsRequired="False"/>
<IMapRel End1MapValue="PIDInlineInstrument" />
<ISchemaObj/>
</Rel>
<Rel>
<IObject
UID="InstrumentType.InstrumentType.PropertyDefToPropertyDef.MF_SPFClass
ificationFromTyping"/>
<IRel UID1="InstrumentType.InstrumentType.PropertyDefToPropertyDef"
UID2="MF_SPFClassificationFromTyping" DefUID="MappingToSPFMapFunction"
OrderValue="0" IsRequired="False"/>
<ISchemaObj/>
</Rel>

Map function implementation

The mapping classes tell the interpreter that there is a map function that needs to be run. The
interpreter calls the method definition ExecuteMapFunction on the ISPFMapFunctionDef
interface.
The property SPFMapFunctionToInvoke on the map function definition is compared, and, if it
matches any of the predefined mapping class values, the method is called.
The ExecuteMapFunction method returns a string that is used to set the property defined by the
mapping relationship. In the example, the map function passes the source object property value
for InstrumentType, and then the value returned is used to set the InstrumentType property on
the target object.
See Also
Consolidation Implementation and Customization (on page 14)
Consolidation implementation basics (on page 14)

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 16

 Consolidation Implementation and Customization

Authoring relationship processing (on page 15)

Classification handling (on page 15)
CDW customization (on page 17)
Correlate by name (on page 22)

CDW customization
Consolidation customization
The following method definitions have been defined against the new
ISPFCDWPublishedDocVersion interface:
 PerformMappingAndTransformation
 ConsolidateChunkOfObjects – Takes a set of items from the input source and decides
how to process them, filling the SmartPlant Foundation transaction. This method is now
obsolete and is no longer called during consolidation.
 ConsolidateChunkOfRels – Acts the same as the ConsolidateChunkOfObjects method.
This method is now obsolete and is no longer called during consolidation.
The methods defined below can be overridden once you have done the sideways override of
ISPFCDWPublishedDocVersion. See the Sideways override topic in the Interface Overrides
section of the SmartPlant Foundation Server Customization Guide for details.
 ConsolidateChunkOfTaggedItems – Takes a group of tagged items from the transformed
file and decides how to process them, adding the changes to the transaction object for
commit to the database.
 ConsolidateRels - Consolidates relationships in a tagged item group.
 ProcessConsolidatedDeleteInstructions - Processes delete instructions.
 TerminateCDWRelsForTerminateRels - Processes delete instructions for relationships.
 ProcessSameAsDeleteInstructions - Processes delete instructions for SameAs
relationships.
 ProcessConsolidatedUpdateInstructions - Processes update and update class
instructions.
 ProcessConsolidatedUnClaimedInstructions - Processes unclaim instructions.
 ProcessConsolidatedClaimInstructions - Processes claim instructions.
 ConsolidateDataObjects - Processes the tool data objects to determine the UIDs of the
CDW objects.
 ConsolidateCDWObjectsPropertiesAndRels - Updates the SPFTEFComprisedOf
relationships, properties, and other relationships of the CDW objects.
 ConsolidateCDWPropertiesAndRels - Updates the SPFTEFComprisedOf relationships,
properties, and any other relationships of the individual CDW objects.
 OnCreateComprisedOfRel - Creates a SPFTEFComprisedOf relationship between the
CDW object and the published object.
 OnDetermineTargetCDWUIDForLocalUID - Determines the CDW object UID for the
current published object being processed and updates it in the ComprisedOfUIDs collections
provided in the input parameters.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 17

 Consolidation Implementation and Customization

 OnLookForTargetCDWUIDForMultipleSameAs - Determines the target CDW UID from

SameAs for the local object.
 OnProcessAllSameAsForLocalUID - Processes all SameAs for the current published
object and updates the target CDW UID for all the involved local and external published
objects.
 ReconsolidateObjectProperties - Reconsolidates the CDW object.
 OnUpdateObjectAndMergeWithInputs - Calls OnSetPropertiesFromSource to update
the properties on the CDW object.
 OnSetPropertiesFromSource - Updates the properties on the CDW object.
 OnSetProperty - Updates the current property on the CDW object.
 OnCreateRelationship - Creates the given CDW relationship.
 OnCreateObject - Creates the CDW object.
 OnThisIsMappedOutputFile - A method that can be overridden to allow the customization
of the transformed tool data file.
Use the object browser to view each individual method available.

Consolidation process
This is pseudo code to describe the current process for CDW consolidation. The following steps
describe the consolidation process:
1. ConsolidateObjects calls PersistFileWithTaggedItemsInContainers to rearrange the tool
data and tombstone files into one combined file in tagged items.
2. ConsolidateObjects calls the method definition PerformMappingAndTransformation.
3. Using the output stream from the mapping function, process the file.
 Extract the component schema and SameAs mappings.
4. Read the file in chunks of tagged items, where the size of the chunks is configurable using
the PublishDataProcessingChunkSize setting in Server Manager.
a. For each chunk, call ConsolidateChunkOfTaggedItems.
b. Inside this function, try to lock the CDW objects and the published objects that they are
comprised of that would be affected. If the objects are locked successfully, process the
instructions and objects. If the objects are not successfully locked, then store the chunk
for processing at the end, once the entire file is completed.
c. If all tagged items have been successfully processed, commit the chunk to the
database.
5. Try again to consolidate chunks that could not be locked during the first attempt.
6. If objects still fail to lock successfully, then fail consolidation.
7. In the case of failed consolidation, set the number of committed chunks on the
SPFTEFTagItmGrpConsCnt property on the ISPFTEFPublishedDocVersion interface on
the document.
If you submit a consolidate task that attempts to lock objects currently locked by
another consolidate task, you receive the following message, "Consolidation was unable to lock

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 18

 Consolidation Implementation and Customization

required objects. Please retry" Retry the failed consolidation task when the first completes and
the objects are unlocked.

Delete instructions
Three method definitions are implemented on ISPCDWObject to allow control of the behavior
when a delete occurs.
1. ProcessItemBeforeToolDelete – Checks to see how many ComprisedOf relationships
exist.
2. OnProcessItemWithSingleComprisedOfRel - Checks to see if the CDW object last
updated date is more recent than the creation date of the ComprisedOf relationship. If the
last updated date is more recent, it indicates the CDW object has been updated and so it will
not delete the CDW object. If the object has not been updated since the creation of the
ComprisedOf relationship, it looks to see if there are relationships to any other objects that
are not part of the mapping. If the object has no other relationships to anything else in
SmartPlant Foundation, it will be deleted.
3. OnProcessItemWithMultipleComprisedOfRel – Terminates any current properties that
have a source domain equal to the domain of the tool data being removed. For each of the
properties being terminated this looks to see if it had a previous value with a different source
domain and if so, re-instates it.

Precedence customization
The default precedence process always updates the data on the CDW object as new data is
published. This process makes the published data represent the last in wins data. This can be
changed through customization.
On the ISPFCDWPublishedDocVersionDefault code class there is an override method called
OnSetProperty. This method is called each time you set a property on a new or existing CDW
object.
The inputs into this function are currently:
OnSetProperty(ByVal pobjTargetIDef As IInterface, ByVal
pstrPropertyDefUID As String, ByVal pobjValue As Object)
Access the properties collection from pobjTargetIDef, find the PropertyDefault object for the
property of interest, and see the existing value and the source domain.
There are two properties, TargetDomain and SourceDomain, that help with precedence.

Mapping customization
The PerformMappingAndTransformation method definition on ISPFCDWPublishedDocVersion
controls mapping. You can perform a sideways override on the
ISPFCDWPublishedDocVersionDefault interface to be able to override the following Methods:
 OnCreateInputAdapter – Allows you to write a new class and inherit from InputAdapter,
must implement ISPFInputAdapter.
 OnCreateOutputAdapter – Allows you to write a new class and inherit from OutputAdapter,
must implement IOutputAdapter.
 OnCreateMappingClass – Allows you to write a new class and inherit from
SPFMappingClass, must implement ISPFMappingClass.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 19

 Consolidation Implementation and Customization

 OnCreateInterpreter – Allows you to write a new interpreter class and inherit from
Interpreter, must implement Interpreter class.
The previous methods allow any project to replace any of the classes with their own custom
version of the class; this replacement is for mapping only. The mapping output class does not
consider the SameAs relationship; it maps the properties using the same UID’s. The consolidate
code performs the required logic for the SameAs relationship.

Input adapter
To override the GetNextObject and GetObject methods, as well as construct custom
AdapterObject (IAdapterObject), use the CreateAdapterObject method.

Output adapter
Ten methods can be overridden. Six are defined on the IOutputAdapter interface.

SPFMappingClass
The role of this class is to interrogate the database to provide mapping information by class
definition or relationship definition. Several methods can be overridden, allowing customization
of what mapping is returned. The IMapClass interface is used to send back instructions
(property mapping) and IDefInstructions (interface mapping).

Interpreter
The interpreter is a simple class that asks the input adapter for an object (IAdapterObject). If it is
an object, the interpreter calls the function OnExecuteObj, which is an override function. If it
finds a relationship, the interpreter calls OnExecuteRel. If it finds an instruction, the interpreter
calls OnExecuteInstruction.

OnExecuteObj
The process logic is described below:
1. Ask mapping class for the mapping for this class definition.
2. If no mapping is found, ignore this input item.
 The current setup means it will always default to CDWObject.
3. Call BringCreate on the output adapter, which creates a new object using the map to class
definition.
4. Set the output object name and description from the input source.
5. Process each of the SetInstructions (properties).
a. Ask the input adapter for the source property value.
b. Tell the output adapter to write the target property with the source property value.
6. Process each of the ISetInstructions (interface).
 If the input source has the interface, then create the mapped interface onto the output
source.
This is a mapping exercise that adds an interface onto the output source if it
exists on the input source.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 20

 Consolidation Implementation and Customization

7. Call FinishCreate on output class.

OnExecuteRel
The process logic is described as below:
1. Extract the relationship definition UID.
2. Ask mapping class for the mapping for this RelDefUID.
3. If no mapping is found, ignore the relationship.
4. Extract the UID, UID1, and UID2 from the input source.
5. Ask the output adapter to create a new relationship using the mapto RelDefUID, UID, UID1,
and UID2 (BeginCreateRel).
6. Process each of the SetInstructions (properties).
a. Ask the input adapter for the source property value.
b. Tell the output adapter to write the target property with the source property value.
7. Process each of the ISetInstructions (interface).
 If the input source has the interface, then create the mapped interface onto the output
source.
This is a mapping exercise that adds an interface onto the output source if it
exists on the input source.
8. Call FinishCreateRel on output class.

OnExecuteInstruction
The process logic is described below:
1. Call BringCreate on the output adapter to create a new instruction object using the class
definition of the instruction.
2. Process each of the interfaces and properties.
a. Ask the adapter for the source property value.
b. If the property is PropValues, AddedInterfaces, RemovedInterfaces,
RemovedProperties, or RelDefUID, then determine the mapped property values.
c. Tell the output adapter to write the property with the determined property value.
3. Call FinishCreate on output class.

Map function customization

You can perform a sideways override of ISPFMapFunctionDefDefault and override the
ExecuteMapFunction method definition. This function takes the return value and uses it to set
the target mapped property.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 21

 Consolidation Implementation and Customization

Correlate by name
In the default implementation, the SameAs relationships manage correlation between two
objects. For example, objectA in the PID domain is the same as objectB in the IDX domain.
These special relationships are placed inside the published XML file and are generated when
manually correlating after retrieve. There is an Auto-Correlate workflow that matches objects by
name and creates the SameAs relationships; this workflow is certified for use on CDW.

 Auto-Correlate will not generate a SameAs relationship if doing so would result in a conflict
(that is, generating the SameAs relationship would result in the CDW object being related to
more than one object of the same Class definition).
 If processing a SameAs relationship generated by Auto-Correlate would result in a conflict,
then the SameAs will be ignored.
 If two different objects have the same class and the same name, they cannot be
consolidated by Auto-Correlate.
 SameAs relationships that are published by the tool (identified as a SameAs relationship
without an OBID) are saved in the database. Existing SPFTEFComprisedOf relationships in
customer data are processed in the same manner as a SameAs relationship generated by
Auto-Correlate. If needed, the data may be corrected by publishing the SameAs
relationships or by reconsolidating.
 A SameAs can result in two objects being related to the same CDW object. If a new object
with the same class and same name is published without a SameAs, it will not be related to
the existing CDW object, but instead will be related to a new CDW object.
 If an object is renamed, any objects related to the renamed object because of a
tool-published SameAs will remain related. However, auto-correlated objects will be related
to a new CDW object.

Auto-correlation customization
You can perform a sideways override of ISPFTEFToolDataFileDefault and override the
following methods:
 PostProcessAutoCorrelatedStructure – This method allows customization of the
auto-correlated, structured object collection determined by out-of-the box code. The method
is called once for every shared object definition for each unique class definition in the tool
data file. It is called after the default logic is executed for that shared object definition and an
updated, auto-correlated structure is available.
 RetrieveObjectsWithClassDefUID – This method is used to retrieve all published objects
from the database with names that match the input criteria.
For those projects that use non-Hexagon PPM tools for authoring data or SmartPlant
Foundation for authoring, there is no mechanism to correlate. To address this gap and to
provide more flexibility than just name correlation, written custom code has been written to use
the unique key definition to define where two objects are the same. This custom code can be
modified as required to fit the needs of your business.
In the following example, we use a unique key definition on the CDW class definition to define
how we correlate. We also specify that the configuration and name define uniqueness. You can
look at other related information and include that in the unique key as well.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 22

 Consolidation Implementation and Customization

<ClassDef>
<IObject UID="SPFCDWInstrument" Name="SPFCDWInstrument"
Description="Instrument (Planned Material)" />
<IClassDef />
<ISchemaObj DisplayName="Instrument (Planned Material)" />
<ISPFClassDefExt SPFIsConfigurationControlled="True"
SPFUniqueKeyDef="CDWInst,CurrentConfig,Name"/>
</ClassDef>
The Method to override is called OnCreateNewObjectAndMergeWithInputs. This method is on
the ISPFCDWPublishedDocVersionDefault interface.
The process logic is described below:
1. Look to see if the CDW class definition has a unique key.
2. Create a temporary object, and set all the properties.
3. Call the GenerateKey function, which returns a unique key.
4. Look in the database for another CDW object with the same unique key.
a. If one is found, update and return it.
b. Otherwise, create a new CDW Object, and return it.
5. The ComprisedOf relationship will be created between the tool data and the object returned.

Public Overrides Function

OnCreateNewObjectAndMergeWithInputs(ByVal pobjPublishedItem As
Generated.IObject, ByVal pobjExistingCDWItem As Generated.IObject, ByVal
pobjCDWObject As StreamingSchema.Model.SchemaObjectDef, ByVal pstrCDWUID
As String) As Generated.IObject
'
' Note:- ExistingCDWItem is nothing
'
' NOTE: Need to do this bit below.
' If this object is a document then attempt to link the document
to its doc master instead of creating a CDW object for it.
'
If pobjPublishedItem IsNot Nothing AndAlso
pobjPublishedItem.Interfaces.Contains("IDocument") Then

Me.CoreModule.QueryRequest.AddQueryInterface("ISPFTEFPublishedDocMaster
")
'
' As the Doc Master and the 2 tier document have the same UID
then it is better to find by UID
'
Dim lobjDocMasters As IObjectDictionary =
CoreModule.QueryRequest.RunByUID(pobjPublishedItem.UID)
If lobjDocMasters IsNot Nothing AndAlso lobjDocMasters.Count
> 0 Then
Return lobjDocMasters(0)
End If
'

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 23

 Consolidation Implementation and Customization

' If a document master has not been found then the code continues
to create a regular CDW object for this published object.
'
End If
'
' Extract the config
'
Dim lstrConfig As String = ""
If pobjExistingCDWItem IsNot Nothing Then
lstrConfig = pobjExistingCDWItem.Config
End If
If String.IsNullOrEmpty(lstrConfig) Then lstrConfig =
CoreModule.Server.Context.CreateConfiguration.ToString
'
' Append an _S on the end so we can distinguish from Tool object
plus we are consistent with the original implementation. Use function so
we
' can change this in just one place should it be wrong.
'
Dim lstrNewUID As String = pstrCDWUID
'
' Make up your own correlate rules here....
'
Dim lobjClassDef As IClassDef =
CType(Me.CoreModule.ProcessCache.Item(pobjCDWObject.ClassDefinitionUID,
"SCHEMA").Interfaces("IClassDef"), IClassDef)
If String.IsNullOrEmpty(lobjClassDef.SPFUniqueKeyDef) =
False Then
'
' Create a temp object so we can call the generate key method
'
Dim lobjTempObj As IObject =
Utilities.GeneralUtilities.InstantiateObjectNoFootprint(Me.CoreModule,
lobjClassDef.UID, "", "", "")
lobjTempObj.Config = lstrConfig
'
' Need to call the base function that will set the properties
on the temp object from the tool representation
'
OnSetPropertiesFromSource(lobjTempObj, pobjCDWObject)
'
' Now call the GenerateKey
'
Dim lstrUniqueKey As String =
CType(lobjTempObj.Interfaces("IObject"),
IObjectDefault).GetClass.GenerateKey(lobjClassDef.SPFUniqueKeyDef)
'
' Now search the database looking for unique key
'
Dim lcolUniqueKeys As New Specialized.StringCollection
lcolUniqueKeys.Add(lstrUniqueKey)
'
' Look for objects with these unique keys

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 24

 Consolidation Implementation and Customization

'
Dim lobjDataMgr As New DataAccess.DataManager(Me.CoreModule)
Dim lcolExistingOBIDs As Generic.Dictionary(Of String,
ArrayList) =
lobjDataMgr.GetExistingOBIDsForDomainAndConfigAndUniquekey(lcolUniqueKe
ys, Me.TargetDomain.UID, lstrConfig)
'
' If there are existing obid's then use that object
'
If lcolExistingOBIDs.Count > 0 Then
Dim lobjCDWExistingItems As IObjectDictionary =
Me.CoreModule.QueryRequest.RunByOBIDCollection(lcolExistingOBIDs(lstrUn
iqueKey))
If lobjCDWExistingItems.Count > 0 Then
Dim lobjExistingCDWItem As IObject = lobjCDWExistingItems(0)
'
' Perform the mapping
' Call function to update the CDW Object
'
Dim lobjUpdatedItem As IObject =
OnUpdateObjectAndMergeWithInputs(lobjExistingCDWItem, pobjCDWObject)
'
' Send back the first item
'
Return lobjExistingCDWItem
End If
End If
End If
'
' Call the mybase code
'
Return
MyBase.OnCreateNewObjectAndMergeWithInputs(pobjPublishedItem,
pobjExistingCDWItem, pobjCDWObject, pstrCDWUID)
End Function

Auto-correlation rules
Using auto-correlation rules, you can configure the auto-correlate workflow to correlate objects
that do not have a name. For example, most piping ports will not have a name, but should be
correlated. You can create this correlation manually, or you can use auto-correlation rules to
consider properties other than the name of the object.
An auto-correlation rule is specific to a CDW class definition. The rule uses either the
relationship to the parent of the object or the specific property values to find the correct object to
correlate with.
Auto-correlation rules will correlate an object with another based on the relationship to the
parent and the following conditions:
 Matching name, if the name is set
 If only one object is found using the relationship to the parent, then the object is matched
directly

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 25

 Consolidation Implementation and Customization

 If the name is not set and a match cannot be determined just on the relationship to the
parent, then the match can be created based on specified property values

 Auto-correlation rules are applied while correlating objects related to documents published
using the Correlate workflow. All published objects with possible correlations are displayed
in the To Do List with the Correlate task. From that task, you can manually choose the
correlations to create, and those objects will be correlated during consolidation.
 Auto-correlation rules are created for CDW classes. However, if you are using the shared
object model and want to use auto-correlation rules, you must first install the CDW schema
and create the rules. Then you can use those rules in your shared object model
environment.
 Auto-correlation rules are not required to automatically correlate items during publish. If no
rule has been configured for a specific class, the system will use the standard auto-correlate
functionality to correlate the items, based on matching name and shared object class.
 If you are manually correlating items that belong to a shared object class for which an
auto-correlation rule exists, the software applies the rules internally and presents a warning
message if the manual correlation does not match the rule. You can dismiss the warning and
continue.
For more information about creating auto-correlation rules, see Managing auto-correlation rules
(on page 27).

Delivered rules
Two auto-correlation rules are delivered with CDW schema. They are inactive by default. To
activate the rules, view them in the List Edit control and check the Is Active option.

Rule Parent Edge Properties

NozzleAutoCorrelateRule SPFCDWEquipmentComponent none

Composition

PipingPortAutoCorrelateRule SPFCDWPipingPortComposition SPFCDWNominalDiameter

Correlating an object using auto-correlation rules

If an object you are correlating has a name, the software will look for a corresponding shared
object based on the name and the classes that can be correlated with your object.
 If only one corresponding shared object is found, then your object will be correlated to it.
 If multiple objects were found with a matching name and valid class, the secondary criteria,
such as an auto-correlate rule, is applied if any rules are configured for the class.
 If only one corresponding object is found after applying the secondary criteria, then the
object will be correlated to that.
 If multiple shared objects are determined to be potential targets for correlation and they
are not of the same type or cannot be converted to the same type with the inclusion of
your object, then you will be asked to make the decision using the To Do List.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 26

 Consolidation Implementation and Customization

A Resolve-Conflicts task is added to your To Do List after the document is loaded and
consolidated. Once you click the Correlate command from this task, a dialog box
displays all the objects that were found to have conflicts during correlation, along with all
the potential matching shared objects. Choose the appropriate shared object for each of
the objects. Once you approve the task, these correlations are updated in the database.
The criteria used when correlating objects are honored in the following priority:
1. SameAs relationship published by a tool
2. Custom SameAs relationship (provided by a user during auto-correlate step)
3. Applied auto-correlate rule

Correlating an unnamed object

Objects without names can be correlated only if secondary auto-correlation rules have been
defined. WIth the exception of the name criteria, the same logic applies for correlating objects
without names as for named objects.

Managing auto-correlation rules

1. Click Find > Integration > Auto Correlate Rules.
2. Right-click on a rule, and click List Edit - Auto Correlate Rules.
From the List Edit window you can view or edit existing rules, or you can create your own rule
in the blank row at the bottom of the table.

Create an auto-correlation rule

1. Provide a name and description for the new rule.
2. Select the shared object class that this rule will apply to from the list in the CDW Class
column.
3. If necessary, use the list in the Parent edge column to choose an edge definition to
navigate from the object to be correlated to its parent object. The list contains edge
definitions that the selected CDW class participates in.
If you select an edge that has one-to-one cardinality, the Correlate by
properties cell is disabled. If you change the edge selection from an edge with one-to-many
cardinality to an edge with one-to-one cardinality, any value in the Correlate by properties
cell is removed.
4. If you want to specify values for properties to be used to match objects for correlation, click
in the Correlate by properties cell. A dialog box appears where you can add required
properties to the list to select them for correlation. Click OK when you are done selecting
properties.
5. Check the Is Active check box to turn on the rule so that it is applied during correlation.
6. Click Apply or OK to create the rule you have configured.

Viewing auto-correlate rules

 Click Find > Integration > AutoCorrelate Rules.
No value in the Is Active column in the List View is the same as a False value.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 27

SECTION 3

How to Configure the CDW

SmartPlant Foundation release 2009 R3 SP2 and later delivers the basic CDW capability with a
demonstration model. The default product does not supply a CDW schema, nor contain any
"smart" tools to help configure a schema. The Schema Editor or another off-the-shelf editor can
be used to configure the CDW schema, just like extending other SmartPlant Foundation or
SmartPlant® Enterprise schemas.
 Use Schema Editor or a similar tool to generate the CDW model load files, which can be
loaded into SmartPlant Foundation to extend the database.
 Use an editor to generate the CDW mapping load files, which are xml files that are loaded
and managed by the user.
 Use the SmartPlant Foundation Desktop Client to create methods, menus, and user access
configuration to expose the CDW model.
There are spreadsheet-based tools developed in projects, which can be used to facilitate this
process until a modeling and mapping GUI is delivered with the product.

Extending the CDW model and mapping

We recommend that you implement CDW by creating your own custom CDW class definitions,
interfaces definitions, and mappings specific to your organization or project. You can reuse the
SmartPlant schema delivered with SmartPlant Foundation and extend it, as needed, to match
your custom CDW schema. However, a demonstration model is delivered that you can use as a
starting point and customize, as needed.

Creating your own CDW schema

When you create a custom CDW class definition, you can choose either of the following two
approaches:
 Create all new interfaces and relationship definitions for your CDW class definitions.
 Reuse those delivered in the SmartPlant schema, whenever possible and appropriate.
Reusing the delivered interface and relationship definitions helps keep the schema small and
reduces the amount of work you must do. The new CDW class definitions simply realize their
own unique primary interfaces and the desired SmartPlant schema interfaces.
As each SmartPlant schema interface is realized, it automatically adds all the
exposed properties and relationship definitions configured from that interface. These can be
excluded from the mapping, but care is needed. If any of these are required properties or
required relationships, they will need mapping to ensure that there are populated.
CDW users will have access to navigating the integration relationship definitions if
they are reused in the CDW schema.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 28

 How to Configure the CDW

Creating new CDW schema objects

If you do not want your CDW class definitions to reuse the existing SmartPlant Foundation
interfaces and properties, you can create your own. While this approach will allow you to have
full control over which properties or relationships are exposed, it will also result in larger schema
files and more work.
This approach is recommended, as it gives far greater control over the
exposure of relationship and property definitions.

CDW mapping
Any properties or relationships that will be consolidated from published objects to the CDW
objects require mapping, as does the CDW model. The following components of the model
require mapping:
 ClassDefToClassDef
 InterfaceDefToInterfaceDef
 RelDefToRelDef
 PropertyDefToPropertyDef
This mapping must be created in xml load files. It is relatively straight forward, especially if it is
1:1 mapping to the SmartPlant Schema interfaces.

New CDW domain group

A new CDW domain group is delivered with the CDW sample database, part of the CDW
consolidated load file, but a sample of the XML used to create it is provided below:

<SPFDomainGroup>
<IObject UID="DG_CDW" Name="CDW"/>
<ISPFAdminItem/>
<ISPFDomainGroup SPFTablePrefix="CDW"/>
<ISPFSubscribableItem />
</SPFDomainGroup>

A new relationship associating the CDW domain to the new CDW domain group is delivered
with the CDW sample database, part of the CDW consolidated load file, but a sample of the
XML used to create it is provided below:

<Rel>
<IObject UID="CDW.CDW"/>
<IRel UID1="DG_CDW" UID2="CDW" DefUID="SPFDomainGroupDomain"/>
</Rel>
For more information on the CDW consolidated load file, see CDW Demonstration Model (on
page 42).

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 29

 How to Configure the CDW

Using the demonstration CDW model as a starting point

While we recommend that you create your own CDW class definitions, it is possible to start with
the delivered demonstration model, which contains one CDW class definition for each
SmartPlant Schema SharedObjectDef. However, if you have created custom shared object
definitions, you will need to extend the delivered model similarly.
When extending the schema, you can either reuse the existing SmartPlant schema objects as
much as possible or create custom CDW schema objects.

Configuring SmartPlant Foundation to use the CDW

SmartPlant Foundation can be configured to use the CDW by enabling the setting for the
attribute CDWEnabled to True.
The CDWEnabled attribute is found in different locations depending on which SmartPlant
Foundation version is being used:
 In SmartPlant Foundation version 2009 R3 SP2 and all service packs, the CDWEnabled
attribute is located in the web.config file under the site setting in SmartPlant Foundation
Server Manager.
 In SmartPlant Foundation version 2009 R4 and later, the CDWEnabled attribute is located in
the SPFAppServer.config file under the configuration service setting in SmartPlant
Foundation Server Manager.
<add key="CDWEnabled" value="True"/>

Configuration to expose consolidated data

Once the published data has been loaded and consolidated, users will want to find, view, and
navigate the consolidated data. To do this, you must create methods and menus, and then
configure user access for the relationships for navigation. Details of how to do this are provided
in the How to Configure the GUI guide, however overall guidelines are provided here.
You can make the CDW GUI easier for users to navigate by doing the following things:
 Providing find and query menu items for the main objects; for example, for equipment and
instruments but not nozzles.
 Try to use CDW only interfaces when querying for data to ensure that the queries are more
efficient.
 Generate the forms for all objects.
 Use form lists or the view related items method to display the primary object information and
some information on related objects. This may be more convenient for the more complex
objects, for example, to display equipment and a list of its nozzles.
 Create a column set to display the key information for objects commonly queried. Avoid
adding every property and relationship to the custom column set, as too much information,
especially relationships, can slow down client performance.
 Manage user access to expose relationships as required.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 30

 How to Configure the CDW

 Create edge definitions to navigate across intermediate objects, such as process points. For
example, create edges to navigate from equipment to pipelines to instruments.
Examples of all the above are provided in the CDW Demonstration Model (on page 42).

Managing and using CDW precedence rules

Prior to the implementation of the CDW precedence rules, data published into SmartPlant
Foundation from an authoring tool and consolidated was stored in the CDW using a "last in
wins" approach. While the latest values for properties of objects published from any single tool
were stored safely in that tool's domain, the CDW reflected that last data that was published for
that object's property, regardless of which tool published it.
CDW precedence rules allow you to specify priority that each domain has for specific pieces of
data. For CDW class definitions, interface definitions, property definitions, relationship
definitions, or properties for specific class definitions, you can rank the order of priority to assign
to each tool domain.
You can use these rules to specify behavior like the examples below:
 Published data consolidated onto an SPFCDWBranchPoint object should prioritize data
from Intergraph Smart® 3D over the other products that published data about that object.
 Properties on the ISPFCDWPipingPortComposition interface should prioritize values from
SmartPlant Electrical, but all the other properties for the SPFCDWBranchPoint object should
prioritize the data from Smart 3D.
 The SPFCDWInstrGasketRqmt property should prioritize the value from the instrument
datasheet over other values for that property. However, other properties on the
ISPFCDWPipingPortComposition interface should prioritize values from SmartPlant
Electrical, and all the other properties for the SPFCDWBranchPoint object should prioritize
the data from Smart 3D.
 The nominal diameter value for ducts should prioritize the value from Smart 3D, but the
nominal diameter for other objects should prioritize values from SmartPlant P&ID.
Precedence rules are applied according to the following criteria:
 Rules can be applied directly to any CDW class definition, interface definition, property
definition, or relationship definition and the rule will apply to all instances of those schema
objects.
 By default, a CDW property definition or interface definition will inherit the precedence rules
set on the higher-level schema object (interface definition or class definition, respectively).
 If you apply a precedence rule to an interface or property definition using a tree to find that
object from a higher-level object (such as a class definition or interface definition,
respectively), the rules applied to the schema object will override any rule inherited from the
higher-level schema object.
 If you apply a precedence rule to an interface definition or property definition, the rule
applies to all instances of that interface or property definition, for all objects. However, you
can override the precedence rule on a property definition by applying a different rule to a
property for a specific class definition.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 31

 How to Configure the CDW

CDW precedence rules

CDW precedence rules determine what published data is included in the CDW domain when
differing data has been published from multiple authoring tools. For each CDW schema object,
class definitions, interface definitions, property definitions, and relationship definitions, you can
specify which domain's data should be given priority over the data from other domains.
When you create a precedence rule, you provide a name for the rule and a list of the domains
from which the data should be given priority and the order in which they should be considered,
using an Order Value.
While data from each domain is stored safely in the database, regardless of these precedence
rules, these rules will determine what data is stored in the CDW domain. Data from a domain
with a lower Order Value will not override the data in the CDW domain, even if it was published
after the older data from the domain with a higher Order Value.
For example, a rule might include the following:

Domain Order Value

ELE 100

PID 90

SP3D 90

LLA 80

In this example:
 Data the LLA domain is prioritized over data from domains not listed.
 Data from the SP3D or SPPID domain is prioritized over data from LLA.
 Data from ELE domain is given the top priority and will not be replaced in the CDW domain
with data from any other domain.
 Since the PID and SP3D domains have the same Order Value, they are both considered a
higher priority than the LLA domain and a lower priority than the ELE domain, but neither is
a higher priority than the other. If data from either of these domains is stored in the CDW
domain when the different data is published into the other domain, the CDW domain value
will be replaced with the new value.

Creating and updating CDW precedence rules

1. Find the CDW schema object for which you want to create or update a precedence rule,
right-click it, and click Manage Precedence Rules.
2. Select an existing rule in the Precedence Rule list and click Update or click Create to make
a new rule.
If you want to edit an existing rule, but it does not appear in the list, use the Find
feature to update the list.
3. If you are creating a new rule, provide a name for it.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 32

 How to Configure the CDW

4. Using the Publish Domains list, create a list of the domains from which the data should
take priority. Click to add the domain to the table on the left side.
5. For each domain listed on the left side, provide an Order Value to set the priority.
The data from each domain will be replaced in the CDW domain only with data
from a domain with a higher value.

Adding CDW precedence rules to a schema object

1. Find the CDW schema object you want to add a precedence rule to, right-click it, and click
Manage Precedence Rules.
2. Use the tree in the CDW Schema window to find the schema object you want to apply the
rule to.
You can apply the rule to a class definition, an interface definition, a property
definition, or a relationship definition, and the rule will apply to all instances of those schema
objects. However, if you expand the property node to show the node for the property specific
to that class definition, you can apply the rule to that specific use of the property definition
without it being applied to other uses of that property.
3. If the rule is not displayed in the list of precedence rules, use the Find control to search for
it.

4. Select the rule and click to associate the rule with the schema object.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 33

SECTION 4

Consolidated Data Warehouse Model

The Consolidated Data Warehouse (CDW) schema consists of extensions to the SmartPlant
schema that can be created and configured to expose and view published data.
When a document is published in an environment configured to use CDW, the published data
document includes the data necessary to publish to the tool’s publish domain, the shared
domain (with the standard shared object), and the CDW domain (with the CDW object).
This section of the document details the CDW extensions to the SmartPlant schema used to
extend the data in the published document and the key interfaces and relationships used by the
configurable CDW model and its mapping.

Additional interfaces for published documents in a

CDW environment
CDW extensions to the SmartPlant Schema for published
documents
CDW published documents use the same document class definitions as the shared object
technology.
The existing published documents use the following class definitions:
 SPFTEFPublishedDocMaster
 SPFTEFPublishedDocRevision
 SPFTEFPublishedDocVersion
The published document version class definition, SPFTEFPublishedDocVersion, has been
modified and extended as follows:

ISPFTEFPublishedDocVersionPI
This is a new primary interface for the SPFTEFPublishedDocVersion class definition. The
ISPFTEFPublishedDocVersion is still realized and it retains the code implementation for the
publish and consolidate mechanism using shared objects. Override mechanisms have been
added in this code for project utilization.

ISPFCDWPublishedDocVersion
The new ISPFCDWPublishedDocVersion interface is optionally realized by the published
document version. It is instantiated when a published document is loaded and the system is
configured to use the CDW, as opposed to the shared object.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 34

 Consolidated Data Warehouse Model

The following diagram shows the relationship to this interface:

CDW object schema

All CDW class definitions use a CDW component schema associated with the CDW domain.
The CDW domain belongs to its own CDW domain group with its own set of database tables.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 35

 Consolidated Data Warehouse Model

The CDW schema is fully configurable, but all the class definitions must realize a minimum set
of interfaces. The diagram below shows the model for typical CDW class definitions, in this
example, the consolidated SPFCDWInstrument.

Base CDW object schema

ISPFCDWObject
This is the main consolidated object interface which implies IObject and is required by all
consolidated class definitions.
There are no properties exposed on this interface.

Functionality configured on ISPFCDWObject

The following methods are configured on this interface.
 View Consolidated Data
 Inconsistency Report

ISPFCDWClassifiedItem
This interface is realized on classified items as well as the ISPFClassifiedItem interface, which it
implies. These should be optionally realized, as the typing properties are not always published
and the classification relationships cannot be determined. See the section Consolidation
Implementation and Customization (on page 14) for more details. Code is implemented on this
interface to control the creation of the SmartPlant Foundation primary classification relationship
and associated classification level relationships used for queries.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 36

 Consolidated Data Warehouse Model

There are no properties exposed on this interface.

Functionality configured on ISPFCDWClassifiedItem

There are no methods configured on this interface.

ISPFTEFPublishedObjectCollection
This interface is retained because it has the ComprisedOf relationship to relate the published
tool data to the consolidated objects.
This enables the CDW to use exactly the same navigation mechanism that is used by the
shared object to view published data.

Additional interfaces on CDW SPFCDWInstrument

The additional interfaces shown in the previous diagram, including the primary interface, are just
an example of the configuration of a consolidated class definition. Each CDW class definition
must have a different primary interface that is unique to and realized only by that class, to
provide a way for unique searches. The additional interfaces can either be copies of the
SmartPlant schema interfaces or they could realize the same SmartPlant schema interfaces.
Creating copies of the interfaces provides more control over which properties are modeled as
described in more detail in the section on How to Configure the CDW (on page 28).

Source domain
To specify the source domain on CDW relationships, a new interface is made called
ISPFCDWObjectDetail.

ISPFCDWObjectDetail
This is an optionally realized interface on the Rel class definition and is used to store the
information about the tool that publishes the data being consolidated.

Name Description Set On

SPFSourceDomain The source domain of the data On CDW Object consolidation

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 37

 Consolidated Data Warehouse Model

This information is available in the history form.

In the default model, ISPFCDWObjectDetail is realized for relationships only, but can easily be
made available for objects, as it is on every relationship.

CDW mapping schema

Base CDW mapping
The following meta-schema relationship definitions are used to define the mapping between the
integration SmartPlant schema and CDW schema.
 ClassDefToClassDef
 InterfaceDefToInterfaceDef
 RelDefToRelDef
 PropertyDefToPropertyDef
 MappingToSPFMapFunction

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 38

 Consolidated Data Warehouse Model

Some examples of mapping are included below:

<Rel>
<IObject UID="PFDControlValve.SPFCDWInstrument.ClassDefToClassDef"
/>
<IRel UID1="PFDControlValve" UID2="SPFCDWInstrument"
DefUID="ClassDefToClassDef" OrderValue="0" IsRequired="False" />
<ISchemaObj />
<IMapRel />
</Rel>
<Rel>
<IObject
UID="InstrumentType.SPFCDWInstrumentType.PropertyDefToPropertyDef" />
<IRel UID1="InstrumentType" UID2="SPFCDWInstrumentType"
DefUID="PropertyDefToPropertyDef" OrderValue="0" IsRequired="False" />
<ISchemaObj />
<IMapRel />
</Rel>
<Rel>
<IObject
UID="IEquipment.ISPFCDWEquipment.InterfaceDefToInterfaceDef" />
<IRel UID1="IEquipment" UID2="ISPFCDWEquipment"
DefUID="InterfaceDefToInterfaceDef" OrderValue="0" IsRequired="False" />
<ISchemaObj />
<IMapRel />
</Rel>
<Rel>
<IObject
UID="EquipmentComponentComposition.SPFCDWEquipmentComponentComposition.
RelDefToRelDef" />
<IRel UID1="EquipmentComponentComposition"
UID2="SPFCDWEquipmentComponentComposition" DefUID="RelDefToRelDef"
OrderValue="0" IsRequired="False" />
<ISchemaObj />
<IMapRel />
</Rel>

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 39

 Consolidated Data Warehouse Model

Map function model

A new meta-schema object, called SPFMapFunctionDef, is available with a relationship from the
IMapRel link interface to the map function.

This new relationship definition allows map functions to be modeled against any
PropertyDef-to-PropertyDef and InterfaceDef-to-InterfaceDef mapping.

Additional map filtering

When specifying a mapping relationship between two interface or property definitions, one
integration and one CDW, you can execute the mapping for one or more class definitions. This
makes it possible to map a common interface like IPBSItem just for the PIDInlineInstrument
class definition by specifying End1MapValue on IMapRel. For example:
<Rel>
<IObject UID="IPBSItem.ISPFCDWPBSItem.InterfaceDefMap"/>
<IRel UID1="IPBSItem" UID2="ISPFCDWPBSItem"
DefUID="InterfaceDefToInterfaceDef" OrderValue="0" IsRequired="False"/>
<IMapRel End1MapValue="PIDInlineInstrument" />
<ISchemaObj/>
</Rel>
To map the interface for multiple class definitions, include the complete list of class definitions
as the value for End1MapValue, separating each class definition name with a comma. For
example, End1MapValue="PIDInlineInstrument,ELEInstrument,INDXInstrument".

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 40

SECTION 5

Authoring relationship model

SPFAuthoringRelDefToCDWRelDef
This meta-schema relationship definition is defined to map from an authoring relationship
definition to a CDW relationship definition. These are defined in the CDW schema files. If any of
these mapping relationships are present, then the publish process generates an additional file
associated with the published document that contains the mapped relationships, and this is
created between the published and common data.
An example of where this new relationship definition can be used is shown below.

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 41

SECTION 6

CDW Demonstration Model

In SmartPlant Foundation releases 2009 R3 SP3 and later, the demonstration model is
delivered in one consolidated load file in the model's directory:
C:\Program Files
(x86)\SmartPlant\Foundation\2018\Models\CDWDEV\CDWDEV_Consolidated.xml
The single load file CDWDEV_Consolidated.xml contains a simple demonstration
model with just the properties required for all the SmartPlant schema class definitions. One
CDW object is created per Shared Object Definition in the schema. For each, Shared Object
Definition mapping has been done between all the related SmartPlant schema class definitions
and the CDW class definitions. This has been modeled and mapped with properties and
relationship definitions just sufficient to show for the demonstration only. A sample database is
also included in the single load file, which adds the CDW database parts to the SmartPlant
Foundation database.

The model
The demonstration model uses one CDW class definition for each SmartPlant Schema
SharedObjectDef. It also uses its own interfaces, properties, and relationships, though it could
just as easily reuse the SmartPlant Schema.
The following class definitions are delivered in the CDWDEV_Consolidated.xml load file:
 SPFCDWBranchPoint
 SPFCDWBulkPhase
 SPFCDWCable
 SPFCDWCableRun
 SPFCDWCableSchedule
 SPFCDWCableTrayPort
 SPFCDWCableway
 SPFCDWCablewayPort
 SPFCDWCircuit
 SPFCDWConduit
 SPFCDWConduitPort
 SPFCDWConduitRun
 SPFCDWControlSysIO
 SPFCDWDuct
 SPFCDWDuctRun
 SPFCDWElectricalConnector

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 42

 CDW Demonstration Model

 SPFCDWElectricalPanel
 SPFCDWEquipment
 SPFCDWEquipmentComp
 SPFCDWEquipmentFoundation
 SPFCDWEquipmentFoundationPort
 SPFCDWFilter
 SPFCDWFooting
 SPFCDWGasket
 SPFCDWHangerSupport
 SPFCDWHVACPort
 SPFCDWInstrument
 SPFCDWInstrumentLoop
 SPFCDWIOCard
 SPFCDWLadder
 SPFCDWLineListRecord
 SPFCDWNozzle
 SPFCDWPhaseChemicalComponent
 SPFCDWPipe
 SPFCDWPipeBoltSet
 SPFCDWPipeClamp
 SPFCDWPipeline
 SPFCDWPipeRun
 SPFCDWPipeSpool
 SPFCDWPipingComponent
 SPFCDWPipingPort
 SPFCDWPipingSystemConnector
 SPFCDWPipingSystemConnector_Process
 SPFCDWPort
 SPFCDWProcessCase
 SPFCDWProcessDataCase
 SPFCDWProcessPoint
 SPFCDWProcessPort
 SPFCDWProcessPort_Process
 SPFCDWRackSlot
 SPFCDWSignalChannel

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 43

 CDW Demonstration Model

 SPFCDWSinglePhase
 SPFCDWSlab
 SPFCDWSteamTrap
 SPFCDWStructuralPort
 SPFCDWStructure
 SPFCDWTerminalItem
 SPFCDWTrunk
 SPFCDWValveOperator
 SPFCDWVent
 SPFCDWWeld
 SPFCDWWiringTray

Mapping
The mapping is a simple 1:1 mapping between the SmartPlant schema and the CDW
demonstration schema.
The demonstration schema also includes mapping for any interface that contains type properties
and a set of PID interfaces to use in the demonstration environment.
 IDifferentialProducer
 IEnergyPort
 IEquipment
 IInstrument
 IPipingComponent
 IEquipmentComponent
 IProcessPointCase
 IPipeCrossSectionItem
 IInlineComponent
 IPipingSpecifiedItem
 IFluidSystem
 IPipingConnector
 IPipingConnectorComposition
The following relationship definitions are also mapped across the SmartPlant schema and CDW
demonstration schema. The mapping process involved creating new CDW interfaces and then
mapping and realizing those.
 EquipmentComponentComposition
 PipingPortComposition
 PipingEnd1Conn

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 44

 CDW Demonstration Model

 PipingEnd2Conn
 PipingConnectors
 PipingTapOrFitting

Exposing the CDW data

The following administration objects are delivered in the CDWDEV_Consolidated.xml load file,
which exposes the published data in the demonstration model:
 A single query menu option is configured that takes advantage of the fact that all the
consolidated objects are classified. Different forms can be configured for different levels of
the classification tree. In the demonstration environment, the different forms are for
equipment and instruments.
 Column sets have been defined for equipment, instruments, pipelines, and nozzles.
 The View Shared Object command and inconsistency reports are available on the shortcut
menus of consolidated objects and the documents they were published on.
 The following edge definitions have been created to make navigation easier:
 CDWPipelineToEquipment
 CDWPipelineToInstruments
 CDWPipingPortToPipelines
Quick Find menus are provided for all objects, but the less common ones are
available from Find > Consolidated Data > Other.

Enabling CDW consolidation

The CDW attribute setting to enable CDW in SmartPlant Foundation is located in the web.config
file for SmartPlant Foundation version 2009 R3 SP2 and service packs, and in the
SPFAppServer.config file for SmartPlant Foundation version 2009 R4 and later.
The CDWEnabled attribute can also be set to True from SmartPlant Foundation Server
Manager.
More information on the CDW attribute setting is covered under the section Configuring
SmartPlant Foundation to use the CDW (on page 30).

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 45

Index
Map functions • 16
A Mapping • 44
Mapping authoring relationships to the
Adding CDW precedence rules to a schema CDW • 12
object • 33 Migration from shared object to CDW • 12
Additional interfaces for published
documents in a CDW environment • 34
Authoring relationship model • 41 P
Authoring relationship processing • 15 Preface • 6
Auto-correlation rules • 25
S
C Summary of the shared object technology •
CDW customization • 17 8
CDW Demonstration Model • 42
CDW mapping schema • 38 T
CDW object schema • 35
CDW precedence rules • 32 The consolidated data warehouse object • 9
Classification handling • 15 The model • 42
Configuration to expose consolidated data •
30 U
Configuring SmartPlant Foundation to use Using the demonstration CDW model as a
the CDW • 30 starting point • 30
Consolidated Data Warehouse Model • 34
Consolidated Data Warehouse Overview • 8
Consolidation Implementation and
Customization • 14
Consolidation implementation basics • 14
Correlate by name • 22
Correlating an object using auto-correlation
rules • 26
Creating and updating CDW precedence
rules • 32
Creating your own CDW schema • 28

E
Enabling CDW consolidation • 45
Exposing the CDW data • 45
Extending the CDW model and mapping •
28

H
How to Configure the CDW • 28

M
Managing and using CDW precedence
rules • 31
Managing auto-correlation rules • 27

SmartPlant Foundation How to Configure the Consolidated Data Warehouse 46