Command line interface for IBM Business Automation Insights for a server

Use the command-line interface to interact with IBM Business Automation Insights services.

Exit code for commands

The commands return 0 on success or a non-zero value when an error occurred during execution.

Starting the services: bai-start

The bai-start command has the following effects and takes options.
  • Starts the Docker containers that are bound to the Business Automation Insights services.
  • Creates the volumes for the Flink job manager and task manager, and for Elasticsearch and for Kafka by using the values of the FLINK_VOLUME_DIR, ELASTICSEARCH_VOLUME_DIR, and KAFKA_VOLUME_DIR variables, which are specified in the .env file.
--acceptLicense
Each time you run the bai-start command, you must read the license agreement on the Software License Agreement and accept it by specifying the --acceptLicense option. If you omit to pass the --acceptLicense option, the bai-start command fails and a message prompts you to read the license.
--init
  • For a first installation, the --init option is mandatory to create all the necessary certificate, keystore, and truststore that are used by the Business Automation Insights services. With this option, the command also prompts you to enter the machine hostname, user name, and passwords to use the administration services, Kafka, and the Kibana user interface.
  • For further restarts, the --init option is not necessary.
  • You can choose a silent installation by providing the response-file.txt response file. 
    ./bin/bai-start --init < ./response-file.txt
    For more information about the response file, see Installing on a server silently.
--savepoint-paths
If you specify the --savepoint-paths option, the bai-start command starts one or multiple processors from an existing savepoint or from a checkpoint path by using a comma-separated list of savepoint paths by processor name. The specified paths must be absolute and refer to existing directories within the container of the job manager service. To retrieve those paths, run the bai-flink-create-savepoints command, as documented in the Creating savepoints for running processors: bai-flink-create-savepoints section later in this page.
./bin/bai-start [--init] [--savepoint-paths="name1:path1,name2:path2,..."]

Displaying the service logs: bai-logs

The bai-logs displays the log of one or more services that are passed as arguments. By default, the logs are displayed from their beginning, using a follow mode that continuously displays lines and waits for possible new lines to be available. If you pass no argument to the command, the list of all Business Automation Insights services is used.
./bin/bai-logs [service1 service2 service3 ...]

Stopping the services: bai-stop

The bai-stop command stops all Business Automation Insights services and removes the named volumes attached to the Docker containers that are bound to the services. This command also triggers the creation of savepoints for the running processors and synchronizes Kibana configuration files.
./bin/bai-stop

Restarting the services: bai-stop + bai-start

To restart the Business Automation Insights services, run the bai-stop command and then the bai-start command. For further restarts, the --init option is not necessary.

Exporting Kibana saved objects: bai-kibana-export-saved-objects

This command exports the saved objects, such as dashboards, visualizations, and index patterns, from the Kibana global tenant to files in an existing directory. You can import these files from the Kibana user interface.
--path
Use this option to specify an existing directory.
./bin/bai-kibana-export-saved-objects --path=<directory>

Synchronizing Kibana configuration files: bai-kibana-synchronize-config

When you make changes in the Kibana user interface to define or edit roles, role mappings, or action groups, the changes are persisted in a specific Elasticsearch index but not in the YAML files of the ./config/kibana directory. The bai-kibana-synchronize-config command updates these YAML files with the latest changes that are persisted in that specific Elasticsearch index.

To ensure that you always have up-to-date Kibana configuration files whenever you restart Business Automation Insights, run the command after each modification you make in the Kibana user interface.
./bin/bai-kibana-synchronize-config

Creating savepoints for running processors: bai-flink-create-savepoints

This command triggers the creation of savepoints for running processors. On completion, it displays the paths that were generated for each processor. These paths are absolute and refer to existing directories within the container of the job manager service.
--stop
If you specify the --stop option, the processors are stopped after the savepoints are triggered.
./bin/bai-flink-create-savepoints [--stop]
Checkpoints
Checkpoints are written to the _volume_/flink/checkpoints/_flink_processor_id_ directory. In this path, the _volume_ placeholder takes the value of the FLINK_VOLUME_DIR variable in the .env file and the _flink_processor_id_ placeholder is the processor identifier that created the savepoint or checkpoint. The <bai-sn-installdir>/processors/running_processors_info file contains the processor identifier by processor name for all the processors that were successfully submitted.

Example: To start from a checkpoint for an ODM processor that was submitted with _flink_processor_id_ 37e7559a707bbbf94e55d0a7960fb161 and created in directory <bai-sn-installdir>/volumes/flink/checkpoints/37e7559a707bbbf94e55d0a7960fb161/chk-320, you specify bai-odm:/mnt/pv/checkpoints/37e7559a707bbbf94e55d0a7960fb161/chk-320 by using option --savepoint-paths.

Savepoints
Savepoints are written to the _volume_/flink/savepoints/dba/_processor_name_ directory. The _volume_ placeholder takes the value of the FLINK_VOLUME_DIR variable in the .env file and _processor_name_ is the name of the processor for which a savepoint was triggered.

Example: To start from a savepoint that was created for the BPMN processor in directory <bai-sn-installdir>/volumes/flink/savepoints/dba/bai-bpmn/savepoint-2e1b81-4f1797568a0d, you specify bai-bpmn:/mnt/pv/savepoints/dba/bai-bpmn/savepoint-2e1b81-4f1797568a0d by using option --savepoint-paths. By default, if the --savepoint-paths option is not specified, the bai-start command restarts from the savepoints that were created by the bai-stop command for each running processor.