SimilaritySolutionVersion - Global

The SimilaritySolutionVersion 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 is used for working with solution versions based on SimilaritySolution API objects in the SimilaritySolution 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 SimilaritySolution methods:

• getActiveVersion()
• getAllVersions()
• getLatestVersion()
• getVersion()

SimilaritySolutionVersion - getProperties()

Gets solution object properties and version number.

表 : 1. Parameters

Name	Type	Description
None

表 : 2. Returns

Type	Description
Object	Contents of the Dataset and SimilaritySolution version details. Results vary by object property setup. { "domainName": "String", "isActive": "String", "label": "String", "lookupDatasetProperties": {Object}, "name": "String", "predictedFieldName": "String", "processingLanguage": "String", "scope": "String", "stopwords": [Array], "testDatasetProperties": {Object}, "trainingFrequency": "String", "updateFrequency": "String", "versionNumber": "String" }
<Object>.domainName	Domain name associated with this dataset. See Domain separation and Predictive Intelligence. 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>.lookupDatasetProperties	Details of the DatasetDefinition() object used as the lookup set. { "encodedQuery": "String", "fieldDetails": [Array], "fieldNames": [Array], "tableName": "String" } Data type: Object.
<Object>.lookupDatasetProperties.tableName	Name of the table for the dataset. For example, "tableName" : "Incident". Data type: String.
<Object>.lookupDatasetProperties.fieldNames	List of field names from the specified table as strings. For example, "fieldNames" : ["short_description", "priority"]. Data type: Array.
<Object>.lookupDatasetProperties.fieldNames.fieldDetails	List of JavaScript objects that specify field properties. [ { "name": "String", "type": "String" } ] Data type: Array.
<Object>.lookupDatasetProperties.fieldNames.fieldDetails.<object>.name	Name of the field defining the type of information to restrict this dataset to. Data type: String.
<Object>.lookupDatasetProperties.fieldDetails.<object>.type	Machine-learning field type. Data type: String.
<Object>.lookupDatasetProperties.fieldDetails.encodedQuery	Encoded query string in standard Glide format. See Encoded query strings. 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>.testDatasetProperties	Details of the DatasetDefinition() object used to retrieve similarities between results searched in this model and results found in the lookupDataset. { "encodedQuery": "String", "fieldDetails": [Array], "fieldNames": [Array], "tableName": "String" } Data type: Object.
<Object>.testDatasetProperties.tableName	Name of the table for the dataset. For example, "tableName" : "Incident". Data type: String.
<Object>.testDatasetProperties.fieldNames	List of field names from the specified table as strings. For example, "fieldNames" : ["short_description", "priority"]. Data type: Array.
<Object>.testDatasetProperties.fieldNames.fieldDetails	List of JavaScript objects that specify field properties. [ { "name": "String", "type": "String" } ] Data type: Array.
<Object>.testDatasetProperties.fieldNames.fieldDetails.<object>.name	Name of the field defining the type of information to restrict this dataset to. Data type: String.
<Object>.testDatasetProperties.fieldDetails.<object>.type	Machine-learning field type. Data type: String.
<Object>.testDatasetProperties.fieldDetails.encodedQuery	Encoded query string in standard Glide format. See Encoded query strings. Data type: String.
<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>.updateFrequency	The frequency at which the model for the solution definition must be rebuilt. Possible values: do_not_update every_1_day every_1_hour every_6_hours every_12_hours every_1_minute every_15_minutes every_30_minutes Default: do_not_update Datatype: String
<Object>.versionNumber	Version number of the SimilaritySolution object. Data type: String.

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

// Get properties
var mlSolution = sn_ml.SimilaritySolutionStore.get('ml_x_snc_global_similarity_solution');

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

Output:

*** Script: {
  "domainName": "global",
  "encoderProperties": {
    "datasetsProperties": [],
    "name": "wordCorpusA"
  },
  "isActive": "true",
  "label": "similarity",
  "lookupDatasetProperties": {
    "encodedQuery": "",
    "fieldNames": [
      "short_description"
    ],
    "tableName": "incident"
  },
  "name": "ml_x_snc_global_global_similarity",
  "processingLanguage": "en",
  "stopwords": [
    "Default English Stopwords"
  ],
  "testDatasetProperties": {
    "fieldNames": [
      "short_description"
    ],
    "tableName": "incident"
  },
  "versionNumber": "3"
}

SimilaritySolutionVersion - getStatus(Boolean includeDetails)

Gets training completion status.

表 : 3. 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

表 : 4. Returns

Type	Description
Object	JavaScript object containing training status information for a SimilaritySolution 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.SimilaritySolutionStore.get('ml_x_snc_global_similarity_solution');

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_similarity_solution';
var mlSolution = sn_ml.SimilaritySolutionStore.get(solutionName);
var trainingStatus = JSON.parse(mlSolution.getLatestVersion().getStatus());

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

Output:

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

SimilaritySolutionVersion - getVersionNumber()

Gets the version number of a solution object.

表 : 5. Parameters

Name	Type	Description
None

表 : 6. Returns

Type	Description
String	Version number.

The following example shows how to get a version number.

// Get version number
var mlSolution = sn_ml.SimilaritySolutionStore.get('ml_x_snc_global_similarity_solution');

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

Output:

Version number: 1

SimilaritySolutionVersion - predict(Object input, Object options)

Gets the input data for a prediction.

表 : 7. 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.

表 : 8. 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.SimilaritySolutionStore.get('ml_x_snc_global_similarity_solution');

// 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));

{
        "<sys_id/now_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.SimilaritySolutionStore.get("ml_x_snc_global_similarity_solution");
// 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));

{
  "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": ""
    }
  ]
}