Installing the IWS Connector for AAI

The IWS Connector is an essential component in the communication chain between AAI and either an IWSz or IWSd workload scheduler. As an AAI administrator or jobstream administrator who is responsible for the technical integration of an IWS workload scheduler and AAI, you need to install and configure the IWS Connector as part of the overall integration process. Use the instructions and information in this topic to understand and guide you through those tasks.

This page includes the following:

What Is the IWS Connector?

The IWS Connector is a component that establishes the communication between IBM Workload schedulers, IWSz mainframe scheduler or IWSd distributed scheduler, and AAI. This standalone component is a custom web application that runs on an Apache Tomcat web server. As a standalone, it runs in its own process space, has its own installer, and writes its own log files. As a web server, it makes data available to the AAI Server via a web HTTP / HTTPS connection.

Like all connectors for AAI, the IWS Connector does the following:

  • Gets job definitions and events (executions) from the workload scheduler
  • Structures the job definition and event data into a format that can be readily absorbed into the AAI database
  • Provides the structured data to the AAI platform server for processing

The IWS Connector is part of the integration of either the mainframe IWSz or the distributed IWSd version of IWS. In the case of IWSd, the IWS Connector is the only integration component that AAI needs. It collects the data directly from the IWSd database, structures it, and then passes it on to AAI. Whereas, with IWSz the IWSz Server for AAI is required to collect the data from the IWSz mainframe and then pass it on to the IWS Connector that then structures the data before passing it on to AAI.

When Do You Need the IWS Connector?

You need to install the IWS Connector when you want to integrate either IWSz or IWSd workload scheduler with AAI. It is the essential component that has direct communication with the AAI Server to provide execution events and job definitions and receive requests for object definitions from AAI.

Considerations for the IWS Connector Installation

Platform options

Just like the AAI server, you can install the IWS Connector on either a Windows or Linux operating system.

Where to install the IWS Connector

For production environments, you should always install and run the IWS Connector on a separate physical server than the server where you have the AAI platform server installed. In the case of an IWSd installation, you can install the IWS Connector on the same physical server.

For low-activity environments with small data transactions, such as a test environment, however, you can install and run the IWS Connector on the same physical server as the AAI platform server.

Multi-instance considerations

One instance of the IWS Connector can support multiple IWSz and/or IWSd workload schedulers that you want to integrate with AAI.

 

Prerequisites for the IWS Connector Installation

Before you can install the IWS Connector, you must have the following ready on the physical server on which you will install the IWS Connector:

  • A Java Development Kit (JDK) installed. (Having only a Java Runtime Environment (JRE) is not sufficient.)
  • The following environment variables defined:  
    • JAVA_HOME: The location of the JDK
    • CATALINA_HOME: The location of the Tomcat installation

For IWSd integrations, before you begin the installation of the IWS Connector, the IWSd workload scheduler that you are connecting to must already be installed and functioning.

Important security recommendation

We strongly recommend that you secure the connection between the IWS Connector and the AAI server with a TLS protocol to protect the IWS data while in transit to AAI. To do this, use the standard procedure described on the tomcat.apache.org and follow the recommendations, which include the following:

  • Create your own keystore
  • Import the certificates and certificate authority (CA) certificates onto the AAI server to avoid extra tasks when you upgrade Java.

For more information, see Configuring the Connectors for TLS Authentication.

Downloading the Product or Solution

Make sure you have downloaded the relevant product bundle or solution. For more information on how to download the relevant component(s), see Downloads.

Continue with the installation steps for your operating system:

Installing the IWS Connector on a Windows Server

After you have taken account of the considerations and provided the prerequisites described previously, use the following steps to install the IWS Connector on a Windows server:

  1. Download the IWS Connector package as described previously in Installing the IWS Connector for AAI.
  2. In the IWS Connector installation folder, go to the \bin folder and run the IWS-Connector-Install-Service.bat file. This does the following:
    • Creates two executable files in the base installation folder called IWS-Connector.exe (which starts the IWS Connector) and IWS-Connectorw.exe (which set the Java options of the Windows Service for the IWS Connector).
    • Installs the IWS Connector as a Windows Service
      Note:

      By default, the Windows service is defined to have an “Automatic” start up. However, initially you must start it manually. This gives you the chance you to modify some configurations before starting the service.

  3. Change the default settings of the Windows Service to increase the memory pool values for the log files and to reduce the pause time between checks for job definition updates.

    1. In the base installation folder, double click the IWS-Connectorw.exe file to open its Properties dialog.
    2. Change the Initial memory pool value to at least 1024 MB
    3. Change the Maximum memory pool value to at least 2048 MB.
    4. Reduce the pause value to five minutes. To do this, in the Java Options panel, insert the following on a new line: 

      -DeventHoldTime=300

    5. Click OK.

  4. Strongly recommended optional step: Secure the connection to the Tomcat server with TLS/SSL using standard procedures as described on the Tomcat website as well as other internet security websites.

  5. If needed, change the port number for incoming execution data to the IWS Apache Tomcat installation.

    By default the Apache Tomcat uses Port 8080 for incoming connections. If you have another Apache Tomcat installation on the same server that already uses Port 8080, change the Apache Tomcat port for the IWS Connector to avoid a clash.

    To do this, open the \conf\server.xml file and change the following statements to apply the new port number and protocol value:

    <!-- A "Connector" represents an endpoint by which requests are received
     and responses are returned. Documentation at:
     Java HTTP Connector: /docs/config/http.html
     Java AJP  Connector: /docs/config/ajp.html
     APR (HTTP/AJP) Connector: /docs/apr.html
     Define a non-SSL/TLS HTTP/1.1 Connector on port 8080
-->
<Connector port="8080" protocol="HTTP/1.1" 
	connection Timeout="20000"
	redirectPort="8443" />
<!-- A "Connector" using the shared thread pool-->
<!--
<Connector executor="tomcatThreadPool" 
	port="8080" protocol="HTTP/1.1" 
	connection Timeout="20000"
	redirectPort="8443" />
  6. Start the IWS Connector Service.

    Open the Windows Services app, then locate and start the IWS Connector Service. Because the Service start-up option is set to “Automatic,” the IWS Connector Service will start automatically after any future restarts of the server.

    Note:

    You can also use the Windows Services tool to stop the IWS Connector Service when required.

The installation is complete. Continue with Next Steps after Installation.

Installing the IWS Connector on a Linux Server

After you have taken account of the considerations and provided the prerequisites described previously, use the following steps to install the IWS Connector on a Linux server:

  1. Download the IWS Connector package as described in Installing the IWS Connector for AAI.

  2. Create a setenv.sh file in the /bin sub-directory of your Tomcat instance.

    You need this file to define overrides of default values for the IWS Connector process on your server.

  3. In the sentenv.sh file, add the following statements to override the default values to values that better support the data management for the integration:

    To increase the Initial and Maximum Heap Memory sizes for the log files, add:

    export CATALINA_OPTS="-Xms4096m –Xmx8192m“

    To decrease the time between checking for job definition updates add:

    JAVA_OPTS="$JAVA_OPTS -DeventHoldTime=300“

  4. Strongly recommended optional step: Secure the connection to the Tomcat server with TLS/SSL using standard procedures as described on the Tomcat website as well as other internet security websites.

  5. If needed, change the port number for incoming execution data to the IWS Apache Tomcat installation.

    By default the Apache Tomcat uses Port 8080 for incoming connections. If you have another Apache Tomcat installation on the same server that already uses Port 8080, change the Apache Tomcat port for the IWS Connector to avoid a clash.

    To do this, open the \conf\server.xml file and change the following statements to apply the new port number and protocol value: 

    <!-- A "Connector" represents an endpoint by which requests are received
     and responses are returned. Documentation at:
     Java HTTP Connector: /docs/config/http.html
     Java AJP  Connector: /docs/config/ajp.html
     APR (HTTP/AJP) Connector: /docs/apr.html
     Define a non-SSL/TLS HTTP/1.1 Connector on port 8080
-->
<Connector port="8080" protocol="HTTP/1.1" 
	connection Timeout="20000"
	redirectPort="8443" />
<!-- A "Connector" using the shared thread pool-->
<!--
<Connector executor="tomcatThreadPool" 
	port="8080" protocol="HTTP/1.1" 
	connection Timeout="20000"
	redirectPort="8443" />

  6. Start the Apache Tomcat web server process that runs the IWS Connector. To do this, run the bin\startup.sh file.

    Note:

    To stop the Apache Tomcat web server process runs the IWS Connector, execute the bin\shutdown.sh file.

  7. Verify that the service is running correctly with the modified configurations. Do this with the following command:

    ps -ef | grep tomcat

The installation is complete. Continue with Next Steps after Installation.

Next Steps after Installation

After you install the IWS Connector, you are ready to define schedulers in AAI to complete the connection and start to receive IWS data in AAI, define jobstreams, and monitor their executions.

Next Steps for IWSd

After installing the IWS Connector for an IWSd workload scheduler, is the only integration component that you need. Therefore, after installing the connector, you can continue with defining an IWSd scheduler in AAI. For information, see Configuring IWS Schedulers (Thick Client).

Next Steps for IWSz

When integrating an IWSz workload scheduler, installing the IWS Connector is the last task outside of AAI. For more information, see AAI - IWSz Integration Using the IWSz Server for AAI, Therefore, after installing the connector, you can continue with defining IWSz schedulers for each instance of the IWSz Server for AAI that were defined. For more information, see Configuring IWSz Schedulers (Web UI) or Configuring IWS Schedulers (Thick Client).

Upgrading an IWS Connector

If you are using IWSz or IWSd schedulers in your AAI environments, then when you upgrade your AAI server, you should also check that you have the latest and compatible version of the IWS Connector. For information, see Compatibility Information.

To upgrade an IWS Connector

  1. Take down the currently installed IWS Connector.

    On Windows: Stop the Windows service for the IWS Connector.

    On Linux: Run the bin\shutdown.sh file.

  2. Upgrade and then start the AAI server. For information, see Upgrading Automic Automation Intelligence.

  3. Upgrade the IWS Connector.

    Check the compatibility matrix (compatibility matrix) to find the relevant information about supported versions and possible dependencies. For more information, see Compatibility Information.

  4. Restart the IWS Connector.

    On Windows: Star the Windows service for the IWS Connector.

    On Linux: Run the bin\startup.sh file.