FileMaker – Best way to use SOAP services

Now and then you have to implement some SOAP web-services into your FileMaker solution. FileMaker does not have a built in Web Service Wizard or SOAP client support. This article will go through the method to implement this the most effective way I know about.

The big advantage of SOAP API’s

There is a lot of different API-flavours out there. Different difficulty levels to implement, but all have this common move that they accept connections, sending a request, and give responses in one form or another.  The formatting of the request and the format of the returned data is described in the API documentation. However, in a SOAP API, we use a WSDL file that is used both on the server side and the client side, and at the same time acts as an important documentation document makes the security of implementing the API that each message is formatted correctly and contain all the required elements in both directions. One cannot change the requirements or the contents of the data-elements on the server side without also changing the WSDL, so in this way, there is a guarantee that the documentation is up-to-date all the time.

Many development tools have built in SOAP Client wizards that help you implement the service, so it is not very difficult in most cases.

How do we do it in FileMaker?

In this tutorial, we will implement an online barcode generator Webservice into our FileMaker application. This can be useful for printing labels and so on.

The demo FileMaker database is available at the bottom of the article.

We depend upon one external plugin to do the HTTP(S) access necessary. SOAP services use the POST protocol, so any insert from URL calls are off the board for this implementation. I will use the TROI URL plugin for this as my recommendation. The version 4.1 of this plugin is a minimum.

There is also a number of tools needed in this tutorial. Some are free, and some at fairly low cost. Here is the list.

  • PAW (MacOS) – Utility to do web-service testing on MacOS. It cost about 49 USD. This software is not used in this particular demonstration but is a very good tool if your service does not behave as expected. You can test the service, and see what responses you get.
  • Any XML or ASCII file editor to edit XML. I am using Oxygen XML editor or BBEdit for that, but any clean text editor will do.
  • Online WSDL analyzer, at www.wsdl-analyzer.com. Used for documentation and generating request templates for our service implementation.
  • To do an import of SOAP service requests, we do need TROI FILE plugin to save the content of the SOAP result to a temporary file.
  • Additionally, the site xmlbeautifier.com is a good tool, when you cut & paste XML responses from the FileMaker data viewer. The XML often comes in one long line and is not easily readable. copy and paste it into this site, and hit “beautify” does the trick.

The WEB service documentation

Most Web services have a comprehensive documentation. Sometimes, it is easy to get lost in the documentation provided as it is so comprehensive and yet fails to provide the simplicity we need to get an overview. The most important piece of documentation we need is the WSDL file itself. This contains almost everything you need to set up the service calls. As the WSDL file is a bit complicated, we use an online tool called WSDL-analyzer that provide us with that simplicity we need.

In order to use it, we will first download the WSDL file for the web service. The WSDL URL is provided from the provider of the service. In this example, it is :

http://www.webservicex.net/genericbarcode.asmx?WSDL

Open the link, and save the file. Rename extension to be “.wsdl”. Go to WSDL-analyzer, and upload the WSDL file. Sometimes, it does not open after upload, but a refresh works well in most cases.

Scroll down to the section of “PortType” where you have all the operations available for that Webservice. Click on the actual “operation” in the left column of the table.

Then you will see a page containing the request template to use.

Copy and paste the Request template into a text editor or an XML-editor, to edit the template. We want to create a custom function that does the whole soap request and return the actual XML response we get from the service. In this way, we can reuse the code in many places, and easily copy the function between several FileMaker databases.

The request template:

First, we must get rid of double quotes – if any. We replace them with single quotes so we can encapsulate the whole block in double quotes in the custom function. There aren’t any in this example, so we go on.

We need to decide which optional parameters to use. Those we don’t use, we cut out.

Then we add placeholder text for the parameters we do want to use. The parameters we want to have a fixed value, we just type that.  The placeholders will be replaced in our custom function with the parameter values of our custom function.

Our Custom Function.

In FileMaker, we open our solution, and go to Custom Functions, and create a new. We can use this as a template for it for later SOAP services, but here is the one I have created for this service:

Soap_BarCode ( vUrl ; Height ; Width ; Angle ; Ratio ; Module ; LeftPos ; TopPos ; BarColor ; BGColor ; FontSize ; barcodeOption ; barcodeType ; showTextPosition ; BarCodeText )

A second useful Custom Function – to extract XML tags from the response.

ExtractXMLData ( XML ; Attribute ; Instance )

 

The Script

I created a table for use with this test application. It basically contains a container field to show the image and each parameter to the service. The Table def looks like this.

A little script now to call the service:

 

The result:

The practical use of this particular Webservice

In this example, I have populated all the parameters in this table, just to be able to experiment with the different parameters. However, in a practical implementation, one would just use the container field on the record containing the data this barcode is about, to example a product. Then, in the call to our custom function, just apply the values needed as constants, except for the barcode text of course. The call to this function could be in a trigger script on the barcode-text field, where it is called each time the barcode text is changed.

Download the example file:

PS – You need to install the TROI URL plugin in order to get this demo to work.

SOAP-Barcode-Example.fmp12

Leave a Reply

Your email address will not be published. Required fields are marked *