Connecting to a SOAP API

iPaaS Documentation Connection Guides
1

Table Of Contents

  • Introduction
  • Step 1: Create a SOAP Client
    • Step 1a: Setting the basics
    • Step 1b: Setting the WSDL
    • Step 1c: Configuring the SOAP endpoint
    • Besides the configuration above, there are more optional configurations available. They are described below.
  • Step 2: Interacting with the SOAP client
    • Step 2a: Creating an incoming configuration
    • Step 3b: Creating an outgoing configuration

Introduction

A SOAP client represents a (remote) web service that is used to read and/or write data. Many systems offer some sort of connectivity through SOAP services. Alumio allows you to create these integrations using SOAP clients.

For this guide, we will be connecting to a public SOAP API, without any authentication. The steps are described below.

Step 1: Create a SOAP Client

This section will explain how to set up a SOAP Client that can be used to consume one or more endpoints of a system.

Step 1a: Setting the basics

First, it is time to set up the basic information by following these steps:

  • Navigate to Clients → SOAP Clients and create a new SOAP Client configuration by hitting the + icon on the right upper side of the screen.
  • Fill in the Name field - please note that while the identifier field is required, it will automatically be generated based on the name.
  • If needed, provide a description of the SOAP Client configuration.
  • If needed, disable the SOAP Client to prevent any communication from or to the system.

Step 1b: Setting the WSDL

Most SOAP services make use of a WSDL file. WSDL is short for Web Services Definition Language and describes the available endpoints on a SOAP service. Alumio uses this WSDL file to construct the appropriate SOAP requests. This is important because within Alumio you are working with JSON while SOAP uses XML.

To configure the WSDL you may select one of the following options:

  • File - In case the WSDL is exposed on a filesystem such as an FTP, sFTP, or Amazon S3 bucket you may use the filesystem. You may follow the guide found here to set up the connectivity between Alumio and the filesystem.
  • HTTP - Most SOAP services expose their WSDL through a (publicly) accessible HTTP endpoint. When selecting the HTTP option you are able to consume WSDLs offered this way. The WSDL might be protected by some form of authentication. You may set up an HTTP Client to handle this for you.
  • Non-WSDL - Some SOAP services do not use a WSDL and this option allows you to work with those.
  • Plain - Some SOAP services do not expose their WSDL through a filesystem or HTTP connection. For these purposes, you can use the plain WSDL within the text field.

When selecting either File or HTTP for the WSDL you are given the possibility to create an Alumio storage that will act as a cache for the WSDL file. This greatly reduces the number of requests done to the SOAP service, as it will no longer retrieve the WSDL file for each interaction.

Step 1c: Configuring the SOAP endpoint

Now that you’ve set up the basics and configured the WSDL file, it’s time to finalize the SOAP Client. To do so, you must select the applicable SOAP version. Currently, Alumio offers support for SOAP 1.1 and SOAP 1.2 . Next to that, you must configure an HTTP Client on which you may configure any required authentication. When there is no (HTTP) authentication present on the SOAP service it is sufficient to select the Default Client.

(Optional) Step 2d:

Besides the configuration above, there are more optional configurations available. They are described below.

  • Keep binary data base64 encoded - This is useful when the SOAP service is returning binary data (such as PDF files, images, etc) that need to be sent to another system. By default, Alumio will try to decode the binary data which may be problematic when you want to send over PDF Files. Enabling this option will prevent Alumio from decoding the data so you may use it within your integration.
  • SOAP Headers - Some SOAP services require header values to be added to each request. Using the SOAP Headers you may configure these headers.

Step 2: Interacting with the SOAP client

Now that you have set up the SOAP client, you can interact with it through an incoming or outgoing configuration. Incoming configurations allow you to read data from a SOAP client, while an outgoing configuration will enable you to send data to a SOAP client.

Step 2a: Creating an incoming configuration

Click here to review the general guide on incoming configurations in order to get familiar with their purpose.

First, choose the relevant subscriber prototype: SOAP Subscriber

Now it’s time to fill in the required fields and set up the connection.

  • Request Method - The SOAP method you want to consume from the web service. I.e. getOrders, getCustomer, getInvoiceOverview
  • Request Data - The data that needs to be sent to the SOAP service. This could contain information such as order numbers, dates, customer information.
  • SOAP Client - The SOAP Client used to set up this connection. All settings of the SOAP Client are inherited when this configuration is executed.
  • Input Transformer - Used to set up dynamic values that can be used within this configuration. I.e. getting today’s date, retrieving pagination from storage, or other uses.
  • Response validator - Some SOAP services may return the error in the body, while still returning a 200 OK status code. Alumio will wrongfully assume everything went as expected. By setting up a response validator you can instruct Alumio to recognize those errors.

Step 3b: Creating an outgoing configuration

Click here to review the general guide on outgoing configurations in order to get familiar with their purpose.

First, choose the relevant publisher prototype:

  • SOAP Publisher - Select this publisher to perform a single API call.
  • Chain SOAP Publisher - Select this publisher in case you need to send multiple API calls. I.e. posting orders to an ERP system, retrieving the ERP order ID, and writing the ERP order ID back to the webshop.

Now it’s time to fill in the required fields.

  • Request Method - The SOAP method you want to consume from the web service. I.e. setOrder, setCustomerAddress, createInvoice
  • SOAP Client - The SOAP Client used to set up this connection. All settings of the SOAP Client are inherited when this configuration is executed.
  • Response validator - Some SOAP services may return the error in the body, while still returning a 200 OK status code. Alumio will wrongfully assume everything went as expected. By setting up a response validator you can instruct Alumio to recognize those errors.

The request data is inherited from your task entity data.

Note: When configuring the SOAP Transformer, SOAP Publisher, and SOAP Chain Publisher, all errors on requests which return a non-200 response, can be ignored. This is made to prevent users from being blocked by any occurring error during response, therefore, it’s possible to use other options in the Alumio functionality.