{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":834,"path":"api-reference/server-api-reference/JSONStreamingBuilderScopedAPI.md","title":"JSONStreamingBuilder - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# JSONStreamingBuilder- Scoped\n\nCreate 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.\n\nUse 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/build-workflows/javascript-step-action-designer.md).\n\nYou can only use this API within the Workflow Studio environment.\n\n## API call order\n\nGenerate JSON payloads using these APIs in the following order:\n\n-   **JSONStreamingBuilder: Creates a builder object**\n\n    Use these methods in the following order to create a builder object:\n\n    1.  JSONStreamingBuilder\\(\\): Instantiates the JSONStreamingBuilder object.\n    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.\n    3.  expiresAt\\(\\): Optional. Sets a time when the attachment expires. Must also call the withAttachment\\(\\) method.\n    4.  build\\(\\): Returns a JSONStreamingAPI object.\n-   **JSONStreamingAPI: Builds the JSON payload**\n\n    Use these methods in the following order to create the JSON payload:\n\n    1.  startObject\\(\\): Creates the parent JSON object.\n    2.  Methods to generate the JSON key-value pairs, such as writeFieldName\\(\\), writeString\\(\\), and writeNumberField\\(\\).\n    3.  endObject\\(\\): Closes the parent JSON object.\n    4.  getJSONString\\(\\) or getAttachmentId\\(\\): Returns the JSON string or attachment ID that you created.\n    5.  close\\(\\): Closes the JSONStreamingAPI object.\n\n## Size limits\n\nPayloads generated through this API cannot exceed these size limits:\n\n-   Attachments: 200 MB\n-   Strings: 5 MB\n\n## Examples\n\nThis example shows how to create a JSON object and store it in the Attachment \\[sys\\_attachment\\] table with a defined expiration date.\n\n```\ntry {\n  var ttl = new GlideDateTime(\"2011-01-01 12:00:00\");\n  var builder = new sn_ih.JSONStreamingBuilder()\n    .withAttachment() // Creates the JSON object in streaming mode within an attachment.\n    .expiresAt(ttl) // Sets an expiration date for the attachment.\n    .build(); // Creates the JSONStreamingAPI object. \n\n  builder.startObject()  // Begins generating the JSON object.\n\t.writeFieldName(\"firstName\")  // Adds a \"firstName\" field \n\t.writeString(\"John\")          // Writes the value of the \"firstName\" field\n\t.writeFieldName(\"lastName\")\n\t.writeString(\"Smith\")\n\t.writeNumberField(\"age\",\"25\") // Write a number field named \"age\" with value \"25\"\n\t.writeFieldName(\"address\")\n\t.startObject()                // Start a new object nested under the parent object\n\t\t.writeStringField(\"streetAddress\", \"21 2nd Street\")\n\t\t.writeStringField(\"city\", \"Santa Clara\")\n\t\t.writeStringField(\"state\", \"CA\")\n\t\t.writeStringField(\"postalCode\", \"11111\")\n\t.endObject()\n\t.writeFieldName(\"phoneNumber\")\n\t.startArray()                    // Start an array \n\t\t.startObject()               // Add the first object to the array \n\t\t\t.writeFieldName(\"type\")\n\t\t\t.writeString(\"home\")\n\t\t\t.writeFieldName(\"number\")\n\t\t\t.writeString(\"212 555-1234\")\n\t\t.endObject()\n\t\t.startObject()               // Add another object to the array \n\t\t\t.writeFieldName(\"type\")\n\t\t\t.writeString(\"fax\")\n\t\t\t.writeFieldName(\"number\")\n\t\t\t.writeString(\"646 555-4567\")\n\t\t.endObject()\n\t.endArray()\n\t.endObject()\n\n  gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.\n} \n\ncatch (err) {\n  gs.log(err);\n} \n\nfinally {\n  builder.close();\n}\n```\n\nAlternatively, 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.\n\n```\n(function execute(inputs, outputs) {\n\n  var builder = new sn_ih.JSONStreamingBuilder().build();\n  \n  builder.startObject()\n    .enablePrettyPrint()\n    .writeTextElement(\"firstName\",\"John\")\n    .writeString(\"John\")\n    .writeFieldName(\"lastName\")\n    .writeString(\"Smith\")\n    .writeNumberField(\"age\",\"25\")\n    .writeFieldName(\"address\")\n    .startObject()\n      .writeStringField(\"streetAddress\", \"21 2nd Street\")\n      .writeStringField(\"city\", \"Santa Clara\")\n      .writeStringField(\"state\", \"CA\")\n      .writeStringField(\"postalCode\", \"11111\")\n    .endObject()\n    .writeFieldName(\"phoneNumber\")\n    .startArray()\n      .startObject()\n        .writeFieldName(\"type\")\n        .writeString(\"home\")\n        .writeFieldName(\"number\")\n        .writeString(\"212 555-1234\")\n      .endObject()\n      .startObject()\n        .writeFieldName(\"type\")\n        .writeString(\"fax\")\n        .writeFieldName(\"number\")\n        .writeString(\"646 555-4567\")\n      .endObject()\n    .endArray()\n    .endObject()\n\n  outputs.payload = builder.getJSONString();\n  \n})(inputs, outputs);\n```\n\nOutput:\n\n```\n{\n\"firstName\" : \"John\",\n\"lastName\" : \"Smith\",\n\"age\" : 25,\n\"address\" : {\n  \"streetAddress\" : \"21 2nd Street\",\n  \"city\" : \"Santa Clara\",\n  \"state\" : \"CA\",\n  \"postalCode\" : \"11111\"\n},\n\"phoneNumber\" : [ {\n  \"type\" : \"home\",\n  \"number\" : \"212 555-1234\"\n}, {\n  \"type\" : \"fax\",\n  \"number\" : \"646 555-4567\"\n} ]\n}\n```\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## JSONStreamingBuilder - JSONStreamingBuilder\\(\\)\n\nInstantiates the JSONStreamingBuilder object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n```\nvar builder = new sn_ih.JSONStreamingBuilder()\n```\n\n## JSONStreamingBuilder - build\\(\\)\n\nReturns a JSONStreamingAPI object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|JSONStreamingAPI|Streaming JSON object used to construct the payload.|\n\nThis example shows how to create a JSON object and store it in the Attachment \\[sys\\_attachment\\] table with a defined expiration date.\n\n```\ntry {\n  var ttl = new GlideDateTime(\"2011-01-01 12:00:00\");\n  var builder = new sn_ih.JSONStreamingBuilder()\n    .withAttachment() // Creates the JSON object in streaming mode within an attachment.\n    .expiresAt(ttl) // Sets an expiration date for the attachment.\n    .build(); // Creates the JSONStreamingAPI object. \n\n  builder.startObject()  // Begins generating the JSON object.\n\t.writeFieldName(\"firstName\")  // Adds a \"firstName\" field \n\t.writeString(\"John\")          // Writes the value of the \"firstName\" field\n\t.writeFieldName(\"lastName\")\n\t.writeString(\"Smith\")\n\t.writeNumberField(\"age\",\"25\") // Write a number field named \"age\" with value \"25\"\n\t.writeFieldName(\"address\")\n\t.startObject()                // Start a new object nested under the parent object\n\t\t.writeStringField(\"streetAddress\", \"21 2nd Street\")\n\t\t.writeStringField(\"city\", \"Santa Clara\")\n\t\t.writeStringField(\"state\", \"CA\")\n\t\t.writeStringField(\"postalCode\", \"11111\")\n\t.endObject()\n\t.writeFieldName(\"phoneNumber\")\n\t.startArray()                    // Start an array \n\t\t.startObject()               // Add the first object to the array \n\t\t\t.writeFieldName(\"type\")\n\t\t\t.writeString(\"home\")\n\t\t\t.writeFieldName(\"number\")\n\t\t\t.writeString(\"212 555-1234\")\n\t\t.endObject()\n\t\t.startObject()               // Add another object to the array \n\t\t\t.writeFieldName(\"type\")\n\t\t\t.writeString(\"fax\")\n\t\t\t.writeFieldName(\"number\")\n\t\t\t.writeString(\"646 555-4567\")\n\t\t.endObject()\n\t.endArray()\n\t.endObject()\n\n  gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.\n} \n\ncatch (err) {\n  gs.log(err);\n} \n\nfinally {\n  builder.close();\n}\n```\n\n## JSONStreamingBuilder - expiresAt\\(Object expiresAt\\)\n\nSets 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.\n\n<table id=\"table_wlk_hzt_hlb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nexpiresAt\n\n</td><td>\n\n[GlideDateTime](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideDateTimeScoped.md)\n\n</td><td>\n\nObject that is set when the attachment expires. -   Minimum value: 7200 seconds, or two hours, from the time the attachment is created. Default.\n-   Maximum value: 172800 seconds, or 48 hours, from the time the attachment is created.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|JSONStreamingBuilder|Builder object used to initiate the JSON payload.|\n\nThis example shows how to create a JSON object and store it in the Attachment \\[sys\\_attachment\\] table with a defined expiration date.\n\n```\ntry {\n  var ttl = new GlideDateTime(\"2011-01-01 12:00:00\");\n  var builder = new sn_ih.JSONStreamingBuilder()\n    .withAttachment() // Creates the JSON object in streaming mode within an attachment.\n    .expiresAt(ttl) // Sets an expiration date for the attachment.\n    .build(); // Creates the JSONStreamingAPI object. \n\n  builder.startObject()  // Begins generating the JSON object.\n\t.writeFieldName(\"firstName\")  // Adds a \"firstName\" field \n\t.writeString(\"John\")          // Writes the value of the \"firstName\" field\n\t.writeFieldName(\"lastName\")\n\t.writeString(\"Smith\")\n\t.writeNumberField(\"age\",\"25\") // Write a number field named \"age\" with value \"25\"\n\t.writeFieldName(\"address\")\n\t.startObject()                // Start a new object nested under the parent object\n\t\t.writeStringField(\"streetAddress\", \"21 2nd Street\")\n\t\t.writeStringField(\"city\", \"Santa Clara\")\n\t\t.writeStringField(\"state\", \"CA\")\n\t\t.writeStringField(\"postalCode\", \"11111\")\n\t.endObject()\n\t.writeFieldName(\"phoneNumber\")\n\t.startArray()                    // Start an array \n\t\t.startObject()               // Add the first object to the array \n\t\t\t.writeFieldName(\"type\")\n\t\t\t.writeString(\"home\")\n\t\t\t.writeFieldName(\"number\")\n\t\t\t.writeString(\"212 555-1234\")\n\t\t.endObject()\n\t\t.startObject()               // Add another object to the array \n\t\t\t.writeFieldName(\"type\")\n\t\t\t.writeString(\"fax\")\n\t\t\t.writeFieldName(\"number\")\n\t\t\t.writeString(\"646 555-4567\")\n\t\t.endObject()\n\t.endArray()\n\t.endObject()\n\n  gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.\n} \n\ncatch (err) {\n  gs.log(err);\n} \n\nfinally {\n  builder.close();\n}\n```\n\n## JSONStreamingBuilder - withAttachment\\(\\)\n\nCreates 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.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|JSONStreamingBuilder|Builder object used to initiate the JSON payload.|\n\nThis example shows how to build the JSON payload and save it as an attachment.\n\n```\ntry {\n  var ttl = new GlideDateTime(\"2011-01-01 12:00:00\");\n  var builder = new sn_ih.JSONStreamingBuilder()\n    .withAttachment() // Creates the JSON object in streaming mode within an attachment.\n    .expiresAt(ttl) // Sets an expiration date for the attachment.\n    .build(); // Creates the JSONStreamingAPI object. \n\n  builder.startObject()  // Begins generating the JSON object.\n\t.writeFieldName(\"firstName\")  // Adds a \"firstName\" field \n\t.writeString(\"John\")          // Writes the value of the \"firstName\" field\n\t.writeFieldName(\"lastName\")\n\t.writeString(\"Smith\")\n\t.writeNumberField(\"age\",\"25\") // Write a number field named \"age\" with value \"25\"\n\t.writeFieldName(\"address\")\n\t.startObject()                // Start a new object nested under the parent object\n\t\t.writeStringField(\"streetAddress\", \"21 2nd Street\")\n\t\t.writeStringField(\"city\", \"Santa Clara\")\n\t\t.writeStringField(\"state\", \"CA\")\n\t\t.writeStringField(\"postalCode\", \"11111\")\n\t.endObject()\n\t.writeFieldName(\"phoneNumber\")\n\t.startArray()                    // Start an array \n\t\t.startObject()               // Add the first object to the array \n\t\t\t.writeFieldName(\"type\")\n\t\t\t.writeString(\"home\")\n\t\t\t.writeFieldName(\"number\")\n\t\t\t.writeString(\"212 555-1234\")\n\t\t.endObject()\n\t\t.startObject()               // Add another object to the array \n\t\t\t.writeFieldName(\"type\")\n\t\t\t.writeString(\"fax\")\n\t\t\t.writeFieldName(\"number\")\n\t\t\t.writeString(\"646 555-4567\")\n\t\t.endObject()\n\t.endArray()\n\t.endObject()\n\n  gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.\n} \n\ncatch (err) {\n  gs.log(err);\n} \n\nfinally {\n  builder.close();\n}\n```\n\nThis example shows how to build the JSON payload and save it as a string.\n\n```\ntry {\n  var builder = new sn_ih.JSONStreamingBuilder().build();\n\n  builder.startObject()\n    .writeFieldName(\"firstName\")\n    .writeString(\"John\")\n    .writeFieldName(\"lastName\")\n    .writeString(\"Smith\")\n    .writeNumberField(\"age\",\"25\")\n    .writeFieldName(\"address\")\n    .startObject()\n    .writeStringField(\"streetAddress\", \"21 2nd Street\")\n    .writeStringField(\"city\", \"Santa Clara\")\n    .writeStringField(\"state\", \"CA\")\n    .writeStringField(\"postalCode\", \"11111\")\n    .endObject()\n    .writeFieldName(\"phoneNumber\")\n    .startArray()\n    .startObject()\n    .writeFieldName(\"type\")\n    .writeString(\"home\")\n    .writeFieldName(\"number\")\n    .writeString(\"212 555-1234\")\n    .endObject()\n    .startObject()\n    .writeFieldName(\"type\")\n    .writeString(\"fax\")\n    .writeFieldName(\"number\")\n    .writeString(\"646 555-4567\")\n    .endObject()\n    .endArray()\n    .endObject()\n\n  gs.log(builder.getJSONString());\n} \n\ncatch (err) {\n  gs.log(\"Exception: \" + err);\n} \n\nfinally {\n  builder.close();\n}\n```\n\nOutput:\n\n```\n{\n\"firstName\" : \"John\",\n\"lastName\" : \"Smith\",\n\"age\" : 25,\n\"address\" : {\n  \"streetAddress\" : \"21 2nd Street\",\n  \"city\" : \"Santa Clara\",\n  \"state\" : \"CA\",\n  \"postalCode\" : \"11111\"\n},\n\"phoneNumber\" : [ {\n  \"type\" : \"home\",\n  \"number\" : \"212 555-1234\"\n}, {\n  \"type\" : \"fax\",\n  \"number\" : \"646 555-4567\"\n} ]\n}\n```\n\n"}}