Using SOAP Services with Logic Apps

Guest Post by:
Wagner Silveira
Principal Integration Architect @ Theta
@WSilveiraNZ

Logic Apps is a new Microsoft cloud integration technology, currently in preview. It allows API centric workflows to be automated and executed within the Azure Platform. The technology is planned to be in general availability in Q2 2016, according to Microsoft’s Integration Roadmap published last year.

Logic Apps bases its actions on Managed Connectors and Custom APIs. Managed Connectors are APIs hosted within Azure that can be used to execute common workflow tasks, like sending an email via SMTP, or connecting to an SQL Server database hosted in Azure, while custom APIs are bespoke APIS created and deployed in the Azure Resource Group the Logic App resides in.

One connector that has been missing for some time is a SOAP connector. With a large ecosystem of SOAP services deployed today, interfacing all sorts of products, from SaaS offerings to custom web services, there is a good chance that integration workflows will need to use one of those services.

Whilst there is no managed SOAP connector, there are a couple of workarounds that can be applied when connecting a Logic App to a SOAP service. Developers can either connect to a SOAP service using the HTTP connector or, when that option is not suitable, they can leverage the Logic App ability to consume Custom APIs, wrapping the SOAP client code around an API App.

Calling SOAP services using the HTTP Connector

The HTTP Connector provides a simple way to connect to SOAP service, by leveraging the HTTP protocol that encapsulates SOAP. The main advantage of this method compared to the API App approach is that it does not add extra latency when invoking a service, as the connector is calling the actual service endpoint.

Using this approach, a user executes a POST call to a SOAP endpoint, configuring the required headers and the SOAP envelope as the body of the HTTP message:

To configure the HTTP Connector to call a SOAP service, the following parameters should be provided:

When invoking a SOAP service, at minimum, the following headers must be provided:

Content-type indicates The MIME type of the request body. This header is important, because SOAP 1.1 and SOAP 1.2 accept very specific content-types. When calling a SOAP 1.1 service, the content-type must be text/xml, while for SOAP 1.2, the content-type is usually application/SOAP+xml.

TIP: While usually you see the character set included with the Content-type header (e.g. Content-type: text/xml; charset="utf-8"), the Logic Apps HTTP connector does not accept the charset value, and it will always default the character set to utf-8. When the charset attribute is provided, the connector generates the following exception:

{"code":"BadRequest","message":"The provided workflow action input is not valid."}

The SOAPAction HTTP request header field can be used to indicate the intent of the SOAP HTTP request. The value is a URI identifying the intent. This value is mandatory for SOAP 1.1 web service calls, but it can be left empty.

For SOAP 1.2 the SOAP Action was replaced by the action attribute on the Content-type header, and its existence is mandatory or not based on the SOAPActionRequired flag defined on the Operation section within the service WSDL file.

When calling a SOAP service the authentication method and parameters required to authenticate the service are defined in the authorization header. One example of an authorization header using Basic authentication can be found below:

"Authorization: Basic <username>:<password>"

Notice that the value of username:password must be base64 encoded. So a sample authorization header looks like:

"Authorization: Basic ZGVmYXxxxxxxxxxx5PajVj"

As Logic Apps have a base64 encoder function available, a typical basic authentication header in a logic app code view would look like:

"Authorization":"Basic @base64('username:password')"

The HEADERS field expects a JSON array to be provided. So when providing one or more headers, the format should be:

{"header1":"value1","header2":"value2",…,"headern":"valuen"}

The example below shows the header parameter populated in the code view:

"headers": {

"Authorization": "Basic @base64('somevaluehere')",

"Content-Type": "text/xml",

"Soapaction": "https://tempuri.org/IEchoService/GetData"

},

When calling a SOAP web service using the HTTP Connector, the body of the call must include the full SOAP envelope. The snippet below shows an example of a SOAP envelope:

<SOAPenv:Envelope xmlns:SOAPenv= ’https://schemas.xmlsoap .org/ soap /envelope/’ >

<SOAPenv:Header/>

<SOAPenv:Body>

<MyBodyData xmlns=”urn:mynamespace”>

<Myparameter>SomeValue</Myparameter>

</MyBodyData>

</SOAPenv:Body>

</SOAPenv:Envelope>

Notice that the SOAP envelope is defined as an XML message. This is not the Logic Apps native format, so a process to create the SOAP message, and to parse the response messages, is required.

While creating a request, this process can be as simple as injecting parameters on a SOAP envelope skeleton, thanks to the parsing capabilities of Logic Apps.

Tip: The SOAP envelope headers and the content of the body will be specific to a service call, based on a WSDL. One of the simplest ways to create the skeleton of a SOAP envelope required for a given operation is to use a SOAP testing tool like SOAP UI, which would auto-generate the web service request in XML format.

More complex cases can leverage the Microsoft Azure BizTalk Service (MABS) XML Transform Connector in conjunction with the JSON Encoder – first converting a JSON input message into XML, then transforming it into the format required using the Tranform Connector. There is also an open source API created by the Logic Apps team that allows a user to execute C# code snippets, which can be useful when creating the SOAP body request.

Transforming body responses into JSON can be done by similar techniques, using the MABS JSON Encoder Connector to convert from XML into JSON or using the C# code snippet API.

API App Wrapper

The HTTP Connector allows you to consume SOAP services just with configuration, but it does not cover all scenarios. Some of the implementations of SOAP and some authentication methods are too complex to be handled by the HTTP connector. .NET Framework and WCF offer a lot of flexibility when communicating with a SOAP service. Another option when consuming SOAP services, therefore, is to encapsulate a WCF proxy client in an API App. This method brings some advantages when used in conjunction with Logic Apps:

• Native JSON request and response, thanks to the API App framework, so no generation of message or parsing of response.
• Swagger based API allows for auto discovery of the API, allowing the visual input of the action parameters and auto-discovery of the response fields within a Logic App.
• Hide complexity of the implementation - like custom behaviours, complex authentication, etc - from the Logic App layer.

Wrapping a SOAP service with an API App is as simple as following these steps:

1. Create a proxy client of the SOAP service to integrate - Visual Studio offers a straightforward way to create the client, using WCF.
2. Create a new Controller class. For each SOAP operation that needs to be exposed, create a new method on the controller. Depending on the requirements, the input and output of the operation can be exactly the same as the original operation, or some changes can be implemented to simplify the operation or to do some initial transformation where required.

Notice that while creating the controller methods, each method can be decorated with the correspondent HTTP verb. This can help identifying the purpose of each method, as per RESTful design.

Once the API is implemented and deployed, it can be accessed in two ways:

1. If the API was deployed on the same resource group as the Logic App, the API auto-discovery feature implemented on Logic Apps will allow you to select the exact API.
2. If the API was deployed in a different resource group, the HTTP + Swagger action will allow you to include the Swagger definition of the API, and from there select the appropriate method.

Summary

SOAP services are still an important piece of the integration landscape. Logic Apps supports consumption of SOAP services in two ways:

Using the HTTP Connector - this provides out-of-the box, configuration only support for SOAP services, by implementing an HTTP Request which contains a SOAP envelope. This method can be used for many interactions, and has the following pros and cons:

Pros:

• No added latency when consuming the SOAP services, as the HTTP Connector will call the actual service.
• No extra development effort required to execute the service, as the HTTP Connector is one of the managed connectors.

Cons:

• This method requires extra steps to create the message body and to parse the message response, as request and response bodies are an XML based SOAP envelope, which are not parsed by Logic Apps natively.
• Some complex scenarios might not be easily implemented, and would require vast knowledge of HTTP request setup in special HTTP headers.

Creating an API App Wrapper - this method uses an API App to wrap the consumption of a SOAP service. The API App presents the operations to the logic app in a format that it can consume. This method can be used for any scenario, with the following pros and cons:

Pros

• Standardization for SOAP services consumption, as any SOAP service that can be consumed by .NET can leverage this technique to be exposed to a Logic App.
• Uses the extensibility and flexibility of WCF to enable complex scenarios.
• The additional layer of indirection provides the opportunity for request and response messages to be pre-processed. This might simplify some of the calls.

Cons

• Adds latency to the SOAP service call, as there is an extra layer of code before the actual SOAP service is called - this might be an issue when performance is important.
• Extra development and deployment effort required.

Currently, a SOAP connector feature is under review on the Logic Apps User Voice feedback forum. The Logic Apps team uses a voting system to choose which suggestions from the community will be included in future sprints. More information on the status of the SOAP connector feature can be found here: https://feedback.azure.com/forums/287593-logic-apps/suggestions/11680188-add-a-SOAP-connector.

• Anonymous
  April 07, 2016
  When wrapping SOAP client, we need to map from JSON request/response to XML, right?
• Anonymous
  September 03, 2016
  The comment has been removed