Communicating with Apple Web Services (GSX) via Filemaker

Web services according to WikiPedia is "a method of communication between two electronic devices over a network." There are websites that provide information as a service. Sites like Google Language API which allows you to translate your website directly without you having to create the translation yourself. This means you could translate your web site to hundreds of languages just with the web services code.

In plain language, web services allows you to call a web site from your website by providing a request, or consuming a request ( a most confusing term), with some data. The web site will then provide you with the result. For example, I send a request to Google Language API with "Japanese" as the required language and "How to speak Japanese" as the data. Google Language API will understand your request and responds with the result as "日本語を話す方法". When you change the language to Korean, and use back the same data, the API will respond with "일본어를하는 방법". Isn't that easier than you writing three different pages each with a different language?

Some web sites provide more than just one functionality. You can actually use the service to perform various actions by using it like a "function" with "parameters". In layman language, it means you need to tell the web service what you want to do with the data provided by you. The web services will understand your request and perform the exact action then return you the result. For example, I can go to a plant information web site and do search, update, create, delete, etc. just by calling the same address with different info.

In a web page, we will normally use Javascript to do the calling and showing the response using the technique call AJAX and a newer technique called JSON as data. It has all the functionality available to do it. You just need to compose what to send and get what is returned.

I have the opportunity to write programs using Filemaker (A database program owned by Apple). It has very good interface that allow very easy creation of database interfaces and web pages. However, its scripting facility is a bit lacking. This is especially true when trying to use the technology above to do translation. You practically have to write a code to do the functionality then write the code that make use of the functionality. That is double the work. Luckily there are plug-in that expand the capability of the application.

The following is a description of what I did to call a Web Service from Apple itself using Filemaker. It is a web service provided by Apple to its agents that provide repair services to its customers. The service provides a number of requests with its associated data. For example, if I need to order a spare part, I will call the web services with the request "orderPart" and "xxxxxx" as part number. Apple will then create an entry in its database that records your request and then send the part to you.

The request is send as a XML that contains the "request action" and the data. The response is also a XML that contains the result of the request. In this way user will see the same display yet the transaction is made in the back ground. The Filemaker program will then display the respond data so that user can see the result of the transaction.

Actually it is easier said than done. There is no such functionality available to talk to web services. Filemaker does have a "insert from URL" function that could call a web site and display the result in a field (a place where you can type in a form). However, it only shows the XML returned from Apple directly which is mostly not understood by user. Its XML facility is also not suited for manipulation with XML in this way. Thus the task is to create a code that could call the web services, send the request in XML format and translate the result to user in a readable format.

The very first task is to create the proper XML. Since there is no such function, it has to be created. XML node is generally in the form "<node>value</node>". As you can see, creating it is not a problem. So instead of typing the "node" and the "value" manually, you just need to call the subscript and pass it with the correct parameters.

Problem is that Filemaker (FMP) cannot pass multiple parameters. It does not have arrays too. There is, however, a "List" function that you can use like "list(value1,value2)". Thus you must combine the two information into one by using "list" before passing it as a parameter. You can even create a sort of array by creating a list within a list.

The XML example above is the basic format. XML, like HTML, also can contain properties. It is in the form "<node property='xxxx'>value</node>". Obviously these nodes can be nested. Setting the property nodes aside (as it is normally not used in "body"). There are four ways to create the XML.

1. The beginning node ("<node>"). With this and the ending node, you can create a nested node to what ever level you want.
2. The ending node ("</node>")
3. The complete node with value ("<node>value</node>").
4. The NULL node ("<node/>")

It is very easy to take the first parameter and treat it as a node by enclosing it with "<" and ">". The value is placed next then the first parameter is used again by enclosing it with "<" and ">".

For those that only need the node name like 1,2, 4 above. It is constructed accordingly.

The value must not contain characters used by XML itself like "<" and ">". Therefore all the values have to be filtered or modified to ensure that the value does not end up as the XML itself. This is called "escaping". With this we are able to construct any XML body. This script will then be store as a script by itself. It always write to a global variable like $$xml so that it does not even need to return a value. The script then becomes a function that create xml nodes.

How then should we add headers. It is very simple. Since we always access to the same address, the header seldom changes. Why not just store it as a plain variable? This is exactly what I did.

In another script we will assemble the xml step by step. Fist we store the header into the variable $$xml. Then we use "run script" to run the script that creates the xml by passing the appropriate values beginning with a code that define what type of nodes we are creating. Repeat the subscript till the whole xml is complete. The result is then a well formed xml. You could even test the output by storing the $$xml in a field or just a custom dialog to ensure that the xml is correctly form by copying and pasting the result in a xml editor.

With the xml available, the next task is to send it to the Apple web services (GSX). Luckily, this functionality is available as a plug-in. BaseElements has the plug-in that could do a post to a website and get a respond into a variable instead of a input field. This functionality is exactly what we need to talk to the server.

The last part is to get the result out of the xml. This functionality is again not available. However, BaseElements does have the functionality to extract values from the xml. It may not be the functionality that I am looking at but at least it can be done. The best way is to transform the whole response xml into something  that is humanly manageable like an array without having to write long codes to do it. But then with the limitations, it is still better than nothing.

The conclusion is that Filemaker can talk to web services. With the database capability, getting chunks data out of the web services is a possibility.

MBS has an excellent example of communicating with GSX. MBS Blog.

Apple will be changing the format used for sending and receiving data.  Please go to part 2 to see how it could be done.