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


---

# Encoder - Global

# Encoder - Global {#ariaid-title1}

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

The Encoder API provides a scriptable object used in Predictive Intelligence stores. This object converts input data into vectors of numbers, based on encoder-specific goals and configurations. Encoders can be used independently to run encodings or can be configured as part of
solutions to encode text columns.

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

Encoders are text processing objects that are either pre-trained or trained based on the language datasets you provide. You can train encoders that determine how the system interprets and processes text fields. For ML solutions that include text, you can train an encoder to specify how to process text and use the trained encoder in a solution.

Encoders have configuration and versions, and can be trained independently with their own
retraining frequency. API-defined encoders are different from UI-defined encoders, because the
retraining of UI-defined encoders is controlled by the solutions using them.  
The encoder setup-to-training flow is as follows:

1. Create one or more datasets 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/lD2dU3P5hPYTlVdnWNZofg#Encoder-Encoder_O "Creates an encoder.") to create an encoder object.
3. Add the encoder object to the encoder store using the [EncoderStore - add()](https://servicenow-prod.fluidtopics.net/Ck0ttww6z5d~KHjWt6Q5~g#EncoderStore-add_O "Adds a new encoder object to the store and returns a unique name.") method.
4. Train the encoder using the [submitTrainingJob()](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-submitTrainingJob "Submits a training job.") method. This creates a version of the object that you can manage using the [EncoderVersion](https://servicenow-prod.fluidtopics.net/8m0IyHRhGsxfd5zKTCjT7g#EncoderVersionAPI "The EncoderVersion API provides a scriptable object used in Predictive Intelligence stores.") API.

{#EncoderAPI__ol_aqf_1xt_2mb}Once you have trained an encoder, you can use it in a solution object:

* [ClassificationSolution](https://servicenow-prod.fluidtopics.net/n0ITHoNNnE5DnGxbNhqWtg#ClassificationSolutionAPI "The ClassificationSolution API is a scriptable object used in Predictive Intelligence stores.")
* [ClusteringSolution](https://servicenow-prod.fluidtopics.net/1UtA64JFiuMrifx24cx4og#ClusteringSolutionAPI "The ClusteringSolution API is a scriptable object used in Predictive Intelligence stores.") (required unless using the Levenshtein distance algorithm)
* [RegressionSolution](https://servicenow-prod.fluidtopics.net/3hYy9ifcFaLlyL23bPPuBg#RegressionSolutionAPI "The RegressionSolution API is a scriptable object used in Predictive Intelligence stores.")
* [SimilaritySolution](https://servicenow-prod.fluidtopics.net/xZSZcyb_NF4dd4dPmDXO3w#SimilaritySolutionAPI "The SimilaritySolution API is a scriptable object used in Predictive Intelligence stores.") (required)

{#EncoderAPI__ul_v1k_kzq_bmb}  
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).

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

Creates an encoder.
To get an encoder for one or more datasets, use this constructor to create a new encoder
object with a unique name.
{#Encoder-Encoder_O__table_gm2_yt5_flb__entry__3}{#Encoder-Encoder_O__solution-obj-domainN-default}{#Encoder-Encoder_O__solution-obj-lang-desc}{#Encoder-Encoder_O__solution-obj-stop-desc}

| Name | Type | Description |
|-|-|-|
| config | Object | JavaScript object containing configuration properties of the encoder. { "algorithmConfig": {Object}, "datasets": [Array], "domainName": "String", "label": "String", "minRowCount": "String", "processingLanguage": "String", "stopwords": [Array], "trainingFrequency": "String" } |
| config.algorithmConfig | Object | Optional. JavaScript object containing algorithm configuration properties. 'algorithmConfig' : { "algorithm": "String" } |
| config.algorithmConfig.algorithm | String | Name of the algorithm for training this encoder. Possible values: * paravec: Paragraph vector word embedding. * tf-idf: Term Frequency--Inverse Document Frequency (TF-IDF)-based text. {#Encoder-Encoder_O__ul_encoder_alg_vals} |
| config.datasets | Array | List of [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.") object names. |
| 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.label | String | Identifies the prediction task. |
| config.minRowCount | String | Optional. Minimum number of records required in the dataset for training. Default: 10000 |
| config.processingLanguage | String | Optional. Processing language in two-letter ISO 639-1 language code format. Default: "en" |
| config.stopwords | Array | Optional. Preset list of strings that the system automatically generates based on the language property setting. For details, see [Create a custom stopwords list](https://www.servicenow.com/docs/access?context=create-custom-stopwords-list&version=xanadu&pubname=xanadu-intelligent-experiences&ft:locale=en-US). Default: English Stopwords |
| config.trainingFrequency | String | 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 {#Encoder-Encoder_O__ul_pmw_523_plb}Default: run_once |
[Table 1. Parameters]

{#Encoder-Encoder_O__table_gm2_yt5_flb}  
The following example shows how to create an encoder job and add it to the encoder
store.

    var myPrbData = new sn_ml.DatasetDefinition({
        'tableName' : 'problem',
        'fieldNames' : ['short_description'],
        'encodedQuery' : 'activeANYTHING'
    });

    var myIncidentData = new sn_ml.DatasetDefinition({
        'tableName' : 'incident',
        'fieldNames' : ['short_description', 'description'],
        'encodedQuery' : 'activeANYTHING'
    });

    var myEncoder = new sn_ml.Encoder({
        'label': "encoder",
        'datasets' : [myPrbData, myIncidentData],
        'algorithmConfig' : {
            'algorithm' : 'tf-idf'
        }
    });
    var myEncoderName = sn_ml.EncoderStore.add(myEncoder);

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

Cancels a job for a encoder object that has been submitted for training.
{#Encoder-cancelTrainingJob__table_bpb_k3z_llb__entry__3}

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

{#Encoder-cancelTrainingJob__table_bpb_k3z_llb} {#Encoder-cancelTrainingJob__table_cpb_k3z_llb__entry__2}

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

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

    var myEncoder = sn_ml.EncoderStore.get('ml_sn_global_global_encoder');

    myEncoder.cancelTrainingJob();

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

Gets the active EncoderVersion object.
{#Encoder-getActiveVersion__table_tvl_m3z_llb__entry__3}

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

{#Encoder-getActiveVersion__table_tvl_m3z_llb} {#Encoder-getActiveVersion__table_uvl_m3z_llb__entry__2}

| Type | Description |
|-|-|
| Object | Active [EncoderVersion](https://servicenow-prod.fluidtopics.net/8m0IyHRhGsxfd5zKTCjT7g#EncoderVersionAPI "The EncoderVersion API provides a scriptable object used in Predictive Intelligence stores.") object. |
[Table 5. Returns]

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

    var mlEncoder = sn_ml.EncoderStore.get('ml_x_snc_global_global_encoder');

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

Output:

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

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

Gets all versions of an encoder.
{#Encoder-getAllVersions__table_tvl_m3z_llb__entry__3}

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

{#Encoder-getAllVersions__table_tvl_m3z_llb} {#Encoder-getAllVersions__table_uvl_m3z_llb__entry__2}

| Type | Description |
|-|-|
| Array | Existing versions of an encoder object. See also [EncoderVersion](https://servicenow-prod.fluidtopics.net/8m0IyHRhGsxfd5zKTCjT7g#EncoderVersionAPI "The EncoderVersion API provides a scriptable object used in Predictive Intelligence stores.") API. |
[Table 7. Returns]

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

    var mlEncoder = sn_ml.EncoderStore.get('ml_x_snc_global_global_encoder');

    var mlEncoderVersions = mlEncoder.getAllVersions();

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

Output:

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

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

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

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

Gets the latest version of an encoder.
{#Encoder-getLatestVersion__table_tvl_m3z_llb__entry__3}

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

{#Encoder-getLatestVersion__table_tvl_m3z_llb} {#Encoder-getLatestVersion__table_uvl_m3z_llb__entry__2}

| Type | Description |
|-|-|
| Object | [EncoderVersion](https://servicenow-prod.fluidtopics.net/8m0IyHRhGsxfd5zKTCjT7g#EncoderVersionAPI "The EncoderVersion API provides a scriptable object used in Predictive Intelligence stores.") object corresponding to the latest version of an [Encoder()](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-Encoder_O "Creates an encoder."). |
[Table 9. Returns]

{#Encoder-getLatestVersion__table_uvl_m3z_llb}  
The following example shows how to get the latest version of an encoder and return its training status.

    var mlEncoder = sn_ml.EncoderStore.get('ml_x_snc_global_global_encoder');

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

Output:

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

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

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

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

{#Encoder-getName__table_pps_43z_llb} {#Encoder-getName__table_qps_43z_llb__entry__2}

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

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

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

    var eligibleFields = JSON.parse(myIncidentData.getEligibleFields(encoder));

    var myEncoder = new sn_ml.Encoder({
       'label': "my encoder",
       'datasets' : [myIncidentData],
       'inputFieldNames': eligibleFields['eligibleInputFieldNames'],
       'predictedFieldName': 'category'
    });

    // update encoder
    sn_ml.EncoderStore.update('ml_x_snc_global_global_my_definition_4', myEncoder);

    // print encoder name
    gs.print('Encoder Name: '+myEncoder.getName());

Output:

    Encoder Name: ml_x_snc_global_global_my_definition_4

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

Gets solution object properties.
{#Encoder-getProperties__table_pps_43z_llb__entry__3}

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

{#Encoder-getProperties__table_pps_43z_llb} {#Encoder-getProperties__table_qps_43z_llb__entry__2}

| Type | Description |
|-|-|
| Object | Contents of the Dataset and [Encoder()](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-Encoder_O "Creates an encoder.") object details in the [EncoderStore](https://servicenow-prod.fluidtopics.net/Ck0ttww6z5d~KHjWt6Q5~g#EncoderStoreAPI "The EncoderStore API provides methods to store and retrieve encoders."). { "algorithmConfig" : {Object}, "datasetsProperties": [Array], "domainName": "String", "label": "String", "name": "String", "processingLanguage": "String", "scope": "String", "stopwords": [Array], "trainingFrequency": "String" } |
| \<Object\>.algorithmConfig.algorithm | Name of the algorithm for training this encoder. Possible values: * paravec: Paragraph vector word embedding. * tf-idf: Term Frequency--Inverse Document Frequency (TF-IDF)-based text. {#Encoder-getProperties__ul_encoder_alg_vals} Data type: String. |
| \<Object\>.algorithmConfig | Optional. JavaScript object containing algorithm configuration properties. 'algorithmConfig' : { "algorithm": "String" } Data type: Object. |
| \<Object\>.datasetsProperties | List of [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.") properties associated with the encoder. { "encodedQuery": "String", "fieldDetails": [Array], "fieldNames": [Array], "tableName": "String" } Data type: Array. |
| \<Object\>.datasetsProperties.tableName | Name of the table for the dataset. For example, `"tableName" : "Incident"`. Data type: String. |
| \<Object\>.datasetsProperties.fieldNames | List of field names from the specified table as strings. For example, `"fieldNames" : ["short_description", "priority"]`. Data type: Array. |
| \<Object\>.datasetsProperties.fieldNames.fieldDetails | List of JavaScript objects that specify field properties. [ { "name": "String", "type": "String" } ] Data type: Array. |
| \<Object\>.datasetsProperties.fieldNames.fieldDetails.\<object\>.name | Name of the field defining the type of information to restrict this dataset to. Data type: String. |
| \<Object\>.datasetsProperties.fieldDetails.\<object\>.type | Machine-learning field type. Data type: String. |
| \<Object\>.datasetsProperties.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\>.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](https://www.servicenow.com/docs/access?context=create-custom-stopwords-list&version=xanadu&pubname=xanadu-intelligent-experiences&ft:locale=en-US). 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 {#Encoder-getProperties__ul_pmw_523_plb}Default: run_once Data type: String. |
[Table 13. Returns]

{#Encoder-getProperties__table_qps_43z_llb}  
The following example gets properties of an encoder object in the store.

    var myEncoder = sn_ml.EncoderStore.get('ml_sn_global_global_encoder');

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

Output:

    *** Script: {
      "datasetsProperties": [
        {
          "tableName": "incident",
          "fieldNames": [
            "assignment_group",
            "short_description",
            "description"
          ],
          "encodedQuery": "activeANYTHING"
        }
      ],
      "domainName": "global",
      "label": "my encoder definition",
      "name": "ml_x_snc_global_global_my_encoder_definition",
      "processingLanguage": "en",
      "scope": "global",
      "stopwords": [
        "Default English Stopwords"
      ],
      "trainingFrequency": "run_once"
    }

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

Gets an encoder by provided version number.
{#Encoder-getVersion_S__table_pps_43z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| version | String | Existing version number of an encoder. |
[Table 14. Parameters]

{#Encoder-getVersion_S__table_pps_43z_llb} {#Encoder-getVersion_S__table_qps_43z_llb__entry__2}

| Type | Description |
|-|-|
| Object | Specified version of the [Encoder()](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-Encoder_O "Creates an encoder.") object on which you can call [EncoderVersion](https://servicenow-prod.fluidtopics.net/8m0IyHRhGsxfd5zKTCjT7g#EncoderVersionAPI "The EncoderVersion API provides a scriptable object used in Predictive Intelligence stores.") API methods. |
[Table 15. Returns]

{#Encoder-getVersion_S__table_qps_43z_llb}  
The following example shows how to get the training status of an encoder by version number.

    var mlEncoder = sn_ml.EncoderStore.get('ml_x_snc_global_global_encoder');

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

Output:

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

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

Activates a specified version of an encoder in the store.
{#Encoder-setActiveVersion_S__table_pps_43z_llb__entry__3}

| Name | Type | Description |
|-|-|-|
| version | String | Name of the [Encoder()](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-Encoder_O "Creates an encoder.") object version to activate. Activating this version deactivates any other version. |
[Table 16. Parameters]

{#Encoder-setActiveVersion_S__table_pps_43z_llb} {#Encoder-setActiveVersion_S__table_qps_43z_llb__entry__2}

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

{#Encoder-setActiveVersion_S__table_qps_43z_llb}  
The following example shows how to activate an encoder version in the store.

    sn_ml.Encoder.setActiveVersion("ml_incident_categorization");

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

Submits a training job.
Note:  
Before running this method, you must first add an encoder to the store using the [EncoderStore - add()](https://servicenow-prod.fluidtopics.net/Ck0ttww6z5d~KHjWt6Q5~g#EncoderStore-add_O "Adds a new encoder object to the store and returns a unique name.") method.
{#Encoder-submitTrainingJob__table_xmd_33z_llb__entry__3}

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

{#Encoder-submitTrainingJob__table_xmd_33z_llb} {#Encoder-submitTrainingJob__table_ymd_33z_llb__entry__2}

| Type | Description |
|-|-|
| Object | [EncoderVersion](https://servicenow-prod.fluidtopics.net/8m0IyHRhGsxfd5zKTCjT7g#EncoderVersionAPI "The EncoderVersion API provides a scriptable object used in Predictive Intelligence stores.") object corresponding to the [Encoder](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-Encoder_O "Creates an encoder.") being trained. |
[Table 19. Returns]

{#Encoder-submitTrainingJob__table_ymd_33z_llb}  
The following example shows how to create a dataset, apply it to an encoder, 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 encoder 
    var myEncoder = new sn_ml.Encoder({

      'label': "my encoder definition",
      'datasets' : [myData],
      'predictedFieldName' : 'assignment_group',
      'inputFieldNames':['short_description']

    });

    // Add the encoder to the store to later be able to retrieve it.
    var my_unique_name = sn_ml.EncoderStore.add(myEncoder);

    // Train the encoder - this is a long running job 
    var myEncoderVersion = myEncoder.submitTrainingJob();