SUDS - Library Overview
The SUDS Library
The SUDS library is a SOAP-based web services client developed for Python. It is extremely simple to use and practically eliminates the need for the user to understand or even view the WSDL of a web service.
The SUDS library used to be included in the Python Standard Library. However it has since been removed, meaning you may not have access to it when performing a fresh install of Ignition. Additionally, development on the library has mostly ceased, so any copies you find online may be drastically outdated.
The information on this page will be maintained for legacy users that need to be familiar with the old SUDS library. As a result, this page and its contents should be considered deprecated.
The SUDS library interprets the WSDL file for you and through a couple simple function calls allows you to get a list of the available methods provided to you by the web service. You can then invoke these methods in Ignition through event scripting to send and receive data in your projects. You will have to familiarize yourself with the SUDS library in order to make use of it.
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.
Python - W3Schools WSDLfrom suds.client import Client
client = Client("http://www.w3schools.com/xml/tempconvert.asmx?WSDL")
print client
This WSDL defines two functions:
CelsiusToFahrenheit(string tempCelsius)andFahrenheitToCelsius(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:
Python - Fahrenheit to Celsiusfrom suds.client import Client
client = Client("http://www.w3schools.com/xml/tempconvert.asmx?WSDL")
far_value = event.source.parent.getComponent('Numeric Text Field').floatValue
cels_value = client.service.FahrenheitToCelsius(far_value)
event.source.parent.getComponent('Label').text = cels_value
Then you can make a second button to do the opposite: calculate Celsius to Fahrenheit.
Python - Celsius to Fahrenheitfrom suds.client import Client
client = Client("http://www.w3schools.com/xml/tempconvert.asmx?WSDL")
cels_value = event.source.parent.getComponent('Numeric Text Field').floatValue
far_value = client.service.CelsiusToFahrenheit(cels_value)
event.source.parent.getComponent('Label').text = far_value
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:
#Import the SUDS Client object
from suds.client import Client
#Instantiate a new Client Object
client = Client("url_to_your_wsdl")
#Call the desired method using the service instance variable
client.service.MyMethod(myArgument)
Complex Arguments
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:
from suds.client import Client
url = 'http://localhost:7575/webservices/hypothetical_webservice?wsdl'
client = Client(url)
print client
And the resulting output is the following:
Suds ( https://fedorahosted.org/suds/ ) version: 0.4 GA build: R699-20100913
Service (hypothetical_webservice)
Prefixes (0):
Ports (1):
(Soap)
Methods:
addContact(Contact contact, )
getContactList(xs:string str, xs:int length, )
getContactByName(Name name, )
Types (3):
Contact
Name
Phone
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:
contact = client.factory.create('Contact')
print contact
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:
(Contact)=
{
phone = []
age = NONE
name(Name) =
{
last = NONE
first = NONE
}
}
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.
contact = client.factory.create('Contact')
phone= client.factory.create('Phone')
phone.areacode = '916'
phone.number = '5557777'
name = client.factory.create('Name')
name.first = 'John'
name.last = 'Doe'
contact.name = name
contact.phone = phone
contact.age = 30
client.service.addContact(contact)
After execution a new contact will have been added via the web service!
Steps to remember when using complex types:
#Create a new type object using the factory instance variable of the Client object
my_type = client.factory.create('MyType')
#If you don't know the structure of the newly created object then print it to the console
print my_type