Administering the Automic Connector

With AAI for Automic Automation you can get the runtime information of executions from different Clients in multiple Automic Automation systems into a single view. This means that you can see executions, whether completed, running or forecasted, of more than one Automic Automation system on a single interface. With execution data in AAI, you have multiple views of different aspects of workflow executions, with aggregations, details and drill-down graphical representations, all at your fingertips. You can see the collected runtime information from different performance aspects without having to switch from one Automic Web Interface to another, making both managing and comparing multiple Clients from one place.

This topic gives you an overview of the AAI integration architecture for Automic Automation and provides instructions on how to install and manage the Automic Connector to enable this integration.

Architecture of the Automic Connector Installation

The following diagram illustrates the relationships between your Automic Automation engines and their Clients, the Automic Connector, Automic schedulers in AAI, and the AAI database.

As illustrated in the diagram, the following are the important relationships in the architecture of connecting Automic Automation Client data to AAI:

• You link only one Automic Connector to an AAI installation (1 Automic Connector to 1 AAI installation).

• All your Automic Automation Clients from all Automic Automation Engines will use the one connector to pass workload data to AAI (many Clients and Engines to 1 Automic Connector).

• And, in AAI you must add a separate scheduler for each Automic Automation Client that you want to view and analyze in AAI (1 Automic Automation Client to 1 AAI scheduler). For more information, see Adding/Editing/Deleting Automic Automation Schedulers.

• All Client job definitions and job execution data is then collected, aggregated, and stored in the AAI database.

Preparations and Considerations for Installing the Automic Connector

Before you install and configure the Automic Connector for AAI, you should complete the following preparation steps:

1. Ensure that AAI is installed and up and running. For information, see Installing AAI.

2. In Client 0 of your Automic Automation installation, update the UC_SYSTEM_SETTINGS variable to set the EXECUTION_TRIGGER to Y[es].

   This is necessary for the Automic Automation to be able to establish the connection to the Automic Connector. For more information, see the "EXECUTION_TRIGGER" topic in the Automic Automation documentation.

   Tip:

   It can be advantageous to activate the EXECUTION_TRIGGER seven or more days before you intend to add your Automic schedulers in AAI, so you can have the maximum data that Automic can provide to AAI on the first day that the scheduler is running. For more information, see Administering the Automic Connector.

3. Check with your database administrator for the following:

   • Confirm that adequate sizing has been allocated for the Automic data that will be sent to AAI and added to its database.

   • Get the database login credentials, such as the database admin user name and password. You will need these during the connector installation (and again later when adding Automic schedulers in AAI)

4. Download the required Automic Connector ZIP file from the download center.

   The file is called AAI.Automic_Connector_<product_version>.zip.

   Make sure to download the version that corresponds to the version of AAI that you want connect to. For instructions, see Downloading AAI and Its Components, and for the required version, see Compatibility Information for AAI 24.4.x.

5. Gather all the configuration setting values that you need during installation. For this read through the steps for your operating system: Installing/Upgrading the Automic Connector on Windows or Installing the Automic Connector on UNIX.

Considerations for Upgrading the Automic Connector

To upgrade an already installed Automic Connector, you must take the following sequence of actions: 

1. Download Automic Connector version for the relevant AAI Server version.

   Upgrades to the Automic Connector always are part of an upgraded AAI version.Check the Compatibility Matrix (Compatibility Matrix) to find the relevant information on supported versions and possible dependencies. For more information, see Compatibility Information for AAI 24.4.x.

2. Take down the Automic Connector.

3. Upgrade and start AAI

4. Then upgrade and start the Automic Connector, using the steps for your operating system: Installing/Upgrading the Automic Connector on Windows or Installing the Automic Connector on UNIX.

Installing/Upgrading the Automic Connector on Windows

To install or upgrade the Automic Connector on Windows:

1. Unzip the downloaded AAI.Automic_Connector_<product_version>.zip.

2. Run the automic-connector.exe file to setup the installer.

3. Follow the instructions in the setup wizard.

   1. (Optional) If you want to create a Start Menu folder and/or shortcuts for all users, you can define a destination directory.

   2. Enter the connector parameters, making sure to provide the required information for your environment and connection type:

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

      • Log file output path

        The path to the location of the log files. The directory must exist and be writable for the connector user account.

      • Max log file size

        The maximum size of the log files. Must be defined as an integer in MB and must be 1 or larger.

      • Max log file count

        The number of log files to be retained. Must be defined as an integer in MB and must be 5 or larger.

Results of the installation or upgrade

When you are done with the wizard, you can find the Automic Connector folder in the directory that you defined.

When the connection was successful:

• The application.yml file is created in the folder where you have installed the Connector. This file contains the configuration values that you have just entered.

• At the same time, a backup copy of the application.yml with the your configurations 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. In this case, you have to manually update the application.yml file with your configurations. Remember to create a backup copy named application.yml.bak.

The Connector starts as a Service (automic-connector). You can use the services.msc to start and stop the service.

Next steps...

Once you have installed the Connector successfully, you have to add Automic Automation schedulers to your AAI environment. For information, see Adding/Editing/Deleting Automic Automation Schedulers.

You must add a new Automic Automation scheduler for each Automic Automation Client that you want to integrate into your AAI environment.

Starting/Stopping the Automic Connector on Windows or Checking Its Status

You can also run the installation file to start or stop the connector on a Windows installation or to check its status.

.\aai-automic-connector.exe /start

.\aai-automic-connector.exe /stop

.\aai-automic-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.

Installing the Automic Connector on UNIX

To install the Automic Connector on UNIX:

1. Go to https://downloads.automic.com/, log in with your Broadcom account and download the relevant version of the Automic Connector. For more information ,see Downloading AAI and Its Components.

2. Unzip the .zip file that you downloaded and unpack the .tar.gz file within to get the connector-install.sh and connector.automic-<version>.rpm files.

3. Run connector-install.sh to start the installation, for example:

   ./connector-install.sh install

   The Connector is installed using the .rpm file provided.

4. Configure the Connector to point to your AAI installation. To do so, run the configure script:

   cd /opt/automic-connector

   sudo -u automic-connector ./configure-automic-connector.sh

   Follow the prompts and make sure you enter the information required:

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

   • Log file output path

     The path to the location of the log files. The directory must exist and be writable for the connector user account.

   • Max log file size

     The maximum size of the log files. Must be defined as an integer in MB and must be 1 or larger.

   • Max log file count

     The number of log files to be retained. Must be defined as an integer in MB and must be 5 or larger.

   Example

   This example shows the Connector installed running HTTPS and on the default port. The Connector name can be freely defined and shows up in the UI when adding the scheduler.

   [sudo -u automic-connector./configure-automic-connector.sh
   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 ./secure/
   Press ENTER to continue...
   
   *** CONFIGURING CONNECTOR ***
   
   Backing up configuration file to: application.yml.bak...
   ...Configuration file backed up to: application.yml.bak.
   
   Please enter the following configuration parameters.
   
   AAI server URI [https://localhost:4443]: https://<host>:4443
   Connector name: automic
   Host name: host
   Connector key password (will not echo, required for HTTPS):
   AAI server username (required for HTTP):
   AAI server password (will not echo, required for HTTP):
   Connector domain: JAWS
   Log file output path. The directory must exist and be writable for the connector user account. [./logs]:
   Max log file size. An integer, in MB. Must be >= 1. [10]:
   Max log file count. An integer, in MB. Must be >= 5. [5]:

   If the installation ended successfully you see the following:

   Verifying AAI server connectivity (please stand by)...2020-12-08 23:54:55,708 INFO [ApiCallerUtil] Attempting HTTP connection to AAI
   
   ...AAI server connectivity verified.
   
   Saving connector configuration to: application.yml...
   ...connector configuration saved to: application.yml.
   
   *** CONNECTOR CONFIGURED ***

5. Start the service using the following command:

   sudo systemctl start automic-connector

Once you have installed the Connector successfully, you have to add Automic Automation schedulers to your AAI environment. For information, see Adding/Editing/Deleting Automic Automation Schedulers.

You must add a new Automic Automation scheduler for each Automic Automation Client that you want to integrate into your AAI environment.

Starting /Stopping, Upgrading, or Uninstalling the Automic Connector on Unix, or Checking Its Status

You can verify the service for a Unix installation by running the following command:

sudo systemctl status automic-connector

You can also use the systemclt command to stop or to restart the connector, or to get its status. For example:

sudo systemctl stop automic-connector

sudo systemctl restart automic-connector

sudo systemctl status automic-connector

If for any reason the service is disabled, you can use the following systemctl command to re-enable it:

sudo systemctl enable automic-connector

It is recommended to have the Connector restart automatically as part of the server reboot process.

You can also run the connector-install.sh to upgrade or uninstall the connector, or to get its status using the following commands:

./connector-install.sh upgrade

./connector-install.sh uninstall

./connector-install.sh status

If the current status of your system does not allow you to run a specific command, you get a corresponding error message. For example, you cannot upgrade a package that has not yet been installed.

./connector-install.sh upgrade

Can't upgrade the connector 'connector.automic" isn't installed. Please 'install' instead.

Additional Commands for a Unix Installation of the Automic Connector

• Log file location

  /opt/automic-connector/logs/automic-connector.log

  tail -f /opt/automic-connector/messages/automic-connector.log

• greps for process status

  ps -eaf | grep connector

• Uninstall the connector  

  rpm -e automic-connector-2.0.0.x86_64

  rm -rf /opt/<Connector Install Dir>

Securing the Automic Connector Communication with TLS

You can secure data communication with the Connector using TLS 1.3 authentication. For more information, see Securing AAI: TLS and Kerberos

The two-way certificate-base authentication is used to secure the connection between the Automic Connector and the AAI Server.

The connection between the Automic Connector and Automic Automation is established using the AE REST API and can be secured (HTTPS) or not (HTTP). If you want to secure the connection (HTTPS) make sure that the certificate used for the communication between the REST process and the Automation Engine in Automic Automation is also included in the Java Truststore where the Automic Connector is installed.

For more information about the relevant certificates, see Securing Connections to the AE (TLS/SSL), Preparing TLS/SSL Certificates, and Types of Server Processes in the Automic Automation documentation at https://docs.automic.com/.

See also:

• Connectors for Universal Schedulers

• Configuring the Connectors for TLS Authentication

• Adding/Editing/Deleting Automic Automation Schedulers