SmartPlant Materials

INtools (SmartPlant® Instrumentation) Integration

Version 2007.4 (6.2.5) November 2006 / April 2008 DMAR1-PE-200001F-Updated

Copyright
Copyright © 2002-2008 Intergraph Corporation. All Rights Reserved.
Including software, 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.

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
Huntsville, Alabama 35894-0001

Warranties and Liabilities

All warranties given by Intergraph Corporation about equipment or software are set forth in your purchase contract,
and nothing stated in, or implied by, this document or its contents shall be considered or deemed a modification or
amendment of such warranties. 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 discussed in this document is furnished under a license and may be used or copied only in accordance
with the terms of this license.
No responsibility is assumed by Intergraph for the use or reliability of software on equipment that is not supplied by
Intergraph or its affiliated companies. THE USER OF THE SOFTWARE IS EXPECTED TO MAKE THE FINAL
EVALUATION AS TO THE USEFULNESS OF THE SOFTWARE IN HIS OWN ENVIRONMENT.

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.

Trademarks
Intergraph, the Intergraph logo, SmartSketch, FrameWorks, SmartPlant, INtools, MARIAN, PDS, and IntelliShip
are registered trademarks of Intergraph Corporation. Microsoft and Windows are registered trademarks of Microsoft
Corporation. Other brands and product names are trademarks of their respective owners.
 Table of Contents

Table of Contents
Introduction ........................................................................................................................4
Imported Data ...............................................................................................................4
Import Data into WBS via Database Link .......................................................................... 4
Imported Entity Types ........................................................................................................ 5
Error Handling ..............................................................................................................8
Import Protocol .............................................................................................................8
Offline Mode ................................................................................................................8

Prerequisites .....................................................................................................................10
Oracle Settings ............................................................................................................10
Required Data in the MARIAN Database ..................................................................10
Attributes .......................................................................................................................... 10
Commodity Groups and Parts ........................................................................................... 10
Units .................................................................................................................................. 11
Node Types ....................................................................................................................... 11
Commodity Codes ............................................................................................................ 11
Specs ................................................................................................................................. 11
Short Codes ....................................................................................................................... 11
Idents ................................................................................................................................. 12
Project Defaults................................................................................................................. 12
Creatable Data in the SmartPlant Materials Database ................................................12
Commodity Codes ............................................................................................................ 12
Idents ................................................................................................................................. 12
WBS Structure .................................................................................................................. 12

Data Import ......................................................................................................................13

Configure SmartPlant Instrumentation Interface ........................................................13
SmartPlant Materials Settings ........................................................................................... 13
SmartPlant Instrumentation Settings................................................................................. 14
SmartPlant Instrumentation Access .................................................................................. 23
Configure Attributes Plus Values ...............................................................................24
Configure Attribute Sets .............................................................................................25
Define Assembly Structure .........................................................................................26
Define Import Job .......................................................................................................27

Offline Mode .....................................................................................................................29

Export SmartPlant Instrumentation Data ....................................................................29
Create a New Schema in the SmartPlant Materials Database ....................................30
Remove Existing SmartPlant Instrumentation Data ...................................................30
Import SmartPlant Instrumentation Data ....................................................................30
Direct Database Link Points to New Schema .............................................................31

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 3

Introduction

Introduction
SmartPlant Materials, a flexible and open materials management system, incorporates
interfaces to those engineering systems and CAD systems with the highest market
significance. These interfaces allow several convenient ways to exchange data with
these systems.

The interface with SmartPlant Instrumentation® is an additional step toward a

globally integrated system. This document describes how to exchange data between
SmartPlant Instrumentation and SmartPlant Materials, beginning with an overview of
the major features.

Imported Data

Import Data into WBS via Database Link

SmartPlant Materials imports SmartPlant Instrumentation bill of materials (BOM)
data into the SmartPlant Materials work breakdown structure (WBS). SmartPlant
Materials triggers the information transfer from SmartPlant Instrumentation to
SmartPlant Materials. SmartPlant Materials initiates the pull of information from
SmartPlant Instrumentation into the SmartPlant Materials database.

SmartPlant Instrumentation has to provide a database that can be accessed by

SmartPlant Materials. SmartPlant Materials can then read this information and load
all new items on demand.

This import is part of the OMI (BOM import) functionality in SmartPlant Materials
(screen B.40.01). Users can select the nodes they want to import from SmartPlant
Instrumentation for each OMI import job and for each entity type to be imported. The
SmartPlant Instrumentation preprocessor converts the SmartPlant Instrumentation
data into an OMI-readable format.

The following questions are decided while importing the data into SmartPlant
Materials:

• What SmartPlant Materials project will the data be imported into? The
project is the logon project. The logon discipline is also the discipline to
which the imported records will belong.
• What issue status will the instruments be imported into in SmartPlant
Materials? This is selected with the import module (screen B.40.01).
• What is the start node for the import? This information is necessary
because the import takes place based on an existing WBS, which means
several nodes might already exists. The hierarchy for SmartPlant

4 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Introduction

Instrumentation is a fixed one, and the one in SmartPlant Materials a

flexible one. In addition, the hierarchy in SmartPlant Materials might
contain more levels than the one in SmartPlant Instrumentation.
Only a special list of users is allowed to import partial commodity parts. The
SmartPlant Materials part access functionality handles this.

Imported Entity Types

The interface supports three entity types: instrument, hookup, and cable drum. Each
of entity type requires different configuration in SmartPlant Materials.

Instrumentation Index
Main subjects of exchange are Field Itemized Instruments or Field-Tag Instruments.

The instruments are created in SmartPlant Instrumentation. They come to SmartPlant

Materials with the following information, or attributes:

• Commodity group
• Commodity part
• Tag number
• A set of sensitive attributes (a set of attributes plus values)
• Plant, which becomes part of the BOM-Path
• Area, which becomes part of the BOM-Path
• Unit, which becomes part of the BOM-Path
• Terminal node, which becomes part of the BOM-Path
To transfer instruments into SmartPlant Materials, you must create Commodity
Groups (S.10.02) and Commodity Parts (S.10.03) in SmartPlant Materials, which will
receive the transferred Commodity Codes. The attributes (A.50.01), which will be
used for the Commodity Code, with their attribute values (A.50.01, window 2) must
be maintained previously. The attributes are to be organized in attribute sets
(A.50.04) that must be associated with the Commodity Parts. If the node types and
the sources of Commodity Group/Part and Terminal Node are declared in IN 10.01,
you can create the database connection and the necessary views by clicking a button
on this screen. From SmartPlant Materials 5.5.3 on, the Group/Part/Terminal Node
definitions are contained in a free format view declaration in IN 10.01. Check the
prerequisites described later in this document.

After you have set up the information in the screens just discussed, use B.40.01 to
import the data. SmartPlant Materials will populate the WBS with standard tagged
material from SmartPlant Instrumentation. If attribute/value combinations are

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 5

Introduction

imported that cannot be mapped to an existing SmartPlant Materials Commodity

Code (CC), SmartPlant Materials automatically creates a new CC and ident.

6 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Introduction

Hook Ups
SmartPlant Materials reads the following SmartPlant Instrumentation information for
hookups:

• Plant, which becomes part of the BOM-Path

• Area, which becomes part of the BOM-Path
• Unit, which becomes part of the BOM-Path
• 4th level node, which can be specified by the user and becomes part of the
BOM-Path (optional)
• Hookup identifier, which is looked up as a ShortCode in S.70.01
Assembly Structure
• Instrument tag, which becomes TAG Number for List Position (optional)
• Instrument/piping class, which becomes Spec-Code for List Position (for
piping only)
• Flag the assembly if it will be imported
The SmartPlant Instrumentation source of hookups is declared in IN 10.01 by means
of a Hookup View select statement. This contains the eight data items listed above.
Additionally, the user has predefined the Commodity Groups/Parts/Codes he wants to
use in SmartPlant Materials and the Short Codes (S.10.08) for the assembly and its
assembly positions, as well as for specs (S.50.03) with their items (S.50.06).
Furthermore, the user has to build up the assembly structure (S.70.01). Check the
prerequisites described later in this document.

If you have adjusted everything, the import can be performed in B.40.01. SmartPlant
Materials will then fill the WBS with standard tagged or untagged material from
SmartPlant Instrumentation, depending on whether a tag number is provided for the
record. The child assemblies are inserted automatically for each position on short
code match of the master assembly.

Cable Drum
The following information is read from SmartPlant Instrumentation for cable drums:

• 1st level node, which can be specified by the user and becomes part of the
BOM-Path (optional)
• 2nd level node, which can be specified by the user and becomes part of the
BOM-Path (optional)
• 3rd level node, which can be specified by the user and becomes part of the
BOM-Path (optional)

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 7

Introduction

• 4th level node, which can be specified by the user and becomes part of the
BOM-Path (optional)
• Drum-number, which becomes the TAG Number in List Positions
• Cable-type, which is used as Commodity Code
• Drum-length, which becomes QTY in List Positions
• Unit of measure, which becomes QTY Unit in List Positions
The SmartPlant Instrumentation source of cable drums is declared in IN 10.01 by
means of a Cabledrum View select statement. This contains the eight data items listed
above. Additionally, the user has predefined the Commodity Groups/Parts/Codes he
wants to use in SmartPlant Materials. Check the prerequisites described later in this
document.

If you have adjusted everything, the import can be performed in B.40.01. SmartPlant
Materials will then fill the WBS with standard tagged material from SmartPlant
Instrumentation.

Error Handling
There are two distinct levels of error handling during SmartPlant Instrumentation
preprocessing. First are the fatal errors that lead to termination of the import and
rollback of all changes. The second type of error is only visible in the protocol file.
For example, single positions cannot be imported because some data is missing. If
this occurs, details are written to the log file. Set the message level (A.60.61) to 5 to
see important warnings and errors for SmartPlant Instrumentation. If you set it to 10,
you will get more output, and with level 20, you will get all information that is
provided concerning the SmartPlant Instrumentation section.

Import Protocol
For each OMI import job, several protocols and log files are created, depending on
whether the job runs in batch or in online mode. All entries from the SmartPlant
Instrumentation preprocessor appear at the beginning of the OMI main protocol file.
There are no extra log files produced for SmartPlant Instrumentation. You can review
the log file for online (not batch) jobs by clicking the View job logfile button.
Furthermore, the OMI import main program writes an import protocol; you can view
this protocol by pressing the View import protocol button.

Offline Mode
If the connection to the SmartPlant Instrumentation database cannot be established
for any reason in a specific project, the SmartPlant Instrumentation tables can be

8 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Introduction

imported into the SmartPlant Materials database using the Oracle export and import
utilities. This data can be accessed the same way as in the online mode.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 9

Prerequisites

Prerequisites
Oracle Settings
The online access service of the SmartPlant Materials SmartPlant Instrumentation
Interface requires a network connection to the SmartPlant Instrumentation database.
The access is done by Oracle database link, so the TNSNAMES.ORA on the
SmartPlant Materials database server must contain an appropriate entry.

Make sure that the init.ora GLOBAL_NAMES parameter for the SmartPlant
Materials database and for the SmartPlant Instrumentation database is set to FALSE,
which is the default.

Required Data in the MARIAN Database

The data needed for SmartPlant Instrumentation depends on the entity type that is the
subject of the import. There are three entity types: Instruments, Hookups and Cable
Drums.

Attributes
Attributes are needed for the Instrument entity type. Instrument material is organized
in attribute-based, rule-driven commodity codes. You must predefine those attributes
that you expect to export from SmartPlant Instrumentation into SmartPlant Materials.
The attributes must have valid descriptions defined in A.50.01 because SmartPlant
Instrumentation contains descriptive texts for attributes instead of attribute values.
SmartPlant Materials finds attribute values and assembles them to identify existing
commodity codes (CCs) or creates new ones. (See x-x-STO-ABC 39*.pdf for more
information.)

If a required attribute cannot be found, SmartPlant Materials generates free-format

CCs and places a message in the log file. If an attribute value or description is not
supplied for a special attribute, SmartPlant Materials assigns the value and
description, which are marked as default in A.50.01 Window 2.

Commodity Groups and Parts

Commodity Groups and Commodity Parts must be present in SmartPlant Materials
for all entity types. Please refer to the SmartPlant Materials standardization module
documentation for details on how to create this data. On screen IN 10.01, you must
specify where to retrieve your group and part data in SmartPlant Instrumentation for

10 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Prerequisites

the Instrument entity type. From MARIAN 5.5.3 on, the Group/Part/Terminal Node
definitions are contained in a free format view declaration in IN 10.01.

Units
The default unit for the material coming from SmartPlant Instrumentation must be
specified on screen IN 10.01 for Instrument and Hookup entity types. For the Cable
Drum entity type, the unit supplied in the SmartPlant Instrumentation import view
must also exist in SmartPlant Materials.

Node Types
The node types defined in B.10.03, which are needed for the nodes (plant, area unit
etc) coming from SmartPlant Instrumentation, must be specified on screen IN 10.01.
They are equal for each entity type. Plant is level 1, area is level 2, unit is level 3, and
terminal node is level 4.

Commodity Codes
The commodity codes imported for the Cable Drum entity type must exist in
SmartPlant Materials. They must be attribute-based commodity codes. Please refer to
the SmartPlant Materials standardization module documentation for details on how to
create this data.

Specs
The spec codes and the spec items imported for the Hookup entity type must exist in
SmartPlant Materials for idents to be found for the assembly positions. Please refer to
the SmartPlant Materials standardization module documentation for details on how to
create this data.

Short Codes
Short codes imported for the Hookup entity type must exist in SmartPlant Materials.
Please refer to the SmartPlant Materials standardization module documentation for
details on how to create this data.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 11

Prerequisites

Idents
The idents imported (or matched with import data) for the Hookup and Cable Drum
entity types must exist in SmartPlant Materials. Idents for the Cable Drum entity type
must belong to SWT. Please refer to the SmartPlant Materials standardization module
documentation for details on how to create this data.

Project Defaults
For the Instrument entity type, the project defaults ZS_AB_AGR (for the default
attribute group) and ZS_AB_UNIT (for the default attribute unit) should be set.
These values are looked up, even if they are not needed. If you insert the Hookup
entity type, the assembly positions inherit the tag number from the assembly header
and become ItemType SWT=Standard with Tag. To allow import of tagged material
with quantities greater than one, set the ZB_TAGQTY to 'N', preventing OMI from
rejecting those records.

Creatable Data in the SmartPlant Materials

Database

Commodity Codes
The commodity codes to which you want to import ident data in the WBS can already
exist for the Instrument entity type. If they do not exist, SmartPlant Materials tries to
create them based on the supplied attribute information describing the commodity
codes. Commodity codes have the item rule "SWT".

Idents
Idents that you want to place in the WBS can already exist. If they do not exist,
SmartPlant Materials tries to create them. Idents have their geometric sizes set to
zero.

WBS Structure
The node hierarchy, which comes from SmartPlant Instrumentation, can be
predefined in the SmartPlant Materials WBS. Each node that exists in SmartPlant
Instrumentation, but not in SmartPlant Materials, is created during the import job if
the node is selected for transfer during the current job.

12 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Data Import

Data Import
This chapter illustrates how the SmartPlant Instrumentation Interface can be used.
Before you can use the interface, all its components must be properly installed and
configured as described in this document.

Configure SmartPlant Instrumentation Interface

To configure the interface, use the SmartPlant Materials IN 10.01 screen.

SmartPlant Materials Settings

Node Types
After defining node types in B.10.03, define the node types for each of the levels.
SmartPlant Materials uses four levels. Three are identical to the structure in
SmartPlant Instrumentation (plant, area, unit). The terminal node is a means of
subdividing the material within one unit. From MARIAN 5.5.3 on, the Terminal
Node definitions are contained in a free format view declaration in IN 10.01. If you
transfer the Hookup entity type, the terminal node is defined in the Hookup View.
For the Cable Drum entity type, the Cable Drum View is used. For each entity type,
there are four node levels available. The node types used are the same independent
from the entity type.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 13

Data Import

Default Quantity Unit

After inserting units in A.10.12, make one of them the default unit for material
coming from SmartPlant Instrumentation. This unit is used for instrument and hookup
items. The child positions of the hookup have their own quantity unit defined in
S.70.01. The cable drum items have their unit defined in the Cable Drum View field.

SmartPlant Instrumentation Settings

Sources for Instruments

Instrument View
The location of instrument data in SmartPlant Instrumentation can be configured
here. The Instrument View contains all information needed by means of SQL. The
statement has the following form:
SELECT column_1,
column_2,
. . .
column_n
FROM table_1@,
table_2@
WHERE column6 = column3
AND column4 = column5
The following is fixed in this statement:

Select List
There must be exactly ten columns in the select list. If you want to leave one of them
out, do not omit the column but enter NULL in the column. The columns are used in
the following order and for the following purposes:
1. Component ID (primary key on the component table in SmartPlant
Instrumentation)
2. Tag Number (maximum 24 digits)
3. Plant name for instrument in WBS (maximum 20 digits)
4. Area name for instrument in WBS (maximum 20 digits)
5. Unit for instrument in WBS (maximum 20 digits)
6. Level 4 (formerly called terminal node, but it isn’t necessarily the terminal node
in the true sense of the word) for instrument in WBS (maximum 20 digits)
7. SmartPlant Materials Commodity Group Code (maximum 10 digits)
8. SmartPlant Materials Commodity Part Code (maximum 10 digits)

14 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Data Import

9. Level 5 for instrument in WBS (maximum 20 digits)

10. Level 6 for instrument in WBS (maximum 20 digits)
The name of the columns is free. In SmartPlant Instrumentation, some columns have
a CHAR data type instead of VARCHAR2 data type. CHAR has a fixed length. If the
actual value is not the same length as the column definition, the remaining digits are
filled with blanks. To avoid problems in SmartPlant Materials, use the RTRIM
function to cut off trailing blanks from fields.

Where Condition
You must reflect the reference to the values selected in IN 20.01 by including
placeholders in the WHERE section of your statement. Users can define a name for
the placeholders. They must appear in the following order:
1. Plant name for instrument in WBS
2. Area name for instrument in WBS
3. Unit for instrument in WBS
4. Level4 (terminal node) for instrument in WBS
5. Level5 for instrument in WBS
6. Level6 for instrument in WBS
You do not need to use all of the levels, but you must include all four in your
statement.

To include a level without using it, use an expression like the following:
WHERE decode(:level_4,'%','%','%')='%'
This expression replaces anything that might be selected in IN 20.01 for level_4 by a
percent and compares it to percent, so the filtering for level_4 is switched off.

The "at" sign (@) appended to your table names in the statement is enhanced by the
appropriate database link name at run time.

Note, that the ORDER BY clause in your view should contain all levels you plan to
use. Otherwise the import might import fewer positions than expected.

Here is a valid example:

SELECT dflt.cmpnt_id,
dflt.cmpnt_name AS tag_number,
p.plant_name,
a.area_name,
u.unit_name,
substr(udf.udf_c01,1,4) AS terminal_node,
substr(udf.udf_c01,1,2) commodity_group,
substr(udf.udf_c01,3,4) AS commodity_part,
udf.udf_c02 AS level5_name,
udf.udf_c03 AS level6_name
FROM component@ dflt,

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 15

Data Import

plant_area@ a,
plant@ p,
plant_area_unit@ u,
udf_component@ udf
WHERE p.plant_name like :plant_name
AND a.area_id = dflt.area_id
AND u.unit_id = dflt.unit_id
AND a.plant_id = dflt.plant_id
AND a.area_id = u.area_id
AND u.plant_id = p.plant_id
AND a.area_name LIKE :area_name
AND u.unit_name LIKE :unit_name
AND dflt.cmpnt_id>0
AND udf.compnt_id=dflt.compnt_id
AND udf.udf_c01 LIKE :level4_name
AND udf.udf_c02 LIKE :level5_name
AND udf.udf_c03 LIKE :level6_name
ORDER BY
p.plant_name,a.area_name,u.unit_name,substr(udf.udf_c01,1,4),
udf_c02,udf_c03

Instrument LevelX
The Instrument LevelX fields may contain a source for the LOVs in IN 20.01 for the
4th to 6th level node. The first three levels are plant, area and unit. The fourth level is
the terminal node. You may leave the fields blank if you do not need six levels. To
support these levels with LOV, use a statement in the following format:
SELECT column_name AS column_alias
FROM table_name@
The column name, alias and the table_name can be chosen deliberately. Additionally
you may place an LOV title in comments (eg., /* Your Title */) within your
statement.

The "at" sign (@) is enhanced by the appropriate database link name at run time.

If you want your selection to depend on previous selections in IN 20.01, you can use
the following variables to refer to the appropriate fields on the screen:

:SmartPlant Instrumentation_selection.plant_name for instrument level 1

:SmartPlant Instrumentation_selection.area_name for instrument level 2

:SmartPlant Instrumentation_selection.unit_name for instrument level3

:SmartPlant Instrumentation_selection.cft_name for instrument level4

(terminal node)

:SmartPlant Instrumentation_selection.level5_name for instrument

level5

:SmartPlant Instrumentation_selection.level6_name for instrument

level6

16 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Data Import

Here is an example:
SELECT substr(tn.udf_c05,1,1) tnode_name
/* Terminal Nodes */
FROM udf_component@ tn where tn.udf_c03=:SmartPlant
Instrumentation_selection.unit_name

Sources for Hookups

Hookup View
The location of hookup data in SmartPlant Instrumentation can be configured here.
The Hookup View contains all information needed by means of SQL. The statement
has the following form:
SELECT column_1,
column_2,
. . .
column_n
FROM table_1@,
table_2@
WHERE column6 = column3
AND column4 = column5
The following is fixed in this statement:

Select List
There must be exactly eight columns in the select list. If you want to leave one of
them out, do not omit the column but enter NULL in the column. The columns are
used in the following order and for the following purposes:
1. Plant name for hookup in WBS (maximum 20 digits)
2. Area name for hookup in WBS (maximum 20 digits)
3. Unit for hookup in WBS (maximum 20 digits)
4. Level 4 for hookup in WBS (maximum 20 digits)
5. SmartPlant Materials spec code (maximum 16 digits)
6. SmartPlant Materials short code (maximum 10 digits)
7. SmartPlant Materials tag number (maximum 24 digits)
8. Flag (maximum 10 digits)
The name of the columns is free. In SmartPlant Instrumentation, some columns have
a CHAR data type instead of VARCHAR2 data type. CHAR has a fixed length. If the
actual value is not the same length as the column definition, the remaining digits are
filled with blanks. To avoid problems in SmartPlant Materials, use the RTRIM
function to cut off trailing blanks from fields. The flag field is an indicator of whether
to include the component in the import run. However, the restriction to exclude
certain components must be implemented by the user in this view.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 17

Data Import

Where Condition
You must reflect the reference to the values selected in IN 20.01 by including
placeholders in the WHERE section of your statement. Users can define a name for
the placeholders. They must appear in the following order:
1. Plant name for hookup in WBS
2. Area name for hookup in WBS
3. Unit for hookup in WBS
4. Level 4 for hookup in WBS
You do not need to use all of the levels, but you must include all four in your
statement.

To include a level without using it, use an expression like the following:
WHERE decode(:level_4,'%','%','%')='%'
This expression replaces anything that might be selected in IN 20.01 for level_4 by a
percent and compares it to percent, so the influence of level_4 is switched off.

The "at" sign (@) appended to your table names in the statement is enhanced by the
appropriate database link name at run time.

Note, that the ORDER BY clause in your view should contain all levels you plan to
use. Otherwise the import might import fewer positions than expected.

Here is an example (ORDER BY needs to be appended):

SELECT
plant.plant_name AS plant,
plant_area.area_name AS area,
plant_area_unit.unit_name AS unit,
hook_up_type.hu_type_name AS hu_category_level4,
NVL(udf_component.udf_c132, udf_component.udf_c131) AS pipe_or_instr_spec,
hook_up.hu_name AS short_code,
component.cmpnt_name AS tag_number,
hook_up_component.bom_include_flg AS flag
FROM
plant@,
plant_area@,
plant_area_unit@,
hook_up@,
hook_up_type@,
hook_up_component@,
component@,
udf_component@
WHERE
component.cmpnt_id = udf_component.cmpnt_id AND
component.plant_id = plant.plant_id AND
component.area_id = plant_area.area_id AND
plant_area_unit.unit_id = component.unit_id AND
hook_up_type.hu_type_id = hook_up.hu_type_id AND
hook_up.hu_id = hook_up_component.hu_id AND
hook_up_component.cmpnt_id = component.cmpnt_id AND

18 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Data Import

component.cmpnt_id <> 0 and

plant.plant_name LIKE :plant_name AND
plant_area.area_name LIKE :area_name AND
plant_area_unit.unit_name LIKE :unit_name AND
hook_up_type.hu_type_name LIKE :level4

Hookup Level4
The Hookup Level4 field may contain a source for the LOV in IN 20.01 for the 4th
level node. You may omit this if you do not need the 4th level. To support the 4th level
with an LOV, use a statement in the following format:
SELECT column_name
FROM table_name@
The column name and the table_name can be chosen deliberately. Additionally you
may place an LOV title in comments (eg., /* Your Title */) within your statement.

The "at" sign (@) is enhanced by the appropriate database link name at run time.

If you want your selection to depend on previous selections in IN 20.01, you can use
the following variables to refer to the appropriate fields on the screen:
:SmartPlant Instrumentation_selection.plant_name
:SmartPlant Instrumentation_selection.area_name
:SmartPlant Instrumentation_selection.unit_name
Here is a valid example that lets the hookup type be selected as the 4th level node in
the unit:
select distinct /*Hook Up Category*/ hu_type_name
FROM hook_up_type@
The string in comment format (Hook Up Category in the previous example) is used as
a field and as a LOV title.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 19

Data Import

Sources for Cable Drums

Cable Drum View

The Cable Drum View defines by means of SQL the source of cable drum
information in SmartPlant Instrumentation. The statement is in the following format:
SELECT column_1,
column_2,
. . .
column_n
FROM table_1@,
table_2@
WHERE column6 = column3
AND column4 = column5
The following is fixed in this statement

Select List
There must be exactly eight columns in the select list. If you want to leave one of
them out, do not omit the column but enter NULL in the column. The columns are
used in the following order and for the following purposes:
1. Level 1 for cable drum in WBS (maximum 20 digits)
2. Level 2 for cable drum in WBS (maximum 20 digits)

20 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Data Import

3. Level 3 for cable drum in WBS (maximum 20 digits)

4. Level 4 for cable drum in WBS (maximum 20 digits)
5. SmartPlant Materials commodity code (maximum 20 digits)
6. Quantity (maximum 15 digits, 3 after decimal point)
7. Quantity unit (maximum 10 digits)
8. SmartPlant Materials tag number (maximum 24 digits)
The name of the columns is free. In SmartPlant Instrumentation, some columns have
a CHAR data type instead of VARCHAR2 data type. CHAR has a fixed length. If the
actual value is not the same length as the column definition, the remaining digits are
filled with blanks. To avoid problems in SmartPlant Materials, use the RTRIM
function to cut off trailing blanks from fields.

Where Condition
You must reflect the reference to the values selected in IN 20.01 by including
placeholders in the WHERE section of your statement. Users can define a name for
the placeholders. They must appear in the following order:
1. Level 1 for cable drum in WBS
2. Level 2 for cable drum in WBS
3. Level 3 for cable drum in WBS
4. Level 4 for cable drum in WBS
You do not need to use all of the levels, but you must include all four in your
statement.

To include a level without using it, use an expression like the following:
WHERE decode(:level_4,'%','%','%')='%'
This expression replaces anything that might be selected in IN 20.01 for level_4 by a
percent and compares it to percent, so the influence of level_4 is switched off.

The "at" sign (@) appended to your table names in the statement is enhanced by the
appropriate database link name at run time.

Note, that the ORDER BY clause in your view should contain all levels you plan to
use. Otherwise the import might import fewer positions than expected.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 21

Data Import

Here is an example (ORDER BY needs to be appended):

SELECT p.plant_name AS level1,
NULL AS level2,
NULL AS level3,
NULL AS level4,
ct.cable_type_name AS commodity_code,
c.cable_length AS qty,
rtrim(uc.cbl_udf_c01) AS unit_code,
substr(c.cable_num,1,24) AS tag_number
FROM cable@ c,
cable_type@ ct,
udf_cable@ uc,
plant@ p
WHERE c.cable_id = uc.cable_id AND
c.plant_id = p.plant_id AND
uc.cable_id = c.cable_id AND
ct.cable_type_id = c.cable_type_id AND
p.plant_name LIKE :plant_name AND
decode(:level2,'%','%','%')='%' AND -- making level 2 irrelevant
decode(:level3,'%','%','%')='%' AND -- making level 3 irrelevant
decode(:level4,'%','%','%')='%' -- making level 4 irrelevant

Cable Drum LevelX

The Cable Drum LevelX field may contain a source for the LOVs in IN 20.01 for
the 1st to 4th level node. You may leave the fields blank if you do not need four levels.
To support these levels with an LOV, use a statement in the following format:
SELECT column_name AS column_alias
FROM table_name@
The column name, alias and the table_name can be chosen deliberately. Additionally,
you may place an LOV title in comments (eg., /* Your Title */) within your
statement.

The "at" sign (@) is enhanced by the appropriate database link name at run time.

If you want your selection to depend on previous selections in IN 20.01, you can use
the following variables to refer to the appropriate fields on the screen:

:SmartPlant Instrumentation_selection.plant_name for cable drum level

1

:SmartPlant Instrumentation_selection.area_name for cable drum level 2

:SmartPlant Instrumentation_selection.unit_name for cable_drum level3

Here is a valid example:

SELECT SUBSTR(cmpnt_func_type_desc,1,4) AS cft
FROM component_function_type@
WHERE cmpnt_func_type_name= :SmartPlant
Instrumentation_selection.unit_name

22 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Data Import

SmartPlant Instrumentation Access

Enter the user name, password, and database alias for the connection that you want to
establish to the SmartPlant Instrumentation database. The database alias must be
defined in the TNSNAMES.ORA file of the database server. When you click the
Create DB Link button, the connection is established and validated. Click the
Create Views button to install the needed views on the SmartPlant Materials
database; these views depend on the database link.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 23

Data Import

Configure Attributes Plus Values

For transfer of the Instrument entity type, you must enter all needed attributes in
A.50.01. In the second window, you can define a list of valid values with their
descriptions.

The first value in curly brackets

will be part of the commodity code
The valid value will be part of description if one of the
the commodity code string. descriptions in the brackets
matches the value from SmartPlant

A number of synonyms
can be defined.

One of these values may come from the SmartPlant Instrumentation database and
should match the values defined in MARIAN. The values can contain wildcards:
“_” (underscore) to replace one character or “%” (percent) to replace none or
more characters.
If an empty value is imported from SmartPlant Instrumentation, there are two
possibilities:
• If a default value has been defined, MARIAN will take it, and the commodity
code will contain the default value.
• If no default value has been defined, an error message is generated in the log
file, and a free format commodity code is generated. Free format means that
no fixed attribute set (A.50.04) is enforced to create the commodity code
string. The commodity code will be concatenated from the part code plus a
sequential number.
If a value comes from SmartPlant Instrumentation that is not contained in the
Valid Descriptions or in the Valid Values, an error message is generated in the

24 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Data Import

Configure Attribute Sets

Use A.50.04 to transfer the Instrument entity type and complete the attribute sets that
you want to use to build CCs with the information where the data for your attributes
can be found in SmartPlant Instrumentation.

The source for the attributes M_COMMODITY_GROUPS and M_PARTS can be left
out because their definition cannot depend on attribute sets. Their source is stored in
IN 10.01 and is equal for the whole project.

The location of the other attributes in SmartPlant Instrumentation can be configured.

The column information tells SmartPlant Materials from which database column in
SmartPlant Instrumentation to query the data. The table is the physical table in
SmartPlant Instrumentation from which the information is fetched. You are not
required to enter a table name if your column belongs to the same table from which
the tag number is retrieved. The tag number for instruments is the column
cmpnt_name within the component table. Therefore, if you use another column in this
table as attribute information, such as cmpnt_serv, you can leave the table field blank.
The same is true for the join column field. The join column field is used to connect
the tag-number-table with the table that contains the column that you want to use as
attribute information.

You can use SQL functions in the column field, for example, to retrieve only a
substring of the requested column. The column name is always prefixed
automatically by the program internally. You will not see the prefix. If you use SQL
functions, SmartPlant Materials cannot set this prefix, so you will have to set it
manually. Always use "dflt" if your column is in the tag-number-table. In other cases,
use "other."

You cannot use SQL functions in the join column field.

Any leading and trailing blanks from the data are removed automatically.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 25

Data Import

Define Assembly Structure

If you want to import hookups, use SmartPlant Materials screen S.70.01 to define the
assemblies.

You must predefine all short codes that you want to use on screen S.10.08. The
assembly is only described by short code, while the child has a position number, a
short code, a quantity, and up to three sizes. Leave out the spec code in both cases.
The concentric reducer in this example may have a second size. The sizes entered in
inches are first looked up, and then the values in the metric fields are looked up. The
default values (-1, -2, and –3) mean that the sizes should be taken from the master
assembly, but this function is not used for the SmartPlant Materials workflow. You
do not have to set -1, -2, and -3 equal to zero in this screen, but the interface will treat
them as zero. The sizes entered have to be predefined in an arbitrary nominals size
table (S.40.01).

26 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Data Import

Define Import Job

To define an import job, use SmartPlant Materials screen B.40.01.

The following settings are specific to SmartPlant Instrumentation:

1. Choose the by SmartPlant Instrumentation Online Access data source.
2. Specify a BOM start node. This step is mandatory.
3. Choose an Issue Status and a List Status. This step is mandatory.
4. Click the Specific Settings button and enter the nodes that you want to include in
this import run. You can select them with LOV or type them in manually. You
can use the Oracle underscore and percent wildcard symbols.
5. When you complete your list, click the Ok button to return to B.40.01.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 27

Data Import

6. Select the Transfer check box.

Tip
• You are not required to select any of the other check boxes on
B.40.01.
7. Now you can save your job definition and start the job.
Refer to the SmartPlant Materials Open MTO Interface Guide (x-x-INT OMI
3E.pdf) for more information about job definition and execution with B.40.01.

28 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Offline Mode

Offline Mode
This chapter illustrates how the SmartPlant Instrumentation Interface can be used in
offline mode. SmartPlant Instrumentation tables are exported using the Oracle export
utility and imported into the SmartPlant Materials database using the Oracle import
utility. The database link in IN 10.01 is simply directed to the schema in the
SmartPlant Materials database where the SmartPlant Instrumentation tables are
stored. The data can be exported and imported on a regular basis or on demand.
However, the whole procedure is done outside the SmartPlant Materials application
either by a batch job or manually.

Export SmartPlant Instrumentation Data

The Oracle export utility provides a way to transfer data objects between Oracle
databases, even if they reside on platforms with different hardware and software
configurations. Export extracts the object definitions and table data from an Oracle
database and stores them in an Oracle binary format export dump file located on the
file system.

Such files can then be transferred using FTP, e-mail, and so on or even physically
transported using tape or floppy disk. The files can then be used with the Oracle
import utility to transfer data between databases that are on machines that are not
connected through a network.

A typical export job started from the command line looks like the following:
exp <user>/<password>@<database> owner=<user>

The <user> is typically the owner of the tables; you only need the owner option if you
export the data logged in as administrator. Instead of exporting all of the user's
objects, you can export tables by defining a comma-separated list:
tables=(component,udf_component). If you have a longer list of tables, you typically
would not include them all in the command line, but you would edit a text file
containing all parameters for the export. Starting the export would be done with the
following:
exp <user>/<password>@<database> parfile=myparms.txt

The parameter file can look like the following:

FILE=expdat.dmp
TABLES=(component,udf_component)
LOG=exp.log

With the FILE option, you can determine the name of the resulting dump file. The
LOG option specifies the name and location of the export log file.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 29

Offline Mode

For SmartPlant Materials, you must at least export the plant, plant_area,
plant_area_unit, and the component table if you want import the Instrument or
Hookup entity types. Additionally, you must export each table you specify in A.50.04
or IN 10.01 (Hookup View, Cable Drum View) for your import.

Create a New Schema in the SmartPlant Materials

Database
You can create a new Oracle user in the SmartPlant Materials database. In SQL*Plus,
you can log in with administrator privileges and use the following syntax:
create user SmartPlant Instrumentation identified by SmartPlant
Instrumentation;

This will create a new user called "SmartPlant Instrumentation", but you can use
another name. Give the user rights to connect to the database and the ability to have
his own database objects using the following syntax:
grant connect,resource to SmartPlant Instrumentation;

Remove Existing SmartPlant Instrumentation Data

If you imported a dump file containing the same tables for this user previously, you
must clear all tables before a new import. Delete can be done with the following
statement in SQL*Plus:
truncate table <tablename>;

You can also drop the whole user by using the cascade option to erase all the user's
objects:
drop user SmartPlant Instrumentation cascade;

Import SmartPlant Instrumentation Data

The Oracle import utility inserts the data objects extracted from one Oracle database
by the export utility (and stored in an export dump file) into another Oracle database.

The import can be started from command line using the following syntax:
imp userid=SmartPlant Instrumentation/SmartPlant
Instrumentation@<database> file=expdat.dmp fromuser=<SmartPlant
InstrumentationDBuser> touser=SmartPlant Instrumentation

The user "SmartPlant Instrumentation" from the example in previous section is used
again. The fromuser option allows you to specify the name of the schema user where
you exported the data from, and touser is the destination. If you export, for example,
a schema in SmartPlant Instrumentation logged in as the owner and you create the
same user in the SmartPlant Materials database, you do not need to specify the

30 SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration

 Offline Mode

fromuser and touser. However, if you export as "system", for example, and import to
another user in the SmartPlant Materials database, you need both of the fromuser and
touser names. To export the data of one user into a schema of a different user, you
must either log on to the SmartPlant Materials database with the same user account
used to create the dump, or you must log in with administrator privileges. As
described with the export utility, you can use the parfile option to point to a text file
where all your options are stored.

Direct Database Link Points to New Schema

The database link set up in IN 10.01 can now be directed to user/password for the
database from which the import was made.

SmartPlant Materials INtools (SmartPlant® Instrumentation) Integration 31