FN4T-Installation Guide

Download as pdf or txt
Download as pdf or txt
You are on page 1of 102

Opcenter Connect

FN for Teamcenter
-
Installation Guide
Contents

Preface 5

Introduction 1-1

Supported Environment
Active Integration Gateway Compatibility Matrix ───────────────── 2-1
Web Browser ──────────────────────────────────────── 2-1
Operating Systems ──────────────────────────────────── 2-1
Install Hosts and Locations ─────────────────────────────── 2-2
Sizing Considerations ─────────────────────────────────── 2-3

Admin UI
Administrative User Interface ────────────────────────────── 3-1
Admin UI Troubleshooting ──────────────────────────────── 3-4

The Active Integration Gateway (AIG) Architecture 4-1

Installation Instructions
Overview of Installation Steps ───────────────────────────── 5-1
Installation ───────────────────────────────────────── 5-1
Introduction ─────────────────────────────────────────── 5-1
Installation preparations ──────────────────────────────────── 5-2
Configure AIG environment using Deployment Center ────────────────── 5-4
Deploy the AIG installation on target machine ────────────────────── 5-12
Upgrade AIG Installation ──────────────────────────────── 5-13
Necessary actions for a successful upgrade ──────────────────────── 5-13
Upgrade AIG via Deployment Center ──────────────────────────── 5-13
Initializing AIG ────────────────────────────────────── 5-14
Security Considerations ──────────────────────────────────── 5-15
Initialization Prerequisites ────────────────────────────────── 5-16
Initializing the BGS ─────────────────────────────────────── 5-18
Registering the GS ─────────────────────────────────────── 5-19
Running as Windows Service ───────────────────────────────── 5-22
Basic Configuration in the Admin UI ───────────────────────── 5-23
User Management ─────────────────────────────────────── 5-24
Setting the License Server ────────────────────────────────── 5-25
Changing Ports ───────────────────────────────────────── 5-26
Setting the BGS Server ──────────────────────────────────── 5-27
Verifying the Installation ─────────────────────────────────── 5-29
Teamcenter Templates ───────────────────────────────── 5-29
Compatibility with other Templates ──────────────────────────── 5-30

Installation Guide 2
© 2019 Siemens
Contents

Deploy Active Integration Templates with Deployment Center ────────────5-30


Deploy AIG Template with TEM ─────────────────────────────── 5-31
Configuring the Mapping ──────────────────────────────── 5-33
Configure Teamcenter Environment for AIG ──────────────────── 5-35
Set AIG GS Environment for a Teamcenter 2-Tier Environment ──────────── 5-35
Set AIG GS Environment for a Teamcenter 4-Tier Environment ──────────── 5-35
Add AIG Error Message Texts to Teamcenter ─────────────────────── 5-36
Connectivity to Teamcenter ───────────────────────────────── 5-36
Configure AIG Environment for Teamcenter ──────────────────── 5-37
Installation of additional components ─────────────────────── 5-37
Install a JDBC Driver to connect to a database ────────────────────── 5-37

Opcenter Connectivity
Introduction ───────────────────────────────────────── 6-1
Opcenter EX DS connection configuration ────────────────────── 6-1
Install Certificate ────────────────────────────────────── 6-4
Test Opcenter Connection ──────────────────────────────── 6-5
Deployment Options ─────────────────────────────────── 6-6
Addressing Multiple Opcenter Servers ──────────────────────── 6-8

Configure AIG for TLS/SSL


Certificates ───────────────────────────────────────── 7-1
Server Authentication ────────────────────────────────── 7-4
Configuring Server Authentication for the BGS ─────────────────────── 7-4
Configuring Server Authentication for the GS ─────────────────────── 7-5
Testing and Troubleshooting Server Authentication ──────────────────── 7-6
Client Authentication ─────────────────────────────────── 7-6
Configuring Client Authentication for the BGS ─────────────────────── 7-6
Configuring Client Authentication for the GS ──────────────────────── 7-7
Testing and Troubleshooting Client Authentication ──────────────────── 7-7
Encrypted Logging ──────────────────────────────────── 7-8
Configuring Symmetric Encryption for Logging ────────────────────── 7-8
Configuring Logging via HTTP using TLS ────────────────────────── 7-10
Troubleshooting ───────────────────────────────────── 7-11

Job Server Installation


Job Server Configuration ───────────────────────────────── 8-1
Job Agent Configuration ───────────────────────────────── 8-2
Set up Teamcenter Multi Connect for AIG Jobs ─────────────────── 8-5

Troubleshooting the AIG Process Start 9-1

Use Nagios to monitor AIG


Nagios Introduction ─────────────────────────────────── 10-1
Base Server Module ─────────────────────────────────── 10-1

Installation Guide 3
© 2019 Siemens
Log Server Module ──────────────────────────────────── 10-2
Job Server Module ──────────────────────────────────── 10-3
Job Agent Module ──────────────────────────────────── 10-3

Glossary A-1

4 Installation Guide
© 2019 Siemens
Preface
This documentation cannot be used as a substitute for consulting advice, because it can never consider
the individual business processes and configuration. Despite our best efforts it is probable that some
information about functionality and coherence may be incomplete.

Issue: December 2019

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 Opcenter Connect FN for Teamcenter 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.

© 2018-2019 Siemens Product Lifecycle Management Software Inc.

Trademark notice:

Siemens, the Siemens logo and Opcenter are registered trademarks of Siemens AG.

Camstar and Teamcenter are trademarks or registered trademarks of Siemens Product Lifecycle
Management Software Inc. or its subsidiaries in the United States and in other countries.

Oracle is a registered trademark of Oracle Corporation.

SAP, R/3, SAP S/4HANA®, SAP Business Suite® and mySAP are trademarks or registered trademarks of SAP
or its affiliates in Germany and other countries.

TESIS is a registered trademark of TESIS GmbH.

All other trademarks, registered trademarks or service marks belong to their respective holders.

Installation Guide 5
© 2019 Siemens
6 Installation Guide
© 2019 Siemens
1. Introduction
This manual explains the installation of the Active Integration Gateway (AIG) software in version 19.2.

The term AIG stands for the entire Active Integration Gateway product family including:

T4S Teamcenter Gateway for SAP Business Suite


T4O Teamcenter Gateway for Oracle EBS
T4EA Teamcenter Gateway for Enterprise Applications
T4S4 Teamcenter Gateway for SAP S/4HANA
T4CEP Teamcenter Gateway for Camstar Enterprise Platform
TCRA4S Teamcenter Reporting and Analytics Gateway for SAP S/4HANA
FN4T Opcenter Connect FN for Teamcenter
TCPCM4S Teamcenter Product Cost Management Gateway for SAP S/4HANA
FN4S Opcenter Connect FN for SAP S/4HANA

Caution:
As this document describes the generic installation of the Active Integration Gateway (AIG)
software, these products are further referenced as AIG.

The Active Integration Gateway (AIG) software solution is a general-purpose integration software that
provides data and process integration between Teamcenter® by Siemens PLM Software and SAP
Business Suite® and SAP S/4HANA®, Oracle E-Business Suite by Oracle Corporation, Camstar Enterprise
Platform, Teamcenter Reporting and Analytics, Opcenter Execution Discrete and/or any other Enterprise
Application, respectively.

For more details about general AIG, please refer to other AIG documentation.

For more information about new components and new versions of AIG, please visit

http://www.plm.automation.siemens.com/en_us/products/active-integration/index.shtml

Installation Guide 1-1


© 2019 Siemens
1. Introduction

1-2 Installation Guide


© 2019 Siemens
2. Supported Environment
2.1 Active Integration Gateway Compatibility Matrix
For detailed information on the compatibility of Active Integration Gateway products with operating
systems, Teamcenter, Teamcenter Product Cost Management, Active Workspace, SAP Business Suite®,
SAP S/4HANA®, Oracle EBS, Camstar and Opcenter Execution Foundation Gateway for Teamcenter
please visit Active Integration Software Certifications.

2.2 Web Browser


For administrative AIG tasks and configuring AIG software, an Admin UI is provided for AIG BGS and GS.
In order to use it, you need an up-to-date web browser. Please refer to the Teamcenter Certifications
for the current "in maintenance Teamcenter versions" to see which browsers and versions are
supported.

Caution:
• Using other web browsers than the ones certified is not recommended.

• There is no guarantee that older versions than the ones certified will work correctly with AIG
Admin UI.

• Newer versions of the certified browsers are supported based on the respective vendors' claims
of compatibility.

• If any problems occur, please refer to Admin UI Troubleshooting of this installation guide.

2.3 Operating Systems


For detailed information about the certified version of operating systems, please refer to Active
Integration Software Certifications and click on Active Integration Compatibility Matrix.

Installation Guide 2-1


© 2019 Siemens
2. Supported Environment

Caution:
Linux only: On every machine running AIG (both BGS and GS) make sure that the operating
system has the "allowed number of open files" greater than 2048. We recommend the number
4096. Please consult the operating system documentation for how to check and configure that.
Windows only: Microsoft Visual C++ Redistributable Packages are required for Active Integration
Gateway (both BGS and GS) on any Windows system. The requirement of the patches depends on
the Operating System and the Teamcenter version in use. In principle, for AIG 19.2 the following
packages are required:

• Microsoft Visual C++ 2012 Redistributable Package: https://www.microsoft.com/en-us/


download/details.aspx?id=30679

• Microsoft Visual C++ 2015 Redistributable Package: https://www.microsoft.com/en-us/


download/details.aspx?id=53840

If Microsoft Visual C++ Redistributable Packages are not installed correctly, AIG BGS or GS cannot
be started properly. An error message will pop-up to mention it.

2.4 Install Hosts and Locations


AIG BGS and GS need to be installed on separate servers, as there may be many transactions at the same
time in a production environment, which could cause problems because of excessive CPU and RAM
demands. For best performance, install the AIG BGS on the host that is supposed to store log files. If not
specified, the log files are stored in <BGS_ROOT>/var/log.

AIG GS (Gateway Service) needs to run on the same host(s) as the Teamcenter server:

• in a Teamcenter 2-Tier environment, AIG GS should be installed on every Teamcenter client machine,
because a Teamcenter client is also a Teamcenter server in the 2-Tier environment.

• in a Teamcenter 4-tier environment: AIG GS should be installed on every Teamcenter pool manager
host.

AIG requires every host of a BGS or GS to have a specific password manager installed. For details see
Initialization Prerequisites

2-2 Installation Guide


© 2019 Siemens
Sizing Considerations

For more information about AIG BGS and GS, please refer to The Active Integration Gateway (AIG)
Architecture.

Caution:
• Do not use shared drives (NFS, SMB/CIFS…) for AIG installations, log file storage or job file
storage. Please use local disk and direct attached Storage, iSCSI, Fibre Channel or an equivalent
technology.

• If you use a firewall, you need an open TCP and UDP port for the AIG services.

• In case you are using a firewall with a content filter, please note that AIG operates two different
protocols on the same TCP/UDP port (HTTP and TPRPC). TPRPC is a AIG native TCP protocol.

2.5 Sizing Considerations


Minimum CPU and memory requirements

Minimum CPU recommendation:

Operating System CPU Type Number of CPUs


Windows Intel/AMD 32/64 bit 2
Linux Intel/AMD 64 bit 2

Minimum memory recommendation (free process memory):

GS in 4-Tier GS in 2-Tier
Operating System BGS Environment Environment
Windows 16 GB 8 GB 8 GB
Linux 16 GB 8 GB 8 GB

Job pool memory and storage size

AIG jobs have a representation in the main memory as well as on the disk. The default Job Pool size is
100,000 jobs; maximum 4,000,000. A Job Pool needs a minimum of 32 GB and can grow up to 64 GB
disk memory.

Calculate log file storage size

Each GS and BGS (without Job Pool and log storage) typically requires a minimum of 2 GB on the file
system. After installation, the GS (2-tier and 4-tier) does not write large files to the file system, while the
BGS stores jobs and log files. The following table shows a recommendation of disk space for the BGS log
storage depending on the number of Teamcenter users, assuming that log compression is on.

Installation Guide 2-3


© 2019 Siemens
2. Supported Environment

Number of Teamcenter users Minimum disk space for the log storage
< 50 100 GB
50 - 500 500 GB
> 500 1 TB or more

AIG compresses log files that have not been accessed for a certain time to save storage capacity. By
default, log files that have not been accessed for two days will be compressed.

You can modify this threshold by adapting the BGS Admin UI → Configuration → Log server →
Advanced Settings tab → Compression setting. For more information about the AIG Admin UI, please
refer to Admin UI. In rare cases, it could happen that the original log file is somehow blocked (e.g.,
because someone accessed it right in that moment), so that the compression cannot be successfully
finished. Then you might see an error log line similar to this one, "tpco_udpCompressLogChannel ::
cannot delete original log file ...", but your log files will work as usual.

2-4 Installation Guide


© 2019 Siemens
3. Admin UI
3.1 Administrative User Interface
The Active Integration Gateway Administrative User Interface (Admin UI) is an application that allows
performing administrative tasks with regard to AIG.

This documentation will give you basic information about the Admin UI and how to reach it. Detailed
information on the single applications contained in it can be found in the according online help of the
Admin UI.

Menu Functionalities Overview

Both the BGS and the GS have their own interface with common and unique functionalities.

Common menu entries are:

• Monitoring: View current statistics of the system and monitor AIG activity.

• Scripts: Execute AIG test scripts. E.g., to check mappings (GS only) or encrypt passwords (BGS only).

• Diagnosis: Download of a stacktrace for our software support.

• System information: View the persistent data of the system.

• Configuration: Display and edit the configuration of AIG. The configuration options and functionalities
are different for BGS and GS.

• Restart: Restart of the application (recommended way is to use the executable bin64/restart).

• About: View service, credits and copyright. About → Service displays the basic information about the
installed BGS/GS.

Installation Guide 3-1


© 2019 Siemens
3. Admin UI

BGS exclusive menu entries are:

• Job management: Control jobs and job agents.

• Log files: View and analyze transaction, system, session and user log files.

Connection and Access to the Admin UI

To access the BGS or GS Admin UI follow these steps:

• Be sure the BGS or GS is installed and configured correctly. Please see Installation Instructions.

• Be sure the BGS or GS is running. If not, start it with <AIG_ROOT>/bin64/restart or start the according
service.

• The Admin UI is available by entering and loading the following URL in your web browser:
The BGS Admin UI can be reached by default by https://<URL of BGS>:11320
The GS Admin UI can be reached by default by https://<URL of GS>:11321

• The very first login to the Admin UI has to be made with the default Username "t4adm" and the
Password you set during the initialization using the <BGS_ROOT>/bin64/initpassword executable. For
more information on the initialization, please refer to TODO. Afterwards the t4adm user can add
additional user accounts in the BGS Admin UI.
For further information on user management, roles and rights please see the Admin UI Online Help
(see below).

3-2 Installation Guide


© 2019 Siemens
Administrative User Interface

Caution:
The port number to reach the Admin UI and whether to use HTTP or HTTPS can be changed. This is
described in the chapter Basic Configuration in the Admin UI.

For troubleshooting and web browser compatibility please refer to Admin UI Troubleshooting and Web
Browser of this installation guide.

Admin UI Online Help

The Admin UI has built-in online help, which can be accessed in two different ways. You can open it
directly without an running and installed server by opening the file in <AIG_ROOT>/var/httpd/aui20/
Teamcenter-Gateway-AdminUI.html or by clicking on the question mark (?) in the upper right corner of
the Admin UI:

By default it will show the help content that applies to the opened menu point. The help can be opened
in a separate window, by click on the symbol.

Installation Guide 3-3


© 2019 Siemens
3. Admin UI

3.2 Admin UI Troubleshooting


If anything seems strange with the AIG Admin UI (or behaving differently from the description here), try
the following:

• Be sure to use a web browser that is supported by your AIG version. For more information about
supported web browser, please refer to Web Browser.

• Activate Java Script for full AIG functionality

• Delete the web browser cache and cookies

• Restart the web browser after the cleaning

If you use Internet Explorer and the Admin UI web page stays blank, please check the document mode
settings of your browser:

• Open the Admin UI web page in your Internet Explorer

• Open Settings → F12 Developer Tools or press F12

• Set the document mode to Edge in the upper right corner of the tools

• The UI login screen should now appear and you can close the developer tools

Usually this behavior is caused by the so called Compatibility View of the Internet Explorer. It can also be
disabled for all pages following these steps:

• Open the Tools → Compatibility View Settings of your Internet Explorer

• Remove the check mark next to Display intranet sites in Compatibility View

• Close the dialog

3-4 Installation Guide


© 2019 Siemens
4. The Active Integration Gateway (AIG)
Architecture
AIG is the integration software to enable bidirectional data integration and process coupling between
Teamcenter and Opcenter Execution Discrete.

AIG consists of two services:

• BGS: AIG Basic Gateway Service is responsible for the licensing and logging. This central service has to
be installed at least once per site and does not need any target system (e.g., SAP, Oracle EBS, ...) or
Teamcenter environment (except possibly for job execution, depending on the configuration).
The AIG Job Server is a part of the AIG BGS that manages transactions - that may be large and
numerous - in the background in order to not keep the Teamcenter user blocked while processing the
data. To install and configure AIG Job Server, please refer to Job Server Installation.
Each AIG process writes logs and debug messages to this central BGS using the UDP/IP protocol. The
AIG log server is a part of the BGS which writes these messages into log files and stores them in the
log server’s file system. Depending on the configuration, the "log cleaner" clears the log files and
directories (roll files over, delete files…). The log files can be viewed with the AIG Admin UI from
anywhere in the network.

Caution:
Any log information is sent via the UDP protocol. If a network connection is down, no AIG
process will be blocked but the sender will not be informed if a log data package is lost.
Definitely logging information will be lost if clients cannot connect to the BGS.

• GS: AIG Gateway Service drives the process mapping. It contains the complete AIG software (includes
all AIG servers, but not the BGS). Several AIG instances can be installed using this package in the
network and they all can use the same AIG BGS. It manages the connection to target enterprise
applications, operates the mapping, etc. Therefore it needs a configured target system (e.g., SAP,
Oracle EBS, ...) and Teamcenter environment. This package contains the client software as well as the
programmable TCL code (mapping) that manages the transfers/imports. Large and numerous
transactions can be executed asynchronously in the background using the Job Server (BGS) and job
agents (GS).

Installation Guide 4-1


© 2019 Siemens
4. The Active Integration Gateway (AIG) Architecture

4-2 Installation Guide


© 2019 Siemens
5. Installation Instructions
5.1 Overview of Installation Steps
To install Active Integration Gateway and get it started properly the following steps are required:

1. Install Active Integration Gateway using Deployment Center.


AIG has to be downloaded and prepared in the software repository, before you can configure its
installation using Deployment Center. In the end the installation has to be deployed to the target
machine and the templates and plugins need to be deployed in Teamcenter.

2. Before starting AIG some prerequisites have to be fulfilled and some considerations should be done
for the sake of security. This manual guides you through the initialization of BGS and GS step by
step.

3. When the software is ready to run some basic configuration in the Admin UI is required to get AIG
started properly.

4. Install the templates and plugins to Teamcenter using tem, if this has not been done yet using
Deployment Center.

5. Configure the Teamcenter environment in AIG.

6. Configure the Enterprise Application for AIG

5.2 Installation

5.2.1 Introduction

The Active Integration Gateway installation is being managed by Deployment Center, a centralized web
application for the deployment of software to a set of target machines. With Deployment Center you can
create an installation of the AIG products, as well as extend an already existing installation by one or
more other products.

Installation Guide 5-1


© 2019 Siemens
5. Installation Instructions

Caution:
This document's purpose is to guide you through an installation of AIG products via Deployment
Center. It is highly recommended to make yourself familiar with the Deployment Center
documentation, as it will provide you with a better understanding of its functions and concepts.
If you want to install the AIG Teamcenter plugins and templates, it is advised to have a
preconfigured environment already containing your Teamcenter installation (which was installed
via the Deployment Center). If you want to install them in a Teamcenter not registered in an
environment, or a Teamcenter that has been registered after its installation, we recommend using
the Teamcenter Environment Manager (TEM).
For upgrade scenarios from an old AIG version to AIG 19.2, please refer to Active Integration -
Migration Guide for migrating AIG mapping, preferences and workflows.
With version 19.2, we prohibit the installation of the Active Integration Gateway Services in an
environment containing a Teamcenter installation. While it will still be possible to select the Active
Integration Gateway Services' software packages and configure the respective components, the
deployment script will fail at the beginning of the procedure, leaving you with a Teamcenter
environment with no further possibility to make changes. You would have to delete the
environment and reregister the Teamcenter installation into the Deployment Center.

Acquire the AIG installation packages

The released Active Integration Gateway (AIG) installation packages are uploaded in GTAC and are
available to all customers to download. Before installing AIG, please acquire the AIG installation
packages according to your operating system(s) and Teamcenter version(s). AIG installation packages
are located in folder Teamcenter and Teamcenter Rapid Start → Full Products → Integrations and
Solutions in GTAC. The AIG installation packages are distributed as zip files.

5.2.2 Installation preparations

The extracted AIG installation packages need to be placed in the Deployment Center repository. We
recommend extracting the package in a safe location before copying it into the repository (e.g.
<DC_Root>/repo/software). If you want to make installations on multiple operating systems, place the
respective AIG installation packages next to each other into the repository.

5-2 Installation Guide


© 2019 Siemens
Installation preparations

You can verify the successful registration of the software in the Deployment Center by checking its
Software Repository. An exemplary Software Repository containing the AIG products looks like this:

External libraries

With Deployment Center, we offer the possibility to have the external libraries required for some
products distributed with your installation. If you want to use this feature, please place the files in the
packages’ directory for this purpose: …/Active_Integration_Gateway_19.2_<TC_Version>_<OS>/AIG/
artifacts/AIG_extensions

The currently supported external libraries are:

• For JDBC drivers add the corresponding jar file, e.g., ojcdbcJava<Version_Number>.jar.
For more information please refer to the following chapter Install a JDBC Driver to connect to a
database

Installation Guide 5-3


© 2019 Siemens
5. Installation Instructions

Note:
These files can also be copied to the installation manually after the deployment of AIG. For
detailed instructions see the chapter "Installation of additional components".

Edit the deployer.properties

For a clean installation experience, edit the file <DC_Root>/repo/system/deployer/deployer.properties.


There, you need to add GS_Comp,BGS_Comp and GS_4TIER_Comp to the property
COMPONENTS_TO_SKIP_INTEROPERABILITY_FOR.

5.2.3 Configure AIG environment using Deployment Center

Once the AIG installation package has been registered by the Deployment Center's Repository Service,
you can start configurating your desired installation in the Deployment Center web interface in the
Environments section.

• Select AIG Software package


For the installation of the Active Integration Gateway Services, you need to create a new
environment. For this, add the Active Integration Gateway - Active Integration Gateway Services
for <TC_version> software package to your newly created Environments list of selected software.

5-4 Installation Guide


© 2019 Siemens
Configure AIG environment using Deployment Center

• Select the environment option


Deployment Center provides two different modes for your installation - either a single box or a
distributed installation.
Single Box installation: The selected software is being installed on a single machine, which may work
in testing environments. This mode is not allowed for a productive environment, as our GS and BGS
instances need to be installed on separate machines!
Distributed installation: You can specify different machines as targets for different software
(components). Use this option by default for productive environments to install BGS and GS on
separate machines.

Installation Guide 5-5


© 2019 Siemens
5. Installation Instructions

• Choose your applications


In the Applications section of the Deployment Center you can select the product(s) for your
installation, as well as the distribution of the external libraries. The Active Integration Gateway
services are subdivided into three groups: The Teamcenter Gateway Products, designed for
Teamcenter environments, the Closed Loop Manufacturing Products, which are part of the "golden
triangle" architecture, and the external libraries for Active Integration products.
Choose the product(s) for your installation from the list of available applications and add them to your
list of selected applications.

5-6 Installation Guide


© 2019 Siemens
Configure AIG environment using Deployment Center

• Configure the AIG components


The Components section is where you define the configurations for the different AIG products'
components: The Gateway Service (GS), the Basic Gateway Service (BGS) and, if selected in the
Applications section, the 4Tier Gateway Service Client. While the amount of BGS instances in your
environment is limited to one, you can install as many instances of the GS as well as 4Tier Gateway
Service Clients as needed, by clicking on the + symbol, choosing them from the Available
Components and updating the Selected Components. If you want to install multiple GS instances,
you must configure different host machines, as you cannot specify different installation paths
elsewise.

Installation Guide 5-7


© 2019 Siemens
5. Installation Instructions

Configure Gateway Service component

For the Gateway Service (GS) you need to specify the machine name, its OS, the installation path as well
as the port numbers, which need to differ from each other. Clicking the eye icon in the top right corner
makes additional port numbers for specific AIG products visible.

5-8 Installation Guide


© 2019 Siemens
Configure AIG environment using Deployment Center

Installation Guide 5-9


© 2019 Siemens
5. Installation Instructions

ConfigureBasic Gateway Service component

For the Basic Gateway Service (BGS) you need to specify the machine name, its OS, the installation path,
the port numbers, which need to differ from each other, as well as the license server with its port
number.

4Tier Gateway Service component

For the 4Tier Gateway Service Client you need to specify the machine name, its OS, the installation path,
the BGS host, as well as the port numbers, which need to differ from each other.

5-10 Installation Guide


© 2019 Siemens
Configure AIG environment using Deployment Center

Generate the deploy script

Once you have configured the components for your installation, go to the Deploy section of
Deployment Center and click on Generate Install Scripts. Deployment Center creates the deployment
scripts, as well as installation instructions for them.

Installation Guide 5-11


© 2019 Siemens
5. Installation Instructions

5.2.4 Deploy the AIG installation on target machine

In order to execute the deployment, you need to have your Deployment Center repository configured as
share, or at least a location containing all packages needed for the installation. This share needs to be
mounted on the target machine.

The deployment script is generated as zip file(s) and can be found in the <DC_Root>/repo/deploy_scripts/
<Your_Environment>/install/<Date>_<Timestamp>/ directory. It needs to be copied to your target
machine where it has to be extracted.

To execute, start the contained deploy.bat/.sh with following parameters: -dcusername, -


dcpassword and -softwareLocation.

The -softwareLocation parameter needs to point at the <DC_Root>/repo directory (in case the
Deployment Center repository is mounted). If you are using an alternative location as package storage,
we recommend emulating the Deployment Centers file structure (i.e., …/repo/software/<packages>).

If the target machine's operating system is Windows and the share containing the software packages is
mounted under the drive letter M:\, you do not need to specify the software location.

5-12 Installation Guide


© 2019 Siemens
Necessary actions for a successful upgrade

Caution:
• Before the deployment script is executed, make sure the JRE_HOME environment variable is set
on the target machine. If you are installing in an environment also containing Teamcenter, also
specify the JAVA_HOME environment variable. Your Deployment Center host must be reachable
over the network.

• If you are installing on Linux, make sure the destination directory for your installation belongs
to the user executing the script.

5.3 Upgrade AIG Installation

5.3.1 Necessary actions for a successful upgrade

The upgrade requires an edited deployer.properties as described in chapter Installation preparations.

Before placing the AIG 19.2 software package into the Deployment Centers repository, you need to copy
the *DCC.xml files under …/Active_Integration_Gateway_19.2_<TC_Version>_<OS>/ AIG/
dc_contributions/deployablecomponents/ over the ones in the 19.1 software package in your repository.

Caution:
If this is not done, your old configuration of the installation path will be overwritten with a default
value, the upgrade process will not be able to create a deploy script for AIG 19.2 and the
environment will be corrupted.

5.3.2 Upgrade AIG via Deployment Center

For the upgrade of FN4T, you need to select the respective environment in the Deployment Center, click
on the + symbol right next to the list of installed software packages, select the Active Integration
Gateway Services for <TC_Version> 19.2.0.<TC_Version> software package and click on Update
Selected Software.

Installation Guide 5-13


© 2019 Siemens
5. Installation Instructions

After this, you can go directly to the deploy section, generate the installation script and execute it on the
target machine, as described in the chapters Configure AIG environment using Deployment Center
and Deploy the AIG installation on target machine. We recommend verifying whether your
configuration of the old installation has been maintained in the components section.

5.4 Initializing AIG


Some prerequisistes have to be fulfilled and security considerations to be made before starting AIG for
the first time. Therefore, make sure you have read this chapter very carefully and followed these steps to
initialize your Active Integration Gateway installation.

Security Considerations

Initialization Prerequisites

Initializing the BGS

Registering the GS

Running as Windows Service

5-14 Installation Guide


© 2019 Siemens
Security Considerations

5.4.1 Security Considerations

We are continuously improving our software to make sure the sensitive information managed by the
Active Integration Gateway is safe. This chapter gives an overview of the measures implemented, where
the data is stored and who can access it. The following chapters guide you through the initialization of
AIG with the various options, obstacles and considerations to be aware of. These instructions are limited
to AIG and do not comprise securing and updating the environment, protecting the communication or
restricting the access according to the principle of least privilege.

The BGS contains a single encrypted database storing all sensitive data like user passwords, registered
GSs and credentials of technical users to EA systems centrally. To encrypt the database an encryption
key has to be defined, which is the initial password specified using the initpassword executable. During
this process, detailed in Initializing the BGS, the database is created, encrypted, the user data for
"t4adm" added and the encryption key is stored in the OS password manager.

The OS password manager is a dedicated password manager software maintaining secrets in the
operating system. Since the database encryption key is required to access the database with each BGS
start, it has to be stored outside of AIG in this OS password manager. As a consequence the OS password
manager has to be available and initialized for AIG to work. For security reasons such password
managers are bound to the logged in OS user, so that it is absolutely necessary and important to
operate AIG with the same user at any time. These prerequisites are detailed in Initialization
Prerequisites. If you are using Windows and want to run BGS/GS as a Windows service also read the
chapter Running as Windows Service very carefully.

To avoid the intrusion by a compromised GS in the network, the installed GSs have to be registered and
approved before an authenticated communicating with the BGS can take place. Therefore, each BGS/GS
has a so-called UUID (Universally Unique Identifier) which identifies the installation in different contexts
and also serves as a "username" for the machine to machine authentication. Each GS has to be "granted
access" by an administrator in the BGS Admin UI, afterwards it can fetch its token, i.e. a generated
"password", from the BGS and store it locally in the OS password manager. From that point on the UUID
and token can be used to authenticate any calls against BGS/GS. For more details, please refer to
Registering the GS.

The picture below exemplifies the verification of credentials centrally in the BGS. Assuming the
initialization has been completed successfully, imagine a call from BGS to GS should be made to retrieve
any data. First, the GS fetches the token stored for its UUID from the OS password manager. Afterwards,
the call to the BGS is made, authenticating with the UUID as username and the token as password. The
BGS verifies the given credentials against the data stored in the encrypted database. It checks if the GS is
known, if it has not been blocked or deleted by an administrator yet and whether the given token
matches. In case of success, the BGS will send the response to the request. The verification of AIG users
works the same way. For example, when a user tries to login to the GS Admin UI, the given credentials
(username, password) are forwarded to the BGS where the verification takes place. Only if the BGS can
be reached and verifies the credentials successfully, access to the GS Admin UI is given.

Installation Guide 5-15


© 2019 Siemens
5. Installation Instructions

As a consequence of all these dependencies, the BGS and GS immediately abort their start and write
emergency log files if some prerequisites are not fulfilled. Each of the following chapters will provide a
short troubleshooting section for the most common problems.

5.4.2 Initialization Prerequisites

AIG requires a platform-specific OS password manager to be available and initialized. On Windows


platforms the Credential Manager available on all supported versions is assumed. For Linux the
standard but not out of the box installed software pass is required. The installation and configuration of
pass is a bit tricky and assumes that GnuPG (gpg) is installed and configured for the operating user, so
that the password store can be initialized with a proper GPG key.

In a host with an installed BGS the OS password manager contains the encryption key for the database
and the token of the BGS itself. On a GS host only the token of the GS is contained. For more
information on the token handling see Registering the GS. Be aware, that such managers are bound to
the logged in OS user for security reasons, i.e., credentials stored by one user cannot be read by any
other user account. Hence, you cannot change the OS user operating AIG and need to use the correct
user from the beginning on.

5-16 Installation Guide


© 2019 Siemens
Initialization Prerequisites

Caution:
• The logged in OS user initializing BGS and GS must be the user operating AIG in the future

• In a 4-tier environment the GS and the poolmanager do not only have to be installed on the
same host, but also executed by the same user.

• Deleting or editing the <AIG_ROOT>/var/conf/uuid file leads to BGS/GS not being able to access
the information stored in there. A BGS can no longer access the database and the GS can no
longer authenticate any calls.

Prerequisites for Windows

The Credential Manager is available on all supported versions and usually does not require any further
initialization. Before proceeding consider which OS user account will be used to operate the software.
Especially when running as Windows service some additional considerations have to take place. Refer to
Running as Windows Service in that case.

Note:
There seems to be a limit of roundabout 900 entries in the Windows Credential Manager. A single
installation of BGS/GS will only need two entries. If you are already using the manager excessively,
this could lead to problems.

Prerequisites for Linux

Download and install pass (see https://www.passwordstore.org/) and GnuPG (gpg2) (see https://
gnupg.org) if needed. Pass requires GPG key for the initialization, which can be generated using the
gpg2 --gen-key command. For more information, refer to the"OpenPGP Key Management" section of
the GnuPG manual. When initializing pass you have to assign the GPG key to be used. For more
information see pass init <gpg-id> command in the man pages.

Note:
Usually the GPG key is secured by a passphrase, which is cached for a dedicated time and also
cleaned after a restart of the host. When expired the passphrase has to be entered in an
interactive screen. As a consequence AIG cannot start until someone enters the passphrase
interactively.

Troubleshooting

The OS password manager is accessed on every start and in between. If the manager cannot be
accessed during the start or does not contain the correct data, the BGS and GS shutdown immediately.
In that case check the file <AIG_ROOT>/tmp/bootstrap_errors.log for hints.

::Bootstrapping::SecureStorageSanityCheck: Accessing secure storage failed

Installation Guide 5-17


© 2019 Siemens
5. Installation Instructions

AIG could not access pass to read or write credentials. Either pass is not installed, not initialized or the
interactive passphrase is no longer cached and needs to be entered manually first.

Check by storing and reading a test value in/from pass from command line with pass insert test,
entering any password twice and pass test to read the value again.

• If the passphrase for the GPG key is no longer in the cache you will be asked for it. Afterwards AIG
works as expected.

• An error message gpg: decryption failed: No secret key means that the GPG key pass
has been initialized with cannot be found and may have been deleted.

• An error message Error: You must run: pass init your-gpg-id before you may use
the password store. indicates that pass has not been initialized yet.

5.4.3 Initializing the BGS

Proceed with the initialization of the BGS, when all prerequisites listed in Initialization Prerequisites are
fulfilled. Remember to start the BGS with the correct OS user, i.e., the user operating the BGS in the
future, see Security Considerations.

The initpassword executable is a lightweight and secure server (by default running at
127.0.0.1:11399) holding the initial password temporarily in memory until it has been fetched and
successfully stored by the dedicated BGS. Especially the secure passing of the password from the
interactive account of an AIG administrator to the non-interactive service log on in Windows can be
established with it. The password entered in initpassword is also used as the initial password for the out
of the box administrative user "t4adm". Changing the password of "t4adm" later, does not affect the
password the database has been encrypted with. Therefore, make sure that you remember or save your
password somewhere securely. For best practices regarding the user management see User
Management.

Caution:
The loss of the password entered in initpassword, i.e., the database encryption key leads to a loss
of all data stored in the secure database!
Similarly, the deletion of the UUID in the BGS, effects that the BGS can no longer find the
password in the OS password manager, also leading to a loss of all data.

Initialization steps

Start <BGS_ROOT>/bin64/initpassword as interactive user and enter the password to encrypt the secure
database. When the initpassword server is up, the BGS has to be started within 60 seconds to fetch the
password from it. If successful, initpassword shuts down, while the BGS keeps running.

5-18 Installation Guide


© 2019 Siemens
Registering the GS

Review the help of the initpassword executable (initpassword --help) if you need to change the
IP stack or port or if you want to extend the timeout. The executable can also be run with command line
parameters, e.g., ./bin64/initpassword -port 11400 -timeout 120.

When running the BGS as Windows service, make sure that you never start the BGS interactively, but
start the according service to fetch the password. For more information see Running as Windows
Service.

Troubleshooting

In case of any errors check the separate log files <BGS_ROOT>/tmp/bootstrap_errors.log and
<BGS_ROOT>/tmp/initpassword.log for error messages. The first log file is written by the BGS and
contains, e.g., fetchInitialT4admPassword: fetching initial password failed:
could not fetch password: Failed to connect to localhost port 11399:
Connection refused if it could not reach the initpassword server. Check if the server is running
when the BGS is started and if the host and port are valid for your network settings. Otherwise overwrite
those settings with your own parameters (see above).

The second log file is written by the initpassword server. The following error messages can be
encountered:

• Timeout reached without fetching the password


The password has not been fetched by the BGS within the time limit. Check if you have started the
BGS of the same installation within the time limit and make sure the BGS has not been initialized yet.
Adapt the host and port settings if needed (see above). Especially on Linux, view the
bootstrap_errors.log log file to detect errors with the OS password manager, see Initialization
Prerequisites.

• Wrong uuid: 'd73a9d91-5eed-46c4-bc95-164e26290b6c' @ 127.0.0.1:54176


A BGS with the shown UUID tried to fetch the password, but has the wrong UUID, i.e., is not the BGS
belonging to this installation. Make sure you are using initpassword and BGS of the same installation.

5.4.4 Registering the GS

All calls sent and received by AIG are authenticated. The machine to machine authentication (e.g. from
GS to BGS) uses the UUID of the installation and a token used as password. Therefore, each installation
stores such a token in the OS password manager. Each GS has to be approved in the BGS Admin UI,
before it receives a token and keeps running. As a consequence of this strict requirement a GS which
cannot reach the BGS, has not been approved by it, is blocked or does not provide the correct credentials
aborts its start.

The BGS also needs its own UUID and a token generated and stored in the OS password manager, e.g.,
to run scripts with authenticated calls in the BGS installation. This does not require any manual steps,
but is done during the very first successful start after initialization. Note, that the BGS entry itself is not
displayed in the list of Gateway Services in the BGS Admin UI.

Installation Guide 5-19


© 2019 Siemens
5. Installation Instructions

Manual approval steps

It is assumed that the BGS has been initialized successfully and is running. Otherwise, return to chapter
Initializing the BGS before proceeding.

Start the GS once with the OS user who is operating the GS later on. The GS will abort its start
immediately. Login as administrator to the BGS Admin UI and open Configuration → Gateway
services. The table lists all GS that have communicated with the BGS so far. For details on the attributes
shown and the buttons available refer to the Admin UI help. Search for the GS that has been started
before, verify the shown data carefully. If you are sure that this is the GS you would like to grant access,
select it and click the Approve button. A token (password) for this GS is generated and temporarily held
in the database until it is fetched, therefore the status of the GS is "waiting for acknowledgement" until
it can be guaranteed that the token has been stored successfully.

Now start the GS a second time. The GS will ask the BGS once again for a token, now receiving and
storing it locally in its OS password manager. From now on the GS can communicate with the BGS and
uses its UUID and the stored token to authenticate. A GS already posessing a token will never request a
token from the BGS again.

Automatic registration

Since it can become cumbersome to manually approve lots of clients a second method for registration is
provided which is more comfortable, but sacrifices some security. In an automatically set up installation
an automatic registration token can be used to skip the manual approval. A token for automatic
registration is copied to the specific hosts and used as a kind of "ticket" during the initialization to be
automatically approved and retrieve the generated token (password) directly.

Login to the BGS Admin UI as administrator and open Configuration → General → Advanced settings.
In the section Automatic registration you can generate, view, overwrite or delete this token. Generate,
copy and distribute it securely to the GS hosts which should register automatically. Set the environment
variable TP_AUTO_REGISTER_TOKEN to the copied token value and make sure this variable can
accessed when starting the GS again. When the GS is started it registers at the BGS with this automatic
registration token, where it is automatically approved, a token for this single GS generated and returned.

If the automatic registration token is overwritten or deleted in the BGS any GS trying to register with it
will fail. All GSs which have already been registered successfully are not affected by this change. Hence,
when the automatic registration token is accidentally leaked simply generate and use a new one from
now on, when you have made sure that no compromised GS has registered.

Registration in the context of Teamcenter

The AIG libraries loaded in Teamcenter also do authenticated calls to BGS/GS. Therefore, the information
how to access the OS password manager is usually passed via the generated file <GS_ROOT>/etc/
t4x_env. In case you are not loading the t4x_env batch/shell script in Teamcenter, you need to run the
script Register Tc Database Connection in the GS Admin UI to register the Teamcenter database
instance in the GS.

5-20 Installation Guide


© 2019 Siemens
Registering the GS

Caution:
In 4-tier environments the GS has to be on the same host and run under the same OS user as the
poolmanager!

Blocking compromised GSs

The Gateway Services list in the BGS Admin UI can also be used to block a suspicious GS and to unblock
it again if it has not been compromised. When blocked, the GS cannot authenticate and will not receive
any repsonse from the BGS. Blocking a GS also blocks the communication with the AIG libraries in the
corresponding Teamcenter instance.

Any GS can be deleted from the list and hence also from the database, if it is no longer needed. Be
careful, because the deletion of a GS cannot be reverted. Any call of a GS deleted from the BGS database
seems to be not authenticated properly, as the GS is not informed about the change.

Troubleshooting

In case the GS cannot start view the <GS_ROOT>/tmp/bootstrap_errors.log. The log


message ::Bootstrapping::checkBGSConnection failed with: HTTP call failed
(expected HTTP/1.1 200 OK) indicates that the BGS could not be reached. This could mean that
the BGS is not running, the BGS settings in the GS are not correct, the GS has been blocked or deleted in
the BGS Admin UI.

In case the GS has accidentally been deleted from the list of approved Gateway Services and should be
added again you have two options:

• The preferred option to register the GS with the same UUID again, login to the GS host with the OS
user operating it. Delete the key Siemens_PL4x_<UUID>/internal/token from the OS password
manager, when the GS is not running. Start the GS and approve it again in the BGS Admin UI.

• Another option, which should not be used if not necessary, is to stop the GS and delete its
<GS_ROOT>/var/conf/uuid file. With the next start, the GS generates a new UUID and can be approved
in the BGS Admin UI. This solution should not be preferred, because there will be remains in the OS
password manager belonging to the old UUID.
In case the script Register Tc Database Connection has been used before, it has to be run again
when the GS has been initialized successfully.

The error message ::Bootstrapping::tryRegisterUUID: This GS is pending and has


not been enabled in the BGS Admin UI yet usually means that the GS has reached the BGS
and initially registered, but an administrator has not yet approved it in the BGS Admin UI. If you were
using the automatic registration token (see above) make sure the token matches the current one
configured in the BGS.

Installation Guide 5-21


© 2019 Siemens
5. Installation Instructions

Refer to Initialization Prerequisites, if the


message ::Bootstrapping::SecureStorageSanityCheck: Accessing secure storage
failed is shown, indicating that the OS password manager cannot be accessed.

5.4.5 Running as Windows Service

In order to run AIG whenever the system is running, BGS and GS can be executed as Windows service.

Caution:
• When running as service never start or stop the BGS/GS at any time manually!
On the one hand switching the OS user will not work due to the way AIG is initialized. On the
other hand executing the software creates files in some subdirectories of the BGS/GS which can
have different access policies if run by a user directly or as service. Handling the Windows
security guidelines and the access management can become very tricky.

• It is recommended to run the service under a specific user account, i.e., to provide a Log On
user.

• It is absolutely necessary that both the Teamcenter Server process and GS run under the same
OS user. Violating this requirement will lead to errors and the component of AIG running in
Teamcenter will neither be able to connect to the GS or BGS.

• We do not recommend starting AIG GS as a Windows service in a Teamcenter 2-Tier client


environment. Instead it should be started together with Teamcenter, for example by calling the
file <GS_ROOT>/bin64/restart.exe in the portal.bat.

Installing the service

Instead of restart.exe, the executable file t4xservice.exe should be used to start BGS and GS as
Windows services.

• Creating a Windows service for the AIG BGS

sc create BGS binPath= "<BGS_ROOT>\bin64\t4xservice.exe" start= auto

• Creating Windows service for the AIG GS

sc create GS binPath= "<GS_ROOT>\bin64\t4xservice.exe" start= auto

More information about how to create, update and delete Windows Service, please refer to Windows
Service Controller help page: https://docs.microsoft.com/en-us/windows-server/administration/
windows-commands/sc-create

5-22 Installation Guide


© 2019 Siemens
Basic Configuration in the Admin UI

Stopping the service

In order to stop AIG BGS and GS services cleanly, create a dedicated script and add it in the Windows
Local Group Policy Editor following these steps:

1. Start gpedit.msc (i.e. the Local Group Policy Editor)

2. Open Windows Settings → Scripts.

3. Select Shutdown.

4. Open the Properties and Add the shutdown script.

5.5 Basic Configuration in the Admin UI


This chapter summarizes the very basic configuration to get Active Integration Gateway started. The
following topics are discussed shortly:

User Management

Setting the License Server

Changing Ports

Setting the BGS Server

Installation Guide 5-23


© 2019 Siemens
5. Installation Instructions

Verifying the Installation

5.5.1 User Management

Initial Password of the Default User

The password of the system administrator "t4adm" is set during the initialization using the <BGS_ROOT>/
bin64/initpassword executable, i.e. initially the password of "t4adm" is the one you entered in
initpassword. Use this password to login to the Admin UI for the first time and configure other users and
a new - independent password for the user "t4adm". For more information on the initialization refer to
Initializing the BGS.

Caution:
There is no recovery, if "t4adm" is the only administrator and you have lost the password for the
account!
Best practice is to configure an LDAP and import at least one user with the role administrator, so
that the password of the administrator is managed outside of AIG and can be reset more easily.

User Management

AIG offers a user management where you can add users who are allowed to access the Admin UI. For
each user, you can choose from four predefined roles to define which areas of the Admin UI should be
accessible and which security context level to view log files and content is assigned. For more
information about roles please refer to Admin UI help.

In the AIG BGS Admin UI, the user management is only accessible to users with the role of Administrator.
By default there is one predefined user t4adm with this role on a newly installed system.

Click Configuration → User management to open the user management page. The following actions
are available

• Add a new user ID


Use the "plus" button in the upper right corner to add a new user to the local directory. Enter a
username, password and assign a role.
If you have configured access to an LDAP directory a second "plus" button (with a database icon)
appears in the upper right corner. Here you can import users from the configured LDAP directories.
Use this button and enter the unique username in the search field. AIG searches for this username in
the LDAP directory attribute configured as username attribute and expects exactly one matching
result. If a user is found you can assign a role and add him to the database. For more information on
how to configure the LDAP directory, please view the Admin UI help.

• Edit an existing user ID. You can change the password (local directory only) or assign a different role.
Please note that in order to avoid a lock out, you cannot change the role of the current user ID or of
"t4adm".

5-24 Installation Guide


© 2019 Siemens
Setting the License Server

• Delete a user ID. The current user ID as well as "t4adm" cannot be deleted.

5.5.2 Setting the License Server

The Active Integration Gateway products are licensed software, protected by a license key.

As a member of the Teamcenter product family, the license for AIG products is included in the Siemens
PLM Software license file.

AIG BGS directly gets the license information from the Siemens PLM Software license server. Thus, you
need to configure AIG BGS to connect to the license server. Click Configuration → General → License
server to specify your Siemens PLM Software license server(s). You can configure up to three license
servers in the Admin UI and decide if they are running in multiple or redundant (fail-over) server
configuration. For more information, please consult the documentation of the Siemens PLM Software
license server.

Installation Guide 5-25


© 2019 Siemens
5. Installation Instructions

When there is an active Teamcenter ITK connection, Teamcenter Gateway will retrieve a license from the
ITK connection if AIG BGS fails to retrieve the license directly from the Siemens PLM License Server.

Save the modified settings and restart the BGS for the configuration to take effect.

5.5.3 Changing Ports

If needed, the port number and other communication settings of BGS and GS server instances can be
modified in the Admin UI. Open Configuration → Server instances and then click the edit button in the
Actions column of the table.

Specifiy your port in the pop-up dialog.

5-26 Installation Guide


© 2019 Siemens
Setting the BGS Server

Save the modification and restart the BGS or GS so that the changes take effect.

Caution:
If you are changing the port number of the SERVER or LOG_SERVER instance, you have to check
that the ports are adapted correctly in the Configuration → Communication channels section.
Especially changing the port number of the BGS server instances requires the adaption of the port
in each connected GS to work properly. For more information, please refer to Setting the BGS
Server and the Admin UI help.

5.5.4 Setting the BGS Server

Setting the BGS server in the GS

To check or modify the set BGS server in AIG GS, open Configuration → Communication channels.

When using the default configuration mode for communication channels the BGS can be set in the Basic
settings tab by entering IP address and port.

Installation Guide 5-27


© 2019 Siemens
5. Installation Instructions

When the advanced settings configuration mode is used, the BGS and BGS_WEB communication
channels in the table have to be edited by clicking the edit button in the Actions column. Enter the host
and port of the BGS and apply the settings to close the popup.

Save the modification and restart GS in the Admin UI.

5-28 Installation Guide


© 2019 Siemens
Verifying the Installation

Setting the BGS host to enable download links

The BGS maintains the communication channels DEFAULT and DEFAULT_WEB pointing to itself in order
to e.g. run scripts. Out of the box these communication channels are set to localhost, which works
properly as long as no TLS encryption takes place. However, it is recommended to change the Host of
these two channels in the BGS Admin UI to the real host address, in order to enable the direct opening/
download of log attachments from within the browser showing the BGS Admin UI. In this case the BGS
uses the information entered in the Host of the DEFAULT_WEB communication channel to construct the
correct download URL.

5.5.5 Verifying the Installation

You can check the installation of AIG GS and AIG license information by executing the Installation
Verification Test-Set. Search for this script in the Scripts section of the GS Admin UI and run it.

The script output shows information about the AIG installation, Teamcenter parameters and AIG license
information.

The script Tc database connection test is offered to test the connection from AIG to Teamcenter. Use
the script to first define and store a credentials alias in the secure storage. Afterwards validate it using
the same script.

5.6 Teamcenter Templates


This chapter explains the Teamcenter BMIDE templates which need to be deployed to the Teamcenter
database.

• Compatibility with other Templates

• Deploy AIG Template with TEM

• Deploy Active Integration Templates with Deployment Center

Installation Guide 5-29


© 2019 Siemens
5. Installation Instructions

5.6.1 Compatibility with other Templates

In general the basic Teamcenter BMIDE templates of all Active Integration Gateway products are
compatible with each other. However this does not apply to the Active Integration Gateway
demonstration templates!

The demonstration templates of T4S ("t4sdemo") and FN4T ("t4clm") are not compatible with each
other. The preferences which are installed by the T4S demo template are overwritten during installation
of FN4T demo template and vice versa. Therefore it is not advisable to install both templates on one
system.

5.6.2 Deploy Active Integration Templates with Deployment Center

Caution:
You should only use the Deployment Center for the distribution for the Teamcenter templates and
plugins, if you already have an existing Teamcenter installation in your environment, that has also
been installed via Deployment Center. In case you have installed Teamcenter with TEM, please
follow the corresponding installation instructions Deploy AIG Template with TEM

The Teamcenter templates and plugins are part of the Active Integration Software Package and should
be registered as Software Packages by the Deployment Centers’ Repository Service after placing the
unzipped package in the Repository, as described in the chapter: Installation Preparation.

Once registered, you can add the Teamcenter templates and plugins to your environment by adding it to
the Environments’ list of selected software. Additionally, you must select them in the list of available
Applications.

You can add the respective templates and plugins for your FN4T installation by selecting your
environment containing Teamcenter and, depending on your usecase, by adding the following software

5-30 Installation Guide


© 2019 Siemens
Deploy AIG Template with TEM

packages to the list of selected software:

5.6.3 Deploy AIG Template with TEM

Caution:
You should only use TEM for the distribution for the Teamcenter templates and plugins, if you
already have an existing Teamcenter installation in your environment, that has also been installed
via TEM. In case you have installed Teamcenter with Deployment Center, please follow the
corresponding installation instructions Deploy Active Integration Templates with Deployment
Center

For the AIG installation, the Teamcenter database and configuration should be adapted by deploying the
AIG template with the Teamcenter Environment Manager (TEM).

For deploying the AIG template with TEM, please perform the following steps:

1. Execute tem.bat in Windows or the corresponding file tem.sh in UNIX/Linux in directory %TC_ROOT
%/install to start TEM

2. In the first screen Maintenance, select Configuration Manager and click Next

3. Select Perform maintenance on an existing configuration

4. Select your desired database

5. Feature Maintenance: select Teamcenter – Add/Remove Features

6. In the next window Features, click Browse and select the AIG template file:

Installation Guide 5-31


© 2019 Siemens
5. Installation Instructions

For Teamcenter 11: <GS_ROOT>/var/template/<t4x>/BMIDE/full_update/feature_<t4x>.xml


For Teamcenter 12: <GS_ROOT>/var/template/<t4x>/BMIDE/full_update/tem_contributions/
feature_<t4x>.xml

7. Then, in the same window, the new feature appears and has to be checked. To deploy FN4T
template, the new feature Teamcenter Gateway for Simatic IT under Extensions should be
selected.

Caution:
Do not deploy the T4x Demonstration Template for a customer installation.

Usually this will cause TEM to also install the RAC extensions if the AIG template has client
extensions. However in some environments this will not always happen. To make sure client
extensions are installed, please also select the corresponding template "<AIG> for Rich Client".

8. Click Next and type the dba password for this database and click Next

9. In the next window Confirmation, you should see the selected features. Click Start to start the
template installation

10. The next window Install shows the progress with a moving bar. This may take some minutes and
should end with the message Install Successful:

5-32 Installation Guide


© 2019 Siemens
Configuring the Mapping

Caution:
• Before starting TEM, please make sure to have all the configuration XML files of any adaptation
that was done up to now (i.e., before the beginning of this AIG installation) in the directory
%TC_DATA%/model. Especially after adaptations using database dumps, there may be missing
files. As TEM will try to delete or modify those files, it will run into an error if any of them is
missing (find the messages in %TC_DATA%/model/delta.xml)

• Be sure to use the correct TEM for the desired Teamcenter installation: check that it shows the
correct Installation Directory (%TC_ROOT%) in the Select Features window (see above). If not,
exit TEM and start the one from the correct Teamcenter directory: %TC_ROOT%/install/tem.bat
or tem.sh.

• As a result the following library libfn4t must be included under the


TC_customization_libraries preference in Teamcenter

• The TEM instance under %TC_ROOT%/install will only install the client extensions to the portal
installation under%TC_ROOT%/install. If your installation has a separate 4-tier RAC installation or
your host has only a client installation, the TEM instance from that specific installation can be
used to install the client extensions of the template. In this TEM run, you only need to select
template "<AIG> for Rich Client".

• When updating already installed AIG templates, TEM may issue a message indicating that the
corresponding template "<AIG> for Rich Client" will not be updated because TEM assumes it is
not installed. The installation of the template (without the RAC components) itself will
continue. If you also need to update the RAC components, the "<AIG> for Rich Client" must be
selected to be installed as if it was not installed before in a separate TEM run.

5.7 Configuring the Mapping


The mapping files define the customer specific data handling when transferring data from one
application to another. These source files need to be placed into <GS_ROOT>/var/mmap, compiled to a
library and deployed in order to take effect.

See also chapter Manage a development environment in the Active Integration - Generic
Configuration Guide.

Installation Guide 5-33


© 2019 Siemens
5. Installation Instructions

Mapping structure and basics

Out of the box the mapping source directory <GS_ROOT>/var/mmap does not contain any mapping at all
but only placeholder directories. You can start from scratch with your own mapping, copy your existing
files or the AIG mapping templates to start with. The mapping templates can be found in
<GS_ROOT>/var/template/t4x/mmap and <GS_ROOT>/var/template/fn4t/mmap.

No mapping file (*.sd ) should be placed directly in the mapping source directory but only in one of its
sub directories. Use the directory <GS_ROOT>/var/mmap/t4x_mapping_config for product independent
mapping files. Each of these directories has to contain a file *_mapping_config.sd (same file name as
the sub directory name) used as entry point when loaded and sourcing further files if needed. In order
to load a mapping when the GS is started, use the function SYSBase::loadLibrary. See FN4T API
Reference for details.

Mapping compilation and deployment

The compilation and deployment of the mapping files in <GS_ROOT>/var/mmap can be done using
either a script or an executable and consists of these steps:

1. Compile one or more mapping libraries from the sources in the sub directories of <GS_ROOT>/var/
mmap to corresponding library files (*.rfdt) in <GS_ROOT>/tmp.

2. Move one or more of those library files to <GS_ROOT>/lib.

3. Restart the GS to load the new mapping.

Either way, you can decide to only execute the first or the first two steps instead of the complete
deployment. When using the Generate mapping and mapping deployment script in the Gateway
Service Admin UI select all or a single specific file to generate mapping for:

5-34 Installation Guide


© 2019 Siemens
Configure Teamcenter Environment for AIG

To automatically compile, copy, deploy and load the mapping select the Generate Mapping and Server
Hot Deployment Mode. The same behavior can be achieved using the <GS_ROOT>/bin64/mmap
executable. For the exact same behavior execute: bin64/mmap -connid DEFAULT -user t4adm
-passwd <yourpassword> -sdstdir lib. For further information please read the help text of the
script and/or the executable.

5.8 Configure Teamcenter Environment for AIG


• Set AIG GS Environment for a Teamcenter 2-Tier Environment

• Set AIG GS Environment for a Teamcenter 4-Tier Environment

• Add AIG Error Message Texts to Teamcenter

• Connectivity to Teamcenter

5.8.1 Set AIG GS Environment for a Teamcenter 2-Tier Environment

In order to integrate AIG functionalities (i.e., AIG workflow handlers) into Teamcenter, Teamcenter
needs to know the AIG environment and AIG libraries which should be loaded during Teamcenter start.
As Teamcenter clears the environment settings while processing its start-up scripts (portal.bat,
start_imr.bat…), the call of AIG environment file has to be done immediately before the start of the
Teamcenter Server process.

Open the file %TC_ROOT%\iiopservers\start_TcServer1.bat (the number and file extension may be
different depending on the platform and installation) in a text editor and add the line to call the AIG
environment before the line to start Teamcenter Server:

• For Windows: call <GS_ROOT>\etc\t4x_env.bat

• For Linux/Unix: . <GS_ROOT>/etc/t4x_env.sh

In case you have more than one Teamcenter database in your Rich Client installation, there is more than
one file like that, e.g., start_TcServer1.bat and start_TcServer2.bat… Be sure to do this modification in
the file(s) corresponding to the database(s) where AIG should be used.

Caution:
As a Teamcenter 2-Tier environment, the adjustment of the Teamcenter start script should be
done to all Teamcenter clients.

5.8.2 Set AIG GS Environment for a Teamcenter 4-Tier Environment

In order to integrate AIG functionalities (i.e., AIG workflows handlers) into Teamcenter, Teamcenter
needs to know the AIG environment and AIG libraries which should be loaded during Teamcenter start.

Installation Guide 5-35


© 2019 Siemens
5. Installation Instructions

In a Teamcenter 4-Tier environment, the AIG environment file should be called during pool or net server
manager start.

In a Teamcenter 4-Tier environment, we recommend editing the start script file: %TC_ROOT%
\pool_manager\confs\config1\tcenv.bat. The following AIG environment file should be called after
executing the file tc_profilevars.bat and before starting Teamcenter Server:

• For Windows: call <GS_ROOT>\etc\t4x_env.bat

• For Linux/Unix: . <GS_ROOT>/etc/t4x_env.sh

5.8.3 Add AIG Error Message Texts to Teamcenter

The AIG error messages are stored in an additional file separate from other Teamcenter error messages
(which are stored in the files ue_errors.xml). It is sap_errors.xml. This file is copied to the target
Teamcenter folder during AIG template deployment.

The AIG error messages use their own number range (starting from 212000) within the Teamcenter
error handling, so there will be no conflicts with other error messages.

AIG supports several languages that are selected automatically according to the Teamcenter GUI
language: if it is started in a language that is not supported by AIG, the AIG GUI and its error messages
will be presented in English.

Use the Teamcenter environment variable TC_MSG_ROOT or TC_USER_MSG_DIR to control where


Teamcenter will search for error message files (e.g., %TC_USER_MSG_DIR%\en_US
\sap_errors.xml). If these are not found there, Teamcenter will use the default directory %TC_ROOT
%\lang\textserver\en_US.

5.8.4 Connectivity to Teamcenter

Credentials used for an automatic login to Teamcenter are maintained centrally by the BGS and have to
be stored in the BGS database, before they can be used. The script Tc database connection test in the
GS Admin UI can be used to store, test, delete and update such credentials. Credentials previously stored
using the script can be used in the mapping with ::ITK::setCredentialsAlias
<CredentialsAlias>.

There are basically three options:

If you do not add the function in your mapping and if you have not specified any default
credentials alias, then the credentials of the operating system user are used to connect to
Teamcenter.

If you have previously executed the action Define Default Credentials Alias in the script to specify
an accout as default one, then this entry ("Default@Teamcenter") will be used.

5-36 Installation Guide


© 2019 Siemens
Configure AIG Environment for Teamcenter

If you have specified a credentials alias using the action Define and Store Credentials Alias
successfully, e.g. "MyCredentialsAlias", then you can explicitly use it in the mapping with
e.g. ::ITK::setCredentialsAlias MyCredentialsAlias.

5.9 Configure AIG Environment for Teamcenter


AIG needs to know the Teamcenter environment in order to work properly. Open the file
<GS_ROOT>/var/conf/script/t4xcust.bat or t4xcust.unix depending on the OS you are using. Edit the first
few lines to define the TC_ROOT and TC_DATA environment variables and make a call to the
tc_profilevars.bat/.sh. For example, to add your Teamcenter environment to AIG on Windows OS use:

set TC_ROOT=C:\Siemens\tc12
set TC_DATA=C:\Siemens\tcdata
call %TC_DATA%\tc_profilevars.bat

5.10 Installation of additional components

5.10.1 Install a JDBC Driver to connect to a database

If you want to use JDBC connections to a database, you must first install a JDBC driver. The AIG delivery
does not contain any JDBC drivers. You must download each required driver on your own and accept the
licensing agreements. To install a JDBC driver for AIG, follow these instructions:

Download the JDBC driver or find it in the database installation. Here are some download URLs for
common JDBC drivers:

• Oracle: https://www.oracle.com/technetwork/database/application-development/jdbc/
downloads/index.html. Click the driver matching your database version, accept the license
agreement, log in with your Oracle account and download package containing the "JDBC Thin driver".

• Microsoft SQL Server: https://www.microsoft.com/en-us/download/details.aspx?id=11774. Select


your language and click the "Download" button. Then follow the download instructions. If you need
an older version of the driver, review the links near the bottom of the page ("Related Resources"). In
case you use integratedSecurity=true; as part of your JDBC connect string, please make sure
sqljdbc_auth.dll is available in the Gateway Service's PATH environment variable. The DLL is part of
the driver installation package.

• MySQL: http://dev.mysql.com/downloads/connector/j/. See the "Archives" link for older versions.

Copy the jar file of the JDBC driver to the <GS_ROOT>/lib/modules directory.

Your JDBC driver can now be used from the AIG mapping and test scripts.

Installation Guide 5-37


© 2019 Siemens
5. Installation Instructions

5-38 Installation Guide


© 2019 Siemens
6. Opcenter Connectivity
6.1 Introduction
The following sub chapters describe necessary installation steps in FN4T to establish connectivity.
Adaptions to custom configurations are described in the Opcenter Connect FN for Teamcenter -
Configuration Guide.

In order to use Closed Loop Manufacturing and to enable two-way connectivity between FN4T and
Opcenter of course the Opcenter server also needs to be configured accordingly. These steps are not
described in detail within this manual. Instead please see the manuals of Opcenter for details. A web
key is required for this access which can be requested right on this page.

6.2 Opcenter EX DS connection configuration


The connection configuration to access a Opcenter server must be set via the script exdsconnect.tcl
in the Gateway Service Admin UI:

This script stores the connection parameters in a central, encrypted database on the BGS. Please use
"Define and Store Credentials Alias" to store credentials. In addition to the default parameters add your
specific data as shown in example above. The parameters have the following meaning:

Action: "Validate AutoLogin" validates connection defined in the


fn4t_mapping_config.sd.

Installation Guide 6-1


© 2019 Siemens
6. Opcenter Connectivity

"Define and Store Credentials Alias" stores data and validates connection at the same
time.

"List Stored Credentials Aliases" lists all stored credentials aliases for target system.

"Validate Stored Credentials Alias" validates connection for given alias. Please set "Keep
or delete the cached token before connecting" to "delete" to enforce generating of the
token in case if the existing (cached) token is no more valid or you need the immediate
feedback for the changed data for the given alias.

"Delete Stored Credentials Alias" removes stored credentials alias.


Credentials This specifies the identifier or label with which the connection info will be stored in the
Alias: encrypted BGS credentials database. In most cases you will only need a single alias for
all Opcenter connections and in this case a good choice would be "default" or the name
of the connection (identical to "EXDS System").
Destination: This is the logical name of the connetion to a single Opcenter system as used in the
mapping logic.
URL The URL component between the port and the specification of the Opcenter
extension: application, beginning with a slash. If e.g. the service URL for the ping service is:
"http://mysitserver:80/sit-svc/Application/AppU4DM/odata/DependencyType", the URL
Extension is the part between ":80" and "/Application". Usually this component is
identical for all Opcenter applications on a server and in most cases /sit-svc is
correct. Ask your Opcenter administrator if uncertain.
Executable this path to a binary or executable is executed whenever FN4T needs to extract a JWT
path for token from the certificate. The token is necessary in order to authenticate against the
token Opcenter server. For details on the certificate, see Install Certificate. The default value
extractor: refers to the OOTB Java library delivered with FN4T. The main class of the Jar file takes
the positional parameters: KeyStorePassword, KeyStorePath, TokenAppName and
CertPassword. Both passwords have to be passed unencrypted to the Jar. The default
configuration of CLM makes sure the Jar is fed with correct parameters. The specific
pattern "#JWTJavaPath#" makes sure the Java executable is used as configured for JWT
on the specific Gateway Service when the token is extracted. This allows the same
configuration to be used on e.g. Linux and Windows, but of course a specific, absolute
path can also be configured, if needed.
Alias for The alias is the alias used in the key store by the administrator who created the key
certificate: store.
Path to key Path to a Java key store file containing the certificate.
store:
KeyStore Password for key store in plain text.
password:
Certificate Password for certificate in plain text.
password:

6-2 Installation Guide


© 2019 Siemens
Opcenter EX DS connection configuration

Seconds This parameter determines the validity period of the created token as configured on
until token the server (FN4T requests a new token after this period). This will be passed as JWT
expires: claim "Expiration Time" (exp) after adding the value of MaxClockSkewInSeconds.
Ask your Opcenter administrator for details.
Max. This is an optional parameter, the default value is 120. This parameter denotes the
assumed number of seconds to subtract from the JWT claim "Not Before" (nbf) and added to the
clock Skew token lifetime "Expiration Time" (exp) of the JWT token used for authentication against
in seconds: the Opcenter server. This time span will be subtracted from the lifetime of the token
cached in shared memory. This parameter allows for the clocks of the FN4T Gateway
Service host and the Opcenter server to differ up to the maximum of the specified
number of seconds. Note that despite this parameter the clocks should be
synchronized. The value of MaxClockSkewInSeconds must be smaller than the value of
TokenExpiresInSeconds!
Keep or Uses existing token stored in cache if any or enforce to delete from cache and generate
delete the a new one.
cached
token before
connecting:
Overwrite: "yes" will overwrite if the chosen value for "Credentials Alias" is already existing. By
choosing "no" the script will only create a new extry, but not overwrite an existing one.

The configured connection details are then used in calls


like ::T4X::CONNECTION2EA::setConnection4UseCase to build a named connection that is used
in RAC or in the mappings in order to address a specific Opcenter system. Several credential sets and
connection details may be configured, allowing to address different Opcenter systems if required. A
"preferred" FN4T connection can be defined
by ::T4X::CONNECTION2EA::selectActiveConnection2EA FN4T "*" "UAFReal". This
connection will be used if not otherwise specified.

For each of your specific Opcenter servers the corresponding URL prefix (protocol, host name, port) has
to be configured in the connection configuration section of the GS Admin UI. This allows to manage the
URL (including also connections specific parameters like TLS certificates and proxy settings) via GS
Admin UI. It is important to make sure that the name of the connection created in the mapping
("UAFReal" in this example) exactly matches the name of the connection created in the GS Admin UI.
Choose "HTTP" as protocol and enter the port of the Opcenter. Restart Gateway Service when done. Here
is an example configuration with one Opcenter server in addition to the 5 OOTB connections:

Installation Guide 6-3


© 2019 Siemens
6. Opcenter Connectivity

Before each interaction with Opcenter, FN4T checks the connectivity using a simple and fast call to the
server. This can be configured in ::FN4T::CONNECTION2EA::CUSTOM::MAPPING::connectEA.
The demo implementation calls ::FN4T::SERVICES::checkConnection. The following API will be
used in this function:

Target System Used API


Opcenter EX DS DependencyType

Caution:
• If your Opcenter exposes an SSL (https) URL, you need to tell FN4T which certificates should be
used, otherwise no certificates will be checked - opening the connection for man-in-the-middle
attacks! Active Integration Gateway clients do not use certificates from the operating system
certificate store, so the certificates have to be specified in the connection configuration of the
Admin UI! For more details, please see the online help in Admin UI.

• Even if you plan to address only a single Opcenter system, you still have to adapt
the ::EXDS::PLANTMAPPING in file fn4t_custom_parameters.sd to reflect your connection
name and the used plant identifiers. Otherwise transfers will fail with an error about a missing
connection. For details on the plant mapping, see also chapter Addressing Multiple Opcenter
Servers

6.3 Install Certificate


Opcenter uses "2-legged" OAuth 2.0 for authentication. This mechanism does not require the user to
enter any credentials, but instead, the host running the service (each FN4T GS host in our case) and the
Opcenter host must have the identical certificate installed in the system's or a specific Java certificate
store. Usually, this certificate is created and provided by the Opcenter administrator. On Windows, such
a certificate is a file with the extension .pfx.

6-4 Installation Guide


© 2019 Siemens
Test Opcenter Connection

FN4T provides only one option to retrieve a valid token (the older getToken.exe has been removed as it
is not platform neutral). The Java Library (TokenExecutable: [list [::SYSBase::getJavaPath
JWT] -jar "[rcwd]/lib/token/x509tokenextractor.jar"] works on all platforms
supported by AIG. The certificate as received from the Opcenter server or administrator (called
sample.pfx in the following example), has to be stored in a Java key store before the library can
extract a token. Moreover a valid JRE (>= Java 8) has to be configured for the "Advanced" Java option
"JVM for OAuth/JWT" in the Admin UI.

Java keytool can be used to store the certificate into a Java key store:

keytool -importkeystore -srckeystore sample.pfx -srcstoretype pkcs12\


-destkeystore var/conf/cert/KeyStore.jks -deststoretype JKS\
-alias pvktmp:f4053187-cd35-4e99-9490-21be88fa17e9 -destalias clm

This call will ask for the key store and certificate password (if required) interactively. You have to enter
the passwords in plain text here. The same passwords have to be entered using the script
exdsconnect.tcl.

Please do not forget to keep the FN4T server clock and the Opcenter server clock synchronized because
otherwise the lifetime of the token cannot be validated correctly because of the JWT claims nbf (Not
Before) and exp (Expiration Time) in the payload part of the token. The configuration parameter
MaxClockSkewInSeconds allows a limited adaption to unsynchronized clocks, but in general clock
synchronization is required!

The chapter Opcenter EX DS connection configuration describes how to configure FN4T to use the
imported certificate. For more details on certificate handling, consult the Opcenter manuals.

6.4 Test Opcenter Connection


Testing

The script Opcenter EX DS connection test in the GS Admin UI (file name Base/exdsconnect.tcl can be
used in order to verify if the configuration has been performed correctly (action "Validate Stored
Credentials Alias").

Troubleshooting

If the validation fails, analyze the log file and check the following:

• Verify the configuration with help of the Opcenter administrator.

• Make sure the connection details have been stored using the script exdsconnect.tcl and the same
credentials alias has been used when
calling ::T4X::CONNECTION2EA::setCredentialsAlias4UseCase.

Installation Guide 6-5


© 2019 Siemens
6. Opcenter Connectivity

• In case your test only succeeds with parameter "Keep or delete the cached token before connecting"
set to "Delete" please verify the connection parameter "Seconds until token expires" and the time
synchronization with the Opcenter web server administrator.

• Make sure the correct IP or host name, port and protocol was entered in the Admin UI! In case of https
as protocol, verify the TLS certificates!

• Make sure Opcenter is up and running and all necessary permissions are applied. Check with your
Opcenter administrator if necessary.

• On the host where the GS is installed: Check network connectivity using the operating system
command ping <IP or host name of the Opcenter server>. Next try to access the Opcenter server by
entering the configured URL (From "Configuration/Communication Channels" in the Admin UI:
concatenate protocol, host name and port and append the value of "URL Extension" as configured in
the named Opcenter connection) in a browser on the GS host. The resulting URL should look similar
to this: "http://mysitserver:80/sit-svc/". If this does not work, check with your local network
administrator. For example a firewall might block the connection.

6.5 Deployment Options


The logical structure of a Closed Loop Manufacturing integration and the participating integration
products looks as follows:

The Active Integration Gateway product family allows to distribute functionalities to different locations
or servers as needed. So it is possible to install two or three of the products (T4S, FN4T and FN4S) in a
single GS (Gateway Service) instance or to distribute to several GS instances vertically (according to
functionalities) or horizontally (scalability). In all scenarios it is highly recommended to keep a single
BGS (Basic Gateway Service) in the network to allow a single access point for logging, job management
and secure credentials storage.

6-6 Installation Guide


© 2019 Siemens
Deployment Options

Single GS

This is an example of a simple installation with a single GS instance. It assumes that all three products
are installed using the Active Integration Gateway installer's "extend" option. Active Integration Gateway
BGS, Opcenter EX DS and SAP are each installed on a separate host. The GS is installed on the
Teamcenter server host, because it needs to be called directly from the tcserver processes in the
Teamcenter pool manager. (The size and number of the host boxes does not indicate any sizing or
importance.)

Note that the GS instance can also address several Opcenter EX DS instances, either on the same host or
on several hosts. In order to improve performance for GS web service calls coming from Opcenter, one
or several GS instances may be added on separate hosts that are not connected to the Teamcenter pool
manager but share only the Teamcenter 2-tier installation package (see Active Integration -
Installation Guideand the Teamcenter manuals).

Separate GS Instances for Teamcenter and Opcenter EX DS

Due to the stricter requirements regarding accessibility and fault tolerance it may be useful to separate
the ERP-MES functionality into one GS instance ("GS1") while the all PLM-related functionality resides on
another GS ("GS2"). In this case the BGS host should also be part of the MES network. It is required to
install all three products on "GS2" instances, as the PLM-related functionalities access code that is part of
the FN4S product. "GS1" only will access FN4S functionality, so it would be sufficient to install only this
product on "GS1". However for simplicity we recommend to install all three products on both GS
instances. This allows to share a single mapping package, making management and maintenance easier.
In this scenario a failure of the Teamcenter host does not affect order processing for materials that have
already been transferred to Opcenter EX DS and SAP.

Distribution of the functionalities can be achieved by taking these measures:

• The trigger script for SAP orders runs on "GS1" and the job agent on "GS1" is configured to process
only SAP-related jobs.

Installation Guide 6-7


© 2019 Siemens
6. Opcenter Connectivity

• In Opcenter EX DS configuration keys, the URLs configured for CLM processing point to the host name
of "GS2" for Teamcenter related services of FN4T (triggerSkeletonTransfer and updateIssueReport) and
to the host name of "GS1" for SAP related services of FN4S (createProdOrderConfAsync and
createProdOrderOperationConfAsync).

The image shows only a single connection of the GS to the MES system for simplicity, but of course also
in such a separated environment each single GS can address several instances of Opcenter EX DS (on a
single or separate hosts, maybe even in different networks). However all GS instances need connectivity
to the BGS. SAP does not necessarily have to be part of the manufacturing network but can also be in
the engineering network or another segment as long as the connectivity is up.

6.6 Addressing Multiple Opcenter Servers


FN4T can address one or many Opcenter servers based on some mapping logic. The delivered demo
mapping assumes the following restrictions:

• There is only a single SAP system and only a single client within this system is relevant for the
scenario.

• There is only a single Teamcenter system relevant for the scenario. (Opcenter requests for
confirmation, non-conformance and 100% download can only go to a single instance.)

• There is 1:1:1 relation between Teamcenter top-level-work area, SAP plant and Opcenter EX DS top-
level equipment element (also called enterprise or plant).

6-8 Installation Guide


© 2019 Siemens
Addressing Multiple Opcenter Servers

• Top-level Teamcenter work area and Opcenter EX DS top-level equipment element (enterprise) are
mapped according to identical names.

• The SAP production plant is mapped to the Opcenter EX DS top-level equipment element (enterprise)
exclusively by the ::EXDS::PLANTMAPPING functionality (see below).

• Each Opcenter server can handle several top-level equipment elements (enterprises). This essentially
means that a single FN4T connection can be used to address several enterprises.

The mapping is defined by a triple of enterprise Id (NId for Opcenter EX DS and a concatenation of item
Id and Revision Id for Teamcenter), the SAP plant ID and the FN4T connection name. In the demo
mapping this is defined using ::EXDS::PLANTMAPPING functionality, similar to the following example:

::EXDS::PLANTMAPPING::add "1000_A" "1000" "SITConnectionA"


::EXDS::PLANTMAPPING::add "2000_A" "2000" "SITConnectionA"
::EXDS::PLANTMAPPING::add "3000_A" "3000" "SITConnectionB"

This is a global definition and should be defined in fn4t_custom_parameters.sd file. The example
defines that the work area with NId "1000_A" (the Opcenter EX DS enterprise) maps to SAP plant 1000
and the FN4T connection "SITConnectionA" has to be used to address Opcenter EX DS. A second
enterprise "2000_A" is also hosted be the same Opcenter server which can be addressed by the FN4T
connection "SITConnectionA", but maps to SAP plant 2000. Finally a separate Opcenter server hosts
"3000_A" (SAP plant 3000) and can be addressed using FN4T connection "SITConnectionB".

Whenever FN4T needs to transfer data to Opcenter, it determines the FN4T connection based on the
top-level work area.

All incoming web service calls from Opcenter carry an "Enterprise" field. Based on this value any
subsequent FN4T, FN4S or T4S action can determine the correct connection to Opcenter. The
namespace ::EXDS::PLANTMAPPING contains all necessary procedures to uniformly access the
previously defined plant mapping.

Note that in the demo scenario implementation the "Enterprise" value of an incoming call is copied to
the description field of the initiated Teamcenter workflow by FN4T. This value always overrules any
default ("preferred") connection and also overrules the connection that results from the top-level work
area or SAP plant. Since the 150% transfer does not know any structure, the demo scenario provides
workflow templates that transfer the master data either to only one Opcenter server, or to several
servers. This can be adapted as needed using standard Teamcenter workflow definition and the FN4T
logon task.

Installation Guide 6-9


© 2019 Siemens
6. Opcenter Connectivity

6-10 Installation Guide


© 2019 Siemens
7. Configure AIG for TLS/SSL
AIG supports TLS (Transport Layer Security) only. The term SSL (Secure Sockets Layer) may be used for
simplification as those two terms are often used interchangeably. The usage of TLS/SSL encryption for
AIG is optional and depends on your requirements. However, a properly installed and tested BGS and GS
are required before you begin. Furthermore, a basic knowledge of TLS/SSL and how to obtain valid
certificates is assumed, as a complete description of TLS/SSL, certificates and certificate authorities is
beyond the scope of this manual.

The TLS implementation of AIG is based on the OpenSSL libraries and using TLS version 1.2 solely.

Caution:
It may happen that you lose the connection to the AIG server due to misconfiguration, so that you
will not be able to fix the configuration using the Admin UI. Therefore, it is highly recommended
to backup your configuration before changing any encryption settings by copying the file
<BGS_ROOT>/var/conf/tpds.overlay or <GS_ROOT>/var/conf/tpds.overlay respectively.

7.1 Certificates
Caution:
AIG provides some self-signed demo certificates out of the box, which are not secure and have to
be replaced with your own for production use. These demo certificates are bound to the localhost
domain name and will not work for installations on separate hosts. Active Integration can not and
does not provide any certificates for your installation or any consulting on how to obtain these
certificates, as this has to match the detailed IT and security requirements of your organization.
Your organization may use an independent certificate authority or use certificates generated by a
third-party vendor. Please contact your IT support to obtain valid certificates, accordingly.

AIG requires X.509 pem encoded certificates using the *.pem file extension. Other files with no or a
different extension will not be shown in the UI and cannot be used during the configuration. The server
and client certificates used need to contain the public certificate and its associated private key (usually
the key is inserted before the certificate). The private key of the certificate file must not be encrypted, as
AIG does not support specifying a pass phrase at the moment.

The CA certificate has to contain the whole chain of CA certificates to verify the validity of the server or
client certificate. Usually the certificates defined in the CA certificate begin with the most specific one
(the one nearest to the server or client certificate) and end with the most generic one, i.e., the one
closest to the certificate root.

If you are using client authentication for the ADMIN_UI20 server instance, you have to import your
client certificate to Firefox (PKCS#12 format) or the OS certificate storage (PEM format), depending on
the browser you use. For detailed information on the needed formats and how to import and use those
certificates, please consult the documentation of your operating system and/or web browser.

Installation Guide 7-1


© 2019 Siemens
7. Configure AIG for TLS/SSL

To check the properties of your certificates before configuration follow these steps:

1. Check that each certificate has a *.pem file extension. PEM encoded certificates can also have the
file extension *.cer or *.crt, therefore it is necessary to check the content of the file as
mentioned in the next step. Since AIG will only view *.pem files in the Admin UI you have to
replace or add this file extension if necessary.

2. Open the certificate file using an text editor and check that each of the following sections can be
found once in the server and client certificate:
-----BEGIN RSA PRIVATE KEY----- … -----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE----- … -----END CERTIFICATE-----
If you cannot read the content of the file then this is probably not a PEM encoded file. The
certificate will not work in AIG if one of the sections is missing in the file.
The CA certificate (chain) file has to contain one or more certificate sections, but no private key
sections.

3. If necessary you can use the following OpenSSL commands - assuming that OpenSSL is installed in
your test system - to check the properties of your certificates in details. For more information on
OpenSSL please consult the official website at https://www.openssl.org/.

a. openssl x509 -inform PEM -in yourCertificate.pem


openssl rsa -inform PEM -in yourCertificate.pem
These commands can be used to test if your certificate and your private key contained in the
certificate file are actually PEM encoded. If working correctly the content of the certificate or
private key is printed between the tags mentioned in section 2. above. If the certificate or
private key is missing or in the wrong format an unable to load error message is shown.

b. openssl verify -CAfile yourChain.pem yourCertificate.pem


Verifies that your server or client certificate has been issued by the CA defined in your CA
certificate (chain). The output has to end with OK.

c. openssl rsa -check -noout -in yourCertificate.pem


Check the consistency of the private key contained in the certificate file. RSA key ok indicates
that the private key is correct, otherwise RSA key error is shown.

d. openssl x509 -noout -dates -in yourCertificate.pem


Prints the validation dates of the certificate. Make sure that the current date is in between
those dates. Otherwise the certificate is already expired or not valid yet.

e. openssl x509 -in yourCertificate.pem -noout -pubkey | openssl md5


openssl rsa -in yourCertificate.pem -pubout | openssl md5
The output of both commands has to match exactly to make sure that the public key
contained in the certificate section matches the public key portion contained in the private
key section. Otherwise the wrong private key has been copied to the wrong certificate file.

f. openssl x509 -noout -modulus -in yourCertificate.pem | openssl md5


openssl rsa -noout -modulus -in yourCertificate.pem | openssl md5

7-2 Installation Guide


© 2019 Siemens
Certificates

The output of both commands has to match exactly to make sure that the public and private
key of your file form a matching key pair.

g. openssl crl2pkcs7 -nocrl -certfile yourChain.pem | openssl pkcs7 -


print_certs -noout
Prints the subject and issuer chain in the order contained in the CA certificate (chain) file. The
recommended order is from the most specific certificate to the most generic root (or most
proximate to the root) certificate. Though AIG does not consider the order of the certificates
in the CA certificate (chain) file you have to make sure that the chain is complete without any
gaps.

h. To view the content of the different certificates as human-readable text you can use the
following commands, depending on the file format:
PEM encoded file: openssl x509 -noout -text -in yourCertificate.pem
PKCS#12 (i.e. *.p12) file: openssl pkcs12 -info -in yourCertificate.p12

Place your certificate files in the <BGS_ROOT>/etc/cert and <GS_ROOT>/var/conf/cert respectively to


make them available for AIG and the configuration dialog of the Admin UI.

Caution:
Since the private key portion of the certificate files is not encrypted you should make sure that the
cert folders are only accessible for AIG, i.e., for the OS user operating AIG.

Using the certificate store of the operating system

For CA certificates it is possible to use certificates from the certificate store of the operating system
instead of copying them to the cert directory. To make use of the OS certificate store the following steps
have to be done before configuring the CA certificates in the Admin UI.

1. Make sure that the needed CA certificates are available in the OS certificate store of each relevant
host. Please consult the documentation of your operating system for more information.

2. Enable the OS certificate store for AIG depending on your OS:


For Windows run the executable <AIG_ROOT>\bin64\t4xsynccerts.exe to synchronize all currently
stored CA certificates of the certificate store to the file <AIG_ROOT>/var/conf/cert/ca-
certificates.crt. When AIG is configured to use the certificate store, it will search for the according
certificate in this file.

Caution:
The t4xsynccerts.exe requires that the execution of PowerShell scripts is allowed otherwise it
fails. Please refer to the documentation for Execution Policies by Microsoft to solve this issue.
Any changes to the content of the OS certificate store are not reflected by the ca-
certificates.crt file. If needed, update the file running the executable again.

Installation Guide 7-3


© 2019 Siemens
7. Configure AIG for TLS/SSL

For Linux no extra configuration is required to enable the certificate store for AIG.

7.2 Server Authentication


Using server authentication (also known as standard authentication or one-way TLS) the client (e.g.,
your GS or web browser) verifies the certificate sent by the server (e.g., your BGS or GS) before
continuing any communication. You can choose to use server authentication for BGS and/or GS as well
as which server instances are affected.

The communication between Teamcenter and the GS is encrypted, as soon as encryption is configured
for the GS.

7.2.1 Configuring Server Authentication for the BGS

For enabling server authentication in the BGS the following certificates have to be available:

• The BGS server certificate has to be placed in the <BGS_ROOT>/var/conf/cert directory.

• The corresponding CA certificate (chain) file has to be available in the BGS and each connected GS.
Either in the <AIG_ROOT>/var/conf/cert directory or in the certificate store of the operating system
(see Using the certificate store of the operating system).

Follow these steps to configure server authentication in the BGS Admin UI:

1. Open Configuration → Server instances and edit all server instances that should send a
certificate for verification. For each server instance enable the Encryption in the dialog for editing
and select the BGS server certificate in the Server certificate editing dialog. Apply the changes to
close the pop-up and proceed with the next server instance if needed.
To enable server authentication for the default BGS (web)services edit the properties of the
SERVER server instance. To operate the Admin UI using TLS, edit the ADMIN_UI20 server instance.

2. Since the BGS needs to be able to communicate with itself properly, e.g. when running a script, you
have to modify the properties for the communication additionally. The settings of the SERVER
server instance configured in step 1. have to match the properties of the communication channels
DEFAULT and DEFAULT_WEB.
Open the Configuration → Communication channels settings, select Use advanced settings for
the Configuration mode if needed and modify these communication channels in the shown table:

a. Edit the DEFAULT channel. Enter the correct Host, i.e., the one that is used in the certificates.
Switch the Transport mode to Encrypted socket (TLS/SSL) and select the corresponding CA
certificate (chain file) or use the Certificate store of the operating system in the CA
certificate editing dialog.

b. Apply the changes to close the pop-up.

7-4 Installation Guide


© 2019 Siemens
Configuring Server Authentication for the GS

c. Repeat the configuration for the DEFAULT_WEB communication channel, that is used for the
URL composition of certain web services. Enter the Host, select HTTPS (TLS/SSL) for
Transport mode and select the same CA certificate (chain file) or use the Certificate store of
the operating system for CA certificate.

d. Apply the changes to close the pop-up.

3. Apply all changes and restart the BGS.

4. Not only the BGS, but also each connected GS has to know the properties for a secure
communication with the BGS, i.e., the settings of the SERVER server instance of the configured
BGS have to match the properties of the communication channels BGS and BGS_WEB in each
connected GS.
Therefore, open the Configuration → Communication channels settings in the Admin UI of each
connected GS, switch to the advanced Configuration mode if necessary and modify these
communication channels:

a. Edit the BGS channel. Enter the correct Host of the BGS, i.e., the one that is used in the
certificates. Switch the Transport mode to Encrypted socket (TLS/SSL) and select the
corresponding CA certificate (chain file) or use the Certificate store of the operating system
in the CA certificate editing dialog.

b. Apply the changes to close the pop-up.

c. Repeat the configuration for the BGS_WEB communication channel, that is used for the URL
composition of certain web services. Enter the Host of the BGS, select HTTPS (TLS/SSL) for
Transport mode and select the same CA certificate (chain file) or use the Certificate store of
the operating system for CA certificate.

d. Apply the changes to close the pop-up.

5. Apply all changes and restart the GS.

7.2.2 Configuring Server Authentication for the GS

For enabling server authentication in the GS the following certificates have to be available:

• The GS server certificate has to be placed in the <GS_ROOT>/var/conf/cert directory.

• The corresponding CA certificate (chain) file has to be placed in the <GS_ROOT>/var/conf/cert


directory or in the certificate store of the operating system (see Using the certificate store of the
operating system).

Follow the steps 1. to 3. as described in Configuring Server Authentication for the BGS, thereby
replacing BGS with GS, i.e., using the GS Admin UI, GS server certificate and restarting the GS in the end
to configure server authentication for the GS.

Installation Guide 7-5


© 2019 Siemens
7. Configure AIG for TLS/SSL

7.2.3 Testing and Troubleshooting Server Authentication

To test the configuration start your BGS and GS using the bin64/debug executable. The debug start
keeps the command shell open so that you can see all log messages in the shell directly. This way you
can see error log messages, even if you cannot access the Admin UI to read log files (e.g., due to
misconfiguration).

To test the server authentication configuration of the Admin UI open a web browser and try to access it
via https://<bgs-host-address>:<bgs-ui-port> or https://<gs-host-address>:<gs-ui-port> respectively.
Make sure that you use the correct host address of the BGS/GS in the URL, which has to be the same as
used in the server certificates. For example, a certificate issued for the domain my.test.domain.com will
show a certificate error in the browser if you try to access the Admin UI using https://localhost:11320.

Open Scripts in the BGS and GS Admin UI and run the Test Communication Channels script to confirm
the correct configuration. Check that all test cases have been completed successfully.

There is one test case for each main communication channel, i.e., DEFAULT and DEFAULT_WEB for BGS
and GS and additionally BGS and BGS_WEB in the GS. If one or more test cases are failing, check the
configuration of the according communication channel again. Additionally, have a look at the
tpbgs64_netd.log and tpapps64_netd.log log files in the BGS Admin UI Log files → System or the
debug command shell of your BGS/GS for any error log messages.

For some detailed error messages and hints to solutions please refer to the chapter Troubleshooting.

7.3 Client Authentication


Using client authentication (also known as mutual authentication or two-way TLS) not only the client
verifies the certificate of the server, but also the server (e.g., your BGS or GS) requests and verifies the
certificate of the client (e.g., your GS or web browser) before continuing any communication. You can
choose to use the server authentication for BGS and/or GS as well as which server instances are affected.

7.3.1 Configuring Client Authentication for the BGS

For enabling client authentication in the BGS make sure you have configured server authentication in
the BGS successfully.

Additionally to the certificates needed for server authentication the BGS client certificate has to be
available in the BGS (<BGS_ROOT>/var/conf/cert) and each connected GS (<GS_ROOT>/var/conf/cert).

Follow these steps to configure client authentication in the BGS Admin UI on top of the server
authentication:

1. Open Configuration → Server instances and edit all server instances that should request and
verify a client certificate. Edit each relevant server instance and select the according CA certificate
(chain file) or use the Certificate store of the operating system in the CA certificate editing
dialog. Apply the changes to close the pop-up and proceed with the next server instance if needed.

7-6 Installation Guide


© 2019 Siemens
Configuring Client Authentication for the GS

To enable client authentication for the default BGS (web)services edit the properties of the SERVER
server instance. To operate the Admin UI using client authentication in the browser, edit the
ADMIN_UI20 server instance.

2. As for the server authentication, the BGS needs to be able to communicate with itself properly, so
you have to modify the properties for the communication additionally. The settings of the SERVER
server instance configured in step 1. have to match the properties of the communication channels
DEFAULT and DEFAULT_WEB.
Open the Configuration → Communication channels settings and edit each of these
communication channels. Select the previously copied client certificate in the Client certificate
editing dialog and press Apply to close the pop-up and continue with the next channel.

3. Apply all changes and restart the BGS.

4. Again, each connected GS has to know the properties for a secure communication with the BGS,
i.e., the settings of the SERVER server instance of the configured BGS have to match the properties
of the communication channels BGS and BGS_WEB in each connected GS. Therefore, open the
Configuration → Communication channels settings in the Admin UI of each connected GS and
edit those communication channels to select the client certificate in the Client certificate editing
dialog.

5. Apply all changes in each connected and edited GS and restart it.

7.3.2 Configuring Client Authentication for the GS

For enabling client authentication in the GS make sure you have configured server authentication in
the GS successfully.

Additionally to the certificates needed for server authentication the GS client certificate has to be placed
in the <GS_ROOT>/var/conf/cert directory.

Follow the steps 1. to 3. as described in Configuring Client Authentication for the BGS, thereby
replacing BGS with GS, i.e., using the GS Admin UI, GS client certificate and restarting the GS in the end
to configure client authentication for the GS.

7.3.3 Testing and Troubleshooting Client Authentication

Similar to the server authentication tests start your BGS and GS using the bin64/debug executable.

To test the client authentication configuration of the Admin UI you have to import the client certificate
to the browser or OS certificate storage first. For more information on how to do this, please refer to the
documentation of your web browser or operating system. Afterwards open your web browser and try to
access the Admin UI via https://<bgs-host-address>:<bgs-ui-port> or https://<gs-host-address>:<gs-ui-
port> respectively. The browser will ask you which client certificate you want to use for this page. If
everything works correctly, the login page will be shown.

Installation Guide 7-7


© 2019 Siemens
7. Configure AIG for TLS/SSL

Open Scripts in the BGS and GS Admin UI and run the Test Communication Channels script again to
confirm the correct configuration. Check that all test cases have been completed successfully.

If one or more test cases are failing, check the configuration of the according communication channel
again. Additionally, have a look at the tpbgs64_netd.log and tpapps64_netd.log log files in the BGS
Admin UI Log files → System or the debug command shell of your BGS/GS for any error log messages.

For some detailed error messages and hints to solutions please refer to the chapter Troubleshooting.

7.4 Encrypted Logging


Any log message sent from a log client to the log server is not encrypted by default. AIG provides two
different basic log configurations, which can be configured to send messages encrypted. For
performance reasons it is highly recommended to use the logging via UDP, if there is not any need to
force AIG running on TCP only (e.g., due to firewall configuration).

Though the log messages sent between log client and server are encrypted no matter which technique
you use, the log files themselves stored in the log root use an unencrypted binary format.

If it is required to run AIG completely encrypted, i.e., all server instances are using TLS/SSL and log
messages are sent encrypted, it is recommended to configure TLS/SSL first, before modifying the log
configuration. Configure server or client authentication for all server instances except LOG_SERVER first
and make sure it is working properly. Afterwards enable and test the encrypted logging. This way it is
easier to receive and view the error messages in the log files occurring during the configuration of TLS/
SSL. Any misconfiguration of the log encryption might result in log lines and files being skipped and
hence you will not be able to debug other issues.

7.4.1 Configuring Symmetric Encryption for Logging

By default AIG is configured to use logging via UDP (User Datagram Protocol), a protocol which does not
guarantee that every sent message is actually received, but provides a high performance. Therefore, it is
highly recommended to prefer this method. To encrypt log messages sent by AIG via UDP symmetric
encryption is used, i.e., the sender and receiver use the exact same password (shared secret) to encrypt
and decrypt messages. To enable the encryption in your log server and clients follow these steps:

1. Configure the log server to run in encrypted mode, i.e., the BGS expects all log messages that are
received to be encrypted. Open Configuration → Server instances in the BGS Admin UI and edit
the LOG_SERVER server instance. Turn the Encryption on and enter a common password used for
log server and clients in the Shared secret box (e.g., my-P4ssw0rd). Apply the settings to close
the pop-up.

Caution:
A log server with log encryption enabled ignores any unencrypted log messages received and
vice versa, encrypted log messages cannot be decrypted by a log server without log
encryption and are discarded.

7-8 Installation Guide


© 2019 Siemens
Configuring Symmetric Encryption for Logging

2. Since the BGS is not only a log server but also a client, additional settings have to be modified to
make sure that messages can be logged.

a. Open Configuration → Communication channels in the BGS Admin UI. If you have not
modified any advanced communication channel settings yet, you have to switch the
Configuration mode to Use advanced settings first, before editing the LOG communication
channel shown in the table.

b. Set the Transport mode to Encrypted socket (shared secret) and enter the exact same
password as used for the log server in the Shared secret text box (e.g., my-P4ssw0rd).
Apply the new settings to close the pop-up.

c. Apply all your changes and restart the BGS.

3. If the log configuration of the BGS has been tested successfully (see below), repeat the step 2.
above for all GS installations connected and logging to this BGS.

To test the log communication after restart, login to the Admin UI of the BGS, open Log → System and
check the most recent content (consider the timestamps in front of each log line) of several log files. For
example, check the tpbgs64*.log log channels as the BGS is usually logging to these during the start.
Similar you can check the tpapps64*.log log channels for each relevant GS in the same menu. Make
sure that log lines have been written recently and can be read.

If you do not see any new log lines or channels, the configuration of the log server (server instance) and
client (communication channel) do not match. Check the configuration again, make sure that the
encryption of the server instance and communication channel is turned on and that both are using the
exact same shared secret. Additionally run some tests to produce log lines (e.g., execute any test scripts)
and do not only check if proper log files have been created where expected, but also check the content
of the Log → User menu in the BGS Admin UI. It should not contain any log channels with cryptic names
and content as shown in the image beneath. If you do see any of these log files one of your clients is
using a different shared secret than the log server and hence producing unusable log content. Check the
configuration to find the log client which is either logging cryptic content or not at all to fix its log
configuration.

Installation Guide 7-9


© 2019 Siemens
7. Configure AIG for TLS/SSL

7.4.2 Configuring Logging via HTTP using TLS

If necessary (e.g., due to firewall settings) AIG can be configured to log via TCP (Transmission Control
Protocol) or more precisely HTTP instead of UDP. This is not the recommended way of logging since the
performance decreases in contrast to UDP.

It is possible to enable encryption when using this option, by using HTTPS instead of HTTP for the log
communication channel. In contrast to the UDP logging each log client does actually not send the log
messages to the LOG_SERVER but to the SERVER server instance of the BGS instead. Hence, when using
this approach the complete BGS communication settings are affected. Follow these steps to enable
encrypted logging using HTTPS:

1. Open Configuration → Server instances in the BGS Admin UI and modify the SERVER server
instance to enable server or client authentication as described in previous chapters.

2. Since the BGS is not only a log server but also a client, additional settings have to be modified to
make sure that messages can be logged.

a. Open Configuration → Communication channels in the same BGS Admin UI, switch the
Configuration mode to Use advanced settings if needed and modify the LOG
communication channel in the table shown.

b. Select HTTPS (TLS/SSL) for the Transport mode and the correct CA certificate (chain) file of
the BGS in the CA certificate editing dialog to enable server authentication for the log
communication. In case of client authentication you have to select the proper BGS client
certificate in the Client certificate editing dialog. Apply your changes to close the pop-up.

c. Apply all your changes and restart the BGS.

7-10 Installation Guide


© 2019 Siemens
Troubleshooting

3. If the log configuration of the BGS has been tested successfully (see beneath), repeat step 2. for all
GS installations connected and logging to this BGS.

To test the log communication start the BGS using the <BGS_ROOT>/bin64/debug executable, so that
you can check error messages in the command shell directly. Open Log → System in the BGS Admin UI
and check the most recent content (consider the timestamps in front of each log line) of several log
files. For example, check the tpbgs64*.log log channels as the BGS is usually logging to these during the
start. Similar you can check the tpapps64*.log log channels for each relevant GS in the same menu.

If you do not see any new log lines or channels, there might be something wrong with the
configuration. Check the output of the command shell for any TLS/SSL error messages. For some
detailed TLS/SSL error messages and hints to solutions please refer to the chapter Troubleshooting.

7.5 Troubleshooting
In this chapter some indications for typical errors occurring during the configuration and usage of
TLS/SSL and encrypted logging are provided. If you are not able to access the BGS Admin UI or read any
log files stop your BGS/GS and start it again using the <BGS_ROOT>/bin64/debug or <GS_ROOT>/bin64/
debug executable. The debug executable will start your BGS/GS as usual but keep a command shell open
showing the most recent log messages.

SSL/TLS handshake failures in the log output

Any error shown in the tpbgs64_netd.log, tpapps64_netd.log or in the command shell can provide
some more detailed information and hint regarding the error. Here are some messages you can
encounter and what could potentially be a reason for their appearance. However, this list is not
exhaustive. Other failure conditions may result in similar error messages.

• SSL error:140760FC:SSL routines:SSL23_GET_CLIENT_HELLO:unknown protocol


Unencrypted communication with an encrypted server. Check if the communication channel is
configured correctly.

• SSL error:14094418:SSL routines:ssl3_read_bytes:tlsv1 alert unknown ca


Server certificate is damaged or a wrong CA certificate (chain) file is configured in the communication
channel. Check the validity of your server certificate and if it matches the CA certificate you are using.

• SSL error:14089086:SSL routines:ssl3_get_client_certificate:certificate


verify failed
Client certificate could not be verified against CA certificate configured in the server.

• SSL error:14094415:SSL routines:ssl3_read_bytes:sslv3 alert certificate


expired
Server certificate is expired. Renew your certificates.

• SSL error:14094412:SSL routines:ssl3_read_bytes:sslv3 alert bad


certificate

Installation Guide 7-11


© 2019 Siemens
7. Configure AIG for TLS/SSL

Probably the Subject Alternative Name of the server certificate is not matching the host configured in
the according communication channel. Make sure that the correct host name is used in the
communication channel and in the server certificate.

• SSL error:0906D06C:PEM routines:PEM_read_bio:no start line


SSL error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib
Server certificate does not contain the private key. Make sure the server and client certificates contain
a certificate and private key section.

• SSL error:0906D06C:PEM routines:PEM_read_bio:no start line


SSL error:140DC009:SSL routines:SSL_CTX_use_certificate_chain_file:PEM lib
Server certificate file exists but it does not contain a certificate section. Make sure the server and
client certificates contain a certificate and private key section.

• SSL error:02001002:system library:fopen:No such file or directory


SSL error:20074002:BIO routines:FILE_CTRL:system lib
SSL error:140DC002:SSL routines:SSL_CTX_use_certificate_chain_file:system
lib
The selected certificate cannot be found. Check if the file exists in the <BGS_ROOT>/etc/cert or
<GS_ROOT>/etc/cert respectively. Check the spelling of the file, maybe it has been renamed.

Hanging AIG asking for pass phrase

A hanging AIG process showing Enter PEM pass phrase: in the command shell indicates that a
certificate with an encrypted private key is used. Hence, a pass phrase would be needed during the start
of each worker. Currently, AIG does not support an encrypted private key in the certificate files.

Certificate is not visible in the Admin UI

Make sure that the certificate file is available in <BGS_ROOT>/etc/cert or <GS_ROOT>/etc/cert


respectively. Check that the file has a *.pem file extension. If the files have just been copied after the
configuration pop-up in the Admin UI has already been opened, close and reopen the pop-up to refresh
the list of available certificate files.

7-12 Installation Guide


© 2019 Siemens
8. Job Server Installation
8.1 Job Server Configuration
The AIG Job Server is part of the AIG BGS installation and therefore does not require a separate
installation. It manages the jobs using a pool that caches all jobs. Furthermore, the BGS contains the
management interface for the AIG Job Server and the jobs. Therefore, it is also called job master.
Whenever this documentation mentions the AIG Job Server, it might imply client functionality as well.
Therefore, this chapter describes the complete configuration of the AIG job functionality – including the
steps on the server and on the client side.

In the BGS Admin UI, select the menu entry Configuration and the topic Job Server in the sidebar.
Three settings, as displayed in the screen shot beneath are shown.

• Storage path: path to the folder where the AIG Job Server stores the jobs. Default is:
<BGS_ROOT>/var/pool.

• Storage time (in days): defines how long executed jobs are stored in the pool. The Job Pool is
cleaned up regularly (every three minutes). All jobs which are in the state Finished, Application Error
or Runtime Error and which are older than the storage time defined here are removed.

• Maximum number of jobs: maximum number of jobs in the Job Pool.

AIG jobs are executed neither by the "tpbgs" nor by a "tpapps" process but rather by individual Job Agent
processes that will be started as child processes by "tpapps". Each GS may handle up to eight of those job
agents. In principle, a BGS can handle a very high number of job agents, but we recommend not using
more than 128 job agents with one BGS. If you need more job agents, please use additional AIG BGS
installations.

The following figure shows the main interactions between job agents and GS ("tpapps") / BGS ("tpbgs"):

Installation Guide 8-1


© 2019 Siemens
8. Job Server Installation

Caution:
Changing the Maximum number of jobs to a smaller number can only be done if the number of
the currently stored jobs is much smaller than the new pool size.

8.2 Job Agent Configuration


Before doing anything in order to use a AIG GS as a Job Agent, be sure to have its standard configuration
completed, i.e. it has to be able to connect to the BGS, etc.

In the GS Admin UI, click Configuration → Job Agent. By default, an empty table is displayed as shown
in the screen shot beneath, which means that there is no Job Agent yet. So this GS does not execute any
job.

8-2 Installation Guide


© 2019 Siemens
Job Agent Configuration

To create a new Job Agent instance, click on the plus icon in the upper right corner of the screen, which
will open a new pop-up window to configure a new agent (see screen shot beneath).

The following settings can be specified for each Job Agent:

• Status: defines whether the agent is activated or not.

• Active: By default, an agent is activated.

• Inactive: This setting can be used to deactivate an agent without losing its settings. An inactive Job
Agent does not actually exist and does not process any job; the BGS will not even try to assign one
to it.

• Job pattern defines the type of jobs this agent may execute, e.g. if not all of them have a correct
Teamcenter environment.

• Use Execute all jobs to allow this Job Agent to execute any job.

• Use Execute GS-jobs to allow this Job Agent to execute only jobs having the appropriate ERP flag
set.

Installation Guide 8-3


© 2019 Siemens
8. Job Server Installation

• Use Expert mode to allow this Job Agent to execute only jobs that match an Expert pattern which
can be specified. This expert pattern is matched against a job property value like the job description
or the job filter. If there is a match, the Job Agent is allowed to execute that job.
For proper functionality, different jobs have to be designed with different key words in their
descriptions or filter attributes in order to be distinguished by the Job Master.
Use * for any and ? for one or more occurrences of unknown (wild-card) characters. For example,
the pattern *ar? would match the key words start, star1, care, car5, park and art,
but not arch or warehouse.

Caution:
If you are using the expert mode, you can enter a comma separated list of patterns to enable
this Job Agent to process multiple patterns. But be aware that the order of the list will control
the order of the job processing! For example, if you enter car*,wheel* the Job Agent will first
process all jobs that match the first pattern car*. Only if no more jobs matching this pattern
have to be processed, the next pattern wheel* will be matched. So if you have for example
Jobs with the keyword wheel* that have a higher priority than jobs with car*, then these jobs
will still be processed after all jobs with car*.

In fact this Job pattern setting does not allow this Job Agent to execute a specific job, but it tells the
job master to assign a pending job to this Job Agent or not.

• Maximum idle memory size (in MB): in some cases a job leaves some memory allocated. In order to
prevent the amount of blocked memory from growing continuously, define the maximum size
allowed before the Job Agent will be restarted so that its memory will be released. The recommended
setting is 128 MB in Windows or 256 MB in UNIX, respectively.

For the first tests of Job Server, we recommend setting as easy and few restrictions as possible.

• 1 Job Agent only

• Execute all jobs

• 128 MB

Be sure to do all the basic testing with those easy settings before modifying them as desired, because
complex settings may result in complex error tracking.

8-4 Installation Guide


© 2019 Siemens
Set up Teamcenter Multi Connect for AIG Jobs

Caution:

• The number of active job agents is the number of rows with status activated. Each GS can host
up to eight Job Agent instances working independently, but in most cases, using only one is
recommended. Consider the quantity of jobs to expect and decide on the required number of
instances.

• To completely remove a Job Agent instance (not only deactivate it), click the "delete" icon in the
table row of the respective agent.

• In order to take the modifications into account, you have to click the "apply" button in the upper
right corner to save the changes and restart the GS.

• Now you should find three instead of two tpapps processes running. The third one is the Job
Agent process (one additional for each Job Agent)

• If you have activated the "external workers", you may find some more processes called "tpapps".

• The created Job Agent will now be visible in the Job management → Agents screen of the BGS
Admin UI of the corresponding Job Server. Depending on network load, etc., this may take up to
two minutes.

8.3 Set up Teamcenter Multi Connect for AIG Jobs


It is possible to work with different connection data for different types of jobs or for the jobs executed
by a specified Job Agent.

In addition, it is possible to set the Teamcenter connection data in the context of the job processing, so
that you can use different Teamcenter users for different job processing. The detailed connection data
configuration is specified by the following two specific procedures:

• for import and transfer jobs ::ITK::MULTI::CONNECT::setCredentialsAlias4Job

• for workflow jobs ::ITK::MULTI::CONNECT::setCredentialsAlias4Workflow

For a detailed description of the input parameters, see FN4T API Reference.

The mandatory parameters define the connection data itself, while the optional parameters define for
which jobs this data shall be applied. This means that a call with only two parameters is valid for all
kinds of jobs and the data is used as default if no more specific data is found. If no default data is set this
way, the default is taken from the settings defined by calling ::ITK::setCredentialsAlias. If no
connection data was set using ::ITK::MULTI::CONNECT::setCredentialsAlias4Job
or ::ITK::setCredentialsAlias, an attempt to connect via auto connect will be done.

Installation Guide 8-5


© 2019 Siemens
8. Job Server Installation

The following example shows how to use different Teamcenter users for different job agents:

set rc [::ITK::MULTI::CONNECT::setCredentialsAlias4Job
JobAgentCredentialsAlias 0]

set rc [::ITK::MULTI::CONNECT::setCredentialsAlias4Job
DefaultCredentialsAlias 1]

Caution:
The number to set in this function call parameter JobAgentId is the internal Job Agent number.
As counters begin with zero in TCL, the internal Job Agent number is the external job number
(shown in the Admin UI) minus one. Job agents are numbered and listed in the UI in creation
order.

Job Agent 0 (i.e. external Job Agent number 1 in the Admin UI) executes all "<T4x>_" jobs with
"testuser1" as Teamcenter user, whereas Job Agent 1 (i.e. external Job Agent number 2 in the Admin UI)
processes all "T4X_WF_BATCH" jobs as Teamcenter user "testuser2".

Additionally, standard and user attributes of jobs can be used to set different connection data. For
examples refer to the FN4T API Reference. The process to check for the connection data starts from the
most detailed Job Agent and attribute settings and iterates through the settings for job agents only
down to default. The first fitting connection setting found is used.

Setting the connection parameters for workflow jobs


using ::ITK::MULTI::CONNECT::setCredentialsAlias4Workflow works a bit different, since
jobs created by a workflow have an attribute "ITK_TC_USER_ID" filled with a user name of the reviewer or
assigner (depending on workflow). At the beginning of the job execution, the matrix with the
connection data will be checked for any data defined for the user name. If none is found, the default
data will be used. In case of default data not being set, an attempt for auto login will be made.

8-6 Installation Guide


© 2019 Siemens
9. Troubleshooting the AIG Process Start
If AIG BGS or GS could not be started, please check the following points:

• First check for the <BGS_ROOT>/tmp/scs.lock or <GS_ROOT>/tmp/scs.lock file.


Some AIG commands (especially start and stop) create a small file scs.lock in the tmp directory to
prevent other commands accessing this process during that time. After the successful execution, this
file is deleted. In some cases (mostly because of an improper process interruption, e.g., its command
window has been closed before it finished), this file remains and then the AIG processes will fail to
start.
Be sure there is no hanging process to start or stop a AIG process, then just delete the file scs.lock and
try again.

• The integrity of the shared memory file (<BGS_ROOT>/var/pef/share.ca or <GS_ROOT>/var/pef/


share.ca) is checked whenever it is opened. As a consequence, if the shared memory is broken (e.g.,
if it was damaged by a previous crash), AIG will not start anymore. If you execute the start via
command shell you will see the following error message:
ERROR: .../var/pef/share.ca integrity check failed. This shared memory
(share.ca) has to be deleted or repaired manually. How to dump and repair
manually: stop all processes and execute "bin64/shmdump -in var/pef/
share.ca" use a text editor to repair all "damaged" entries in
<t4x_root>/tmp/shm.dump delete or rename <t4x_root>/var/pef/share.ca start
"bin64/tpshell" and execute "source tmp/shm.dump" to import the repaired
shared memory NOTE if you delete <t4x_root>/var/pef/share.ca without
repairing you will lose all data dumped to tmp/shm.dump
If AIG does not start due to a failed shared memory integrity check, you can run the following steps
trying to repair the shared memory manually:

1. Stop all processes.

2. Execute bin64/shmdump in BGS or GS root directory.

3. Open the file tmp/shm.dump using a text editor.

4. Repair all entries beginning with # CHECK => damaged by editing them manually and save
the file.

5. Delete (or move) the damaged shared memory file var/pef/share.ca.

6. Start bin64/tpshell and execute source tmp/shm.dump.

After the execution of all these steps a new share.ca file will have been created and AIG will be able
to run again.

Installation Guide 9-1


© 2019 Siemens
9. Troubleshooting the AIG Process Start

9-2 Installation Guide


© 2019 Siemens
10. Use Nagios to monitor AIG
10.1 Nagios Introduction
Nagios (now known as Nagios Core) is free and open source software for monitoring systems, networks
and infrastructure. For more information, please visit https://www.nagios.org/.

Nagios can be used for monitoring the AIG infrastructure (e.g., the core server, log server, Job Server,
job agents). Therefore, Nagios needs access to the AIG installations, to servers as well as to clients. If
Nagios is already used in that environment for monitoring IT services, it can be used for checking AIG as
well. AIG provides these Nagios modules for monitoring:

• Base Server Module

• Log Server Module

• Job Server Module

• Job Agent Module

The AIG modules are tested with Nagios core 3.4.1.

Usually, Nagios is used to monitor the AIG BGS. Therefore, the Nagios modules are included in the BGS
installation. However, if you want to monitor your GS, simply copy the file <BGS_ROOT>/var/init/
start.ngs_server to the <GS_ROOT>/var/init directory to enable the base server module for your GS.

The following examples show how to test each module, which data is returned by AIG and how to define
the command in the Nagios configuration file commands.cfg. When using Windows, do set
TP_NCONHIDE=1 in the command shell before executing the Nagios module for test to keep the
command shell open.

10.2 Base Server Module


The AIG base server module works with the BGS and GS server. It monitors the memory and CPU usage
of the server as well as the server call statistics. The following optional parameters can be passed:

-memuse warninglevel;errorlevel memory usage in MB (default=0,0)


-calls warninglevel;errorlevel application calls per minute
(default=0,0)
-ecalls warninglevel;errorlevel application error calls per minute
(default=0,0)
-wcmd warninglevel;errorlevel application calls in waiting queue
(default=0,0)

Installation Guide 10-1


© 2019 Siemens
10. Use Nagios to monitor AIG

To test this module navigate to your BGS or GS directory and execute the following command in an OS
command shell:

bin64/tps var/init/start.ngs_server

T4x Base OK - MEM=278.6 MB CPU=4% WCMD=0 1/m CALLS=0 1/m ERRCALLS=0 1/m
|
MEM=278.6 CPU=4 WCMD=0 C=0 EC=0

Nagios command (example):

Nagios command (example):


define command {
command_name check_t4xbase
command_line cd /etc/nagios/plugins/bgs &&
bin64/tps var/init/start.ngs_server
}

10.3 Log Server Module


The AIG log server module works only with the BGS. The following optional parameters can be passed:

-pkg warninglevel;errorlevel packets per minute (default=0,0)


-epkg warninglevel;errorlevel errors per minute (default=0,0)

To test this module navigate to your BGS directory and execute the following command in a command
shell:

bin64/tps var/init/start.ngs_log

T4x Log OK - TRAFFIC=0.01 MB/m PKG=27 1/m EPKG=0 1/m |


TRAFFIC=0.01 PKG=27 EPKG=0

Nagios command (example):

define command{
command_name check_t4xlog
command_line cd /home/work/t4x_bgs &&
bin64/tps var/init/start.ngs_log
}

10-2 Installation Guide


© 2019 Siemens
Job Server Module

10.4 Job Server Module


The AIG Job Server module works only with the BGS. The following optional parameters can be passed:

-poolsz warninglevel;errorlevel job-pool-size in % (default=0,0)


-ready warninglevel;errorlevel number of ready jobs (default=0,0)
-running warninglevel;errorlevel number of running jobs (default=0,0)
-waiting warninglevel;errorlevel number of waiting jobs (default=0,0)
-apperror warninglevel;errorlevel number of jobs in application error
(default=0,0)
-rterror warninglevel;errorlevel number of jobs in runtime error
(default=0,0)
-finish warninglevel;errorlevel number of finish jobs (default=0,0)

To test this module navigate to your BGS directory and execute the following command in a command
shell:

bin64/tps var/init/start.ngs_batch

T4x job OK - POOLSZ=0% READY=1 RUN=0 WAIT=2 AERR=2 RERR=4 FIN=4 |


POOLSZ=0 READY=1 RUN=0 WAIT=2 AERR=2 RERR=4 FIN=4

Nagios command (example):

define command{
command_name check_T4xJobs
command_line cd /home/work/t4x_bgs &&
bin64/tps var/init/start.ngs_batch
}

10.5 Job Agent Module


The AIG Job Agent module works only with BGS. This module does not provide any additional
parameters.

To test this module navigate to your BGS directory and execute the following command in a command
shell:

bin64/tps var/init/start.ngs_batchclient

T4x Job Agent CRITICAL - oberon (SunOS)/16612 winab100-64 (Windows NT)/


3516
winab100 (Windows NT)/520 win28ab91r2 (Windows NT)/3672 winab100

Installation Guide 10-3


© 2019 Siemens
10. Use Nagios to monitor AIG

(Windows NT)/2516
winab100 (Windows NT)/2516 win2008-t43-83 (Windows NT)/2628 - BCLCNT=19
| BCLCNT=19

Nagios command (example):

define command{
command_name check_t4xjobagent
command_line cd /home/work/t4x_bgs &&
bin64/tps var/init/start.ngs_batchclient
}

10-4 Installation Guide


© 2019 Siemens
A. Glossary
A
ABAP
ABAP is a proprietary programming language of the SAP AG.

Admin
is the term used in this document for people who install and configure Teamcenter and its components.
This is in contrast to the "user" role.

Admin UI
Web based administrative user interface of the GS and BGS.

AIG
The entire Active Integration Gateway product family.

AIG_ROOT
Please see GS_ROOT and BGS_ROOT. This term is used if something is true for both the GS and BGS.

AI-Object
Application-Interface Object

API
Application Programming Interface.

Apps
See "GS".

AppServer
Application Server.

B
BAPI
The Business Application Programming Interface allows external programs to access objects and
business processes in SAP.

BGS
Basic Gateway Service.

Installation Guide A-1


© 2019 Siemens
A. Glossary

BGS_ROOT
The installation directory of the Basic Gateway Service (e.g. C:\Siemens\BGS).

BMIDE
Teamcenter Business Modeler IDE (Integrated Development Environment)

BOM
A Bill Of Materials is a list of the parts or components and their quantities that are required to build a
product.

BOM Header
A BOM Header is the top item of a BOM. BOMs can have multiple levels, so this often means the top
item of the actual level.

BOP
The Bill Of Process describes a manufacturing process and lists the operations and steps with all their
instructions, consumed materials, resources, work places and machines.

C
CCObject
Collaboration Context Object

CEP
Camstar Enterprise Platform

Change Master
The Engineering Change Master (ECM) contains the metadata to a change number.

Characteristic
An characteristic is an attribute of a SAP class.

CIO
Camstar Interoperability

D
Data Carrier
Please see Vault.

A-2 Installation Guide


© 2019 Siemens
Dataview
The Dataview is an extension to the Teamcenter RAC and is deployed as part of the TEM installation
process of the Teamcenter Gateway. The Dataview is used to display the real-time data of external
applications, associated with Teamcenter objects.

Dataview mark-up
is the language understood by the Dataview. The Dataview receives messages written in this language
from the T4x server. Such messages can be formatted as XML or JSON. Normally users do not see such
messages. They may however appear in log files or error messages. The so called prop mapping (e.g.
t4s_prop_mapping_template.sd) contains TCL commands that compose messages in the Dataview
mark-up.

DCD
Data Collection Definition

DIR
DIR is the abbreviation for a SAP Document Info Record.

Document Key
A Document Info Record is identified by the combination of Document Type, Document Number,
Document Part and Document Version.

Document Structure
A Document Structure is like a Bill Of Materials for Documents.

E
EA
stands for Enterprise Application, any software or set of computer programs used by business users to
perform various business functions in context of current integration's portfolio with Teamcenter.

ECN
The Engineering Change Notice can also be called an Engineering Change Note, Engineering Change
Order (ECO), or just an Engineering Change (EC).

EPM
Enterprise Process Modeling

EWI
Electronic Work Instructions

Installation Guide A-3


© 2019 Siemens
A. Glossary

F
File Stream
Method of transfer to send an original to SAP.

FN4S
Closed Loop Manufacturing for SAP S/4HANA®

G
Gateway Menu
An additional menu item of the Teamcenter Gateway software available in the Teamcenter RAC.

GRM
The Generic Relationship Management provides a general way in which two objects can be associated
via a relationship.

GS
Gateway Service, manages the communication between Enterprise Applications.

GS_ROOT
The installation directory of the Gateway Service (e.g. C:\Siemens\GS).

GUI
Graphical user interface.

GUID
Globally Unique Identifier

I
IDGEN
The IDGEN is a mechanism to get an external ID from the ERP system when assigning a Teamcenter ID.

Inspection Plan
Contains characteristics to be inspected in an operation and equipment to be used.

iPPE
Integrated Product and Process Engineering is a module that can be used to mange products with many
variants.

A-4 Installation Guide


© 2019 Siemens
ITK
The Integration Toolkit (ITK) is a set of software tools provided by Siemens PLM Software that you can
use to integrate third-party or user-developed applications with Teamcenter.

J
JCO
The Java Connector is an interface to . In the context of it is now mostly replaced by the Netweaver RFC
interface.

JDBC
Java Database Connectivity is an application programming interface (API) for the programming language
Java, which defines how a client may access a database.

Job
Teamcenter Gateway features asynchronous transfer. This datatransfer is managed via a Job.

Job Pool
The Job Pool contains all finished and unprocessed Jobs. It is managed by the BGS.

Job Server
The Job Server on the Basic Gateway Service (BGS) manages the Job and distribution them to the Job
Agent for processing.

JSON
JavaScript Object Notation is a lightweight data-interchange format1.

K
KPro
Kpro stands for Knowledge Provider. See also Data Carrier.

L
LOV
List of Values

1 JSON.org

Installation Guide A-5


© 2019 Siemens
A. Glossary

M
Mapping
The mapping is part of the T4x configuration. It contains the code that controls the behavior of the data
transfer between Teamcenter and the ERP system.

MFK
Multi-key functionality in Teamcenter.

MM
MM is the abbreviation for a SAP Material Master.

MOM
Manufacturing Operations Management

N
NCN
Non-Conformance Notification

NetWeaver RFC SDK


The NetWeaver RFC SDK contains libraries for 3rd party applications to connect to . It can be obtained
from the SAP ONE Support Launchpad.

O
Object Key
The Object Key is a string that contains the ID of an Enterprise Application object. If the identifier is a
combination of multiple keys, then the Object Key is a combination of those keys in a defined order and
format.

Object Link
A relation between SAP objects like Material Master and Document Info Record.

Object Management Record


Belongs to a SAP Change Number and Documents changes of one particular SAP object like a Material
Master.

OOTB
Out of the box

A-6 Installation Guide


© 2019 Siemens
Original
A representation of a file in SAP.

OSS Note
The OSS Note is an online patch service for SAP. The patch can be identified by the OSS Notes number.

P
PIR
PIR is an abbreviation for a SAP Purchase Info Record.

Portal Transaction
This means that a transfer to SAP that is not triggered by a workflow handler but via the Gateway Menu.

R
RAC
stands for Rich Application Client also referred to as rich client or portal.

Revision Level
Used to show changes with reference to a change to a SAP Material Master or Document Info Record.

RFC
Remote Function Call (SAP)

S
SAP
SAP S/4HANA® / SAP Business Suite®

SAP GUI
This is the application for the SAP Business Suite® and SAP S/4HANA®.

SAP Logon
This is the application that a user needs to start the SAP GUI for a particular system. It may also refer to
the process of logging in to SAP in Teamcenter via .

SAP Portal iView URL


Can be used to show sap content in a browser window.

Session Log
Shows one log file for each Teamcenter session. Written if T4x transactions are executed

Installation Guide A-7


© 2019 Siemens
A. Glossary

SSL
Secure Sockets Layer.

T
T4O_ROOT
Please see GS_ROOT

T4S 4-Tier Client (SAP Lite)


The 4-Tier Client or SAP Lite is a stripped down GS. It´s only purpose is to open the SAP GUI on a
Teamcenter 4-Tier Client.

T4x
The entire Teamcenter Gateway product family.

TAO
The ACE ORB is a open-source and standards-compliant real-time C++ implementation of CORBA based
upon the Adaptive Communication Environment (ACE).

TargetTypeName
This is the T4x internal name for the transaction type. E.g. MaterialMaster or
DocumentInfoRecord.

TC
Teamcenter

TCL
is a high-level, general-purpose, interpreted, dynamic programming language.

TCPCM
Teamcenter Product Cost Management

TCPCM4S
Teamcenter Product Cost Management Gateway for SAP S/4HANA

TEM
Teamcenter Environment Manager

Transaction Code
A Transaction Code is a quick access code for a Transaction in the SAP GUI:

A-8 Installation Guide


© 2019 Siemens
Transaction Log
The Transaction Log is a T4x logfile on the BGS. It contains log information for a specific T4x transaction.

Transfer Window
The Transfer Window triggers transactions via the Gateway Menu.

Transport Package
A file that contains functions that can be imported to SAP.

U
UOM
UOM stands for Unit of Measure.

URI
Unified Resource Identifier: a generalized from of a resource locator (URL) and resource name (URN),
which just identifies a resource, but is not necessarily sufficient to locate (find) the resource. URIs are
often used to identify configurations in Java and other languages. See https://en.wikipedia.org/wiki/
Uniform_Resource_Identifier for more details.

URL
Unified Resource Locator: a string with a certain format, allowing to load a resource from a network.
URLs are a specific form or URNs.

User Exit (SAP)


A User Exit is a code for a program that is called if an object like an MaterialMaster has been changed or
updated. In the context of T4S it is often used to initiate the process to trigger a transfer from SAP to
Teamcenter.

User Log
The User Log is a T4x logfile on the BGS. If you define a customized logchannel, the information is
written into a User Log of that name.

V
Value Set
A Value Set is the SAP term for a list of selectable values for a characteristic.

Installation Guide A-9


© 2019 Siemens
A. Glossary

Vault
The Vault is a server where a SAP DocumentInfoRecord original is stored. A synonym is also Data Carrier.

W
WBS
WBS is an abbreviation for a SAP Work Breakdown Structure.

X
XML
Extensible Markup Language is designed to store and transport data in a format that is both human- and
machine-readable.

XRT
stands for XML Rendering Template, also known as XML Rendering Stylesheet. These are XML
documents stored in datasets that define how parts of the Teamcenter user interface are rendered. They
are used for the Rich Client as well as the Active Workspace.

Z
ZPTC
This is the short name for a Z-Table with the name /TESISPLM/ZPTC, used to trigger a transfer from SAP.

Z-Table
"Z" is a well-known prefix name for custom tables in the SAP world. A special table used with is the
table /TESISPLM/ZPTC.

A-10 Installation Guide


© 2019 Siemens
Siemens Industry Software
Headquarters Europe
Granite Park One Stephenson House
5800 Granite Parkway Sir William Siemens Square
Suite 600 Frimley, Camberley
Plano, TX 75024 Surrey, GU16 8QD
USA +44 (0) 1276 413200
+1 972 987 3000

Asia-Pacific
Americas Suites 4301-4302, 43/F
Granite Park One AIA Kowloon Tower, Landmark East
5800 Granite Parkway 100 How Ming Street
Suite 600 Kwun Tong, Kowloon
Plano, TX 75024 Hong Kong
USA +852 2230 3308
+1 314 264 8499

About Siemens PLM Software


Siemens PLM Software is a leading global © 2019 Siemens. Siemens, the Siemens
provider of product lifecycle management logo and SIMATIC IT are registered
(PLM) software and services with 7 million trademarks of Siemens AG. Camstar, D-
licensed seats and 71,000 customers Cubed, Femap, Fibersim, Geolus, I-deas, JT,
worldwide. Headquartered in Plano, Texas, NX, Omneo, Parasolid, Solid Edge,
Siemens PLM Software works Syncrofit, Teamcenter and Tecnomatix are
collaboratively with companies to deliver trademarks or registered trademarks of
open solutions that help them turn more Siemens Industry Software Inc. or its
ideas into successful products. For more subsidiaries in the United States and in
information on Siemens PLM Software other countries. All other trademarks,
products and services, visit registered trademarks or service marks
www.siemens.com/plm. belong to their respective holders.

You might also like