---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# PredictabilityEstimate - Global

# PredictabilityEstimate - Global {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 minutes to read

The PredictabilityEstimate API is a scriptable object used in Predictive Intelligence stores. This object provides estimation of how predictable fields
of a dataset can be, and which features can be useful for predicting those fields.

This API requires the Predictive Intelligence plugin (com.glide.platform_ml) and is provided within the `sn_ml` namespace.  
The predictability estimate setup-to-training flow is as follows:

1. Create a dataset using the [DatasetDefinition](https://servicenow-prod.fluidtopics.net/5PRN6njd2wF_we1ri_egPw#DatasetDefinitionAPI "The DatasetDefinition API provides methods to identify a set of records including a table name, columns, and row selection criteria to use as input for ML training algorithms. Datasets don't contain the actual data.") API.
2. Use the [constructor](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-PredictabilityEstimate_O "Creates a predictability estimate.") to create a predictability estimate object.
3. Add the predictability estimate object to the predictability estimate store using the [PredictabilityEstimateStore - add()](https://servicenow-prod.fluidtopics.net/CjCKNAt8AIxjXNKuZMSPpQ#PredictbltyEstStore-add_O "Adds a new predictability estimate object to the store and returns a unique name.") method.
4. Train the predictability estimate using the [submitTrainingJob()](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-submitTrainingJob "Submits a training job.") method. This creates a version of the object that you can manage using the [PredictabilityEstimateVersion](https://servicenow-prod.fluidtopics.net/te3rOtHieLlcBoL_8P_Rzg#PredictabilityEstimateVersionAPI "The PredictabilityEstimateVersion API is a scriptable object used in Predictive Intelligence stores.") API.
5. Get estimated predictive values using the [PredictabilityEstimateVersion -- getResults()](https://servicenow-prod.fluidtopics.net/te3rOtHieLlcBoL_8P_Rzg#PredictbltyEstV-getResults "Returns JSON results containing suggested input fields for an output field.") method.

{#PredictabilityEstimateAPI__ol_mmm_n1c_dmb}  
Note:  
This API runs with full privileges before the Vancouver Patch 7 Hotfix 2b and Washington DC Patch 7 releases. With later releases, grant access using ACLs. For more information see [Query ACLs](https://www.servicenow.com/docs/access?context=query-acl-rule&version=xanadu&pubname=xanadu-platform-security&ft:locale=en-US).

For usage guidelines, refer to [Using ML APIs](https://www.servicenow.com/docs/access?context=using-ml-apis&version=xanadu&pubname=xanadu-intelligent-experiences&ft:locale=en-US).

## PredictabilityEstimate - PredictabilityEstimate(Object config) {#ariaid-title2}

Creates a predictability estimate.
To get new predictability estimates on the same dataset, use this constructor to create a
new PredictabilityEstimate object with a unique name.
{#PrdctbltE-PredictabilityEstimate_O__table_gm2_yt5_flb__entry__3}{#PrdctbltE-PredictabilityEstimate_O__solution-obj-domainN-default}

| Name | Type | Description |
|-|-|-|
| config | Object | JavaScript object containing configuration properties of the predictability estimate. { "dataset": {Object}, "domainName": "String", "inputFieldNames": [Array], "label": "String", "minRowCount": "String", "predictedFieldName": "String", "trainingFrequency": "String" } |
| config.dataset | Object | [DatasetDefinition](https://servicenow-prod.fluidtopics.net/5PRN6njd2wF_we1ri_egPw#DatasetDefinitionAPI "The DatasetDefinition API provides methods to identify a set of records including a table name, columns, and row selection criteria to use as input for ML training algorithms. Datasets don't contain the actual data.") name. |
| config.domainName | String | Optional. Domain name associated with this dataset. See [Domain separation and Predictive Intelligence](https://www.servicenow.com/docs/access?context=domain-separation-predictive-intelligence&version=xanadu&pubname=xanadu-intelligent-experiences&ft:locale=en-US). Default: Current domain, for example, `"global"`. |
| config.inputFieldNames | Array | List of candidate input fields as strings to be considered for estimation. |
| config.label | String | Identifies the prediction task. |
| config.minRowCount | String | Optional. Minimum number of records required in the dataset for training. Default: 10000 |
| config.predictedFieldName | String | Identifies a field to be trained for predictability. |
| config.trainingFrequency | String | Optional. 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 {#PrdctbltE-PredictabilityEstimate_O__ul_pmw_523_plb}Default: run_once |
[Table 1. Parameters]

{#PrdctbltE-PredictabilityEstimate_O__table_gm2_yt5_flb}  
The following example shows how to create an estimation job and add it to the
PredictabilityEstimate store.

    var myIncidentData = new sn_ml.DatasetDefinition({
      'tableName' : 'incident',
      'encodedQuery' : 'activeANYTHING'
    });

    var myEstimate = new sn_ml.PredictabilityEstimate({
      'label': "predictability estimate",
      'dataset' : myIncidentData,
      'inputFieldNames':['short_description'], 
      'predictedFieldName': 'category'
    });

    var myEstimateName = sn_ml.PredictabilityEstimateStore.add(myEstimate);

## PredictabilityEstimate - cancelTrainingJob() {#ariaid-title3}

Cancels a job for a predictability estimate object that has been submitted for training.
{#PrdctbltE-cancelTrainingJob__table_bpb_k3z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 2. Parameters]

{#PrdctbltE-cancelTrainingJob__table_bpb_k3z_llb} {#PrdctbltE-cancelTrainingJob__table_cpb_k3z_llb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 3. Returns]

{#PrdctbltE-cancelTrainingJob__table_cpb_k3z_llb}  
The following example shows how to cancel an existing
training job.

    var myEstimate = sn_ml.PredictabilityEstimateStore.get('ml_sn_global_global_predictability_estimate');

    myEstimate.cancelTrainingJob();

## PredictabilityEstimate - getActiveVersion() {#ariaid-title4}

Gets the active
PredictabilityEstimateVersion object.
{#PrdctbltE-getActiveVersion__table_tvl_m3z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 4. Parameters]

{#PrdctbltE-getActiveVersion__table_tvl_m3z_llb} {#PrdctbltE-getActiveVersion__table_uvl_m3z_llb__entry__2}

| Type | Description |
|-|-|
| Object | Active [PredictabilityEstimateVersion](https://servicenow-prod.fluidtopics.net/te3rOtHieLlcBoL_8P_Rzg#PredictabilityEstimateVersionAPI "The PredictabilityEstimateVersion API is a scriptable object used in Predictive Intelligence stores.") object. |
[Table 5. Returns]

{#PrdctbltE-getActiveVersion__table_uvl_m3z_llb}  
The following example shows how to get an active
PredictabilityEstimate
version from the store and return its training status.

    var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

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

Output:

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

## PredictabilityEstimate - getAllVersions() {#ariaid-title5}

Gets all versions of a predictability estimate.
{#PrdctbltE-getAllVersions__table_tvl_m3z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 6. Parameters]

{#PrdctbltE-getAllVersions__table_tvl_m3z_llb} {#PrdctbltE-getAllVersions__table_uvl_m3z_llb__entry__2}

| Type | Description |
|-|-|
| Array | Existing versions of a solution object. See also [PredictabilityEstimateVersion](https://servicenow-prod.fluidtopics.net/te3rOtHieLlcBoL_8P_Rzg#PredictabilityEstimateVersionAPI "The PredictabilityEstimateVersion API is a scriptable object used in Predictive Intelligence stores.") API. |
[Table 7. Returns]

{#PrdctbltE-getAllVersions__table_uvl_m3z_llb}  
The following example shows how to get all PredictabilityEstimate
version objects and call the getVersionNumber() and
getStatus() estimate version methods on them.

    var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

    var mlEstimateVersions = mlEstimate.getAllVersions();

    for (i = 0; i < mlEstimateVersions.length; i++) {
    gs.print("Version " + mlEstimateVersions[i].getVersionNumber() + " Status: " + mlEstimateVersions[i].getStatus() +"\n");
    };

Output:

    Version 3 Status: {"state":"predictability_estimate_complete","percentComplete":"100","hasJobEnded":"true"}

    Version 2 Status: {"state":"predictability_estimate_complete","percentComplete":"100","hasJobEnded":"true"}

    Version 1 Status: {"state":"predictability_estimate_cancelled","percentComplete":"0","hasJobEnded":"true"}

## PredictabilityEstimate - getLatestVersion() {#ariaid-title6}

Gets the latest version of a predictability estimate.
{#PrdctbltE-getLatestVersion__table_tvl_m3z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 8. Parameters]

{#PrdctbltE-getLatestVersion__table_tvl_m3z_llb} {#PrdctbltE-getLatestVersion__table_uvl_m3z_llb__entry__2}

| Type | Description |
|-|-|
| Object | [PredictabilityEstimateVersion](https://servicenow-prod.fluidtopics.net/te3rOtHieLlcBoL_8P_Rzg#PredictabilityEstimateVersionAPI "The PredictabilityEstimateVersion API is a scriptable object used in Predictive Intelligence stores.") object corresponding to the latest version of a [PredictabilityEstimate()](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-PredictabilityEstimate_O "Creates a predictability estimate."). |
[Table 9. Returns]

{#PrdctbltE-getLatestVersion__table_uvl_m3z_llb}  
The following example shows how to get the latest version of a predictability estimate and return its training status.

    var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

    gs.print(JSON.stringify(JSON.parse(mlEstimate.getLatestVersion().getStatus()), null, 2));

Output:

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

## PredictabilityEstimate - getName() {#ariaid-title7}

Gets the name of the object to use for interaction with the store.
{#PrdctbltE-getName__table_pps_43z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 10. Parameters]

{#PrdctbltE-getName__table_pps_43z_llb} {#PrdctbltE-getName__table_qps_43z_llb__entry__2}

| Type | Description |
|-|-|
| String | Name of the estimate object. |
[Table 11. Returns]

{#PrdctbltE-getName__table_qps_43z_llb}  
The following example shows how to update
PredictabilityEstimate
dataset information and print the name of the object.

    // Update estimate
    var myIncidentData = new sn_ml.DatasetDefinition({
       'tableName' : 'incident',
       'fieldNames' : ['category', 'short_description', 'priority'],
       'encodedQuery' : 'activeANYTHING'
    });

    var myEstimate = new sn_ml.PredictabilityEstimate({
       'label': "my estimate",
       'dataset' : myIncidentData,
       'inputFieldNames':['short_description'],
       'predictedFieldName': 'category'
    });

    // update estimate
    sn_ml.PredictabilityEstimateStore.update('ml_x_snc_global_global_my_definition_4', myEstimate);

    // print estimate name
    gs.print('Estimate Name: '+myEstimate.getName());

Output:

    Estimate Name: ml_x_snc_global_global_my_definition_4

## PredictabilityEstimate - getProperties() {#ariaid-title8}

Gets predictability estimate object properties.
{#PrdctbltE-getProperties__table_pps_43z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 12. Parameters]

{#PrdctbltE-getProperties__table_pps_43z_llb} {#PrdctbltE-getProperties__table_qps_43z_llb__entry__2}

| Type | Description |
|-|-|
| Object | Contents of the Dataset and [PredictabilityEstimate()](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-PredictabilityEstimate_O "Creates a predictability estimate.") object details in the [PredictabilityEstimateStore](https://servicenow-prod.fluidtopics.net/CjCKNAt8AIxjXNKuZMSPpQ#PredictabilityEstimateStoreAPI "Enables storing and retrieving predictability estimates."). { "datasetProperties": {Object}, "domainName": "String", "inputFieldNames": [Array], "label": "String", "name": "String", "predictedFieldName": "String", "scope": "String", "trainingFrequency": "String" } |
| \<Object\>.datasetProperties | Lists the properties of the [DatasetDefinition()](https://servicenow-prod.fluidtopics.net/5PRN6njd2wF_we1ri_egPw#DDef-DatasetDefinition_O "Creates an instance of the DatasetDefinition class, enabling you to define a dataset by table name, fields, and query.") object associated with the estimate. { "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. [ { "name": "String", "type": "String" } ] Data type: Array. |
| \<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](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US). Data type: String. |
| \<Object\>.domainName | Domain name associated with this dataset. See [Domain separation and Predictive Intelligence](https://www.servicenow.com/docs/access?context=domain-separation-predictive-intelligence&version=xanadu&pubname=xanadu-intelligent-experiences&ft:locale=en-US). Data type: String. |
| \<Object\>.inputFieldNames | List of candidate input fields as strings to be considered for estimation. 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\>.scope | Object scope. Currently the only valid value is `global`. 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 {#PrdctbltE-getProperties__ul_pmw_523_plb}Default: run_once Data type: String. |
[Table 13. Returns]

{#PrdctbltE-getProperties__table_qps_43z_llb}  
The following example gets properties of a predictability estimate object in the store.

    var mySolution = sn_ml.PredictabilityEstimateStore.get('ml_sn_global_global_predictability_estimate');

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

Output:

    *** Script: {
      "datasetProperties": {
        "tableName": "incident",
        "fieldNames": [
          "category",
          "short_description",
          "priority",
          "assignment_group.name"
        ],
        "fieldDetails": [
          {
            "name": "category",
            "type": "nominal"
          },
          {
            "name": "short_description",
            "type": "text"
          }
        ]
      },
      "domainName": "global",
      "inputFieldNames": [
        "short_description"
      ],
      "label": "my estimate definition",
      "name": "ml_x_snc_global_global_my_definition_26",
      "predictedFieldName": "category",
      "processingLanguage": "en",
      "scope": "global",
      "stopwords": [
        "Default English Stopwords"
      ],
      "trainingFrequency": "run_once"
    }

## PredictabilityEstimate - getVersion(String version) {#ariaid-title9}

Gets a predictability estimate by provided version number.
{#PrdctbltE-getVersion_S__table_pps_43z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| version | String | Existing version number of a predictability estimate. |
[Table 14. Parameters]

{#PrdctbltE-getVersion_S__table_pps_43z_llb} {#PrdctbltE-getVersion_S__table_qps_43z_llb__entry__2}

| Type | Description |
|-|-|
| Object | Specified version of the [PredictabilityEstimate()](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-PredictabilityEstimate_O "Creates a predictability estimate.") object on which you can call [PredictabilityEstimateVersion](https://servicenow-prod.fluidtopics.net/te3rOtHieLlcBoL_8P_Rzg#PredictabilityEstimateVersionAPI "The PredictabilityEstimateVersion API is a scriptable object used in Predictive Intelligence stores.") API methods. |
[Table 15. Returns]

{#PrdctbltE-getVersion_S__table_qps_43z_llb}  
The following example shows how to get the training status of a predictability estimate by version number.

    var mlEstimate = sn_ml.PredictabilityEstimateStore.get('ml_x_snc_global_global_predictability_estimate');

    gs.print(JSON.stringify(JSON.parse(mlEstimate.getVersion('1').getStatus()), null, 2));

Output:

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

## PredictabilityEstimate - setActiveVersion(String version) {#ariaid-title10}

Activates a specified version of a predictability estimate in the store.
{#PrdctbltE-setActiveVersion_S__table_pps_43z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| version | String | Name of the [PredictabilityEstimate()](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-PredictabilityEstimate_O "Creates a predictability estimate.") object version to activate. Activating this version deactivates any other version. |
[Table 16. Parameters]

{#PrdctbltE-setActiveVersion_S__table_pps_43z_llb} {#PrdctbltE-setActiveVersion_S__table_qps_43z_llb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 17. Returns]

{#PrdctbltE-setActiveVersion_S__table_qps_43z_llb}  
The following example shows how to activate a predictability estimate version in the store.

    sn_ml.PredictabilityEstimate.setActiveVersion("ml_x_snc_global_global_my_estimate_definition");

## PredictabilityEstimate - submitTrainingJob() {#ariaid-title11}

Submits a training job.
Note:  
Before running this method, you must first add a predictability estimate to the store using the [PredictabilityEstimateStore - add()](https://servicenow-prod.fluidtopics.net/CjCKNAt8AIxjXNKuZMSPpQ#PredictbltyEstStore-add_O "Adds a new predictability estimate object to the store and returns a unique name.") method.
{#PrdctbltE-submitTrainingJob__table_xmd_33z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 18. Parameters]

{#PrdctbltE-submitTrainingJob__table_xmd_33z_llb} {#PrdctbltE-submitTrainingJob__table_ymd_33z_llb__entry__2}

| Type | Description |
|-|-|
| Object | [PredictabilityEstimateVersion](https://servicenow-prod.fluidtopics.net/te3rOtHieLlcBoL_8P_Rzg#PredictabilityEstimateVersionAPI "The PredictabilityEstimateVersion API is a scriptable object used in Predictive Intelligence stores.") object corresponding to the [PredictabilityEstimate](https://servicenow-prod.fluidtopics.net/13sZDEHepHKxiQarQCAddQ#PrdctbltE-PredictabilityEstimate_O "Creates a predictability estimate.") being trained. |
[Table 19. Returns]

{#PrdctbltE-submitTrainingJob__table_ymd_33z_llb}  
The following example shows how to create a dataset, apply it to a predictability estimate, add it to a store, and submit the training job.

    // Create a dataset 
    var myData = new sn_ml.DatasetDefinition({

      'tableName' : 'incident',
      'fieldNames' : ['assignment_group', 'short_description', 'description'],
      'encodedQuery' : 'activeANYTHING'

    });

    // Create an estimate 
    var myEstimate = new sn_ml.PredictabilityEstimate({

      'label': "my estimate definition",
      'dataset' : myData,
      'predictedFieldName' : 'assignment_group',
      'inputFieldNames':['short_description']

    });

    // Add the estimate to the store to later be able to retrieve it.
    var my_unique_name = sn_ml.PredictabilityEstimateStore.add(myEstimate);

    // Train the estimate - this is a long running job 
    var myEstimateVersion = myEstimate.submitTrainingJob();