Configuring Automic Web Interface
You have already installed the Automic Web Interface. Now you can proceed with configuration activities. Many of them are optional.
This page includes the following:
The servlet container/application server can only make use of the memory it is configured to use, so you must choose the heap size according to your hardware configuration.
Use the G1 garbage collector, which significantly reduces garbage collection pauses for large heaps.
The number of users presented below are concurrent users, which means users logged in at the same time, being more or less active.
The hardware configurations proposed already include some headroom and yield very good response times for the given amount of users below.
If possible, use a fast network connection (10Gbit/s Ethernet) for the connection to Automation Engine.
Usually not even a hundredth of that is used under very high load, but a fast connection helps with latency and keeps data transfers short, which in turn reduces CP usage.
Server Configuration Sizes
Small Single Server Configuration: A small VM will run up to 50 concurrent sessions:
CPU: 4 virtual cores
Basic Single Server Configuration: A medium size VM will run up to 200 concurrent sessions:
CPU: 8 virtual cores
Fast Single Server Configuration: A medium size VM will run up to 500 concurrent sessions:
CPU: 16 virtual cores
Create a KeyStore File for your Tomcat Installation.
Open a command prompt with administrator rights and change the path to the Tomcat configuration directory (TOMCAT_HOME/conf/).
Create a keystore file with a self-signed certificate, using the following command. This will result in the output as shown below (status after complete editing).
The cursor will jump to the first line you can enter your values in. After each entry confirm with the Return key to jump to the next line.
"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -keystore tomcat-keystore.jks -storepass myTomcatKeystorePassword
What is your first and last name?
What is the name of your organizational unit?
What is the name of your organization?
What is the name of your City or Locality?
What is the name of your State or Province?
What is the two-letter country code for this unit?
Is CN=localhost, OU=YOUR_UNIT, O=YOUR_ORGANIZATION, L=YOUR_CITY, ST=YOUR_STATE, C=AT correct?
Enter key password for <tomcat>
(RETURN if same as keystore password):
You have to use the hostname / domain of your AWI instance as your first and last name (
localhostin this example).
This command will create a new keystore file named
tomcat-keystore.jksprotected with the password
myTomcatKeystorePasswordlocated in the configuration directory. The keystore contains a self-signed certificate for your AWI instance.
Import a signed certificate into the keystore (optional).
You can skip this step, if you use a self-signed certificate that you created in the previous step.
Use the following command to import a chain certificate or root certificate (if available) into your keystore first:
"%JAVA_HOME%\bin\keytool" -import -alias root -keystore tomcat-keystore.jks -trustcacerts -file <filename_of_the_chain_certificate>
Now import the certificate using this command:
"%JAVA_HOME%\bin\keytool" -import -alias tomcat -keystore tomcat-keystore.jks -file <your_certificate_filename>
To import an existing certificate signed by your own Certificate Authority (CA) into a
PKCS12keystore using OpenSSL you would execute a command like this:
openssl pkcs12 -export -in mycert.crt -inkey mykey.key
-out mycert.p12 -name tomcat -CAfile myCA.crt
-caname root -chain
Important! The Tomcat only supports keys and certificates in the
Configure the Tomcat connection.
server.xmlfile located in the configuration directory of your Tomcat instance.
Add the following connector configuration to your configuration file and save it:
protocol="Enter the current apache protocol here"
keyAlias="tomcat" keystoreFile="conf\tomcat-keystore.jks" keystorePass="myTomcatKeystorePassword"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" />
Restart your Tomcat instance to apply the changes.
For the parameter
keystorePassenter the password of the
Important! The previous example illustrates the how to configure the connector as it is at the time of writing. Check the Tomcat documentation for potential changes and for the latest information at Apache Tomcat.
Test the access to your AWI instance.
You can now access the Automic Web Interface using a secure connection.
As URL use
If you are using a self-signed certificate you may receive a warning that the connection is untrusted, because is not possible to verify the identity.
You can only avoid this warning if you are using signed certificates by a trusted certificate authority. The connection's encryption is the same as with a self-signed certificate.
Note: You have to confirm (add a security exception) that you want to use the self-signed certificate.
The procedure to secure the access to AWI depends on the WebSphere profile used in your company. Please refer to the official IBM WebSphere documentation for more information.
By default, the AWI configuration files are located in the web applications folder on the WebServer. In some cases it can be convenient to change this path, for example if the users who will configure the AWI should have no access rights to the WebServer folder.
Whether you are installing via the ONE Installer or manually, you can customize the path in which the configuration files should be stored. For this purpose, you set the following JVM arguments, either specifying them in the Java environment or using the management utilities of your WebServer:
-Dcom.uc4.ecc.config.dir= Use to change the path when installing manually.
In a Tomcat installation, the default path of the configuration files is <webserver>/webapps/awi/config.
Let's suppose that you want to store the configuration files in the C:\AWI_config\config folder. In an installation with Tomcat you must add the following attribute to the CATALINA_OPTS environment parameter
-Dcom.uc4.ecc.autoinstall.dir= Use to change the path when using the ONE Installer.
In a Tomcat installation, the default path of the configuration files is <webserver>/webapps/awi/WEB-INF/autoinstall
Let's suppose that you want to store the configuration files in the C:\AWI_config\plugins folder. In an installation with Tomcat you must add the following attribute to the CATALINA_OPTS environment parameter
Note: After setting this argument you must restart the application server.
The Automic Web Interface supports different user authentication configurations which result in different user login options. As a system administrator, you can configure AWI to support the authentication and login approach that you want.
By default, when users log into AWI, the entire authentication process is handled by the Automation Engine to which the instance is connected. AE confirms whether the user credentials match the values in the related user object (USER).
You can also enable single sign-on using either the Kerberos or SAML protocol, or enable parametrized login.
Using the Standard AWI Login
By default, the AWI users have to provide the following login information when they open the AWI:
English (default), Deutsch, Français
Depending on how the automationEngine.index parameter in configuration.properties is defined, either one or all defined connections to the backend Automation Engine are listed. For more information, see configuration.properties.
The number of the user client.
User name in the user definition.
- Department (optional)
The user's department in the user definition.
If the LDAP option is selected in the user definition, this is the user's domain password, which she uses when logging into the computer at startup. Without LDAP, this is the password that is entered in the user definition.
- Session Color (optional)
An accent color for the process strip at the top of the AWI browser page and for highlighted selections. When users open more than one session, having different session colors helps users distinguish which session they are in.
Your browser stores your login entries (except password) for your next login.
Note: You can always change the session color from the session menu in the main menu bar.
Using Single Sign-On
Setting up single sign-on for the Automation Engine system allows users to login only once, without having to enter login details over and over again. The Automation Engine supports Kerberos Key Distribution Center (KDC) and the Security Assertion Markup Language 2.0 (SAML 2.0) protocols.
You enable single sign-on (SSO) in the configuration.properties of your Automic Web Interface instance by setting the sso.kdc.enabled or sso.saml.enabled property to true, depending on which protocol you want to use. For more information, see configuration.properties.
You can also decide if you want to enable autologin to use a fully or partially automatic login:
Enabling autologin results in a fully automatic login and allows you to bypass entering any login information in the future . Make sure to select your session options (Language, Connection, Client, Session Color) before enabling it.
Disabling autologin results in a partially automatic login and allows you to change your session options (Language, Connection, Client, Session Color) without having to enter your user information or password.
For more information on SSO, Kerberos and SAML configuration, see Setting up Single Sign-On.
Enabling Parametrized Login in AWI
Another convenient feature is enabling parametrized login, which you do by appending the login parameters in the URL that you use to start AWI. This is helpful if you or users use several connections and/or clients. You can just bookmark the various login combinations. When you open the bookmarked URL, you have to enter only your password.
In your AWI instance, set the parameter_login.enabled property to true in the configuration.properties file, see configuration.properties.
In your AWI startup URL, append the login information that you want to have already entered in the login window.
Note: If your browser does not access AWI over an SSL protocol, your URL will start with http://.
As an administrator, you might want to send individualized URLs to your new users
For information about the kind of log data to collect for an CA Automic Support ticket, see Preparing Log Files for Error Reporting.
If errors occur, the logging information can help you finding the source for the error. Logging is enabled by default. You can change the default log level if you want more or less event occurrences written to the log file.
Logging in the AWI is handled by the Tomcat logback framework. You can define the log level in the
logback.xml file. The specified log level defines the lowest severity. Its occurrence and the occurrence of events of higher severity are logged. Extensive logging, however, can impact AWI's performance. When you encounter performance problems, check your log level and reduce the written messages by specifying a higher log level, if necessary.
Logging involves the following files:
...\<AWI>\configfolder of your application server.
- Log files in the
logsfolder of your application server.
The log level values available (highest to lowest) are:
Purpose: Failure of some action of an AWI component that AWI was not able to recover from, such as
Tracing Data in Message: No user-identifying data. However, hostnames, other site-specific data, class names, object names, and the like are included with the event related specifications. The message contains the full stack trace.
Purpose: Unexpected behavior of an AWI component, such as unstable network connections that require auto-reconnect from AWI, a post-timeout retry, or triggering of a workaround for a third-party bug .
Tracing Data in Message: Same as ERROR level
Purpose: Configuration values at login or component startup, or global configuration changes.
Tracing Data in Message: Same as ERROR level but without the full stack trace.
Purpose: High-level user-specific actions such as login/logout events, user changes (such as object edits), authorization related events (such as successful/failed setup actions), and important performance measures
Tracing Data in Message: User information (such as user ID and HTTP session ID) and event related specifications.
Purpose: Low-level user-specific actions such as navigation, object open, button clicks, the payload of backend-calls, internal application events, and all calls to the backend.
Tracing Data in Message: Same as DEBUG.
Changing the Log Level
Logging is enabled by default set to DEBUG, but, if necessary, you can change the log level in the
logback.xml configuration file that you find in the
...\<AWI>\config folder of your application server.
Important! Do not change any other parameters in this file. Changing other parameters might prevent CA Automic from investigating situations that cause errors.
The log level is defined in the
<root> element by the
level="[log_level]"> element The <root> element contains the
<appender-ref> element that specifies that this
<root> element defines the LOGGER appender. The LOGGER appender is the component that writes the logging events to the log file.
To Change the Log Level
- Switch to the
webapps\<AWI>\configfolder and open the
- Search for the
Note: You can find the
<root>element best by searching for
<root>element is one line above.
- Change the log level for the root appender by setting the
level="[log_level]"attribute to the lowest log level for which you want messages to be written to the log file. For more information, see Log Levels.
- For the changes to take effect, stop and restart your application server.
The log level is set to "DEBUG" (default value) in the following example. If you change it to "INFO", fewer messages are written to the file, as non-critical log messages are ignored.
<!-- Log level is set here. Possible values: TRACE, DEBUG, INFO, WARN, ERROR
DEBUG is recommended on testing and development instances.
INFO is recommended on production instances.
<appender-ref ref="LOGGER" />
AWI Log Files
The log files are located in the
logs folder of your application server and are named <host name>_ECC_Log.##.TXT:
<host name>is the computer's name where the application server is running#.
##is an ascending number. 00 is the current log file.
The current log file is a
.txt file, older log files are compressed in
Note: As an administrator, you can also enable writing trace files (similarly named as the log files (
<Host name>_ECC_TRACE.##)) to this folder to find the cause of an error.
By default the AWI interface has the CA Automic logo on the login dialog and in the header bar. All pages use the default gold color and shades of black and gray. You can customize the color and logo to reflect your company brand.
To Change the Logo
Prepare your logo file. Make sure the image size is not larger than:
Copy logo.png into the …\<AWI>\config\theme folder.
Add the configuration parameter logo.filename = logo.png to the color.properties file to specify the new logo.
Depending on how your logo looks like, you may want to add a white box to differentiate it from the dark background. To do so, add the parameter white.background = true to the color.properties file
Note: If you do not see the changes with the next login to AWI, restart the Tomcat Webserver.
To Change the Color Scheme
Open the colors.properties file that is available in the …\webapps\<AWI>\config\theme folder. For more information, see colors.properties.
In the maincolor parameter, specify the RGB color code. Make sure to precede it with the pound sign (#) and follow it with a semicolon (;).
For example, enter "maincolor = #fac800;" for the default gold.
Note: If you do not see the changes with the next login to AWI, restart the Tomcat Webserver.
There is a number of mandatory and optional configuration files that you have to modify.
Important! The configuration files that are not included here should not be modified.
Used to define the connection between the AWI installation to the AE systems that can be used as its backend.
logback.xml: Optional. Default settings are provided.
Controls logging behavior. You can change the lowest severity level of messages that you want to have tracked. The delivered value is "INFO".
Used to define aspects of the communication between the AWI and the AE, such as the security options and timeout intervals.
Defines a custom theme color for the AWI user interface.
After installing and configuring AWI you can start setting up your system or you can continue with the installation of other plug-ins and components.
For more information, see Requirements and Installation Types.
You can use the Automic Web Interface through any kind of proxy in the general sense, whether for TLS termination, load balancing, redundancy or all of these at the same time.
A single, powerful server can handle the traffic expected in AWI in a high performance Automation Engine installation. Therefore, you do not need to set up load balancers to improve the performance of the Automic Web Interface.
However, if you want high availability, you must have different AWI instances running on different hosts.
In this case, you need a load balancer to redirect the traffic in case one of the AWI instances fails.
Tip: It is recommended to have a hot/hot configuration with two instances, both of them serving traffic together. A switchover should only happen if the one server fails. Also, each instance must be able to handle all the traffic. Otherwise, if the other instance fails, the one that takes over would overload. If for any reason a single server cannot handle the load, you can add more instances to handle failures. For example, four or five instances instead of the required three.
Requirements for Load Balancers
To run with AWI, your load balancer must support sticky sessions. Like many Java webapps, AWI uses the JSESSIONID session cookie. You can configure your load balancer to use this cookie, or add its own, to route requests of the same session to the same server.
If you run AWI with websockets enabled, your load balancer must support them.
Please use the same path on your load balancer and the servlet containers.
If your servers are located on
http://backend2/awi, and your load balancer is located on the host
publicawihost, configure your load balancer to serve AWI on
If your load balancer does health checks via additional http requests, please use the relative path or check to do so. For example, if your AWI is reachable via
https://myawiserver/awi, the health check should invoke
This URL will return a response with status code 200 if AWI is running and the servlet container is handling requests, and not create any http sessions.
A load balancer or proxy can be very useful for transparently switching over between two versions of AWI when finalizing a Zero Downtime Upgrade. For more information, see Zero Downtime Upgrade.
On Tomcat, AWI uses WebSockets as an efficient way of sending information to the client. If you are using Weblogic or Websphere, AWI will fall back to long polling.
- Set the
allowWebsockets=falseparameter in AWI's configuration.properties file. For details, see Network Settings
- Running AWI without WebSockets slightly increases the CPU load on the servlet container, though, so be sure to add more resources to compensate for this.
- Do not increase system or client settings that affect how much data is shown to the user unless absolutely necessary.
- Do not put too many objects in the root folder. Apart from being overwhelming to navigate for a human user, it has a side effect on performance: The root folder is shown in Process Assembly by default and a long list of objects (thousands) significantly increases the memory per session as well as the CPU used when retrieving the folder list.
AWI shows loading indicators while waiting for responses to backend requests. Possible bottleneck symptoms are:
The web interface locks up:
The AWI server likely is the bottleneck.
Try increasing memory and Java heap space
Try increasing the amount of CPU cores
Loading times are too high:
Automation Engine likely is the bottleneck.
You can increase the number of DWPs and JWPs