Create a builder object to build a large XML payload for use in a REST or SOAP request to send bulk data to a third-party API. You can also create the payload as an XML string for a non-streaming option.

Use these methods in a Flow Designer Script step with the sn_ih namespace identifier. For example, you can use this API to create an XML payload in the Flow Designer 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 Flow Designer Script step.
Note: You can only use this API within the Flow Designer environment.

API call order

Generate XML payloads by first instantiating a builder object with XMLStreamingBuilder and then calling the methods in the XMLStreamingAPI class:

1. XMLStreamingBuilder: Creates a builder object
Use these method in the following order to create a builder object:
  1. XMLStreamingBuilder(): Instantiates the XMLStreamingBuilder object.
  2. withAttachment(): Optional. Creates an XML document as an attachment and stores it in the Streaming Attachments [streaming_attachment] table. If you don't call this method, the API builds the payload as an XML string.
  3. expiresAt(): Optional. Sets a time when the attachment expires. False is the default. Must also call the withAttachment() method.
  4. build(): Returns an XMLStreamingAPI object.
2. XMLStreamingAPI: Builds the XML payload
Use these methods in the following order to create the XML payload:
  1. startDocument(): Creates the top-level parent element in the XML document.
  2. Methods to generate child elements in the XML document, such as writeTextElement(), startElement(), and writeArray().
  3. Methods to generate attributes for an element, such as writeAttribute(), writeNamespace(), and writeDtd().
  4. endElement(): Closes an XML element.
  5. endDocument: Closes the top-level parent element.
  6. getXMLString() or getAttachmentId(): Returns the XML string or attachment ID that you created.
  7. close(): Closes the XMLStreamingAPI object.

Size limits

Payloads generated through this API cannot exceed these size limits:

  • Attachments: 200 MB
  • Strings: 5 MB

Example

The following example shows how to create an XML document and store it in the Streaming Attachments [streaming_attachment] table with a defined expiration date.


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

  builder.startDocument("Employee") // Begins generating the XML document.
    .writeTextElement("firstName","John") // Writes a "firstName" element and value.
    .writeTextElement("lastName","Smith")
    .writeTextElement("age","25")
    .startElement("address") // Adds an "address" parent element.
      .writeTextElement("streetAddress", "21 2nd Street") // Writes a child element and value.
      .writeTextElement("city", "Santa Clara")
      .writeTextElement("state", "CA")
      .writeTextElement("postalCode", "11111")
    .endElement() // Adds a closing tag for the "address" element.
    .startElement("phoneNumber")
      .writeTextElement("type","home")
      .writeTextElement("number","212 555-1234")
      .writeTextElement("type","fax")
      .writeTextElement("number","646 555-4567")
    .endElement()
  .endDocument() // Stops generating the XML document.
      
  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 an XML string. You can use this option to create payloads under 5 MB.

(function execute(inputs, outputs) {

  var builder = new sn_ih.XMLStreamingBuilder().build();
  
  builder.startDocument("Employee")
    .enablePrettyPrint()
    .writeTextElement("firstName","John")
    .writeTextElement("lastName","Smith")
    .writeTextElement("age","25")
    .startElement("address")
      .writeTextElement("streetAddress", "21 2nd Street")
      .writeTextElement("city", "Santa Clara")
      .writeTextElement("state", "CA")
      .writeTextElement("postalCode", "11111")
    .endElement()
    .startElement("phoneNumber")
      .writeTextElement("type","home")
      .writeTextElement("number","212 555-1234")
      .writeTextElement("type","fax")
      .writeTextElement("number","646 555-4567")
    .endElement()
  .endDocument()

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

Output:

<?xml version="1.0" encoding="UTF-8"?>
<firstName>John</firstName>
<lastName>Smith</lastName>
<age>25</age>
<address>
  <streetAddress>21 2nd Street</streetAddress>
  <city>Santa Clara</city>
  <state>CA</state>
  <postalCode>11111</postalCode>
</address>
<phoneNumber>
  <type>home</type>
  <number>212 555-1234</number>
  <type>fax</type>
  <number>646 555-4567</number>
</phoneNumber>

XMLStreamingBuilder - build()

Returns an XMLStreamingAPI object.

Table 1. Parameters
Name Type Description
None
Table 2. Returns
Type Description
XMLStreamingAPI Streaming XML object for constructing the payload.

Example

The following example shows how to create an XML document and store it in the Streaming Attachments [streaming_attachment] table with a defined expiration date.


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

  builder.startDocument("Employee") // Begins generating the XML document.
    .writeTextElement("firstName","John") // Writes a "firstName" element and value.
    .writeTextElement("lastName","Smith")
    .writeTextElement("age","25")
    .startElement("address") // Adds an "address" parent element.
      .writeTextElement("streetAddress", "21 2nd Street") // Writes a child element and value.
      .writeTextElement("city", "Santa Clara")
      .writeTextElement("state", "CA")
      .writeTextElement("postalCode", "11111")
    .endElement() // Adds a closing tag for the "address" element.
    .startElement("phoneNumber")
      .writeTextElement("type","home")
      .writeTextElement("number","212 555-1234")
      .writeTextElement("type","fax")
      .writeTextElement("number","646 555-4567")
    .endElement()
  .endDocument() // Stops generating the XML document.
      
  gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.
} catch (err) {
  gs.log(err);
} finally {
  builder.close();
}

XMLStreamingBuilder - expiresAt(Object expiresAt)

Sets a time when the attachment expires. Must also call the withAttachment() method.

Table 3. Parameters
Name Type Description
expiresAt GlideDateTime Object that is set when the attachment expires.
  • Minimum value: 7200 seconds, or two hours, from the time the attachment is created. This is the default value if you don't call the expiresAt() method.
  • Maximum value: 172800 seconds, or 48 hours, from the time the attachment is created.
Table 4. Returns
Type Description
XMLStreamingBuilder Builder object used to initiate the XML payload.

Example

The following example shows how to create an XML document and store it in the Streaming Attachments [streaming_attachment] table with a defined expiration date.


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

  builder.startDocument("Employee") // Begins generating the XML document.
    .writeTextElement("firstName","John") // Writes a "firstName" element and value.
    .writeTextElement("lastName","Smith")
    .writeTextElement("age","25")
    .startElement("address") // Adds an "address" parent element.
      .writeTextElement("streetAddress", "21 2nd Street") // Writes a child element and value.
      .writeTextElement("city", "Santa Clara")
      .writeTextElement("state", "CA")
      .writeTextElement("postalCode", "11111")
    .endElement() // Adds a closing tag for the "address" element.
    .startElement("phoneNumber")
      .writeTextElement("type","home")
      .writeTextElement("number","212 555-1234")
      .writeTextElement("type","fax")
      .writeTextElement("number","646 555-4567")
    .endElement()
  .endDocument() // Stops generating the XML document.
      
  gs.log(builder.getAttachmentId()); // Returns the sys_id of the attachment.
} catch (err) {
  gs.log(err);
} finally {
  builder.close();
}

XMLStreamingBuilder - withAttachment()

Creates an XML document as an attachment and stores it in the Streaming Attachments [streaming_attachment] table. If you don't call this method, the API creates the XML document as a string.

Table 5. Parameters
Name Type Description
None
Table 6. Returns
Type Description
XMLStreamingBuilder Builder object used to initiate the XML payload.

Example

The following example shows how to create an XML document and store it in the Streaming Attachments [streaming_attachment] table with a defined expiration date.


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

  builder.startDocument("Employee") // Begins generating the XML document.
    .writeTextElement("firstName","John") // Writes a "firstName" element and value.
    .writeTextElement("lastName","Smith")
    .writeTextElement("age","25")
    .startElement("address") // Adds an "address" parent element.
      .writeTextElement("streetAddress", "21 2nd Street") // Writes a child element and value.
      .writeTextElement("city", "Santa Clara")
      .writeTextElement("state", "CA")
      .writeTextElement("postalCode", "11111")
    .endElement() // Adds a closing tag for the "address" element.
    .startElement("phoneNumber")
      .writeTextElement("type","home")
      .writeTextElement("number","212 555-1234")
      .writeTextElement("type","fax")
      .writeTextElement("number","646 555-4567")
    .endElement()
  .endDocument() // Stops generating the XML document.
      
  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 XML payload and save it as a string.

(function execute(inputs, outputs) {

  var builder = new sn_ih.XMLStreamingBuilder().build();
  
  builder.startDocument("Employee")
    .enablePrettyPrint()
    .writeTextElement("firstName","John")
    .writeTextElement("lastName","Smith")
    .writeTextElement("age","25")
    .startElement("address")
      .writeTextElement("streetAddress", "21 2nd Street")
      .writeTextElement("city", "Santa Clara")
      .writeTextElement("state", "CA")
      .writeTextElement("postalCode", "11111")
    .endElement()
    .startElement("phoneNumber")
      .writeTextElement("type","home")
      .writeTextElement("number","212 555-1234")
      .writeTextElement("type","fax")
      .writeTextElement("number","646 555-4567")
    .endElement()
  .endDocument()

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

Output:

<?xml version="1.0" encoding="UTF-8"?>
<firstName>John</firstName>
<lastName>Smith</lastName>
<age>25</age>
<address>
  <streetAddress>21 2nd Street</streetAddress>
  <city>Santa Clara</city>
  <state>CA</state>
  <postalCode>11111</postalCode>
</address>
<phoneNumber>
  <type>home</type>
  <number>212 555-1234</number>
  <type>fax</type>
  <number>646 555-4567</number>
</phoneNumber>

XMLStreamingBuilder - XMLStreamingBuilder()

Instantiates the XMLStreamingBuilder object.

Table 7. Parameters
Name Type Description
None

Example

This example shows how to instantiate a builder object.

var builder = new sn_ih.XMLStreamingBuilder()