Soap API Connector

The soap connector is used to hit SOAP based endpoints. It’s body contains a mapped XML to JS payload.
To convert a SOAP payload to JSON, use the xml-js NPM module in “compact” format, e.g.:

  xml-js soap.xml --compact

Then, this payload can be substituted into your BaaS connector body:

{
  "Alias": "MySoapConnector",
  "Type": "soap",
  "Endpoint": "https://graphical.weather.gov:443/xml/SOAP_server/ndfdXMLserver.php",
  "Body": {
    "_declaration": {
      "_attributes": {
        "version": "1.0"
      }
    },
    "soapenv:Envelope": {
      "_attributes": {
        "xmlns:ndf": "https://graphical.weather.gov/xml/DWMLgen/wsdl/ndfdXML.wsdl",
        "xmlns:soapenv": "http://schemas.xmlsoap.org/soap/envelope/",
        "xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
        "xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance"
      },
      "soapenv:Body": {
        "ndf:CornerPoints": {
          "_attributes": {
            "soapenv:encodingStyle": "http://schemas.xmlsoap.org/soap/encoding/"
          },
          "sector": {
            "_attributes": {
              "xsi:type": "xsd:string"
            }
          }
        }
      }
    }
  },
  "Headers": {
        "Content-Type": "text/xml"
  },
  "Method": "POST",
  "RequestMapping": {
    "sector": {
      "inputPath": "$.sector",
      "requestBodyPath": "$[\"soapenv:Envelope\"][\"soapenv:Body\"][\"ndf:CornerPoints\"][\"sector\"][\"_text\"]",
      "type": "requestBody"
    }
  },
  "ResponseMapping": {

  },
  "RestrictionGroup": "12345678-1234-1234-1234-123456789012" //optional, see Restriction Groups
}

For reference, here is the XML SOAP request and response.

A POST is performed to https://graphical.weather.gov:443/xml/SOAP_server/ndfdXMLserver.php

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ndf="https://graphical.weather.gov/xml/DWMLgen/wsdl/ndfdXML.wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <ndf:CornerPoints soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <sector xsi:type="xsd:string">conus</sector>
      </ndf:CornerPoints>
   </soapenv:Body>
</soapenv:Envelope>

And the response is :

<?xml version="1.0" encoding="ISO-8859-1"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <ns1:CornerPointsResponse xmlns:ns1="https://graphical.weather.gov/xml/DWMLgen/wsdl/ndfdXML.wsdl">
            <listLatLonOut xsi:type="xsd:string">&lt;?xml version=&apos;1.0&apos;?&gt;&lt;dwml version=&apos;1.0&apos; xmlns:xsd=&apos;http://www.w3.org/2001/XMLSchema&apos; xmlns:xsi=&apos;http://www.w3.org/2001/XMLSchema-instance&apos; xsi:noNamespaceSchemaLocation=&apos;https://graphical.weather.gov/xml/DWMLgen/schema/DWML.xsd&apos;&gt;&lt;minResolution&gt;304.000000&lt;/minResolution&gt;&lt;latLonList&gt;20.191999,-121.554001 20.331773,-69.208160 50.105547,-60.885558 49.939721,-130.103438&lt;/latLonList&gt;&lt;/dwml&gt;</listLatLonOut>
        </ns1:CornerPointsResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

For mapping of request and response parameters, see SOAP API Request & Response Mapping.

AWS SDK Connector

The aws-sdk BaaS connector allows you to directly call a functionality within the AWS SDK.

{
  "Alias": "detectSentiment",
  "Body": {},
  "Credentials": "srn:vault::goes::here",
  "Type": "aws-sdk",
  "Endpoint": "Comprehend",
  "Method": "detectSentiment",
  "RequestMapping": {
    "LanguageCode": {
      "inputPath": "$.LanguageCode",
      "requestBodyPath": "$.LanguageCode",
      "type": "requestBody"
    },
    "Text": {
      "inputPath": "$.Text",
      "requestBodyPath": "$.Text",
      "type": "requestBody"
    }
  },
  "Region": "eu-west-1"
}

aws-sdk BaaS entries require your AWS credentials in order to function. They should be saved as a Secret, and then referenced by the Credentials property.

The Endpoint field maps to the name of the AWS service you are calling in the aws-sdk. In this example, we’re using the Comprehend service; the Method is the function to call in that service, which is detectSentiment in this case.

SOAP API request and response mapping

The following API connector is used to make a request to an endpoint that performs basic mathmatical calculations.

{
  "Method": "POST",
  "Endpoint": "https://a5cw4kf88j.execute-api.eu-west-1.amazonaws.com/hedev/soap-on-a-rope/wsdl",
  "Headers": {
    "Content-Type": "text/xml"
  },
  "Alias": "somename",
  "Organization": "yourorg",
  "Updated": 1574174250115,
  "RequestMapping": {
    "valB": {
      "type": "requestBody",
      "requestBodyPath": "$[\"soapenv:Envelope\"][\"soapenv:Body\"][\"AddFunctionRequest\"][\"valB\"][\"_text\"]",
      "inputPath": "$.valB"
    },
    "valA": {
      "type": "requestBody",
      "requestBodyPath": "$[\"soapenv:Envelope\"][\"soapenv:Body\"][\"AddFunctionRequest\"][\"valA\"][\"_text\"]",
      "inputPath": "$.valA"
    }
  },
  "ResponseMapping": {},
  "Type": "soap",
  "Body": {
    "_declaration": {
      "_attributes": {
        "version": "1.0"
      }
    },
    "soapenv:Envelope": {
      "_attributes": {
        "xmlns:soapenv": "http://schemas.xmlsoap.org/soap/envelope/",
        "xmlns:tem": "http://tempuri.org/"
      },
      "soapenv:Body": {
        "AddFunctionRequest": {
          "valA": 0,
          "valB": 0
        }
      }
    }
  },
  "Created": 1574174250115,
  "Srn": "srn:baas:REGION:ORGANIZATION:api-connector:soap"
}

This endpoint’s service has 4 possible functions, but for this example we are only testing AddFunctionRequest. SubtractFunctionReques, multiplyFunctionRequest etc are also available. The structure of the XML request to this soap service is as follows:

SOAP request format

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <tem:AddFunctionRequest>
         <tem:valA>2</tem:valA>
         <tem:valB>2</tem:valB>
      </tem:AddFunctionRequest>
   </soapenv:Body>
</soapenv:Envelope>

The soapenv:Envelope section in the body of the API connector replicates this request and is converted to XML before being sent to the endpoint. In this case it is ok to omit the tem: namespace. For demonstration purposes, here we will provide an execution json file, but in practice, a bot or worker will utilise the API connector. Note that the values of 0 in the body of the API connector are default values to be replaced by the values in the execution file.

SOAP API connector execution script

{
  "Alias": "soap",
  "valA": 2,
  "valB": 2
}

valA in the execute json file is mapped to valA in the body of the API connector using the requestBodyPath:

"$[\"soapenv:Envelope\"][\"soapenv:Body\"][\"AddFunctionRequest\"][\"valA\"][\"_text\"]"

and likewise valB in the execute json file is mapped to valB in the body of the API connector using the requestBodyPath:

"$[\"soapenv:Envelope\"][\"soapenv:Body\"][\"AddFunctionRequest\"][\"valB\"][\"_text\"]"

valA and valB are retrieved from the execute json file via the inputPaths “$.valA” and “$.valB”.

The unmapped response from this request is as follows:

Response without response mapping

{
    "response": {
        "xml": "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"  xmlns:tns=\"http://tempuri.org/\" xmlns:tm=\"http://microsoft.com/wsdl/mime/textMatching/\"><soap:Body><AddFunctionResponse xmlns=\"http://tempuri.org/\"><result>4</result></AddFunctionResponse></soap:Body></soap:Envelope>",
        "json": {
            "_declaration": {
                "_attributes": {
                    "version": "1.0",
                    "encoding": "utf-8"
                }
            },
            "soap:Envelope": {
                "_attributes": {
                    "xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/",
                    "xmlns:tns": "http://tempuri.org/",
                    "xmlns:tm": "http://microsoft.com/wsdl/mime/textMatching/"
                },
                "soap:Body": {
                    "AddFunctionResponse": {
                        "_attributes": {
                            "xmlns": "http://tempuri.org/"
                        },
                        "result": {
                            "_text": "4"
                        }
                    }
                }
            }
        }
    },
    "statusCode": 200,
    "duration": 256
}

However this may be a bit unwieldly, so if we’re only interested in a portion of this response, we can do some response mapping to remedy this. So replace:

"ResponseMapping": {}

with…

 "ResponseMapping": {
    "result": {
      "type": "responseBody",
      "responseBodyPath": "$[\"json\"][\"soap:Envelope\"][\"soap:Body\"][\"AddFunctionResponse\"][\"result\"][\"_text\"]",
      "outputPath": "$.result"
    }
  }

This will extract the result from the responseBodyPath (which mirrors the json path in the response before the response mapping) and map it to the key result as stated in the outputPath (i.e. “$.result”). The resulting mapped response, as follows, extracts only the information that we are interested in.

Response with response mapping

{ response: { result: '4' },
  statusCode: 200,
  duration: 1288,
  headers: {}
}