DBACLD-160991 - Validate Instructions for BOM Dynamic Domain sample

DBACLD-160991 - Validate Instructions for BOM Dynamic Domain sample

Author: siasin

decisioncenter/dynamicdomain/README-DOCKER.md

@@ -11,19 +11,19 @@ Before following the steps below, make sure you have built the customization JAR
 
 ## 1. Build the Sample Code
 
-The following steps show how to compile the sample code into a JAR file using a Docker container with Maven and JDK 17.
+The following steps show how to compile the sample code into a JAR file using a Docker container with Maven and JDK 21.
 
 1. Navigate to the project directory:
    ```bash
    cd decisioncenter/dynamicdomain/src/ilog.rules.studio.samples.bomdomainpopulate
    ```
 
-2. Run the command below to build the JAR file:
+1. Run the command below to build the JAR file:
    ```bash
    docker run --rm \
         -v "$(pwd)":/usr/src/sample \
         -w /usr/src/sample \
-        maven:3.8.5-openjdk-17 \
+        maven:3.9.9-ibm-semeru-21-jammy \
         mvn clean install -Dtarget.docker
    ```
    > **Result**: The generated JAR file will be located in the `target` directory with the name `bomdomainpopulate-1.0.jar`.
@@ -39,7 +39,7 @@ To set up the ODM container with dynamic domain support:
    ```
    > **Explanation**: This command initializes the ODM environment required for the sample.
 
-2. Copy and configure the H2 database library for Decision Center:
+1. Copy and configure the H2 database library for Decision Center:
    ```bash
    docker-compose exec odm-dynamic-domain sh -c "cp /config/resources/h2*.jar /config/apps/decisioncenter.war/WEB-INF/lib/h2.jar"
    docker-compose restart odm-dynamic-domain
@@ -65,20 +65,20 @@ To set up and populate the dynamic domains database:
 
 # Using the sample
 
-1. Log in into the [Business Console](http://localhost:9060/decisioncenter).<!-- markdown-link-check-disable-line -->
+1. Log in to the Business Console at [http://localhost:9060/decisioncenter](http://localhost:9060/decisioncenter).<!-- markdown-link-check-disable-line -->
     - user = `rtsAdmin`
     - password = `rtsAdmin`
 1. Navigate to the **Administration** tab. In the **Settings** sub-tab, click **Custom Settings** and click the *Add custom setting* **icon** and set:
     - name = `teamserver.derbyDataBaseDomainProvider`
     - description = `derbyDataBaseDomainProvider`
     - type = `String`
-    - leave `default value` empty
-1. Set the value of the new custom setting to `ilog.rules.studio.samples.bomdomainpopulate.DataBaseDomainValueProvider`
+    - leave `default value` empty. Save the setting.
+1. Set the value of this new custom setting to `ilog.rules.studio.samples.bomdomainpopulate.DataBaseDomainValueProvider`.
 1. Navigate to the **Library** tab.
-1. Import the rule project archive `projects/bomdomainpopulate-rules.zip`.
+1. Import the rule project archive `dynamicdomain/projects/bomdomainpopulate-rules.zip`.
     > Note: this rule project `bomdomainpopulate-rules` is only aimed at editing rules to demonstrate loading domains from a database. It is missing a deployment configuration and cannot be executed.
-1. **Navigate to the Library** tab. Select the **bomdomainpopulate-rules** box (click anywhere except the name) and choose the **main branch**. 
-1. Display the rule `CheckOrder > OrderType`. Notice the error **Value (string) 'CompanyX' is incorrect**. Edit the rule and either remove **"CompanyX"** and press SPACE or double-click **"CompanyX"**. A list of suitable companies gets displayed in a drop-down. Close down the rule without saving.
+1. Once the archive is imported, the **bomdomainpopulate-rules** decision service will be displayed. Click the **main** branch to access to the decision artifacts. 
+1. Display the rule `CheckOrder > OrderType`. An error **Value (string) 'CompanyX' is incorrect** is displayed. Edit the rule and either remove **"CompanyX"** and press SPACE or double-click **"CompanyX"**. A list of suitable companies gets displayed in a drop-down. `CompanyX` is not one of these companies. Close down the rule **without** saving.
 1. Display the rule `CheckCurrency > CurrencyRestriction`. No warning is displayed.
 1. Let's now make some changes in the dynamic domains in the database. Run:
     ```bash
@@ -90,10 +90,16 @@ To set up and populate the dynamic domains database:
         -script /script/sql/modifyTables.sql \
         -showResults"
     ```
-1. Display the rule `CheckOrder > OrderType` back again. Notice that there is no error anymore. The effects of the changes done in the database are taken into account automatically because the values that the field `stock` can take are dynamically fetched from the database (and not stored in the BOM).
+1. Display the rule `CheckOrder > OrderType` back again. Notice that there is no error anymore. The effects of the changes (the addition of `CompanyX` and `CompanyY`) done in the database are taken into account automatically because the values that the field `stock` can take are dynamically fetched from the database (and not stored in the BOM).
 1. Conversely if you display the rule `CheckCurrency > CurrencyRestriction`, there is still no warning. So let's now import the changes done in the database into the BOM. Click the **Model** tab, and then the **Dynamic Domains** sub-tab. Expand all the three domains. You should see this: (Notice that the **Australian Dollar** was removed)
 
     ![Dynamic Domains update](images/dynamicDomainsUpdate.png)
 
 1. Tick **Domain** to select all the domains, and click the **Apply changes** button. Confirm the change.
 1. Display the rule `CheckCurrency > CurrencyRestriction` back again. Now a warning `'Australian Dollar' is deprecated` is displayed as the result of the update of the Dynamic Domains in the BOM.
+
+# Stopping the sample
+
+```bash
+docker-compose down
+```

decisioncenter/dynamicdomain/README-KUBERNETES.md

@@ -5,31 +5,28 @@ This README explains how to run the BOM dynamic domain sample in Kubernetes.
 #  Configuring the sample in Kubernetes
 ## 1. Build the sample code 
 
-The instructions below enable to build the JAR using a Docker container featuring Maven and a JDK version 17. 
+The instructions below enable to build the JAR using a Docker container featuring Maven and a JDK version 21. 
 
-Run  command below in the `decisioncenter/dynamicdomain/src/ilog.rules.studio.samples.bomdomainpopulate` directory:
+Run the command below in the `decisioncenter/dynamicdomain/src/ilog.rules.studio.samples.bomdomainpopulate` directory:
 
 This will compile the source code 
 ```bash
 docker run --rm \
       -v "$(pwd)":/usr/src/sample \
       -w /usr/src/sample \
-      maven:3.8.5-openjdk-17 \
+      maven:3.9.9-ibm-semeru-21-jammy \
       mvn clean install
 ``` 
+> **Result**: The generated JAR file will be located in the `target` directory with the name `bomdomainpopulate-1.0.jar`.
 
 ## 2. Uploading JARs on a file server
 
-The customization JARs can be made available to Decision Center in two ways:
-1. the **legacy way**: by copying the JARs to a PVC and referencing this PVC using the parameter `decisionCenter.customlibPvc`
-1. or the **new way** (since 9.0 only): by copying the JARs on a file server and referencing the files to download from this file server using the parameter `decisionCenter.downloadUrl`
+Any file server reachable by Decision Center is suitable. 
 
-This document explains how to follow the **new way**. Any file server reachable by Decision Center is suitable. You can either use an existing one or follow the instructions [here](https://github.com/DecisionsDev/odm-docker-kubernetes/blob/vnext-release/contrib/file-server/README.md#setup-an-httpd-file-server) to deploy a httpd file server in a new pod.
-
-However you must use the **legacy way** if you deploy a version of ODM older than 9.0. Here are some [instructions](https://www.ibm.com/docs/en/odm/9.0.0?topic=kubernetes-customizing-decision-center-business-console) in the documentation.
+You can either use an existing one or follow the instructions [here](https://github.com/DecisionsDev/odm-docker-kubernetes/blob/vnext-release/contrib/file-server/README.md#setup-an-httpd-file-server) to deploy a httpd file server in a new pod.
 
 Two JARs must be made available:
-  1. the Decision Center extension JAR built [previously](README.md#building-the-decision-center-extension-jar),
+  1. the Decision Center extension JAR built [previously](README-KUBERNETES.md#1-build-the-sample-code)
   1. the JDBC driver of the database storing the data of the dynamic domains.
 
 Download the JDBC driver (if the internal PostgreSQL database is used):
@@ -43,21 +40,59 @@ curl -T target/bomdomainpopulate-1.0.jar $FILESERVER_URL
 curl -T jdbc-driver.jar $FILESERVER_URL
 ```
 
+If all goes well, you should have an output with `201` status for the uploading of the JARs. For example:
+```console
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>201 Created</title>
+</head><body>
+<h1>Created</h1>
+<p>Resource /bomdomainpopulate-1.0.jar has been created.</p>
+</body></html>
+```
+
 ## 3. Deploying ODM
 
-Add the public IBM Helm charts repository:
+To get access to the ODM material, you must have an IBM entitlement key to pull the images from the IBM Cloud Container registry.
+
+### a. Retrieve your entitled registry key
+
+- Log in to [MyIBM Container Software Library](https://myibm.ibm.com/products-services/containerlibrary) with the IBMid and password that are associated with the entitled software.
+
+- In the **Container Software and Entitlement Keys** tile, verify your entitlement on the **View library page**, and then go to *Entitlement keys* to retrieve the key.
+
+### b. Create a pull secret by running the kubectl create secret command
+
+```bash
+kubectl create secret docker-registry my-odm-docker-registry --docker-server=cp.icr.io \
+    --docker-username=cp --docker-password="<ENTITLEMENT_KEY>" --docker-email=<USER_EMAIL>
+```
+Where:
+
+- `<ENTITLEMENT_KEY>`: The entitlement key from the previous step. Make sure to enclose the key in double quotes.
+- `<USER_EMAIL>`: The email address associated with your IBMid.
+
+> **Note**
+> The `cp.icr.io` value for the docker-server parameter is the only registry domain name that contains the images. You must set the docker-username to `cp` to use the entitlement key as the docker-password.
+
+The `my-odm-docker-registry` secret name must be used for the `image.pullSecrets` parameter when you run a Helm install of your containers. The `image.repository` parameter should also set to `cp.icr.io/cp/cp4a/odm`.
+
+### c. Add the public IBM Helm charts repository:
+
 ```bash
-helm repo add ibmcharts https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
+helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
 helm repo update
-````
+```
+
+### d. Check that you can access the ODM charts:
 
-Check that you can access the ODM charts:
 ```bash
 helm search repo ibm-odm-prod
 ```
 ```bash
-NAME                        	CHART VERSION	APP VERSION	DESCRIPTION
-ibmcharts/ibm-odm-prod      	<version>     <version>  	IBM Operational Decision Manager  License By in...
+NAME                          CHART VERSION APP VERSION	DESCRIPTION
+ibm-helm/ibm-odm-prod         25.0.0        9.5.0.0  	IBM Operational Decision Manager  License By in...
 ```
 
 Create a file named `values.yaml`. This file will be used by the `helm install` command to specify the configuration parameters. 
@@ -82,33 +117,42 @@ internalDatabase:
 
 Add all the other parameters suitable to your platform in `values.yaml`. Check this [link](https://github.com/DecisionsDev/odm-docker-kubernetes/tree/master/platform) for help.
 
-Install an ODM release named `myodmsample` (if you choose a different release name, you need to edit the file [database.properties](src/ilog.rules.studio.samples.bomdomainpopulate/src/main/resources/data/database.properties)):
+If you are on Openshift, you can use this [values.yaml](./src/ilog.rules.studio.samples.bomdomainpopulate/values.yaml) file by replacing `<FILESERVER_URL>` with the actual URL of the file server hosting the JARs.
+
+Install an ODM release named `myodmsample`: 
 ```bash
-helm install myodmsample ibmcharts/ibm-odm-prod -f values.yaml
+helm install myodmsample ibm-helm/ibm-odm-prod -f values.yaml
 ```
+> **NOTE**: If you choose a **different** release name, you must edit the value of `database.url` parameter accordingly in the [database.properties](src/ilog.rules.studio.samples.bomdomainpopulate/src/main/resources/data/database.properties), [rebuild](README-KUBERNETES.md#1-build-the-sample-code) the `bomdomainpopulate-1.0.jar`, and upload the JAR to the file server again.
 
 ## 4. Configuring Decision Center
 
 The class that implements the customization must be declared:
-- either using a custom setting
-- or using a JVM parameter 
+- either using a custom setting at Business Console
+- *or* using a JVM parameter
 
 ### 4.1 Using a custom setting
-1. Log in into the Business Console as an admin
+1. Log in to the Business Console. Use the following credentials if you install with the [values.yaml](./src/ilog.rules.studio.samples.bomdomainpopulate/values.yaml) for OCP:  
+   - **Username**: `odmAdmin`  
+   - **Password**: `odmAdmin`
 1. Navigate to **Administration > Settings > Custom Settings**
 1. Click the *Add custom setting* **icon** and set:
     - name = `teamserver.derbyDataBaseDomainProvider`
     - description = `derbyDataBaseDomainProvider`
     - type = `String`
-    - leave `default value` empty
-1. Set the value to `ilog.rules.studio.samples.bomdomainpopulate.DataBaseDomainValueProvider`
+    - leave `default value` empty. Save the setting.
+1. Set the value of this new custom setting to `ilog.rules.studio.samples.bomdomainpopulate.DataBaseDomainValueProvider`.
 
 ### 4.2 Using a JVM parameter
 
-Follow instructions similar to [here](https://www.ibm.com/docs/en/odm/9.0.0?topic=kubernetes-persisting-decision-center-ruleset-cache) to add the JVM parameter below: (using in a Config Map referenced by the Helm parameter **decisionCenter.jvmOptionsRef**)
+Follow instructions as described [here](https://www.ibm.com/docs/en/odm/9.0.0?topic=kubernetes-persisting-decision-center-ruleset-cache) to create a Config Map with the additional JVM parameter below: 
 ```
 -Dilog.rules.teamserver.derbyDataBaseDomainProvider=ilog.rules.studio.samples.bomdomainpopulate.DataBaseDomainValueProvider
 ```
+You need to set this new Config Map using the Helm parameter **decisionCenter.jvmOptionsRef**. To do so, apply an upgrade to your helm release:
+```bash
+helm upgrade myodmsample ibm-helm/ibm-odm-prod --reuse-values --set decisionCenter.jvmOptionsRef=<your_updated_dc_jvm_options_ref_configmap>
+```
 
 ## 5. Initializing the database
 
@@ -129,21 +173,21 @@ Follow instructions similar to [here](https://www.ibm.com/docs/en/odm/9.0.0?topi
     kubectl exec $DBSERVER -- psql -U odmusr -d odmdb -f /tmp/createAndPopulate.sql
     ```
 
-## 6. Using the Sample
+## 6. Using the sample
 
-1. Log in into the Business Console.
+1. Log in to the Business Console.
 1. Navigate to the **Library** tab.
-1. Import the rule project archive `projects/bomdomainpopulate-rules.zip`.
+1. Import the rule project archive `dynamicdomain/projects/bomdomainpopulate-rules.zip`.
     > Note: this rule project `bomdomainpopulate-rules` is only aimed at editing rules to demonstrate loading domains from a database. It is missing a deployment configuration and cannot be executed.
-1. Display the rule `CheckOrder > OrderType`. Notice the error **Value (string) 'CompanyX' is incorrect**. Edit the rule and either remove **"CompanyX"** and press SPACE or double-click **"CompanyX"**. A list of suitable companies gets displayed in a drop-down. Close down the rule without saving.
+1. Display the rule `CheckOrder > OrderType`. An error **Value (string) 'CompanyX' is incorrect** is displayed. Edit the rule and either remove **"CompanyX"** and press SPACE or double-click **"CompanyX"**. A list of suitable companies gets displayed in a drop-down. Close down the rule **without** saving.
 1. Display the rule `CheckCurrency > CurrencyRestriction`. No warning is displayed.
 1. Let's now make some changes in the dynamic domains in the database. Run:
     ```bash
     kubectl cp ./sql_scripts/modifyTables.sql $DBSERVER:/tmp
     kubectl exec $DBSERVER -- psql -U odmusr -d odmdb -f /tmp/modifyTables.sql
     ```
 
-1. Display the rule `CheckOrder > OrderType` back again. Notice that there is no error anymore. The effects of the changes done in the database are taken into account automatically because the values that the field `stock` can take are dynamically fetched from the database (and not stored in the BOM).
+1. Display the rule `CheckOrder > OrderType` back again. Notice that there is no error anymore. The effects of the changes (the addition of `CompanyX` and `CompanyY`) done in the database are taken into account automatically because the values that the field `stock` can take are dynamically fetched from the database (and not stored in the BOM).
 1. Conversely if you display the rule `CheckCurrency > CurrencyRestriction`, there is still no warning. So let's now import the changes done in the database into the BOM. Click the **Model** tab, and then the **Dynamic Domains** sub-tab. Expand all the three domains. You should see this: (Notice that the **Australian Dollar** was removed)
 
     ![Dynamic Domains update](images/dynamicDomainsUpdate.png)

decisioncenter/dynamicdomain/README.md

@@ -1,4 +1,4 @@
-# BOM dynamic domain Sample
+# BOM dynamic domain sample
 
 ## Introduction
 
@@ -19,9 +19,9 @@ In this sample, you will :
 - store new values of the dynamic domains in a database,
 - update the rule project with the new values of the dynamic domains.
 
-## Running this sample in Rule Designer
+## 1. Running the sample in Rule Designer
 
-### 1) Building the Eclipse plugin
+### 1.1 Building the Eclipse plugin
 
 To use the sample in Rule Designer, you need to build an Eclipse plugin.
 - In Eclipse, make sure that,
@@ -31,27 +31,27 @@ To use the sample in Rule Designer, you need to build an Eclipse plugin.
 - Select the folder `decisioncenter/dynamicdomain/src/ilog.rules.studio.samples.bomdomainpopulate` 
 - Tick the project `ilog.rules.studio.samples.bomdomainpopulate` and click **Finish**
 - Right-click the `build-bomdomainepopulate.xml` file and click **Run as > Ant Build**. A file named `bomdomainpopulate.jar` gets generated at the root of the project.
-- Click **Export > Plug-in Development > Deployable Plug-ins and fragments** to build the plugin. Click **Next**, choose `<ECLIPSE_HOME>/dropins` as the destination directory (where `<ECLIPSE_HOME` should be replaced by the HOME directory of the running Eclipse), and click **Finish**.
+- Right-click on the project and click **Export > Plug-in Development > Deployable Plug-ins and fragments** to build the plugin. Click **Next**, enter `<ECLIPSE_HOME>/dropins` as the destination directory (where `<ECLIPSE_HOME>` should be replaced by the HOME directory of the running Eclipse), and click **Finish**.
 - Restart Eclipse.
 
   >Note: if you modify the plugin and deploy it again, start Eclipse with the `-clean` parameter to force a cache update.
 
-### 2) Instructions to use the sample in Rule Designer
+### 1.2 Instructions to use the sample in Rule Designer
 
 - Import the projects below located in the `decisioncenter/dynamicdomain/projects/` directory:
   - bomdomainpopulate-bd-helper
   - bomdomainpopulate-rules
   - bomdomainpopulate-xom
 
-- Follow the [instructions from the documentation](https://www.ibm.com/docs/en/odm/9.0.0?topic=domains-data-sources-bom-sample-details).
+- Follow the [instructions from the documentation](https://www.ibm.com/docs/en/odm/9.0.0?topic=domains-data-sources-bom-sample-details) to try out how the sample works in Rule Designer.
 
-## Running this sample in Decision Center
+## 2. Running the sample in Decision Center
 
-### 1) Prerequisites
+### 2.1 Prerequisites
 
 Ensure you have at least Docker 24.0.x (and optionally Kubernetes 1.27+).
 
-### 2) Configuring how to connect to the database (kubernetes only)
+### 2.2 Configuring how to connect to the database (kubernetes only)
 
 If you deploy ODM on Docker, there is nothing to configure.