System z Jazz Gateway overview

With the System z® Jazz™ Gateway, you can programmatically retrieve work item numbers and status from the Rational Team Concert™ for System z repository.

The System z Jazz Gateway runs as a server daemon on z/OS®, Windows®, Linux®, and other platforms, to perform SSL authentication to a Jazz repository. It passes a work item number in a REST URI to the Jazz repository to get the work item XML, and then returns either the work item status or the complete work item XML to the client.

How the System z Jazz Gateway communicates with the Jazz repository

The System z Jazz Gateway server daemon communicates with a particular port to retrieve client requests. On z/OS, you make these requests by submitting a System z Jazz Gateway server job. You can modify your REXX™ client to specify a particular port so that the client and the System z Jazz Gateway server daemon can communicate with each other through a socket connection.

  1. To call the REXX client, use a REXX EXEC like a stand-alone EXEC or an SCLM user exit to set up required parameters like these:
    • userid
    • password
    • Jazz repository URL
    • port number
    • work item number
  2. The REXX client passes this information to the System z Jazz Gateway server daemon and waits for a response.
  3. The System z Jazz Gateway server daemon authenticates with the Jazz repository and passes the work item request through a REST URI.
  4. The Jazz Gateway server returns the work item information in XML, and the server daemon does one of the following:
    • It extracts the work item status from the XML.
    • It passes the complete XML back to the REXX client, which returns it to the calling EXEC.

Installing the Jazz Gateway

The Jazz Gateway is installed on z/OS using SMP/E as part of the Build System Toolkit for System z component. If you want to install the gateway on the supported distributed platforms, you must download the Jazz Gateway .zip file from the Rational Team Concert for System z All Downloads section on Jazz.net.

Prerequisites for installing the Jazz Gateway on UNIX and Windows
  • IBM Java software development kit (SDK) 1.5 must be installed
  • The JAVA_HOME environment variable must be set to the directory that contains the Java 1.5 SDK
  • The java.exe must be added to the PATH
For more information, see the Detailed System Requirements for the Rational Team Concert for System z 2.0 server environments.

Installing the Jazz Gateway on UNIX

Complete the following steps to install the Jazz Gateway on UNIX:
  1. Download the RTCz-JazzRestGateway-2.0.0.2.zip from the Rational Team Concert for System z All Downloads section on Jazz.net: https://jazz.net/downloads/rational-team-concert-z/releases/2.0.0.2
  2. Unzip the following .jar files to your Jazz Gateway install directory:
    • RTCz-JazzGateway-<buildID>.jar
    • log4j-1.2.12.jar
    • com.ibm.team.repository.common_1.0.1.I200909060153.jar
    • org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar
    • commons-httpclient-3.0.jar

Invoking the Jazz Gateway on UNIX using Java

Complete the following steps to invoke the Jazz Gateway on UNIX:
  1. Open a shell terminal
  2. Change to the directory where the gateway files are installed
  3. Enter the following command:
    java -cp .\RTCz-JazzGateway-<buildID>.jar;.\log4j-1.2.12.jar;
    .\com.ibm.team.repository.common_0.6.1.I200810072228.jar;.\org.eclipse.osgi_3.3.2.R33x_v20080105.jar;.\commons-httpclient-3.0.jar com.ibm.teamz.jazz.gateway.JazzGateway 6666 
    Note: For this example 6666 is the port number used by the gateway.
  4. Enter CTRL+C to stop the gateway.

Example UNIX shell script

The following example is a shell script for stopping and starting Jazz Gateway. You can customize the example according to your environment by changing the value of JAVA_HOME and GTW_DIR.
#! /bin/sh
#
# RTCzGateway-daemon:       Starts/stops the Jazz Gateway
#
#              
name="IBM Jazz Gateway"
export JAVA_HOME=<Java_sdk_directory>
export GTW_DIR=<Jazz_gateway_directory>

port=${2:-3456}
PID=GtwPid.$port
cmd="$JAVA_HOME/bin/java -classpath $GTW_DIR/RTCz-JazzGateway-I20090929-1150.jar:$GTW_DIR/log4j-1.2.12.jar:$GTW_DIR/com.ibm.team.repository.common_1.0.1.I200909060153.jar:$GTW_DIR/org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar:$GTW_DIR/commons-httpclient-3.0.jar com.ibm.teamz.jazz.gateway.JazzGateway $port"

Start() {

   if [ -f $PID ] 
   then
      echo "$name $port already started"
   else
      echo "Starting $name $port daemon... "
       $cmd >$PID.log 2>&1& 
      echo $! >$PID
   fi
}


Stop() {
   if [ -f $PID ] 
   then
           echo "Shutting down $name $port daemon: "
      kill -9 `cat $PID`
      rm $PID
   else
           echo "$name $port daemon not started "
   fi
}

Restart() {
   Stop
   Start
}

# See how we were called.
case "$1" in
  start)
   Start
   ;;
  stop)
   Stop
   ;;
  restart)
   Restart
   ;;
  *)
   echo $"Usage: $0 {start|stop|restart} <port_number>"
   exit 1
esac

exit $?
You can use this script as a system initialization script. The administration of this type of shell scripts differs for each UNIX or Linux platform on which the Jazz Gateway is supported. The following table lists the location of system initialization scripts for each system:
System Location
AIX /etc/rc.d
Red Hat /etc/rc.d/init.d
SUSE /etc/init.d
Solaris /etc/init.d

Installing the Jazz Gateway on Windows

Complete the following steps to install the Jazz Gateway on Windows:
  1. Download the RTCz-JazzRestGateway-2.0.0.2.zip from the Rational Team Concert for System z All Downloads section on Jazz.net: https://jazz.net/downloads/rational-team-concert-z/releases/2.0.0.2
  2. Unzip the following .jar files to your Jazz Gateway install directory:
    • RTCz-JazzGateway-<buildID>.jar
    • log4j-1.2.12.jar
    • com.ibm.team.repository.common_1.0.1.I200909060153.jar
    • org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar
    • commons-httpclient-3.0.jar

Invoking the Jazz Gateway on Windows using Java

Complete the following steps to invoke the Jazz Gateway on Windows:
  1. Open a command prompt window
  2. Change to the directory where the gateway files are installed
  3. Enter the following command:
    java -cp .\RTCz-JazzGateway-<buildID>.jar;.\log4j-1.2.12.jar;.\com.ibm.team.repository.common_0.6.1.I200810072228.jar;.\org.eclipse.osgi_3.3.2.R33x_v20080105.jar;.\commons-httpclient-3.0.jar com.ibm.teamz.jazz.gateway.JazzGateway 6666 
    Note: For this example 6666 is the port number used by the gateway.
You can use the command file startgw.cmd to start the gateway. Before starting the gateway, update the JAVA_HOME variable in the script.

Example for setting up a Windows service

The Jazz Gateway is a Java application; therefore, it does not include direct support for running as a Windows service. However, there are several service wrappers available. This example uses Java Service Launcher. You can modify this example for the service wrapper that you use.

Configuring the Java Service Launcher

Complete the following steps to configure the Java Service Launcher (JSL) for the Jazz Gateway:
  1. Open a command prompt and change directories to the bin directory that contains the jsl.ini file.
  2. Edit the jsl.ini file in the bin directory:
    • Define a variable in the [define] section to store the port number used by the gateway
      • PORT= gateway_port_number
    • Define a variable in the [define] section to store the path to the installation directory of the gateway
      • GTW_DIR= gateway_directory
    • Change appname, servicename, displayname, and servicedescription to names and descriptions that you choose, for example, IBM Jazz Gateway (%PORT%).
    • Set the jrepath setting to %JAVA_HOME%.
      Note: Make sure you set the jrepath in the [java] section of the .ini file, not the [service] section, which has a similar comment.
    • Set the useconsolehandler setting to true to ensure that the build engine continues to run after a logout.
    • Set the systemout setting to something like %GTW_DIR%\gtw%PORT%.out.log.
    • Set the systemerr setting to something like %GTW_DIR%\lgtw%PORT%.err.log.
    • In the [java] section, add the following parameters to pass to Java:
      • params = 4
      • param00 = -cp
      • param01 = %GTW_DIR%\RTCz-JazzGateway-I20090929-1150.jar;%GTW_DIR%\log4j-1.2.12.jar;%GTW_DIR%\com.ibm.team.repository.common_0.6.1.I200810072228.jar;%GTW_DIR%\org.eclipse.osgi_3.3.2.R33x_v20080105.jar;.\commons-httpclient-3.0.jar
      • param02 = com.ibm.teamz.jazz.gateway.JazzGateway
      • param03 = %PORT%
  3. From the command prompt, run jsl -debug to test your configuration. This will run Jazz Gateway. You should see a message similar to:
    Debugging IBM Jazz Gateway (gateway_port_number)
    Now starting JVM
    ControlHandler registered after JVM start
  4. Resolve any additional errors before continuing.
  5. Check the log file you set in systemout setting to determine whether the gateway is listening to the port number specified by the PORT variable.
  6. Enter CTRL+C to end the debug test.

Installing the Windows service and starting the Jazz Gateway

Complete the following steps to install the JSL Windows service and start the Jazz Gateway:
  1. From the command prompt, change directories to the jsl bin directory.
  2. Run jsl -install.
  3. Open the Windows services control panel (Start > Run > services.msc).
  4. Find the IBM Jazz Gateway service (or whatever you named it in the .ini file).
  5. Right-click and select Start.
  6. Request builds to ensure your build engine is successfully processing build requests.
  7. After the initial setup, the service will start automatically when the system boots, because of the the starttype=auto setting in the ini file.
Note: If you need to change the settings in the .ini file, you must first stop and uninstall the service (see instructions below). Then make your changes to the .ini file and reinstall the service.

Stopping the Jazz Gateway service

Complete the following steps to stop the Jazz Gateway service:
  1. Open the Windows services control panel (Start > Run > services.msc).
  2. Find the IBM Jazz Gateway service (or whatever you named it in the .ini file).
  3. Right-click and select Stop.

Uninstalling the Windows service

Complete the following steps to uninstall the JSL Windows service:
  1. Open the Windows services control panel (Start > Run > services.msc).
  2. Find the IBM Jazz Gateway service (or whatever you named it in the .ini file).
  3. Right-click and select Stop.
  4. From the command prompt, change directories to the jsl bin directory.
  5. Run jsl -remove.