Release Notes for IBM Sterling Transformation Extender, V10.1.1.0

NOTE: If LauncherAdmin.bin is not available at /yourdir/dockerdemo directory, create a dummy one before running the command to add the directory as following:

echo > /yourdir/dockerdemo/LauncherAdmin.bin

docker run -w /opt/ibm/wsdtx -v /yourdir/dockerdemo/LauncherAdmin.bin:/opt/ibm/wsdtx/LauncherAdmin.bin itx-launcher-1011/ubuntu:0.21 launcheradmin.sh -auto -addir /opt/ibm/wsdtx/systems

To start the launcher and block the shell: 

NOTE: Make sure LauncherAdmin.bin and dtx.ini are available in the mounted volumes /yourdir/dockerdemo and /yourdir/dockerdemo/config respectively before starting the launcher

To start the launcher and block the shell: 
 docker run -h Launcher1 --name Launcher1 -w /opt/ibm/wsdtx -v
/yourdir/dockerdemo/LauncherAdmin.bin:/opt/ibm/wsdtx/LauncherAdmin.bin -v
/yourdir/dockerdemo/config/dtx.ini:/opt/ibm/wsdtx/config/dtx.ini  -v
/yourdir/dockerdemo/systems:/opt/ibm/wsdtx/systems -v
/yourdir/dockerdemo/logs:/opt/ibm/wsdtx/logs  itx-launcher-1011/ubuntu:0.21

Install the 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:

C:\IBM\TransformationExtender_n.n.n

When you install Transformation Extender products on a Microsoft Windows operating system, do not specify C:\Program Files as your target installation location because of compatibility issues.

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.

1. Download and extract the archive (.tgz) file to a directory of your choice.
2. 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.

1. Download the IBM Sterling Transformation Extender installation package to all Windows systems where you want to install the IBM Sterling Transformation Extender.
2.  Install IBM Sterling Transformation Extender interactively and record your installation responses by running the setup executable file as follows:
   
   install_dir\txrt_10.1.1.0_build_win64.exe -r
   
   Your responses during installation are recorded in the C:\Windows\setup.iss response file.
3. Copy the setup.iss response file to the Windows system where you want to silently install IBM Sterling Transformation Extender.
4. 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_10.1.1.0_build_win64.exe -s -f1full_path\setup.iss
   
   This step replicates all your responses from the interactive installation.

1. Edit the file <MQSI_WORKPATH>/components/<NODE>/servers/<SERVER>/server.conf.yaml.  Back up the original file.
2. Find the section starting in column one titled UserDefinedPlugins:.  If this section does not exist, add it to the bottom of the file.
3. Under UserDefinedPlugins from 2), indented by two spaces, there should be a ComIbmWTXManager: entry.  If this does not exist, add it.
4. There should be an entry under ComIbmWTXManager from 3) indented by four spaces resourceConfigFile:.  If this does not exist, add it.
5. Add the path to the Transformation Extender resource configuration file as the value of resourceConfigFile.

Installing the ITX REST API in a web server

• A web server that supports Servlet 3.0 containers, such as Tomcat, Glassfish, or Jetty.

The tx-rest.properties configuration file is installed in the ITX installation directory (install_dir). Comments in the file explain each property.

At a minimum, set the following properties in the tx-rest.properties file. 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.

1. Set the authentication.enabled to true to enable the authentication.
2. 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.
3. Install the Runtime REST API, docker or tomcat install.
4. Use the new Authentication option. For example, the ITX-REST runtime session API to create token.
5. Use the token or basic authentication to invoke other ITX REST calls to browse and access the ITX Runtime REST API.
6. 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.

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

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:

{

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:

1. Install ITX Runtime and Monitoring.
2. Enter:
   cd /opt/ibm/wsdtx/restapi/docker
3. 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.
4. To confirm that the image is in the Docker repository, run docker images and look for the tx-rest image.

• 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

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

1. Set the parameter resource.registry.configuration.file in the tx-rest.properties 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
2. Re-start the Tomcat server.

=====================================================================
ADAPTER-SPECIFIC INSTALLATION AND CONFIGURATION
=====================================================================

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

1. Click Start > Run and enter regedit to launch the Registry Editor.
2. Navigate to the HKEY_LOCAL_MACHINE\SOFTWARE\GNU\GNUPG key.
3. Right click on the GNUPG key, select New > String Value from the menu, and name the string value gpgProgram.
4. Double-click gpgProgram to assign a value to it.
5. In the Value field, enter the full path to the GnuPG gpg.exe file. For example:
   C:\IBM\GNU\GnuPG\gpg.exe
6. Click OK.
7. Select File > Exit to exit the Registry Editor.

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