ibm-itx-rs Usage Example

Edit online

The following example demonstrates how to import the ibm-itx-rs image, how to create a running container and how to execute example map OneInOneOut.lnx. This example map takes the input string, converts it to uppercase string and returns that string.

About this task

To import the ibm-itx-rs image, create a running container and execute example system, complete the following steps:

Procedure

Start by logging into the IBM Entitled Registry (cp.icr.io) to pull the ibm-itx-rs image:
```
docker login -u <username> -p <password> cp.icr.io
```
Note: Login credentials, username and password, are provided with the entitlement of the product. Internet access to download the image from the IBM Entitled Registry is a prerequisite for saving the image in the local docker registry or to the local image server.
1. Pull the docker image by image tag or image digest from the IBM Entitled Registry:
```
docker image pull cp.icr.io/cp/ibm-itx-rs:10.1.2.1.20250328
```
```
docker image pull cp.icr.io/cp/ibm-itx-rs@sha256:c789036b8c28d5433dcbd2d68f89dc3fad26b61623348164497f79ca0456c7f4
```
  Note: Image tag and digest change when a refreshed container image is published to the IBM Entitled Registry. Replace proper image tag/digest accordingly in the commands listed in this document.
2. If you have downloaded the docker image from the IBM Entitled Registry in a docker archive, for example, ibm-itx-rs_10.1.2.1.20250328.tar.gz, load the ibm-itx-rs docker image archive to the local docker registry:
```
docker load -i ./ibm-itx-rs_10.1.2.1.20250328.tar.gz
```
3. List the images to ensure ibm-itx-rs image was imported:
```
docker images
```
  The command returns the list of images, which includes image with the name ibm-itx-rs and the tag 10.1.2.1.20250328.
Note: The 10.1.2.1.20250328 tag value is assigned to the ibm-itx-rs image. It represents the image version and you will use it later to start the container based on this image.
Create directories on the host to serve as bind mounts for the container (Docker managed volumes could be used instead of host managed directories as well). For example, as a test, to create them under /tmp on the host system:
mkdir -p /tmp/itx-rs/logs

mkdir -p /tmp/itx-rs/data/maps

mkdir -p /tmp/itx-rs/data/tmp

mkdir -p /tmp/itx-rs/data/extra

mkdir -p /tmp/itx-rs/data/mqdata
Optionally, you can also create a config directory. You can store dtx.ini and other runtime configuration files in it if you wish to modify them from the defaults used by the container. To start with the default configuration files deployed with the image, you can perform the following steps to create a temporary container and extract the config directory from it to use it as the starting point:
```
docker create --name itx-rs-tmp ibm-itx-rs:10.1.2.1.20250328
```
```
docker cp itx-rs-tmp:/opt/runtime/config /tmp/
```
```
docker rm itx-rs-tmp
```
1. You can then edit /tmp/config/dtx.ini file and customize the settings in it. Refer to the documentation included in the configuration file for details about the individual settings. No customization is necessary to complete this example.
Save the compiled map OneInOneOut.lnx to /tmp/itx-rs/data/maps directory. This map is a simple transformation map that converts the provided string to upper-case. The string is provided in a request and passed to the input card. The result is collected from the output card and returned in the response:
```
cp ./OneInOneOut.lnx /tmp/itx-rs/data/maps
```
Run the container by invoking the following command (as one line):
```
docker run --name itx-rs -it -d -p 8080:8080 -v /tmp/config:/opt/runtime/config -v /tmp/itx-rs/data:/data -v /tmp/itx-rs/logs:/logs ibm-itx-rs:10.1.2.1.20250328
```
Note: The -v /tmp/config:/opt/runtime/config argument is optional and is needed only if you customized configuration files on the host and have made changes to them that you wish to be used by the runtime in the container.

Note: The -p 8080:8080 argument is used to bind port 8080 on the local host to port 8080 in the container. This will allow you to submit REST calls via a curl command to localhost:8080, which in turn will be served by Tomcat running in the container.
1. Ensure that the itx-rs container is running:
```
docker ps
```
  The command should return a list of running containers, which should include a container with name itx-rs.

Check that the container is serving traffic by obtaining the version:

curl -X GET "http://localhost:8080/itx-rs/v1/version"

It returns a JSON document in this format:

{"version":"10.1.2.1","name":"IBM Sterling Transformation Extender Runtime Server","revision":"0","date":"20250328"}

Run the map synchronously by invoking the following command (as one line):
```
curl -X PUT -d "This is a test" "http://localhost:8080/itx-rs/v1/maps/direct/OneInOneOut?input=1&output=1"
```
It returns the value:
THIS IS A TEST

Note: The map source file OneInOneOut.mms is also provided. If you open it in Design Studio or Design Server, you will observe that it has one input card of File type, reading from file in.txt, and one output card of File type, writing to file out.txt.
Note: In the previous invocation of the map, the input and output cards were overridden to use the request and response data of the REST API call. If you create file in.txt in the same maps directory as the OneInOneOut.lnx compiled map and invoke the map without specifying the overrides, the map will run and produce out.txt file in the same maps directory, with the same text as in.txt file, except it will be changed to uppercase:
```
echo "This is a file test" > /tmp/itx-rs/data/maps/in.txt
```
```
curl -X PUT -d "" "http://localhost:8080/itx-rs/v1/maps/direct/OneInOneOut"
```
```
cat /tmp/itx-rs/data/maps/out.txt
```
It should display the value:

THIS IS A FILE TEST
Note: The locations of the files in the provided sample map are specified as relative file names only, which means that they must reside in the same directory as the compiled map. If you specify absolute locations of the files in the maps, note that those locations must be valid locations in the container file system. For example, if you specified -v /tmp/itx-rs/data:/data argument when you started the container as in this example, you can store a file somewhere under the /tmp/itx-rs/data directory, and you should refer to it in the maps as if it was under /data directory, since /tmp/itx-rs/data directory in the host file system is mapped to /data directory in the container file system.
To run the map asynchronously, the Runtime Server must run in fenced mode and be able to connect to the Redis server to get the execution status of a (long) running map, fetch the map output(s), map trace and audit. The Redis host and port number may have to be configured accordingly and specify the fenced mode when running the Runtime Server instance as following:
```
docker run --name itx-rs -it -d -p 8080:8080 -e ITX_RS_RUN_MODE=fenced -e ITX_RS_REDIS_HOST=REDIS_HOST -e ITX_RS_REDIS_PORT=REDIS_PORT -v /tmp/config:/opt/runtime/config -v /tmp/itx-rs/data:/data -v /tmp/itx-rs/logs:/logs ibm-itx-rs:10.1.2.1.20250328    
```
where, REDIS_HOST is the hostname or IP address of the Redis server, and REDIS_PORT is the listening port of the Redis server (default port is 6379 if not specified).
1. The following command returns a JSON response with a link to check the map execution status.
```
curl -X POST -d "This is a test" "http://localhost:8080/itx-rs/v1/maps/direct/OneInOneOut?input=1&output=1"
```
  A sample snippet as following:
```
{"id":"5e8fabfc-4da5-4e22-9bff-27db13827f43",
"href":"http://localhost:8080/itx-rs/v1/maps/direct/5e8fabfc-4da5-4e22-9bff-27db13827f43/status"}
```
2. A long running map execution status can then be fetched using the link provided in the JSON response.
```
curl -X GET "http://localhost:8080/itx-rs/v1/maps/direct/5e8fabfc-4da5-4e22-9bff-27db13827f43/status"
```
  The map execution status would look something like as shown below with the link(s) for map output(s).
```
{"status":0,"outputs":[{"href":"http://localhost:8080/itx-rs/v1/maps/direct/9690ed3b-0804-4bda-a076-b336bd0cc733/outputs/1","card_number":1,"mime_type":"application/octet-stream"}],"start_timestamp":"2020-12-18T02:41:50.943+0000","elapsed_time":1,"status_message":"Map completed successfully"}
```
3. To fetch the map output from the Runtime Server, the output link in the map execution status JSON response must be utilized as following:
```
curl -X GET "http://localhost:8080/itx-rs/v1/maps/direct/9690ed3b-0804-4bda-a076-b336bd0cc733/outputs/1"
```
  It should return the value:
  THIS IS A TEST
To perform cleanup, remove the image, container, and local host directories used as bind mounts, run the following commands:
```
docker stop itx-rs
```
```
docker rm itx-rs
```
```
docker rmi ibm-itx-rs:10.1.2.1.20250328
```
```
rm -rf /tmp/itx-rs
```
```
rm -rf /tmp/config
```