Post on 30-Oct-2021
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 3 (v 20180925)
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: matrix-hotline@t-systems.com
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/
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 4 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 5 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 6 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 7 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 8 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 9 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 10 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 11 (v 20180925)
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:
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 12 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 13 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 14 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 15 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 16 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 17 (v 20180925)
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".
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 18 (v 20180925)
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)).
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 19 (v 20180925)
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).
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 20 (v 20180925)
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).
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 21 (v 20180925)
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.
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. 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).
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(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.
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(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).
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(PartMenu) [list type_Part]
set SAPConfig(ECOMenu) [list type_ECO]
set SAPConfig(ChangeOrderMenu) [list type_ChangeOrder]
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 22 (v 20180925)
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).
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(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.
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.
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).
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 23 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 24 (v 20180925)
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)
TCL Extension libraries: libmxsaprfc85.so
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)
TCL Extension libraries: libmxsaprfc85.so
SAP libraries: libicudata.so.34
libicui18n.so.34
libicuuc.so.34
librfcum.so
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 25 (v 20180925)
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
enovia.install file of the server installation.
Copy the TCL extension libraries from the installation package to the directory your
3DEXPERIENCE Platform administrative rich client uses for binary files.
o On Windows platforms the correct location is the BIN_PATH given in the
enovia.install file of the rich client ("Studio") installation.
o On Unix and Linux platforms the correct location is the LIB_PATH given in the
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.
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
enovia.install file of the server installation.
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.
o On Windows platforms the correct location is the BIN_PATH given in the
enovia.install file of the rich client ("Studio") installation.
o On Unix and Linux platforms the correct location is the LIB_PATH given in the
enovia.install file of the rich client ("Studio") installation.
For UNIX installations please check the libraries to make sure that the access rights are correct, it
should be chmod=755.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 26 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 27 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 28 (v 20180925)
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).
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 29 (v 20180925)
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:
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 30 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 31 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 32 (v 20180925)
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
Troubleshooting section of this guide to fix the problem.
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:
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 33 (v 20180925)
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
Troubleshooting section of this guide to fix the problem.
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 34 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 35 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 36 (v 20180925)
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
during the installation:
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 37 (v 20180925)
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
during the installation:
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 38 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 39 (v 20180925)
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)
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 40 (v 20180925)
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
during the installation:
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 41 (v 20180925)
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
menus defined in the
SAPConfig(ECOMenu) variable of
the installation script (usually, the
type_ECO tree).
SAPCOActions command The command added to the category
menus defined in the
SAPConfig(ChangeOrderMenu)
variable of the installation script
(usually, the type_ChangeOrder
tree).
SAPCAActions command The command added to the category
menus defined in the
SAPConfig(ChangeActionMenu)
variable of the installation script
(usually, the type_ChangeAction
tree).
SAPMCOActions command The command added to the category
menus defined in the
SAPConfig(MCOMenu) variable of
the installation script (usually, the
type_MCO tree).
SAPPartActions command The command added to the category
menus defined in the
SAPConfig(PartMenu) variable of
the installation script.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 42 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 43 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 44 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 45 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 46 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 47 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 48 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 49 (v 20180925)
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,
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 50 (v 20180925)
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.
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.
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 51 (v 20180925)
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).
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 52 (v 20180925)
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)
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 53 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 54 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 55 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 56 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 57 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 58 (v 20180925)
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".
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 59 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 60 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 61 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 62 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 63 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 64 (v 20180925)
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> ]
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 65 (v 20180925)
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] ...
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 66 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 67 (v 20180925)
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 |
SAP_INT[1|2] | SAP_NUMC | SAP_BCD
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 68 (v 20180925)
mxsaprfc Parameter Reference: tables
-tables { ( <NAME> <STRUCTURE> ) ... }
STRUCTURE ::= { { <NAME> <TYPE> <LENGTH> } ... }
TYPE ::= SAP_FLOAT | SAP_DATE | SAP_TIME | SAP_CHAR |
SAP_INT[1|2] | SAP_NUMC | SAP_BCD
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 } ...
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 69 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 70 (v 20180925)
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 }
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 71 (v 20180925)
{ 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 \
-connect { -3 -h sapsrv01 -c 001 -u myname -p mypwd -l EN } \
-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 {
{ PARAMCLASS SAP_CHAR 1 }
{ PARAMETER SAP_CHAR 30 }
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 72 (v 20180925)
{ 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 \
-connect { -3 -h sapsrv01 -c 001 -u myname -p mypwd -l EN } \
-export { FUNCNAME SAP_CHAR } \
-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 {
{ PARAMCLASS SAP_CHAR 1 }
{ PARAMETER SAP_CHAR 30 }
{ EXID SAP_CHAR 1 }
{ POSITION SAP_NUMC 4 }
{ OFFSET SAP_NUMC 6 }
}
mxsaprfc call RFC_GET_FUNCTION_INTERFACE_P \
-connect { -3 -h sapsrv01 -c 001 -u myname -p mypwd -l EN } \
-export { FUNCNAME SAP_CHAR } \
-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 }
{ TEXT2 SAP_CHAR 2 }
{ INT1 SAP_INT }
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 73 (v 20180925)
}
# 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 \
-connect { -3 -h sapsrv01 -c 001 -u myname -p mypwd -l EN } \
-export { IMP_STRUCT1 STRUCT_DESC } \
-export { IMP_NUM1 SAP_INT } \
-export { IMP_DATUM1 SAP_DATE }
set TABLE_STR_DESC {
{ TEXT1 SAP_CHAR 50 }
{ TEXT2 SAP_CHAR 2 }
{ INT1 SAP_INT }
}
set TABLE1 { { {This is long} xy 2049 } }
set IMP_CHAR1 "Nonsense"
mxsaprfc call Z_RFC2
-connect { -3 -h sapsrv01 -c 001 -u myname -p mypwd -l EN } \
-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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 74 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 75 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 76 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 77 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 78 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 79 (v 20180925)
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: √
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 80 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 81 (v 20180925)
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: "*.*"
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 82 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 83 (v 20180925)
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:
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 84 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 85 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 86 (v 20180925)
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 87 (v 20180925)
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?
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 88 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 89 (v 20180925)
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.
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.
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 90 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 91 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 92 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 93 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 94 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 95 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 96 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 97 (v 20180925)
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.
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 98 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 99 (v 20180925)
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
3DEXPERIENCE X-BOM Connector for SAP Administrator's Guide 100 (v 20180925)
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