AAI Integration for CA Workload Automation ESP

Automic Automation Intelligence (AAI) for ESP allows you to put the runtime information of executions from different Clients in multiple ESP systems into a single view. This means that you can see running executions (and possibly failed ones) of more than one ESP system in a single interface, without having to switch from one ESP interface to another.

The ESP Connector can be installed either on Windows and UNIX (Linux or zLinux) platforms.

ESP Requirements

Before installing the ESP Connector, make sure that all the necessary CA Workload Automation ESP components are installed and configured. For more information, please refer to the official CA Workload Automation ESP documentation.

ESP Connector Requirements

Before starting with the ESP Connector installation, make sure that your system meets the following requirements:

• Minimum memory amount: 4GB

• Minimum disk space: 1GB

• Java is installed and PATH contains a path to Java binaries, otherwise configuring the ESP Connector is not possible because the configuration script fails.

Setup and Configuration

Before adding an ESP instance to your Automic Automation Intelligence system, you must have Automic Automation Intelligence up and running. For more information, see Installation Guide.

The ESP Connector has to be installed as well. You can find the relevant installation files (Windows or UNIX) at https://downloads.automic.com/. If you need help with the installation, please contact our support team at https://support.broadcom.com/.

The naming conventions for the ESP Connector .zip file are the following:

• AAI.ESP_Connector_<product_version>.zip

Also, you can secure your Connectors using TLS 1.2 based secure connections. For more information, see Two-Way Certificate-Based Authentication over TLS 1.2.

See also Configuring Connectors for Authentication.

Installing the ESP Connector on Windows

The configuration of the ESP connector starts automatically after the installation.

To install the ESP Connector on Windows:

1. Go to https://downloads.automic.com/ and log in with your Broadcom account.

2. On the Downloads page, select Automic Automation Intelligence > Automic Automation Intelligence Engine MULTI-PLATFORM and download the relevant version of the ESP Connector.

   Put the .zip file in a temp location on the server where the connector will run and unzip the file to that location.

3. Run the esp-aai-connector-<version>.exe file to setup the installer.

4. Follow the instructions in the setup wizard. You are prompted to configure the connector during the installation.

   Once the installation completes successfully, the ESP connector starts as a Service.

5. If the connector configuration failed during the installation, or if you want to change the configuration, do the following:

   1. Go to the folder where the connector is installed.

   2. Execute setup.bat file. This will open the Command prompt window.

      Important!

      • Once setup.bat is started, the following message prompts you to obtain the Connector certificate: "If you are planning to make a TLS based connection to AAI then before proceeding please obtain the connector certificate package from the AAI server and copy it to C:\Program Files\esp-aai-connector\secure\"

      • If using the Connector certificate, generate it now. For more information, see Generating the AAI Server Key.

   3. Follow the instructions and enter the required information:

      • AAI server URI

        You must specify the protocol, domain host name or IP address, and a listening port number of the AAI server. This information should be captured during the AAI server installation.

        If you are using the Connector certificate, this URI may use HTTPS and port 4443. Otherwise, it will likely be the same port that is used to launch the AAI client from a browser, for example http{s}://hostname:port.

      • Connector name

        Name of your choice. This name will be selected from the web UI when adding a scheduler to AAI.

      • Host name

        Domain name or IP address of the host where the Connector runs

      • Connector key password

        This is only required if an HTTPS connection is used between the Connector and the AAI server. If HTTP is used, leave this empty and hit Enter.

      • AAI server user name

        Only required when using HTTP.

        Name of the user ID that will be used to establish a connection to the AAI server. The user must be authorized to add new schedulers.

      • AAI server password

        This is required only if a HTTP connection is used between the Connector and the AAI server. If HTTPS is used, this can be omitted.

      • Connector domain

        Typically this is JAWS. This is the login domain for the user/password provided and it can be any of the list of domains that have been set up in AAI. For more information about domains, see Domains.

   4. After you have entered the required information, the script continues with the connection to the AAI server to verify that the provided data is correct.

      If the connection is successful, the application.yml file is created in the folder where you have installed the Connector. This is a configuration file that contains the configuration values that you have just entered. At the same time, a backup copy of the application.yml is automatically created and renamed to application.yml.bak.

      In the case of a failure, the application.yml file is not populated with the values you entered. You would have to manually repeat the configuration process.

   5. Open the Automic Automation Intelligence web interface and add the ESP scheduler. For more information, see Configuring CA Workload Automation ESP Schedulers.

Starting, Stopping, Uninstalling and Connector Status - Windows

On Windows, you can start and stop the ESP connector and check its status as a Service.

You can also run the esp-aai-connector.exe to start it, stop it and check its status.

esp-aai-connector.exe /start

esp-aai-connector.exe /stop

esp-aai-connector.exe /status

Expected output if the service is running:

Running.

Auto-start.

Expected status if the service is not running:

Not running.

Auto-start.

For details, refer to the output.log file that is created in the folder where the Connector was installed.

Uninstalling the Connector

To uninstall the connector, do the following:

1. Go to Apps & features.

2. Select esp-aai-connector-(version).exe.

3. Select the Uninstall button and follow the instructions.

Installing the ESP Connector on UNIX (Linux or zLinux)

To install the ESP Connector on UNIX (Linux or zLinux):

1. Go to https://downloads.automic.com/ and log in with your Broadcom account.

2. On the Downloads page, select Automic Automation Intelligence > Automic Automation Intelligence Engine MULTI-PLATFORM and download the relevant version of the ESP Connector.

   Put the .zip file in a temp location on the server where the connector will run and unzip the file to that location.

3. To install the ESP Connector do one of the following:

   • Use the rpm command as follows:

     rpm -ihv esp-aai-connector-(version).noarch.rpm

   • Use the yum command as follows:

     yum localinstall esp-aai-connector-(version).noarch.rpm

   Note:

   Currently only one Connector per system can be installed.

4. To configure the ESP Connector, go to the directory where the connector was installed.

5. Execute the configure-esp-aai-connector.sh file.

6. Follow the instructions and enter the required information:

   • AAI server URI

     Protocol, domain host name or IP address, and a listening port number of the AAI server. This information should be captured during the AAI server installation.

   • Connector name

     Name of your choice. This name will be selected from the web UI when adding a scheduler to AAI.

   • Host name

     Domain name or IP address of the host where the Connector runs

   • Connector key password

     This is only required if a HTTPS connection is used between the Connector and the AAI server. If HTTP is used, leave this empty and hit Enter.

   • AAI server user name

     Name of the user ID that will be used to establish a connection to the AAI server. The user must be authorized to add new schedulers.

     This is required only if a HTTP connection is used between the Connector and the AAI server. If HTTPS is used, this can be omitted.

   • AAI server password

     User ID password that will be used to establish a connection to the AAI server.

     This is required only if a HTTP connection is used between the Connector and the AAI server. If HTTPS is used, this can be omitted.

   • Connector domain

     Typically this is JAWS. This is the login domain for the user/password provided and it can be any of the list of domains that have been set up in AAI. For more information about domains, see Domains.

     This is required only if a HTTP connection is used between the Connector and the AAI server. If HTTPS is used, this can be omitted.

7. After you have entered the required information, the script continues with the connection to the AAI server to verify that the provided data is correct. If the connection is successful, the application.yml file is created in the directory where you have installed the Connector.

   In the case of a failure, the application.yml file is not populated with the values you entered. You would have to manually repeat the configuration process.

8. Register the ESP Connector and the Scheduler to AAI.

   Open the Automic Automation Intelligence web interface and add the ESP scheduler. For more information, see Configuring CA Workload Automation ESP Schedulers.

Starting, Stopping, Uninstalling and Connector Status - UNIX

You can run the esp-aai-connector.exe to start it, stop it and check its status.

To start or stop the connector, or to retrieve its status, start the command prompt as an administrator and enter the respective command:

sudo systemctl start esp-aai-connector

sudo systemctl stop esp-aai-connector

sudo systemctl status esp-aai-connector

Expected output:

esp-aai-connector.service - Esp-Aai-Connector   
Loaded: loaded (/etc/systemd/system/esp-aai-connector.service; enabled; vendor preset: disabled)   
Active: active (running) since Thu 2021-04-29 20:18:36 UTC; 1 months 9 days ago 
Main PID: 670155 (java)    
Tasks: 61 (limit: 100628)   
Memory: 1.0G   
CGroup: /system.slice/esp-aai-connector.service           
└─670155 java -jar /opt/esp-aai-connector/esp-aai-connector.jar

Uninstalling the Connector

To uninstall the connector issue the following commands:

• rpm –qa | grep <package name>

  This command returns the actual package name.

  Example:rpm –qa | grep esp-aai-connector

  Output example:esp-aai-connector-1.0.0~rc.1-.noarch

• rpm -e grep <package name returned by rpm -qa>

  Example (supposing that the rpm -qa command returned esp-aai-connector-1.0.0 .x86_64):

  rpm -e esp-aai-connector-1.0.0 .x86_64

  Important! Remove the extra "-" character before the last section of the package name. This "-" character comes from the rpm -qa.

  For example, if the package name is esp-aai-connector-1.0.0~rc.1-.noarch, remove the last "-" so that the package name is as follows: esp-aai-connector-1.0.0~rc.1.noarch.

Setting the Connector to Request Definition Data at Start

Optionally, after installing and configuring the connector, you can verify that the JCL is submitted to ESP before starting the ESP connector:

1. Obtain the ESP Connector ID.

   When the Connector starts, it prints out its ID in the log, for example *** Connector received (AXlmKbmkOnQ=).

   The string in brackets is the Connector ID. Keep this ID at hand because you will need it later.

2. Retrieve the scheduler configuration using the following command:

   curl http://{host:port}/aai/api/v2/schedulers?fetch=all

   where you replace host and port with your installation data.

   The output contains the configuration data of all your schedulers.

3. Use the Connector ID that you have just obtained to find the configuration that pertains to your Connector.

   The configuration data also provides the schedulerID. Keep this ID at hand because you will need it later.

4. In your schedule's configuration, copy the entire json block that is called schedulerConnectionConfig and paste it to the conf.json file. Wrap that block in { }. This is what it should look like:

   {
     "schedulerConnectionConfig" : {
       ...    
     }  
   }

5. To add the configuration that enables to retrieve jobs at start, copy and paste the following template at the end of the schedulerConnectionConfig block in your conf.json file:

   "default-trigger.publish-jobs-on-startup": true

   The content of the conf.json file should be similar to this now:

   {
     "schedulerConnectionConfig" : {
       ...
       "default-trigger.publish-jobs-on-startup": true
     }  
   }

6. To update the configuration, run the following command:

   curl -v -H "Content-Type: application/json" -X PUT --data

   @conf.json -u your_username:your_password

   http://{host:port}/aai/api/v2/schedulers/{schedulerId}

   Where:

   • {schedulerId} is the scheduler ID that you have just got in the configuration data.

   • your_username and your_password are your AAI credentials

     Note:

     If you are running this command from a different folder then specify an absolute path to your conf.json file.

   • {host:port} are your installation data

7. Once you have verified the connection, you can turn off the retrieval of jobs at start by modifying the conf.json and turning off the publish-jobs-on-startup flag. For this purpose, run again the following command:

   curl -v -H "Content-Type: application/json" -X PUT --data

   @conf.json -u your_username:your_password

   http://{host:port}/aai/api/v2/schedulers/{schedulerId}

   The content of the conf.json file should be similar to this now:

   {
     "schedulerConnectionConfig" : {
       ...
       "default-trigger.publish-jobs-on-startup": false
     }  
   }

Enabling Secure Connection Between the ESP Connector and ESP Message Hub

1. Obtain the ESP Connector ID.

   When the Connector starts, it prints out its ID in the log, for example *** Connector received (AXlmKbmkOnQ=).

   The string in brackets is the Connector ID. Keep this ID at hand because you will need it later.

2. Retrieve the scheduler configuration using the following command:

   curl http://{host:port}/aai/api/v2/schedulers?fetch=all

   where you replace host and port with your installation data.

   The output contains the configuration data of all your schedulers.

3. To configure a secure connection, copy and paste the following template at the end of the schedulerConnectionConfig block in your conf.json file:

   "esp-scheduler.mq-transport": "jks",

   "esp-scheduler.mq-jks-keyStore": "",

   "esp-scheduler.mq-jks-keyStorePassword": "",

   "esp-scheduler.mq-jks-trustStore": "",

   "esp-scheduler.mq-jks-trustStorePassword": ""

4. The content of the conf.json file should be similar to this now:

   {
     "schedulerConnectionConfig": {
       ...
       "esp-scheduler.mq-transport": "jks",
       "esp-scheduler.mq-jks-keyStore": "",
       "esp-scheduler.mq-jks-keyStorePassword": ""
       "esp-scheduler.mq-jks-trustStore": "",
       "esp-scheduler.mq-jks-trustStorePassword": ""
     }  
   }

5. Update the keyStore, the trustStore and their respective passwords.

   Update the properties according to your environment. Typically, the keyStore stores the private key of the ESP Connector and the trustStore stores the public key of the Message Hub server.

   The content of the config.json file should be similar to this:

   {
     "schedulerConnectionConfig": {
       ...
       "esp-scheduler.mq-transport": "jks",
       "esp-scheduler.mq-jks-keyStore": "/u/a/keystore.jks",
       "esp-scheduler.mq-jks-keyStorePassword": "123"
       "esp-scheduler.mq-jks-trustStore": 
   "/u/a/truststore.jks",
       "esp-scheduler.mq-jks-trustStorePassword": ""
     }  
   }

6. To update the configuration, run the following command:

   curl -v -H "Content-Type: application/json" -X PUT --data

   @conf.json -u your_username:your_password

   http://{host:port}/aai/api/v2/schedulers/{schedulerId}

7. Start the ESP connector.

See also:

• Configuring Connectors for Authentication
• Configuring ESP Schedulers