Google Apps Script

SOAP Overview

SOAP was originally defined as the Simple Object Access Protocol - now known simply as SOAP. It is an XML based protocol that facilitates access to Web Services. SOAP allows for disparate systems to connect to each other over the standard HTTP protocol.

The new Apps Script functionality helps to make it easy to construct calls to SOAP functions (known as 'operations'), and then parse the resulting XML return values.

To begin using SOAP from Google Apps Script, you'll need the basic information about the service you plan to access. SOAP Services are defined by a WSDL file - Web Services Definition Language. This Service Definition provides all the details that Apps Script needs to invoke the operations of that service (akin to functions or methods in Apps Script). The WSDL file is generally provided at a URL associated with that service.

The WSDL file provides details on operations (functions/methods) provided by the service, and the parameters that must be provided to invoke each operation. Apps Script will automatically package up the requests, invoke the operations, and unpack the responses automatically - saving a significant amount of potentially error-prone coding.

Contents

SOAP Walkthrough

To use a SOAP service from Google Apps Script, there are a set of common steps that you will need to perform. These steps are listed below and include links to examples that use real SOAP services so that you can see them in action.

  1. To begin using the SOAP service, the web address for the WSDL file describing the service is required. This web address can be used to create a Wsdl that can then be used to access the SOAP service on the internet (or on your intranet if SDC is enabled). (example)
  2. Once the Wsdl object has been created, its service names can be queried to find the relevant service. (example)
  3. Once the name of the desired service is found, a WsdlService object describing that service can be retrieved from the Wsdl object. (example)
  4. Once the WsdlService object is obtained, the names of the available SOAP operations can then be found. (example)
  5. To invoke a web service, you will normally have to provide arguments with your request. (example)
  6. SOAP operations can then be invoked off the WsdlService in several ways. Debugging methods are also included to help diagnose SOAP errors. (example)
  7. An invoked SOAP operation will return its result as an XmlElement object. This can then be queried or manipulated as necessary. (example)

Shorthand XML

Because XML is used so often in SOAP, Apps Script provides an advanced shorthand form to construct XML documents. This shorthand form can be used interchangeably with the XML objects demonstrated in the accompanying tutorials, but it is far more concise, allowing you to focus more on the content of the document and not on the steps to actually construct it.

In the shorthand, JavaScript arrays can be used for XML elements, and JavaScript associative arrays (maps or objects) can be used for attributes.

Say you wanted to create the following snippet of XML:

  <GetGeoIP xmlns="http://www.webservicex.net/">
    <IPAddress>{ipAddress}</IPAddress>
  </GetGeoIP>

(where {ipAddress} was a dynamic value that you would supply at runtime).

The default way of constructing this snippet of XML would be:

  var param = Xml.element("GetGeoIP", [
                Xml.attribute("xmlns", "http://www.webservicex.net/"),
                Xml.element("IPAddress", [
                  ipAddress
                ])
              ]);

However, with the shorthand form, you can instead write:

  var param = [ "GetGeoIP",
                { "xmlns" : "http://www.webservicex.net/" },
                [ "IPAddress", ipAddress ]
              ];

The format of this shorthand is as follows:

  • XmlElements are represented as a JavaScript array with a String in the first position. The value of this string will become the tag name of the generated element.
  • All following elements in the array become children of the XmlElement using the following rules
  • Associative arrays that map Strings to Strings are transformed into XmlAttributes on the containing XmlElement. They key in the associative array will become the attribute name and the value in the associative array will become the attribute value.
  • Array children themselves are recursed upon and transformed into XmlElement children if they match the first rule
  • All other children are converted into strings are are stored as XmlText children in the containing XmlElement

SOAP Header

Occasionally a SOAP service will require additional information to be sent along with a SOAP operation. For example, some SOAP services require authentication parameters to be sent in a special header section of the request. The SOAP service allows you to pass along this information by passing an additional argument in the invocation call like so:

  var header = Xml.element(...);
  var result = geoService.GetGeoIP(param, header);

To verify what the message will look like before actually sending it, the getSoapEnvelope method can then be used like so:

  var header = Xml.element(...);
  var envelope = geoService.getSoapEnvelope("GetGeoIP", param, header)
  Logger.log(envelope);

Accessing Intranet Services

If you have SOAP Services that are only available in your intranet and you've already set up SDC for your enterprise, then you can access your SOAP Service from Google Apps Script by passing true to the useIntranet parameter of SoapService.wsdl like so:

  var wsdl = SoapService.wsdl(wsdlAddress, true);

From then on, all network communication will be performed over SDC so that it can access your internal SOAP Service.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.