ClusteringSolutionVersion - Global

  • Release version: Australia
  • Updated March 12, 2026
  • 14 minutes to read

    • The ClusteringSolutionVersion 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.

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

    ClusteringSolutionVersion - cancelUpdateJob()

    Cancels an update job on a trainer.

    Table 1. Parameters
    Name Type Description
    None
    Table 2. Returns
    Type Description
    None

    The following example shows how to cancel an active training job that has been submitted using the submitTrainingJob() method.

    var myCluster = new sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution");
var mlSolutionVersion = myCluster.getActiveVersion();

mlSolutionVersion.cancelUpdateJob();

    ClusteringSolutionVersion - deleteClusterAssignments(Object options)

    Deletes cluster assignments from rows by position in table sequence or GlideDateTime.

    Table 3. Parameters
    Name Type Description
    options Object Object defining one option for deleting cluster assignments.
    Note:
    Only one delete option is valid.
    options.updatedUntil String Deletes rows for clusters with updated_since values occurring before this value. Format must be provided as GlideDateTime.
    { "updatedUntil" : "String" }
    options.sequenceUntil String Deletes rows for clusters with insert_sequence values occurring before this value in the ML Cluster Detail [ml_cluster_detail] table. The sequence position starting point value is 1. 
    { "sequenceUntil" : Number }
    Table 4. Returns
    Type Description
    Number Number of rows deleted from the ML Cluster Detail [ml_cluster_detail] table.

    The following example shows how to delete rows for clusters with updated_since time preceding '2020-06-28 02:50:53'.

    var mlSolution = sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution");

var mlSolutionVersion = mlSolution.getActiveVersion();

var options = {};
options.updatedUntil = '2020-06-28 02:50:53';

var results = mlSolutionVersion.deleteClusterAssignments(options);

gs.print("Number of deleted rows: "+results);

    Output:

    Number of deleted rows: 6417

    The following example shows how to delete rows for clusters with updated_since that are sequentially positioned prior to 1000.

    var mlSolution = sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution");

var mlSolutionVersion = mlSolution.getActiveVersion();

var options = {};
options.sequenceUntil = 1000;

var results = mlSolutionVersion.deleteClusterAssignments(options);

gs.print("Number of deleted rows: "+results);

    Output:

    Number of deleted rows: 999

    ClusteringSolutionVersion - getClusterAssignments(Object options)

    Gets assignments for a clustering solution.

    Table 5. Parameters
    Name Type Description
    options Object Values to use to narrow down the returned results by group, level, system update times, and table row number within a clustering solution. Minimum of one argument must be specified.
    {
     "cluster_id": "String",
     "group_by": "String",
     "limit": Number,
     "sequenceSince": Number,
     "sequenceUntil": Number,
     "topNPerCluster": Number,
     "updatedSince": "String",
     "updatedUntil": "String"
}
    options.cluster_id String Optional. Cluster ID of a trained solution in the Cluster Summary [ml_cluster_summary] table.
    options.group_by String Optional. Identifies the segmentation field for which to retrieve cluster memberships, for example, assignment_group.

    This field provides the same grouping as options provided in the Use Group By check box in the Clustering Definition form. The information provided varies based on the table selected in the Table field. For more information, see Create and train a clustering solution .
    options.limit Number Optional. Maximum number of cluster assignments to retrieve.
    options.sequenceSince Number Starting position in a table sequence. Returns information for clusters with insert_sequence enabled and positioned after this value in the ML Cluster Detail [ml_cluster_detail] table. The sequence position starting point value is 1.
    options.sequenceUntil Number Returns assignments for clusters with insert_sequence values occurring before this value in the ML Cluster Detail [ml_cluster_detail] table. The sequence position starting point value is 1.
    options.topNPerCluster Number Number of top results to receive for each cluster.
    options.updatedSince String Optional. Date and time. Returns information for clusters with sys_updated_on after the value provided in GlideDateTime.
    options.updatedUntil String Optional. Date and time. Returns information for clusters with sys_updated_on before the value provided in GlideDateTime.
    Table 6. Returns
    Type Description
    Array List of objects containing cluster information in increasing order by cluster_id.
    [
    {
       "cluster_id": "String",
       "group_by": "String",
       "rec_display_id": "String",
       "rec_sys_id": "String"
     }
]
    <object>.cluster_id Unique cluster number within a solution of clusters.
    <object>.group_by If grouped, name of the segmentation field associated with this cluster.
    <object>.rec_display_id Record type and number.
    <object>.rec_sys_id Record sys_id.

    The following example shows how to use the options object to filter clustering results.

    var mlSolution = sn_ml.ClusteringSolutionStore.get("solution_name");

var mlSolutionVersion = mlSolution.getActiveVersion();

var options = {};
options.clusterId = 56;
options.topNPerCluster = 10;
options.updatedUntil = '2020-01-17 23:16:14'; 
options.updatedSince = '2020-01-17 23:16:13'; 
options.sequenceUntil = 1000; 
options.sequenceSince = 1100; 
options.limit = 100;

var results = mlSolutionVersion.getClusterAssignments(options)

gs.print(results);

    Output:

    [{"cluster_id":"1","rec_display_id":"Incident": "INC0014483","rec_sys_id":"04e33e7adb401300864adfea5e961900","group_by":"network"},
 {"cluster_id":"1","rec_display_id":"Incident": "INC0011133","rec_sys_id":"5bd23af2db401300864adfea5e96194d","group_by":"network"}]

    ClusteringSolutionVersion - getClusterInfo(Object options)

    Gets information for a specified clustering solution in the store. The purity measurement provides insights as a percentage for the clustering fields on which the purity is based.

    Table 7. Parameters
    Name Type Description
    options Object Optional. Object containing properties that enable filtering results within a clustering solution.
    {
  "clusterId": "String",     
  "groupBy": "String",
  "limit": "String",
  "recSysId": "String",
  "sequenceSince": Number,
  "sequenceUntil": Number,
  "updatedSince": "String",
  "updatedUntil": "String"
}

    Default: Return cluster memberships for all clusters.
    options.clusterId String Optional. Cluster ID of a trained solution in the Cluster Summary [ml_cluster_summary] table.
    options.groupBy String Optional. Identifies the segmentation field for which to retrieve cluster memberships, for example, assignment_group.

    This field provides the same grouping as options provided in the Use Group By check box in the Clustering Definition form. The information provided varies based on the table selected in the Table field. For more information, see Create and train a clustering solution .
    options.limit Number Optional. Maximum number of cluster assignments to retrieve.
    options.recSysId String Optional. Sys_id of a record by which to find cluster information.
    options.sequenceSince Number Starting position in a table sequence. Returns information for clusters with insert_sequence enabled and positioned after this value in the ML Cluster Detail [ml_cluster_detail] table. The sequence position starting point value is 1.
    options.sequenceUntil Number Optional. Ending position in a table sequence. Returns assignments for clusters with insert_sequence values occurring before this value in the ML Cluster Detail [ml_cluster_detail] table. The sequence position starting point value is 1.
    options.updatedSince String Optional. Date and time. Returns information for clusters with sys_updated_on after the value provided in GlideDateTime format.
    options.updatedUntil String Optional. Date and time. Returns information for clusters with sys_updated_on before the value provided in GlideDateTime.
    Table 8. Returns
    Type Description
    Array List of objects containing cluster information.
    [
  {   
    "cluster_concept": "String",
    "cluster_id": "String",
    "cluster_quality": "String",
    "cluster_size": "String",
    "group_by": "String",
    "insert_sequence": "String",
    "purity": "String",
    "sys_updated_on": "String"
  }
]
    <object>.cluster_concept Set of words that describe the cluster in descending order of frequency.

    Data type: String
    <object>.cluster_id Unique cluster number within a solution of clusters.
    <object>.cluster_quality Number from 0 to 100. Higher numbers indicate higher cluster density.

    Data type: String
    <object>.cluster_size Number of records in a cluster.

    Data type: String
    <object>.group_by If grouped, name of the segmentation field associated with this cluster.

    Data type: String
    <object>.insert_sequence Sequential position number of the cluster in the Cluster Summary [ml_cluster_summary] table.

    Data type: String
    <object>.purity Percentage value representing the purity of cluster quality.
    <object>.sys_updated_on System GlideDateTime value representing the date and time at which this cluster was last updated.

    Data type: String

    The following example shows how to set the options object parameter and print the filtered cluster results.

    var mlSolution = sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution");

var mlSolutionVersion = mlSolution.getActiveVersion();

var options = {};
options.updatedSince = '2020-05-28 02:09:53'; 
options.updatedUntil = '2020-05-28 03:15:00';
options.sequenceSince = 1;
options.limit = 10;

var results = mlSolutionVersion.getClusterInfo(options);

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

    Output:

    [
  {
    "cluster_id": "1",
    "cluster_quality": "100",
    "cluster_size": "17",
    "purity": "",
    "insert_sequence": "8",
    "group_by": "VPN   Customer",
    "sys_updated_on": "2020-05-28 02:09:53",
    "cluster_concept": "vpn instance connection ldap user log unable usability tunnel"
  },
  {
    "cluster_id": "1",
    "cluster_quality": "100",
    "cluster_size": "10",
    "purity": "",
    "insert_sequence": "24",
    "group_by": "Live Feed",
    "sys_updated_on": "2020-05-28 02:09:53",
    "cluster_concept": "feed live user note work disable group default usability sort"
  },
  {
    "cluster_id": "1",
    "cluster_quality": "100",
    "cluster_size": "18",
    "purity": "",
    "insert_sequence": "40",
    "group_by": "Integrations",
    "sys_updated_on": "2020-05-28 02:09:53",
    "cluster_concept": "integrate usability certificate error"
  },
...
]

    ClusteringSolutionVersion - getProperties()

    Gets solution object properties and version number.

    Table 9. Parameters
    Name Type Description
    None
    Table 10. Returns
    Type Description
    Object Contents of the Dataset and ClusteringSolution version details. Results vary by object property setup.
    {
  "algorithmConfig": {Object},
  "datasetProperties": {Object},
  "domainName": "String",
  "groupByFieldName": "String", 
  "inputFieldNames": [Array],
  "isActive": Boolean,
  "label": "String",
  "minRecordsPerCluster": Number,
  "name": "String",
  "processingLanguage": "String",
  "scope": "String",
  "stopwords": [Array],
  "trainingFrequency": "String",
  "updateFrequency": "String",
  "versionNumber": Number
}
    <Object>.algorithmConfig JavaScript object containing algorithm configuration properties. Property results vary by the value set in the algorithm property.

    Data type: Object

    'algorithmConfig' : {
  "algorithm": "String",  
  // See algorithmConfig.algorithm setting description for property settings based on algorithm
}
    <Object>.algorithmConfig.algorithm Method for encoding your solution.
    Properties for dbscan:
    'algorithmConfig': {
  "algorithm": "dbscan",
  "distanceMetric": "String",
  "epsilon": Number,
  "minimumNeighbours": Number
}
    Properties for kmeans:
    'algorithmConfig': {
  "algorithm": "kmeans",
  "targetCoverage": Number
}

    Data type: String
    <Object>.algorithmConfig.distanceMetric DBSCAN algorithm only. Distance metric to scan for similar data objects.

    Data type: String
    <Object>.algorithmConfig.epsilon DBSCAN algorithm only. Decimal value between 0 and 1 representing the size of the neighborhood search radius.

    Data type: Number
    <Object>.algorithmConfig.minimumNeighbours DBSCAN algorithm only. Minimum number of neighbors required in a point to be a part of a cluster. For levenshteinDistance the value must be 1 so that no points are excluded from the dataset.

    Data type: Number
    <Object>.algorithmConfig.targetCoverage K-means algorithm only. Percentile field to filter out records that are less similar to each other.

    Data type: Number
    <Object>.datasetProperties

    Lists the properties of the DatatsetDefinition object associated with the solution.

    {
  "encodedQuery": "String",
  "fieldDetails": [Array],
  "fieldNames": [Array],
  "tableName": "String"
}

    Data type: Object
    <Object>.datasetProperties.encodedQuery Encoded query string in the standard platform format. See Encoded query strings.

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

    Data type: Array of Objects

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

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

    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.tableName Name of the table for the dataset. For example, "tableName" : "Incident".

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

    Type: String
    Object.groupByFieldName Field name by which the system groups records into one or more clusters.

    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>.minRecordsPerCluster Minimum number of records to allow in any cluster.

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

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

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

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

    // Get properties
var mlSolution = sn_ml.ClusteringSolutionStore.get('ml_x_snc_global_global_clustering_solution');

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

    Output:

    *** Script: {
  "algorithmConfig": {
    "algorithm": "kmeans",
    "targetCoverage": "90"
  },
  "datasetProperties": {
    "tableName": "incident",
    "fieldNames": [
      "category",
      "short_description",
      "state",
      "description"
    ],
    "encodedQuery": "activeANYTHING"
  },
  "domainName": "global",
  "groupByFieldName": "category",
  "inputFieldNames": [
    "short_description"
  ],
  "isActive": "true",
  "label": "clustering solution",
  "minRecordsPerCluster": 2,
  "name": "ml_x_snc_global_global_clustering_solution",
  "processingLanguage": "en",
  "stopwords": [
    "Default English Stopwords"
  ],
  "updateFrequency": "do_not_update",
  "versionNumber": "1"
}

    ClusteringSolutionVersion - getStatus(Boolean includeDetails)

    Gets training completion status.

    Table 11. 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 12. Returns
    Type Description
    Object JavaScript object containing training status information for a ClusteringSolution 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.ClusteringSolutionStore.get('ml_x_snc_global_global_cluster_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_cluster_solution';
var mlSolution = sn_ml.ClusteringSolutionStore.get(solutionName);
var trainingStatus = mlSolution.getLatestVersion().getStatus();

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

    Output:

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

    ClusteringSolutionVersion - getTopNPurityInfo(Object options)

    Gets the top purity results for a clustering solution. The purity measurement provides insights as a percentage for the clustering fields on which the purity is based.

    Table 13. Parameters
    Name Type Description
    options Object Options that determine the number and format of the top cluster purity results.
    {
  "clusterIds": [Array],
  "groupBy": [Array],
  "purityFields": [Array],
  "topN": Number,
  "topNFields": Number
}
    options.clusterIds Array Optional. List of cluster IDs provided as strings. A cluster ID is provided in the Cluster Summary [ml_cluster_summary] table. If provided, this method returns purity cluster information for each specified cluster.

    Default: This method returns purity information for all clusters.
    options.groupBy Array Optional. List of group_by field strings from your table to help the system identify the class which is most frequent in the cluster. If provided, returns purity information for cluster solutions using group_by fields. The Cluster Summary [ml_cluster_summary] table lists clusters and any associated Group by values.

    This field only applies to clusters that use group by in the clustering definition. Eligible fields are listed in the Table field. For details on the group by feature, refer to Create and train a clustering solution.
    options.purityFields Array Optional. List of purity field strings. If provided, this method only returns information for these purity fields. You can view purity values for a cluster in the Cluster Summary [ml_cluster_summary] table lists.
    Note:
    If both purity_fields and top_n_fields are provided, this method returns top_n_fields first, then selects fields from purity_fields.

    Default: Return purity information for all purity fields saved for the cluster.
    options.topN Number Optional. Restricts the number of predictions to return to the highest values for each purity field.

    Maximum value: 10

    Default: Return all purity information for each purity field.
    options.topNFields Number Optional. Restricts the number of purity fields returned to fields with the highest purity for each cluster.

    Maximum value: 10

    Default: Return all fields in the cluster.
    Table 14. Returns
    Type Description
    String JSON-formatted string containing a list of clusters with purity fields and details.
    Note:
    Results vary based on settings made in the options input parameter.

    The following information illustrates how cluster purity results are sorted and categorized. Refer to the example for actual output.

    {
  "<clusterID>":[
    // List sorted by purity per field
    { "<fieldName>":[
      // List sorted by purity per field value
      {"<field_val1_1>":"<purity>"},
        // Additional field values
    ]},
    // Additional fields
  ],	  
  // Additional clusters
}
    String.<clusterID> List of clusters arranged in descending order by purity value per cluster.

    Data type: Array
    String.<clusterID>.<field> List of objects representing purity fields arranged in descending order by purity value per field. The options.top_n_fields input object parameter property determines the number of fields returned.
    "<field>":[{"<field_val>":"<purity>"}]}

    Data type: Array
    String.<clusterID>.<field>.<values> List of objects containing field value and purity. For example, {"priority":[{"5":"100"}]} is a priority field with a score of 5 and a purity value of 100 percent. Results list in descending order by purity percentage. The options.top_n input object parameter property determines the number of results returned.

    Data type: Array

    The following example shows how to get the top two purity results for the category field in specific cluster solutions.

    var solution = new GlideRecord('ml_solution');
solution.addQuery('sys_id', '<clustering_solution_sys_id>');
solution.addQuery('active', 'true');
solution.query();

while (solution.next()) {

  var options = {};
  options.clusterIds = ['1', '3', '5'];
  options.purityFields = ['category'];
  options.topN = '2';
  options.topNFields = '2';

  var clustering = new sn_ml.ClusteringSolutionVersion(solution);
  var results = clustering.getTopNPurityInfo(options);

  gs.info(results);
}

    Output displays purity insights based on the settings provided in the options parameter.

    {"1":[{"category":[{"network":"99.96"},{"inquiry":"0.04"}]}],"3":[{"category":[{"Systems Engineering":"100"}]}],
"5":[{"category":[{"Security":"100"}]}]}

    ClusteringSolutionVersion - getUpdateStatus()

    Gets the status of the most recent clustering solution update job.

    Table 15. Parameters
    Name Type Description
    None
    Table 16. Returns
    Type Description
    String State of the clustering solution update.
    States:
    • Configuration or network error
    • Error while updating solution
    • Fetching files for updating
    • Preparing data
    • Unauthorized
    • Update complete
    • Updating is cancelled
    • Updating request received
    • Updating request timed out
    • Updating solution
    • Uploading
    • Waiting

    The following example shows how to get the update status of a clustering solution.

    var myCluster = new sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution");

gs.print(JSON.stringify(myCluster.getActiveVersion().getUpdateStatus()));

    Output:

    "Update Complete"

    ClusteringSolutionVersion - getVersionNumber()

    Gets the version number of a solution object.

    Table 17. Parameters
    Name Type Description
    None
    Table 18. Returns
    Type Description
    String Version number.

    The following example shows how to get a version number.

    // Get version number
var mlSolution = sn_ml.ClusteringSolutionStore.get('ml_x_snc_global_global_clustering_solution');

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

    Output:

    Version number: 1

    ClusteringSolutionVersion - submitUpdateJob(Object options)

    Submits clustering update jobs with options to narrow results to a specific table and filter for matching records.

    Table 19. Parameters
    Name Type Description
    options Object JavaScript object containing options on which to base a clustering solution update.
    {
        "filter" : "String",
        "table" : "String"
    }
    options.filter String Encoded query string in the standard platform format. Enables running an update job based on the filter provided.
    options.table String Name of the table on which to run an update job.
    Table 20. Returns
    Type Description
    None

    The following example shows how to submit an update job.

    var myCluster = new sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution");

var options = {"filter" : "precision", "table" : "incident"};

myCluster.getActiveVersion().submitUpdateJob(options);