ClassificationSolutionVersion - Global

  • Release version: Xanadu
  • Updated August 1, 2024
  • 11 minutes to read

    • The ClassificationSolutionVersion API is a scriptable object used in Predictive Intelligence stores.

    This API requires the Predictive Intelligence plugin (com.glide.platform_ml) and is provided within the sn_ml namespace.

    This API is used for working with solution versions based on ClassificationSolution API objects in the ClassificationSolution store.

    The system creates a solution version each time you train a solution definition. Most versions are created during scheduled solution training.

    Methods in this API are accessible using the following ClassificationSolution - Global methods:

    ClassificationSolutionVersion - getPredictionPerformance(Object options)

    Calculates solution precision and coverage.

    To use this method, you must first create settings using the setPredictionSettings() method.

    Table 1. Parameters
    Name Type Description
    options Object Selects a metric to retrieve within a span of dates. For more information, see Configuring target metrics.
    {
  "fromDate": "String",
  "metricName": "String",
  "toDate": "String"
}
    options.fromDate String Optional. Start date from which to retrieve metrics in system date time format.
    options.metricName String Name of the metric.
    Valid values:
    • precision
    • coverage
    options.toDate String Optional. End date from which to retrieve metrics.

    Formnt: System date time format.
    Table 2. Returns
    Type Description
    Object Parseable JavaScript object containing the results for the input metric.
    {
  "metricName" : "String",
  "metricValue" : "String",
  "numberOfPredictionsConsidered" : "String"
}
    Object.metricName Name of metric selected as input.

    Data type: String
    Object.metricValue Value of the selected metric.

    Data type: String
    Object.numberOfRecordsConsidered Number of records in the Predictor Results [ml_predictor_results] table considered for calculations.

    Data type: String

    The following example shows how to get a precision value from the active version of a solution.

    // Get precision value
var mlSolution = sn_ml.ClassificationSolutionStore.get('ml_incident_categorization');

gs.print(JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getPredictionPerformance({"metricName": "precision"})), null, 2));

    Output:

    {
  "metricName": "precision",
  "metricValue": "70.10",
  "numberOfPredictionsConsidered": "10"
}

    ClassificationSolutionVersion - getPredictionSettings()

    Gets estimated precision, estimated coverage, estimated recall values from the ML Solutions [ml_solution] table and records from the Class Confidence [ml_class] table.

    Table 3. Parameters
    Name Type Description
    None
    Table 4. Returns
    Type Description
    Object Returns prediction settings for each class. Data includes precision, coverage, recall, and distribution values of all classes included in the trained model from the ML Solutions [ml_solution] table. For details, see Predictive model components.
    {
  "<class name>": {Object}
}
    <Object>.<class name> Training statistics data from the Class Confidence [ml_class] table. For more information, see Configuring target metrics.

    Data type: Object

    {
  "precision": "String",
  "coverage": "String",
  "recall": "String"
}
    <Object>.<class name>.precision Estimated solution precision metric for this class.

    Data type: String (numerical value)
    <Object>.<class name>.coverage Estimated solution coverage metric for this class.

    Data type: String (numerical value)
    <Object>.<class name>.recall Estimated solution recall metric for this class.

    Data type: String (numerical value)

    The following example shows how to get prediction settings of an active solution version.

    var mlSolution = sn_ml.ClassificationSolutionStore.get('ml_incident_categorization');

gs.print(JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getPredictionSettings()), null, 2));

    Output:

    {
  "solutionSettings": {
    "precision": "61.69",
    "coverage": "66.75",
    "recall": "57.54"
  },
  "classSettings": {
    "Approvals": {
      "precision": "100",
      "coverage": "0",
      "recall": "0"
    },
    "Authentication": {
      "precision": "38.71",
      "coverage": "98.44",
      "recall": "56.25"
    },
    "Automation": {
      "precision": "100",
      "coverage": "0",
      "recall": "0"
    }, ...

    ClassificationSolutionVersion - getProperties()

    Gets solution object properties and version number.

    Table 5. Parameters
    Name Type Description
    None
    Table 6. Returns
    Type Description
    Object Contents of the Dataset and ClassificationSolution version details. Results vary by object property setup.
    {
  "algorithmConfig": {
    "algorithm": "String",
    "targetClassRecall": "String"
  },
  "datasetProperties": {Object},
  "domainName": "String",
  "encoder": {Object},
  "groupByFieldName": "String",   
  "inputFieldNames": [Array],
  "isActive": Boolean,
  "label": "String",
  "name": "String",
  "predictedFieldName": "String",
  "processingLanguage": "String",
  "scope": "String",
  "stopwords": [Array],
  "stopwords": [Array],
  "trainingFrequency": "String",
  "versionNumber": "Number"
}
    <Object>.algorithmConfig Method for encoding the solution.

    Data type: Object
    <Object>.algorithmConfig.algorithm Name of the encoding algorithm for training this solution.
    Possible values:
    • xgboost: XGBoost encoding to optimize the training.
    • logisticRegression: Method using the logistic regression model for categorical targets such as nominal or ordinal.

    Data type: String
    <Object>.algorithmConfig.targetClassRecall Class recall parameter to steer a solution's training to bias a specific class. The recall value is a number between 0 and 100 representing a percentage.

    Data type: String
    <Object>.datasetProperties

    Lists the properties of the DatasetDefinition() object associated with the solution.

    Data type: Object

    {
  "encodedQuery": "String",
  "fieldDetails": [Array],
  "fieldNames": [Array],
  "tableName": "String"
}
    <Object>.datasetProperties.tableName Name of the table for the dataset. For example, "tableName" : "Incident".

    Data type: String
    <Object>.datasetProperties.fieldNames List of field names from the specified table as strings. For example, "fieldNames" : ["short_description", "priority"].

    Data type: Array
    <Object>.datasetProperties.fieldNames.fieldDetails List of JavaScript objects that specify field properties.

    Data type: Array of Objects

    [
  {
    "name": "String",
    "type": "String"
  }
]
    <Object>.datasetProperties.fieldNames.fieldDetails.<object>.name Name of the field defining the type of information to restrict this dataset to.

    Data type: String
    <Object>.datasetProperties.fieldDetails.<object>.type Machine-learning field type.

    Data type: String
    <Object>.datasetProperties.fieldDetails.encodedQuery Encoded query string in standard Glide format. See Encoded query strings.

    Data type: String
    <Object>.domainName Domain name associated with this dataset. See Domain separation and Predictive Intelligence.

    Data type: String
    <Object>.encoder Encoder object assigned to this solution. See Encoder - Encoder(Object config).

    Data type: Object
    <Object>.groupByFieldName Field name by which the system groups records to build classification solutions.

    Data type: String
    <Object>.inputFieldNames List of input field names as strings. The model uses these fields used to make predictions.

    Data type: String
    <Object>.isActive Flag that indicates whether this version is active.
    Valid values:
    • true: Version is active.
    • false: Version is not active.

    Data type: String
    <Object>.label Identifies the prediction task. 
    {
  "label": "my first prediction"
}

    Data type: String
    <Object>.name System-assigned name.

    Data type: String
    <Object>.predictedFieldName Identifies a field to be trained for predictability.

    Data type: String
    <Object>.processingLanguage Processing language in two-letter ISO 639-1 language code format.

    Data type: String
    <Object>.scope Object scope. Currently the only valid value is global.

    Data type: String
    <Object>.stopwords Optional. Preset list of strings that the system automatically generates based on the language property setting. For details, see Create a custom stopwords list.

    Data type: Array
    <Object>.trainingFrequency The frequency to retrain the model.
    Possible values:
    • every_30_days
    • every_60_days
    • every_90_days
    • every_120_days
    • every_180_days
    • run_once
    Default: run_once

    Data type: String
    <Object>.versionNumber Version number of the ClassificationSolution object.

    Data type: String

    The following example gets properties of the active object version in the store.

    // Get properties
var mlSolution = sn_ml.ClassificationSolutionStore.get('ml_incident_categorization');

gs.print(JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getProperties()), null, 2));

    Output:

    *** Script: {
  "datasetProperties": {
    "encodedQuery": "activeANYTHING^EQ",
    "fieldNames": [
      "short_description",
      "category"
    ],
    "tableName": "incident"
  },
  "domainName": "global",
  "inputFieldNames": [
    "short_description"
  ],
  "isActive": "true",
  "label": "Incident Categorization_Trainer",
  "name": "ml_incident_categorization",
  "predictedFieldName": "category",
  "processingLanguage": "en",
  "stopwords": [
    "Default English Stopwords"
  ],
  "versionNumber": "1"
}

    ClassificationSolutionVersion - getStatus(Boolean includeDetails)

    Gets training completion status.

    Table 7. Parameters
    Name Type Description
    includeDetails Boolean Flag that indicates whether to return status details.
    Valid values:
    • true: Return additional details.
    • false: Don't return additional details.

    Default: False
    Table 8. Returns
    Type Description
    Object JavaScript object containing training status information for a ClassificationSolution object.
    {
  "state": "String",
  "percentComplete": "Number as a String",
  "hasJobEnded": "Boolean value as a String",
  "details": {Object}
}
    <Object>.state Training completion state. If the training job reaches a terminal state, the job does not leave that state. If the state is terminal, the hasJobEnded property is set to true.
    Possible values:
    • fetching_files_for_training
    • preparing_data
    • retry
    • solution_cancelled (terminal)
    • solution_complete (terminal)
    • solution_error (terminal)
    • solution_incomplete
    • training_request_received
    • training_request_timed_out (terminal)
    • training_solution
    • uploading_solution
    • waiting_for_training

    Data type: String
    <Object>.hasJobEnded Flag that indicates whether training is complete.
    Valid values:
    • true: Training is complete.
    • false: Training is incomplete.

    Data type: Boolean value as a String
    <Object>.percentComplete Training percent complete. If the completion percentage is less than 100, the job might be in a terminal state. For example, if training times out.

    Data type: Number as a String

    Range: 0 thru 100
    <Object>.details Object containing a list of additional training details.

    Data type: Object

    The following example shows a successful result with training complete.

    // Get status
var mlSolution = sn_ml.ClassificationSolutionStore.get('ml_incident_categorization');

gs.print(JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getStatus(true), null, 2)));

    Output:

    {
 "state":"solution_complete",
 "percentComplete":"100",
 "hasJobEnded":"true",
 "details":{"stepLabel":"Solution Complete"} // This information is only returned if getStatus(true);
}

    The following example shows an unsuccessful result with training complete.

    // Get status
var solutionName = 'ml_x_snc_global_global_classification_solution';
var mlSolution = sn_ml.ClassificationSolutionStore.get(solutionName);
var trainingStatus = mlSolution.getLatestVersion().getStatus();

gs.print(JSON.stringify(JSON.parse(trainingStatus), null, 2));

    Output:

    {
 "state":"solution_error",
 "percentComplete":"100",
 "hasJobEnded":"true"
}

    ClassificationSolutionVersion - getTrainingStatistics()

    Gets all the training statistics for a given solution.

    Table 9. Parameters
    Name Type Description
    None
    Table 10. Returns
    Type Description
    Object JavaScript object with statistics for each class included in training and values for each class that was excluded from training. For details, see Predictive model components.
    {
  "includedClasses": {Object},
  "excludedClasses": {Object}
}
    <Object>.includedClasses Object containing precision, coverage, recall, and distribution values of each class in the trained model.

    Data type: Object

    
  "includedClasses": {
    "<class name>": {
      "distribution": "String",
      "statistics": [Array]
    },
    <Object>.includedClasses.<class name>.distribution Value of the outcome probability distribution for this class.

    Data type: String
    <Object>.includedClasses.<class name>.statistics List of objects providing training statistics data. For more information, see Configuring target metrics.

    Data type: Array of Objects

    [
  {
    "coverage": "String",
    "precision": "String",
    "recall": "String",
    "selected": "String"
  }
]
    <Object>.includedClasses.<class name>.statistics.coverage Estimated solution coverage metric for this class.

    Data type: String (numerical value)
    <Object>.includedClasses.<class name>.statistics.precision Estimated solution precision metric for this class.

    Data type: String (numerical value)
    <Object>.includedClasses.<class name>.statistics.recall Estimated solution recall metric for this class.

    Data type: String (numerical value)
    <Object>.includedClasses.<class name>.statistics.selected Flag that indicates whether this class contains records included in solution training.
    Valid values:
    • true: This class contains records selected for training the solution.
    • false: This class is excluded from training.

    Data type: String (Boolean value)

    Default: false
    <Object>.excludedClasses Distribution and row count of all the classes excluded from training.

    Data type: Object

    
  "excludedClasses": {
    "<class name>": {
      "distribution": "0.11",
      "rowCount": "9"
    }
    <Object>.excludedClasses.<class name>.distribution Value of the outcome probability distribution for this class.

    Data type: String
    <Object>.excludedClasses.<class name>.rowCount Number of rows excluded from training.

    Data type: String (numerical value)

    The following example shows how to get training statistics from the active solution.

    // Get training stats
var mlSolution = sn_ml.ClassificationSolutionStore.get('ml_incident_categorization');

gs.print(JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getTrainingStatistics()), null, 2));

    Output:

    {
  "includedClasses": {
    "Approvals": {
      "distribution": "0.43",
      "statistics": [
        {
          "precision": "100",
          "coverage": "0",
          "recall": "0",
          "selected": "true"
        }
      ]
    }, 
    "Authentication": {
      "distribution": "4.3",
      "statistics": [
        {
          "precision": "39.33",
          "coverage": "95.31",
          "recall": "54.69",
          "selected": "false"
        },
        {
          "precision": "100",
          "coverage": "0",
          "recall": "0",
          "selected": "false"
        },
     ...
    }
    ...
  "excludedClasses": {
    "ACE": {
      "distribution": "0.11",
      "rowCount": "9"
    },
    "AHA": {
      "distribution": "0.01",
      "rowCount": "1"
    }, 
    ...
}

    ClassificationSolutionVersion - getVersionNumber()

    Gets the version number of a solution object.

    Table 11. Parameters
    Name Type Description
    None
    Table 12. Returns
    Type Description
    String Version number.

    The following example shows how to get a version number.

    // Get version number
var mlSolution = sn_ml.ClassificationSolutionStore.get('ml_incident_categorization');

gs.print("Version number: "+JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getVersionNumber()), null, 2));

    Output:

    Version number: 1

    ClassificationSolutionVersion - predict(Object input, Object options)

    Gets the input data for a prediction.

    Table 13. Parameters
    Name Type Description
    input Object GlideRecord or array of JSON objects containing field names and values as key-value pairs.
    options Object Optional values for filtering prediction results.
    {
  "apply_threshold": Boolean,
  "top_n": Number
}
    options.apply_threshold Boolean Flag that indicates whether to check the threshold value for the solution and apply it to the result set.
    Valid values:
    • true: Return results in which confidence is greater than threshold.
    • false: Return all results.

    Default: True
    options.top_n Number If provided, returns the top results, up to the specified number of predictions.
    Table 14. Returns
    Type Description
    Object JSON object containing the prediction results sorted by sys_id or record_number. 
    {
    <identifier>: [Array]
}
    <Object>.<identifier> List of objects with details for each prediction result.

    Data type: Array of Objects

    <identifier>: [
  {
    "confidence": Number,
    "predictedSysId": "String",
    "predictedValue": "String", 
    "threshold": Number
  }
]
    <Object>.<identifier>.<object>.confidence Value of the confidence associated with the prediction. For example, 53.84.

    Data type: Number
    <Object>.<identifier>.<object>.predictedSysId The sys_id of the predicted value. Results can be from any table on which information is being predicted.

    Data type: String
    <Object>.<identifier>.<object>.predictedValue Value representing the prediction result.

    Data type: String
    <Object>.<identifier>.<object>.threshold Value of the configured threshold associated with the prediction.

    Data type: Number

    The following example shows how to display prediction results for a predict() method that takes a GlideRecord by sys_id for input and includes optional parameters to restrict to top three results and exclude the threshold value.

    var mlSolution = sn_ml.ClassificationSolutionStore.get('ml_incident_categorization');

// single GlideRecord input
var input = new GlideRecord("incident");
input.get("<sys_id>");

// configure optional parameters
var options = {};
options.top_n = 3;
options.apply_threshold = false;

var results = mlSolution.getVersion(1).predict(input, options);
// pretty print JSON results
gs.print(JSON.stringify(JSON.parse(results), null, 2));

    Output:

    {
  "<sys_id/gr>": [
    {
      "confidence": 62.10782320780268,
      "threshold": 20.36,
      "predictedValue": "Clone Issues",
      "predictedSysId": ""
    },
    {
      "confidence": 6.945237375770391,
      "threshold": 16.63,
      "predictedValue": "Instance Administration",
      "predictedSysId": ""
    },
    {
      "confidence": 5.321061076300759,
      "threshold": 23.7,
      "predictedValue": "Administration",
      "predictedSysId": ""
    }
  ]
}

    The following example shows how to display prediction results for a predict() method that takes an array of field names as key-value pairs for input and includes optional parameters to restrict to top three results and exclude the threshold value.

    var mlSolution = sn_ml.ClassificationSolutionStore.get('ml_incident_categorization');

// key-value pairs input
var input = [{"short_description":"my email is not working"}, {short_description:"need help with password"}];

// configure optional parameters
var options = {};
options.top_n = 3;
options.apply_threshold = false;
var results = mlSolution.predict(input, options);

// pretty print JSON results
gs.print(JSON.stringify(JSON.parse(results), null, 2));

    Output:

    {
  "1": [
    {
      "confidence": 37.5023032262591,
      "threshold": 10.72,
      "predictedValue": "Authentication",
      "predictedSysId": ""
    },
    {
      "confidence": 24.439964862166583,
      "threshold": 23.7,
      "predictedValue": "Administration",
      "predictedSysId": ""
    },
    {
      "confidence": 11.736320486031047,
      "threshold": 100,
      "predictedValue": "Security",
      "predictedSysId": ""
    }
  ],
  "2": [
    {
      "confidence": 99,
      "threshold": 17.77,
      "predictedValue": "Email",
      "predictedSysId": ""
    },
    {
      "confidence": 3.182137005157543,
      "threshold": 10.72,
      "predictedValue": "Authentication",
      "predictedSysId": ""
    },
    {
      "confidence": 2.8773826570713514,
      "threshold": -1,
      "predictedValue": "Email (I/f)",
      "predictedSysId": ""
    }
  ]
}

    ClassificationSolutionVersion - setPredictionSettings(Object options)

    Sets precision, coverage, or recall values at solution level or class level.

    Table 15. Parameters
    Name Type Description
    options Object Metric configuration values. For information about these features, see Configuring target metrics.
    {  	 
   "metricName" : "String",
   "metricValue" : "String",
   "className" : "String"
}
    options.metricName String Name of the metric to set.
    Valid values:
    • coverage
    • precision
    • recall
    options.metricValue String Numeric value to assign to the metric.
    options.className String Optional. Name of the class to restrict results to. Use the getTrainingStatistics() method to retrieve a complete list of classes for a solution.
    Table 16. Returns
    Type Description
    None

    The following example shows how to set a precision metric to 89.5 for a class named Clone Issues.

    var mlSolution = sn_ml.ClassificationSolutionStore.get('ml_x_snc_global_global_classification');
var input = {"metricName" : "precision", "metricValue" : "89.5", "className" : "Clone Issues"};

mlSolution.getActiveVersion().setTrainingStatistics(input);