Installation Guide
Installation Guide
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.
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
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
Monitoring AIG
Monitoring Introduction ─────────────────────── 9-1
4 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
Contents
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.
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.
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.
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.
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:
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.
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.
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.
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
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, …).
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
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.
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.
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.
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
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.
Pro: reduces the above described complexity on a server, automatic failover cluster
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.
1. Project scope
2. Assumption
All servers are virtualized. Please remember: Do not overcommit the resources of a host!
3. Installed products
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
• 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
6. Sizing proposal
• Development environment
BGS
GS
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):
=> Memory: 12 GB
• Test environment
BGS
Use 1 core for 4 threads => 8 / 4 = 2 => use 2 cores for BGS
GS
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
=> 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)
1 GS (16 threads) host with 64GB free RAM and > 4 Cores
• Production environment
BGS
GS
4000 concurrent Teamcenter users => 10% concurrent AIG users for synchronous export
transactions ( 0.1 * 4000 = 400):
2-8 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
High-availability Cluster
=> 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)
min. 6 GS (16 threads) hosts with 64 GB free RAM and 5 Cores each
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.
Both BGS and GS have their own interfaces with common and unique functionalities.
• 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).
• 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
• Log files: View and analyze transaction, system, workflow, session and user log files.
• 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 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.
• 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.
If you use Internet Explorer and the Admin UI web page stays blank, please check the document mode
settings of your browser:
• 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:
• Remove the check mark next to Display intranet sites in Compatibility View
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.
• 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:
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.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.
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.
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
• 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
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.
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.
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
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
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
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.
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
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
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
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:
• If you are installing on Linux, make sure the destination directory for your installation belongs
to the user executing the script.
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:
• Inside of <BGS_ROOT>\var have following permissions for <Account>, outside of it read permissions
for files and read and list permissions for folders:
5-12 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
File System Hardening
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:
• Inside of <GS_ROOT>\var have following permissions for <Account>, outside of it read permissions for
files and read and list permissions for folders:
Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-13
© 2022 Siemens
5. Installation Instructions
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.
To upgrade an AIG product from previous versions to 22.1, perform the following steps:
• 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.
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.
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
In the <AIG Installation Directory>/tmp directory, you will find a file named extendedSkip.tcl – it contains
a list with all detected changed files.
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
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).
Security Considerations
Initialization Prerequisites
Registering the GS
TLS/SSL Configuration
Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-17
© 2022 Siemens
5. Installation Instructions
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.
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.
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.
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
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:
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.
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.
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:
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).
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.
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.
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.
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
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 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.
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.
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.
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.
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.
Instead of restart.exe, the executable file t4xservice.exe should be used to start BGS and GS as
Windows services.
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
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:
4. Select Shutdown.
5-28 Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1
© 2022 Siemens
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.
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.
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.
User Management
Changing Ports
Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 5-31
© 2022 Siemens
5. Installation Instructions
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:
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.
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.
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
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
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
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.
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.
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.
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
• Workflow task EAX2LogonTask which can be added to workflows to enable EA login, connection
verification and interactive selection.
• Preferences specifying blocklists and allowlists to restrict the amount of attributes during data
extraction for the OOTB Teamcenter data model.
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.
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:
• 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
• 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!
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!
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
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
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
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 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
For more details, see the chapter titled "Manage a development environment" in the Basic Configuration
Guide — T4EA.
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.
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.
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.
• Connectivity to Teamcenter
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.
• %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:
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.
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:
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.
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>.
• 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.
set TC_ROOT=C:\Siemens\tc<VersionNumber>
set TC_DATA=C:\Siemens\tcdata
call %TC_DATA%\tc_profilevars.bat
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".
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.
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
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:
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.
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).
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
• It is strictly recommended to run this Redis server instance exclusively for AIG and not run different
applications on the same Redis server instance.
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.
Example
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).
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.
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
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:
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/.
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.
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.
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.
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
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.
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.
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:
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).
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.
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.
The communication between Teamcenter and GS is encrypted, provided encryption is configured for the
GS instance.
• 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.
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.
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.
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.
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.
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.
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
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.
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.
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
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.
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.
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
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.
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.
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.
There is unencrypted communication with an encrypted server. Check if the communication channel
is configured correctly.
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.
The client certificate could not be verified against the CA certificate configured in the server.
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.
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.
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.
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.
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.
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.
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).
• 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.
• 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.
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 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.
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:
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.
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:
4. Repair all entries beginning with # CHECK => damaged by editing them manually and save
the file.
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.
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.
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.
The database stores the collected time series of sensor data. This data can be retrieved later for
display in the presentation layer.
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.
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.
AIGMONITORING.AAA.BBB.CCC
AIGMONITORING.AAA.BBB.DDD
AIGMONITORING.AAA.EEE.FFF
AIGMONITORING.AAA.EEE.GGG
AIGMONITORING.AAA.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.
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:
• <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.
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:
• <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.
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):
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.
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):
In order to configure Telegraf properly, perform the following steps (consult the project site for
details):
• 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 should be configured as the output in Telegraf and the input in Grafana.
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):
• Set up a dashboard.
Teamcenter Gateway for Enterprise Applications - Installation Guide, Teamcenter Gateway for Enterprise Applications 22.1 9-9
© 2022 Siemens
9. Monitoring AIG
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:
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.
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)
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
The AIG log server module only works with BGS. The following optional parameters can be passed:
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
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
}
The AIG Job Server module only works with BGS. The following optional parameters can be passed:
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
define command{
command_name check_T4xJobs
command_line cd /home/work/t4x_bgs &&
bin64/tps var/init/start.ngs_batch
}
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
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.
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.
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.
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 .
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.
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
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 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