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


---

# EncoderVersion - Global

# EncoderVersion - Global {#ariaid-title1}

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

The EncoderVersion API provides 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 encoder versions based on [Encoder API](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#EncoderAPI "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.") objects in the [Encoder store](https://servicenow-prod.fluidtopics.net/Ck0ttww6z5d~KHjWt6Q5~g#EncoderStoreAPI "The EncoderStore API provides methods to store and retrieve encoders.").

The system activates the most recent version of the encoder when it completes training, and only allows one version to be active at a time. However, you can activate any previously trained version you want to use to make predictions.  
Methods in this API are accessible using the following Encoder methods:

* [getActiveVersion()](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-getActiveVersion "Gets the active EncoderVersion object.")
* [getAllVersions()](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-getAllVersions "Gets all versions of an encoder.")
* [getLatestVersion()](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-getLatestVersion "Gets the latest version of an encoder.")
* [getVersion()](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-getVersion_S "Gets an encoder by provided version number.")
{#EncoderVersionAPI__ul_ycl_fzf_tlb}

## EncoderVersion - getProperties() {#ariaid-title2}

Gets encoder object properties and version number.
{#EncoderV-getProperties__table_d2m_zwz_4lb__entry__3}

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

{#EncoderV-getProperties__table_d2m_zwz_4lb} {#EncoderV-getProperties__table_e2m_zwz_4lb__entry__2}

| Type | Description |
|-|-|
| Object | Contents of the Dataset and [Encoder](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#Encoder-Encoder_O "Creates an encoder.") details. Results vary by object property setup. { "algorithmConfig" : {Object}, "datasetsProperties": [Array], "domainName": "String", "isActive": "String", "label": "String", "name": "String", "predictedFieldName": "String", "processingLanguage": "String", "scope": "String", "stopwords": [Array], "trainingFrequency": "String", "versionNumber": "Number" } |
| \<Object\>.algorithmConfig | Optional. JavaScript object containing algorithm configuration properties. 'algorithmConfig' : { "algorithm": "String" } Data type: Object. |
| \<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. {#EncoderV-getProperties__ul_encoder_alg_vals} Data type: String. |
| \<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\>.isActive | Flag that indicates whether this version is active. Valid values: * true: Version is active. * false: Version is not active. {#EncoderV-getProperties__ul_i5m_lp1_dmb} 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 {#EncoderV-getProperties__ul_pmw_523_plb}Default: run_once Data type: String. |
| \<Object\>.versionNumber | Version number of the Encoder object. Data type: String. |
[Table 2. Returns]

{#EncoderV-getProperties__table_e2m_zwz_4lb}  
The following example gets properties of the active object
version in the store.

    // Get properties
    var mlEncoder = sn_ml.EncoderStore.get('ml_incident_categorization');

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

Output:

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

## EncoderVersion - getSentenceVectors(Array input) {#ariaid-title3}

Returns vectors for each input sentence.
{#EncoderV-getSentenceVectors_A__table_rtq_hdb_rlb__entry__3}

| Name | Type | Description |
|-|-|-|
| input | Array | Array of strings as sentences from which to receive vectors. |
[Table 3. Parameters]

{#EncoderV-getSentenceVectors_A__table_rtq_hdb_rlb} {#EncoderV-getSentenceVectors_A__table_stq_hdb_rlb__entry__2}

| Type | Description |
|-|-|
| String | Array of sentence vectors. |
[Table 4. Returns]

{#EncoderV-getSentenceVectors_A__table_stq_hdb_rlb}  
The following example shows how to return a vector for a single sentence.

    var myEncoderName = 'GloVe';

    var myEncoder = sn_ml.EncoderStore.get(myEncoderName);

    var input = ["I like to code."];

    var vectors = myEncoder.getActiveVersion().getSentenceVectors(input);

    gs.print(vectors);

Output:

    *** Script: [-0.16243751347064972,0.30614474415779114,0.08489049971103668,
    -0.48100000619888306,-0.170997753739357,0.08779674768447876,-0.07848624140024185,-0.15123701095581055,
    -0.07843250036239624,-1.9505999088287354,0.3007825016975403,-0.07804800570011139,-0.04779449850320816,
    0.04803549498319626,0.09848674386739731,0.2427891194820404,-0.41138750314712524,0.10880374908447266,
     ... ,
    0.21227750182151794,0.18478751182556152,-0.3113832473754883,-0.16560424864292145,0.09052124619483948]

## EncoderVersion - getSimilarWords(Array input, Object options) {#ariaid-title4}

Returns words similar to each input word in the descending rank order of
similarity.
{#EncoderV-getSimilarWords_A_O__table_mxj_kdb_rlb__entry__3}

| Name | Type | Description |
|-|-|-|
| input | Array | Array of words for which to find similar words. |
| options | Object | Map to refine results. { "topN":"String" } |
| options.topN | String | If provided, returns the top results up to the specified number of words. For example, use `"10" ` to return the top 10 most similar words. |
[Table 5. Parameters]

{#EncoderV-getSimilarWords_A_O__table_mxj_kdb_rlb} {#EncoderV-getSimilarWords_A_O__table_nxj_kdb_rlb__entry__2}

| Type | Description |
|-|-|
| Array | List of elements containing the similar words for the input word in the corresponding position. These similar words are represented by an of array of pairs in the format `[word, similarity score]`. |
[Table 6. Returns]

{#EncoderV-getSimilarWords_A_O__table_nxj_kdb_rlb}  
The following example shows how to get similar words using the <kbd class="ph userinput">GloVe</kbd>
encoder.

    var myEncoderName = 'GloVe';
    var myEncoder = sn_ml.EncoderStore.get(myEncoderName);
    var input =  ["apple"];
    var options = {"topN":"5"};
    gs.print(myEncoder.getActiveVersion().getSimilarWords(input, options));	

Output:

    *** Script: [[["iphone",0.5987],["macintosh",0.5836],["ipod",0.5761],["microsoft",0.5664],["ipad",0.5628]]]

## EncoderVersion - getStatus(Boolean includeDetails) {#ariaid-title5}

Gets training completion status.
{#EncoderV-getStatus_B__table_xfh_vbw_plb__entry__3}

| 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. {#EncoderV-getStatus_B__ul_n33_ckw_plb} Default: False |
[Table 7. Parameters]

{#EncoderV-getStatus_B__table_xfh_vbw_plb} {#EncoderV-getStatus_B__table_yfh_vbw_plb__entry__2}

| Type | Description |
|-|-|
| Object | JavaScript object containing training status information for an [Encoder](https://servicenow-prod.fluidtopics.net/lD2dU3P5hPYTlVdnWNZofg#EncoderAPI "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.") 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 {#EncoderV-getStatus_B__ul_a5q_gh4_vlb} Data type: String |
| \<Object\>.hasJobEnded | Flag that indicates whether training is complete. Valid values: * true: Training is complete. * false: Training is incomplete. {#EncoderV-getStatus_B__ul_icy_zjx_rlb} 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 |
[Table 8. Returns]

{#EncoderV-getStatus_B__table_yfh_vbw_plb}  
The following example shows a successful result
with training complete.

    // Get status
    var mlEncoder = sn_ml.EncoderStore.get('ml_incident_categorization');

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

Output:

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

The following example shows an unsuccessful
result with training complete.

    // Get status
    var encoderName = 'ml_x_snc_global_global_encoder';
    var mlEncoder = sn_ml.EncoderStore.get(encoderName);
    var trainingStatus = mlEncoder.getLatestVersion().getStatus();

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

Output:

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

## EncoderVersion - getVersionNumber() {#ariaid-title6}

Gets the version number of a solution object.
{#EncoderV-getVersionNumber__table_jsz_sbw_plb__entry__3}

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

{#EncoderV-getVersionNumber__table_jsz_sbw_plb} {#EncoderV-getVersionNumber__table_ksz_sbw_plb__entry__2}

| Type | Description |
|-|-|
| String | Version number. |
[Table 10. Returns]

{#EncoderV-getVersionNumber__table_ksz_sbw_plb}  
The following example shows how to get a version
number.

    // Get version number
    var mlEncoder = sn_ml.EncoderStore.get('ml_incident_categorization');

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

Output:

    Version number: 1

## EncoderVersion - getWordVectors(Array input) {#ariaid-title7}

Returns vectors for each input word.
{#EncoderV-getWordVectors_A__table_jtt_mdb_rlb__entry__3}

| Name | Type | Description |
|-|-|-|
| input | Array | List of strings as words from which to receive vectors. |
[Table 11. Parameters]

{#EncoderV-getWordVectors_A__table_jtt_mdb_rlb} {#EncoderV-getWordVectors_A__table_ktt_mdb_rlb__entry__2}

| Type | Description |
|-|-|
| Array | List of vectors for each word provided. |
[Table 12. Returns]

{#EncoderV-getWordVectors_A__table_ktt_mdb_rlb}  
The following example shows how to get a vector from the word
<kbd class="ph userinput">hello</kbd>.

    var myEncoderName = 'GloVe';
    var myEncoder = sn_ml.EncoderStore.get(myEncoderName);
    var input =  ["hello"];

    gs.print(myEncoder.getActiveVersion().getWordVectors(input));

Output:

    *** Script: [[-0.337119996547699,-0.2169100046157837,-0.006636499892920256,
    -0.41624999046325684,-1.2554999589920044,-0.0284659992903471,-0.7219499945640564,
    -0.5288699865341187,0.0072085000574588776,0.3199700117111206,0.02942500077188015,
    -0.013236000202596188,0.4351100027561188,0.2571600079536438,0.3899500072002411,
     ... ,
    0.3384299874305725,0.4055800139904022,0.18073000013828278,0.6424999833106995]]