Release Notes
Abstract
These release notes contain the information required to install and configure IBM Sterling Transformation Extender, version 11.0.1.0
Content
© Copyright IBM Corporation 2005, 2016. All rights reserved. © Copyright HCL Technologies Ltd. 2017, 2024. All rights reserved.
=====================================================================
CONTENTS
=====================================================================
About this release
Installation and configuration
Design Server
Runtime and monitoring
API-specific installation
Adapter-specific installation and configuration
Upgrade and migration
New and changed behavior
SSL Configuration
Resolved Authorized Program Analysis Reports (APARs)
Known Issues
Software Development Kit notes
Launcher notes
Contacting customer support
Notices and trademarks
ABOUT THIS RELEASE
=====================================================================
Where to find the software to download
To download the software for this version of the IBM Sterling Transformation Extender, go to Passport Advantage. This location will direct you to the Passport Advantage (PA) and Passport Advantage Express (PAE) overview page. Passport Advantage (PA) and Passport Advantage Express (PAE) are comprehensive IBM programs by which Clients may order Eligible Products. Customers can search PA and PAE for the following part numbers to download files.
Part numbers for IBM Sterling Transformation Extender Base V11.0.1.0 Multiplatform Multilingual eAssembly (G0BR3ML) Images:
- Design Studio Windows - M0J1ZML
- Runtime and Monitoring AIX - M0J22ML
- Runtime and Monitoring Linux - M0J23ML
- Runtime and Monitoring Windows - M0J25ML
- Runtime and Monitoring zLinux - M0J24ML
- Design Server Linux - M0J26ML
Part number for IBM Sterling Transformation Extender Design Studio V11.0.1.0 Windows Multilingual eAssembly (G0BR1ML):
- Design Studio Windows - M0J1ZML
Program number for IBM Sterling Transformation Extender z/OS V11.0.1.0 - 5655-RA2
Program number for IBM Sterling Transformation Extender z/OS Subscription & Support V11.0.1.0 - 5655-R97
Program number for Subscription & Support 5655-R97 - 5655-RA2
For details about supported hardware and software, see the system requirements.
Additional product documentation is available only in the online documentation. No documentation is installed with the product.
For answers to frequently asked questions and workarounds for known problems in all product releases, see the IBM Support website.
The release notes in this document apply to the components listed below. There are also sections for notes that apply to specific components.
- Transformation Extender Design Server
- Transformation Extender Design Studio
- Transformation Extender Runtime and Monitoring
All images provided by IBM Sterling Transformation Extender are digitally signed by IBM. Signature can be verified by following the steps outlined in the markdown document included within the distribution archive file for Linux, zLinux and AIX platforms. For Windows platform installer executable files, signature can be easily verified by checking the ‘Digital Signatures’ tab in the Properties window.
IBM Runtime Environment, Semeru Java Technology Edition
Transformation Extender V11.0.1.0 installs the operating system-appropriate version of IBM® 64-bit Runtime Environment, Semeru Java™ Certified Edition, Version 17.0.10.0.
Use the installed version of the runtime environment. If you configure IBM Sterling Transformation Extender to use a different runtime environment, it must be the same version as the installed runtime environment.
The IBM Runtime Environment, Java Technology Edition is not included with the IBM Sterling Transformation Extender for z/OS® product, V11.0.1.0. IBM Sterling Transformation Extender for z/OS customers can download it from z/OS® or from Shopz.
About Federal Information Processing Standard (FIPS) support, see the Statement of direction on FIPS support in Java Runtime Environment provided by IBM Sterling Transformation Extender.
About translations
Transformation Extender products are available in the following languages:
- Brazilian Portuguese
- English (United States)
- French
- German
- Italian
- Japanese
- Korean
- Simplified Chinese
- Spanish
- Traditional Chinese
IBM Sterling Transformation Extender products display in English if the IBM representative of a country did not choose to translate them.
The IBM Sterling Transformation Extender online documentation has been translated into French.
For the latest product information, see the English online documentation.
Support for other IBM product integrations
Support for other IBM product integrations is not available in this version of product release. IBM App Connect Enterprise (ACE), IBM Sterling B2B Integrator (SI), IBM Sterling Transformation Extender Advanced (ITXA) and IBM DataPower Gateway integrations are not supported in this release. Lack of support for Java 17 in the other IBM products at this time and the necessary integration updates required to support IBM product integrations are the reasons for not having support in this product release.
INSTALLATION AND CONFIGURATION
=====================================================================
Supported platforms
This version of Transformation Extender is supported on the following platforms:
- AIX
- Windows
- Linux (x64)
- Linux for System z®
- z/OS
When you use IBM Sterling Transformation Extender with another product, ensure that you satisfy the system requirements of the base product and apply all required fixes to the base product. See the support portal for information about product fixes.
Installing Design Studio and Runtime and Monitoring on Windows operating systems
Design Studio and Runtime and Monitoring are installed by default under C:\Program Files directory for Administrator user accounts. It is highly recommended to use ‘Run as administrator’ option while installing them to the default directory. The elevated privileges for Administrator user accounts allow proper installation of the product components.
When installing Design Studio Patch for any issue with Design Studio in future for this version of software, ensure that the Design Studio application is running under Administrator mode. Use ‘Run as administrator’ when starting Design Studio for installing Design Studio Patch.
Since C:\Program Files directory is protected, elevated administrator privileges are required for proper installation of Design Studio Patch on the existing Design Studio installation. Without elevated privileges, installation of Design Studio Patch would not install the patched component(s) successfully to an existing Design Studio installation.
Installing the example files
For example, to install Transformation Extender example files on Windows operating systems, follow these steps:
- During installation of Design Studio, click Custom installation in the Setup Type window.
- Ensure that Example Files is selected in the Select Components window.
Design Studio installs the example files in the data directory folder:
data_dir\examples
The Typical installation of Runtime and Monitoring does not install example files. Use the Custom option to install the example files. Example files are only installed when Design Server option is selected.
Changing the JVM heap size in Design StudioDesign Studio sets a default Java® Virtual Machine (JVM) heap size. You can adjust the heap size of the JVM to meet the needs of your installation. To change the heap size, edit the install_dir\DesignStudio\itx_eclipse\eclipse\eclipse.ini file and change the value of the -Xmx1024m parameter. For example, to set the default heap size to 512 MB, change -Xmx1024m to -Xmx512m.
Installing on Windows operating systems
Before using third-party software with Transformation Extender installed on your Windows operating systems, check with your vendor to ensure that it is compatible with the operating system.
Overriding the default UTF-8 encoding of XML documents
UTF-8 is the default encoding when an XML document does not explicitly specify the encoding. Use the DTX_SCHEMA_ENCODING Language Environment variable to override the default encoding. The encoding that you specify applies to all input and output cards in a map.
- In a Launcher environment, the encoding applies to the XML input and output of all maps in the Launcher instance.
- In an IBM App Connect Enterprise environment, the encoding applies to the XML input and output of all maps in the broker where the variable is set.
export DTX_SCHEMA_ENCODING=IBM-1047
Malloc-bucket memory allocation in 64-bit Launcher on AIX systems
An APAR in AIX® V7 versions can cause memory corruption in processes that use malloc buckets. When malloc buckets are enabled, the memory corruption causes crashes or hangs in random Launcher processes on 64-bit Transformation Extender on AIX systems.
To avoid this memory corruption, Transformation Extender enables malloc buckets only when the AIX APAR is fixed on the computer where the Launcher is installed. This is because one of the following conditions exists:
- The APAR fix is included in the installed version of AIX
- The required AIX APAR fixes are installed:
- AIX V7.1: APAR IV28148
Malloc buckets set Mon Mar 2 13:51:41 EST 2022 HOME: /AIX_install_dir
The log file is discarded when AIX restarts.
Configuring the size and number of the Launcher system_name_timestamp.log file
The config.yaml configuration file can specify the maximum size of the Launcher system_name_timestamp.log file and the maximum number of log files to keep before the oldest log file is deleted. See the Launcher documentation for details about the CircularLogSize and CircularLogFileNum options.
Configuring UNIX environment variables
The environment variables required to execute a Transformation Extender map or system must be set prior to execution.
You can set the environment variables PATH, DTX_TMP_DIR, DTX_DATA_DIR, and DTX_HOME_DIR, as well as the appropriate library path variable for your platform, by running the setup program:
After you log on to your computer, source the setup program in the Transformation Extender installation directory before executing a map or system file (using the Launcher). This sets the required environment variables for this session only. Modify the .profile script to set the environment variables for all sessions.
The following command procedure assumes that your UNIX command line environment is the Korn (ksh) shell.
. /install_dir/setup
where install_dir is the directory where you installed the Transformation Extender base product. For example, if /home/itx is the installation directory, source the . /home/itx/setup command.
There must be a space between the initial source operator (.) and the command path.
Soft DATA segment or heap size on UNIX systems
The default setting for the Soft DATA segment or heap size parameter can cause problems on UNIX platforms. The root user must reset the Soft DATA Segment value to a value larger than the default.
NOTE: On AIX platforms, use the IBM smit (System Management Interface Tool) utility to reset the Soft DATA Segment value.
Set this value one time for each user, not one time for each session). Choosing the correct value depends on the following factors:
- Amount of memory available on the machine.
- Size of data being processed.
- Type of processing occurring on the respective data.
- Other major applications that run on the machine.
If memory permits, start with the default value and increase it as needed. Use the following command to test the value by temporarily setting the value within your own environment:
ulimit -d <value>
When you set the Soft DATA Segment value, the change takes effect only for the current session.
Required IBM XL C/C++ runtime package maintenance level on AIXEnabling Launcher Cooperative Listener for Files
To enable cooperative file listening for the Launcher, you must modify the data_dir\config\config.yaml and add the yaml path:
/runtime/m4file/FileListenCooperativeListener: true
NOTE: The yaml path, along with other /runtime/m4file settings have been added to config.yaml for 11.0.1.0.
Microsoft .NET Framework 4.0 requirementTransformation Extender requires .NET Framework 4.0 to register an assembly such as dtxInterop.dll.
- Download and install .NET Framework 4.0.
- To ensure that the current dtxCOM.dll is registered:
- Unregister the current dtxCOM.dll:
regsvr32 /u dtxCom.dll - Register the V11.0.1.0 dtxCOM.dll:
regsvr32 dtxCom.dll
- Unregister the current dtxCOM.dll:
Invoke the regasm utility from the Microsoft.NET\Framework directory. For example:
C:\Windows\Microsoft.NET\Framework\v4.0.30319\regasm dtxInterop.dll
Before you open the Design Studio
By default, Eclipse applications cache plug-ins. In certain circumstances, the default Eclipse behavior might prevent Design Studio from opening, cause Design Studio to be unstable, to exhibit the behavior of an earlier release, or cause the run map process to fail.
To avoid these problems, take one of the following steps before you open the Design Studio application:
- Clear the cached version of the Design Studio plug-ins by running the cleanextenderstudio.bat file. The cleanextenderstudio.bat file is installed at the root of the install_dir directory.
- Delete the .metadata folder that is in your workspace, and then import the workspace again, or switch to a different workspace.
- Your workspace became corrupted.
In this case, the open process fails when Eclipse attempts to open the Design Studio. - You installed a patch provided by the Transformation Extender customer support team that copied files to the itxstudio directory.
In this case, when Eclipse attempts to open the Design Studio, it uses the cached versions of the Design Studio plug-ins from the prior release on which this patch was installed, which causes the open Design Studio process to fail. - You installed a fix pack release on top of a Transformation Extender 11.0.x release.
In this case, when Eclipse attempts to open the Design Studio, it uses the cached versions of the Design Studio plug-ins from the prior release on which this fix pack was installed, which causes the open Design Studio process to fail.
- You ran a map that could not be loaded into memory, which caused the map to fail and the Design Studio application to terminate abnormally. When you tried to reopen the application, the open process failed.
When attempting to run the setup for the Design Studio or Runtime and Monitoring, the Run option does not appear on the pop-up window. This prevents the installation of the setup. To resolve this issue, complete the following steps:
- Right-click on the Design Studio or Runtime and Monitoring setup file and select the Run as administrator option.
If the Run option does not appear on the pop-up window, perform steps from 2 through 7. - Right-click on the Design Studio or Runtime and Monitoring setup file and select the Properties option.
- Under the General tab, locate the Unblock checkbox.
- Check the Unblock checkbox.
- Click on the Apply button to save the changes.
- Click on the OK button to confirm the changes.
- Right-click on the Design Studio or Runtime and Monitoring setup file and select the Run as administrator option.
The Run option now appears on the pop-up window.
DESIGN SERVER
=====================================================================
RUNTIME AND MONITORING
=====================================================================
NOTE: Before using third-party software with Transformation Extender, check with your vendor to ensure that the software is compatible with the operating system.
To install Runtime and Monitoring on Windows systems:
On Microsoft® Windows® systems, download and run the executable file. On Windows systems, Transformation Extender products are installed in the following default directory:
To install Runtime and Monitoring on Linux, zLinux and AIX systems:
A single Linux® and AIX installation provides the Map Command Server, Launcher, Transformation Extender API and monitoring tools. The supported UNIX® shells are ksh and bash.
- Download and extract the archive (.tgz) file to a directory of your choice.
- Go to the installation directory and run the setup command:
. ./setup
Use the dtxcmdsv execution command to run a map with the Map Command Server.
To create your own SSL self-signed certificate with attributes that meet the needs of your Design Server execution environment, follow these steps:
- Install Design Server:
a. Download the *.tar.gz file to any Linux OS.
b. Use gunzip to uncompress the *.tar.gz file
c. tar -xvf the *.tar file
d. Run ./install.sh script file
e. Run ./start.sh - To interact with the container tx-client run the following from the Linux prompt:
docker exec -it tx-client /bin/bash - cd ssl-certificates/self-signed
- Use command vi server-crt.cnf and change localhost to the hostname being used for the docker install of Design Server.
- Use command vi server-crt.ext and change localhost to the hostname being used for the docker install of Design Server.
- Under directory ssl-certificates/self-signed verify the script file, genselfsigned.sh.
- chmod +x genselfsigned.sh to allow execution of the script.
- Execute:
. ./genselfsigned.sh - You are prompted several times to provide a password phrase. Make sure the password phrase is complex for greater security.
- Exit from the tx-client container.
- Stop all four containers (mongodb, redis, tx-client and tx-server) by using the command:
./stop.sh - Start all four containers (mongodb, redis, tx-client and tx-server) by using the command:
./start.sh - Open a browser to import the certificate.
- In the Chrome browser, click on the vertical ellipsis and select Settings.
- Under Settings, click Advanced.
- Under Privacy and security select Manage certificates the Certificates window opens.
- Under the certificates window click Import to install the certificate. When the certificate installs it is displayed under the Authorities tab.
- Download the IBM Sterling Transformation Extender installation package to all Windows systems where you want to install the IBM Sterling Transformation Extender.
- Install IBM Sterling Transformation Extender interactively and record your installation responses by running the setup executable file as follows:
install_dir\txrt_11.0.1.0_build_win64.exe -r
Your responses during installation are recorded in the C:\Windows\setup.iss response file. - Copy the setup.iss response file to the Windows system where you want to silently install IBM Sterling Transformation Extender.
- Silently install IBM Sterling Transformation Extender by running the package executable file as follows. Note that there is no space between the -f1 keyword and the full path to the setup.iss file:
install_dir\txrt_11.0.1.0_build_win64.exe -s -f1full_path\setup.iss
This step replicates all your responses from the interactive installation.
Additional UNIX runtime information:
Do not execute the setup program if you want to configure the environment variables manually. If you decide not to use the setup script, you must manually set the shared library path according to your platform. Use the DTX_TMP_DIR environment variable to set the location of temporary files, as described in the following procedure.
Set location for temporary files (DTX_TMP_DIR):
During map execution, the Command Server creates temporary files for resource handling and for retaining debug information. The default directory for these temporary files is /tmp. To specify a different directory for temporary files, set the DTX_TMP_DIR environment variable. For example:
DTX_TMP_DIR=install_dir/tmp
export DTX_TMP_DIR
If multiple users or groups are to access the Command Server engine, define DTX_TMP_DIR instead of using the default /tmp directory. Define and export the DTX_TMP_DIR variable manually or with the setup script. The directory specified for DTX_TMP_DIR must have permission 777 to provide permission to the user, the group, and all others. Define and export the DTX_TMP_DIR variable before you set the directory permission. To set the permission, run the chmod command:
chmod 777 $DTX_TMP_DIR
Enabling environmental debug information (DTX_DEBUG):
When the DTX_DEBUG environment variable is defined, the Command Server can produce environmental diagnostic information that can be helpful when a problem is encountered during map execution. By default, the DTX_DEBUG environment variable is not defined and environmental diagnostic information is not recorded.
When you define the DTX_DEBUG environment variable, environmental diagnostic information is recorded in a file named dtxinfo.log located in the directory defined by the DTX_TMP_DIR environment variable (or in the /tmp directory, if DTX_TMP_DIR is not defined).
To enable the environmental debug facility, set the DTX_DEBUG environment variable to TRUE. For example:
DTX_DEBUG=TRUE
export DTX_DEBUG
To disable the environmental debug facility, set the DTX_DEBUG environment variable to FALSE. For example:
DTX_DEBUG=FALSE
export DTX_DEBUG
The following is a sample of the information contained in the environmental debug file:
PROCESS_ID: 2309, API_REF: 1
Date/Time: Fri Jul 25 14:30:09.279783 2022
FILE: mercmain.c, line: 714
info: [IBM Sterling Transformation Extender Product Version: 11.0.1]
PROCESS_ID: 2309, API_REF: 1
Date/Time: Fri Jul 25 14:30:09.280252 2022
FILE: mercmain.c, line: 744
info: [IBM Sterling Transformation Extender RUNNING: Fri Jul 25 14:30:09 2022]
PROCESS_ID: 2309, API_REF: 1
Date/Time: Fri Jul 25 14:30:09.470357 2022
FILE: mercrun.c, line: 1951
New Map File - Fri Jul 25 14:30:09 2022
[/install_dir/examples/general/map/sinkmap/sinkmap.mmc]
Tracing I/O problems (DebugName and DebugAppend):
You can set the DebugName and DebugAppend options in the config.yaml file under /runtime/Connections Manager to enable the Map Command Server to trace I/O-related problems. These options are as follows:
Where:
- file_name is the name of the debug file for the Connections Manager.
- false disables the append specification so that the debug information is written to a new debug log file instead of appending to the existing one.
- true enables the append specification so that the debug information is appended to the contents of an existing debug log file.
After you install mapping components on UNIX platforms, set the appropriate shared object path environment variable to access the shared libraries. This procedure varies slightly depending on the platform being used.
For example, to set this variable for an IBM AIX platform, enter:
LIBPATH=$LIBPATH:install_dir/libs
export LIBPATH
NOTE: Because the AIX platform caches shared libraries, if you update a shared library on the disk, you will not be able to see the update. Use the slibclean command as the root user to remove the old shared library from system memory.
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:install_dir/libs
export LD_LIBRARY_PATH
NOTE: In the examples, install_dir/libs is the directory where the shared libraries are located.
=====================================================================
ITX REST API
The ITX REST API is a .war file that you can deploy in any web server that supports the Servlet 3.0 specification, such as Apache Tomcat. These instructions describe how to deploy to Tomcat, but the instructions can be adjusted for other web servers.
These instructions also describe how to create and run a Docker image that contains the ITX REST API.
See the ITX Programming Interface documentation in the online documentation and the tutorial installed in data_dir\examples\restapi for details about using the ITX Runtime REST API.
Installing the ITX REST API in a web server
Prerequisites:- A web server that supports Servlet 3.0 containers, such as Tomcat, Glassfish, or Jett.
The config.yaml configuration file is installed in the ITX installation directory (install_dir) on non-Windows platforms and ITX data directory (data_dir) on Windows platforms. Comments in the file explain each property.
At a minimum, set the following properties in the config.yamlfile. The directories you specify in the configuration file must be existing directories:
- map.dirs – one or more directories that contain the compiled map files.
- catalog.dir – the directory where the map catalog file is to be created.
- work.dir – the directory for temporary files used during map execution.
- redis.host – the host (and port) of the Redis server. By default, this is set to localhost.
- exec.log.dir – the directory where map execution logs are written.
If the authentication.enabled is set to true, the REST API calls will be authenticated using the specified authentication.server. Default is false. To enable the REST API authentication, specify authentication.enabled to true.
where, <ipaddress> is the IP address of the authentication server installation (or its host name).
<port> is the port on which the authentication server listens for requests (typically the port number is 8443).
To enable the ITX Runtime REST API authentication, modify the authentication.enabled and authentication.server settings:
- Set the authentication.enabled to true to enable the authentication.
- Enter the correct IP port of the ITX server installation. For example, https://<ITX server IP>:8443.
NOTE: Make sure that TCP address <ITX server IP>:8443 is not blocked by the firewall or it is visible within the ITX REST container, if container installation is done. - Install the Runtime REST API, docker or tomcat install.
- Use the new Authentication option. For example, the ITX-REST runtime session API to create token.
- Use the token or basic authentication to invoke other ITX REST calls to browse and access the ITX Runtime REST API.
- Open the SWAGGER URLs in the browser:
https://<ITX Runtime REST API IP>:<ITX Runtime REST API PORT>/tx-rest/api-docs?url=/tx-rest/openapi.json
https://<ITX Runtime REST API IP>:<ITX Runtime REST API PORT>/tx-rest/api-docs?url=/v2/docs
where the ITX Runtime REST API IP is the HOST IP of the machine where REST API is installed. The ITX Runtime REST API PORT is the API port, for example localhost:9443
NOTE: The ITX Runtime REST API Authentication can be used only in combination with HTTPS scheme.
Follow the steps described in Validating deployment to test that the server is running.
- Use the change directory command, cd, to go from the root, to restapi/tomcat.
- Run:
./dtxtomcat.sh
This returns a list of command line arguments. - Run:
./dtxtomcat.sh list
This shows you what is stopped and what is running. - Run:
./dtxtomcat.sh install
This installs the Apache Tomcat server and starts the tx-rest. - Run:
./dtxtomcat.sh list
This will show that Apache Tomcat server and tx-rest are started.
The tx-rest.war file implements the REST API for Transformation Extender. It's installed in the $DTX_HOME_DIR/restapi directory. Deploy the .war file like any other web application. In the case of Tomcat, copy the .war file to the Tomcat webapps folder, either manually or through the Tomcat web console, for example:
http://<ITX Runtime REST API server>:8080/manager/html/list
The console of the web server displays whether the application started correctly. If the application did not start correctly, search the web server's log file for errors related to the tx-rest application.
Validating deployment
After you deploy the tx-rest application, by default, it runs with a context root of tx-rest.
In a browser specify: http://<ITX Runtime REST API server>:8080/tx-rest/. If the tx-rest application is running correctly, it reports version and status information:
"version": "11.0.1.0",
"status": "OK",
"name": "ITX Runtime REST API",
"up_time": "0 days, 0 hours, 2 minutes, 19 seconds",
"date":"20240726",
"revision": "50"
}
Swagger documentation
To view the Swagger documentation for the ITX REST APIs, enter the following URL in a browser:
http://<ITX Runtime REST API server>:8080/tx-rest/api-docs?url=/tx-rest/openapi.json
You can invoke the APIs directly from the Swagger interface by clicking Try it out under each API definition.
Running in a Docker container
Use these instructions to run the Transformation Extender REST API in a Docker container. These instructions apply only to the Linux platform.
To build the Docker image:
- Install ITX Runtime and Monitoring.
- Enter:
cd /opt/ibm/wsdtx/restapi/docker - Run build_image.sh to build the Docker image. If you want to customize the content of the Docker image (such as by adding components), edit the Dockerfile.
- To confirm that the image is in the Docker repository, run docker images and look for the tx-rest image.
- Create a directory on the host to hold the map files, the catalog, and the map execution log.
- To run the Docker images:
- In the following command, replace mydir with the path of the directory you created in step 5.
docker create --name tx-rest -it -d -p 8080:8080 -v mydir:/data tx-rest
If you want to invoke the API on a different port, change the -p command. For example, to use port 4444, change the command to -p 4444:8080. - docker start tx-rest
- In the following command, replace mydir with the path of the directory you created in step 5.
- Follow the steps described in Validating deployment to test that the server is running.
Using the Resource Registry feature with maps called by ITX REST API
These instructions can be used to enable Resource Registry features working in ITX maps that are called by the ITX REST API, which runs under Apache Tomcat, or on the Linux platform.
- Set the parameter resource.registry.configuration.file in the config.yaml file to point to a valid (available) .MRC file on the file system.
For example:
#The resource registry configuration file. File which can be used to define generic alias,
# can be created anywhere.
resource.registry.configuration.file=/opt/ibm/wsdtx/tx-rest/tx-rest-resource-registry.mrc - Re-start the Tomcat server.
=====================================================================
ADAPTER-SPECIFIC INSTALLATION AND CONFIGURATION
=====================================================================
Apache Kafka adapter
Aspera adapter
CICS adapter
Connect: Direct adapter
DB2 adapter
Java-based adapters
JNDI adapter
MIME adapter
ODBC adapter
OpenPGP adapter
Oracle and Oracle AQ adapters
SNMP adapter
Sybase adapter
The Aspera adapter is supported only on the Linux on Intel® platform.
Use this procedure to install the required CICS server-side components on a z/OS system.
The CICS adapter requires the cicssrvr.loadlib file that is shipped with Transformation Extender and is located in the installation directory. The cicssrvr.loadlib file includes server-side components required to use the CICS adapter to connect to CICS.
To install the cicssrvr.loadlib file:
- Transfer the cicssrvr.loadlib file in binary mode from the installation directory on your computer to a z/OS data set with 80-byte fixed-length records (RECFM=FB, LRECL=80,system-determined blksize). This means no ASCII-to-EBCDIC translation and no elimination of carriage-return or line-feed characters.
- After you have installed the file on z/OS, issue the TSO RECEIVE command to create a load library from it. At the READY prompt, type the following:
receive inda(‘my.upload’)
The following messages are displayed:
INMR901I Dataset MY.UPLOAD from USER on NODENAME
INMR906A Enter restore parameters or 'DELETE' or 'END' + - Type the name of the load library to be created as follows:
da('my.loadlib')
Messages are displayed, indicating that the load library is being created. - Define the programs to the CICS region that will be running the CICS adapter server-side components.
The programs can be defined to CICS by adding the following statements to the CICS CSD definitions. To update the CSD, use either the DFHCSDUP CICS batch utility program or use the CEDA transaction and use the following statements as an example:
DEFINE PROGRAM(DTXC3270)
GROUP(DTXCICS)
DESCRIPTION(3270 BRIDGE EXIT)
LANGUAGE(LE)
DATA(ANY)
DEFINE PROGRAM(DTXCDRIV)
GROUP(DTXCICS)
DESCRIPTION(ADAPTER DRIVER)
LANGUAGE(LE)
DATA(ANY) - Add the cicssrvr load library to the DFHRPL concatenation for the CICS region that will be running the CICS adapter server-side components.
Important: Transformation Extender Connect:Direct adapter is thread unsafe on UNIX® platforms
The Command Server runtime environment ensures threadsafe processing when using the Connect:Direct adapter. To ensure threadsafe processing when using the Connect:Direct adapter in other Transformation Extender runtime environments on UNIX platforms, follow these design guidelines for your solution implementation:
- In a Launcher runtime environment, run only one map that uses the Connect:Direct adapter, and set the Max Concurrent Map Instances setting to 1. You still can deploy multiple Launcher processes to achieve parallel execution.
- In an Integration Server runtime environment, run only one map that uses the Connect:Direct adapter, and disable concurrent instances. You still can deploy multiple IBM App Connect Enterprise execution groups to achieve parallel execution.
- When using Transformation Extender APIs, run only one map that uses the Connect:Direct adapter, and run only one map instance at a time from the same process.
For the DB2 adapter to connect with a DB2 database from a Linux, UNIX, or Microsoft Windows system, install an IBM Data Server Client Package. An IBM Data Server Client Package is available for you to download from the internet for free. Select an IBM Data Server Client Package that includes the CLI driver, which the DB2 adapter uses to connect to a DB2 database. When configuring a database connection for a z/OS or IBM i operating system, you also need a DB2 Connect license. For further information about choosing, installing, and configuring an IBM Data Server Client Package, see the IBM DB2 Database for Linux, UNIX, and Windows knowledge center.
Specify the DB2 adapter from either the map command line, for example,
-DBTYPE DB2
, or from the Database Interface Designer, for example, in the "Adapter Type" field of the "Database Definition" window.For more details about using the DB2 adapter, see the related topics in the online documentation.
To configure the Java-based adapters, modify the CLASSPATH environment variable, either directly or by adding the JAR file entries to the /runtime/External Jar Files: key of the config.yaml file. Alternatively, you can add directories that contain JAR files to the /runtime/External Jar Directories: key of the config.yaml file.
The /runtime/External Jar Files and /runtime/External Jar Files keys are valid only when the adapter is invoked by the Command Server, Launcher, or a non-Java-based API.
For example, edit config.yaml like this to add c:\mypath\myjar.jar to the class path
External Jar Files:
jar1: c:\mypath\myjar.jar
NOTE: 1 represents the next available number when there are multiple JAR entries or JAR directories. Environment variables cannot be used in these entries.
External Jar Files:
jar1: c:\J2EE\lib\j2ee.jar
jar2: c:\J2EE\lib\j2ee.jar
To specify directories that contain the JAR files:
runtime:
External Jar Directories:
Dir1: c:\J2EE\lib
Dir2: c:\mypath
- Set environmental variable J2EE_HOME to point to the installed directory.
- Update the CLASSPATH environment variable as described below.
Platform CLASSPATH Environment Variable Windows %J2EE_HOME%\lib\j2ee.jar Linux $J2EE_HOME/lib/j2ee.jar
The following indicates the supported JNDI drivers for use with the JNDI adapter:
- COS Naming service provider, 1.2.1 release
- DNS Service Provider, 1.2 release
- File system service provider, 1.2 release
- LDAP service provider, 1.2.4 release
- RMI registry service provider, 1.2.1 release
The MIME adapter requires J2EE and "javax.mail" classes. After installing the appropriate Java Platform, Enterprise Edition installation, modify the CLASSPATH to include the J2EE and “javax.mail” class modules. IBM Sterling Transformation Extender ships jakarta.mail jar file under extjar folder by default that can be used for MIME adapter purposes.
For details about using the ODBC adapter, see the online documentation.
Follow these steps to install and configure the ODBC adapter on Windows systems:
- Install the latest ODBC Driver for your specific database.
- Go to Administrative Tools and select: ODBC Data Sources (64-bit)
- Select: Start > Settings > Control Panel > System and Security> Administrative Tools > Data Sources (ODBC)
- Select the System DSN tab and click Add.
- In the Create New Data Source window, select the ODBC driver and click Finish.
- Install the ODBC driver for your specific database.
- Edit the $DTX_HOME_DIR/unixODBC/etc/odbc.ini file with the following contents. As an example, for MS SQL Server, use your libmsodbcsql version and location on the "Driver=" entry.
NOTE: The odbc.ini file is an example. Refer to your ODBC driver vendor for parameter details.
NOTE: The name that you assign to the data source name is what you will use for the ODBC Adapter -SOURCE command.
[<data source name>]
Driver=<full path to driver library>
Description=<Optional>
Trace=NO
Server=<ipaddress, or hostname>
Port=<port number>
Database=<database name> - Edit the $DTX_HOME_DIR/unixODBC/etc/odbcinst.ini file with the following contents:
[<data source name>]
Driver=<full path to driver library>
Description=<Optional>
UsageCount=1
NOTE: In product versions later than 9.0.0.x, the following lines in the $DTX_HOME_DIR/unixODBC folder are part of the setup script, and do not need to be manually added:
export LD_LIBRARY_PATH=$DTX_HOME_DIR/unixODBC/linux/lib:$LD_LIBRARY_PATH
export ODBCINI=$DTX_HOME_DIR/unixODBC/etc/odbc.ini
export ODBCSYSINI=$DTX_HOME_DIR/unixODBC/etc - Run the . ./setup script from the root installation location.
- Run the following command to test the connection:
isql -v <data source name> <userid> <password>
IBM Sterling Transformation Extender ODBC connection with Design Server, see the technote IBM Sterling Transformation Extender ODBC connection with design Server for more details.
In V10.0.0 and later, the OpenPGP adapter is installed as part of the base product.
Downloading the GnuPG libraries for the OpenPGP Adapter
This release of the OpenPGP adapter supports GnuPG V1.4.2 and later for Windows and UNIX® operating systems.
The OpenPGP Adapter uses the Gnu Privacy Guard (GnuPG) third-party product to perform the functionality required by the adapter. To use the OpenPGP Adapter, you must first download and install the GNU PG libraries from the GNU website.
- For Windows operating systems, the binary images for the GnuPG product are available for download.
- For UNIX operating systems, you must download and recompile the GnuPG source to generate the binary images.
Configuring the gpg.exe file location in the Windows registry
The OpenPGP Adapter requires the following change to the registry for it to determine the location of the GnuPG (gpg.exe) executable file.
To specify the location of the GnuPG gpg.exe file in the registry:
- Click Start > Run and enter regedit to launch the Registry Editor.
- Navigate to the HKEY_LOCAL_MACHINE\SOFTWARE\GNU\GNUPG key.
- Right click on the GNUPG key, select New > String Value from the menu, and name the string value
gpgProgram
. - Double-click
gpgProgram
to assign a value to it. - In the Value field, enter the full path to the GnuPG gpg.exe file. For example:
C:\IBM\GNU\GnuPG\gpg.exe
- Click OK.
- Select File > Exit to exit the Registry Editor.
The Transformation Extender OpenPGP Adapter requires the GPG_PATH environment variable to be set to the directory of the GnuPG gpg executable file. Use either of the following methods to set the GPG_PATH environment variable:
- Add the setting of this variable to the user login profile, so that it is always set.
- Add it to the bottom of the setup script that contains all of the environment variables needed by Transformation Extender.
export GPG_PATH=/usr/local/bin
See the Transformation Extender system requirements for the supported database versions.
Support for Oracle databases does not include support for the Oracle Exadata platform.
The SNMP adapter is automatically included with all base editions of Transformation Extender. The SNMP Agent is an optionally installed component of Transformation Extender Runtime and Monitoring.
To use the SNMP adapter or the SNMP Agent, you must install the Java™ Dynamic Management Kit (JDMK) runtime module available from the OpenDMK project.
With the Sybase adapter, you can connect to the Sybase Adaptive Server Enterprise (ASE) and Sybase IQ databases. See the Transformation Extender system requirements for the supported database versions. See the Sybase adapter documentation for the list of supported data types.
- Maps with cards that utilize IBM MQ or Database (Legacy) connection types do not run successfully in web UI. Such maps can be designed in the web UI but then need to be deployed to a runtime server and executed there.
- When running maps or flows that utilize one or more of Apache Kafka, Apache HDFS, JDBC, Amazon S3, Amazon SQS, Amazon SNS, Apache Active MQ, SFTP, REST, Salesforce, OData and Azure SQL connection types, the DTXHOME or DTX_HOME_DIR environment variable need to be set to point to the product install home directory. If the environment variable is not set, the “Adapter not found” message is reported when running the map. This requirement applies to all platforms on which the map command Server and flow command server are supported.
When the log file name is not specified for Apache Kafka, Apache HDFS, JDBC, Amazon S3, Amazon SQS, Amazon SNS and Apache Active MQ adapters, the log file with the default name is not created when it should. The workaround is to always specify the file name.
UPGRADE AND MIGRATION
=====================================================================
With the introduction of configuration variables, the same behavior existed – if no resource registry variables and no configuration variables, %myfile% remains in the resolved string.
However, with the introduction of flow variables being used also as resource registry variables. If no resource registry variables and no configuration variables exist, it has a third path to check, and there will be system flow variables, so now, if user is not using resource registry or configuration variables, C:\temp\%myfile%.txt will be resolved to C:\temp\.txt. This is now the behavior, even outside of running flows.
Support for 64-bit platforms only
This version of Transformation Extender supports 64-bit platforms only, Connect:Direct integration is not supported on the Windows platform.
Changes to anyType XML schema fields prevent older maps from compiling
A fix to the native schema type tree to properly process anyType XML schema fields changed the format of the type tree. Because anyType fields include anyAttribute, additional levels are added to the native schema type tree to handle any attributes that might occur in the data. As a result, maps older than V9.0.0.2 do not compile because the path to these elements changed.
To eliminate the need for remapping, set the new ITX_NS_NOANYTYPE environment variable to TRUE. When enabled, ITX_NS_NOANYTYPE forces the Transformation Extender native schema type tree generator to create the type tree identical to the one before the anyAttribute fix was added.
Previously date fields were text type fields. Now they are date type fields. This may cause map compiler issues with 10.1.0 and higher version maps.
JSON schema output now has formatting tab characters. Previously there were no tab characters in the output.
JSON native schema Restart and package processing
JSON native schema Restart:
JSON schema fields with "_V" following the name and fields starting with "oneOf", "allOf" and "anyOf" are virtual fields. Virtual JSON fields do not appear in the data and have no syntax. Syntax is controlled by real fields above these virtual fields.
Real fields are fields that appear in the JSON data. It is impossible to restart to a data location that does not appear in the data. Selecting a virtual field for restart may fail. Use a real field either above or below the virtual fields for restart.
JSON native schema package:
JSON schema fields with "_V" following the name and fields starting with "oneOf", "allOf" and "anyOf" are virtual fields. Virtual JSON fields do not appear in the data and have no syntax. Syntax is controlled by real fields above these virtual fields.
Real fields are fields that appear in the JSON data. Using a virtual field in a package command will give incomplete syntax. Use a real field either above or below the virtual fields for complete syntax.
Running Transformation Extender with locally vs globally installed GSKit
IBM Sterling Transformation Extender installs a local version of IBM Global Security Kit (GSKit) in the install_dir/GSKit directory. Local GSKit installation enables Transformation Extender to automatically run its installed version of GSKit without additional software installation or environment configuration.
IBM products that Transformation Extender integrates with might use:
- A local version of GSKit that is installed by that product
- A global version of GSKit that is installed by the GSKit installation program.
- When globally installed, the security modules of GSKit are available on a system-wide basis.
If the Design Studio or utilities do not start correctly, check the PATH environment for GSKit, and put the ITX version of GSKit in front:
For example: PATH=C:\Program Files\IBM\TransformationExtender_11.0.1\GSKit\lib64;%PATH%
64-bit support for EXIT structure of C API
Customers who use the C Exit must rebuild their EXIT library for V9.0.0 or higher.
Change to resolution of relative paths for some interfaces that use files as arguments
In earlier releases, Transformation Extender changed from the directory of the currently running process to the map directory before it ran a map.
For example, before running the /home/abc_acct/8413/maps/myoracle.mmc map, Transformation Extender changed from the directory of the currently running process to the /home/abc_acct/8413/maps directory. If the myoracle.mmc map used a relative path to specify files, the path resolves relative to the map directory. In this example, Transformation Extender creates an adapter trace file called m4oracle.mtr in the /home/abc_acct/8413/maps directory if the trace file was defined with any of the following relative paths:
../../8413/maps/m4oracle.mtr
./m4oracle.mtr
m4oracle.mtr
IBM Sterling Transformation Extender V9.0.0 or higher does not change to the map directory before it runs a map. V9.0.0 or higher resolves relative paths by appending the relative path to the directory of the currently running process. The following interfaces are affected by this change:
- Custom functions that use files as arguments
- Adapter trace files in Transformation Extender Runtime and Monitoring integrations
- API implementations that open files after calling a map
xmllib->XSLTEX( "ipo.in.xml", "ipo.xsl", "transform.log")
- The first two arguments can be data or a file.
- The third argument is always a file.
- The first argument can be be data or a file.
- The fourth argument is always a file.
- The first argument can be data or a file.
- The second argument is always a file (optionally prefixed by default name space).
- The third argument is always a file.
On UNIX systems:
export DTX_CHDIR=TRUE
On Windows systems:
set DTX_CHDIR=TRUE
For best results, use an absolute path for adapter trace files. You can use the GETDIRECTORY function to dynamically build an absolute path.
Native XML schemas with prologs must use XSD as the type of the main input card
When a native XML schema has a prolog, the Type setting of the main input card must be XSD (the root of the XML document). A parser error results when the XML schema has a prolog and the Type setting specifies a sub-element of the root.
As a general practice, use XSD as the Type setting in the main input card of all native XML schemas. The XSD setting parses correctly regardless of whether the schema includes a prolog.
For all Xerces type trees, use Doc XSD as the Type setting of the main input card, regardless of whether the XML document has a prolog. Parsing errors can result if the XML document includes a prolog and you specify a sub-element of Doc XSD as the Type setting of the main input card.
Recompile existing V8.4.1.1 maps that use the Standards Processing Engine adapter
A map that uses the Standards Processing Engine (SPE) adapter to run adapter action commands such as ENVELOPE, DEENVELOPE, and TRANSFORM must be compiled with Transformation Extender V8.4.1.2 or later. To upgrade a map that you developed with Transformation Extender V8.4.1.1, delete the existing Response.mtx file and recompile the map using the updated Response.xsd file that is included with a later version of Transformation Extender. The schema for the SPE adapter response was updated in V8.4.1.2. A map must use the new version of the Response.xsd file to correctly process the SPE response.
Maps cannot reuse work files from earlier releases
Transformation Extender V8.4.1 and later work files are not compatible with work files from earlier releases. If a map reuses work files that were created with an earlier release, you must delete the work files and run the map to create new work files that are compatible with version 8.4.1 and later.
Custom function memory allocation on Windows systems
Transformation Extender V8.4.1 and later releases require custom functions that run on Microsoft Windows systems to use the new mpiMemMalloc and mpiMemRealloc memory management functions to allocate or reallocate the lpDataFromApp buffer.
Migrating maps, type trees, and systems
Maps, type trees, and systems from versions 5.0 and later can be used with V9.0.0 and later. You must regenerate systems. Although it is not always required for running maps from an earlier version, you should reanalyze and save the type trees, and save and recompile the maps; otherwise, the processes must convert the files each time they load the files.
- If you are migrating from V8.0 to V11.0.1.0, you must run your database triggering scripts in order to successfully run source-triggered database systems. After V11.0.1.0 is installed on the supported Oracle or SQL Server databases, no earlier release of Transformation Extender can use triggering on that database, because the client and source reference different names.
- To use the new code page functionality, you must make new selections for the Data Language and National Language type properties in your type trees.
- If you previously used a non-international version of Transformation Extender (formerly DataStage TX or Mercator), Native has been redefined to be Latin1 instead of ASCII.
- During installation, if you are prompted to register this version as the default program for opening Transformation Extender file types and you choose "Yes," all Transformation Extender files, such as *.mtt or *.mms, open with this version.
When you save a source file from an earlier version of a Transformation Extender product in the current version, the content and structure of that file is automatically converted to the format for the current version.
After conversion to the current version formats, do not open these files in earlier versions of a Transformation Extender product component. After conversion, the format of the source has changed and there are added features that are not supported in the earlier versions.
- *.mtt files are converted in memory when the file is opened. The backup *.omt file is created when the file is saved.
- *.mms files do not need to be converted for the current version.
- A map created in an earlier version opens in the current version.
- *.msl files do not need to be regenerated. They are converted dynamically.
- *.mmc files do not need to be recompiled.
- *.msd files still work the same way, creating an *.osd when the file is opened.
- *.mdq files open in the current version.
- Analyze each type tree file for logic and structure and then save it in the current version of the Type Designer.
- Regenerate type trees for queries, tables, and stored procedures.
- For maps that will be executed using a current version of the Map Command Server or Launcher, build all maps using the equivalent (current) version of the Map Designer.
- Build and generate the Launcher system (.msl) file or the command file for all systems defined in the current version of the Integration Flow Designer.
- If you have designed maps that could produce 0 bytes of data to an adapter (this is especially critical for R/3 adapters), you must change the OnSuccess setting to CreateOnContent or use the -XO adapter option.
- When you open a map that references a custom adapter, or an adapter that is no longer supported in this version of the product, the Source or Target in the Edit Card window is blank. The map builds successfully but, returns a "Source not available" or "Target not available" message when it executes. The solution is to select an adapter from the list in the Edit Card window.
Install latest Microsoft SQL Server drivers to support SSL 1.2
https://www.microsoft.com/en-us/download/details.aspx?id=56730
Microsoft Technical Note document is at the following location:
Performance of maps
If you are migrating from an earlier version, you should be aware of the relative performance of running maps in this version.
Using ini2yaml migration utility
ini2yaml migration utility is recommended to be used only when large set of dtx.ini files from earlier version must be migrated to config.yaml files. Manually migrate the configuration where possible for smaller set of files to limit unexpected issues with the migration utility.
The following issues must be worked around when using default config.yaml file with the ini2yaml migration utility:
By default, config.yaml is installed as read-only file on Windows platform under C:\ProgramData\IBM\TransformationExtender_11.0.1\config folder. Set write permissions to the default config.yaml file before using the ini2yaml utility.
Set masterKeyFile key value under server category to empty by removing config/configvar.mkf value before running the ini2yaml utility on Linux platform. Missing the default configvar.mkf file in the installation folder results in an error.
NEW AND CHANGED BEHAVIOR
=====================================================================
For an overview of new features in this release, see the What's New information in the online documentation.
The structure of native JSON type trees has been changed. The encoding item of native JSON type trees has been removed. A new Data Language card property was created as a replacement for the encoding item for output cards which use native JSON.
Type trees and maps which use the encoding item remain valid. A newly imported or customized native JSON type tree will not have the encoding item. Conversion of a rule on the encoding item to a selection of the Data Language card property is necessary when a map with an output card which uses native JSON has a rule on the encoding item which becomes invalid. For example, if the JSON document which defines the type tree for an output card is reimported, then the encoding item will be absent in the type tree. A rule on the encoding item then becomes an unresolved rule.
In some cases, automatic conversion is performed for a rule on the encoding item of a native JSON output card. When automatic conversion cannot be performed, manual removal of the rule on the encoding item should be performed. A suitable value should then be chosen for the Data Language card property of the output card. When manual removal is required, map compilation will not succeed until the invalid rule is deleted.
Design Studio does not support Navigator view in this product release as the underlying Eclipse 4.31 platform has removed support for Navigator view. Users can use Project Explorer view that closely matches with Navigator view.
Design Studio does not support the short-cut keys, Ctrl + C and Ctrl + V, in the Map’s input and output card views of a map. User can choose Copy and Paste context-menu options to copy and paste the type names from the input and output card views.
The active theme of the Design Studio depends on the Operating System. The user interface by default may be dark based on the operating system. The Dark theme can be changed to Light by updating the preferences of the Design Studio. Navigate to Preferences > General > Appearance and enable theming by selecting Enable Theming option if not already and select Light from Theme selection choices list.
Transformation Extender Design Server
Removed functions, components, and platforms
The following functions, components, and platforms are removed in this release:
- Navigator view in Design Studio
Use Project Explorer instead.
Deprecated functions, components, and platforms
The following functions, components, and platforms are deprecated in this release:
- tbcconv utility
- WSDL Classic Importer
- z/OS 31-bit Batch/IMS/API
- REST API Docker container files on Linux platform
Updated functions, components, and platforms
The following functions are updated in this release:
- CURRENTTIME
- CURRENTDATETIME
CURRENTTIME and CURRENTDATETIME functions use daylight saving time when it is in effect and the system is configured to use it.
Configuring SSL certificates for the IBM Sterling Transformation Extender Runtime REST API/Design Server
After installing IBM Sterling Transformation Extender, setup the custom SSL certificates for the Runtime REST API/Design Server.
Note: For the Runtime REST API/Design Server to use the certificate, ensure that /client/inbound/protocol is set to https and it is the default setting.
Create the SSL certificates or use the SSL certificates from a third-party provider (example GoDaddy Inc). PEM is the preferred format for the certificates. If the certificates are not of the PEM format, convert the certificates to PEM format.
Split the SSL certificates into three files. Each file must contain one of the following SSL certificate components:
- Private key
- Server certificate key
- Certificate authority keys
The following table lists the GoDaddy-provided certificates in their corresponding files:
File |
Description |
Private key file |
The file format is PEM and the extension of the file is KEY. The content of the file starts and ends with the following lines: … -----END PRIVATE KEY----- |
Server certificate key file |
The file format is PEM and the extension of the file is KEY. The content of the file starts and ends with the following lines: … -----END CERTIFICATE----- |
Certificate authority (CA) keys |
You need these keys to sign off the private keys and public keys. Bundle the keys into a single file or multiple files. The files are not required if the certificates are self- signed. The CA certificates start and stop with the following lines: … -----END CERTIFICATE----- |
Configuring SSL certificates for Runtime REST API/Design Server
To configure SSL certificates for IBM Sterling Transformation Extender Runtime REST API/Design Server, complete the following steps:
- Prepare the SSL certificate files.
- Within the IBM Sterling Transformation Extender client installation folder, copy the certificate files to the ssl-certificates/public - certificates folder. The relative path of the installation root folder for different platforms are as follows:
Microsoft Windows
The client installation folder is DesignServer/client.
Linux (Native)
The client installation folder is node-context/install.
Linux (Docker)
The client installation folder is within the tx-client container at /usr/src/app.
Use the docker cp command to copy files from a local folder to the Docker tx-client container.
- Setup the config.yaml for /client/inbound/ssl section to point to the certificate files copied in Step 2.
Example:
key: "ssl-certificates/private-certificates/server-key.pem"
cert: "ssl-certificates/public-certificates/server.crt"
ca: "ssl-certificates/public-certificates/gd1.crt,ssl-certificates/ public-certificates/gd2.crt,ssl-certificates/public-certificates/gd3.crt" - Restart the IBM Sterling Transformation Extender application. If your user profile has all the appropriate privileges, open a shell, and change the working directory to the installation root.
- In case of Microsoft Windows, execute the following commands:
DesignServer\stop.bat
DesignServer\start.bat - In case of Linux-based systems, execute the following commands:
./ITX stop
./ITX start
Configuring SSL certificates for the IBM Sterling Transformation Extender Apache Tomcat application server
If you implement IBM Sterling Transformation Extender on a setup containing Apache Tomcat server, the implementation works as a Tomcat application.
Apache Tomcat uses a Java keystore to store SSL certificates. To import certificates into the IBM Sterling Transformation Extender application server Java keystore, use the openssl utility. For more details related to openssl installation, see https://www.openssl.org/.
To configure SSL certificates for the IBM Sterling Transformation Extender Apache Tomcat application server, complete the following steps:
- To export the SSL certificates into pkcs12 format, run the command openssl pkcs12.
- The system prompts you to provide the password phrase (for example <my passphrase>) to protect the generated certificate file.
The -CAfile command option supplies the CA bundle.
Example: If GoDaddy provides multiple CA PEM files, bundle all CA files (concatenated as text files) into single file named cabundle.crt:
gd1.crt>>
cabundle.crt
gd2.crt>>
cabundle.crt
gd3.crt>>
cabundle.crt
openssl pkcs12 -export -in sever.crt -inkey server.key -out dtxtomcat.p12
-name dtxtomcat -CAfile cabundle.crt -caname root - Depending on the platform, access the keytool application from the provided location:
Microsoft Windows
C:\Program Files\IBM\TransformationExtender_<version>\java\bin\keytool.exe
Linux-based OS
tomcat-context/install/java/bin/keytool
To generate java keystore, run the following command:
Note: The value of <my passphrase> must match the passphrase value set for the
configuration property /tomcat/keystore/password. - For Microsoft Windows and Linux-based operating systems, copy the generated Java keystore to the following location:
install_dir/restapi/tomcat/server/dtxtomcat.keystore
where install_dir is:- For Microsoft Windows - C:\Program Files\IBM\TransformationExtender_<version>
- For Linux-based operating systems - tomcat-context/install
- In case of IBM Sterling Transformation Extender installation on Docker environment, copy the keystore file from a local folder to the tx-rest container at /usr/local/tomcat using the docker cp command. The value of <my pass phrase> must match the passphrase value in the /usr/local/tomcat/conf/server.xml file within the container.
- Restart the IBM Sterling Transformation Extender application. If your user profile has all the appropriate privileges, open a shell, and change the working directory to the installation root.
- In case of Microsoft Windows, execute the following commands:
DesignServer\stop.bat
DesignServer\start.bat - In case of Linux-based systems, execute the following commands:
./ITX stop
./ITX start
- In case of Microsoft Windows, execute the following commands:
Configuring SSL certificates for the IBM Sterling Transformation Extender Java WEB Client
This documentation explains how to configure an SSL certificate for the IBM Sterling Transformation Extender Java WEB client.
Note: Please note that if you encounter the following error, you will need to import the IBM Sterling Transformation Extender server certificate into the JRE keystore or truststore. This problem occurs when java web clients try to access web servers that have server certificates signed by unknown authority.
com.hcl.tx.server.impl.ServiceException: An
error was encountered when invoking an endpoint:
javax.net.ssl.SSLHandshakeException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.
To configure SSL certificates for the IBM Sterling Transformation Extender Java WEB client, follow these steps:
- Collect the WEB server certificate by executing the following command:
openssl s_client -connect <IBM Sterling Transformation Extender server hostname>:<PORT> - Copy the following content from the generated output after running the earlier command and save the certificate in either .cer file format:
------BEGIN CERTIFICATE------
...
------END CERTIFICATE------ - Import the certificate from the file (created in step 2) into JRE (Java Runtime Environment) keystore using the following command:
- For Windows:
sudo keytool -import -trustcacerts -keystore install_dir/java/lib/security/cacerts -storepass changeit -noprompt -alias <Alias> -file <Cert File path> - For Linux Native:
sudo keytool -import -trustcacerts -keystore install_dir/tomcat-context/install/ java/lib/security/cacerts -storepass changeit -noprompt -alias <Alias> -file <Cert File path>
- For Windows:
- Restart IBM Sterling Transformation Extender.
- In the Design Server installation folder, start the Design Server application:
./start.sh - Copy the Design Server self_ca_root.pem root certificate file to the installation folder:
docker cp tx-client:/usr/src/app/ssl-certificates/self-signed/self_ca_root.pem - Transfer the self_ca_root.pem root certificate file to the computer where the Design Server will run.
- Start the browser and import the self_ca_root.pem file into the root certificate truststore:
If you are using a Chrome browser:
a. Go to Settings > Advanced > Manage Certificates.
b. In the Trusted Root Certification Authorities tab, click Import and import the self_ca_root.pem file.
If you are using a Firefox browser:
a. Go to Options > Privacy Security > Certificates and click View Certificates.
b. In the Authorities tab, click Import and import the self_ca_root.pem file.
- Restart your browser.
=====================================================================
RESOLVED AUTHORIZED PROGRAM ANALYSIS REPORTS (APARs)
=====================================================================
For a list of APARs that are fixed in this version of the product, see the fix list.
=====================================================================
Known Issues
=====================================================================
Map Audit log generated by the runtime incorrectly places output data validation errors of an output card under input card messages section when Data Audit Settings for output card items were specified in the map. This issue is applicable only when SummaryAudit is turned ON, which generates additional validation error messages in the map audit log in this version of software. To workaround this issue, set maximumCount value to 0 in config.yaml file under validationErrors category for server section.
Design Studio may abend when SummaryAudit is turned ON to get the data validation errors logged in the map audit log randomly. This random abend may happen to any map run within the Design Studio. Command Server, Launcher, Design Server and TX API (including REST API) map executions are not affected by this issue. The workaround is to turn OFF the SummaryAudit or set maximumCount value to 0 in config.yaml file under validationErrors category for server section.
By default on Windows platform, configuration files – config.yaml, dtx_keys.sth, dtx_keys.p12 – are installed with ‘Read-only’ permissions under default data directory, C:\ProgramData\IBM\TransformationExtender_11.0.1\config folder. You may experience issues when using product tools when they are read-only. Change the permissions of the files to be writeable during runtime before using the product.
At times, Design Studio may fail to perform Undo and Redo operations in the map rule editor window. This behavior could be observed with short-cut keys, context menu and tool bar icons in the Design Studio for Undo and Redo operations.
Design Studio can be installed stand-alone or it can be installed into an existing Eclipse based application, in which Transformation Extender Development perspective is provided for designing maps and type trees. Design Studio installed in another Eclipse based application currently lacks support for COBOL Copybook Importer, PL/I Include Importer and IMS TM Resource Adapter Importer. During installation, deselect ITX Design Studio EMD Feature and ITX Design Studio GDM Feature from the list of available ITX repositories as they would fail due to missing dependencies not available outside the standalone installation environment.
=====================================================================
SOFTWARE DEVELOPMENT KIT NOTES
=====================================================================
The following Software Development Kit components are automatically included when you install the Design Studio. Use Transformation Extender Runtime and Monitoring as the runtime environment with the Software Development Kit.
IBM Sterling Transformation Extender Application Programming Interface requirements
The IBM Sterling Transformation Extender Programming Interface consists of C, C#, COM, Java, REST, Java RMI and Python APIs.
The required header files, library files for these APIs are located in the following directories:
Files | Windows Directory | UNIX Directory |
Headers | install_dir | $install_dir/src |
Library | install_dir | $install_dir/libs |
Schemas | install_dir | $install_dir/src |
JARs | install_dir\tools |
About ICU library version
This release of Transformation Extender uses International Components of Unicode (ICU) version 55.1.0. For more information about ICU, visit ICU website.
LAUNCHER NOTES
=====================================================================
These notes are for the Launcher Administration, Management Console, and Resource Registry components of the Transformation Extender Runtime and Monitoring.
Resource Registry trace file
Use the [Launcher] logging options in the data_dir\config\config.yaml configuration file to set the Resource Registry trace options. The trace file logs encrypted aliases and displays them as masked values.
To use these products in a non-Windows environments, the X Window server must be running on the local host machine or system. You must set the DISPLAY environment variable and export it.
The DISPLAY environment variable identifies the X Window server that is to display the X Window Transformation Extender GUI client. The syntax might vary depending on the shell version that you are using. To set the DISPLAY environment variable:
export DISPLAY=<display_name>:<server_display[.screen_number]>
- The DISPLAY environment variable name must be in uppercase letters.
- The display_name is the IP address or domain name of the local host machine that is to display the X Window Transformation Extender GUI client application.
- server_display is the number assigned to the X Window server that is to display on the host machine.
Because most local host machines have a maximum of one display monitor, keyboard, and mouse, in most cases, you specify the server_display as :0, and omit the screen_number .
If your system has more than one monitor (display screen) as in multi-headed systems, each monitor is identified by a unique screen number. You specify the screen_number by appending it to the end of the X server_display specification, for example, :0.1. The default screen_number is 0, which refers to the primary screen, and when it is 0, you do not need to specify it; for example, you can specify only the server_display simply as :0.
Example 1:
export DISPLAY=mycomputer.ibm.com:0
Where:
- mycomputer.ibm.com is the domain name of the local host that is to display the X Window Transformation Extender GUI client application.
- 0 is the value for the server_display that is assigned to the DISPLAY environment variable.
The host system exports the value to the X Window client so that it will display the X Window Transformation Extender GUI client application on the primary screen of the computer with the mycomputer.ibm.com domain name through the X server assigned as 0.
Example 2:
export DISPLAY=192.168.1.110:0
Where:
- 192.168.1.110 is the IP address of the local host that is to display the X Window Transformation Extender GUI client application.
- 0 is the value for the server_display that is assigned to the DISPLAY environment variable.
The host system exports the value to the X Window client so that it will display the X Window Transformation Extender GUI client application on the primary screen of the computer with the 192.168.1.110 IP address through the X server assigned as 0.
Display errors in non-Windows environments
To avoid display errors related to font.properties when starting the Launcher Administration, Management Console, or Resource Registry, ensure that the display X server has access to all fonts used in the font.properties of the Java installation.
CONTACTING CUSTOMER SUPPORT
=====================================================================
Contact Customer Support at 1-800-IBM-SERV, or go to the support portal.
=====================================================================
NOTICES AND TRADEMARKS
=====================================================================
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
US
HCL
2600 Great America Way,
Suite 401, Santa Clara CA 95054
USA
Attention: Office of the General Counsel
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
HCL
2600 Great America Way,
Suite 401, Santa Clara CA 95054
USA
Attention: Office of the General Counsel
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
IBM may use or distribute any of the information you provide in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM Director of Licensing
IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
US
HCL
2600 Great America Way,
Suite 401, Santa Clara CA 95054
USA
Attention: Office of the General Counsel
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements, or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All these names are fictitious and any similarity to actual people or business enterprises is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing, or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.
- Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
- Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
- Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
- Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.
- UNIX is a registered trademark of The Open Group in the United States and other countries.
Permissions for the use of these publications are granted subject to the following terms and conditions.
Applicability
These terms and conditions are in addition to any terms of use for the IBM website.
Personal use
You may reproduce these publications for your personal, non-commercial use provided that all proprietary notices are preserved. You may not distribute, display, or make derivative work of these publications, or any portion thereof, without the express consent of IBM.
Commercial use
You may reproduce, distribute and display these publications solely within your enterprise provided that all proprietary notices are preserved. You may not make derivative works of these publications, or reproduce, distribute, or display these publications or any portion thereof outside your enterprise, without the express consent of IBM.
Rights
Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either express or implied, to the publications or any information, data, software or other intellectual property contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use of the publications is detrimental to its interest or, as determined by IBM, the above instructions are not being properly followed.
You may not download, export or re-export this information except in full compliance with all applicable laws and regulations, including all United States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
IBM Online Privacy Statement
IBM Software products, including software as a service solutions (“Software Offerings”) may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user, or for other purposes. In many cases no personally identifiable information is collected by the Software Offerings. Some of our Software Offerings can help enable you to collect personally identifiable information. If this Software Offering uses cookies to collect personally identifiable information, specific information about this offering’s use of cookies is set forth below.
This Software Offering does not use cookies or other technologies to collect personally identifiable information.
If the configurations deployed for this Software Offering provide you as customer the ability to collect personally identifiable information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for notice and consent.
For more information about the use of various technologies, including cookies, for these purposes, see IBM’s Privacy Policy at http://www.ibm.com/privacy and IBM’s Online Privacy Statement at http://www.ibm.com/privacy/details in the section entitled “Cookies, Web Beacons and Other Technologies,” and the “IBM Software Products and Software-as-a-Service Privacy Statement” at http://www.ibm.com/software/info/product-privacy.
Was this topic helpful?
Document Information
Modified date:
26 July 2024
UID
ibm17155282