Operation

The best4Automic modules are all based on the best4java framework. They offer the same, uniform handling via this framework. The framework offers sufficient flexibility so that the modules can provide variations in handling according to their functionality.

Once the configuration is complete, the modules can be started directly. The best4Automic distribution provides start scripts for this. These are located in the bin subdirectory. To start best4Automic modules on a UNIX system, the script b4A can be used. The scripts must be called in the bin directory as the working directory. The following examples assume that the bin subdirectory of the best4Automic distribution is the current working directory

./b4A te.Read --help

On Windows systems, use the script b4A.bat.

.\b4A.bat te.Read --help

Or alternatively the PowerShell script.

.\b4A.ps1 te.Read --help

In addition to starting b4A modules, the start scripts also provide other functions that are determined using the --help parameter.

> ./b4A --help



--help shows this output
--version shows the version of best4Automic
--modules shows a list of available b4A modules
--shell starts the best4Automic shell
--dashboard starts the best4Automic dashboard
--setup Here the b4A connections can be configured in a graphical interface.
--server starts the best4Automic server
--custom-solution An interface for customer-specific extensions

Further information on the subject of custom solutions can be found in the b4A online documentation.

The --modules parameter can be used to display a list of all available modules. This can also be obtained using the graphical b4A Dashboard.

More information on the --server option can be found in the section and further details on the --shell option can be found in the section.

Each of the b4A Module can be started as a command line program or with a graphical user interface. The parameters for a module are the same, regardless of the variant used. This functionality is realized by a framework on which all modules are based. The functionality of the framework that is important for best4Automic is described below.

Configuration mechanism

best4java is a library that, in addition to many extensions for the Java Runtime Environment, provides a framework that makes it possible to write programs that have both a graphical and a command line-based user interface.

A configuration mechanism is provided based on this framework. This mechanism is used and extended by the best4Automic modules.

When a module is started, the values for the configuration parameters are read from the following sources in the specified order:

1. file defaults.conf
2. file <module>.conf (<module> is to be replaced by the name of the respective module)
3. command line parameters
4. input in the graphical user interface (if used)

Finally, the specified values are checked based on the parameter type. The framework comes with some predefined types. These are extended by Automic-specific types.

Standard parameter types

• Boolean value
• Character string
• Password
• numbers
• Constant from a predefined list
• List of constants
• Directory
• File name
• Date or timestamp

Automatic parameter types

best4Automic Object lists

• List of object types
• List of object types including links
• List of startable object types
• List of object attributes that can be searched for
• Activity status (one or more) Automic folder

The best4Automic object lists are special text files that can be used as input by some best4Automic modules. The object sets to be processed are read from the files. An object filter can be specified per line, of which there are four types:

<name pattern> Examples: B4A.*, B4A.JOBP.TEST

<object type>:<name pattern>

Examples: JOBS:B4A.*, JOBP:B4A.*

FOLDER:<folder name>

Examples: FOLDER:B4A_OBJECTS, FOLDER:B4A_TESTS

<object type>:<name pattern>;<folder name>;<title>

Examples: JOBS:B4A.JOBS.NEW.1;B4A.TESTS/SAMPLES;This is a b4A job

The fourth variant is used when modules generate b4A object lists as output. These files can also be used as input. However, the object title contained is not used as a criterion for the selection. When used as an input file, duplicate entries in the file are automatically ignored.

User interfaces

Based on the configuration mechanism, the best4Automic modules provide a command line interface and a graphical user interface. Which of the interfaces is used can be determined via a command line option. If a module is called without options, the command line interface is used. The graphical interface can be activated via the -X option (long name --gui).

Command line interface

The command line version of the best4Automic modules behaves as known from many UNIX programs. The options all have a long name, which is specified on the command line with a leading --. Some also have a short name consisting of a single letter, which can be used with a leading -.

Except for the boolean options, all options have an additional parameter, which is specified separated by one or more spaces. Example:

./b4A info.Search -C B4A-1 --folder TESTS

To get the names and descriptions of all available options, each module has the option --help (short name -h).

> ./b4A info.Agent --help
## General ##
-h, --help Show this information
                            - Default: false
-X, --gui Use a graphical user interface instead of command line options
                            - Default: false
## Access data ##
-C, --connection * Defines the b4A connection consisting of server, port, client and optional access data
                            - Valid values:
-u, --username User
-d, --department Department of the user
-w, --password Password for the user
-W, --password-file A file containing the user's password



## Output ##
--csv-file * File name for the output in CSV format
                            - Default:
--csv-mode The 'overwrite' mode overwrites existing files while the 'append' mode appends new data to existing files.
                              - Default: overwrite
                              - Valid values: overwrite, append
## Advanced ##
--log-variants Defines the log variants to be activated
                            - Default: PROGRESS, REPORT
                            - Valid values: REPORT, PROGRESS
--log-flags Defines a set of options for logging
                            - Default: TIMESTAMP
                            - Valid values: TIMESTAMP, SESSION, TIMEKEEPING, MONOCHROME
--log-levels Log level
                            - Default: ERROR, WARNING, INFO
                            - Valid values: ERROR, DEBUG, INFO, WARNING, TRACE, JAVA_API, DATASTREAM
--log-datastream-prefix All outputs for the DATASTREAM log level are prefixed with this character string
                            - Default: @B4A_STREAM@
--log-datastream-separator The columns of the DATASTREAM log level are separated by this character string
                            - Default: §§
--log-error-mode Controls how the modules react to errors. By default, the modules only terminate in the event of fatal errors (mode 'never')
                            - Default: never
                            - Valid values: never, on-first-error, on-progress-finished
--log-encoding Defines the coding for reading and writing files
--encryption-key * Defines the secret for password encryption
                            - Default: server
                            - Valid values: server, ae-script

Options that are mandatory have an asterisk after the long name. Depending on the default values, options may or may not be mandatory.

A default value is specified for some options. This is a default value that is predefined either by the module itself or by a configuration file. The defaults can be overwritten by specifying the option when it is called. Depending on the option, only certain values may be permitted. This is indicated in the cases by the entry Valid values. The values are case-sensitive.

Boolean options work like a toggle button. Specifying a Boolean option changes the current value to the other value. If the default value of a boolean option is false, then specifying this option would set the value to true. If the default value is true, then the value would be set to false when the option is specified.

Graphical user interface

To use the graphical user interface of a best4Automic module, start it with the option --gui (short name -X).

./b4A te.Read -X

The options are divided into the same groups as in the command line interface. These are represented by different tabs. Many of the parameters are available for several modules. Based on these, the following describes how to operate the graphical user interface. The concept is used by all modules and can also be applied to options not explained here. Details can be found in the following sections on the individual modules.

Mandatory options are highlighted here with bold text. Depending on how other options are set, this status may change. This is displayed accordingly in the user interface.

To obtain information on the individual options, click on the question mark (?) directly next to the name of the option. Short explanations of the respective option are displayed in the notification window.

Once the configuration of the module is complete, the module can be started using the Execute button. This button has a menu that can be opened using the arrow. This can be used to select an action other than start. The alternative actions take the settings made and generate certain formats from them.

*Create command line The action creates a command line call for b4A that uses the same settings.

Create configuration The action takes the settings and creates a configuration that can either be used with the b4A actions or written to a configuration file.

Create JSON

The action creates a JSON snippet from the settings that can be used with the b4A action, which can start b4A modules via the b4A RESTful API.

All available categories and modules are displayed in the interface. If a restricted license is used (only some categories have been licensed), the modules for which no license is available are marked with a small lock behind the module name. These modules can be opened and viewed. Execution is not possible.

Access data

As with Automic Web Interface, modules that open one or more connections to an Automic mandate require the connection data and access data of the user. These are requested on the Access data tab.

The available connections are read from the configuration file defaults.conf (Details). The options User, Department and Password must be filled in in the same way as for Automic Web Interface. If a connection is selected that contains access data, the additional data specified will be ignored, i.e. those of the connection will be preferred.

Input data

Input: Objects

note

Please note that folders are excluded when using date filters (modification, creation or use), as the information is not available for these objects.

Many of the best4Automic modules work with sets of Automic objects. The modules can determine these sets in various ways:

• Object search: similar to Automic Web Interface, search parameters can be defined to determine the desired objects.

• Folder scanner: The method runs through the tree recursively from a defined folder and can limit the number of objects using a number of filters. Links can also be found. The options for filtering based on the content of the objects are not supported by this technique. This mode is the slowest overall, but has the advantage that there are no restrictions regarding the number of objects per folder, which is limited in the classic search.

• b4A object lists: With this method, objects are searched for using object name patterns.

• b4A-Object-Variable: In this mode, the objects are read from the keywords of the entries in variable objects. Several variable objects can be used at once with one object name pattern.

Which method is used can be defined on the Input tab with the Search mode option. The Object search mode offers the most filter criteria.

Group: Input

Search mode (input-mode)

Defines the way to find objects

Possible values: folder-scanner (scan), object-search (search), b4A-object-list (file), b4A-object-variable (vara)

Input file (input)

Input file for the b4A object list search mode

Object types (types)

Defines the object types to be examined

Possible values: Calendar (CALE), Notification (CALL), RA-Solution (CITC), Client (CLNT), Code-Table (CODE), Connection (CONN), Cockpit (CPIT), Dashboard (DASH), Documentation (DOCU), Event (EVNT), Filter (FILTER), Folder (FOLD), Agent (HOST), Host Group (HOSTG), Agent/client assignment (HSTA), File transfer (JOBF), Job group (JOBG), Include (JOBI), Job (JOBS), Workflow (JOBP), RemoteTaskManager (JOBQ), Link (LINK), Login (LOGIN), Schedule (JSCH), Script (SCRI), Synchronization (SYNC), Timezone (TZ), User (USER), Group (USRG), Variable (VARA), Stylesheet (XSL), PromptSet (PRPT), Queue (QUEUE), Storage (STORE), Service Level Objective (SLO), Period (PERIOD)

Object name (name)

Object names must correspond to the specified filter

Folder (folder)

Search in the specified folder

Ignore missing folders (folder-ignore-missing) If the option is set, folders from the 'Folder' option that do not exist are ignored. The default behavior is to terminate the module with an error.

Recursive (recursive)

Search in subfolders

Include links (include-links)

Search additionally for links to objects

Group: Text search

Text search (text)

Text that is searched for in several attributes

Search in (search-in)

Attributes that are searched for the specified text

Search in variable (search-in-vara)

Defines which fields of a variable are to be searched in

Variable data types (search-in-vara-type)

Data types of variables to be searched.

Group: Date restrictions

Date definition (search-date)

Defines the type of date selection for the search

Start timestamp (begin)

Start of the interval in the format YYYY-MM-DD HH:MM:SS

End timestamp (end) End of the interval in the format YYYY-MM-DD HH:MM:SS

User name pattern (date-user)

Pattern of the user who created, edited or used the object

Group: Extended

b4A exclude list (file) (exclude-list)

A b4A object file that contains patterns of object names to be ignored

b4A Exclude list (variable) (exclude-vara)

A b4A object variable that contains patterns of object names to be ignored

Ignore errors when reading the b4A exclusion list (exclude-ignore)

If the option is set, all errors when reading the b4A exclusion list are ignored

Traverse workflows (traverse-flows)

Includes all tasks from flowcharts (recursive)

analyze scripts (parse-processes)

Search for object references in scripts

For workflows, there is also the option Traverse workflows. If this is set, all objects included in the workflows are included recursively. In this case, recursive means that the tasks of sub-workflows are also included.

Furthermore, an option User name pattern is provided in the search in connection with the date definition. This allows the objects to be additionally filtered according to the user name that created, changed or used the objects.

The options b4A-exclude-list (file) (exclude-list) and b4A-exclude-list (variable) (exclude-vara) can be used to specify a file or variable that contains best4Automic object lists. The objects defined in the lists are excluded during processing. It is possible to specify either only one source or both. In the latter case, the lists are merged. If errors are to be ignored when attempting to read these sources, this can be done using the option Ignore errors when reading the b4A exclusion list (exclude-ignore).

The option analyze scripts (--parse-processes) can also include objects that are referenced in the scripts of the objects found. The Automic Automation Engine script functions are searched for object names. If script variables are used in the functions, a simple resolution is attempted. Nested variants are also supported. The resolution does not work for variables that are not defined in the script itself, for example by inheritance.

Example of a simple resolution:

set &object# = "B4A.JOBS.TEST"
:set &ret# = activate_uc_object( &object# )

Example of a nested resolution:

:set &suffix# = "TEST"
:set &object# = "B4A.JOBS.&suffix#"
:set &ret# = activate_uc_object( &object# )

Input: Activities

Another group of modules does not work with Automic objects, but with activities. For these modules, there are other options for searching for the relevant entries in the Input group. The following criteria can be specified to select the desired activities:

• Object name: A pattern for the name of the objects
• NOT: Negates the pattern for object names
• RunID: Restricts the selection to a single activity with the specified RunID
• Object types: Selection of allowed object types
• User: Pattern for the user name
• Regular expression for the status text: The status text of the activities must match the specified expression
• Age in days: Defines the minimum age of the activities to be considered Only top activities: If the option is set, then only the top activities in the hierarchy are considered Active, wait, cancel and OK status: Selects all permitted statuses for the activities
• b4A exclusion list (file), b4A exclusion list (variable), * Ignore errors when reading the b4A exclusion list*: see here

Group: Input

Search mode (input-mode)

Defines the way to find objects

Possible values: folder-scanner (scan), object-search (search), b4A-object-list (file), b4A-object-variable (vara)

Object types (types)

Defines the object types to be examined

Possible values: Notification (CALL), Event (EVNT), File transfer (JOBF), Job group (JOBG), Job (JOBS), Workflow (JOBP), RemoteTaskManager (JOBQ), Schedule (JSCH), Script (SCRI)

Object name (name)

Object names must correspond to the specified filter

Folder (folder)

Search in the specified folder

Ignore missing folders (folder-ignore-missing) If the option is set, folders from the 'Folder' option that do not exist are ignored. The default behavior is to terminate the module with an error.

Recursive (recursive)

Search in subfolders

Include links (include-links)

Search additionally for links to objects

Group: Text search

Text search (text)

Text that is searched for in several attributes

Search in (search-in)

Attributes that are searched for the specified text

Search in variable (search-in-vara)

Defines which fields of a variable are to be searched in

Variable data types (search-in-vara-type)

Data types of variables to be searched.

Group: Date restrictions

Date definition (search-date)

Defines the type of date selection for the search

Start timestamp (begin)

Start of the interval in the format YYYY-MM-DD HH:MM:SS

End timestamp (end) End of the interval in the format YYYY-MM-DD HH:MM:SS

User name pattern (date-user)

Pattern of the user who created, edited or used the object

Group: Advanced

b4A exclude list (file) (exclude-list)

A b4A object file that contains patterns of object names to be ignored

b4A Exclude list (variable) (exclude-vara)

A b4A object variable that contains patterns of object names to be ignored

Ignore errors when reading the b4A exclusion list (exclude-ignore)

If the option is set, all errors when reading the b4A exclusion list are ignored

Traverse workflows (traverse-flows)

Includes all tasks from flowcharts (recursive)

analyze scripts (parse-processes)

Search for object references in scripts

Check the prerequisites

Some modules require certain configurations, which are checked after the connection has been established and the user has successfully logged in. If these are not fulfilled, the module aborts the process. In most cases, the configurations are settings in the client. These include, for example

• Usage search in scripts
• Version management
• Access to the transport case
• XML documentation

The last example shows a property that is checked by the mc.DocumentationEdit module. However, this is only carried out if the XML documentation is accessed. This shows that some prerequisites are only required when using certain module capabilities.

Automic folder selection

Many operations can be restricted to a folder and its subfolders. The folder can be selected in the modules via a selection dialog if the corresponding configuration has been made (Details).

If the necessary configuration is not available, the folder can be entered manually. Folders with or without a leading client folder can be used.

0010/B4A@TESTS/FOLDER.1/SUBFOLDER.1

or

B4A@TESTS/FOLDER.1/SUBFOLDER.1

Test mode

Some of the modules offer a test mode. If this mode is activated, all write operations in the Automic Automation Engine are not carried out. The module sequence is processed as completely as possible.

Output

The results of some modules can be saved in a file in CSV format. There are some options that influence the output. The name of the output file is predefined, but can be changed as required by adjusting the output file option. The default value saves the data in the data directory of the best4Automic installation.

The CSV file mode option defines whether existing files are to be overwritten or the new data appended.

It is also possible to display the data in a table in the graphical user interface using the Show tabular view option.

Many modules offer the option Save b4A object list. This is used to save a best4Automic object list in a file that contains all the objects that were processed when a module was run. If the option Save only successfully processed objects is also set, the object is only saved if processing was successful without errors. If the file already exists, it will be overwritten. This can be prevented with the option Append processed objects to existing file. Duplicates are not included in the file with any of the variants.

The same function is also available for a variable object. The list of objects is saved in a variable object. The option Save b4A object variable is required for this.

Group: Output

Save b4A object list (save-objects)

Saves the processed objects in a b4A object file

Save b4A object variable (save-objects-vara)

Saves the processed objects in a b4A object variable

Save only successfully processed objects (save-success-only)

An object is only written to the file if the processing was successful

Append processed objects to existing file/variable (save-append) If the file/variable already exists, new entries are appended.

Output file (csv-file)

File name for the output in CSV format

CSV file mode (csv-mode)

The 'overwrite' mode overwrites existing files while the 'append' mode appends new data to existing files. Possible values: overwrite (overwrite), append (append)

Summary (summary)

Activates the creation of a summary in a file in CSV format

File name for the summary (summary-file)

Defines the file name for the summary of the analysis

b4A Dashboard

The b4A Dashboard, which is only available in the graphical version, provides an overview of the available modules. This can also be used to start the individual modules in graphical mode. This can be started from the bin directory of the best4Automic installation with the following command on UNIX systems

./b4A

and with the command

.\b4A.bat

and

.\b4A.ps1

on Microsoft Windows compatible systems.

To start the via the , one of the scripts b4A or b4A.bat is used, depending on the platform. If windows.powershell = true is set in defaults.conf, b4A.ps1 is used instead of b4A.bat.

Server

The best4Automic server offers the option of starting several modules via one process. This makes it possible to save resources and start the modules faster in environments in which several modules are often started in parallel or in which a large number of modules are started in a short period of time, as the Java runtime environment only has to be started once.

To start modules in server mode, --server must be specified as the first option at startup (before the module name). If the server process is not yet running, it will be started automatically.

./b4A --server info.Search -C B4A-1 --name "B4A.*"

In the above example, the is started first if it is not yet running and then the module is executed. If a server process is already running, the start of the module is sent to the server. The report of the started module is sent from the server to the client. If the server mode is used in automation, for example, the reports of the modules will still be visible in the executing job.

If a server is running, modules can still be started without using the server. To do this, simply remove the --server option.

In the default configuration, the listens on the local network interface (localhost) and uses port 62441. This can be adjusted by placing a file named server.json in JSON format in the configuration directory.

{
  "host" : "localhost",
  "port" : 62441
}

This mode only works for the command line version of the modules. The graphical mode cannot be used.

In addition to starting modules, the understands a few internal commands. These are specified in the command line instead of the b4A module.

./b4A --server <internal command>

PING

A running responds to this command with PONG. This command can be used to ensure that an instance is running and functioning.

EXIT

This command is answered by the with OK. The server then exits.

CONNECT <b4A connection> Sets a standard connection that is used by all modules that are started via the server. Modules that use more than one connection are not included. When starting the modules, the connection option can then be omitted, as this is replaced by the default connection. The command is answered with OK if the connection could be opened successfully. Otherwise, the response is FAILED.

DISCONNECT

Closes the standard connection if one is defined. The connection option must then be specified again for all b4A modules. The command is answered with an OK.

VERSION

Outputs the version number of the

Shell

The can be started with the --shell option. This is a simple shell with which all best4Automic modules can be started. Two important functions are made available via this interface. These are:

• Starting multiple modules with an open connection. The b4A Shell command connect can be used to establish a connection that can be used by all modules started in the shell.
• The calls of the individual shell commands and b4A Module can also be written to a file that can be transferred to the b4A Shell via standard input.

Example for the use of the b4A Shell:

> ./b4A --shell
# best4Automic Shell 4.3.0



help - shows this output
quit, exit - exits the b4A shell
connect <connection> - connects to the specified b4A connection
disconnect - closes the current connection
<b4A module> <arguments> - starts a best4Automic module



 > connect B4A-1
== Connect with B4A-1 ==
== Login to client 10 as WRITER/B4A ==
Connect withB4A-1
B4A-1 > info.Search --folder B4A.TESTS/REPLACE_AGENT
best4Automic 3.0.0
List objects on
[2017-01-15 19:23:49.489] 0010/B4A.TESTS/REPLACE_AGENT/REPLACE_AGENT.EVNT.FILE.1
[2017-01-15 19:23:49.493] 0010/B4A.TESTS/REPLACE_AGENT/REPLACE_AGENT.JOBF.1
[2017-01-15 19:23:49.495] 0010/B4A.TESTS/REPLACE_AGENT/REPLACE_AGENT.JOBS.1
successful: 3, failed: 0, ignored: 0



B4A-1 > disconnect
[2017-01-15 19:23:57.708] Connection to AE10(0010) closed
Connection B4A-1 closed
 >

If a file shell.b4a with the following content is created, it can be transferred to the best4Automic shell.

connect B4A-1
info.Search --folder B4A.TESTS/REPLACE_AGENT
info.Search --folder B4A.TESTS/REPORTS
te.Read --name "B4A.*" --days 30
disconnect

To do this, the best4Automic shell must be started as follows. This then executes all commands one after the other.

> ./b4A --shell < shell.b4a