1. Configuring Applications Using Application Composer
  2. How to Call SOAP Web Services

How to Call SOAP Web Services

You can call SOAP web services from your Groovy scripts in Application Composer. You might call a web service for access to internal or external data, or for example, to perform a calculation on your data.

Calling web service methods from your scripts involves two high-level steps:

  1. Creating a reference to the web service. This includes registering the web service with a variable name that you use in your Groovy code.

  2. Writing Groovy code in Expression Builder that calls the web service. For each call, the code must prepare the inbound arguments to the web service, call a web service method, and then process the return value from the web service.

Creating a Web Service Reference

To register a web service for use in your scripts, you first select Web Services in the Common Setup pane in Application Composer, then select SOAP. You then associate a web service variable name with a URL that provides the location of the Web Service Description Language (WSDL) resource that represents the service you want to call.

For example, you might register a web service variable name of EmployeeService for a web service that your application needs to call for working with employee data from another system. The URL for this web service's WSDL might be:

http://example.com:8099/Services/EmployeeService?WSDL

Of course, the server name, the port number, and path name for your actual service will be different. If the port number is omitted, then it's assumed that the service is listening on the default HTTP port number 80.

Read "SOAP Web Service References for Groovy Scripts: Explained" for more information about creating web service references.

Writing Groovy Code to Call a Web Service

When you call a web service from a Groovy script, the code must prepare the arguments to the web service before calling a web service method, and then process the data returned from the web service. If your code passes structured data to and from a web service, read "Using Groovy Maps and Lists with Web Services" below.

You insert the code for the call to the web service from the Web Services tab in Expression Builder. The Web Services list displays the set of registered web service variable names and the Functions list displays the available methods for a given web service.

To insert a call to a web service in a Groovy script.

  1. Select the Web Services tab in Expression Builder.

  2. Select a variable name from the Web Services list.

  3. Select a method from the Functions list.

    The code that will be inserted is shown under Function Signature.

  4. Click the Insert button to insert the code to call the web service method.

A web service call from a Groovy script has the following syntax:

adf.webServices.YourServiceVariableName.MethodName(args)

The information under function signature includes the parameter types and also the return type to indicate the type of variable the result of the call should be assigned to. The possible return types are as follows:

Return Value

Return Type

Void

Void

Scalar values (integer, string and so on)

The actual Java return type

Object

Map

Collection

List

Using Groovy Maps and Lists with Web Services

When passing and receiving structured data to and from a web service, a Groovy map represents an object and its properties. For example, an Employee object with properties named Empno, Ename, Sal, and Hiredate would be represented by a map object having four key-value pairs, where the names of the properties are the keys.

You can create an empty Map object using the syntax: 

def newEmp = [:]

Then, you can add properties to the map using the explicit put() method like this: 

newEmp.put("Empno",1234) 
newEmp.put("Ename","Sean") 
newEmp.put("Sal",9876) 
newEmp.put("Hiredate",date(2013,8,11))

Alternatively, and more conveniently, you can assign and update map key-value pairs using a simpler direct assignment notation like this: 

newEmp.Empno = 1234 
newEmp.Ename = "Sean" 
newEmp.Sal = 9876 
newEmp.Hiredate = date(2013,8,11)

Finally, you can also create a new map and assign some or all of its properties in a single operation using the constructor syntax:

def newEmp = [Empno : 1234,
              Ename : "Sean",
              Sal : 9876,
              Hiredate : date(2013,8,11)]

To create a collection of objects you use the Groovy List object. You can create one object at a time and then create an empty list, and call the list's add() method to add both objects to the list:

def dependent1 = [Name : "Dave",
                  BirthYear : 1996]
def dependent2 = [Name : "Jenna",
                  BirthYear : 1999]
def listOfDependents = []
listOfDependents.add(dependent1)
listOfDependents.add(dependent2)

To save a few steps, the last three lines in the preceding example can be done in a single line by constructing a new list with the two desired elements in one line like this:

def listOfDependents = [dependent1, dependent2]

You can also create the list of maps in a single operation using a combination of list constructor syntax and map constructor syntax:

def listOfDependents = [[Name : "Dave",
                         BirthYear : 1996],
                        [Name : "Jenna",
                         BirthYear : 1999]]

If the employee object in the previous codes examples has a property named Dependents that's a list of objects representing dependent children, you can assign the property using the same syntax as shown above (using a list of maps as the value assigned):

newEmp.Dependents = [[Name : "Dave",
                      BirthYear : 1996],
                     [Name : "Jenna",
                      BirthYear : 1999]]

Lastly, note that you can also construct a new employee with nested dependents all in a single statement by further nesting the constructor syntax:

def newEmp = [Empno : 1234,
              Ename : "Sean",
              Sal : 9876,
              Hiredate : date(2013,8,11),
              Dependents : [
                   [Name : "Dave",
                    BirthYear : 1996],
                   [Name : "Jenna",
                    BirthYear : 1999]]
              ]

For more information on maps and lists, see the section called Working with Maps in the Groovy Scripting Reference guide.

Related Topics