Beruflich Dokumente
Kultur Dokumente
Configuration Guide
Version 10.1
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.
Cautions are important notes with crucial impact on the installation or operation of the
software
After some installation or operation step you should validate the result as described
here before proceeding
Table of Contents
1
Introduction ....................................................................................... 9
2.1
2.2
2.3
2.4
2.5
2.1.1
2.1.2
Configuring supported objects and the T4S user interface (GUI) ......................... 14
2.1.3
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
Overview ............................................................................................................. 26
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.3.2
2.3.3
2.3.4
2.3.5
2.4.2
2.4.3
2.4.4
2.4.5
Definition of DIR data mapping from SAP to Teamcenter (reverse mapping) ...... 70
TESIS PLMware
Introduction
2.6
2.7
2.8
2.9
2.5.1
2.5.2
2.5.3
2.5.4
2.5.5
2.5.6
Definition of BOM data mapping from SAP to Teamcenter (reverse mapping) .... 80
2.6.2
2.6.3
2.6.4
Definition of ECM data mapping from SAP to Teamcenter (reverse mapping) ..... 83
2.6.5
2.6.6
2.7.2
2.7.3
2.7.4
2.8.2
2.8.3
2.8.4
2.10
2.9.1
2.9.2
2.9.3
2.9.4
2.11
2.12
2.13
2.14
2.15
2.16
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
2.18
2.19
SAP Data View within the T4S Rich Client extension .................................... 138
2.20
2.21
2.22
2.23
3.1
3.2
3.3
Storing SAP account information for more than one SAP account to be used
in a workflow ..................................................................................................... 181
3.4
3.5
4.1
Some SAP Error Messages and how to handle them .................................... 189
5.1
5.2
5.2.2
5.2.3
5.3
5.4
6.1
6.2
6.3
6.4
6.5
6.6
6.7
6.8
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:
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.
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
modify all the affected preferences in that file according to your needs
TESIS PLMware
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.
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
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.
13
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)
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
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
14
TESIS PLMware
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
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 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)
SAP connections:
T4S.AttributesStylesheets.<symbolic_name>.EaConnections
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.
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
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
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
17
T4S can show the following data in the T4S transfer window:
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 sap2SAPMatNo which is a compound property of the current object, see below
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
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"/>
19
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"/>
T4S allows using the wildcards * and ? in the target type names
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
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:
21
2.1.5
Choose the T4S menu functions (transaction types between Teamcenter and
SAP)
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
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
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
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).
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
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.
# -------------------------------------------------# 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
25
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 UNIX/Linux, define it as an executable file (the file extension does not matter)
Any attribute that is stored in a Teamcenter form, e.g. the standard Item Revision Master Form
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
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
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
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
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
"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:
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
$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
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:
"$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
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
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 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
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
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.
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
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
doing large modifications so you can compare the file with its previous content if the new
version should not work as expected
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)
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
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
2.2.3
Generate Mapping
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
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
As every single T4S thread runs through this file when initializing, you may notice that
it is executed several times
TESIS PLMware
2.2.4
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).
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:
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
TESIS PLMware
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.
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
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)
TcData(Workflow:RootTaskName)
TcData(Workflow:TaskName)
TcData(Workflow:JobName)
TcData(Workflow:JobDescription)
TcData(Workflow:Action)
TcData(Workflow:Argument:x)
TcData(Workflow:ReleaseStatus)
42
TESIS PLMware
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")
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)
TcData(Portal:Action)
44
TESIS PLMware
2.2.5
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"
$::T4S_Defaults(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.
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
45
2.2.6
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)]
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
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
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 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.
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
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
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
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
49
Plant specific material data; almost all the values of the material master table MARC can be
filled
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
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
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.
51
"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
52
TESIS PLMware
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
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
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
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
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.
55
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
T4S_MaterialMasterFieldMapping2items_tag:Item=
item_id
T4S_MaterialMasterFieldMapping2items_tag:Item:IMAN_master_form:Item
Master=
user_data_1
2.3.5
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>
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.
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):
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
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.
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
}
59
2.4.1
To define the dataset types and data mapping from Teamcenter to SAP the following adaptations
in the Teamcenter preferences have to be done.
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)
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
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
You have to specify all of these for each defined Type separately (i.e. for each entry in
the TypeList preference)
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
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):
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
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
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
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
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
::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
NamedFileReference: defines the relation to the actual Teamcenter file, i.e. the
Datasets named reference
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
65
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
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
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
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
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:
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)
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.
$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
2.4.4
To define the reverse data mapping from SAP to Teamcenter the following adaptations in the
Teamcenter preferences have to be done.
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
69
2.4.5
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"} {
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
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
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
To define the BOM view types and data mapping from Teamcenter to SAP the following
adaptations in the Teamcenter preferences have to be done:
71
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
72
TESIS PLMware
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.
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.
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"
}
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
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
"$::T4S_Defaults(Plant)"
"$::T4S_Defaults(BomAlternative)"
"$::T4S_Defaults(BomUsage)"
""
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)
74
TESIS PLMware
set ::SAPDat(Bom:BomHeader:BMEIN)
set ::SAPDat(Bom:BomHeader:STLBE)
set ::SAPDat(Bom:BomHeader:LABOR)
set ::SAPDat(Bom:BomHeader:LOSVN)
set ::SAPDat(Bom:BomHeader:LOSBS)
set ::SAPDat(Bom:BomHeader:MATNR_LONG)
set ::SAPDat(Bom:BomHeader:OITXT)
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
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
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
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
77
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:
Component (unique identification of the object represented in this BOM line, in most cases
MM or DIR)
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!
78
TESIS PLMware
2.5.4
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
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]
79
2.5.5
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)
2.5.6
Be aware of the settings for different Item Types for BOM as described in the
beginning of this chapter.
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
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
81
2.6.1
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
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
Depending on its installation, SAP may require the date in a different format
TESIS PLMware
2.6.3
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
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"
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]"
83
2.6.5
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
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
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
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
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
#
# 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
2.7.1
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
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:
87
The individual fields available are shown in the tables in the appendix.
The examples below show data mapping of EQUIPMENT number and 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.:
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
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
2.7.4
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:
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"]
89
2.8.1
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
2.8.2
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:
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"
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
91
2.8.4
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:
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
2.9.1
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
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
93
2.9.2
For setting data to the SAP Vendor, T4S provides amongst others the following:
Company Code
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
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
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
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
95
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
97
There are some significant differences in the configuration of Teamcenter for routing
compared to other transactions
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
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.
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.
TESIS PLMware
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.
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
103
"http://localhost:7001/tc"
"proxy"
set ::T4X::SOA::CtrlParam(HTTPProxyPort)
80
http://erp.esworkplace.sap.com
"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"
"NETWORK"
set ::T4S_Defaults(ProjectProfile)
"U"
104
TESIS PLMware
set ::T4S_Defaults(NetworkProfile)
"Z000002"
105
"WBS"
set ::T4S_Defaults(ProjectProfile)
"U"
set ::T4S_Defaults(NetworkProfile)
"Z000002"
106
TESIS PLMware
107
108
TESIS PLMware
109
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.
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
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"
111
T4S_GenericObjMapping2ItemRevision=
IMAN_master_form_rev:ItemRevision Master
T4S_GenericObjFieldMapping2IMAN_master_form_rev:ItemRevision Master=
user_data_1
user_data_2
user_data_3
::T4X::TC::MAPPING::storeReverseMappingAttribute GenericObj
"ItemRevision:IMAN_master_form_rev:ItemRevision Master" user_data_1
"GenericObject mapping test"
If you want to get Generic Object data, you have to execute the following function prior to asking
SAP for data:
112
TESIS PLMware
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.
The Generic BOM Mapping can be applied to all Teamcenter POM object types
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.
For detailed information about the handler please see Chapter 2.21 Workflow
Handler Functions.
113
For the definition of the preferences you can use the examples for the standard
OOTB transfer types.
114
TESIS PLMware
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"
115
116
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
Additional information can be found in "Teamcenter Gateway for SAP Business Suite
Preparing SAP for Teamcenter Integration Guide" chapter 8
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).
117
Transaction MM01
or MM02
Modify data
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
118
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
"MM"
checkJobIsValid
compareObjectNr
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
T4S
# File:
trigger_sap_zjob.tcl
# --------------------------------------------------
119
"Mode"
"Interval"
::TestScript::setScriptParam "BatchTemplate"
[list MM DIR BOM ECM PO WC POBOM]
::TestScript::setScriptParam "ObjectType"
"Z-Table Object Type
(optional)" [list "" MATERIAL DOCUMENT BOM ECM PO WC POBOM]
::TestScript::setScriptParam
Batchjob (optional)"
::TestScript::checkTestParam $::argv
-BatchTemplate
-ObjectType
-AdditionalInfo
-Mode
}
}
} 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
exit 0
}
# -------------------------------------------------# Method:
compareObjectNr
# Description:
# 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:
# Created:
kh, 20050823
121
# Return
#
# Changes:
# CHANG-DDMMYYYY-HACKER: aenderungaenderungaenderung
# -------------------------------------------------proc checkJobIsValid { ZPTC_Id } {
set rc_func
$::g_const_FALSE
#
# 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
set
$tmp_BomKey
$tmp_BomKey
$tmp_BomKey
} 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
123
# Description:
# Created:
kh, 20050823
# Return
#
# Changes:
# CHANG-DDMMYYYY-HACKER: aenderungaenderungaenderung
# -------------------------------------------------proc triggerBatchJob { args } {
# 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
DIR
BOM
ECM
PO
WC
POBOM
EQUI
FUNCLOC
VENDOR
PIR
IPPE_NODES
124
TESIS PLMware
NETWORK
WBS
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
}
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"
125
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
if { $rc == "OK" } {
# set the status of the job to "Q" (QUEUE), so that the job
#
126
TESIS PLMware
127
if { $::g_Mode == "single" } {
exit 0
}
after $::g_Interval
}
exit 0
ZPTC entry:
OBJECT_TYP
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
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
Mapping template
Usage
OBJECT
T4S_IMPORT_OBJECT
t4s_object_import_template.sd
META
T4S_IMPORT_META
t4s_meta_import_template.sd
129
In general T4S is able to create and update Teamcenter objects of following types:
Item
ItemRevision
Form
GDE
Dataset
view
ICO
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
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:
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):
to:
[::T4X::CUSTOM::MAPPING::TOOLBOX::selectTC_Object LATEST item_id
$MaterialNumber object_desc [::T4S::TC::MAPPING::SAPFieldMapping
MaterialMaster $MaterialNumber MATERIALDESCRIPTION:MATL_DESC:1]]
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
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.
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
133
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)
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.
134
{set ::StatusInfo(RuntimePropertyValue)
TESIS PLMware
[::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:
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:
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
Each click on such an object requires an additional data transfer from SAP and
therefore you will notice a delay
""
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]}
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
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
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]
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
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 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
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
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
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
The fields Material, Base Unit of Measure are standard text fields created with the
command createFieldEntry as described above
143
set LineList
[split $Line :]
set LineIndex
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
#
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
::T4X::PROP::MAPPING::begin
TESIS PLMware
-doc rc column
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:
145
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]
146
TESIS PLMware
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
147
-doc rc hyperlink
-doc rc hyperlink
-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
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.
Start your Teamcenter client and check that an empty LOV is attached to the desired
attribute
149
TESIS PLMware
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
151
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
TESIS PLMware
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.
T4X-attach-LogfileDataset
Description
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
Arguments
Use/placement
Restrictions
None
Handler name
T4S-validate-ChangeNumber
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
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
Arguments
154
TESIS PLMware
Restrictions
None
Handler name
T4S-validate-BillOfMaterial
Description
Arguments
Use/placement
Restrictions
None
Handler name
T4S-validate-WBS-BillOfMaterial
Description
Arguments
Use/placement
Restrictions
None
Handler name
T4S-validate-DocumentInfoRecord
Description
155
Use/placement
Restrictions
None
Handler name
T4S-validate-EquipmentMaster
Description
Arguments
Use/placement
Restrictions
None
Handler name
T4S-validate-FunctionalLocation
Description
Arguments
156
TESIS PLMware
Restrictions
None
Handler name
T4S-check-T4SFolderExists
Description
Checks if the T4S folder (in order to manage workflow targets) exists
Arguments
None
Use/placement
Restrictions
None
T4S-transfer-MaterialMaster
Description
Arguments
None
Use/placement
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
157
Restrictions
The SAP logon data must be present and correct. This is best
158
TESIS PLMware
Handler name
T4X-attach-RevisionRule
Description
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
T4X-attach-RevisionRule
-mode=add
-use_rev_rule=MyRevRule
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
Handler name
T4S-transfer-OrderBillOfMaterial
Description
This handler transfers for each configured BOM view type a defined
order bill of materials to SAP.
Arguments
Use/placement
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
Use/placement
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
Arguments
Use/placement
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
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
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
-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
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
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
Use/placement
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
Arguments
None
Use/placement
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
Arguments
None
Use/placement
Restrictions
The SAP logon data must be present and correct. This is best
checked with the "T4S-validate-SAPLogon rule handler.
162
TESIS PLMware
Handler name
T4S-transfer-PIR
Description
Arguments
None
Use/placement
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
Arguments
None
Use/placement
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
163
Teamcenter to SAP
Arguments
-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
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
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
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
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
165
Handler name
T4S-create-Folder
Description
Arguments
None
Use/placement
Restrictions
None
Handler name
T4X-create-T4X-BatchJob
(replacing former T4S-create-T4S-BatchJob)
Description
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
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".
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
167
-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
Restrictions
Handler name
T4S-add-Form2CC
Description
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
Restrictions
Handler name
T4S-transfer-Routing
Description
168
TESIS PLMware
-Target=Routing|InspectionPlan|RefSetOfOperations
Defines the routing target type and the used mapping files (default
value is Routing)
Use/placement
Restrictions
Handler name
T4S-transfer-ProductionOrder
Description
Arguments
None
Use/placement
Restrictions
Handler name
T4S-transfer-CC-BOM
Description
Arguments
None
Use/placement
Restrictions
169
Depending on how you want to use T4S, this may be useful or not
Handler name
EPM-attach-item-revision-targets
Description
Arguments
None
Use/placement
Restrictions
None
Handler name
EPM_attach_related_objects
Description
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
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
171
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
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
::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
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)
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:
173
items_tag:$ItemType:revision_list:$ItemRevisionType
item_revision_id] == } {
set This_is_the_last_Revision
true
}
174
TESIS PLMware
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
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).
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
177
BATCH
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
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
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
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
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
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
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
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:
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
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
183
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:
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:
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
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
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
185
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
Enter the SAP user name into the input field and click run
Include the output string into the line above in the file t4s_mapping_config.sd
TESIS PLMware
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.:
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:
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
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
189
Some, but not all, of these error conditions may be handled in the T4S mapping and
checked with the mapping test scripts.
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
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.
191
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
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
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:
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.
193
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
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
195
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!
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.
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
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.
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.
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
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.
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.
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
198
TESIS PLMware
199
200
TESIS PLMware
Pack Canvas
Changes the size of the drawing panel, so that all objects just fit into it
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
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.
203
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).
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
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.
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"
In addition to "tpwrite" there are two more functions to write to the transaction log file:
205
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
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
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
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
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
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
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
[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
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)
210
TESIS PLMware
puts "nio"
}
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)
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