A Simple Example
If you read through the SUDS documentation, you'll see that the Client object is the primary interface for most users. It is extremely simple using this object and a few print statements to view a list of available methods provided by the web service you are connecting to. This example will illustrate how to make an initial connect to a web service, print out the list of available methods, and then call one of these methods and display the resulting value in a label on an Ignition window at the push of a button. The below example uses a public web service and is available for anyone to test against.
First, we can use the script playground to test out some scripting calls and see the output. The below example shows how to get a reference to a client object. By printing this client object to the console we get an output of all the available methods, types, and other information about the web service as defined in the WSDL file.
This WSDL defines two functions: CelsiusToFahrenheit(string tempCelsius) and FahrenheitToCelsius(string tempFahrenheit). These are the functions that this web service makes available to you. Don't worry about the fact that the methods are listed twice. This is just because the WSDL has two definitions of the functions that are formatted for different SOAP version standards. To call these functions in Ignition scripting, you have to make use of the "service" member of the client object. You can see printing the returned results shows the conversion.
To make a simple conversion window in an Ignition project you can add a button, a numeric textbox, and a label to a window. Then on the button to calculate a Fahrenheit to Celsius calculation, you would place something like the following:
Then you can make a second button to do the opposite: calculate Celsius to Fahrenheit.
With your scripts in place your window should now function as a simple temperature conversion tool!
Beyond the Example
While the example is relatively simple, it can easily be expanded upon. However, always keep the general workflow in mind when using the SUDS library:
In the overview, the methods provided by the web service were very simple and took simple argument types. Sometimes however, the web service will describe complex types and allow you create instances of these types that can then be added to the system/machine that the web service is providing an interface for.
A simple, hypothetical example of this would be a system that stores contact information of clients and can be used as an address book of sorts by other systems on the network. It may provide not only a way to pull contact information for a certain individual out, but also a way to insert new contacts. We'll keep the example simple and say that contacts have only a name and a phone number.
This example is completely hypothetical. It is intended to give insight into complex types. It does not make use of an an actual functional web service.
For example, say we create and print the client object we associated with our web service in the following manner:
And the resulting output is the following:
Here you can see that, while not too complicated, the web service defines more than just methods that take simple type arguments and return the same. Under the Types section, you can see there are three "complex" types. These are basically just objects like one creates in an object oriented programming language like java. The SUDS Client object has an instance variable called "factory" that allows you to create these complex types so you can use them to invoke methods defined by your web service that take complex arguments.
If we wanted to add a contact using the addContact() method, we have to create a contact object first:
The create function creates a new contact object that knows its own structure. We can view this structure by calling print on this new object and see that it prints the following:
By examining the Contact type object, we can see its structure and know what we need to create in order to have a valid Contact to add to the address book. We could then do the following to supply the necessary information for the Contact object and then call our addContact function.
After execution a new contact will have been added via the web service!
Steps to remember when using complex types: