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


---

# JSONStreamingBuilder - Scoped

# JSONStreamingBuilder - Scoped {#ariaid-title1}

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

Create a builder object used to build a large streaming JSON payload to use in a REST or SOAP request to send bulk data to a third-party API. You can also create the payload as a JSON string for a non-streaming option.
Use these methods in the Workflow Studio script step with the `sn_ih` namespace identifier. For example, you can use this API to create a JSON payload in the Workflow Studio Script step and pass the returned value to the REST step to send the request to a third-party service. For more information, see the Workflow Studio [Script
step](https://www.servicenow.com/docs/access?context=javascript-step-action-designer&version=xanadu&pubname=xanadu-build-workflows&ft:locale=en-US).

You can only use this API within the Workflow Studio environment.

## API call order {#JSONStreamingBuilderScopedAPI__section_owy_pd5_hlb}

Generate JSON payloads using these APIs in the following order:  

JSONStreamingBuilder: Creates a builder object
:   Use these methods in the following order to create a builder object:  
    1. JSONStreamingBuilder(): Instantiates the JSONStreamingBuilder object.{#JSONStreamingBuilderScopedAPI__json-api-constructor}
    2. withAttachment(): Optional. Creates the JSON object as a streaming attachment and stores it in the Streaming Attachments \[streaming_attachment\] table. If you do not call this method, the API creates the payload as a JSON string.{#JSONStreamingBuilderScopedAPI__with-attachments}
    3. expiresAt(): Optional. Sets a time when the attachment expires. Must also call the withAttachment() method.{#JSONStreamingBuilderScopedAPI__expires-at}
    4. build(): Returns a JSONStreamingAPI object.{#JSONStreamingBuilderScopedAPI__build}
    {#JSONStreamingBuilderScopedAPI__ol_obn_dd5_hlb}

JSONStreamingAPI: Builds the JSON payload
:   Use these methods in the following order to create the JSON payload:  
    1. startObject(): Creates the parent JSON object.{#JSONStreamingBuilderScopedAPI__start-object}
    2. Methods to generate the JSON key-value pairs, such as writeFieldName(), writeString(), and writeNumberField().
    3. endObject(): Closes the parent JSON object.{#JSONStreamingBuilderScopedAPI__end-object}
    4. getJSONString() or getAttachmentId(): Returns the JSON string or attachment ID that you created.
    5. close(): Closes the JSONStreamingAPI object.{#JSONStreamingBuilderScopedAPI__close}
    {#JSONStreamingBuilderScopedAPI__ol_yzk_qgn_hlb}

## Size limits {#JSONStreamingBuilderScopedAPI__section_qkj_sd5_hlb}

Payloads generated through this API cannot exceed these size limits:  
* Attachments: 200 MB
* Strings: 5 MB
{#JSONStreamingBuilderScopedAPI__ul_llq_msw_3lb}

## Examples {#JSONStreamingBuilderScopedAPI__section_nzz_rd5_hlb}

This example shows how to create a JSON object and store it in the Attachment
\[sys_attachment\] table with a defined expiration date.  

    try {
      var ttl = new GlideDateTime("2011-01-01 12:00:00");
      var builder = new sn_ih.JSONStreamingBuilder()
        .withAttachment() // Creates the JSON object in streaming mode within an attachment.
        .expiresAt(ttl) // Sets an expiration date for the attachment.
        .build(); // Creates the JSONStreamingAPI object. 

      builder.startObject()  // Begins generating the JSON object.
    	.writeFieldName("firstName")  // Adds a "firstName" field 
    	.writeString("John")          // Writes the value of the "firstName" field
    	.writeFieldName("lastName")
    	.writeString("Smith")
    	.writeNumberField("age","25") // Write a number field named "age" with value "25"
    	.writeFieldName("address")
    	.startObject()                // Start a new object nested under the parent object
    		.writeStringField("streetAddress", "21 2nd Street")
    		.writeStringField("city", "Santa Clara")
    		.writeStringField("state", "CA")
    		.writeStringField("postalCode", "11111")
    	.endObject()
    	.writeFieldName("phoneNumber")
    	.startArray()                    // Start an array 
    		.startObject()               // Add the first object to the array 
    			.writeFieldName("type")
    			.writeString("home")
    			.writeFieldName("number")
    			.writeString("212 555-1234")
    		.endObject()
    		.startObject()               // Add another object to the array 
    			.writeFieldName("type")
    			.writeString("fax")
    			.writeFieldName("number")
    			.writeString("646 555-4567")
    		.endObject()
    	.endArray()
    	.endObject()

      gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.
    } 

    catch (err) {
      gs.log(err);
    } 

    finally {
      builder.close();
    }

Alternatively, this example shows how to use the API in the Script step and create the
payload as a JSON string. You can use this option to create payloads under 5 MB.  

    (function execute(inputs, outputs) {

      var builder = new sn_ih.JSONStreamingBuilder().build();
      
      builder.startObject()
        .enablePrettyPrint()
        .writeTextElement("firstName","John")
        .writeString("John")
        .writeFieldName("lastName")
        .writeString("Smith")
        .writeNumberField("age","25")
        .writeFieldName("address")
        .startObject()
          .writeStringField("streetAddress", "21 2nd Street")
          .writeStringField("city", "Santa Clara")
          .writeStringField("state", "CA")
          .writeStringField("postalCode", "11111")
        .endObject()
        .writeFieldName("phoneNumber")
        .startArray()
          .startObject()
            .writeFieldName("type")
            .writeString("home")
            .writeFieldName("number")
            .writeString("212 555-1234")
          .endObject()
          .startObject()
            .writeFieldName("type")
            .writeString("fax")
            .writeFieldName("number")
            .writeString("646 555-4567")
          .endObject()
        .endArray()
        .endObject()

      outputs.payload = builder.getJSONString();
      
    })(inputs, outputs);

Output:  

    {
    "firstName" : "John",
    "lastName" : "Smith",
    "age" : 25,
    "address" : {
      "streetAddress" : "21 2nd Street",
      "city" : "Santa Clara",
      "state" : "CA",
      "postalCode" : "11111"
    },
    "phoneNumber" : [ {
      "type" : "home",
      "number" : "212 555-1234"
    }, {
      "type" : "fax",
      "number" : "646 555-4567"
    } ]
    }

## JSONStreamingBuilder - JSONStreamingBuilder() {#ariaid-title2}

Instantiates the JSONStreamingBuilder object.
{#JSB-JSONStreamingBuilder__table_mkq_q22_1lb__entry__3}

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

{#JSB-JSONStreamingBuilder__table_mkq_q22_1lb}  

    var builder = new sn_ih.JSONStreamingBuilder()

## JSONStreamingBuilder - build() {#ariaid-title3}

Returns a JSONStreamingAPI object.
{#JSB-build__table_g3z_zf2_1lb__entry__3}

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

{#JSB-build__table_g3z_zf2_1lb} {#JSB-build__table_h3z_zf2_1lb__entry__2}

| Type | Description |
|-|-|
| JSONStreamingAPI | Streaming JSON object used to construct the payload. |
[Table 3. Returns]

{#JSB-build__table_h3z_zf2_1lb}  
This example shows how to create a JSON object and store it in the Attachment
\[sys_attachment\] table with a defined expiration date.

    try {
      var ttl = new GlideDateTime("2011-01-01 12:00:00");
      var builder = new sn_ih.JSONStreamingBuilder()
        .withAttachment() // Creates the JSON object in streaming mode within an attachment.
        .expiresAt(ttl) // Sets an expiration date for the attachment.
        .build(); // Creates the JSONStreamingAPI object. 

      builder.startObject()  // Begins generating the JSON object.
    	.writeFieldName("firstName")  // Adds a "firstName" field 
    	.writeString("John")          // Writes the value of the "firstName" field
    	.writeFieldName("lastName")
    	.writeString("Smith")
    	.writeNumberField("age","25") // Write a number field named "age" with value "25"
    	.writeFieldName("address")
    	.startObject()                // Start a new object nested under the parent object
    		.writeStringField("streetAddress", "21 2nd Street")
    		.writeStringField("city", "Santa Clara")
    		.writeStringField("state", "CA")
    		.writeStringField("postalCode", "11111")
    	.endObject()
    	.writeFieldName("phoneNumber")
    	.startArray()                    // Start an array 
    		.startObject()               // Add the first object to the array 
    			.writeFieldName("type")
    			.writeString("home")
    			.writeFieldName("number")
    			.writeString("212 555-1234")
    		.endObject()
    		.startObject()               // Add another object to the array 
    			.writeFieldName("type")
    			.writeString("fax")
    			.writeFieldName("number")
    			.writeString("646 555-4567")
    		.endObject()
    	.endArray()
    	.endObject()

      gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.
    } 

    catch (err) {
      gs.log(err);
    } 

    finally {
      builder.close();
    }

## JSONStreamingBuilder - expiresAt(Object expiresAt) {#ariaid-title4}

Sets a time when the attachment expires. Must also call the withAttachment() method. If you do not call this
method, the attachment expires two hours from the time the attachment is created.
{#JSB-expiresAt_O__table_wlk_hzt_hlb__entry__3}

| Name | Type | Description |
|-|-|-|
| expiresAt | [GlideDateTime](https://servicenow-prod.fluidtopics.net/xOhnNqU1cKMjoQSfmtxVCw#c_GlideDateTimeScoped "The scoped GlideDateTime class provides methods for performing operations on GlideDateTime objects.") | Object that is set when the attachment expires. * Minimum value: 7200 seconds, or two hours, from the time the attachment is created. Default. * Maximum value: 172800 seconds, or 48 hours, from the time the attachment is created. {#JSB-expiresAt_O__ul_xsc_trx_3lb} |
[Table 4. Parameters]

{#JSB-expiresAt_O__table_wlk_hzt_hlb} {#JSB-expiresAt_O__table_xlk_hzt_hlb__entry__2}

| Type | Description |
|-|-|
| JSONStreamingBuilder | Builder object used to initiate the JSON payload. |
[Table 5. Returns]

{#JSB-expiresAt_O__table_xlk_hzt_hlb}  
This example shows how to create a JSON object and store it in the Attachment
\[sys_attachment\] table with a defined expiration date.

    try {
      var ttl = new GlideDateTime("2011-01-01 12:00:00");
      var builder = new sn_ih.JSONStreamingBuilder()
        .withAttachment() // Creates the JSON object in streaming mode within an attachment.
        .expiresAt(ttl) // Sets an expiration date for the attachment.
        .build(); // Creates the JSONStreamingAPI object. 

      builder.startObject()  // Begins generating the JSON object.
    	.writeFieldName("firstName")  // Adds a "firstName" field 
    	.writeString("John")          // Writes the value of the "firstName" field
    	.writeFieldName("lastName")
    	.writeString("Smith")
    	.writeNumberField("age","25") // Write a number field named "age" with value "25"
    	.writeFieldName("address")
    	.startObject()                // Start a new object nested under the parent object
    		.writeStringField("streetAddress", "21 2nd Street")
    		.writeStringField("city", "Santa Clara")
    		.writeStringField("state", "CA")
    		.writeStringField("postalCode", "11111")
    	.endObject()
    	.writeFieldName("phoneNumber")
    	.startArray()                    // Start an array 
    		.startObject()               // Add the first object to the array 
    			.writeFieldName("type")
    			.writeString("home")
    			.writeFieldName("number")
    			.writeString("212 555-1234")
    		.endObject()
    		.startObject()               // Add another object to the array 
    			.writeFieldName("type")
    			.writeString("fax")
    			.writeFieldName("number")
    			.writeString("646 555-4567")
    		.endObject()
    	.endArray()
    	.endObject()

      gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.
    } 

    catch (err) {
      gs.log(err);
    } 

    finally {
      builder.close();
    }

## JSONStreamingBuilder - withAttachment() {#ariaid-title5}

Creates the JSON object as a streaming attachment and stores it in the Streaming Attachments \[streaming_attachment\] table. If you do not call this method, the API creates the payload as a JSON string.
{#JSB-withAttachment__table_fm2_dzt_hlb__entry__3}

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

{#JSB-withAttachment__table_fm2_dzt_hlb} {#JSB-withAttachment__table_gm2_dzt_hlb__entry__2}

| Type | Description |
|-|-|
| JSONStreamingBuilder | Builder object used to initiate the JSON payload. |
[Table 7. Returns]

{#JSB-withAttachment__table_gm2_dzt_hlb}  
This example shows how to build the JSON payload and save it as an attachment.

    try {
      var ttl = new GlideDateTime("2011-01-01 12:00:00");
      var builder = new sn_ih.JSONStreamingBuilder()
        .withAttachment() // Creates the JSON object in streaming mode within an attachment.
        .expiresAt(ttl) // Sets an expiration date for the attachment.
        .build(); // Creates the JSONStreamingAPI object. 

      builder.startObject()  // Begins generating the JSON object.
    	.writeFieldName("firstName")  // Adds a "firstName" field 
    	.writeString("John")          // Writes the value of the "firstName" field
    	.writeFieldName("lastName")
    	.writeString("Smith")
    	.writeNumberField("age","25") // Write a number field named "age" with value "25"
    	.writeFieldName("address")
    	.startObject()                // Start a new object nested under the parent object
    		.writeStringField("streetAddress", "21 2nd Street")
    		.writeStringField("city", "Santa Clara")
    		.writeStringField("state", "CA")
    		.writeStringField("postalCode", "11111")
    	.endObject()
    	.writeFieldName("phoneNumber")
    	.startArray()                    // Start an array 
    		.startObject()               // Add the first object to the array 
    			.writeFieldName("type")
    			.writeString("home")
    			.writeFieldName("number")
    			.writeString("212 555-1234")
    		.endObject()
    		.startObject()               // Add another object to the array 
    			.writeFieldName("type")
    			.writeString("fax")
    			.writeFieldName("number")
    			.writeString("646 555-4567")
    		.endObject()
    	.endArray()
    	.endObject()

      gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.
    } 

    catch (err) {
      gs.log(err);
    } 

    finally {
      builder.close();
    }

This example shows how to build the JSON payload and save it as a string.

    try {
      var builder = new sn_ih.JSONStreamingBuilder().build();

      builder.startObject()
        .writeFieldName("firstName")
        .writeString("John")
        .writeFieldName("lastName")
        .writeString("Smith")
        .writeNumberField("age","25")
        .writeFieldName("address")
        .startObject()
        .writeStringField("streetAddress", "21 2nd Street")
        .writeStringField("city", "Santa Clara")
        .writeStringField("state", "CA")
        .writeStringField("postalCode", "11111")
        .endObject()
        .writeFieldName("phoneNumber")
        .startArray()
        .startObject()
        .writeFieldName("type")
        .writeString("home")
        .writeFieldName("number")
        .writeString("212 555-1234")
        .endObject()
        .startObject()
        .writeFieldName("type")
        .writeString("fax")
        .writeFieldName("number")
        .writeString("646 555-4567")
        .endObject()
        .endArray()
        .endObject()

      gs.log(builder.getJSONString());
    } 

    catch (err) {
      gs.log("Exception: " + err);
    } 

    finally {
      builder.close();
    }

Output:

    {
    "firstName" : "John",
    "lastName" : "Smith",
    "age" : 25,
    "address" : {
      "streetAddress" : "21 2nd Street",
      "city" : "Santa Clara",
      "state" : "CA",
      "postalCode" : "11111"
    },
    "phoneNumber" : [ {
      "type" : "home",
      "number" : "212 555-1234"
    }, {
      "type" : "fax",
      "number" : "646 555-4567"
    } ]
    }