SMTP Configuration Commands

As an AAI administrator or in-house developer, you can use the commands in this topic to define and maintain the SMTP mail server connection for your AAI installation. This mail server is used to send jobstream alerts that are defined to trigger email notifications. It is also used to send reports that are defined to be sent by email.

This connection definition is the same as the one that you otherwise define on the Other tab of the AAI Configuration Tool. For more information, see Configuration Tool - Other Tab.

For information about system configuration commands, see Configuration Tool Command Line Interface.

This topic describes everything you need to prepare for and run the commands for managing your SMTP connection configuration.

This page includes the following:

• smtpconfig --create
• smtpconfig --update
• smtpconfig --delete

smtpconfig --create

Configure a new SMTP mail server connection for your AAI installation. .

This process requires two preparation steps before running the command:

• Step 1: Define the smtpconfig.properties file
• Step 2: Prepare password input
• Step 3: Create an SMTP connection
• Example — Creating an SMTP Connection with a Script

Step 1: Define the smtpconfig.properties file

You define the configuration for the mail server configuration in a properties file. A template file is provided to simplify this task. Use the following steps to prepare the file:

1. Go to the config directory of your AAI installation (<Full path to AAI Installation directory>/config).
2. Make a copy of the smtpconfig.template file and name it smtpconfig.properties.

   You can move your properties file anywhere on the same physical server where AAI is installed.   

   In the smtpconfig.properties file, define the properties for your connection, as described below.

Properties of the smtpconfig.properties file

• smtpEmailSender (optional) - If specified, this email address will appear as the sender of the SMTP emails.

  Some SMTP servers require a sender email address. However, even if yours does not require it, we recommend that you specify a distinct sender email address so that recipients can recognize and filter emails from the server.

  Default: None

• smtpHostName (required) - The DNS hostname or IP address of your mail server.

  Values: A valid IPV4 address, such as "10.10.10.10" or "blrbdl003136-01.example.net"

  Default: None

• smtpPort (optional) - The port your mail server has open for connections.

  Values: Any number between 1 – 65535

  Default: 25

• smtpUseStartTls (optional) - This parameter enables TLS-encrypted communications between AAI and the SMTP server. See Configuring the AAI Server for TLS Authentication.

  Values: true / false

  Default: false

• smtpUser (optional) - If your mail server requires a mail user and password to send mails, provide the mail user name. For example, "aaiMailAdmin".

  Default: None

  Note:

  For security reasons, the properties file has no parameter for the SMTP user password. For information about how to provide the password to your configuration, see smtpconfig --create

Example smtpconfig.properties file

smtpEmailSender=smtp.alert.generator@mycompany.com

smtpHostName=10.10.10.10

smtpPort=655

smtpUseStartTls=false

smtpUser=smtpAdmin

Step 2: Prepare password input

If your SMTP mail server requires a password, the command will fail if you do not provide one. There are three options to provide the password value, and if a password is not required there are options to not provide one.

Option 1: Manual entry at runtime with the -p parameter

Use the -p parameter in the command. No preparation is necessary.

Option 2: With a properties file and the -pf parameter

Create an smtpPassword.properties file somewhere on the AAI installation server with the following property key and the password value:

smtpPassword="<password_value>"

Option 3: With an environment variable

Define an environment variable on the AAI server, where you run the command. No command parameter is required. The command will look for the variable when it runs. Use the following steps

• On Windows:

  1. On the AAI server, open the command-line prompt and go to the folder for environment variables.  

  2. Use the following command to create an smtpPassword variable with the password value:

     SETX smtpPassword "<password_variable_value>"

     Important!

     The variable value must not be empty when you are in a Windows environment.

  3. Restart the Command Prompt for the changes to take effect.  

     Important!

     Do not skip this step, even if you define the environment variable via the Windows Settings interface utility!

• On Linux:

  1. On the AAI server, open the command-line prompt and go to the folder for environment variables.

  2. Use the following command to create an smtpPassword variable with the password value:

     set smtpPassword=<password_variable_value>

Option 4: Choosing to provide no password

If your SMTP mail server does not require a password, you can configure the connection without one in one of the following ways:

• Use the -p parameter and when you are prompted to enter a password at runtime, just press Enter.

• Use the -pf parameter and create an smtpPassword.properties file with an empty the password value: smtpPassword=""

• (Only in Linux) Create an smtpPassword environment variable that has an empty value: set smtpPassword=

Step 3: Create an SMTP connection

Prerequisites and dependencies

• You are logged in as an admin user in AAI.
• No SMTP server is already configured for AAI.
• You have completed Step 1: Define the smtpconfig.properties file
• You have completed Step 2: Prepare password input, as needed

Result

An SMTP connection for mail communications with AAI is created according to the configuration settings specified in the required properties file and optional password as you specify in the command that you run

Command and Parameters

The following shows all required and optional parameters of the command to create an SMTP mail server configuration for an AAI installation.

java -Dswing.aatext=true -Daai.installation.dir="<Full path to AAI Installation directory>" -jar config.jar smtpconfig --create "<Full path>/smtpconfig.properties" -p |-pf <Full path>/smtpPassword.properties"

Where smtpconfig --create are the command and the method, and the following are the possible parameters:

• -Daai.installation.dir="<Full path to AAI Installation directory>"(optional)

  The full path to the AAI installation directory to be specified when you want to run the command from somewhere on the AAI server other than <AAI Installation directory>/config.

• "<Full path>/smtpconfig.properties"

  The full path for the smtpconfig.properties file with the all configuration settings, except the password.

• -p (optional)

  An additional parameter that causes the command to prompt you at runtime to enter the SMTP password.

• -pf "<Full path>/smtpPassword.properties" (optional)

  An additional parameter that points to an smtpPassword.properties file that contains the SMTP password.

Important!

Do not run both the -p and the -pf parameters in the same command! 

Example commands: Create an SMTP configuration from the CLI

Example 1:

We are in the <AAI installation>/config directory when we run the command, and we want to be prompted for the password.

java -Dswing.aatext=true -jar config.jar smtpconfig --create "<Full path>/smtpconfig.properties" -p

When we run the command, we will be prompted to enter a password. If a password is required, and we do not enter one, after the third prompt attempt, the configuration would fail.

Example 2:

We are outside the <AAI installation>/config directory when we run the command and we have defined the password in a properties file.

java -Dswing.aatext=true -Daai.installation.dir="<Full path to AAI Installation directory>" -jar config.jar smtpconfig --create "<Full path>/smtpconfig.properties" -pf "<Full path>/smtpPassword.properties"

Example 3: 

We are in the <AAI installation>/config directory when we run the command, and we have defined the password in the environment variable smtpPassword.

java -Dswing.aatext=true -jar config.jar smtpconfig --create "<Full path>/smtpconfig.properties"

With this command, if no smtpPassword environment variable exists, the configuration will fail.

Example — Creating an SMTP Connection with a Script

You can use a script to create an SMTP connection for AAI mail communications.

Prerequisites and dependencies

• You are logged in as an admin user in AAI.
• No SMTP server is already configured for AAI.
• You have defined the configuration settings in your smtpconfig.properties file. For information, see Step 1: Define the smtpconfig.properties file.
• If you intend to provide an SMTP password with the smtpPassword.properties file or the smtpPassword variable, you have prepared those.
• Before you run the script, you start in the start in the config directory in the AAI Installation directory.

Example

The following example shows the script that you might run on a Linux server to create the SMTP configuration when the password is defined in a properties file:

run.sh smtpconfig --create "<Full path>/smtpconfig.properties" -pf "<Full path>/smtpPassword.properties"

On a Windows server, replace run.sh with run.bat.

smtpconfig --update

Make changes to the configuration of the SMTP mail server connection that is defined for your AAI installation.

Step 1: Define an smtpconfig_update.properties file

You define the updates to your SMTP mail server configuration in a specific properties file. A template file is provided to simplify this task. Use the following steps to prepare the file:

1. Go to the config directory of your AAI installation (<Full path to AAI Installation directory>/config).
2. Make a copy of the smtpconfig.properties file that you used to create the configuration and name it smtpconfig_update.properties.

   You can move your properties file anywhere you want on the same physical server where AAI is installed.   

   Tip:

   You could also copy the provided smtpconfig.template file and name it smtpconfig_update.properties. The advantage of copying the smtpconfig.properties file is that you see the most recently configured settings and can comment out what you want to keep as is.

3. In your smtpconfig_update.properties file, do the following:

   1. For each property that you want to change, enter the new value and make sure that there is no # (pound sign) at the beginning the line.
   2. For each property that you want to keep as is, add a # (pound sign) at the beginning the line.

   For a description of all the properties and their allowed values, see Step 1: Define an smtpconfig_update.properties file in the instructions for creating an SMTP mail server configuration.

4. Save your properties file.

Example smtpconfig_update.properties input file

In the following example, we change the sender email address for the SMTP messages and we clear the previous smtpUser name:

smtpEmailSender=someone@mycompany.com

#smtpHostName=

#smtpPort=

#smtpUserStartTLS=false

smtpUser=

Step 2: Prepare password input

If you want to update the SMTP password, and you want to use the smtpPassword.properties file or an smtpPasword environment variable to provide it to the configuration update, then prepare that input. For information, see Step 2: Prepare password input under the steps for creating an SMTP connection.

Step 3: Update your SMTP connection

Prerequisites and dependencies

• You are logged in as an admin user in AAI.
• An SMTP server is already configured for AAI.
• You have completed Step 1: Define an smtpconfig_update.properties file
• You have completed Step 2: Prepare password input, as needed

Result

An SMTP connection for mail communications with AAI is updated according to the configuration settings specified in the required properties file and optional password as you specify in the command that you run.

Command and Parameters

The following shows all required and optional parameters of the command to create an SMTP mail server configuration for an AAI installation.

java -Dswing.aatext=true -Daai.installation.dir="<Full path to AAI Installation directory>" -jar config.jar smtpconfig --update "<Full path>/smtpconfig_update.properties" -p |-pf <Full path>/smtpPassword.properties"

Where smtpconfig --update are the command and the method, the configuration values to change are defined in smtpconfig_update.properties and the remaining parameters are the same as for the create command.

Example command: Update an SMTP configuration from the CLI

We are outside the <AAI installation>/config directory when we run the command and we have defined the password in a properties file.

java -Dswing.aatext=true -Daai.installation.dir="<Full path to AAI Installation directory>" -jar config.jar smtpconfig --update "<Full path>/smtpconfig_update.properties" -pf "<Full path>/smtpPassword.properties"

The command checks whether a connection configuration already exists and validates the settings. It also looks for the smtpPassword.properties file and updates the password accordingly.

The command updates the connection.

Example — Updating an SMTP Connection with a Script

You can use a script to update an existing SMTP connection for AAI mail communications.

Prerequisites and dependencies

• You are logged in as an admin user in AAI.
• An SMTP server configuration for AAI exists.
• You have defined the configuration settings in your smtpconfig_update.properties file. For information, see Step 1: Define an smtpconfig_update.properties file.
• Before you run the script, you start in the start in the config directory in the AAI Installation directory.

Example

The following example shows the script to update the SMTP configuration on a Linux server and the password is defined in a properties file:

run.sh smtpconfig --update "/Automic_Automation_Intelligence/config/smtpconfig_update.properties" -pf "/Automic_Automation_Intelligence/config/smtpPassword.properties"

On a Windows server, replace run.sh with run.bat.

smtpconfig --delete

Delete the SMTP mail server connection for your AAI installation.

Prerequisites and dependencies

• You are logged in as an admin user in AAI.
• An SMTP server connection configuration for AAI exists.

Result:

Your SMTP connection configuration for mail communications with AAI is reset to the initial, default values. For a description of the default values for the related properties, see Step 1: Define the smtpconfig.properties file in the instructions for creating an SMTP connection.

Command and Parameters

The following shows all required and optional parameters of the command to create an SMTP mail server configuration for an AAI installation.

java -Dswing.aatext=true -Daai.installation.dir="<Full path to AAI Installation directory>" -jar config.jar smtpconfig --delete

Where smtpconfig --delete are the command and the method, and -Daai.installation.dir is the optional parameter to specify the path to the AAI/config folder.

The command checks whether a connection configuration exists and resets the configuration to its initial, default values.

Example output: Delete an SMTP connection

In the following example, the first line in italics is the command we enter. The rest is returned by the program.

With this command entry, we run the smtpconfig --delete command to reset the SMTP connection configuration to its initial default values. We also use the optional parameter to specify the location of the AAI installation directory.

java -Dswing.aatext=true -Daai.installation.dir="/opt/Automic_Automation_Intelligence" -jar config.jar smtpconfig --delete

Starting Config Tool

19:09:30.043 INFO [configui.settings.SmtpConfigHandler] Running smtp config

19:09:30.043 INFO [configui.settings.SmtpConfigHandler] Resetting smtp fields in database

19:09:31.382 INFO [configui.settings.SmtpConfigHandler] Reset of smtp fields is successful

Example — Deleting an SMTP Connection with a Script

You can use a script to reset your SMTP connection configuration in AAI to its initial, default values. With this action, you disable SMTP mail notifications for jobstream alerts, and sending reports with emails directly from AAI.

Prerequisites and dependencies

• You are logged in as an admin user in AAI.
• An SMTP server configuration for AAI exists.
• Before you run the script, you start in the start in the config directory in the AAI Installation directory.

Parameters

• smtpconfig the command for the smtp configuration.
• --delete is the method/mode.

Example

The following example shows the script to delete the SMTP configuration on a Linux server:

run.sh smtpconfig --delete

On a Windows server, replace run.sh with run.bat.