SmartPlant Materials Open MTO Interface (OMI)

SmartPlant Materials Open MTO Interface (OMI)

Version 2011 R1 (7.1.0)

November 2013

DMAR1-PE-200003I

Copyright Copyright © 2002- 2013 Intergraph® Corporation. All Rights Reserved. Intergraph is part of Hexagon.

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 from Intergraph Corporation.

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 300 Intergraph Way Huntsville, AL 35813

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 End User License Agreement ("EULA") 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 EULA or does not have a valid licenseagreement 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. 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 EULA 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.

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.

2 SmartPlant Materials Open MTO Interface (OMI)

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 software products and any third-party Software Products obtained from Intergraph Corporation, its subsidiaries, or distributors (including any Documentation, Other Documentation or technical data related to these products) are subject to the export control laws and regulations of the United States. Diversion contrary to U.S. law is prohibited. These Software Products, and the direct product thereof, must not be exported or re-exported, directly or indirectly (including via remote access) under the following circumstances:

a. To Cuba, Iran, North Korea, Sudan, or Syria, or any national of these countries. b. To any person or entity listed on any U.S. government denial list, including but not limited to, the U.S. Department of Commerce

Denied Persons, Entities, and Unverified Lists, http://www.bis.doc.gov/complianceandenforcement/liststocheck.htm, the U.S. Department of Treasury Specially Designated Nationals List, http://www.treas.gov/offices/enforcement/ofac/, and the U.S. Department of State Debarred List, http://www.pmddtc.state.gov/compliance/debar.html.

c. To any entity when Licensee knows, or has reason to know, the end use of the Software Product 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 Licensee knows, or has reason to know, that an illegal reshipment will take place. e. Any questions regarding export or re-export of these Software Products should be addressed to Intergraph Corporation’s Export

Compliance Department, Huntsville, Alabama 35894, USA.

Trademarks Intergraph, the Intergraph logo, Intergraph Smart, PDS, SmartPlant, SmartMarine, FrameWorks, I-Sketch, IntelliShip, ISOGEN, SmartSketch, SPOOLGEN, SupportManager, SupportModeler, Sapphire, and FreeView are trademarks or registered trademarks of Intergraph Corporation or its subsidiaries in the United States and other countries. 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 Materials Open MTO Interface (OMI) 3

Contents Preface .......................................................................................................................................................... 7

Documentation Comments ..................................................................................................................... 7

Conceptual Overview .................................................................................................................................. 9

SmartPlant Materials BOM Data Structures ........................................................................................... 9 Propagating Variable BOM Attributes ................................................................................................... 10 BOM Issue Status ................................................................................................................................. 10 BOM Revision Control and Release/Lock Status ................................................................................. 11 Design Change Control ......................................................................................................................... 11 Mapping BOM Hierarchical Data to a Flat File Structure ...................................................................... 11 Processing PDS BOM Reports ............................................................................................................. 12 Processing SmartPlant® Instrumentation Data .................................................................................... 12 Open API Features ............................................................................................................................... 12

Prerequisites .............................................................................................................................................. 13

ORACLE Tools...................................................................................................................................... 13 Required Data in the SmartPlant Materials Database .......................................................................... 13 Database Configuration ........................................................................................................................ 14

Imported Data ............................................................................................................................................ 15

General File Format .............................................................................................................................. 15 Record Types ........................................................................................................................................ 15 Record Layout ....................................................................................................................................... 17 Processing Logic ................................................................................................................................... 26

Transfer / Simulation Mode ............................................................................................................ 27 Replace / Append Mode ................................................................................................................. 28 Position Numbering ........................................................................................................................ 28 Design Change Control: Processing Site Quantities ...................................................................... 28 Delayed automatic reissue of DCI quantity .................................................................................... 31 Tagged Items .................................................................................................................................. 31 TAG – Attribute Based Tag ............................................................................................................ 32 BOM Assemblies ............................................................................................................................ 33 Import with Company Mapping ....................................................................................................... 33 Fabrication Tracking - Spool Import Mode ..................................................................................... 34 Object Codes and Recognize Mode ............................................................................................... 35

Import File Example .............................................................................................................................. 36

Data Import ................................................................................................................................................. 39

File Placement ...................................................................................................................................... 39 Defining an Import Job .......................................................................................................................... 39 Starting Job Execution .......................................................................................................................... 40 Reviewing the Import Protocol .............................................................................................................. 41

Flat Loading Config Import....................................................................................................................... 43

Collect Import Data ............................................................................................................................... 44


Contents

Define Column Mappings ...................................................................................................................... 45 Start Flat Loading Config Import ........................................................................................................... 53

BOM Data Export ....................................................................................................................................... 57

Selecting Data to be Exported .............................................................................................................. 57 Specifying Export Parameters .............................................................................................................. 58 Starting BOM Export ............................................................................................................................. 59

Open API..................................................................................................................................................... 61

Available PL/SQL Packages ................................................................................................................. 61 Integration of Data Loading CIP Procedure .......................................................................................... 61 Creating a Job Programmatically .......................................................................................................... 62 Loading Data Programmatically ............................................................................................................ 62 Event Procedures.................................................................................................................................. 63 Transaction Control ............................................................................................................................... 65 Sample Code and Demonstrations ....................................................................................................... 65

Implementation Reference........................................................................................................................ 67

SmartPlant Materials Tables ................................................................................................................. 67 Stored PL/SQL Program Units .............................................................................................................. 67 Transaction Control ............................................................................................................................... 68 Lock Handling ....................................................................................................................................... 68

Appendix: Setup and Configuration ........................................................................................................ 69

Directories and Files ............................................................................................................................. 69 File Placement for Online and Batch Jobs ............................................................................................ 69 Adjusting the SQL*Loader Parameter File ............................................................................................ 69 Configuring SmartPlant Materials Settings ........................................................................................... 69

Relevant DBA Settings ................................................................................................................... 70 Relevant Project/Discipline Default Settings .................................................................................. 71 Lock Handling Setup ...................................................................................................................... 73

Appendix: Error Messages ....................................................................................................................... 75

Appendix: Utility Files and Scripts .......................................................................................................... 77

SQL*Loader Parameter File .................................................................................................................. 78 Export Script (B.20.01.44) ..................................................................................................................... 78 Import Protocol Report Script (B.40.R.01) ............................................................................................ 81

Index ........................................................................................................................................................... 85


This document describes the Open MTO Interface (OMI).

Documentation Comments Send documentation comments or suggestions to [email protected] (mailto:[email protected]?subject=documentation comments).

Preface


mailto:[email protected]?subject=documentation%20comments

Preface


S E C T I O N 1

The Open MTO Interface (OMI) is the standard interface for easy and transparent access to all the data in the Bill of Materials (BOM) module.

OMI allows you to import and export complete project BOM structures or any selected subsets of that structure. Because it can work with plain ASCII files in their own native format as well as with PDS® standard type-G BOM reports, it allows for a convenient interchange of structured BOM data with external systems as well as with other SmartPlant Materials systems.

Additionally, an open PL/SQL API is provided. This API makes it much easier for SmartPlant Materials users to develop and implement a customized solution to retrieve and preprocess BOM data from their existing data sources in cases where creation and loading of ASCII files may not be desirable. This API is seamlessly integrated with the standard OMI processing and enables users to import data from such external data sources in one single step.

This chapter provides an overview of BOM terminology and key concepts. Understanding these concepts is necessary for an understanding of how the OMI interface works and using its features to their fullest extent.

SmartPlant Materials BOM Data Structures The central Bill of Materials (BOM) tables consist of a two-fold recursive structure: One of these is the table M_LIST_NODES, which stores the structure of BOMs. Each record in this table represents a BOM node, which has a project reference, a node name, a type reference, and optionally, a parent node reference. The second one is the M_LIST_POS table, which stores the BOM positions in the context of a BOM node. This table also has a recursive structure to allow creation and structured storage of BOM assemblies.

Both tables have several detail tables, so it is possible to associate description text in several languages to each BOM node, or to enter document references for individual BOM positions. The most important detail tables are those that store the variable attribute values. For nodes, this is the M_LIST_NODE_VALUES table; for positions, it is the M_LIST_POS_VALUES table. Records in both tables reference a specific attribute from A.50.01 and have a field to hold the assigned attribute value.

These attributes are user-definable, which allow for easy setup of a customized data structure that can hold all the information about your BOM data, without you having to hard-code this data structure into the physical data model. This feature makes the BOM module very flexible and easy to customize.

Conceptual Overview


Conceptual Overview

Propagating Variable BOM Attributes When BOM data is entered or loaded, records for variable attributes for nodes and for positions are created automatically, with an initially empty value field. The attributes that are assigned depend on the data item.

For BOM nodes, records for all attributes that are assigned to the specific node type (B.10.03) are created. Additionally, all attributes along with their values that are present for the parent node are also propagated to the new node.

For BOM positions, records for all attributes that have been set up as discipline-dependent position attributes in B.10.04 are created. Additionally, all attributes and their values that are present for the BOM node to which the position belongs are also propagated to the new position.

Whenever an attribute value is changed, the modified value is propagated downwards through the BOM hierarchy such that all attributes that have not been changed on this lower level will also be updated accordingly; for example, modification of an attribute value on the topmost node of a BOM hierarchy will also update this attribute on all BOM nodes and BOM positions that are located beneath this root node and that are not locked.

The main purpose of this mechanism is to have all significant attributes that may be needed as a query criterion or as an MTO grouping criterion available on all levels of the Bill of Materials.

BOM Issue Status For each BOM node, SmartPlant Materials allows you to have different sets of BOM positions that basically represent the same material requirements but are distinguished by a separate issue status. All issue status definitions are comparable by their order sequence number, indicating the progress or the quality increase of each BOM positions data set from one issue status to the next. For example, the first issue status could be an initial rough estimate, the next could be the preliminary design, and the third one could be the final design. In the downstream workflow, SmartPlant Materials can use the different issue statuses in the BOM data to apply a ‘Best Quantity’ logic when creating engineering requisitions in the requisitioning and Material Take Off module.

All data that is imported through OMI is also subject to this logic. You can specify the issue status into which positions data is loaded as a default parameter for the import job; furthermore, you have the option to include a different issue status on the BOM node level in your import data that individually overrides the import job default parameter for specific subsets of the positions data.


Conceptual Overview

BOM Revision Control and Release/Lock Status The BOM module also provides a means to release (that is, locking) selected BOM nodes. This functionality is available through the B.20.01.35 Verification and Status screen. Release of BOM data is driven by list status, which is a non-key attribute on the BOM positions table that indicates the data quality with regard to user-definable data requirements. After a node is locked, no changes to its detail data are allowed unless a new revision is created. Creating a new revision saves the data of the old (locked) revision into a history table to allow tracking of changes throughout several revisions, and creating a new revision also resets the list status on the position level back to the default initial list status.

For BOM data import through OMI, you can specify how the import program should handle locked nodes for which modification data is in the import file. You can allow OMI to create a new revision automatically in such a case, or you can specify that such data should remain unchanged and the BOM lock respected.

Design Change Control The SmartPlant Materials Site module stores reserved and issued quantities against the BOM positions table. This makes it necessary to handle the business case of a BOM modification through OMI when material from this BOM is either already reserved or even already issued on site, for example, because of design changes.

To control how such modifications should be processed, the Transfer Site Qty check box on B.40.01 and the ZI_OMI_DCC and ZI_OMI_DCA project defaults are available. If configured for automatic Design Change Control, OMI logs design changes, performs automatic cancellation of over-reserved quantities, reissues design change quantities to appropriate design change warehouses, and logs reservation shortages. User acknowledgments of such events are tracked by a system-generated Material and Design Maintenance number.

Detailed processing rules for the "Transfer Site Qty" option and the "Design Change Control" option are documented in Processing Logic (on page 26).

Mapping BOM Hierarchical Data to a Flat File Structure

OMI uses two distinct methods of mapping the recursive BOM structure to a flat ASCII file. For BOM nodes, you must sequentially provide all nodes from root to leaf node in your import file, using the NODE_BEGIN and NODE record types. Together, these nodes form a unique description of one path through the BOM tree. You repeat this path description for all leaf nodes into which you want to import positions data. Detail data to the nodes themselves (such as NLS descriptions, node attribute values) must be provided only for the first occurrence of each node, so you do not need to (and for performance reasons, you should not) repeatedly include this data with each new incarnation of a node record in a different BOM path.

For import of BOM assemblies, you specify the assembly structure by providing a number that indicates the level in the structure. The assembly structure is processed by the import program through the use of a stack data structure.


Conceptual Overview At any point in time, OMI keeps track of the current import context as it processes the import data in a sequential manner from the interface table while at the same time it navigates through the recursive data structures of your BOM by using a state-driven programmatic approach.

Processing PDS BOM Reports It is possible to import PDS standard G-type BOM reports, or ISOGEN®-formatted reports into the SmartPlant Materials BOM module. In order to do this import operation, a separate SQL*Loader control file is used to transfer the PDS report into an intermediate table where its contents are transformed internally into the OMI format, and then are further processed like any other OMI import file. For details about the PDS formats, refer to the SmartPlant Materials PDS Interface Configuration document, available from the Printable Guides page in the software.

Processing SmartPlant® Instrumentation Data It is now possible to import SmartPlant® Instrumentation BOM data via online access. For more information, refer to the SmartPlant Instrumentation Integration document, available from the Printable Guides page in the software.

Open API Features Besides the possibility of a customized loading procedure as a data source for OMI, further options are available to implement customer-specific business logic by using CIP calls for the following processing events:

omi_job_start

omi_job_end

bom_node_found

bom_node_created

bom_pos_created

In each of these event procedures, the internal OMI main program processing state is fully exposed by passing a read-only data structure to the CIP package. This feature allows for a very flexible and powerful implementation of business logic that in earlier releases would have made modifications to the OMI core code necessary. For more information, see Open API (on page 61).


S E C T I O N 2

This section illustrates which software components are needed, which kind of BOM administration and setup data need to be present, and which database configuration aspects should be considered before the OMI interface can be used.

ORACLE Tools See the SmartPlant Materials Installation and Migration Guide for more information.

Required Data in the SmartPlant Materials Database For the OMI interface to work, you must have already created a complete and working BOM setup. For more information about the BOM Administration screens, please consult the documentation for the SmartPlant Materials BOM module. This BOM setup data consists of the following data items:

1. There needs to be at least one applicable list status present (B.10.02).

2. A default list status must have been defined as the project or project discipline default (A.20.12/A.20.13 screens). This default list status must be open; that is, it must allow deletion and overwriting of BOM positions, and it must have the Lock indicator unchecked.

3. At least one issue status must have been defined (B.10.08).

4. A default issue status must have been defined as the project/project discipline default (A.20.12/13).

5. All required BOM node types and their associated variable node attributes must have been set up on the B.10.03screen.

6. All required discipline-dependent variable BOM position attributes must have been set up on the B.10.04 screen.

7. If applicable, the allowed BOM node type hierarchy must have been defined (B.10.07).

8. The BOM position numbering scheme, consisting of the ZB_LPSTART and ZB_LP_INC parameters on the A.20.12/13 screens, must have been defined.

9. You must have specified whether free or fixed BOM structures are in effect with the ZB_BOMHIER parameter on A.20.12/13.

10. You must have specified whether any quantity other than 1 is allowed for tagged items or not with the ZB_TAGQTY parameter on A.20.12/13. This parameter is ignored for shape material.

11. On the A.10.15 screen, a default item type with item rule SOT (Standard without tags) must be present.

12. On the A.20.12/13 screen, a valid definition of the default Commodity Part for tagged items and shape tagged items must be present.

Prerequisites


Prerequisites 13. You must decide how BOM position numbers will be built upon importing and configure the

ZI_OMI_POS project default accordingly.

14. Depending on how modifications to BOMs with quantities already reserved or even issued on-site should be handled by OMI, the ZI_OMI_TSQ project default needs to be configured accordingly.

15. The ZX_BOM_UK1...ZX_BOM_UK4 parameters can be set additionally, if the TSQ logic is used. These parameters define BOM attributes that help to uniquely identify a BOM position in the mapping search phase of a Site Qty Transfer operation.

16. If the "Transfer Site Qty" logic is used, the ZI_OMI_DCC and ZI_OMI_DCA parameters for the Design Change Control option must also be configured

Depending on the kind of data you want to import, other SmartPlant Materials modules must also have been set up correctly. Among those data items that you should check are:

1. All attributes that are to be used must be set up correctly on the A.50.01 screen.

2. As far as units for BOM positions and variable attributes are concerned, you must have a working setup of unit systems (A.10.06), unit sets (A.10.07), units (A.10.12), and their conversion rules (A.10.13).

3. If you intend to use the OMI company mapping feature, the company-specific translations for SmartPlant Materials commodity codes (S.30.C.01) and idents (S.80.C.01) must have been set up.

Database Configuration The A.60.04 DBA Settings screen offers the option to assign dedicated rollback segments to specific SmartPlant Materials jobs. Use of this option requires that one or more rollback segments with sufficient space are created and brought online. Furthermore, all directories that SmartPlant Materials needs for its log files should be configured correctly in the instance initialization parameter file (init.ora).

If you are going to perform imports with a significant amount of data, you should also make sure that the shared pool size and the database block buffer cache are sized adequately to achieve optimal performance. If you already have a large amount of BOM data present in your SmartPlant Materials database, you should consider using the cost based optimizer with a mode of FIRST_ROWS, and also perform a full analysis of the M_SYS schema on a regular basis; otherwise, import performance may drop. Please refer to the sample init.ora file that is provided with the SmartPlant Materials Installation and Migration Guide. Furthermore, it is possible to specify the optimizer mode as well as the sort area size that OMI should use on a per-job basis by setting parameter values for OMI_OPTIMIZER_MODE and OMI_SORT_AREA_SIZE on the A.60.04 DBA Settings screen.


S E C T I O N 3

This section outlines the general file format that OMI uses. It further discusses the available record types and shows how each of them is used to create a specific BOM element during import processing.

General File Format The import file needs to be a flat ASCII file.

All physical columns need to be on one single line, thus forming a physical record.

Columns are separated by the pipe special character ('|', ASCII code 124).

Each physical record must be terminated by a new line character (making it a proper text file with regard to the platform in use).

The character or combination of characters for a new line is platform-specific; on UNIX, this is a single line feed character, ASCII code 10, while on Microsoft Windows, it is a line feed and a carriage return with ASCII codes 10 and 13 next to each other.

Record Types The following record types can be used in an OMI import file:

1. NODE_BEGIN - This record type indicates the beginning of a new node path. It must always be the first record in an OMI file, because it gives the initial context for the remaining records up to the next occurrence of a NODE or NODE_BEGIN record. OMI does not process any other data records until this initial NODE_BEGIN record occurrence has been found. This record type always references a root BOM node, that is, one that does not have any parent node in the BOM. If the referenced BOM node already exists, OMI uses its internal ID as the first context; otherwise, it creates it as a new root node and remembers this ID as the context. All BOM nodes are created in the discipline that the user who started the import job was logged into.

2. NODE - This record type indicates an intermediate BOM node (that is, a BOM node that is not a root node, but instead either a leaf node or an inner node in a BOM hierarchy) in the context of the previous NODE or NODE_BEGIN record. If it is already present, OMI simply remembers its identifier to provide the BOM path context for the following records; otherwise, it is created.

3. NODE_NLS - This record type specifies a language-dependent description for the current BOM node. If a description in the specified language is already present, it is updated; otherwise, OMI creates it.

4. NODE_A - This record type specifies the assignment of a variable attribute to a BOM node. Generally, the attribute assignment itself is already present after a node has been created, because of the propagation mechanism outlined in the Propagating Variable BOM Attributes (on page 10), so that OMI only has to update its value. Also, for numerical attributes, OMI

Imported Data


Imported Data

checks the unit and performs a unit conversion, if necessary. If this node already has a substructure (for example, because it is a new incarnation of this node, but within a different BOM path), an update of the attribute value also causes this modification to be propagated downwards in this substructure. For performance reasons, it is better to have each node attribute only once in an import file to avoid processing of redundant information.

5. NODE_MODIFIER - This record type allows the modification of a specific node attribute value for all nodes with the specified node type and the specified node name in the substructure of the current BOM path (that is, in the context of the current sequence of NODE_BEGIN, NODE, ... , NODE record occurrences). The node type has to be an exact match; the node name, however, is subject to SQL wildcard matching, if one or more wildcard characters are present. Wildcard characters are '_' (the underscore), which matches any single character, and '%' (the percent sign), which matches any combination of characters.

6. DISC - The DISC record type has the purpose of assigning BOM positions to a specific discipline. This record type must occur at least once before the first POS record appears in the import file (otherwise, OMI is not able to process the position records at all); this discipline assignment is in effect for all following POS records until a new DISC record appears. Please note that the discipline assignment for positions is unrelated to that of nodes: nodes that are created by OMI always belong to the discipline into which the user who started the job was logged in; on the other hand, it is possible to import position data into multiple other disciplines in this import job by use of the DISC record type.

7. POS - This record type specifies a BOM position that is created by OMI as a detail record to the current BOM node. It can either be a main position or a sub position in a BOM assembly (this is controlled by the value of the 'level' column). Furthermore, there are four distinct ways of setting up those fields that allow the unique identification of the kind of material that is referenced by this position:

By Specification - Position data must include spec code, short code, option code, and sizes.

By Commodity Code - Position data must include commodity code and sizes.

By Ident Code - Position data must include ident code.

By Tag Number - Position data must include tag number and item type; optionally, a group code, a part code, an ident code, and a short and a long commodity code layout may be specified as well. For item rule ‘TAB’, position data must include tag number, item type, and commodity code; optionally, a group code, a part code, and an ident code. For item rule ‘SHP’, position data must include tag number, item type, and plate number; optionally, a group code, a part code, and an ident code.

It is also possible to only supply this position information partly, but then it may not be possible for SmartPlant Materials to find a matching ident for these positions. If you specify more information than needed for one of these modes, OMI validates that the redundant parts of these data items are consistent with each other (for example, if you have an ident code as well as a commodity code in your import data); if they are not, an error is logged and the record rejected. Please note that it is possible to import positions by specification even if this specification is not yet complete, with the consequence that SmartPlant Materials does not find an ident initially. However, you can use the check procedure 'FND_IDENT' in the B.20.01.41 Start BOM job module at any time later on, after you have completed the specification to find a matching ident and thus complete the position data. Meanwhile, this position is just present on the BOM, but not yet available for MTO. This feature allows for a flexible way of parallelizing the engineering workflow of creating


Imported Data

specifications in SmartPlant Reference Data on the one hand and the business workflow of finding initial quantity estimates for BOM data on the other hand.

8. POS_A - This record type specifies the assignment of a variable attribute to a BOM position. The attribute propagation logic works the same way as for BOM nodes: after a position has been created, the attribute assignment itself is generally already present; OMI just has to update the attribute value; if necessary, a unit conversion also takes place.

9. POS_DOCUMENT - This record type allows the assignment of a document reference to the current BOM position. The document definition itself must already be present in the SmartPlant Materials documentation module. You can either include only the document code, and then OMI then assigns the highest available revision of this document; or you can specify the document code together with the intended document revision.

10. IDENT_A - This record type specifies the assignment of an ident value to a BOM position ident (only for item rule ‘TAB’). The ident value propagation logic works the same way as for B.20.01: after a position has been created, the ident values are copied from the commodity values as a template; OMI just has to update the ident value, and, if necessary, insert a new one.

11. RENAME_TAG_CC - This record type allows the renaming of tagged items in the same way that is offered on the SmartPlant Materials S.80.24 Rename Tagged Items screen using the Update Commodity Code only option for a manual update.

12. RENAME_TAG - This record type allows the renaming of tagged items in the same way that is offered on the SmartPlant Materials S.80.24 Rename Tagged Items screen using the Update Tag Number option for a manual update.

13. UPDATE_TAG_DESC - This record type allows updating the order description of tagged items (that is, to change the commodity code layout of the commodity code of a tagged item) via OMI. This is analogous to what can already be done manually on the B.20.01.22 Tag Description screen for tagged items on the BOM.

14. PROJECT - This optional record type allows restricting the import of a data file to a specific SmartPlant Materials project. It specifies into which project the file may be imported, and when this does not match the SmartPlant Materials project the user starting the job is logged into, the OMI program stops the import process with an error message. This new record type helps to minimize the possibility for user errors.

Record Layout All import data is initially loaded into the OMI interface table, either through SQL*Loader, by using a customized version of the m_pck_omi_custom.omi_load API package procedure, or indirectly by using the PDS report data source option.

If you intend to use the OMI API, it is up to you to ensure that your data conforms to the interpretation of each of these fields. If you use SQL*Loader, the fields in each record of the import file are transferred into physical columns of this interface table by applying the mapping rules from the SQL*Loader control file.

For more information on this PL/SQL API, refer to Open API (on page 61).

The following table illustrates the mapping; it also introduces the logical column names that are used in the next section, explaining the detailed record layouts for each OMI record type.


Imported Data Position of physical field in the import file

Physical column name in the interface table

Logical name (used on the B.40.01 screen)

Interpretation

1 KIND Record Type Static

2 ONE F-1 Variable

3 TWO F-2 Variable

4 THREE F-3 Variable

5 FOUR F-4 Variable

6 FIVE F-5 Variable

7 SIX F-6 Variable

8 SEVEN F-7 Variable

9 EIGHT F-8 Variable

10 NINE F-9 Variable

11 TEN F-10 Variable

12 ELEVEN F-11 Variable

13 TWELVE F-12 Variable

14 OBJECT Object Code Static

15 REV Rev Static (data item is obsolete)

16 UNIT Unit Code Static

17 OPTION_CODE Option Code Static

18 ITEM Item Type Static

19 IN_3 Input 3 Static



22 THIRTEEN F-13 Static


Imported Data Position of physical field in the import file

Physical column name in the interface table

Logical name (used on the B.40.01 screen)

Interpretation

23 FOURTEEN F-14 Static

24 FIFTEEN F-15 Static

25 SIXTEEN F-16 Static

26 SEVENTEEN F-17 Static

Table 1: Mapping import fields

While some fields always have the same meaning for the OMI main program (mainly the fields needed for the POS record type), other fields are interpreted differently, depending on the value in the ‘Record Type’ column. The field indicating the logical record type must always be the first physical field in the import file; the remaining fields must follow in the sequence shown above.

Intermediate fields that are not needed by a specific record type must be left empty, such that the field separator character is still present.

For detailed record layout requirements and the corresponding field interpretations, please refer to the following tables. The value in the O/M column indicates whether the data item is optional (O) or mandatory (M).

Logical Column

Data Content Data Type

Length O/M Comment

Record Type NODE_BEGIN Character N/A M Record type keyword as a constant

F-1 Node Type Character 10 M List Structure Code (B.10.03)

F-2 Node Name Character 10 M

F-3 Issue Status Character 10 O Defaults to job parameter, if not present.

Table 2: Record layout for NODE_BEGIN

Logical Column


Length O/M Comment

Record Type NODE Character N/A M Record type keyword as a constant



Imported Data Logical Column


Length O/M Comment

F-2 Node Name Character 10 M

F-3 Issue Status Character 10 O Defaults to job parameter, if not present.

Table 3: Record layout for NODE

Logical Column


Length O/M Comment

Record Type NODE_NLS Character N/A M Record type keyword as a constant

F-1 Language Character 60 M Language Description (A.10.01)

F-2 Short Desc Character 20 M

F-3 Description Character 60 M

Table 4: Record layout for NODE_NLS

Logical Column


Length O/M Comment

Record Type NODE_A Character N/A M Record type keyword as a constant

F-1 Attribute Code Character 30 M Attribute Code (A.50.01)

F-2 Attribute Value Character 255 O

Unit Code Unit Code Character 10 O If unit in A.50.01 differs: unit conversion

Table 5: Record layout for NODE_A

Logical Column


Length O/M Comment

Record Type DISC Character N/A M Record type keyword




Length O/M Comment

as a constant

F-1 Discipline Code Character 10 M Discipline Code (A.10.09)

Table 6: Record layout for DISC

Logical Column


Length O/M Comment

Record Type NODE_MODIFIER

Character N/A M Record type keyword as a constant


F-2 Node Name Character 10 M May contain SQL wildcards




Table 7: Record layout for NODE_MODIFIER

Logical Column


Length O/M Comment

Record Type POS Character N/A M Record type keyword as a constant

F-1 Spec Code Character 16 O S.50.03

F-2 Short Code Character 10 O

F-3 Size 1 Character 7 O

F-4 Size 2 Character 7 O

F-5 Commodity Code

Character 60 O S.30.01




Length O/M Comment

F-6 Ident Code Character 13 O S.80.*

F-7 Quantity Number (15,3) M

F-8 Pos Character 10 O (M) BOM position number. Processing method depends on project default ZI_OMI_POS.

F-9 Tag Number Character 60 O Processing depends on item type

F-10 CCL Short Character 2000 O For creation of tagged items only

F-11 CCL Long Character 2000 O For creation of tagged items only

F-12 Assembly Level Number 2 M Must be 1 for main positions; must have the appropriate value for BOM assembly structures. See Processing Logic (on page 26).

Object Object Code Character 100 O See Object Codes and Recognize Mode (on page 35).

Rev Rev Number 2 O Obsolete; only included for backwards compatibility of file format. Always enter 0.

Unit Code Unit Code Character 10 M If position has an ident (either direct or indirect), and the unit associated with this ident differs: unit conversion.

Option Code Option Code Character 10 O Defaults to Option 1, if not specified

Item Item Type Character 10 O A.10.15; if not specified, default item type with item rule SOT




Length O/M Comment

will be assigned.

Input 3 Size 3 Character 10 O



F-13 Group Code Character 10 O For creation of tagged items only; overrides ZB_TAGPART. For shape material, the project default ZB_SH_PART will be used and cannot be overridden by import data.

F-14 Part Code Character 10 O For creation of tagged items only; overrides ZB_TAGPART. For shape material, the project default ZB_SH_PART will be used and cannot be overridden by import data.

F-15 List Status Code Character 10 O If not present, job parameter for list status will be used

F-16 Requisition Ind Character 1 O Must be either Y or N; defaults to Y

F-17 Plate Number Character 24 O For creation of shape material only

Table 8: Record layout for POS

Logical Column


Length O/M Comment

Record Type POS_A Character N/A M Record type keyword as a constant

F-1 Attribute Code Character 30 M Attribute Code




Length O/M Comment

(A.50.01)



Table 9: Record layout for POS_A

Logical Column


Length O/M Comment

Record Type POS_DOCUMENT


F-1 Document Code Character 255 M Document Code (D.10.11)

F-2 Revision Character 5 O If not present, highest revision

Table 10: Record layout for POS_DOCUMENT

Logical Column


Length O/M Comment

Record Type IDENT_A Character N/A M Record type keyword as a constant



Unit Code Unit Code Character 10 O

Table 11: Record layout for IDENT_A

Logical Column Data Content Data Type

Length O/M Comment

Record Type RENAME_TAG_CC



Imported Data Logical Column Data Content Data

Type Length O/M Comment

F-1 Old Tag Number Character 24 M Tag Number to rename

F-2 New Tag Number Character 24 M Tag Number to which to rename to

Table 12: Record layout for RENAME_TAG_CC


Length O/M Comment

Record Type RENAME_TAG Character N/A M Record type keyword as a constant

F-1 Old Tag Number Character 24 M Tag Number to rename

F-2 New Tag Number Character 24 M Tag Number to which to rename to

Table 13: Record layout for RENAME_TAG


Length O/M Comment

Record Type UPDATE_TAG_DESC


F-1 Tag Number Character 24 M Tag Number for which order description should be changed

F-2 Language Character 24 M Language of order description to change

F-10 New CCL Short Character 2000 M

F-11 New CCL Long Character 2000 M

Table 14: Record layout for UPDATE_TAG_DESC


Imported Data Logical Column Data Content Data

Type Length O/M Comment

Record Type PROJECT Character N/A M Record type keyword as a constant

F-1 SmartPlant Materials project

Character 10 M SmartPlant Materials project into which this data may be imported

Table 15: Record layout for PROJECT

Processing Logic After data has been loaded into the OMI interface table, the OMI main import program is started. As a first step, it validates all specified job parameters and initializes (that is, looks up and checks) all needed project defaults. If an error is encountered in this phase of execution, the job is cancelled and an appropriate error message is raised, indicating the kind of problem to the user.

In a second step, the main program dynamically creates an index on the interface table that helps to speed up processing of the imported data. When the job finishes, this index is dropped again, so that the next run of an OMI job (especially in the data loading phase through SQL*Loader or the OMI API) can run as quickly as possible.

When OMI begins to scan through the import data, it looks for the first occurrence of a NODE_BEGIN record, which provides the initial BOM context. All the remaining records are then processed in the order they were loaded, while the BOM is searched or updated by this import data recursively. BOM attribute propagation is initiated at the appropriate points as BOM data is created. OMI takes the specified transaction size into account; that is, it processes the import data in chunks of this transaction size, and after each chunk, issues a database commit. This mechanism controls usage of rollback space, that is, an appropriate value for the transaction size that takes into account the amount of data to be loaded, together with a specification of a rollback segment that OMI can use helps to improve import performance significantly.

The revision control mechanism that is available in the BOM module is also integrated with OMI processing logic. For this reason, the Rev field on the POS type records is not used any longer and is in the import file specification only to maintain compatibility with previous versions of the file format.

Instead, the BOM revision is derived at runtime, using the following criteria:

For BOM positions, it is always the revision of the node where they are located.

For BOM nodes that are newly created by OMI, the revision number is always 0.

For existing nodes that are updated by OMI (or to which positions are added), the resulting revision number depends on the present revision number, the Locked property of the node, and the job parameter check box Rev+1:

If a node is not locked, the revision number is not changed.


Imported Data

If a node is locked, but revision increment has not been allowed, the BOM node and its associated detail data (node description, node values, and positions) is not modified at all.

If a node is locked and revision increment is allowed, the revision number is incremented by 1 (and the node is unlocked, and its present positions list status is reset to the project default list status again in order to allow data modification from the OMI import data to take place).

Fields for the NODE_BEGIN, NODE, and POS record types are available. For these fields, the following logic applies:

Issue Status on NODE_BEGIN and NODE Records - If no issue status is present for a record of this type, the issue status from the job definition is in effect. If it is present, it overrides the job issue status (that is, it is in effect for this node only), and controls the import of positions data for this node. A set of position data from the import file always replaces a set of position data that is already present at a particular BOM node with that same issue status, regardless of whether the issue status in effect has been defined on the level of an individual node, or only globally for the job.

List Status on POS Records - If no list status is present for a record of this type, the list status from the job definition is in effect. If it is present, it overrides the job list status (that is, it is in effect for the current position only). Please note that the same restrictions to which a default BOM list status must conform also apply for a "local" list status specification on the POS record level: such a list status must allow deletion and overwriting, and it must not have the Lock check box checked.

Requisition Indicator on POS Records - If this field is empty in the import file, this indicator (which corresponds to the Req check box on the B.20.01 Single Position screen) defaults to Y, and the position must be included by an MTO. If this field is not empty, it may only contain a 'Y' character or an 'N' character, which corresponds to checked (include in MTO) and not checked (do not include in MTO), respectively.

Group Code and Part Code on POS Records - If these fields are empty in the import file, the commodity part that has been defined by the ZB_TAGPART project default parameter (for shape material, ZB_SH_PART) is used for creation of the commodity code / ident code for tagged items. For more information, see Tagged Items (on page 31). If they are present, they must together specify a valid commodity part; this part is then used instead of the project default commodity part for creation of a commodity code / ident code for tagged items (not for shape material; in that case, the software uses ZB_SH_PART), but only for the current position. For subsequent position records that do not specify this commodity part, the project default part is in effect again. Please note that commodity codes and idents for tagged items are only created if the item type has an item rule of TOM, TWM, or SHP.

There are several modes available in which BOM data is processed. These modes and their significance are outlined in the following sections.

Transfer / Simulation Mode You can specify that OMI should run in simulation mode. In this mode, BOM nodes, node attributes, node descriptions, BOM positions, position attributes, and position document references are not created or updated (except for the NODE_MODIFIER record type, these records are always processed regardless of whether the mode is transfer or simulation).

All data validations that can be done without creating BOM data take place, and any data problems that OMI finds are written to the import log. This mode is a means for quickly checking


Imported Data if the format of the import file is correct or not. The transfer mode, on the other hand, is the default mode. It creates or updates BOM data from the import data, as described in the other sections of this guide.

Replace / Append Mode On the B.40.01 OMI Import Jobs screen, the Append check box specifies whether the OMI job replaces BOM position data at BOM nodes (unchecked) or whether it appends BOM positions to those already existing at BOM nodes (checked). For shape material, the software uses the append mode, whether specified or not. Shape material is not deleted.

The default operation mode is to replace BOMs. In the append mode, the setting value AUTO for the ZI_OMI_POS project default is ignored, and instead, DATA is assumed. So when positions are to be appended, it is necessary that you include position numbers in the data source (for example, in the ASCII file). In append mode, these position numbers are used by the import program to ensure that positions are not being duplicated by the append operation.

The software rejects positions with duplicate position numbers, as well as position records without a position number.

Append mode does not work with recognize mode; positions can be appended only in normal mode. In append mode, it is not possible to load positions into a new highest issue status at a node - positions can only be appended into the existing highest issue status.

Append mode does work, however, in Fab Spool import mode. For example, single spool items can be appended to existing nodes, while those already existing are kept by the software.

Position Numbering Usually the position numbering for imported BOM positions is done automatically by OMI. The project default ZI_OMI_POS allows for another position numbering option. This project default can be set to AUTO or DATA.

With AUTO, the old logic for automatic numbering is in effect, which completely ignores the position number in the ASCII file.

If it is set to DATA, the position number from the import data is kept and used. Of course, this situation requires a few additional validations to take place, because within a BOM node in one issue status, the position number must be unique. If the DATA option is used, the Pos (F-8) field in a position record becomes a mandatory data item. If a number included in the import data is not unique, it is prefixed with an "!" character to indicate the data problem. If a prefixed number is not unique, the position is rejected with an error message in the OMI log.

Design Change Control: Processing Site Quantities The SmartPlant Materials Site module stores reserved or issued material quantities for reservation jobs or issue reports against the BOM directly on the BOM tables. The basic philosophy behind this processing is that once the site workflow is reached, the design phase definitively has ended, and BOM modifications will most likely not occur any longer. However, the exceptional cases in which major design changes must be reflected in the BOM data occur (although reservations and issues have already been done against affected BOMs) and must be taken into account by OMI.

The actual business case for this scenario is one of the following events, if a reservation or issue has been made against BOM data in the highest issue status at a specific BOM node:


Imported Data Deletion of the BOM positions (either explicitly or by deletion of the complete BOM structure)

is attempted.

If either reserved or issued quantity is stored on a BOM position, SmartPlant Materials does not allow deletion any longer. Instead, the error message "MAR-20234: Position #1 at node #2 has reserved/issued qty on site, cannot delete" is raised.

Import of a replacement position data set via OMI for this issue status is attempted.

This case is equivalent to the previous one. OMI rejects any position data for the same issue status if any existing position in that issue status has either a reserved or issued quantity.

Import of position data with a higher issue status than the present highest one for the affected BOM node is attempted, where any position in the present highest issue status has either a reserved or issue quantity.

The position data set in the present highest IFC issue status keeps the site quantities. Forecasting/reservation and issuing is normally done using the SmartPlant Materials Best Quantity algorithm, which only takes into account the highest IFC issue status (this issue status has Site Quantities) at a node. If a higher issue status is loaded, the next forecast/reservation/issue still uses the IFC issue status, as only the IFC status is visible in the Site module. However, engineering can work with the new highest engineering issue status in the meantime; the site quantities remain in the IFC status until the BOM check TSQ is used.

This last case is the one where OMI applies its Transfer Site Quantity logic, if the Transfer Site Qty check box has been checked. Otherwise, OMI simply imports this new highest issue status.

The TSQ logic is a 'Best Match' algorithm: for each affected position in the old highest issue status, OMI attempts to find a matching position in the new highest issue status. If one is found, the reserved and the issued quantities are moved to this position, and are set to zero on the old one. If no matching position can be found, an equivalent position with quantity 0 is created in the new highest issue status and site quantities are transferred in the same way.

The search for a matching position itself is performed in one of two possible ways:

1. The first possibility only uses ident, unit, and parent position reference (that is, using the internal foreign key column parent_lp_id). It is in effect when no values have been defined for the ZX_BOM_UK1...ZX_BOM_UK4 parameters. If this check finds more than one matching position, it takes the one where the difference between the new position quantity and the old position issued quantity is smallest.

2. The second possibility is in effect when at least one of up to four possible BOM position attributes have been defined as a logical BOM unique key using the ZX_BOM_UK1...ZX_BOM_UK4 parameters. This possibility basically performs the same comparison logic as the first possibility; however, this additionally makes sure to select a position where attribute values for specified attributes also match.

When exactly one match is found, the transfer logic described above is applied. All other cases cause a warning with type SITE_QTY to be logged by OMI. These warnings can be viewed in the second window (Import protocol) of the B.40.01 screen, or by printing the B.40.R.01 Import Protocol report.

Additionally, OMI checks whether importing a new highest issue status for a BOM node affects any unposted Material Issue Report or any open Reservation Run Result. If so, this situation is also logged with the relevant information about the MIR header and/or the Reservation job header.


Imported Data If the Design Change Control option (ZI_OMI_DCC) is enabled, the following logic also takes place:

OMI calculates the outstanding quantity for a BOM position. This quantity is just the difference between the new position quantity and the issued quantity, or 0 if the issued quantity is greater than the new position quantity.

OMI logs reservation shortages to the C.50.01 BOM Design Change Log screen. A reservation shortage is found if the reserved quantity is smaller than the outstanding quantity.

OMI logs over-reserved quantities to the C.50.01 BOM Design Change Log screen and cancels over-reserved quantities automatically. An over-reservation is found if the reserved quantity is greater than the outstanding quantity.

OMI logs design change issue quantities to the C.50.01 BOM Design Change Log screen and reissues these quantities to the appropriate design change warehouse automatically. A design change issue quantity is just the difference between the new position quantity and the issued quantity if the issued quantity is greater than the new position quantity. The design change issue warehouse to which the DCI quantity is issued is the warehouse that is assigned to the original MIR subcontractor and has the Design Change Issue indicator checked on the C.10.02 Warehouses screen.

After the OMI job has finished, all such log entries are available for review on the C.50.01 BOM Design Change Log screen. Additionally, the C.50.R.01 report can be run to print the log information.

All design change log entries need to be acknowledged by the user. For each acknowledgment, a new Material and Design Maintenance Control number (MDM number) is generated by the software, and log entries are stored in context of that MDM number for later review.

The project default parameter ZI_OMI_DCA is provided to specify how OMI should handle old unacknowledged design change control log entries that it may eventually encounter during load of a new highest issue status position data set into a BOM node. This situation can happen if several OMI import jobs that import into the same BOM structure that has site quantities are being run one after another without reviewing and acknowledging C.50.01 data. Possible values for this parameter are:

ERR: Raises an error and rejects the complete BOM node OMI input data if there are any unacknowledged log entries in C.50.01 for that node. This error implies that a new data set with a new highest issue status can only be loaded if all previous design change log entries have explicitly been acknowledged by the user on the C.50.01 screen.

ACK: Have OMI automatically acknowledge the design change for the old highest issue status and keep the log entry.

DEL: Have OMI ignore the unacknowledged design change for the old highest issue status, delete the log entry, and, eventually, create new log entries if appropriate for new imported quantities.


Imported Data

Delayed automatic reissue of DCI quantity If there are design change issue quantities found for BOM positions, and there is no design change issue warehouse specified for the original MIR subcontractor, the software cannot automatically perform the reissue to DCI warehouse. This case is indicated as "Undetermined DCI warehouse" on C.50.01. It is also not possible to acknowledge the log entry in such a case.

Instead, the user can either specify a DCI warehouse for the subcontractor in question on the C.10.02 screen and then click the Acknowledge button on the C.50.01 screen, or the user can specify a DCI warehouse just for this one log entry in question in the third block of the C.50.01 screen and then click the Acknowledge button. In both cases, processing the reissue is postponed to the acknowledge event.

Tagged Items With the implementation of processing logic for tagged items, it is possible to define materials that are not standardized within SmartPlant Materials. This processing logic is also integrated with the OMI interface code.

For the correct processing of such tagged BOM positions, three data items in the import data are important:

The tag number itself, which can be included in the import file in the F-9 field.

The item type reference, which can be included in the Item Type field.

The ident code, which may be specified for creation of tagged items.

The different item types that can be set up in the A.10.15 module are based on five different item rules. These item rules control the processing of BOM positions during OMI import and also in all further workflows downstream:

SOT (Standard without Tags) - This default rule is for material that is standardized within SmartPlant Materials. This rule is used by OMI if there is no item type specified in the import file.

SWT (Standard with Tags) - These items are also standardized within SmartPlant Materials; for material tracking purposes, however, they have been assigned a tag number; that is, if the import file specifies an item type with this rule, a tag number must be present; otherwise, OMI rejects this record. Furthermore, the ZB_TAGQTY project default setting is validated for such an item together with the item quantity from the import file. If this parameter is set to Y for SWT items, the quantity must always be 1. If there is any other quantity in the file, OMI rejects the POS (position) record.

REF (Reference Items) - No special logic is applied by OMI if an item of this item rule is imported. On the BOM, however, this item rule has the effect that such positions are excluded from all MTOs; that is, such items only have a reference (documentation) purpose.

TOM (Tagged Items without Milestones), TWM (Tagged Items with Milestones), and SHP (Tagged Shapes) - Items that have an item type with one of these rules are not standardized within SmartPlant Materials (or they are standardized externally). As far as the tag number and the item quantity are concerned, the same processing rules as for SWT items also apply here. Additionally, OMI (and the SmartPlant Materials BOM module) creates a commodity code (for which it just uses the supplied tag number) and a pseudo ident code (with all input_1 to input_5 values set to 0) to allow unique identification and thus further tracking of such tagged items in the downstream workflow.


Imported Data

The content of fields F-10 and F-11 is used to create the short and long commodity code layouts, respectively. If an ident code is specified for such a record and this ident does not exist yet, it is used for creation of the tagged item ident. If the ident already exists when tagged item creation is necessary or if the tagged item already exists but the specified ident code does not match that of the tagged item commodity in the database, the position record is rejected with an error message.

If no ident code is specified for the tagged item, the ident code is just generated automatically by the software in the same way as for standard idents when the tagged item commodity is created. If the ident code does not need to be created because it already exists in the database, the presently assigned commodity code and ident code are looked up and used for the BOM position; that is, OMI recognizes TOM / TWM / SHP tagged items that are already present in the database.

TFM (Tagged Fabricated Items with Milestones) - Items that have an item type with item rule TFM can only be imported in Fab Spool Import mode. Vice versa, items of a type with an item rule other than TFM can only be imported in normal import mode. For more information, see Fabrication Tracking - Spool Import Mode (on page 34).

Furthermore, there are three control record types provided to handle the update of tagged items:

RENAME_TAG_CC updates the commodity code only analogous to the equivalent button function on the S.80.24 Rename Tag Number screen.

RENAME_TAG globally does a forced update of the commodity code as well as the tag number throughout the whole system, analogous to the equivalent button function on the S.80.24 Rename Tag Number screen.

UPDATE_TAG_DESC updates tagged item order descriptions.

For the record layouts of these control records, see Record Types (on page 15).

TAG – Attribute Based Tag For the correct processing of attribute-based tag BOM positions, three data items in the import data are important:

The tag number itself, which can be included in the import file in the F-9 field.

The item type reference, which can be included in the Item Type logical field.

The commodity code, which must exist in the database (import file F-5 field).

The ident code is optional. OMI tries to find the ident by item rule, commodity code, and the tag number. If no ident exists, a new one is created. If an ident code exists in the ASCII file, OMI can create the new ident with this code, if the code does not exist in the database. After creating the new list position, the commodity values are copied to the ident values as a template.

You can update these ident values or insert new ones with OMI (IDENT_A in ASCII file).


Imported Data

BOM Assemblies OMI import and export are enabled to handle BOM assemblies, which are hierarchically-structured BOM positions that can be created manually in the B.20.01 module or by copying SmartPlant Reference Data assembly structures into the BOM by use of the BOM_COPY procedure in the B.20.01.41 module. OMI recognizes BOM assemblies by checking the value in the Assembly Level column (F-12).

An assembly must always have a main (or master) position. This position has assembly level 1. The next level in an assembly hierarchy is indicated by level 2; that is, a position with level 2 is created as a child position of the previous level 1 position. From each assembly POS record to the next in the import data, this level value may increase by 1, thus instructing OMI to open a new level. From each assembly POS record to the next, the level may decrease by any number; this instructs OMI to leave the previous level of the assembly hierarchy and return to the specified level for creation of a new (sub-) position. OMI maintains the state of its processing of BOM assembly structures in a stack data structure. If there are any inconsistent assembly records in the import data (for example, when a level increases by more than 1), an appropriate error message is written to the import protocol, and processing of the current assembly is cancelled; that is, it continues with the next valid POS or NODE_... record.

BOM assemblies can also have variable position attributes or document references on the sub-position level. For import, they are handled the same way as for main positions. For BOM data export on the B.20.01.44 screen, however, you have the option of specifying a method for attribute selection. The default on B.20.01.44 is to include only those attributes that are necessary for re-importing the exported data into a SmartPlant Materials system with a similar setup of BOM attributes. Propagated attributes that have not been changed (as indicated by the Manual check box) on lower levels are not repeated in the export file for those lower levels of the node structure, or in the case of a BOM assembly, for lower levels of the assembly structure. This logic avoids attribute redundancy (these additional attribute records would be redundant because their value is already given by the implicit propagation logic in the BOM module).

As far as the structure itself is concerned, from a theoretical point of view, assembly structures could have an arbitrary depth; however, for practical reasons, this depth is limited to 14 levels.

Import with Company Mapping On the B.40.01 screen, OMI offers the option to specify that a company-dependent translation of commodity codes and ident codes has to take place during import processing. These translations can be set up on the S.30.C.01 screen for commodity codes and on the S.80.C.01 screen for ident codes in SmartPlant Reference Data. If this option is being used by specifying a company via in B.40.01, OMI searches the translation tables for the corresponding SmartPlant Materials commodity code and ident code for that company, so that when a translation has been found, only the SmartPlant Materials codes are written to the BOM. If no translation for a position record can be found, or the translation is not unique, the record is rejected.

Company mapping behavior is controlled by two project defaults:

ZI_OMI_CM (OMI Company mapping option) - Specifies whether in company mapping import mode, only company ident codes are accepted (option COMP), or company ident codes as well as SmartPlant Materials ident codes (option BOTH) are accepted. The default is COMP. For the latter case, you can also specify a mapping priority with ZI_OMI_CMP. In earlier SmartPlant Materials releases, only the COMP option behavior was available.


Imported Data ZI_OMI_CMP (OMI Company mapping priority) - For company mapping import mode with

mapping option BOTH (see ZI_OMI_CM above), this option specifies which ident OMI should use if a company ident as well as a SmartPlant Materials ident are available for a specific ident code. Available options are COMP (this uses the company ident), MAR (this uses the SmartPlant Materials ident), and REJ, which disallows ambiguous ident codes, rejects the position record in such a case, and writes an error entry to the OMI log.

OMI states in its log file, among some other job parameters, which company has been specified for the translation and which options are in effect.

Fabrication Tracking - Spool Import Mode This import mode has been implemented based on the following requirements:

The ability to build a single identifier for each spool piece

The ability to receive a list of spool numbers associated to a BOM node from fabricators

The ability to associate spool numbers to BOM nodes via OMI import

The ability to process spool numbers throughout the complete SmartPlant Materials workflow, which includes Expediting and Traffic in the Procurement module, as well as Receiving and Issuing in the Site module

The basic solution to these requirements is three-fold:

1. Distinguish spool number BOM items from all other BOM items by means of the item rule that is attached to the item type. Spool number BOM items always have an item type with item rule TFM, whereas "normal" BOM items use item rules as outlined in Tagged Items (on page 31).

2. For TFM (Spool) BOM items, interpret the physical BOM tag number as the spool number.

3. Completely separate TFM item processing by OMI from non-TFM item processing.

This approach makes it possible to manage the complete cycle of expediting traffic, and receiving and issuing spools using SmartPlant Materials standard functionality for tag number processing throughout the complete workflow.

The OMI interface therefore implements the following behavior with respect to BOM item types:

OMI allows import to existing nodes based on the TFM item type. In Fab spool import mode, only TFM items can be imported. In normal import mode, only non-TFM items can be imported. There cannot be a mixture of these item types in the same OMI job run; although, of course, there can be a mixture of these item types located at the same BOM nodes. The OMI import mode is specified by a check box for the job definition on the B.40.01 screen.

When using the "Fab Spool Import" mode (that is, only TFM spool items are to be imported),

it is necessary that the ZB_TFMPART project default parameter be set to a valid commodity part; otherwise, job execution fails with an error message.

When TFM (non-TFM) items are to be imported with a specific issue status, and TFM (non-TFM) items present on the BOM in this issue status have Site quantities (that is, reserved qty, issued qty, or both), this BOM position data set is rejected. In this case, only importing with a higher issue status is allowed.

When TFM (non-TFM) items are to be imported with a specific issue status, and TFM (non-TFM) items present on the BOM with a lower issue status (that is, one with a lower


Imported Data

order sequence number) have Site quantities, it is necessary that the ZI_OMI_TSQ project default parameter be set to 'Y' in order to allow OMI to apply the Site Quantity Transfer algorithm. Otherwise, this BOM position data set is rejected.

When importing TFM (non-TFM) items to a present BOM node with a new highest issue status, present non-TFM (TFM) items at this BOM node (that is, items of a type with the opposite rule) with the current highest issue status are moved up to the new highest issue status (which means that they are updated; please be especially aware that they are NOT COPIED to the new status, they are MOVED) in order not to change the MTO or Forecast/reservation job's view at the BOM data.

Object Codes and Recognize Mode In normal mode, OMI does not apply any special logic to the object code field on position records. You can specify, however, that you want to run the import job in recognize mode. The recognize mode (not for item rule SHP) then uses a fundamentally different import processing logic: in this mode, the object code has the purpose to uniquely identify existing BOM positions in the context of the current BOM path (and of course, in its substructure) and then to apply the data modifications from the import file to these positions. In comparison to the normal OMI import mode, the following processing rule differences are in effect when the recognize mode is used:

1. Node Path descriptions - As soon as a valid BOM path is available by interpretation of the import data, all existing positions in the substructure of the current BOM node are checked for uniqueness of their object code fields. If there are duplicate object codes present, the processing of this part of the BOM is cancelled, and processing continues with the next NODE_BEGIN record. The central prerequisite for recognize mode operation is met: the ability to identify positions only by the object code.

2. BOM positions - If for a specific node, there are positions in the import file, as a first step, all positions at this node that have an object code are marked. During subsequent steps, all import records for these nodes that also have an object code are processed and their marks are reset. As a consequence, after processing of this node is finished (that is, when another NODE_BEGIN or NODE record appears), all positions from this node that still have the mark from the first step set are not included in the import file. These positions are moved (operation move-out) to the temporary recognize mode "exchange" m_list_pos_objects table, thus logically deleting them from the current BOM node. On the other hand, if positions with an object code are encountered and processed, a matching position with the same object code is first searched for in this "exchange" table, before the object code is searched on the BOM. The net effect of this processing is that by means of an object code specification, specific BOM positions may be moved from one BOM node to another BOM node, using the m_list_pos_objects table as temporary storage (also referred to as an "exchange area" in the OMI import protocol).

Positions that could not be recognized (that is, they could neither be found in the exchange area nor on the BOM) are simply created as a new position by OMI. If a position can be recognized in the exchange area, it is "moved in", that is, it is created at the current node, and then updated according to the current position record. If a position can be recognized at the current node, there is no need to move it, so it can simply be updated according to the current position record and location.

Updated position fields in recognize mode are:

Quantity

Quantity Unit


Imported Data

Created By (will be set to 'OMI Recognize')

Spec Code

Short Code

Option Code

Group/Part/Commodity/Ident Code

Input 1 - Input 5

Tag Number

Object Code

recognize_id (only used internally for the recognize mode algorithm; it has no inherent meaning)

Processing of position attribute records in recognize mode does not differ from normal mode processing.

Positions at locked nodes are not processed (specifically, they are NOT moved) unless the import job parameters also allow a revision increment.

3. Extended Logging in recognize mode - If the recognize mode is in effect, more detailed information on the operations taken (that is, move-in, move-out, update of recognized positions) is written to the OMI import protocol, additionally stating the BOM path, the object code, and the position number (as found for the import record). Furthermore, the main log statistics section displays the overall number of such operations.

Import File Example A simple import file that only specifies a BOM structure without importing any positions data could have the following layout:

NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE_NLS|ENGLISH|PS_OMI_PROJECT|PS_OMI_PROJECT|||||||||||||||||||||| NODE_A|DES_AREA|DA1||||||||||||0|-|||||||||| DISC|PIPING|||||||||||||||||||||||| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L1||||||||||||0||||||||||| NODE_NLS|ENGLISH|L1|L1|||||||||||||||||||||| NODE_A|USE_CODE|L1||||||||||||0|-|||||||||| NODE_A|SCAN_CODE|SCAN1||||||||||||0|-|||||||||| NODE_A|TEST_PACK|TP-L1||||||||||||0|-|||||||||| NODE_A|DWG_REF_NO|DWG-L1||||||||||||0|-|||||||||| NODE_A|SUB_CONT|SUBC1||||||||||||0|-|||||||||| DISC|PIPING|||||||||||||||||||||||| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L1||||||||||||0||||||||||| NODE|SHT NO|S1||||||||||||0||||||||||| NODE_NLS|ENGLISH|S1 SHDSC|S1 DSC|||||||||||||||||||||| NODE_A|S/F|S||||||||||||0|-|||||||||| DISC|PIPING|||||||||||||||||||||||| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L1||||||||||||0||||||||||| NODE|SHT NO|S2||||||||||||0|||||||||||


Imported Data NODE_NLS|ENGLISH|S2 SHDSC|S2 DSC|||||||||||||||||||||| NODE_A|S/F|F||||||||||||0|-|||||||||| DISC|PIPING|||||||||||||||||||||||| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L2||||||||||||0||||||||||| NODE_NLS|ENGLISH|L2|L2|||||||||||||||||||||| NODE_A|SCAN_CODE|SCAN2||||||||||||0|-|||||||||| NODE_A|USE_CODE|L2||||||||||||0|-|||||||||| NODE_A|TEST_PACK|TP-L2||||||||||||0|-|||||||||| NODE_A|DWG_REF_NO|DWG-L2||||||||||||0|-|||||||||| NODE_A|SUB_CONT|SUBC2||||||||||||0|-|||||||||| DISC|PIPING|||||||||||||||||||||||| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L2||||||||||||0||||||||||| NODE|SHT NO|S1||||||||||||0||||||||||| NODE_NLS|ENGLISH|S1 SHDSC|S1 DSC|||||||||||||||||||||| NODE_A|S/F|S||||||||||||0|-|||||||||| DISC|PIPING|||||||||||||||||||||||| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L2||||||||||||0||||||||||| NODE|SHT NO|S2||||||||||||0||||||||||| NODE_NLS|ENGLISH|S2 SHDSC|S2 DSC|||||||||||||||||||||| NODE_A|S/F|F||||||||||||0|-|||||||||| DISC|PIPING||||||||||||||||||||||||

Another file, this time including some tagged items in its position data on the first sheet node (in BOM path /PS_OMI_IMP/L1/S1 with position discipline = PIPING), could look like the following:

NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE_NLS|ENGLISH|PS_OMI_PROJECT|PS_OMI_PROJECT|||||||||||||||||||||| DISC|PIPING|||||||||||||||||||||||| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L1||||||||||||0||||||||||| NODE_NLS|ENGLISH|L1|L1|||||||||||||||||||||| NODE_A|USE_CODE|L1||||||||||||0|-|||||||||| NODE_A|SCAN_CODE|SCAN1||||||||||||0|-|||||||||| NODE_A|TEST_PACK|TP-L1||||||||||||0|-|||||||||| NODE_A|DWG_REF_NO|DWG-L1||||||||||||0|-|||||||||| NODE_A|SUB_CONT|SUBC1||||||||||||0|-|||||||||| DISC|PIPING|||||||||||||||||||||||| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L1||||||||||||0||||||||||| NODE|SHT NO|S1|10|||||||||||0||||||||||| NODE_NLS|ENGLISH|S1 SHDSC|S1 DSC|||||||||||||||||||||| NODE_A|S/F|S||||||||||||0|-|||||||||| DISC|PIPING|||||||||||||||||||||||| POS|||0|0|||1|10|OMI_TAG_1|OMI_TAG_1 - CCL Short|OMI_TAG_1 - CCL Long|1||0|EA|1|T|0|0|0|GRP_1||05|N| POS|||0|0|||1|20|OMI_TAG_2|OMI_TAG_2 - CCL Short|OMI_TAG_2 - CCL Long|1||0|EA|1|T|0|0|0||PRT_1|05|N| POS|||0|0|||1|30|OMI_TAG_3|OMI_TAG_3 - CCL Short|OMI_TAG_3 - CCL Long|1||0|EA|1|T|0|0|0|GRP_1|PRT_1|05|N|


Imported Data POS|||0|0|||1|40|OMI_TAG_4|OMI_TAG_4 - CCL Short|OMI_TAG_4 - CCL Long|1||0|EA|1|T|0|0|0|EQUIPMENT|X|05|N| POS|||0|0|||1|50|OMI_TAG_5|OMI_TAG_5 - CCL Short|OMI_TAG_5 - CCL Long|1||0|EA|1|T|0|0|0|TAGS|PRT_1|05|N| POS|||0|0|||1|60|OMI_TAG_6|OMI_TAG_6 - CCL Short|OMI_TAG_6 - CCL Long|1||0|EA|1|T|0|0|0|TAGS|TAG_PART|05|N| POS|||0|0|||1|70|OMI_TAG_7|OMI_TAG_7 - CCL Short|OMI_TAG_7 - CCL Long|1||0|EA|1|T|0|0|0|||05|N| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L1||||||||||||0||||||||||| NODE|SHT NO|S2||||||||||||0||||||||||| NODE_NLS|ENGLISH|S2 SHDSC|S2 DSC|||||||||||||||||||||| NODE_A|S/F|F||||||||||||0|-|||||||||| DISC|PIPING|||||||||||||||||||||||| NODE_BEGIN|PROJECT|PS_OMI_IMP||||||||||||0||||||||||| NODE|LINE NO|L2||||||||||||0||||||||||| NODE_NLS|ENGLISH|L2|L2|||||||||||||||||||||| NODE_A|USE_CODE|L2||||||||||||0|-||||||||||

Both files would effectively create a BOM structure like this:

Table 16: Example for created BOM Structure


S E C T I O N 4

All OMI interface operations can be initiated and controlled on the B.40.01 BOM Import screen. Here you can set up job definitions; start OMI jobs online or in batch mode; check the outcome of job execution; and review the SQL*Loader Log file, the OMI main import log file, and the detailed import protocol.

File Placement You must store your import data file in a directory with write access, together with all files in the %SPMAT_HOME%\Sql\Install\OMI directory. For online jobs, these files are processed on a local disk drive on your client computer; for batch jobs, all these files must be stored on a disk drive on the server.

Defining an Import Job An OMI import job is defined by entering a new record on B.40.01:

For online jobs, you can use the Upload button to pick an import file from your local file systems. For batch jobs, you can use the Default Dir button to select the default directory on the server that is appropriate for your project and login discipline. Use of this button requires that

Data Import


Data Import your SmartPlant Materials application administrator has set up the necessary directory parameters on the A.60.04 and/or on A.20.12/13 screens. If you click the Upload button, the file upload page appears in a separate browser window. You can pick your file from the file system and send it to the SmartPlant Materials application server. Specify the destination path in the BOM_UPLOAD_DEST DBA setting with a trailing backslash. It gets a new unique filename there, which is displayed in the Import Path and Import File fields. If you start a batch job, this file is downloaded to the database server if you set the BOM_IMPORT_GET_FILE DBA setting to Y. The file is requested at the virtual path you specify in the BOM_UPLOAD_URL DBA setting (hostname/path without a trailing slash) and written to the path defined in the BOM_IMPORT_PATH DBA setting.

In the Runtime Options section, select the Next Issue Status check box to let the import procedure automatically determine the issue status of the imported positions. When the Next Issue Status check box is selected,

The issue status specified in the Issue Status field will be ignored,

The issue status specified in the uploaded file will be ignored,

BOM positions are created with the next highest issue status available for the node into which these positions are being imported.

The issue statuses having the usage defined as ‘Not Selectable and Exclude Best QTY’ on the B.10.08 Issue Status screen are not considered when determining the next highest issue status.

In the Runtime Options section, select the Lock BOM check box to automatically lock nodes, node values, positions, and position values during the BOM import.

Starting Job Execution When you have supplied all job parameters, you can start the OMI job either online or in batch The Start button opens another window, where you can choose the execution mode (Online, Batch, or Schedule).


Data Import

Reviewing the Import Protocol When an online import job has finished, you can review the log files as well as the import protocol that has been created:

The OMI online log includes several execution statistics, as well as a short summary of data-related problems or data errors that the main import program may have encountered. Please make sure to also check the SQL*Loader Log file; if for some reason your import file had a severe problem with complying to the OMI file format, this log file indicates this problem.

In order to retrieve the Loader Log file from the server in case of batch jobs, your DBA also needs to configure the OMI working directory as UTL_FILE_DIR in the database instance initialization parameter file.


Data Import The detailed OMI import protocol is available for review in the second window of the B.40.01 screen:

You can further customize the kind of protocol information that is displayed by use of the Display Options group in the upper right hand corner. Additionally, OMI will have created a spooled-out version of the log table in the working directory; this file serves as a first-cut protocol containing the most relevant log information and is suited for printout in landscape format. The SmartPlant Materials B.40.R.01 report, which supplies more detailed information, is also available; you can start it from the B.40 submenu.


S E C T I O N 5

Within the BOM import, there is a facility to import your data into SmartPlant Materials called Flat Loading Config. This facility conforms to the import of an ASCII file, but all elements of a BOM (bill of materials) are put together in one record separated by a freely definable delimiter, for example, ‘;’.

This method is an easier way to import. Just collect your data in an Excel sheet and export it to an ASCII file. Then all you have to do is define the column mappings of the ASCII file in SmartPlant Materials and start the Flat Loading Config import. In addition to that import, you can write your own BOM import that will be used instead of the internal import if you want to add some proprietary functions and behavior.

You can use FLC import only in projects. This functionality does not work in product groups.

There are three steps to import a BOM into SmartPlant Materials:

1. Collect your data in an Excel sheet. Use this Excel sheet for the import, or generate a csv file that contains the columns of the data separated with a freely definable separator.

2. Define the columns so that SmartPlant Materials knows the meaning of the columns in the Excel/csv file.

3. Start the import.

Flat Loading Config Import



Collect Import Data The picture below shows an Excel sheet containing all the data for a BOM import. You can collect your data with any other tool that you want, but there must be an Excel or csv file for the import.

The order of the data concerning the columns you assign is freely selectable because you must map them later in SmartPlant Materials anyway.

All columns of each row must be filled completely; for example, if you have several items of a BOM node, you must fill all columns of the node repeated for the appropriate item so that each row contains all the necessary information to import that item of that node. Additionally, you can leave columns free, which might be necessary when filling the Excel sheet or csv file automatically. You just have to account for it later when you map the columns in SmartPlant Materials.

CSV Files After gathering all the data, save the Excel sheet and choose CSV as the file format (*.csv). If you have already loaded into a csv file, then just save. Excel stores the data with semicolon separated columns.



You are allowed to use any character as a column separator, but keep in mind that if a character defined as a column separator occurs within a string, an error might arise while importing the csv file.

Define Column Mappings Before you can start the import operation, you must map the columns so that SmartPlant Materials can store the data in the correct manner.

Open the B.10.41 Flat Configurations screen to define the FLC config with the column mapping.

At the top of the screen in the Flat Configs block, you must enter a name for the configuration to identify the mapping when you start the import later on the B.40.01 BOM Import screen.

Enter a unique name in the Config Name field and a description in the Comment field.

Enter a character in the Delimiter field for the column separator in the csv file. Leave it empty if you use the default delimiter ‘;’ or if you are importing from Excel files.

The number of lines to be skipped during FLC Load must be entered in the Skip Lines field.

Select the Summarize Positions check box if equal positions of a node should be summarized. In this context, equal means not only the basic position data like ident, unit, and so forth must be the same, but also the attribute values. When working with tag description multi NLS feature, tagged items are not summarized. Tagged items are also not summarized if the project default ZB_TAGQTY is set to Y.

If you want the import operation to include a check for CMS (Component Management System) idents, select a CMS class system from the LOV in the Class System field. During BOM import


Flat Loading Config Import using FLC, the FIND_IDENT procedure finds the corresponding CMS ident based on a given set of CMS ident property values and the class system. The ident property values are defined using the FLC items POS_CATTR (Attribute Property) and POS_CTAB (Table Property). These FLC items are not available when a class system is not associated. Similarly, the FLC items POS_SPEC, POS_SHORT, POS_OPTION, POS_CC, POS_SIZE1...4, POS_IATTR, POS_TAB, POS_CG, and POS_CP are not available when a class system is associated.

If the FLC load does not import quantity units, the unit entered in the Quantity Unit field is used. Select the unit from the list of values. All units of the unit group QUANTITY are available. If the FLC load does not import length units, the unit entered in the Length Unit field is used. Select the unit from the list of values. All units of the unit group QUANTITY are available. Both units can be used in the CIP procedure omi_set_unit in the package m_pck_omi_custom to fill the unit field of the table m_flat_pre_imports during the import.

To assign BOM procedures to the flat config, click the BOM Procedures button. Window 2 opens where you can select procedures defined on B.10.21 BOM Procedures/Macros.

With the selection of Pre or Post in the last field, you define if the procedure runs before the import starts (pre) or when it is completed (post).

The Post procedures are not executed automatically during the import. If you run the import job with an enabled Pit Stop option, you must click the Run Procedures button. For more information, see Start Flat Loading Config Import (on page 53).


Flat Loading Config Import Back on the main window of B.10.41, you can define a sort option for BOM position data within each end node. The sort order can be defined on the configuration header level using the Define Sort Order button.

Window 4 opens where the sortable items of the current configuration are displayed. Double-click the items in the Item field in the order you want to add them to the Sort Positions By field. You can add the keyword DESC so this column is sorted in descending order. To add this keyword, select the Descending check box and then double-click in the Item field.

The following items can be used for sorting if they are used in the selected config:

POS_IDENT

POS_CC

POS_CG

POS_CP

POS_ITR

POS_LSTAT

POS_OBJECT

POS_OPTION

POS_SHORT

POS_SIZEn

POS_SPEC

POS_TAG_NU


Flat Loading Config Import When you have added the necessary sort items, click the Apply button to apply this sort order. Window 4 is closed, and the defined sort order is displayed in the Sort Positions By field on B.10.41. Click the Cancel button to return to the configuration without applying changes. To clear the sorting field, you can click the Remove button.

If no sort order is defined, the software uses the standard sort order, which is the order of position data of the import file (fload_id).

In the Flat Config Items block, you define the column mapping. All columns of the file to be imported must be entered in the correct order of the occurrence in the file, without any gaps. If a column is not used in the Excel sheet, just choose IGNORE from the list of values in the Item field, so this column is not read during the import. Select the item from the list of values. The available items with their meaning are listed below.

Item Meaning

GUID Unique identifier for the record

IGNORE Dummy column

NODE_ATTR Horizontal Location and Interpretation of Node Attribute

NODE_LEV0N Horizontal Location of 0th Node Name in Hierarchy on Position Level

NODE_LEV1N Horizontal Location of 1st Node Name in Hierarchy on Position Level

NODE_LEV2N Horizontal Location of 2nd Node Name in Hierarchy on Position Level

NODE_LEV3N Horizontal Location of 3rd Node Name in Hierarchy on Position Level








Flat Loading Config Import POS_ATTR Horizontal Location and Interpretation of Position Attribute

POS_CC Horizontal Location of Commodity Code on Position Level

POS_CG Horizontal Location of Commodity Group on position level

POS_CP Horizontal Location of Commodity Part on position level

POS_IDENT Horizontal Location of Ident Code on Position Level

POS_ISTAT Issue status per node

POS_ITR Horizontal Location of item rule on position level

POS_LSTAT Horizontal Location of item rule on position level

POS_MAIN Horizontal Location of main assembly position

POS_NUM Horizontal Location of the position number

POS_OPTION Horizontal Location of Option Code on Position Level

POS_QTY Horizontal Location of Quantity on Position Level

POS_RTYPE Horizontal Location of Record Type on Position Level

POS_SHORT Horizontal Location of Short Code on Position Level

POS_SIZ2WU Horizontal Location of Size2 with Unit on Position Level

POS_SIZE1 Horizontal Location of Size1 on Position Level




POS_SPEC Horizontal Location of Spec Code on Position Level

POS_SUB01 Horizontal Location of Sub Position Number at assembly level 1






Flat Loading Config Import POS_SUB06 Horizontal Location of Sub Position Number at assembly level 6





POS_SUM_ID Summarize equal idents on position level

POS_TAB Horizontal Location of a table detail to identify commodity code

POS_TAG_LO Horizontal Location of tag number long layout (standard/login language) on position level

POS_TAG_L2 Horizontal Location of tag number long layout (second language) on position level

POS_TAG_L3 Horizontal Location of tag number long layout (third language) on position level

POS_TAG_NU Horizontal Location of tag number on position level

POS_TAG_SH Horizontal Location of tag number short layout (standard/login language) on position level

POS_TAG_S2 Horizontal Location of tag number short layout (second language) on position level

POS_TAG_S3 Horizontal Location of tag number short layout (third language) on position level

POS_UNIT Position Quantity Unit (NO LENGTH but pcs, EA, and so on)

If you have assigned a class system to the flat config in the Class System field, you must assign these items to your FLC config:

POS_CATTR Attribute Property

POS_CTAB Table Property

The POS_CATTR and POS_CTAB items are not available when you haven’t assigned a

class system to the FLC config.


Flat Loading Config Import The FLC items POS_SPEC, POS_SHORT, POS_OPTION, POS_CC, POS_SIZE1...4,

POS_IATTR, POS_TAB, POS_CG, and POS_CP are not available when a class system is assigned to the FLC config.

The Values field also offers a list of values. The available values depend on the selected item. You cannot enter any value in the Value field where it’s not applicable, that is, for items GUID, IGNORE, NODE_LEVxN, POS_CC, POS_CG, or POS_CP.

If you want to specify a default value for the column, you can enter it in the Default field.

With regard to POS_ISTAT, this setting is on the node level. If the first row belonging to a node does not have a value for the issue status, the value from the import job is used. An LOV is available in the Default field for the POS_ISTAT item. If a value is entered in the Default field, it is applied to records where a value for issue status is missing.

Enter a comment in the Comment field to explain the purpose of the item.

The Consider Delta check box allows you to define whether that column must be considered when importing the same file again with updated data.

To make the input of column mapping easier to do, you can mark the Propose Sequence check box at the top of the block. When this option is selected, the next sequence number is entered automatically when you enter a new column.

Click the Resequence button at the bottom of the block to rebuild the sequence order after you have deleted records that have caused gaps in the sequence.

When the mapping is complete and all config items are entered, click the Validate button to check if all items are valid. If not, a message appears, informing you about discrepancies and how to correct them. Some columns are mandatory and must be entered. There must be nodes without gaps, node values, exactly one item and attributes. If any of these elements is missing, you are prompted about the necessary action to solve it.

With the Reset button, you can delete all internal temporary data and backups of the flat loading config import concerning the actual configuration. This action does NOT delete any imported BOM.

Click the Templates button to create a new configuration from a standard FLC template delivered with the product. Window 3 opens, and all templates are listed.


Flat Loading Config Import The following standard FLC templates are available:

Application Report FLC Comment

SmartMarine 3D Plates 3D PLATES SmartMarine 3D Plates Report

SmartMarine 3D Profiles 3D PROFILES SmartMarine 3D Profile Report

Intergraph Smart™ 3D Cable Tray 3D CABLETRAY Smart 3D Cable Tray Report

Smart 3D Handrail 3D HANDRAIL Smart 3D Handrail Report

Smart 3D Piping 3D PIPING Smart 3D Piping Report

Smart 3D Steel Structure 3D STEELSTR Smart 3D Steel Structure Report

Select the template you want to use, and click the Start button to copy the config items to the FLC config. If you create an FLC config by copying the items from a standard template, it is recommended that you do not change it.

In this template, each column expected to be loaded is configured by the following fields:

Sequence - The sequence of columns in the file.

Item - Defines the type of data being loaded from the current column.

Value - Value has an item-dependent meaning. A context-sensitive LOV is available.

Value required - This item needs a value defined if checked. If it is not defined, the template is not copied into the FLC configuration.

Auto Create - If this box is checked by the software, it tells the user that the item will be created automatically by the software in all relevant tables and screens. For example, an attribute, which at this point in time is not defined for BOM usage, but configured here in the template as such, will be created automatically. This auto-creation saves a lot of configuration time.

Report column - An information field that lists the name of the column used in the MTO XLS report before the header was deleted.



Start Flat Loading Config Import Open the B.40.01 BOM Import screen.

Create a new import job. First, enter a name in the Job Code field, and select Flat Loading Config from the dropdown list in the Data Source field.

Next, click the Upload button to upload a file from your local computer to the application server. A new screen appears where you can select the file you want to import into SmartPlant Materials.

Then enter values in the Issue Status and List Status fields. Lists of values are available for both fields.

Finally, you must assign the FLC configuration that you have defined on B.10.41 Flat Configurations as described above. You can store mappings for all the different files you want


Flat Loading Config Import to import, so be sure to select the matching configuration for the import file from the list of values.

If you do not define a Delimiter value for the columns of the csv file, the default and recommended value, a semicolon, is used.

After that, you can set the Load Option value for the import: ASCII, CIP, Custom Screen, or Excel File. The default value ASCII means that the import reads the csv file and executes the import completely internally. Choosing the Custom Screen load option calls a custom screen before starting the actual import. The purpose of this custom screen is to copy data into the FLC tables. The custom screen must be defined by the application server-specific DBA setting FLC_CUSTOM_SCREEN on A.60.04.

If you do not want the import performed in this way, you can write your own import procedure using the package m_pck_omi_custom. There is a procedure called omi_flc_load that you can use to implement your own source code for the import of the BOM data. If you choose the load option CIP, the procedure omi_flc_load is executed instead of the internal import.

To check the flat data after it is imported but before it is moved to the staging area, select the Pit Stop check box.

To start the BOM import job, click the Start button. The job first validates the mapping configuration just like the validation on B.10.41 Flat Configurations when you click the Validate button. If there is any problem found concerning the mapping, an error message occurs, and you are prompted to correct the configuration on the B.10.41 Flat Configurations screen.

When the import is done, you can check the result by viewing the log file and, in case of problems, the error report.

If you already have run the import and you want to make some changes in the file, you can make the changes and then start the import again. Select the import job again, and click the New run button. A new job code is generated and you can launch the import again. SmartPlant Materials detects the changes and imports only the changed data.

Only the columns for which you marked the Consider Delta check box on B.10.41 Flat Configurations are imported.


Flat Loading Config Import When the job is defined with the Pit Stop indicator selected, the job stops after importing the flat data into table M_FLAT_PRE_IMPORTS. The procedures of type PRE that are assigned to the FLC configuration are executed before the job stops. The job status is set to STAGE and displayed in the Job Status field, the Review Data button and the Cancel Job button are enabled, and the Start button changes to Continue Job.

A staged import job blocks all other jobs with the same FLC config from being started.

A staged import job prevents changes to the FLC configuration.

Click the Review Data button. A window opens where the data of table M_FLAT_PRE_IMPORTS appears.

You can review, modify, and delete the displayed data. Click the Auto-Create Config button at the bottom to create a screen configuration according to the used FLC configuration. The fields assigned to the FLC configuration are displayed.

You can use the Order By … button to change the sort order of the displayed records. The selected sort order is shown in the Ordered by field at the top of the screen.

LOVs are provided where applicable, for example, in the Commodity Group, Commodity Part, and Commodity Code fields.


Flat Loading Config Import Procedures of type ‘Post‘ that were assigned to the FLC configuration can be applied to the data. You can select single procedures from the shortcut menu as displayed in the picture below.

Or, you can run all assigned procedures using the Run Procedures button at the bottom.

Clear the Import check box of all positions that are not to be imported.

Finally, click the Cancel button to close this window and return to the main B.40.01 screen. Click the Continue Job button to continue the FLC import. To cancel the import, click the Cancel Job button.


S E C T I O N 6

The BOM download module (B.20.01.44 List Download) is the BOM export interface in SmartPlant Materials that creates files in the OMI file format; these files can then be used to import this BOM data into another SmartPlant Materials system.

Selecting Data to be Exported On the B.20.01 screen, in the BOM tree window, select the BOM node for which you want to export the BOM substructure and, optionally, also positions data:

BOM Data Export


BOM Data Export

In the toolbar under the main menu, click the button to invoke the B.20.01.44 parameter screen:

Specifying Export Parameters You can export only structure data, or you can also include the BOM positions data. Furthermore, you can specify an option for assembly export. If you want to include only a structural subset under the BOM starting node, you can use a query condition that has been created on A.60.06 with a proper module reference 'B.20.01.44'; this query serves to restrict exported BOM nodes and detail data based on a node selection criterion.

You must also specify for which issue status BOM positions data should be exported: you can specify a specific issue status, or you can have the export program determine the highest or lowest issue status for each node, and then export only positions of this status.

The last option you need to specify is how BOM attributes should be exported. The first option (for SmartPlant Materials Re-Import) takes the BOM attribute propagation logic into account; this option writes records for attributes only once for each first occurrence of a node in the BOM path; subsequent new incarnations of the same node in the context of a different path do not repeat this redundant detail data.

The second option restricts exported attributes to those that are not propagated, that is, only direct node type attributes (B.10.03) and direct discipline-dependent position attributes (B.10.04) are exported, with the additional restriction that these attributes must be included in your BOM view.


BOM Data Export The third and fourth options are similar to the first and second, respectively; however, they do not take into account the propagation logic, that is, they export attribute records for all qualifying attributes, regardless of whether they are propagated or not.

Starting BOM Export After all parameters have been entered, you can start the export online or in batch. After the operation has finished, you can find the export file in OMI format in the specified directory, with the specified file name.


BOM Data Export


S E C T I O N 7

The OMI interface has a PL/SQL call interface that allows you to implement your own data loading code that then populates the OMI M_IMPORT_INTERFACES interface table; this loading code is used instead of SQL*Loader. This feature is useful in cases where this data is already accessible in another database, so it would not make sense to create intermediate files. All data sources that can be accessed from within a stored PL/SQL package procedure, that is, another local or remote Oracle database by means of a database link, or even a database from another vendor for which Oracle Corporation supplies a Transparent Gateway product, can be used for such a customized data transfer implementation.

Additionally, a set of event procedures allows the implementation of a more sophisticated customized business logic that can then be transparently integrated with the standard OMI job execution code.

Available PL/SQL Packages The API consists of two packages.

The first package is m_pck_omi_utl, which must not be modified at all. This package provides the create_job procedure, which inserts a job definition record into the OMI job table and returns the internal identifier of this job to the caller, and the write_omi_log procedure, which allows you to insert status records in the OMI protocol table from within your own event procedures in m_pck_omi_custom. The package also provides two procedures to delete OMI job data: the m_pck_omi_utl.clear_job_data procedure performs the action behind the Clear Import Data button on the B.40.01 screen; the m_pck_omi_utl.clear_job procedure deletes the complete OMI job from the database. Both procedures return the number of deleted records back to the caller via the p_cnt IN/OUT parameter.

The second package body is m_pck_omi_custom. The omi_load procedure in this package is the place where the PL/SQL code for a custom loading program can be implemented. Furthermore, the package body also contains templates for the supported event procedures with an empty execution block (that is, with a BEGIN NULL; END; block).

Integration of Data Loading CIP Procedure Use of the OMI data loading CIP is controlled by the OMI data source option group on the B.40.01 screen, so that it is possible to enable or disable its use on a per-job basis. If it is set to use the API CIP, the SQL*Loader call is replaced with a call to the m_pck_omi_custom.omi_load CIP procedure. Because you can only modify the m_pck_omi_custom package body, the package spec itself remains stable, so that a recompilation of the calling application (that is, the B.40.01 screen) is not necessary.

Open API


Open API

Creating a Job Programmatically The m_pck_omi_utl.create_job procedure has the following call specification:

PROCEDURE create_job (p_proj_id IN m_projects.proj_id%TYPE, p_omij_code IN m_omi_import_jobs.omij_code%TYPE, p_omi_data_source IN m_omi_import_jobs.omi_data_source%TYPE, p_dp_id IN m_disciplines.dp_id%TYPE, p_import_path IN m_omi_import_jobs.import_path%TYPE, p_import_file IN m_omi_import_jobs.import_file%TYPE, p_stat_id IN m_status.stat_id%TYPE, p_lst_id IN m_list_status.lst_id%TYPE, p_transfer_ind IN m_omi_import_jobs.transfer_ind%TYPE, p_find_ident_ind IN m_omi_import_jobs.find_ident_ind%TYPE, p_recognize_ind IN m_omi_import_jobs.recognize_ind%TYPE, p_rev_increment_ind IN m_omi_import_jobs.rev_increment_ind%TYPE, p_transaction_size IN m_omi_import_jobs.transaction_size%TYPE, p_mapping_ind IN m_omi_import_jobs.mapping_ind%TYPE, p_pbc_id IN m_pds_bom_configs.pbc_id%TYPE, p_pds_start_ln_id IN m_omi_import_jobs.pds_start_ln_id%TYPE, p_company_id IN m_companies.company_id%TYPE, p_user_comment IN m_omi_import_jobs.user_comment%TYPE, p_omij_id IN OUT m_omi_import_jobs.omij_id%TYPE);

This procedure creates a job definition record according to the parameters you pass and then commits this transaction. It is not necessary to use this procedure for a custom loading logic; however, its presence enables you to create a job programmatically if you, for example, use a host language environment, and it thus encapsulates access to the SmartPlant Materials OMI data structure, which might be subject to change between versions into a single stored procedure call.

If you use this procedure, you must store the OMIJ_ID in a host variable in your program because this internal job ID is necessary for a call to the m_pck_omi_custom.omi_load procedure as a call parameter.

Loading Data Programmatically The call specification for the m_pck_omi_custom.omi_load CIP procedure looks like the following:

PROCEDURE omi_load (p_omij_id IN m_omi_import_jobs.omij_id%TYPE);

The only parameter that is necessary is the internal job ID. You must insert this value into the omij_id column as you fill the interface table with your program, because the OMI main program uses this ID to identify all the records that belong to the job being executed. You must make sure that you issue a database commit when your procedure is finished. The framework for a possible implementation is outlined in the included comment section; please be sure to take into account the assumptions and prerequisites described in that comment if you are going to implement your own loading code.

After your procedure has been called, the OMI main import program takes control. The program expects to find the interface table filled; all records are subject to the same processing rules and


Open API the same validations as if the table had been filled by SQL*Loader. To the main program, it is totally transparent which method was used to supply the input data.

Please be especially aware of the fact that the sequence in which you insert records here is absolutely crucial to the main import program: you must use the m_seq_import_interfaces_rowcnt database sequence to supply values for the seq_id column, because the OMI main program processes the input records in the order of this column value.

You will most likely have to implement the actual INSERT statement in the center of several nested loops that will have loop code for each of the levels that make up the BOM hierarchy. In other words, an outer loop may control creation of structure records (NODE_BEGIN, NODE) from a tree walk type of query; for each such structure record, an inner loop will handle the structure detail data such as NODE_NLS and NODE_A records. Furthermore, for each node with BOM positions, another set of nested loops should handle the position records, and for each position record, all the variable position attributes. You must take care that before you insert the first position record for any node, you must supply a valid discipline reference by using a DISC record type. You can change position discipline assignments as often as it is needed, even in the context of the same node.

Event Procedures For specific OMI processing events, matching event procedures in the m_pck_omi_custom CIP package are called. Parameters passed to these CIPs always include the internal primary key of the OMI import job (p_omij_id) and a record variable that holds the complete internal processing state of the OMI main program (and for which the PL/SQL record type is declared in the m_pck_bom_load package specification).

Additionally, node level event procedures get the primary key of the affected node passed (p_ln_id), and the position level procedure gets the position primary key passed (p_lp_id).

The following events are supported by the API:

omi_job_start Call specification: PROCEDURE omi_job_start (p_omij_id IN m_omi_import_jobs.omij_id%TYPE, p_state IN m_pck_bom_load.state_rec_type);

This procedure is called after an OMI job has started successfully, that is, at that point in time, the interface table has been populated from the selected data source, and the OMI main program has been called and has successfully initialized all job parameters and configuration options. No records from the interface table have been read or processed yet, however.

omi_job_end Call specification: PROCEDURE omi_job_end

(p_omij_id IN m_omi_import_jobs.omij_id%TYPE, p_state IN m_pck_bom_load.state_rec_type);


Open API

This procedure is called after an OMI job has read and processed the last data record from the interface table; all outstanding BOM transactions have been committed at that point in time. However, no data from the interface table has been deleted yet. Also, the job_status and job_status_summary have not yet been updated for the job record (this update also depends on the outcome of the omi_job_end call).

bom_node_found Call specification: PROCEDURE bom_node_found

(p_omij_id IN m_omi_import_jobs.omij_id%TYPE, p_state IN m_pck_bom_load.state_rec_type, p_ln_id IN m_list_nodes.ln_id%TYPE);

This procedure is called after an interface table record of type NODE _BEGIN or NODE has been processed and the corresponding BOM node has been found to already exist in the database.

The existence of a BOM node does not necessarily imply that this BOM node was already present before this OMI job started; it could also mean that this node was created by this job at some earlier point in time. However, this fact is not tracked by OMI; internal processing status is tracked only from one interface table record to the next, from one BOM position assembly to the next, and finally from one BOM node to the next.

All validations on the node level have been successfully performed at this point in time; also, the internal state as exposed to the CIP by the p_state parameter (see also its type definition in the m_pck_bom_load package specification) contains all necessary variable values to continue processing with the next interface table record in the context of the found BOM node.

bom_node_created Call specification: PROCEDURE bom_node_created

(p_omij_id IN m_omi_import_jobs.omij_id%TYPE, p_state IN m_pck_bom_load.state_rec_type, p_ln_id IN m_list_nodes.ln_id%TYPE);

This procedure behaves the same way as the bom_node_found procedure as far as the processing state is concerned. The bom_node_created procedure is called, however, if OMI has created the BOM node in question immediately before.

bom_pos_created Call specification: PROCEDURE bom_pos_created

(p_omij_id IN m_omi_import_jobs.omij_id%TYPE, p_state IN m_pck_bom_load.state_rec_type, p_assy_stack IN m_pck_bom_load.par_lp_tab_type, p_lp_id IN m_list_pos.lp_id%TYPE);


Open API

This procedure is called immediately after OMI has inserted a new position into the BOM m_list_pos table. For the case in which a BOM assembly is currently being processed, and this structure is valid (that is, the state variable p_state.s_ill_ass_struc evaluates to FALSE), the p_assy_stack variable (which is a PL/SQL Index-By table) contains the assembly structure stack. Its elements may then be accessed by p_state.s_cur_ass_lvl for the current assembly level and p_state.s_prev_ass_lvl for the previous (that is, the parent position) assembly level.

Please be aware that this procedure is called once for each position created; you should keep the code you implement here as compact and fast as possible, because otherwise, the overall OMI import performance will be seriously affected.

Transaction Control If you intend to implement your own business logic using the OMI API, you need to pay attention to the following requirements regarding transaction control in your m_pck_omi_custom CIP code:

1. The m_pck_omi_custom.omi_load procedure MUST commit.

2. Event procedures ARE NOT ALLOWED to commit. Otherwise, a lot of error conditions that also seriously affect the OMI main program processing can occur. If you need any kind of sub transaction handling capabilities in your code, you may only do so by either using intermediate savepoints, or by implementing autonomous transactions. However, you must also not use those savepoint identifiers that are already used internally by the OMI main program before CIP callouts are made. These identifiers are: sv_cr_tag, sv_bom_node_created, sv_bom_node_found, sv_bom_pos_created, sv_lp_pre_transfer, sv_omi_job_start, and sv_omi_job_end.

If a CIP callout results in an unhandled exception situation in your code, the OMI main program rolls the transaction back to the savepoint that it marked previously before the CIP call. The program then writes an error log entry containing the original Oracle error message that was caused by your code, commits this log transaction, and then re-raises the exception. Any such error in your code causes an unsuccessful termination of the complete OMI import job.

Sample Code and Demonstrations In the api_demo\ subdirectory of your SmartPlant Materials OMI installation, you can find two commented examples on how to use the event procedures. Each example is provided in the form of an m_pck_omi_custom package body creation script.

1. omi_cst_sample1.pbd - This simple example illustrates how to insert progress records into custom tables for each OMI event.

2. omi_cst_sample2.pbd - This example provides the logic to have OMI detect via the CIP package which line level BOM nodes and which sheet level BOMs already present before the job started were not loaded in the current OMI job run. Using the BOM procedure m_delete_structure_prc together with an appropriate exception handling mechanism, such sheet nodes are then deleted in the omi_job_end event procedure. Furthermore, all actions related to this logic are logged using the m_pck_omi_utl.write_omi_log procedure; this logging includes records in a way that they may be viewed directly from the B.40.01 screen (Window 2: Import protocol) after the job has finished.


Open API

In order to test and/or use this example, three new custom tables must be installed in another database schema called L_SYS, using the provided omi_cst_sample2.tab script file. For more information, please check the comment sections in both files.


S E C T I O N 8

SmartPlant Materials Tables The OMI interface uses the following database tables:

M_OMI_IMPORT_JOBS - This table stores the job definitions and job options.

M_IMPORT_INTERFACES - This table stores the data loaded either with SQL*Loader or the CIP package. This table is intermediate storage that is then processed by the OMI main program; the main program analyzes and validates the import data and creates BOM data items in the central SmartPlant Materials BOM tables for valid input records.

M_IMPORT_INTERFACE_LOGS - This table stores the import protocols for OMI jobs. The import protocol block on the B.40.01 screen as well as the protocol report B.40.R.01 are based on this table.

M_IMPORT_INTERFACE_ERRS - If the main import program encounters and logs an error to the log table, the offending import records are also copied to this table in order to allow for easier analyzing of data errors. These records are displayed in the detail section in the B.40.01 Import protocol window.

M_PDS_BOM_CONFIGS - This table stores the header of a PDS-to-OMI transfer configuration.

M_PDS_BOM_CONFIG_ITEMS - This table stores the details of PDS-to-OMI transfer configuration in the context of a header record in table m_pds_bom_configs.

M_PDS_RAW_DATA - The PDS to OMI data source option initially loads a PDS standard G-Type BOM report into this intermediate table via SQL*Loader.

Stored PL/SQL Program Units The OMI interface code consists of the following PL/SQL objects:

M_PCK_BOM_DOWNLOAD - The code for the export functionality in B.20.01.44.

M_PCK_OMI_UTL - Various auxiliary procedures and functions for OMI import. Implements the lock handling and provides the environment for SQL*Loader.

M_PCK_OMI_LOOKUP - Contains all internal lookup functions that the OMI main program uses.

M_PCK_BOM_LOAD - The OMI main program.

M_PCK_OMI_CUSTOM - This package provides the PL/SQL API for the OMI interface. Its package body is the only piece of OMI code that customers may modify.

M_PCK_PDS_BOM_IMPORT - This package reads and interprets the contents of the m_pds_raw_data table into which a PDS report is loaded initially, then transforms it into the native OMI format, and finally transfers it into table m_import_interfaces.

Implementation Reference


Implementation Reference

Transaction Control Transaction control is handled internally by the OMI main program. After the number of database operations as specified in the Transaction Size job parameter has been performed, a database commit is issued, and the cursor on the interface table is reopened at the correct position. With this implementation, the Oracle server specifics for the 'Fetch across commits' feature is taken into account, while at the same time it is still possible to process large files without the need of having extremely big rollback segments online.

Lock Handling Lock handling on the job level is implemented in the M_PCK_OMI_UTL package. The lock handling acquires one exclusive user defined lock per SmartPlant Materials project for each job. Lock handles have the form MAR$OMI_<proj_id> and are processed through the DBMS_LOCK Oracle API. Allocated unique handles are visible in the database dictionary table.


A P P E N D I X A

In This Appendix Directories and Files ...................................................................... 69 File Placement for Online and Batch Jobs .................................... 69 Adjusting the SQL*Loader Parameter File .................................... 69 Configuring SmartPlant Materials Settings .................................... 69

Directories and Files The OMI files are located in the %SPMAT_HOME%\SQL\OMI directory. This directory contains the utility files that are needed to run the interface.

File Placement for Online and Batch Jobs The files provided in the %SPMAT_HOME%\SQL\OMI directory must be copied to all OMI working directories. The controlling main program on the B.40.01 screen expects to find these files in the directory path that you specified for your import data file; if the control files are not present in the same directory, you get an error message and further import processing is unable to continue.

Furthermore, this working directory must also be updateable by the calling user because OMI creates its import protocol file and its SQL*Loader Log, Bad, and Discard files in this directory.

Adjusting the SQL*Loader Parameter File The SQL*Loader parameter file omi52.par is in the %SPMAT_HOME%\SQL\OMI directory. It contains an initial setting of 1 MB that SQL*Loader allocates for its bind array. You may modify this bind array size according to your data volume; higher settings require more memory, but will speed up SQL*Loader operation significantly.

Configuring SmartPlant Materials Settings Before you can use the OMI interface, several configuration tasks must be performed. These tasks include setting options on the A.60.04 and on the A.20.12/13 screens.

Appendix: Setup and Configuration



Relevant DBA Settings LOG_FILE_DEST - Specifies globally in which server directory log files for various

SmartPlant Materials programs are created. Can be overridden on A.20.12/13 by supplying a value for the ZX_MAR_LOG parameter.

LOG_ONLINE_JOBS - Specifies whether log files for online jobs should be created at all. Activating this option is highly recommended.

BOM_IMPORT_PATH - Specifies the global default directory for OMI. Can be overridden on A.20.12/13 by supplying a value for the ZI_OMI_IN parameter.

PLUS_EXECUTABLE - Globally specifies the name of the Oracle SQL*Plus program. In OMI, this setting is needed for creating a first-cut import protocol that is spooled out to a file for each job after the main import program finishes.

SQLLDR_EXECUTABLE - Globally specifies the name of the Oracle SQL*Loader program. In OMI, this setting is necessary if you want to use SQL*Loader to populate the interface table from flat ASCII files.

RBS_OMI - Globally specifies a rollback segment that is dedicated to OMI import jobs. If this setting is not configured, the Oracle server randomly assigns a rollback segment to OMI transactions.

OMI_OPTIMIZER_MODE - Specifies the optimizer mode that OMI job execution should use. This value can be CHOOSE, RULE, FIRST_ROWS, or ALL_ROWS. Once the OMI job finishes, the optimizer mode that was in effect before the job started is restored again.

SORT_AREA_SIZE - Specifies the sort area size that is available to all SQL statements (including dynamic index creation) that are executed during an OMI job. You can specify a value between 64K and 256MB here. Once the OMI job finishes, the sort area size that was in effect before the job started is restored again.

Web Environments Click the Upload button to open a new browser window displaying an upload form. Make sure the DBA SERVLET_PATH setting on A.60.04 is set. The value can look like the following:

your_web_server/servlets

The name of your web server is followed by the string /servlets. Do not append a trailing slash.

After the user selects a file from his file system, he can click the Submit button to send the file to the server. The destination path on the application server where the file is stored must be maintained in the DBA BOM_UPLOAD_DEST setting on A.60.04. Here is the valid format for the value:

c:\spmat\bom_uploads\

When the upload is finished, the user can close the additional browser window. The directory and file name of the uploaded file are automatically stored in the appropriate fields of B.40.01. The file name is concatenated by the string OMIJID and the ID of the actual OMI job.



Online Mode The directory stored in BOM_UPLOAD_DEST must contain the OMI control (*.ctl) and .parameter (*.par) files required by the SQL*Loader.

Enter the remaining parameters on B.40.01, and click the Start Online button to run the job.

Batch Mode There is a special solution if the user wants to start the import in batch mode. Normally, the user must use FTP or other programs to send his file to the database server (where it is needed for batch processing); in this case, the database downloads the file from the application server to the file system of the database server. To activate this feature, configure the following:

1. Specify the DBA BOM_UPLOAD_URL setting on A.60.04 to enable the web server to find the OMI file on the application server. A valid entry for the setting is:

your_web_server/bom_uploads

The name of your web server is followed by a virtual directory name. Do not append a trailing slash. You must define an alias in the web server configuration. In the spmat2011.conf file on the application server, there should be a line that looks like the following:

AliasMatch ^/bom_uploads/(..*) "C:\spmat\bom_uploads\$1"

The right hand entry must match the DBA BOM_UPLOAD_DEST setting, except that there is a slash instead of a backslash at the end. The left hand entry must match the BOM_UPLOAD_URL, but the server name is omitted and a trailing slash is added.

2. Specify the DBA BOM_IMPORT_GET_FILE setting on A.60.04 to be Y.

3. Specify the DBA BOM_IMPORT_PATH setting on A.60.04. This setting is used for importing in batch mode and for finding the import file on the database server, independent of a web or client/server environment. The directory stored in BOM_IMPORT_PATH must contain the OMI control (*.ctl) and .parameter (*.par) files that are required by the SQL*Loader.

Click the Start Batch button to check whether a file with this name already exists. If it does not exist, download the one on the application server to the database server.

Relevant Project/Discipline Default Settings ZB_BOMHIER - Specifies whether free or fixed BOM hierarchies are allowed.

ZB_LPSTART - Starting BOM position number.

ZB_LP_INC - Increment for BOM position number.

ZB_LST_ID - Default list status for new BOM positions.

ZB_NODE_UK - If this project default is set to Y, the node names for a node type must be unique within the project. When the software tries to import a node name that already exists for the node type in the project, this setting causes an error message to be written in the log file, and the node is not imported.

ZB_STAT_ID - Default issue status for new BOM positions.

ZB_TAGPART - Default commodity part for tagged items. May be overridden by a group/part specification in the import data.


Appendix: Setup and Configuration ZB_SH_PART – Default commodity part for shape tagged items. Cannot be overridden by a

group/part specification in the import data.

ZB_TAGQTY - Specifies whether for tagged Items any quantity other than 1 is allowed or not (not for item rule SHP).

ZB_VALNODE - If this project default is set to Y, only the node names pre-defined on the B.10.03 Node Types screen for the corresponding node types are allowed to be created during the BOM import. If a node name in the OMI file does not match any of the node names specified on B.10.03, the node is not created and an error message is written to the log file. If the short description or the description for the node does not match the values pre-defined on B.10.03, the pre-defined short description or description is used while creating the node. A warning is written to the log file.

ZI_OMI_CM - OMI company mapping option. Specifies whether in company mapping import mode, only company ident codes are accepted (option COMP), or company ident codes as well as SmartPlant Materials ident codes (option BOTH) are accepted. The default is COMP. For the latter case, you can also specify a mapping priority with ZI_OMI_CMP.

ZI_OMI_CMP - OMI company mapping priority. For company mapping import mode with mapping option BOTH (see ZI_OMI_CM above), this option specifies which ident OMI should use if a company ident as well as a SmartPlant Materials ident is available for a specific ident code. Available options are COMP (this option uses the company ident), MAR (this option uses the SmartPlant Materials ident), and REJ, which disallows ambiguous ident codes, rejects the position record in such a case, and writes an error entry to the OMI log.

ZI_OMI_IN - Default directory for OMI files, defined on the project/discipline level. If it is not set up on this level, the global configuration parameter BOM_IMPORT_PATH value from A.60.04 is used. Please note that these configuration options only influence what value is returned when you click the Default Dir button on this screen. You can at any time specify the directory and file location information manually, without needing to configure these settings at all. These settings just allow a SmartPlant Materials application administrator to make the use of OMI more convenient for users.

ZI_OMI_OPT - This project default is now obsolete. Instead, you can specify a data source on a per-job basis directly on the B.40.01 screen.

ZI_OMI_POS - Specifies the method OMI should use for creation of position numbers for imported BOM positions. The AUTO setting means that OMI does not care about the data content of the position number column from the ASCII file, but instead builds position numbers automatically, based only on ZB_LPSTART and ZB_LP_INC. On the other hand, the DATA setting means that the position number is a required field in the ASCII file that OMI must use on the BOM. For position records where the position number is missing, an error message is generated and the position rejected.

ZI_OMI_DCC – Design Change Control option. This option only takes effect if the site qty transfer option (ZI_OMI_TSQ) is also enabled. If set to Y, OMI will perform automatic cancellation of over-reserved quantities, automatic re-issuing of design change quantities to appropriate design change warehouses, and automatic logging of reservation shortages, if it encounters such situations during load of a new highest issue status position data set into a BOM node.

ZI_OMI_DCA - Design Change Automatic Acknowledgment option. This option specifies how OMI should handle old unacknowledged design change control log entries it may encounter during loading of a new highest issue status position data set into a BOM node. Possible values are: ERR, ACK, and DEL. The default is ERR. These setting values have the following meanings:



ERR: Raise an error and reject the BOM node. This value implies that a new issue status cannot be loaded unless all design change log entries have been explicitly acknowledged on the C.50.01 screen.

ACK: Automatically acknowledge the design change for the old highest issue status and keep the log entry. ACK also implies that you cannot delete the OMI job on the B.40.01 screen after applying a design change, because this job then becomes part of the design change history. The software needs to keep the OMI job along with the design change log entry for future reference.

DEL: Ignore the unacknowledged design change for the old highest issue status and delete the log entry.

Lock Handling Setup For OMI, an algorithm has been implemented to better coordinate concurrent data loading. It is now possible to have one load job per project (regardless of whether online or in batch); these jobs run concurrently with each other.

This algorithm makes use of user-definable lock handling directly on the Oracle server and dramatically decreases the likelihood of deadlock situations, while at the same time import performance is improved because it is no longer necessary for the OMI program to obtain row level locks on the import data. This global project lock handling needs to be configured with the following two parameters:

ZI_OMI_TBT - OMI batch lock timeout (maximum allowable lock wait time specified in minutes).

ZI_OMI_TON - OMI online lock timeout (maximum allowable lock wait time specified in seconds).


A P P E N D I X B

In addition to some error messages that the B.40.01 screen may raise if you fail to supply a complete and valid job definition, the most important and informative messages are available in the second window on the B.40.01 screen. Here you can review the import protocol; in case of a data error, the protocol message states the cause of a problem that the OMI main program has found; the detail section displays the offending record.

Appendix: Error Messages


Appendix: Error Messages


A P P E N D I X C

These utility files perform basic I/O functions for the OMI interface and the B.20.01.44 BOM Download screen. They are on the SmartPlant Materials distribution media, but must be copied to the working directories used for these interfaces.

C.1 SQL*Loader Control Files -- ---------------------------------------------------------- -- File: omi52onl.ctl -- OMI interface in Online Mode -- -- PS 13-DEC-2000: Changed field sizes for OMI 5.2 -- -- ---------------------------------------------------------- Options (Errors = 0, Rows = 2000) -- ---------------------------------------------------------- LOAD DATA -- ---------------------------------------------------------- APPEND INTO TABLE m_sys.m_import_interfaces WHEN (1:2) <> '--' TRAILING NULLCOLS ( kind TERMINATED BY "|", one TERMINATED BY "|", two TERMINATED BY "|", three TERMINATED BY "|", four TERMINATED BY "|", five TERMINATED BY "|", six TERMINATED BY "|", seven TERMINATED BY "|", eight TERMINATED BY "|", nine TERMINATED BY "|", ten CHAR(2000) TERMINATED BY "|", eleven CHAR(2000) TERMINATED BY "|", twelve TERMINATED BY "|", object TERMINATED BY "|", rev TERMINATED BY "|", unit TERMINATED BY "|", option_code TERMINATED BY "|", item TERMINATED BY "|", in_3 TERMINATED BY "|", in_4 TERMINATED BY "|", in_5 TERMINATED BY "|", thirteen TERMINATED BY "|", fourteen TERMINATED BY "|", fifteen TERMINATED BY "|",

Appendix: Utility Files and Scripts


Appendix: Utility Files and Scripts sixteen TERMINATED BY "|", seventeen TERMINATED BY "|" ) -- End of SQL*Loader-Control-File omi52onl.ctl ----------

This file for online loads and the omi52.ctl file for batch loads specify the load options and the SmartPlant Materials table into which the ASCII file is loaded.

You must not modify these files.

The piping_g.ctl control file is used for loading PDS BOM reports into SmartPlant Materials. It has the following structure:

-- Controlfile to import the PDS report output piping_g into -- SPMAT raw data table. This is required for importing PDS data -- into BOM via OMI (B.40.01) -- -- 25-JAN-2000 df created -- LOAD DATA INTO TABLE m_pds_raw_data APPEND -- the existing data is handled by m_pck_pds_bom_import (line SEQUENCE(MAX,1), text POSITION (1:255) CHAR )

SQL*Loader Parameter File The name of this file is omi52.par. Its only purpose is to specify the bind array and read the array size that SQL*Loader should use. You can change these values so that they better suit your data volume.

readsize=1000000 bindsize=1000000

You must not add any other configuration options to this file. It is very important that the load operation is performed using the conventional path method; otherwise, the interface will not work properly.

Export Script (B.20.01.44) This script (B200144.sql) is run by the B.20.01.44 module after all export parameters have been specified and the export job is started. It calls the server side main procedure and spools out the extracted BOM data from the interface table to the specified file. For batch download, another script file (B200144B.sql) with slightly different options is provided.

REM --------------------------------------------------- REM SmartPlant Materials REM --------------------------------------------------- REM REM File: B200144.SQL


Appendix: Utility Files and Scripts REM List Download REM Author: PSchneider REM Created: 16-MAR-1997 REM REM Modifications, changes, enhancements, fixes: REM REM When Who What REM --------- ---------- --------------------------------------------------- REM 13-MAR-98 PSchneider Added m_list_pos.input_3 - input_5 to exported data REM 06-APR-98 PSchneider Added support for query condition on node structure, REM new parameter is p_aqc_id REM 02-JUL-98 PSchneider Added Issue Status for BOM position selection, REM new parameter is p_stat_id REM 12-JAN-99 PSchneider Added maxdata and array size parameters REM 17-FEB-1999 PSchneider Added new fields for OMI 5.1.0 REM 13-DEC-1999 PSchneider Changed field sizes for OMI 5.2.0 REM -------------------------------------------------------------------------- REM REM REM Parameters for procedure call are: REM REM &1: p_from_project BOOLEAN REM &2: p_from_pr_name V2(10) REM &3: p_luv_id NUMBER(12) REM &4: p_user_dp_id NUMBER(12) REM &5: p_ln_id_start NUMBER(12) REM &6: p_with_struc BOOLEAN REM &7: p_with_pos BOOLEAN REM &8: p_assem_option NUMBER REM &9: p_attr_option NUMBER REM &12: p_aqc_id NUMBER REM &13: p_stat_id NUMBER REM REM Spool parameters: REM REM &10: Name of spoolfile REM &11: Path for spoolfile REM REM WHENEVER SQLERROR EXIT FAILURE REM WHENEVER OSERROR EXIT FAILURE SET TAB OFF SET TIMING OFF SET FEEDBACK OFF SET LINESIZE 3710 SET MAXDATA 50000 SET ARRAYSIZE 1 SET PAGESIZE 0


Appendix: Utility Files and Scripts SET TIMING OFF SET HEADING OFF PROMPT PROMPT SELECT '******************' FROM dual; SELECT '* *' FROM dual; SELECT '* SPMat ' || m_pck_install_infos.marian_version || ' *' FROM dual; SELECT '* *' FROM dual; SELECT '******************' FROM dual; PROMPT SELECT m_pck_install_infos.copyright_1 FROM dual; PROMPT PROMPT PROMPT Module: B.20.01.44 List download PROMPT PROMPT PROMPT Call parameters: PROMPT PROMPT Projekt: &2 PROMPT Spoolfile: &11.\&10 PROMPT PROMPT LUV id: &3 PROMPT Assembly option: &8 PROMPT Attribute option: &9 PROMPT Query condition id: &12 PROMPT PROMPT Calling download procedure... PROMPT SET TERMOUT ON SET ECHO OFF EXECUTE m_pck_bom_download.m_list_download_prc(&1, '&2', &3, &4, &5, &6, &7, &8, &9, &12, &13) SET TERMOUT ON PROMPT Procedure completed. Starting download... SPOOL &11.\&10 SET TERMOUT OFF SET TRIMSPOOL ON SELECT RTRIM(DECODE(import,'Y',kind,'N', rpad('--|',3+2*(ei_level-1),'__') || kind) || '|' || one || '|' || two || '|' || three || '|' || four || '|' || five || '|' || six || '|' || seven || '|' || eight || '|' || nine || '|' || ten || '|' || eleven || '|' || ei_level || '|' || object || '|' || rev || '|' || unit || '|' || option_code || '|' || item || '|' || in_3 || '|' || in_4 || '|' || in_5 || '|' || thirteen || '|' || fourteen || '|' || fifteen || '|' || sixteen || '|' || seventeen || '|') FROM m_export_interfaces ORDER BY ei_seq_id;


Appendix: Utility Files and Scripts SPOOL OFF SET HEADING ON SET PAGESIZE 24 SET LINESIZE 100 SET FEEDBACK ON SET TERMOUT ON PROMPT PROMPT Download done. Press <ENTER> to return to SPMAT. PAUSE EXIT

Import Protocol Report Script (B.40.R.01) This script is called immediately after the main import program finishes. It creates a first-cut import protocol that is suited for printout in DIN A4 landscape or in DIN A3 portrait format. You can change the formatting options, or include additional columns from the protocol table, but you should not change the script parameters, because the B.40.01 screen and the OMI scripts rely on being able to pass these parameters to the script.

REM --------------------------------------------------- REM SmartPlant Materials REM --------------------------------------------------- REM REM File: B40R01.SQL REM OMI Import Protocol for last JCS import, REM will be called immediately after main REM import program finished in JCS REM Author: PSchneider REM REM REM Modifications, changes, enhancements, fixes: REM REM When Who What REM ----------- ---------- --------------------------------------------------- REM 10-Oct-1997 PSchneider Created REM 23-Mar-1998 PSchneider Added additional info for BOM node creation REM 18-Feb-1999 PSchneider Merged changes for OMI 5.1: new script parameters REM REM ---------------------------------------------------------------------------- REM REM REM Parameters for script call are: REM REM &1: omij_id NUMBER(12) REM &2: omij_code VARCHAR2(10) REM &3: proj_id VARCHAR2(10) REM &4: Fully qualified name for spoolfile REM


Appendix: Utility Files and Scripts WHENEVER SQLERROR EXIT FAILURE WHENEVER OSERROR EXIT FAILURE SET TIMING OFF SET FEEDBACK OFF SET LINESIZE 1600 SET TRIMSPOOL ON SET PAGESIZE 66 SET ARRAYSIZE 1 SET VERIFY OFF SPOOL &4 PROMPT PROMPT SELECT '******************' FROM dual; SELECT '* *' FROM dual; SELECT '* SPMat ' || m_pck_install_infos.marian_version || ' *' FROM dual; SELECT '* *' FROM dual; SELECT '******************' FROM dual; PROMPT SELECT m_pck_install_infos.copyright_1 FROM dual; PROMPT PROMPT PROMPT Report script: B.40.R.01 - OMI Import Protocol PROMPT PROMPT Call parameters: PROMPT PROMPT OMI-Job (ID) : &1 PROMPT OMI-Job (Code) : &2 PROMPT Project : &3 PROMPT Spoolfile : &4 PROMPT PROMPT COLUMN line HEADING Line# FORMAT 9999999 COLUMN kind HEADING Kind FORMAT a12 COLUMN text HEADING Text FORMAT a50 WORD_WRAPPED COLUMN path HEADING BOM-Path FORMAT a60 COLUMN pos HEADING Pos# FORMAT a10 COLUMN one HEADING F-1 FORMAT a20 COLUMN two HEADING F-2 FORMAT a20 COLUMN three HEADING F-3 FORMAT a20 COLUMN four HEADING F-4 FORMAT a20 SET TERMOUT OFF SELECT iil.err_line line, iil.kind kind, iil.state st, iil.text text, DECODE(iil.err_ln_id, NULL, NULL, list_path_to_root(iil.err_ln_id, '/')) path, DECODE(iil.state, 'E', err_lp_pos, NULL) pos, iie.one one,


Appendix: Utility Files and Scripts iie.two two, iie.three three, iie.four four FROM m_import_interface_errs iie, m_import_interface_logs iil WHERE iil.omij_id = &1 AND iil.proj_id = UPPER('&3') AND iil.seq_id = iie.seq_id (+) AND iil.kind <> 'COMMIT' ORDER BY iil.log_id; SET TERMOUT ON PROMPT PROMPT PROMPT OMI Import protocol done. PROMPT SPOOL OFF EXIT


Appendix: Utility Files and Scripts


A Adjusting the SQL*Loader Parameter File •

69 Appendix

Error Messages • 75 Setup and Configuration • 69 Utility Files and Scripts • 77

Available PL/SQL Packages • 61

B Batch Mode • 71 BOM Assemblies • 33 BOM Data Export • 57 BOM Issue Status • 10 BOM Revision Control and Release/Lock

Status • 11

C Collect Import Data • 44 Conceptual Overview • 9 Configuring SmartPlant Materials Settings •

69 Creating a Job Programmatically • 62

D Data Import • 39 Database Configuration • 14 Define Column Mappings • 45 Defining an Import Job • 39 Delayed automatic reissue of DCI quantity •

31 Design Change Control • 11

Processing Site Quantities • 28 Directories and Files • 69

E Event Procedures • 63 Export Script (B.20.01.44) • 78

F Fabrication Tracking - Spool Import Mode •

34 File Placement • 39

File Placement for Online and Batch Jobs • 69

Flat Loading Config Import • 43

G General File Format • 15

I Implementation Reference • 67 Import File Example • 36 Import Protocol Report Script (B.40.R.01) •

81 Import with Company Mapping • 33 Imported Data • 15 Integration of Data Loading CIP Procedure •

61

L Loading Data Programmatically • 62 Lock Handling • 68 Lock Handling Setup • 73

M Mapping BOM Hierarchical Data to a Flat

File Structure • 11

O Object Codes and Recognize Mode • 35 Online Mode • 71 Open API • 61 Open API Features • 12 ORACLE Tools • 13

P Position Numbering • 28 Preface • 7 Prerequisites • 13 Processing Logic • 26 Processing PDS BOM Reports • 12 Processing SmartPlant® Instrumentation

Data • 12 Propagating Variable BOM Attributes • 10

Index


Index R Record Layout • 17 Record Types • 15 Relevant DBA Settings • 70 Relevant Project/Discipline Default Settings

• 71 Replace / Append Mode • 28 Required Data in the SmartPlant Materials

Database • 13 Reviewing the Import Protocol • 41

S Sample Code and Demonstrations • 65 Selecting Data to be Exported • 57 SmartPlant Materials BOM Data Structures

• 9 SmartPlant Materials Tables • 67 Specifying Export Parameters • 58 SQL*Loader Parameter File • 78 Start Flat Loading Config Import • 53 Starting BOM Export • 59 Starting Job Execution • 40 Stored PL/SQL Program Units • 67

T TAG – Attribute Based Tag • 32 Tagged Items • 31 Transaction Control • 65, 68 Transfer / Simulation Mode • 27

W Web Environments • 70


SmartPlant Materials Open MTO Interface (OMI)

Documents

Transcript of SmartPlant Materials Open MTO Interface (OMI)