Skip to main content
Version: 8.1

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.

Disclaimer

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.

  1. 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 WSDL
    from suds.client import Client
    client = Client("http://www.w3schools.com/xml/tempconvert.asmx?WSDL")
    print client

    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:

  2. 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 Celsius
    from 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

  3. Then you can make a second button to do the opposite: calculate Celsius to Fahrenheit.

    Python - Celsius to Fahrenheit
    from 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

  4. 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:

Pseudocode - WSDL Workflow
#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.

note

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:

Pseudocode - Client Object
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:

Python - Results
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:

Pseudocode - Using a Method
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:

Python - Structure
(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.

Pseudocode - Adding a Contact
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:

Pseudocode - Complex Type Reminders
#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
Last updated on by Zedriel