Adding a Machine Learning configuration file as a XOM resource

About this task

You create an ml.properties file with the required Machine Learning service configuration and set it as a XOM resource. This approach offers the advantage of defining the endpoint for each RuleApp, enhancing customization and flexibility in managing Machine Learning configurations.

(Option 1) Using Rule Designer

1. In the Rule Designer workspace that contains your rule projects, create a new Java™ project.

2. Create a new ml.properties file in the default src folder.

3. Add the following lines:

   com.ibm.rules.ml.rest.baseurl=<value>
   com.ibm.rules.ml.rest.urlsuffix=<value>
   com.ibm.rules.ml.rest.authentication.url=<value>
   com.ibm.rules.ml.rest.authentication.apikey=<value>

   The properties are defined as follows:

   • com.ibm.rules.ml.rest.baseurl property is the base URL of your ML models REST endpoint, which is used to obtain a score. It is the part before the model's deployment ID. For example, if your full URL is https://us-south.ml.cloud.ibm.com/ml/v4/deployments/30d8261b-47ad-48d1-8b78-2f043474ff91/predictions?version=2021-05-01, the value is https://us-south.ml.cloud.ibm.com/ml/v4/deployments.

   • com.ibm.rules.ml.rest.authentication.url property is the identity server of the scoring server. You provide this endpoint with an API key, and it in return gives you a token to use with the scoring server. For example, the value might be https://iam.cloud.ibm.com/identity/token.

   • com.ibm.rules.ml.rest.authentication.apikey property is the API key that is passed to the identity server to obtain a token. For example, the value might be XXXYYYYZZZZZ. To generate an API key from your IBM Cloud® user account, go to Manage access and users - API Keys and create or select an API key for your user account.

   • com.ibm.rules.ml.rest.urlsuffix property is an optional setting. If you provide a value, it is added to the end of your scoring URL after the deployment ID.

     For example, if you use a value of predictions?version=2021-05-01 with a base URL of https://us-south.ml.cloud.ibm.com/ml/v4/deployments and a deployment id of 30d8261b-XXX-YYY-8b78-2f043474ff91, the full URL that is used to access Machine Learning is https://us-south.ml.cloud.ibm.com/ml/v4/deployments/30d8261b-XXX-YYY-8b78-2f043474ff91/predictions?version=2021-05-01.

     If you do not specify a value, Operational Decision Manager automatically uses a value of predictions?version=YYYY-MM-DD, where YYYY-MM-DD is today's date in that format. If you specify a deployment that contains a slash (/), no suffix is applied.

4. Save your changes.

5. In the Rule Explorer view, right-click the rule project and then click Properties.

6. Click Java Execution Object Model and select the new Java project to include the ml.properties.

7. When you deploy the RuleApp, the ml.properties is included as one of the XOMs.

(Option 2) Using Rule Execution Server console

1. Create a new ml.properties file with the parameter as described in (Option 1) Using Rule Designer.

2. Compress ml.properties into an archive named ml-properties.zip.

3. Sign in to the Rule Execution Server console.

   Note:

   The RuleApp archive to integrate with the Machine Learning service must be deployed along with its XOM.

4. Click the Explorer tab to open it.

5. In the navigator tree pane, click Resources to view the deployed XOM.

   1. Click Deploy Resource button to deploy the ml-properties.zip file as a new resource.

   2. Make sure a new resource ml-properties.zip with version 1.0 is added.

6. In the navigator tree pane, click Libraries to view the deployed RuleApp libraries.

   1. Click the specific RuleApp library that you want to add the Machine Learning service configuration.

   2. Click the Add Internal Resource Reference button and choose ml-properties.zip/1.0 to add to this RuleApp library.

   3. Make sure a new internal resource reference ml-properties.zip with version 1.0 is added.

(Option 3) Using REST API

Alternatively, you can use REST API to update the deployed XOM resources and libraries by using the following commands:

# To compress your ml.properties file as an archive
zip /<your_directory>/ml-properties.zip ml.properties

# To add the ml-properties.zip file as a XOM resource 
curl -i --header "accept: application/xml"  --header "Content-type: application/octet-stream" -X POST --data-binary @/<your_directory>/ml-properties.zip  https://<res_admin_id>:<res_admin_pwd>@<host>:<port>/res/apiauth/xoms/ml-properties.zip

# To get all managed XOM libraries URIs using the specific RuleApp library name
URIS=$(curl --header "accept: application/json" https://<res_admin_id>:<res_admin_pwd>@<host>:<port>/res/apiauth/libraries/<your_ruleapp_library>/<ruleapp_version> -k -q -s | grep content | sed 's/.*\[//; s/\].*//' | sed 's/\"//g')

# To update the resources and libraries referenced by the specific managed XOM library
curl --header "content-type: text/plain" -X PUT -d "$URIS,resuri://ml-properties.zip/1.0" https://<res_admin_id>:<res_admin_pwd>@<host>:<port>/res/apiauth/libraries/<your_ruleapp_library>/<ruleapp_version> -k -q -s