X-BOM Connector for SAP

X-BOM Connector for SAP

Administrator's Guide

3DEXPERIENCE R2019x

3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 2 (v 20180925)

3DEXPERIENCE Platform is based on the V6 Architecture © 2007-2018 Dassault Systèmes.

The 3DEXPERIENCE Platform for 2019x is protected by certain patents, trademarks, copyrights, and other

restricted rights, the full list of which is available at the 3DS support site: http://help.3ds.com/ .

Certain portions of the 3DEXPERIENCE Platform R2019x contain elements subject to copyright owned by third

party, the full list of which is also available at the 3DS support site mentioned above.

You will require an account with support in order to view this page. From the support page, select your desired

product version and language to launch the appropriate help. Select Legal Notices from left frame. This displays

the full list of patents, trademarks and copyrights for this product.

Any copyrights not listed belong to their respective copyrights owners.

http://help.3ds.com/2017x/English/DSDoc/Frontmatter/spenot.htm?ContextScope=all&id=fe3ebdcf1077405eb89ec31d4deb130b#Pg0&ProductType=&ProductName


Additional Copyright and Trademark Information

© 2013 ff T-Systems International GmbH

All rights reserved.

PROPRIETARY RIGHTS NOTICE: This documentation is proprietary property of T-Systems International.

The documentation that accompanies T-Systems products describes the applications as delivered by T-Systems. This documentation may include readme files, online

help, user guides, and administrator guides. If changes are made to an application or to the underlying framework, T-Systems cannot ensure the accuracy of this

documentation. These changes include but are not limited to: changing onscreen text, adding or removing fields on a page, making changes to the administrative

objects in the schema, adding new JSPs or changing existing JSPs, changing trigger programs, changing the installation or login process, or changing the values in any

properties file. For instructions on customizing the product see the Administrator’s Guide.

T-Systems International GmbH

Hahnstraße 43d

D-60528 Frankfurt am Main

Germany

Phone +49 69 66531-0, Fax +49 69 66531-5059

E-mail for questions related to this product: [email protected]

http://www.t-systems.com/

Additional Components

SAP R/3 is a registered trademark of SAP Deutschland AG & Co KG

SAP Deutschland AG & Co KG

Hasso-Plattner-Ring 7

69190 Walldorf

Phone +49-6227-7-47474

http://www.sap.com/

http://www.t-systems.com/

http://www.sap.com/


Table of Contents

Overview .............................................................................................................. 8

About X-BOM Connector for SAP ........................................................................ 8

Before Reading This Guide .................................................................................. 9

Getting the Most Out of This Guide ...................................................................... 9

Conceptual Notes ............................................................................................. 10

Place in Product Development Process and Application Architecture................. 10

TCL Programming Architecture .......................................................................... 11

Dynamic Libraries .............................................................................................. 12

General Remarks ............................................................................................... 12

Native RFC Connection ..................................................................................... 13

JCo Connection ................................................................................................. 13

User Interface .................................................................................................... 13

Installation ......................................................................................................... 14

Installation Prerequisites .................................................................................... 14

Preparing the Installation.................................................................................... 15

Remarks about the PLM-side Initialization Files ................................................. 15

Getting the SAP Connection Libraries ................................................................ 15

Collecting Basic SAP Information ....................................................................... 16

Collecting Basic 3DEXPERIENCE Platform Information..................................... 17

Support of Current Change Object Types .......................................................... 18

Collecting Other Information ............................................................................... 19

Setting up a Test Plan ........................................................................................ 19

Editing the Schema Installation Program ............................................................ 19

Installing X-BOM Connector for SAP ............................................................................. 23

Installing the Shared Libraries (Native SAP RFC) .............................................. 23

File Names for MS Windows (64-bit) .................................................................. 24

File Names and Settings for AIX (64-bit) ............................................................ 24

File Names and Settings for Solaris (SPARC and x-86/64, 64-bit) ..................... 24

File Names and Settings for Linux (SuSe and Redhat, 64-bit) ............................ 24

Shared Library Destinations ............................................................................... 25

Extending UNIX Environment Variables ............................................................. 26

Installing the Shared Libraries (SAP JCo) .......................................................... 26

Shared Library Destinations ............................................................................... 26


Installing and Customizing the SAP Function Modules ....................................... 27

Running the Schema Installation Program ......................................................... 28

Checking and Updating Application Settings ...................................................... 28

SAP Connection ................................................................................................. 28

Trace File Destination ........................................................................................ 29

Switching Trace File Creation On/Off ................................................................. 29

Date and Time Formats ..................................................................................... 29

3DEXPERIENCE Decimal Separator ................................................................. 30

Declaring Which Change Objects to Enable for Transfer ................................... 30

Installing the Web User Interface ....................................................................... 31

Completing the Installation ............................................................................................ 32

Typical Post-Installation Tasks ........................................................................... 34

Setting Up Additional Rich Client Installations .................................................... 34

Modifying Your Installation ................................................................................. 34

Un-Installing X-BOM Connector for SAP ............................................................ 34

Schema and GUI Reference ............................................................................. 36

Schema Extension ............................................................................................. 36

Types ................................................................................................................. 36

Attributes ............................................................................................................ 36

Policies .............................................................................................................. 37

Programs: Customer-Adaptable TCL Libraries ................................................... 37

Programs: Standard TCL Programs and Libraries .............................................. 38

Programs: Methods and Wizards ....................................................................... 39

Programs: Triggers ............................................................................................ 40

GUI Extension .................................................................................................... 40

Common Component GUI Extensions................................................................ 40

Web Application Extensions: JSP Files .............................................................. 43

Web Application Extensions: Property Files ....................................................... 44

Web Application Extensions: Help Files ............................................................. 44

Other 3DEXPERIENCE Platform Elements ........................................................ 44

Dynamic Libraries Reference .......................................................................... 45

Overview ............................................................................................................ 45

Loading the Libraries .......................................................................................... 45

Accessing SAP Through the mxsaprfc Command .............................................. 46

Configuration Options ...................................................................................... 47

Configuring the SAP Connection ........................................................................ 47


Changing the SAP System ID ............................................................................ 47

Choosing the SAP Connection Interface ............................................................ 48

SAP User Capabilities ........................................................................................ 49

Configuring Date and Decimal Separator Formats ............................................. 49

Configuring Attribute Ranges ............................................................................. 50

Configuring Attribute Mapping ............................................................................ 51

Default Values in "SAP Default Values" Attribute ............................................... 51

Mapping and Configuration Settings in SAPSettings.tcl ..................................... 52

Settings Related to Engineering Change Objects ............................................... 54

Settings Related to Handling of Manufacturing BOMs and MCOs ...................... 55

Setting the Document URL for Viewing Through 3DEXPERIENCE .................... 55

Configuring Basic Attribute Value Conversion .................................................... 56

Configuring Event Triggers ................................................................................. 57

Customization Options..................................................................................... 59

Extending the Help System ................................................................................ 59

Notes on Internationalization (i18n) .................................................................... 60

How to Use and Modify Library Procedures ....................................................... 61

How to Change Core Procedures ....................................................................... 62

Attribute Value Conversion ................................................................................. 62

Considerations for Special Object Types ............................................................ 62

Extended customizing: The mxsaprfc TCL Command ........................................ 63

Command Syntax .............................................................................................. 64

mxsaprfc Function Reference: call ..................................................................... 64

mxsaprfc Function Reference: open ................................................................... 64

mxsaprfc Function Reference: close .................................................................. 65

mxsaprfc Function Reference: getprocess/getthread ......................................... 65

mxsaprfc Function Reference: help .................................................................... 65

mxsaprfc Parameter Reference: connect/handle ................................................ 65

mxsaprfc Parameter Reference: export .............................................................. 67

mxsaprfc Parameter Reference: import .............................................................. 67

mxsaprfc Parameter Reference: tables .............................................................. 68

mxsaprfc Parameter Reference: tcldebug .......................................................... 68

mxsaprfc Coding Examples: SAP Connection .................................................... 68

mxsaprfc Coding Examples: Import, Export, Tables ........................................... 69

mxsaprfc Coding Examples: Miscellaneous ....................................................... 70

Customizing SAP .............................................................................................. 74

Customizing the SAP Document Management System ...................................... 74


Prerequisite for Physical File Transfer – Native SAP RFC .................................. 74

Prerequisite for Physical File Transfer – SAP JCo.............................................. 75

Customizing SAP DMS Settings ......................................................................... 75

Defining SAP Document Originals by Backlink to 3DEXPERIENCE ................... 78

Checking the DMS Customization Tables .......................................................... 82

Customizing the SAP BOM System ................................................................... 83

Customizing the SAP Engineering Change Management .................................. 84

Troubleshooting ............................................................................................... 87

General Recommendations for Troubleshooting ................................................ 87

Log Files and Tracing ......................................................................................... 88

TCL Logging ...................................................................................................... 89

mxsaprfc Trace .................................................................................................. 89

SAP RFC Trace ................................................................................................. 89

Library Load Test ............................................................................................... 90

Possible Problems and How to Solve them ........................................................ 90

Incident Reports ................................................................................................. 91

Known Issues ..................................................................................................... 91

Glossary ............................................................................................................ 92

Index .................................................................................................................. 98


Overview

X-BOM Connector for SAP is an application that provides an interface between the

3DEXPERIENCE Platform™ PLM environment and the SAP R/3™ ERP environment, enabling

data transfer and synchronisation in both directions. This guide helps you to install and manage

this application.

In this section:

About X-BOM Connector for SAP

Before Reading This Guide

Getting the Most Out of This Guide

About X-BOM Connector for SAP

X-BOM Connector for SAP is an application that extends the functions of the 3DEXPERIENCE

Platform PLM system towards a data exchange and synchronisation with the enterprise resource

planning system SAP R/3. Standard functions are the transfer of 3DEXPERIENCE Parts to SAP

Material Masters, 3DEXPERIENCE specifications to SAP Document Information Records,

3DEXPERIENCE BOMs to SAP BOMs and 3DEXPERIENCE COs/ECOs to SAP Change Masters.

You can also transfer other objects and their attributes if you configure X-BOM Connector for SAP

accordingly. In addition, it has functions to view SAP data and to compare BOMs between SAP and

the 3DEXPERIENCE Platform Platform.

X-BOM Connector for SAP can be used interactively through the 3DEXPERIENCE user interface,

but in many customer environments it is set up to work mainly through 3DEXPERIENCE Platform

event triggers.

X-BOM Connector for SAP is highly configurable- in fact, there is no such thing as a "standard

installation" in productive use. The reason is that the SAP systems as well as the PLM and ERP

business processes are quite specific for each company. Consequently, X-BOM Connector for SAP is

not so much a ready-to-use application but a toolbox that has pre-fabricated code for many business

cases. It is your task as a system administrator to choose the settings and to add the customizations

from this toolbox to support the business processes your company requires. This guide is there to help

you to find the tools you need.

Note: All references to "PLM" items or functions refer to items or functions in the 3DEXPERIENCE

Platform PLM system; all references to "ERP" or "SAP" items or functions refer to items or functions

in the SAP R/3 ERP system.


Before Reading This Guide

The functions of X-BOM Connector for SAP are not described in detail here. To learn more about the

functions provided please refer to the X-BOM Connector for SAP User's Guide and to the available

sales documents, for example the X-BOM Connector for SAP Feature List document.

You should also be aware of the business processes your company employs. To customize the

application or to work together with external experts who do the customizing, you need to be aware of

the process decisions that were made, and you will also need to co-operate with the SAP system

administrators of your company. Many configuration or customization options require some

knowledge of the SAP system(s), their configuration, and how to access them in your network.

Many decisions about the way the 3DEXPERIENCE and SAP systems shall work together will have

been taken before you even start to install X-BOM Connector for SAP, and you should know those

decisions. They range from purely technical issues like SAP system names and connection ports to

high-level decisions about the way the PLM and ERP processes shall work together, including

questions like "which system is master for which data" and "what is required from one system before

the other is allowed to do what".

Getting the Most Out of This Guide

We assume that you are aware of the contents the Application Exchange Framework guides and that

you know the programming and customization guides for 3DEXPERIENCE Platform. X-BOM

Connector for SAP uses the standard 3DEXPERIENCE customization methods and user interface

elements.

To install our product you need to know how to install an application suite in 3DEXPERIENCE

Platform and to deploy it as a web application. You also need to know where 3DEXPERIENCE

Platform is installed and how the system is set up (servers, locations, installation paths, start-up scripts

etc.).

You should also read the Engineering BOM Management Administrator's Guide and, if you use it, the

Manufacturing BOM Management Administrator's Guide, and you should be accustomed to the object

types and attributes and to the concepts of the engineering change process described there. In

particular, be aware of the object types your PLM system uses and what their significance is. This

guide refers to the standard object types installed with the Engineering BOM Management

application.

You should be familiar with SAP's concept for revisions and effectivity dates, because it is radically

different from the concept used in the 3DEXPERIENCE Platform. Without understanding the SAP

concept it will be difficult to work with the integration and to interpret the results of your actions

correctly. You should also be aware of what "BOM Usage" means in SAP.

Published examples in this document, including but not limited to scripts, programs, and related

items, are intended to provide some assistance to customers by example. They are for demonstration

purposes only. It does not imply an obligation to provide examples for every published platform, or

for every potential permutation of platforms/products/versions/etc.


Conceptual Notes

This section explains the concepts behind X-BOM Connector for SAP. To know these concepts

will help you to understand the possible customizations that you can apply. It should also help

you in discussions with your SAP-side counterparts.

In this section:

Place in Product Development Process and Application Architecture

TCL Programming Architecture

Dynamic Libraries

User Interface

Place in Product Development Process and Application Architecture

X-BOM Connector for SAP is an application that has out-of-the-box functions to transfer parts, bills

of material, documents and COs/ECOs. Because customer processes and SAP systems are so very

different, X-BOM Connector for SAP is also a toolbox to expand the standard functionality. Its place

in the product development process is typically at the border between PLM and ERP responsibilities,

though other uses are possible and known:

These are the main features of our application from an architectural point of view:

X-BOM Connector for SAP extends the 3DEXPERIENCE Platform TCL interpreter by

one universal command to communicate with SAP servers. It uses the standard SAP

RFC libraries or, alternatively, the standard SAP JCo libraries for the actual

communication.

X-BOM Connector for SAP extends the 3DEXPERIENCE Platform functions. If you

use SAP JCo mode you may need to add a few function modules we provide to SAP,

otherwise X-BOM Connector for SAP does not change anything in your SAP system.

The X-BOM Connector for SAP application identifies itself as the service suite

"MxSAP" in the 3DEXPERIENCE application environment.


The X-BOM Connector for SAP functions are implemented as TCL scripts. Some of the

script libraries are expressly provided for the customer to modify and extend the basic

functions.

You can use the functions of X-BOM Connector for SAP interactively through JSPs and

user interface components that come with the application. Using the functions through

triggers is also possible and actually more typical in productive environments.

X-BOM Connector for SAP mainly uses SAP BAPI (Business Application

Programming Interface) function modules. Access to the function modules is through

SAP's RFC protocol. X-BOM Connector for SAP is designed to allow using any RFC-

enabled SAP function module, not just the BAPI modules the out-of-the-box installation

uses.

All communication is synchronous, meaning that the user's 3DEXPERIENCE Platform process is

suspended until SAP returns a result message. Do not confuse this with the ability to run in batch

mode; it is quite possible to customize X-BOM Connector for SAP to run in batch mode, but this still

leaves each "atomic" transfer synchronous, only that it suspends the batch process instead of the user

client system.

Communication between X-BOM Connector for SAP and SAP uses SAP's RFC protocol (Remote

Function Calls), which means that communication is done at the application layer of SAP's 3-tier

architecture. The protocol can be invoked by using either the native RFC libraries (pre-V6R2013x this

was the only option) or the SAP JCo libraries.

Top: X-BOM Connector for SAP native RFC connection variant

Bottom: X-BOM Connector for SAP JCo connection variant

TCL Programming Architecture

The individual functions are implemented as TCL script procedures that run in the 3DEXPERIENCE

runtime program environment (RPE). The procedures are organized into libraries (programs holding

TCL code) that reside in the 3DEXPERIENCE database. TCL libraries fall into two categories:


Customer Libraries: They contain the procedures that you may change for

customization. These libraries will never get replaced when you upgrade your

installation. Customer libraries are SAPSettings.tcl, SAPToplevel.tcl and

SAPCustomerLib.tcl.

Core Libraries: They should be used as delivered, you should not change them for

customization. These libraries may be replaced when you upgrade your installation. All

libraries not mentioned above are core libraries.

Customer library procedures always overload core library procedures. If you need to change core

library procedures you can copy them to SAPCustomerLib.tcl and change the copy.

The names of all libraries, as well as the names of all other database objects added during the

installation, supplied with X-BOM Connector for SAP begin with "SAP" which makes it easy to find

them in the 3DEXPERIENCE Business application.

You can apply further customization by writing new procedures, changing or adding GUI elements

and adding new RFC-enabled function modules to SAP. To use such new SAP modules you do not

need to extend the mxsaprfc command, it can handle any existing and new SAP modules as it is.

For compatibility and administrative purposes X-BOM Connector for SAP also defines some methods

that you can you can use from a rich client environment. Please note that rich client access for non-

administrative users is strongly discouraged by Dassault Systèmes.

Dynamic Libraries

General Remarks

You can use either of the two connection methods described below, native RFC or JCo. Please note

that you have to rerun the Schema Installation (see Running the Schema Installation Program) for the

JCo Connection (see SAP Connection).

To switch the connection method you only need to modify a single setting parameter and re-start the

3DEXPERIENCE Platform server. Switching the connection method does not require any changes to

the TCL procedures that provide the business logic, and it does not change the functionality or the

user experience in any way.

See the Installation section of this manual for information of how to install the libraries and about the

dependencies between them. Please see the Dynamic Libraries Reference section for detailed

information about the mxsaprfc command.


Native RFC Connection

The mxsaprfc dynamic library (mxsaprfc85.dll on a Windows system) extends the

3DEXPERIENCE TCL interpreter by the command mxsaprfc. This command is used for all

communication to SAP. Normally you do not need to know about this command as it is encapsulated

in TCL procedures, but it may be useful for advanced customization projects.

The SAP librfc library set is needed for communication to SAP, which means that it must be

available on the 3DEXPERIENCE Platform server or even on the client machine if you use the

3DEXPERIENCE rich client. The RFC libraries are supplied by SAP and must match the SAP

version you run. They come in two flavours, either as a single library for non-Unicode SAP systems

or as a set of libraries that can be used for Unicode and non-Unicode SAP systems. For ENOVIA and

3DEXPERIENCE systems of version V6R2011x or later you must use the Unicode-enabled set of

libraries.

Native RFC connections have been officially deprecated by SAP with release 7.11. However, as of

7.12 SAP still provides the RFC libraries, and because of the wide use of this connection method we

expect that it will continue to work for a long time.

JCo Connection

For this method, the mxsaprfc command is implemented as a TCL procedure that accepts the same

call parameters as the mxsaprfc command described above. This TCL procedure processes the call

parameters into a form suitable for a Java Program Object (JPO) provided with X-BOM Connector for

SAP. This JPO in turn uses the SAP JCo Libraries to connect to SAP.

Instead of the librfc libraries you need SAP’s set of JCo libraries for this connection option. The

JCo libraries are supplied by SAP and must match the SAP version you run.

In addition to the libraries a specific argument parser is requested for this kind of connection to SAP.

This class has to put in the same directory like the JCo libraries (see Shared Library Destinations).

Because of limitations of SAP JCo you need to install a set of function modules in SAP if you want to

use physical file transfer from 3DEXPERIENCE to SAP. These function modules are delivered with

X-BOM Connector for SAP in the form of an SAP transport order. You need to have SAP

NetWeaver 7 installed on your SAP system to use these function modules.

User Interface

The user interface uses a few Java server pages (JSPs) whose names begin with gdSAP or SAP and

that reside in a web application directory named sap. The pages use standard, 3DEXPERIENCE

common-component-style interface elements like menus, commands, portals and channels. Access to

most of the pages is provided through 3DEXPERIENCE categories, in other words through the type-

specific Categories menu. In a standard installation the category for X-BOM Connector for SAP is

called SAP Power View or SAP Actions and is available for Parts, ECOs, COs or CAs, MCOs and

documents. Each Power View page provides a type-specific toolbar menu that is always called SAP

Actions.


Installation

This section describes the installation procedure for X-BOM Connector for SAP, including the

initial set-up to connect to the SAP system as well as test procedures to check your installation.

In this section:

Installation Prerequisites

Preparing the Installation

Installing X-BOM Connector for SAP

Completing the Installation

Typical Post-Installation Tasks

Installation Prerequisites

X-BOM Connector for SAP can be installed on any 3DEXPERIENCE Platform system

from version 10.5 on. Older systems may need additional customizing, though in

principle an installation should be possible. X-BOM Connector for SAP supports the

same platforms as 3DEXPERIENCE Platform.

X-BOM Connector for SAP can connect to SAP systems from 4.6C on, up to and

including ECC6 (7.x). Support for older SAP systems is possible on a project basis but

is not recommended due to severe limitations of the SAP API in these old versions.

Please note that the mxsaprfc libraries that come with the installation set are built

against the most recent TCL and SAP libraries. If you want to install X-BOM Connector

for SAP on an older ENOVIA, 3DEXPERIENCE or SAP system you may need other

libraries; in that case please contact your support partner to get the mxsaprfc libraries

that fit your system environment.

The installer delivered with the application package is not the usual, wizard-style

installer other 3DEXPERIENCE applications use. The reason is that there is no such

thing as a "standard installation" if we talk of productive systems (and we consider out-

of-the-box systems as suitable only for evaluations, demos and generally getting

acquainted with the product). To use a "standard installation" would require a "standard

SAP system" (which is not a well-defined term in itself) and "standard business

processes" (which is even fuzzier). Nevertheless you can install X-BOM Connector for

SAP in less than half an hour if you know its ERP and PLM environment well.

The standard installer assumes that the Engineering BOM Management application is

installed in 3DEXPERIENCE Platform. You can also install X-BOM Connector for

SAP on systems without Engineering BOM Management, but this requires some minor

changes to the installation script.


If you plan to use the BOM and document transfer features please contact your SAP

counterpart and make sure that the SAP system is set up to work with these items. See

the Customizing SAP section for information about these and other typical SAP

configuration and customization tasks. You can do SAP customizing before or after

installing X-BOM Connector for SAP, the installation script itself is independent of

SAP functionality; in fact, it does not touch the SAP system at all.

Please note that you need to have SAPHTTP or SAPFTP installed on the

3DEXPERIENCE Platform server machine if you plan to transfer physical files from

PLM to SAP and vice versa (checkin/checkout functions).

If you use JCo connections and want to transfer physical files, you need to install a set

of custom SAP function modules that are part of the X-BOM Connector for SAP

installation kit; this requires that SAP NetWeaver 7 as a prerequisite. See the section

Installing X-BOM Connector for SAP for details.

X-BOM Connector for SAP can be installed but will not run on 3DEXPERIENCE

systems unless you have an appropriate license. Please contact your sales representative

for licensing conditions.

Preparing the Installation

This manual assumes use of 64-bit operating systems, because current 3DEXPERIENCE versions do

not support 32-bit operating systems. Please contact support if you need support for 32-bit OS.

Remarks about the PLM-side Initialization Files

You need information on some of the 3DEXPERIENCE settings during the installation and

configuration of X-BOM Connector for SAP, in particular about the path to the 3DEXPERIENCE

installation and the local settings for date and time. The entry point for your inquiries is the file

enovia.install; it gives you the paths to all important system components, in particular to the

directories BIN_PATH and LIB_PATH where executable files and libraries are located and to the file

enovia.ini where most settings are made. On Unix systems settings may also be made through

environment variables, usually set in the start scripts of the web application server and the rich client

applications.

This installation guide is written for a default 3DEXPERIENCE Platform installation with default

initialization file locations as they are in ENOVIA/3DEXPERIENCE V6R2011x and later. For older

systems please use the older initialization file system, as described in your 3DEXPERIENCE

documentation. For detailed information about the initialization files please see the 3DEXPERIENCE

Platform Installation Guide.

Getting the SAP Connection Libraries

The SAP RFC libraries need to be installed on the 3DEXPERIENCE Platform server, and on every

client machine that shall use X-BOM Connector for SAP with the 3DEXPERIENCE rich client. These

libraries are property of SAP AG and are not part of the X-BOM Connector for SAP installation

package. Your SAP administrators should be able to provide them for you.

Depending on the connection method(s) you want to use, you need the native SAP RFC libraries or

the SAP JCo libraries, or both. SAP JCo connections are only supported for

ENOVIA/3DEXPERIENCE V6R2013x or later.


Native RFC Libraries

o In former releases this was just one library named librfccm or librfc32;

beginning with ENOVIA V6R2011x and full Unicode support this one library has been

replaced with a set of connection libraries. Please look up the exact file names for the

SAP libraries in the section Installing the Shared Libraries, below.

Note: Beginning with ENOVIA V6R2011x you need to install the libraries for Unicode-

enabled SAP systems even if your SAP system is not Unicode-enabled. SAP will care

for the proper character transition process in either case.

o Hint: Look up SAP OSS Note 413708 ("RFC Library That is Current at This Time") to

see how to obtain the correct SAP libraries ("SAP RFC SDK Unicode") for your SAP

system. As of this writing you find them at the SAP Support site, under Support

Packages and Patches / Entry by Application Group / Additional Components / SAP

RFC SDK Unicode. You need a username and password to access the SAP Support site.

Generally the most recent libraries are compatible to older SAP systems, so get the

newest you can find.

o You need to install these libraries in a directory that is included in the PATH system

environment variable; for details please see the Installing X-BOM Connector for SAP

section.

o Note that these libraries will be in place already if a proper SAPGUI client is installed

on the machine. Since having a SAPGUI on your machine is a good idea anyway for

doing administrative work and for checking transfer results when testing the system, or

for troubleshooting purposes, you can save some work if you ask your SAP counterpart

to install the latest SAPGUI client for you on all machines that need the libraries.

SAP JCo Libraries

o The JCo installer packages are platform-specific because they contain JNI modules. You

need to get the JCo installer for the platform your 3DEXPERIENCE Platform server

runs on.

See SAP Notes 549268 and 1077727 for operating system support and JDK

requirements.

o Find the JCo download area at http://service.sap.com/connectors and follow the link

'SAP Java Connector -> Tools & Services'.

o You need to install these libraries in directories that are included in the PATH and

CLASSPATH system environment variables; for details please see the SAP JCo

Installation Manual and the Installing X-BOM Connector for SAP section, below.

o SAP JCo does not support direct transfers of physical files. If you need to send files

from 3DEXPERIENCE to SAP or vice versa you need to install a set of SAP function

modules. They are provided with the X-BOM Connector for SAP installation kit, you do

not get it from SAP.

For this option, you need to have SAP NetWeaver 7 or higher installed on the SAP

system.

Collecting Basic SAP Information

To connect to SAP you need information about the SAP system and a SAP user. This user must have

access rights to work through RFC connections. He does not necessarily need rights to access SAP

interactively, but if he has not, you will need a second user with interactive access to test and verify

http://service.sap.com/connectors


the system. See the Configuring the SAP Connection section for more detailed discussion of SAP

users.

SAP system information will typically be provided by your SAP system administrator. You need the

following information:

SAP system ID: Usually a 3-character string like "I01", "PLM" or so. The installation

defaults to "PLM".

SAP host: The IP address or name of the SAP server. The installation defaults to an

arbitrary IP address.

SAP system number: A 2-digit number. The installation defaults to "00".

SAP client number: A 3-digit number. The installation defaults to "100".

SAP user: Username and password. The installation defaults to "mxsap/matrix".

SAP Plant List: A list of 4-digit plant IDs that shall be available to the

3DEXPERIENCE user. The installation defaults to 0001, 1000, 1100, 2000.

SAP Document Type: The SAP document type you want to use for document transfers.

The installation defaults to "DRW".

SAP BOM Usage Info: A list of 1-digit usage IDs and their explanations. The

installation defaults to "2=Engineering/Design" (default value), "1=Production",

"3=Universal".

SAP Date Format: Find out what date and date/time formats SAP expects. The

installation defaults to "%m/%d/%Y" for the date and "%m/%d/%Y %H:%M:%S" for

date/time (i.e. to the US date and time format).

SAP languages available: Your SAP system has certain languages available for login

and for messages. You should know what languages are available and whether the

match the language(s) used for 3DEXPERIENCE, otherwise you may get mixed-

language output or may even not be able to log into SAP.

You should also find out which character set (SAP codepage) your SAP system uses and whether it is

Unicode-enabled or not. This will become important later in the customization process.

Collecting Basic 3DEXPERIENCE Platform Information

You need to know some settings and to make some decisions about the 3DEXPERIENCE system:

Installation user: Username and password. The installation defaults to "creator/<no

password>".

Vault to Create Configuration Objects In: The installation defaults to

"eService Administration".

Store Designation: Any store that is not dedicated to specific file types will do. The

installation defaults to "STORE".

Note: No files are actually checked in during the installation, but we need a valid store

name to create a policy object.

Relations to Consider for BOM Transfer: The relationships in this list are available to

the user when transferring engineering bills of material in 3DEXPERIENCE. The

installation defaults to "EBOM".


Plant-Related Information: You need this information only if you plan to use

3DEXPERIENCE MBOM-related functions. The object type and attribute default to

"Plant" and "Plant ID"; do not change them unless you are prepared to massively

customize the Manufacturing BOM Management module. The plant mapping list

defines a 1:1 mapping of 3DEXPERIENCE and SAP plant IDs.

Types to Add Methods to: This is only relevant if you plan to use the rich client. The

installation defaults to Part, ECO, Change Order, DOCUMENTS, Drawing Print.

Note: This is a legacy functionality. Methods are mainly used in rich client

environments; they are usually not available in web environments.

Types to Add Categories to: This information is needed to set up the web GUI, in

particular to add commands and menus to the GUI for these types. You need the

symbolic names of the types. The installation defaults to type_Part, type_ECO,

type_ChangeOrder, type_DrawingPrint, type_CADDrawing, type_Sketch and

type_MCO.

Note that the type_ECO category is there to support pre-R2014x objects. See also the

remarks about customizing the use of Change Order vs. Change Action object below.

Decimal Symbol: Find out what decimal symbol 3DEXPERIENCE uses; normally you

find this information in enovia.ini or in the UNIX startup files for the

3DEXPERIENCE server and client systems. This information will later be needed to

decide whether a decimal conversion must be set up.

Date Format: Find out what date and date/time formats 3DEXPERIENCE expects;

normally you find this information in enovia.ini or in the UNIX startup files for the

3DEXPERIENCE server and client systems. This information will later be needed to

decide whether a date conversion must be set up.

Support of Current Change Object Types

With 3DEXPERIENCE Platform 3DEXPERIENCE R2014x the data model for engineering change

has changed. The former ECR/ECO (Engineering Change Request, Engineering Change Order)

objects have been replaced by the Change Request (CR), Change Order (CO) and Change Action

(CA) object types. CR/CO are roughly equivalent to ECR/ECO, but CA is a new type that makes it

possible to handle similar objects by grouping them together in one CA. One CO can have one or

more (multiple) CAs and can only be completed when all connected CAs are promoted to Complete.

Please note that Part and Document transfers to SAP starting from both COs and CAs are limited to

the extent that the CA must be at least in "In Work" status in its lifecycle; this is a limitation from the

3DEXPERIENCE process, not from X-BOM Connector for SAP functionality. The underlying reason

is that in the first stages of the CO lifecycle the “affected items” show the old revisions or Parts; the

new revisions exist only after the CA has been promoted to "In Work".

In the default configuration X-BOM Connector for SAP supports the SAP transfer for ECOs (to

handle legacy objects) and COs (to handle new objects). If you decide to use CAs instead of COs for

SAP transfers (you can use either one or the other, not both) you need to change some settings in the

installation program and, after the installation, some settings in the SAPSettings.tcl program . Pre-

defined blocks of settings exist to make the customization easier.

At this point of the installation you should decide which schema to use, which is actually a question

about the business process you want to use, and take a note to modify the settings if you need to

deviate from the default process. The settings you should apply before the installation (i.e. changes to

the installation program itself) are described in the step-by-step instructions below (see Editing the

Schema Installation Program, setting SAPConfig(ValidFromTypes)).


Collecting Other Information

Trace File / Scratch Directory: Name of a directory for writing trace files and

temporary files (during installation and also later during operation). The installation

defaults to "c:\temp" on Windows and to "/tmp" on UNIX.

Physical file transfer: If you plan to transfer physical files to and from SAP with the

Document Checkin and Document Checkout functions (as opposed to transferring a

URL backlink to 3DEXPERIENCE), you need to make sure that SAPHTTP or SAPFTP

are installed on the 3DEXPERIENCE server machine.

Note: If you use the SAP JCo connection method and want to use physical file transfer

functions, you need to install a set of function modules in your SAP system.

See the sections Installing X-BOM Connector for SAP and Customizing the SAP

Document Management System for details on these topics.

You will need all of the information listed above to install and set up X-BOM Connector for SAP.

Other information will be needed after the installation, for example attribute defaults and mapping

information. Such information should be part of your implementation specification. See the

Configuration Options section for information about how to set up attribute defaults and mapping.

Follow the recommendations in the 3DEXPERIENCE documentation about setting up the

internationalization settings. In our experience working in UTF8 throughout your system works

best.

Setting up a Test Plan

A test plan should be part of your project plan. The tests must be based on your requirement

specification and must verify that every function available to the users works as intended, as well as

every triggered (background) and batch function you specified. Preparing the test data in

3DEXPERIENCE may take some time, so start in time. Do not only take a look at creation of new

data in SAP but also at updating existing data; if this applies to your installation, do not forget

consider the behaviour of migrated and legacy data.

Take care to prepare the test objects with exactly the process that will you use for your production

business objects. Plan also tests with "minimalistic" 3DEXPERIENCE business objects, i.e. objects

that contain only the minimal allowed information; such a test shows whether all mandatory SAP

fields are supplied with data during object creation.

Take particular care to set up tests for all triggered events that you plan to use to verify correct

behaviour of event-triggered operations.

When setting up your test plan please keep in mind that you provide data to manufacturing. As data

progresses along the value chain, mistakes become increasingly expensive. Involve your SAP

colleagues in the testing, because they may be able to see problems that would go unnoticed from a

PLM-oriented perspective.

Editing the Schema Installation Program

This program installs the X-BOM Connector for SAP schema, that means it adds some administrative

and business objects to the 3DEXPERIENCE Platform database. In order to adapt the program to your

environment you need to enter some of the information collected above into the installer program.

If you have not done so yet, now is the time to unpack the installation package file (.tar.gz format).


Locate the installation program. The program is named MxS-ERP-Install-

Standard-EC-Integration.mql and you find it in the install directory of

the installation package.

Open the program in a text editor and locate the file section marked "Begin of customer

configuration".

This is the only file section you should edit. Do not edit any code beyond the "End of

customer configuration" mark.

Edit the codes lines as described below. You may not need to change some of the values

if they fit your environment.

o set SAPConfig(matrixInstallUser) "creator"

set SAPConfig(matrixInstallPassw) ""

Replace "creator" and "" with the username and password of the administrative

3DEXPERIENCE user you want to use for the installation (see Installation User,

above).

o set SAPConfig(SAPVault) "eService Administration"

Replace "eService Administration" with a 3DEXPERIENCE vault name (see Vault to

Create Configuration Objects In, above).

Recommendation: Do not change the vault name, it is the same vault 3DEXPERIENCE

programs use for similar data.

o set SAPConfig(SAPStore) "STORE"

Replace "STORE" with the name of an existing 3DEXPERIENCE store (see Store

Designation, above).

o set SAPConfig(mxsapDir) "c:/temp"

Replace "c:/temp" with the name of a directory (see Scratch Directory, above).

Note that the path is entered in TCL syntax. You need to use the forward slash "/" for

the path even if you are on a Windows system. Do not use the backslash "\" as a

separator.

o set SAPConfig(SAPDestination) "PLM"

Replace "PLM" with ID of your SAP system (see SAP system ID, above).

o set SAPConfig(SAPHost) "192.168.1.1"

Replace "192.168.1.1" with the IP address or the host name of the SAP server (see SAP

host, above).

When working with host names make sure that the name can be resolved into an IP

address on every machine, including rich client machines, that uses X-BOM Connector

for SAP.

o set SAPConfig(SAPSystem) "00"

Replace "00" with the system number of your SAP system (see SAP system number,

above).

o set SAPConfig(SAPClient) "100"

Replace "100" with the client number you will use on your SAP system (see SAP client

number, above).

o set SAPConfig(SAPUser) "mxsap"

set SAPConfig(SAPPassword) "matrix"

Replace "mxsap" and "matrix" with the username and password of the SAP user (see

SAP user, above).


o set SAPConfig(useJCO) "0"

Replace "0" with "1" if you want to configure your connection to use the SAP JCo

interface. Leave the default "0" if you want to use the native SAP RFC interface.

Note: You can easily change this setting later in SAPSettings.tcl

o set SAPConfig(SAPRangesPlant) [list 0001 …]

Replace "0001 ..." with a list of SAP plants you plan to use (see SAP Plant List,

above). The first plant in the list becomes the default plant in the web GUI.

Note: The brackets and the "list" keyword are necessary parts of the TCL code and must

not be removed. The command uses the TCL "list" command syntax.

o set SAPConfig(SAPDocType) "DRW"

Replace "DRW" with the document type you want to use in SAP. This value is used in

SAPCustomerLib.tcl, proc getSapDocKeys.

o set SAPConfig(SAPDocPageURL) "http:// …"

Replace the URL with the one appropriate for your 3DEXPERIENCE system (domain

or IP address and port number). This configuration sets the initial value for the

mxsapSetting(docPageURL)setting which is used when building the document

original URL before transferring it to SAP.

o set SAPConfig(SAPRangesUsage) [list "2=Engineering"

…]

Replace "2=Engineering..." with a list of BOM usages you plan to use (see SAP BOM

Usage Info, above). The first usage in the list becomes the default usage in the web

GUI.


not be removed. The command uses the TCL "list" command syntax. Put each list value

in double quotes, as they are in the default entry.

o set SAPConfig(SAPRangesRelation) [list EBOM]

Replace "EBOM" with a list of 3DEXPERIENCE relationship names that shall be

considered for BOM explosion (see Relations to Consider for BOM Transfer, above).



o set SAPConfig(ValidFromTypes) [list ECO "Change Order"]

The listed object types get a new attribute "SAP Valid From" that is used to set the

effectivity date in SAP. Replace the values in brackets with the names of the

3DEXPERIENCE change object types that shall get this attribute added to their

definition. By default, we apply the attribute to Change Order objects and, for legacy

use, to ECO objects.



o set SAPConfig(PartTypes) [list Part]

set SAPConfig(ECOTypes) [list ECO "Change Order"]

set SAPConfig(DocumentTypes) [list DOCUMENTS …]

This is a legacy setting. Replace the values in brackets with the names of the

3DEXPERIENCE Part types, change object types and Document types that shall get

certain methods added to their definition (see Types to Add Methods to, above).



o set SAPConfig(PartMenu) [list type_Part]

set SAPConfig(ECOMenu) [list type_ECO]

set SAPConfig(ChangeOrderMenu) [list type_ChangeOrder]


set SAPConfig(MCOMenu) [list type_MCO]

set SAPConfig(DocumentMenu) [list type_Drawing …]

Replace "type_..." with the symbolic names for the 3DEXPERIENCE types for which

you want to add functions to their categories menu (see Types to Add Categories to,

above). Note that the ECO object is used for legacy objects only, and that you may

replace type_ChangeOrder with type_ChangeAction if you decide to allow transfers

from Change Actions instead of Change Orders (see Support of Current Change Object

Types for details).



o set SAPConfig(PlantMapping) [list 0000000001 0001

…]

set SAPConfig(PlantType) "Plant"

set SAPConfig(PlantIDAttrib) "Plant ID"

The PlantMapping defines a 1:1 relation between 3DEXPERIENCE plant IDs and

SAP plant IDs. PlantType defines the 3DEXPERIENCE type that shall be considered

a "Plant", and PlantIDAttrib tells us which is the identifying attribute of an

3DEXPERIENCE plant (see Plant-Related Information, above). Except for the

mapping list, changes to these settings require additional customization and should be

avoided.



Save the file and close it.

You may now proceed to the section Installing X-BOM Connector for SAP; look for the instructions

appropriate for the operating system you use (Windows or Unix).


Installing X-BOM Connector for SAP

The installation is somewhat automated, but the automated script does not do a complete installation.

Some manual work is required. This section is a walk-through of the installation; please follow the

steps in the order given here.

Please read the section Preparing the Installation and collect all information listed there, otherwise

you will not be able to complete the installation. You also need knowledge about your

3DEXPERIENCE system and the way it is installed and set up.

We strongly recommend that you install a native SAP client (SAPGUI) on the machine on which you

want to do the administrative tasks. Please contact your SAP counterpart about this installation as we

cannot provide any details about it.

The following two sections describe how to install the shared libraries for the connection to SAP. You

must choose at least one of the options "native SAP RFC" or "SAP JCo". It is possible to install both

options; if you do, you will be able to switch between both options later (this requires a server restart).

Installing the Shared Libraries (Native SAP RFC)

This section describes how to install the libraries for the native SAP RFC interface. If you do not plan

to use native RFC, please ignore this section.

To use native SAP RFC, the parameter mxsapSetting(useJCO) in SAPSettings.tcl must

be set to "0".

The shared libraries are binary files that are system-specific and that have different names on different

operating systems.

The TCL extension libraries come with the installation package in both 32-bit and 64-bit

versions. The directories containing the libraries are in the bin folder of the installation

package, named after the operating system and extended by -32 or -64 for 32-bit and 64-

bit platforms, respectively. Use only the libraries for your platform(s) and ignore the

other library files.

Note: Beginning with ENOVIA V6R2012, only 64-bit operating systems are supported.

The SAP libraries must be provided by your SAP administrators. Please take care to get

the SAP libraries for the right operating system and for 32-bit or 64-bit operation, as

needed.

Please note that you need to get the Unicode library set, even if your SAP system is not set up

for Unicode operation.

The libraries need to be copied to the 3DEXPERIENCE Platform server machine. You must also

install them on rich clients that you use for administrative work; we recommend to set up at least one

such rich client.

The file names given here are those for the current 3DEXPERIENCE Platform release. Different

libraries may be needed for older systems; please contact support if you need to set up X-BOM

Connector for SAP for older ENOVIA/3DEXPERIENCE or SAP systems.


File Names for MS Windows (64-bit)

Note that the file names for 32-bit and 64-bit version are identical; confusingly, SAP decided to put

"32" into the names even for 64-bit libraries.

TCL Extension libraries: mxsaprfc85.dll

SAP libraries: icudt34.dll

icuin34.dll

icuuc34.dll

librfc32u.dll

libsapu16vc80.dll

libsapucum.dll

File Names and Settings for AIX (64-bit)

TCL Extension libraries: libmxsaprfc85.so

SAP libraries: librfcum.so

libsapu16.so

libsapu16_mt.so

libsapucum.so

File Names and Settings for Solaris (SPARC and x-86/64, 64-bit)


SAP libraries: libicudata.so.34

libicui18n.so.34

libicuuc.so.34

librfcum.so

libsapu16.so

libsapu16_mt.so

libsapucum.so

File Names and Settings for Linux (SuSe and Redhat, 64-bit)


SAP libraries: libicudata.so.34

libicui18n.so.34

libicuuc.so.34

librfcum.so


libsapu16.so

libsapu16_mt.so

libsapucum.so

Shared Library Destinations

Copy the TCL extension libraries from the installation package to the directory your

3DEXPERIENCE Platform server uses for binary files.

o On Windows platforms the correct location is the BIN_PATH given in the

enovia.install file of the server installation.

o On Unix and Linux platforms the correct location is the LIB_PATH given in the


Copy the TCL extension libraries from the installation package to the directory your

3DEXPERIENCE Platform administrative rich client uses for binary files.


enovia.install file of the rich client ("Studio") installation.



Copy the SAP libraries from the SAP RFC SDK package to the directory your

3DEXPERIENCE Platform server uses for binary files. This could be any directory in

the path list of the machine, but see our recommendation below.

Note that this step may not be necessary if a Unicode-enabled SAPGUI is already

installed on this machine.





Copy the SAP libraries from the SAP RFC SDK package to the directory your

3DEXPERIENCE Platform administrative rich client uses for binary files. This could

be any directory in the path list of the machine, but see our recommendation below.

Note that this step may not be necessary if a Unicode-enabled SAPGUI is already

installed on this machine. We strongly recommend that you install a SAPGUI on your

administrative rich client machine.





For UNIX installations please check the libraries to make sure that the access rights are correct, it

should be chmod=755.


Extending UNIX Environment Variables

For some UNIX systems you need to update your environment variables. You can do this in the start

scripts of the server and rich client applications.

On AIX systems it is necessary that the install paths of the libraries are included in the

LIBPATH environment variable.

On Solaris and Linux systems it is necessary that the install paths of the libraries are

included in the LD_LIBRARY_PATH environment variable.

Installing the Shared Libraries (SAP JCo)

This section describes how to install the libraries for the SAP JCo interface. If you do not plan to use

SAP JCo, please ignore this section.

To use SAP JCo, the parameter mxsapSetting(useJCO) in SAPSettings.tcl must be set to

"1" (see SAP Connection). The value of this setting during installation is relevant, because with value

"0" certain programs don’t get installed. If you later decide to utilize SAP JCo, modify the

corresponding parameter in the installer script and rerun the schema installation (see Running the

Schema Installation Program). Note that you may have to manually modify SAPSettings.tcl,

because the installer won’t overwrite this program if it already exists in the database.

The shared libraries are binary files that are specific to your operating system and that have different

names on different operating systems.

The SAP libraries must be provided by your SAP administrators. Please take care to get

the SAP libraries for the right operating system and for 32-bit or 64-bit operation, as

needed.

The SAP JCo libraries come as a ZIP package that must be unpacked in an arbitrary

installation directory. In this ZIP file you find a JAR library (sapjco*.jar), system-

specific shared libraries (sapjco* or libsapjco*), documentation and also a Readme file.

You do not need the TCL extension library (mxsaprfc) when using SAP JCo.

The libraries need to be installed on the 3DEXPERIENCE Platform server machine. You must also

install them on rich clients that you use for administrative work; we recommend to set up at least one

such rich client.

Shared Library Destinations

Unpack the ZIP file provided by SAP, recursively if necessary, until you are left with a plain folder;

place the folder content into an arbitrary directory of your machine (henceforth called <sapjco_path>).

Open the Readme file and follow the installation instructions.

You must make the SAP JPO library folder known to the operating system:

Add <sapjco_path> to the PATH environment variable, or, on UNIX systems, to

LIBPATH (AIX) or LD_LIBRARY_PATH (Solaris, Linux).

Add <sapjco_path> to the CLASSPATH environment variable.

Alternatively you can move the libraries from <sapjco_path> to folders that are already included in

PATH/LIBPATH/LD_LIBRARY_PATH resp. CLASSPATH.


For UNIX installations please check the libraries to make sure that the access rights are correct, it

should be chmod=755

Note that these path settings must be in effect in your target 3DEXPERIENCE Platform environments

(i.e. all server and rich client environments you plan to use).

Installing and Customizing the SAP Function Modules

You need to install these function modules only if you plan to transfer physical files into SAP. If you

only transfer URLs to the PLM file, or if you do not transfer documents at all, you may ignore this

step.

We provide the function modules together with a necessary customization in the X-BOM Connector

for SAP installation package in the form of a SAP Transport Order (SAP TO). The TO is delivered in

a folder named sap-transport. Give the contents of this folder and the information in this section

of the Admin Guide to your SAP counterpart to install and configure the function modules.

The SAP TO consists of two files. One is named K<6-digit-number>.IE5, the other R<6-

digit-number>.IE5. The first is a text file that holds information about the transport order, the

second is a binary file that holds the actual content. Please see the SAP documentation for details

about TO installation.

The new SAP Function Modules come with two custom parameters CHECKIN_PFAD and

CHECKOUT_PFAD. These parameters allow you to set the checkin and checkout path for the physical

files, i.e. a folder where these files are stored temporarily. By default they point to the working

directory of a SAP system that runs under Windows, i.e. .\

To change the setting, use SAP transaction /GBA/JCO_SYPARAM.

Enter any path that is convenient in a format understood by your SAP operating system. Note that the

last character of the path names must be a backslash (or slash, if on a UNIX system).

You must change the path if your SAP system runs under Unix because the default value only fits a

Windows system.


Running the Schema Installation Program

You can now proceed with the schema installation.

Open an MQL client and set the context of a user with administrative privileges (for

example "creator").

Switch to TCL mode by entering tcl; and change the working directory to the

directory where you unpacked the installation package. Navigate to the folder that

contains the file MxS-ERP-Install-Standard-EC-Integration.mql; this

folder will be named install.

Verify that you are in the correct directory by entering glob *; (this should return a

list of files, including MxS-ERP-Install-Standard-EC-Integration.mql).

Leave TCL mode by entering exit;

Run the installer file by entering run MxS-ERP-Install-Standard-EC-Integration.mql;

Note: On some systems you may have to enter the command with the full path name, like run /tmp/<mxsap>/install/MxS-ERP-Install-Standard-EC-

Integration.mql;

MQL seems to ignore the current directory on some platforms.

This will install the necessary schema and user interface elements. The changes will only be

committed to the database if no errors occurred; if you encounter errors, the error message will give

you information what went wrong. In that case correct the problem and try again. An "Installation

completed successfully" message indicates that the changes have been committed to the database.

Please see the Schema and GUI Reference section for a list of installed items.

Note that you may run the installer repeatedly without negative results. The programs

SAPSettings.tcl, SAPToplevel.tcl and SAPCustomerLib.tcl that are typically

adapted to your specific needs will never be overwritten by a subsequent installation. If you want to

re-install those programs as delivered you must delete them from the database first.

Checking and Updating Application Settings

SAP Connection

Parameter in SAPSettings.tcl: The following setting must fit your installation. If you followed the instructions given

above, it should be correct:

o If you want to use native SAP RFC (default): set mxsapSetting(useJCO) "0"

o If you want to use SAP JCo: set mxsapSetting(useJCO) "1"

After changing this setting you need to re-start the 3DEXPERIENCE server. For the

JCo Connection a rerun of the schema installation could be necessary (see Running the

Schema Installation Program).


Trace File Destination

You set the target directory for trace files with the setting set SAPConfig(mxsapDir) (see above,

in section Editing the Schema Installation Program). If you want to change that setting, you can do so

in two places:

Change in SAPSettings.tcl: Change the instruction

set mxsapSetting(MXSAPDIR) "c:/temp" or

set mxsapSetting(MXSAPDIR) "/tmp"

in the program object SAPSettings.tcl to a value of your choice. Note that TCL

syntax demands forward slashes for the path specification even on Windows systems.

Changing the MXSAPDIR Environment Variable:

o On Windows systems edit the file enovia.ini (make sure to apply this change to all

enovia.ini files, for rich client and the server installations, as needed). Check for a

section marked [MXSAP]

If such a section does not exist, create it. Then check for an entry like MXSAPDIR=c:\temp

and change it to a value of your choice. If such an entry does not exist (in a default

installation, it does not), create it. Note that the path specification must be in the system-

specific format (i.e. backslashes for Windows systems).

o On UNIX systems set and export the MXSAPDIR environment variable in the

application start scripts. This would be that startup scripts for the individual rich client

applications (matrix, mql, system, business) and the server startup environment file

mxEnv.sh.

Note that the setting via the environment variable overrides the setting in SAPSettings.tcl. This

may be convenient for testing purposes.

Switching Trace File Creation On/Off

You can switch trace file creation on or off. Open the program SAPSettings.tcl with the

3DEXPERIENCE Business application, look for the following setting and change it to the value

appropriate for your SAP environment:

set mxsapSetting(szDebug) 1

By default tracing is switched on (value=1), and we recommend to leave it on at least until testing is

completed. Set it to off (value=0) in productive environments if you are sure that no problems exist.

Usually it is best to leave tracing on because it gives the instant option to review any problems.

For more information about trace files please see the Troubleshooting section.

Date and Time Formats

You should check the date and time formats on your system against the settings on the SAP system.

Open the program SAPSettings.tcl with the 3DEXPERIENCE Business application and look

for these settings and change them to the values appropriate for your SAP environment:


set mxsapSetting(SAPDateFormat) "%m/%d/%Y"

set mxsapSetting(SAPDateTimeFormat) "%m/%d/%Y %H:%M:%S"

You will find comments near these settings that help you to choose the correct setting for your SAP

system. For European SAP systems the values should usually be changed to

set mxsapSetting(SAPDateFormat) "%d.%m.%Y"

set mxsapSetting(SAPDateTimeFormat) "%d.%m.%Y %H:%M:%S"

Please check also that the date format preference for the SAP user is set to the same format.

Next, look for the following settings and change them to the values appropriate for your

3DEXPERIENCE environment:

set mxsapSetting(DateFormatType) US

set mxsapSetting(DateFormatSep) "/"

For European 3DEXPERIENCE systems the values should usually be changed to

set mxsapSetting(DateFormatType) EUROPE

set mxsapSetting(DateFormatSep) "."

Please note that the first set of values must fit the SAP system and the second set of values must fit the

3DEXPERIENCE system. If the settings in SAP and 3DEXPERIENCE are incompatible it may be

necessary to change the date conversion algorithm.

3DEXPERIENCE Decimal Separator

You should check the decimal separator format setting against the setting in the 3DEXPERIENCE

system. Open the program SAPSettings.tcl with the 3DEXPERIENCE Business application and

look for this setting and change it to the values appropriate for your environment:

set mxsapSetting(MatrixDecimalSep) "."

You will find comments near the settings that help you to choose the correct setting for your

3DEXPERIENCE system. The 3DEXPERIENCE settings are defined in the enovia.ini file

(Windows) or the application start scripts (UNIX).

Please note that the values must fit the 3DEXPERIENCE system, not the SAP system.

Declaring Which Change Objects to Enable for Transfer

As explained in Support of Current Change Object Types, you can choose whether to use Change

Order objects (CO) or Change Action objects (CA) to initiate transfers to SAP. By default, COs and

the legacy ECO objects will be supported.

If you stayed with the default setting, i.e. decided to use COs and to support legacy

ECOs, you do not need to change anything in SAPSettings.tcl

If you decided to use CAs, you must edit SAPSettings.tcl by un-commenting one

block of code and commenting another one. Find the section titled Support of different

types of 3DEXPERIENCE change objects. In this section you find four blocks of code

for the different possible options. Find the block you need from the block descriptions

and un-comment this block. Comment the other three blocks out. Edit the active Block

if necessary.


Installing the Web User Interface

In the installation package, find the directory webgui.

Copy the included sap directory to the directory defined as STAGING_PATH in the

enovia.install file.

In webgui, find the directory named properties. Copy all files with the

.properties extension to

STAGING_PATH/properties

Find the file webgui/properties/emxSystem.properties_addendum.txt

and open it in a text editor. Now find the file STAGING_PATH/properties/emxsystem.properties

and open it in a text editor.

Paste the following block from emxSystem.properties_addendum.txt to the

end of emxsystem.properties:

# Begin of MxSAP-Integration

eServiceSuiteMxSAP.URL = common/emxNavigator.jsp

eServiceSuiteMxSAP.Directory = sap

eServiceSuiteMxSAP.StringResourceFileId =

gdMxSAPStringResource

eServiceSuiteMxSAP.ApplicationPropertyFile =

gdMxSAPStringResource.properties

eServiceSuiteMxSAP.PropertyFileAlias =

gdMxSAPStringResource.properties

# End of MxSAP-Integration

Then paste the line eServiceSuiteMxSAP, \

as an additional line into the list of applications that define the eServiceSuites.DisplayedSuites

property.

Note: The syntax above assumes that you include the line in the middle of the property

definition, not as the last line. Look up the property definition syntax when in doubt.

The next step is to copy the help files to their proper location. In the installation

package, find the directory doc. Open it and copy the sap directory you find there to

the STAGING_PATH/doc directory.

Now save emxsystem.properties and run the war_setup application (formerly

known as warutil) to re-build the web application, then stop the web application server

and deploy the web application. Finally, re-start the web application server. See the

3DEXPERIENCE documentation for details about this step.

You are now done with the basic installation. Please proceed with the section Completing the

Installation.


Completing the Installation

To complete your installation you need to test the connection to the SAP system and to download the

SAP RFC structure information to the 3DEXPERIENCE Platform system. We recommend to do the

testing and to complete the set-up in the following steps:

Open the 3DEXPERIENCE rich client Navigator, log in as an administrative user, find

the business object "SAP Schema Map" "SAP Mapper" and execute the SAP Ping

method on this object.

If you get a message saying "Communication with SAP ... via RFCPING: OK" you

know that the communication between 3DEXPERIENCE and SAP works.

If you get an error message please note the error message and look up the

Troubleshooting section of this guide to fix the problem.

On the same object, execute the SAP Download Structures method. This will create a

3DEXPERIENCE program object named SAPStructures.tcl in your database. It

holds information about the RFC structures used by your SAP system.

If you get an error message please note the error message and look up the


On the same object, execute the SAP System Info method. This should show a window

with detailed information about your SAP system. It will also warn you if certain

settings (like date/time) are different in SAP from the settings you made during the

installation. If you get such warnings you need to correct the situation before

proceeding. See the Configuration Options section, above, about how to set up format

information.

Open the 3DEXPERIENCE web client. Log in as an administrative user and go to the

Utility menu in the My Apps menu.

Use Sap Info. If you see something like the following window, all is well:


If the SAP Info menu is not present, please check whether you re-started the web application server.

If the problem persists or if the result window does not open as described please see the


You are now ready to do a quick test of X-BOM Connector for SAP with real data. We recommend

that you perform the following tests, in the order given:

Find a Part object that has no documents attached and use Create SAP Material. Use

the SAP Material Details tab or the SAPGUI to check whether the material master has

been created in SAP.

Attach a Drawing Print to the Part and repeat the transfer. Use the SAPGUI to find the

material master, navigate to the document view and check the entry for document

originals. Use SAP's View function to view the file.

Add more Part objects to your Part, making it an assembly. Use Create SAP BOM in

check mode to transfer the parts belonging to the BOM (the BOM itself is not

transferred in check mode). Then use Create SAP BOM in transfer mode to transfer the

BOM; use the Display SAP BOM tab to view the transfer result.

Use Compare SAP BOM to compare both BOMs. They should be identical.

Create a CO to revise the assembly. Set the Valid From date of the CO to some date in

the future. Change the 3DEXPERIENCE BOM by adding or removing components and

changing quantities. Change some part attributes and check new files into the

specifications.

Promote all CAs that have been created to In Work.

Transfer the CO, using the Create SAP CO action. (This will only transfer the CO

itself, not the attached items.) Use Transfer to SAP from CO to transfer the CO and all

affected items.

View the SAP change master, materials, documents and BOM. Check whether all

changes have been transferred as expected.


Go to Compare SAP BOM again. If you compare the BOM of 3DEXPERIENCE part

revision 2 and the SAP BOM as it is valid today, you should get a list of difference; if

you compare it with the SAP BOM again, but with a date that is equal to the CO's Valid

From date, you should see identical BOMs again. This test shows whether the setting of

SAP's effectivity date from the CO's Valid From date works correctly.

While this is not an exhaustive test scenario, it uses most of the installed transfer routines and gives a

good indication whether there are problems in the set-up. If the tests described above work you may

proceed with tests according to your test plan. For example, additional tests may be required if you

want to use 3DEXPERIENCE MBOM-related functions.

Typical Post-Installation Tasks

Setting Up Additional Rich Client Installations

Note that rich clients are nowadays almost exclusively used for administrative purposes; Dassault

Systèmes recommends that you do not make the rich clients available to non-administrative users.

For each rich client installation you need to make the TCL extension libraries and the SAP libraries if

you plan to use native SAP RFC, and/or the SAP JCo libraries if you plan to use SAP JCo, available

to the client system. Follow the steps given in Installing the Shared Libraries for the client/studio

installation.

Modifying Your Installation

When the installation and initial testing are complete you typically want to extend functionality,

switch to other SAP systems or modify other settings. The sections Configuration Options and

Customization Options describe such tasks in detail. Typical tasks are:

Change SAP connection interface: see section Configuring the SAP Connection

Change SAP user or password: see section Configuring the SAP Connection

Change SAP system ID: see section Changing the SAP System ID

Decide which types of change objects shall be transferred: see section Settings Related

to Engineering Change Objects

Modify the plant and BOM usage option lists: see section Configuring Attribute Ranges

Extend the help system: see section Extending the Help System

Un-Installing X-BOM Connector for SAP

With the installation package you get an auxiliary program:

MxS-ERP-Uninstall-Standard-EC-Integration.mql

This program removes the installation from your 3DEXPERIENCE Platform database,

including those TCL libraries that are used for customer-specific customization. It does

not remove the web GUI components and the shared libraries.

The tool is delivered in the same folder as the installation program.


Please be aware that this tool may cause damage to your 3DEXPERIENCE installation if not used

properly, for example if your installation was customized without completely following the

customization guidelines or if the uninstaller version does not match your installation version.

Please note also that the uninstaller also removes all TCL programs you have customized!

The footprint of X-BOM Connector for SAP is minimal, and the application does not consume

resources as long as it is not used; therefore de-activating may be a good alternative to uninstalling it.

De-activating follows normal 3DEXPERIENCE procedures; it is enough to deny interactive users

access to the commands of X-BOM Connector for SAP and to de-activate any triggers you may have

activated.


Schema and GUI Reference

This section describes the schema (data model) elements X-BOM Connector for SAP adds to

3DEXPERIENCE Platform and the user interface elements it adds to the database and to the web

application. It also describes the business objects created during installation.

In this section:

Schema Extension

GUI Extension

Other 3DEXPERIENCE Platform Elements

Schema Extension

Types

X-BOM Connector for SAP adds the following types to the 3DEXPERIENCE Platform Schema

during the installation:

Name Description

SAPSYSTEM Abstract parent type for the types described below

SAP Defaults Used to collect certain default values for the transfer

to SAP. One instance will be created during the

installation.

SAP Schema Map Used to provide information about the destination

SAP system and to provide some methods used for

installation and troubleshooting. One instance will be

created during the installation.

Attributes

3DEXPERIENCE Platform adds the following attributes to the 3DEXPERIENCE Platform schema



Name Type Description

SAP Default Values string

multi-

line

Attribute of type SAP Defaults. Holds default values

for SAP fields that are used when no other value is

assigned by the transfer rules.

SAP Destination string Attribute of type SAP Schema Map. Holds the SAP

system ID (3-character string).

SAPRangesPlant string Stores the possible values for SAP plant ID. Is not

attached to any type.

SAPRangesRelation string Stores the names of relations to be considered for

EBOM explosion. Is not attached to any type.

SAPRangesUsage string Stores the possible values for SAP BOM usage. Is not

attached to any type.

SAP Valid From string This attribute will be added to all types listed for the

SAPConfig(ECOTypes) variable. It is used to set SAP

effectivity dates.

Policies

3DEXPERIENCE Platform adds the following policies to the 3DEXPERIENCE Platform schema


Name Description

SAP Interface A very basic policy that we use for all types defined

by X-BOM Connector for SAP. The access rights

assume that only administrative users have access to

the rich client, otherwise they should be changed to

be more restrictive.

Programs: Customer-Adaptable TCL Libraries

3DEXPERIENCE Platform adds the following programs (TCL libraries) to the 3DEXPERIENCE

Platform schema during the installation. These libraries are meant to be adapted for the customer

environment. Once installed in the database they will not be updated with subsequent installation runs.

Name Description

SAPCustomerLib.tcl Provides many procedures to perform functions that

are expected to need customizing, for example SAP

connection information. Many procedures serve as

"hooks" to implement extended logic if desired.

SAPSettings.tcl Provides configuration options and basic attribute and

type mappings.


Name Description

SAPToplevel.tcl Procedures in this library provide entry points and

delegate the actual work to other library procedures.

SAPCustomerMessages-DE.txt

SAPCustomerMessages-EN.txt

SAPCustomerMessages-FR.txt

SAPCustomerMessages-IT.txt

SAPCustomerMessages-JA.txt

SAPCustomerMessages-ZH.txt

Pseudo-program files to provide language-specific

texts for error messages, rich client GUI etc.

Use these programs to override standard messages

with your own, or to extend the existing set of

messages.

Programs: Standard TCL Programs and Libraries

The following programs and TCL procedure libraries are added to the 3DEXPERIENCE Platform

Schema during the installation. These libraries should never be changed by the customer; they may be

overwritten with subsequent installation runs. See the section How to Change Core Procedures for

information about how to change procedures defined in these libraries.

Name Description

SAPUniversalTrigger

SAPUniversalUpdateJPO

SAPUniversalUpdateJSP

These are the unified entry points to the TCL call

structure used by X-BOM Connector for SAP. They

differ mainly in the way parameters are passed to the

following modules.

SAPAppsLib.tcl

SAPBAPILib.tcl

SAPBom.tcl

SAPBomCompare.RFC.tcl

SAPBomRFC.tcl

SAPClassLib.tcl

SAPDocLib.tcl

SAPECNLib.tcl

SAPHexLib.tcl

SAPLib.tcl

SAPLoader.tcl

SAPMatLib.tcl

SAPMessages.tcl

SAPPMLib.tcl

SAPRFCLib.tcl

SAPVendor.tcl

SAPWorkflow.tcl

These are libraries that provide TCL procedures to be

used as delivered, grouped into separate programs by

their function.


Name Description

SAPToolsJPO

SAPRangesJPO

A collection of methods used for BOM-related

operations, in particular to select BOM filters and to

display BOM results in the web GUI.

SAPJCOLib.tcl

SAPJCoJPO

SAPDestinationDataProviderJPO

Programs to provide the JCo connection functionality

SAPMessages.tcl Library for message-related procedures

SAPMessages-DE.txt

SAPMessages-EN.txt

SAPMessages-FR.txt

SAPMessages-IT.txt

SAPMessages-JA.txt

SAPMessages-ZH.txt

Pseudo-program files to provide language-specific

texts for error messages, rich client GUI etc.

Programs: Methods and Wizards

The following programs are added to the 3DEXPERIENCE Platform Schema during the installation.

Some of these programs are obsolete because non-administrative users no longer should have access

to rich client functions. Some of these programs provide administrative functions.

Name Description

SAP Download Structures

SAP PING

SAP System Info

SAP TEST LIBRARY LOAD

Methods on the "SAP Schema Map" type, for admin

purposes only

SAP Push Material

SAP Push BOM

SAP Show Attributes

Methods on all Part types (as defined by the variable

SAPConfig(PartTypes) in the installation

program)

SAP Wz BOM Tool (RFC) Rich client wizard on all Part types (as defined by the

variable SAPConfig(PartTypes) in the

installation program)

SAP Push Document

SAP Show Attributes

Methods on all Document types (as defined by the

variable SAPConfig(DocumentTypes) in the

installation program)

SAP Push Change Order

SAP Push From Change Order

SAP Show Attributes

Methods on all ECO types (as defined by the variable

SAPConfig(ECOTypes) in the installation

program)


Name Description

SAP BOM Cost Rollup

SAP BOM Tool

SAP Bulk Transfer

SAP Check Transfers ECN

SAP Display Classification

SAP Document Checkin

SAP Document Checkout

SAP Issue Material Number

SAP Push Maintenance

Notification

SAP Push PM Object

These programs are delivered as method templates

and are not used in the out-of-the-box installation.

You may use them as examples of the X-BOM

Connector for SAP call structure.

SAPWzBomProlog

SAPWzDoCompareBom

SAPWzGetValueList.tcl

SAPWzListEntryCheck

SAPWzLoadChoices

SAPWzLoadCompareResult

SAPWzLoadResultList

SAPWzSaveButton

SAPWzSetGetBom

These programs are part of an obsolete wizard and

are only delivered for compatibility purposes.

Programs: Triggers

The following trigger programs are added to the 3DEXPERIENCE Platform Schema during the

installation:

Name Description

SAP Trigger Push Change

Order

SAP Trigger Push From Change

Order

SAP Trigger Push Material

These programs are delivered as trigger program

templates and are not used in the out-of-the-box

trigger templates (see Configuring Event Triggers).

You may still use them as examples of the X-BOM

Connector for SAP call structure.

GUI Extension

Common Component GUI Extensions

The following common component elements are added to the 3DEXPERIENCE Platform Schema



Name Type Description

SAPDocumentActions command The command added to the category

menus defined in the

SAPConfig(DocumentMenu)

variable of the installation script.

SAPECOActions command The command added to the category


SAPConfig(ECOMenu) variable of

the installation script (usually, the

type_ECO tree).

SAPCOActions command The command added to the category


SAPConfig(ChangeOrderMenu)

variable of the installation script

(usually, the type_ChangeOrder

tree).

SAPCAActions command The command added to the category


SAPConfig(ChangeActionMenu)

variable of the installation script

(usually, the type_ChangeAction

tree).

SAPMCOActions command The command added to the category


SAPConfig(MCOMenu) variable of

the installation script (usually, the

type_MCO tree).

SAPPartActions command The command added to the category


SAPConfig(PartMenu) variable of

the installation script.


SAPBomTool

SAPCompareMBOMFromMCO

SAPDocumentCheckin

SAPDocumentCheckout

SAPIssueMaterialNumber

SAPPushBom

SAPPushChangeOrder

SAPPushDocument

SAPPushFromChangeOrder

SAPPushFromMCO

SAPPushMaterial

SAPPushMaterialFromMBOM

SAPShowAttributes

SAPShowAttributesPlant

SAPSystemInfo

command These commands are used in the

action bar menus.

SAPCompareBOM

SAPDisplayBOM

SAPMaterialDetails

SAPMxPartDetails

command These commands are used as tabs in

the channels used in the PowerView

pages.

SAPBOMPlantFilter

SAPBOMUsageFilter

SAPBOMValidFromFilter

SAPBOMRecursionLevelFilter

SAPShowBOMFilterButton

SAPCompareBOMFilterButton

command These commands work as filters and

filter buttons for BOM view and

compare functions

SAPDocumentToolBar

SAPECOToolBar

SAPCOToolBar

SAPCAToolBar

SAPMCOActionsToolBar

SAPMCOToolBar

SAPPartToolBar

menu These are the toolbars for the

PowerView pages.

SAPDocumentActionsToolBar

SAPECOActionsToolBar

SAPCOActionsToolBar

SAPCAActionsToolBar

SAPPartActionsToolBar

menu These are the drop-down action

menus used in the above toolbars.

SAPShowBOMInputToolBar

SAPCompareBOMInputToolBar

menu These toolbars hold filters for BOM

display and compare functions.


SAPCompareMBOM

SAPDisplayBOM

table Display the results for BOM view

and compare operations

SAPMCOPortal

SAPPartPortal

portal These are portals used on the

PowerView pages.

SAPBOMDetailsView

SAPDetailsView

SAPMCOPartRevsView

SAPMCOMBOMView

channel These are the channels used in the

portals described above.

The schema installation changes or extends the following standard GUI elements:

AdminTools menu: Add command SAPSystemInfo

ENCBOMActionsToolBar menu: Add commands SAPBomTool, SAPPushBom,

SAPPushMaterial, SAPShowAttributesPlant

Tree menus specified in SAPConfig(DocumentMenu), SAPConfig(ECOMenu),

SAPConfig(ChangeOrderMenu), SAPConfig(ChangeActionMenu),

SAPConfig(MCOMenu) and SAPConfig(PartMenu) variables of the installation script:

Add one command each to show MxSAP page.

Web Application Extensions: JSP Files

X-BOM Connector for SAP comes with the following Java server pages (JSPs) to extend the user

interface of the 3DEXPERIENCE Platform web application:

emxAppBottomPageInclude.jsp

emxAppTopPageInclude.jsp

gdSAPBOMToolStart.jsp

gdSAPBOMToolStartFS.jsp

gdSAPHelp.jsp

gdSAPPowerView.jsp

gdSAPPowerViewBOMInput.jsp

gdSAPPowerViewSelectPlant.jsp

gdSAPPushBOMStart.jsp

gdSAPPushBOMStartFS.jsp

gdSAPSelectPlant.jsp

gdSAPSelectPlantFS.jsp

gdSAPStylesAllMedia.css

gdSAPUniversal.jsp

gdSAPUniversalFS.jsp

gdSAPUtil.jsp

SAPCheckout.jsp

SAPError.jsp

SAPLogin.jsp

Some pages are only delivered for backward compatibility. Pages whose names begin with "SAP" are

only templates to show how the user interface can be extended to meet your requirements.


Web Application Extensions: Property Files

X-BOM Connector for SAP needs the following property files to work:

String resource property files for JSPs (see Installing the Web User Interface)

An addition to the emxSystem.properties file to register the MxSAP application

suite and to set suite-specific properties (see Installing the Web User Interface)

Web Application Extensions: Help Files

X-BOM Connector for SAP comes with a placeholder help file (ENOHelp.htm) that shows an

abbreviated version of the X-BOM Connector for SAP User's Guide and has a link to the complete

PDF guides. See the section Extending the Help System for information about adapting the help

system to your needs.

Other 3DEXPERIENCE Platform Elements

During the installation the following business objects are created and added to the database:

type "SAP Defaults", name "MATERIAL", no revision

Provides defaults for SAP material creation.

type "SAP Schema Map", name "SAP Mapper", no revision

Provides a SAP destination, that is the ID of the SAP system to use and provides

methods used during installation and testing.

This object may also have the SAPRFC.INI file checked in; this file is normally

obsolete now and is only delivered for compatibility with older SAP versions that did

not have the BAPI interface. (However, you may still use SAPRFC.ini to switch SAP

tracing on, see SAP RFC Trace for details.)

type "eService Trigger Program Parameters", 5 business objects:

name "PolicyDrawingPrintStateApprovedPromoteAction"

revision "SAPCreateDocinfoRecordExample"

name "PolicyECPartStateApprovedPromoteAction"

revision "SAPCreateMaterialMasterExample"

name "PolicyECOStateReviewPromoteAction"

revision "SAPTransferECOExample"

name "PolicyFormalChangeStateInApprovalPromoteAction"

revision "SAPTransferCOExample"

name "PolicyMCOStandardStateReviewPromoteAction"

revision "SAPTransferManufacturingChangeMasterExample"

These objects provide examples of how to implement event-triggered operation (see

Configuring Event Triggers for details). After the initial installation they are in

Inactive state, they do not affect business processes at all until activated.


Dynamic Libraries Reference

This section describes the dynamic libraries X-BOM Connector for SAP uses to connect to SAP.

This information is for reference purposes only, usually you do not need to work directly with

these libraries.

This section refers to native RFC connections only; SAP JCo connections do not use the

mxsaprfc dynamic library.

In this section:

Overview

Loading the Libraries

Accessing SAP Through the mxsaprfc Command

Overview

If used in native RFC connection mode, X-BOM Connector for SAP uses a shared library to extend

the functionality of the 3DEXPERIENCE TCL interpreter. This is already described in the

Conceptual Notes section of this manual and in the Place in Product Development Process and

Application Architecture section, while the Dynamic Libraries section there provides some details

about the libraries already.

For details about the library installation, including instructions about the required SAP library, please

refer to the Installing the Shared Libraries section in the installation guide. The SAP libraries are not

described here as they are not part of this software product.

Loading the Libraries

With the installation package you get one or more mxsaprfc* libraries. If more than one

mxsaprfc* library is in the package please install all; X-BOM Connector for SAP will load the

correct library for your system automatically when any function of X-BOM Connector for SAP needs

them. No configuration is required.

You can test-load the libraries by executing the program SAP TEST LIBRARY LOAD. For details

please see the section Library Load Test in the Troubleshooting section of this manual.

In native RFC connection mode, the mxsaprc function becomes available as a TCL command when

the library was loaded. In SAP JCo mode the mxsaprc function is implemented as a TCL procedure.


Accessing SAP Through the mxsaprfc Command

The mxsaprc function allows you to connect to a SAP system and to access any SAP function that is

RFC-enabled. To see whether a certain SAP function is RFC-enabled, open a SAPGUI client and use

the Function Builder (SE37) transaction to check the function settings.

The standard X-BOM Connector for SAP functions use mxsaprfc calls, but you can also use

mxsaprfc in your own code to create extensions of the standard functions. The RFC function you

want to use is one of the parameters of the mxsaprfc call.

For a complete reference of the mxsaprfc command and for coding examples please see the section

Extended customizing: The mxsaprfc TCL Command.


Configuration Options

This section describes several options you have to configure your installation. For information

about further customization that requires programming please see the Customization Options

section.

In this section:

Configuring the SAP Connection

Configuring Date and Decimal Separator Formats

Configuring Attribute Ranges

Configuring Attribute Mapping

Configuring Basic Attribute Value Conversion

Configuring Event Triggers

Configuring the SAP Connection

This section describes how to change the SAP connection settings, including the SAP username and

password. All connection parameters will be determined in separate TCL procedures, all of which

depend on the SAP system ID:

SAP User Name and Password Edit SAPCustomerLib.tcl::gdGetSAPPwd to set the correct user name depending on the

SAP system ID. Edit SAPCustomerLib.tcl::gdGetSAPUser to set the correct user

password depending on the SAP system ID.

SAP Client Edit SAPCustomerLib.tcl::gdGetSAPClient to set the correct SAP client number (a 3-

digit number) depending on the SAP system ID.

SAP Host and System Number Edit SAPCustomerLib.tcl::gdGetMxSAPRFCConnect to set the correct SAP host (name

or IP address) and system number (a 2-digit number) depending on the SAP system ID.

After the installation these procedures contain exemplary code that shows how to adapt them later.

You need to be familiar with the TCL switch command to edit these procedures.

Changing the SAP System ID

If you need to change the SAP system ID itself you need to know how the connection settings are

derived in different cases.


In SAPSettings.tcl there is a variable mxsapSetting(SAPDestination) that is

evaluated in SAPToplevel.tcl::gdUniversalMethod and that can take one of two possible

values:

FIX: Means that there is only one SAP system to connect to and that the general

settings in SAPStructures.tcl will be used. The SAP system ID will be taken

from the attribute SAP Destination of the business object "SAP Schema Map" "SAP

Mapper".

VAR: Means that the SAP system ID will be determined algorithmically at runtime by

adapting

SAPCustomerLib.tcl::gdCustomerDetermineSapDestination. This

enables automatic loading of the SAP structures belonging to that SAP system.

Note that at any time only one SAP connection is handled, though the connection libraries would

allow to handle several connections in parallel. This implies that even with the VAR setting each

transfer to one SAP system must be finished before the transfer to another SAP system can begin.

"Parallel" transfer would require control structures that loop through multiple transfer processes to

one SAP system at a time and perhaps apply different data conversions per each destination system;

such control structures are not part of the standard system.

If you need to connect to multiple SAP systems, change

SAPSettings.tcl::mxsapSetting(SAPDestination) to VAR and to edit

SAPCustomerLib.tcl::gdCustomerDetermineSapDestination to

establish a system selection algorithm. The actual connection parameters must then be

coded into a couple of procedures in SAPCustomerLib.tcl that return the SAP user name

and password and other connection parameters.

If you want to connect to only one SAP system set

SAPSettings.tcl::mxsapSetting(SAPDestination) to FIX and set the

SAP system ID by changing the attribute SAP Destination of the business object

"SAP Schema Map" "SAP Mapper".

All changes described here become effective immediately, there is no need to restart anything.

Choosing the SAP Connection Interface

Your options are

Native SAP RFC, using the C interface libraries (librfc*)

SAP JCo, using the Java connection libraries (sapjco*)

Note that each option requires that certain SAP libraries are installed on your system, otherwise

transactions will fail. Please look up the section Installing X-BOM Connector for SAP and check that

all required libraries are in place before changing the connection interface setting.

In SAPSettings.tcl there is a variable mxsapSetting(useJCO) that is evaluated when

initiating a transfer and that can take one of two possible values:

set SAPConfig(useJCO) "0"

Connect through native SAP RFC, using the TCL extension mxsaprfc and the SAP C

libraries. This is the default value.


set SAPConfig(useJCO) "1"

Connect through SAP JCo, using the SAP Java libraries. This connection method

became available with ENOVIA V6R2013x and cannot be used for earlier releases.

If you need to go deeper into customizing, you find the relevant code in the program

SAPRFCLib.tcl, in the procedure gdLoadMxSAPRFC.

You must restart the 3DEXPERIENCE Platform server after switching between connection RFC and

SAP JCo.

SAP User Capabilities

The SAP users you configure to access SAP through RFC must be enabled to use RFC connections;

he must, of course, also be enabled to use the necessary transactions like creating/modifying material

etc. You also have to decide whether this user shall be a system user or a dialog user. We recommend

having a dialog user for testing and a system user for productive work, for the following reasons:

System users can not log into the SAPGUI client. This lessens the risk if someone learns

the SAP username and password you use for X-BOM Connector for SAP. The system

user's password does not expire, which is convenient for productive use.

Only dialog users can access SAP interactively, and only dialog users can run the ABAP

debugger, which makes dialog users well suited for testing.

Please contact your SAP counterpart to decide on the necessary privileges for the SAP users you need.

Configuring Date and Decimal Separator Formats

Different SAP APIs behave differently when it comes to date formatting. Some interfaces, in

particular the ones available for handling BOMs, expect date and time to be submitted in the default

time format set for the SAP user who connected to SAP. 3DEXPERIENCE also has date and time

settings to consider, and in TCL there is no date format at all, because all TCL variables are strings

and only hold a string that resembles a date for the human user. Similar problems exist with the

representation of decimal numbers, as the setting for the decimal separator typically is a point in the

USA and a comma in most European states. To compound the problem, the default settings of

3DEXPERIENCE are the US formats, while SAP's are European.

X-BOM Connector for SAP has built-in logic to handle some cases automatically, but it cannot

resolve all conflicts. Therefore you should take care to harmonize the environments by setting certain

configuration variables.

Note that the date and decimal point format displayed to the user of the 3DEXPERIENCE web

environment may be different from the format used in the 3DEXPERIENCE RPE.

Here are the rules to avoid date and time format conflicts:

In SAPSettings.tcl there are 4 variables to set date and time formats. All of them

are explained in the program, and exemplary settings are given.

o mxsapSetting(SAPDateFormat) and

mxsapSetting(SAPDateTimeFormat) must be set to the date and time formats

defined as the SAP user's default formats.

If the SAP user is a dialog user, you can check these defaults from the SAPGUI,


otherwise you need to ask your SAP administrator. In the SAPGUI, use the menu

System-User Profile-Own Data and look at the Defaults tab.

o mxsapSetting(DateFormatType) and mxsapSetting(DateFormatSep)

must correspond to the setting for the 3DEXPERIENCE environment that is normally

defined by the variable MX_NORMAL_DATE_FORMAT in enovia.ini or in the

application start script.

Note: enovia.ini is a file that replaces MATRIX.INI and EMATRIX.INI from

3DEXPERIENCE Platform version V6R2010x on. See the 3DEXPERIENCE Platform

Installation Guide for details.

If no setting is defined in SAPSettings.tcl X-BOM Connector for SAP will try to

find the settings from the 3DEXPERIENCE environment, but this may not always give

the desired results because this environment can be set up in many different ways.

In SAPSettings.tcl there is one variable to set the decimal separator format.

o mxsapSetting(MatrixDecimalSep must be set to the decimal separator format

defined for TCL. The 3DEXPERIENCE setting is normally defined by the variables

MX_DECIMAL_SYMBOL and MX_TCL_ANSI_NUMERIC in enovia.ini or in the

application start script.




Recommendation: In our experience, most 3DEXPERIENCE installations work best when the date

used in the RPE is set to US format (like 06/25/2009 for June 25th

, 2009), the decimal separator is set

to "." (point), and MX_TCL_ANSI_NUMERIC=TRUE.

Please refer to the 3DEXPERIENCE Platform documentation about the settings and variables for the

3DEXPERIENCE environment.

Configuring Attribute Ranges

There are three 3DEXPERIENCE attributes that define values for drop-down lists for the web user

interface. These attributes are created when installing X-BOM Connector for SAP; they are not

attached to any business objects and are never directly visible in the user interface, only their range

and default value definitions are used.

SAPRangesUsage

Defines the BOM Usage drop-down list for the BOM Tool user interface. Note that it

does not set the SAP usage attribute for BOM transfers to SAP, as this is coded into the

TCL procedure gdTopDetailBom in SAPToplevel.tcl.

SAPRangesRelation

Defines the possible values for BOM relations on the 3DEXPERIENCE side for BOM

transfers from SAP to 3DEXPERIENCE. Note that it is not used for normal BOM

transfers from 3DEXPERIENCE to SAP, in this case the relations that must be

considered are defined by mxsapSetting(mxbomRel) in SAPSettings.tcl.

SAPRangesPlant

Defines the possible values for SAP plant dropdown lists that show up in the user

interface of several X-BOM Connector for SAP functions.

To change the value lists, edit the ranges of the attributes through the 3DEXPERIENCE Business

application. You may change the displayed values of the lists (i.e. as they show up in the web GUI) by


editing the corresponding properties in the string resource files (file names

gdMxSAPStringResource*, entries emxFramework.Range.*); this is the normal translation

feature used by 3DEXPERIENCE Platform. This feature is also used for internationalization of GUI

and range lists (see also section Notes on Internationalization (i18n)). The out-of-the-box translations

for range values correspond to standard SAP settings.

The default values of the drop-down lists are the default values of the attributes.

Configuring Attribute Mapping

Attribute mapping describes which 3DEXPERIENCE attribute is the equivalent of which SAP field.

There are two places where mapping is done:

Configure static mapping and simple conversions in SAPSettings.tcl

Configure more complex mapping in the procedures of SAPCustomerLib.tcl. See

Customization Options for details about complex mapping.

We do not describe all configuration options of SAPSettings.tcl in this document, as some of

them are obsolete and only kept for compatibility purposes. Do not use any undocumented settings

unless advised to do so.

Default Values in "SAP Default Values" Attribute

The business object "SAP Defaults" "MATERIAL" has an attribute "SAP Default Values" that you

can use to assign constant values to SAP fields. The main use of this mechanism is to provide values

for fields that are mandatory in SAP, but have no 3DEXPERIENCE counterpart.

We use these settings only during creation of a new material master in SAP, we will not

use them for material updates or for the transfer of other SAP object types.

They will always assign the same, constant value; you cannot define any algorithmic

setting here.

They will provide values for SAP fields that have no corresponding 3DEXPERIENCE

field (in other words, fields that are not mapped to a 3DEXPERIENCE attribute).

They will also provide a default value if the SAP field is mapped to a 3DEXPERIENCE

attribute and that attribute is empty (has no value assigned in 3DEXPERIENCE).

To use the default value option you need to edit the SAP Default Values attribute. We provide

exemplary code for the values. The following lines are examples only:

HEADDATA-MATL_TYPE FERT # Material Type

The MATL_TYPE field of the HEADDATA transfer parameter is set to FERT (SAP's

code for a manufactured part) for all new material masters.

The hash sign (#) is the TCL comment character, we ignore the sign itself and all

remaining text of that line.

HEADDATA-BASIC_VIEW X # Basic Data

The BASIC_VIEW field of the HEADDATA transfer parameter is set to X (SAP's code

for a "checkmarking" the field, meaning that the basic view shall be created for all new

material masters).


CLIENTDATA-MATL_GROUP 01 # Material Group

The MATL_GROUP field of the CLIENTDATA transfer parameter is set to 01

(meaning that the material group 01 is assigned to all new material masters by default).

Note that the transfer will fail if the field or parameter names are wrong or if the assigned value

contradicts the values allowed in your SAP system.

Please use the default value mechanism only within the limits described above. We recommend to put

the business logic into other modules like SAPSettings.tcl and SAPCustomerLib.tcl.

It is possible to define multiple SAP Defaults objects that apply for specific plants or specific material

types only, in effect creating a hierarchy of mapping objects in which a more specific object always

overrides a more general one. The easiest way to create them is to clone the object provided with the

standard installation, using the naming schema

MATERIAL_<MAT_TYPE>

MATERIAL_<SAP_PLANT_ID>

MATERIAL_<MAT_TYPE>_<SAP_PLANT_ID>

for the object name, as appropriate.

Mapping and Configuration Settings in SAPSettings.tcl

Here you can define direct mappings (attribute value is transferred unchanged from 3DEXPERIENCE

attribute to SAP field) and simple conversions like cutting off attribute values after a certain character.

Note that only a few of the conversions described here are applicable in both transfer directions.

Note: You need to enter SAP field names according to SAP API conventions. This means that for

fields transferred through BAPI functions you need to use the full name of the field, including the

name of the transfer parameter. This means that the names will look somewhat like CLIENTDATA-

NET_WEIGHT (CLIENTDATA being the BAPI function parameter that is used to send the SAP

structure to which the NET_WEIGHT field belongs), while for other interfaces the field name alone is

sufficient. Generally, BOM functions use the short, fieldname-only form while most other functions

use the longer form. To find out details about SAP parameters, structures and fields SAP provides the

transaction SE37; please contact your SAP administrator if this is not familiar to you.

Mappings are defined in the following format: set mxsapSetting(SAP_FIELD) ENOVIA_ATTRIBUTE

,for example set mxsapSetting(CLIENTDATA-BASE_UOM) "Unit of Measure"

defines that the 3DEXPERIENCE attribute "Unit of Measure" shall be transferred to the

SAP field "BASE_UOM", with "BASE_UOM" belonging to a SAP structure that is

transferred in the CLIENTDATA parameter of the BAPI function.

We provide a large number of dummy entries for often-used SAP fields in

SAPSettings.tcl. If no 3DEXPERIENCE attribute is given, no data will be

transferred to the SAP field; this is the default for most fields (hence the "dummy"

qualification).

The following mappings may not be removed, but the value may be empty. They define

the 3DEXPERIENCE attributes that correspond to SAP fields identifying BOM

positions. Note that BOM positions are usually identified by more than one key field.

mxsapSetting(mxPosition) maps to POSNR (default: Find Number)

mxsapSetting(mxQuantity) maps to MENGE (default: Quantity)

mxsapSetting(mxItemCategory) maps to POSTP (default: none)

mxsapSetting(mxSubText) maps to UPTXT (default: none)


mxsapSetting(mxRefDes) maps to EBORT (default: Reference Designator)

mxsapSetting(mxSortInd) defines alternative sort criteria.

There are some variables in SAPSettings.tcl that define process-relevant behaviour:

mxsapSetting(Material_ExternalNumber) allows you to get the material

number from SAP, rather than using the 3DEXPERIENCE part name. This is different

from just converting the part name during transfer, because the 3DEXPERIENCE part

will be renamed in the process to match the SAP material number.

Corresponding settings exist for SAP documents and change numbers.

Please be extremely careful using this behaviour, because renaming the 3DEXPERIENCE

Part object will likely disrupt business processes defined by the 3DEXPERIENCE

applications.

mxsapSetting(Material_StoreNumberAsAttribute) and

mxsapSetting(Material_StoreNumberAttribute) allow you to store the

SAP material number in an 3DEXPERIENCE attribute. This may be useful for easy

reference if part name and material number are very different because of a complex

name conversion rule.

Corresponding settings exist for SAP documents and change numbers.

mxsapSetting(SAPLanguage) sets the language for SAP messages, i.e. it

determines the language of SAP messages returned to the user and to the log file; it has

no other effect. This setting may be overridden by the language setting of your browser.

Note that SAP will not honour the language setting for all messages.

Note that this setting does not affect the language setting for attributes like description

and material long text. To change that setting you need to adapt

SAPCustomerLib.tcl, procedure gdCustomerFillMaterialTable

(materials) and SAPToplevel.tcl, procedure gdToplevelDocumentCheckin

(documents).

mxsapSetting(SAPLoginLanguage) sets the language for the SAP login. Note

that the SAP login will fail if SAP does not support the login language you set. This

setting does not affect the message language of SAP.

Note that this setting does not affect the language setting for attributes like description

and material long text. To change that setting you need to adapt

SAPCustomerLib.tcl, procedure gdCustomerFillMaterialTable

(materials) and SAPToplevel.tcl, procedure gdToplevelDocumentCheckin

(documents).

mxsapSetting(SAPUsesBrowserLanguage) If true (1), this sets the language

for the SAP login to the language you set for the browser and overrides

mxsapSetting(SAPLoginLanguage). Note that the SAP login will fail if SAP

does not support the login language you set. This setting does not affect the message

language of SAP.

mxsapSetting(Material), mxsapSetting(mxTempPolicy),

mxsapSetting(mxPolicy), mxsapSetting(mxInitRev),

mxsapSetting(matBomTypeET), mxsapSetting(matBomTypeZB),

mxsapSetting(createVault) are used when transferring bills of material back

from SAP to 3DEXPERIENCE. These settings define the target objects and attributes if

new objects and relations must be created in 3DEXPERIENCE.

mxsapSetting(szDocInitRev) and mxsapSetting(szDocPolicy) have a

similar function for SAP documents.


mxsapSetting(szRelDoc), mxsapSetting(szDocRelDirection),

mxsapSetting(szDocType), mxsapSetting(szDocTypes) and

mxsapSetting(matrixFormat) are used to navigate the 3DEXPERIENCE

relations between parts and documents and thus determine which documents can be

managed.

mxsapSetting(docPageURL) is used when building the document original URL

before transferring it to SAP. Only applies if the document originals shall be managed

and viewed through 3DEXPERIENCE.

mxsapSetting(szChangeRelType), mxsapSetting(szChangeBOType)

and mxsapSetting(szChangeRelDirection) are used to navigate the

3DEXPERIENCE relations between ECOs and other business objects and thus

determine how change items are managed.

mxsapSetting(mxbomRel) and mxsapSetting(mxbomRelDirection) are

used to navigate the 3DEXPERIENCE EBOM relations and thus determine how BOMs

are exploded. If you want traverse more than one relation, define

mxsapSetting(mxbomRel) as a comma-separated list of relation names.

mxsapSetting(mxbomRelDirection) should usually be set to "from" (which is

the default), the other options (empty string or "both") make no sense in a BOM context.

mxsapSetting(ignoreSubitemQuantityMismatch),

mxsapSetting(factorBOMQuantity),

mxsapSetting(fixedBOMFactor),

mxsapSetting(ignoreMxZeroQuantity) and

mxsapSetting(allowNegativeBOMItemQuantity) are variables that set the

application's behaviour for transfer of quantity values. They are documented in

SAPSettings.tcl.

mxsapSetting(alwaysSetRevLevel) and

mxsapSetting(ErrorWhenDifferentChangeNumber) set the behaviour for

handling revisions and change number.

mxsapSetting(noTransferStateList) and

mxsapSetting(notReadyStateList) let you define transfer conditions

dependent on 3DEXPERIENCE object status.

Settings Related to Engineering Change Objects

As explained in Support of Current Change Object Types, you can choose whether to use Change

Order objects (CO) or Change Action objects (CA) to initiate transfers to SAP. By default, COs and

the legacy ECO objects will be supported. You decided which object types to use during the

installation of X-BOM Connector for SAP.

If you want to change the object types, you must edit SAPSettings.tcl. Find the

section titled Support of different types of 3DEXPERIENCE change objects. In this

section you find four blocks of code for the different possible options. Find the block

you need from the block descriptions and un-comment this block. Comment the other

three blocks out. Edit the active block if necessary.


Settings Related to Handling of Manufacturing BOMs and MCOs

The settings described in this section are only relevant if you have the Manufacturing BOM

Management application installed on your 3DEXPERIENCE system and if you want to transfer

manufacturing BOMs to SAP.

You will find all the settings described here in the SAPSettings.tcl library. The most important

setting is the plant mapping list that is described in detail below. All the other settings require

extensive additional customization of the standard 3DEXPERIENCE applications to be effective; you

should only use them if you deviated from the standard 3DEXPERIENCE schema.

We recommend that you contact Dassault Systèmes or T-Systems if you need MBOM customization

other than the plant mapping described below.

mxsapPlantMap parameters establish a 1:1 mapping between the 3DEXPERIENCE

and SAP plants. On the 3DEXPERIENCE side, the identifying characteristic for a plant

is the "Plant ID" attribute (not the plant name), on the SAP side, the plant number.

The format of mxsapPlantMap is

mxsapPlantMap("ENOVIA_plantID") "SAP_plant_number"

and you need one such line per plant you want to map. For example, set mxsapPlantMap(0000000001) "1000"

maps the 3DEXPERIENCE plant that has the Plant ID attribute value of "0000000001"

to the SAP plant with the SAP plant number of "1000". Note that the 3DEXPERIENCE

Plant ID attribute always has a unique value per plant.

Plant mapping is used whenever plant-specific 3DEXPERIENCE information is used, for

example MCOs and MBOMs. No MBOM-related function will work correctly (if at all) if

plant mapping is not set or if the mapping is wrong.

Setting the Document URL for Viewing Through 3DEXPERIENCE

X-BOM Connector for SAP can be configured to create document originals in SAP by actually

copying the document file to SAP, or to write just a link (an URL) that points to the file original in

3DEXPERIENCE. The latter has the advantage that no duplicate file is created and that the SAP user

always sees the most current version of the file, but at the disadvantages of drawing an

3DEXPERIENCE license and of not having the file under SAP control.

If you want to use the "link-to-3DEXPERIENCE" method you need to edit this line in SAPSettings.tcl

to the value you need:

set mxsapSetting(docPageURL) \

"http://localhost:8080/enovia/common/emxNavigator.jsp?emxSuiteDirect

ory=components&suiteKey=Components&objectId="

The procedure gdCustomerGetDocumentReference (in SAPCustomerLib.tcl) will then

build a URL of the format

http://localhost:8080/enovia/common/emxNavigator.jsp?emxSuiteDirecto

ry=components&suiteKey=Components&objectId==17558.14442.42448.56979

In SAP, the document originals are set to

WSAPPLICATION1=NET and DATACARRIER=INTERNET

http://localhost:8080/enovia/sap/SAPcheckout.jsp?id=17558.14442.42448.56979

http://localhost:8080/enovia/sap/SAPcheckout.jsp?id=17558.14442.42448.56979


during creation of the document original. This tells SAP to open the file reference (URL) via the

Internet, using the default Internet application of the operating system.

If you want to do more intricate customizing you need to edit the procedure

gdCustomerGetDocumentReference itself.

Configuring Basic Attribute Value Conversion

You need to use the TCL procedure gdCustomerConvertAttribute (in

SAPCustomerLib.tcl) for most attribute value conversions (see the Customization Options

section for details). However, you can define some simple conversion rules in SAPSettings.tcl.

mxsapSetting(Integers)

A list of SAP fields that should be treated as integer numbers when getting them from

SAP.

mxsapSetting(Reals)

A list of SAP fields that should be treated as real (floating-point) numbers when getting

them from SAP.

mxsapSetting(Dates)

A list of SAP fields that should be treated as dates when getting them from SAP.

mxsapSetting(ResetFields)

A list of SAP fields that should be reset (emptied) in SAP on each transfer to SAP. This

can be necessary because sending an empty field to SAP just causes the transfer for that

field to be ignored by SAP.

The variable mxsapSetting(cutoffCharacter) defines the character that

marks the "tail" of the attribute value that shall not be transferred. By default, this

character is the blank (ASCII 32).

Cutting off applies only to attributes that you define in the mxsapSetting(Cutoff)

list.

Example: In 3DEXPERIENCE, the Find Number can be any string. In SAP, the

corresponding attribute POSNR can only be a 4-digit number. If you establish a

business rule that 3DEXPERIENCE Find Numbers shall always be 4 digits, optionally

followed by a blank and additional text, you can use the "cutoff" (truncation) to obtain

valid SAP position numbers without programming.

Note that date-time strings are automatically truncated by X-BOM Connector for SAP if

the corresponding SAP field is only a date.

mxsapSetting(NoUpateFields) defines all SAP fields that may be created from

3DEXPERIENCE but shall not be updated from 3DEXPERIENCE in later transfers.

This is necessary if certain SAP fields shall get their initial value from

3DEXPERIENCE attributes, but SAP will then become the master system for these

fields.

mxsapSetting(factorBOMQuantity) and

mxsapSetting(fixedBOMFactor)

Allow quantity conversion for BOM transfers, either rule-based or by a fixed factor.

May be necessary because of SAP's limitations for decimal number ranges.


Configuring Event Triggers

X-BOM Connector for SAP comes with exemplary event triggers. Following 3DEXPERIENCE

standards, the triggers come in the form of trigger parameter objects, i.e. 3DEXPERIENCE business

objects that configure the behaviour of a triggered operation through their attributes. For details about

triggers in 3DEXPERIENCE Platform and how to use and configure them please see the

3DEXPERIENCE Platform Application Development Guide.

Five trigger parameter objects are installed automatically with the standard installation. Their type is

always "eService Trigger Program Parameters".

Name "PolicyDrawingPrintStateApprovedPromoteAction"

Revision "SAPCreateDocinfoRecordExample"

When active, this object transfers a Drawing Print document to SAP when it is released.

Technically, it uses the switch "PushDocument" in gdUniversalMethod.

Name "PolicyECPartStateApprovedPromoteAction"

Revision "SAPCreateMaterialMasterExample"

When active, this object transfers a Part object and all specifications attached to it to

SAP when the Part is released. If the Part has an EBOM, the first level of this EBOM

will also be transferred, including Parts in the BOM that are not yet in SAP.

Technically, it uses the switch "PushMaterialTrigger" in gdUniversalMethod.

Name "PolicyFormalChangeStateInApprovalPromoteAction"

Revision "SAPTransferFromCOExample"

When active, this object transfers a CO object and all its affected Parts and specification

documents to SAP when the CO is promoted to “Complete”. If Parts have EBOMs,

these EBOMs will also be transferred. Technically, it uses the switch

"PushFromChangeOrder" in gdUniversalMethod.

Name "PolicyECOStateReviewPromoteAction"

Revision "SAPTransferECOExample"

Same as above, but for the legacy ECO objects. In this case, the promotion to

“Released” triggers the action.

Name "PolicyMCOStandardStateReviewPromoteAction"

Revision "SAPTransferManufacturingChangeMasterExample"

When active, this object transfers an MCO object and all its affected Parts and

specification documents to SAP when the MCO is released. If Parts have MBOMs,

these MBOMs will also be transferred. Technically, it uses the switch

"PushFromPlantChangeOrder" in gdUniversalMethod.

All these objects are installed in Inactive state, i.e. they do not affect business objects and

processes at all. To activate the triggered operation you need to promote them to Active state.

The out-of-the-box installation provides procedures and settings that make these event triggers

effective as soon as you activate the parameter objects, in other words they are ready to use for a

simple standard process. In spite of this, the idea of providing the trigger parameter objects is just to

give examples of how triggered operation of X-BOM Connector for SAP may be configured, not to

provide a complete solution.

Triggered action of X-BOM Connector for SAP always follows the same implementation principle.

The trigger executes the TCL program SAPUniversalTrigger which in turn calls the procedure

gdUniversalTrigger ( included in TCL program SAPToplevel.tcl).

gdUniversalTrigger calls the procedure gdUniversalMethod in which the branching for


required functions (PushDocument, PushMaterialTrigger, PushFromChangeOrder,

PushFromPlantChangeOrder, passed in program argument 2) takes place.

Additional parameters that may be needed are passed as key-value-pairs to the procedures doing the

actual work. An example of how to pass such key-value-pairs is included in all three trigger parameter

objects: program argument 4 is the key "plant", and program argument 5 is its value "0001". They are

evaluated in the function procedures.

The sequence number is 77 for all trigger examples, i.e. they will run after all standard

3DEXPERIENCE triggers.

The comments in the trigger parameter objects and in the TCL procedures will help you to understand

how this works in case you want to implement triggered actions yourself.

As installed, the transaction result is signalled through a notice that pops up when the transfer is

complete. While this is appropriate in case of an error, and for a test environment even in case of

success, you may want to switch success messages off in productive environment. To do so, find the

procedure gdUniversalMethod in SAPToplevel.tcl and look for these lines, near the end

of the procedure:

...

if {[string length $msg]} {

mql notice [string trim $msg]

DEBUG "MQL NOTICE issued"

...

To switch success messages off, just put a comment mark (#) before the line beginning with "mql

notice".


Customization Options

This section describes your options to add customizations that extend X-BOM Connector for SAP

into functionality that cannot be provided by mere configuration.

Some parts of this section require that corresponding adaptations be made on the PLM and the

SAP side. You may need some SAP system administration knowledge to understand these

instructions, and you may need to work together with your SAP counterpart to implement them.

In this section:

Extending the Help System

How to Use and Modify Library Procedures

Attribute Value Conversion

Considerations for Special Object Types

Extended customizing: The mxsaprfc TCL Command

Extending the Help System

X-BOM Connector for SAP comes with its own help system. As installed with X-BOM Connector for

SAP, it provides help texts for the generic, out-of-the box functions. You may want to modify the help

system to reflect your corporate standards and business processes; this section describes how to do

that.

The entry element of the help system is a file called ENOHelp.htm that resides in the doc/sap

folder of your web application. However, to change the help content you should not modify files in

that folder but follow these steps:

Go to the STAGING_PATH directory of your installation.

Open the doc/sap folder.

Open the folder for the language you want to modify. Out of the box, only the default

folder en exists (for English help). You may add new language folders if you wish.

Apply all modifications you need.

Run the war_setup program and deploy the web application as usual to make your

changes visible to the users.

Here is a description of the help system to enable you to make changes without damaging the system:

The help system looks for X-BOM Connector for SAP help files in the doc/sap folder

of the web application.


Help uses the browser language to determine the help language. If it does not find a

directory for the browser language, it will use the default language (i.e. English,

directory name en).

In the language directory, it looks for a file named ENOHelp.htm. If it does not find

this file, it looks for the ENOHelp.htm file in the en directory. If it still does not find

it, it displays a warning saying something like "No help available".

ENOHelp.htm uses a "help marker" to find the context-specific help information. The

help marker is defined in the command admin object that opened the current function.

To see the help markers, open the business application rich client, find the command

object you want to investigate, and look at the Link-Href attribute. In the URL defined

there you will find a string like "&HelpMarker=SAPMCOHelp". For this help

marker, the help system would call ENOHelp.htm with a parameter

"&topic=SAPMCOHelp". The value of the HelpMarker parameter may be any

arbitrary string that does not violate HTTP conventions.

To remove the Help button entirely, use "&HelpMarker=false".

ENOHelp.htm evaluates he topic parameter; out of the box, it uses the value to

jump to a certain destination (anchor). This is done through a Javascript function that

runs when the help page loads.

From here on, you must find your own way to extend the system. The content, Javascript and the link

schema in ENOHelp.htm are easy enough to understand and commented extensively, so you should

be able, with the help of your web content developers, to modify it any way you want to.

Notes on Internationalization (i18n)

Internationalization (or "i18n", for short) means to provide the user interface and messages in a

language chosen by the user or the administrator. X-BOM Connector for SAP uses i18n for the

following features:

Messages and log file: Message texts are provided in the 3DEXPERIENCE programs

named SAPMessages-<languagecode>.txt and

SAPCustomerMessages-<languagecode>.txt. Message texts defined in

SAPCustomerMessages override those in SAPMessages; please do not edit the

SAPMessages programs as they will be overwritten by an upgrade. Which language

you use depends on your browser language and on the setting

mxsapSetting(SAPLanguage) in SAPSettings.tcl. If the message file for

the selected language is not found, the message language defaults to English (EN).

Web GUI: X-BOM Connector for SAP uses the standard mechanism provided by

3DEXPERIENCE Platform. All translations are in property files named

gdMxSAPStringResource*. The browser language determines which of the

language files is used; the default language is English (EN).

Dropdown list translation: The same property files hold "translations" for attribute

value ranges that are used in dropdown lists, for example for BOM usage (attribute

SAPRangesUsage); look for properties named emxFramework.Range.<attribute_name>.<range_value>

The attribute range is just a list of values SAP accepts, and the web GUI translates this

into something meaningful through the text provided by the string resource file. If no

property is available in the language file used, the original range value is displayed (for


example, out of the box there is no translation for SAP plant names, but you can add

properties for them). In any case, only the original range value is sent to SAP, not the

displayed value.

Note that "translation" can have two different meanings here: In addition to the usual multi-

language translation, displayed texts may be adapted to fit your SAP system or terms your

users are familiar with.

How to Use and Modify Library Procedures

The business logic of X-BOM Connector for SAP is implemented as TCL procedures, grouped in a

set of TCL libraries whose names all begin with "SAP". These libraries are installed as

3DEXPERIENCE programs of the "MQL" type; like all 3DEXPERIENCE programs, you can view

and edit them in the rich client Business application. The libraries come in two types:

Customer libraries are installed as templates to provide some out-of-the-box functions.

These libraries are meant to be changed in customer installations and are never

overwritten when you upgrade the product. There are three customer libraries:

o SAPToplevel.tcl provides the standard entry points for all functions

o SAPCustomerLib.tcl provides standard procedures for attribute conversion, SAP

connection settings, compare functions and other procedures that will likely have to be

modified for your environment

o SAPSettings.tcl provides no procedures but only static settings like attribute

mappings etc. that will be used by all procedures

Core libraries you should never change. They are part of the standard product and are

liable to replacement should you upgrade the product. All libraries except the three

listed above are core libraries.

The following diagram shows the libraries and the structure of procedure calls. Please note that no

triggers are provided with the standard installation, you must provide them for yourself. The standard

entry point for triggered functions is the gdToplevelUniversalTrigger procedure.

The methods provided for "native client", i.e. 3DEXPERIENCE rich clients, are provided exclusively

for administrative purposes and for backward compatibility.


How to Change Core Procedures

It may very well be that you need to change a procedure in a core library; with complex software

environments like 3DEXPERIENCE Platform and SAP, not every modification can be kept on a

simple configuration level. The load sequence we implemented makes it possible to do this safely.

To change a procedure in a core library,

copy the procedure from the core library and paste it into the SAPCustomerLib.tcl

program,

then edit the procedure there.

SAPCustomerLib.tcl is always loaded last in the sequence of libraries and consequently procedures

defined there overload previously loaded procedures.

Attribute Value Conversion

We provide the TCL procedure gdCustomerConvertAttribute (in

SAPCustomerLib.tcl) for attribute value conversions that go beyond a simple truncation (see

also Configuring Basic Attribute Value Conversion) but that do not involve complicated algorithmic

determination of the attribute value. The sequence in which attributes are converted is this:

All attributes that have a mapping defined in SAPSettingsd.tcl and are on the

"Cutoff" list are truncated.

All attributes that have a mapping defined in SAPSettingsd.tcl are sent to

gdCustomerConvertAttribute. The conversion should limited to such

algorithms that require only the current 3DEXPERIENCE attribute value and the name

of the SAP field as input.

The last chance to do conversions, and the right place to execute more complicated

conversion algorithms, are the procedures gdCustomerFillMaterialTable,

gdCustomerFillDocumentTable and gdCustomerFillECNTables. In

these procedures you have the full information about the 3DEXPERIENCE object

available and consequently could assemble data from several attributes or even across

relationships to calculate a value to fill into one SAP field. Also, these procedures are

not dependent on an existing mapping in SAPSettingsd.tcl.

gdCustomerConvertAttribute has two nested switch constructions, where the outer

construction switches by SAP field name and the inner one switches by the attribute value in

3DEXPERIENCE. To change the value conversion you need to change the TCL code, please see the

Customization Options section for details. However, we provide some sample code for the SAP field

CLIENTDATA-BASE_UOM with a simple mapping of unit-of-measure values from 3DEXPERIENCE

to SAP, and even with very little TCL experience you can change them if necessary.

Considerations for Special Object Types

As mentioned above, there are the three central procedures gdCustomerFillMaterialTable,

gdCustomerFillDocumentTable and gdCustomerFillECNTables that can be used for

attribute conversion. As they are called immediately before the actual call to the SAP RFC, these

same procedures may be used to implement other algorithms connected with the transfer.


One pretty universal procedure that you should take note of is gdCustomerUserExit (in

SAPCustomerLib.tcl) that is called automatically at some stations of the transfer. This

procedure gets information about the 3DEXPERIENCE object id, the SAP object type, the context

(pre- or post-transfer call) and possibly the change number. With that information it is able to do a lot;

before beginning to change core library procedures please check what gdCustomerUserExit can

do for you.

There are other pre-defined procedures that may perform tasks for special transfer types. We will not

discuss these procedures in detail here, as they have good internal documentation, we will just

mention them here so you have some pointers where to look if you want to do some really deep

customizing:

Parts and Material Masters: gdCustomerFillMaterialTable,

gdCustomerGetRecordNumber, gdCustomerGetRevIdentifier,

gdGetAttributes, gdGetPlant, gdRevCompare

Bills of Material: gdCompareBOMItems, gdCustomerAnalyzeMatrixBOM,

gdCustomerCreateFilter, gdCustomerGetBomAlternative,

gdCustomerGetItemCategory, gdCustomerParseSubitemLines,

gdCustomerParseSubitems, gdGetPlantForBOM, gdIsPositionValid,

gdCustomerGetRecordNumber, gdCustomerGetRevIdentifier,

gdRevCompare

Change Masters: gdCustomerFillECNTables,

gdCustomerGetRecordNumber, gdGetAttributes

Documents and Document Links: gdCustomerFillDocumentTable,

gdCustomerGetDocumentReference, gdGetDocApplication,

getSapDocKeys, gdGetAttributes

See the section Setting the Document URL for Viewing Through 3DEXPERIENCE for information

about how to set up the SAP document link to enable viewing of the document in 3DEXPERIENCE.

Extended customizing: The mxsaprfc TCL Command

The TCL command mxsaprfc is a new TCL command; depending on the connection interface you

use, it is implemented as a new TCL command or as a TCL procedure; both accept the same

parameter set. All RFC calls we make are initiated and handled through this command. It is your

ultimate resource to access each and every SAP module that is RFC-enabled. Here we give a brief

description of the command and its use.

One parameter of an mxsaprfc call to SAP is the name of the RFC-enabled SAP function you want

to execute. RFC functions are provided with data and return result values through additional

mxsaprfc parameters. The parameters can be of the types scalar, structure and table.

Scalars are basic data types of SAP (CHAR, INT, NUMCHAR, DATE, TIME, BCD,

and FLOAT). Scalars can either export or import data.

Structures are one-dimensional arrays of scalars; they are defined in SAP. Structures can

either export or import data.

Tables are two-dimensional arrays; a row is defined by a structure, and a table can have

any number of rows. A table can export as well as import data.


Note that the terms "export" and "import" depend on the point of view; an export from X-BOM

Connector for SAP is considered an import from SAP's point of view. We always use the terms as

seen from X-BOM Connector for SAP, so exported data goes to SAP and imported data comes from

SAP.

If you have installed the mxsaprfc library for the native SAP RFC connection, you can also get

most of the information given here by opening an MQL client, setting a context, going to TCL mode

and entering load mxsaprfc85

mxsaprfc help

Command Syntax

The general command syntax for mxsaprfc is

mxsaprfc <FUNCTION> [PARAMETERS]

See below for reference information about the six possible functions (call, open, close, getprocess,

getthread, help), the six possible parameters (connect, handle, import, export, tables, tcldebug), and

for coding examples.

mxsaprfc Function Reference: call

This command initiates the given SAP RFC function <SAPFUNCTION>. Multiple occurrences of -

export, -import and -tables are allowed.

mxsaprfc call <SAPFUNCTION>

-connect <CONNECT_PARAMETERS> | -handle <HANDLE_ID>

[ -export <EXPORT_PARAMETERS> ]

[ -import <IMPORT_PARAMETERS> ]

[ -tables <TABLES_PARAMETERS> ]

[ -tcldebug <DEBUG_PARAMETERS> ]

<SAPFUNCTION> ::= Name of SAP's RFC function. Capitalization and spelling of the SAP function

name must be identical to the function definition in SAP.

The –export parameters transport data from TCL variables to the SAP function.

The –import parameters transport data from SAP to a TCL variable.

The –table parameters can transport data both ways.

If you use the -connect option, X-BOM Connector for SAP opens a new connection to the SAP

system and closes it automatically and immediately after the call. If you use -handle, an existing

connection is used and not closed by the call. See the descriptions of open, close and of the

-handle and –connection parameters for details.

mxsaprfc Function Reference: open

mxsaprfc open

-connect <CONNECT_PARAMETERS>

[ -tcldebug <DEBUG_PARAMETERS> ]


Opens a connection to the SAP system described by <CONNECT_PARAMETERS> and leaves the

connection open. The function returns a handle that can be used in subsequent calls to mxsaprfc call <FUNCTION> -handle ...

Note: More than one SAP connection, even to different SAP systems, can be open at the same time.

Note: Each connection will remain open until you close it again explicitly, using the mxsaprfc

close function.

mxsaprfc Function Reference: close

mxsaprfc close –handle <HANDLE_ID>

[-tcldebug <DEBUG_PARAMETERS>]

Closes the SAP connection identified by <HANDLE_ID>.

mxsaprfc Function Reference: getprocess/getthread

mxsaprfc getprocess | getthread

Returns the process or thread id as an integer value. Can be used in debug output or filename

generation to distinguish different sources of data. In a single-threaded context the resulting thread id

will always be 0.

mxsaprfc Function Reference: help

The help command gives general reference information.

This command only returns useful information if the connection library for the native SAP RFC

connection is installed, but all information it gives is also present in this manual.

help <FUNCTION|PARAMETER> gives information about one function or parameter, similar to

the reference you are reading now. Possible functions/parameters are call, close, connect,

export, get, import, open, tables, tcldebug.

mxsaprfc help help gives detailed information about the help text syntax.

mxsaprfc Parameter Reference: connect/handle

–handle <HANDLE_ID>

This parameter passes the handle of an existing open connection to the function call. The connection

must have been opened with the mxsaprfc open command first. The connection will remain open

until you close it again explicitly.

-connect { <SAP_SYSTEM> <LOGON_DATA> }

This parameter tells mxsaprfc to connect to the SAP system for just this one function call and to

close the connection again after call is completed. Normally you should use it in this form: ... -connect [gdGetMxSAPRFCConnect] ...


and adapt the procedure gdGetMxSAPRFCConnect (in SAPCustomerLib.tcl) if necessary.

Below is a detailed explanation of possible parameters for deeper customization.

SAP_SYSTEM ::= <SAPRFC_INI_CONNECT> | <DIRECT_CONNECT>

SAPRFC_INI_CONNECT ::=

-D <DESTINATION> or

DEST=<destination> = name of the RFC destination in saprfc.ini. Instead of using

the connection and additional options defined above, you can also work with the

'saprfc.ini'-file and all needed options must be defined in this file. Using this feature, this

program can run in an SNC environment.

DIRECT_CONNECT ::=

o TYPE=3 or

-3 = R/3 mode on. You must set this to connect to SAP R/3; this is the only supported

connection type. Specify the following additional parameters:

o ASHOST=<HOSTNAME> or

-h <HOSTNAME> = hostname of the R/3 target system.

o SYSNR=<SYSTEM NUMBER> or

-s <SYSTEM_NUMBER> = system number of the target system. This determines the

TCP/IP service to be used to connect to the R/3 system. The default value is 0 and the

default service being used then is sapgw00.

o -gui = (optional) start sapgui to allow dynpro and graphics processing (3.0C or later

required on the target system).

Additional optional parameters:

o TRACE=1 or

-t = turn trace on. All operations are written to the trace file dev_rfc.

o ABAP_DEBUG=1 or

-debug = turn ABAP/4 debugging mode on. This only works if SAP GUI is installed

on the client system and the target SAP system has version 3.0C or later.

LOGON_DATA ::=

o USER=<USERID> or

-u <USERID> = SAP user id

o PASSWD=<PASSWORD> or

-p <PASSWORD> = SAP password

o CLIENT=<CLIENT> or

-c <CLIENT> = SAP client

o LANG=<LANGUAGE> or

-l <LANGUAGE> = SAP logon language

Some or all of these can also be put into saprfc.ini. Command line parameters override the saprfc.ini

settings.


mxsaprfc Parameter Reference: export

-export { ( <NAME> (<TYPE> [<LENGTH>])|<STRUCTURE> ) ... }

type ::= SAP_FLOAT | SAP_DATE | SAP_TIME | SAP_CHAR |

SAP_INT[1|2] | SAP_NUMC | SAP_BCD

structure ::= { { <NAME> <TYPE> <LENGTH> } ... }

Provides variable names and their types to be exported towards SAP. Only give the name of a

variable, not its value; <NAME> is the name of both an SAP field/structure and a TCL variable. Use

the exact name SAP uses in respect of capitalization and spelling. An exported variable must exist in

TCL. The value must be of appropriate type.

SAP_DATE has 8 digits in the format YYYYMMDD, SAP_TIME 6 digits in the format HHMMSS.

Values for structured variables are lists with as many elements as in <STRUCTURE>. The data type of

each element must correspond to SAP's data type at the same position in <STRUCTURE>. Data length

is taken from the variable's value, except for type SAP_BCD (binary coded decimal). For this type,

<LENGTH> is mandatory to interpret data.

A BCD length consists of two parts separated by a decimal dot. The former gives overall length, the

latter the number of decimal digits. Use half of the value shown in SAP for overall length, if

necessary rounded up to the next integer. Use SAP's value for the number of decimal digits.

Example: SAP:23.7 -> mxsaprfc:12.7

Note: SAP_INTs are assumed to be aligned at 4 byte boundaries, SAP_FLOATs at 8 byte boundaries.

mxsaprfc Parameter Reference: import

-import {( <NAME> (<TYPE> [<LENGTH>]) | <STRUCTURE> ) ...}

TYPE ::= SAP_FLOAT | SAP_DATE | SAP_TIME | SAP_CHAR |


STRUCTURE ::= { { <NAME> <TYPE> <LENGTH> } ...}

Provides variable names and their types to be imported from SAP. Only give the name of a variable,

not its value; <NAME> is the name of both an SAP field/structure and a TCL variable. Use the exact

name SAP uses in respect of capitalization and spelling. An imported variable may exist or not, it is

created even if it is empty.

Results for structured variables are lists with as many elements as defined in <STRUCTURE>. The

data type of each element corresponds to SAP's data type at the same position in <STRUCTURE>.

Most types have fixed lengths. Default lengths are: SAP_CHAR 250

SAP_NUMC 10

For type BCD (binary coded decimal), <LENGTH> is mandatory to interpret data. A BCD length

consists of two parts separated by a decimal dot. The former gives overall length, the latter the number

of decimal digits. Use half of the value shown in SAP for overall length, if necessary rounded up to

the next integer. Use SAP's value for the number of decimal digits.

Example: SAP:23.7 -> mxsaprfc:12.7

Note: SAP_INTs are assumed to be aligned at 4 byte boundaries, SAP_FLOATs at 8 byte boundaries.


mxsaprfc Parameter Reference: tables

-tables { ( <NAME> <STRUCTURE> ) ... }

STRUCTURE ::= { { <NAME> <TYPE> <LENGTH> } ... }

TYPE ::= SAP_FLOAT | SAP_DATE | SAP_TIME | SAP_CHAR |


Provides table names and their structure definitions to be exported towards and imported from SAP.

For both <NAME> and <STRUCTURE> only give variable names instead of their values; <NAME> is

the name of both an SAP structure and a TCL variable. <NAME> has to have the exact spelling and

capitalization used in SAP.

The TCL representation of the SAP tables is a nested list; the elements of the outer list are table rows,

and each row itself also being represented as a list; these inner lists must match the structure definition

of the table rows.

The structure description (column layout) given in <STRUCTURE> must exactly match SAP's table

definition, which can be found using the ABAP Workbench. Obey order, capitalization, spelling and

type for all table columns.

Provide a value for <LENGTH> only in case of SAP_CHAR, SAP_NUMC or SAP_BCD.

SAP_DATE has 8 digits in the format YYYYMMDD, SAP_TIME 6 digits in the format HHMMSS.

For a detailed description of SAP_BCD see help on exports or imports.

mxsaprfc Parameter Reference: tcldebug

-tcldebug [<LEVEL>] [<TRACE_FILE>] [<FILE_OPTION>]

This parameter switches debugging on and sets debugging options.

<LEVEL> controls the level of detail in which debugging output will be written. Values range from 1

to 15, higher values lead to more output. The default is 1.

<TRACE_FILE> gives the name and path to the file to use. Use TCL syntax, meaning that you use

slashes (/) for path specifications on all operating systems, not backslashes (\). The default file spec is

mxsapfrc_debug.trc in the current directory.

<FILE_OPTION> controls use of the debugging file: A value of 0 overwrites the file each time a

new call is made. With 1 (default) all new lines are appended. A value of 2 opens a new trace file for

each call, appending a unique timestamp to the file's name.

mxsaprfc Coding Examples: SAP Connection

This section provides some examples of how to code SAP connections. You must provide the actual

connect string for each required SAP destination in the procedure gdGetMxSAPRFCConnect in

SAPCustmerLib.tcl. Here are two examples of -connect parameters:

mxsaprfc ... -connect { -D PROD -u myname -p mypwd } ...

mxsaprfc ... -connect { -3 -h sapsrv01 -c 001 -u myname -p mypwd

-l EN } ...


You can modify gdGetMxSAPRFCConnect to provide any specific functionality to determine the

actual SAP destination that you need to communicate with.

The options given in the connect string are described in the SAP RFC documentation. The list of

options provided in the function reference above is a summary; please refer to the SAP documentation

for further information.

In the previous examples, the mxsaprfc call opened a new connection to SAP R/3 through the

―connect parameter, which was subsequently closed following completion of the RFC.

However, in some cases it is necessary to perform consecutive RFCs within the same login context;

for example, this is necessary when we perform a call to a BAPI which initiates an update in R/3.

Following the BAPI, it is necessary to call BAPI_TRANSACTION_COMMIT. The following code

snippet shows how you can do this. GetConnectString is a procedure that provides the complete

connect string described above:

set handle [mxsaprfc open -connect [GetConnectString]]

mxsaprfc call BAPI_DOCUMENT_CHANGE \

-handle $handle \

-import { RETURN typeRETURN } \

...

-export { DOCUMENTDATA typeDOCUMENTDATA } \

...

-tables { OBJECTLINKS typeOBJECTLINKS }

mxsaprfc call BAPI_TRANSACTION_COMMIT \

-handle $handle \

-import { RETURN typeRETURN } \

-export { WAIT SAP_CHAR }

mxsaprfc close -handle $handle

mxsaprfc Coding Examples: Import, Export, Tables

Examples for the –import parameter:

mxsaprfc ... -import { FUNC_NAME SAP_CHAR LANG SAP_CHAR }

puts "Name: $FUNC_NAME, Lang: $LANG"

Remember that FUNC_NAME and LANG are the names of both SAP fields (of the SAP_CHAR type)

and TCL variables.

Here is an example for a structure import:

set typeOfSTRUCTURE { { NAME SAP_CHAR 12 } { VALUE SAP_NUMC 6 } }

mxsaprfc ... -import { STRUCTURE typeOfSTRUCTURE }

puts "Structure Name: [lindex $STRUCTURE 0] Value: [lindex

$STRUCTURE 1]"

Examples for the –export parameter:

set FUNC_NAME GET_SYSTEM_INFO

mxsaprfc ... -export { FUNC_NAME SAP_CHAR }

Remember that FUNC_NAME is the name of both an SAP field (of the SAP_CHAR type) and a TCL

variable.


Here is an example for a structure export:

set typeOfSTRUCTURE { { NAME SAP_CHAR 12 } { VALUE SAP_NUMC 6 } }

set STRUCTURE { ABC 123456 }

mxsaprfc ... -export { STRUCTURE typeOfSTRUCTURE }

Example for the –tables parameter:

set typeOfTABLE { { NAME SAP_CHAR 12 } { VALUE SAP_NUMC 6 } }

set TABLE { { ABC 12345 } { XYZ 654321 } }

mxsaprfc ... -tables { TABLE typeOfTABLE }

foreach row $TABLE {

puts "Name: [lindex $row 0] Value: [lindex $row 1]" }

mxsaprfc Coding Examples: Miscellaneous

The following examples show usage patterns for some typical functions. They are in no means com-

plete but are meant to outline the general ideas behind mxsaprfc.

Note: Be very careful in specifying –connect parameters, SAP is completely non-forgiving about

errors there and may crash the complete application. Note also that the user "myname" must be

authorized in SAP to use RFCs.

# Functionality: Read RFC_SYSTEM_INFO

load C:/.../mxsaprfc85.dll ;# adapt this to your system!

mxsaprfc call RFC_SYSTEM_INFO \

-connect { -3 -h sapsrv01 -c 001 -u myname -p mypwd -l EN } \

-import { RFCSI_EXPORT SAP_CHAR } \

-import { CURRENT_RESOURCES SAP_INT } \

-import { DIALOG_USER_TYPE SAP_CHAR } \

-import { MAXIMAL_RESOURCES SAP_INT } \

-import { RECOMMENDED_DELAY SAP_INT } \

-import { RFC_LOGIN_COMPLETE SAP_CHAR }

puts "Structure RFCSI_EXPORT:\n$RFCSI_EXPORT"

puts "User Type : $DIALOG_USER_TYPE"

puts "Login compl: $RFC_LOGIN_COMPLETE"

puts "Max Res : $MAXIMAL_RESOURCES"

puts "Current Res: $CURRENT_RESOURCES"

puts "Rec Delay : $RECOMMENDED_DELAY"

# Use a structured definition for an import variable:

set RFCSI_DESC {

{ RFCPROTO SAP_CHAR 3 }

{ RFCCHARTYP SAP_CHAR 4 }

{ RFCINTTYP SAP_CHAR 3 }

{ RFCFLOTYP SAP_CHAR 3 }

{ RFCDEST SAP_CHAR 32 }

{ RFCHOST SAP_CHAR 8 }

{ RFCSYSID SAP_CHAR 8 }

{ RFCDATABS SAP_CHAR 8 }

{ RFCDBHOST SAP_CHAR 32 }


{ RFCDBSYS SAP_CHAR 10 }

{ RFCSAPRL SAP_CHAR 4 }

{ RFCMACH SAP_CHAR 5 }

{ RFCOPSYS SAP_CHAR 10 }

{ RFCTZONE SAP_CHAR 6 }

{ RFCDAYST SAP_CHAR 1 }

{ RFCIPADDR SAP_CHAR 15 }

{ RFCKERNRL SAP_CHAR 4 }

{ RFCSI_RESV SAP_CHAR 44 }

}

mxsaprfc call RFC_SYSTEM_INFO \

-connect { ASHOST=sapsrv01 CLIENT=001 \

USER=myname PASSWD=mypwd LANG=EN } \

-import { RFCSI_EXPORT RFCSI_DESC } \

-import { DIALOG_USER_TYPE SAP_CHAR } \

-import { RFC_LOGIN_COMPLETE SAP_CHAR }

puts "Structure RFCSI_EXPORT:\n$RFCSI_EXPORT"

puts "No. of elements: [llength $RFCSI_EXPORT]"

puts "User Type : $DIALOG_USER_TYPE"

puts "Login compl : $RFC_LOGIN_COMPLETE"

# Read functions's parameter list from SAP (portable version):

set FUNCNAME "RFC_SYSTEM_INFO"

set FCT_INTFCE_DESC {

{ PARAMCLASS SAP_CHAR 1 }

{ PARAMETER SAP_CHAR 30 }

{ TABNAME SAP_CHAR 30 }

{ FIELDNAME SAP_CHAR 30 }

{ EXID SAP_CHAR 1 }

{ POSITION SAP_NUMC 4 }

{ OFFSET SAP_NUMC 6 }

{ INTLENGTH SAP_NUMC 6 }

{ DECIMALS SAP_NUMC 6 }

{ DEFAULT SAP_CHAR 21 }

{ PARAMTEXT SAP_CHAR 79 }

}

mxsaprfc call RFC_GET_FUNCTION_INTERFACE_P \


-export { FUNCNAME SAP_CHAR } \

-tables { PARAMS_P FCT_INTFCE_DESC }

puts $PARAMS_P

foreach p $PARAMS_P { puts "[llength $p] $p" }

# Read function's parameter list from SAP

# (non-portable integer version):

set FUNCNAME "RFC_SYSTEM_INFO"

set FCT_INTFCE_DESC {




{ TABNAME SAP_CHAR 30 }

{ FIELDNAME SAP_CHAR 30 }

{ EXID SAP_CHAR 1 }

{ POSITION SAP_INT }

{ OFFSET SAP_INT }

{ INTLENGTH SAP_INT }

{ DECIMALS SAP_INT }

{ DEFAULT SAP_CHAR 21 }

{ PARAMTEXT SAP_CHAR 79 }

}

mxsaprfc call RFC_GET_FUNCTION_INTERFACE \



-tables { PARAMS FCT_INTFCE_DESC }

puts "$PARAMS \n\n"

foreach p $PARAMS { puts "[llength $p] $p" }

# Changing number or order of elements in a table description

# will ***FAIL***! Reason: All field lengths are added

# to find out the beginning (offset) for the next field.

# This computation fails in case of reordering or omission.

set FCT_INTFCE_DESC_FAIL {



{ EXID SAP_CHAR 1 }

{ POSITION SAP_NUMC 4 }

{ OFFSET SAP_NUMC 6 }

}

mxsaprfc call RFC_GET_FUNCTION_INTERFACE_P \



-tables { PARAMS_P FCT_INTFCE_DESC_FAIL }

puts $PARAMS_P

foreach p $PARAMS_P { puts "[llength $p] $p" }

# Example of mis-constructed table:

set TEST_INTFCE {

{ Parameter_1 1 0 "Test one" }

{ PARAMETER_2 15 15 "Test two" }

{ PARAMETER_2 15 "Test three" }

{ PARAMETER_3 15 15 "Test four" "This will fail." }

}

# RFC test program Z_RFC1

set STRUCT_DESC {

{ TEXT1 SAP_CHAR 50 }


{ INT1 SAP_INT }


}

# Proper values for structure:

set IMP_STRUCT1 { {This is long} xy 2049}

# Structure values exceed limits:

set IMP_STRUCT1 { {This is a text much too long, which will extend

far beyond the given limit of 50 characters.} xyzxyzxyz 2049}

set IMP_NUM1 347348

set IMP_DATUM1 19990923

mxsaprfc call Z_RFC1 \


-export { IMP_STRUCT1 STRUCT_DESC } \

-export { IMP_NUM1 SAP_INT } \

-export { IMP_DATUM1 SAP_DATE }

set TABLE_STR_DESC {



{ INT1 SAP_INT }

}

set TABLE1 { { {This is long} xy 2049 } }

set IMP_CHAR1 "Nonsense"

mxsaprfc call Z_RFC2


-tables { TABLE1 TABLE_STR_DESC } \

-export { IMP_CHAR1 SAP_CHAR } \

-import { EXP_CHAR1 SAP_CHAR } \

-tcldebug 8 c:/temp/rfc.txt 1

puts "Table:"

foreach p $TABLE1 { puts "[llength $p] $p" }

puts "Exp1: $EXP_CHAR1"

# end of example code


Customizing SAP

This section describes certain typical SAP settings and configurations that may be necessary to

work with bills of material and documents on SAP systems. Standard SAP installations may have

these options de-activated, and the information here should help you to tell your SAP system

administrator what you need.

This section requires some SAP system administration knowledge to understand these

instructions, and you may need to work together with your SAP counterpart to implement them.

In this section:

Customizing the SAP Document Management System

Customizing the SAP BOM System

Customizing the SAP Engineering Change Management

Note 1: All recommendations made below for any SAP settings describe our experience with typical

SAP configurations or with conditions we found in a majority of customization projects, they do not

constitute SAP "best practice" recommendations. Of course, all decisions to introduce modifications

depend on your PLM and ERP business processes, which in turn may be influenced by the

characteristics of 3DEXPERIENCE Platform and SAP. Please consider the recommendations to be

just pointers where you could look if you experience problems with the set-up of transfers.

Note 2: All changes made to SAP may change the structure definitions we use to transfer data

between 3DEXPERIENCE Platform and SAP. Please do not forget to perform a new SAP Download

Structures to re-create the SAPStructures*.tcl program(s) after modifying your SAP system.

Please alert your SAP colleagues to this problem so they can give you a notification when they work

on what they may otherwise perceive as "SAP-internal" maintenance.

Customizing the SAP Document Management System

This section describes some required SAP requisites and settings you should typically check to enable

document transfer by X-BOM Connector for SAP.

Prerequisite for Physical File Transfer – Native SAP RFC

The information in this section is only relevant if you use native SAP RFC as your connection

interface. Ignore it if you use only SAP JCo.

If you decided to transfer copies of physical files to and from SAP on Document Checkin and

Document Checkout, as opposed to transferring a URL that points to the 3DEXPERIENCE system


as the "document original", you need to have SAPHTTP or SAPFTP installed on the

3DEXPERIENCE Platform server machine. At least one of these SAP modules is required to send

and receive files in the context of a SAP RFC transaction.

You can get these modules from the SAP download site. SAPHTTP/SAPFTP must match your SAP

system version, and you need different versions for Unicode and non-Unicode SAP systems. When

installing SAPHTTP/SAPFTP take care to include the path to these applications in the PATH variable

used by the 3DEXPERIENCE process. Please see the SAP documentation for details about the

applications and their installation.

Prerequisite for Physical File Transfer – SAP JCo

The information in this section is only relevant if you use SAP JCo as your connection interface.

Ignore it if you use only native SAP RFC.

Contrary to SAP RFC, SAP JCo does not support the direct transfer of physical files. For this reason

you need to install new function modules in your SAP system if you want to copy physical files from

SAP to 3DEXPERIENCE or vice versa. You do not need the function modules if you only transfer a

backlink URL.

We provide these function modules together with a necessary customization in the X-BOM Connector

for SAP installation package in the form of a SAP Transport Order (SAP TO). The TO is delivered in

a folder named sap-transport. Give the contents of this folder to your SAP counterpart to install

the function modules. See the section Installing X-BOM Connector for SAP / Installing and

Customizing the SAP Function Modules for information about how to install them and how to set the

new custom parameters that come with the function modules.

Customizing SAP DMS Settings

Open a SAPGUI client and open transaction SPRO. Click SAP Reference IMG and navigate to

Cross-Application Components, Document Management and then to Control Data, as shown

below.


First, find the document types you need (this must fit the getSapDocKeys procedure in

SAPCustomerLib.tcl) and check/change the control data for those document types (Define Document

Types / IMG Activity icon):

Highlight: Rev.Level / Version checkboxes, Details button

If you want to let SAP automatically assign revision levels on your documents you must

checkmark the Rev. Level Assgment checkbox.

Note: This requires that you also enable revision level assignment for Engineering

Change (see section Customizing the SAP Engineering Change Management).

Recommendation: Turn revision level assignment OFF.

If you want to let SAP automatically assign version numbers on your documents you

must checkmark the Version Assign checkbox.

Recommendation: Turn version assignment OFF.

To set more options for specific document types, select one type and click the Details button. Note

that you can also set the revision level and version assignment behaviour from the Details screen.


Choose the type of document Number Assignment to determine which kind of

assignment (internal, external, with options and user exits) is used for the document

number.

Recommendation: Set number assignment to blank (empty) because this setting allows

both internal and external assignment.

Set the document Version No. Increment control to match the revision number

sequence in 3DEXPERIENCE Platform document policies.

Recommendation: Set this field to * (asterisk) to allow any number sequence.

To define which document type can be linked to which type of other object use the Define Object

Links screen which is also in the Define Object Types tree.


Each entry defines one possible link. For example, the highlighted line defines that DRW documents

may be linked to Material Masters. Be sure to define all links you need.

Defining SAP Document Originals by Backlink to 3DEXPERIENCE

SAP allows to define a document original as a URL, that is a link to the repository where the

document original actually resides (the relation between SAP documents and their originals is

somewhat similar to the relation between an 3DEXPERIENCE Document and its files). This gives us

the option to leave the physical file in the 3DEXPERIENCE system while still being able to access it

from SAP; whether you want to use that option is up to you.

The advantages of linked originals are that you save storage space for the file copy, and

that SAP users see the same file, in the same current status, as the 3DEXPERIENCE


users. Another advantage is that you do not need SAPFTP or SAPHTTP installed on

your 3DEXPERIENCE server machine (see the section Customizing the SAP Document

Management System for details on this).

Disadvantages are that you may prefer to keep a file copy with a certain, approved status

in SAP rather than the latest file. You also need to keep in mind that linked originals

require that your SAP users also have named-user 3DEXPERIENCE Platform licenses

because they will access the files through an 3DEXPERIENCE server.

To prepare SAP for the URL-based backlink "storage" go to Document Management / General

Data and click the IMG Activity icon in the General Data category.

Double-click Define Data Carrier type "external DMS" to see existing entries and if necessary

click New Entries to define a data carrier type with the values

Type: "EX"

Description: "External DMS"

Online: √


Select the newly defined data carrier type and double-click Define external DMS. If necessary click

New Entries again to create a data carrier with the values

Data Carrier: "INTERNET"

Data Carrier Type: "EX"

Description: "3DEXPERIENCE PLM external DMS" (optional)

Ex: √

Now double-click on Define data carrier type "Server, Frontend" to see existing entries. If

necessary, click New Entries to create an entry with the values

Type: "PC"

Path: "C:\temp" (or similar)

CAD System: ""

Online: √

Select the newly defined data carrier type and double-click Identify frontend computers. To make

the new entry the default value, click the Default entry button.


The next task is to customize the workstation application. The IMG Activity icon next to Define

Workstation Application in the General Data folder is the entry point for this task.

Check whether a workstation application NET exists. If necessary click New Entries again to create a

new application with the values

Application: "NET"

Description: "Netscape or IE"

Suffix: ""

Archive ID: ""

Start Authorization: √

No rename: ""

File Format: "*.*"


Now select the NET application type and double-click Define Workstation Application in Network.

If necessary click New Entries to create an application with the values

Workstation application: "NET"

Data Carrier Type: "PC"

Application type: 1 (that is "display only")

Path with program name: "%AUTO%"

Path for ref. file: ""

Start Authorization: √

Checking the DMS Customization Tables

For SAP experts it may be easier to check the set-up described above through a quick look at the SAP

tables. Use SAP transaction SE11 and check these tables:

TDWD (Data Carrier/Network Nodes)

Check for an entry DTTRG=Default, TYPDT=PC, NETADR=DEFAULT

Check for an entry DTTRG=INTERNET, TYPDT=EX

TDWP (Workstation Applications)

Check for an entry DAPPL=NET, APPLB=X

TDWE (Data Carrier Type)

Check for an entry TYPEDT=EX, ONLINE=X


Customizing the SAP BOM System

This section describes some required SAP settings you should typically check to enable BOM transfer

by X-BOM Connector for SAP.

In the SPRO transaction, navigate to Define Modification Parameters and click IMG Activity:

Make sure that the CAD Active option is set:

Next. navigate to Define Item Categories and click IMG Activity:


Check whether the Subitems are enabled for the BOM categories you need (in the example, the BOM

category "L" is selected):

Customizing the SAP Engineering Change Management

This section describes some required SAP settings you should typically check to enable revision level

transfer by X-BOM Connector for SAP.

The SAP revision level is a 2-character-attribute on the relation between a material master and a

change master, it is not an attribute of the material master itself. This implies that

a change master is needed to set a revision level (otherwise you have no relation to write

a revision to) and that

the material master itself is not changed by adding a revision level (because the revision

is written to the relation, not to the material master).

In the standard installation X-BOM Connector for SAP will transfer the original 3DEXPERIENCE

revision number. You can implement your own algorithm to map 3DEXPERIENCE and SAP

revisions if you want; you must do so if your 3DEXPERIENCE revision numbers have more than 2

characters.

Note: It is usually not a good idea to make the 3DEXPERIENCE revision number a part of the SAP

material number; doing so would break the standard SAP BOM handling and would require a

completely new SAP BOM per 3DEXPERIENCE revision.

To enable revision transfer you should check and possibly change the following SAP settings. For

details, please see the SAP documentation about Engineering Change Management.


Use SAP transaction SPRO, navigate to Set Control Data in the Logistics-General section and click

IMG Activity:

Check Rev Level Act. Check or uncheck Ext. Revision Level and Higher Rev Level as required

(Ext. Revision Level is usually switched off).

Next, navigate to Define Revision Levels for Materials and click IMG Activity. Define the revision

levels to fit to the levels you want to set. This can be 3DEXPERIENCE revision levels (as defined in

the policies) or other level designators, if you use a more complex transfer algorithm.


Troubleshooting

This section gives you information about what to do when X-BOM Connector for SAP does not

work as expected. It includes information about how to perform basic checks, where to look for

the reasons of the problem, how to set up logging and tracing and how to submit issue reports.

In this section:

General Recommendations for Troubleshooting

Log Files and Tracing

Library Load Test

Known Issues

General Recommendations for Troubleshooting

This section gives you some general information about how to proceed when you encounter problems

with X-BOM Connector for SAP. As an interface program between two network-based applications,

X-BOM Connector for SAP has more possible causes of problems than a native program running on

your local machine; problems can be caused by X-BOM Connector for SAP itself, but also by either

the 3DEXPERIENCE PLM environment or the SAP ERP environment. In addition, a lot of

infrastructure is involved: Web application servers, database servers, firewalls or network connections

can fail and cause trouble, often with insufficient or even misleading error messages. Very often not

all of these components are even within your own area of competence or responsibility.

The consequence of this complicated environment is that anyone whom you call to help will need a lot

of information if he shall have a chance to find the underlying source of the problem and to propose a

solution.

If you encounter problems, here is a list of steps you should take to tackle the problem:

General Set-Up

o Who has notified you of the malfunction? Can you reproduce the problem together with

the user? Is this a function that has worked before for that user, and if it did, when was it

last seen to work?

o Does the same function work with different input data (for example with other business

objects), and does the same function work for other users? If it does, what are the

differences between the objects (attribute values, files checked in, object or structure

size, responsible organisation) or between the users (function and access rights,

domain/location, language settings, date settings, decimal point settings)?

o Has the environment changed recently? Has any 3DEXPERIENCE or SAP software

been updated or did the data model change? Have users been disabled or may passwords

have expired? Have servers received new IP addresses, or have network connections

been re-routed?


o Did you update X-BOM Connector for SAP recently, or did you change X-BOM

Connector for SAP configuration values?

What went wrong, actually?

o What exactly did the error message say, if any was shown? Not all error messages give

good information about the real problem, and some are just misleading. Check the

function results; do they check with what the error message said? For example, if it said

"Material could not be generated", is it true and was really no material record created?

How to get and share additional information

o Your best source of information are the various log files X-BOM Connector for SAP

can be configured to write. See the section Log Files and Tracing for information about

these files.

Log files are the single most important means of letting any support person know what

has happened.

Test Steps

Here are some simple tests you can perform yourself to find out what the nature of the

problem is:

o If there is doubt that the integration works at all, test the basic function of the integration

by performing the same checks as for a new installation: Does the SAP system respond

at all ("SAP PING" method)? Can you view the SAP system information ("SAP Info"

method)?

If these tests do not work, you need to verify that the SAP system is up and that its

address and access information match those configured into the integration.

o If the error message indicates a problem with the mxsaprfc command you may want

to test whether the TCL extension libraries can be loaded. Use the test described in

Library Load Test, below.

If this fails you need to check that the mxsaprfc* shared library and the SAP shared

libraries (librfc* or sapjco*) are in a place where they can be found. The libraries

must be in the PATH defined on the system; usual places are the BIN_PATH

(Windows) or the LIB_PATH (Unix/Linux) directory of the 3DEXPERIENCE server

and studio applications; if you use SAP JCo, Java error messages like "Class not found"

may point to a problem with the CLASSPATH. Please note that checking path settings

from a shell window may not be enough, because the settings in the 3DEXPERIENCE

environment may be different from those in the shell.

o If the problem seems to be connected to data structures you should try to download the

SAP structure information again, using the "SAP Download Structures" function.

o If the error message indicates that SAP complains about missing or incompatible data

please contact your SAP colleagues to check how they interpret the error message and

whether they applied changes to the SAP system recently.

Log Files and Tracing

X-BOM Connector for SAP can write log files on 3 different levels.


TCL Logging

This is by far the most common logging we use; by default, this logging is switched on. It writes log

files named mxsap.trace.<timestamp>.log.

Switch this logging on by setting set mxsapSetting(szDebug) 1

in SAPSettings.tcl.

You can further get a summary of all SAP transaction by setting set mxsapSetting(logSAPTransactions) 1

in SAPSettings.tcl.

As a last option, you can override the default logging procedure by un-commenting the line set mxsapSetting(Log_CustomerProc) gdCustomerLog

in SAPSettings.tcl.

X-BOM Connector for SAP writes TCL log files to the directory specified by

the mxsapSetting(MXSAPDIR) setting in SAPSettings.tcl or

the MXSAPDIR environment variable, set in enovia.ini or through environment

variables.




The setting in the .ini files will override SAPSettings.tcl. The default values in SAPSettings.tcl

are /tmp for Unix and C:\temp for Windows systems. By default, no MXSAPDIR entry is present

in the .ini files; please see the section Trace File Destination (which is in the installation section) for

more information on how to set this.

mxsaprfc Trace

The mxsaprfc command writes its own trace files if the –tcldebug parameter is passed to it. If

you need to trace a specific mxsaprfc call add the –tcldebug parameter where it is called in the

TCL procedures. The trace is written to files with file names in the format "m<something>.trc".

For details, see the description of the –tcldebug parameter at mxsaprfc Parameter Reference:

tcldebug.

SAP RFC Trace

SAP RFC can write trace files with names like "rfc00116_00104.trc". You can only switch

them on via a SAPRFC.ini file. The SAPRFC.ini is normally put into the same directory as the

executable you are working from. This is, in our case, the place where the mxsaprfc* shared library

is, i.e. the BIN_PATH (Windows) or LIB_PATH (Unix/Linux) of your system.

A setting of RFC_TRACE = 1

will switch RFC tracing on. The trace file will be placed in the same directory as the current

executable.


If there is no SAPRFC.ini file in your system, you can create it as a standard text file. Its content

should only be the one line quoted above (RFC_TRACE = 1).

Library Load Test

One common problem is that not all required libraries needed by the integration are available on your

system, or that they are not in the correct path. Se the section Getting the SAP Connection Libraries

for details on required libraries.

To test whether libraries can be loaded, use the MQL program SAP TEST LIBRARY LOAD. The

program writes a trace file if tracing is enabled. You can use this program to test that our TCL

extension libraries can be loaded correctly in your environment and that initialization files are

readable. It also returns a lot of other information about your operating system, SAP system and

3DEXPERIENCE environment.

Call the program from the MQL application by setting context and entering the command exec prog “SAP TEST LIBRARY LOAD”;

or start the program from the rich client Navigator application by finding the business object "SAP

Schema Map" "SAP Mapper" "" and executing the method SAP TEST LIBRARY LOAD on this

object.

The program will write a trace file to the temp directory you specified when installing X-BOM

Connector for SAP. The last line will give a summary, the content before that provide the details.

To perform such tests in a web environment you can use the Run MQL function of the

3DEXPERIENCE web GUI (My Apps – Utilities – Run MQL). Enter execute Program “SAP TEST LIBRARY LOAD”

into the command line. However, this is only suitable for a short test, for serious trouble with libraries

a more in-depth investigation may be necessary.

Possible Problems and How to Solve them

Libraries are loaded in several steps: TCL loads our library mxsaprfc85, this tries to load the SAP

RFC libraries (librfc32u and its dependencies, as described in the section Installing the Shared

Libraries), which in turn depend on certain systems libraries provided by the operating system. If you

use SAP JCo, X-BOM Connector for SAP will first access the Java library sapjco*.jar, which in

turn will load system-specific libraries.

In case of a suspected library load problem, please try the following steps to find the underlying

problem:

Execute SAP TEST LIBRARY LOAD as described above. It tells you where it wrote

the log file.

In the rare case that SAP TEST LIBRARY LOAD crashes without any return

message, it is probable that a library is damaged or does not fit your operating system.

Check, replace and try again.

Look into the log file. The section after the message "Check Environment ..." gives

information about the system environment as it is in the 3DEXPERIENCE process. In

particular, the path and library search path information may be interesting to check, to

see whether the environment meets your intention.

The part concerning us mainly comes after a message "Check loading of shared

libraries...". In this section we first try to load the mxsaprfc library, and after that the


SAP RFC libraries, one by one. You can ignore messages saying "couldn't find

procedure ****_Init", but all other error messages point to a problem.

A load problem for a single library may point to a corrupt library. In most other cases,

the message will indicate that a certain library is missing. Provide that library and try

again.

Incident Reports

If you have problems you cannot solve by the procedure described above please submit an incident

report as specified in your maintenance and support contract. To be able to help you efficiently it is

very important that you provide the following information together with your incident report:

Environment

3DEXPERIENCE Platform version and server platform/OS version, SAP version, X-

BOM Connector for SAP version and connection method (SAP RFC or SAP JCo)

What did you want to do? What was the starting situation, what did you want to achieve, and what was the

expected result?

What happened? How did the system respond? Was data actually transferred or not? What part of that

data was correct, what showed unexpected values? What error messages did you get?

Supporting information Most important is the X-BOM Connector for SAP log file. We need this for nearly

every incident report, so it is a good idea to provide it together with the report. X-BOM

Connector for SAP writes a new log file for each transaction, so make sure you send the

ones relevant to the problem (the log files have a time stamp in their name that could

help to identify them).

Screenshots may sometimes also help to identify problems.

Known Issues

Please see the readme file for X-BOM Connector for SAP in the 3DEXPERIENCE "program

directory" documentation for any issues existing in the current version. This file is available from the

3DEXPERIENCE support site.


Glossary

0

3DEXPERIENCE The brand logo, introduced in 2013, for CATIA and ENOVIA products

A

ADK Application Development Kit, the JAVA API of 3DEXPERIENCE Platform

AEF An obsolete name for the Business Process Services (BPS) application module, see

BPS

API Application Programming Interface, the programming interface to an application.

3DEXPERIENCE Platform provides a script language (MQL/TCL) and a Java

toolkit (ADK). SAP provides a number of APIs and a programming language

called ABAP to extend the API. X-BOM Connector for SAP mainly uses the

BAPI and CSAP interfaces of SAP.

B

BAPI Business Application Programming Interface, a collection of function modules

provided by SAP. Most X-BOM Connector for SAP functions use BAPI function

modules.

BOM Bill of Material. Generic term, but also the SAP name for its part structure

representation. SAP distinguishes different BOM usage by the addition of an

integer key value.

BOM is also the new name for the Engineering BOM Management product,

formerly known as Engineering Central.

BOM Usage An SAP concept. Different usages for an SAP BOM are distinguished by the

"BOM Usage" parameter, usually defined as 1 = Production, 2 = Engineering or 3

= Universal.

BPS Business Process Services, a package that combines the Application Engineering

Framework and other central 3DEXPERIENCE applications.


C

Change Action CA, a type of change object that was introduced with 3DEXPERIENCE R2014x

Change Number SAP's equivalent to a 3DEXPERIENCE CO

Change Order CO, a new type of change object in 3DEXPERIENCE R2014x and later that

replaces the ECO

Category The name for the items in the menu of the Categories bar. Each category gives you

a different view on the current object. Technically, each category is a command

item. The SAP Power View and SAP Actions categories show information

relevant to X-BOM Connector for SAP.

CPIC User Special user type in SAP who is not allowed to login in SAP GUI, which means

that he cannot use SAP interactively

D

Dassault Systèmes A French company that develops, among other things, the 3DEXPERIENCE

Platform software systems.

DIR Short for Document Information Record, see DocInfo Record

DocInfo Record Document Information Record, SAP's equivalent to an 3DEXPERIENCE

document or specification

Document Original SAP's equivalent to an 3DEXPERIENCE document file

E

EBOM Engineering Bill of Material, a bill of material that represents a product from the

engineering point of view. The EBOM is usually the template for the

corresponding manufacturing bill of material (MBOM).

ECO Engineering Change Order, a type of change object that became obsolete with

3DEXPERIENCE R2014x

ECR Engineering Change Request, a type of change object that became obsolete with

3DEXPERIENCE R2014x


Effectivity Date The central concept in SAP for handling what 3DEXPERIENCE calls revisions.

Any object, including BOM positions, is valid in a certain time interval denoted by

the from and to effectivity dates.

ENG An obsolete product trigram for the Engineering BOM Management application

that is part of the BOM process product.

Engineering BOM Management A 3DEXPERIENCE application, part of the 3DEXPERIENCE Platform. The

Engineering BOM Management implements the engineering change process as

well as BOM and specification management.

3DEXPERIENCE Platform A PLM system by Dassault Systèmes (known as ENOVIA Live Collaboration

until V6R2014)

ERP Enterprise Resource Planning, a generic term for material handling, resource

management, manufacturing management. SAP is a software system that supports

ERP processes.

F

Function Module A SAP term for API functions. Function modules provide a specific functionality

and belong to certain interfaces. One of those interfaces is BAPI. To use a certain

function module for X-BOM Connector for SAP the function module must be

RFC-enabled.

G

gedas A former German company that initially developed the X-BOM Connector for

SAP software application under the name of MxS-ERP. gedas has become part of

T-Systems International GmbH.

GUI Graphical User Interface, the surface of a software product as the user sees it. In

3DEXPERIENCE Platform the GUI is implemented as a set of Web pages that can

be viewed and manipulated through a web browser.

I

i18n A short notation for the word "internationalization", meaning the presentation of

the user interface and messages in a language selected by the user or administrator.


J

JCo Java Connector, a SAP toolkit that allows a Java application to communicate with

any SAP System. See http://service.sap.com/connectors for more information.

JPO Java Program Object, a Java program that is stored as an object in the

3DEXPERIENCE Platform database. JPOs are part of the ADK of

3DEXPERIENCE Platform and can be used to customize 3DEXPERIENCE

Platform.

M

Manufacturing BOM Management A 3DEXPERIENCE application (product trigram MBO), part of the

3DEXPERIENCE Platform. Manufacturing BOM Management implements

functions to manage manufacturing-related data.

Material Also called Material Master, SAP's equivalent to an 3DEXPERIENCE Part object

Matrix The old, now obsolete name of the PLM software now called 3DEXPERIENCE

Platform.

MBO Dassault Systèmes’ product and license trigram that designates the Manufacturing

BOM Management application. Was labelled MFG until release V6R2014.

MBOM Manufacturing Bill of Material, a bill of material for use in the manufacturing

process; it is often specific to one or more manufacturing plants. The MBOM may

be different from the EBOM in the parts belonging to it, in part quantities, and in

structure.

MCO Manufacturing Change Order

MFG Obsolete ENOVIA trigram, see MBO

MM Short for Material Master, see Material

MQL The script API of 3DEXPERIENCE Platform. MQL commands follow TCL

syntax and are implemented as an extension of the TCL command interpreter.

MQL programs may reside in the 3DEXPERIENCE Platform database as database

objects or as external program files.

MxS-ERP, MxSAP Other names for the software that is sold by Dassault Systèmes under the name of

X-BOM Connector for SAP



P

Part An engineering item managed by 3DEXPERIENCE. Also called "assembly" if it

consists of sub-parts, or "component" if it does not.

Path Definitions You can look up all paths for the 3DEXPERIENCE Platform installation in a file

called enovia.install.

Plant A manufacturing site. Manufacturing items, including most SAP items, always are

associated with one or more plants, while engineering items, including most

3DEXPERIENCE items, are not. In SAP, plants are identified by 4-digit ID

numbers; in 3DEXPERIENCE, plants have names plus an ID number.

PLM Product Lifecycle Management

R

Revision A term that designates a distinct object in 3DEXPERIENCE, but only an object

attribute in SAP. The revision concept in SAP is completely different from that of

the 3DEXPERIENCE Platform. See also "effectivity".

RFC Remote Function Call, an SAP protocol for accessing SAP server functions from

other systems. The term is also used for a SAP toolkit that allows a C application

to communicate with any SAP System. See http://service.sap.com/connectors for

more information.

RMI An obsolete name for the 3DEXPERIENCE Platform Platform Server

RPE Runtime Program Environment, the runtime environment for all application

programs of the 3DEXPERIENCE Platform application suite, including X-BOM

Connector for SAP. See the programming guides of the 3DEXPERIENCE

Platform for details.

S

SAM Dassault Sysdtèmes’ product and license trigram that designated the X-BOM

Connector for SAP application in ENOVIA releases V6R2014 and earlier.

Replaced in 3DEXPERIENCE R2014x by the XSA product.

SAP R/3 An ERP system developed by SAP AG

SAPGUI The proprietary client software for the SAP R/3 system



T

TCL Tool Command Language, an open-source script language. Its syntax is used for

the MQL API of 3DEXPERIENCE Platform

T-Systems International GmbH A German global IT services and consulting company (subsidiary of Deutsche

Telekom) that develops the X-BOM Connector for SAP application amongst other

things.

Trigger A concept in the 3DEXPERIENCE Platform software, meaning that a certain

"event" (something happening to a PLM object) causes a program to start in

background that checks the requirements for the event or performs automatic

follow-up functions. For example, in many companies the release of a part

"triggers" an automatic transfer of the part to SAP

V

Valid From A date field for Change Orders and legacy ECOs that is used to define the SAP

effectivity date; see also: Effectivity Date

X

XSA Dassault Systèmes’ product and license trigram that designates the X-BOM

Connector for SAP application in 3DEXPERIENCE releases 3DEXPERIENCE

R2014x and later. XSA replaces the SAM application.


Index

3

3DEXPERIENCE

schema 17

system info 17

3DEXPERIENCE menus 40

3DEXPERIENCE schema

attributes 36

methods 39

policies 37

programs 37

triggers 40

types 36

A

attribute ranges 50

displayed values 50

attributes

conversion 56

default values 51

mapping 51

value conversion 62

B

bill of material see BOM, EBOM, MBOM

BIN_PATH 15

BOM 92

relations 50

usage attribute 92

C

change object types 18, 54

checkin

prerequisites 15

checkout

prerequisites 15

configuration

attribute mapping 51

attribute ranges 50

date/time format 49

internationalization 50

SAP connection 47

connection interface 12

connection method 12

core TCL libraries 12, 38

customer-specific TCL libraries 12, 37

customization 61

ECO/CO/CA 54

mxsaprfc 63

procedure reference 62

D

date and time format 29

date format 49

3DEXPERIENCE 18

SAP 17

decimal separator 30

decimal symbol 18

default values 51

deployment 31

documents

linked original 55, 78

URL settings 55, 78

E

EBOM 93

ematrix.ini 15

ENG 94

Engineering Central support 14

enovia.ini 15

enovia.install 15

ERP 94

event triggers 57

F

file transfer

prerequisites 15

G

GUI see User Interface

H

help system 31, 59

files 44


I

incident reports 91

initialization files 15

installation

3DEXPERIENCE version 14

business objects 44

help system 31

initialization files 15

installer program 19

librfc 23

mxsaprfc 23

prerequisites 14

rich clients 34

SAP libraries 23, 26

SAP structure info 32

SAP version 14

sapjco 26

schema 28

TCL libraries 23

test plan 19

testing 32

uninstaller 34

war_setup/deployment 31

web interface 31

internationalization 60

J

JCO see SAP JCO

JSP 13, 43

L

LIB_PATH 15

libraries

architecture 61

core TCL 12, 38

customer-specific TCL 12, 37

customization rules 61

installation 23, 26

load test 90

SAP 13

SAP librfc 15

SAP librfc32 15

SAP sapjco 15

SAPSettings.tcl 52

TCL extension 13

librfc libraries 13, 15

log file 88

enable/disable 29

set destination 29

M

Matrix see 3DEXPERIENCE

matrix.ini 15

MBO 95

MBOM 55, 95

method programs 39

MXSAPDIR 29

mxsaprfc 13, 46

call function 64

close function 65

coding examples 68

connect parameter 65

export parameter 67

getprocess function 65

getthread function 65

handle parameter 65

help function 65

import parameter 67

open function 64

tables parameter 68

tcldebug parameter 68

mxsaprfc reference 63

mxsaprfc tracing 89

N

number format 30

P

PING SAP function 32

plant id

3DEXPERIENCE plant id 55

SAP plant number 55

plant list 50

plant mapping 55

platforms and versions 14

problem handling 87

properties 44

property files 44

R

revision handling 84

RFC access 46

RPE 96

S

SAM 96

SAP

BOM set-up 83

BOM usage 17

change mgmt set-up 84


connection info 17

custom function module 75

customization 74

DMS set-up 74

document type 17

plant list 17

revisions/versions 84

system id 17

user id 17

SAP Actions 13

SAP BOM usage 50

SAP connection 12, 48

client number 47

configuration 47

host 47

system ID 47

system number 47

user 47

SAP Download Structures function 32

SAP Info function 32

SAP JCO

Architecture 11

SAP libraries 13, 15

SAP PING function 32

SAP plant list 50

SAP plant number 55

SAP PowerView 13

SAP R/3 96

SAP RFC tracing 89

SAP structure information 32

SAP user 49

SAPFTP 15, 74

SAPHTTP 15, 74

sapjco libraries 13, 15

SAPSettings.tcl 52

schema

BOM relations 50

business objects 44

GUI components 40

menus and commands 40

T

TCL extension library 13

test plan 19

testing

interactive tests 33

library load test 90

SAP Info 32

SAP PING 32

time format 49

tool

MxS-ERP-Uninstall-Standard-EC-Integration.mql

34

trace file 88

enable/disable 29

set destination 29

trigger programs 40

triggered operation 57

troubleshooting 87

U

uninstall tool 34

user interface 94

installation 31

JSP 43

SAP Actions 13

SAP Powerview 13

V

version handling 84

W

war_setup 31

warutil 31

X

XSA 97

X-BOM Connector for SAP

Documents

Transcript of X-BOM Connector for SAP