Sie sind auf Seite 1von 212

Teamcenter Gateway for SAP Business Suite

Configuration Guide
Version 10.1

Integrated solutions for your product development

About this manual


This manual explains the configuration of the Teamcenter Gateway for SAP Business Suite (T4S)
V10.1.
This manual is part of the Teamcenter Gateway for SAP Business Suite documentation set. Please
see the following document for an overview of the documentation available:

Teamcenter_Gateway_for_SAP_Business_Suite-DocumentationOverview-V1010.pdf

The software is continually being enhanced. We reserve the right to add or modify functionality in a
way that is not consistent with the description in this manual as part of the routine maintenance
and enhancement process. We will do our best to keep this manual up to date to reflect those
changes.
Issue: September 2013

Legal notice:
All rights reserved. No part of this documentation may be copied by any means or made available
to entities or persons other than employees of the licensee of the Teamcenter Gateway for SAP
Business Suite or those that have a legitimate right to use this documentation as part of their
assignment on behalf of the licensee to enable or support usage of the software for use within the
boundaries of the license agreement.
TESIS PLMware GmbH 2002-2013

Trademark notice:
Siemens is a registered trademark of Siemens AG
Teamcenter is a registered trademark of Siemens Product Lifecycle Management Software Inc.
SAP, R/3 and mySAP are registered trademarks of SAP AG
Oracle is a registered trademark of Oracle Corporation
TESIS is a registered trademark of TESIS GmbH
TESIS PLMware is a registered trademark of TESIS PLMware GmbH
All other product names or designations may be trademarks or registered trademarks of their
respective owners.

TESIS PLMware

Introduction

Documentation Conventions:
The manual uses the following conventions:

A note gives important hints and technical background information and helps you taking
decisions later.

If several choices exist for an installation or operation step, we recommend a solution


that works best in most configurations. However you may choose another alternative
depending on your environment.

Cautions are important notes with crucial impact on the installation or operation of the
software

Prerequisites describe conditions that must be fulfilled before installation or operation


can continue

After some installation or operation step you should validate the result as described
here before proceeding

Teamcenter Gateway for SAP Configuration Guide V10.1

Table of Contents
1

Introduction ....................................................................................... 9

Configuring T4S to support customer specific requirements ..... 10

2.1

Configuring the object types to transfer by T4S .............................................. 14

2.2

2.3

2.4

2.5

2.1.1

Define Teamcenter object types to use with T4S ................................................. 14

2.1.2

Configuring supported objects and the T4S user interface (GUI) ......................... 14

2.1.3

Define Teamcenter objects you want to support in the T4S GUI.......................... 14

2.1.4

Define the attributes you want to see in a T4S transfer window ........................... 15

2.1.5

Choose the T4S menu functions (transaction types between Teamcenter and
SAP).................................................................................................................... 22

General Data Mapping Functionality ................................................................. 26


2.2.1

Overview ............................................................................................................. 26

2.2.2

How to modify the mapping ................................................................................. 34

2.2.3

The file t4s_mapping_config.sd ........................................................................... 37

2.2.4

Basics for standard transactions (initiated from within Teamcenter) .................... 39

2.2.5

Direct Mapping of Constants ............................................................................... 45

2.2.6

Obtaining special Teamcenter information: database and user ........................... 46

Configuration of MM data mapping from Teamcenter to SAP ........................ 47


2.3.1

Configuration of MM data mapping from Teamcenter to SAP .............................. 47

2.3.2

Definition of MM data mapping from Teamcenter to SAP .................................... 49

2.3.3

Mapping of additional MM data............................................................................ 51

2.3.4

Configuration of MM data mapping from SAP to Teamcenter (reverse mapping) 55

2.3.5

Definition of MM data mapping from SAP to Teamcenter (reverse mapping)....... 57

Document Info Record data mapping ............................................................... 59


2.4.1

Configuration of DIR data mapping from Teamcenter to SAP .............................. 60

2.4.2

Simplified DIR data mapping configuration from Teamcenter to SAP .................. 65

2.4.3

Definition of DIR data mapping from Teamcenter to SAP .................................... 66

2.4.4

Configuration of DIR data mapping from SAP to Teamcenter (reverse mapping) 69

2.4.5

Definition of DIR data mapping from SAP to Teamcenter (reverse mapping) ...... 70

Bill of Material Data Mapping ............................................................................. 71

TESIS PLMware

Introduction

2.6

2.7

2.8

2.9

2.5.1

Configuration of BOM data mapping from Teamcenter to SAP ............................ 71

2.5.2

Definition of BOM data mapping from Teamcenter to SAP .................................. 74

2.5.3

Important notes on modifying a SAP BOM .......................................................... 77

2.5.4

Mapping of additional BOM data: Occurrence Notes ........................................... 79

2.5.5

Configuration of BOM data mapping from SAP to Teamcenter (reverse mapping)


............................................................................................................................ 80

2.5.6

Definition of BOM data mapping from SAP to Teamcenter (reverse mapping) .... 80

Engineering Change Master Data Mapping ...................................................... 81


2.6.1

Configuration of ECM data mapping from Teamcenter to SAP ............................ 82

2.6.2

Definition of ECM data mapping from Teamcenter to SAP .................................. 82

2.6.3

Configuration of ECM data mapping from SAP to Teamcenter (reverse mapping)


............................................................................................................................ 83

2.6.4

Definition of ECM data mapping from SAP to Teamcenter (reverse mapping) ..... 83

2.6.5

Handle ECM with different object types ............................................................... 84

2.6.6

Create the ECM as a copy of an existing ECM .................................................... 85

Transfer of Equipment data................................................................................ 87


2.7.1

Configuration of Equipment data mapping from Teamcenter to SAP ................... 87

2.7.2

Definition of Equipment data mapping from Teamcenter to SAP ......................... 87

2.7.3

Configuration of Equipment data mapping from SAP to Teamcenter (reverse


mapping) ............................................................................................................. 88

2.7.4

Definition of Equipment data mapping from SAP to Teamcenter (reverse mapping)


............................................................................................................................ 89

Transfer of Functional Location data ................................................................ 90


2.8.1

Configuration of Functional Location data mapping from Teamcenter to SAP ..... 90

2.8.2

Definition of Functional Location data mapping from Teamcenter to SAP ........... 91

2.8.3

Configuration of Functional Location data mapping from SAP to Teamcenter


(reverse mapping) ............................................................................................... 91

2.8.4

Definition of Functional Location data mapping from SAP to Teamcenter (reverse


mapping) ............................................................................................................. 92

Transfer of Vendor data ...................................................................................... 93

Teamcenter Gateway for SAP Configuration Guide V10.1

2.10

2.9.1

Configuration of Vendor data mapping from Teamcenter to SAP ........................ 93

2.9.2

Definition of Vendor data mapping from Teamcenter to SAP ............................... 94

2.9.3

Configuration of Vendor data mapping from SAP to Teamcenter (reverse


mapping) ............................................................................................................. 94

2.9.4

Definition of Vendor data mapping from SAP to Teamcenter (reverse mapping) . 94

Transfer of Purchase Info Record (PIR) data .................................................... 95


2.10.1 Configuration of PIR data mapping ...................................................................... 95
2.10.2 Definition of PIR data mapping from Teamcenter to SAP .................................... 96
2.10.3 Definition of PIR data mapping from SAP to Teamcenter (reverse mapping)....... 96

2.11

Transferring manufacturing data general overview ...................................... 97


2.11.1 Transferring Standard Routing from Teamcenter PLMXML to SAP ..................... 97
2.11.2 Transferring Inspection Plan from Teamcenter PLMXML to SAP ........................ 97
2.11.3 Transferring Manufacturing BOM from Teamcenter PLMXML to SAP ................. 97
2.11.4 Transferring Production Order data from SAP to Teamcenter ............................. 97

2.12

Transfer of Standard Routing data .................................................................... 98


2.12.1 Configuration of routing data mapping from Teamcenter to SAP ......................... 98
2.12.2 Definition of Routing data mapping from Teamcenter to SAP ............................ 101
2.12.3 Configuration of Routing data mapping from SAP to Teamcenter (reverse
mapping) ........................................................................................................... 102

2.13

Transfer of network/WBS data ......................................................................... 103


2.13.1 Limitations and requirements ............................................................................ 103
2.13.2 Transfer of network data mapping from Teamcenter to SAP ............................. 104
2.13.3 Transfer of WBS data mapping from Teamcenter to SAP.................................. 106
2.13.4 Configuration of network data mapping from SAP to Teamcenter ..................... 107
2.13.5 Configuration of WBS data mapping from SAP to Teamcenter .......................... 108

2.14

Work breakdown Structure Bill of Material Data Mapping............................. 110

2.15

Transfer of Generic Objects ............................................................................. 110


2.15.1 Configuration of Generic data mapping from Teamcenter to SAP ..................... 110
2.15.2 Definition of Generic data mapping from Teamcenter to SAP ............................ 111
2.15.3 Configuration of Generic data mapping from SAP to Teamcenter (reverse
mapping) ........................................................................................................... 112
2.15.4 Definition of generic data mapping from SAP to Teamcenter (reverse mapping)112

2.16

Generic BOM Data Mapping ............................................................................. 113

TESIS PLMware

Introduction

2.16.1 Configuration of Generic BOM data mapping from Teamcenter to SAP ............ 113
2.16.2 Definition of Generic BOM data mapping from Teamcenter to SAP ................... 115
2.16.3 Configuration of Generic BOM data mapping from SAP to Teamcenter (reverse
mapping) ........................................................................................................... 115
2.16.4 Definition of Generic BOM data mapping from SAP to Teamcenter (reverse
mapping) ........................................................................................................... 115

2.17

Data Transfer without triggering it from within Teamcenter ......................... 117


2.17.1 General Import steps ......................................................................................... 117
2.17.2 Monitor SAP staging table (ZPTC) .................................................................... 119
2.17.3 Supported types for Import ................................................................................ 128
2.17.4 Import Mapping ................................................................................................. 130

2.18

Obtaining Teamcenter runtime properties from SAP .................................... 133


2.18.1 Configuring runtime properties for the material master ...................................... 133
2.18.2 Using runtime properties for the Material Master ............................................... 134

2.19

SAP Data View within the T4S Rich Client extension .................................... 138

2.20

Create a Teamcenter List of Values (LOV) with T4S ...................................... 149


2.20.1 Configure a Teamcenter LOV for T4S use ........................................................ 149
2.20.2 Definition of data mapping for a Teamcenter LOV ............................................. 150

2.21

Workflow Handler Functions............................................................................ 152


2.21.1 T4S rule handlers .............................................................................................. 153
2.21.2 T4S action handlers .......................................................................................... 157
2.21.3 Important Teamcenter handlers used by T4S standard workflows ..................... 170

2.22

Deprecated Configuration Functionality ......................................................... 172

2.23

Use of BMIDE Conditions (CLIPS) for configuration of rules........................ 175

How to provide Teamcenter and SAP account information ....... 177

3.1

Storing Teamcenter account information in plain text format ...................... 177

3.2

Storing SAP account information in plain text format ................................... 178

3.3

Storing SAP account information for more than one SAP account to be used
in a workflow ..................................................................................................... 181

3.4

Storing Teamcenter account information in encrypted format ..................... 183

3.5

Storing SAP account information in encrypted format.................................. 185

Troubleshooting a T4S Installation ............................................. 186

4.1

Some SAP Error Messages and how to handle them .................................... 189

Teamcenter Gateway for SAP Configuration Guide V10.1

UI based mapping tool.................................................................. 191

5.1

Create a sub mapping in the T4S Mapping Tool ............................................ 193

5.2

The T4S Mapping Tool menu bar ..................................................................... 195


5.2.1

File .................................................................................................................... 195

5.2.2

Sub mapping ..................................................................................................... 196

5.2.3

Extras ................................................................................................................ 197

5.3

The Drawing Panel ............................................................................................ 198

5.4

Operators ........................................................................................................... 201

Basics on the script language TCL ............................................. 202

6.1

TCL procedures................................................................................................. 202

6.2

Output Functions .............................................................................................. 203

6.3

Namespaces ...................................................................................................... 204

6.4

Variables ............................................................................................................ 205

6.5

List Variables ..................................................................................................... 207

6.6

Data Arrays ........................................................................................................ 207

6.7

Some important TCL functions ........................................................................ 207

6.8

Traps to avoid in TCL ....................................................................................... 209

TESIS PLMware

Introduction

Introduction

The Teamcenter Gateway for SAP Business Suite (T4S) software solution is a general purpose
integration software that provides data and process integration between Teamcenter by Siemens
PLM and SAP R/3 / SAP ERP by SAP AG.
T4S provides a wide range of interactive and workflow functions to transfer and synchronize data
between Teamcenter and SAP.
The main functions in the current version cover the following SAP functional areas:

SAP materials management

SAP document management

SAP bill of materials management

SAP change management

SAP equipment management

SAP functional location management

SAP routing management

SAP network management

SAP vendor management

SAP purchase info record management

You can adapt the individual T4S functions to your requirements by applying specific modifications
to the data mapping process. The steps are described in detail in the T4S manuals.
For more information on new components and new versions of T4S visit www.tesis.de.

Teamcenter Gateway for SAP Configuration Guide V10.1

Configuring T4S to support customer specific


requirements

The T4S installation has been successfully completed

The connection to both Teamcenter and SAP has been verified to work properly; see
"Teamcenter Gateway for SAP Business Suite Installation Guide" for details

Starting with T4S release 7.1, T4S mapping can be configured using a GUI based mapping tool in
addition to the script-based mapping definition, see chapter UI based mapping tool starting on p.
191.
The GUI based mapping tool facilitates the definition of typical mapping situations but is not meant
to cover every possible scenario. Therefore, the mapping files produced by this tool are modifiable,
using the script-based methods as described in chapter General Data Mapping Functionality
starting on p. 26.
Preparing T4S manually (not with the GUI based mapping tool) for a certain transfer type (MM,
BOM, DIR, etc.) consists of two steps:
1. Modifying Teamcenter preferences to describe which Teamcenter data is necessary for the
transfer or should be displayed in the GUI. This step is called Configuration in this
document.
2. Adapting the TCL program code dedicated to this type of transfer, mainly to define the
mapping between Teamcenter and SAP fields. This step is called Definition of the
mapping in this document.
The basic configuration of T4S is done by adding certain keys to the Teamcenter preferences
(Teamcenter My Teamcenter Edit Options) that are stored in the database itself. Some
T4S preferences have been imported while installing T4S using the Teamcenter Environment
Manager (tem), see T4S Installation Guide. Unless stated differently, every configuration key
described in this document is valid for every supported Teamcenter version.

In order to perform large modifications, do not modify each preference directly in Teamcenter
but do the following:

10

export your existing Teamcenter preferences

create a backup of the export file

modify all the affected preferences in that file according to your needs

delete all the other (unmodified) preferences from that file

import the modified file to Teamcenter as described below

TESIS PLMware

Configuring T4S to support customer specific requirements

There are three different ways to modify the Teamcenter configuration:

Using an XML file with the preferences, see the Teamcenter Utility documentation for the
utility preferences_manager or chapter How to modify the Teamcenter preferences in the
T4S FAQ (document Teamcenter_Gateway_for_SAP-FAQ)

Import saved Teamcenter preferences from a file that may have been exported from
another Teamcenter installation. In the Rich Client in the application My Teamcenter,
select the menu Edit Options:

The following screen shot and the corresponding description is from Teamcenter 8. It
looks slightly different in Teamcenter 9 and pretty much different in Teamcenter 10.
Especially the menu point to click first from here is not called Index but Filters.

In the lower left part, click Index


In the lower right part of the window, click Import
Click on the Browse button (the three dots) on the right of the Import file name field
and browse to the xml file with your customized T4S preference definition.
Select the other options as shown in the screenshot (Site, Automatic, and Merge):

Teamcenter Gateway for SAP Configuration Guide V10.1

11

In the lower right part of the window, click Import and wait some seconds until it is
ready (status in the lower left corner will switch from Importing to Ready)
If you have group or role specific T4S preferences (user specific preferences are not
supported), do the same with these: be sure to have only these in the import XML file
and select the appropriate Scopes during the import. T4S also handles group and role
preferences but in order to not allow Teamcenter users giving themselves more rights
than defined by an administrator (e.g. adding a T4S transaction type like BOM Change
in the SAP GUI), T4S does not handle user preferences

By creating the preferences with the GUI-based schema extractor, see separate
documentation: Teamcenter Gateway for SAP Business Suite Schema Extractor Guide

12

Restart Teamcenter in order to activate the modification. Then, T4S is ready to work,
that means you should find the additional menu Teamcenter Gateway with some sub
menus in the Teamcenter GUI.

TESIS PLMware

Configuring T4S to support customer specific requirements

Define the required T4S preferences carefully. Only define and import preferences that
are required to support your custom types and use cases. Do not import the sample file
that T4S provides in <T4S_ROOT>\var\template\t4s. That is only for your information and
an example reference.

Teamcenter Gateway for SAP Configuration Guide V10.1

13

2.1 Configuring the object types to transfer by T4S

2.1.1

This chapter is supposed to show the general functionality. As an example the Material
Master (MM) transfer is shown here; it works the same for other types (DIR, BOM)

Define Teamcenter object types to use with T4S

The following preferences define which Teamcenter object types are allowed to be used by T4S
regarding the desired SAP object type. In any case, T4S only supports the Revision, not the
Item itself, no matter of which Item Type they are:
T4S_MaterialMasterTypeList=
SAP2_T4S_Item Revision
SAP2T4S_AttrItemRevision

This means, T4S will only use Teamcenter data objects of types like SAP2_T4S_Item Revision
and SAP2T4S_AttrItemRevision for the Material Master functionality.

2.1.2

If you do not want to support some functionality for a specific object type at all (e.g. the
reverse mapping), do not leave the appropriate preference out, but set it empty (i.e.
set it without any value). The preferences described in the following chapters have to be
set for all the object types defined in the TypeList preference

Configuring supported objects and the T4S user interface (GUI)

The T4S user interface is built as a Java extension to the Teamcenter GUI and is contained in
the T4S jar files. You can adapt the T4S user interface to suit your requirements. For example, you
can remove functions from the menu which you do not require. These functions have to be
specified for each data type separately in the Teamcenter preferences; see the following chapters
for details.
The examples below show the possibilities for the material master handling; it works accordingly
for the other SAP object types.

2.1.3

Define Teamcenter objects you want to support in the T4S GUI

The most important is the key T4S_MaterialMasterDisplayableTypeList=. This is a


subset of the values of T4S_MaterialMasterTypeList= and means that T4S only has to use
these types in the GUI. If the key T4S_MaterialMasterDisplayableTypeList= is not
present or empty, T4S will use every type defined in the TypeList.

14

TESIS PLMware

Configuring T4S to support customer specific requirements

Example:
T4S_MaterialMasterDisplayableTypeList=
SAP2_T4S_Item Revision
T4S_MaterialMasterTypeList=
SAP2_T4S_Item Revision
SAP2T4S_AttrItemRevision

This means: allow SAP2_T4S_Item Revision and SAP2T4S _AttrItemRevision for the T4S
Material Master transactions, but only show SAP2_T4S_Item Revision in the T4S GUI. This might
be useful if you want to allow more types in the workflows than in the GUI.

2.1.4

Define the attributes you want to see in a T4S transfer window

Since V9.1, T4S uses Teamcenter style sheets to display additional data in the T4S transfer
window. For more details on the usage and definition of style sheets in Teamcenter please check
the Teamcenter manual. Set the following preferences (see examples below) to define

The symbolic names of the style sheets T4S should use:


T4S.AttributesStylesheets

The actual names of the datasets T4S should use (the names of Teamcenter Datasets of
type XMLRenderingStylesheet, each containing one style sheet as an XML file; same
way as Teamcenter itself uses it internally):
T4S.AttributesStylesheets.<symbolic_name>.Rendering
This preference is optional. If not set, T4S uses the symbolic name as the Dataset name
(i.e. the actual Teamcenter Dataset name must be the same as the defined symbolic name)

Which of these style sheets T4S should use with which


o

Teamcenter object types:


T4S.AttributesStylesheets.<symbolic_name>.Types

SAP connections:
T4S.AttributesStylesheets.<symbolic_name>.EaConnections

SAP object types:


T4S.AttributesStylesheets.<symbolic_name>.EaObjectTypes

All these three preferences are optional: any one that is set is part of the decision which
style sheet will be used. If none of these preferences fits to your current transaction (the
combination of selected Teamcenter object type, SAP object type, SAP connection), T4S
will use the Teamcenter default style sheet for the selected object (e.g. the
ItemRevSummary for an Item Revision of any Item type)
If the current Teamcenter object is not specified in the Types preference explicitly but there is a
Types preference for another type that has a common super type with the current object, then that
one will be used.

Teamcenter Gateway for SAP Configuration Guide V10.1

15

Example:

16

Your Teamcenter data model has an Item Type MyTypes with the sub types MyType1
and MyType2

There is a Types preference defined for MyType1 but none for MyType2

You select an Item Revision of type MyType2 and open a T4S transfer window by
selecting any transaction type for this object type from the T4S Gateway menu

Then the T4S GUI will search for the a Types preference for the selected object and not
find it, but find the one for MyType1, so it will use the style sheet defined in that Types
preference

The names EaConnections and EaObjectTypes are named like that because T4x
could use it with other systems than SAP; in this context, EA means Enterprise
Application

For the same reason (T4x uses it for other products than T4S, too), the values for the
EaObjectTypes preferences are not exactly the same as in other T4S preferences;
please check the valid entries from this list:
Material
Document
BillOfMaterial
Change
Equipment
FunctionalLocation
Vendor

Although all the other T4S preferences start with T4S (or T4X, respectively) and an
underscore (e.g. T4S_MaterialMasterTypeList), the new GUI preferences use a dot
instead, and they need dots to separate the single name parts, too, e.g.
T4S.AttributesStylesheets.T4S_StyleSheet_1.Types
This is because a name may contain underscores whereas a dot is a separator for the
single parts of the complete preference name

TESIS PLMware

Configuring T4S to support customer specific requirements

Example:
T4S.AttributesStylesheets=
T4S_StyleSheet_Material_1
T4S_StyleSheet_Material_2
T4S_StyleSheet_BOM
T4S_StyleSheet_Dataset
T4S.AttributesStylesheets.T4S_StyleSheet_Material_1.Types=
SAP2_T4S_Item Revision
SAP2T4S_AttrItemRevision
T4S.AttributesStylesheets.T4S_StyleSheet_Material_2.Types=
ManufacturerPart Revision
T4S.AttributesStylesheets.T4S_StyleSheet_Dataset.Types=
MSWord
PDF
T4S.AttributesStylesheets.T4S_StyleSheet_Material_1.EaConnections=
ET1@800
T4S.AttributesStylesheets.T4S_StyleSheet_Material_1.EaObjectTypes=
Material
Then define the style sheets in Teamcenter:

Open any of the Teamcenter default style sheet Datasets and export its xml file for your
reference how to set it up, e.g. the ItemRevSummary (find it by using the Teamcenter
Dataset query with that name or the Dataset type XMLRenderingStylesheet)

Adapt this exported xml file to your needs and save it with a new name, e.g.
MyMaterialStylesheet

Create a Dataset named as you stated in the preferences (e.g.


T4S_StyleSheet_Material_1 from the examples above) and import the xml file to it

From TC 9.1 onwards, there is a folder "StyleSheetCache" where these style sheet
Datasets have to be stored in (so you may search for the folder and find all the style sheets
instead of searching the Datasets as described above); in earlier TC versions, just leave
them unreferenced

Repeat these two steps (create xml file and create Dataset with that file) for each style
sheet you want to use

Restart Teamcenter in order to see any modification

Teamcenter Gateway for SAP Configuration Guide V10.1

17

T4S can show the following data in the T4S transfer window:

the data belonging to the selected object

compound properties, see below

data of any object related to the current object, e.g. data on a Teamcenter form (if it is
related to the current object, e.g. the Item Revision master form), see below

Using data on an object related to the current object is less adaptation effort and it works
much faster than the compound properties because these use Teamcenter runtime
properties

The T4S migration tool can create the style sheets and needed preferences
automatically from the old preferences
T4S_<object_type>ListOfDisplAttributes4*
see Teamcenter Gateway for SAP Business Suite Migration Guide for details

Example for a style sheet section (in the xml file you created from the Teamcenter default style
sheet, just modify the sections with the property lines, e.g. <property
name="object_string"/>; not shown completely here because the lines are very long, so it
would look rather strange here with the many line breaks; see complete example below):
<property name="object_string"/>
<property name="sap2SAPMatNo"/>
<property source="IMAN_master_form_rev.SAP2_T4S_Item Revision
Master" name="SentMMToSAP"/>
<property source="IMAN_master_form_rev.SAP2_T4S_Item Revision
Master" name="SAP2OldMatNo" modifiable="true"/>
This defines to show

the object_string of the current object (so no property source is given)

the sap2SAPMatNo which is a compound property of the current object, see below

two attributes from the SAP2_T4S_Item Revision Master form

The parameters are

18

property name (or just name if it is not the first part in property): the attribute/property
name on the current object, or a compound property

property source: the object with the relation from the current object if the data is stored
on another object

modifiable (optional): if set to true, you may modify the attribute in the T4S transfer
window and it will be stored to Teamcenter (see below for details)

TESIS PLMware

Configuring T4S to support customer specific requirements

Note that there is no parameter for defining how to show it in Teamcenter; this is
determined automatically from the attribute/property using the Teamcenter multi language
functionality

Example for such a line that will show the attribute SAP_DirNo of the
T4S_DatasetExtensionForm after you selected a Dataset (instead of an Item Revision) when
opening the T4S transfer window:
<property source="ref_list.T4S_DatasetExtensionForm" name="SAP_DirNo"/>
Complete example for a style sheet defining Teamcenter data to be shown in the T4S transfer
window (see detailed descriptions above):
<?xml version="1.0" encoding="UTF-8"?>
<!-============================================================================
Copyright (c) 2003-2005 UGS Corporation
Unpublished - All Rights Reserved
============================================================================
Filename: t4s_demo_stylesheet.xml
-->
<rendering xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="XMLRenderingStylesheet_Schema.xsd">
<header>
<image source="thumbnail"/>
<classificationTrace/>
<property name="owning_user"/>
<property name="last_mod_date"/>
<property name="release_status_list"/>
<property name="object_type"/>
</header>
<page text="Overview" format="TwoColumn">
<firstcolumn>
<section text="Item Revision Properties">
<property name="object_desc"/>
<property name="items_tag"/>
<separator/>
<property source="item" name="object_name"/>
<property source="IMAN_master_form_rev.SAP2_T4S_Item Revision
Master" name="SAPMatNo"/>
<property source="IMAN_master_form_rev.SAP2_T4S_Item Revision
Master" name="SentMMToSAP" modifiable="false"/>

Teamcenter Gateway for SAP Configuration Guide V10.1

19

<property source="IMAN_master_form_rev.SAP2_T4S_Item Revision


Master" name="SAPChangeNo" modifiable="false"/>
<property source="IMAN_master_form_rev.SAP2_T4S_Item Revision
Master" name="SAP2Unit" modifiable="true"/>
<property source="IMAN_master_form_rev.SAP2_T4S_Item Revision
Master" name="SAP2OldMatNo" modifiable="true"/>
<property source="IMAN_master_form_rev" name="SAP2Unit"/>
</section>
</firstcolumn>
</page>
</rendering>

To navigate through several objects in the property source parameter, use the same
syntax as in the mapping:
RELATION1.TARGETTYPE1:RELATION2.TARGETTYPE2...
Example:
<property source="structure_revisions.SAP2_T4S_Item Revision:
IMAN_master_form_rev. SAP2_T4S_Item Revision Master" name=" SentBOMToSAP"
modifiable="false"/>

The relation structure_revisions in above example is just a pseudo relation to navigate


from a BOM View Revision to the corresponding Item Revision. Pseudo relation means
that it is not a genuine Teamcenter data model relation. Whenever T4S gets this relation
name, the target object is not determined in the usual way by navigating the actual
Teamcenter relation but searching the Item Revision corresponding to this BOM view

T4S allows using the wildcard * in the relation names

T4S allows using the wildcards * and ? in the target type names

Example for using wildcards: :


<property source="structure_revisions.*:*.SAP2_T4S_Item Revision Master"
name="SentBOMToSAP" modifiable="false"/>

You may define an object type explicitly (e.g. SAP2_T4S_Item Revision Master
in the example above), then it will be used for that only, or set a place holder for all the
types of the same type class, e.g. as shown above:
<property source="item" name="object_name"/>
<property source="IMAN_master_form_rev" name="SAP2Unit"/>

In order to use Compound Properties, define them in Teamcenter using BMIDE. Please read
the Teamcenter BMIDE manual for details. The following screen shot shows an example of the
definition for sap2SAPMatNo that can be used to show the SAP material number in the T4S
transfer window:

20

TESIS PLMware

Configuring T4S to support customer specific requirements

After this is defined and deployed, you may use it. This example and additionally
sap2SentMMToSAP for a transfer status (e.g. OK or Error and a timestamp) are included in
the t4sdemo tem feature; see "Teamcenter Gateway for SAP Business Suite Installation Guide"
for details how to use tem and BMIDE with T4S. Then the T4S transfer window looks like that:

Teamcenter Gateway for SAP Configuration Guide V10.1

21

2.1.5

Choose the T4S menu functions (transaction types between Teamcenter and
SAP)

Modify the preference T4S_Gateway_Menu_Explorer_Entries in order to set the available


functions in the additional T4S menu T4S Gateway in My Teamcenter. This does not affect the
workflow functionality but only specifies the functions the user may select from the menu.
Without having to do any additional adaptations, the same menu T4S Gateway will be shown in
the Structure Manager, the Multi Structure Management and the Manufacturing Process
Planer.
Each value for this preference consists of two parts:

The object type it is used for

The function for this object type

Example (see more examples below): the value for displaying an SAP material master (MM) is
MM_DISPLAY
The possible object types are:

MM Material Master

BOM Bill of Material

DIR Document Info Record

ECM Engineering Change Master

EQUI Equipment Master

FCL Functional Location

VENDOR Vendor
Please not that for the time being, the only Vendor management transaction type T4S
supports in the Portal is display; the mere processing works in the Workflow only

The possible functions are (in brackets: the object type(s) this function works for):

22

CREATE (all except PIR and Vendor) creates an object of the desired type in SAP with
the SAP GUI (i.e. a SAP window opens where you can enter data manually). In this case,
you can also use SAPs function to create an object from a template (MM, ECM and
Functional Location: Copy from; DIR: Template; Equipment: Reference; not possible
for BOM)

CHANGE (all except PIR and Vendor) modifies the SAP object with the SAP GUI

CREATE_HID (all except PIR and Vendor) creates an object of the desired type in SAP
without the SAP GUI (i.e. no SAP windows opens)

CHANGE_HID (all except PIR and Vendor) modifies the SAP object without the SAP GUI

DISPLAY (all except PIR) displays the SAP object in the SAP GUI

HTTP_DISPLAY (all) displays the SAP object in the SAP GUI for HTML; the base URL of
the SAP system needs to be defined in the mapping (see Note and example on page 25).
TESIS PLMware

Configuring T4S to support customer specific requirements

RESERVE (MM) gets the next valid Material Master number from SAPs number
generator (internal numbering) and stores this for further usage. Caution: this does not
prevent that anyone creates a SAP MM with this number if he states it explicitly, but it tells
SAP not to give this number again if it is asked for a new one

LINK (all except BOM, PIR and Vendor) tells T4S to use a corresponding SAP object with
a stated identification. Actually, it allows the user to search for a data object in SAP and
stores its ID (and any other desired data) in the Teamcenter attribute stated in the mapping
file. Same as in any other case with T4S, SAP does not recognize a relation

LINKVIACLASS (MM) - same as "Link" but looks for an MM with specifiable characteristic
values in a SAP class instead of searching an MM ID. This is done by calling "Find Objects
in Classes" in SAP. Please check SAP documentation on details

PSB (MM, BOM, DIR, ECM) Opens the Product Structure Browser in SAP

HTTP_PSB (MM, BOM, DIR, ECM, EQUI, FLC) Opens the Product Structure Browser
in SAP GUI for HTML; the base URL of the SAP system needs to be defined in the
mapping.

Each function uses the mapping (described later in chapter General Data Mapping
Functionality starting on page 26) and sets the appropriate data to the SAP object and
to the Teamcenter object.

If a transaction type is specified for an object type that does not allow that (e.g. PSB for
EQUI) this will be shown in the menu nevertheless without showing an error to the
Teamcenter user. If this invalid transaction is performed, an error message is shown.

If at least one entry for a specific type (e.g. Material Master) is given, the
corresponding sub menu will appear; e.g. the entry MM_DISPLAY is sufficient to show
the sub menu Material Master in the T4S Gateway menu. If that preference
does not contain any entry MM_*, then the sub menu Material Master is not
shown at all

If that preference does not exist or is set empty then the menu point
SAP Connections... is shown only

The T4S Gateway menu can be switched off completely by setting the following
preference (type logical; by default it does not exist):
T4S.UI.GatewayMenu.Hide=true

The same preference exists for each T4x product (e.g.


T4S.UI.GatewayMenu.Hide). If there is more than one T4x product installed in the
same Teamcenter installation, it may be useful to switch all the T4x Gateway menus
off and on with one preference only: T4X.UI.GatewayMenu.Hide=true

If this is set, it will deactivate all the T4x Gateway menus, but if the preference
T4S.UI.GatewayMenu.Hide=false is set additionally, the T4S Gateway menu will
be shown (all other T4x Gateway menus remain hidden).

Teamcenter Gateway for SAP Configuration Guide V10.1

23

Example:
T4S_Gateway_Menu_Explorer_Entries=
SAPCONNECT
MM_CREATE_HID
MM_CHANGE_HID
MM_DISPLAY
MM_RESERVE
MM_LINK
MM_PSB
BOM_DISPLAY
BOM_PSB
DIR_CREATE_HID
DIR_CHANGE_HID
DIR_DISPLAY
VENDOR_DISPLAY

In the T4S Gateway menu, you will then find the corresponding entries, e.g. for DIR: Create
direct, Change direct and Display. If you click such a menu point after selecting one or multiple
valid objects, T4S will open the T4S transfer window that shows the configured data for this
object and transaction type (see chapter Define the attributes you want to see in a T4S on p. 15 for
details) and you can start the transaction by clicking Perform or Perform all. If you do not want
to wait and click, you can configure T4S to start some transactions immediately using the
preference T4S_Gateway_AutoPerform. Whenever a transaction type stated as a value of this
preference is selected from the T4S Gateway, the T4S transfer window is opened and the
transaction will start immediately without waiting for the click on Perform.
Example as shipped in the template file, i.e. all these Display transactions will be started
automatically, any other will wait for the click on Perform:
T4S_Gateway_AutoPerform=
MM_DISPLAY
BOM_DISPLAY
DIR_DISPLAY
ECM_DISPLAY
EQUI_DISPLAY
FCL_DISPLAY

24

TESIS PLMware

Configuring T4S to support customer specific requirements

The configuration of the SAP GUI for HTML feature (e.g. preference entry
MM_HTTP_DISPLAY) needs an additional configuration step in the
t4s_mapping_config.sd for the corresponding SAP backend system. This configuration
is done by the function call ::T4S::CONNECTION2SAP::storeWebGuiConfig. With
this call it is possible to configure the base URL of the SAP GUI for HTML and if the
URL should be displayed in the context of the SAP Enterprise Portal, more details
regarding the parameters can be found in the API documentation.

Example Configurations for the SAP GUI for HTML:


# -------------------------------------------------# In this case we store the base URL for SAPGUI for HTML configuration for the
# SAP system ET1 and client 800
# -------------------------------------------------::T4S::CONNECTION2SAP::storeWebGuiConfig ET1 800 \
"http://sapsrv.tesis.de:8020/sap/bc/gui/sap/its/webgui?~transaction="

# -------------------------------------------------# In this case we store the base URL for SAP Enterprise Portal configuration for
# the SAP system ET2 and client 800
# -------------------------------------------------::T4S::CONNECTION2SAP::storeWebGuiConfig ET2 800 \
"http://sapep2.tesis.de:50000/irj/portal?NavigationTarget=ROLES://portal_content/T
ESIS/sap_transaction_iview&System=de_tesis_ET2_800&TCode=" true

# -------------------------------------------------# In this case we store the base URL for SAP Enterprise Portal configuration for
# the SAP system ET2 and client 800 and we configure that we use the native SAPGUI
# to start the SAP transaction
# -------------------------------------------------::T4S::CONNECTION2SAP::storeWebGuiConfig ET2 800 \
"http://sapep2.tesis.de:50000/irj/portal?NavigationTarget=ROLES://portal_content/T
ESIS/sap_transaction_iview&System=de_tesis_ET2_800&TCode=" true WinGui

Teamcenter Gateway for SAP Configuration Guide V10.1

25

2.2 General Data Mapping Functionality


2.2.1

Overview

T4S provides a simple environment based on the script language TCL for the mapping of data
between the systems (Teamcenter and SAP). A very useful help on TCL can be found on the
following Internet page: http://www.tcl.tk/man/tcl8.5/TclCmd/contents.htm
An introduction to the most relevant TCL functions and their usage can be found in Basics on the
script language TCL on page 202 ff.
Modifying the T4S mapping always consists of these steps:
1. Set Teamcenter preferences to configure the Teamcenter objects whose data T4S should
read from Teamcenter or may write to, respectively
2. Specify the mapping (define the handling of the data, e.g. which Teamcenter attribute gives
data to which SAP field and vice versa) in the mapping files
3. Create the compilation of all mapping source files: t4s_mapping_config.rfdt
4. Move this file to <T4S_ROOT>\lib
5. Restart T4S
You can use the batch template <T4S_ROOT>\etc\t4s_build_mapping.bat.template
to compile the mapping and move the rfdt file to the lib directory in one step.
In order to use it from the operating system directly:

In Windows: Just remove the .template from the file extension

In UNIX/Linux, define it as an executable file (the file extension does not matter)

Or use the mapping hot deploy, see below.


Generally, there are three kinds of data T4S can read from Teamcenter:

Any attribute that is stored in a Teamcenter form, e.g. the standard Item Revision Master Form

The properties of an object, e.g. item_id, item_revision_id, object_desc, release date

Classification data as defined in the Teamcenter classification application

All definitions for the mapping have to be done in the T4S mapping source files. By default, every
one of them contains all the definitions for one SAP object type and is named with that type, see
following list. All the mapping files T4S has to use have to be located in the directory
<T4S_ROOT>\var\mmap. The following list shows all the mapping files T4S is shipped with in that
directory:

26

t4s_mapping_config.sd
t4s_bom_mapping.sd
t4s_dir_mapping.sd
t4s_ecm_mapping.sd

the central mapping configuration file


for the Bill of Material mapping
for the Document Info Record mapping
for the Engineering Change Master mapping
TESIS PLMware

Configuring T4S to support customer specific requirements

t4s_equi_mapping.sd
t4s_funcloc_mapping.sd
t4s_mm_mapping.sd
t4s_mm_item_import.sd
t4s_prop_mapping.sd
t4s_query_mapping.sd
t4s_vendor_mapping.sd

for the Equipment mapping


for the Functional Location mapping
for the Material Master mapping
for the MM import to Teamcenter mapping
for the SAP Data View mapping
for mapping the SAP query mapping
for the Vendor mapping

You may name these files freely; see How to modify the mapping on p. 34 and The file
t4s_mapping_config.sd on p. 37

In most cases not all of these files are needed for a T4S installation and we recommend
only keeping the needed files in the mmap directory because too many files there will just
be confusing

Therefore the shipped directory <T4S_ROOT>\var\mmap does not contain all the T4S
mapping example files and the included file t4s_mapping_config.sd does not
source all of them

In order to provide many mapping examples but not confuse you with too many details at once,
T4S provides the following mapping files additionally. These are not stored in the same folder
<T4S_ROOT>\var\mmap, but in <T4S_ROOT>\var\template\t4sdemo\mmap.
In order to use one of them, copy the desired file to the default mmap directory and modify it there
only. Please note that many of them need the additional T4S demo package (see chapter Adapt
the Teamcenter Data Model for T4S with TEM and BMIDE in the "Teamcenter Gateway for SAP
Business Suite Installation Guide" for details). These templates include the basic mapping files,
too, but not exactly the same, so their names are not exactly the same but include the word
template additionally. These contain more specific usage examples than the mapping files in the
standard mapping directory <T4S_ROOT>\var\mmap.
These additional files are:
t4s_bom_item_import_template.sd
for the BOM import to Teamcenter mapping
t4s_bom_mapping_template.sd
for the Bill of Material mapping
t4s_connection_mapping_template.sd for mapping different SAP connections at runtime
t4s_dir_item_import_template.sd
for the DIR import to Teamcenter mapping
t4s_dir_mapping_template.sd
for the Document Info Record mapping
t4s_dirbom_mapping_template.sd
for the Document structure mapping
t4s_ecm_item_import_template.sd
for the ECM import to Teamcenter mapping
t4s_ecm_mapping_template.sd
for the Engineering Change Master mapping
t4s_equi_item_import_template.sd
for the Equipment import to Teamcenter mapping
t4s_equi_mapping_template.sd
for the Equipment mapping
t4s_equibom_mapping_template.sd
for the Equipment BOM mapping
t4s_funcloc_item_import_template.sd
for the Functional Location import mapping
t4s_funcloc_mapping_template.sd
for the Functional Location mapping
t4s_genbom_mapping_template.sd
for the Generic BOM mapping

Teamcenter Gateway for SAP Configuration Guide V10.1

27

28

t4s_genobj_mapping_template.sd
for the Generic Object mapping
t4s_idgen_mapping_template.sd
for the Item ID generation from SAP MM ID mapping
t4s_ippe_node_mapping_template.sd
for the SAP iPPE node mapping
t4s_ippe_structure_import_template.sd
for the SAP iPPE structure import mapping
t4s_lov_mapping_template.sd
for the List of Values mapping
t4s_mapping_config_template.sd
the central mapping configuration file
t4s_meta_import_template.sd
for the import of meta data, i.e. the source and
target object do not need a 1:1 relationship
t4s_meta_mapping_template.sd
for the generic batch job creation
t4s_mm_item_import_template.sd
for the MM import to Teamcenter mapping
t4s_mm_mapping_template.sd
for the Material Master mapping
t4s_network_item_import_template.sd
for the network import to Teamcenter mapping
t4s_network_mapping_template.sd
for the network mapping
t4s_orderbom_mapping_template.sd
for the Order Bill of Material mapping
t4s_pir_item_import_template.sd
for the Purchase Info Record import to
Teamcenter mapping
t4s_pir_mapping_template.sd
for the Purchase Info Record mapping
t4s_plmxml_refsetofoperations_mapping_template.sd
for the routing operations reset mapping
t4s_plmxml2_bom_mapping_template.sd for the PLMXML based BOM mapping
t4s_plmxml2_inspectionplan_mapping_template.sd
for the PLMXML based inspection plan mapping
t4s_plmxml2_routing_mapping_template.sd
for the PLMXML based routing mapping
t4s_prodorder_import_template.sd
for the Production Order import to Teamcenter
t4s_prop_mapping_template.sd
for the SAP Data View mapping
t4s_query_mapping_template.sd
for mapping the SAP query mapping
t4s_rtp_mapping_template.sd
for the Runtime Property mapping
t4s_schedule_mapping_template.sd
for the schedule manager integration mapping
t4s_variant_option_import_template.sd
for the generic object based item import
t4s_vendor_item_import_template.sd
for the Vendor import to Teamcenter
t4s_vendor_mapping_template.sd
for the Vendor mapping
t4s_wbs_bom_import_template.sd
for the Work Breakdown Structure import
t4s_wbs_bom_ mapping_template.sd
for the Work Breakdown Structure mapping
t4s_wbs_item_import_template.sd
for the Work Breakdown Structure import to
Teamcenter mapping
t4s_wbs_mapping_template.sd
for the Work Breakdown Structure mapping
t4s_workcenter_import_template.sd
for the Equipment based Work Center import
t4x_custom_mapping_toolbox.sd
for the custom toolbox mapping functions
t4x_data_view_demo.sd
for the SAP data view demo mapping
t4x_workflow_batchjob_template.sd
for defining customer specific Batch functions
t4x_workflow_review_template.sd
for defining automatic Workflow Review decisions

TESIS PLMware

Configuring T4S to support customer specific requirements

The samples in the mapping template files may serve as a guideline to your own customer specific
implementation and show the use of the functions provided to make the implementation easier.
These functions and their possible adaptations are described in the following chapters.

Any statement that starts with set ::SAPDat is supposed to hand data to SAP

The command for storing data in Teamcenter is


::T4X::TC::MAPPING::storeReverseMappingAttribute

The command to read an attribute from a Teamcenter object is


::T4X::TC::MAPPING::FieldMapping

The command to read an attribute from a Teamcenter object in context of a structure


::T4X::TC::MAPPING::IndexedFieldMapping

Every mapping command looks similar to this one:


set ::SAPDat(Material:MaktData:LANGU_ISO:1)

"EN"

This example sets the language for the first SAP Material Master description to English.
If the value you want to set is not a constant string but a value that has to be read from
Teamcenter, it looks like this:
set ::SAPDat(Material:HeadData:MATERIAL)
[::T4X::TC::MAPPING::
FieldMapping "$ItemRevisionType:items_tag:$ItemType" item_id]
This sets the material number of the SAP Material Master to the Teamcenter Item ID of the current
Item Revision. It executes the function FieldMapping (which is defined in the namespace
::T4X::TC::MAPPING) with the parameters $ItemRevisionType and item_id and
stores the result in the variable ::SAPDat(Material:HeadData:MATERIAL).
From the parentheses we know that SAPDat is an array variable and the double colon shows it is
defined globally. This is a T4S internal variable to store the data before they are sent to SAP in a
single call.

Although it might look like a fixed data structure (see Data Arrays on p. 207), there is no
need from the T4S point of view to set any specific data in order to be able to fill a SAP
data structure. If there is a need to set more data than the obviously needed, this is a
SAP restriction, not a T4S one. For T4S, it is only a kind of loose collection of data that is
handed to SAP as one package

To find out which Teamcenter data are accessible for the mapping, run the corresponding
mapping test script (see the "Teamcenter Gateway for SAP Business Suite Administration Guide"
for details). Then, any accessible Teamcenter data is stated in the paragraph starting with the line
###::TcData Direct Data ###
Teamcenter Gateway for SAP Configuration Guide V10.1

29

In that data list, every colon (:) there needs a colon in the mapping, too, in order to read the
corresponding Teamcenter data.
Example: You want to read the Item ID of the current Item Revision for processing the MM:

Run the MM test mapping from the Admin GUI

In the output, you will find the following:


TcData(ItemRevision:items_tag:Item:item_id)

To store the Item ID in the variable My_ID, you have to specify in the MM mapping file:
set My_ID [::T4X::TC::MAPPING::FieldMapping "$ItemRevisionType
:items_tag:$ItemType" item_id]

If you use a fixed type name (e.g. ItemRevision) instead of the variable
$ItemRevisionType, only data from an Item Revision of the given Item Type is used.
The variable $ItemRevisionType automatically contains the current Item Revision type,
so the example above will read the Item ID of the current Item Revision no matter of the
Item Type

The logic in the field mapping is as follows:

$ItemRevisionType is the current object (the one that was selected when starting the
T4S function from the GUI or the workflow, respectively). In most cases, this is an Item
Revision. From there, follow the given relations and data objects to the desired data, see
following examples:

"$ItemRevisionType:items_tag:$ItemType" "item_id"
This means: take the item_id from the Item. The Item is related by items_tag to the
Item Revision which is the current object. It is neither necessary nor useful to specify
whether "item_id" is a property or an attribute of the object $ItemType

In order to check the relations, have a look at the Details tab (or Properties tab,
respectively) in the Teamcenter application My Teamcenter
Example: If you are looking for the relation between an Item and its Master Form,
select the Item and find on the right the Type Item Master and the Relation
IMAN_master_form
In Teamcenter, some of the relations are shown with the translated name, e.g. Item
Master instead of IMAN_master_form. Find the corresponding names in the file
<TC_ROOT>\lang\textserver\en_US\system_property_names_locale.xml
or ask Teamcenter to show you the real name by setting the preference (maybe a user
or a site preference): TC_display_real_prop_name to 1. The default value is zero,
i.e. it shows the translated names

30

TESIS PLMware

Configuring T4S to support customer specific requirements

In some cases, T4S does not use a relation actually but an internal functionality to find the
correct object because the target may not be unique. Most important: following the
reference items_tag from an Item Revision to the Item is unique (because every Item
Revision has exactly one Item), but the reverse is not necessarily unique (an Item may
have more than one Item Revision), so by default, T4S has to use the last Item Revision
which it determines internally when asked the following way.
Therefore the relations to be specified in the field mapping function calls are different for
unique and non-unique relations:

set TestItem $ItemRevisionType:items_tag:$ItemType

set TestItem $ItemType:revision_list:$ItemRevisionType

"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
"SAPMatNo"
This means: take the SAPMatNo which is an attribute of the Item Revision Master Form.
This is related by IMAN_master_form_rev to the Item Revision

No matter if you had to specify the value #__getAllProperties__#:Properties in


order to be able reading the piece of data you need, never state something like
#__getAllProperties__#:Properties in the mapping

The target object found by the given combination of relations and types should be unique,
e.g. an Item has exactly one Item Master form by default. If you have several targets with
the same combination of relations and types and use the T4S default way of reading
attributes, Teamcenter will give you data from any one of those targets. In order to set up
T4S to read several forms with the same combination of relations and types, see T4S FAQ

If the string you want to send to SAP is empty, the entire command is ignored, i.e.
it is not possible to pass an empty string to SAP
it does not matter if you have a statement like
set ::SAPDat(Material:HeadData:MATERIAL) ""
in the mapping file or not; it will not be sent to SAP as an empty string but ignored

To clear a field in SAP, do the following:


If you transfer an empty string, nothing will happen
In SAP MM: Pass a string that consists of blanks (as many as the field can store) and at
least one more character that is not a blank, e.g. " x" (three blank characters followed
by "x") for a string field of length three.
This also clears a SAP MM date field (to achieve this, pass 10 blanks and the "x")
If the field is defined as date (instead of a string), then pass zeros instead of blanks
In SAP BOM, DIR and ECM: pass only an exclamation mark ("!")
Maybe this behavior is different, depending on your SAP system. If in doubt, try all
these possibilities

Teamcenter Gateway for SAP Configuration Guide V10.1

31

Note that SAP does not allow the clearing of all fields, e.g. the field Description (short
text) must not be cleared in most cases
Caution: with ECM, SAP behaves different from MM etc. If you try to clear an empty
field, the exclamation mark will be stored there. But if the field was not empty, it will be
cleared

The logic in the reverse mapping is as follows:

The expression reverse mapping in T4S means storing data (mostly read from
SAP, but could be data from anywhere) back to Teamcenter during a standard
transaction where the start point was in Teamcenter

In the reverse mapping, it is different. The function is storeReverseMappingAttribute and its


parameters are the data type (here: MaterialMaster), the TC target data object (here: the attribute
user_data_1 in the Item Revision Master Form) and the SAP identifier for the desired object (here:
$MaterialNumber which is only a variable):
::T4X::TC::MAPPING::storeReverseMappingAttribute MaterialMaster
"ItemRevision:IMAN_master_form_rev:ItemRevision Master" user_data_1
$MaterialNumber
The same reverse mapping call with a genuine SAP data mapping (OLD_MAT_NO of the MM)
looks like this:
::T4X::TC::MAPPING::storeReverseMappingAttribute MaterialMaster
"ItemRevision:IMAN_master_form_rev:ItemRevision Master" user_data_1
[::T4S::TC::MAPPING::SAPFieldMapping MaterialMaster $MaterialNumber
CLIENTDATA:OLD_MAT_NO]

32

The function SAPFieldMapping does not work in the context with BOMs; if you want
to read SAP BOM data, do the following (example for the first ECN of this BOM):
if {[lindex [::TPSAP::BOM::BAPI::readBillOfMaterial] 0]
== "BOM_FOUND"} {
set BOM_ECN
$::BOMResultDat(STPO_API02:CHANGE_NO:1)
}

TESIS PLMware

Configuring T4S to support customer specific requirements

For backups of the mapping files, we recommend creating another directory parallel
to var/mmap, e.g. var/mmap_test. Keeping more than one version of a mapping file in
the original var/mmap directory should not be a problem as long as the file
extension is modified (e.g. .sd_backup_20080815 instead of .sd). Never store
backups of mapping files with the original extension .sd in the var/mmap
directory.

T4S supports any data type (string [any length], date, numbers, Boolean attributes
(logical)). If a transfer to a specially formatted field (either on Teamcenter or on SAP
side) fails, it might be a problem with the data format. If possible, try and use a
standard string instead for testing

By default, T4S reads some properties of any object type (e.g. Item or Item Revision
of any Item Type, Dataset, Form): object_name, object_tag, object_desc, item_id
(or item_revision_id, respectively, for an Item Revision) as long as Teamcenter
provides them (e.g. a Dataset does not have an ID) even if not specified explicitly.
Many more properties are available if the key word Properties is used for a specific
data object in the Teamcenter preferences; see description of the preference
T4S_MaterialMasterMapping4 below

If a T4S function does not work correctly with a custom Teamcenter Item Type, try the
same with the standard Teamcenter Item Type Item. Maybe your own Item Type
has special settings that cause a problem

The T4S menu buttons are labeled Create direct and Change direct. In the
Teamcenter preferences, the corresponding entry is MM_CREATE_HID or
MM_CHANGE_HID, respectively. When talking about hidden functions, it is the
same as Create direct and Change direct

T4S is shipped with one template mapping file for each of the supported data types
(MM, BOM, DIR, see above) with examples of reasonable data transfers in both
directions. In order to make these examples work in most environments and not to
overload the files, they do not contain every possible setting! In order to check the
SAP fields T4S can read and write, consult the Teamcenter Gateway for SAP Business
Suite Preparing SAP for Teamcenter Integration Guide that is part of the T4S
documentation set.

Teamcenter Gateway for SAP Configuration Guide V10.1

33

T4S does not use the real SAP field name, e.g. the Industry Sector of a SAP
material master record is called RMMG1-MBRSH in SAP, but T4S uses it as
SAPDat(Material:HeadData:IND_SECTOR). It is not possible to use the real SAP
field name in T4S.

SAP does not provide exactly the same functionality for the interactive
transactions (e.g. MM Create, where a SAP window appears to the T4S user) and
the hidden ones (e.g. MM Create direct, where the data are exchanged between
Teamcenter and SAP without opening a SAP window). For instance, it is not possible
to create a SAP Material Master with a given Plant ID with MM Create. This only
works in the hidden way (MM Create direct). The standard workflows work exactly
in the same way as the hidden functions. Make sure to set up your test scenarios
according to the transaction types that will be used in the genuine production
environment later.

When using fixed floating point number values in the mapping, you have to use a dot
as decimal separator (e.g. 1.234) in most cases; a comma is not processed
correctly. Unfortunately this may be different in different SAP installations, so be sure
to implement it in the way your SAP system allows it.

Some SAP fields do not allow blanks at the end of a string by default (e.g. the
Document version in the DIR header). Therefore T4S removes blanks from strings
that were read from a Teamcenter form. If you do not want that, please follow the
instructions in the chapter "How to read data in hexadecimal format or without
trimming blanks" in the T4S FAQ document.

2.2.2

34

How to modify the mapping

The only files that are subject to changes for the mapping are the ones in the directory
<T4S_ROOT>\var\mmap (and the Teamcenter preferences as precondition)

Mapping files must be stored in plain text format (no Unicode etc.)

Mapping files are executed during runtime, they must be written strictly in TCL syntax

Badly formatted mapping files can result in strange problems when executing the T4S
software

Proper compilation of the mapping file does not prove the correctness of the mapping
file

See the "Teamcenter Gateway for SAP Business Suite Administration Guide" for
details, including how to execute various test scripts to verify the mapping

In order to modify a mapping functionality, adapt the corresponding mapping file in the directory
<T4S_ROOT>\var\mmap. Be sure to have a backup of the file in another directory before
TESIS PLMware

Configuring T4S to support customer specific requirements

doing large modifications so you can compare the file with its previous content if the new
version should not work as expected

Run the program <T4S_ROOT>\<bin>\mmap which creates the files


<T4S_ROOT>\tmp\mmap.flist
this text file contains a list of all the files in the <T4S_ROOT>\var\mmap directory that are
packed together to:
<T4S_ROOT>\tmp\t4s_mapping_config.rfdt
this is the ready-to-use mapping file which is stored in a binary format and used by T4S for
the transactions

Move t4s_mapping_config.rfdt from <T4S_ROOT>\tmp\ to <T4S_ROOT>\lib\ where


it is expected by T4S. If you want to keep different ready-made mappings, just backup the old
t4s_mapping_config.rfdt file

Restart T4S, so it can read the new files: execute <T4S_ROOT>\bin\restart.exe

Test the new mapping using the Admin GUI (see the "Teamcenter Gateway for SAP Business
Suite Administration Guide")

If the mapping seems OK you have to restart Teamcenter in order to use the new mapping in
T4S and read the new preferences: in a 4-tier installation, restart the pool server and then the
Teamcenter clients; in a 2-tier installation, restart your Teamcenter client (every Teamcenter
client that should use the modified mapping)

In order to take modifications into account in a 4-tier installation, it may be enough to


restart the T4S 4-tier server for mapping modifications
restart the Teamcenter 4-tier clients for preference modifications (and restart the T4S 4-tier
clients if there are any, see "Teamcenter Gateway for SAP Business Suite Installation
Guide")
If that should not work, restart everything as mentioned in the sentence above.

The previous sections describe the default handling of the mapping files. If you do not
want to keep your mapping source files (t4s*.sd) in the default directory T4S/var/mmap
(maybe you do not want them in a T4S installation at all) set the environment variable
TPMMAP_SRCDIR to the directory where the files are located. Similarly, you may define
another target directory for the compiled mapping file (environment variable
TPMMAP_DSTDIR) and a different file name for it (environment variable TPMMAP_OUT).
In the very most cases there is no need for these settings but if you want to set
them, we recommend setting these lines in t4xcust.bat.

Explanation: the following example shows the settings that make T4S handle it in the
default way (i.e. it will behave the same as if these environment variables are not set at
all) if it is installed in C:\T4S (in Windows, you may use slashes or backslashes or
directory separator):
set TPMMAP_SRCDIR=C:/T4S/var/mmap

Teamcenter Gateway for SAP Configuration Guide V10.1

35

set TPMMAP_DSTDIR=C:/T4S/tmp
set TPMMAP_OUT=t4s_mapping_config.rfdt

36

The next example shows how to handle these files independently from any T4S
installation directory::
set TPMMAP_SRCDIR=C:/Backups/T4S_test/mmap
set TPMMAP_DSTDIR=C:/Backups/T4S_test
set TPMMAP_OUT=t4s_mapping_config.backup

In any case (independently of these settings), the only compiled mapping file T4S will use
at runtime is the file <T4S_ROOT>/lib/t4s_mapping_config.rfdt so be sure to put
the file with the correct name there.

In order to compile the mapping and move the rfdt file to the lib directory in one step, use
batch template <T4S_ROOT>\etc\t4s_build_mapping.bat.template, see
previous chapter.

The mapping hot deploy allows taking a mapping modification into account without
restarting TC and the T4S Apps completely. In your T4S shell, just change the directory
to %TP_T4XINSTL% and execute the following line:
bin64\mmap -server
"%TPS_SERVER_APPS_IP%@%TPS_SERVER_APPS_PORT%" -user t4adm:geheim
This takes a couple of seconds only and then the mapping modification will be used
immediately. If as in this example the password for the T4S admin user t4adm has
not been modified, the parameter -user may be left out, so it could be as easy as:
bin64\mmap server T4S_server@47123

In order to find all the options mmap offers, open a command shell (not necessarily a
Teamcenter or T4S shell), change the directory to %TP_T4XINSTL% and execute the
following line:
bin32\mmap help

Note that mapping modification can also be done via test script Tools -> Generate
mapping and mapping deployment":

TESIS PLMware

Configuring T4S to support customer specific requirements

This script can be executed in three modes:

2.2.3

Generate Mapping

Generate Mapping and File Copy

Generate Mapping and Server Hot Deployment

The file t4s_mapping_config.sd

The file t4s_mapping_config.sd in the directory <T4S_ROOT>\var\mmap is the first file that is
read by the T4S software in context with mapping functionality. It may contain basic settings as
well as variables which are supposed to be used in more than one mapping file, see

Direct Mapping of Constants on p. 45. One of the last paragraphs in this file is for telling T4S
which files contain the customer accessible mapping functions, e.g.
source -relax t4s_mm_mapping_template.sd
Teamcenter Gateway for SAP Configuration Guide V10.1

37

This means T4S has to read the content of the file t4s_mm_mapping_template.sd. The
argument -relax means the file is looked up in the memory first and only if its content is not there,
the file is loaded from disc (only in the same directory <T4S_ROOT>\var\mmap). In principle, the
file names may be modified freely as long as the file extension .sd is kept. Every file stated there
that has the file extension .sd is actually used for the mapping functionality. In fact the only file T4S
actually uses for the mapping is the compiled mapping file t4s_mapping_config.rfdt but this
is what to think about in order to create the compiled mapping file correctly.

Be sure to have the correct file names (the files located in <T4S_ROOT>\var\mmap)
in the source section of this file

The file t4s_mapping_config.sd must not be renamed as T4S will read it and
check there which mapping files to use. It is only read at T4S startup, not in every
transaction. Therefore, it is impossible evaluating anything there that changes during
T4S runtime, because the result will be the same in every run. So for example if you
want to get a time stamp and define that in that file, the variable value will be the same
every time you use it. Please use the object type specific mapping files for current
calculations. Some Teamcenter related data are also impossible to read there, most
important the TC DB name: ::TcData(SiteIdName)
(see chapter

38

Obtaining special Teamcenter information: database and user on p. 46)

Some of the functions, e.g. for the routing transfer, need the additional SAP JCo
Adapter, so maybe you have to implement it for additional functionality although T4S
worked correctly without it; see the chapter JCo (Java Connector) in the "Teamcenter
Gateway for SAP Business Suite Preparing SAP for Teamcenter Integration Guide" for
details

In order to not use a mapping file it is enough to not source it in


t4s_mapping_config.sd. However, we strongly recommend keeping only those
mapping files in the mmap directory that you really want to use

As every single T4S thread runs through this file when initializing, you may notice that
it is executed several times

TESIS PLMware

Configuring T4S to support customer specific requirements

2.2.4

Basics for standard transactions (initiated from within Teamcenter)

The following sub chapters contain hints that only apply on mapping data (from Teamcenter to
SAP and back from SAP to Teamcenter) during a transaction triggered from within Teamcenter
(either Portal action or Workflow event).

2.2.4.1 Mapping of Teamcenter data to SAP


The first thing you have to do is configuring the data sources, i.e. the Teamcenter data T4S will
read in order to pass data to SAP. This is done in the Teamcenter preferences. For every data
object on the SAP side (material master, document), T4S provides data structures that can be
filled using the customer-specific mapping function TC_Object2SAP_<type> which is found in the
upper part of the corresponding mapping file. Adapt the function according to your needs, i.e.
especially choose the attributes you want to read from Teamcenter and the fields you want to set in
SAP.
As mentioned above, the function ::T4X::TC::MAPPING::FieldMapping allows getting
Teamcenter data. If these data are not just strings but lists (e.g. bill of materials items), use the
function ::T4X::TC::MAPPING::IndexedFieldMapping instead. If you call such a function
with a Teamcenter data source that is not configured correctly (maybe a misspelling), the result will
always be an empty string.

The result is always a string, no matter of the data type in Teamcenter

If the original data is of type Boolean, you will get 1 (true) or 0 (false)

The result of a Date or other non-string-attribute may be different from what you see
in Teamcenter itself

It is no problem if you try and read data that does not exist. In this case, the result will
be empty. This is useful when reading an attribute that exists in an object of one Item
Type (then you get the correct data), but not in another Item Type (then it is empty).
So you do not have to distinguish the Item Types explicitly.

The mapping result is empty if the queried data do not exist (no error), but there is a
warning in the T4S session log. Example for this message when trying to read the
non-existing attribute does_not_exist on the ItemRev Master Form (Item Type
SAP2_T4S_Item):
::T4X::TC::MAPPING::FieldMapping - Warning: No TcData entry
found for >SAP2_T4S_Item Revision:IMAN_master_form_rev:
SAP2_T4S_Item Revision Master< and >does_not_exist<!

Be aware of the return value of the mapping functions (meaning the different procedures within one
mapping file): the return value is T4S specific, not part of generic TCL: T4S evaluates the return
Teamcenter Gateway for SAP Configuration Guide V10.1

39

codes of its functions. If you want to exit a function without causing T4S starting its error handling,
be sure to use the same return value that you find at the end of this function and nothing else:

In the functions for the mapping from Teamcenter to SAP it is


return "OK" or return $Status

If you want to stop the transaction and output your own error message, use return
"ERROR" instead. Then the transaction is aborted completely. If it was started from a
workflow, it will stop at this point. To create an own error message, T4S provides two
functions:
::T4X::CORE::storeMessage2 Mapping $err_msg ERROR
::T4X::CORE::storeUserMessage ERROR <err#> <p1> <p2>
Add one of them immediately before the return "ERROR", where the variable
$err_msg contains your desired error message (set it before). For more details see
chapters How to write additional Log File Information and following in the Teamcenter
Gateway for SAP Business Suite FAQ.

If you want to skip one object without influencing the rest of the transaction (and not
stop the workflow), use return "SKIPPED". This will not call SAP with the current
object data (e.g. a MM, complete BOM or only one position in a BOM) and not perform
the reverse mapping for it, but immediately go on with the next object without providing
an error message (which would cause the workflow to stop). We recommend providing
a log message in such a case for being able to track why the object was skipped

If you want to update your Teamcenter object with the corresponding data from SAP,
but not modify the SAP data, use return "REVERSEMAPPINGONLY"

The functions for the reverse mapping (from SAP to Teamcenter) should always return
"OK" as long as no error occurred; else the reverse mapping is skipped and a
corresponding log message is created:
The update of the Teamcenter object after the transfer was
switched off by the reverse mapping status

Only the reverse mapping return value SKIPPED will end the transaction
successfully and do no reverse mapping to Teamcenter. With any value besides
OK and SKIPPED, T4S will treat the whole transaction as if an error occurred
actually

40

The proc callCustomerRuleHandler which is included in every mapping file to support


the type specific rule handlers, always needs return $Decision, where Decision
is a variable with the value of either EPM_go (workflow proceeds) or
EPM_nogo (workflow stops). See chapter How to attach more functionality to a
workflow in the "Teamcenter Gateway for SAP Business Suite FAQ " for details

TESIS PLMware

Configuring T4S to support customer specific requirements

2.2.4.2 Reverse Mapping: store data from SAP to Teamcenter


For the reverse mapping you also have to configure the target sources in Teamcenter
preferences, i.e. the Teamcenter attributes T4S should be able to write to. T4S provides a separate
mapping function SAP_<type>2TC_Object in the appropriate mapping file for each object type to
define the reverse mapping of data from SAP to Teamcenter. If you call such a function for a
Teamcenter data target that is not configured correctly, it will not be modified.

If you try to set invalid data to an attribute in a Teamcenter form, Teamcenter may
refuse the whole saving action or fail to save the form that contains the doubtful data

If you try to fill a Teamcenter attribute with a string that is too long for this attribute, the
string will be cut to the correct length and stored. The logs will contain a warning, but
the user is not notified by a message box. Most of this data is not stored in clear text
format. If you want to output them, you have to use the code sequence [binary
format {H*} $var] (see examples below)

It should not cause a problem but T4S provides a warning in the logs if a Teamcenter
attribute is configured for reverse mapping (i.e. the corresponding FieldMapping2
preference is specified) but not used in the mapping. The corresponding warning in
the session log is:
T4X_UPDTC_getReverseMappingValue: ***=ERROR
where *** is the Teamcenter attribute (including relations) as specified in the
Teamcenter preferences

If a Teamcenter attribute is not defined as type String, you have to set the data in a
special format in order to store them in Teamcenter:
Logical (Boolean): set "TRUE", "YES" (not case sensitive) or "1" in the mapping
file to set the value to true. Any other string will set the value to false
Date: use the format "2007.06.30 15:07:00" (for setting it to June 30, 2007 at 7
past 3 PM), might be different depending on the Teamcenter installation

From T4S point of view, there is no problem with a Teamcenter attribute defined as
type LongString; just use it as any other string attribute. If the string to write to this
attribute contains a new line (\n), Teamcenter will automatically put the following part
of the string into the next line

If you want to write information to customer specific attributes on the Item or Item
Revision, please make sure that the attribute of the Business Object in BMIDE is
configured as modifiable.

Teamcenter Gateway for SAP Configuration Guide V10.1

41

The attempt to set data to a Teamcenter data object that does not exist is ignored and
does not cause a problem. This is useful when setting an attribute that exists in an
object of one Item Type but not in another Item Type. So you do not have to
distinguish between the Item Types explicitly

The attempt to set Teamcenter data that have not been configured correctly (missing
or insufficient preference T4S_*Mapping2* or a misspelling in the corresponding
preference name or value) will result in the correct mapped data but as it impairs
performance T4S will report an error, e.g.
Status : 1700 = Option not found:
T4S_MaterialMasterFieldMapping2items_tag:Item

2.2.4.3 Using T4S transaction information


Depending on the mode of the transaction, T4S provides additional data for the individual mapping
functions. These can be used for control purposes in the mapping process. At present the following
modes are supported:

Interactive mode (also called Portal mode; using the T4S GUI)

Workflow mode (using the workflows from within the Teamcenter standard application My
Teamcenter)

In the workflow mode all of the data known for a workflow such as job name, Rule/Action
handler name and Rule/Action handler parameter are made available to the mapping process.
All of the currently available control parameters in the workflow are listed in the following table:
T4S data structure

Meaning

TcData(GatewayMode)

Has the value "Workflow

TcData(Workflow:RootTaskName)

Name of the process template

TcData(Workflow:TaskName)

Name of the current task

TcData(Workflow:JobName)

Name of the current Job

TcData(Workflow:JobDescription)

Description of the current Job

TcData(Workflow:Action)

Action of the workflow task (Assign, Start, Complete,


Skip, Suspend, Resume or Perform)

TcData(Workflow:Argument:x)

Arguments defined in the configuration of the Rule /


Action handler. Note that the counter starts with zero

TcData(Workflow:ReleaseStatus)

Release status to be checked by Rule handler

42

TESIS PLMware

Configuring T4S to support customer specific requirements

JobName and JobDescription are the two fields Process Name and Description that
you may enter freely when starting a Workflow manually (File New Process)

The FAQ contains some mapping examples for getting these data, e.g. in chapter How
to obtain detailed information about the workflow

Most of this data is not stored in clear text format. If you want to output them, you have
to use the code sequence [binary format {H*} $var] (see examples below)

When just asking for an argument name, you cannot distinguish which handler an
argument belongs to; it may be in the definition of any of the rule or action handlers in
this workflow. So any argument should have a unique name, then you can distinguish
it by its name; or check the Workflow Task additionally: TcData(Workflow:TaskName)

In most cases, you will know the name of the argument (available workflows and arguments will be
explained in chapter Workflow Handler Functions from p. 152 on), so search for the argument by
its name and evaluate it this way.
This is an example for reading a workflow argument when you know its name (set the SAP
BOM plant ID to the argument value or use a default value if not set in the workflow template):
if {$::TcData(GatewayMode) eq "Workflow"} {
set MyArgValue [dict get [::T4X::TC::MAPPING::
getWorkflowArgumentValue2 "-Plant1"] ArgumentValue]
}
if {$MyArgValue eq ""} {
set ::SAPDat(Bom:BomHeader:Plant)

$::T4S_Defaults(Plant)

} else {
set ::SAPDat(Bom:BomHeader:Plant)

$MyArgValue

}
In this example, the value of the Workflow Job argument -Plant1 is used as the Plant ID for the
BOM header. If the argument -Plant1 does not exist or is empty, the predefined Plant is used,
same if this code is called from the Portal instead of the Workflow. (see details on the usage of
::T4X::TC::MAPPING::getWorkflowArgumentValue2 in the "Teamcenter Gateway for SAP Business
Suite FAQ")

Teamcenter Gateway for SAP Configuration Guide V10.1

43

Note that the example above does allow distinguishing if the workflow handler argument does not
exist or is empty. In cases where this difference should be important, do the following instead:
if {$::TcData(GatewayMode) eq "Workflow"} {
# A Workflow argument exists in a Workflow only
set MyArg1 [::T4X::TC::MAPPING::getWorkflowArgumentValue2
"-Plant1"]
if {[dict get $MyArg1 Status] eq "OK"} {
# Workflow argument found, so evaluate it:
set MyArgValue [dict get $MyArg1 ArgumentValue]
if {[string length $MyArgValue] eq 0} {
# The argument value is empty
set ::SAPDat(Bom:BomHeader:Plant) $::T4S_Defaults(Plant)
} else {
set ::SAPDat(Bom:BomHeader:Plant) $MyArgValue
}
} else {
# Workflow argument not found
set ::SAPDat(Bom:BomHeader:Plant)
$::T4S_Defaults(Plant)
}
} else {
# Not in a Workflow
set ::SAPDat(Bom:BomHeader:Plant)
$::T4S_Defaults(Plant)
}
In this example, the value of the Workflow Job argument Plant1 is used as the Plant ID for the
bill of materials header. If the argument Plant1 does not exist or is empty, the predefined Plant
is used, same if this code is called from the Portal instead of the Workflow.

Using the T4S dict structure (dictionary), T4S allows you distinguish whether the
argument does not exist or it does not have a value

Portal mode: At present, only the information that it is the portal mode and the name of the T4S
function (i.e. the button the user pressed in the T4S GUI) are transferred:
T4S data structure

Meaning

TcData(GatewayMode)

Has the value "Portal

TcData(Portal:Action)

Meaning of the portal button (values DISPLAY, LINK,


CREATE, CREATE_HID, CHANGE)

44

TESIS PLMware

Configuring T4S to support customer specific requirements

2.2.5

Direct Mapping of Constants

This functionality is provided to allow the usage of the same variable value in more than one
mapping file, see How to modify the mapping (p. 34). A useful example is the SAP Plant ID which
may be used for the Material and for the BOM as well. Store it as a variable in the settings file
<T4S_ROOT>\var\mmap\t4s_mapping_config.sd and use it in both of the mapping files.
Example:
Definition in <T4S_ROOT>\var\mmap\t4s_mapping_config.sd:
set ::T4S_Defaults(PlantId)

"1000"

Usage for MM:


set ::SAPDat(Material:MarcData:PLANT)

$::T4S_Defaults(Plant)

Usage for BOM:


set ::SAPDat(Bom:BomHeader:Plant)

$::T4S_Defaults(Plant)

Both of these calls will get the same value for the plant ID. So this value only has to be modified at
one point of the mapping, no matter how often it is used.

You may introduce any variable you like in this style

Be sure not to set there any variables that T4S will modify at runtime automatically,
e.g. the whole variable array ::StatusInfo; it is altered in each transaction by T4S
itself

If you define an own global variable (i.e. its name starts with the double colon, e.g.
::TestValue) be sure to delete it between two runs because it may keep its
previous value. Depending on the way it is used this cleaning should be done in the
beginning or the end of the transaction:
unset ::TestValue

Teamcenter Gateway for SAP Configuration Guide V10.1

45

2.2.6

Obtaining special Teamcenter information: database and user

There is some Teamcenter information that is available in the mapping independently from the
data type.
Example: Getting the current Teamcenter database name (maybe you want to do different
mappings on different databases):
if {[info exists ::TcData(SiteIdName)]} {
set SiteName [string trim \
[::T4X::TC::MAPPING::decodeTcDataString $::TcData(SiteIdName)]]
} else {
set SiteName "SiteName_not_found"
}

Example: Getting the current Teamcenter user name, group and role name:
set current_TC_user

[tpco_formatHEX16 $::TcData(UserName)]

set current_TC_group [tpco_formatHEX16 $::TcData(GroupName)]


set current_TC_role

46

[tpco_formatHEX16 $::TcData(RoleName)]

You can find more data of this kind when executing a test mapping in the Admin
GUI and checking the data output.

You can use nearly everything (but not all!) in the mapping exactly the same as
shown in a test mapping, but most of them not by asking ::TcData directly

All the data that are directly related to the queried Teamcenter object are better
used with the FieldMapping function, or in BOM mapping with the
IndexedFieldMapping function, respectively

TESIS PLMware

Configuring T4S to support customer specific requirements

2.3 Configuration of MM data mapping from Teamcenter to SAP

This section contains useful information about the generic mapping process in addition to
the specific Material Master data mapping. If you skip this chapter and proceed to the
BOM, DIR etc mapping sections directly, you may not be satisfied with the depth of
explanations. Please refer to the statements given here for the MM mapping

Some characters may not be stored to some fields in SAP, e.g. when trying to set a tab
character (tabulator) into a MM description or a BOM position text, it will be shown as a
hash in SAP:
Test with#tab

If you want to map data from a Teamcenter object to SAP material master you need to think about
the following:

What are the required attributes that I need to set on SAP MM?

Which information needs to be read from the Teamcenter object to be able to map all
attributes to SAP MM?

Do I want to store any information back to the TC object, i.e. status, date of transfer?

We advise you to get at least some high level answers to these questions before you start the
configuration work.

2.3.1

Configuration of MM data mapping from Teamcenter to SAP

Only Item Revisions (no Items) can be defined! A material master transfer is always
based on TC object class type ItemRevision.

This step defines which data needs to be read from the Teamcenter source object. It is important
to limit the amount of data to the data that you really need to get best performance for your
transaction. Any data that is not required for the transaction should not be read! To define the data
mapping from Teamcenter to SAP the following adaptations in the Teamcenter preferences have
to be done:

Definition of Item Revision Types which should be supported

Definition of related Teamcenter objects that contribute relevant attributes to the mapping.
The objects have to be defined for each item revision type (defined above)

The following examples show the complete configuration for the material master data mapping.

Teamcenter Gateway for SAP Configuration Guide V10.1

47

Define two Item Revision types for usage with T4S, but only show the standard ItemRevision in
the T4S GUI:
T4S_MaterialMasterTypeList=
SAP2_T4S_Item Revision
SAP2T4S_AttrItemRevision
ItemRevision
T4S_MaterialMasterDisplayableTypeList=
SAP2_T4S_Item Revision

Leaving the key T4S_MaterialMasterDisplayableTypeList= empty is the


same as not stating it at all, i.e. then every data type that is configured with
T4S_MaterialMasterTypeList= is used in the T4S GUI
Be aware some custom ItemRevision types require a blank, standard types do not. Be
careful to use the correct syntax.

Specify the TC data objects from which you want to pass data to SAP by T4S. Be aware that you
should limit the data for processing to the required objects to ensure best performance for
transactions. Note that such a key has to be set for every entry (ItemRevision type) in the
T4S_MaterialMasterTypeList=:
T4S_MaterialMasterMapping4SAP2_T4S_Item Revision=
items_tag:SAP2_T4S_Item
items_tag:SAP2_T4S_Item:#__getAllProperties__#:Properties
items_tag:SAP2_T4S_Item:IMAN_master_form:SAP2_T4S_Item Master
#__getAllProperties__#:Properties
IMAN_master_form:SAP2_T4S_Item Revision Master
IMAN_classification:icm0
T4S_MaterialMasterMapping4SAP2T4S_AttrItemRevision=
items_tag:SAP2T4S_AttrItem
IMAN_master_form_rev:SAP2T4S_AttrItemRevision Master

48

TESIS PLMware

Configuring T4S to support customer specific requirements

2.3.2

The logic is that T4S follows the relation to the next object and from there continues to
the one after that, etc.

Example: items_tag:SAP2_T4S_Item:#__getAllProperties__#:Properties
From the SAP2_T4S_Item Revision (which is the current object, stated in the
preference name), the SAP2_T4S_Item can be accessed following the relation
items_tag. From the Item, follow the relation #__getAllProperties__# to the
properties of the Item. Note that #__getAllProperties__# is not a Teamcenter relation. It
is inserted by T4S to be able to follow the same logic that a relation leads to the next
object. A similar thing is IMAN_classification:icm0

The key word SAP2_T4S_Item Revision does not have to be stated explicitly as a
value, because it is the current object itself. If you do not state
#__getAllProperties__#:Properties, T4S will only be able to read its properties
object_name, object_desc and item_revision_id (or item_id for the Item itself,
respectively)

If you are in doubt whether you configured the data sources correctly, try the T4S script
T4S mapping test; see the "Teamcenter Gateway for SAP Business Suite
Administration Guide" for details

Defining the entry #__getAllProperties__#:Properties allows T4S to read all


attributes defined at the given object. In environments with many tags, runtime
attributes, etc. pointing or retrieving data from other objects will cause huge additional
data traffic and will impact performance negatively. In such cases please use the Black
or White List functionality to limit the number of attributes from all attributes to those
that you really need, see chapter How to use T4S Black or White list feature to
improve performance in the Teamcenter Gateway for SAP Business Suite FAQ for
more details.

Definition of MM data mapping from Teamcenter to SAP

Next step is the definition of mapping the data to the required SAP fields.
After the configuration has been done in the Teamcenter preferences, the definition has to be done
in the mapping file. For the mapping of Teamcenter data to SAP material master data, T4S
provides a data structure analog to the SAP material master functions. The current T4S version
supports the following SAP data structures of the Material Master:

Header segment with control information; material number, sector, material type and the
views to be processed are defined here

Client specific material data; almost all the values of the material master table MARA can
be filled

Teamcenter Gateway for SAP Configuration Guide V10.1

49

Plant specific material data; almost all the values of the material master table MARC can be
filled

SAP material descriptions, also in various languages

SAP long texts, also in various languages (see T4S FAQ document)

Quantity units

For defining the attribute mapping for a MM transaction please review the delivered mapping
template file t4s_mm_mapping_template.sd. The procedures TC_Object2SAP_MaterialMaster and
TC_Object2SAP_MaterialMaster_Standard are most relevant.
Please have a look into the mapping template files and the "Teamcenter Gateway for SAP Business
Suite Preparing SAP for Teamcenter Integration Guide" to learn about how to set SAP field
attributes.

For material master transactions with the SAP GUI, SAP provides only a very restricted
data interface. This is why in transactions using the SAP GUI many of the values have to
be entered manually in the SAP GUI

All of the underlined T4S data fields are passed on to the input masks of the SAP GUI

Further fields in transactions with the SAP GUI can be made available on request

The following example shows one possible data mapping for the SAP material number (which is
the Teamcenter Item ID). Note that it is all one line:
set ::SAPDat(Material:HeadData:MATERIAL)
[string toupper
[::T4X::TC::MAPPING::FieldMapping
"$ItemRevisionType:items_tag:$ItemType" "item_id"]]
The logic with the relations is exactly the same as before in the Teamcenter preferences.

When creating a material master record, SAP automatically converts the number to full
upper case, but any further access will fail if the ID is not given exactly as stored in SAP
(i.e. in full upper case). Thats why the string toupper command should always be used

If you want to use a different number in Teamcenter and in SAP, it is useful to fill one of the
Teamcenter attributes with the SAP material number. This example shows the data mapping
where T4S first reads the attribute SAPMatNo (which is included i.e. into the ItemRevision Master
form) and only if this is empty, the Item ID is used as the SAP material number:

50

TESIS PLMware

Configuring T4S to support customer specific requirements

set T4S_MatNo
[string toupper
[::T4X::TC::MAPPING::FieldMapping "$ItemRevisionType:
IMAN_master_form_rev:$ItemRevisionType Master" SAPMatNo]]
if {$T4S_MatNo eq ""} {
set ::SAPDat(Material:HeadData:MATERIAL)
[::T4X::TC::MAPPING::FieldMapping
$ItemRevisionType:items_tag:$ItemType" item_id]
} else {
set ::SAPDat(Material:HeadData:MATERIAL)

$T4S_MatNo

This example shows data mapping of material type, industry sector (which are taken from the
global variable stored in t4s_mapping_config.sd, see Direct Mapping of Constants on p. 45) and
old material number (taken from the Item Name):
set ::SAPDat(Material:HeadData:MATL_TYPE)
$::T4S_Defaults(SAPMaterialType)
set ::SAPDat(Material:HeadData:IND_SECTOR)
$::T4S_Defaults(Industry)
set ::SAPDat(Material:MaraData:OLD_MAT_NO)
[::T4X::TC::MAPPING::FieldMapping
"$ItemRevisionType:items_tag:$ItemType" "object_name"]

2.3.3

Mapping of additional MM data

This chapter describes how to set additional data to an MM. In order to facilitate error tracking,
please try that only after you successfully created a MM with the standard data.

Teamcenter Gateway for SAP Configuration Guide V10.1

51

2.3.3.1 Set plant specific data to the MM


If you want to set plant specific data for an MM, you have to specify the Plant ID and at least one
plant specific view in the MM mapping, e.g.:
set ::SAPDat(Material:HeadData:QUALITY_VIEW)

"X"

set ::SAPDat(Material:MarcData:PLANT)

$::T4S_Defaults(Plant)

set ::SAPDat(Material:MarcData:PUR_STATUS)
# Plant specific Material Status

"02"

SAP only accepts one Plant ID per transaction. In order to set additional data for another
plant, you can do the following:

Use the T4S functionality multi transfer that allows transferring more than one set of
data to SAP where SAP only allows one per transaction. Please consult the chapter
How to transfer several sets of similar data in one transaction (multi transfer)
in the "Teamcenter Gateway for SAP Business Suite FAQ" for details

In the GUI: every Change direct can set data for another plant
Therefore it is useful to store the data for the new plant in a Teamcenter attribute that
is modifiable in the T4S GUI

In a Workflow:
Attach an additional action handler T4S_update-MaterialMaster-AH for every
plant (i.e. if you want to set data for three plants, you must have this action handler
three times in the task SAP_MM_UPDATE)
In order to have the action handlers perform different things for each plant, add a
parameter for the plant to each of these handlers (e.g. -Plant as argument name
and the needed Plant ID as value). This parameter has to be read in the mapping

2.3.3.2 Create the MM as a copy of an existing MM (reference material)


The function "setMaterialMaster_by_Reference" reads data from an existing SAP MM and
sets all the values into the new structure SAPDat which will be used for creating the new MM. Any
value may be modified in the mapping. Then the MM is created in SAP.
Example for the usage with plant specific data (the variable MaterialMaster_Ref contains the
ID of the SAP MM you want to copy; Plant the ID of the plant from which data have to be read):
# Read the reference MM data:
::TPSAP::MM::setMaterialMaster_by_Reference TEST true
$MaterialMaster_Ref $Plant
# Set the desired MM ID for the new MM:
set ::SAPDat(Material:HeadData:MATERIAL) $MaterialMaster_New

52

TESIS PLMware

Configuring T4S to support customer specific requirements

You can use the params "Plant", "Comp_Code", "Val_Area", "Val_Type", "Storage_Loc",
"Sales_Org", "Distr_Channel", "Whse_Number" and "Storage_Type" in this function for determining
for which plant etc. the values should be read and copied.
The complete function header is (for how to set the params):
proc setMaterialMaster_by_Reference {
TEST
blnOverwriteFields
MatNr_Reference
{Plant {}}
{Comp_Code {}}
{Val_Area {}}
{Val_Type {}}
{Storage_Loc {}}
{SalesOrg {}}
{Distr_Channel {}}
{Whse_Number {}}
{Storage_Type {}}
args
}
Explanation: You have to provide the first three parameters (the fix value TEST, the flag
"blnOverwriteFields" and the reference MM ID), all the others are optional. If omitted, they do not
receive a default value (this is what {} means). The parameter blnOverwriteFields (only true or
false allowed, case sensitive) determines if a variable of the array SAPDat is overwritten if it
already contains a value.

This functionality is not exactly the same as the SAP default Copy from when
creating a new Material Master; that really creates a complete copy of an existing MM.
In contrast to that, this T4S functionality for creating a reference material cannot copy
every data from an existing Material. For example, it cannot copy the Material long
texts or classification values.

If you want to copy all of the attributes you have to read them first and then set them
explicitly to the new Material Master. This is possible even if there is plant specific data
to be copied for several plants.

If any of the given parameter values does not exist for the given MM, SAP will return
NOT_FOUND for this function call and not give any data.
Example: there is a MM in Plant 1000 in your SAP. When calling the function
setMaterialMaster_by_Reference for this existing MM with the value 2000 for
the Plant, you will not get empty Plant data for this MM, but not any MM result data at
all

Teamcenter Gateway for SAP Configuration Guide V10.1

53

Only with MM Create where a SAP window opens (but not with Create Direct), T4S can use
the SAP functionality to create a new MM as a copy of an existing one. To activate this, add the
following line in the MM mapping file:
set ::SAPDat(Material:Parameter:UseRefMaterial)

"12345"

If you then click MM Create in the T4S GUI, you will find the given value "12345" automatically
filled in the field Copy from. Then you may type a new MM ID (or just press Enter to get one
from SAP) and have a new MM with the same data as your referenced MM 12345.

As in any other case when creating a new MM, you need to specify the "Industry sector"
and "Material type" as well

2.3.3.3 How to set the SAP MM Revision Level

For creating a revision level in SAP (this applies to any object type where SAP allows a
revision level, not only to Material Masters) be aware of the following:

For setting the revision level, SAP requires the usage of a change number. This ECM
has to be valid for the object type the revision level has to be assigned to

SAP may allow setting the revision level to a given value or not. If you think T4S does
not set the value correctly, please ask your SAP consultants if your SAP system
allows setting the value fix (else SAP generates a value no matter what is transferred)

For setting the revision level to a Material Master, SAP requires the usage of a change number that
is valid for Materials:

54

TESIS PLMware

Configuring T4S to support customer specific requirements

Add the following sequence to your MM mapping file (for instance, directly after the MATL_TYPE
and IND_SECTOR section).
In this example, the ECM ID is taken from the attribute SAPChangeNo in the Item Revision Master
Form and the Revision Level is the Item Revision ID:
# MM Revision Level Support
set ::SAPDat(Material:Parameter:CHANGE_NO) [::T4X::TC::MAPPING::
FieldMapping "$ItemRevisionType:IMAN_master_form_rev:
$ItemRevisionType Master" "SAPChangeNo"]
set ::SAPDat(Material:Parameter:REVISION_LEVEL_NEW)
[::T4X::TC::MAPPING::FieldMapping "$ItemRevisionType" "item_revision_id"]

After a successful MM Create transaction, you should see a new SAP MM with a Revision Level:

2.3.4

Configuration of MM data mapping from SAP to Teamcenter (reverse


mapping)

In this step you need to configure the objects and attributes where T4S shall store information after
the MM transaction has been performed.
To define data mapping from SAP to Teamcenter the following adaptations in the Teamcenter
preferences have to be done.

Definition of Teamcenter objects, which are used to store SAP data generally (the definition
has to be done for each item revision type supported by T4S (definition of types see
above))

Definition of fields used in these Teamcenter objects to store the data (you have to define
fields for each structure defined in step one)

The data mapping of the SAP material master back to Teamcenter is carried out at the end of
every SAP transaction that was not aborted with an invalid transfer status like SKIPPED (see
above) or with an invalid mapping status.

Teamcenter Gateway for SAP Configuration Guide V10.1

55

Example for the configuration of the reverse mapping structure:


The example describes reverse mapping of data to the Item Revision Master using the Teamcenter
relation IMAN_master_form (some fields of the form) and to the Item Revision itself (description),
as well as the Item ID. The example contains the handling for different Item Revision Types, too
(ItemRevision and Design Revision).
Specify the TC data objects which are allowed to receive data from SAP by T4S:
T4S_MaterialMasterMapping2ItemRevision=
IMAN_master_form_rev:ItemRevision Master
items_tag:Item
items_tag:Item:IMAN_master_form:Item Master
ItemRevision
T4S_MaterialMasterMapping2FunctionalityRevision=

Such a key has to be set for every entry in the T4S_MaterialMasterTypeList

It may be left empty, i.e. in this example T4S does not store any data to a Teamcenter
FunctionalityRevision

Unlike the configuration for the mapping from Teamcenter to SAP (preference
T4S_MaterialMasterMapping4), you have to specify ItemRevision here, because T4S
needs this entry for the following key T4S_MaterialMasterFieldMapping2 ItemRevision,
see below

Specify the TC attributes which are allowed to receive data from SAP by T4S:
T4S_MaterialMasterFieldMapping2IMAN_master_form_rev:ItemRevision
Master=
SAPMatNo
SAPMatNoReserved
SentMMToSAP
user_data_1
user_data_2
user_data_3
T4S_MaterialMasterFieldMapping2ItemRevision=
object_desc

56

TESIS PLMware

Configuring T4S to support customer specific requirements

T4S_MaterialMasterFieldMapping2items_tag:Item=
item_id
T4S_MaterialMasterFieldMapping2items_tag:Item:IMAN_master_form:Item
Master=
user_data_1

2.3.5

Such a key has to be set for every entry in the T4S_MaterialMasterMapping2<type>

Every entry in the T4S_MaterialMasterMapping2<type> needs such a key

Such a key is only used if the type is included in T4S_MaterialMasterMapping2<type>,


i.e. if you have a type MyType1 but the key T4S_MaterialMasterMapping2<type> does
not have a value MyType1, the key T4S_MaterialFieldMasterMapping2MyType1 will
be ignored

It makes no sense to state such a key and leave it empty. If a data object is not supposed
to get data, delete it from T4S_MaterialMasterMapping2<type>

Definition of MM data mapping from SAP to Teamcenter (reverse mapping)

Be sure to have the Teamcenter attributes configured in the Teamcenter preferences, otherwise
T4S will not store any data there. The input parameters of the reverse mapping function are the
T4S function name (e.g. Change), the status and the corresponding SAP material number. With
this material number an enquiry is made to SAP.
The function storeReverseMappingAttribute stores something into a Teamcenter attribute
(or property, respectively).
Example for the easiest possible reverse mapping (store the MM ID into the attribute SAPMatNo
of the Item Revision Master Form):
::T4X::TC::MAPPING::storeReverseMappingAttribute MaterialMaster
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
SAPMatNo $MaterialNumber
Another important data is a current time stamp. This can be created by TCL using clock, e.g.
::T4X::TC::MAPPING::storeReverseMappingAttribute MaterialMaster
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
SentMMToSAP "[clock format [clock seconds] -format "%Y-%m-%d %R"]"
If SAP data has to be stored to Teamcenter, the function storeReverseMappingAttribute
has to be used with a SAP data source. At present T4S provides the SAP field names listed in the
corresponding tables.

Teamcenter Gateway for SAP Configuration Guide V10.1

57

58

The test script mentioned works for any supported SAP version, but for SAP 4.6C it is not
necessarily needed.

Material master data other than those described in the table can only be supported by the
introduction of client-specific mapping functions and the corresponding adaptation at the
SAP system.

SAP uses different kinds of field naming in their systems and T4S has to respect that in
the mapping:

Example for storing the SAP MM description into user_data_2 with SAP 4.7 (the :1 at
the end of the line indicates the Material description in the first language):

::T4X::TC::MAPPING::storeReverseMappingAttribute MaterialMaster "$ItemRevMaster"


user_data_2 [::T4S::TC::MAPPING::SAPFieldMapping MaterialMaster $MaterialNumber
MATERIALDESCRIPTION:MATL_DESC:1]

Be aware that SAP may renumber the languages alphabetically, i.e. although if you
specify the languages in the order IT, ES, EN in the mapping for creating the MM, you
may get them back in the order EN, IT, ES (ES for Spanish is internally coded as S and
therefore ordered after IT!)

TESIS PLMware

Configuring T4S to support customer specific requirements

2.4 Document Info Record data mapping


A Document Info Record (DIR) in SAP is very similar to a Dataset in Teamcenter: an object with
some data that may include physical files which are called Originals in a SAP DIR. These files
can be opened in their original application from the SAP GUI (according to its configuration).
Therefore, a workstation application has to be configured in SAP for the data type, and the
application has to be available locally.
T4S supports the transfer of Teamcenter data based on Datasets or Item Revisions. 1:1 relations
between the configured Teamcenter object and the SAP DIR are created. The main difference
between both methods is the object to start from in Teamcenter:

Using the Dataset method, T4S will create one DIR from this one Dataset, no matter how many
files it contains.

Using the Item Revision method, T4S will create one DIR from this one Item Revision, no
matter how many Datasets it contains and how many files they contain all together

In both cases, the object to start a DIR workflow from is the Item Revision, see details below. And
in both cases, T4S will only use the configured Dataset and file types. It may upload all the files
contained in the corresponding object (Item Revision or Dataset) to this one DIR as original files.
The information to identify this SAP DIR uniquely (the SAP DIR key: document type, document
ID, document part and document version) may be stored in a new form attached as named
reference of the dataset or in attributes in any form of the Item or Item Revision.

KPro (Knowledge Provider) is the generic document management service in SAP

For document types without KPro support, only a maximum of two originals is supported
for one DIR, all others are ignored

Teamcenter can handle datasets with more than one file and T4S will process them all
correctly, no matter if they have different named references (independent of their actual
file type)

SAP may limit the number of files per DIR. In case no KPro is used, only two files can
be stored for each DIR, and there is a limitation of the physical size of each file (see
SAP documentation for details)

If you want to upload files to SAP with T4S, you may encounter Datasets that do not
contain files. But as this might be a configuration error, the DIR mapping template file
contains the following for facilitating error tracking (you will find this output in the test
mapping and in the T4S session log):
if {$::SAPDat(Document:Files:NumberOfFiles) == "0"} {
puts
"The number of files is zero!"
tpwrite "The number of files is zero!"
# Maybe it is OK, but this warning might be useful for error tracking
}

Teamcenter Gateway for SAP Configuration Guide V10.1

59

2.4.1

Configuration of DIR data mapping from Teamcenter to SAP

To define the dataset types and data mapping from Teamcenter to SAP the following adaptations
in the Teamcenter preferences have to be done.

Definition of supported Datasets or Item Revision types

For each dataset the SAP DIR default data (type, document part, version)

For each dataset the named references (used for SAP DIR originals) which should be
supported

For each named reference the SAP workstation application, SAP file extension, data
carrier, temporary file directory, KPRO name

For each dataset the form which should be used to store SAP information

If not stated differently, all of these keys have to be stated even if they are empty
(because the corresponding functionality is not needed)

T4S supports two different ways of handling SAP documents in Teamcenter:


The configuration of Dataset will handle each Dataset uniquely and so create one
DIR for each Dataset (then the SAP DIR will contain no or one original file)
The configuration of Item Revision will only create one DIR for the whole Item
Revision and attach one original file for each Dataset (then the SAP DIR may
contain several original files)
Do not mix these two together
In the T4S GUI, you have to select a Dataset or an Item Revision according to the
configuration
For the DIR workflow, you always have to select the Item Revision
For the mapping to SAP, the DIR mapping file has one branch for each of the two
modes, but only the one for your desired mode has to be used:
if {$ObjectClassName == "Dataset"} {
or
} elseif {$ObjectClassName == "ItemRevision"} {

The following examples show the complete configuration for the Document data mapping. The
corresponding settings for Item Revision are appended in parentheses:
Define the Dataset types (Item Revision types) that are allowed for T4S:
T4S_DocumentInfoRecordTypeList=
UGMASTER
(ItemRevision)

60

TESIS PLMware

Configuring T4S to support customer specific requirements

There is no key T4S_DocumentInfoRecordDisplayableTypeList= specified in this


example, i.e. we want the T4S GUI to show all the specified Dataset types or Item
Revision types, respectively.

Specify the Teamcenter data objects that should be read when a DIR is processed. In this
example, all the possible settings for Item and Item Revision are done (for the standard Item and
the Functionality Item, too):
T4S_DocumentInfoRecordMapping4UGMASTER=
#__getAllProperties__#:Properties
IMAN_specification:ItemRevision:items_tag:Item
IMAN_specification:ItemRevision
IMAN_specification:ItemRevision:IMAN_master_form_rev:ItemRevision
Master
IMAN_specification:FunctionalityRevision:items_tag:Functionality
IMAN_specification:FunctionalityRevision
IMAN_specification:FunctionalityRevision:IMAN_master_form_rev:
FunctionalityRevision Master
ref_list/UGPART:ImanFile
ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm

If e.g. you leave out the line IMAN_specification:ItemRevision:items_tag:Item, you


will not be able to read the ID of the Item the current Dataset belongs to (the result
string will be empty)

You have to specify all of these for each defined Type separately (i.e. for each entry in
the TypeList preference)

The corresponding setting for using DIR with ItemRevision is:


T4S_DocumentInfoRecordMapping4ItemRevision=
items_tag:Item
items_tag:Item:IMAN_master_form:Item Master
items_tag:Item:#__getAllProperties__#:Properties
IMAN_master_form_rev:ItemRevision Master
#__getAllProperties__#:Properties
IMAN_classification:icm0

Teamcenter Gateway for SAP Configuration Guide V10.1

61

IMAN_Rendering:DirectModel:ref_list/JTPART:ImanFile
IMAN_specification:UGMASTER:ref_list/Graphics-Interface:ImanFile
IMAN_specification:ItemRevision:items_tag:Item

For each Dataset type, specify the default document key for the SAP document info record. This
is always the document type, part and version. Be sure to state all these three values for every
desired type (if there are less than three values, the key will be treated as if it was empty).
T4S_DocumentInfoRecordDefaultDocumentKey4UGMASTER=
CAD
001
00

For each Dataset type, specify a list of named references for a specified dataset type. These are
the file types that you import into the Teamcenter Dataset and are attached to the SAP DIR as an
original:
T4S_DocumentInfoRecordMappingNamedFileList4UGMASTER=
ref_list/UGPART:ImanFile
That means, when processing a Dataset of type UGMASTER, T4S only uses files that are
attached as named reference UGPART for uploading to SAP.
For each file type (what you see in Teamcenter as named reference), specify the SAP
Workstation Application which is used for viewing/printing the file:
T4S_DIR_WorkstationApplication4ref_list/UGPART:ImanFile=
DXF

An incorrect setting does not affect the DIR creation as long as this Workstation
Application exists. The only thing is that SAP might not be able to handle the file correctly

For each file type, specify the file extension that SAP will attach to the file.
T4S_DIR_FileExtension4ref_list/UGPART:ImanFile=
PRT

This extension is not necessarily the file name extension used by the computer operating
system (it may be the same accidentally). This also has no effect on the DIR creation
itself.

62

TESIS PLMware

Configuring T4S to support customer specific requirements

For each file type, specify the data carrier path, i.e. where the file is saved before sending it to
SAP (this has to be filled in any case; in UNIX/Linux, it should be something like /tmp instead of
C:/temp):
T4S_DIR_DataCarrierPath4ref_list/UGPART:ImanFile=
C:/temp

If this is a SAP file server, the files should remain there (then, it is not C:/temp in most
cases, but something like X:/sapfiles), else they may be deleted. T4S deletes them
automatically if you set the following in the DIR mapping:
set ::SAPDat(Document:Parameter:DeleteOldFileSystemFiles) "TRUE"

A UNIX/Linux system may allow using C:/temp as well, but this is not the same as in
Windows. Therefore it may confuse users and we do not recommend using it.
Example of what will happen:
$ pwd
/home/infodba
$ md c:/temp
$ cd c:/temp
$ pwd
/home/infodba/c:/temp

Additionally, a copy of each file is stored temporarily before sending it to SAP. For determining
the directory where the file will be stored, T4S checks the following values and uses the first
directory that exists in the file system of the current tcserver environment and is writeable for T4S
(depending on the operating system user access rights):

Teamcenter preference TC_transfer_area

Operating system environment variable TC_TMP_DIR

Operating system environment variable TMP

Operating system environment variable TEMP

Operating system environment variable TMPDIR

If a preference or environment variable, respectively, from this list does not exist or is
empty, T4S will go on checking the next target in the list without any problem

The preference TC_transfer_area may contain several values (e.g. for Windows and for
UNIX/Linux) that are checked one after another prior to checking the environment variables
in the stated order. The environment variables may contain one value only (i.e. one
possible target directory) each

Teamcenter Gateway for SAP Configuration Guide V10.1

63

As this check is done at runtime (not during the installation of T4S) the target directory may
be different on different machines or for different users

These files are deleted automatically if you set the following in the DIR mapping:
set ::SAPDat(Document:Parameter:DeleteTempOriginals) "TRUE"

If T4S could not determine a valid directory according to this list, it cannot export the file from
Teamcenter and therefore not upload it to SAP as DIR original file. In this case, an error
message is written into the T4S session log file.

For each file type, specify the data carrier name, i.e. where the file is saved in SAP (may be
empty, see below):
T4S_DIR_DataCarrierName4ref_list/UGPART:ImanFile=
SAPVault

For the first tests, leave this key empty. If not set, the DIR creation is not disturbed (but the
file cannot be stored at the correct target), but if set incorrectly, the DIR is not created at
all!

For each file type, specify the KPRO, if files should be stored there (may be empty):
T4S_DIR_KproName4ref_list/UGPART:ImanFile=
KPRO1

Files can either be stored in a SAP Vault or in a KPRO but not both, so do not use
both of the options T4S_DIR_KproName4 (with KPRO) and
T4S_DIR_DataCarrierName4 (without KPRO) in the Teamcenter preferences
together. At least one of these two has to be stated empty

In either case, the option "T4S_DIR_DataCarrierPath4..." has to be set

If you want to create a SAP document structure (this is a SAP data structure similar to a
material BOM but it contains DIRs instead of MMs), specify a list of named references. These are
the file types that are attached to the SAP DIR that is in the DIR structure:
T4S_DocumentInfoRecordMappingObjectList4ItemRevision=
IMAN_specification:PDF
64

TESIS PLMware

Configuring T4S to support customer specific requirements

This is the only key in the T4S DIR configuration that may be left out completely. But in
any unused case (left empty or not stated at all), it will be stated as missing in the log
files, so do not bother with that warning

Find details on document structures in the chapter How to create a SAP document structure in the
document "Teamcenter Gateway for SAP Business Suite Frequently Asked Questions".

2.4.2

Simplified DIR data mapping configuration from Teamcenter to SAP

In order to facilitate the DIR preferences setting, T4S offers the possibility for specifying the
necessary file handling data during DIR processing in the mapping.

Please see the remarks in the previous chapter for details about how to find the correct
values for the needed SAP data

Define the needed data by using the following mapping functions:

::T4S::DIR::CONFIG::setDocumentInfoRecordOriginalsConfig
Use this function to define the needed information to specify an original file transfer to SAP
based on a given Teamcenter object type and the relation or named reference to the file.
The function has the following arguments:
o

ObjectTypeName: Teamcenter object type name (e.g. MSWord or ItemRevision)

NamedFileReference: defines the relation to the actual Teamcenter file, i.e. the
Datasets named reference

WSApp: defines the SAP workspace application (like JT or WRD)

FileExtension: defines the file extension with which the SAP original file will be
stored (e.g. tif, jt, doc or docx)

DatacarrierName: defines SAP data carrier name for the desired SAP storage

DatacarrierPath: defines the path used to hand the original file over to SAP

KProName: Name of the SAP Knowledge Provider used to store the original file

::T4S::DIR::CONFIG::setDocumentInfoRecordKeyDefaults
Same as the preference T4S_DocumentInfoRecordDefaultDocumentKey4<type>,
this function defines the default SAP document key (DIR type, part and version; as the ID
will be different in nearly every transaction, it is not useful to define as a default) for a given
Teamcenter object type (such as a Dataset type or ItemRevision).
The function has the following arguments:
o

ObjectTypeName: Teamcenter object type name (same as above, e.g. MSWord)

DOCUMENTTYPE: SAP document info record type

Teamcenter Gateway for SAP Configuration Guide V10.1

65

DOCUMENTPART: SAP document info record part

DOCUMENTVERSION: SAP document info record version

Example:
::T4S::DIR::CONFIG::setDocumentInfoRecordOriginalsConfig MSWord
ref_list/word:ImanFile WRD doc MyDatacarrierName C:/temp
::T4S::DIR::CONFIG::setDocumentInfoRecordKeyDefaults MSWord DRW 000 00

2.4.3

Do not use the preference and mapping based configuration together

Definition of DIR data mapping from Teamcenter to SAP

For the mapping of Teamcenter data to the SAP document info record, T4S provides a data
structure analogous to the SAP document functions. This means that all fields which can be
addressed via BAPIs can be filled with values from Teamcenter. The current T4S version supports
the following SAP data structures:

Document data

Original files (is derived automatically)

Object links

The individual fields available are shown in the chapter Supported SAP fields T4S can write to in
the "Teamcenter Gateway for SAP Business Suite Preparing SAP for Teamcenter Integration
Guide".

For document info record transactions with the SAP GUI, SAP provides only a very
restricted data interface for documents. This is why in the DIR Create transaction with
the SAP GUI, only the DIR itself is created. It contains the main data, but no Original files.
They have to be transferred subsequently to SAP in a second step (DIR Change).
Setting classification information in a SAP DIR also only works in that second step. When
using the functionality without SAP GUI (Create direct), it is all done in one step

This behavior may vary in different SAP systems!

The examples below show data mapping of DIR number, type, version, document part and
description:
set ::SAPDat(Document:DrawData:DOCUMENTNUMBER)
[::T4X::TC::MAPPING::FieldMapping "$ObjectTypeName:
ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm" "SAP_DirNo"]

66

TESIS PLMware

Configuring T4S to support customer specific requirements

set ::SAPDat(Document:DrawData:DOCUMENTTYPE)
[::T4X::TC::MAPPING::FieldMapping "${ObjectTypeName}:
ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm" "SAP_DirType"]
set ::SAPDat(Document:DrawData:DOCUMENTVERSION)
[::T4X::TC::MAPPING::FieldMapping "${ObjectTypeName}:
ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm" "SAP_DirVersion"]
set ::SAPDat(Document:DrawData:DOCUMENTPART)
[::T4X::TC::MAPPING::FieldMapping "${ObjectTypeName}:
ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm" "SAP_DirPart"]"
set ::SAPDat(Document:DrawData:DESCRIPTION)
[::T4X::TC::MAPPING::FieldMapping
"${ObjectTypeName}:IMAN_specification:$ItemRevisionType" "object_name"]

This only sets the description in the current language (the language with which you started SAP).
In the functions that use the SAP GUI it is not possible to set descriptions for additional languages.
The description field will be empty for other languages.
To set the DIR description in more than one language, use the following (additionally to the
description setting above). It supports two ways of usage:

Possibility 1: enter the SAP internal language code:


::TPSAP::DIR::setSAPDocumentDescription 1 "E" "" "English description"
::TPSAP::DIR::setSAPDocumentDescription 2 "D" "" "German description"
::TPSAP::DIR::setSAPDocumentDescription 3 "1" "" "Chinese description"
Possibility 2: enter the ISO language code:
::TPSAP::DIR::setSAPDocumentDescription 1 "" "EN" "English description"
::TPSAP::DIR::setSAPDocumentDescription 2 "" "DE" "German description"
::TPSAP::DIR::setSAPDocumentDescription 3 "" "ZH" "Chinese description"

This can only set the description in a language that is properly installed in SAP, see
chapter Which languages are installed? in the T4S FAQ

This does not work with the SAP GUI transactions (only with Create direct or
Change direct, respectively)

Be sure to set the number parameter ascending and contiguous

Mapping of additional DIR data: SAP object link

Teamcenter Gateway for SAP Configuration Guide V10.1

67

SAP allows linking different objects together, e.g. a DIR and an MM. The following example shows
how this is done with T4S. Add the following line in the DIR mapping (from Teamcenter to SAP):
set ::SAPDat(Document:ObjectLink:MATERIAL)
[::T4S::DIR::MAPPING::getObjectLinkList
"${ObjectTypeName}:IMAN_specification:$ItemRevisionType:IMAN_master_form
_rev:
$ItemRevisionType Master" "SAPMatNo"]
This will create a SAP object link between the current DIR and an MM with the ID that is stored in
the attribute SAPMatNo in the Item Revision Master Form. If this MM does not exist, there will be
no error and the link will be initialized nevertheless. When you go to the object link tab in this DIR,
SAP will tell you that the MM does not exist. If the MM is created afterwards, the link will work
without any further effort.

2.4.3.1 How to set the SAP DIR Revision Level


Note that SAP requires the usage of a change number for setting the revision level. This ECM has
to be valid for documents. See chapter How to set the SAP MM Revision Level on p. 54 for details
on revision level requirements.
Add the following sequence to your DIR mapping file. In this example, the ECM ID is taken from
the attribute SAPChangeNo in the Item Revision Master Form and the Revision Level is the Item
Revision ID:
# DIR Revision Level Support:
set ::SAPDat(Document:DrawData:ECNUMBER)
set ::SAPDat(Document:Parameter:setNewRevisionLevel)

$SAPChangeNumber
$ItemRevID

After a successful DIR create or update transaction, you should see a new Revision Level in this
DIR in SAP:

68

TESIS PLMware

Configuring T4S to support customer specific requirements

2.4.4

Configuration of DIR data mapping from SAP to Teamcenter (reverse


mapping)

To define the reverse data mapping from SAP to Teamcenter the following adaptations in the
Teamcenter preferences have to be done.

Definition of Dataset extension form(s) (added as named reference to dataset after a


successful DIR transaction)

Assignment of supported named references to dataset extension forms (for each supported
named reference)

Fields in these forms (have T4S store SAP document info record data)

Example for configuration of dataset data mapping (general settings in the Teamcenter
preferences):
The example shows the definition of the form and the fields in the form. The form
T4S_DatasetExtensionForm is added to the dataset automatically after a successful DIR
transaction.
For each Dataset type, specify the Teamcenter data object(s) where T4S should write to (may be
left empty). This is especially important for the SAP DIR key (DIR type, number, part, and version):
T4S_DocumentInfoRecordMapping2UGMASTER=
ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm

This is only needed if you want to store information about the DIR in Teamcenter.
Then, after every successful DIR transaction, a T4S_DatasetExtensionForm is
added to the current Dataset

The keyword NamedReference is used for telling T4S that the following name is not
a relation, but a reference

For each target in T4S_DocumentInfoRecordMapping2<type>, specify the attribute that should


receive data from T4S (as the T4S_DatasetExtensionForm is the same for each Dataset type in
our examples, we only need one key of this kind):
T4S_DocumentInfoRecordFieldMapping2
ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm=
DirSendToSAP
SAP_DirNo
SAP_DirPart
SAP_DirType
SAP_DirVersion

Teamcenter Gateway for SAP Configuration Guide V10.1

69

2.4.5

Definition of DIR data mapping from SAP to Teamcenter (reverse mapping)

In the reverse mapping you also have to distinguish whether you create a DIR from an Item
Revision or from a Dataset. Therefore the mapping file has the two branches

if {$::TcData(ItemInfo:ObjectClassName) == "Dataset"} {

} elseif {$::TcData(ItemInfo:ObjectClassName) == "ItemRevision"} {

The following examples shows data mapping of transaction time, document type, number, part and
version to the defined fields for the Dataset configuration:
::T4X::TC::MAPPING::storeReverseMappingAttribute DocumentInfoRecord
"${DatasetType}:ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm"
DirSendToSAP
"$SapSystem $SapClient [clock format [clock seconds] format "%Y.%m.%d %H:%M:%S"]"
::T4X::TC::MAPPING::storeReverseMappingAttribute DocumentInfoRecord
"${DatasetType}:ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm"
SAP_DirType
$DocumentType
::T4X::TC::MAPPING::storeReverseMappingAttribute DocumentInfoRecord
"${DatasetType}:ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm"
SAP_DirNo
[::TPSAP::DIR::getExternalDocumentNumber [string trim
$DocumentNumber]]
::T4X::TC::MAPPING::storeReverseMappingAttribute DocumentInfoRecord
"${DatasetType}:ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm"
SAP_DirPart
$DocumentPart
::T4X::TC::MAPPING::storeReverseMappingAttribute DocumentInfoRecord
"${DatasetType}:ref_list/T4S_DATASET_EXTENSION:T4S_DatasetExtensionForm"
SAP_DirVersion
$DocumentVersion

For the Item Revision configuration, it looks as follows (store the DIR ID into the Item Revision
Masters attribute user_data_2):
::T4X::TC::MAPPING::storeReverseMappingAttribute DocumentInfoRecord
"$ItemRevisionType:IMAN_master_form_rev:ItemRevision Master"
user_data_2 [::TPSAP::DIR::getExternalDocumentNumber [string trim
$DocumentNumber]]

70

TESIS PLMware

Configuring T4S to support customer specific requirements

2.5 Bill of Material Data Mapping


The Teamcenter BOM structure is read using a predefined revision rule. T4S sends always one
level of BOM to SAP. Sub assemblies have to be transferred in different transactions. T4S also
allows transferring occurrence notes to BOM line specific data to SAP (e.g. the bulk indicator,
position text etc.). It is possible to distinguish between Item types, e.g. different Item types for
design parts and raw materials. These might be transferred to set the SAP BOM line as different
position types.

You can configure T4S to extract data from several levels of the Teamcenter BOM
structure. So you can add additional Items to be sent from a lower level. But only one level
is sent to SAP for one transaction
See chapter How to read more than one level of Teamcenter BOM in the Teamcenter
Gateway for SAP Business Suite FAQ for details

The expressions BOM line and BOM position are synonymous

Although in most cases T4S uses the complete Teamcenter object type name that is
shown in the column Type (e.g. view BOMView Revision in the following screenshot),
T4S uses the short type name as shown in the object name (here: view) for the BOM
handling (same in the preferences and the mapping):

This is because view is the actual type name whereas view BOMView Revision is a
display name only that may be different in every language and therefore T4S would not
work correctly if used with different languages.

2.5.1

Configuration of BOM data mapping from Teamcenter to SAP

To define the BOM view types and data mapping from Teamcenter to SAP the following
adaptations in the Teamcenter preferences have to be done:

Definition of supported BOM view types

For each type the revision rule has to be defined

Teamcenter Gateway for SAP Configuration Guide V10.1

71

The setting BOM Action (e.g. set ::T4S_Defaults(BomAction) "5"


in the BOM mapping file) determines how SAP handles the BOM when using the T4S
function BOM Display. In most cases, the value 5 should be used. Then SAP will show
the BOM in the same way as if you started transaction CS03 (Display material BOM)
whereas the setting "1" will open CS11 instead (Explode BOM: Level by Level). From
the T4S point of view, only these two settings (1 and 5) may be used reasonably

SAP offers different sets of function modules for BOM handling. If you encounter
problems during BOM handling, it may be necessary to switch to the older set by setting
one of the following switches in the T4S BOM mapping:
set ::SAPDat(Bom:Parameter:useOldBomChangeFunction)
"TRUE"
set ::SAPDat(Bom:Parameter:useOldBomCreateFunction)
"TRUE"
set ::SAPDat(Bom:Parameter:useOldBomFunctions)
"TRUE"

For using the old SAP BOM function modules for the complete BOM handling, set the line
with useOldBomFunctions; for only using the old ones for creating or updating BOMs,
set the line with useOldBomCreateFunction or useOldBomChangeFunction,
respectively

The data SAP requires for creating a BOM using the old functions may be different, e.g.
you may have to set the Base quantity:
set ::SAPDat(Bom:BomHeader:BMENG) "1"

Only the old SAP BOM function modules can create different BOM Alternatives, but they
cannot set customer specific fields, so this is an example where you have to use both old
and new function modules: if you set the line with useOldBomCreateFunction, you
may create a BOM using the old function modules and then modify this BOM including
customer specific fields using the new function modules as these will be used
automatically if the other useOldBom switches are not set

Example for the definition of the supported BOM view types:


The example defines 2 BOM view types (view and sap). For both types the same revision rule is
used (Latest Working). Furthermore, you may set a list of valid BOM header ItemRevision types
and define the data for processing from Teamcenter specifically:
T4S_BillOfMaterialTypeList=
view
sap
T4S_BillOfMaterialDisplayableTypeList=

72

TESIS PLMware

Configuring T4S to support customer specific requirements

view
T4S_BillOfMaterialMapping4view=
Latest Working
T4S_BillOfMaterialMapping4sap=
Latest Working
T4S_BillOfMaterialHeaderTypeList=
SAP2_T4S_Item Revision
T4S_BillOfMaterialHeaderMapping4SAP2_T4S_Item Revision=
items_tag:SAP2_T4S_Item
T4S_BillOfMaterialLineMapping4SAP2_T4S_Item Revision=
items_tag:SAP2_T4S_Item

The BOM TypeList only refers to the BOM view types themselves, no matter which Item
Type they belong to.

The preference T4S_BillOfMaterialDisplayableTypeList is optional and configures the


view types that are suitable for portal based BOM transactions. If not set the types from
the preference T4S_BillOfMaterialTypeList are used.

For workflow transactions T4S needs to know which ItemRevision types are valid as
BOMHeader types. The preference T4S_BillOfMaterialHeaderTypeList is
optional. If not set all ItemRevision types that are configured in
T4S_MaterialMasterTypeList are valid for a BOM transfer. If you do not want to
use the same ItemRevision types for MM and BOM processing, set this preference
T4S_BillOfMaterialHeaderTypeList additionally.

The preference T4S_BillOfMaterialHeaderMapping4 controls the amount of data that


is processed for the BOM header object. To achieve best processing performance only
add entries to the preference that are really required inside the mapping logic. The same
applies for the preference T4S_BillOfMaterialLineMapping4 that controls the data
export for each BOM line type. You need to add a preference for each ItemRevision Type
that should be transferred to the SAP BOM.
Both preferences are optional. If not set T4S applies the set of data defined in the
preference T4S_MaterialMasterMapping4

Teamcenter Gateway for SAP Configuration Guide V10.1

73

2.5.2

Although an ItemRevision Type may be not specified in the Material type list or in the
T4S_BillOfMaterialLineMapping4, T4S will try to read it if it is used as a BOM position. In
order to avoid strange effects, you should configure T4S to not use a BOM position if it is
of a special type (of course you can exclude positions for other reasons in the same way,
see below). The following code in the BOM position mapping function
(TC_Object2SAP_BillOfMaterialPosition) will just skip the desired position
without creating an error or stopping a Workflow Job (i.e. the transaction will end
successfully and this position will just be missing in SAP as if it didnt exist in
Teamcenter):
if {$ItemType == "xy"} {
tpwrite "Skip BOM pos $PosIndex because its Item Type is xy"
return "SKIPPED"
}

Definition of BOM data mapping from Teamcenter to SAP

For data mapping of Teamcenter data to a SAP bill of materials, T4S provides a data structure
analogous to the bill of materials functions. This means that all fields which can be addressed can
be filled with values from Teamcenter. The current T4S version supports the following SAP data
structures:

SAP bill of materials header data, e.g. bill of materials alternative, BOM header long texts

Individual bill of materials items, i.e. the single BOM positions

BOM position related data, like long texts, subpositions and local dependencies

The examples below show data mapping of BOM header data using data defined in T4S basic
settings file (see

Direct Mapping of Constants, p. 45):


set ::SAPDat(Bom:BomHeader:Plant)
set ::SAPDat(Bom:BomHeader:BomAlternative)
set ::SAPDat(Bom:BomHeader:BomUsage)

"$::T4S_Defaults(Plant)"
"$::T4S_Defaults(BomAlternative)"
"$::T4S_Defaults(BomUsage)"

set ::SAPDat(Bom:BomHeader:BomAlternativeText) ""


set ::SAPDat(Bom:BomHeader:BomText)

""

set ::SAPDat(Bom:BomHeader:BomState)

"$::T4S_Defaults(BomState)"

set ::SAPDat(Bom:BomHeader:BomApplication)

"$::T4S_Defaults(BomApplication)"

set ::SAPDat(Bom:BomHeader:BomAction)

"$::T4S_Defaults(BomAction)"

set ::SAPDat(Bom:BomHeader:BMENG)

"" ;# Base quantity (BTCI)

74

TESIS PLMware

Configuring T4S to support customer specific requirements

set ::SAPDat(Bom:BomHeader:BMEIN)

"" ;# Base unit of measure for BOM

set ::SAPDat(Bom:BomHeader:STLBE)

"" ;# BOM Authorization group

set ::SAPDat(Bom:BomHeader:LABOR)

"" ;# Laboratory/design office

set ::SAPDat(Bom:BomHeader:LOSVN)

"" ;# From lot size

set ::SAPDat(Bom:BomHeader:LOSBS)

"" ;# To lot size

set ::SAPDat(Bom:BomHeader:MATNR_LONG)
set ::SAPDat(Bom:BomHeader:OITXT)

"" ;# 40 character Material Number


""
# Object management record description

If they are set, be aware of side effects, e.g. the base quantity and its unit of measure
(BMENG and BMEIN) are possibly not modifiable after creation

Depending on the SAP BOM configuration, any of these values may be empty

The function TC_Object2SAP_BillOfMaterial is executed once for the whole BOM, so here are
the settings for the BOM header (see above). Then the function
TC_Object2SAP_BillOfMaterialPosition is called once for each BOM position.
The following example shows how the position number is set according to the Teamcenter BOM
sequence number:
set ::SAPDat(Bom:Position:POSNR:$BomLineIndex)
[::T4X::TC::MAPPING::IndexedFieldMapping $PositionIndex
BOMLine bl_sequence_no]

In the BOM mapping, the BOM header has always the PositionIndex 0, whereas the
BOM Positions have the numbers 1, 2

The PositionIndex is a parameter to the BOM mapping functions (BOM and BOM
position mapping function as well). In the BOM position mapping function, the variable
BomLineIndex is used additionally because of possible index changes

SAP treats material related BOM positions as references to existing Material Masters.
So each of these BOM positions has to exist as Material Master before creating the BOM
in SAP, else SAP will provide an error. This can be prevented in the mapping (see
Example 1) if you get the MaterialNumber from a Teamcenter attribute that is only
filled when the SAP Material Master is created. Of course it will not work in this way if you
map the Item ID (or similar data independent from SAP) to the MaterialNumber

If a Teamcenter BOM contains alternative positions, T4S will transfer them all to SAP
(which may be useful or not, depending on your processes). If you do not want that, you
can prevent it in the mapping. As only the preferred alternative (the one you will see in

Teamcenter Gateway for SAP Configuration Guide V10.1

75

Teamcenter Structure Manager) has a Find Number (or Sequence Number, respectively)
in the Teamcenter BOM, you can evaluate that (see Example 2). As this is no problem
from neither T4S nor SAP point of view, a BOM workflow job is not aborted by default
and the user is not informed directly
Example 1:
# Do not pass a BOM Position to SAP if its "MaterialNumber" is empty
#
(if it is taken from a TC attribute that is filled when the SAP
#
MM is created):
if {$MaterialNumber == ""} {
tpwrite "BOM custom mapping does not use Position $PositionIndex:
MaterialNumber not found (does MM exist in SAP?)"
return "SKIPPED"
}
Example 2:
# Do not pass a BOM Position to SAP if its Position Number is empty
#
(read from the Find/Sequence Number; it might be an alternative
position):
if {$Position == ""} {
tpwrite "BOM custom mapping does not use Position $PositionIndex:
no Teamcenter BOM Sequence No (is it an alternative position?)"
return "SKIPPED"
}
In the examples above, the BOM is created without the current position. If you want to abort the
whole BOM creation, do the following instead:
Example 3:
# Abort BOM creation if a Position has an empty "MaterialNumber":
if {$MaterialNumber == ""} {
::T4X::CORE::storeMessage2 Mapping "BOM creation aborted because
no MaterialNumber found for position $PositionIndex" ERROR
return "ERROR"
}

76

Avoid using BOM position numbers (sequence numbers) with different lengths (e.g. 10,
20, 100) because this may lead to a sorting problem in the SAP BOM (e.g. 10, 100,
20 instead of 10, 20, 100). If this should occur, make sure to send the position
numbers with four digits always (SAP does not allow more), e.g. 0010, 0020, 0100
In most cases this does not happen with pure numeric position numbers, but with
characters only or both of them mixed, e.g. A23, B1, C012

TESIS PLMware

Configuring T4S to support customer specific requirements

If T4S can not set a SAP BOM field although it might look like a standard field in SAP,
try and transfer it as if it was a customer specific SAP BOM field:
Example to transfer the value val1 to a customer defined SAP BOM field CUSTOM1:
set ::SAPDat(Bom:CustomFields4Position:CUSTOM1:$PosIndex) "val1"
See chapter How to transfer customer specific SAP BOM fields in the Teamcenter
Gateway for SAP Business Suite FAQ for details

2.5.3

Important notes on modifying a SAP BOM

The following explains some SAP internal BOM behavior that is important to note for proper
handling with T4S
If you modify a BOM manually in the SAP GUI and then modify it again using T4S, you may find
duplicated lines or other unexpected effects. This is the result of the SAP CAD indicator a flag
used by SAP to distinguish if the object (maybe just a BOM line) was created from within the SAP
GUI or using an external tool such as T4S. Any BOM line created manually in the SAP GUI does
not have this flag set; BOM lines created by T4S or similar tools do. The reason for that behavior is
allowing to add BOM positions manually that are not reflected in Teamcenter. During an update,
they are not altered by T4S and especially not deleted although they do not exist in the
Teamcenter BOM. A typical example is a manual for a technical product. This is typically not part
of the Teamcenter BOM but needed in the SAP BOM for the correct packaging, so it is added
manually in SAP. So if the product itself is modified in the Teamcenter BOM and this BOM is
transferred to SAP by T4S, the BOM position for the manual is not removed from the SAP BOM
because SAP checks that this position does not have the CAD indicator set and prevents its
modification. To check this flag, double-click the Item number in the SAP BOM, then SAP will open
the view BOM: Item: All data, activate the tab BasicData there and find the CAD Indicator in
the section General Data.

T4S can create and update a SAP BOM without CAD indicator as well. Therefore, set
the following in the BOM mapping:
For the BOM header, add the following line in the function
TC_Object2SAP_BillOfMaterial:
set ::SAPDat(Bom:Parameter:FL_CAD)

""

For the BOM positions, add the following line in the function
TC_Object2SAP_BillOfMaterial:
set ::SAPDat(Bom:Position:CADPO:$BomLineIndex)

""

Note that the value to set is not a blank but an empty string

As this has some side effects (see above), we recommend this for very special cases
only. Especially, you might be surprised about the results if SAP BOMs are modified in

Teamcenter Gateway for SAP Configuration Guide V10.1

77

SAP directly and by T4S

Another important thing to mention is that SAP does not modify the complete BOM during an
update, but only modified lines (modify a line, add a line, or remove a line). If you modify a BOM
but some of the positions are the same as before, you may find that SAP did not modify all the
lines. The following screenshot shows an example where a BOM was created without ECN, then
modified using ECN 500000000416 and then modified again using ECN 500000000417:

So in both modifications, SAP did not modify the BOM position 0030 with the MM ID 2830.
T4S always transfers the whole set of BOM data to SAP, then SAP evaluates if a line has to be
modified. By default, SAP identifies a BOM position (to compare the existing one with the new set
of data coming from T4S) by the combination of the following data in a BOM line:

Position number (shown as Item)

Position type (shown as ICt = Item Category)

Component (unique identification of the object represented in this BOM line, in most cases
MM or DIR)

CAD indicator (not shown here)

Sort field (not shown here; by default it is more to the right in this table and shown as
SortStrng, this is why it also called SortString)

This leads to two important points to keep in mind when modifying a SAP BOM containing two or
more positions with the same data in these fields via T4S:

SAP may give the error message that the BOM position cannot be uniquely identified and
refuse the modification

In some cases SAP may store a modification nevertheless but only one of those lines will
be changed correctly. In this case, you may lose data in the existing SAP BOM!

In order not to lose data, this should be avoided

78

TESIS PLMware

Configuring T4S to support customer specific requirements

2.5.4

Mapping of additional BOM data: Occurrence Notes

Occurrence Notes are small texts that may be attached to a Teamcenter BOM position in only this
BOM. First you have to configure in the Teamcenter preferences which T4S should read. T4S does
not limit the number of Occurrence Notes, but be aware that this is an additional data transfer
which decreases performance when processing large data. The following example shows the
usage of the two Occurrence Notes bl_has_children (standard in Teamcenter) and My_OccNote
(a custom type):
T4S_BillOfMaterialOccurrenceNotes4view=
bl_has_children
My_OccNote

T4S can only read Occurrence Notes of type string (check in the Business Modeler
BMIDE)

If BOM positions are packed in the Structure Manager, Teamcenter will not give
you the complete data on these positions: it will not tell the alternative positions, and if
there are Occurrence Notes, it will only tell Packed Notes, neither their names nor the
values

Some Occurrence Notes are used by T4S by default without having to configure them
explicitly, e.g. the Quantity

The Occurrence Note bl_has_children is set in a Teamcenter BOM if this has another
BOM on its own, so you can determine a BOM structure in Teamcenter

An Occurrence Note type has to be defined in the Business Modeler

The usage in the mapping file is for example (in the same way, the Quantity is determined):
set My_OccNote_new
[::T4X::TC::MAPPING::IndexedFieldMapping
$BomLineIndex BOMLine My_OccNote]

Teamcenter Gateway for SAP Configuration Guide V10.1

79

2.5.5

Configuration of BOM data mapping from SAP to Teamcenter (reverse


mapping)

To define the reverse data mapping from SAP to Teamcenter the following adaptations in the
Teamcenter preferences have to be done.

Definition of Teamcenter objects which are used to store SAP data (has to be defined for
each BOM view type)

Definition of fields in these objects

Example for configuration of BOM data mapping (general settings):


The example shows the reverse mapping for two BOM view types to their Item Revision Master
Forms. Note that the ItemRevision Master Form may be the same for both BOM view types, so
only one preference FieldMapping is needed:
T4S_BillOfMaterialMapping2view=
structure_revisions:ItemRevision:IMAN_master_form_rev:ItemRevision
Master
T4S_BillOfMaterialMapping2sap=
structure_revisions:ItemRevision:IMAN_master_form_rev:ItemRevision
Master
T4S_BillOfMaterialFieldMapping2structure_revisions:ItemRevision:IMAN_ma
ster_form:ItemRevision Master=
SendToSAP
user_data_3

2.5.6

Be aware of the settings for different Item Types for BOM as described in the
beginning of this chapter.

Definition of BOM data mapping from SAP to Teamcenter (reverse mapping)

The examples below show data mapping of transaction time (to the Item Revision Master Form
attribute SendToSAP) and function code (to the Item Revision Master Form attribute
user_data_3). All fields have to be configured in the Teamcenter preferences before (see above):
::T4X::TC::MAPPING::storeReverseMappingAttribute BomHeader
"view:structure_revisions:ItemRevision:IMAN_master_form_rev:ItemRevision
Master" SendToSAP [clock format [clock seconds] -format "BOM: %d.%m.%Y
%H:%M:%S"]
::T4X::TC::MAPPING::storeReverseMappingAttribute BomHeader
"view:structure_revisions:ItemRevision:IMAN_master_form_rev:ItemRevision
Master" user_data_3 "BOM OK"

80

TESIS PLMware

Configuring T4S to support customer specific requirements

2.6 Engineering Change Master Data Mapping


Teamcenter and SAP both offer a change management as functionality to bundle several changes
in one object. The goal is to activate different modifications on several engineering objects (e.g.
bills of materials) at the same time without having to process them all manually. T4S can link SAP
change objects (ECM) to other SAP objects whether the Teamcenter change management is used
or not. T4S passes data to the ECM, no matter if they are stored in a Teamcenter change object or
anywhere else.
Using Teamcenter Change Management, the Teamcenter change revisions can be used as T4S
workflow targets. T4S is looking for configured folders (problem items, solution items)
automatically and transfers all found and configured objects to SAP. This way of working provides
a more tight connection between Teamcenter and SAP change management.
The following examples only show the method where in Teamcenter no Change Object is used,
but only information about the SAP ECM is stored in the Item Revision Master Form. This
information may be used by the other data types in order to change the SAP data object with this
ECM. As the logic is exactly the same as with MM, it is described more briefly here for ECM.

As in the T4S mapping for each supported object type, the logic is not dependent on
where the data come from, e.g. from an Item Revision Master Form or from a
Teamcenter Change object

Be sure to adapt the preferences and mapping according to the used Teamcenter
objects

SAP does not allow the transfer of ECM data with the transactions Create and
Change, i.e. it is not possible to pass data from Teamcenter to SAP this way. If you
start these transactions you will not see your Teamcenter data in SAP (the ECM will be
created with default values). Create Direct and Change Direct pass the data correctly

With the standard BAPIs, SAP does not allow modifying an MM with ECM by the
interface as it is possible with BOM and DIR. But it is possible to use it together with the
Revision Level (see How to set the SAP MM Revision Level on p. 51). With some
special SAP customization and T4S adaption to that, T4S can also provide the
functionality to change an MM with ECM without using the Revision Level. Please feel
free to contact us if you should need that

Teamcenter Gateway for SAP Configuration Guide V10.1

81

2.6.1

Configuration of ECM data mapping from Teamcenter to SAP

The following example shows how to configure ECM that it is used in T4S only with an Item
Revision:
T4S_ChangeMasterTypeList=
ItemRevision
Specify the source data objects for the mapping to the SAP ECM:
T4S_ChangeMasterMapping4ItemRevision=
items_tag:Item
items_tag:Item:IMAN_master_form:Item Master
items_tag:Item:#__getAllProperties__#:Properties
IMAN_master_form_rev:ItemRevision Master
#__getAllProperties__#:Properties

2.6.2

Definition of ECM data mapping from Teamcenter to SAP

The following example shows a correct ECM mapping from an Item Revision:
set ::SAPDat(ChangeMaster:HeadData:CHANGE_NO)
[::T4X::TC::MAPPING::FieldMapping
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
"SAPChangeNo"]
set ::SAPDat(ChangeMaster:HeadData:VALID_FROM)
"[clock format [clock seconds] -format "%d.%m.%Y"]"
set ::SAPDat(ChangeMaster:HeadData:STATUS)
"01"
set ::SAPDat(ChangeMaster:HeadData:DESCRIPT)
[::T4X::TC::MAPPING::FieldMapping
"${ItemRevisionType}:IMAN_master_form_rev:${ItemRevisionType}
Master" "user_data_3"]
set ::SAPDat(ChangeMaster:HeadData:REASON_CHG)
"[::T4X::TC::MAPPING::FieldMapping
${ItemRevisionType}:IMAN_master_form_rev:${ItemRevisionType} Master"
"item_comment"]

82

The current object will always be called ItemRevisionType, no matter if it is a


Teamcenter Change Object or an Item Revision

The valid-from-date (VALID_FROM) is set to the current date in this example. In


most cases, it will be a fixed date in the future. SAP will refuse the transaction if you
try and use a date in the past

Depending on its installation, SAP may require the date in a different format

It is not possible to create an ECM with an ECM profile

TESIS PLMware

Configuring T4S to support customer specific requirements

2.6.3

Configuration of ECM data mapping from SAP to Teamcenter (reverse


mapping)

The following example shows how to configure T4S to store ECM data in an Item Revision:
T4S_ChangeMasterMapping2ItemRevision=
IMAN_master_form_rev:ItemRevision Master
T4S_ChangeMasterFieldMapping2IMAN_master_form_rev:ItemRevision
Master=
SAPChangeNo
user_data_1
user_data_2
user_data_3

2.6.4

Definition of ECM data mapping from SAP to Teamcenter (reverse mapping)

The following example shows how data are stored in an Item Revision during the ECM transaction:
::T4X::TC::MAPPING::storeReverseMappingAttribute ChangeMaster
"ItemRevision:IMAN_master_form_rev:ItemRevision Master" user_data_1
"ECM created"

In this example, we use ItemRevision instead of $ItemRevisionType, so this call will


only work for the Item type Item, not for any other types.

If you want to get SAP ECM data, you have to execute the following function prior to asking SAP
for data:
Set rc [::TPSAP::ECM::getChangeMasterInfo $ChangeNumber]

Then, you could for example store the Reason for Change into user_data_3 (remember that this
was used before to set the ECM description):
::T4X::TC::MAPPING::storeReverseMappingAttribute ChangeMaster
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
user_data_3 "Reason: [::T4S::TC::MAPPING::SAPFieldMapping
ChangeMaster $ChangeNumber REASON_CHG]"

Teamcenter Gateway for SAP Configuration Guide V10.1

83

2.6.5

Handle ECM with different object types

This is useful if you want to use Teamcenter change management and want to copy the correlation
you have in Teamcenter between the ECM and its target objects to SAP. Set the following
Teamcenter preferences:
Example for the old Teamcenter change management:
T4S_process_ECM_pseudofolder_names=
affected_items/EC_affected_item_rel
solution_items/EC_solution_item_rel
Example for the new Teamcenter change management:
T4S_process_CM_pseudofolder_names4ProblemReportRevision=
CMHasSolutionItem
CMHasProblemItem
T4S_process_CM_pseudofolder_names4ChangeNoticeRevision=
CMHasSolutionItem
CMHasProblemItem
T4S_process_CM_pseudofolder_names4ChangeRequestRevision=
CMHasSolutionItem
CMHasProblemItem
T4S_process_CM_pseudofolder_names4SAP2_T4S_Item Revision=
CMHasSolutionItem
CMHasProblemItem

This tells T4S to use the objects as workflow targets that are stored in the pseudo folders
affected_items and solution_items. Nevertheless, the Teamcenter ECM is the object where the
workflow has to be started from, no matter if it is the MM workflow or another one.

84

As this is similar to the Teamcenter preferences standard key


"ECM_pseudofolder_names" or "CM_pseudofolder_names", respectively, you can
copy the folder names from there

Unlike the old Teamcenter change management, the new change management uses a
separate preference for each change type (see suffixes in above example:
4ProblemReportRevision, 4ChangeNoticeRevision, 4ChangeRequestRevision
and 4SAP2_T4S_Item Revision)

TESIS PLMware

Configuring T4S to support customer specific requirements

If you add an Item Revision as Workflow target which is linked into one of the ECM
pseudo folders stated in these preferences, T4S will process that Item Revision twice:
once as target and once more from the relation in the pseudo folder
In order to avoid that double processing, there are two ways
do not use an Item Revision as Workflow target if it is present in such a pseudo
folder in the same Workflow job already
or exclude the pseudo folder name from the preference "ECM_pseudofolder_names"
or "CM_pseudofolder_names", respectively
Due to different Teamcenter handling in the old and new change management, T4S also
behaves differently if the corresponding preference does not exist (same if it exists but
does not have a value):
old change management: if there is no value for the preference
ECM_pseudofolder_names, T4S will use every object of a configured object type
from all the ECM pseudo folders
new change management: if there is no value for the preference
CM_pseudofolder_names, T4S will not use any object from the ECM pseudo
folders
In order to prevent the processing of the ItemRevisions from all folders in the old change
management, set a dummy value to the preference, e.g. "Do not use". Then, only the
Item Revisions that are attached as target will be processed

You can use data related like this in any of the T4S mappings, e.g. use the Teamcenter
Change Item ID as SAP ECN, so you have to read this ID during a BOM transaction although your
current object may be one of the Item Revisions linked into one of these pseudo folders:

Add the following value to the corresponding Mapping4 preference (remember to add it to the
Material related preference for BOM, e.g. T4S_MaterialMasterMapping4ItemRevision
for the handling in the Material transactions):
EC_affected_item_rel:EngChange Revision:items_tag:EngChange

Then add the in the reverse mapping:


set change "$ItemRevisionType:EC_affected_item_rel:
EngChange Revision:items_tag:EngChange"
set ECN [::T4X::TC::MAPPING::IndexedFieldMapping 0 $change item_id]

Similar to this example, you may use the other relations as well. Please have a look into your
existing Teamcenter Change preferences to find the correct spellings.

2.6.6

Create the ECM as a copy of an existing ECM

Up to now, T4S does not provide a special function to support that (similar to the reference
material functionality, see Create the MM as a copy of an existing MM (reference material) on p.
52. Instead of that, you may just read all the data of an existing ECM and set these to the new
ECM according to this example:
Teamcenter Gateway for SAP Configuration Guide V10.1

85

set get_ECM [::TPSAP::ECM::getChangeMasterInfo "ChangeNumber"]


if {$get_ECM == "OK"} {
::TPSAP::ECM::initSAPChangeMasterStructure
# initialize the data array fort he new ECM
foreach elem [array names ::SAPDat ChangeMaster:HeadData:*] {
set LineList [split $elem :]
set LineKey

[lindex $LineList end]

#
# Copy all the data to the new array:
if {[info exists ::ECMResultDat($LineKey)]} {
set ::SAPDat($elem) $::ECMResultDat($LineKey)
}
}
} else {
tpwrite "Given ECM does not exist"
# Maybe react with aborting the transaction:

return "ERROR"

86

TESIS PLMware

Configuring T4S to support customer specific requirements

2.7 Transfer of Equipment data


In SAP, an Equipment is a physical tool, gadget or machine that is needed for manufacturing. This
can be a primitive screw driver as well as a large CNC machine. The SAP Equipment object
describes the tools physical characteristics.

2.7.1

Configuration of Equipment data mapping from Teamcenter to SAP

The following example shows how to configure a Teamcenter Item Revision (here of type
Functionality) that it is used for SAP Equipment:
T4S_EquipmentMasterTypeList=
FunctionalityRevision

The following two issues are SAP internal restrictions for the Equipment transactions
that open a SAP window (Create and Change):

It is not possible to hand data to SAP, so the SAP window is opened but it
contains only its own default data (or the ones that were stored there before,
respectively), not those from Teamcenter

When the SAP object is locked (e.g. because it is modified by another user), T4S
seems to do nothing and there is no error message

The Equipment transactions without opening a SAP window (Create Direct and
Change Direct) work as expected (similar to what you see with an MM transaction).

Specify the source data objects for the mapping to the SAP Equipment Master:
T4S_EquipmentMasterMapping4FunctionalityRevision=
items_tag:Functionality
items_tag:Functionality:IMAN_master_form:Functionality Master
items_tag:Functionality:#__getAllProperties__#:Properties
IMAN_master_form_rev:FunctionalityRevision Master
#__getAllProperties__#:Properties
IMAN_classification:icm0

2.7.2

Definition of Equipment data mapping from Teamcenter to SAP

For data mapping of Teamcenter data to the SAP Equipment, T4S provides a data structure
analogous to the SAP Equipment Master. This means that all fields which can be addressed via
BAPIs can be filled with values from Teamcenter. The current T4S version supports the following
SAP data structures:

Teamcenter Gateway for SAP Configuration Guide V10.1

87

Number (ID) of the Equipment Master to be created


Valid-From Date for Equipment to be created
Installation Date for Equipment

General Data for Technical Objects

Equipment specific data

The individual fields available are shown in the tables in the appendix.
The examples below show data mapping of EQUIPMENT number and category:

set ::SAPDat(EQUI:PARAMETER:EQUIPMENT) [string toupper


[::T4X::TC::MAPPING::FieldMapping
"$ItemRevisionType:IMAN_master_form_rev: $ItemRevisionType Master"
"user_data_1"]] ; # Equipment Number
set ::SAPDat(EQUI:DATA_SPECIFIC:EQUICATGRY) "M" ; # Equipment category

If you want to manage a piece of equipment not only as an independent and individual
object, but also as a piece of material within the framework of inventory management,
you must provide it with serialization data, i.e.:

A unique combination of material and serial number

Stock information

Warehouse information

By using this data, you describe the piece of equipment as an individual item of a
particular material.

2.7.3

Configuration of Equipment data mapping from SAP to Teamcenter (reverse


mapping)

The following example shows how to configure T4S to store Equipment data in an Item Revision:
T4S_EquipmentMasterMapping2FunctionalityRevision=
IMAN_master_form_rev:FunctionalityRevision Master
T4S_EquipmentMasterFieldMapping2IMAN_master_form_rev:FunctionalityRevis
ion Master=
user_data_1

88

TESIS PLMware

Configuring T4S to support customer specific requirements

2.7.4

Definition of Equipment data mapping from SAP to Teamcenter (reverse


mapping)

In the reverse mapping you also have the possibility to address all the fields provided by the SAP
BAPIs and store them into Teamcenter attributes. The current T4S version supports the following
SAP data structures:

General Data for Technical Objects

Equipment specific data

The following example shows data mapping of the created equipment number and the transfer
time:
::T4X::TC::MAPPING::storeReverseMappingAttribute EquipmentMaster
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
user_data_1 $ExternalEquiNumber
::T4X::TC::MAPPING::storeReverseMappingAttribute EquipmentMaster
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
user_data_2 [clock format [clock seconds] -format "%Y.%m.%d"]

Teamcenter Gateway for SAP Configuration Guide V10.1

89

2.8 Transfer of Functional Location data


In SAP, a Functional Location describes the location or logical function of a tool (machine).

2.8.1

Configuration of Functional Location data mapping from Teamcenter to SAP

The following example shows how to configure a Teamcenter Item Revision (here of type
Functionality) that it is used for a SAP Functional Location:
T4S_FunctionalLocationTypeList =
FunctionalityRevision
#T4S_FunctionalLocationDisplayableTypeList =
#FunctionalityRevision

The following issues are SAP internal restrictions for the Functional Location
transactions that open a SAP window (Display, Create and Change):

It is not possible to hand data to SAP except from the data to identify the object,
so the SAP window is opened but it contains only its own default data, not those
from Teamcenter; but the transactions without opening a SAP window (Create
Direct and Change Direct) work as expected (similar to what you see with an
MM transaction)

Different from most SAP object types, a Display without a valid Functional
Location ID (no number given or the Functional Location with this ID does not
exist in this SAP system), does not open a SAP GUI at all but the T4S transaction
ends with the SAP error message Functional location <ID> does not exist

Specify the source data objects for the mapping to the SAP Functional Location:
T4S_FunctionalLocationMapping4FunctionalityRevision=
items_tag:Functionality
items_tag:Functionality:IMAN_master_form:Functionality Master
items_tag:Functionality:#__getAllProperties__#:Properties
IMAN_master_form_rev:FunctionalityRevision Master
#__getAllProperties__#:Properties
IMAN_classification:icm0

90

TESIS PLMware

Configuring T4S to support customer specific requirements

2.8.2

Definition of Functional Location data mapping from Teamcenter to SAP

For data mapping of Teamcenter data to the SAP Functional Location, T4S provides a data
structure analogous to the SAP Functional Location Master. This means that all fields which can be
addressed via BAPIs can be filled with values from Teamcenter. The current T4S version supports
the following SAP data structures:

Number (ID) of the Functional Location to be created

General Data for Technical Objects

Functional Location specific data

The individual fields available are shown in the tables in the appendix.
The examples below show data mapping of Functional Location number and category:
set ::SAPDat(FUNCLOC:PARAMETER:FUNCLOC) [string toupper
[::T4X::TC::MAPPING:: FieldMapping "$ItemRevisionType:
IMAN_master_form:$ItemRevisionType Master" "user_data_1"]]
set ::SAPDat(FUNCLOC:DATA_SPECIFIC:CATEGORY)

2.8.3

"S"

Configuration of Functional Location data mapping from SAP to Teamcenter


(reverse mapping)

The following example shows how to configure T4S to store Functional Location data in an Item
Revision:
T4S_FunctionalLocationMapping2FunctionalityRevision=
IMAN_master_form_rev:FunctionalityRevision Master
T4S_FunctionalLocationFieldMapping2IMAN_master_form_rev:
FunctionalityRevision Master=
user_data_1
user_data_2

Teamcenter Gateway for SAP Configuration Guide V10.1

91

2.8.4

Definition of Functional Location data mapping from SAP to Teamcenter


(reverse mapping)

In the reverse mapping you also have the possibility to address all the fields provided by the SAP
BAPIs and store them into Teamcenter attributes. The current T4S version supports the following
SAP data structures:

General Data for Technical Objects

Functional Location specific data

The following example shows data mapping of the created Functional Location number and the
transfer time:
::T4X::TC::MAPPING::storeReverseMappingAttribute FunctionalLocation
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
user_data_1 $ExternalFuncLocNumber
::T4X::TC::MAPPING::storeReverseMappingAttribute FunctionalLocation
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
user_data_2 [clock format [clock seconds] -format "%Y-%m-%d %R"]

92

TESIS PLMware

Configuring T4S to support customer specific requirements

2.9 Transfer of Vendor data


The term Vendor refers to a company that sells any items which may be for example used as raw
materials in your own production. From T4S point of view, the most important data are their
address and contact data.

2.9.1

The T4S Vendor processing is supported in Workflows only.


The only thing you may do with Vendor data in the Portal is Display.
In order to activate it, add the value VENDOR_DISPLAY to the T4S menu preference
T4S_Gateway_Menu_Explorer_Entries

Please see chapter Choose the T4S menu functions (transaction types between
Teamcenter and SAP) on p. 22 for more details on details about handling this
preference

T4S calls the SAP transaction Vendor display using JCo, so you have to install JCo in
order to use it. Please see chapter Configuring T4S Connectivity to SAP in the
Teamcenter Gateway for SAP Business Suite Installation Guide and chapter JCo
(Java Connector) in the Teamcenter Gateway for SAP Business Suite Preparing SAP
for Teamcenter Integration Guide for details on the JCo installation

In order to create or change a Vendor, T4S uses the SAP function module
/TESISPLM/T4S_CALL_TRANSACTION which is not standard SAP. So if you want to
use this T4S functionality, you have to deploy the transport package
TESISPLM_T4S_CALL_TRANSACTION, see chapter SAP transport packages for
T4S functionality in the Teamcenter Gateway for SAP Business Suite Prepare SAP for
Teamcenter Integration Guide

Configuration of Vendor data mapping from Teamcenter to SAP

The following example shows how to configure a Teamcenter Item Revision (here of type
Vendor) that it is used for a SAP Vendor:
T4S_VendorTypeList=
VendorRevision

Specify the source data objects for the mapping to the SAP Vendor:
T4S_VendorMapping4VendorRevision=
items_tag:Vendor
vendor_role_info:ManufacturerInfo
items_tag:Vendor:#__getAllProperties__#:Properties

Teamcenter Gateway for SAP Configuration Guide V10.1

93

2.9.2

Definition of Vendor data mapping from Teamcenter to SAP

For setting data to the SAP Vendor, T4S provides amongst others the following:

Vendor Number (ID)

Company Code

Complete address data (city, street)

The following example shows the data mapping of the Vendor number which is created from the
current Item ID with the Prefix V-:
set ::SAPDat(Vendor:BasicData:VendorNo)
"V-[string toupper
[::T4X::TC::MAPPING::FieldMapping $Item item_id]
Please find more pre-defined Vendor mapping data in the delivered mapping template file as well
as a list of possible data to set at the end of the file.

2.9.3

Configuration of Vendor data mapping from SAP to Teamcenter (reverse


mapping)

The following example shows how to configure T4S to store SAP Vendor data in Teamcenter:
T4S_VendorMapping2VendorRevision=
VendorRevision
items_tag:Vendor
T4S_VendorFieldMapping2VendorRevision =
object_name
object_desc
T4S_VendorFieldMapping2items_tag:Vendor=
supplier_addr
supplier_phone

2.9.4

Definition of Vendor data mapping from SAP to Teamcenter (reverse


mapping)

The following example shows data mapping of the Vendor transfer time:
::T4X::TC::MAPPING::storeReverseMappingAttribute Vendor
$ItemRevisionType object_desc "$ExternalVendorNumber transferred
at [clock format [clock seconds] -format "%Y-%m-%d %R"]"

94

TESIS PLMware

Configuring T4S to support customer specific requirements

2.10 Transfer of Purchase Info Record (PIR) data


In SAP, a Purchase Info Record (PIR) contains data about how to buy a specific material, e.g. the
Vendor, the contact person with this Vendor, the order unit and the typical delivery time.
The starting point in Teamcenter is a Commercial Part and a Manufacturer Part with the Vendor
information. Copy the Commercial Part and paste it as commercialparts into the Manufacturer
Part, so that it looks similar to the following screenshot:

Note that in the Teamcenter dialog File New Part, the type name shown may be Vendor
Part instead of Manufacturer Part; they may be used interchangeably.

The T4S PIR processing is supported in Workflows only. There is no T4S PIR
functionality to be started from the T4S Gateway menu in the Teamcenter client

In order to create or change a PIR, T4S uses the SAP function module
/TESISPLM/T4S_CALL_TRANSACTION which is not standard SAP. So if you want
to use this T4S functionality, you have to deploy the transport package
TESISPLM_T4S_CALL_TRANSACTION, see chapter SAP transport packages for
T4S functionality in the Teamcenter Gateway for SAP Business Suite Prepare SAP
for Teamcenter Integration Guide

2.10.1 Configuration of PIR data mapping


For using SAP PIR functionality, T4S needs in principle the same preferences as for MM: TypeList,
Mapping4, Mapping2 Please check the preferences template file for preferences
T4S_PurchaseInfoRecord* and the purchase info record mapping template file
t4s_pir_mapping_template.sd for details.

Teamcenter Gateway for SAP Configuration Guide V10.1

95

2.10.2 Definition of PIR data mapping from Teamcenter to SAP


For setting data to the SAP PIR, T4S provides amongst others the following data:

Purchase Info Record Number (ID)

Material Number (ID)

Vendor Number (ID)

Vendor Material Number (ID)

Vendor Material Group

The following example show the data mapping for the Vendor number in this PIR which is created
from the current Item ID with the Prefix V- (find more mapping data in the delivered mapping
template file t4s_pir_mapping_template.sd):
set ::SAPDat(PurchaseInfoRecord:BasicData:VendorNo)
"V-[string toupper [::T4X::TC::MAPPING::FieldMapping $Item item_id]
Please find more pre-defined PIR mapping data in the delivered mapping template file as well as a
list of possible data to set at the end of that file.

2.10.3 Definition of PIR data mapping from SAP to Teamcenter (reverse mapping)
The following example shows data mapping of the created Vendor number and the transfer time:
::T4X::TC::MAPPING::storeReverseMappingAttribute Vendor
$ItemRevisionType object_name $VendorNumber
::T4X::TC::MAPPING::storeReverseMappingAttribute Vendor
$ItemRevisionType object_desc "$ExternalVendorNumber transferred
at [clock format [clock seconds] -format "%Y-%m-%d %R"]"

96

TESIS PLMware

Configuring T4S to support customer specific requirements

2.11 Transferring manufacturing data general overview


A comprehensive set of transaction types is supported in the manufacturing area:

ROUTING: Create, Change, Read, Change header

INSPECTION PLAN: Create

MBOM: PLMXML based BOM transactions

PRODUCTION ORDER: Read Order

2.11.1 Transferring Standard Routing from Teamcenter PLMXML to SAP


T4S is able to provide several routing transfers to SAP. Changing a routing via T4S or reading its
content requires that TESIS customized BAPIs are deployed into the SAP environment which will
allow you changing a routing or its header or you may read a routing from SAP. Only the routing
create action is possible with the SAP standard BAPI.
Various business cases and use cases may be supported including a wide range of supported
routing objects including production resource tools and inspection characteristics.
T4S is shipped with mapping templates that can be used out of the box for a limited depth of
transaction according to your customization level of Teamcenter and SAP.
Learn more about Routing in the next chapter.

2.11.2 Transferring Inspection Plan from Teamcenter PLMXML to SAP


The transfer capabilities of T4S include Inspection Plans from Teamcenter to SAP which is a
specific type of routing for quality assurance purposes. Depending on your specific use case the
existing capabilities or customer specific enhancements can be provided upon your request.
Mapping files can be provided on a customer project basis.

2.11.3 Transferring Manufacturing BOM from Teamcenter PLMXML to SAP


T4S provides the possibility to transfer Bill Of Material based on a PLMXML export file from
Teamcenter. Such a solution may be interesting if the goal of your transaction would be to derive
several SAP BOM based on a configurable 150%-BOM in Teamcenter where you would like to
extract the multiple configured BOM in the interface instead of creating them in Teamcenter. Other
use cases may be also supported upon your request.
Mapping files can be provided on a customer project basis.

2.11.4 Transferring Production Order data from SAP to Teamcenter


The transfer of Production Order data from SAP to Teamcenter can be used to close the feedback
loop in your manufacturing scenario. Depending on the customers use case T4S can be
individually customized to support the transfer of production order header data and may be further
enhanced upon request.

Teamcenter Gateway for SAP Configuration Guide V10.1

97

2.12 Transfer of Standard Routing data


In SAP a Routing is a description of work steps uniquely identified by a routing group and routing
group-counter. It usually has a relation to a manufacturing BOM header material not limited to only
one relation. It also contains consumed materials and production resource tools that are used to
manufacture the allocated material within the process described in the list of operations.
In Teamcenter the corresponding structures and relations are typically created and maintained in
the Manufacturing Process Planner application and stored in so called collaboration contexts.

2.12.1 Configuration of routing data mapping from Teamcenter to SAP


The routing transfer is based on Teamcenter PLMXML using a so called Application-Interface
Object and is only supported as workflow transaction (no portal action!). You have to load the T4S
BMIDE Template for Teamcenter or you may create a proper AI-Object and Form in your database
to support the routing transaction based on your own BMIDE project model.
T4S is shipped with a routing mapping template which is able to transfer SAP standard routings type N with Operation, Material-Task-Allocation and Component-Allocation. The general
transaction capability is limited by the SAP BAPI. The mapping template is not fully configured to
support all possible objects but can be enhanced.
In order to run transactions based on TESIS custom BAPI you have to deploy an available SAP
transport to your system. Prior to that step you are limited to the routing create transactions.

There are some significant differences in the configuration of Teamcenter for routing
compared to other transactions

For Routing no routing specific Teamcenter preferences are needed

The only preference to adapt is TC_customization_libraries to load the


t4s_manufacturing.dll

There must be two transfer modes and the AI-Object available in the database
that are typically deployed when introducing the T4S BMIDE standard template to
your project respectively database.

There is no T4S portal mode available. All routing transactions are Teamcenter
workflow based. A workflow template T4S_ROUTING is shipped with the BMIDE
template

You have to configure T4S to start from a proper Teamcenter environment by setting
the TC_ROOT and TC_DATA and source the tc_profilevars.bat (preferably using
t4xcust, see there)

For some transactions you have to provide a SAP JCo connection for T4S (not
required for the create transaction)

The target object for a routing transaction is a MECollaborationContext or a subtype of it. For using
the standard mapping template you have to include a MEProductContext, a MEProcessContext
and a MEPlantContext with ConfigurationContext for each Structure including the proper
98

TESIS PLMware

Configuring T4S to support customer specific requirements

configuration rule. The process should consist of a header node of type MEProcess and a list of
operation of type MEOP. The root object of the MEProductContext reflects the BOM-Header
material to which the routing will be allocated. The MEPlantContext could contain plant and work
center information for the routing and for each operation.

Sample of a routing structure in Teamcenter


Pick the MECollaborationContext as target and run the template workflow T4S_Routing. A routing
is created in SAP reflecting the data model in Teamcenter according to your mapping.

Teamcenter Gateway for SAP Configuration Guide V10.1

99

After the transaction returned successfully you will find a new form attached to the Collaboration
Context with the Group and Counter information of the routing.

Result of the transaction in SAP:


100

TESIS PLMware

Configuring T4S to support customer specific requirements

2.12.2 Definition of Routing data mapping from Teamcenter to SAP


T4S has introduced a new XML reader engine and mapping syntax that allows much faster
transactions and based on a new mapping language that allows easier customization of the
mapping. It is essential to have some PLMXML and general routing structure knowledge to
successfully customize the routing mapping.
T4S ships with two different mapping files and PLMXML reader engines. The new one as
mentioned before is highly enhanced but requires a full manual migration of any existing mapping
code of previous T4S releases. In order to support existing routing mapping code we also support
Teamcenter Gateway for SAP Configuration Guide V10.1

101

the previous PLMXML engine. You can specify the usage of the parser type in your mapping.
Default is using the new parser.
To switch on support of previous routing syntax you should add to your t4s_mapping_config.sd the
following line:
set ::T4S::PLMXML::ROUTING::CtrlParam(useObjectServerBasedReader) "FALSE"
For detailed information about the new object based mapping syntax please refer to the document
PLMXML Reader Guide.

2.12.3 Configuration of Routing data mapping from SAP to Teamcenter (reverse


mapping)
Based on a standard SAP BAPI there is no reverse transaction of routing data beside the group
and counter that will be stored at a form related to the MECollaborationContext.
After the transaction you will find a new Form attached to the MECollaborationContext that
contains the group and counter of the created routing. In SAP you will find a routing with the group
and counter stored in the form.

102

Routing can be pretty complex objects, and transfers may fail if the mapping
parameters are not set to match each of the specifics of the Teamcenter and SAP
side customizations and/or configuration settings! Critical points are the plant, work
center, control key and setup type key, and you should always use a small and
simple routing object initially while testing the mapping configuration so that it is
easier to detect potential problems.

If a routing fails due to data issues and you did correct data in Teamcenter you
should always create a new workflow or you can create a new Sync in the AI-Object
of the previously failed workflow instead.

TESIS PLMware

Configuring T4S to support customer specific requirements

2.13 Transfer of network/WBS data


Teamcenter Schedule can be transferred to SAP via batch job to either network or WBS element
(work breakdown structure). The import depending on the settings can be done for SAP network to
Teamcenter schedule or SAP WBS element to Teamcenter schedule.

2.13.1 Limitations and requirements


T4S uses TC SOA functionality for the network/WBS handling, i.e. it needs the Teamcenter pool
manager and its Web application server (e.g. BEA or JBOSS) running. So this functionality can be
used on a Teamcenter 4-tier server only
Notes:

The T4S network/WBS processing is supported in Workflows only.

ProjectManagement.xlm shall be copied from var\template\t4sdemo into


tcdata\soa\policies.

The following mappings have to be sourced:


t4s_network_item_import_template.sd
t4s_wbs_item_import_template.sd
t4s_query_mapping_template.sd
t4s_schedule_mapping_template.sd

T4S_SCHEDULE Workflow template needs to be imported

T4S_NETWORK_QUERY and T4S_WBS_ELEMENT_QUERY need to be imported and

set to be run by user: $TC_BIN/tc_set_query_where_run -u=<user name> -p=<password> query=<query_name>


-run=user

The following set of preferences has to be defined:


T4S_ScheduleTypeList Schedule
T4S_ScheduleMapping4Schedule Schedule attributes list
T4S_ScheduleMapping2Schedule Schedule
T4S_ScheduleFieldMapping2Schedule - T4S_Properties:Properties
T4X_SupportedUserQueries List of user query names (T4S_WBS_ELEMENT_QUERY,
T4S_NETWORK_QUERY)
T4S_ImportObject_SupportedTypes - List of user query names with * at the end
T4X_QUERY_TargetSystem4T4S_NETWORK_QUERY set to T4S
T4X_QUERY_TargetSystem4T4S_WBS_ELEMENT_QUERY set to T4S

Teamcenter Gateway for SAP Configuration Guide V10.1

103

Needed SOA settings


# URL for accessing Teamcenter SOA services ("http(s)://<host>:<port>/<application>")
# use port 7001 for WebLogic or 8080 for WebSphere
set ::T4X::SOA::CtrlParam(TcSoaUrl)

"http://localhost:7001/tc"

# HTTP proxy is used for SAP Enterprise services


set ::T4X::SOA::CtrlParam(HTTPProxyHost)

"proxy"

set ::T4X::SOA::CtrlParam(HTTPProxyPort)

80

# HTTP proxy user and password


set ::T4X::SOA::CtrlParam(HTTPProxyUsername) "#!!#!!"
set ::T4X::SOA::CtrlParam(HTTPProxyPassword) "#!!#!!"
# for Enterprise Workplace (set proxy!):
set ::T4X::SOA::CtrlParam(SAPHostAndPort)

http://erp.esworkplace.sap.com

# SAP client (deutsch: Mandant, e.g. 800)


set ::T4X::SOA::CtrlParam(SAPClient)

"800"

# SAP service URL prefix (e.g. for project services this is usually "sap/bc/srt/pm/sap")
set ::T4X::SOA::CtrlParam(SAPServicePrefix) "sap/bc/srt/pm/sap"
# SAP service profile (e.g. "default_profile")
set ::T4X::SOA::CtrlParam(SAPServiceProfile) "default_profile"
# SAP service profile version (e.g. "2")
set ::T4X::SOA::CtrlParam(SAPServiceProfileVersion) "2"
# SAP service binding (e.g. "binding_t_https_a_http" means transfer type https and http/basic
# authorization)
set ::T4X::SOA::CtrlParam(SAPBindingType)

"binding_t_http_a_http"

::SYSBase::evalCryptCode
"276abd5012e13c4980cdda75f09a7098f00a4cc65c39a114ce4af1fa9f41b1d31b0baa76ade4f705e
5655ba99767f2a3569741f56d0242b874915ebe5b4c5827e5ba5dc2bdbf9f9646472ef72addf700a6
d347b57f9021e54edffa6bd2e6df65d3c382644523b03d9fa1f1d1e998dfc302ced7e97beea62fba9a0
3f5d2"

2.13.2 Transfer of network data mapping from Teamcenter to SAP


# Schedule to WBS / NETWORK
set ::T4S_Defaults(TC2SAPType)

"NETWORK"

set ::T4S_Defaults(ProjectProfile)

"U"

104

TESIS PLMware

Configuring T4S to support customer specific requirements

set ::T4S_Defaults(NetworkProfile)

"Z000002"

The transfer of Schedule to SAP is done by T4S_SCHEDULE workflow.


The variable ::T4S_Defaults(TC2SAPType) has to be set to "NETWORK"
If the attribute SAP2ProjectID is empty new project with the ProjectID=itemID will be searched for.
If it doesnt exist yet it will be created otherwise an update will be run.
If the attribute SAP2NetworkID is empty a new network for this project will be created, otherwise
the existing network will be updated

Teamcenter Gateway for SAP Configuration Guide V10.1

105

2.13.3 Transfer of WBS data mapping from Teamcenter to SAP


# Schedule to WBS / NETWORK
set ::T4S_Defaults(TC2SAPType)

"WBS"

set ::T4S_Defaults(ProjectProfile)

"U"

set ::T4S_Defaults(NetworkProfile)

"Z000002"

The transfer of Schedule to SAP is done by T4S_SCHEDULE workflow.


The variable ::T4S_Defaults(TC2SAPType) has to be set to WBS"
If the attribute SAP2ProjectID is empty new project with the ProjectID=itemID will be searched for.
If it doesnt exist yet it will be created otherwise an update will be run.
If the attribute SAP2NetworkID is empty a new WBS element with the ID A-<itemId>-1 for this
project will be created, otherwise the existing WBS element will be updated.

106

TESIS PLMware

Configuring T4S to support customer specific requirements

2.13.4 Configuration of network data mapping from SAP to Teamcenter


2.13.4.1 Trigger the import batch job

2.13.4.2 Network import job

Teamcenter Gateway for SAP Configuration Guide V10.1

107

2.13.4.3 Import network to Schedule mapping

2.13.5 Configuration of WBS data mapping from SAP to Teamcenter


2.13.5.1 Trigger the import WBS batch job

108

TESIS PLMware

Configuring T4S to support customer specific requirements

2.13.5.2 WBS import job

2.13.5.3 Import WBS to Schedule mapping

Teamcenter Gateway for SAP Configuration Guide V10.1

109

2.14 Work breakdown Structure Bill of Material Data Mapping


Beside the normal BOM transfer T4S also supports OOTB the transfer of a Teamcenter BOM
structure to the corresponding Work Breakdown Structure Bill of Material (WBS BOM). The
configuration and the mappings are done in a similar way as for the normal BOM transfer. The
OOTB functionality is provided by a WBS BOM specific action and rule handler and the provided
t4s_wbs_bom_mapping_template.sd. All relevant information can be found in the mapping
template and or in the description of the normal BOM transfer.

2.15 Transfer of Generic Objects


The Generic Object data mapping allows the transfer of data to a target object in SAP that is not
covered by the OOTB functionality of T4S. The functionality is provided by a generic action and
rule handler and the generic object mapping file.

The generic mapping can be applied to all Teamcenter POM object types

For the transfer of structures based on views, use the generic BOM mapping and
provide the handler argument -useView4Transfer = TRUE for using the view object.
The transfer of Generic BOM is described in the next chapter.

2.15.1 Configuration of Generic data mapping from Teamcenter to SAP


The following example shows how to configure a Generic Object that it is used in T4S only with an
Item Revision. The term GenericObj in this example can be replaced by any other declaration for
different cases of Teamcenter object types so that the mapping can be used for multiple purposes.

110

The T4S Action-Handler T4S-transfer-GenericObject and Rule-Handler T4Svalidate-GenericObject will need the argument -TargetTypeName with the value
GenericObj (or another custom value you define for your implementation) in order
to use the relevant preferences and branch in your object mapping. For more
detailed information about the handler please see Chapter 2.21 Workflow Handler
Functions.

It is also possible to use the MaterialMaster preferences for the Generic Object
Handler. In this case for example set the handler argument -TargetTypeName to
MaterialMaster.

TESIS PLMware

Configuring T4S to support customer specific requirements

Define the object types that are allowed for T4S:


T4S_GenericObjTypeList=
ItemRevision

Specify the source data objects for the mapping:


T4S_GenericObjMapping4ItemRevision=
items_tag:Item
items_tag:Item:#__getAllProperties__#:Properties
items_tag:Item:IMAN_master_form:Item Master
IMAN_master_form_rev:ItemRevision Master
#__getAllProperties__#:Properties

2.15.2 Definition of Generic data mapping from Teamcenter to SAP


For defining the attribute mapping for a MM transaction please review the delivered mapping
template file t4s_genobj_mapping_template.sd. The procedure TC_Object2SAP_Object is most
relevant.

The following example shows a correct Material mapping from an Item Revision:
set ::SAPDat(Material:HeadData:Material)
[::T4S::TC::MAPPING::FieldMapping
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
"SAP_MATNO"]
set ::SAPDat(Material:HEADDATA:IND_SECTOR)
$::T4S_Defaults(Industry)
set ::SAPDat(Material:HEADDATA:MATL_TYPE)
$::T4S_Defaults(SAPMaterialType)
set ::SAPDat(Material:HEADDATA:BASIC_VIEW)"X" ;# Basic Data View
set ::SAPDat(Material:CLIENTDATA:CAD_ID)"X"

Teamcenter Gateway for SAP Configuration Guide V10.1

111

2.15.3 Configuration of Generic data mapping from SAP to Teamcenter (reverse


mapping)
The following example shows how to configure T4S to store Generic Object data in an Item
Revision:

T4S_GenericObjMapping2ItemRevision=
IMAN_master_form_rev:ItemRevision Master

T4S_GenericObjFieldMapping2IMAN_master_form_rev:ItemRevision Master=
user_data_1
user_data_2
user_data_3

2.15.4 Definition of generic data mapping from SAP to Teamcenter (reverse


mapping)
The following example shows how data are stored in an Item Revision during the Generic Object
transaction:

::T4X::TC::MAPPING::storeReverseMappingAttribute GenericObj
"ItemRevision:IMAN_master_form_rev:ItemRevision Master" user_data_1
"GenericObject mapping test"

In this example, we use ItemRevision instead of $ItemRevisionType, so this call will


only work for the Item type Item, not for any other types.

If you want to get Generic Object data, you have to execute the following function prior to asking
SAP for data:

set rc [::T4S::GENOBJ::CUSTOM::MAPPING::getObjectInfo $TransactionId


$TargetTypeName $ObjectKey]

112

TESIS PLMware

Configuring T4S to support customer specific requirements

Then, you could for example store the content of the variable MyValue into user_data_3:

::T4S::TC::MAPPING::storeReverseMappingAttribute GenericObj
"$ItemRevisionType:IMAN_master_form_rev:$ItemRevisionType Master"
user_data_3 $MyValue

Although in the reverse mapping the parameter MaterialMaster is used, this does not
necessary imply a material transaction! The parameter has no meaning anymore but
must be provided.

2.16 Generic BOM Data Mapping


The Generic BOM data mapping allows the transfer of BOM data to a target object in SAP that is
not covered by the OOTB functionality of T4S. The functionality is provided by a generic action and
rule handler and the genbom mapping file.

The Generic BOM Mapping can be applied to all Teamcenter POM object types

2.16.1 Configuration of Generic BOM data mapping from Teamcenter to SAP


The following example shows how to configure a Generic BOM Object that it is used in T4S only
with an Item Revision. The term GenericBom in this example can be replaced by any other
declaration for different cases of Teamcenter object types so that the mapping can be used for
multiple purposes.

The T4S Action-Handler T4S-transfer-GenericObject and Rule-Handler T4Svalidate-GenericObject will need the argument -TargetTypeName with the value
GenericBom (or another custom value you define for your implementation) in
order to use the relevant preferences and branch in the Generic BOM mapping.

Additionally the argument -useView4Transfer with the value YES and


BomHeaderTypeList e.g. with the value MaterialMaster.

For detailed information about the handler please see Chapter 2.21 Workflow
Handler Functions.

Teamcenter Gateway for SAP Configuration Guide V10.1

113

For the definition of the preferences you can use the examples for the standard
OOTB transfer types.

Define the ObjectTypes that are allowed for T4S:


T4S_GenericBomTypeList=
view

Define the Revision Rule


T4S_GenericBomMapping4view =
Latest Working

Specify the source data objects for the mapping:


T4S_GenericBomLineMapping4ItemRevision=
items_tag:Item
items_tag:Item:#__getAllProperties__#:Properties
items_tag:Item:IMAN_master_form:Item Master
IMAN_master_form_rev:ItemRevision Master
#__getAllProperties__#:Properties

Specify the source data objects for the mapping:


T4S_GenericBomOccurrenceNotes4view =
bl_quantity
bl_sequence_no

114

TESIS PLMware

Configuring T4S to support customer specific requirements

2.16.2 Definition of Generic BOM data mapping from Teamcenter to SAP


For defining the attribute mapping for a generic BOM transaction please review the delivered
mapping template file t4s_genbom_mapping_template.sd. The procedures
TC_Object2SAP_Object and TC_Object2SAP_ObjectPosition are most relevant.
The following example shows a correct Material mapping from an Item Revision:
set ::SAPDat(BillOfMaterial:HeadData:Material)
[::T4X::TC::MAPPING::IndexedFieldMapping 0 $Item item_id

set Quantity [::T4X::TC::MAPPING::IndexedFieldMapping


$TcPositionIndex BomLine bl_quantity]

2.16.3 Configuration of Generic BOM data mapping from SAP to Teamcenter


(reverse mapping)
The following example shows how to configure T4S to store ECM data in an Item Revision:

T4S_GenericBomMapping2view =
structure_revisions:ItemRevision:IMAN_master_form_rev:ItemRevision
Master

T4S_GenericBomFieldMapping2structure_revisions:ItemRevision:IMAN_master
_form_rev:ItemRevision Master

user_data_1
user_data_2
user_data_3

2.16.4 Definition of Generic BOM data mapping from SAP to Teamcenter (reverse
mapping)
The following example shows how data are stored in an Item Revision during the Generic BOM
transaction:

::T4X::TC::MAPPING::storeReverseMappingAttribute MaterialMaster
"ItemRevision:IMAN_master_form_rev:ItemRevision Master" user_data_1
"GenericBom mapping test"

Teamcenter Gateway for SAP Configuration Guide V10.1

115

116

In this example, we use ItemRevision instead of $ItemRevisionType, so this call will


only work for the Item type Item, not for any other types.

Although in the reverse mapping the parameter MaterialMaster is used, this does not
necessary imply a material transaction! The parameter has no meaning anymore but
must be provided.

TESIS PLMware

Configuring T4S to support customer specific requirements

2.17 Data Transfer without triggering it from within Teamcenter


T4S is a bi-directional gateway to exchange data between both systems. The previous chapters
explained in detail how to set up data transfer initiated from within Teamcenter. This chapter
delivers some basic explanation on how to initiate data transfer from SAP to Teamcenter.

2.17.1 General Import steps


In contrast to T4S transactions triggered from Teamcenter, all transfers from SAP to Teamcenter
are executed asynchronously. This means that no immediate feedback can be delivered to SAP
trigger event and further that it takes some time until the data transfer is completed. Required
steps:
1. SAP event triggers transfer by creating entry in custom SAP staging table (ZPTC table)
2. T4S scheduled trigger reads entry and creates a batch job
3. Batch job is executed (as defined in mapping file)
a. Read SAP data
b. Find related TC object
c. Update / Create TC object
d. Update TC attributes
e. Additional actions like set status, trigger a TC workflow, send email
f.

Update entry in ZPTC table (status S or E)

4. Batch job status indicates success or failure of import

Additional information can be found in "Teamcenter Gateway for SAP Business Suite
Preparing SAP for Teamcenter Integration Guide" chapter 8

See details on ZPTC table in chapter 8.1 Z-Table:

See details on SAP event trigger in chapter 8.2 SAP Event trigger

Example:
Use case a material master is modified in SAP. On save (1) the SAP user exit catches the event
and creates a new entry in ZPTC table (2). The T4S trigger picks up the new entry from ZPTC
table (E2S_STATUS is BLANK) (3), creates a T4S batch job (4). When the batch job is executed
the T4S mapping engine identifies corresponding TC object and updates attributes (5). As last step
the status in ZPTC table is updated (6).

Teamcenter Gateway for SAP Configuration Guide V10.1

117

Logic in User Exit


Does a ZPTC entry for this MM alread exists?
no, insert entry to ZPTC table
- assign ID from number range
- default field value OBJECT_TYP to MATERIAL
- store Material number to field OBJECT_ID
- store plant ID to field REASON1
- do not set value to E2S_STATUS
update ZPTC entry

SAP Material Master

Transaction MM01
or MM02
Modify data
save

User exit triggers from MM01/02 save

Custom
logic in user
exit

/TESISPLM/ZPTC_INSERT

2
SAP table: /TESISPLM/ZPTC
Trigger
Script
monitors
SAP table.

4
T4S Batch
Program

ID
10
11

OBJECT_TYP OBJECT_ID
MATERIAL
47125689
MATERIAL
47125690

Mapping Logic:
Find TC Item =
OBJECT_ID
Error if Item does not exist
Read SAP MM data
Update attributes
Update ZPTC entry
E2S_STATUS

REASON1
1000
3000

E2S_STATUS
S
6

/TESISPLM/ZPTC_UPDATE

E2S_STATUS values are:


BLANK: waiting to be
processed by T4S
Q: being processed by T4S
E: T4S finished with error
S: T4S finished successfully
More status are configurable

118

To support this use case following steps need to be done:

ZPTC table and ZPTC functions needs to be imported to SAP.

A SAP trigger event needs to be defined

T4S batch client needs to be configured, see Teamcenter Gateway Batch Server
Guide for details

A T4S scheduler script needs to monitor ZPTC table (see following chapter)

TESIS PLMware

Configuring T4S to support customer specific requirements

2.17.2 Monitor SAP staging table (ZPTC)


T4S needs to monitor entries in the SAP table ZPTC from outside SAP and initiate data transfer
to Teamcenter by creating a T4S batch job. You need to define a TCL script that performs required
steps and schedule the script to run on desired interval, see the following chapters for details.

2.17.2.1 Trigger Script


The following example gives you a ready to use script that will allow you to check SAP ZPTC table
and create desired batch jobs for found entries.
You can run this script on demand from web frontend or as scheduled script. If you run it as
scheduled script, make sure that the default input parameters match your needs.
Default parameters that need to be set in script for scheduled run:
set ::g_BatchTemplate

"MM"

The script will execute the procedures in following order:


triggerBatchJob

define and execute ZPTC query

checkJobIsValid

validate if batch job should be created

compareObjectNr

do additional check on object id

Prevent T4S from creating un-desired batch jobs that will fail on TC data import, i.e.
object ID does not match pattern that identifies relevant objects in Teamcenter.

Include also logic to SAP event trigger function to not even create ZPTC entry in the
first place for non-Teamcenter relevant objects (if possible with SAP means)

#===================================================
# TESIS PLMware

GmbH

# Baierbrunnerstrasse 15, D-81379 Muenchen, Tel: 089-747377-0


#===================================================
#
# -------------------------------------------------# Project:

T4S

# File:

trigger_sap_zjob.tcl

# --------------------------------------------------

::TestScript::setScriptDesc "Trigger Z-Table import job"


Teamcenter Gateway for SAP Configuration Guide V10.1

119

# <ARGNAME> <DESCRIPION> <[list OPTION VAULE]>


#::TestScript::setScriptParam
"loop"]
::TestScript::setScriptParam
(1 min = 60000)"

"Mode"
"Interval"

"Mode" [list "single"


"Interval in milliseconds

::TestScript::setScriptParam "BatchTemplate"
[list MM DIR BOM ECM PO WC POBOM]

"Used Batchjob template"

::TestScript::setScriptParam "ObjectType"
"Z-Table Object Type
(optional)" [list "" MATERIAL DOCUMENT BOM ECM PO WC POBOM]
::TestScript::setScriptParam
Batchjob (optional)"

"AdditionalInfo" "AdditionalInfo for

::TestScript::checkTestParam $::argv

set ::g_ObjectType ""

if {[llength $argv] > 1} {


foreach {Parameter Value} [lrange $::argv 1 end] {
switch -exact -- $Parameter {
-Interval

{set ::g_Interval $Value}

-BatchTemplate

{set ::g_BatchTemplate $Value}

-ObjectType

{set ::g_ObjectType $Value}

-AdditionalInfo

{set ::g_AdditionalInfo $Value}

-Mode

{set ::g_Mode $Value}

}
}
} else {
printUsage
}

proc printUsage {} {
puts "usage:"
puts "wrong usage: [lindex $::argv 0] -Interval Interval
-BatchTemplate BatchTemplate -Mode RunMode AdditionalInfo
AdditionalInfo -ObjectType ObjectType"
120

TESIS PLMware

Configuring T4S to support customer specific requirements

exit 0
}

# Test that all needed parameters have been passed in


foreach Parameter {::g_Interval ::g_BatchTemplate ::g_Mode} {
if {![info exists $Parameter]} {
puts "Missing $Parameter"
printUsage
}
}

# -------------------------------------------------# Method:

compareObjectNr

# Description:

Compares a given ObjectNr to a list of valid ObjectNr

# Created:

kh, 20050823

# Return
#
# Changes:
# CHANG-DDMMYYYY-HACKER: aenderungaenderungaenderung
# -------------------------------------------------proc compareObjectNr { ObjNr } {
set rc $::g_const_FALSE
if {[info exists ValidObjNr($ObjNr)] == 1} {
set rc $::g_const_TRUE
}
# since we have no list to compare, we return TRUE as default
set rc $::g_const_TRUE
return $rc
}

# -------------------------------------------------# Method:

checkJobIsValid

# Description:

Checks if the Object is allowed to be processed

# Created:

kh, 20050823

Teamcenter Gateway for SAP Configuration Guide V10.1

121

# Return
#
# Changes:
# CHANG-DDMMYYYY-HACKER: aenderungaenderungaenderung
# -------------------------------------------------proc checkJobIsValid { ZPTC_Id } {
set rc_func

$::g_const_FALSE

set ::g_ObjectID $::g_const_NOT_FOUND

#
# Use Z-Table ID to get the object ID
#
set rc [::TPSAP::ZPTC:ZPTC_Get_Detail $ZPTC_Id]

if { $rc == "0"} {
set ::g_ObjectID $::sap_result_array(ZPTC_RETURN:OBJECT_ID)

if { $::g_ObjectType == "DOCUMENT" } {
set tmp_DocumentKey [split $::g_ObjectID ";@;"]
if { [llength $tmp_DocumentKey] == 10 } {
set ::g_ObjectID [format "%25s%3s%3s%2s" [lindex
$tmp_DocumentKey 0] [lindex $tmp_DocumentKey 3] [lindex $tmp_DocumentKey
6] [lindex $tmp_DocumentKey 9]]
} else {
puts "ERROR: The DocumentKey from SAP has an invalid format ( ->
$::g_ObjectID ). It should be like DokNr;@;DokAr;@;DokTl;@;DokVr..."
return $::g_const_FALSE
}
} elseif { $::g_ObjectType == "BOM" } {
#
# ::g_ObjectID is the BOM key from SAP concatenated with the sign
';@;'
#
set tmp_BomKey [split $::g_ObjectID ";@;"]
if { [llength $tmp_BomKey] == 22 } {

122

TESIS PLMware

Configuring T4S to support customer specific requirements

set
$tmp_BomKey
$tmp_BomKey
$tmp_BomKey

::g_ObjectID [format "%18s%4s%1s%2s%12s%12s%8s%8s" [lindex


0] [lindex $tmp_BomKey 3] [lindex $tmp_BomKey 6] [lindex
9] [lindex $tmp_BomKey 12] [lindex $tmp_BomKey 15] [lindex
18] [lindex $tmp_BomKey 21]]

} else {
puts "ERROR: The BomKey from SAP has an invalid format ( ->
$::g_ObjectID ). It should be like
MatNr;@;Plant;@;Usage;@;Alternative;@;AenNr;@;AenNr;@;Datuv;@;Datub"
return $::g_const_FALSE
}
}

#
# Check if this entry has already been moved to the queue,
# then do not process it again
#
set Status_E2S $::sap_result_array(ZPTC_RETURN:STATUS_E2S)

if { $Status_E2S != "Q" } {
#
# Check if it is a valid object ID
#
set rc_func [compareObjectNr $::g_ObjectID]
} else {
puts "T4S-INFO: JobStatus equal Q -> Stop Action because job was
already moved tho batchserver-queue..."
set rc_func $::g_const_QUEUED
}
}

return $rc_func

# -------------------------------------------------# Method:

triggerBatchJob

Teamcenter Gateway for SAP Configuration Guide V10.1

123

# Description:

Run query and evaluate given ZPTC entries

# Created:

kh, 20050823

# Return
#
# Changes:
# CHANG-DDMMYYYY-HACKER: aenderungaenderungaenderung
# -------------------------------------------------proc triggerBatchJob { args } {

puts "Ready to run ZPTC Trigger Script for BatchTemplate


>$::g_BatchTemplate<, ObjectType >$::g_ObjectType<, Interval
>$::g_Interval<, Mode >$::g_Mode< and AdditionalInfo
>$::g_AdditionalInfo<"

# Now define the search criteria to identify ZPTC entries that shall
# trigger the creation of a new batch job
set Where0 "STATUS_E2S = ''"
set Where1 "and DELETED = ''"
set Where2 ""

if { $::g_ObjectType == "" } {
switch -exact -- [string toupper $::g_BatchTemplate] {
MM

{ set ::g_ObjectType "MATERIAL" }

DIR

{ set ::g_ObjectType "DOCUMENT" }

BOM

{ set ::g_ObjectType "BOM" }

ECM

{ set ::g_ObjectType "ECM" }

PO

{ set ::g_ObjectType "PO" }

WC

{ set ::g_ObjectType "WC" }

POBOM

{ set ::g_ObjectType "POBOM" }

EQUI

{ set ::g_ObjectType "EQUI" }

FUNCLOC

{ set ::g_ObjectType "FUNCLOC" }

VENDOR

{ set ::g_ObjectType "VENDOR" }

PIR

{ set ::g_ObjectType "PIR" }

IPPE_NODES

124

{ set ::g_ObjectType "IPPE_NODES" }

TESIS PLMware

Configuring T4S to support customer specific requirements

NETWORK

{ set ::g_ObjectType "NETWORK" }

WBS

{ set ::g_ObjectType "WBS" }

VARIANT_OPTIONS { set ::g_ObjectType "VARIANT_OPTIONS" }


}
}

puts "ObjectType >$::g_ObjectType<..."

if { $::g_ObjectType != "" } {
set Where2 "and OBJECT_TYP = '$::g_ObjectType'"
} else {
puts "STOP ACTION - No ObjectType for Z-Table call!"
exit 0
}

if {[::T4S::CONNECTION2SAP::testSAPLogin] == "ERROR" } {
exit 0
}

set rc [::TPSAP::ZPTC::ZPTC_Dyn_Search $Where0 $Where1 $Where2]

puts "Result of ZPTC_Dyn_Search -> $rc"

if { $rc != "" } {
set tmp_str [string range $rc 0 0]
# check if the retrieval was successful (then it returns the
# number of matches or one of the following return codes:
# ERROR, NOT_LOGIN, NOT_FOUND
if { $tmp_str > "0" && $tmp_str <= "9"} {
foreach Element [lsort -command
::TPSAP::compareIndexedInterfaceTable [array names ::sap_result_array
TAB_RESULT:ID:*]] {
set ZTAB($Element) $::sap_result_array($Element)
}
puts "T4S-INFO: Found $tmp_str Elements to process"

Teamcenter Gateway for SAP Configuration Guide V10.1

125

foreach Element [lsort -command


::TPSAP::compareIndexedInterfaceTable [array names ZTAB TAB_RESULT:ID:*]]
{
set el [string trim $ZTAB($Element)]

set rc [checkJobIsValid $el]

if { $rc == $::g_const_TRUE } {
puts "T4S-INFO: Create ZPTC-Batchjob for Id $el"
# now we can create BatchJobs...
set Status [catch {set rc
[::T4X::BATCHJOB::IMPORT::createBatchjob "T4S_IMPORT_$::g_BatchTemplate"
"$::g_ObjectID" "SAP2TC" "$el" "$::g_AdditionalInfo"]}]
puts "+++ createBatchjob Status = $rc +++"
if {[lindex $rc 0] != "OK"} {
if {[catch {puts [binary format {H*} [lindex $rc 1]]} ] == 1}
{puts [lindex $rc 1]}
}

#
# CleanUp
#
unset ::g_ObjectID

puts "T4S-INFO: Create ZPTC-Batchjob for ZPTC Id >$el< ->


Status = $rc"

if { $rc == "OK" } {
# set the status of the job to "Q" (QUEUE), so that the job
#

is not taken again into the Queue:

#puts "T4S-INFO: Mark Job as >moved to queue< returned with:


# [::T4S::ZPTC::Set_ZPTC_Status $el "Q" "JOB ALREADY MOVED
# TO T4S-BATCHSERVER-QUEUE"]"
}
} elseif { $rc == $::g_const_QUEUED } {

126

TESIS PLMware

Configuring T4S to support customer specific requirements

puts "T4S-INFO: ZPTC-Batchjob for ZPTC Id $el is NOT PROCESSED


BECAUSE checkJobIsValid returns -> $rc"
#
# mark the not queued job as deleted
#
if { $el != "" } {
#set rc [::TPSAP::ZPTC::ZPTC_Delete "X" $el]
#puts "T4S-INFO: Set Deletion Flag for ZPTC Id >$el< finished
# with $rc..."
}
} else {
puts "T4S-INFO: STOP ACTION - checkJobIsValid returns -> $rc"
::T4S::ZPTC::Set_ZPTC_Status $el "E" "JOB NOT PROCESSED checkJobIsValid returned with $rc!"
}
}
} else {
puts "ERROR while executing ::TPSAP::ZPTC::ZPTC_Dyn_Search -> $rc"
}
} else {
puts "ERROR while executing ::TPSAP::ZPTC::ZPTC_Dyn_Search ->
no Returncode given"
}
}
# some defaults (do not change!)
set g_const_NOT_FOUND "NOT_FOUND"
set g_const_TRUE
"TRUE"
set g_const_FALSE
"FALSE"
set g_const_QUEUED
"QUEUED"
set ::g_BatchTemplate "MM"
#############################################
# Loop fuer Polling
while {1} {
set g_ObjectID $g_const_NOT_FOUND
puts "Start trigger..."
triggerBatchJob

Teamcenter Gateway for SAP Configuration Guide V10.1

127

if { $::g_Mode == "single" } {
exit 0
}

after $::g_Interval
}
exit 0

See more details on how to use the scheduler in Teamcenter Gateway


Administration Guide, chapter TOOLS Scheduler

2.17.3 Supported types for Import


T4S offers a variety of pre-defined import batch jobs and import mapping templates. Be sure to use
the correct mapping file to configure the data import for the given object type. Available types are:
SAP object
type

ZPTC entry:
OBJECT_TYP

Batch job type

Mapping template

Material
master

MATERIAL

T4S_IMPORT_MM

t4s_mm_item_import_template.sd

Document
Info Record

DOCUMENT

T4S_IMPORT_DIR

t4s_dir_item_import_template.sd

Bill of
Material

BOM

T4S_IMPORT_BOM

t4s_bom_item_import_template.sd

Change
master

ECM

T4S_IMPORT_ECM

t4s_ecm_item_import_template.sd

Production
Order

PO

T4S_IMPORT_PO

t4s_prodorder_import_template.sd

Work center

WC

T4S_IMPORT_WC

t4s_workcenter_import_template.sd

Production
Order BOM

POBOM

T4S_IMPORT_POBOM

t4s_prodorder_bom_import_template.sd

Equipment

EQUI

T4S_IMPORT_EQUI

t4s_equi_item_import_template.sd

128

TESIS PLMware

Configuring T4S to support customer specific requirements

Functional
Location

FUNCLOC

T4S_IMPORT_FUNCLOC

t4s_funcloc_item_import_template

Vendor

VENDOR

T4S_IMPORT_VENDOR

t4s_vendor_item_import_template

Purchase Info
Record

PIR

T4S_IMPORT_PIR

t4s_pir_item_import_template.sd

Single Level
iPPE
Structure

IPPE_NODES

T4S_IMPORT_IPPE_NODES

t4s_ippe_structure_import_template.sd

Network

NETWORK

T4S_IMPORT_NETWORK

t4s_network_item_import_template.sd

Work
breakdown
structure

WBS

T4S_IMPORT_WBS

t4s_wbs_item_import_template.sd

Work
breakdown
structure Bill
of Material

WBS_BOM

T4S_IMPORT_WBS_BOM

t4s_wbs_bom_import_template.sd

Teamcenter
Variant
Options

VARIANT_OPTIONS

T4S_IMPORT_VARIANT_OPTIONS

t4s_variant_option_import_template.sd

Additionally T4S provides two batch job types and import mapping templates to support other
object types as well. Additional configuration effort will be required to read SAP data within the
mapping files:
ZPTC entry:
OBJECT_TYP

Batch job type

Mapping template

Usage

OBJECT

T4S_IMPORT_OBJECT

t4s_object_import_template.sd

Support any other SAP


business object for import
mapping

META

T4S_IMPORT_META

t4s_meta_import_template.sd

This job type is used for


any TC import job that is
not necessarily connected
to one SAP business
object at all.

Teamcenter Gateway for SAP Configuration Guide V10.1

129

In general T4S is able to create and update Teamcenter objects of following types:
Item
ItemRevision
Form
GDE
Dataset
view
ICO

2.17.4 Import Mapping


The different import mapping templates follow the same steps in general with one exception, the
META Import mapping (details on this see below)
1. Get data from related SAP object
2. Select corresponding Teamcenter object (either use TC query or selects with ITK calls TC
object type depends of job type, i.e. ItemRevision, Item, view, dataset)
3. Create missing Teamcenter object (optional)
4. Update attributes on Teamcenter object (also attributes on related objects)
5. Update Teamcenter object (trigger workflow,set status)
6. Cleanup

For the Material master import batch job the mapping procedures are processed in this order:
1. getMaterialMasterInfo
This procedure will read the related SAP material master information. Input parameter
Material number is retrieved from batch job attribute ImportObjectId.
valid return of function:
SKIPPED batch job execution will be aborted, ZPTC entry (if configured) will
be update to E2S_STATUS C (cancelled)
OK $Materialnumber batch job execution will be continued
ERROR $message batch job execution will be aborted, ZPTC entry (if configured) will be
update to E2S_STATUS E (error)
2. selectTC_Object
This procedure will identify the corresponding Teamcenter Item Revision. You can either
use a Teamcenter query or if the material number matches the Item ID you can use ITK
calls to get the latest Item Revision.
valid return parameters:
OK $ItemRevisionTag batch job execution will continue with proc
SAP_MaterialMasterMapping2TC_Object
FOUND $ItemRevisionTag batch job execution will continue with proc
SAP_MaterialMasterMapping2TC_Object
NOT_FOUND $Message batch job execution will continue with proc createTC_Object
(using search query)
130

TESIS PLMware

Configuring T4S to support customer specific requirements

ITEMID_DOESNT_EXIST $Message batch job execution will continue with proc


createTC_Object (using ::ITK::ITEM_exists)
SKIPPED batch job execution will be stopped successfully without an error
<any other return status> $ErrorMessage batch job execution will be stopped with an
error
3. createTC_Object
This procedure allows you to create a new TC object (Item and ItemRevision). If you do not
want to create a new TC object but continue to next import step make sure that the
procedure selectTC_Object always finds the correct object.
valid return parameters:
OK $objecttag batch job execution will continue with procedure
SAP_MaterialMasterMapping2TC_Object
ERROR $message batch job execution will abort with status ERROR, ZPTC entry will be
updated with error message and status E (error)
SKIPPED T4S will do nothing and abort the batch job execution by going to cleanup
procedure directly.
4. SAP_MaterialMasterMapping2TC_Object
This procedure enables you to update Teamcenter attributes using the
storeReverseMappingAttribute function. The
No return parameter required.
5. updateTC_Object
This procedures allows you to perform any other update function on the Teamcenter Item
or ItemRevision, i.e. create an alternate ID object, trigger a workflow, set a status, create a
form, create a relation.
valid return parameters:
OK ERROR SKIPPED : This status will be passed to cleanup procedure as
BatchJobStatus.
6. Cleanup
This procedure allows you to perform any specific action on end of batch job execution, e.g.
send an email

Teamcenter Gateway for SAP Configuration Guide V10.1

131

If the mapping function returns the value SKIPPED, do not add a message as
second list element because T4S will then set the batch job status to
ApplicationError. Return the Status SKIPPED without a message and the job will
finish with status FINISHED

With version 10.0, Teamcenter supports Multi-field Keys (MFK). This means that a
set of key attributes can be defined for a unique identification of an object. Therefore,
it cant be assumed anymore that the Item ID is unique. MFK supports the following:

Business objects with different type and same Item ID

Business objects with different vendor and same Item ID

By default, the import mapping templates only use the Item ID for unique object
identification. If you need to enable MFK support, you have to do the following
adaptions in the mapping procedures (see above):

selectTC_Object: Append a list of additional attribute name and value pairs to


the call of ::T4X::CUSTOM::MAPPING::TOOLBOX::selectTC_Object. For
example, change the line from:
[::T4X::CUSTOM::MAPPING::TOOLBOX::selectTC_Object LATEST item_id
$MaterialNumber]

to:
[::T4X::CUSTOM::MAPPING::TOOLBOX::selectTC_Object LATEST item_id
$MaterialNumber object_desc [::T4S::TC::MAPPING::SAPFieldMapping
MaterialMaster $MaterialNumber MATERIALDESCRIPTION:MATL_DESC:1]]

createTC_Object: Append a list of additional attribute name and value pairs to


the call of ::T4X::CUSTOM::MAPPING::TOOLBOX::createTC_Object. For
example, change the line from:
set Status [::T4X::CUSTOM::MAPPING::TOOLBOX::createTC_Object
$NewItemId $NewItemName $NewItemRevisionId $NewItemType]

to:
set Status [::T4X::CUSTOM::MAPPING::TOOLBOX::createTC_Object
$NewItemId $NewItemName $NewItemRevisionId $NewItemType
object_desc [::T4S::TC::MAPPING::SAPFieldMapping MaterialMaster
$MaterialNumber MATERIALDESCRIPTION:MATL_DESC:1]]

132

TESIS PLMware

Configuring T4S to support customer specific requirements

2.18 Obtaining Teamcenter runtime properties from SAP


T4S supports the use of SAP data as Teamcenter runtime properties, i.e. data that is not saved in
the Teamcenter database, but only retrieved and shown as properties at Teamcenter runtime
(therefore its called runtime property). In principle, T4S can provide any data that it may read from
In the standard version, runtime properties can be defined for the Teamcenter object classes
ItemRevision and ItemRevision Master. For additional objects, the corresponding functions must
be extended in libt4x_rtp.dll. In Teamcenter, these data are shown when you right-click the
corresponding object and select Properties.

The use of T4S runtime properties impairs the performance of the transaction, as an
inquiry to SAP is made for each runtime property. We do not recommend defining
actions that request a large number of SAP runtime properties to be displayed in
Teamcenter in a single action. Use the SAP Data View within the T4S Rich Client
extension described in chapter 2.19 instead if a large number of attributes has to be
displayed.

2.18.1 Configuring runtime properties for the material master


The runtime properties are defined by certain entries in the Teamcenter preferences. First you
have to implement the library for the runtime properties functionality in the
TC_customization_libraries, see example below. Then the necessary data has to be
specified. After the corresponding key word you can define the required runtime properties line by
line. The names of the properties (the values of the key) may be given freely; they are used
internally for identifying the actual data and for displaying the labels in Teamcenter automatically.
The standard version supports the following definitions in the Teamcenter preferences:

There are two possibilities to define the runtime properties for specific Teamcenter object
types. The default configuration is using the T4S_MaterialMasterTypeList preference
to add new run time properties to the specified item revision types. It is also possible to
overwrite the definition with T4S_MaterialMaster_RTP_TypeList preference; this
allows the definition of runtime properties for Teamcenter Forms.

Define the list of Runtime Properties for your desired object class with the preference
T4S_MaterialMaster_RTP4<ObjectType> = <List of RTPs>
Example: configure the RTP SAP Matl Desc for an ItemRevision:
T4S_MaterialMaster_RTP4ItemRevision=
SAP Matl Desc
After you restart the Teamcenter Rich Client, you should find the additional property
SAP Matl Desc on any Item Revision

Define the Teamcenter data that T4S has to read in order to determine the correct SAP
object for getting the desired Runtime Properties. In most cases, you will need a SAP MM
ID. If it is stored in an attribute in the Item Revision Master Form, you have to state this

Teamcenter Gateway for SAP Configuration Guide V10.1

133

here. So the entry here is something that is stated in the key


T4S_MaterialMaster_RTP_Mapping4<type>
as well (as this has to use the same data for determining the SAP MM ID).
Example: read the attribute SAPMatNo from the Item Revision Master Form:
T4S_MaterialMaster_RTP_Mapping4ItemRevision=
IMAN_master_form_rev:ItemRevision Master:SAPMatNo

2.18.2 Using runtime properties for the Material Master


The actual mapping of the SAP data to the individual runtime properties is handled by the freely
configurable RTP mapping that is done in the separate file t4s_rtp_mapping_template.sd.
This consists of two functions for defining the mapping for the material master runtime properties:

getMaterialReadParameters defines the read parameters (i.e. material number and plant)
for the getMaterialMasterRuntimeProperty function

getMaterialMasterRuntimeProperty defines the mapping for the runtime property data for
the specified SAP MM (which is determined in getMaterialReadParameters)

The function for reading the runtime properties (getMaterialMasterRuntimeProperty) uses


the same functions for reading the material master data as the material master reverse mapping
function. This means that all the values from the material info table can also be displayed as
runtime properties in the Teamcenter Portal and do not have to be stored separately in
Teamcenter.
Example 1 for the mapping of the above configured RTPs:

First determine the Teamcenter data for identifying the corresponding SAP object in the
function getMaterialReadParameters:
switch exact -- $AttributeName {
{IMAN_master_form_rev:ItemRevision Master:SAPMatNo}
{set MaterialNumber $AttributeValue}
}

The left part of the long line (IMAN_master) needs to be exactly the same as the
value of the preference T4S_MaterialMaster_RTP_Mapping4ItemRevision. In fact
this means that T4S will run through this function with this value and try to evaluate the
MaterialNumber depending on the logic stated here. For error tracking purposes, check
the functions end message in the logs whether it determined the SAP MM ID correctly.

Then define the actual runtime properties in the function


getMaterialMasterRuntimeProperty:
switch -exact -- [string toupper $ValueTag] {
{SAP MATL DESC}

134

{set ::StatusInfo(RuntimePropertyValue)
TESIS PLMware

Configuring T4S to support customer specific requirements

[::T4S::TC::MAPPING::SAPFieldMapping MaterialMaster
$MaterialNumber MATERIALDESCRIPTION:MATL_DESC:1]}
default

{set ::StatusInfo(RuntimePropertyValue)
"Unknown Property Mapping"}

These are only two lines in the switch command, the first starts with {SAP MATL DESC}
and the second with default.

Then you should see the value filled by SAP in the additional property SAP MATL DESC in a
standard Item Revisions properties form:

Teamcenter Gateway for SAP Configuration Guide V10.1

135

If there is no active connection to SAP at the time, T4S will not try to read the RTP
In any case, you should find the property name, possibly empty
If the new property is not shown at all, check
if the the preference TC_customization_libraries has the entry libt4x_rtp
as well as the libt4x_rtp library (a file with the file extension corresponding to the
operating system, i.e. the whole file name is e.g. libt4x_rtp.dll or
libt4x_rtp.so) is present in T4S/bin (bin32 or bin64, respectively)
These entries are dependent on the Item Type, i.e. you need these two entries for each
Item Type separately
Depending on the SAP connection and network load it may take some seconds to show a
value correctly in Teamcenter after a modification in SAP. In between Teamcenter may
show the old data
If the corresponding MM is not found (maybe the attribute SAPMatNo is empty, the stated
MM does not exist or the mapping is not correct), the info Unknown MM is shown
instead
SAP will refuse providing new data if the last call was less than about 2 minutes before,
i.e. you will never get new data if you keep on asking too frequently

Another possibility to see the RTPs is inserting a new column in the Details view in My
Teamcenter:

Right-click on a column head and select Insert column

Choose your desired data object (e.g. Item Revision) and the desired property

You will get an additional column for the given Runtime Property:

136

In order to see the properties of an ItemRevision here, you have to select the Item and
define the property for the Item, not the ItemRevision

TESIS PLMware

Configuring T4S to support customer specific requirements

Each click on such an object requires an additional data transfer from SAP and
therefore you will notice a delay

Example 2 for the mapping of plant specific RTPs:


In order to get plant specific MM data as runtime properties, you have to specify the Plant ID in the
function getMaterialReadParameters additionally,
e.g.
set Plant $::T4S_Defaults(PlantId)
(instead of set Plant
which is included in our RTP template mapping file).
If you want to read valuation data of this MM (e.g. price information), you have to specify the
ValuationArea additionally. In most cases it is the same value as Plant. Then modify this
section from the T4S RTP template mapping file
set MaterialNumber ""
set Plant

""

set CompanyCode

""

set ValuationArea

""

set ValuationType

""

Iike this:
set MaterialNumber ""
set Plant

$::T4S_Defaults(PlantId)

set CompanyCode

""

set ValuationArea

$::T4S_Defaults(PlantId)

set ValuationType

""

The other two values (CompanyCode and ValuationType) are usually not needed.
The settings in the function getMaterialMasterRuntimeProperty to read the SAP MM values
Standard price and Price unit could be as follows:
{SAP STANDARD PRICE}
{set ::StatusInfo(RuntimePropertyValue)
[::T4S::TC::MAPPING::SAPFieldMapping MaterialMaster
$MaterialNumber VALUATIONDATA:STD_PRICE]}
{SAP PRICE UNIT}
{set ::StatusInfo(RuntimePropertyValue)
[::T4S::TC::MAPPING::SAPFieldMapping MaterialMaster
$MaterialNumber VALUATIONDATA:PRICE_UNIT]}

Teamcenter Gateway for SAP Configuration Guide V10.1

137

2.19 SAP Data View within the T4S Rich Client extension
T4S has the capability to show real-time SAP attribute values for the selected Item revision within
the Teamcenter Rich Client application using the Eclipse view technology. The T4S SAP data
view can be attached to any Teamcenter perspective, such as the Structure Manager perspective.
The SAP data view is also accessibly within the T4S transfer window (then it is independent from
Eclipse). This view can display a configurable set of SAP attributes independently from the
Teamcenter data model. This means that the data is not stored in Teamcenter and therefore the
displayed attributes cannot be used in search queries or any other functionality working with
Teamcenter attributes.

The SAP data view is fully integrated into the Teamcenter GUI

If you do not want to show tab SAP Data in the T4S transfer window, disable it by
setting the preference T4S.UI.Transaction.Tabs accordingly. The default values in
the preference are:
T4S.UI.Transaction.Tabs=
Attributes
CustomData
Status
Info

Attributes - Shows the Teamcenter data based on a given style sheet

CustomData - Shows the SAP Data view

Status - Shows the detailed status messages

Info - Shows the copyright information

As the Eclipse object "SAP Data" in Teamcenter is created by Teamcenter itself (T4S
just fills it with data if it exists), T4S cannot deactivate it. In order to not show the
Teamcenter Eclipse object, just close it and be sure Teamcenter is not configured to
reopen it automatically
If it is not shown and you want to see it, select from the main Teamcenter menu:
Window Show View Other Teamcenter Gateway SAP Data
This chapter only describes the handling of the SAP Data View for the Material
Master in detail; it is very similar for the other SAP object types (BOM, DIR)
Although the functionality looks similar, there is no technical correlation between
"Runtime Properties" and the "SAP data view"; they can be used independently from
each other

The actual mapping of the SAP data shown in the SAP data view is handled by a freely
configurable mapping that is done in the separate file t4s_prop_mapping_template.sd. It
consists of one function per object type called GetSAPData_<object_type>, e.g. the function
GetSAPData_MaterialMaster for handling data from a SAP Material Master.

138

TESIS PLMware

Configuring T4S to support customer specific requirements

All SAP Data View definitions have to be done between the calls of functions createMainEntry
and createMainEndEntry, e.g.:
#
# XML Header with Status OK
#
set rc [::T4X::PROP::MAPPING::createMainEntry $ObjectType "OK" ""]
.
.
.
<Data View Definitions>
.
.
.
append rc [::T4X::PROP::MAPPING::createMainEndEntry]

For the view, individual sections corresponding to the SAP Material Master views can be defined,
e.g. general data, forecast data, sales data etc. From the technical point of view, it does not
matter if the data shown in one section belong to the same logical unit of SAP data, but for better
understanding from the users point of view, we recommend grouping similar data together.
The following example shows how to create a section called General Data from SAP MM
CLIENTDATA with the two entries MATERIAL and BASE_UOM that are shown to the user as
Material and Base Unit of Measure:
# Create an expandable section for General Data
# The function createSectionEntry to create the section needs the
# SAP name of the data to show, the name to show in the GUI and the
# flag Expanded (true/false; should it be open or not at startup):
append rc [::T4X::PROP::MAPPING::createSectionEntry "CLIENTDATA"
"General Data" "true"]
# The function createFieldEntry to create the single entries needs the
# SAP Name, the name to show in the GUI and the flag Multiline Value
# (true/false):
append rc [::T4X::PROP::MAPPING::createFieldEntry "MATERIAL" "Material"
[::T4S::TC::MAPPING::SAPFieldMapping MaterialMaster $ItemId
CLIENTDATA:MATERIAL] "false"]
append rc [::T4X::PROP::MAPPING::createFieldEntry
"BASE_UOM"
"Base Unit of Measure" [::T4S::TC::MAPPING::SAPFieldMapping
MaterialMaster $ItemId CLIENTDATA:BASE_UOM] "false"]
append rc [::T4X::PROP::MAPPING::createSectionEndEntry]

Teamcenter Gateway for SAP Configuration Guide V10.1

139

As the data to show has to be read from SAP, T4S uses the same mechanism to get it as
in any of the T4S reverse mapping functions, so call the same function
SAPFieldMapping with the same parameters here

In order to find the correct call to get the desired SAP data, check the description of the
T4S reverse mapping and the generic description in chapter Reverse Mapping: store
data from SAP to Teamcenter on p. 41 of this document. Find descriptions specific to the
different data types (MM, DIR) in the chapters following that one and lists of examples
in chapter SAP fields T4S can read from in the "Teamcenter Gateway for SAP Business
Suite Preparing SAP for Teamcenter Integration Guide"

In order to identify the SAP objects correctly according to your Teamcenter settings, be
sure to adapt the corresponding lines in the mapping file
t4s_prop_mapping_template.sd (e.g. set MaterialNumber ) in the same
way as in the corresponding lines in the mapping files for these object types

The following screen shot shows the Eclipse perspective SAP Data active in the Teamcenter GUI
with a BOM view Revision selected:

140

TESIS PLMware

Configuring T4S to support customer specific requirements

To view the SAP specific information within Teamcenter, select an appropriate object (e.g. an Item
Revision or a Dataset) and the SAP object type you want to check. Then T4S will process the data
for the selected object and the selected SAP object type according to defined mapping.
The SAP Data View header (the grey part) shows the following information:

The current SAP connection, e.g. SAP1@800.


If more than one SAP connection is defined in your T4S installation, you can select another
from the list that will open when clicking the icon

The current SAP object type, e.g. Material Master. When clicking the icon

, a list opens

showing all the SAP object types configured for the selected Teamcenter object, e.g.:

Last Refreshed is the date and time when the shown data have been processed

The icon next to the time stamp shows the current processing status or/and result:
o

processing right now

the processing finished OK

the processing finished with an error and T4S could not get the requested data
from SAP. In most cases this is not really an error, but is just because the requested
SAP object does not exist

Click the refresh button

to determine the data again from SAP immediately

The window content shows the desired SAP data as defined in the T4S mapping, e.g. the SAP
object ID, the short description in every defined language and some more data. In principle the
SAP Data View can show every data you see in the SAP GUI in the display of the same object.
The following SAP object types are supported for the T4S SAP Data View:

MM

BOM

ECM

DIR

Functional Location

Equipment

Vendor

Query

Teamcenter Gateway for SAP Configuration Guide V10.1

141

As shown in the screen shots, you may show data as text lines, checkboxes or tables
(most interesting for BOM), and hyperlinks additionally (to files or URLs)

If the data are not shown as a table (the upper part that starts with Head data in the
screen shot above) and nothing special is specified in the properties mapping, you will
always find two columns alongside; each data field shows the name as defined in the
mapping (see example above) and its value below it

If more than one SAP connection is defined in your T4S installation, you can select
another from the list that will open when clicking the icon

You may select the SAP connection (as defined in the T4S installation) to get the data
from (e.g. SAP1@123 would mean the data are checked from the SAP system SAP1
with the client 123) and the SAP object type (MM, BOM, DIR) to check. So if you select
Bill of Material here, the SAP data view will show you data from the same SAP BOM as
you can see in the SAP GUI when selecting the BOM Display function from within the
T4S Gateway menu (with the same TC object selected)

When selecting the SAP Data view, T4S will check for which SAP object types (MM,
BOM, DIR) the selected Teamcenter object is configured, i.e. it checks the
T4S_*TypeList* preferences for the selected Teamcenter object type. The first one it
finds is used as the type to show in the SAP Data view. As the T4S transfer window is
opened for a specific SAP object type, it does not allow switching

T4S will remember the SAP object type a Teamcenter object has been used with the
SAP data view. So when selecting a Teamcenter object that has been used with the SAP
data view before in the same Teamcenter session, T4S will maybe not use the first type
as described in the previous point but the one that has been open before

Same with the SAP system: when selecting a Teamcenter object that has been selected
before, the SAP data view will show the data from the same SAP connection as the
previous check on the same Teamcenter object, no matter if another SAP connection has
been used in between

So if you select another Teamcenter object after you checked the SAP datea view for the
previously selected one, you may find data from another SAP connection although you
did not select another SAP connection explicitly

T4S supports some more special possibilities how to show the SAP data in that view besides the
above described. Here is an example screen shot of the SAP data view showing them (find below
explanations how to define them in the properties mapping file t4s_prop_mapping.sd):

142

TESIS PLMware

Configuring T4S to support customer specific requirements

This shows the following SAP data view features:

The fields Material, Base Unit of Measure are standard text fields created with the
command createFieldEntry as described above

The table Material Shorttext is created as follows:


# First create the table itself:
append rc [::T4X::PROP::MAPPING::createTableEntry DESC
"Material Shorttext" [list "LANGU_ISO" "MATL_DESC"]
[list "Language" "Short Description"]]
# Fill the table with data using a loop to find all the
#
corresponding SAP data:
foreach Line [::T4X::CORE::sortIndexedInterfaceTable
[array names ::MMResultDat MATERIALDESCRIPTION:LANGU_ISO:*]] {

Teamcenter Gateway for SAP Configuration Guide V10.1

143

set LineList

[split $Line :]

set LineIndex

[lindex $LineList end]

set Language
[string trim
$::MMResultDat(MATERIALDESCRIPTION:LANGU_ISO:$LineIndex)]
set Desc
[string trim
$::MMResultDat(MATERIALDESCRIPTION:MATL_DESC:$LineIndex)]
# Add one line for each found language to the table
#

(the parameters are the column name and the value):

append rc [::T4X::PROP::MAPPING::createTableRecordEntry
[list $Language $Desc]]
}
# Then finish the table:
append rc [::T4X::PROP::MAPPING::createTableEndEntry]

The fields below Material Shorttext are created as follows. Please note the difference
between the right part where the two value fields are aligned (i.e. the left border of the lower
value field is exactly below the upper one) and the left part without alignment. Whenever
there is a separator (the horizontal line) the fields below it will not be aligned with the
fields above it. And the whole section is defined to be shown in two columns:
# First create the column (similarly to the table described
#
above, columns need to be closed, see below; note that you
#
do not have to define the number of columns explicitly
#
but just create more than one in the same section):
::T4X::PROP::MAPPING::begin

-doc rc column -resizable true

# Then create the fields you want to show:


::T4X::PROP::MAPPING::create -doc rc property name
"Material type" -value $MatlType
::T4X::PROP::MAPPING::create -doc rc separator
# A separator may be hidden so it will behave the same but
#
you cannot see it:
... separator -hide true
::T4X::PROP::MAPPING::create -doc rc property name
"Item category" -value $ItemCat
::T4X::PROP::MAPPING::create -doc rc text -value "Test text box
with given height 30 and width 250" -height 30 -width 250
# Finish the first column and create the second one:
::T4X::PROP::MAPPING::end

-doc rc column

::T4X::PROP::MAPPING::begin

-doc rc column -resizable true

::T4X::PROP::MAPPING::create -doc rc property name


"Size/dimensions" -value $SizeDim
# Create a field with a tool tip (a little popup when putting
#
the mouse over an object without clicking):
::T4X::PROP::MAPPING::create -doc rc property -name "Net weight"
-value "$NetWeight $WeightUnit"
144

TESIS PLMware

Configuring T4S to support customer specific requirements

-tooltip "ISO weight unit: $WeightUnit_ISO"


::T4X::PROP::MAPPING::create -doc rc property value
"Material status: $MatlStatus"
::T4X::PROP::MAPPING::end

-doc rc column

# Then finish the section:


append rc [::T4X::PROP::MAPPING::createSectionEndEntry]

The section Additional data is created as follows:


# First create the table itself:
append rc [::T4X::PROP::MAPPING::createSectionEntry "Additional
data" "Additional data" false]
# The last parameter "false" causes the new section to be shown
#
collapsed on creation, but it may be opened by clicking it
# After all the data are defined for the section, finish it:
append rc [::T4X::PROP::MAPPING::createSectionEndEntry]

The tabs inside the section Material Shorttext are created as follows:
# First create the table itself (the parameters are the same):
append rc [::T4X::PROP::MAPPING::createTableRecordEntry
[list $Language $Desc]]
}
# Then finish the table:
append rc [::T4X::PROP::MAPPING::createTableEndEntry]

In order to show different things but not all of them together (for not confusing the user and
saving space) you may use tabs, e.g. as the Plant data shown here. Click on one or
another tab to show its content:

This is created as follows:


# In this example the plant IDs 1000, 2200 and 3000 are set fix:
foreach Plant {1000 2200 3000} {
# Note that T4S needs to query the MM data from SAP for every
#
plant separately (the second value $Plant is for the
#
Valuation Area):
set Status [::TPSAP::MM::getAllMaterialMasterInfos
$MaterialNumber $Plant "" $Plant ""]

Teamcenter Gateway for SAP Configuration Guide V10.1

145

# Open a new tab using the key word "page":


::T4X::PROP::MAPPING::begin -doc rc page title
"SAP plant $Plant"
set ValClass
[::T4S::TC::MAPPING::SAPFieldMapping
MaterialMaster $MaterialNumber VALUATIONDATA:VAL_CLASS]
::T4X::PROP::MAPPING::create -doc rc property name
"Valuation class" -value $ValClass
set Currency
[::T4S::TC::MAPPING::SAPFieldMapping
MaterialMaster $MaterialNumber VALUATIONDATA:CURRENCY]
set StdPrice
[::T4S::TC::MAPPING::SAPFieldMapping
MaterialMaster $MaterialNumber VALUATIONDATA:STD_PRICE]
::T4X::PROP::MAPPING::create -doc rc property name
"Standard price" -value "$StdPrice $Currency"
# Finish the current page (tab):
::T4X::PROP::MAPPING::end -doc rc page
}

With T4S V10.0 the following new SAP Data View procedures were introduced (in
namespace ::T4X::PROP::MAPPING), which allow much more flexibility for displaying the
data:
begin and end: The begin command is mostly used to build up complex structures
with container widgets. It comes in companionship with the end command. The
commands between a begin and its corresponding end command create the piece
of text used to render the contents of the container widget. The following types of
container widgets are supported: section, page and column
create: Create a piece of text which the T4S SAP data view will render into a
widget, e.g. a property

The following old procedures can be replaced by these new procedures (but the old ones
are still valid):
createSectionEntry and createSectionEndEntry can be replaced by begin
and end, e.g.:
append rc [::T4X::PROP::MAPPING::createSectionEntry "Additional data"
"Additional data" false]
append rc [::T4X::PROP::MAPPING::createSectionEndEntry]

::T4X::PROP::MAPPING::begin -doc rc section -title "Additional data"


::T4X::PROP::MAPPING::end -doc rc section

createFieldEntry can be replaced by create, e.g.:


append rc [::T4X::PROP::MAPPING::createFieldEntry

146

TESIS PLMware

Configuring T4S to support customer specific requirements

"INVENTORY_ITEM_NUMBER" "Inventory Item Number" $ItemNumber "false"]


append rc [::T4X::PROP::MAPPING::createFieldEntry
"MATERIAL" "Material number" $MaterialNumber false]

::T4X::PROP::MAPPING::create -doc rc property name


"Material number" -value $MaterialNumber -namePosition ABOVE

For more information about these procedures, please see the Teamcenter Gateway for
SAP Business Suite API Reference

In this chapter only a subset of all supported SAP Data View features was demonstrated.
For more information about all T4S 10.1 supported SAP Data View features, please see
the Data View Demo which can be included into the SAP Data View for Material Master
by simply doing the following:
In mapping function GetSAPData_MaterialMaster uncomment the line:
append rc [::T4X::PROP::MAPPING::DEMO::createDemoPage $Parameters]
Then the Data View Demo will be displayed on a new tab:

The mapping examples for this demo can be found in file t4x_data_view_demo.sd
(make sure that this file is sourced in t4s_mapping_config.sd).
Example: this is how to create the hyperlinks (note that each call consists of three lines):
::T4X::PROP::MAPPING::begin

-doc rc hyperlink -name "A hyperlink"

Teamcenter Gateway for SAP Configuration Guide V10.1

147

-value "TESIS PLMware GmbH"


::T4X::PROP::MAPPING::create -doc rc openUrl -url
"http://www.tesis.de/plmware"
::T4X::PROP::MAPPING::end

-doc rc hyperlink

::T4X::PROP::MAPPING::begin -doc rc hyperlink -name "A hyperlink


that launches an internal browser" -value "TESIS PLMware GmbH
(internal browser)"
::T4X::PROP::MAPPING::create -doc rc openUrl -url
"http://www.tesis.de/plmware" -useExternalBrowser false
::T4X::PROP::MAPPING::end

-doc rc hyperlink

# Note that the default is external browser, so not setting the


switch -useExternalBrowser false is the same as setting it to
true
::T4X::PROP::MAPPING::begin -doc rc hyperlink -name "A button
hyperlink" -value "TESIS PLMware GmbH" -style BUTTON
::T4X::PROP::MAPPING::create -doc rc openUrl -url
"http://www.tesis.de/plmware"
::T4X::PROP::MAPPING::end

-doc rc hyperlink

Example: this is how to create a file link (clicking it will ask the operating system to open the
stated file with the default tool, e.g. Notepad for a text file in Windows):
::T4X::PROP::MAPPING::begin -doc rc hyperlink -name "A file link"
-value "Test description document"
::T4X::PROP::MAPPING::create -doc rc openUrl -url
"file:///C:/PLM/T4S_Docs/Test_1.txt"
::T4X::PROP::MAPPING::end

-doc rc hyperlink

Note that you may add a tool tip (a little popup window that is shown when the mouse it put
over a field but no mouse button pressed) by adding the following parameter:
-tooltip "TESIS PLMware Homepage"

148

TESIS PLMware

Configuring T4S to support customer specific requirements

2.20 Create a Teamcenter List of Values (LOV) with T4S


T4S provides a functionality to modify a Teamcenter list of values. The data may be created in the
mapping file or retrieved directly from a SAP list of value. Currently, only SAP list of values from
table MARA (Material data without relation to a plant) are supported.

Teamcenter sometimes caches LOV data. Changes to the definition of the T4S LOV
values require a restart of the Teamcenter client restarting the tpapps process is not
sufficient.

The LOV type creation in the Teamcenter database is done automatically when deploying the T4S
feature file with tem.

2.20.1 Configure a Teamcenter LOV for T4S use


In order to maintain a LOV, do the following in BMIDE:

Create a LOV with type T4S_ListOfValuesString with either exhaustive or suggestive


usage

Do not enter any values

In the next step, attach the LOV to the desired attribute

Deploy the change to your database

Start your Teamcenter client and check that an empty LOV is attached to the desired
attribute

Teamcenter Gateway for SAP Configuration Guide V10.1

149

2.20.2 Definition of data mapping for a Teamcenter LOV


You can define default values for the T4S LOV or you can read a SAP LOV and map it to the
Teamcenter LOV. Define the logic for the specified LOVs in the separate mapping file
t4s_lov_mapping_template.sd. The file can differentiate between different T4S LOVs by
their names in a switch-statement, so you can have multiple instances of T4S LOVs.
Example 1: write default values:
::T4S::LOV::storeValue2ListOfValues "Test1234" Descr1
::T4S::LOV::storeValue2ListOfValues "Test2345" Descr2
::T4S::LOV::storeValue2ListOfValues "Test3456" Descr3
::T4S::LOV::storeValue2ListOfValues "Test4567" Descr4
In this example, Test is always the actual value for the LOV and Descr is the
corresponding description for this value (optional).
Example 2: write default values using a TCL list variable:
set LovList [list "Value1" "Value2" "Value3" "Value4"]
foreach Value $LovList {
::T4S::LOV::storeValue2ListOfValues $Value
}

Example 3: map SAP LOV Material group:


set Status [::TPSAP::readF4BapiHelp "BUS1001" "Material"
"GetDetail" "MaterialGeneralData" "MATL_GROUP"]
if {$Status == "OK"} {
foreach Element [lsort -command
::TPSAP::compareIndexedInterfaceTable
[array names ::F4ResultDat HELPVALUES:HELPVALUES:*]] {
set Index [lindex [split $Element :] end]
if {[info exists
::F4ResultDat(HELPVALUES:HELPVALUES:$Index)]} {
::T4S::LOV::storeValue2ListOfValues [string range
$::F4ResultDat(HELPVALUES:HELPVALUES:$Index) 0 9] [string range
$::F4ResultDat(HELPVALUES:HELPVALUES:$Index) 10 end]
} else {
::T4S::LOV::storeValue2ListOfValues
$::F4ResultDat($Element)
}
150

TESIS PLMware

Configuring T4S to support customer specific requirements

tpwrite "F4ResultDat($Element): $::F4ResultDat($Element)"


}
}
array unset ::F4ResultDat

Depending on how the SAP connection is set up in your T4S implementation, you might
be surprised to not find SAP LOV data if no SAP connection is set up yet. Therefore
defining the SAP auto login for LOV is a good idea in many cases; see chapter How to
provide Teamcenter and SAP account information on p. 177 for details

Teamcenter Gateway for SAP Configuration Guide V10.1

151

2.21 Workflow Handler Functions


As well as the functions in the portal, T4S also provides functions for supporting workflows. The
T4S rule and action handlers can be combined with all other handlers without any major
modification.

152

Each handler knows what kind of object types it belongs to, i.e. there is no environment
to be set. For example, the T4S-validate-ChangeNumber (which checks a SAP ECM)
always calls the ECM mapping, although it may have been started from a material
workflow or from a document workflow

Some handlers may be placed in the Start action of the Root Task. As Teamcenter will
discard the entire workflow job if an error occurs in this action (which also means that
T4S cannot store its log file Dataset), error tracking might be harder in this case so this is
not recommended

Some Workflow handler arguments may be used with different handlers, so they are not
repeated in the description of every handler separately. Especially the transfer handlers
(e.g. T4S-transfer-MaterialMaster) support arguments to modify their behavior in a
specific way, see following points

T4S can use different SAP connections in different workflows. Therefore the handler
T4S-validate-SAPLogon as well as every handler that exchanges data between
Teamcenter and specific SAP objects (i.e. every T4S "transfer handler) may use the
handler arguments -use_SAP_system and -use_SAP_client to specify the SAP
system (as defined in saprfc.ini) and client number to be used

The same handlers (i.e. every T4S "transfer handler) may use the following handler
arguments additionally (do not use both at the same time!):
-collect_all_errors=TRUE
This will allow T4S processing all attached workflow targets and not stop until all
targets are processed. Then the whole set of errors can be handled together
-continue_on_error=TRUE
This will tell the hander to not stop in case a T4S error occurred, i.e. an error from
the Teamcenter error number range 212000 to 212999 which is reserved for T4x

Every T4S "transfer handler supports the argument -use_condition_on_target,


see chapter "Use of BMIDE Conditions (CLIPS) for configuration of rules" in this
document for details

Every T4S "transfer handler supports the argument -AddObject4Mapping to allow


T4S reading Teamcenter data during the transaction that have not been configured (i.e.
set in the corresponding Mapping4 preference). The syntax is the same as in the
corresponding, e.g. -AddObject4Mapping=IMAN_specification:MSWord

TESIS PLMware

Configuring T4S to support customer specific requirements

If T4S should handle different SAP connections (different for workflow or portal
transactions, different workflow templates), be sure to define those correctly according
to your needs

The following chapters describe each handler currently available with T4S.

2.21.1 T4S rule handlers


Handler name

T4X-attach-LogfileDataset

Description

Creates a log file for the workflow

Arguments

None

Use/placement

The rule handler should be used if possible in the "Start" action of the
Root Task so that all subsequent handlers can use the log file

Restrictions

None

Additional information

During a Workflow Job run, the log file is created in the Attachments
of this Workflow Job; check in Workflow Viewer
The handler may be placed in any task (preferably in action
"Complete"), but be sure not to put more than one in one Workflow
template.
Note: if this handler is used, the log information that is written into this
file will not be written to the T4S session log file any more

Handler name

T4S-validate-SAPLogon

Description

Examination of the SAP login

Arguments

-use_SAP_system (optional): if set, T4S will use the SAP system


stated as the value of this argument

Use/placement

The handler should be used if possible in the Complete action of the


SAP logon task

Restrictions

None

Handler name

T4S-validate-ChangeNumber

Teamcenter Gateway for SAP Configuration Guide V10.1

153

Description

This rule handler checks if a change number was given and may
additionally check if an ECM with this ID exists in SAP

Arguments

-check=CHANGENUMBER (mandatory): check if a Change Number


was given (i.e. ::SAPDat(ChangeMaster:HeadData:CHANGE_NO)
is not empty)
-check_EPM_Targets=True (optional): read data from each Workflow
job target data additionally *
-mode=CHECKSAP (optional): check if an ECM with this ID exists in
SAP

Use/placement

The rule handler may be placed in the Start action of the Root Task.
Then it will not be executed for every target, but only once in the
Wokflow job. It also has the advantage that T4S may change the
Workflow Job Name; later Teamcenter will not allow that
* If the argument -check_EPM_Targets=True is set, it does not
check the Job Name as Change Number, but you can set it freely in
the mapping and differently for every target of this Workflow job (see
document "Teamcenter Gateway for SAP Business Suite Frequently
Asked Questions"). If this is not set, the handler will only read the
Workflow Job Name and use this as change number, no matter of the
number of targets. But nevertheless, the mapping needs to point to
this information:
set ::SAPDat(ChangeMaster:HeadData:CHANGE_NO)
[tpco_formatHEX16 $::TcData(Workflow:JobName)]

Restrictions

None

Handler name

T4S-validate-MaterialMaster

Description

Checks whether all the necessary information for a material master


transaction is defined

Arguments

If no arguments are transferred, the action is used as a parameter for


the function of the rule handler. Only the actions Perform (equivalent
to the argument -Check= MANDATORYFIELDS) and "Complete
(equivalent to the argument -Check=MATERIALNUMBER) return valid
values. All other actions return "EPM_undecided.
-Check=<MANDATORYFIELDS | MATERIALNUMBER>
MANDATORYFIELDS: Checks whether all mandatory fields
are defined for the material master transaction after mapping.
No SAP enquiry is made for the check.
MATERIALNUMBER: Checks whether the reverse mapping of

154

TESIS PLMware

Configuring T4S to support customer specific requirements

the material number was successful.


Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

None

Handler name

T4S-validate-BillOfMaterial

Description

Checks whether all the necessary information for a bill of materials


transaction is defined.

Arguments

If no arguments are transferred, the action is used as a parameter for


the function of the rule handler. Only the actions "Perform and
"Complete (equivalent to the argument -Check=
MANDATORYFIELDS) return valid values. All other actions return
"EPM_undecided.
-Check=MANDATORYFIELDS
Checks whether all mandatory fields are defined for the BOM
transaction after mapping. No SAP enquiry is made for the
check.

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

None

Handler name

T4S-validate-WBS-BillOfMaterial

Description

Checks whether all the necessary information for a Work Breakdown


Structure Bill of Materials transaction is defined.

Arguments

-user_rule=<Name of the Rule>


Optional argument, if it is not specified the value is set to "Default"
Beside this argument it is possible to specify the same arguments
used by the T4S-transfer-WBS-BillOfMaterial action handler.

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

None

Handler name

T4S-validate-DocumentInfoRecord

Description

Checks whether all the necessary information is defined for the


creation of a document info record or if the reverse mapping of the

Teamcenter Gateway for SAP Configuration Guide V10.1

155

SAP document key was successful, respectively


Arguments

If no arguments are transferred, the action is used as a parameter for


the function of the rule handler
- Check=<MANDATORYFIELDS | DOCUMENTKEY>
MANDATORYFIELDS: Checks whether all mandatory fields
are defined for the document info record transaction after
mapping. No enquiry is made of the SAP system for the check.
DOCUMENTKEY: Checks whether the reverse mapping of the
SAP document key was successful.

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

None

Handler name

T4S-validate-EquipmentMaster

Description

Checks whether all the necessary information is defined for the


creation of an equipment master

Arguments

If no arguments are transferred, the action is used as a parameter for


the function of the rule handler.
-Check=<MANDATORYFIELDS | EQUIPMENTNUMBER >
MANDATORYFIELDS: Checks whether all mandatory fields
are defined for the equipment master transaction after
mapping. No enquiry is made of the SAP system for the check.
EQUIPMENTNUMBER: Checks whether the reverse mapping
of the equipment number was successful.

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

None

Handler name

T4S-validate-FunctionalLocation

Description

Checks whether all the necessary information is defined for the


creation of a functional location

Arguments

If no arguments are transferred, the action is used as a parameter for


the function of the rule handler.
-Check=<MANDATORYFIELDS | FUNCLOCNUMBER >
MANDATORYFIELDS: Checks whether all mandatory fields

156

TESIS PLMware

Configuring T4S to support customer specific requirements

are defined for the functional location transaction after


mapping. No enquiry is made of the SAP system for the check.
FUNCLOCNUMBER: Checks whether the reverse mapping of
the functional location number was successful.
Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

None

Handler name

T4S-check-T4SFolderExists

Description

Checks if the T4S folder (in order to manage workflow targets) exists

Arguments

None

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

None

2.21.2 T4S action handlers


Handler name

T4S-transfer-MaterialMaster

Description

For an element of object class type ItemRevision a material master is


created or altered in SAP

Arguments

None

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler.

Handler name

T4S-transfer-BillOfMaterial

Description

This handler transfers for each configured BOM view type a defined
bill of materials to SAP

Arguments

-bom_rev_rule=<BOM revision rule name>


optional; if set, the stated revision rule overrides the BOM revision rule
setting T4S_BillOfMaterialMapping4 in the Teamcenter preferences.
If you use a BOM rule handler as well, it needs the same argument.
See also below with the additional T4x handler
T4X-attach-RevisionRule for BOM revision rule handling

Teamcenter Gateway for SAP Configuration Guide V10.1

157

-bomview_prio_list=<list of BOM view types>


optional, value is a comma-separated list of BOM view types; if set,
T4S reads this list and checks if one of the stated BOM view types is
present in the target according to the preference
T4S_BillOfMaterialTypeList. Then it uses the Teamcenter
BOM object according to the first matching type only and ignores all
the others given to this handler. If none of the stated types is present,
no BOM is transferred although the target list may contain several
BOM views. The value for this argument is a comma separated list
without additional blanks. T4S just removes the commas and uses the
strings as they are as type names, e.g.
-bomview_prio_list=view,MBOM,BOM3
-no_transfer_of_empty_bom
optional (not setting it is the same as setting it to FALSE); if set to
TRUE, an empty Teamcenter BOM (it does not contain any position)
will be ignored; else T4S will try and create an empty SAP BOM, i.e.
the BOM header with all its data but no BOM position.
Caution: this is only used for BOMs that are stored empty in
Teamcenter; if a BOM gets empty during the T4S mapping because
all its positions are skipped, this setting will not skip the BOM transfer;
that has to be handled in the BOM mapping separately
-unpack_all_bomlines
optional; if set to TRUE, T4S will provide all BOM positions unpacked
and allow the packing in the mapping according to any logic defined
there
-scan_max_bomlevel
optional. DEFAULT value is 1. It defines the maximum number of
structure levels that are read by T4S. Only relevant if multi-level BOM
transfer is configured (see chapter How to read more than one level
of Teamcenter BOM in the "Teamcenter Gateway for SAP Business
Suite FAQ")
Similar to Teamcenters Structure Manager functionality (preferences
PSEshow), T4S may be configured to ignore BOM lines whose Item
Revision cannot be evaluated uniquely using the Revision Rule
configured for this Workflow. Therefore T4S offers the following
handler arguments (optional; if set to TRUE, T4S will ignore the
appropriate BOM lines):
-hide_unconfigured_bomlines
-hide_suppressed_bomlines
-hide_variants_bomlines
-hide_incremental_changes_bomlines
Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best

158

TESIS PLMware

Configuring T4S to support customer specific requirements

checked with the "T4S-validate-SAPLogon rule handler

Handler name

T4X-attach-RevisionRule

Description

This handler creates a dynamic revision rule and attaches it to the


current workflow job for telling another T4x handler later in the same
workflow job how to find the desired data from Teamcenter. This
allows T4S handling the Teamcenter BOM occurrence effectivity in a
more flexible way than the standard fix defined revision rules

Arguments

-mode=add | delete
add (default) will attach the specified revision rule to current workflow
target
delete will remove the attached revision rule from the workflow target
and delete it from the data base
-use_rev_rule=(revision rule template name)
required for the mode add
-input=(effectivity info)
defines the effectivity information that should be added to the new
revision rule template (required for the mode = add). Possible values:
last_release_status:date / unit / end_item
EPM_release_status_attachment:date / unit / end_item
-rev_rule_relation=(Teamcenter relation type name)
defines the relation name or reference attribute that is used to attach
the revision rule to the workflow job (required)
The last_release_status is a real Teamcenter release status and this
value determines if T4x should use the date, the unit or the end_item
of that Teamcenter status object. In contrast to that, the
EPM_release_status_attachment is a temporary status object
attached by T4x; the effectivity determination by the status date, unit
or the end_item of that status object works the same.
If no argument is specified the handler returns with an error message.

Use/placement

The handler can be used in any task, preferably in action "Complete".


Example how to use this handler for a T4S BOM workflow in order to
use the dynamic revision rule MyRevRule: set three handlers in the
"Complete" action of a T4S BOM workflow task with the handler
arguments as stated here:

T4X-attach-RevisionRule
-mode=add
-use_rev_rule=MyRevRule

Teamcenter Gateway for SAP Configuration Guide V10.1

159

-rev_rule_relation=IMAN_reference
-input=last_release_status:date

T4S-transfer-BillOfMaterial
-use_attached_rev_rule=true

T4X-attach-RevisionRule
-mode=delete
-rev_rule_relation=IMAN_reference

That means a new revision rule is created based on the revision rule
template MyRevRule, it is attached to the workflow target and used
by the T4S BOM handler. The third handler will remove the revision
rule then
Restrictions

The specified revision rule template must exist in the Teamcenter


database

Handler name

T4S-transfer-OrderBillOfMaterial

Description

This handler transfers for each configured BOM view type a defined
order bill of materials to SAP.

Arguments

Same as T4S-transfer-BillOfMaterial, see above

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler

Handler name

T4S-transfer-EquiBillOfMaterial

Description

This handler transfers for each configured Equipment BOM view type
a defined equipment bill of materials to SAP

Arguments

Same as T4S-transfer-BillOfMaterial, see above

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler

Handler name

T4S-transfer-WBS-BillOfMaterial

Description

This handler transfers for each configured BOM view type a defined
Work Breakdown Structure Bill of Materials to SAP

160

TESIS PLMware

Configuring T4S to support customer specific requirements

Arguments

Same as T4S-transfer-BillOfMaterial, see above

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler

Handler name

T4S-transfer-ChangeNumber

Description

Creates a change number in SAP on the basis of the workflow job


name

Arguments

-UPDATE_EXISTING=TRUE|FALSE
Optional (default: TRUE): if this is set to FALSE, the ECM is created
but not modified. The handler checks first if the ECM already exists
and if it does, this handler aborts the transaction

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler

Handler name

T4S-transfer-DocumentInfoRecord

Description

Creates a new document info record in SAP for a given data set with
all the metadata (including the original files)

Arguments

All arguments are optional:

-mode=CREATE | UPDATE
= UPDATE (DEFAULT): create the DIR or update it f it exists
= CREATE: the DIR is only created, not updated (if the DIR
already exists the workflow stops with an error)

-metadata=YES|NO
= YES (DEFAULT): create/update the metadata of the DIR
= NO: do not update the metadata of the DIR

-objectlinks=YES|NO
= YES (DEFAULT): create/update the object links of the DIR
= NO: do not update the object links of the DIR

-documentstructure=YES|NO
= YES: create/update the document structure for the DIR
= NO (DEFAULT): do not update the document structure for the
DIR

Teamcenter Gateway for SAP Configuration Guide V10.1

161

-ORIGINALS=YES|NO
= YES (DEFAULT): create/update the original data (i.e. the files) of
the DIR
= NO: do not update the original data (files) of the DIR

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler.

Handler name

T4S-transfer-DocumentStructure4BomView

Description

This handler transfers for each configured BOM view type a defined
Document Struture to SAP

Arguments

Same as T4S-transfer-BillOfMaterial, see above

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler

Handler name

T4S-transfer-EquipmentMaster

Description

For an element of object class type ItemRevision an equipment


master is created or altered in SAP

Arguments

None

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler.

Handler name

T4S-transfer-FunctionalLocation

Description

For an element of object class type ItemRevision an equipment


master is created or altered in SAP

Arguments

None

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler.

162

TESIS PLMware

Configuring T4S to support customer specific requirements

Handler name

T4S-transfer-PIR

Description

For an element of object class type ItemRevision a Purchase Info


Record wil be created in SAP.

Arguments

None

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler.

Handler name

T4S-transfer-Vendor

Description

For an element of object class type ItemRevision a Vendor is created


or altered in SAP

Arguments

None

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler.

Handler name

T4S-transfer-GenericObject

Description

A configured Teamcenter object is transferred via a Teamcenter


workflow to a specified SAP target object. In SAP, the defined object
is created or updated and depending on the business rules approved
or rejected.
The business logic for the creation or update of the SAP object is
defined and implemented by the customer in the mapping file.
Supported Objects: all Teamcenter POM object types
Note that for Generic Object handlers, the same concept of
preferences for data extraction is used as for all out of the box object
types.
Also the data mapping for Generic Object handlers is done in the
same way as for out of the box object types: Define the Generic
Object mapping for a specific type in your own mapping file (dont
forget to source it in t4s_mapping_config.sd) in the following functions:

TC_Object2SAP_Object for defining the data mapping from

Teamcenter Gateway for SAP Configuration Guide V10.1

163

Teamcenter to SAP

Arguments

TC_Object2SAP_ObjectPosition for defining the data


mapping from Teamcenter BOM Position to SAP. Only for
BOM views.

SAP_Object2TC_Object for defining the back mapping from


SAP to Teamcenter

performSapTransfer for customer specific definition of the


actual transfer to SAP

getObjectInfo for retirieving the object information from SAP

callCustomerRuleHandler for defining a customer specific


rule handler

-TargetTypeName=<TargetTypeName>
Required: The TargetTypeName is a freely definable name. This
name has to be equal to the variable part of the preference names
used for the data extraction and to the last part of the namespace of
corresponding mapping.
Example:

Handler Argument:
-TargetTypeName=GenericObj
Preference Keys:
T4S_GenericObjTypeList
T4S_GenericObjMapping4SAP2_T4S_Item Revision
T4S_GenericObjMapping2SAP2_T4S_Item Revision

-useView4Transfer=TRUE
Required for BOM transfers: Enables the BOM view based generic
transfer to SAP
-BomHeaderTypeList=<SupportedObjectTypeList>
Required for BOM transfers: defines the list of valid types preference
name (format is T4S_<SupportedObjectTypeList>TypeList) that is
used to identify which structure needs to be transferred
In addition all other T4S handler arguments are possible
Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler.

Handler name

T4S-define-PreferredSapSystem

164

TESIS PLMware

Configuring T4S to support customer specific requirements

Description

This handler defines the preferred SAP connection for all following
transfer handlers, i.e. as long as no other SAP connection is given,
this one will be used

Arguments

Example:
-use_SAP_system=SAP2
-use_SAP_client=800

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler.

Handler name

T4S-SessionProxy

Description

This handler manages a proxy to forward the SAP login data between
different TC users if they are involved in one workflow, i.e. only the
first user will have to type his or her SAP login data and every SAP
transaction in the same Workflow job will be done with the same SAP
user.
Add -Mode=Save after the SAP Logon Task. If another TC user gets
the workflow (e.g. a reviewer), add -Mode=Read in his task to enable
him sending data to SAP with the same SAP user as the TC user who
started the workflow without the need to login separately. As then, this
TC user automatically uses the same SAP login outside of any
Workflow, too, you should add -Mode=Forget to avoid that

Arguments

-Mode=Save|Read|Forget|Delete
=Save (Saves the current SAP login into a T4S proxy)
=Read (Reads the SAP login from a T4S proxy)
=Forget (Deletes the logon data from the T4S proxy without
deleting the T4S Proxy itself) *
=Delete (Deletes a T4S proxy) *
* The difference is that after Forget the login data are not used
automatically again, but they may be reused with the argument
-Mode=Read; after a Delete, they cannot be restored

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler before the
T4S-SessionProxy called with the -Mode=Save argument.
Caution: do not use this handler with -Mode=Forget in a Workflow

Teamcenter Gateway for SAP Configuration Guide V10.1

165

Task that is executed before the Workflow is shifted to another


Teamcenter user (e.g. a generic T4S batch user), because this would
delete the current users SAP login (for Workflow and interactive use
as well)

Handler name

T4S-create-Folder

Description

This handler creates a folder in order to manage workflow targets

Arguments

None

Use/placement

The handler can be used in any task, preferably in action "Complete"

Restrictions

None

Handler name

T4X-create-T4X-BatchJob
(replacing former T4S-create-T4S-BatchJob)

Description

This handler creates a T4S Batch Job

Arguments

No mandatory arguments.
Optional arguments:
-Filter = [string]
Stores the string to the Batch job attribute JobFilter which can be used
to control which batch execution client may be assigned to execute
the job.
-JobPrio = [integer value 1 99]
This argument assigns a priority specifically to the workflow batch job
different from the default value 50. A lower value signifies a higher
priority. Batch jobs with high priority are executed first.
-JobNamePrefix = [any string]
This will manipulate the batch job name in the batch queue. Use this
to be able to differentiate by job name which workflow created the
batch job. (see details in "Teamcenter Gateway BatchServerGuide").
Valid Keyword:
- $SITE
- $USERID
- $USERNAME
- $GROUP
- $ROLE
-JobTimeout= [integer value]
Assigns the timeout value in seconds for the batch job. If a job
execution is not finished in the time frame the batch job will abort with

166

TESIS PLMware

Configuring T4S to support customer specific requirements

status RUNTIME ERROR.


-TimeWindowStart = hh:mm:ss
Sets the Batch job Attribute Time Window Begin to define the time of
first possible execution of the batch job per day. If not set default value
is 00:00:00 meaning the job may be executed at any time.
-TimeWindowEnd = hh:mm:ss
Sets the Batch job Attribute Time Window End to define the time of
last possible execution of the batch job per day. If not set default value
is 00:00:00 meaning the job may be executed at any time.
-tc_user = SelectedReviewer|ResponsibleParty
Sets the batch job attribute ITK_TC_USER_ID to a specific TC user to
use for the ITK connection of the batch job.
SelectedReviewer: Evaluate the user specified in workflow argument
-reviewer of TC OOTB action handler EPM-fill-in-reviewers (TC
versions < 10.1: CR-fill-in-reviewers) used in preceding Review Task.
ResponsibleParty: Evaluate the user specified in workflow argument
-assignee of TC OOTB action handler EPM-auto-assign (TC versions
< 10.1: auto-assign) used in preceding Do Task.
Please review "Teamcenter Gateway BatchServerGuide" to learn
more about batch job handling.
Use/placement

The handler can be used in any task, preferably in action "Start" of the
perform-signoff task. It is also possible to use the handler in a DO-task
as well.

Restrictions

None
Please Review required Workflow configuration in "Teamcenter
Gateway BatchServerGuide".

Manufacturing related handlers:

To be able to use the manufacturing related functions (routing, production order, CC


BOM, create AI, addform handlers), you have to include the following library in the
Teamcenter preferences:
TC_customization_libraries=
libt4s_manufacturing

The corresponding handler names are T4S-create-AIObject4CC, T4S-add-Form2CC, T4Stransfer-Routing, T4S-transfer-ProductionOrder, and T4S-transfer-CC-BOM:
Handler name

T4S-create-AIObject4CC

Description

Creates an Application Interface Object of type specified in

Teamcenter Gateway for SAP Configuration Guide V10.1

167

handler argument for the CC Object found as target attachment of


the current task
Arguments

-AI_TYPE
Mandatory: Application Interface Object Type Name
-use_cc_name
Optional (default: false). If set to true the name of the newly
created AI object is based on the CC object that is used as an
input for the AI object. We recommend to set this to true.

Use/placement

The handler can be used in any task, preferably in action


"Complete"

Restrictions

Works only for objects of type CC object

Handler name

T4S-add-Form2CC

Description

Adds the form specified by handler argument FORM_TYPE to the


CC Object found as target attachment of current task. If argument
handler ADD_AS_TARGET is also specified, the form will be
added also as target attachment of the current task.

Arguments

-FORM_TYPE
Mandatory: form type name of form to be added
- ADD_AS_TARGET
Optional, no value. If specified, the newly created form is added as
a workflow target attachment, otherwise it is only attached to the
CC
-RESET_FORM
If specified the content of the form (if it already exists) is reset

Use/placement

The handler can be used in any task, preferably in action


"Complete"

Restrictions

Works only for objects of type CC object.


The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler

Handler name

T4S-transfer-Routing

Description

Transfers Routing Data extracted from the Application Interface


Object found as target attachment of the current task to SAP. After
the creation of the routing in SAP, group counter and group id
information is written back into TC in the form attached to the CC

168

TESIS PLMware

Configuring T4S to support customer specific requirements

Object contained in the Application Interface Object.


Arguments

-Target=Routing|InspectionPlan|RefSetOfOperations
Defines the routing target type and the used mapping files (default
value is Routing)

Use/placement

The handler can be used in any task, preferably in action


"Complete"

Restrictions

Works only for objects of type Application Interface Object. A form


with at least to attributes ( for group counter and group id ) must
be attached to the CC Object contained in the Application
Interface Object.
The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler

Handler name

T4S-transfer-ProductionOrder

Description

Transfers Production Order Data extracted from the Application


Interface Object found as target attachment of the current task to
SAP

Arguments

None

Use/placement

The handler can be used in any task, preferably in action


"Complete"

Restrictions

Works only for objects of type Application Interface Object.


The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler

Handler name

T4S-transfer-CC-BOM

Description

Transfers MBOM Data extracted from the Application Interface


Object found as target attachment of the current task to SAP.

Arguments

None

Use/placement

The handler can be used in any task, preferably in action


"Complete"

Restrictions

Works only for objects of type Application Interface Object.


The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler

Teamcenter Gateway for SAP Configuration Guide V10.1

169

2.21.3 Important Teamcenter handlers used by T4S standard workflows

Depending on how you want to use T4S, this may be useful or not

The action handler EPM-attach-item-revision-targets is deprecated but still available

The newer action handler EPM-attach-related-objects allows more flexibility to select


the objects to attach than the older EPM-attach-item-revision-targets

Handler name

EPM-attach-item-revision-targets

Description

This handler attaches every data object that is linked by


IMAN_specification to the current object (the Item Revision where the
Workflow is started from) as target to the workflow job

Arguments

None

Use/placement

The handler can be used in the root task of any workflow

Restrictions

None

Handler name

EPM_attach_related_objects

Description

This handler allows attaching specified objects that are linked by a


specified relation to the current object (the Item Revision where the
Workflow is started from) as target to the workflow job

Arguments

relation=<relation_type> | property=<property_type>
type=<object_type_1>[,<object_type_2> ]
att_type=<attachment_type>
This handler allows some more arguments. Please see Teamcenter
documentation for more details.
Example 1 (e.g. for Datasets):
relation=IMAN_specification
att_type=target
Example 2 (e.g. for BOM views):
relation=PSBOMViewRevision
type=view
att_type=target

170

TESIS PLMware

Configuring T4S to support customer specific requirements

Use/placement

The handler can be used in the root task of any workflow. For
attaching more than one object/relation type combination, place this
handler more than once in the same Workflow template

Restrictions

None

Teamcenter Gateway for SAP Configuration Guide V10.1

171

2.22 Deprecated Configuration Functionality

All the necessary modifications described here may be done automatically by the T4S
migration tool, see Teamcenter Gateway for SAP Business Suite Migration Guide for
details

The following attribute names are deprecated since T4S V8.1 and have to be replaced (in the
preferences and in the mapping files) as described here:

IdString for the Teamcenter Item ID: use the original data model name item_id

IdString for the Teamcenter Item Revision ID: use the original data model name
item_revision_id

Name for the Teamcenter object name: use the original data model name object_name

Description for the Teamcenter object description: use the original data model name
object_desc

Since T4S V9.0, the following names are deprecated additionally:

The library libt4s_idgen is replaced by libt4x_idgen. The whole configuration of the ID


generation functionality is modified; see chapter How to use the SAP internal number
generator in the "Teamcenter Gateway for SAP Business Suite FAQ" for details

The preference value for reading all object properties T4S_Properties:Properties is now
#__getAllProperties__#:Properties

Since T4S V9.1, the following key word to be used in the mapping is deprecated additionally:

Before T4S V9.1, the key word "BomLine:OccurrenceNote" was used in the BOM
mapping for reading a Teamcenter BOM occurrence note. This is still valid in T4S V9.1 for
the occurrence notes T4S reads by default (e.g. bl_sequence_no, bl_quantity), but not for
customer specific ones. The new key word is just BOMLine for every type of BOM
occurrence notes

Since T4S V9.1, the following functions to be used in the mapping are deprecated:

172

The function ::T4X::CORE::storeMessage is replaced by ::T4X::CORE::storeMessage2


with an additional parameter, because there is an additional function
::T4X::CORE::storeMessage2DatasetLogfile now, see chapter How to write to the T4S
Workflow logfile Dataset in the Teamcenter Gateway for SAP Business Suite FAQ for
details

::T4X::TC::MAPPING::getWorkflowArgumentValue
is replaced by the new function
::T4X::TC::MAPPING::getWorkflowArgumentValue2
with additional functionality, see chapter How to use workflow arguments in the mapping
in the Teamcenter Gateway for SAP Business Suite FAQ for details
TESIS PLMware

Configuring T4S to support customer specific requirements

The following relation (navigation) names are deprecated in T4S and have to be replaced as
described here:

E2S_NamedReferences for the configuration and mapping to access the dataset named
reference information: use ref_list/<NamedReferenceName>
(e.g. ref_list/T4S_DATASET_EXTENSION)

T4S_NamedReferences for the configuration and mapping to access the dataset named
reference information: use ref_list/<NamedReferenceName>
(e.g. ref_list/T4S_DATASET_EXTENSION)

NamedReference:<NamedReferenceName> for the configuration and mapping to access


the dataset named reference information: use ref_list/<NamedReferenceName>
(e.g. ref_list/T4S_DATASET_EXTENSION)

Since T4S V10.0, the relation name IMAN_master_form_rev (which is in fact not a real
Teamcenter relation name) is deprecated and has to be replaced by IMAN_master_form
from T4S V11.0 on (i.e. it still works in T4S V10.x)

Before version 8.1, T4S used the relation name revision_list for navigating from a
Teamcenter Item Revision to its Item or back. From T4S V8.1 on, you have to replace
revision_list by items_tag in order to navigate from a Teamcenter Item Revision to its Item.
For navigating in the other direction, i.e. from an Item to its latest Item Revision, keep using
the relation name revision_list
Examples:

Check the Item ID of the current Item Revision:


set ItemID [::T4X::TC::MAPPING::FieldMapping
$ItemRevisionType:items_tag:$ItemType item_id]

Check Item Revision ID of the last Revision in the current Item:


set LastRev [::T4X::TC::MAPPING::FieldMapping
$ItemType:revision_list:$ItemRevisionType item_revision_id]

The mapping with $ItemType:revision_list:$ItemRevisionType


will always return data of the last Revision in the current Item. If you are starting from the
last Revision and ask this way:
set LastRev [::T4X::TC::MAPPING::FieldMapping $ItemRevisionType:
items_tag:$ItemType:revision_list:$ItemRevisionType
item_revision_id]
T4S will not return the same value but an empty value because all the data of this Item
Revision is already stored and may be looked up with the standard mapping call. So this
is a convenient way for testing if the currently used Item Revision is the last Revision in
the same Item:
if {[::T4X::TC::MAPPING::FieldMapping $ItemRevisionType:

Teamcenter Gateway for SAP Configuration Guide V10.1

173

items_tag:$ItemType:revision_list:$ItemRevisionType
item_revision_id] == } {
set This_is_the_last_Revision
true
}

174

TESIS PLMware

Configuring T4S to support customer specific requirements

2.23 Use of BMIDE Conditions (CLIPS) for configuration of rules


Teamcenter allows defining special conditions in BMIDE that may be used with T4S in order to
allow a codeless possibility to control the transfer of a workflow target object. This OOTB solution
may replace customer specific Workflow handlers and therefore facilitate the Workflow handling.
Using this functionality T4S will check if a Workflow target has to be processed or not without
checking the mapping code and therefore reduce the needed overall Workflow processing time.
The functionality using the BMIDE based conditions is only active if a specific workflow handler
argument is specified. It is supported for all the object based validate and transfer handlers, i.e.
nearly all the T4S handlers with one of these two words in its name, but not e.g. T4S-validateSAPLogon which is not specific to an object type.
For the support of the transfer conditions you need to define a BMIDE condition (see screen shot
below) and this condition needs to be defined with the following signature:
<ConditionName> (WorkspaceObject o)
(e.g. SAP2DemoCondition (WorkspaceObject o))

Teamcenter Gateway for SAP Configuration Guide V10.1

175

The code in the condition should return TRUE if the condition is fulfilled and can call any other subcondition that is needed. More details on how to define conditions and sub conditions can be found
in the BMIDE online help.
In a second step an additional handler argument needs to be specified in the used transfer handler
to enable the support of the BMIDE condition during the transfer. All these handlers (see above)
now support a new handler argument to enable the BMIDE condition based transfer:
-use_condition_on_target=<BMIDE Condition Name>
This specifies the name of the BMIDE condition used to verify if the selected workflow target or
change notice folder target object has to be processed by T4S or not. So the T4S workflow handler
calls the stated BMIDE condition and subsequently triggers the actual T4S processing if the
condition returns true. In case of an error during the condition processing the transfer is also
triggered. If the transfer is skipped by the condition the following message is written to the T4S
session log file:
Processing of 000011/A;1-MyName skipped by Condition <BMIDE Condition
Name>
and the following corresponding entries in the attached workflow log file:
<date and time>: <HandlerName>: process Item Revision object: 000011/A;1MyName
<date and time>: <HandlerName>: returns for Action: Complete =>
SKIPPED_BY_CONDITION

176

This does not need additional Workflow handler arguments or mapping code.

TESIS PLMware

How to provide Teamcenter and SAP account information

How to provide Teamcenter and SAP account


information

This may be used in order to be able to work without having to enter login data; it is also known as
auto login (to Teamcenter or to SAP).

The settings described here have to be done in the file


<T4S_ROOT>\var\mmap\t4s_mapping_config.sd

Each modification of this file requires rebuilding the mapping, see


How to modify the mapping on p. 34

3.1 Storing Teamcenter account information in plain text format


The following line will define a Teamcenter account, i.e. the connection to Teamcenter is
established with the user credentials without the need to type a user name and password
manually. This way you may access Teamcenter data from outside the Teamcenter portal, e.g. the
T4S Admin GUI or the T4S Batch Server.
set Status [::ITK::setConnectionParameters "user" "password" "group"]

Since the Teamcenter account information should not be accessible to anybody we


recommend storing the account information in encrypted form, see Storing Teamcenter
account information in encrypted format for details

This line must not contain comment signs (#) nor any additional characters

Make sure to pair the opening and closing square brackets [ ] properly

Replace user, password and group by the correct values; none of the parameters is
optional

Do not use a dollar sign in the password because TCL will try and replace the
following part by a variable content that does not exist most probably

If there is more than one line defining ITK accounts in the file, the last one is used

Teamcenter Gateway for SAP Configuration Guide V10.1

177

3.2 Storing SAP account information in plain text format


The following line will define a SAP account.
In General:
::T4S::CONNECTION2SAP::setConnectionInfoPlain
system client user password language mode usage
::T4S::CONNECTION2SAP::selectActiveConnection2SAP "*" system client
Example:
::T4S::CONNECTION2SAP::setConnectionInfoPlain
PLM
800
user1 passw EN USE_SAPRFCINI

BATCH

::T4S::CONNECTION2SAP::selectActiveConnection2SAP "*" PLM 800

Since the SAP account information should not be accessible to anybody we


recommend storing the account information in encrypted form, see chapter Storing
SAP account information in encrypted format below for details

This line must not contain comment signs (#) nor any additional characters

Replace system, client, user, password, language and usage by the values you want to
define according to the SAP system to be used (same as if you type it in SAP GUI), see
the example above

If any of the strings contains special characters (most likely for the password), enclose
it in quotation marks

Do not use a dollar sign in the password because TCL will try and replace the
following part by a variable content that does not exist most probably
Only the parameter usage is optional; if omitted, this SAP connection is used for
everything but SCRIPTING (see below)

178

Be sure to write the values for usage and system in all upper case letters (unless the
system is really defined with lower case letters which is usually not the case)

If you need more than one SAP auto login (e.g. WORKFLOW for one user and
SCRIPTING for another one), define them in separate lines

In any case (one or more accounts defined), you have to define the active SAP
connection (last line in the example above). This one will be used automatically if
nothing else is specified, e.g. by manual selection or workflow handler argument

Using this auto login means that many T4S SAP transactions will be done with the
same SAP user (also known as Technical user, as defined here) although they are

TESIS PLMware

How to provide Teamcenter and SAP account information

triggered from different human users. Please make sure that you are in compliance with
SAP licensing requirements when you define communication via a Technical user.
Setting up such communication is not meant to circumvent any licensing requirements
per your software contract with SAP; it is only meant for user convenience

The parameter usage determines for which transaction types this account information
should be used. The possible key words are as follows:

PORTAL: use this for all T4S transactions where a user presses a T4S button in
Teamcenter (in the T4S menu or the T4S GUI). Alternatively, you may specify a
separate SAP login for handling each portal transaction on each object type
separately (the key words are always PORTAL <object_type> <action>), e.g.:
PORTAL MM DISPLAY

for MM Display

PORTAL MM CREATE

for MM Create

PORTAL MM CHANGE_HID for MM Change hidden (direct)


PORTAL DIR CREATE_HID for DIR Create hidden (direct)
PORTAL BOM DISPLAY

for BOM Display

etc
The values are the same as for the T4S GUI configuration, see chapter
Choose the T4S menu functions (transaction types between Teamcenter
and SAP) on p. 22 in this document
PORTAL * LOV
see chapter

for updating Teamcenter LOVs from SAP,

Create a Teamcenter List of Values (LOV) with T4S on p. 149 in this


document. The auto login definition with the asterisk as shown here will
enable the SAP connection for every LOV or it may be restricted to a
specific LOV, i.e. if you have more than one LOV to handle, you will
need more of than one LOV auto login line, each one with one of the
LOV names as defined in BMIDE, e.g.:
::T4S::CONNECTION2SAP::setConnectionInfo SAP1 800 a65790
74b0caf8 EN USE_SAPRFCINI PORTAL SAP_LOV_1 LOV
PORTAL * SAPDATA_VIEW
use this for the SAP Data View,
see chapter SAP Data View within the T4S Rich Client extension on p.
138 in this document. Similar as with LOV, you may set it as shown
here with the asterisk for all types or with MM, BOM etc. (in one
separate line each) for restricting the auto login to the specified type(s)

WORKFLOW: use this for all T4S transactions from a Workflow, see below

IDGEN: use this for getting a new SAP Material number when executing the
Teamcenter function Assign while creating a new Item

Teamcenter Gateway for SAP Configuration Guide V10.1

179

180

BATCH: use this for T4S transactions launched from the T4S Batch server,
including T4S Admin GUI scripts using the T4S Batch functionality (each script with
the word batch in its name) , see "Teamcenter Gateway for SAP Business Suite
Administration Guide" for details on T4S scripts

SCRIPTING: use this for the T4S Admin GUI scripts


Caution: The scripts using the T4S Batch functionality need BATCH instead, see
above

RTP: use this for the Runtime Properties, see chapter Obtaining Teamcenter
runtime properties from SAP on p. 133 in this document

QUERY: use this for the T4S user query functionality. In order to use it for specific
queries only, add the query name to this call (else it is used for any T4S user
query), e.g.:
::T4S::CONNECTION2SAP::setConnectionInfoPlain SAP1 800
user passwd EN USE_SAPRFCINI QUERY T4S_DEMO_QUERY

(parameter omitted): this is a combination of all the usages besides SCRIPTING

Additional notes for the usage:

If you are in doubt which usage is the correct one for your desired functionality, start
trying without the last parameter for testing

If the value for usage is none of the list here, T4S will ignore the line, so if it does
not work, please check exactly the number and position of each parameter value
and the spelling

Any usage that is not covered by such an auto login definition will require a manual
SAP login, so you may have to login manually to SAP although there were
successful transactions before already (because they used the auto login)

These T4S SAP auto logins are stored in the tpapps process, only the one for
SCRIPTING is stored on the BGS. Therefore, after removing the auto logins from
the mapping and restarting tpapps, T4S will not use them any more besides the one
for SCRIPTING. This will still be available for the Admin GUI scripts as long as the
BGS is running or it is deleted explicitly. This may be done in the T4S script SAP
connection test with the parameter LOGIN set to Delete, or in the mapping:
::T4S::CONNECTION2SAP::deleteConnectionInfo $Dest $Client SCRIPTING

If only a SCRIPTING connection is defined (no other usages), you may omit the
additional line with "selectActiveConnection2SAP"; any other usage needs that
additional line

If such a line is added to the t4s_mapping_config.sd file, this account will be used for
SAP access and the user will not be able using another SAP connection for the
given usage by logging in manually; not even another user name with the same SAP
system name and client number

Any usage that is not covered by such an auto login definition will require a manual
SAP login, so you may have to login manually to SAP although there was a successful
transaction before

TESIS PLMware

How to provide Teamcenter and SAP account information

Teamcenter Gateway for SAP Configuration Guide V10.1

181

3.3 Storing SAP account information for more than one SAP
account to be used in a workflow

T4S is working with all these SAP accounts as expected using the manual SAP login
In order to use different SAP systems in workflows (in one workflow job or using different workflow
templates) do the following:

Define each of the needed SAP accounts as described above, e.g.


::T4S::CONNECTION2SAP::setConnectionInfoPlain SAP1 800 user1 passw EN
USE_SAPRFCINI
::T4S::CONNECTION2SAP::setConnectionInfoPlain SAP2 800 user2 passw EN
USE_SAPRFCINI

182

As described with saprfc.ini (see Teamcenter Gateway for SAP Business Suite Installation
Guide in more details, there is no need to set DEST to the SAP system name; it is just an
identifier for T4S. In order to use the same SAP system with different user names, you may
set up two or more sections in saprfc.ini that are physically the same SAP system. Then
create two lines with the auto login information here that may contain different user names,
client numbers or language codes or a combination of them

In each workflow template where one of these SAP accounts should be used, the workflow
arguments -use_SAP_system and -use_SAP_client with corresponding values
may be added to the corresponding T4S action handler, e.g. with the value SAP1 in the
handler T4S-transfer-DocumentInfoRecord

This defined SAP system will be used in this and all subsequent workflow tasks and jobs as
long as there is no other SAP system definition

In order to use the same SAP connection in each Task of the same workflow template and
checking this connection at the beginning of each Workflow Job, we recommend setting
these arguments in the rule handler T4S-validate-SAPLogon instead, i.e. before any T4S
transfer handler, e.g.:

TESIS PLMware

How to provide Teamcenter and SAP account information

T4S determines the SAP system to be used in a Workflow handler as follows:

As long as no T4S workflow action handler with the arguments -use_SAP_system


and -use_SAP_client was executed in this T4S session (i.e. since T4S was
started), T4S will use the SAP connection from the last definition with
selectActiveConnection2SAP in the file t4s_mapping_config.sd in every
workflow handler

As soon as a T4S workflow action handler with the argument -use_SAP_system and
-use_SAP_client was executed, T4S will go on using this SAP connection until
another connection is defined (by a Workflow handler or setting another Preferred
system in the SAP Connections window)

As this may result in different behavior when executing several jobs of the same
workflow templates, we recommend using these handler arguments in every T4S
workflow template only or not at all; but not some workflow templates with and others
without these arguments

Teamcenter Gateway for SAP Configuration Guide V10.1

183

3.4 Storing Teamcenter account information in encrypted format


In order to store the Teamcenter login data without storing the user credentials in clear text in the
mapping, do the following.

You successfully tested the Teamcenter auto login as described in the chapter Storing
Teamcenter account information in plain text format on p. 177. The only difference here is
that the user credentials are stored encrypted in the mapping
The same function setConnectionParameters as described above is used, but you have to set an
additional flag to tell it that the user name and password are encrypted. The default value is TRUE
to use these two strings as they are provided, so it may be left out when not encrypting these
strings. Set it to FALSE for telling T4S the strings for user name, password and group are
encrypted, e.g.:
set Status [::ITK::setConnectionParameters "153e3a842a" "eaec068" "" FALSE]

In this example, the group is left empty so the user will be in his default group.
To create these encrypted strings and use it in the T4S mapping, do the following:

Open the BGS Admin GUI application "Script Environment"

Select the T4S script "T4S Password Crypt"

Enter the string to encrypt (e.g. user1)

Click run to execute the script

Find the encrypted string 153e3a842a in the script output

Paste this into the above mentioned line

Do the same with the password for this user1

Do the same with the group name if desired

Save the file and rebuild the mapping

Another possibility is encrypting the entire line (i.e. the entire TCL command) that defines the ITK
connection info instead of the user credentials only:

Open the BGS Admin GUI application Script Environment

Select the T4S script T4S EvalCrypt

Enter the following command in the test script input field (replace user, password and group
by the values you want to define (none of the parameters is optional). If you want to use
the default group for this user, provide an empty string for group, e.g.:
::ITK::setConnectionParameters user1 pw1 ""

184

TESIS PLMware

How to provide Teamcenter and SAP account information

You will get an output like "HICHGGLBKPDOEPKCOOLO" (the string can be very long)

Include the output string into the line with evalCryptCode in the mapping file as in the
example stated below

Rebuild the mapping

Example for an encrypted ITK connection:


if {[::SYSBase::evalCryptCode HICHGGLBKPDOEPKCOOLO] == 1} {
tpwrite "t4s_mapping_config.sd: ERROR decrypting ITK User account info"
} else {
tpwrite "t4s_mapping_config.sd: using encrypted ITK User account"
}

The message indicating success does not mean that the login is accepted; it just
means that the decryption was successful (because the encrypted string was logically
correct)

The T4S script T4S EvalCrypt used here encrypts a whole TCL command no matter
of the content and purpose of the command; it is different from T4S Password Crypt
described above that only encrypts a string to be used as parameters for the auto login
functions

You may encrypt any TCL command to be used in the T4S mapping like this. As it gets
rather unreadable then, we recommend using this in very special cases only

Teamcenter Gateway for SAP Configuration Guide V10.1

185

3.5 Storing SAP account information in encrypted format

You successfully tested the SAP auto login as described in the chapter 3.1Storing
Teamcenter account information in plain text format on page 177. The only difference here
is that the user credentials are stored encrypted in the mapping

The following example will define a SAP account with user name and password encrypted:
::T4S::CONNECTION2SAP::setConnectionInfo PLM 800 341d0a857eaf9529
14282c827eaf96 EN USE_SAPRFCINI WORKFLOW

This line is the same as above but only the function name is different (because it expects
encrypted strings) and the strings for the user name and password are encrypted

To create the encrypted strings for the user name and password, do the following:

186

Open the BGS Admin GUI application Script Environment

Select the T4S script T4S Password Crypt

Enter the SAP user name into the input field and click run

You will get an output like "341d0a857eaf9529"

Include the output string into the line above in the file t4s_mapping_config.sd

Do the same for the password

Rebuild the mapping

TESIS PLMware

UI based mapping tool

Troubleshooting a T4S Installation

This chapter contains some hints on specific problems with the T4S handling after it is
basically running. If T4S is not running correctly at all, please check the Troubleshooting
chapter in the documentation Teamcenter Gateway for SAP Business Suite Installation
Guide

This chapter contains some detailed error descriptions so it might help you just searching
for a part of the shown error message here, no matter if the error message was created
by Teamcenter, SAP or T4S

More useful hints can be found in the documentation Teamcenter Gateway for SAP
Business Suite Frequently Asked Questions

In case of an unclear error situation, try the configuration check, see Teamcenter
Gateway Administration Guide for details

Please be sure if the error is caused by the mapping or something in the environment. If in doubt,
try and use your latest backup (or even the T4S standard mapping templates) to see if T4S runs
correctly with settings that used to work correctly.
Here is a list of common error situations:

If T4S is running correctly but seems to work extremely slowly when processing large
amounts of data (or even a process crashes), then check if your hardware fulfills the
requirements for T4S. For details see the documentation Teamcenter Gateway for SAP
Business Suite Installation Guide, chapter Pre-installation Considerations, especially
sub chapter Sizing Considerations.
If that did not help, check if Teamcenter itself is working correctly with those large data
amounts; maybe the network is overloaded then

If the T4S processes were already running but they consistently fail to start now, maybe the
file scs.lock was not deleted; please see the Troubleshooting chapter in the
documentation Teamcenter Gateway for SAP Business Suite Installation Guide

If you find a TCL error invalid command name or namespace doesn't exist,
one of the executed functions contains a function name (or a namespace name,
respectively) that has not been defined. Please check the following:
In most cases this is just a typo, e.g. T4S-ERROR: invalid command name
"tpwrit" means you missed the e of "tpwrite"
If the name in quotation marks (tpwrit in the above example) is one of the T4S
functions (e.g. TC_Object2SAP_MaterialMaster), it might be an error in the
structure in a mapping file (the files <T4S_ROOT>\var\mmap\*.sd), e.g. a bracket is
missing or one too much. You can check that by sourcing the suspicious file directly in
TCL using the following command in the T4S command shell (from the T4S/var/mmap
directory), e.g.:

Teamcenter Gateway for SAP Configuration Guide V10.1

187

tps t4s_mm_mapping_template.sd
This does not find every possible error in the files semantic, but it may give you a hint
on the error, e.g. missing close-brace or invalid command name "}"".
In case of no found error, it will not create any output
Maybe the function you want to call is in another file and T4S does not read it although
it is needed. As this may be a DLL as well as a mapping file, check the entries in
TC_customization_libraries
and the source section of the file t4s_mapping_config.sd
e.g. for the T4S Runtime Properties functionality:
source -relax t4s_rtp_mapping_template.sd
and check if it is read correctly (for a DLL, check the tcserver syslog file: search for
Cant load and Could not load)
The same things (file not loaded or typo in a function call) may be the reason for the
following error message

The TCL error T4S-ERROR: can't read "Function": no such variable. also
may be the result of a typo, but it may be the result of an incomplete migration of T4S
mapping files from an older T4S installation to a new one, because in earlier versions (older
than T4S V7), the T4S functions contained an additional parameter Function that does
not exist any longer. See T4S Migration Guide for details.

The Teamcenter ERROR 515007 = POM not started usually results from of a direct
ITK call in the T4S mapping without a correct ITK connection. Please check the following:
Is T4S started with the Teamcenter environment known? Example:

set TC_ROOT= ...

set TC_DATA= ...


call %TC_DATA%\tc_profilevars
call <T4S_ROOT>\etc\t4x_env.bat
<T4S_ROOT>\bin32\restart

The following two things may be necessary or not, depending on the Teamcenter
customization:
Do you have the ITK auto login activated in the file t4s_mapping_config.sd? Example:
set Status [::ITK::setConnectionParameters "user" "pw" "group"]

Enter the same login data as if you log in to Teamcenter, so the group may be empty.
Do you have the explicit ITK connect function call before the ITK call itself in the
corresponding mapping file? Example:
set Connection [::ITK::connect2TcDB]
set rc [<namespace>::<ITK function name> <parameters>]

188

A T4S test script seems to run forever without doing anything?


Every T4S script that reads or writes Teamcenter data needs ITK connection, i.e.
TESIS PLMware

UI based mapping tool

connection to the Teamcenter database without using Teamcenter portal or similar. If this is
not established by ITK auto connect or the ITK connect script and the current operating
system user name is no valid Teamcenter user, ITK asks for a console login. As in most
cases the ITK console (a command shell) is not shown, it is impossible to type the login
data there. Then the script will wait until it reaches its internal timeout (one hour by default).
Should you find a T4S script running very long and there was no successful run prior to
that, check the following points. If it should be the case, stop T4S (and so the tpitkpipe with
it), establish the ITK connection and try again

If T4S cannot read data of a specific type (e.g. data from one specific form type) although
the corresponding Mapping4 preference is correct, check the definition of this object type
in the database. If a T4S shows something like
T4S-LOG: E2S_RETRIEVE_getFormDataValues : returns 38015
(the Teamcenter error code 38015 means Unable to find a property with name %1$) then
the definition of this object type in the database is most likely incorrect. This may happen if
for example a Teamcenter object type definition has been modified or deleted and created
new later

The SAP error message CM_NO_DATA_RECEIVED at the end of a transaction may results
from the following:
The SAP GUI was closed with the cross in the upper right corner instead of clicking one
of the three colored arrows (Back, Exit, Cancel):

If this occurs randomly and in workflows as well, please check the SAP OSS note
867582

Whenever a problem occurs in a T4S functionality using java (including SAP JCo), e.g. the
transaction Vendor display does not work (additional symptoms may be error messages
containing PIPE BREAK", "UnsatisfiedLinkError", "Can't load IA), check if JCo is
installed correctly. Please see chapter Configuring T4S Connectivity to SAP in the
Teamcenter Gateway for SAP Business Suite Installation Guide and chapter JCo (Java
Connector) in the Teamcenter Gateway for SAP Business Suite Preparing SAP for
Teamcenter Integration Guide for details on the JCo installation

Teamcenter Gateway for SAP Configuration Guide V10.1

189

4.1 Some SAP Error Messages and how to handle them

Some, but not all, of these error conditions may be handled in the T4S mapping and
checked with the mapping test scripts.

The SAP messages


Field WERKS has been transferred inconsistently or is blank
or WERKS for MARC is ""; previously ""
mean that you tried to set plant specific data but did not give a valid Plant ID. Maybe
additional plant specific data need an additional plant ID (although the ID is the same in
most cases), e.g. the Storage Location requires setting the plant ID for the storage data
separately: set ::SAPDat(Material:MardData:PLANT) ...
The SAP message
Message: The material cannot be maintained since no maintainable
data transferred.
means that you either sent the same data that are already stored in this object or tried to
set data that are not allowed there, e.g. because the SAP target field has a LOV (List of
Values) that does not allow the new value. In both cases, SAP does not store anything in
this transaction.
After the transaction BOM Create, the message
Update Bill of Material: Usage of 'LEAVE ON TRANSACTION' in Batch
input forbidden"
means that the BOM already exists use BOM Change instead of BOM Create
The expression Batch input refers to a data transfer to SAP by an interface, e.g. T4S
Network address DEFAULT of your computer is not maintained.
This is not because of incorrect mapping, but a SAP DIR configuration problem: add the
entry DEFAULT for your desired Data Carrier type: SPRO Cross-Application
Components Document Management General Data Define Data Carrier: define at
least
o

In Define Data Carrier type server, front end: a type PC (selectable from the list, just
add a local directory, e.g. C:\temp\)

Below that in Identify front end computers: a type Default (selectable from the list,
leave all defaults)

This means, you allow any Windows PC to connect to this SAP using the default Data
Carrier. Only set an environment variable hostname with your computer name (which is
recommended in the SAP help) if you need to identify each machine uniquely and do not
want to set a default for all the machines.
SAP:: When the document is changed, status must be changed
(when creating or updating a DIR) means that this document type requires
190

TESIS PLMware

UI based mapping tool

any status when the DIR is created

another status when the DIR is modified

You can check this in SAP in the definition of your document type, checkbox Status
change. Note that it may be impossible to change from one status to each other status;
maybe a status even prevents any further modification at all.
Caution: although SAP may allow creating a DIR directly in SAP without asking for a
status, it will possibly refuse the DIR creation by T4S. This is not a T4S bug, but a SAP
restriction.
Errors in the mapping to set SAP classification data are often hard to track because most of
the error messages do not contain a hint where they belong to neither the classification
itself nor the characteristic name is mentioned, e.g. Entry does not have the
format date when you try to set a SAP class attribute that is formatted as date.
CURRENCY initial v., currency amount 1,2000 in STD_PRICE was
transferred without a currency
means that anything in MARC or MBEW is missing (or inconsistent) in order to set the price
information. Unfortunately SAP does not tell which field has to be modified. Then the MM is
not updated. T4S may not set the currency!
Enter a material type
may mean you are transferring valuation data, but miss necessary values for it, in most
cases MbewData:VAL_AREA or MbewData:VAL_CLASS which may be mandatory.

Teamcenter Gateway for SAP Configuration Guide V10.1

191

UI based mapping tool

This tool allows the T4S administrator to configure the T4S mapping in a very convenient way by
showing the mapping details graphically. It creates mapping files as you do it manually as well, see
chapter How to modify the mapping on p. 34 for details.
Caution: The Mapping Tool requires a Java Runtime Environment (JRE 1.4 or higher version). On
a system that has Teamcenter installed, this should already be installed.
In order to activate the GUI based mapping tool, extract the additional zip file
Teamcenter_Gateway_for_SAP_10.1.0_MappingGUI.zip and copy its contents to a new directory.
We recommend a new directory inside the existing T4S directory, e.g.
<T4S_ROOT>\mappingtool. The only thing that needs to be copied directly into the T4S
installation is the directory mmap, i.e. you should rename the existing directory
<T4S_ROOT>\var\mmap to backup your current settings and then copy the directory
<T4S_ROOT>\mappingtool\var\mmap to <T4S_ROOT>\var\mmap. In fact, the path does not
matter because it will try to connect to the GS using the default connection localhost:45401.
In order to modify that, open the file <T4S_ROOT>\MappingTool\etc\config.properties
and modify this line according to your T4S installation:
DefaultBaseURL=http://localhost:45401/pxml
Then you are ready to open the UI based mapping tool:

192

start your T4S (<T4S_ROOT>\bin32\start.exe; of course it needs BGS connection)

in any command shell, change to the mapping tool directory and execute
t4s_mapping.bat, e.g.:
cd <T4S_ROOT>\mappingtool
t4s_mapping.bat

then, the mapping tool should open and look something like this:

TESIS PLMware

UI based mapping tool

There will be an error message when the tool is launched for the first time in an
installation that the mapping tool cannot read the current mapping because it is missing
or damaged. This is because the file <T4S_ROOT>\var\conf\mapping.xml does not
exist when the tool is started first, as this file is written when the mapping is saved (File
Save Mappings on Server). If this error message recurs after a saved mapping file exists
it does indicate a problem.

To store the element structure of the mappings, T4S uses two files in <T4S_ROOT>\var\conf:

tc2sap_structure.xml (for the mapping from Teamcenter to SAP)

sap2tc_structure.xml (for the mapping from SAP to Teamcenter)

If you want to work on an existing mapping, start by selecting Open Mappings on Server from the
main menu. Note that this only handles mapping files correctly that have been created by the
Mapping Tool itself. Therefore they are named t4s_*_mapping_maptool.sd instead of
t4s_*_mapping_template.sd.
During the program start the mapping tool loads the mapping element structure automatically from
<T4S_ROOT>\var\conf (see above) and a sub window is created for each mapping. The sub
windows are opened by the combo box in the upper right corner of the program window. Each of
those mapping sub windows consists of two tree structures containing the elements of the mapping
and a drawing panel with buttons below that.

Teamcenter Gateway for SAP Configuration Guide V10.1

193

5.1 Create a sub mapping in the T4S Mapping Tool


A sub mapping is one piece of data to be set in Teamcenter or SAP, respectively. Just drag a
target object from the right upper window into the blank field in the lower part and add the logic to it
by dragging appropriate data objects from the upper left window to it and combine them.
Depending on its type, double-clicking a box allows modifying its value(s) or shows its result. For
creating a sub mapping with more than one element of the left tree structure, use the drawing
panel and place the elements in any desired arrangement.
The following example shows how the mapping of the Material number is set to a string built up
from the fixed value TP- (using a Constant String) combined with the Item ID of your current
Teamcenter object:

The blue lines indicate target data already defined whereas black lines show target
data that are still left empty.

Please read the chapter How to modify the mapping on p. 34 for more details

After you finished your mapping, save it by selecting Save Mappings on Server from the main
menu. Then you will find your mapping files modified in <T4S_ROOT>\var\mmap.
Then you have to recreate the mapping as described above in detail:

194

execute mmap.exe

TESIS PLMware

UI based mapping tool

move the result file t4s_mapping_config.rfdt from <T4S_ROOT>\tmp to <T4S_ROOT>\lib

To switch between sub mappings consider the following: Each element of the right tree structure
can be assigned to at most one sub mapping. In contrast to this, an element of the left tree
structure can be used in several different sub mappings. In both tree structures, those elements
are highlighted in color, for which there already exists (at least) one sub mapping. If an element
with an assigned sub mapping belongs to a category, of which the corresponding tree structure
isnt open, the category itself is highlighted in color. In this way, it is indicated, that the category
contains elements with assigned sub mappings. Based on the right tree structure, the user has the
possibility of displaying all elements of the left tree structure, which are used for a specific sub
mapping. By selecting one of the highlighted elements of the right tree structure, exactly those
elements of the left tree structure are connected by lines to the respective right element. If the
user is interested in displaying all relations and dependencies of a specific sub mapping in detail,
he has to double click on the respective highlighted element of the right tree structure. As
consequence of this action, the chosen sub mapping is transferred to the drawing panel. Also for
changes of an already existing sub mapping, it must be displayed in the drawing panel in this way.
Also for elements of the left tree structure you can display connection lines to elements of the right
tree structure. In this case, the connection lines describe the sub mappings which have a reference
to the selected element. As this relation isnt definite concerning sub mappings, because for an
element of the left tree structure there may exist several sub mappings, at this point it isnt possible
of displaying a sub mapping in the drawing panel. This transaction always has to be realized as
mentioned before. To distinguish the just described two kinds of connection lines, a describing text
is displayed at the bottom of the dividing bar between the two tree structures. The description
describes stands for the first type of connection line, whereas referenced by stands for the
second type.
There are three possibilities for deleting sub mappings:

Marking one of the highlighted elements of the right tree structure and then pressing the
Delete key on the keyboard

Right clicking on a highlighted element of the right tree structure and then selecting the
appropriate menu item in the popup menu, which has been activated by clicking the right
mouse button

If a sub mapping is open in the drawing panel, you may simply click on the button Discard
Sub mapping

Teamcenter Gateway for SAP Configuration Guide V10.1

195

5.2 The T4S Mapping Tool menu bar


The current chapter explains the commands that can be started from the menu bar.

5.2.1

File
Load Structure from Server

Loads two XML files, which describe the structure of the different mappings, from the server. For
each mapping direction (TC SAP and SAP TC) one XML file is loaded. The files are retrieved
automatically from the server directory <T4S_ROOT>\var\conf. Therefore a precondition of this
command is that the structure files are available on the server in the appropriate directory!

Open Mappings From Server

Opens previously saved mappings, i.e. XML files in the directory <T4S_ROOT>\var\conf on the
server. The mappings have to fit with the just loaded structure. Otherwise the process of loading
the mapping is interrupted.

The last version of the mapping file as saved on the server gets loaded.

If there doesnt exist any mapping file on the server, a warning dialog is displayed.

Save Mappings on Server

All changes carried out on the current mappings so far, are deleted with the loading of a new
file. To be on the safe side, youre made aware on this fact by a warning dialog.

Saves all opened mappings including all sub mappings within the drawing panels into an XML file
(mapping.xml) into the directory <T4S_ROOT>\var\conf. Before saving the sub mappings within
the drawing panels, all redundant objects (see the section about buttons below the drawing panel)
are removed out of these sub mappings.

If a mapping file already exists on the server, this old mapping file is overwritten.

196

TESIS PLMware

UI based mapping tool

Reset current Mapping

Deletes all sub mappings of the current visible mapping (the mapping of the activated tab). Just
before deleting, you are asked by a dialog window, if you really want to reset the current visible
mapping.

Reset all Mappings

Deletes all mappings (the mappings of all tabs) including sub mappings of the current session.
Once again an appropriate warning dialog appears just before the process of deleting.

Page settings

Allows configuring the page settings for printing by using an appropriate dialog window. For
example, the page size, the page margins and the page orientation can be specified.

Scaling

Allows configuring the scaling factors for printing by using an appropriate dialog window. Before
printing the content to be printed is scaled horizontally and vertically by the specified values.

Print

Allows starting a print process with the specified settings by using an appropriate dialog window.
The dialog window allows for additional settings und shows the number of pages needed.

Exit

Closes the program

5.2.2

Sub mapping

The commands of this menu refer all to the sub mapping, which is visible in the drawing
panel, at this moment.

Save and close sub mapping

When invoking this command, the current sub mapping within the drawing panel is saved internally
by the program and an empty drawing panel is opened. Now you are able to create a new sub
mapping or to load an existing one into the empty drawing panel.

When clicking on this button, the sub mapping isnt saved permanently.

If you intend to save it permanently, you have to select the command File -> Save Mappings on
Server in the menu bar.

Discard Sub mapping

Deletes the sub mapping, which is open in the drawing panel at the moment.
Teamcenter Gateway for SAP Configuration Guide V10.1

197

5.2.3

Extras

This has only the one sub menu Options.


For the current session you have the possibility to change some of the default settings, defined in
the configuration file. The undertaken changes are memorized until closing the program or
changing the settings again.

198

Change default divider size


Invoking this function, you can configure the width of the bar between the two tree
structures. This bar can be shifted left and right, at any time

Change default string for Concat


Invoking this function, you can specify the default setting for the string to put between two
elements which have to be concatenated

Change default constant string


With this function, you have the possibility to change the default value for the constant
string

Change default URL


The mapping tool also allows you to change the URL, which is used for loading a structure
from the server

Change printer resolution


Last but not least, it is possible to change the printer resolution. The printer resolution has
to be specified in dpi (dots per inch).

TESIS PLMware

UI based mapping tool

5.3 The Drawing Panel


At the bottom part of the program window, the drawing panel is located. Within this panel, also
more comprehensive sub mappings can be created. For this purpose, you have to add some
elements of the tree structures at the upper part of the program window to the drawing panel.
Afterwards you finish the complete sub mapping by connecting the items in the drawing panel with
lines. In the following, these steps are described in more detail.
Adding elements to the drawing panel
There are the following possibilities available for adding some elements of the two upper tree
structures to the drawing panel below:
Drag&Drop: Simply pull some elements of one of the two tree structures downwards into
the drawing panel. The elements will be put into the location, where you drop the mouse
button.
Double clicking: When double clicking on one of the elements of the tree structures, it will
be inserted into the upper part of the drawing panel in the height of the appropriate tree.
Keyboard entry: Select an element of one of the tree structures with the cursor keys, then
press the enter key.
Right clicking -> popup menu: The last alternative to add an element into the drawing panel,
is to click on an element of a tree structure with the right mouse button and afterwards to
choose the menu item Add element to drawing panel in the appearing popup menu.
Adding operators to the drawing panel
Next to the program window, to the right, there is the toolbox which contains the buttons for the
operators. By clicking on one of these buttons, a new operator is generated and inserted into the
drawing panel. Besides this possibility, the operators can also be put into the drawing panel via
Drag&Drop. The third possibility is, to click with the right mouse button on the empty drawing
panel. An effect of this action is the opening of a popup menu, where you can select one of the two
operators. After some elements or operators have been added to the drawing panel, they can be
moved into any other position by pressing the left or right mouse button in the middle of the
element or operator and pulling the object into the desired position, keeping the mouse button
pressed.
Deleting elements and operators from the drawing panel
If some of the just inserted elements or operators arent needed any more, you can delete them by
clicking with the right mouse button on one of the respective elements or operators and afterwards
choosing the menu item Delete element in the popup menu. The simpler way is just marking the
respective component and then pressing the Delete button of the keyboard.

Deleting an element or operator only is possible if no connection exists to any other


element or operator.

Teamcenter Gateway for SAP Configuration Guide V10.1

199

200

TESIS PLMware

UI based mapping tool

Connecting elements within the drawing panel


Each element within the drawing panel has at least one input box or output box. With the help of
these boxes, elements of the tree structures and operators can be connected among each other.
For this purpose you have to locate the mouse on such a box and pull a line to a box of another
object, to which a connection should be generated. This action is restricted by only connecting
input boxes (these ones are located at the left side of an object) with output boxes (these ones are
located at right side of an object) and the opposite way around. So for example, it isnt possible to
connect two input boxes. In the case, that a line is drawn from or to a box that is already
connected, the old connection is deleted.
Buttons below the drawing panel
Right below the drawing panel, there exists a set of buttons. The functionality of these buttons is
described in the following:

Save and close sub mapping:


By invoking this command, the current sub mapping of the drawing panel is saved intern
the program. An empty drawing panel is provided where to create a new sub mapping or to
load an existing one
Attention: When clicking on this button, the sub mapping isnt saved permanently. To save
it permanently, choose the File Save Mappings on Server in the menu bar

Discard Sub mapping


Deletes the sub mapping, which is open in the drawing panel at the moment

Pack Canvas
Changes the size of the drawing panel, so that all objects just fit into it

Remove unneeded elements


Removes all elements which arent connected to the element of the right tree structure (for
each sub mapping there exists only one such an element). This connection neednt to be a
direct one, but also can go through several operators

Remove unneeded elements from the toolbox


Removes all user defined black box elements from the toolbox, which are neither contained
in some drawing panel nor saved in some mapping

Preview
The drawing panel provides a preview function to make it possible for the user to control, if a
certain sub mapping really executes the desired mapping. For this purpose, you can assign each
element of the left tree structure, which is part of the current sub mapping, to any string. So you
have to click with the right mouse button on such an element within the drawing panel. In the
following step choose the menu item Configuration in the invoked popup menu. Instead you may
simply double click on the respective element. A dialog box for configuration will appear, where you
have to type the desired string into. This string will be processed by the connected operators. The
preview of the complete result string is displayed directly in the box of the element of the right tree
structure, to which the string should be mapped. This preview changes with each configuration of
an element, which has to be mapped or with each configuration of an operator. As the string is cut,
in the case that it is too long, there exists also another possibility to display the preview: Click with
the right mouse button on the appropriate element within the drawing panel and select the menu
Teamcenter Gateway for SAP Configuration Guide V10.1

201

item Preview of the result string in the invoked popup menu. Again, you also have the possibility of
double clicking the respective element. Soon a message box with the preview string will appear.
Moreover you may have the wish to see how the input data is processed up to a certain operator.
This is possible by the same way: A right click on the operator and afterwards selecting the menu
item Preview of the result string.
Configuration
For the preview function, it is possible to configure the preview data for the current sub mapping
within the drawing panel. Besides this, the operators can be configured. So the user may for
example configure the length of the operator Substr (-> see the chapter 5 about operators). The
configuration function is achieved by clicking with the right mouse button on an element or operator
and selecting the appropriate menu item in the popup menu, or just by a double click on the
respective component. However, an element of the right tree structure cant be configured. Each
configuration has direct effects on the preview function.
General Popup Menu
All functions, which can be invoked by pressing on a button below the drawing panel, can also be
invoked by choosing an appropriate menu item in a popup menu. Move the mouse pointer to an
empty area in the drawing panel and then click with the right mouse button to open the general
popup menu.

202

TESIS PLMware

UI based mapping tool

5.4 Operators
The following operators are available for extending a sub mapping:

Concat (Concatenation)
This operator has two input parameters. The operator concatenates these two parameters,
whereas a string, that is specified in the configuration file, or can be changed either in the
configuration window of the operator or via Extras -> Options , is inserted between the two
parameters

Substr (Substring)
This operator cuts the string which is transferred by the one and only input parameter. The
cut is done by following the specifications of the configuration window, which is displayed,
after the user has chosen the respective menu item in the popup menu. The configuration
of this operator allows the user to determine the start and end position of the new string,
whereas 0 indicates the first sign of the string and -1 denotes that the compete remaining
string should be transferred. In the case that the user didnt configure the operator, the
whole string of the input parameter is transferred

Decision
This operator allows specifying logical branches. There is exactly one control input
parameter, at least two value input parameters and exactly one output parameter. The
number of value input parameters and the values associated to them can be specified by
the user using the configuration window. The value linked to the control input parameter is
compared to the values associated to the value input parameters. If there is a match then
the value linked to the corresponding input parameter is returned as output parameter. If
there is no match then the empty string is returned as output parameter. Each new instance
of the decision operator has a unique individual name generated automatically

Blackbox
This operator allows specifying TCL code directly. There is any number of input parameters
and at least one output parameter. The number of input and output parameters and their
associated values can be specified by the user using the configuration window. Values
associated to input parameters specify input arguments for the operators TCL code;
Values associated to output parameters specify output arguments for the operators TCL
code. The string "value of _individual name_" is always returned as output parameter, as it
is not possible executing the defined TCL code. Each new instance of the black box
operator has a unique individual name generated automatically the user can change. If
the user changes the name, the black box operator is added to the toolbox as user defined
operator

To configure one of the two operators, you may just double click on the respective operator.
Moreover, you may click with the right mouse button on the operator and afterwards select the
menu item Configuration in the popup menu. Below the name of an operator, a short version of
the configuration is displayed. This holds for the concat and substring operator.

Teamcenter Gateway for SAP Configuration Guide V10.1

203

Basics on the script language TCL

T4S provides a simple programming environment based on TCL for the mapping of data between
the systems (Teamcenter and SAP). TCL is a widely used scripting language; a TCL interpreter is
integrated into the T4S infrastructure. A very useful help on TCL can be found on the following
Internet page: http://www.tcl.tk/man
(quick command reference http://www.tcl.tk/man/tcl8.5/TclCmd/contents.htm).

6.1 TCL procedures


The TCL interpreter comes with many built-in procedures that can be used inside a TCL program.
These procedures include:
string functions
arithmetic functions
basic input and output
etc.
Also a number of T4S functions (e.g. log output, configuration file access, SAP server access, ITK
handling, etc) are available as TCL procedures. More functions can be defined as TCL procedures
on demand.
Any TCL procedure has to be defined with a unique name and a list of arguments:
proc Person_Data {Name Street City} {
Then the argument variables Name, Street and City have to be passed by the calling routine
and can be accessed inside this procedure. It is possible to define procedures with the same name
but a different number of arguments, but there is no function overload as known from other
programming languages such as C. TCL will always use the last definition it read. So defining
the same function name twice in the same namespace is not recommended.
A function does not need a return but it may contain several return entries wherever
necessary in the code. A return causes the function exiting at this point and returning the
specified value to the calling routine. A return value is recommended but not needed. So the last
command in every function should be for example return 0.
To call this function, type for instance:
Person_Data "Name1" "Stree1" "City1"
Person_Data Name1 Street1 City1

or even without quotation marks:

In both cases, these three strings (they are not variables) are passed to the function Person_Data.
Calling a function with a wrong number of parameters will result in an error message wrong #
args. If you are not sure how many arguments you want to pass to this function, you can add the
key word args to the argument list in the function definition. If you define the function as
proc Person_Data {Name Street City args} {
you may call it with more parameters without getting an error. Using less than three parameters in
the function call will result in the wrong # args error again. If you provide more than three, than
they will be put into args which is a list variable, see below.

204

TESIS PLMware

Basics on the script language TCL

Another way of calling a function is to put its name in square brackets. Then its return value
(maybe an empty string if the function has no return value) is inserted at the point in the code
where it was called. The square brackets include the function name and the parameter list. For
example, if the above mentioned function has a return "OK", the call
tpwrite "call to Person_Data: [Person_Data Name1 Street1 City1]"
will result in the output call to Person_Data: OK. Of course the function will be executed in
the same way as above and if there are output commands those will also be returned.

6.2 Output Functions


The standard TCL command for an output is puts. Puts is used for output to files and to console
channels as well. For output in T4S, only tpwrite is used which is an adaptation of the TCL
standard puts modified specifically to write into the T4S log files.
In most cases, you should not use the standard TCL command puts in any of the T4S
mapping files because you will not find the output in the logs. puts will only create an output as
expected when not writing to a file, e.g. in a T4S test script (see chapter The T4S test scripts in
the Teamcenter Gateway for SAP Business Suite Administration Guide for details), where the
output is sent to the created web page, but not stored in any of the logs. So in most cases, you
should prefer writeCustomMappingLog (or writeCustomReverseMappingLog, respectively),
that sends its output to the web page and to the transaction log file, see below.

T4S will create each log file (always within the log path) without warning if it does not yet
exist (and also create the directories that do not yet exist).

In order to store additional debug output in a log, you may just use the following line in any of the
mapping files: tpwrite ++++++++++ output text
When stated without options, this writes ++++++++++ output text to tpapps.log. As the log
files maybe very big, we recommend adding a string that is found easily, in the above example the
plus signs.
If you want to write anything into a specific file, add the option -logchannel:
Example to write a line to the file tmp/test.log:
tpwrite -logchannel "tmp/test.log"

+++ test +++

Example to write a line to the session log file:


tpwrite -logchannel [::T4X::CORE::getSessionLogChannel] +++ test +++

In addition to "tpwrite" there are two more functions to write to the transaction log file:

::T4X::TRANSLOG::writeCustomMappingLog (writes a line to the mapping section of the


transaction log file)

Teamcenter Gateway for SAP Configuration Guide V10.1

205

::T4X::TRANSLOG::writeCustomReverseMappingLog (writes a line to the reverse mapping


section of the transaction log file)

See chapter Log File Handling in the Teamcenter Gateway for SAP Business Suite
Administration Guide for details.

6.3 Namespaces
Namespaces are a kind of grouping mechanism for functions and variables. As long as you are in
the same namespace you can access every function and variable by its name alone. When trying
to use it from inside another namespace, you have to call it with the whole namespace identifier. In
the mapping files, there is always a section starting with the word namespace.
This is at first the name of the current namespace (e.g. for material mapping:
namespace eval ::T4S::MM::CUSTOM::MAPPING), then the names of the functions that are
allowed to be accessed from outside this current namespace (namespace export). In fact, a
function may be called from within another namespace (in the T4S context this is mostly from
within another mapping file) even without the namespace export definition when the call
contains the complete namespace, e.g. the call to the first MM mapping function would be
::T4S::MM::CUSTOM::MAPPING::TC_Object2SAP_MaterialMaster.
The closing bracket of the namespace eval is at the very end of a mapping file, i.e. the
namespace definition contains all the functions defined in that file. If a function inside a namespace
is not stated with namespace export, it is not possible to call it from outside this namespace.
This entire name is always stated in the function header as Method.

206

Any variable defined outside a namespace and outside a function is accessible


everywhere without a namespace name

The key word variable within a namespace eval command creates and initializes a
namespace variable, e.g. variable test abc. If this command (but without the
initializing abc) is called from within a procedure inside this namespace, it will refer to
the same variable test. For instance, in the BOM mapping file, the command variable
BomPositionInfo does not create a new variable, but it allows the access to the
variable BomPositionInfo that is created in the same namespace but outside the
function definition. Without the variable BomPositionInfo, you would have to
write it with the whole namespace name to access it.

TESIS PLMware

Basics on the script language TCL

6.4 Variables
Variables have to exist when they are called, else an error can't read <name>: no such
variable is given. You can introduce a variable at any point of a mapping file by simply defining
it, e.g. set Var1 value. Then you can use this new variable, e.g. tpwrite $Var1.
The counterpart of set is unset (clear memory). This may be stated at any point in a program,
but it is never necessary from the logic point of view. It might be useful for memory size reasons.
It is not possible to concatenate strings with the plus ("+") symbol. Strings can be built up by just
putting its parts into quotation marks, no matter if they are variables or constant strings (but
constant strings always have to be put in quotation marks):
set var1 $var1 and $var2
If the variable var1 is rather long, then it is more efficient to use the append command:
append var1 and $var2
This allows any number of arguments. All of them (besides var1 itself) are put together into the
variable var1. It does not matter if this already exists; if not it is created.
Variables are either global (if defined outside any procedure) or local (if defined inside a
procedure, then they are normally only accessible inside this procedure). There are two
possibilities of accessing a global variable within a procedure without defining a new (local) one:

tell the TCL interpreter that this name in this procedure always refers to a global variable:
global paul

tell the TCL interpreter at the call to the variable that it is a global variable: $::paul

Then inside the procedure "jim", both calls to the variables refer to a global variable:
set paul empty
set john empty
proc jim{args} {
global paul
set var3 $paul
set var7 $::john
}

We recommend only using the scope operator (::), not the keyword global. So you always see
that a global variable is used. This also allows using a variable in more than one function.
You can put that variable in the header of the file (maybe inside or outside a namespace
definition):
Definition:

set ::Test_Var1

content of Test_Var1

Teamcenter Gateway for SAP Configuration Guide V10.1

207

tpwrite $::Test_Var1
tpwrite Variable: $::Test_Var1

Call:

This tells the TCL interpreter that Test_Var1 is a global variable (so it should not look for that in
the local variable memory space). It also works in different files; see

Direct Mapping of Constants on p. 45. The names of the files do not matter (see How to modify the
mapping on p. 34) but the names of the namespaces, functions etc must not be altered.

208

If a word in an output starts with a dollar sign ($) it is a variable, else it is a constant

Be careful with special characters in the source code:


- blanks divide different words (e.g. variable names or TCL key words)
- an open square bracket ([) will expect a close square bracket and a function name
(e.g. string trim) inside it to execute
- an open curly brace ({) will expect a close one, too. It is used to group
expressions where logically only one is allowed, e.g. in an if structure

In a string, curly braces divide a variable name from a text, so you can combine the
value of a variable with other text without blanks, e.g. (if Var1 is 123)
set test_var start{$Var1}end
will set the variable test_var to start123end. If you leave the curly braces, it will cause a
TCL error if the variable $Var1end is not defined

As a rule, TCL treats any variable as a string, independent of its content. To use its
numeric content, use the expr command, e.g. you can count something with
set Index_new [expr $Index+1]
sets Index_new to the value that is
one more than $Index.
Caution: If $Index is empty or contains other characters than digits, this causes an error

Variables can be evaluated as Boolean, too: if {$error_occurred} {


A value 0 (zero) is interpreted as false, any other numeric value as true. If the string
contains other characters than digits, this causes an error.
Caution: in such a string, 000 is evaluated as zero and 001 as one

If the position in a variable (string, field, list) is needed, note that the first element is
always referenced as zero

It is possible (but unwise!) to use the same name for a global and a local variable.
Although it is possible to distinguish them exactly with the scope operator (::) there
surely will be a confusion at any time

TESIS PLMware

Basics on the script language TCL

6.5 List Variables


A variable contains mostly one string, but there is a way to have several strings in one variable:
create a list variable (this is done in TCL with the key word list). The most important commands
for lists are:
concat arg1 arg2: treats each argument (any number of arguments allowed) as a list
and concatenates them into a single list. It also eliminates leading and trailing spaces in the
arguments and adds a single separator space between them
lappend: append an element to a list variable

llength: count the number of elements in a list

lindex: retrieve an element from a list

6.6 Data Arrays


Arrays are a construction where several variables can be accessed with a common variable name
and one or more indices. The indices are not integers (as known from other programming
languages) but strings. This means there is no unique order of the indices and not all possible
variables with the defined indices have to exist at any time. Maybe you have an array with the
known indices b and c at one point of a TCL program. If you later find the same variable name
with the index c, it does not mean necessarily that the same variable name with the index b
exists. This means for T4S: if you find the error mesage can't read
"::TcData(ItemInfo:ObjectClassName)": no such variable
in the test mapping (in the Admin GUI) it is in most cases not a programming error, but this variable
was not created because the test mapping tried to get data from an object that does not exist.
For further information on array handling in TCL, see the TCL tutorial:
http://www.tcl.tk/man/tcl8.5/tutorial/Tcl22.html

6.7 Some important TCL functions

[binary format {H*} $var]


gives the clear text of the binary coded variable var. Although in TCL, binary format is
mainly used for creating a binary string from normal data, binary format {H*} will do the
opposite and extract the readable text data from the binary format.
T4S additionally offers an own function called tpco_formatHEX16 which does the
same in principle (de-hex a text in hex format) but it has the advantage that it does not
end with a runtime error if the input string is not a pure hex string, but it just returns an
empty string. The original TCL command will end with an error message like:
expected hexadecimal string but got "48656c6c6fxyz" instead

[clock format [clock seconds] -format "%Y-%m-%d %R"]


gives a formatted time string, here for example:
2005-03-01 14:32 [clock seconds]
is the number of seconds elapsed from a virtual start time

Teamcenter Gateway for SAP Configuration Guide V10.1

209

Note that according to ISO 8601 specifications, the TCL clock functions are defined for
the time range from year 1970 to year 2037 only

[format "%s.%s" $Num1 $Num2]


generates a formatted string in nearly the same way as the ANSI C sprintf function (see
the above mentioned TCL help for details)

[info ]
Return information about the state of the TCL interpreter, e.g.
[info exists varName]
returns "1" if the variable named varName exists in the current context (either as a global
or local variable) and has been defined by being given a value, returns 0 otherwise.
Useful to test if a variable exists

regsub -all {\.} $Quantity {,} Quantity_new


copies the string Quantity to the string Quantity_new with all the dots replaced by a
comma. The variable names may be the same (then it is overwritten)
Please see the point regular expressions in the next chapter

[scan $string1 $format result_strings]


Parse string using conversion specifiers in the style of sscanf from C++, e.g.
set parts [scan $inputstring "%\[^_\]_%s" v1 v2]
searches for an underscore (_) in the variable inputstring and saves the two parts (one
before and one after the underscore) into the two variables v1 and v2. If there is no
underscore, v2 will be empty and v1 the same as inputstring. As this is a very powerful
function you should read the manual when using it for special needs

[string length $Var1]

[string range $Var1 0 9] gives the first 10 characters of Var1

[string repeat " " 5]

gives a string that consists of five blanks

[string toupper $Var1]

converts Var1 to upper cases

[string trim $Var1]

cuts white space (spaces, tabs, newlines, and carriage


returns) at beginning and end of Var1

[string trimleft $Var1]

cuts white space at beginning of Var1 (analogue: trimright)

[string trim $Var1 x]

cuts every x at beginning and end of Var1

gives the number of characters in Var1

Caution: If you have a string like abcddde and perform [string trim $Var1 de] on that,
you will not get abcdd, but abc

The most important TCL operators are == (equal), != (not equal), < (smaller), > (bigger)

In TCL, the standard if command is:


if { $var1 == "abc"} {
puts "OK"
} else {

210

TESIS PLMware

Basics on the script language TCL

puts "nio"
}

In TCL, the standard for loop is:


for {set x 0} {$x<10} {incr x} {
puts "x is $x"
}

6.8 Traps to avoid in TCL

Every open bracket needs a close bracket of the same type (parenthesis ( ), curly brace
{ } or squared bracket [ ]). Many text editors allow searching for a corresponding
bracket

The open curly brace has to be in the same line as the command that opens it, and it
needs a blank before it. A line that only contains an open curly brace (as often used in C
programs) is an error in TCL. A correct line in TCL is
if {$Status == "ERROR"} {

When commenting out an open curly brace, there has to be a corresponding close curly
brace that is commented out, too. This example would cause an error (even if there is no
corresponding close curly brace in the source code):
# if {$Status == "ERROR"} {
This is correct (no matter if there is code commented or not between the two lines):
# if {$Status == "ERROR"} {
# }

Do not add any comments in a switch structure. Even inside a comment, the logical
structure is checked and even the code may be used as if it was not commented:
This is example does not create a runtime error, but nevertheless the result will be 2 if
the checked variable has the value SAP OK:
switch -exact -- $Value {
# Test: {SAP OK}
{set xy "2"}
{SAP OK}
{set xy "1"}
{SAP NOT OK}
{set xy "0"}
default
{set xy "error"}
}
Although it looks more logically correct, a line like this inside the switch will cause an
error:
# {SAP OK}
{set xy 2}
So please move any comment outside the structure

The backslash indicates that the following control character is not to be used as such. So if
a source code line ends with \, the following line is treated as if it was in the same line (as
the new line character is ignored). If there is a blank following the backslash it will not
work (as the blank is ignored which does not mean anything)

Teamcenter Gateway for SAP Configuration Guide V10.1

211

Some characters are evaluated as regular expressions, i.e they have a special meaning.
Thats why the backslash in the first curly braces of the following command is necessary
(copy the string Quantity with all dots replaced by commas to the new string
Quantity_new):
regsub -all {\.} $Quantity {,} Quantity_new
For details, see TCL online help: http://www.tcl.tk/man/tcl8.5/TclCmd/re_syntax.htm

Comments after a statement are not allowed. The only way is to tell the TCL interpreter to
handle the following as a new line. This is done with a semicolon (;). The following
example is a correct line with a statement and a comment in only one source code line (but
internally treated as two lines):
puts "Hello World" ;# This is a comment after the command

TCL does not handle variables with a defined type as known in other programming
languages. In principle, every variable is a string but TCL will try and handle it as the type it
thinks it is, e.g. an octal number:
If a string contains a number, TCL will try and evaluate it as number. Although it might
seem strange, the following conditions are always true:
if {"0" == "000"}
if {"+00001.2" == "1.200"}
For the same reason, the equation with two strings containing an e may fail as TCL
will treat it as a number in exponential notation. In contrast to integer, the numeric type
float (floating point number) does not have a defined overflow, so a number with a too
high exponent will not be treated as another smaller number, but as value infinite. So
the in the following example, TCL will compare infinite with infinite which means they
are equal:
if {"5e321" == "6e321"}
To avoid this equation problem, be sure to tell TCL you want to compare strings
instead of numbers (eq for equal, ne for not equal):
if {"5e321" == "6e321"} true
if {"5e321" eq "6e321"} false
Any string that may be a number and starts with zero is treated as an octal number,
so a string "08" or "09" leads to a TCL error when it is used in an equation. If you read
strings that should be evaluated as numbers, be sure that there are no leading zeros,
e.g. for the SAP DIR version:
set Doc_Temp [string trimleft $DocumentVersion "0"]

212

TCL allows error suppression with the command catch. Then the program continues
after the line that caused the error and no error message is stated. As this may prevent
error tracking, you should only use it if you cannot find another way. Of course it is better to
make a program fail-safe by detecting and handling errors systematically instead of only
preventing error messages

If a function with the same name is defined more than once, TCL uses the last one that it
reads. This may happen if you have backups of your mapping files in the directory
T4S/var/mmap, so avoid this even if the file names are different

TESIS PLMware

Das könnte Ihnen auch gefallen