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


---

# Transformer - Scoped, Global

# Transformer - Scoped, Global {#ariaid-title1}

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

The Transformer API provides methods to parse and transform
structured JSON or XML source content into structured key-value pair output, using a defined set
of rules.

This API works along with the TransformerDefinition and TransformerRuleList APIs. Together, these APIs transform XML nodes or any entity in a structured JSON document into an output of
name-value pairs. Supported JSON entities including objects and elements within an array, such as strings, numbers, and other arrays.  
* The
  TransformerRuleList API enables you to create transformation
  rule lists that define what data in the source document to include in the output and
  how to transform the source data.

* The
  TransformerDefinition API associates a transformation rule list
  with a JSON/XML record path to define reusable transform definition objects. You can
  use a transform definition object to transform one or more source documents.

* The Transformer API performs
  the actual data transformation, one data entity at a time, using the specified
  transformation rule list to create the desired output data.

{#TransformerScriptedAPI__ul_nsk_xfv_bkb}

You can use the Transformer class in both scoped and global server
scripts. When using this class, use the `sn_tfrm` namespace identifier. Before
this API is available in an instance, you must activate the Transformation Service plugin
(com.glide.transform).

The following example illustrates how to use the TransformerRuleList API
to define the transformation rules, the TransformerDefinition API to define
the transformation criteria, and the Transformer API to actually perform
the transformation.

This code example retrieves an external JSON-based stock details document, creates rules for
transforming that data into a tabular table, and then transforms the source document, one row
at a time. The following is a snippet of the JSON source document being transformed:  

    {
      "NOW": {
        "quote": {
          "symbol": "NOW",
          "companyName": "ServiceNow Inc.",
          "primaryExchange": "New York Stock Exchange",
          "sector": "Technology",
          "open": 166.78,
          "openTime": 1522935000556,
          "close": 165.77,
          "changePercent": 0.00656,
           ...
         },
     ...}

    var stockAPI = new sn_ws.RESTMessageV2('Stock Details', 'Default GET'); 
    var response = stockAPI.execute(); 
    var responseBody = response.getBody(); // obtain the source JSON document

    /* Define the list of rules to use to transform the acquired JSON stock detail 
    information into a tabular table */

    var transformerRuleList = new sn_tfrm.TransformerRuleList() // instantiate the rule list object
      .fromJSON() // indicate that the source document is JSON
      .addRule('ticker', '$.quote.symbol') // add a rule to copy the value in the "symbol" field of the source document to the ticker field in the output document (no changes)
      .addRule('change_percentage', '$.quote.changePercent') // copy the "changePercent" field from source into the change_percentage field of output document
      .thenMultiply('100') // multiply the change_percentage value by 100
      .thenRoundDown('0') // addthen round it down to a whole number 
      .addRule('close_price', '$.quote.close') // copy the "close" field to the close_price field in the 21=-[';output
      .thenAdaptCurrency('USD', false) // attach the US dollar code to the close_price field, but do not display the symbol
      .addRule('summary') // add a blank "summary" field to the output (no corresponding source field)
      .thenConcat('Shares of ') // in the summary field concatenate the string "Shares of "
      .thenConcatSymbol('ticker') // then concatenate the "ticker" field from the source document
      .thenConcat(' closed at ') // then concatenate the string " closed at "
      .thenConcatSymbol('close_price'); // then concatenate the "close_price" field from the source document

    // Create a transformer definition that associates the rule list to use and the record path of the set of records in the source document to transform.  
    var path = '$.*'; 
    var transformerDefinition = new sn_tfrm.TransformerDefinition(transformerRuleList, path);
     
    // Instantiate the transformer object.
    var transformer = new sn_tfrm.Transformer(transformerDefinition, responseBody); 

    // Transform the source data, one row at a time, until all rows are processed.
    var results = []; 
    while (transformer.transform()) { 
      results.push(transformer.getRow());
    } 

Output:

     {ticker: "Now", change_percentage: "0", close_price: "165.77 USD", summary: "Shares of Now closed at 165.77" }

## Transformer - Transformer(Object transformerDefinition, String document) {#ariaid-title2}

Instantiates a Transformer object (constructor).
{#Trans-Transformer_O_S__table_uq2_glh_phb__entry__3}

| Name | Type | Description |
|-|-|-|
| transformerDefinition | Object | Object that describes the content transformation; includes rule list and JSONPath/XPath record path. Use the TransformerRuleList() and TransformerDefinition() APIs to generate this object. |
| document | String | Source document to translate. |
[Table 1. Parameters]

{#Trans-Transformer_O_S__table_uq2_glh_phb}  

    var stockAPI = new sn_ws.RESTMessageV2('Stock Details', 'Default GET'); 
    var response = stockAPI.execute(); 
    var responseBody = response.getBody(); 

    var transformerRuleList = new sn_tfrm.TransformerRuleList()
      .fromJSON()
      .addRule('ticker', 'quote.symbol') 
      .addRule('change_percentage', 'quote.change') 
      .thenMultiply('100') 
      .thenRoundDown('0') 
      .addRule('close_price', 'quote.close') 
      .thenAdaptCurrency('USD', false) 
      .addRule('summary') 
      .thenConcat('Shares of ') 
      .thenConcatSymbol('ticker') 
      .thenConcat(' closed at ') 
      .thenConcatSymbol('close') 

     
    var path = '$.*'; 
    var transformerDefinition = new sn_tfrm.TransformerDefinition(transformerRuleList, path); 
    var transformer = new sn_tfrm.Transformer(transformerDefinition, responseBody); 

    var results = []; 
    while (transformer.transform()) { 
      results.push(transformer.getRow());
    }

## Transformer - getRow() {#ariaid-title3}

Returns
the row resulting from the last transformation (or null if no row
exists).
{#Trans-getRow__table_gyt_trh_phb__entry__3}

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

{#Trans-getRow__table_gyt_trh_phb} {#Trans-getRow__table_hyt_trh_phb__entry__2}

| Type | Description |
|-|-|
| Object | Object containing one transformed row/node of data. |
[Table 3. Returns]

{#Trans-getRow__table_hyt_trh_phb}  

    var results = []; 
    while (transformer.transform()) { 
      results.push(transformer.getRow());

Output:

     {ticker: "Now", change_percentage: "0", close_price: "165.77 USD", summary: "Shares of Now closed at 165.77" }

## Transformer - transform() {#ariaid-title4}

Transforms the next available
row/node
in the source document.
{#Trans-transform__table_kjw_tph_phb__entry__3}

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

{#Trans-transform__table_kjw_tph_phb} {#Trans-transform__table_ljw_tph_phb__entry__2}

| Type | Description |
|-|-|
| Boolean | Flag that indicates whether there is a valid next row to transform. * true: Valid next row * false: No additional rows {#Trans-transform__ul_zcn_2qh_phb} |
[Table 5. Returns]

{#Trans-transform__table_ljw_tph_phb}  

    var results = []; 
    while (transformer.transform()) { 
      results.push(transformer.getRow());

Output:

     {ticker: "Now", change_percentage: "0", close_price: "165.77 USD", summary: "Shares of Now closed at 165.77" }