Scoring rules REST API

You use the Scoring rules API to define and edit the scoring definition that is used by an analytical model.

To change the scoring rules or scoring definition, IBM® Maximo® Production Optimization SaaS provides the following APIs:

Define a new scoring rule

To define a new scoring rule, use the operation and API path that are outlined in the following table:

Table 1. Define a new scoring rule API

Operation Path Description
POST /api/v1/scoring/scoringrule/{name} Defines a new scoring rule or scoring definition.

Table 2. The parameters to define a new scoring rule

Parameters Location Required Description
tenantId header true The Maximo Production Optimization SaaS tenant ID.
userId header true The Maximo Production Optimization SaaS user ID.
apiKey header true The Maximo Production Optimization SaaS API key.
name path true The scoring rule name.
payload body true The scoring rule definitions.

For example, to create a scoring rule for the failure probability prediction model that has the name failureprobability_scoring_demo, you must supply the following information:

The following sample payload creates a new scoring rule for a failure probability prediction model:

  {
    "model": "failureprobability",
    "data_config": {
      "entity_datetime_column_name": "dateofsensordata",
      "entity_failure_type_enum": {
        "0": "NoFault",
        "1": "Fault"
      },
      "entity_id_column_name": "asset_id",
      "entity_ok_status": [
        0
      ],
      "entity_predict_period": "7d"
    },
    "scoring_config": {
      "bucket": "po-datasets",
      "delete": false,
      "feature_endpoint": "https://us-south.ml.cloud.ibm.com/v3/wml_instances/d739718a-xxxx-xxxx-xxxx-xxxxxxxxxxxx/deployments/52f96e1b-xxxx-xxxx-xxxx-b2fb936b440e/online",
      "object": "sensor_data_demo1.csv",
      "scoring_endpoint": "https://us-south.ml.cloud.ibm.com/v3/wml_instances/d739718a-xxxx-xxxx-xxxx-xxxxxxxxxxxx/deployments/52f96e1b-xxxx-xxxx-xxxx-ca30cf20c22c/online"
    },
    "cos_config": {
      "apikey": "AkGexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxJGikd",
      "endpoint_url": "https://s3-api.us-geo.objectstorage.softlayer.net",
      "ibm_auth_endpoint": "https://iam.ng.bluemix.net/oidc/token"
    },
    "po_config": {
      "apiKey": "27a06148xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx88b866bac8a",
      "tenantId": "xxx",
      "url": "https://prod.productionoptimization.ibm.com",
      "userId": "xxx"
    },
    "wml_config": {
      "apikey": "5wm9nxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxPQ19V",
      "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:pm-20:us-south:a/b1ed0xxxxxxxxxxxxxxxxxxxxxx3034f:d7397xxx-xxxx-xxxx-xxxx-xxxxxxx7a135::",
      "iam_apikey_name": "auto-generated-apikey-10864xxx-xxxx-xxxx-xxxx-xxxxxxx86c6e",
      "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
      "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/b1ed0xxxxxxxxxxxxxxxxxxxxxx3034f::serviceid:ServiceId-4d4712af-2641-493f-ad54-d792c96ec445",
      "instance_id": "d7397xxx-xxxx-xxxx-xxxx-xxxxxxx7a135",
      "password": "4c890xxx-xxxx-xxxx-xxxx-xxxxxxx5e237",
      "url": "https://us-south.ml.cloud.ibm.com",
      "username": "10864xxx-xxxx-xxxx-xxxx-xxxxxxx86c6e"
    }
  }

The sample includes the following sessions:

When you have the information, you can use the openapi UI or the curl command to create the scoring rule, for example:

    curl -X POST "https://prod.productionoptimization.ibm.com/api/v1/scoring/scoringrule/failureprobability_scoring_demo"  
     -H  "accept: application/json"  
     -H  "userId: xxx"  
     -H  "tenantId: xxx"  
     -H  "apiKey: 27a06148xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx88b866bac8a"  
     -H  "Content-Type: application/json"  
     -d "{\"cos_config\":{\"apikey\":\"AkGexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxJGikd\",\"endpoint_url\":\"https://s3-api.us-geo.objectstorage.softlayer.net\",\"ibm_auth_endpoint\":\"https://iam.ng.bluemix.net/oidc/token\"},\"data_config\":{\"entity_datetime_column_name\":\"dateofsensordata\",\"entity_failure_type_enum\":{\"0\":\"NoFault\",\"1\":\"Fault\"},\"entity_id_column_name\":\"asset_id\",\"entity_ok_status\":[0],\"entity_predict_period\":\"7d\"},\"model\":\"failureprobability\",\"po_config\":{\"apiKey\":\"27a06148xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx88b866bac8a\",\"tenantId\":\"xxx\",\"url\":\"http://ts-svc:9080\",\"userId\":\"xxx\"},\"scoring_config\":{\"bucket\":\"po-datasets\",\"delete\":false,\"feature_endpoint\":\"https://us-south.ml.cloud.ibm.com/v3/wml_instances/d739718a-xxxx-xxxx-xxxx-xxxxxxxxxxxx/deployments/52f96e1b-xxxx-xxxx-xxxx-b2fb936b440e/online\",\"object\":\"sensor_data_demo1.csv\",\"scoring_endpoint\":\"https://us-south.ml.cloud.ibm.com/v3/wml_instances/d739718a-xxxx-xxxx-xxxx-xxxxxxxxxxxx/deployments/52f96e1b-xxxx-xxxx-xxxx-ca30cf20c22c/online\"},\"wml_config\":{\"apikey\":\"5wm9nxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxPQ19V\",\"iam_apikey_description\":\"Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:pm-20:us-south:a/b1ed0xxxxxxxxxxxxxxxxxxxxxx3034f:d7397xxx-xxxx-xxxx-xxxx-xxxxxxx7a135::\",\"iam_apikey_name\":\"auto-generated-apikey-10864xxx-xxxx-xxxx-xxxx-xxxxxxx86c6e\",\"iam_role_crn\":\"crn:v1:bluemix:public:iam::::serviceRole:Writer\",\"iam_serviceid_crn\":\"crn:v1:bluemix:public:iam-identity::a/b1ed0xxxxxxxxxxxxxxxxxxxxxx3034f::serviceid:ServiceId-4d4712af-2641-493f-ad54-d792c96ec445\",\"instance_id\":\"d7397xxx-xxxx-xxxx-xxxx-xxxxxxx7a135\",\"password\":\"4c890xxx-xxxx-xxxx-xxxx-xxxxxxx5e237\",\"url\":\"https://us-south.ml.cloud.ibm.com\",\"username\":\"10864xxx-xxxx-xxxx-xxxx-xxxxxxx86c6e\"}}"

The response is 201 with the scoring rule information that is created:

    {
      "data": {
        "_id": "783a9a6d8f608b85efe5592ca206c4a0",
        "_rev": "1-35cb45610c0e9dc4598e2061ea15b3f4",
        "cos_config": {
          "apikey": "AkGexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxJGikd",
          "endpoint_url": "https://s3-api.us-geo.objectstorage.softlayer.net",
          "ibm_auth_endpoint": "https://iam.ng.bluemix.net/oidc/token"
        },
        "data_config": {
          "entity_datetime_column_name": "dateofsensordata",
          "entity_failure_type_enum": {
            "0": "NoFault",
            "1": "Fault"
          },
          "entity_id_column_name": "asset_id",
          "entity_ok_status": [
            0
          ],
          "entity_predict_period": "7d"
        },
        "model": "failureprobability",
        "name": "failureprobability_scoring_demo",
        "po_config": {
          "apiKey": "27a06148xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx88b866bac8a",
          "tenantId": "xxx",
          "url": "http://ts-svc:9080",
          "userId": "xxx"
        },
        "scoring_config": {
          "bucket": "po-datasets",
          "delete": false,
          "feature_endpoint": "https://us-south.ml.cloud.ibm.com/v3/wml_instances/d739718a-xxxx-xxxx-xxxx-xxxxxxxxxxxx/deployments/52f96e1b-xxxx-xxxx-xxxx-b2fb936b440e/online",
          "object": "sensor_data_demo1.csv",
          "scoring_endpoint": "https://us-south.ml.cloud.ibm.com/v3/wml_instances/d739718a-xxxx-xxxx-xxxx-xxxxxxxxxxxx/deployments/52f96e1b-xxxx-xxxx-xxxx-ca30cf20c22c/online"
        },
        "wml_config": {
          "apikey": "5wm9nxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxPQ19V",
          "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:pm-20:us-south:a/b1ed0xxxxxxxxxxxxxxxxxxxxxx3034f:d7397xxx-xxxx-xxxx-xxxx-xxxxxxx7a135::",
          "iam_apikey_name": "auto-generated-apikey-10864xxx-xxxx-xxxx-xxxx-xxxxxxx86c6e",
          "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
          "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/b1ed0xxxxxxxxxxxxxxxxxxxxxx3034f::serviceid:ServiceId-4d4712af-2641-493f-ad54-d792c96ec445",
          "instance_id": "d7397xxx-xxxx-xxxx-xxxx-xxxxxxx7a135",
          "password": "4c890xxx-xxxx-xxxx-xxxx-xxxxxxx5e237",
          "url": "https://us-south.ml.cloud.ibm.com",
          "username": "10864xxx-xxxx-xxxx-xxxx-xxxxxxx86c6e"
        }
      },
      "msg": "created rule failureprobability_scoring_demo for xxx...",
      "status": 201
    }

Get an existing rule based on the name of the tenant

To get an existing rule based on the name of the tenant, use the operation and API path that are outlined in the following table:

Table 3. Get an existing rule based on the name of the tenant API

Operation Path Description
GET /api/v1/scoring/scoringrule/{name} Get an existing scoring rule or scoring definition

Table 4. The parameters for getting an existing rule based on the name of the tenant

Parameters Location Required Description
tenantId header true Maximo Production Optimization SaaS tenant ID
userId header true Maximo Production Optimization SaaS user ID
apiKey header true Maximo Production Optimization SaaS API key
name path true The scoring rule name
  curl -X GET "https://prod.productionoptimization.ibm.com/api/v1/scoring/scoringrule/failureprobability_scoring_demo"  
  -H  "accept: application/json"  
  -H  "userId: xxx" -H  "tenantId: xxx"  
  -H  "apiKey: 27a06148xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx88b866bac8a"

Get all the existing scoring rules of a tenant

To get all existing scoring rules that are used by a tenant, use the following API:

Table 5. Get all existing scoring rules of a tenant API

Operation Path Description
GET /api/v1/scoring/scoringrule Get all existing scoring rules ir scoring definitions for the tenant

Table 6. The parameters for getting all existing scoring rules of a tenant API

Parameters Location Required Description
tenantId header true Maximo Production Optimization SaaS tenant ID
userId header true Maximo Production Optimization SaaS user ID
apiKey header true Maximo Production Optimization SaaS API key
skip query false Skip n records when querying
limit query false Limit n records that are returned
  curl -X GET "https://prod.productionoptimization.ibm.com/api/v1/scoring/scoringrule"  
  -H  "accept: application/json"  
  -H  "tenantId: xxx" -H  "userId: xxx"  
  -H  "apiKey: 27a06148xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx88b866bac8a"

Update an existing scoring rule

To update an existing scoring rule, use the operation and API path that are outlined in the following table:

Table 7. Update an existing scoring rule API

Operation Path Description
PUT /api/v1/scoring/scoringrule/{name} Update an existing scoring rule or scoring definition

Table 8. The parameters for updating an existing scoring rule API

Parameters Location Required Description
tenantId header true PO tenant ID
userId header true PO user ID
apiKey header true PO API key
name path true The scoring rule name
payload body true The updated scoring rule definitions

You need to input the updated part with the model that is used in your payload, for example:

  {
    "model": "failureprobability",
    "data_config": {
      "entity_datetime_column_name": "dateofsensordata",
      "entity_failure_type_enum": {
        "0": "NoFault",
        "1": "Fault"
      },
      "entity_id_column_name": "asset_id",
      "entity_ok_status": [
        0
      ],
      "entity_predict_period": "1w"
    }
  }

The example updates the scoring rule 'failureprobability_scoring_demo'.

  curl -X PUT "https://prod.productionoptimization.ibm.com/api/v1/scoring/scoringrule/failureprobability_scoring_demo"  
  -H  "accept: application/json"  
  -H  "tenantId: xxx" -H   
  "userId: xxx"  
  -H  "apiKey: 27a06148xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx88b866bac8a"  
  -H  "Content-Type: application/json"  
  -d "{\"model\":\"failureprobability\",\"data_config\":{\"entity_datetime_column_name\":\"dateofsensordata\",\"entity_failure_type_enum\":{\"0\":\"NoFault\",\"1\":\"Fault\"},\"entity_id_column_name\":\"asset_id\",\"entity_ok_status\":[0],\"entity_predict_period\":\"1w\"}}"

When the operation is successful, it returns the following updated information:

  {
    "data": {
      "_id": "783a9a6d8f608b85efe5592ca206c4a0",
      "_rev": "3-c4b1798e13912354288c84e81b69deee",
      "cos_config": {
        "apikey": "AkGexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxJGikd",
        "endpoint_url": "https://s3-api.us-geo.objectstorage.softlayer.net",
        "ibm_auth_endpoint": "https://iam.ng.bluemix.net/oidc/token"
      },
      "data_config": {
        "entity_datetime_column_name": "dateofsensordata",
        "entity_failure_type_enum": {
          "0": "NoFault",
          "1": "Fault"
        },
        "entity_id_column_name": "asset_id",
        "entity_ok_status": [
          0
        ],
        "entity_predict_period": "1w"
      },
      "model": "failureprobability",
      "name": "failureprobability_scoring_demo",
      "po_config": {
        "apiKey": "27a06148xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx88b866bac8a",
        "tenantId": "xxx",
        "url": "http://ts-svc:9080",
        "userId": "xxx"
      },
      "scoring_config": {
        "bucket": "po-datasets",
        "delete": false,
        "feature_endpoint": "https://us-south.ml.cloud.ibm.com/v3/wml_instances/d739718a-xxxx-xxxx-xxxx-xxxxxxxxxxxx/deployments/52f96e1b-xxxx-xxxx-xxxx-b2fb936b440e/online",
        "object": "sensor_data_demo1.csv",
        "scoring_endpoint": "https://us-south.ml.cloud.ibm.com/v3/wml_instances/d739718a-xxxx-xxxx-xxxx-xxxxxxxxxxxx/deployments/52f96e1b-xxxx-xxxx-xxxx-ca30cf20c22c/online"
      },
      "wml_config": {
        "apikey": "5wm9nxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxPQ19V",
        "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:pm-20:us-south:a/b1ed0xxxxxxxxxxxxxxxxxxxxxx3034f:d7397xxx-xxxx-xxxx-xxxx-xxxxxxx7a135::",
        "iam_apikey_name": "auto-generated-apikey-10864xxx-xxxx-xxxx-xxxx-xxxxxxx86c6e",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/b1ed0xxxxxxxxxxxxxxxxxxxxxx3034f::serviceid:ServiceId-4d4712af-2641-493f-ad54-d792c96ec445",
        "instance_id": "d7397xxx-xxxx-xxxx-xxxx-xxxxxxx7a135",
        "password": "4c890xxx-xxxx-xxxx-xxxx-xxxxxxx5e237",
        "url": "https://us-south.ml.cloud.ibm.com",
        "username": "10864xxx-xxxx-xxxx-xxxx-xxxxxxx86c6e"
      }
    },
    "msg": "scoring rule failureprobability_scoring_demo for xxx updated",
    "status": 200
  }

Delete an existing scoring rule

To delete an existing scoring rule, use the following API:

Table 9. Delete an existing scoring rule API

Operation Path Description
DELETE /api/v1/scoring/scoringrule/{name} Delete a scoring rule or scoring definition

Table 10. The parameters required to delete an existing scoring rule

Parameters In Required Description
tenantId header true Maximo Production Optimization SaaS tenant ID
userId header true Maximo Production Optimization SaaS user ID
apiKey header true Maximo Production Optimization SaaS API key
name path true The scoring rule name

For example:

  curl -X DELETE "https://prod.productionoptimization.ibm.com/api/v1/scoring/scoringrule/test_abc"  
  -H  "accept: application/json"  
  -H  "tenantId: xxx"  
  -H  "userId: xxx"  
  -H  "apiKey: 27a06148xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx88b866bac8a"

The following response is returned:

  {
    "data": {
      "_id": "4f54a07dbce386365937b128a513a6ba"
    },
    "msg": "scoring rule test_abc for T1 deleted",
    "status": 200
  }