GuidesReferenceChangelogVideosDiscord
Sign UpLogin

OBJECT_TO_SOAP

The function OBJECT_TO_SOAP takes an Object and returns a string representing the equivalent XML object in a SOAP envelope.

This function takes a single Object as input. It returns a string which can be parsed as the equivalent XML object in a SOAP envelope.

This function is also capable of parsing modifiers that define formatting and wrapping elements that have no one-to-one equivalent in Airscript Objects. These modifiers make it possible to use the OBJECT_TO_SOAP function to create SOAP envelopes with roots, headers, namespaces, and more. Modifier details must be specified in a single modifier Object that the OBJECT_TO_SOAP function accepts as optional input.

Declaration

OBJECT_TO_SOAP(object, header, modifier) -> soap

Parameters

object (required, type: Object)
Any Object.

header (generally optionally but required by modifier, type: Object)
The header that will be assigned to the equivalent SOAP envelope.

modifier (optional, type: Object)

An object with one or many of the following properties:

  • format (optional, type: boolean, default: FALSE) - Defines whether the returned XML document will be rendered to eliminate whitespace or rendered to be indented and readable. FALSE means that it will be rendered to eliminate whitespace, TRUE means that it won't.
  • attributeNamePrefix (optional, type: string, default: "@") - Defines the string that will distinguish XML elements from XML attributes. Properties of the object prefixed by the attributeNamePrefix will be rendered as XML elements rather than attributes.
  • soapVersion (optional, type: string, default: "1.1") - Defines which SOAP version will be used to construct the SOAP envelope.
  • soapPrefix (optional, type: string, default: "soap") - Defines the namespace prefix for the SOAP envelope, body, and header.
  • root (generally optional but required by namespace, type: string, default: NULL) - Defines the outer element of the SOAP body.
  • namespace (optional, type: string, default: NULL) - Defines the XML namespace that the SOAP body contents will be placed in. This property must be in an Object containing the root property in order to be correctly parsed.
  • headerRoot (generally optional but required by headerNamespace, type: string, default: NULL) - Defines the outer element of the SOAP header.
  • headerNamespace (optional, type: string, default: NULL) - Defines the XML namespace that the SOAP header contents will be placed in. This property must be in an Object containing the headerRoot property in order to be correctly parsed.

Return Values

soap (type: text)
The SOAP envelope equivalent to the given object.

Examples

When given an Object, the OBJECT_TO_SOAP function will create an envelope for it:

OBJECT_TO_SOAP({ "key": "value" }) -> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Header/><soap:Body><key>value</key></soap:Body></soap:Envelope>

In order to define an outer element of the SOAP body, a root will need to be explicitly defined using a modifier Object with a root property. In order for the OBJECT_TO_SOAP function to parse a modifier Object, it will also need to be assigned a header, as follows:

OBJECT_TO_SOAP(
  {
    "name": "Joan Smith",
    "title": "CEO",
    "id": "01-0001768"
  }, {"header": "contact"},
  { "root": "request" }
) -> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Header><header>contact</header></soap:Header><soap:Body><request><name>Joan Smith</name><title>CEO</title><id>01-0001768</id></request></soap:Body></soap:Envelope>

The modifier Object can contain multiple properties. For instance, the following example uses:

  • the format property to produced legible, indented XML,
  • the soapVersion property to construct a SOAP envelope according to the syntax of SOAP version 1.2,
  • the soapPrefix property to define namespace prefix of the SOAP envelope, body, and header as "FOO",
  • the root property to wrap the SOAP body as "request",
  • the namespace property to place the contents of the SOAP body in the namespace "https://tempuri.org",
  • the headerRoot property to wrap the SOAP header as "header_request", and
  • the headerNamespace property to place the contents of the SOAP header in the namespace "https://tempuri.org":
OBJECT_TO_SOAP(
  {
    "name": "Joan Smith",
    "title": "CEO",
    "id": "01-0001768"
  },
  { "header": "contact" },
  {
    "format": TRUE,
    "soapVersion": "1.2",
    "soapPrefix": "FOO", 
    "root": "request",
    "namespace": "https://tempuri.org",
    "headerRoot": "header_request",
    "headerNamespace": "https://tempuri.org"
  }
) -> <FOO:Envelope xmlns:FOO="http://www.w3.org/2003/05/soap-envelope">
  <FOO:Header>
    <header_request xmlns="https://tempuri.org">
      <header>contact</header>
    </header_request>
  </FOO:Header>
  <FOO:Body>
    <request xmlns="https://tempuri.org">
      <name>Joan Smith</name>
      <title>CEO</title>
      <id>01-0001768</id>
    </request>
  </FOO:Body>
</FOO:Envelope>

The default value of the attributeNamePrefix is "@", which means that properties of the given SOAP body prefixed by "@" will be rendered as XML elements rather than attributes, such as what happens to the id property in the following example:

OBJECT_TO_SOAP(
  {
    "name": "Joan Smith",
    "title": "CEO",
    "@id": "01-0001768"
  },
  { "header": "contact" },
  {
    "format": TRUE,
    "root": "request"
  }
) -> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <header>contact</header>
  </soap:Header>
  <soap:Body>
    <request id="01-0001768">
      <name>Joan Smith</name>
      <title>CEO</title>
    </request>
  </soap:Body>
</soap:Envelope>

You can also add a attributeNamePrefix property to the modifier Object to define it differently. For instance, the following example defines attributeNamePrefix as "element_". Note how this then results in the character "@" being parsed just like any other character:

OBJECT_TO_SOAP(
  {
    "name": "Joan Smith",
    "title": "CEO",
    "element_id": "01-0001768"
  },
  { "header": "contact" },
  {
    "format": TRUE,
    "root": "request",
    "attributeNamePrefix": "element_"
  }
) -> <soap:Envelope>
  <@xmlns:soap>http://schemas.xmlsoap.org/soap/envelope/</@xmlns:soap>
  <soap:Header>
    <header>contact</header>
  </soap:Header>
  <soap:Body>
    <request id="01-0001768">
      <name>Joan Smith</name>
      <title>CEO</title>
    </request>
  </soap:Body>
</soap:Envelope>