Teamcenter Gateway for SAP Business Suite Installation Guide

TeamcenterGateway for SAPBusiness Suite-Installation Guide

Contents

Preface 5

Introduction 1-1

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

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

The Active Integration Gateway (AIG) Architecture 4-1

Installation InstructionsOverview of Installation Steps ───────────────────────────── 5-1Installation ───────────────────────────────────────── 5-1

Introduction ─────────────────────────────────────────── 5-1Installation preparations ──────────────────────────────────── 5-2Configure AIG environment using Deployment Center ────────────────── 5-4Deploy the AIG installation on target machine ────────────────────── 5-12

Upgrade AIG Installation ──────────────────────────────── 5-13Necessary actions for a successful upgrade ──────────────────────── 5-13Upgrade AIG via Deployment Center ──────────────────────────── 5-13

Initializing AIG ────────────────────────────────────── 5-14Security Considerations ──────────────────────────────────── 5-15Initialization Prerequisites ────────────────────────────────── 5-16Initializing the BGS ─────────────────────────────────────── 5-18Registering the GS ─────────────────────────────────────── 5-19Running as Windows Service ───────────────────────────────── 5-22

Basic Configuration in the Admin UI ───────────────────────── 5-23User Management ─────────────────────────────────────── 5-24Setting the License Server ────────────────────────────────── 5-25Changing Ports ───────────────────────────────────────── 5-26Setting the BGS Server ──────────────────────────────────── 5-27Verifying the Installation ─────────────────────────────────── 5-29

Teamcenter Templates ───────────────────────────────── 5-29Compatibility with other Templates ──────────────────────────── 5-30

Installation Guide 2© 2019 Siemens

Deploy Active Integration Templates with Deployment Center ──────────── 5-30Deploy AIG Template with TEM ─────────────────────────────── 5-31

Configuring the Mapping ──────────────────────────────── 5-33Configure Teamcenter Environment for AIG ──────────────────── 5-35

Set AIG GS Environment for a Teamcenter 2-Tier Environment ──────────── 5-35Set AIG GS Environment for a Teamcenter 4-Tier Environment ──────────── 5-36Add AIG Error Message Texts to Teamcenter ─────────────────────── 5-36Connectivity to Teamcenter ───────────────────────────────── 5-37

Configure AIG Environment for Teamcenter ──────────────────── 5-37Configure Enterprise Application for AIG ────────────────────── 5-37

Connectivity between SAP and Teamcenter Gateway for SAPBusiness Suite

Content of the hosts and services Files ──────────────────────── 6-1Configure SAP Connection with Netweaver ───────────────────── 6-2Test SAP Connection with Netweaver ───────────────────────── 6-3Configure SAP Connection with JCO ───────────────────────── 6-5Test SAP Connection with JCO ───────────────────────────── 6-6

Configure AIG for TLS/SSLCertificates ───────────────────────────────────────── 7-1Server Authentication ────────────────────────────────── 7-4

Configuring Server Authentication for the BGS ─────────────────────── 7-4Configuring Server Authentication for the GS ─────────────────────── 7-5Testing and Troubleshooting Server Authentication ──────────────────── 7-6

Client Authentication ─────────────────────────────────── 7-6Configuring Client Authentication for the BGS ─────────────────────── 7-6Configuring Client Authentication for the GS ──────────────────────── 7-7Testing and Troubleshooting Client Authentication ──────────────────── 7-7

Encrypted Logging ──────────────────────────────────── 7-8Configuring Symmetric Encryption for Logging ────────────────────── 7-8Configuring Logging via HTTP using TLS ────────────────────────── 7-10

Troubleshooting ───────────────────────────────────── 7-11

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

Troubleshooting the AIG Process Start 9-1

Use Nagios to monitor AIGNagios Introduction ─────────────────────────────────── 10-1Base Server Module ─────────────────────────────────── 10-1Log Server Module ──────────────────────────────────── 10-2

Contents


Job Server Module ──────────────────────────────────── 10-3Job Agent Module ──────────────────────────────────── 10-3

Glossary A-1

4 Installation Guide© 2019 Siemens

PrefaceThis documentation cannot be used as a substitute for consulting advice, because it can never considerthe individual business processes and configuration. Despite our best efforts it is probable that someinformation about functionality and coherence may be incomplete.

Issue: December 2019

Legal notice:

All rights reserved. No part of this documentation may be copied by any means or made available toentities or persons other than employees of the licensee of the Teamcenter Gateway for SAP BusinessSuite® or those that have a legitimate right to use this documentation as part of their assignment onbehalf of the licensee to enable or support usage of the software for use within the boundaries of thelicense agreement.

© 2002-2019 Siemens Product Lifecycle Management Software Inc.

Trademark notice:

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

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

Oracle is a registered trademark of Oracle Corporation.

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

TESIS is a registered trademark of TESIS GmbH.

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


1. IntroductionThis manual explains the installation of the Active Integration Gateway (AIG) software in version 19.2.

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

T4S Teamcenter Gateway for SAP Business Suite

T4O Teamcenter Gateway for Oracle EBS

T4EA Teamcenter Gateway for Enterprise Applications

T4S4 Teamcenter Gateway for SAP S/4HANA

T4CEP Teamcenter Gateway for Camstar Enterprise Platform

TCRA4S Teamcenter Reporting and Analytics Gateway for SAP S/4HANA

FN4T Opcenter Connect FN for Teamcenter

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

FN4S Opcenter Connect FN for SAP S/4HANA

Caution:

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

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

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

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

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

Installation Guide 1-1© 2019 Siemens

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

1. Introduction

1-2 Installation Guide© 2019 Siemens

2. Supported Environment

2.1 Active Integration Gateway Compatibility Matrix

For detailed information on the compatibility of Active Integration Gateway products with operatingsystems, Teamcenter, Teamcenter Product Cost Management, Active Workspace, SAP Business Suite®,SAP S/4HANA®, Oracle EBS, Camstar and Opcenter Execution Foundation Gateway for Teamcenterplease visit Active Integration Software Certifications.

2.2 Web Browser

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

Caution:

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

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

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

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

2.3 Operating Systems

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


http://www.plm.automation.siemens.com/locale/support/gtac/certifications.shtml

https://www.plm.automation.siemens.com/en_us/support/gtac/certifications.shtml

https://www.plm.automation.siemens.com/de_de/support/gtac/certifications.shtml

https://www.plm.automation.siemens.com/de_de/support/gtac/certifications.shtml

Caution:

Linux only: On every machine running AIG (both BGS and GS) make sure that the operatingsystem has the "allowed number of open files" greater than 2048. We recommend the number4096. Please consult the operating system documentation for how to check and configure that.

Windows only: Microsoft Visual C++ Redistributable Packages are required for Active IntegrationGateway (both BGS and GS) on any Windows system. The requirement of the patches depends onthe Operating System and the Teamcenter version in use. In principle, for AIG 19.2 the followingpackages are required:

• Microsoft Visual C++ 2012 Redistributable Package: https://www.microsoft.com/en-us/download/details.aspx?id=30679

• Microsoft Visual C++ 2015 Redistributable Package: https://www.microsoft.com/en-us/download/details.aspx?id=53840

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

2.4 Install Hosts and Locations

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

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

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

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

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



https://www.microsoft.com/en-us/download/details.aspx?id=30679




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 filestorage. Please use local disk and direct attached Storage, iSCSI, Fibre Channel or an equivalenttechnology.

• 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 differentprotocols on the same TCP/UDP port (HTTP and TPRPC). TPRPC is a AIG native TCP protocol.

2.5 Sizing Considerations

Minimum CPU and memory requirements

Minimum CPU recommendation:

Operating System CPU Type Number of CPUs

Windows Intel/AMD 32/64 bit 2

Linux Intel/AMD 64 bit 2

Minimum memory recommendation (free process memory):

Operating System BGSGS in 4-Tier

EnvironmentGS in 2-Tier

Environment

Windows 16 GB 8 GB 8 GB

Linux 16 GB 8 GB 8 GB

Job pool memory and storage size

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

Calculate log file storage size

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

Sizing Considerations


Number of Teamcenter users Minimum disk space for the log storage

< 50 100 GB

50 - 500 500 GB

> 500 1 TB or more

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

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



3. Admin UI

3.1 Administrative User Interface

The Active Integration Gateway Administrative User Interface (Admin UI) is an application that allowsperforming administrative tasks with regard to AIG.

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

Menu Functionalities Overview

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

Common menu entries are:

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

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

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

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

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

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

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


BGS exclusive menu entries are:

• Job management: Control jobs and job agents.

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

Connection and Access to the Admin UI

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

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

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

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

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

3. Admin UI


Caution:

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

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

Admin UI Online Help

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

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

Administrative User Interface


3.2 Admin UI Troubleshooting

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

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

• Activate Java Script for full AIG functionality

• Delete the web browser cache and cookies

• Restart the web browser after the cleaning

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

• Open the Admin UI web page in your Internet Explorer

• Open Settings → F12 Developer Tools or press F12

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

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

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

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

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

• Close the dialog

3. Admin UI


4. The Active Integration Gateway (AIG)ArchitectureAIG is the integration software to enable bidirectional data integration and process coupling betweenTeamcenter and SAP Business Suite®.

AIG consists of two services:


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

Caution:

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

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

4. The Active Integration Gateway (AIG) Architecture


5. Installation Instructions

5.1 Overview of Installation Steps

To install Active Integration Gateway and get it started properly the following steps are required:

1. Install Active Integration Gateway using Deployment Center.AIG has to be downloaded and prepared in the software repository, before you can configure itsinstallation using Deployment Center. In the end the installation has to be deployed to the targetmachine and the templates and plugins need to be deployed in Teamcenter.

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

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

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

5. Configure the Teamcenter environment in AIG.

6. Configure the Enterprise Application for AIG

5.2 Installation

5.2.1 Introduction

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


Caution:

This document's purpose is to guide you through an installation of AIG products via DeploymentCenter. It is highly recommended to make yourself familiar with the Deployment Centerdocumentation, as it will provide you with a better understanding of its functions and concepts.

If you want to install the AIG Teamcenter plugins and templates, it is advised to have apreconfigured environment already containing your Teamcenter installation (which was installedvia the Deployment Center). If you want to install them in a Teamcenter not registered in anenvironment, or a Teamcenter that has been registered after its installation, we recommend usingthe Teamcenter Environment Manager (TEM).

For upgrade scenarios from an old AIG version to AIG 19.2, please refer to Active Integration -Migration Guide for migrating AIG mapping, preferences and workflows.

With version 19.2, we prohibit the installation of the Active Integration Gateway Services in anenvironment containing a Teamcenter installation. While it will still be possible to select the ActiveIntegration Gateway Services' software packages and configure the respective components, thedeployment script will fail at the beginning of the procedure, leaving you with a Teamcenterenvironment with no further possibility to make changes. You would have to delete theenvironment and reregister the Teamcenter installation into the Deployment Center.

Acquire the AIG installation packages

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

5.2.2 Installation preparations

The extracted AIG installation packages need to be placed in the Deployment Center repository. Werecommend 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 therespective AIG installation packages next to each other into the repository.



https://docs.plm.automation.siemens.com/content/pl4x/19.2/T4S/en_US/migration_guide/preface.html

https://docs.plm.automation.siemens.com/content/pl4x/19.2/T4S/en_US/migration_guide/preface.html

http://www.siemens.com/gtac

http://www.siemens.com/gtac

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

External libraries

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

The currently supported external libraries are:

• SAP libraries comprise the files libicudecnumber.dll/.so, libsapucum.dll/.so, sapjco3.dll/ libsapjco3.so,sapnwrfc.dll/ libsapnwrfc.so, sapjco3.jar, sapnwrfc.ini and the saplogon.properties.These files can also be included in the 4-tier Gateway Service client installation.

Installation preparations


Note:

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

Edit the deployer.properties

For a clean installation experience, edit the file <DC_Root>/repo/system/deployer/deployer.properties.There, you need to add GS_Comp,BGS_Comp and GS_4TIER_Comp to the propertyCOMPONENTS_TO_SKIP_INTEROPERABILITY_FOR.

5.2.3 Configure AIG environment using Deployment Center

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

• Select AIG Software packageFor the installation of the Active Integration Gateway Services, you need to create a newenvironment. For this, add the Active Integration Gateway - Active Integration Gateway Servicesfor <TC_version> software package to your newly created Environments list of selected software.



• Select the environment optionDeployment Center provides two different modes for your installation - either a single box or adistributed installation.Single Box installation: The selected software is being installed on a single machine, which may workin testing environments. This mode is not allowed for a productive environment, as our GS and BGSinstances 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 onseparate machines.

Configure AIG environment using Deployment Center


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



• Configure the AIG componentsThe 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 theApplications section, the 4Tier Gateway Service Client. While the amount of BGS instances in yourenvironment is limited to one, you can install as many instances of the GS as well as 4Tier GatewayService Clients as needed, by clicking on the + symbol, choosing them from the AvailableComponents 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 pathselsewise.



Configure Gateway Service component

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



ConfigureBasic Gateway Service component

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

4Tier Gateway Service component

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



Generate the deploy script

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



5.2.4 Deploy the AIG installation on target machine

In order to execute the deployment, you need to have your Deployment Center repository configured asshare, or at least a location containing all packages needed for the installation. This share needs to bemounted 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 targetmachine where it has to be extracted.

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

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

If the target machine's operating system is Windows and the share containing the software packages ismounted 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 environment variable is seton the target machine. If you are installing in an environment also containing Teamcenter, alsospecify the JAVA_HOME environment variable. Your Deployment Center host must be reachableover the network.

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

5.3 Upgrade AIG Installation

5.3.1 Necessary actions for a successful upgrade

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

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

Caution:

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

5.3.2 Upgrade AIG via Deployment Center

For the upgrade of T4S, you need to select the respective environment in the Deployment Center, clickon the + symbol right next to the list of installed software packages, select the Active IntegrationGateway Services for <TC_Version> 19.2.0.<TC_Version> software package and click on UpdateSelected Software.

Necessary actions for a successful upgrade


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

5.4 Initializing AIG

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

Security Considerations

Initialization Prerequisites

Initializing the BGS

Registering the GS

Running as Windows Service



5.4.1 Security Considerations

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

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

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

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

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

Security Considerations


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

5.4.2 Initialization Prerequisites

AIG requires a platform-specific OS password manager to be available and initialized. On Windowsplatforms the Credential Manager available on all supported versions is assumed. For Linux thestandard but not out of the box installed software pass is required. The installation and configuration ofpass is a bit tricky and assumes that GnuPG (gpg) is installed and configured for the operating user, sothat the password store can be initialized with a proper GPG key.

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



Caution:

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

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

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

Prerequisites for Windows

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

Note:

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

Prerequisites for Linux

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

Note:

Usually the GPG key is secured by a passphrase, which is cached for a dedicated time and alsocleaned after a restart of the host. When expired the passphrase has to be entered in aninteractive screen. As a consequence AIG cannot start until someone enters the passphraseinteractively.

Troubleshooting

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

::Bootstrapping::SecureStorageSanityCheck: Accessing secure storage failed

Initialization Prerequisites


https://www.passwordstore.org/

https://gnupg.org

https://gnupg.org

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

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

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

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

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

5.4.3 Initializing the BGS

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

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

Caution:

The loss of the password entered in initpassword, i.e., the database encryption key leads to a lossof all data stored in the secure database!

Similarly, the deletion of the UUID in the BGS, effects that the BGS can no longer find thepassword in the OS password manager, also leading to a loss of all data.

Initialization steps

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



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

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

Troubleshooting

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

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

• Timeout reached without fetching the passwordThe password has not been fetched by the BGS within the time limit. Check if you have started theBGS of the same installation within the time limit and make sure the BGS has not been initialized yet.Adapt the host and port settings if needed (see above). Especially on Linux, view thebootstrap_errors.log log file to detect errors with the OS password manager, see InitializationPrerequisites.

• Wrong uuid: 'd73a9d91-5eed-46c4-bc95-164e26290b6c' @ 127.0.0.1:54176A BGS with the shown UUID tried to fetch the password, but has the wrong UUID, i.e., is not the BGSbelonging to this installation. Make sure you are using initpassword and BGS of the same installation.

5.4.4 Registering the GS

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

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

Registering the GS


Manual approval steps

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

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

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

Automatic registration

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

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

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

Registration in the context of Teamcenter

The AIG libraries loaded in Teamcenter also do authenticated calls to BGS/GS. Therefore, the informationhow 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 thescript Register Tc Database Connection in the GS Admin UI to register the Teamcenter databaseinstance in the GS.



Caution:

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

Blocking compromised GSs

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

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

Troubleshooting

In case the GS cannot start view the <GS_ROOT>/tmp/bootstrap_errors.log. The logmessage ::Bootstrapping::checkBGSConnection failed with: HTTP call failed(expected HTTP/1.1 200 OK) indicates that the BGS could not be reached. This could mean thatthe BGS is not running, the BGS settings in the GS are not correct, the GS has been blocked or deleted inthe BGS Admin UI.

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

• The preferred option to register the GS with the same UUID again, login to the GS host with the OSuser operating it. Delete the key Siemens_PL4x_<UUID>/internal/token from the OS passwordmanager, 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 approvedin the BGS Admin UI. This solution should not be preferred, because there will be remains in the OSpassword manager belonging to the old UUID.In case the script Register Tc Database Connection has been used before, it has to be run againwhen the GS has been initialized successfully.

The error message ::Bootstrapping::tryRegisterUUID: This GS is pending and hasnot been enabled in the BGS Admin UI yet usually means that the GS has reached the BGSand initially registered, but an administrator has not yet approved it in the BGS Admin UI. If you wereusing the automatic registration token (see above) make sure the token matches the current oneconfigured in the BGS.

Registering the GS


Refer to Initialization Prerequisites, if themessage ::Bootstrapping::SecureStorageSanityCheck: Accessing secure storagefailed is shown, indicating that the OS password manager cannot be accessed.

5.4.5 Running as Windows Service

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

Caution:

• When running as service never start or stop the BGS/GS at any time manually!

On the one hand switching the OS user will not work due to the way AIG is initialized. On theother hand executing the software creates files in some subdirectories of the BGS/GS which canhave different access policies if run by a user directly or as service. Handling the Windowssecurity guidelines and the access management can become very tricky.

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

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

• We do not recommend starting AIG GS as a Windows service in a Teamcenter 2-Tier clientenvironment. Instead it should be started together with Teamcenter, for example by calling thefile <GS_ROOT>/bin64/restart.exe in the portal.bat.

Furthermore, bright transaction e.g. displaying a material master would start the SAP GUIinvisible due to the security context.

Installing the service

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

• Creating a Windows service for the AIG BGS

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

• Creating Windows service for the AIG GS

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

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



https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create

https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create

Stopping the service

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

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

2. Open Windows Settings → Scripts.

3. Select Shutdown.

4. Open the Properties and Add the shutdown script.

5.5 Basic Configuration in the Admin UI

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

User Management

Setting the License Server

Changing Ports

Setting the BGS Server

Basic Configuration in the Admin UI


Verifying the Installation

5.5.1 User Management

Initial Password of the Default User

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

Caution:

There is no recovery, if "t4adm" is the only administrator and you have lost the password for theaccount!

Best practice is to configure an LDAP and import at least one user with the role administrator, sothat the password of the administrator is managed outside of AIG and can be reset more easily.

User Management

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

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

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

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

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



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

5.5.2 Setting the License Server

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

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

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

Setting the License Server


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

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

5.5.3 Changing Ports

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

Specifiy your port in the pop-up dialog.



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

Caution:

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

5.5.4 Setting the BGS Server

Setting the BGS server in the GS

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

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

Setting the BGS Server


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

Save the modification and restart GS in the Admin UI.



Setting the BGS host to enable download links

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

5.5.5 Verifying the Installation

You can check the installation of AIG GS and AIG license information by executing the InstallationVerification 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 licenseinformation.

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

5.6 Teamcenter Templates

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

• Compatibility with other Templates

• Deploy AIG Template with TEM

• Deploy Active Integration Templates with Deployment Center

Verifying the Installation


5.6.1 Compatibility with other Templates

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

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

5.6.2 Deploy Active Integration Templates with Deployment Center

Caution:

You should only use the Deployment Center for the distribution for the Teamcenter templates andplugins, if you already have an existing Teamcenter installation in your environment, that has alsobeen installed via Deployment Center. In case you have installed Teamcenter with TEM, pleasefollow the corresponding installation instructions Deploy AIG Template with TEM

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

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

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



packages to the list of selected software:

5.6.3 Deploy AIG Template with TEM

Caution:

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

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

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

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

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

3. Select Perform maintenance on an existing configuration

4. Select your desired database

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

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

Deploy AIG Template with TEM


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

7. Then, in the same window, the new feature appears and has to be checked. To deploy T4S or T4S4template, the new feature Teamcenter Gateway for SAP Business Suite under Extensions should beselected.

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 clientextensions. However in some environments this will not always happen. To make sure clientextensions are installed, please also select the corresponding template "<AIG> for Rich Client".

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

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

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



Caution:

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

• Be sure to use the correct TEM for the desired Teamcenter installation: check that it shows thecorrect 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.bator tem.sh.

• As a result the following library libt4s must be included under theTC_customization_libraries preference in Teamcenter

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

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

5.7 Configuring the Mapping

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

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

Configuring the Mapping


https://docs.plm.automation.siemens.com/content/pl4x/19.2/T4S/en_US/generic_configuration_guide/preface.html

https://docs.plm.automation.siemens.com/content/pl4x/19.2/T4S/en_US/generic_configuration_guide/preface.html

Mapping structure and basics

Out of the box the mapping source directory <GS_ROOT>/var/mmap does not contain any mapping at allbut only placeholder directories. You can start from scratch with your own mapping, copy your existingfiles or the AIG mapping templates to start with. The mapping templates can be found in<GS_ROOT>/var/template/t4x/mmap and <GS_ROOT>/var/template/t4s/mmap. For the demo templatescopy the files from <GS_ROOT>/var/template/t4xdemo/mmap and <GS_ROOT>/var/template/t4sdemo/mmap instead.

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

Mapping compilation and deployment

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

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

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

3. Restart the GS to load the new mapping.

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



https://docs.plm.automation.siemens.com/docs/pl4x/19.2/en_US/API_Doc_t4s.zip


To automatically compile, copy, deploy and load the mapping select the Generate Mapping and ServerHot Deployment Mode. The same behavior can be achieved using the <GS_ROOT>/bin64/mmapexecutable. 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 thescript and/or the executable.

5.8 Configure Teamcenter Environment for AIG

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

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

• Add AIG Error Message Texts to Teamcenter

• Connectivity to Teamcenter

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

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

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

Configure Teamcenter Environment for AIG


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

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

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

Caution:

As a Teamcenter 2-Tier environment, the adjustment of the Teamcenter start script should bedone to all Teamcenter clients.

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

In order to integrate AIG functionalities (i.e., AIG workflows handlers) into Teamcenter, Teamcenterneeds to know the AIG environment and AIG libraries which should be loaded during Teamcenter start.In a Teamcenter 4-Tier environment, the AIG environment file should be called during pool or net servermanager start.

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

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

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

5.8.3 Add AIG Error Message Texts to Teamcenter

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

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

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

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



5.8.4 Connectivity to Teamcenter

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

There are basically three options:

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

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

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

5.9 Configure AIG Environment for Teamcenter

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

set TC_ROOT=C:\Siemens\tc12set TC_DATA=C:\Siemens\tcdatacall %TC_DATA%\tc_profilevars.bat

5.10 Configure Enterprise Application for AIG

For the information about the configuration of SAP ERP for AIG, please refer to the TeamcenterGateway for SAP Business Suite - SAP Business Suite Preparation Guide.

Connectivity to Teamcenter


https://docs.plm.automation.siemens.com/content/pl4x/19.2/T4S/en_US/preparation_guide/preface.html


6. Connectivity between SAP andTeamcenter Gateway for SAP BusinessSuite

6.1 Content of the hosts and services Files

The hosts and services files need to be configured to include the SAP system host names and serviceport(s). Normally this is done automatically if SAP GUI has been installed on the local machine. If not ithas to be done manually.

Hosts example

C:\windows\system32\drivers\etc\hosts (or /etc/hosts)

# <IP address> <host name> [aliases...] [#<comment>]134.244.102.231 sapsrv sapsrv.dev.tplocal134.244.102.235 sapet2 sapet2.dev.tplocal134.244.102.238 sapet3 sapet3.dev.tplocal

Services example

C:\windows\system32\drivers\etc\services (or /etc/services)

# <service name> <port number>/<protocol> [aliases...] [#<comment>]sapgw00 3300/tcpsapgw01 3301/tcpsapgw02 3302/tcpsapgw03 3303/tcpsapgw04 3304/tcpsapgw05 3305/tcpsapgw06 3306/tcpsapgw07 3307/tcpsapgw20 3320/tcp


Caution:

Make sure that the host is reachable and the port is open in case there is a firewall between theSAP system and the machines where T4S will be installed. This can be checked with telnet viacommand shell telnet sapsrv.dev.tplocal 3300.

The telnet feature needs to be enabled in your Windows installation to run this command.

In case of an error you will receive a message like this:

Connecting To sapsrv.dev.tplocal...Could not open connection to thehost, on port 3300: Connect failed.

6.2 Configure SAP Connection with Netweaver

Using SAP Netweaver requires some previous deployment:

• Deployment of the SAP Netweaver SDK library files to <GS_ROOT>/bin64. For more details please seeSAP Netweaver SDK in the Teamcenter Gateway for SAP Business Suite - SAP Business SuitePreparation Guide

• Deployment of the configuration file sapnwrfc.ini, which defines the available SAP connections forT4S. The configured file needs to be placed in <GS_ROOT>/etc.A template can be found in <GS_ROOT>/var/template/sap . It can also be created automatically by theT4S GS script Build sapnwrfc.ini template.

Additionally the Netweaver library files are required. Those can be downloaded from the SAP downloadportal. Please refer to the Active Integration Software Certifications to see which Netweaver libraryfits to your Active Integration Gateway version.

Caution:

If you have updated from a previous AIG version: The file saprfc.ini has been replaced withsapnwrfc.ini. The parameter RFC_TRACE is now called TRACE.

The SAP RFC SDK and the Netweaver RFC SDK have some library files in common. When deployingthe Netweaver library files "over" an already deployed RFC SDK, make sure that the Netweaverlibrary files replace the existing older RFC library files.

The file transfer with SAPftp and SAPhttp still requires the SAP RFC libraries.

Be sure to keep a backup of all files until AIG has been fully tested, because the newest DLL filesmay not be correct for your SAP system and you might still need the older version.

Enable SAP Load Balancing

Adapt the variable TYPE in the sapnwrfc.ini file as follows:

TYPE=B

6. Connectivity between SAP and Teamcenter Gateway for SAP Business Suite




http://www.plm.automation.siemens.com/locale/support/gtac/certifications.shtml

If set to "B", then AIG connects to a "message server". Instead of the parameter ASHOST you have toconfigure the parameter MSHOST with the host system of the message server.

A detailed explanation of all parameters can be found in the configuration file itself.

6.3 Test SAP Connection with Netweaver

Testing

The script SAP connection test in the GS Admin UI (file name Base/sapconnect.tcl) can be used in orderto verify if the deployment of Netweaver has been performed correctly.

The credentials to connect to SAP are stored centrally in a database on the BGS. Therefore, you need torun the action Define and Store Credentials Alias first, to define a credentials dataset to be used toconnect. This action also tests the connection and only stores the credentials dataset, if the connectionwas established successfully. Afterwards, the action Validate Stored Credentials Alias can be used atany time to test the connection with an already existing Credentials Alias fetching the credentials fromthe BGS.

If no error message is shown, the Netweaver deployment is working successfully.

Store T4S Credentials for ET5 with Alias 'MyCredentialsAlias' overwrite: noValidating connection...

#################################+++ INFO: Connection to ET5 is OK#################################

###########################################Connected to destination: ET5Connected to client: 800###########################################SAPNWRFC Library Version: 750 Patch Level 2########################################################################Backend System is: SAP Business Suite (R3)####################################

Test SAP Connection with Netweaver


Caution:

Validate AutoLogin checks the credentials alias defined and stored for test scripts only, i.e., forthe mode SCRIPTING. For example:

T4X::CONNECTION2EA::setCredentialsAlias4UseCase T4S ET5@800 MyCredentialsAlias SCRIPTING::T4X::CONNECTION2EA::selectActiveConnection2EA T4S "*" "ET5" "800"

Troubleshooting

If the test fails, check the following:

• The configuration as described in last chapter Configure SAP Connection with Netweaver.

• Check if you can log on to SAP using SAP GUI on the same system.

• If the configured SAP system host and port can be reached or are blocked by a firewall. See alsoContent of the hosts and services Files.

• Check if the required modifications described in the Chapter Netweaver RFC SDK and SAP FunctionCalls Used and Permissions Required in the Teamcenter Gateway for SAP Business Suite - SAPBusiness Suite Preparation Guide have been met.

Testing the NW RFC Connection

In the SAP Netweaver RFC SDK package you have downloaded from SAP you will find startrfc.exe. Thistest executable from SAP can be used to check the RFC connection to the SAP system. It consumes allthe libraries from the Netweaver SDK package. This test will also produce meaningful trace files.

Caution:

This test only checks the NW RFC connection to the SAP system from the actual host. This does notmean that the obtained NW RFC SDK is the correct version for T4S!

You can run the check as follows:

startrfc.exe -h <ashost> -s <sysnr> -u <user> -p <password> -c <client> -l EN -t -i

Options of the executable are:

-h <ashost> SAP application server to connect to this needs to include the SAP router string if





applicable -s <sysnr> system number of the target SAP system -u <user> user -p <passwd> password -c <client> client -l <language> logon language -D <destination> destination defined in RFC config file sapnwrfc.ini -F <function> function module to be called, only EDI_DATA_INCOMING or EDI_STATUS_INCOMING is supported -E PATHNAME=<path> path, including file name, to EDI data file or status file, with maximum length of 100 charachters -E PORT=<port name> port name of the ALE/EDI interface with maximum length of 10 charachters -t enable RFC trace -help or -? display this help page -v display the version of the NWRFC library and the version of the compiler used by SAP to build this program -i connect to the target system and display the system info

The result should look like this:

SAP System ID: ET5SAP System Number: 02Partner Host: partnerhost123xOwn Host: MYHOST01Partner System Release: 750Partner Kernel Release: 749Own Release: 721Partner Codepage: 4103Own Codepage: 4103User: MYSAPUSERNAMEClient: 800Language: E

6.4 Configure SAP Connection with JCO

Steps to enable an SAP connection with JCO:

• Copy the jar file sapjco3.jar into the directory <GS_ROOT>/lib (same file name and directory for allplatforms).

Configure SAP Connection with JCO


• Copy the SAP JCO libraries (e.g., *.dll, *.pdb, *.sl, *.so,…) into the directory <GS_ROOT>/bin64 (samedirectory for all platforms).

• Deployment of the configuration file saplogon.properties which defines the available SAPconnections and connection data for JCO. It can be created automatically by using the GS script Buildsapnwrfc.ini template.

Caution:

New custom calls should be implemented via the Netweaver interface.

In the long term, existing JCO calls should be replaced by Netweaver calls.

6.5 Test SAP Connection with JCO

Testing

After the JCO connection has been configured and set up, check the functionality as follows: Start theJCO test script SAP JCO test. It allows entering a debug file name as parameter (optional) and requires aconnection to SAP that has been established already (e.g. by the script SAP connection test).

If everything is correct, the output is something like the following (before and after these lines there ismore information shown):

v jco_call v--- 8< --- Output -------------------------------------------------::TPSAP::JCO::JCO_test finished with >OK<----------------------------------------------------------::sap_result_array(USER_NAME) = TPUSER01::sap_result_array(DATE_FORMAT) = DD.MM.YYYY::sap_result_array(DECIMAL_SIGN) = ,::sap_result_array(SAP_SYSTEM_RELEASE) = 701::sap_result_array(LANGUAGE) = E--- >8 ------------------------------------------------------------^ jco_call: GOOD ( 1.23s) ^

(...) _____________ / /



__/ Net Result /___________________________________________________

GOOD ( 3.15s) :)___________________________________________________________________ script call exit

Caution:

Before executing the script, a connection to some SAP system has to be established. One way toachieve this is by using the script SAP connection test that was used to test the Netweaverconnection.

Troubleshooting

If there should be any error message, check your JCO installation using the instructions above. Be sure toset the correct Java path in the GS configuration. If the setting is default, then the path from the systemvariable JRE_HOME or JAVA_HOME is used.

Check the executable path that the GS actually uses. This may be done as follows:

• Using the GS Admin UI:Open Monitoring → Details → Process list and check the path of all the java processes in theCommand column.

• Asking the operating system:In Linux, enter the following in a command shell and check the output: ps -aef | grep java.In Windows use an external process information tool that shows the complete command line, e.g.,the tool "Process Explorer". The following screenshot shows it running with the process java.exe(highlighted in green) running in C:\Windows\system32:

This tool has the additional advantage that it shows directly the process that started the one you arelooking for. In the shown example java.exe has been started by a tpapps.exe, so it is our desired JCOjava process.

Please verify the content of the services file C:\Windows\System32\drivers\etc\services. Example:

Test SAP Connection with JCO


sapgw01 3301/tcp # SAP System Gateway Portsapdp01 3201/tcp # SAP System Dispatcher PortsapmsDMA 3600/tcp # SAP System Message Server Port

A logfile with debug information can be written in case of problems. To enable the log, set the followingenvironment variable in the file <GS_ROOT>/var/conf/script/t4x_cust.bat or t4x_cust.sh to an existing filepath of your choice:

set TP_JCO_LOG="C:/temp/JCO.log".

Disable debugging afterwards because the file will grow larger over time.



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

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

Caution:

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

7.1 Certificates

Caution:

AIG provides some self-signed demo certificates out of the box, which are not secure and have tobe replaced with your own for production use. These demo certificates are bound to the localhostdomain name and will not work for installations on separate hosts. Active Integration can not anddoes not provide any certificates for your installation or any consulting on how to obtain thesecertificates, 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 athird-party vendor. Please contact your IT support to obtain valid certificates, accordingly.

AIG requires X.509 pem encoded certificates using the *.pem file extension. Other files with no or adifferent extension will not be shown in the UI and cannot be used during the configuration. The serverand client certificates used need to contain the public certificate and its associated private key (usuallythe key is inserted before the certificate). The private key of the certificate file must not be encrypted, asAIG 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 orclient 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 oneclosest to the certificate root.

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


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 thefile extension *.cer or *.crt, therefore it is necessary to check the content of the file asmentioned in the next step. Since AIG will only view *.pem files in the Admin UI you have toreplace or add this file extension if necessary.

2. Open the certificate file using an text editor and check that each of the following sections can befound once in the server and client certificate:-----BEGIN RSA PRIVATE KEY----- … -----END RSA PRIVATE KEY----------BEGIN CERTIFICATE----- … -----END CERTIFICATE-----If you cannot read the content of the file then this is probably not a PEM encoded file. Thecertificate 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 keysections.

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

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

b. openssl verify -CAfile yourChain.pem yourCertificate.pemVerifies that your server or client certificate has been issued by the CA defined in your CAcertificate (chain). The output has to end with OK.

c. openssl rsa -check -noout -in yourCertificate.pemCheck the consistency of the private key contained in the certificate file. RSA key ok indicatesthat the private key is correct, otherwise RSA key error is shown.

d. openssl x509 -noout -dates -in yourCertificate.pemPrints the validation dates of the certificate. Make sure that the current date is in betweenthose dates. Otherwise the certificate is already expired or not valid yet.

e. openssl x509 -in yourCertificate.pem -noout -pubkey | openssl md5openssl rsa -in yourCertificate.pem -pubout | openssl md5The output of both commands has to match exactly to make sure that the public keycontained in the certificate section matches the public key portion contained in the privatekey section. Otherwise the wrong private key has been copied to the wrong certificate file.

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

7. Configure AIG for TLS/SSL


https://www.openssl.org/

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

g. openssl crl2pkcs7 -nocrl -certfile yourChain.pem | openssl pkcs7 -print_certs -nooutPrints the subject and issuer chain in the order contained in the CA certificate (chain) file. Therecommended order is from the most specific certificate to the most generic root (or mostproximate to the root) certificate. Though AIG does not consider the order of the certificatesin the CA certificate (chain) file you have to make sure that the chain is complete without anygaps.

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

Place your certificate files in the <BGS_ROOT>/etc/cert and <GS_ROOT>/var/conf/cert respectively tomake them available for AIG and the configuration dialog of the Admin UI.

Caution:

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

Using the certificate store of the operating system

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

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

2. Enable the OS certificate store for AIG depending on your OS:For Windows run the executable <AIG_ROOT>\bin64\t4xsynccerts.exe to synchronize all currentlystored CA certificates of the certificate store to the file <AIG_ROOT>/var/conf/cert/ca-certificates.crt. When AIG is configured to use the certificate store, it will search for the accordingcertificate in this file.

Caution:

The t4xsynccerts.exe requires that the execution of PowerShell scripts is allowed otherwise itfails. Please refer to the documentation for Execution Policies by Microsoft to solve this issue.

Any changes to the content of the OS certificate store are not reflected by the ca-certificates.crt file. If needed, update the file running the executable again.

Certificates


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

7.2 Server Authentication

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

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

7.2.1 Configuring Server Authentication for the BGS

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

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

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

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

1. Open Configuration → Server instances and edit all server instances that should send acertificate for verification. For each server instance enable the Encryption in the dialog for editingand select the BGS server certificate in the Server certificate editing dialog. Apply the changes toclose 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 theSERVER server instance. To operate the Admin UI using TLS, edit the ADMIN_UI20 server instance.

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

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

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



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

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

3. Apply all changes and restart the BGS.

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

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

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

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

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

5. Apply all changes and restart the GS.

7.2.2 Configuring Server Authentication for the GS

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

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

• The corresponding CA certificate (chain) file has to be placed in the <GS_ROOT>/var/conf/certdirectory or in the certificate store of the operating system (see Using the certificate store of theoperating system).

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

Configuring Server Authentication for the GS


7.2.3 Testing and Troubleshooting Server Authentication

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

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

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

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

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

7.3 Client Authentication

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

7.3.1 Configuring Client Authentication for the BGS

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

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

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

1. Open Configuration → Server instances and edit all server instances that should request andverify a client certificate. Edit each relevant server instance and select the according CA certificate(chain file) or use the Certificate store of the operating system in the CA certificate editingdialog. 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 SERVERserver instance. To operate the Admin UI using client authentication in the browser, edit theADMIN_UI20 server instance.

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

3. Apply all changes and restart the BGS.

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

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

7.3.2 Configuring Client Authentication for the GS

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

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

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

7.3.3 Testing and Troubleshooting Client Authentication

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

To test the client authentication configuration of the Admin UI you have to import the client certificateto the browser or OS certificate storage first. For more information on how to do this, please refer to thedocumentation of your web browser or operating system. Afterwards open your web browser and try toaccess 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. Ifeverything works correctly, the login page will be shown.

Configuring Client Authentication for the GS


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

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

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

7.4 Encrypted Logging

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

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

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

7.4.1 Configuring Symmetric Encryption for Logging

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

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

Caution:

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



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

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

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

c. Apply all your changes and restart the BGS.

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

To test the log communication after restart, login to the Admin UI of the BGS, open Log → System andcheck the most recent content (consider the timestamps in front of each log line) of several log files. Forexample, check the tpbgs64*.log log channels as the BGS is usually logging to these during the start.Similar you can check the tpapps64*.log log channels for each relevant GS in the same menu. Makesure 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) andclient (communication channel) do not match. Check the configuration again, make sure that theencryption of the server instance and communication channel is turned on and that both are using theexact same shared secret. Additionally run some tests to produce log lines (e.g., execute any test scripts)and do not only check if proper log files have been created where expected, but also check the contentof the Log → User menu in the BGS Admin UI. It should not contain any log channels with cryptic namesand content as shown in the image beneath. If you do see any of these log files one of your clients isusing a different shared secret than the log server and hence producing unusable log content. Check theconfiguration to find the log client which is either logging cryptic content or not at all to fix its logconfiguration.

Configuring Symmetric Encryption for Logging


7.4.2 Configuring Logging via HTTP using TLS

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

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

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

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

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

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

c. Apply all your changes and restart the BGS.



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

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

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

7.5 Troubleshooting

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

SSL/TLS handshake failures in the log output

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

• SSL error:140760FC:SSL routines:SSL23_GET_CLIENT_HELLO:unknown protocolUnencrypted communication with an encrypted server. Check if the communication channel isconfigured correctly.

• SSL error:14094418:SSL routines:ssl3_read_bytes:tlsv1 alert unknown caServer certificate is damaged or a wrong CA certificate (chain) file is configured in the communicationchannel. Check the validity of your server certificate and if it matches the CA certificate you are using.

• SSL error:14089086:SSL routines:ssl3_get_client_certificate:certificateverify failedClient certificate could not be verified against CA certificate configured in the server.

• SSL error:14094415:SSL routines:ssl3_read_bytes:sslv3 alert certificateexpiredServer certificate is expired. Renew your certificates.

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

Troubleshooting


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

• SSL error:0906D06C:PEM routines:PEM_read_bio:no start lineSSL error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM libServer certificate does not contain the private key. Make sure the server and client certificates containa certificate and private key section.

• SSL error:0906D06C:PEM routines:PEM_read_bio:no start lineSSL error:140DC009:SSL routines:SSL_CTX_use_certificate_chain_file:PEM libServer certificate file exists but it does not contain a certificate section. Make sure the server andclient certificates contain a certificate and private key section.

• SSL error:02001002:system library:fopen:No such file or directorySSL error:20074002:BIO routines:FILE_CTRL:system libSSL error:140DC002:SSL routines:SSL_CTX_use_certificate_chain_file:systemlibThe selected certificate cannot be found. Check if the file exists in the <BGS_ROOT>/etc/cert or<GS_ROOT>/etc/cert respectively. Check the spelling of the file, maybe it has been renamed.

Hanging AIG asking for pass phrase

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

Certificate is not visible in the Admin UI

Make sure that the certificate file is available in <BGS_ROOT>/etc/cert or <GS_ROOT>/etc/certrespectively. Check that the file has a *.pem file extension. If the files have just been copied after theconfiguration pop-up in the Admin UI has already been opened, close and reopen the pop-up to refreshthe list of available certificate files.



8. Job Server Installation

8.1 Job Server Configuration

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

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

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

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

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

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

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


Caution:

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

8.2 Job Agent Configuration

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

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



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

The following settings can be specified for each Job Agent:

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

• Active: By default, an agent is activated.

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

• Job pattern defines the type of jobs this agent may execute, e.g. if not all of them have a correctTeamcenter 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 flagset.

Job Agent Configuration


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

Caution:

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

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

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

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

• 1 Job Agent only

• Execute all jobs

• 128 MB

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



Caution:

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

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

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

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

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

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

8.3 Set up Teamcenter Multi Connect for AIG Jobs

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

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

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

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

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

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

Set up Teamcenter Multi Connect for AIG Jobs



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

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

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

Caution:

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

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. Forexamples refer to the T4S API Reference. The process to check for the connection data starts from themost detailed Job Agent and attribute settings and iterates through the settings for job agents onlydown to default. The first fitting connection setting found is used.

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




9. Troubleshooting the AIG Process StartIf AIG BGS or GS could not be started, please check the following points:

• First check for the <BGS_ROOT>/tmp/scs.lock or <GS_ROOT>/tmp/scs.lock file.Some AIG commands (especially start and stop) create a small file scs.lock in the tmp directory toprevent other commands accessing this process during that time. After the successful execution, thisfile is deleted. In some cases (mostly because of an improper process interruption, e.g., its commandwindow has been closed before it finished), this file remains and then the AIG processes will fail tostart.Be sure there is no hanging process to start or stop a AIG process, then just delete the file scs.lock andtry again.

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

1. Stop all processes.

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

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

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

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

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

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


9. Troubleshooting the AIG Process Start


10. Use Nagios to monitor AIG

10.1 Nagios Introduction

Nagios (now known as Nagios Core) is free and open source software for monitoring systems, networksand infrastructure. For more information, please visit https://www.nagios.org/.

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

• Base Server Module

• Log Server Module

• Job Server Module

• Job Agent Module

The AIG modules are tested with Nagios core 3.4.1.

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

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

10.2 Base Server Module

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

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


https://www.nagios.org/

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

bin64/tps var/init/start.ngs_server

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

Nagios command (example):

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

10.3 Log Server Module

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

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

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

bin64/tps var/init/start.ngs_log

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


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



10.4 Job Server Module

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

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


bin64/tps var/init/start.ngs_batch

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


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

10.5 Job Agent Module

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


bin64/tps var/init/start.ngs_batchclient

T4x Job Agent CRITICAL - oberon (SunOS)/16612 winab100-64 (Windows NT)/3516 winab100 (Windows NT)/520 win28ab91r2 (Windows NT)/3672 winab100

Job Server Module


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


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



A. Glossary

A

ABAPABAP is a proprietary programming language of the SAP AG.

Adminis 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 UIWeb based administrative user interface of the GS and BGS.

AIGThe entire Active Integration Gateway product family.

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

AI-ObjectApplication-Interface Object

APIApplication Programming Interface.

AppsSee "GS".

AppServerApplication Server.

B

BAPIThe Business Application Programming Interface allows external programs to access objects andbusiness processes in SAP.

BGSBasic Gateway Service.

Installation Guide A-1© 2019 Siemens

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

BMIDETeamcenter Business Modeler IDE (Integrated Development Environment)

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

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

BOPThe Bill Of Process describes a manufacturing process and lists the operations and steps with all theirinstructions, consumed materials, resources, work places and machines.

C

CCObjectCollaboration Context Object

CEPCamstar Enterprise Platform

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

CharacteristicAn characteristic is an attribute of a SAP class.

CIOCamstar Interoperability

D

Data CarrierPlease see Vault.

A. Glossary

A-2 Installation Guide© 2019 Siemens

DataviewThe Dataview is an extension to the Teamcenter RAC and is deployed as part of the TEM installationprocess of the Teamcenter Gateway. The Dataview is used to display the real-time data of externalapplications, associated with Teamcenter objects.

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

DCDData Collection Definition

DIRDIR is the abbreviation for a SAP Document Info Record.

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

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

E

EAstands for Enterprise Application, any software or set of computer programs used by business users toperform various business functions in context of current integration's portfolio with Teamcenter.

ECNThe Engineering Change Notice can also be called an Engineering Change Note, Engineering ChangeOrder (ECO), or just an Engineering Change (EC).

EPMEnterprise Process Modeling

EWIElectronic Work Instructions


F

File StreamMethod of transfer to send an original to SAP.

FN4SClosed Loop Manufacturing for SAP S/4HANA®

G

Gateway MenuAn additional menu item of the Teamcenter Gateway software available in the Teamcenter RAC.

GRMThe Generic Relationship Management provides a general way in which two objects can be associatedvia a relationship.

GSGateway Service, manages the communication between Enterprise Applications.

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

GUIGraphical user interface.

GUIDGlobally Unique Identifier

I

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

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

iPPEIntegrated Product and Process Engineering is a SAP Business Suite® module that can be used to mangeproducts with many variants.

A. Glossary


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

J

JCOThe Java Connector is an interface to SAP Business Suite®. In the context of T4S it is now mostlyreplaced by the Netweaver RFC interface.

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

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

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

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

JSONJavaScript Object Notation is a lightweight data-interchange format1.

K

KProKpro stands for Knowledge Provider. See also Data Carrier.

L

LOVList of Values

1 JSON.org


http://www.json.org/

M

MappingThe mapping is part of the T4x configuration. It contains the code that controls the behavior of the datatransfer between Teamcenter and the ERP system.

MFKMulti-key functionality in Teamcenter.

MMMM is the abbreviation for a SAP Material Master.

MOMManufacturing Operations Management

N

NCNNon-Conformance Notification

NetWeaver RFC SDKThe NetWeaver RFC SDK contains libraries for 3rd party applications to connect to SAP Business Suite®. Itcan be obtained from the SAP ONE Support Launchpad.

O

Object KeyThe Object Key is a string that contains the ID of an Enterprise Application object. If the identifier is acombination of multiple keys, then the Object Key is a combination of those keys in a defined order andformat.

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

Object Management RecordBelongs to a SAP Change Number and Documents changes of one particular SAP object like a MaterialMaster.

OOTBOut of the box

A. Glossary


OriginalA representation of a file in SAP.

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

P

PIRPIR is an abbreviation for a SAP Purchase Info Record.

Portal TransactionThis means that a T4S transfer to SAP that is not triggered by a workflow handler but via the T4SGateway Menu.

R

RACstands for Rich Application Client also referred to as rich client or portal.

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

RFCRemote Function Call (SAP)

S

SAPSAP S/4HANA® / SAP Business Suite®

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

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

SAP Portal iView URLCan be used to show sap content in a browser window.


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

SSLSecure Sockets Layer.

T

T4O_ROOTPlease see GS_ROOT

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

T4xThe entire Teamcenter Gateway product family.

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

TargetTypeNameThis is the T4x internal name for the transaction type. E.g. MaterialMaster orDocumentInfoRecord.

TCTeamcenter

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

TCPCMTeamcenter Product Cost Management

TCPCM4STeamcenter Product Cost Management Gateway for SAP S/4HANA

TEMTeamcenter Environment Manager

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

A. Glossary


Transaction LogThe Transaction Log is a T4x logfile on the BGS. It contains log information for a specific T4x transaction.

Transfer WindowThe Transfer Window triggers transactions via the Gateway Menu.

Transport PackageA file that contains functions that can be imported to SAP.

U

UOMUOM stands for Unit of Measure.

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

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

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

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

V

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


https://en.wikipedia.org/wiki/Uniform_Resource_Identifier

https://en.wikipedia.org/wiki/Uniform_Resource_Identifier

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

W

WBSWBS is an abbreviation for a SAP Work Breakdown Structure.

X

XMLExtensible Markup Language is designed to store and transport data in a format that is both human- andmachine-readable.

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

Z

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

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

A. Glossary


Siemens Industry Software

HeadquartersGranite Park One5800 Granite ParkwaySuite 600Plano, TX 75024USA+1 972 987 3000

AmericasGranite Park One5800 Granite ParkwaySuite 600Plano, TX 75024USA+1 314 264 8499

EuropeStephenson HouseSir William Siemens SquareFrimley, CamberleySurrey, GU16 8QD+44 (0) 1276 413200

Asia-PacificSuites 4301-4302, 43/FAIA Kowloon Tower, Landmark East100 How Ming StreetKwun Tong, KowloonHong Kong+852 2230 3308

About Siemens PLM SoftwareSiemens PLM Software is a leading globalprovider of product lifecycle management(PLM) software and services with 7 millionlicensed seats and 71,000 customersworldwide. Headquartered in Plano, Texas,Siemens PLM Software workscollaboratively with companies to deliveropen solutions that help them turn moreideas into successful products. For moreinformation on Siemens PLM Softwareproducts and services, visitwww.siemens.com/plm.

© 2019 Siemens. Siemens, the Siemenslogo and SIMATIC IT are registeredtrademarks of Siemens AG. Camstar, D-Cubed, Femap, Fibersim, Geolus, I-deas, JT,NX, Omneo, Parasolid, Solid Edge,Syncrofit, Teamcenter and Tecnomatix aretrademarks or registered trademarks ofSiemens Industry Software Inc. or itssubsidiaries in the United States and inother countries. All other trademarks,registered trademarks or service marksbelong to their respective holders.

Teamcenter Gateway for SAP Business Suite Installation Guide

Documents

Transcript of Teamcenter Gateway for SAP Business Suite Installation Guide