IBM Business Automation Insights

https://www.ibm.com/docs/en/bai
Admin
IBM Business Automation Insights is a business automation platform that provides insights and...
Tokens:81,446
Snippets:580
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### Log in to OC Client

Source: https://www.ibm.com/docs/en/bai/25.0_topic=upgrade-backing-up-your-custom-resources

This command logs you into the target cluster using the OC client. It requires the cluster IP, port, and administrator credentials. Ensure you have the OC client installed and configured.

```bash
oc login https://<CLUSTERIP>:<port> -u <ADMINISTRATOR>
```

--------------------------------

### Ingress Definition Example - JSON

Source: https://www.ibm.com/docs/en/bai/23.0_topic=processing-defining-ingress

This JSON snippet demonstrates the structure for defining an ingress, including Kafka topic, timestamp path, event filtering (selector), and event transformation. It also shows an example egress definition.

```json
{
    "ingresses": [
        {
            "uid": "I0001",
            "type": "kafka",
            "topic": "icp4ba-bai-ingress",
            "timestampPath": {
                "type": "jslt-inline",
                "expression": ".meta.timestamp"
            },
            "selector": {
                "type": "jslt-inline",
                "expression": "test(.type, \"COMPLETED\")"
            },
            "transformer": {
                "type": "jslt-file",
                "filename": "transform-ingress.jslt"
            }
        }
    ],
    "egresses": [
        {
            "uid": "E0001",
            "type": "kafka",
            "name": "kafka-bai-egress",
            "topic": "icp4ba-bai-egress",
            "enabled": true
        }
    ]
}
```

--------------------------------

### Download the CLI archive using curl

Source: https://www.ibm.com/docs/en/bai/25.0_topic=walkthrough-using-management-cli

This command downloads the BAI management CLI archive using curl. It requires the management URL and authentication credentials. Ensure curl version 7 or later is installed.

```shell
curl -k https://${MANAGEMENT_URL}/cli --header 'Authorization: Basic X' -o ${DESTINATION_DIR}/bai-command.tar.gz
```

--------------------------------

### Example Configuration File Structure

Source: https://www.ibm.com/docs/en/bai/23.0_topic=sources-processing-configuration

This illustrates the expected directory structure for configuration files referenced by processing-conf.json. It includes the main configuration file, custom Elasticsearch mappings, and JSLT scripts for event selection and transformation.

```text
<configuration directory>
   |-- processing-conf.json
   |-- orders-mapping.json => custom ElasticSearch mapping
   |-- event-selector.jslt => custom jslt, referenced by processing-conf.json
   +-- event-transformer.jslt => another custom jslt, referenced by processing-conf.json
```

--------------------------------

### Delete and Re-create BAI Setup Job (Bash)

Source: https://www.ibm.com/docs/en/bai/23.0_topic=troubleshooting-apache-flink-jobs

This snippet provides the commands to delete existing BAI setup job pods and then re-create the setup job. This is a solution for BAI job pods stuck in Init:0/1 status, often caused by issues with the setup job itself. It uses `oc` CLI and `jq` for JSON manipulation.

```bash
oc delete pod <custom_resource_name>-bai-setup-aaaaa
oc delete pod <custom_resource_name>-bai-setup-bbbbb
oc delete pod <custom_resource_name>-bai-setup-ccccc
oc delete pod <custom_resource_name>-bai-setup-ddddd

oc get job <custom_resource_name>-bai-setup -o json | jq "del(.spec.selector)" | jq "del(.spec.template.metadata.labels)" | oc replace --force -f -
```

--------------------------------

### Backup Business Automation Insights Multi-patterns

Source: https://www.ibm.com/docs/en/bai/25.0_topic=upgrade-backing-up-your-custom-resources

This command backs up Business Automation Insights multi-patterns by exporting the 'bai' engine definition to a YAML file. It requires kubectl to be installed and configured to access the cluster. The output is saved to 'ibm-bai-backup-cr.yaml' in the specified project.

```bash
kubectl get insightsengine bai -n <project_name> -o yaml > ibm-bai-backup-cr.yaml
```

--------------------------------

### Process Started Time Series Attributes Example (JSON)

Source: https://www.ibm.com/docs/en/bai/23.0_topic=formats-process-time-series-format

This JSON object represents the attributes of a 'PROCESS_STARTED' event in a time series. It includes details such as event ID, offset, partition, version, timestamp, system IDs, process identifiers, and state. This data can be used for monitoring, auditing, and analyzing process execution flows.

```json
{
            "id": "I21182bb87a319361792162189",
            "offset": 61253,
            "partition": 0,
            "version": "1.0.0",
            "type": "PROCESS_STARTED",
            "timestamp": "2018-05-24T03:18:38.379-05:00",
            "bpmSystemId": "7cf5b53b-6c76-487c-93e5-25361b46d01d",
            "bpmCellName": "bpmCell01",
            "processId": "aba2ab57-97b0-4ff4-be70-08cb69dc03ca",
            "processVersionId": "2064.b265633f-17b0-4204-adf5-4973c81959be",
            "processApplicationId": "629954f3-3be8-4f9b-ae78-10d8e58392c0",
            "processApplicationSnapshotName": "",
            "processApplicationVersionId": "2064.b265633f-17b0-4204-adf5-4973c81959be",
            "processApplicationName": "Tracking 2",
            "processInstanceId": "aba2ab57-97b0-4ff4-be70-08cb69dc03ca.7cf5b53b-6c76-487c-93e5-25361b46d01d.1310",
            "shortProcessInstanceId": "1310",
            "sequenceId": 1,
            "createdHighResolutionTimestamp": 56152534230,
            "processName": "Process 2-1",
            "processSnapshotName": "",
            "processState": "Active",
            "trace-id": "1b944420-1143-46a4-b30f-d6a269db3a4c",
            "span-id": "bf5a-a20892c20275"
}
```

--------------------------------

### Display IBM BAi Service Status and Version

Source: https://www.ibm.com/docs/en/bai/25.0_topic=walkthrough-using-management-cli

Retrieves and displays the current status and version information for the IBM Business Automation Insights service. This command has no input parameters.

```bash
management-cli env info
```

--------------------------------

### Import Processing Configuration for IBM BAi

Source: https://www.ibm.com/docs/en/bai/25.0_topic=walkthrough-using-management-cli

Imports a processing configuration for either Operational Decision Manager or Automation Decision Services. Requires the configuration name and the path to the directory containing the configuration files. The path should point to the 'dba' subdirectory.

```bash
management-cli processing-conf import --name="dba/bai-odm" --directory=<directory>/dba
```

```bash
management-cli processing-conf import --name="dba/bai-ads" --directory=<directory>/dba
```

--------------------------------

### Log in to IBM BAi CLI

Source: https://www.ibm.com/docs/en/bai/25.0_topic=walkthrough-using-management-cli

Authenticates with the IBM Business Automation Insights management environment. Requires the management URL as an input parameter. Avoids exposing credentials in shell history.

```bash
management-cli env login --management-url=${MANAGEMENT_URL}
```

--------------------------------

### Unpack the CLI archive using tar

Source: https://www.ibm.com/docs/en/bai/25.0_topic=walkthrough-using-management-cli

This command unpacks the downloaded BAI management CLI archive using the tar utility. It assumes the archive has been downloaded to the specified destination directory. Bash 3.2 or later is recommended.

```shell
tar xvf ${DESTINATION_DIR}/bai-command.tar.gz
```

--------------------------------

### Log out from IBM BAi CLI

Source: https://www.ibm.com/docs/en/bai/25.0_topic=walkthrough-using-management-cli

Logs out the current session from the IBM Business Automation Insights management environment. This command has no input parameters.

```bash
management-cli env logout
```

--------------------------------

### Monitoring Source Fields with Label Example

Source: https://www.ibm.com/docs/en/bai/25.0_topic=configuration-monitoring-source-odm

Illustrates how to configure monitoring source fields, specifying a mandatory field for data retrieval and an optional field to serve as a label in Business Performance Center. Requires at least one field for data aggregation.

```yaml
monitoring_source_fields:
  - field: "item_id.keyword"
    label_field: "item_name"
```

--------------------------------

### Export Processing Configuration for IBM BAi

Source: https://www.ibm.com/docs/en/bai/25.0_topic=walkthrough-using-management-cli

Exports the processing configuration for either Operational Decision Manager or Automation Decision Services. Requires the configuration name and an output directory. The specific name depends on the service being configured.

```bash
management-cli processing-conf export --name="dba/bai-odm" --directory=<directory>
```

```bash
management-cli processing-conf export --name="dba/bai-ads" --directory=<directory>
```

--------------------------------

### Define Monitoring Source Fields for Data Aggregation

Source: https://www.ibm.com/docs/en/bai/23.0_topic=sources-processing-configuration

This JSON example illustrates configuring the `fields` attribute for a monitoring source. It includes a primary field (`item_id.keyword`) for unique identification and an optional `labelField` (`item_name`) for display. It also shows how to include an `item_version` field to differentiate multiple versions of the same item.

```json
"fields": [
        {
            "field": "item_id.keyword",
            "labelField": "item_name"
        },
        {
            "field": "item_version"
        }
      ]
```

--------------------------------

### Deploy Processing Application with Savepoint CLI

Source: https://www.ibm.com/docs/en/bai/23.0_topic=sources-managing-processing-application

Deploys a processing application, optionally starting from a specified savepoint. This allows for resuming processing from a previous state, ensuring data consistency and minimizing downtime. Requires the savepoint path.

```bash
management-cli processing-app deploy --savepoint-path=<savepoint-path>
```

--------------------------------

### Create and Deploy Processing Application with CLI

Source: https://www.ibm.com/docs/en/bai/23.0_topic=processing-custom-operations

Demonstrates the command-line interface (CLI) commands to manage a processing application. This includes creating a new application, importing its configuration from a directory, and deploying it for execution.

```bash
management-cli processing-app create --name="test-app"

```

```bash
management-cli processing-conf import --name="test-app" --directory="./test-app"

```

```bash
management-cli processing-app deploy --name="test-app"

```

--------------------------------

### Monitor Pod Status with oc get pods

Source: https://www.ibm.com/docs/en/bai/23.0_topic=specifics-updating-your-business-automation-insights-custom-resource

This command monitors the status of all pods in real-time, displaying updates as they occur. The `-w` flag enables watch mode. This is essential for verifying that all automation containers have successfully started and are in a 'Running' state.

```bash
oc get pods -w
```

--------------------------------

### Example of Tracked Fields with Various Data Types

Source: https://www.ibm.com/docs/en/bai/23.0_topic=formats-tracked-field-format-in-time-series

This example showcases a populated `trackedFields` object, illustrating how different data types are represented. It includes string, dateTime, integer, and boolean types, demonstrating the expected format for each.

```json
"trackedFields": {
        "claimId.string": "9.152.116.48.1527774200016.1579group5",
        "policyId.string": "1527774275173",
        "lossDate.dateTime": "1998-12-24T12:59:38.00Z",
        "repairQuotationCost.integer": 1000,
        "providerId.string": "ThirdProvider6",
        "thirdPartyPolicyId.string": "ThirdPolicy750",
        "thirdPartyClaimId.string": "TP12435-AA-101",
        "thirdPartyAccepted.boolean": true
    }
```

--------------------------------

### Restart bai-setup Kubernetes Job (Kubernetes/Shell)

Source: https://www.ibm.com/docs/en/bai/23.0_topic=troubleshooting-setup

This command restarts the `bai-setup` Kubernetes job, which in turn restarts the associated pods. It is useful when `bai-setup` pods are in an error state and the retry limit has been reached. The command uses `oc` and `jq` to manipulate the job's JSON definition and replace it, forcing a restart.

```shell
oc get job <custom_resource_name>-bai-setup -o json | jq 'del(.spec.selector)' | jq 'del(.spec.template.metadata.labels)' | oc replace --force -f -
```

--------------------------------

### Create Processing Application using management-cli

Source: https://www.ibm.com/docs/en/bai/23.0_topic=processing-duration-operations

This command creates a new processing application named 'test-app' using the management-cli tool. This is the first step in setting up the application before importing configuration.

```bash
management-cli processing-app create --name="test-app"
```

--------------------------------

### Example of BPMN Raw Event Attributes

Source: https://www.ibm.com/docs/en/bai/23.0_topic=formats-bpmn-raw-event

This is a JSON example illustrating the raw event attributes for BPMN processes or activities. It demonstrates the structure and common fields, including context and trace information, used by IBM Business Automation Insights for event processing.

```json
{
  "event_type": "bpmn_activity",
  "timestamp": "2024-05-23T10:00:00Z",
  "rootContainerId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "containerId": "f0e9d8c7-b6a5-4321-0fed-cba987654321",
  "processInstanceId": "1a2b3c4d-5e6f-7890-1234-567890abcdef",
  "activityInstanceId": "98765432-10fe-dcba-9876-543210fedcba",
  "activityType": "ServiceTask",
  "activityName": "InvokePaymentGateway",
  "duration": 500,
  "state": "COMPLETED",
  "context": {
    "trace-id": "abc123xyz789",
    "correlation-id": "def456uvw012"
  }
}
```

--------------------------------

### Stopping Processing Jobs

Source: https://www.ibm.com/docs/en/bai/23.0_topic=sources-managing-processing-application

Guide on how to stop a running Flink job (processing job) associated with your deployed application.

```APIDOC
## How to stop the processing

Guide on how to stop a running Flink job (processing job) associated with your deployed application.

1. **List jobs to identify the target job:**
   Find the job matching your application name with a `running` state.
   ```
   management-cli processing-jobs list
   ```

2. **Cancel the job using its ID:**
   Once identified, use the job ID to cancel it. This operation is synchronous.
   ```
   management-cli processing-jobs cancel --job-id=<job-id>
   ```

3. **Verify job status:**
   Run the list command again to confirm the job's state is now `CANCELED`.
```

--------------------------------

### Consume Processed Events using management-cli Kafka Consumer

Source: https://www.ibm.com/docs/en/bai/23.0_topic=processing-duration-operations

This command starts a Kafka consumer to listen for and display JSON messages from the 'icp4ba-bai-time-elapsed-egress' topic. This is used to monitor the output of the duration operation.

```bash
management-cli kafka consumer-json --topic=icp4ba-bai-time-elapsed-egress
```

--------------------------------

### Deploy Processing Application using management-cli

Source: https://www.ibm.com/docs/en/bai/23.0_topic=application-creating-processing

Deploys the processing application, which includes creating or updating Elasticsearch indices, Kafka topics, and monitoring sources. It also initiates a Flink processing job.

```bash
management-cli processing-app deploy --name="test-app"
```

--------------------------------

### Decisions Time Series Events Attributes

Source: https://www.ibm.com/docs/en/bai/25.0_topic=events-operational-decision-manager-time-series-formats

This section outlines the attributes for decisions time series events, including their descriptions, requirement status, and data types. It also provides examples for specific fields.

```APIDOC
## POST /event/decisions

### Description
This endpoint accepts time series events from decision executions for analysis and monitoring in Business Automation Insights. The event structure follows a defined notation for attributes related to ruleset execution.

### Method
POST

### Endpoint
/event/decisions

### Parameters
#### Request Body
- **version** (String) - Required - The time series format version. Example: `"1.0.1"`
- **id** (String) - Required - The event identifier, containing the decision ID of the ruleset execution.
- **timestamp** (String) - Required - The timestamp of the event in ISO8601 format.
- **odmType** (String) - Required - The type of the ODM event. Must be `"ruleset"`.
- **type** (String) - Required - The type of the event. One of: `"EXECUTION_SUCCESS"`, `"EXECUTION_FAILURE"`, `"TRACE_GENERATION_ERROR"`.
- **rulesetPath** (String) - Required - The canonical ruleset path in the format `<ruleAppName>/<ruleAppVersion>/<rulesetName>/<rulesetVersion>`.
- **duration** (Integer) - Required - The total duration of the ruleset execution in milliseconds.
- **`<ruleAppName>.<rulesetName>.in.<inputParameterField>`** (JSON primitive type) - Optional - The ruleset input parameter. Included if `bai.emitter.input` is `true`. For array inputs, each element is a separate field (e.g., `myRuleApp.myRuleset.in.0.children`).
- **`<ruleAppName>.<rulesetName>.out.<outputParameterField>`** (JSON primitive type) - Optional - The ruleset output parameter. Included if `bai.emitter.output` is `true`. For array outputs, each element is a separate field (e.g., `myRuleApp.myRuleset.out.0.children`).
- **trace.rule.names** (JSON array of strings) - Optional - The names of the executed rules. Present by default unless `bai.emitter.trace` is `false`.
- **trace.task.names** (JSON array of strings) - Optional - The names of the executed tasks. Present by default unless `bai.emitter.trace` is `false`.
- **trace.task.durations** (JSON array object) - Optional - The durations of the executed tasks in milliseconds. Present by default unless `bai.emitter.trace` is `false`.

### Request Example
```json
{
  "version": "1.0.1",
  "id": "decision-123e4567-e89b-12d3-a456-426614174000",
  "timestamp": "2023-10-27T10:00:00Z",
  "odmType": "ruleset",
  "type": "EXECUTION_SUCCESS",
  "rulesetPath": "MyRuleApp/1.0/MyRuleset/1.0",
  "duration": 50,
  "MyRuleApp.MyRuleset.in.loanAmount": 50000,
  "MyRuleApp.MyRuleset.out.approved": true,
  "trace.rule.names": ["Rule1", "Rule2"],
  "trace.task.names": ["TaskA", "TaskB"],
  "trace.task.durations": [20, 30]
}
```

### Response
#### Success Response (200)
- **status** (String) - Indicates the success of the event ingestion. Example: `"success"`

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Monitoring Source Fields with Item Version

Source: https://www.ibm.com/docs/en/bai/25.0_topic=configuration-monitoring-source-odm

An example of monitoring source field configuration that includes both an item identifier, its label, and an optional item version. This allows for distinct monitoring sources for each version of an item with the same identifier.

```yaml
monitoring_source_fields:
  - field: "item_id.keyword"
    label_field: "item_name"
  - field: "item_version"
```

--------------------------------

### Import Kafka Certificate using keytool

Source: https://www.ibm.com/docs/en/bai/24.0_topic=emitter-generating-truststore-case-event

This command imports a Kafka certificate file (e.g., kafka.pem) into a truststore (truststore.jks) with a specific alias. Ensure the keytool utility and certificate file are accessible.

```shell
<Workflow_Install_Root>/java/bin/keytool[.exe]\
  -importcert \
  -alias kafkaServer \
  -keystore truststore.jks \
  -file kafka.pem \
  -noprompt
```

--------------------------------

### Expected Duration Operation Result

Source: https://www.ibm.com/docs/en/bai/23.0_topic=processing-duration-operations

This JSON structure represents the expected output from the duration operation after processing correlated start and end events. It includes the correlation ID, timestamps, and the calculated time elapsed in milliseconds.

```json
{
  "correlationId":"order_1",
  "timestamp":"2021-05-07T00:00:07.000-04:00",
  "startTimestamp":"2021-05-07T00:00:01.000-04:00",
  "endTimestamp":"2021-05-07T00:00:07.000-04:00",
  "time-elapsed":6000
}
```

--------------------------------

### Login to OpenShift

Source: https://www.ibm.com/docs/en/bai/25.0_topic=storage-cleaning-up-indices

Logs the user into the OpenShift cluster. This is a prerequisite for executing subsequent commands that interact with the OpenShift environment.

```bash
kubectl login <cluster>
```

--------------------------------

### Get Flink Job Manager Pod Name

Source: https://www.ibm.com/docs/en/bai/23.0_topic=troubleshooting-apache-flink-jobs

This command identifies and retrieves the name of the Flink job manager pod based on its component label. This is a prerequisite for interacting with the job manager, such as executing commands within its container.

```bash
JOB_MANAGER_POD=$(oc get pods -l component=jobmanager --no-headers -o custom-columns=Namae:.metadata.name | head -n 1)
oc rsh -c jobmanager ${JOB_MANAGER_POD}
```

--------------------------------

### Sample Order Events (JSON)

Source: https://www.ibm.com/docs/en/bai/23.0_topic=processing-handling-uncompleted-operations

Provides sample JSON events representing different stages of an order process, from creation to completion. These events are used for testing the data processing pipeline.

```json
{"id": "order_1", "kind": "order", "timestamp": "2022-04-07T00:05:42.000-04:00", "status": "ORDER_CREATED"}
```

```json
{"id": "order_1", "kind": "order", "timestamp": "2022-04-09T00:08:42.000-04:00", "status": "ORDER_PROCESSING"}
```

```json
{"id": "order_1", "kind": "order", "timestamp": "2022-04-09T00:09:42.000-04:00", "status": "ORDER_VERIFICATION"}
```

```json
{"id": "order_1", "kind": "order", "timestamp": "2022-04-09T00:10:42.000-04:00", "status": "ORDER_DONE"}
```

--------------------------------

### Retrieve Kafka Bootstrap Servers

Source: https://www.ibm.com/docs/en/bai/23.0_topic=emitters-retrieving-information-connection-kafka

This command retrieves the external bootstrap servers for the Kafka instance managed by Business Automation Insights. It utilizes `oc` to get Kafka configuration and extract the bootstrap server addresses from the status.

```bash
BOOTSTRAP_SERVERS=$(oc get kafka iaf-system -o jsonpath='{.status.listeners[?(.name=="external")].bootstrapServers}')
```

--------------------------------

### Import Processing Configuration using management-cli

Source: https://www.ibm.com/docs/en/bai/23.0_topic=application-creating-processing

Imports the processing configuration defined in a specified directory into the management service. The service validates the configuration for compliance.

```bash
management-cli processing-conf import --name="test-app" --directory="./test-app"
```

--------------------------------

### Define Event Aggregation Logic with JSLT

Source: https://www.ibm.com/docs/en/bai/23.0_topic=processing-custom-operations

Specifies the logic for aggregating business events into a summary using JSLT. It defines functions for calculating start and end times, duration, state, and merging data from new events with existing summaries.

```jslt
let iso8601Format = "yyyy-MM-dd'T'HH:mm:ss"
def start-time()
  if (test($businessEvent.status, "ORDER_CREATED"))
    { "startTimestamp": $timestamp }
  else if ($summary.startTimestamp != null)
    { "startTimestamp": $summary.startTimestamp }
  else
    {}
def end-time()
  if (test($businessEvent.status, "ORDER_DONE"))
    { "endTimestamp": $timestamp }
  else if ($summary.endTimestamp != null)
    { "endTimestamp": $summary.endTimestamp }
  else
    {}
def duration()
  let startTime = get-key(start-time(), "startTimestamp", null)
  let endTime = get-key(end-time(), "endTimestamp", null)
  if ($startTime != null and $endTime != null)
    { "duration": floor(parse-time($endTime, $iso8601Format) - parse-time($startTime, $iso8601Format)) }
  else
    {}
def state()
  if ($isBusinessEventMoreRecent)
    { "state": $businessEvent.status }
  else
    { "state": $summary.state }
def timestamp()
  if ($isBusinessEventMoreRecent)
    { "timestamp": $timestamp }
  else
    { "timestamp": $summary.timestamp }
def previous-data()
  if ($summary.data != null)
    $summary.data
  else
    {}
def current-data()
  { for ($businessEvent.data) .key: .value }
def aggregate-data()
 if ($isBusinessEventMoreRecent)
   { "data" : current-data() + previous-data() }
 else
   { "data" : previous-data() + current-data() }
aggregate-data() + // data
duration() + // duration
end-time() +  // endTimestamp
start-time() +  // startTimestamp
state() +
timestamp() +
{
  "operationName": $name,
  "correlationId": $correlationId
}

```

--------------------------------

### Retrieve BAI Processor Job Name (Kubernetes CLI)

Source: https://www.ibm.com/docs/en/bai/25.0_topic=walkthrough-updating-processing-configuration

Retrieves the name of the Kubernetes job for the ODM or ADS processor. This command uses `oc get jobs` and `grep` to filter for the relevant job name based on the processing type.

```bash
oc get jobs -o=custom-columns=Name:.metadata.name --no-headers | grep bai-odm
```

```bash
oc get jobs -o=custom-columns=Name:.metadata.name --no-headers | grep bai-ads
```
Tokens:
Raw