Configuration

Once all the steps from the Installation chapter have been completed, the basic configuration of the best4Automic modules must be carried out to adapt them to the environment. To do this, settings must be made in a configuration file and the Java runtime environment to be used must be specified.

The configuration of the Core Edition and the Rest Edition are largely the same, as they are based on the same mechanisms. The differences between the Rest Edition and the Core Edition are described in this section.

Basic configuration

The first step is to define the Java runtime environment to be used. If the preferred Java runtime environment installed in the system is to be used directly, no adjustments are necessary. However, if a special Java runtime environment must be used for best4Automic, this should be defined via the environment variable JAVA_HOME. The best4Automic start scripts use this variable to determine the correct Java installation.

If the Java runtime environment is set accordingly, the basic configuration for best4Automic can be created. A separate configuration file can be created for each individual best4Automic module. The naming convention for this configuration file is <module>.conf, where <module> is to be replaced by the name of the respective module. It must be stored in the conf subdirectory by default. The default values are entered in this file line by line according to the format <long option name>=value (for example name=*TEST* or connection=B4A-1). If this does not exist, default values are read from the file defaults.conf, which is located in the subdirectory mentioned above. In addition to the default settings for the modules, this file also contains settings that are necessary for the basic function of the modules. These are described below.

License

Before using best4Automic, a corresponding license must be installed. This can be obtained from the best4Automic sales department. The license is delivered as a ZIP archive containing two files. These two files (license.json and license.sig) must be copied into the conf directory of the best4Automic installation.

As long as no license is installed, all best4Automic modules can be started and configured, only the execution is prevented. The best4Automic dashboard and best4Automic setup can still be used.

Connections

To enable the modules to establish a connection to one or more Automic Automation Engine servers, the connections must be specified in the configuration file. This is done in the form of URLs, which are specified as a comma-separated list in the connections option. A URL defines the following connection parameters:

• Server: IP address or name of the Automic Automation Engine server
• Port: Port of the CP (Communication Process) for the connection
• Environment: Name of an environment defined in the configuration
• Client: Number of the client to which the connection is established
• Name: A descriptive name for the connection
• User name (second variant): User to be used for the connection
• Password (second variant): Password of the user
• Department (second variant): Department of the user

With these parameters, the URL is structured as follows:

automic://<server>:<port>/<name>#<client>

In the second variant of the URL, the access data can also be specified in the URL:

automic://<server>:<port>/<name>?client=<client>;username=<username>;department=<department>;password=<password>

Any number of these URLs can be defined so that the connection data to all existing clients can be predefined. An example of a list with several connections is included in the configuration file supplied.

connections=automic://ae21.b4a.local:2217/B4A-1#1, \
    automic://ae21.b4a.local:2217/B4A-2?client=2;username=writer;department=b4a;password=test1234, \
    automic://ae21.b4a.local:2217/ORA0#0

Another variant of the URLs allows the definition of the server and the port to be outsourced and replaced by a set of transport addresses. This is useful if you want to implement reliability when establishing a connection. In the variants described so far, best4Automic can only address one CP at a time to establish the connection. If this cannot be reached for any reason, the module cannot establish the connection and therefore cannot execute the desired function. A list of CPs can be defined so that best4Automic has the option of switching to other CPs. These can be referenced in the URL. This requires define an entry in the configuration file according to the following format:

servers-<environment name> = <IP address or name>:<port>, ...

In the URLs, the expression <environment name> can then be used instead of <server>:<port> as shown in the following format:

automic://<environment name>/<name>?client=<client>;username=<username>;department=<department>;password=<password>

Example:

servers-prod = ae21-1.b4a.local:2217, ae21-1.b4a.local:2218, ae21-2.b4a.local:2219, ae21-2.b4a.local:2220
connections = automic://prod/prod10?client=10,username=WRITER,department=B4A,password=--10DJH342HDNDQA

If the Automic Automation Engine uses a certificate that cannot be verified by the system-wide CA certificates, b4A must be informed of the directory in which the correct certificate can be found. The setting certificate-directory can be used for this. The directory in which the required CA certificate can be found in PEM format must be specified here. In the following example, the certificates would be searched for in a folder certs, which is located in the base folder of the b4A installation.

certificate-directory = ../certs

This setting can be overwritten by the system property b4j.cert.directory.

Reestablishing connections

In the event that an open connection is lost, for example due to the sudden loss of the JCP, best4Automic attempts to re-establish this connection. The time between two reconnection attempts is doubled until the next attempt. Starting with 500 milliseconds. The maximum duration between two attempts can be configured, just like the maximum number of attempts. The following two settings are used for this:

max-reconnect-attempts = 10
max-reconnect-wait-time = 60000

logs

The best4Automic modules can log the tasks performed at different levels. A distinction is made between two types.

Progress (PROGRESS) Serves as an indication of the progress of processing

Report (REPORT)

Is the actual logging of the work carried out

The amount of information logged can be controlled via seven different levels. The levels can be combined with each other as required.

ERROR Important error messages

WARNING

Warning messages

INFO

Basic information on processing

DEBUG

Extended information (for developers)

TRACE

Logs the time consumption of certain actions, for example queries from the Automic server

JAVA_API

Activates the internal debugger of the Java API, which logs communication with the Automic Automation Engine as far as possible

DATASTREAM

Further details can be found in the section b4A Datastreams

The level of detail of the logging can also be influenced by flags:

• Timestamp: Enable or disable prefixed timestamps for report lines
• Time measurement: Additional output at the end about the time required
• Session: Details of the open session
• Monochrome (Terminal): If the option is deactivated, colors are used on UNIX terminals

All these log settings can be changed via module options.

• log-levels: To set the level for logging
• log-variants: To activate the progress bar and the report
• log-flags: This can be used to define formats and additional information in the logs.

The default settings for logging can be defined in a configuration file. By default, this is logging.json in the conf directory. However, the name of the file can be overwritten with the Java system property b4a.logging.configuration.filename. The settings are described below.

• output.standard.enabled: Specifies whether the log should be output on the standard output. When executed via the command line via the command line, in the user interface in the Report tab. This can also be done in parallel to writing to a file.
• output.standard.encoding: Defines the encoding for the standard output. If the parameter is not set here, the encoding of the environment or the encoding set with the log-encoding option automatically applies. More on this in this section.
• output.file.enabled: Specifies whether the log should be written to a file. This can also be done in parallel to writing to the standard output.
• output.file.encoding: Defines the encoding to be used for writing to the file. If the parameter is not set here, the encoding of the environment or the encoding set with the log-encoding option automatically applies. More on this in this section.
• output.rotation.dailyRotation: The output file for logging is automatically rotated. In addition to a size-limited rotation, this option can be used to activate rotation at the start of a new day.
• output.rotation.maxFileSize: Specifies the maximum size of log files for the log rotation before a new file is created. The size must be specified in MiB.
• output.rotation.maxBackupCount: This option is used to specify the maximum number of files to be retained during rotation before the oldest file in each case is deleted.
• output.file.name: Name and path of the log log file.
• levels: List of log levels. If these are not set via this option, the default values are ERROR, WARNING and INFO.
• flags: List of protocol flags. If these are not set via this option, the default value is only TIMESTAMP.
• variants: List of protocol variants. If these are not set via this option, the default values are REPORT and PROGRESS.

Coding of the output

Normally, the encoding of the environment in which best4Automic is started is used for the output of the logs. Nowadays, this is often UTF-8. Automic Automation Engine does not support this encoding. It may therefore be necessary to set the encoding for the output independently of the environment. This can be done as described here via the logging.json or with the log-encoding option. If set, this option overwrites the entry in the logging.json. The known identifiers for coding can be used here. Examples:

• UTF-8
• ISO-8859-1
• ISO-8859-15

Behavior in case of error

How the modules behave when an error occurs can be configured using the log-error-mode option. Three modes are available for this:

• Never: In this case, the module runs until all objects have been processed or all tasks have been completed. Only in exceptional cases is the module terminated with an error code. These are errors that the module cannot correct or that make further work impossible.
• First error: If an error occurs when processing an object in the process, the module is terminated immediately. Regardless of whether other objects could still have been processed (no fatal error such as connection termination)
• At the end of the process: Even if errors occur with several objects, the module is only terminated with an error when the last object has been processed.

Graphical user interface

Each of the best4Automic modules can be used as a command line program or with a graphical user interface. A connection must be selected for some functions of the graphical user interface. For example, to select a folder for operations.

Some of the options are displayed in subgroups that can be collapsed. The setting gui-bundle-expand can be used to define whether these groups are initially expanded or collapsed.

Advanced configurations

This section describes configuration options that relate to central settings for the entire best4Automic distribution. These are set via environment variables or Java system properties. The environment variable JAVA_OPTS can be used to pass the Java system property to the java runtime environment. Examples can be found in the following sections.

Directories

The best4Automic distribution contains a predefined directory structure that sets the standard. Each of these directories can be changed. Environment variables or Java system properties can be used for this, which are described below.

Environment variable	Java system property	Description
B4J_BIN_DIR	b4j.binary.directory	Absolute path to the start scripts
B4J_LIB_DIR	b4j.library.directory	Absolute path to the jar libraries and the metadata
B4J_DOC_DIR	b4j.documentation.directory	Absolute path to the documentation
B4J_DATA_DIR	b4j.data.directory	Absolute path to the data directory in which many modules store their output files by default
B4J_CONF_DIR	b4j.configuration.directory	Absolute path to the configuration files. Both the defaults.conf, modules.conf and the optional module configurations are searched for in the location. If the environment variable B4J_CONF_FILE is also set, then the module configuration is read from the specified file. All other configurations are still searched for in the directory B4J_CONF_DIR
B4J_TEMP_DIR	b4j.temp.directory	Absolute path to a directory in which temporary files are stored
	b4j.cert.directory	Path to a directory in which certificates are stored that are required for the encrypted connection to Automic Automation Engine
B4J_SCRIPT_DIR	b4j.script.directory	Absolute path to a directory in which b4A Custom Solutions are stored
B4J_CUSTOM_COMPLIANCE_DIR	b4j.custom.compliance.directory	Absolute path to a directory in which customer-specific compliance tests can be stored. These are delivered in the form of b4A Compliance Test Distributions.
B4J_CUSTOM_REPOSITORY_DIR	b4j.custom.repository.directory	Absolute path to a directory in which customer-specific repository backends can be stored. These are delivered in the form of Groovy files.
B4J_CUSTOM_REST_DATA_SOURCE_DIR	b4j.custom.rest.datasource.directory	Absolute path to a directory in which customer-specific data sources can be stored. These are delivered in the form of Groovy files.

Example for the use of environment variables.

export B4J_CONF_DIR = "/applications/configuration/best4Automic"
export B4J_DATA_DIR = "/tmp"
./b4A

To set the Java system properties, the environment variable JAVA_OPTS can be used as shown in the following example.

export JAVA_OPTS = "-Db4j.configuration.directory=/applications/configuration/best4Automic -Db4j.data.directory=/tmp"
./b4A

Language

The following languages are supported by the modules:

• German
• English

When the best4Automic modules are started, the language used is determined based on the environment. If this is not the desired language, it can be overwritten via an additional file in the configuration directory. To do this, locale.conf must be created. This can contain the properties language and country. The language can be en or de. country must be set to DE, UK or US

language=en
country=DE

best4Automic Setup

There is a graphical interface for creating and editing the connections.

The connections and environments stored in defaults.conf can be edited here.

After adding, editing or deleting a connection or environment, the Save button can be used to save the changes to defaults.conf. If you leave the setup via the Close button and there are unsaved changes, a query appears asking whether the configuration should be saved before closing.

Environments

The connections first require environments as a basis. These can be edited in this area. The Add button opens a dialog in which the environment name and the communication processes can be specified. The environment name may only occur once per best4Automic installation.

Double-clicking on a row in the table opens a dialog for changing the corresponding environment.

Connections

The environments can now be used for the connections. Here too, the Add button opens a dialog. The environment can be selected here via a dropdown. As soon as the environment and client are specified, the recommended name for the connection is generated. This can be changed manually, but will be overwritten again if the environment or client is modified. As soon as the group Specify login data (add) is expanded, the fields User name and Password are mandatory fields.

The connections are usually very similar. Therefore, an existing connection can be duplicated using the Duplicate button and adjusted in the following dialog.

Double-clicking on a row in the table opens a dialog for changing the corresponding connection.

Rest Edition

The Rest Edition is delivered as a WAR archive. To edit the configuration, the WAR archive (Tomcat version) or the zip archive (standalone version) must be unpacked. This contains a directory structure similar to that of the Core Edition (Details). The files in the conf directory are the same. There is another configuration file with the name api.json. Settings for the b4A RESTful API are made there, which are described below.

• rest.fileUploadDirectory: Specifies the directory in which files are stored that are uploaded via the /file/upload endpoint. If the option is not set or the specified directory does not exist, the data directory of the b4A RESTful API installation is used.
• rest.enableServiceEndpoints: Determines whether the XML configuration is loaded and the service endpoints are accessible rest.auth.type: Specifies the authentication method. Can be Basic or Token
• rest.auth.token.secret: Key for generating the token. This must be at least 512 bits long.
• rest.auth.token.issuer: Issuer of the token
• rest.auth.token.ttl: Validity period of the token in minutes
• rest.auth.status.token: Token for sending a message from the Automic Automation Engine using the supplied action and for the two supplied services
• rest.auth.groups.module: Name of the user group to which a user must belong in order to send POST requests against the b4A RESTful API in addition to GET
• rest.auth.groups.info: This user group may only send GET requests against the b4A RESTful API. Requests to the service area are excluded.
• rest.auth.groups.service: User group to send GET and POST requests against the b4A RESTful API. Admin requests and the sending of messages from the Automic Automation Engine are excluded.
• rest.auth.groups.admin: The user group stored here may send all requests against the b4A RESTful API. The only exception is the sending of messages from the Automic Automation Engine
• rest.auth.connection: b4A connection in which authentication and authorization take place. This connection also handles many read operations and changes to the XML configuration by b4A RESTful API administrators.
• rest.module.callback.timeout: Time in milliseconds after which the callback times out without a response rest.service.configuration: Defines the name of the XML vara in which the configuration of the roles and services are stored rest.service.objectExtensions: For the features of the additional input fields and the redirection of PromptSets, additional configurations to objects in the Automic Automation Engine are necessary. The structured documentation of objects is used for this purpose. This option is used to configure the name of the documentation tab in which the b4A RESTful API should search for additional configurations.
• rest.service.userSettings.vault: Defines the name of the storage object in which the user settings are saved. The object must exist when the b4A RESTful API is started.
• rest.service.userSettings.defaultsEntry: Defines the name of the entry within the storage object for the default user settings. The entry must exist and be valid when the b4A RESTful API is started.
• rest.cors.origin: Defines which list of remote servers may access the data of the b4A RESTful API. When using the service portal, the web servers must be stored. This setting is used to support CORS (Cross-Origin Resource Sharing)
• rest.performance.parallel.service: Limits globally for the b4A RESTful API the parallel requests to the Automic Automation Engine for the list of activities. The limit applies across the board for the endpoint /service/tasks/{categoryName} and /service/history. Here you can specify for how many services parallel requests can be sent.
• rest.performance.parallel.instance: Limits globally for the b4A RESTful API the parallel requests to the Automic Automation Engine for the list of activities. The limit applies across the board for the endpoint /service/tasks/{categoryName} and /service/history. Here you can specify for how many instances of services requests can be sent in parallel.
• rest.performance.history.maxResults: Limits the maximum number of statistics records per service that are searched at the /service/history endpoint. The actual number of statistics records returned may vary. Instances that have not yet been deactivated and instances of a service that have a parent but for which the TaskFilter has been set to no_parent are filtered out.
• rest.performance.cache.maxObjects: Limits the number of Automic objects stored in the internal caches
• rest.performance.cache.defaultValidTime: Limits the time in milliseconds that an object remains in the cache
• rest.performance.monitoring.externalCheckInterval: Defines the intervals at which to check for executions of services that are called outside the b4A Service Portal and have none stored as TaskFilter in the configuration. Services that are marked as passive via the isPassive attribute with true automatically have the none TaskFilter. Even if the attribute has been set differently. If such an instance is found, the authorized users in the b4A Service Portal are informed about the start and the execution appears in the overview. Regular checking can significantly increase the load on the Automic Automation Engine. Therefore, another option would be to increase the time to five minutes, for example. Services with a shorter runtime should not be automatically deactivated after the end so that they appear in the list of executions in the b4A Service Portal, even if no check was run between the start and end of the service. The time must be specified in milliseconds.

In addition, further settings can be adjusted in application.properties. In the Tomcat version, this is located in the directory WEB-INF/classes. In the standalone version, it is located in the b4A-rest-launcher.jar, which must be unpacked in advance, in the directory BOOT-INF/classes.

spring.jpa.properties.hibernate.show_sql: Specifies whether the SQL statements should be recorded in the Apache Tomcat® logs

• spring.servlet.multipart.max-file-size: Sets the maximum size of individual files that can be sent via a multipart/form-data request. This limits the size of files that can be sent via the /file/upload endpoint and is set to 10MB by default.
• spring.servlet.multipart.max-request-size: Sets the total request size for a multipart/form-data request, which can theoretically consist of multiple files. This is relevant for the total size of the request via the /file/upload endpoint.

For all changes to configurations, the Apache Tomcat®, or the Java process of the standalone variant, must be restarted so that the changes are applied.

Outsourcing directories

Using the Java Naming and Directory Interface (JNDI), the directories for the jar libraries and the metadata (lib directory), the configuration directory (conf) and the standard data directory (data) can be swapped out.

In Tomcat, for example, a configuration file must be stored under <CATALINA_HOME>/conf/Catalina/<hostname>/<war-name>.xml with the following content:

<context>
  <Environment name="b4j.configuration.directory" value="C:/Path/to/conf/directory/" type="java.lang.String"/>
  <Environment name="b4j.library.directory" value="C:/Path/to/lib/directory/" type="java.lang.String"/>
  <Environment name="b4j.data.directory" value="C:/Path/to/data/directory/" type="java.lang.String"/>
</context>