Teamcenter Gateway

for Enterprise
Applications
—
Installation Guide
Teamcenter Gateway for Enterprise Applications 22.1
Unpublished work. © 2022 Siemens

This Documentation contains trade secrets or otherwise confidential information owned by Siemens Industry Software Inc. or
its affiliates (collectively, “Siemens”), or its licensors. Access to and use of this Documentation is strictly limited as set forth in
Customer’s applicable agreement(s) with Siemens. This Documentation may not be copied, distributed, or otherwise disclosed
by Customer without the express written permission of Siemens, and may not be used in any way not expressly authorized by
Siemens.

This Documentation is for information and instruction purposes. Siemens reserves the right to make changes in specifications
and other information contained in this Documentation without prior notice, and the reader should, in all cases, consult
Siemens to determine whether any changes have been made.

No representation or other affirmation of fact contained in this Documentation shall be deemed to be a warranty or give rise to
any liability of Siemens whatsoever.

If you have a signed license agreement with Siemens for the product with which this Documentation will be used, your use of
this Documentation is subject to the scope of license and the software protection and security provisions of that agreement. If
you do not have such a signed license agreement, your use is subject to the Siemens Universal Customer Agreement, which
may be viewed at https://www.sw.siemens.com/en-US/sw-terms/base/uca/, as supplemented by the product specific terms
which may be viewed at https://www.sw.siemens.com/en-US/sw-terms/supplements/.

SIEMENS MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS DOCUMENTATION INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF
INTELLECTUAL PROPERTY. SIEMENS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL OR
PUNITIVE DAMAGES, LOST DATA OR PROFITS, EVEN IF SUCH DAMAGES WERE FORESEEABLE, ARISING OUT OF OR RELATED TO
THIS DOCUMENTATION OR THE INFORMATION CONTAINED IN IT, EVEN IF SIEMENS HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.

TRADEMARKS: The trademarks, logos, and service marks (collectively, "Marks") used herein are the property of Siemens or other
parties. No one is permitted to use these Marks without the prior written consent of Siemens or the owner of the Marks, as
applicable. The use herein of third party Marks is not an attempt to indicate Siemens as a source of a product, but is intended to
indicate a product from, or associated with, a particular third party. A list of Siemens’ Marks may be viewed at:
www.plm.automation.siemens.com/global/en/legal/trademarks.html. The registered trademark Linux® is used pursuant to a
sublicense from LMI, the exclusive licensee of Linus Torvalds, owner of the mark on a world-wide basis.

About Siemens Digital Industries Software

Siemens Digital Industries Software is a leading global provider of product life cycle management (PLM) software and services
with 7 million licensed seats and 71,000 customers worldwide. Headquartered in Plano, Texas, Siemens Digital Industries
Software works collaboratively with companies to deliver open solutions that help them turn more ideas into successful
products. For more information on Siemens Digital Industries Software products and services, visit www.siemens.com/plm.

Support Center: support.sw.siemens.com

Send Feedback on Documentation: support.sw.siemens.com/doc_feedback_form

 Contents

Preface 7

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 and Scaling Considerations ─────────────────── 2-3
High-availability Cluster ─────────────────────── 2-9

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

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 the target machine ────────────── 5-11
File System Hardening ────────────────────────── 5-12
Upgrade an Existing AIG Installation ───────────────── 5-14
Select the 22.1 software package ───────────────────── 5-14
Securing of critical files ───────────────────────── 5-15
Initializing AIG ─────────────────────────── 5-17
Security Considerations ───────────────────────── 5-18
Initialization Prerequisites ──────────────────────── 5-19
Initializing the BGS ─────────────────────────── 5-21
Registering the GS ─────────────────────────── 5-23
TLS/SSL Configuration ────────────────────────── 5-26
Running as Windows Services ────────────────────── 5-27
Operating AIG with multiple OS users ─────────────────── 5-29
Basic Configuration in the Admin UI ───────────────── 5-31
User Management ─────────────────────────── 5-32
Setting the License Server ──────────────────────── 5-33
Changing Ports ───────────────────────────── 5-34

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 3
© 2022 Siemens
 Setting the BGS Server ────────────────────────── 5-36
Verifying the Installation ───────────────────────── 5-37
Teamcenter Templates ─────────────────────── 5-37
Template Content ──────────────────────────── 5-37
Compatibility with other Templates ──────────────────── 5-39
Deploy Active Integration Templates with Deployment Center ───────── 5-39
Deploy AIG Template with TEM ────────────────────── 5-40
Configuring the Mapping ────────────────────── 5-43
Configure Teamcenter Environment for AIG ────────────── 5-44
Set AIG GS Environment for a Teamcenter 2-Tier Environment ───────── 5-44
Set AIG GS Environment for a Teamcenter 4-Tier Environment ───────── 5-45
Add AIG Error Message Texts to Teamcenter ──────────────── 5-45
Connectivity to Teamcenter ─────────────────────── 5-46
Configure AIG Environment for Teamcenter ────────────── 5-46
Installation of additional components ──────────────── 5-46
Install a JDBC Driver to connect to a database ──────────────── 5-46
Install AXIS2 for using SOAP services ──────────────────── 5-47
Install CXF for using SOAP services ──────────────────── 5-48
Install a provider for JMS Messaging ──────────────────── 5-48
Integration of Redis/ LevelDB as global SHM storage ────────── 5-49

Configure AIG for TLS/SSL

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

Job Server Installation

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

Troubleshooting AIG Startup Errors 8-1

Monitoring AIG
Monitoring Introduction ─────────────────────── 9-1

4 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Contents

Implementation Example via Telegraf™, InfluxDB® and Grafana® Software

──────────────────────────────── 9-7
Use Nagios® to Monitor AIG (deprecated) ─────────────── 9-10

Glossary A-1

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5
© 2022 Siemens
6 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 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: May 2022

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 Active Integration Gateway 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.

© 2002-2022 Siemens Industry 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 Industry 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.

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse,
this product.

Telegraf™ is a trademark owned by InfluxData, which is not affiliated with, and does not endorse, this
product.

The Grafana® Word Mark and Grafana Logo are either registered trademarks/service marks or
trademarks/service marks of Coding Instinct AB, in the United States and other countries and are used
with Coding Instinct’s permission. We are not affiliated with, endorsed or sponsored by Coding Instinct,
or the Grafana community.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 7
© 2022 Siemens
 Nagios®, the Nagios logo, and Nagios graphics are the servicemarks, trademarks, or registered
trademarks owned by Nagios Enterprises, which is not affiliated with, and does not endorse, this
product.

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

Acknowledgements

This product includes numerous open source components. For more information, please refer to the
readme on OSS in the download section. In particular we like to point out:

Contains portions or was derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://
www.openssl.org/) This product includes cryptographic software written by Eric Young
([email protected]).

8 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 1. Introduction
This manual explains the installation of the Active Integration Gateway (AIG) software, version 22.1.

The term AIG refers to the entire Active Integration Gateway product family, including:

S4S Teamcenter Integration for SAP S/4HANA

T4S Teamcenter Gateway for SAP Business Suite
T4S4 Teamcenter Gateway for SAP S/4HANA
T4ST Teamcenter Gateway for PLM system integration by SAP
T4O Teamcenter Gateway for Oracle EBS
T4EA Teamcenter Gateway for Enterprise Applications
T4CEP Teamcenter Gateway for Camstar Enterprise Platform
FN4T Opcenter Connect FN for Teamcenter
FN4S Opcenter Connect FN for SAP S/4HANA
TCPCM4S Teamcenter Product Cost Management Gateway for SAP S/4HANA
TCPCM4EA Teamcenter Product Cost Management Gateway for Enterprise Applications
TCPCM4T Teamcenter Product Cost Management Gateway for Teamcenter
RDL4T Opcenter Connect RDL for Teamcenter
QL4T (T4EA) Opcenter Connect Quality for Teamcenter
CN4T Opcenter Connect CN for Teamcenter

Caution:
This document describes the general installation of the Active Integration Gateway (AIG) software.
The term AIG will therefore be used to refer to any of the above products.

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

For more details about AIG in general, please refer to the appropriate AIG documentation.

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

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 1-1
© 2022 Siemens
 1. Introduction

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

1-2 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 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 Discrete please visit Active Integration
Software Certifications.

2.2 Web Browser

For administrative AIG tasks including configuration of the AIG software, an Admin UI is provided for
each of AIG's two main components, known as BGS and GS. In order to use it, you need an up-to-date
web browser. Please refer to Teamcenter Certifications and Information in the section for the current
"in maintenance Teamcenter versions" to see which browser versions are supported.

Caution:
• Using a web browser that is not listed as supported is not recommended.

• There is no guarantee that a browser version older than a supported version will work correctly
with the AIG Admin UI.

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

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

2.3 Operating Systems

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

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" set to a number greater than 2048. We recommend
the number 4096. To verify and configure this setting, please consult the operating system
documentation.
Windows only: The Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019 is
required for Active Integration Gateway (both BGS and GS) on any Windows system. If this
software is not installed correctly, then AIG's BGS and GS components will be unable to start and

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 2-1
© 2022 Siemens
 2. Supported Environment

an error message will be displayed. The latest download links to this package can be found at
https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads.

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 on a single server due to excessive CPU
and RAM demands. For best performance, install 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 instance to have a specific password manager installed. For
details, see Initialization Prerequisites.

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 an AIG-native TCP protocol.

2-2 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Sizing and Scaling Considerations

2.5 Sizing and Scaling Considerations

Definitions

Sizing - How much resources (CPU, Hosts, …) are needed to process the workload.

Scaling - How to design the system architecture that the workload can processed with the defined
resources (Job Agents, Threads, …).

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 8 GB 8 GB 8 GB
Linux 8 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; the maximum is 4,000,000. A Job Pool needs a minimum of 32 GB of disk space and and
can grow up to 64 GB.

Calculate log file storage size

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

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

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 2-3
© 2022 Siemens
 2. Supported Environment

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 adjusting the BGS Admin UI → Configuration → Log server →
Advanced Settings tab → Compression setting. For more information on this setting, refer to the
chapter Log Server in the Admin UI Guide. In rare cases, the original log file could become blocked (e.g.,
because someone accessed it right in that moment), which prevents the compression from finishing. In
that case, you might see an error log line similar to "tpco_udpCompressLogChannel :: cannot delete
original log file ...", but your log files will work as usual.

Sizing and Scaling of BGS

The recommendation how to size the BGS is described above.

To scale the BGS it is possible to define threads on the Admin UI of the BGS. The maximum number of
threads should not be higher than 16. In most of the cases 8 threads are sufficient. To optimize the
performance of AIG it is very important that the BGS can write very fast to the hard disk. It is also
recommended that the folder in which the BGS is writing log information is not monitored by a virus
scanner. Please also consider the recommendations in the following chapter about virtualization of AIG
components.

It is strongly recommended to use only one BGS in one system environment. Moreover, it is strongly
recommended that the BGS is running on a host without any other software components like for
example the Teamcenter Pool Manager. Please also consider the recommendations in the following
chapter about virtualization of AIG components.

Sizing and Scaling of GS

The recommendation how to size the GS is described above.

To scale the GS it is possible to define threads on the Admin UI of the GS. The maximum number of
threads should not be higher than 16. It is also possible to define a higher number of job agents to
process more jobs in parallel.

Furthermore, it is possible to scale AIG by using more than one GS in different ways:

1. Install one GS on the host (4tier) / Install one GS on the client (2tier) → Scale by using more
threads or job agents

Pro: economical, simplest way of administration until to certain extent

2-4 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Sizing and Scaling Considerations

Cons: uneconomical if the complexity gets to high (long maintenance windows, high effort in
debugging performance issues on the host), missing failover cluster if only one host exists

Note:
It is strongly recommended to NOT install more than one GS on a host. It is possible to
increase the number of threads or job agents with a second GS. But more than one GS on a
host does not reduce the complexity to simplify the administration of a server.

2. Install one GS on the host (4tier) → Scale by using more hosts

Pro: reduces the above described complexity on a server, automatic failover cluster

Cons: more expensive

Note:
Use virtualization of AIG components to reduce costs.

Caution:
It is strongly recommended to: one GS - one Host

Virtualization

There is no technical issue which speaks against the virtualization of AIG components (BGS, GS). The
only clear recommendation is not to overcommit the resources of a host by too many virtual machines.

The BGS needs his own host and this host must be up at any time.

The GS must be up if it should handle something. If a GS is not up because missing resources on the
host the performance could be reduced or maybe there is no failover cluster anymore.

Exemplary procedure to size and scale AIG environments

1. Project scope

Transfer data between Teamcenter and SAP/ Enterprise Application

2. Assumption

All servers are virtualized. Please remember: Do not overcommit the resources of a host!

3. Installed products

Teamcenter , T4S / T4S4 and T4EA

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 2-5
© 2022 Siemens
 2. Supported Environment

4. AIG environments

• Development environment

50 Teamcenter users, 20 concurrent Teamcenter users, 1 concurrent user for synchronous

import transactions

• Test environment

500 Teamcenter users, 300 concurrent Teamcenter users, 2 concurrent users for synchronous
import transactions

• Production environment

8000 Teamcenter users, 4000 concurrent Teamcenter users, 5 concurrent users for synchronous
import transactions

5. Transfer use cases

• Synchronous export (triggered by Teamcenter workflow) and import (synchronous triggered by

an Enterprise Application) transactions

• Asynchronous import transactions (asynchronous AIG jobs)

6. Sizing proposal

• Development environment

BGS

50 Teamcenter users => 500 GB disc space

6 GS threads => 6 BGS threads

Use 1 core for 4 threads => 6 / 4 = 1.5 => 2 cores

=> Recommendation (AIG only) for first performance tests:

1 BGS (6 threads) host with 8 GB free RAM and 2 Cores

GS

1 concurrent user for synchronous import transactions:

1 * 1-2 connections to TC per user * 2 GB memory per thread

(connection to TC = ITK pipe) = 4 GB memory

2-6 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Sizing and Scaling Considerations

20 concurrent Teamcenter users => 10% concurrent AIG users for synchronous export
transactions (0.1 * 20 = 2):

2 * 1 connection to TC per user * 2 GB memory per thread

(connection to TC = ITK pipe) = 4 GB memory

2 Job Agent for asynchronous import transactions:

2 * 1 connection to TC per user * 2 GB memory per thread

(connection to TC = ITK pipe) = 4 GB memory

=> Number of threads: 6

=> Memory: 12 GB

=> Use 1 core for 4 threads => 6 / 4 = 1.5

=> Recommendation (AIG only) for first performance tests:

1 GS (6 threads) host with 12 GB free RAM and 2 Cores

• Test environment

BGS

500 Teamcenter users => 1 TB disc space

16 GS threads => 8 BGS threads

Use 1 core for 4 threads => 8 / 4 = 2 => use 2 cores for BGS

=> Recommendation (AIG only) for first performance tests:

1 BGS (8 threads) host with 32 GB free RAM and > 2 Cores

GS

2 concurrent users for synchronous import transactions:

2 * 1-2 connections to TC per user * 2 GB memory per thread

(connection to TC = ITK pipe) = 8 GB memory

300 concurrent Teamcenter users => 10% concurrent AIG users for synchronous export
transactions (0.1 * 300 = 30):

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 2-7
© 2022 Siemens
 2. Supported Environment

30 * 1 connection to TC per user * 2 GB memory per thread

(connection to TC = ITK pipe) = 60 GB memory

2 Job Agent for asynchronous import transactions:

2 * 1 connection to TC per user * 2 GB memory per thread

(connection to TC = ITK pipe) = 4 GB memory

=> Number of threads: 36 => use max. 16 threads per GS (no performance optimization
anymore)

=> Memory: 72 GB => use 64 GB RAM per GS (no performance optimization anymore)

=> Use 1 core for 4 threads => 16 / 4 = 4 => use 4 cores for AIG (no performance
optimization anymore)

=> Recommendation (AIG only) for first performance tests:

1 GS (16 threads) host with 64GB free RAM and > 4 Cores

• Production environment

BGS

8000 Teamcenter users => 2 TB disc space

=> Recommendation (AIG only) for first performance tests:

1 BGS (8 threads) host with 32 GB free RAM and 5 Cores

GS

5 concurrent users for synchronous import transactions:

5 * 4-8 connections to TC per user * 2 GB memory per thread

(connection to TC = ITK pipe) = 80 GB memory

4000 concurrent Teamcenter users => 10% concurrent AIG users for synchronous export
transactions ( 0.1 * 4000 = 400):

400 * 1 connection to TC per user * 2 GB memory per thread

(connection to TC = ITK pipe) = 800 GB memory

2 Job Agent for asynchronous import transactions:

2-8 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 High-availability Cluster

2 * 1 connection to TC per user * 2 GB memory per thread

(connection to TC = ITK pipe) = 4 GB memory

=> Number of threads: 442 => use max. 16 threads per GS (no performance optimization
anymore)

=> Memory: 884 GB => use 64 GB RAM per GS (no performance optimization anymore)

=> Use 1 core for 4 threads => 442 / 4 = 111 => use 5 cores for AIG (no performance
optimization anymore)

=> Recommendation (AIG only) for first performance tests:

min. 6 GS (16 threads) hosts with 64 GB free RAM and 5 Cores each

Install one GS per TC pool manager

Maybe move Job Agents on dedicated host(s).

2.6 High-availability Cluster

In an AIG installation, the BGS is often considered the single point of failure. To increase the operational
readiness of the AIG BGS server, existing high-availability cluster implementations of the operating
systems can be used. The AIG BGS can be operated with these clusters in such a way that one instance
of the server is always available. In order to protect the data of the AIG BGS, these can be stored on
redundant storage systems. Snapshots of the internal databases of the AIG BGS can also be created and
stored as a backup.

Pacemaker can be used to implement a high-availability cluster under Linux. For Windows servers, the
Microsoft Windows Failover Cluster (WFC) is available.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 2-9
© 2022 Siemens
 2. Supported Environment

2-10 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 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 related to AIG.

This documentation will give you basic information about the Admin UI and how to access it. Detailed
information on the individual applications contained within it can be found in the Admin UI Guide.

Menu Functionalities Overview

Both BGS and GS have their own interfaces 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 a stack trace 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 the application (however, it is recommended to use the executable bin64/restart).

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

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 3-1
© 2022 Siemens
 3. Admin UI

BGS-exclusive menu entries are:

• Job management: Control jobs and job agents.

• Log files: View and analyze transaction, system, workflow, 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 BGS or GS is installed and configured correctly. Please see Installation Instructions.

• Be sure BGS or GS is running. If not, start it with <AIG_ROOT>/bin64/restart or start the corresponding
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 at https://<URL of BGS>:11320

The GS Admin UI can be reached by default at 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 Initializing the BGS. 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 Guide (see
below).

3-2 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Admin UI Troubleshooting

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 the Admin UI Troubleshooting and
Web Browser sections of this installation guide.

Admin UI Guide

In the Admin UI you can access the Admin UI Guide in a new browser tab by clicking on the question
mark (?) in the upper right corner at any time.

3.2 Admin UI Troubleshooting

If anything behaves unusually in the AIG Admin UI (or behaves 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 browsers, please refer to Web Browser.

• Enable JavaScript for full AIG functionality

• Delete the web browser cache and cookies

• Restart the web browser after the above step

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

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 3-3
© 2022 Siemens
 3. Admin UI

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

• Open Tools → Compatibility View Settings in Internet Explorer

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

• Close the dialog

3-4 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 4. The Active Integration Gateway (AIG)
Architecture
AIG is integration software for enabling bidirectional data integration and process coupling, including
between Teamcenter and other enterprise applications.

AIG consists of two services:

• BGS: The AIG Basic Gateway Service (BGS) is responsible for 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, ...)

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 4-1
© 2022 Siemens
 4. The Active Integration Gateway (AIG) Architecture

or Teamcenter environment (except possibly for job execution, depending on the configuration). The
AIG Job Server is a part of AIG BGS that manages transactions - which may be large and numerous - in
the background. This allows the Teamcenter user to continue working while the system is processing
data. To install and configure the AIG Job Server, please refer to Job Server Installation.

Each AIG process writes logs and debug messages to this central BGS instance using the UDP/IP
protocol. The AIG log server is a part of 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 on 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. Logging
information will certainly be lost if clients cannot connect to the BGS instance.

• GS: The AIG Gateway Service (GS) drives the process mapping. It contains the complete AIG software
(including all AIG servers, but not BGS). Several AIG instances can be installed using this package in
the network and they all can use the same AIG BGS instance. GS manages the connection to target
enterprise applications, operates the mapping, etc. It therefore 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).

4-2 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 5. Installation Instructions
5.1 Overview of Installation Steps
To install Active Integration Gateway and start it 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. After configuring the AIG installation using Deployment
Center, 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 security considerations
should be made. 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 start
AIG 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 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 AIG products, as well as extend an existing installation with one or more
additional products.

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.
Please refer to AIG combability matrix for further information on the supported Deployment
Center release versions.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-1
© 2022 Siemens
 5. Installation Instructions

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 instance not registered in
an environment, or a Teamcenter instance 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 22.1, please refer to Migration Guide —
T4EA for migrating AIG mappings, preferences and workflows.
Do not install BGS together with any AIG GS installation in the same directory. You must specify
one directory for BGS and another directory for GS.
Do not install AIG BGS or GS on a shared (mounted) drive, including drives that are physically
located on the same machine but connected by a network connection. UNC paths (\\server\share)
are not allowed as well.
Avoid long path names and blanks (spaces) in the path names.
Be sure to have the required permissions on folders and files of AIG BGS and GS. Consider the
instructions in chapter File System Hardening.
As it might cause file system problems, be sure to exclude the AIG directory from an automatic
backup. If required, only the directory <BGS_ROOT>/var should be included.
Once BGS or GS has been started, you are not allowed to change the folder name or installation
path.

Acquire the AIG installation packages

The released Active Integration Gateway (AIG) installation packages are uploaded to Support Center
and are available to all customers to download. Before installing AIG, please acquire the AIG installation
packages corresponding to your operating system(s) and Teamcenter version(s). 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 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 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 option 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_22.1_<TC_Version>_<OS>/AIG/artifacts/
AIG_extensions

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-3
© 2022 Siemens
 5. Installation Instructions

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

• The Apache-CXF libraries must be placed in the directory as ZIP archive.

For more information please refer to the following chapter Install CXF for using SOAP services

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

5.2.3 Configure AIG environment using Deployment Center

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

• Select the AIG Software package

For the installation of the Active Integration Gateway Services, you can either create a new
environment, or use an already existing environment containing a Teamcenter and/ or Active
Workspace installation. For this, add the Active Integration Gateway - Active Integration Gateway
Services for <TC_version> software package to your newly created Environment in the list of
selected software.

5-4 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 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.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-5
© 2022 Siemens
 5. Installation Instructions

• Choose your applications

In the Applications section of Deployment Center you can select the product(s) for your installation,
as well as the distribution of any external libraries. The Active Integration Gateway services are
subdivided into three groups: Teamcenter Gateway Products, designed for Teamcenter environments,
Closed Loop Manufacturing Products, which are part of the "golden triangle" architecture, and
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 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 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 and the Pipeline Designer. While the maximum
number of BGS instances in your environment is limited to one, you can install as many instances of
the GS, 4Tier Gateway Service Client and Pipeline Designer as needed, by clicking on the + symbol,

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-7
© 2022 Siemens
 5. Installation Instructions

choosing them from the Available Components list 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 otherwise.

Caution:
The Pipeline Designer is supported only by specific AIG products and is intended for use in
specific use cases. Please refer to the AIG Release Compatibility Matrix for a list of AIG products
which support Pipeline Designer.

Configure the 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.

Caution:
Do not install the Gateway Service under the suggested directory C:\Program Files or any other
directory with a space in the name. It will cause errors!

5-8 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Configure AIG environment using Deployment Center

Configure the Basic 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.

Caution:
Do not install the Basic Gateway Service under the suggested directory C:\Program Files or any
other directory with a space in the name! It will cause errors.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-9
© 2022 Siemens
 5. Installation Instructions

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.

5-10 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Deploy the AIG installation on the target machine

5.2.4 Deploy the AIG installation on the target machine

In order to execute the deployment, you need to have your Deployment Center repository located on a
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 the deployment, start the extracted deploy.bat/.sh with following parameters: -
dcusername, -dcpassword and -softwareLocation.

The -softwareLocation parameter needs to point to 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 matching the Deployment Center's 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.

Caution:
• Before the deployment script is executed, make sure the JRE_HOME/JRE64_HOME environment
variable is set on the target machine. Your Deployment Center host must be reachable over the
network.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-11
© 2022 Siemens
 5. Installation Instructions

• If you want to mount the software repository of the DC unter a network drive with Windows, do
it with net use:

net use m: \\myhost.my.domain\deployment_center\repo

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

5.2.5 File System Hardening

For AIG running under non-privileged account (<Account>) it is required to be set-up in specific manner.

AIG can be installed with Administrator or equivalent account on Windows and Linux platforms. In Linux
environment unprivileged <Account> specific permissions can be set-up by setting owner of files to root
and assigning permissions via group permissions of group with name <Account>. In Windows specific
permissions can be assigned directly on folders and files by setting security permissions in Properties
dialog.

BGS set-up

BGS can be installed anywhere on the file system with the following conditions:

• <BGS_ROOT> and all folders beneath are readable by <Account>

• All files in <BGS_ROOT>\bin have execute permissions for <Account>

• <BGS_ROOT>\etc\server has execute permissions for <Account>

• Depending on deployed platform <BGS_ROOT>\etc\t4x.unix or <BGS_ROOT>\etc\t4x.bat has execute

permissions for <Account>

• <BGS_ROOT>\tmp has write and list permissions for <Account>

• Inside of <BGS_ROOT>\var have following permissions for <Account>, outside of it read permissions
for files and read and list permissions for folders:

• <BGS_ROOT>\var\conf\tpds.overlay read and write permissions

• <BGS_ROOT>\var\db read, write and list permissions

• <BGS_ROOT>\var\db\structured_secrets.db read and write permissions

• <BGS_ROOT>\var\pef read, write and list permissions

• <BGS_ROOT>\var\pool read, write and list permissions

5-12 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 File System Hardening

• <BGS_ROOT>\var\upload read, write and list permissions

For account isolation following folders should be isolated into separate folders:

• <BGS_ROOT>\tmp

• <BGS_ROOT>\etc

• <BGS_ROOT>\var\conf

• <BGS_ROOT>\var\db

• <BGS_ROOT>\var\pref

• <BGS_ROOT>\var\pool

• <BGS_ROOT>\var\upload

Isolation can be performed by creation of symlinks to user-context depended locations like "~" in Linux
and "%APPDATA%" or "%PROGRAMDATA%" on Windows systems.

GS set-up

GS can be installed anywhere on the file system with the following conditions:

• <GS_ROOT> and all folders beneath are readable by <Account>

• All files in <GS_ROOT>\bin have execute permissions for <Account>

• <GS_ROOT>\etc\server has execute permissions for <Account>

• Depending on deployed platform

• <GS_ROOT>\etc\t4x.unix or <GS_ROOT>\etc\t4x.bat has read and execute permissions for

<Account>

• <GS_ROOT>\etc\t4x_env.sh or <GS_ROOT>\etc\t4x_env.bat has read and write permissions for

<Account>

• <GS_ROOT>\tmp has write and list permissions for <Account>

• Inside of <GS_ROOT>\var have following permissions for <Account>, outside of it read permissions for
files and read and list permissions for folders:

• <GS_ROOT>\var\conf\tpds.overlay read and write permissions

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-13
© 2022 Siemens
 5. Installation Instructions

• <GS_ROOT>\var\pef read, write and list permissions

• <GS_ROOT>\var\pool read, write and list permissions

• <GS_ROOT>\var\upload read and write and list permissions

For account isolation following folders should be isolated into separate folders:

• <GS_ROOT>\tmp

• <GS_ROOT>\etc

• <GS_ROOT>\var\conf

• <GS_ROOT>\var\pref

• <GS_ROOT>\var\pool

• <GS_ROOT>\var\upload

Isolation can be performed by creation of symlinks to user-context depended locations like "~" in Linux
and "%APPDATA%" or "%PROGRAMDATA%" on Windows systems.

5.3 Upgrade an Existing AIG Installation

5.3.1 Select the 22.1 software package

To upgrade an AIG product from previous versions to 22.1, perform the following steps:

• first you need to copy the folder Active_Integration_Gateway_22.1_<TC_Version>_win64\AIG

\dc_contributions\deployablecomponents from the 22.1 software package over the respective folder
in your old installations software package in the Deployment Centers repository, before adding the
22.1 software package to the repository.

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

Caution:
For upgrades from AIG versions < 20.2, you need to exclude all files having PIPELINE_DESIGNER in
their file name, as it is not available in previous versions.

5-14 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Securing of critical files

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 the target machine.

Note:
We recommend to verifing whether your configuration of the old installation has been maintained
in the components section.

5.3.2 Securing of critical files

Before executing the actual upgrade steps, an additional diagnosticChecks task is executed. It ensures
that no essential changes will be overwritten. If any files have been changed, the diagnosticsCheck task
will fail.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-15
© 2022 Siemens
 5. Installation Instructions

If this is the case, please check the log file for the source of the failure.

You may see the following message:

ERROR: modified files detected, please check the file d:/temp/extList/gs/tmp/extendedSkip.tcl

ERROR: Update / Extention not possible, danger of loosing data

INFO: please check the file d:/temp/extList/gs/tmp/extendedSkip.tcl and make a copy off all the listed
files

INFO: if you wish to extend/update after securing the files - copy d:/temp/extList/gs/tmp/extendedSkip.tcl
into d:/temp/extList/gs/var/install directory and run the installer again

If you see such a message, proceed as follows:

In the <AIG Installation Directory>/tmp directory, you will find a file named extendedSkip.tcl – it contains
a list with all detected changed files.

If you wish to proceed with the upgrade:

1. Create a backup copy of the listed files (they will be overwritten during the upgrade process).

5-16 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Initializing AIG

2. Move the extendedSkip.tcl file into <AIG Installation Directory>/var/install directory.

3. Run the deploy scripts again.

4. After successful installation, remove <AIG Installation Directory>/var/install/extendedSkip.tcl from

the directory.

5. If the upgrade of GS and BGS is done with one deploy script and you have changed files in both,
you will have to repeat the process (once for GS and once for BGS).

5.4 Initializing AIG

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

Security Considerations

Initialization Prerequisites

Initializing the BGS

Registering the GS

TLS/SSL Configuration

Running as Windows Services

Operating AIG with multiple OS users

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-17
© 2022 Siemens
 5. Installation Instructions

5.4.1 Security Considerations

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

BGS contains a single encrypted database which centrally stores all sensitive data like user passwords,
registered GS instances, and credentials of technical users of EA systems. 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 and encrypted,
the user data for "t4adm" is 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 every time BGS
is started, it has to be stored outside of AIG in the 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, once initialized, AIG can only be operated by
the same OS user. These prerequisites are detailed in Initialization Prerequisites. Operating AIG with
different OS user accounts is not enabled by default, but it can be enabled. For details, read the chapter
Operating AIG with multiple OS users carefully, as there are some drawbacks you need to be aware of.
If you are using Windows and want to run BGS/GS as Windows services, also read the section Running
as Windows Services very carefully.

To avoid an intrusion by a compromised GS instance on the network, the installed GS instances have to
be registered and approved before authenticated communication with the BGS instance can take place.
Therefore, each BGS/GS instance 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 instance 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 instance 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 figure below demonstrates how credentials are centrally verified in BGS. Assuming the initialization
has been completed successfully, imagine a call from GS to BGS being made to retrieve some data. First,
the GS instance uses its UUID to fetch the token stored for it from the OS password manager.
Afterwards, the call to BGS is made, authenticating with the UUID as the username and the token as the
password. BGS verifies the given credentials against the data stored in the encrypted database. It checks
if the GS instance is known, if it has not been blocked or deleted by an administrator yet, and whether
the given token matches. In case of success, BGS will send a 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 instance, where the verification takes place.
Access to the GS Admin UI will be given only once the BGS instance is reached and it verifies the
credentials successfully.

5-18 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Initialization Prerequisites

As a consequence of all these dependencies, BGS and GS immediately abort startup and write
emergency log files if some prerequisites are not fulfilled. Each of the following sections 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 to be available. For
Linux, the standard (but not installed out of the box) software pass is required. The installation and
configuration of pass is a bit tricky and assumes that GnuPG (gpg2) 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 instance, the OS password manager stores the encryption key for the
database and the token of the BGS instance itself. On a GS host, the password manager only stores the
token of the GS instance. For more information regarding 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, in the default use case, you cannot
change the OS user operating AIG and need to use the correct user from the beginning and on. For
using AIG with multiple OS users, see the chapter Operating AIG with multiple OS users.

Caution:
• The logged in OS user initializing BGS and GS must be the user operating AIG in the future,
unless you are using the multiple OS users feature.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-19
© 2022 Siemens
 5. Installation Instructions

• In a 4-tier environment, GS and the poolmanager do not only have to be installed on the same
host, but also executed by the same user. The same requirements need to be fulfilled for a 2-tier
environment and the Teamcenter Server process.

• Deleting or editing the file <AIG_ROOT>/var/conf/uuid (or <HOME>/.aig/bgs/uuid or

<HOME>/.aig/gs/uuid when using the multiple OS users feature) results in BGS/GS being unable
to access the information stored in there. BGS can no longer access the database and 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.
Additionally, when running BGS/GS as Windows services, some additional considerations have to take
place. Refer to Running as Windows Services in that case.

Note:
There is a limit of approximately 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 a GPG key for 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 the 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. If you don’t have high security requirements, you may find it more convenient to use
a key with no passphrase.

Troubleshooting

An error message command get_passphrase failed: Permission denied or cancelled by

userwhen running gpg2 --gen-key usually indicates that you have used su - <user> rather than
logging in directly. The default passphrase prompt uses direct access to the terminal, which is owned by
the logged in OS user and is thus inaccessible to the current user. Either login directly or see the GPG
documentation for other ways to supply the passphrase.

5-20 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Initializing the BGS

The OS password manager is accessed when AIG starts and while it is running. If the manager cannot be
accessed during startup or does not contain the correct data, BGS and GS shut down immediately. In
that case, check the file <AIG_ROOT>/tmp/bootstrap_errors.log for details:

::Bootstrapping::SecureStorageSanityCheck: Accessing secure storage failed

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 using pass to store and read a test value from the 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 and AIG will then
work as expected.

• An error message gpg: decryption failed: No secret key indicates that the GPG key pass
was 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 BGS once all prerequisites listed in Initialization Prerequisites are
fulfilled. Remember to start BGS with the correct OS user, i.e., the user operating 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 instance. Additionally, it can be used as a means of securely
passing the password from the interactive account of an AIG administrator to the non-interactive service
logon in Windows. 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 BGS makes BGS unable to find the password in the OS
password manager, also leading to a loss of all data.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-21
© 2022 Siemens
 5. Installation Instructions

Initialization steps

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

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.

Start BGS with <BGS_ROOT>/bin64/start or <BGS_ROOT>/bin64/restart. When running BGS as a Windows

service, make sure that you never start BGS interactively, but start the corresponding service to fetch the
password. For more information see Running as Windows Services.

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 BGS and will
contain messages such as fetchInitialT4admPassword: fetching initial password
failed: could not fetch password: Failed to connect to localhost port 11399:
Connection refused if BGS could not reach the initpassword server. Check if the server is running
when 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 BGS within the time limit. Check if you have started the BGS
instance from the same installation within the time limit and make sure BGS has not been initialized
yet. Modify the host and port settings if needed (see above). Additionally, on Linux, check 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 instance with the shown UUID tried to fetch the password, but has the wrong UUID, i.e., is not
the BGS instance belonging to this installation. Make sure you are using initpassword and BGS from
the same installation.

To reset the BGS a couple of manual steps are required before initializing it again.

5-22 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Registering the GS

Caution:
Be careful when deleting files from the BGS directory or entries from the OS password manager.
These actions are irrevocable and may lead to a loss of data. Ensure that you touch the correct files
and entries.
A reset of the BGS will also reset the registration of all connected GS. All connected and
successfully registered GS need to be reset too, as described in order to work. Refer to the
Troubleshooting section of Registering the GS for more information. All Enterprise Application
connection data and credentials stored in the encrypted database are also lost.

After accomplishing these manual steps, with the corresponding BGS stopped, you can start over new
with initializing the BGS:

1. Open <BGS_ROOT>/var/conf/uuid with a text editor and remember the old UUID in there. It will be
needed for subsequent steps.

2. Delete the entries Siemens_PL4x_<uuid>/internal/token and Siemens_PL4x_<uuid>/internal/

InitialKey from the OS password manager.

3. Delete the files <BGS_ROOT>/var/conf/uuid and <BGS_ROOT>/var/db/structured_secrets.db from the

BGS directory.

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 instance has to be approved in the BGS Admin
UI before it can receive a token and keep running. As a consequence of this strict requirement, a GS
instance which cannot reach the BGS instance, has not been approved by the BGS instance, is blocked,
or does not provide the correct credentials will abort its start.

The BGS instance 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 and 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.

Manual approval steps

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

Start GS once with the OS user who will be operating the GS instance later on. GS will abort its startup
immediately. Log in to the BGS Admin UI as the administrator (i.e. t4adm) and open Configuration →
Gateway services. The table lists all GS instances that have communicated with the BGS instance so far.
For details on the attributes shown and the buttons available, refer to the Admin UI Guide. Search for
the GS instance that had been started before and carefully verify the displayed data. If you are sure that

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-23
© 2022 Siemens
 5. Installation Instructions

this is the GS instance to which you would like to grant access, select it and click the Approve button. A
token (password) for this GS instance is generated and temporarily held in the database until it is
fetched; therefore, the status of the GS instance will be "waiting for acknowledgment" until it can be
guaranteed that the token has been fetched and stored successfully.

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

Automatic registration

Since it can become cumbersome to manually approve many clients, a second method for registration is
provided. This method is more convenient, 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 is used as a kind of "ticket" during the
initialization. Using this "ticket", the GS is automatically approved and retrieves the generated token
(password) directly.

Login to the BGS Admin UI as the administrator (i.e. t4adm) and open Configuration → General →
Advanced settings. In the section Automatic registration you can generate, view, overwrite, or delete
this token. Generate a token, copy it, and securely distribute it to the GS hosts you want automatically
registered. Set the environment variable TP_AUTO_REGISTER_TOKEN to the copied token value and
make sure this variable can be accessed when starting GS again. When GS is started it registers with BGS
using this automatic registration token. It is automatically approved and a generated token for this
single GS instance is returned.

If the automatic registration token is overwritten or deleted in BGS, any GS instance trying to register
with it will fail. All GS instances which have already been registered successfully are not affected by this
change. Therefore, if the automatic registration token is accidentally leaked, simply generate and use a
new one from then on. Make sure that no compromised GS instance has registered using the old
registration token.

Registration in the context of Teamcenter

The AIG libraries loaded in Teamcenter also do authenticated calls to BGS/GS. Therefore, information
regarding 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 instance.

Caution:
In 4-tier environments, GS has to be on the same host and run under the same OS user as the
poolmanager. The same requirements need to be fulfilled for GS and the Teamcenter server
process in a 2-tier environment.

5-24 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Registering the GS

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 response 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.

The error message ::Bootstrapping::tryRegisterUUID: Requesting a token failed

with: Failed to connect to <BGS SERVER> port <PORT>: Connection refused usually
means that the BGS is not running or a firewall is blocking the connection.

The error message ::Bootstrapping::tryRegisterUUID: Requesting a token failed

with: illegal response means that the GS cannot understand the response it received. The most

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-25
© 2022 Siemens
 5. Installation Instructions

likely reason is that it's connecting to something other than the BGS server; perhaps you accidentally
specified the Admin UI port rather than the regular BGS port.

The error message ::Bootstrapping::tryRegisterUUID: Requesting a token failed

with: Recv failure: Connection was reset usually means that the GS has connected to the
BGS and made a request, but a firewall is blocking the response from the BGS.

Refer to Initialization Prerequisites, if the

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

To reset the GS a couple of manual steps are required before registering it again.

Caution:
Be careful when deleting files from the GS directory or entries from the OS password manager.
These actions are irrevocable and may lead to a loss of data. Ensure that you touch the correct files
and entries.

After accomplishing these manual steps, with the corresponding GS stopped and BGS running, you can
start over new with registering the GS:

1. Open <GS_ROOT>/var/conf/uuid with a text editor and remember the old UUID in there. It will be
needed for subsequent steps.

2. Login to the BGS Admin UI as administrator, search and delete the corresponding UUID entry from
the list of registered GS in Configuration → Gateway services.

3. Delete the entry Siemens_PL4x_<uuid>/internal/token from the OS password manager.

4. Delete the files <GS_ROOT>/var/conf/uuid and <GS_ROOT>/etc/t4x_env.bat or t4x_env.sh from the

GS directory.

5.4.5 TLS/SSL Configuration

Starting with version 21.1 AIG has Server Authentication configured out of the box. The required demo
certificates are generated during first start of BGS. For GS the certificates are generated during second
start after receiving the authentication token.

These self-signed demo certificates are not secure and have to be replaced by your own
certificates for production use!

To replace the certificates follow instructions of chapter Configuring Server Authentication for BGS
and chapter Configuring Server Authentication for GS.

5-26 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Running as Windows Services

Note:
In case of an upgraded AIG product the self-signed demo certificates are generated during first
start of BGS and GS as well, but the existing configuration is unchanged.

5.4.6 Running as Windows Services

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

Caution:
• When running BGS or GS as service, never start or stop BGS/GS manually at any time!
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 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. If needed, you can
make use of the multiple OS users feature at your own risk to enable a service as well as an
interactive user for the same installation.

• 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 AIG component running in
Teamcenter will neither be able to connect to GS nor BGS.

• Though it is possible, it is not recommended to start 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 file). Ensuring
that the Teamcenter service and AIG GS run under the same OS user can become very complex.

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 AIG BGS

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

• Creating Windows service for AIG GS

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

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-27
© 2022 Siemens
 5. Installation Instructions

Caution:
The space after the "=" signs in the sc create command is required, as is the lack of space
before them!

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

Stopping the service

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

1. Create a shutdown script:

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

3. Open Windows Settings → Scripts.

4. Select Shutdown.

5. Open the Properties and Add the shutdown script:

5-28 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Operating AIG with multiple OS users

5.4.7 Operating AIG with multiple OS users

If needed, AIG installations of BGS or GS can be used by multiple different OS users (for example, in
cases where two people share the same workstation). This feature is turned off by default and needs to
be explicitly turned on. Before making use of it, read this chapter carefully so that you are aware of all
advantages and disadvantages of this solution.

The problem that a classic installation cannot be shared between users arises due to the storing of the
token in the OS password manager of the OS user. For example, imagine two users Alice and Bob using
the same workstation with a classic AIG GS installation from time to time. Assume that Alice used the
installation first and registered the GS instance with BGS, and a UUID "123" has been created in the GS
installation directory, which has been written to the t4x_env file and registered and approved in BGS.
Finally, the token for the UUID has been generated and stored in the OS password manager of Alice's OS
user account. If Bob tries to operate the same AIG GS instance the next day, the authentication
validation will fail because the GS instance uses the same UUID "123", but Bob does not have the
corresponding token in his OS password manager and cannot access the store of other users.

General considerations and preconditions

To allow multiple OS users running the same AIG installation, each user gets his or her own UUID. As a
consequence, each GS UUID needs to be approved either manually or by using the automatic
registration, as described in Registering the GS. In contrast to a classic single-user installation, blocking,
unblocking or deleting a UUID in the BGS Admin UI does not affect not the complete installation, but
only the access for the user owning this UUID.

When this feature is activated, the UUID file is not stored in <AIG_ROOT>/var/conf/uuid, but in the home
directory of the current OS user. The home directory is specified by the environment variable $HOME for
Linux and %USERPROFILE% for Windows. AIG will create a directory .aig and a subdirectory bgs or gs
and store the UUID in there. Hence, the new file path for the GS UUID is <HOME>/.aig/gs/uuid.

The feature is activated by setting the environment variable TP_HOME_UUID to an arbitrary value, e.g.
TP_HOME_UUID=1. The easiest way is setting this feature switch globally for the user; otherwise, you
need to be aware that the switch needs to be set in dedicated places on initialization and every start of
AIG.

When uninstalling AIG, also remember to delete the .aig directory in the home directory of every user.

Caution:
• The environment variables $HOME or %USERPROFILE% need to be available and set to a proper
directory.

• It is neither recommended nor possible to run multiple versions of AIG on the same host using
this feature, as there can only be one UUID file in the home directory for each BGS and GS
instance.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-29
© 2022 Siemens
 5. Installation Instructions

• Running the same software under different OS users can become complicated. Make sure that
all OS users have sufficient rights to access, write, and delete files. The configuration of the
correct access rights is your own responsibility.

• Only delete the <HOME>/.aig directory or any of its contents if you are absolutely sure that it is
no longer needed. Make sure that there is no automatic process in place which may accidentally
delete anything from that directory. Deleting the files of a registered user will corrupt his or her
AIG installation.

Initializing BGS

Though it is possible to run BGS under different OS users, it is not recommended, as there are several
drawbacks. In order to initialize BGS for multiple users, follow these steps for each user:

Make sure that TP_HOME_UUID=1 is set, either globally or in two different command line windows,
which you can use to execute the subsequent steps. It must be set before either initpassword can be
used or BGS can be started. If this is the very first time this BGS instance is initialized, execute
<BGS_ROOT>/bin64/initpassword and follow the steps as described in Initializing the BGS. Afterwards,
start BGS to fetch the initial password. If this installation is already in use by other OS users, it is
absolutely necessary to enter the exact same initial password as for previous initializations. Otherwise
the secure database, encrypted with this very first password, cannot be accessed and the initialization
will fail. As a consequence, if you have changed the password of the user "t4adm" in the meantime, it is
reset again to the basic password provided in the initpassword executable.

For each subsequent launch of BGS or any of its processes, the environment variable has to be set in
order to use the correct UUID. If you do not set the environment variable globally for the user or system,
you need to set it in the command line window you use to start BGS.

The UUID of the currently running BGS instance is invisible in the Gateway services list of the BGS
Admin UI. If multiple users are running BGS, bear in mind that the UUIDs of the other users are shown in
the list and could be blocked or deleted.

Registering the GS

In order to run a GS instance with different OS users, make sure that TP_HOME_UUID=1 is set before
starting the GS instance. The GS instance will create its UUID in the home directory of the user and try to
register as usual. Follow the steps described in Registering the GS and use the automatic or manual
method to approve the GS instance. As with BGS, the environment variable has to be set for each
subsequent launch in order to find the correct UUID file. If it is not set globally for the user or system, set
it in the command line window used to start GS. It does not suffice to set it in other AIG GS script files, as
the location of the UUID file needs to be correct before the very first moment of the GS start sequence.

To work in the context of Teamcenter, the environment variable also has to be set before loading the
t4x_env shell/batch file. In case the variable is not set globally, set it right before calling t4x_env in
start_TcServer1.bat or tcenv.bat, respectively. For more information, see either Set AIG GS
Environment for a Teamcenter 2-Tier Environment or Set AIG GS Environment for a Teamcenter 4-
Tier Environment.

5-30 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Basic Configuration in the Admin UI

Caution:
As was the case with a classic single-user installation, GS and the poolmanager (4-tier) or
Teamcenter server (2-tier) process need to run under the same OS user in a multi-user installation.

Running as Windows Services

You can also use the multi-user feature when BGS and GS are running as Windows services. For
information on how to create the services, see Running as Windows Services. The TP_HOME_UUID=1
environment variable needs to be set for the corresponding user or as system variable, as there is no
other way to pass environment variables to services.

Define a dedicated Log On user for the service and do not use the local system account. The
initpassword executable required to initialize BGS cannot be run interactively when using a local system
account. Instead, if the service is running under, say, the log on user Alice, make sure that you are also
logged in to Windows with Alice's account to use initpassword interactively. A mix of accounts (e.g. Alice
interactively and BGS as a service running under the local system account), would store two different
UUID files in the home directory of each account, which will not match and hence not fetch the
password. Since the local system account is like a global user without any interactive desktop but with a
separate user profile, it does not make sense to use it for GS when multiple users will use the same
installation. Using the local system account for the GS service is contradictory to the philosophy of the
multi-user feature. Additionally, running as a service is in general not recommended for 2-tier GS clients.
This feature is most valuable for GS clients started by different OS users and hence usually started
interactively; therefore, include a call to start AIG in the portal.bat file, as described in Running as
Windows Services.

Caution:
• BGS and GS must run under a dedicated Log On user and may not be started using a local
system account.

• Keep the restrictions mentioned in Running as Windows Services in mind. They are also valid
for the multi-user feature.

5.5 Basic Configuration in the Admin UI

This chapter summarizes the basic configuration needed to start using Active Integration Gateway. The
following topics are covered:

User Management

Setting the License Server

Changing Ports

Setting the BGS Server

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-31
© 2022 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 process 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
process, see Initializing the BGS.

Caution:
There is no recovery method if "t4adm" is the only administrator and you have lost the password
for the account!
The best practice is to configure an LDAP directory 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 page where you can add users, thereby granting them access to 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 is assigned for viewing log files and content. For
more information about roles, please refer to the chapter User Management and Role Management in
the Admin UI Guide.

In the AIG BGS Admin UI, the user management page 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. From 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 or her to the database. For more
information on how to configure the LDAP directory, please consult the Admin UI Guide.

5-32 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Setting the License Server

• 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".

• 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 members of the Teamcenter product family, the license for AIG products is included in the Siemens
PLM Software license file.

AIG BGS directly gets its 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 a multiple or redundant (fail-over) server
configuration. For more information, please consult the documentation of the Siemens PLM Software
license server.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-33
© 2022 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.

Caution:
All licenses for Teamcenter and Teamcenter Gateway products need to be stored on the same
license server. Distribution across multiple license servers (multiple server configuration) is no
longer supported by Teamcenter.

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

For more information on configuring server instances, see the chapter titled General in the Admin UI
Guide.

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.

5-34 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Changing Ports

Specifiy your port in the pop-up dialog.

Click the save icon in the Admin UI to save the changes, then choose to restart BGS or GS when
prompted so that the changes take effect.

For more information on configuring server instances, see the chapter titled Server Instances in the
Admin UI Guide.

Caution:
If you change the port number of the SERVER or LOG_SERVER instance, you must ensure that the
port numbers are adjusted correctly in the Configuration → Communication channels section.
Additionally, if you change the port number of the BGS server instance, you must adjust the port
number in each connected GS instance. For more information, please refer to Setting the BGS
Server and the Admin UI Guide.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-35
© 2022 Siemens
 5. Installation Instructions

5.5.4 Setting the BGS Server

Setting the BGS server in the GS Admin UI

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

Edit the communication channels BGS, BGS_WEB and LOG by clicking the edit button in the Actions
column. Enter the host and port of the BGS server instance and click Apply to close the popup.

Click the save icon in the Admin UI to save the changes, then choose to restart GS when prompted.

For more information on configuring communication channels, see the chapter titled Communication
Channels in the Admin UI Guide.

5-36 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Verifying the Installation

Setting the BGS host to enable download links

BGS maintains the communication channels DEFAULT, DEFAULT_WEB and EXTERNAL_WEB pointing to
itself in order to perform actions such as running scripts or downloading log files. 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 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
BGS Admin UI in the browser. In this case, BGS uses the information entered in the Host setting of the
EXTERNAL_WEB communication channel to construct the correct download URL.

5.5.5 Verifying the Installation

You can check AIG GS installation information 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 secure storage. Afterwards, validate it using the
same script.

5.6 Teamcenter Templates

5.6.1 Template Content

This section gives a high level overview of the Teamcenter BMIDE templates included with your
integration product. For more details please have a look at the template contents. Installation of the
templates is described in later sections.

t4ea - Teamcenter Gateway for Enterprise Applications

This template has to be deployed in order to make T4EA work. It depends on the "foundation" template
only and contains:

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-37
© 2022 Siemens
 5. Installation Instructions

• Data Model Extensions: EAX2LogonTask and EAX2LogonTaskTemplate allow login and

verification of the EA connection and optionally allow the Teamcenter user to select the active EA
connection during Teamcenter Workflow execution.

• Workflow task EAX2LogonTask which can be added to workflows to enable EA login, connection
verification and interactive selection.

• Preference TC_customization_libraries adds the T4EA workflow handler libraries to the

Teamcenter server.

• Preference T4EA.UI.GatewayMenu.Hide to hide the T4EA gateway menu by default.

• Preference T4X.UI.ShowLog.ExternalBrowser.Executable and

T4X.UI.ShowLog.ExternalBrowser, allowing to specify an external browser binary to use on
UNIX-based platforms.

• Preferences specifying blocklists and allowlists to restrict the amount of attributes during data
extraction for the OOTB Teamcenter data model.

Teamcenter Gateway for Enterprise Applications/Integration for Rich Client

This template will be installed automatically along with the "t4ea" template to a local 2-Tier or 4-Tier
installation of the Teamcenter Rich Client, if such an installation exists. You may also want to deploy this
template on additional clients. It contains:

• Several Jar files containing the Rich Client extensions specific to T4EA (interactive workflow task,
Dataview, external query and import menu). These Jar files are copied to the \portal\plugins folder.

• Several language .xml files containing error texts specific to T4EA. These XML files are copied to the
\lang\textserver folder.

t4eademo - T4EA Demonstration Template

This template contains a sample configuration intended to show how T4EA can be operated. It may not
be deployed to productive environments! Instead it can only serve as a "template" for your custom
templates. The t4eademo template depends on "foundation" and "t4ea". It contains:

• Data model extensions: Type EAX4FixedAsset and Naming Rule EAX4GenFixedAssetID

• Preference TC_customization_libraries adds the libt4x_idgen library to the Teamcenter

server.

• Several T4EA-specific preferences to support the demo scenario (all start with prefix "T4EA" or "T4X"
and are in categories "EA Gateway" and "Gateway Foundation").

5-38 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Compatibility with other Templates

• Preference AWC_ItemRevision.showObjectLocation.SUMMARYRENDERING to allow to display

WebDV in Active Workspace.

• Saved queries T4EA_Product, T4EA_Product_Row, T4EA_ProductInformation and

T4EA_ProductInformation_Row to support external queries and import.

• Several workflows which allow to operate the demo scenario, all starting with name prefix "T4EA".

Caution:
This template is intended for product demonstration and customization training workshops. It
should never be deployed in the context of a productive datamodel!

5.6.2 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!

5.6.3 Deploy Active Integration Templates with Deployment Center

Caution:
You should only use Deployment Center to deploy the Teamcenter templates and plugins if you
already have an existing Teamcenter installation in your environment which was also installed via
Deployment Center. If you installed Teamcenter with TEM, please follow the corresponding
installation instructions in the section 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 Deployment Center’s Repository Service after placing the
unzipped package in the Repository, as described in the Installation preparations section.

Once registered, you can add the Teamcenter templates and plugins to your environment by adding it to
the environment’s 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 T4EA installation by selecting your
environment containing Teamcenter and, depending on your use case, by adding the following software

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-39
© 2022 Siemens
 5. Installation Instructions

packages to the list of selected software:

5.6.4 Deploy AIG Template with TEM

Caution:
You should only use TEM to deploy the Teamcenter templates and plugins if you already have an
existing Teamcenter installation in your environment which was also installed via TEM. If you
installed Teamcenter with Deployment Center, please follow the corresponding installation
instructions in the section Deploy Active Integration Templates with Deployment Center

As part of the AIG installation process, the Teamcenter database and configuration must be modified by
deploying the AIG template using the Teamcenter Environment Manager (TEM).

To deploy the AIG template with TEM, 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. On the first page, Maintenance, select Configuration Manager and click Next

3. Select Perform maintenance on an existing configuration

4. Select your desired database

5. On the Feature Maintenance page, select Teamcenter – Add/Remove Features

6. On the next page, Features, click Browse and select the AIG template file:

5-40 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Deploy AIG Template with TEM

For Teamcenter 13: <DC_ROOT>/repo/software/Active_Integration_Gateway_22.1_tc13_win64/tc/

features/t4ea/tem_contributions/feature_t4ea.xml

7. On the same page, the new feature appears and has to be checked. To deploy the T4EA template,
select the new feature Teamcenter Gateway for Enterprise Applications under Extensions.

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 ensure that the 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. On the next page, Confirmation, you should see the selected features. Click Start to start the
template installation

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-41
© 2022 Siemens
 5. Installation Instructions

10. The next page, Install, shows the installation progress with a moving bar. This may take a number
of minutes to complete and should end with the message Install Successful:

Caution:
• Before starting TEM, please make sure to have all the configuration XML files of any
environment customizations that were made until now (i.e., before the beginning of this AIG
installation) in the directory %TC_DATA%/model. Additionally, after environment customizations
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 are missing (these errors are logged 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.

• The library libt4ea 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 though it was not installed in a previous TEM run.

5-42 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Configuring the Mapping

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.

For more details, see the chapter titled "Manage a development environment" in the Basic Configuration
Guide — T4EA.

Mapping structure and basics

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

No mapping file (*.sd ) should be placed directly in the mapping source directory but only in one of its
subdirectories. Each of these directories has to contain a file *_mapping_config.sd (same file name as
the subdirectory name) which is used as an entry point when loaded and can source further files if
needed.

Use the directory <GS_ROOT>/var/mmap/t4x_mapping_config for product-independent mapping files.

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 source files in the subdirectories 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 GS to load the new mapping.

Whether you compile the mapping using a script or an executable, you can choose 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 a mapping for:

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-43
© 2022 Siemens
 5. Installation Instructions

To automatically compile, copy, deploy, and load the mapping, select the Generate Mapping and
Server Hot Deployment Mode. The same result 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 which AIG environment and AIG libraries should be loaded when Teamcenter starts. As
Teamcenter clears the environment settings while processing its start-up scripts (portal.bat,
start_imr.bat…), the call to the AIG environment file has to be done immediately before the start of the
Teamcenter Server process.

Open the file

• %TC_ROOT%\tctpservers\starttcserver.bat

5-44 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Set AIG GS Environment for a Teamcenter 4-Tier Environment

(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

If you have more than one Teamcenter database in your Rich Client installation, there will be multiple
script files, start_TcServer2.bat… Be sure to modify the file(s) corresponding to the database(s) where
AIG should be used.

Caution:
In a Teamcenter 2-Tier environment, the modification of the Teamcenter start script should be
done for 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 which AIG environment and AIG libraries should be loaded when Teamcenter starts. In a
Teamcenter 4-Tier environment, the AIG environment file should be called when starting pool or net
server manager.

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 file ue_errors.xml). This additional file is sap_errors.xml, which should be
copied to the target Teamcenter folder during AIG template deployment.

Note:
If you have additional Teamcenter servers or 2-tier clients that do not share the TC_ROOT
directory where the AIG template was deployed, you will either need to deploy the template to
those servers, too, or manually copy the AIG text files from <GS_ROOT>\var\template\lang
\textserver to %TC_ROOT%\lang\textserver.

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

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-45
© 2022 Siemens
 5. Installation Instructions

AIG supports several languages that are selected automatically according to the Teamcenter GUI
language. If Teamcenter 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 no
such files are found there, Teamcenter will use the default directory %TC_ROOT%\lang\textserver\en_US.

5.8.4 Connectivity to Teamcenter

Credentials used to automatically log in to Teamcenter are centrally maintained by 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 three main 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
account as the default, then this entry ("Default@Teamcenter") will be used.

• 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 details about 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\tc<VersionNumber>
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:

5-46 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Install AXIS2 for using SOAP services

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.

5.10.2 Install AXIS2 for using SOAP services

Note:
This technology is deprecated! It is recommended to move existing integrations from the direct
TCL implementation "TCL to SOAP" to the CXF solution "WSDL to T4x".

If your Teamcenter Gateway for Enterprise Applications or Teamcenter Gateway Extension Package
server is to provide or consume SOAP services using the AXIS2 Java Adapter, you must download and
provide Apache Axis2 libraries for the SOAP server to work.

Browse to http://axis.apache.org/axis2/java/core/ and download the zip package for at least version
1.7.9. To install it, simply unzip the archive to the <GS_ROOT>/lib directory, so that you get a
subdirectory axis2-1.7.9 there, with at least subdirectories conf, lib and repository in turn. The bin,
samples and webapp directories and their content are not needed.

In addition to Axis2 version 1.7.9, also Rampart version 1.6 is needed. Please note that in this case 1.7
releases won't work. Rampart is the security module of Axis2 and can be downloaded e. g. from http://
archive.apache.org/dist/axis/axis2/java/rampart/1.6.4/. To install it, please unzip the files contained in
the lib and modules directories of the archive to the lib and repository/modules subdirectories of your
Axis2 installation. Finally add the Rampart modules rampart-1.6.4.mar and rahas-1.6.4.mar to the
modules.list file in the repository/modules subdirectory of your Axis2 installation.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-47
© 2022 Siemens
 5. Installation Instructions

5.10.3 Install CXF for using SOAP services

If your Teamcenter Gateway for Enterprise Applications or Teamcenter Gateway Extension Package
server is to provide or consume SOAP services using the "WSDL to T4x" feature, you must download and
provide Apache CXF libraries for the SOAP server to work.

Browse to http://archive.apache.org/dist/cxf/ and download the zip package for at least version 3.4.4
(current link: http://archive.apache.org/dist/cxf/3.4.4/apache-cxf-3.4.4.zip). From the downloaded zip,
extract the contents of the lib directory and store the libraries in your <GS_ROOT>/lib/apache-cxf/lib
directory. You can then import WSDLs to the AIG repository using the wsdl2t4x tool.

If you are using AIG with JDK 11 runtime, additional libraries no longer contained in JDK 11 need to be
downloaded and put into the classpath. We recommend to store them in <GS_ROOT>/lib/apache-cxf/lib,
since jar files placed there are automatically part of the classpath. The libraries required depend on the
features used in your configuration. Missing libraries are reported in logfiles with "ecmd" in the name or
in the tpapps64.log during startup. In most cases the following libraries help:

• saaj-impl-1.5.1.jar (current link: https://mvnrepository.com/artifact/com.sun.xml.messaging.saaj/

saaj-impl/1.5.1)

• jaxb-api-2.3.1.jar (current link: https://mvnrepository.com/artifact/javax.xml.bind/jaxb-api/2.3.1)

• javax.activation-1.2.0.jar (current link: https://mvnrepository.com/artifact/com.sun.activation/

javax.activation/1.2.0)

This list represents a working combination at the release date of this documentation. Open source
components may experience vulnerabilities, version changes and relocations. Please check if newer
versions are applicable.

5.10.4 Install a provider for JMS Messaging

For AIG JMS integration, you must provide a JMS implementation library matching your messaging
broker or infrastructure. Consult the messaging manufacturer’s manuals for details about this. The JMS
implementation libraries have to be placed in the <GS_ROOT>/lib/modules/messaging directory. These
implementation jars cannot be provided by Siemens PLM Software because of licensing issues.

Here is a list of jar files which enable AIG to communicate with ActiveMQ 5.12.0 (all can be downloaded
from http://activemq.apache.org/download.html):

• activemq-broker-5.12.0.jar

• activemq-client-5.12.0.jar

• geronimo-j2ee-management_1.1_spec-1.0.1.jar

• geronimo-jms_1.1_spec-1.1.1.jar

5-48 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Integration of Redis/ LevelDB as global SHM storage

• hawtbuf-1.11.jar

• slf4j-api-1.7.7.jar

The following list of jars enables AIG to communicate with IBM MQ 7.5 (all of these jars are contained in
the IBM MQ 7.5 client installation package):

• com.ibm.mq.headers.jar

• com.ibm.mq.jar

• com.ibm.mq.jmqi.jar

• com.ibm.mqjms.jar

• dhbcore.jar

• fscontext.jar

• jndi.jar

• providerutil.jar

AIG needs a JMS 1.1 jar file in the installation. Newer JDKs contain that jar at least in the EE edition. In
these cases no additional jar is required. Some brokers (like, e.g., IBM MQ) bring a jms.jar with them,
which you can use. If neither your broker nor your JDK contains a jms.jar, you can for example download
it from this maven repository: http://mvnrepository.com/artifact/javax.jms/jms/1.1 and store it in the
lib/modules/messaging directory.

You can then use the AIG messaging adapter to receive and send messages (see Connectivity Guide —
T4EA for details).

5.11 Integration of Redis/ LevelDB as global SHM storage

The SHM Global Storage (SGS) extends the SHM storage in AIG with a new storage class. SHM is a KEY/
VALUE storage available at all levels of AIG. Until now, there were the storage classes LOCAL and
SHARED.

LOCAL: Resides on the HEAP of the process and becomes invalid when the process is terminated. The
entries are local to the OS process.

SHARED: It is persistent and local to an AIG Instance (PES/GS). Its size is limited, but this memory works
without network connections.

For the SGS, the memory class GLOBAL was established. There are two implementations for SGS.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-49
© 2022 Siemens
 5. Installation Instructions

1. Default (OOTB):

An embedded KEY/ VALUE database was provided in the PES to realize a zero-config deployment of
AIG and cover simple use cases. A configuration is not necessary. The data is stored persistently
and can be accessed by any process within an AIG installation (PES/GS). The database volume is
limited to about 100GB, and no clustering, failover, or backup is supported.

2. Redis:

To support business-critical applications, it is possible to bind a Redis database. With the Redis
integration, it is possible to have multiple AIG installations accessing the same database. External
applications can also access the database, and thus providing another easy way to exchange data.

5-50 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Integration of Redis/ LevelDB as global SHM storage

Redis Configuration

Prerequisites

• A Redis server (>= 6.1) is needed (Redis)

• It is strictly recommended not to run this server on the PES or GS hosts.

• It is strictly recommended to run this Redis server instance exclusively for AIG and not run different
applications on the same Redis server instance.

• AIG supports only 2-way TLS connections to Redis

• A valid server certificate for Redis is required

• A valid client certificate for AIG is required

Configuration

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-51
© 2022 Siemens
 5. Installation Instructions

AIG uses a Redis server if it has been configured. A special switch to change from the embedded
database to Redis does not exist. The configuration is located in the etc/tpds file of the PES server.

Find this section in the tpds and configure it - all certificates and keys must be in PEM format.

HOST..: The Redis server host - DNS or IP

PORT..: The Redis sever port

CACERT: The Root Certificate chain

KEY...: The Private KEY without a passphrase

CERT..: The Client Certificate

Example

# Configuration of Redis for Global Storage

dnoes SYS.SHM.REDIS.HOST bluezone.jw
dnoes SYS.SHM.REDIS.PORT 6379
dnoes SYS.SHM.REDIS.CACERT <bgs installation
path>/var/conf/cert/t4xdefault.ca.crt
dnoes SYS.SHM.REDIS.KEY <bgs installation
path>/var/conf/cert/redis.client.key
dnoes SYS.SHM.REDIS.CERT <bgs installation
path>/var/conf/cert/redis.client.crt

Testing of the Configuration for Default (OOTB)

First step: The PES must be configured and started! Then, run this test on the PES server. If it was
successful, repeat this with all GS servers:

Open the bin64/tpshell and execute this (choose meaningful KEY key name).

[T4x] > tpco_shmset global TEST.KEY "Hello World" 0

This command should return without error messages. Then look into the system log of the PES server.
There you should find these two messages. If so then AIG should have successfully created a KEY in the
RedisDB.

.../tpbgs64.log :: tpnci_smsgoInitRedisConnection :: REDIS connection

parmas :: <hostname>:6379 CERT=/home/t4x/bgs/conf/cert/redis.client.crt
KEY=/home/t4x/bgs/var/conf/cert/redis.client.key CA=/home/t4x/bgs/var/
conf/cert/t4xdefault.ca.crt
.../tpbgs64.log :: tpnci_smstoInitRedisConnect :: successfull connection
(<hostname>:6379)

5-52 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Integration of Redis/ LevelDB as global SHM storage

Note:
Please adapt /home/t4x/bgs to your BGS installation path.

If this did not work, follow the error messages in the PES SystemLog.

To check if AIG is able to read the external KEY, this must be executed in the bin/tpshell

[T4x] > tpco_shmget global TEST.KEY Hello World

If the query result is correct, then the integration of RedisDB into AIG should now be successful.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-53
© 2022 Siemens
 5. Installation Instructions

5-54 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 6. 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, properly installed and tested BGS and GS
instances 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 in AIG is based on the OpenSSL libraries and uses TLS version 1.2/ 1.3
exclusively.

Caution:
If you mis-configure these settings, you may lose connection to the AIG server and will be unable
to fix the configuration using the Admin UI. Therefore, it is highly recommended to back up 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.

6.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
extension 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.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 6-1
© 2022 Siemens
 6. 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.

2. Open the certificate file using a text editor and check that each of the following sections can be
found once in the server and client certificates:

-----BEGIN RSA PRIVATE KEY----- … -----END RSA PRIVATE KEY-----

-----BEGIN CERTIFICATE----- … -----END CERTIFICATE-----

If you cannot read the contents of the file, then it 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 detail. 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 the file is valid, the content of the certificate or
private key is printed between the tags mentioned in step 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

Checks 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 date range in which the certificate is valid. Make sure that the current date is in
between those dates. Otherwise, the certificate is either already expired or not yet valid.

6-2 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Certificates

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 was 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

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 nearest
to the root) certificate. Although AIG does not consider the order of the certificates in the CA
certificate (chain) file, you must still make sure that the chain is complete and 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>/var/conf/cert and <GS_ROOT>/var/conf/cert directories,

respectively, to make them available for AIG and the configuration dialog in 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 by AIG (i.e., by 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.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 6-3
© 2022 Siemens
 6. Configure AIG for TLS/SSL

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 CA

certificates currently stored in the certificate store with the file <AIG_ROOT>\var\conf\cert\ca-
certificates.crt. When AIG is configured to use the certificate store, it will search for the appropriate
certificate in this file.

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

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

6.2 Server Authentication

Using server authentication (also known as standard authentication or one-way TLS), the client (e.g.,
your GS instance or web browser) verifies the certificate sent by the server (e.g., your BGS or GS
instance) 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 GS is encrypted, provided encryption is configured for the
GS instance.

6.2.1 Configuring Server Authentication for BGS

To enable server authentication in 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 instance and each
connected GS instance. It can be stored in either the <AIG_ROOT>/var/conf/cert directory or the
certificate store of the operating system (see Using the certificate store of the operating system).

Tip:
Create a backup copy of <BGS_ROOT>/var/conf/tpds.overlay and <GS_ROOT>/var/conf/tpds.overlay
before changing configuration.

6-4 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Configuring Server Authentication for BGS

On BGS start with server instance SERVER and the corresponding communication channels. Test
the configuration with script "Test Communication Channels" before adapting server instance
ADMIN_UI20.

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 setting in the Edit
Server Instance dialog and select the BGS server certificate in the Server certificate editing sub-
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 BGS needs to be able to communicate with itself properly, e.g. when running a script, you
must also modify the communication settings. The settings of the SERVER server instance
configured in step 1 have to match the properties of the communication channels DEFAULT,
DEFAULT_WEB and EXTERNAL_WEB.

Open the Configuration → Communication channels settings and modify these communication
channels in the displayed 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 appropriate CA
certificate (chain file) or use the Certificate store of the operating system in the CA
certificate editing sub-dialog.

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

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

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

3. Apply all changes and restart BGS.

4. In addition to BGS, each connected GS instance has to know the settings for secure communication
with BGS, i.e., the settings of the SERVER server instance of the configured BGS instance have to
match the properties of the communication channels BGS and BGS_WEB in each connected GS
instance.

Therefore, open the Configuration → Communication channels settings in the Admin UI of each
connected GS instance and modify these communication channels:

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 6-5
© 2022 Siemens
 6. Configure AIG for TLS/SSL

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

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

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

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

5. Apply all changes and restart GS.

6.2.2 Configuring Server Authentication for GS

To enable server authentication in 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).

To configure server authentication for the GS instance, follow steps 1 to 3 described in Configuring
Server Authentication for BGS, except replace all references to BGS with GS, i.e., use the GS Admin UI,
use the GS server certificate, and restart GS at the end.

6.2.3 Testing and Troubleshooting Server Authentication

To test the configuration, start your BGS and GS instances using the bin64/debug executable. The debug
executable 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 instance in the URL, which has to be the
same as the one 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 pages and run the Test Communication Channels script to
confirm the correct configuration. Check that all test cases completed successfully.

6-6 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Client Authentication

There is one test case for each main communication channel, i.e., DEFAULT and DEFAULT_WEB in both
BGS and GS and also BGS and BGS_WEB in GS. If one or more test cases are failing, check the
configuration of the corresponding 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 instance for any error log messages.

For more details about error messages and some possible solutions, please refer to the Troubleshooting
section.

6.3 Client Authentication

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

6.3.1 Configuring Client Authentication for BGS

To enable client authentication in the BGS make sure you have configured server authentication in the
BGS successfully.

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

Follow these steps to configure client authentication in the BGS Admin UI after configuring 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 appropriate CA
certificate (chain file) or use the Certificate store of the operating system in the CA certificate
editing sub-dialog. Apply the changes to close the pop-up and proceed with the next server
instance if needed.

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 with server authentication, BGS needs to be able to communicate with itself properly, so you
must also modify the communication settings. The settings of the SERVER server instance
configured in step 1 have to match the properties of the communication channels DEFAULT,
DEFAULT_WEB and EXTERNAL_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 sub-dialog and press Apply to close the pop-up and continue with the next channel.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 6-7
© 2022 Siemens
 6. Configure AIG for TLS/SSL

3. Apply all changes and restart BGS.

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

5. Apply all changes in each connected and edited GS instance and restart each of them.

6.3.2 Configuring Client Authentication for GS

To enable client authentication in GS, make sure you have configured server authentication in the GS
successfully.

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

To configure client authentication for the GS instance, follow steps 1 to 3 described in Configuring
Client Authentication for BGS, except replace all references to BGS with GS, i.e., use the GS Admin UI,
use the GS client certificate, and restart GS at the end.

6.3.3 Testing and Troubleshooting Client Authentication

Similar to the server authentication tests, start your BGS and GS instances 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.

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

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

For more details about error messages and some possible solutions, please refer to the Troubleshooting
section.

6-8 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Encrypted Logging

6.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 encrypted messages. For
performance reasons, it is highly recommended to use the logging via UDP, if there is no reason to force
AIG to run on TCP only (e.g., due to firewall configuration).

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

If there is a need to run AIG completely encrypted, i.e., all server instances using TLS/SSL and all log
messages being 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 they are 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 that occurred during the configuration
of TLS/SSL. Any misconfiguration of encrypted logging might result in log lines and files being skipped
and then you will not be able to debug other issues.

6.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 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; then BGS will expect 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 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.

2. Since 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 and edit the LOG
communication channel shown in the table.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 6-9
© 2022 Siemens
 6. Configure AIG for TLS/SSL

b. Set the Transport mode to Encrypted socket (shared secret) and enter the exact same
password as the one 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 BGS.

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

To test the log communication, after the restart, log in to the BGS Admin UI, 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 BGS is usually logging to these channels during
startup. Similarly, you can check the tpapps64*.log log channels for each relevant GS instance from 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, making 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 check that the proper log files have been created where expected and 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 such as those shown in the screenshot below. If you do see any of these log
files, then 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 which log clients are are logging either cryptic
content or no content at all; then, fix their log configuration.

6-10 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Configuring Logging via HTTP using TLS

6.4.2 Configuring Logging via HTTP using TLS

If necessary (e.g., due to firewall settings), AIG can be configured to send logs via TCP (Transmission
Control Protocol), or, to be specific, via HTTP instead of via UDP. This is not the recommended method of
logging since the performance is decreased in comparison to UDP.

It is possible to enable encryption when using this option, which will make AIG use HTTPS instead of
HTTP for the log communication channel. In contrast to UDP logging, each log client does not actually
send log messages to the LOG_SERVER but sends them to the SERVER BGS server instance instead.
Hence, when using this approach, all of the 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 sections.

2. Since the BGS server 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 and modify the
LOG communication channel in the table.

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

c. Apply all your changes and restart the BGS server.

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

To test the log communication, start BGS using the <BGS_ROOT>/bin64/debug executable, which will
allow you to 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 BGS is usually logging to these channels
during startup. Similarly, you can check the tpapps64*.log log channels for each relevant GS instance 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 more details
about TLS/SSL error messages and some possible solutions, please refer to the Troubleshooting section,
below.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 6-11
© 2022 Siemens
 6. Configure AIG for TLS/SSL

6.5 Troubleshooting
In this section, explanations for some typical error messages 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 server and start it again using the <BGS_ROOT>/bin64/debug or
<GS_ROOT>/bin64/debug executable. The debug executable will start 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 tpbgs64_netd.log, tpapps64_netd.log, or the command shell can provide some
more detailed information and hints regarding the error. Here are some messages you can encounter
and some potential reasons 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

There is 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

The server certificate is damaged or the wrong CA certificate (chain) file is configured for 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

The client certificate could not be verified against the CA certificate configured in the server.

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

expired

The server certificate is expired. Renew your certificates.

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

certificate

The Subject Alternative Name of the server certificate probably does not match the host configured in
the corresponding 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

6-12 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Troubleshooting

The 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

The 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 in case it was renamed.

AIG is hanging when 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 being used. Hence, a pass phrase would be needed when
starting each worker. Currently, AIG does not support certificate files with encrypted private keys.

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 file was just copied while the
configuration pop-up in the Admin UI was already open, close and reopen the pop-up to refresh the list
of available certificate files.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 6-13
© 2022 Siemens
 6. Configure AIG for TLS/SSL

6-14 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 7. Job Server Installation
7.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 AIG jobs using a pool that caches all jobs. In addition, BGS includes a
management interface for the AIG Job Server and the jobs. Therefore, the AIG Job Server is also called
the job master. Whenever this documentation mentions the AIG Job Server, it might refer to client
functionality as well. Therefore, this chapter describes the complete configuration of AIG's job
functionality – including the steps on the server and on the client side.

In the BGS Admin UI, select the Configuration entry in the main menu and the Job Server category in
the sidebar. Three settings are shown, as seen in the screenshot below:

• Storage path: the path to the folder where the AIG Job Server stores the jobs. The default value 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). At that time, all jobs which are in the Finished,
Application Error or Runtime Error state and which are older than the storage time defined here are
removed.

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

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

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

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 7-1
© 2022 Siemens
 7. 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.

7.2 Job Agent Configuration

Before configuring an AIG GS server to use Job Agents, be sure to complete its standard configuration (it
must be able to connect to the BGS server, etc...).

In the GS Admin UI, click Configuration → Job Agent. By default, an empty table is displayed, as seen in
the screenshot below. This indicates that there are currently no Job Agents. Therefore, this GS server is
currently unable to execute any jobs.

7-2 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 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 the screenshot below).

The following settings can be specified for each Job Agent:

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

• Active: This is the default setting.

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

• Job pattern: defines the type of jobs this agent may execute; it may be useful to restrict this in some
scenarios (e.g. if they do not all 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.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 7-3
© 2022 Siemens
 7. Job Server Installation

• Use Expert mode to allow this Job Agent to execute only jobs that match a specified Expert
pattern. This expert pattern is matched against a job property value such as 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 keywords 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 keywords 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. Be aware, however, 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*. The next pattern wheel* will be
matched only if no more jobs matching the first pattern remain to be processed. So even if you
have, for example, jobs with the keyword wheel* that have a higher priority than jobs with
car*, these jobs will nevertheless be processed after all jobs with car*.

Note that assigning a job pattern to a Job Agent will not actually force that Job Agent to execute a
particular job. Rather, the job pattern simply indicates which pending jobs the job master is permitted
to assign to that Job Agent.

• 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, this setting defines the
maximum memory allocation allowed before the Job Agent is restarted so that its memory is
released. The recommended setting is 128 MB in Windows or 256 MB in UNIX, respectively.

When first testing the Job Server, we recommend setting as few and simple restrictions as possible.

• 1 Job Agent only

• Execute all jobs

• 128 MB

Be sure complete all basic testing using these simple settings before making any desired modifications,
because complex settings may result in complex error tracking.

7-4 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Set up Teamcenter Multi Connect for AIG Jobs

Caution:

• The number of active job agents is the number of rows with the Active status. Each GS server
can host up to eight Job Agent instances working independently, but in most cases, using only
one is recommended. Consider the expected quantity of jobs when choosing the required
number of instances.

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

• In order for your changes to take effect, you have to click the "apply" button in the upper right
corner to save the changes and restart the GS server.

• After restarting, you should find three (or more) tpapps processes running instead of just two.
The third process is the Job Agent process (one additional process for each Job Agent)

• If you are using "external workers", you may find additional "tpapps" processes.

• Once created, a Job Agent will be visible in the Job management → Agents screen of the BGS
Admin UI of the corresponding Job Server. Depending on network load, etc., it may take up to
two minutes before a newly-created Job Agent will appear.

7.3 Set up Teamcenter Multi Connect for AIG Jobs

It is possible to use different connection data for different types of jobs or for jobs executed by specific
Job Agents.

In addition, it is possible to set the Teamcenter connection data in context of the job being processed, so
that you can use different Teamcenter users when processing different jobs. The connection data and
additional configuration details should be specified by using the following two 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 the T4EA API Reference.

The mandatory parameters define the connection data itself, while the optional parameters define for
which jobs this data shall be used. A call made with only the two mandatory parameters is valid for all
kinds of jobs and its connection data will be used as the default whenever no connection data with a
more specific condition associated is found. If no default connection 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 made.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 7-5
© 2022 Siemens
 7. 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 that should be used as the 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
the order in which they were created.

In this example, 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 document titled T4EA API Reference. The process of selecting which connection
data to use first attempts to match the most detailed Job Agent and attribute settings, then attempts to
match settings defined for job agents only, and finally, if no matches were found, uses the default
connection data. The connection data associated with the first connection setting match 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 the attribute "ITK_TC_USER_ID" set to the user name of the reviewer or
assigner (depending on workflow). At the beginning of the job's execution, the matrix with the
connection data will be checked for any connection data defined for that user name. If nothing is found,
the default connection data will be used. If no default connection data is set, an attempt at auto login
will be made.

7-6 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 8. Troubleshooting AIG Startup Errors
If AIG BGS or GS fail to start, do check the following:

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

Some AIG commands (especially start and stop) create a small file named scs.lock in the tmp directory
to prevent other commands from accessing this process during that time. After a successful
execution, this file is deleted. In some cases (usually due to an improper process interruption, such as
the command window being closed before the process has finished), this file remains, causing AIG
processes to fail to start.

Be sure there is no hanging start or stop 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 command
via the 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 attempt to repair the
shared memory manually by following these steps:

1. Stop all AIG processes.

2. Execute bin64/shmdump in the 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 completing all of these steps, a new share.ca file will have been created and AIG will be able to
run again.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 8-1
© 2022 Siemens
 8. Troubleshooting AIG Startup Errors

8-2 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 9. Monitoring AIG
9.1 Monitoring Introduction
In order to connect AIG to existing monitoring systems, AIG provides a REST interface over HTTPS. The
payload format used is JSON.

Caution:
• This interface only supports real-time monitoring. In other words, AIG provides a sensor data
snapshot when it receives a request over the REST interface. AIG does not store or edit the
sensor data. The persistent storage and processing (e.g. reporting, event triggers, etc...) of the
data must be handled outside of AIG.

• This interface is only responsible for the sensors that are related to the AIG application. System
monitoring, network monitoring, and process watching are not the responsibility of AIG. They
can be done better and more reliably with the sensors provided by the operating system.

• Log-channel-based monitoring is not supported by this interface.

General Concept

The AIG monitoring interface behaves passively. It only supplies data if it is triggered from outside. This
trigger is typically an agent/collector. This means that the AIG monitoring interface supports a data pull
model. AIG never pushes data to the monitoring system.

• Provider (AIG):

AIG serves as the provider, where several sensors are defined. Some of those sensors are predefined
(e.g. total count of jobs), while others can be user defined. The user defined sensors can be set via

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 9-1
© 2022 Siemens
 9. Monitoring AIG

client API; see the document titled API Documentation — T4EA for details. The available monitoring
functionality can be found in namespace ::MONITORING.

For querying the defined sensors, a REST service is provided. This service will return detailed,
structured sensor information.

• Collector (open source or third-party commercial solution):

The collector queries the defined sensors via a REST request. Detailed sensor information is returned
by the REST call as structured JSON. The collector is responsible for periodic polling, persistence, and
processing. This functionality is provided by an agent.

• Database (open source or third-party commercial solution):

The database stores the collected time series of sensor data. This data can be retrieved later for
display in the presentation layer.

• Presentation Layer (open source or third-party commercial solution):

The collected sensor data is processed and displayed in the presentation layer. This may include
displaying the time series of sensor data or displaying sensors that have reached some threshold. If
using thresholds, agents for generating alert messages (e.g. E-Mails, SMS, etc...) can also be defined
here.

Data Translation to JSON

The sensor data saved in the AIG provider is translated to a JSON structure and returned by the REST call.
The sensor naming scheme uses a dot notation, which represents a tree structure. The root of the tree is
hard coded to AIGMONITORING. The levels are separated by a dot.

An example sensor structure:

AIGMONITORING.AAA.BBB.CCC
AIGMONITORING.AAA.BBB.DDD
AIGMONITORING.AAA.EEE.FFF
AIGMONITORING.AAA.EEE.GGG
AIGMONITORING.AAA.HHH

The corresponding tree structure:

AIGMONITORING ---> AAA ---> BBB ---> CCC

| └-----> DDD
|--> EEE ---> FFF
| └-----> GGG
└--> HHH

Translation to JSON:

9-2 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Monitoring Introduction

{
"AIGMONITORING":{
"AAA":{
"BBB":{
"CCC":<c_value>,
"DDD":<d_value>
},
"EEE":{
"FFF":<f_value>,
"GGG":<g_value>
},
"HHH":<h_value>
}
}
}

Caution:
When setting the sensor data in the AIG provider, be aware of the following restrictions:

• Only leaves of the tree should be assigned a value. Attempting to assign a value to an inner tree
node will result in loss of data when the sensor data is translated to JSON.
→ In the example above, attempting to assign a value to the sensor with ID
AIGMONITORING.AAA.BBB would result in loss of data when the sensor data is translated to
JSON.

• The sensors should be set to numeric values only. String and boolean values are not supported,
because metrics are evaluated.

For a detailed example, refer to the section titled Implementation Example via Telegraf™, InfluxDB®
and Grafana® Software.

Sensor Types

AIG provides some predefined sensors, such as one that provides the total count of jobs. In addition, the
user may define his or her own sensors in the AIG provider.

AIG offers the following sensor types:

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 9-3
© 2022 Siemens
 9. Monitoring AIG

• Central Sensors:

Central sensors are independent of any AIG GS/BGS instance. Such comprehensive sensor data is
stored directly on the AIG BGS server.

To set central sensor data, AIG provides several functions, e.g. ::MONITORING::setSensor.

For detailed information on this functionality including some examples, please see the document
titled API Documentation — T4EA.

The following example shows a JSON payload returned by the web service. It includes some user
defined central sensors:

{
"AIGMONITORING":{
"TRANSACTIONS":{
"TOTALCNT":1000,
"ERRORCNT":100,
"WAITCNT":50,
"OKCNT":850,
"TYPE":{
"INPUT":400,
"OUTPUT":600

9-4 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Monitoring Introduction

}
}
}

The following nodes are used in the JSON to represent a central sensor:

• AIGMONITORING: The root of the tree.

• <sensor_id>: Sensor ID. This is the variable name specified by the user, e.g. by passing the name
to the argument sensorId when calling the function setSensor. Example:
TRANSACTIONS.TOTALCNT

• <sensor_value>: Sensor value. Sensor values are contained in the leaves of the JSON tree
structure. A sensor value can be specified by the user, e.g. by passing the value to argument value
of function setSensor. In the example above, the value of sensor TRANSACTIONS.TOTALCNT is
1000.

• Instance Sensors

Instance sensors are dependent on a specific AIG GS/BGS instance and need to be distinguished from
sensors with the same name from different AIG GS/BGS instances. GS instance sensor data is primarily
cached on the GS server itself, and periodically transferred to the BGS server.

All predefined sensors provided out-of-the-box by AIG belong to this group.

For setting instance specific sensor data, AIG provides several functions,
e.g. ::MONITORING::setSensorForInstance.

For detailed information on this functionality including some examples, please see the document
titled API Documentation — T4EA.

The following example shows a JSON payload returned by the web service. It includes the out-of-the-
box AIG sensors, which are instance sensors:

{
"AIGMONITORING":{
"PRODUCTION":{
"SYS":{
"GS_20200513-115633-7bf1ef68-5b5b-4731-b727-acbe4ae6ee7d":{
"MEMUSAGE":{
"VIRTUALMEM":610.609375,
"REALMEM":280.79296875
},
"CPUUSAGE":0,
"CALLSTAT_SUM":{
"UDP":0,
"RPCCALLSTLS":0,

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 9-5
© 2022 Siemens
 9. Monitoring AIG

"RPCCALLS":0,
"NATIVE":0,
"HTTPCALLSTLS":0,
"HTTPCALLS":0,
"HTTP":0,
"ERROR":{
"TLSCALLS":0,
"PLAINCALLS":0
},
"EPIPE":0
}
},
"BGS_20200513-115624-d6a37a77-97fd-4964-b627-40df904f3061":{
"MEMUSAGE":{
"VIRTUALMEM":548.09375,
"REALMEM":312.984375
},
"JOBPOOL":{
"POOL_SIZE_OP":100000,
"POOL_SIZE":0,
"JOBS":{
"WAITING":0,
"RUNTIME_ERROR":0,
"RUNNING":0,
"READY":0,
"FINISHED":0,
"APPLICATION_ERROR":0
}
},
"CPUUSAGE":0,
"CALLSTAT_SUM":{
"UDP":0,
"RPCCALLSTLS":0,
"RPCCALLS":12,
"NATIVE":15,
"HTTPCALLSTLS":0,
"HTTPCALLS":3,
"HTTP":1,
"ERROR":{
"TLSCALLS":0,
"PLAINCALLS":0
},
"EPIPE":0
}
}
}
}
}
}

9-6 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Implementation Example via Telegraf™, InfluxDB® and Grafana® Software

The example consists of two sections for instance sensor data: One for a GS instance, and one for a
BGS instance.

The following nodes are used in the JSON to represent an instance sensor:

• AIGMONITORING: The root of the tree.

• <site>: A site, e.g. DEVELOPMENT, TEST, PRODUCTION. This node enables differentiating
between different systems. The default value is PRODUCTION, as in the example above.

• SYS: A fixed node used to distinguish instance sensor data from central sensor data.

• <unique instance identifier>: The unique GS/BGS instance identifier, used to ensure the
uniqueness of instance sensor IDs. This identifier is generated automatically. In the example above,
there are two unique instance identifiers: GS_20200513-115633-7bf1ef68-5b5b-4731-
b727-acbe4ae6ee7d for the GS instance and BGS_20200513-115624-
d6a37a77-97fd-4964-b627-40df904f3061 for the BGS instance.

• <sensor_id>: Sensor ID. This is the variable name specified by the user, e.g. by passing the name
to the argument sensorId when calling the function setSensorForInstance. Example:
MEMUSAGE.REALMEM

• <sensor_value>: Sensor value. Sensor values are contained in the leaves of the JSON tree
structure. A sensor value can be specified by the user, e.g. by passing the value to the argument
value when calling the function setSensorForInstance. In the example above, the value of
sensor MEMUSAGE.REALMEM is 280.79296875.

9.2 Implementation Example via Telegraf™, InfluxDB® and

Grafana® Software
In the following section, an implementation example is shown using the open source solutions
Telegraf™, InfluxDB® and Grafana®. For details on these solutions, please consult the respective
project web sites.

Caution:
This is an example to show what a complete monitoring solution including all four components
might look like. Please be aware that AIG only supports the setup and configuration of provider
and its components (left box of the picture below). AIG is not responsible for providing the
functionality of or supporting the setup and/or configuration of monitoring applications such as
Telegraf, InfluxDB, or Grafana. Setting up those solutions is the explicit responsibility of the user
and can be done with the help of the documentation on the respective project web sites.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 9-7
© 2022 Siemens
 9. Monitoring AIG

• Provider (AIG):

AIG serves as the provider where several sensors are defined.

It is possible to define your own sensors using the monitoring API; see the document titled API
Documentation — T4EA for details. The available monitoring functionality can be found in
namespace ::MONITORING.

The following example demonstrates how to set six different sensors:

::MONITORING::setSensor TRANSACTIONS.TOTALCNT 1000

::MONITORING::setSensor TRANSACTIONS.ERRORCNT 100
::MONITORING::setSensor TRANSACTIONS.WAITCNT 50
::MONITORING::setSensor TRANSACTIONS.OKCNT 850
::MONITORING::setSensor TRANSACTIONS.TYPE.INPUT 400
::MONITORING::setSensor TRANSACTIONS.TYPE.OUTPUT 600

When a REST request is made by a collector (e.g. Telegraf), the above sensor information is translated
to the JSON structure below and transmitted back to the collector.

{
"AIGMONITORING":{
"TRANSACTIONS":{
"TOTALCNT":1000,
"ERRORCNT":100,
"WAITCNT":50,
"OKCNT":850,
"TYPE":{
"INPUT":400,
"OUTPUT":600

}
}

9-8 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Implementation Example via Telegraf™, InfluxDB® and Grafana® Software

}
}

• Collector (Telegraf):

Telegraf is an agent for collecting metrics.

In order to configure Telegraf properly, perform the following steps (consult the project site for
details):

• Configure Telegraf to use InfluxDB as the output plugin.

• In order to query sensor information from the AIG provider via REST call, the following URL need to
be configured in Telegraf by modifying the file /etc/telegraf/telegraf.conf:

{
... ... ...
[[inputs.httpjson]]
name = "t4x"
servers = [
"http://t4adm:<your t4adm password>@<your BGS host>:11300/MONI/
aigmonitoring",
]
response_timeout = "1s"
method = "GET"
... ... ...

• Database (InfluxDB):

InfluxDB stores the time series of sensor data collected by Telegraf.

InfluxDB should be configured as the output in Telegraf and the input in Grafana.

Please consult the respective project web sites for details.

• Presentation Layer (Grafana):

Grafana is a solution for data visualization and monitoring.

Grafana needs to be properly configured in order to display the time series of sensor data stored in
the database. You will need to perform the following steps (consult the project site for details):

• Add a new data source (InfluxDB) in the front end.

• Set up a dashboard.

• Add new panels including queries.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 9-9
© 2022 Siemens
 9. Monitoring AIG

9.3 Use Nagios® to Monitor AIG (deprecated)

Caution:
The monitoring approach described in this chapter is deprecated as of AIG 20.1. However, if you
have already implemented this approach for monitoring AIG (that is, when upgrading from an
older version), this approach will still work as before. If you are setting up a new monitoring
solution for AIG, we recommend using the approach described in the Monitoring Introduction
section.

Introduction

Nagios® (now known as Nagios Core) is a free and open source software for monitoring systems,
networks and infrastructure. For more information, please visit the project site.

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 server and client installations. If Nagios is already
used in your environment for monitoring IT services, it can be used to monitor 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 BGS. Therefore, the Nagios modules are included in the BGS
installation. However, if you want to monitor a GS instance, 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 the GS
instance.

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

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:

9-10 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Use Nagios® to Monitor AIG (deprecated)

-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)

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
}

Log Server Module

The AIG log server module only works with 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):

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 9-11
© 2022 Siemens
 9. Monitoring AIG

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

Job Server Module

The AIG Job Server module only works with 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
}

Job Agent Module

The AIG Job Agent module only works 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:

9-12 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Use Nagios® to Monitor AIG (deprecated)

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
(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
}

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 9-13
© 2022 Siemens
 9. Monitoring AIG

9-14 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 A. Glossary
A
ABAP
Advanced Business Application Programming: A proprietary programming language of SAP AG.

Admin
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 applies to both the GS and BGS.

AI Object
Application Interface Object.

API
Application Programming Interface.

Apps
Please see GS.

AppServer
Application Server.

B
BAPI
Business Application Programming Interface: SAP interface that allows external programs to access SAP
objects and business processes.

Basic Gateway Service

The component of AIG that is responsible for Licensing, Logging and Job management.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 A-1
© 2022 Siemens
 A. Glossary

BGS
Basic Gateway Service.

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

BMIDE
The Teamcenter Business Modeler IDE (Integrated Development Environment).

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

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

BOP
Bill Of Process: A list of the operations and steps in a manufacturing process along with all their
instructions, consumed materials, resources, work places and machines.

C
CC Object
Collaboration Context Object.

CEP
Camstar Enterprise Platform.

Change Master
An SAP object containing the metadata for a change number. See also Engineering Change Master
(ECM).

Characteristic
An attribute of an SAP class.

CIO
Camstar Interoperability.

D
Data Carrier
See Vault.

A-2 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Dataview
An extension to the Teamcenter RAC (and Active Workspace) that displays real-time Enterprise
Application data associated with a Teamcenter object.

Dataview mark-up
The language understood by the Dataview. The Dataview receives messages written in this language
from the T4x server, formatted as XML or JSON. Users do not normally see such messages, but they
may appear in log files or error messages. The "prop mapping" (e.g., t4s_prop_mapping_template.sd)
contains TCL commands that compose messages in the Dataview mark-up language.

DC_ROOT
The installation directory of Deployment Center (e.g., C:\Siemens\DeploymentCenter).

DCD
Data Collection Definition.

DIR
An SAP Document Info Record.

Document Key
The unique identifier of a Document Info Record consisting of the combination of Document Type,
Document Number, Document Part and Document Version.

Document Structure
A list of the document parts or components and their quantities that are required to assemble a
structured document, similar to a BOM.

E
EA
Enterprise Application.

ECM
An SAP Engineering Change Master.

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

Enterprise Application
Any software or set of computer programs used by business users to perform various business functions
in the context of the current integration portfolio with Teamcenter.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 A-3
© 2022 Siemens
 A. Glossary

EPM
Enterprise Process Modeling.

ERP
Enterprise Resource Planning: The integrated management of main business processes such as
production planning, purchasing inventory, sales, marketing, finance, human resources, and more.

EWI
Electronic Work Instructions.

F
File Stream
A method of directly transferring an Original to SAP rather than using SAPftp or SAPhttp.

FN4S
Opcenter Connect FN for SAP S/4HANA.

G
Gateway Menu
A menu of Teamcenter Gateway functions that is available in the Teamcenter RAC.

Gateway Service
The component of AIG that manages the communication between Teamcenter and Enterprise
Applications and drives the Mapping process.

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

GS
Gateway Service.

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

GUI
Graphical User Interface.

GUID
Globally Unique Identifier.

A-4 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 I
IDGEN
ID Generator: A mechanism to get an external ID from an Enterprise Application when assigning a
Teamcenter ID.

Inspection Plan
A list of characteristics to be inspected in an inspection operation and the associated test equipment to
be used.

iPPE
Integrated Product and Process Engineering: An SAP module that can be used to mange products with
many variants.

ITK
Integration Toolkit: A set of software tools provided by Siemens PLM Software that can be used to
integrate third-party or user-developed applications with Teamcenter.

J
JCO
Java Connector: An interface allowing Java applications to connect to SAP. In the context of , it is now
mostly replaced by the NetWeaver RFC SDK.

JDBC
Java Database Connectivity: An API for the programming language Java that defines how a client may
access a database.

Job
A collection of operations to be performed in the background rather than as part of a user’s interactive
session. The Teamcenter Gateway features asynchronous transfer, which is managed via a Job.

Job Agent
The component of the Gateway Service that executes Jobs.

Job Pool
A queue of all Jobs (whether pending, currently executing or completed) that is managed by the BGS.

Job Server
The component of the Basic Gateway Service that manages the Job Pool and distributes pending Jobs
to Job Agents for processing.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 A-5
© 2022 Siemens
 A. Glossary

JSON
JavaScript Object Notation: A lightweight data-interchange format. (See https://www.json.org/ for more
information.)

K
KPro
Knowledge Provider: A cross-application and cross-media technical information infrastructure within the
framework of SAP. See also Data Carrier.

L
LOV
List of Values: Teamcenter term for a list of selectable values for a property. See also Value Set.

M
Mapping
The part of the T4x configuration that contains the code to control the behavior of the data transfer
between Teamcenter and an Enterprise Application.

MFK
Multi-field key functionality in Teamcenter.

MM
An SAP Material Master.

MOM
Manufacturing Operations Management.

MRP
Manufacturing Resource Planning: A production planning, scheduling and inventory control system used
to manage manufacturing processes.

N
NCN
Non-Conformance Notification.

NetWeaver RFC SDK

Libraries allowing third-party applications to connect to SAP using RFCs. It can be obtained from the SAP
ONE Support Launchpad.

A-6 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 O
Object Key
A string containing 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 two SAP objects such as a Material Master and a Document Info Record.

Object Management Record

An SAP object that links an ECM to another SAP object such as a Material Master or Document Info
Record.

OOTB
Out Of The Box: A feature or function that works without any modification or customization.

Original
A representation of a file in SAP.

OSS Notes
An online patch service for SAP. A specific patch can be identified by its OSS Note number.

P
PIR
An SAP Purchase Info Record.

Portal Transaction
A transfer to an Enterprise Application that is not triggered by a workflow handler but via the Gateway
Menu.

R
RAC
The Teamcenter Rich Application Client. Also referred to as Rich Client or Portal.

Revision Level
An SAP attribute that uniquely identifies the particular version of an SAP Material Master or Document
Info Record associated with a Change Master.

RFC
Remote Function Call.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 A-7
© 2022 Siemens
 A. Glossary

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

SAP GUI
The client application for SAP.

SAP Logon
The application that a user runs 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

The URL of the SAP Integrated View (iView) that can be used to show SAP content in a browser window.

Session Log
A T4x logfile on the BGS containing log information for a specific Teamcenter session in which T4x
functions have been executed.

SSL
Secure Sockets Layer.

T
T4O_ROOT
See GS_ROOT.

T4S 4-Tier Client (SAP Lite)

A stripped down GS that is only able to open the SAP GUI on a Teamcenter 4-Tier Client.

T4x
The entire Teamcenter Gateway product family.

TAO
The ACE ORB: An open-source and standards-compliant real-time C++ implementation of CORBA
(Common Object Request Broker Architecture) based upon the Adaptive Communication Environment
(ACE).

TargetTypeName
The T4x internal name for a transaction type, such as MaterialMaster or DocumentInfoRecord.

A-8 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 TC
Teamcenter.

TCL
Tool Command Language: A high-level, general-purpose, interpreted, dynamic programming language.
(See https://www.tcl.tk/ for more information.)

TCPCM
Teamcenter Product Cost Management.

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

TEM
Teamcenter Environment Manager.

TLS
Transport Layer Security.

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

Transaction Log
A T4x logfile on the BGS containing log information for a specific T4x transaction.

Transfer Window
The window that is displayed when triggering transactions via the Gateway Menu.

Transport Package
A file containing a set of functions that can be imported to SAP.

U
UOM
Unit of Measure.

URI
Uniform Resource Identifier: A string of characters in a specific format (such as a URL or URN) that
unambiguously identifies a particular resource. URIs are often used to identify configurations in Java and

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 A-9
© 2022 Siemens
 A. Glossary

other languages. (See https://en.wikipedia.org/wiki/Uniform_Resource_Identifier for more

information.)

URL
Uniform Resource Locator: A URI that identifies a web resource by specifying its location on a computer
network and a mechanism for retrieving it.

URN
Uniform Resource Name: A URI that identifies a resource by name without specifying a location or
access method.

User Exit (SAP)

SAP program code that is called if an object like a Material Master 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
A T4x logfile on the BGS containing log information written to a customized logchannel.

V
Value Set
SAP term for a list of selectable values for a Characteristic. See also LOV.

Vault
A server where an SAP Document Info Record Original is stored. Also called Data Carrier.

W
WBS
An SAP Work Breakdown Structure.

X
XML
Extensible Markup Language: A format for storing and transporting data that is both human-readable
and machine-readable.

XRT
XML Rendering Template: Also known as an XML Rendering Stylesheet, this is an XML document stored
in a dataset that defines how parts of the Teamcenter user interface are rendered. They are used for the
Rich Client as well as Active Workspace.

A-10 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
 Z
ZPTC
The short name for a Z-Table with the name /TESISPLM/ZPTC, which is used to trigger transfers from
SAP.

Z-Table
A custom SAP table ("Z" is a well-known prefix name for custom tables in the SAP world). In the context
of , this refers to the table /TESISPLM/ZPTC, which is used to trigger transfers from SAP.

Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 A-11
© 2022 Siemens