Implementing SOAP Web Services with LANSA Integrator

This article originally published in the Architects Corner section of our LANSA Review customer magazine Issue 33, 2006.

There is a wealth of material on the Web and in print about Web services, so rather than formal definitions, technical specifications and standards, this article will describe Web services in a less formal and more practical way. First, we will look at what Web services can do for you, their relationship with SOA and why you do need to understand all this. Then we will outline how LANSA Integrator takes the complexity out of implementing Web services for LANSA and 3GL developers alike.

This is just a brief outline of how to implement Web services using LANSA Integrator. Web services are just one of the many "Java services" you can rapidly integrate into your System i, Windows or UNIX business applications with LANSA Integrator. The LANSA Web site has a range of LANSA Integrator documentation including online demonstrations and tutorials that you can complete at your leisure.

What can Web Services do for You?

First, let's try to stop thinking of the Internet as being what you can see in your browser. These days much more transpires on the Internet than meets the eye. Web services are "Web services" not because you access them through your browser, but because you implement them using Internet protocols and standards such as XML and HTTP over a common, shared infrastructure backbone.

By using Web services you can turn the most traditional character-based or batch application into an Internet application. By this, I do not mean that a colorful, graphically rich interface will magically replace your 80 x 24 green-screens (as it happens, LANSA has another solution for that). What I mean is that if your application is enhanced or extended to offer or implement some of its functionality by means of Web services, then it becomes an Internet application. This can become an important aspect of application modernization — in some cases, the only aspect that really matters.

You can think of Web services as a highly abstracted means of calling and exchanging information between programs. The crucial difference from traditional techniques (and perhaps the most compelling motivation for the development of Web services) is that you don't need to know any details of the program implementation. You don't need to know what language the other program is written in, what operating system it runs on, whether it uses EBCDIC or ASCII, what protocols are necessary to invoke it or where it is located. At least that's the theory.

In the simplest sense, Web services are a means of using or publishing application functionality from or to any other connected computer in your organization or across the world. The functionality is typically packaged up as discrete methods or operations, each receiving parameters or returning data.

If you are familiar with the concepts of object-oriented programming (OOP), you might think that this is OOP by a different name. While there are some parallels, Web services are generally much "chunkier" and typically represent organizational entities, their attributes and operations. One general characteristic of Web services (and SOA) implementations is that the external interface they present tends to reflect more closely the real-world view of the organization and its operations. This leads me to the next item.

What About Web Services and Service Oriented Architecture?

The first thing to understand is that SOA is not a product. It is a design pattern or architecture that is a logical progression, albeit an important one, of previous architectural approaches in response to contemporary expectations and demands for responsiveness and flexibility in IT.

SOA is independent of platforms, tools and standards and there are many possible ways of implementing an SOA. Web services on the other hand, are a concrete example of a set of standards and protocols that may be used to implement SOA. The common thread that binds the two is in the word "service."

One way to begin to realize the benefits of SOA is to implement Web services that can be combined to create a composite application, reused across multiple applications and replaced with an equivalent that exposes the same interface.

Why do I Need to Understand Web Services?

The first and most important reason may be that you don't have any choice.

One of the key trends in recent years has been the integration of business processes, both inside and outside an organization. There are many business drivers for this trend — you may have heard phrases such as streamlining business processes, improving data quality, increasing responsiveness, reducing inventory levels etc. — and the reality is that integration may not be at the discretion of the IT department, but rather be mandated by business requirements.

A second reason concerns application architecture. Many developers will claim to have been following the essential principles of SOA long before the term was coined. However the SOA approach can be distinguished from past architectural practice in two ways. Firstly, by an emphasis on interoperability through the use of widely accepted standards and secondly, by a view of services that is much closer to the business view. At present, Web services are the most accessible framework for implementing SOA.

The third reason concerns modernization of "legacy" applications. The term legacy seems to have acquired negative connotations when, in many cases, what we mean by legacy applications are those that are at the heart of the operation of most enterprises today.

Many of these applications were developed before the emergence of the trends discussed here and need to be adapted. Modernization can take many forms, but attaching Web service interfaces to existing applications can be one way to ensure their continued relevance. Compared to other processes this can often be a relatively inexpensive technique.

LANSA Integrator Makes Web Service Implementation Easier

Despite the attention and hype surrounding Web services and the touted benefits, the technology has not yet lived up to its full potential. Standards are still developing and interoperability for early adopters has not always met expectations. This lack of maturity and interoperability, along with the plethora of standards and supporting technologies can make developing applications that publish or use Web services a daunting task.

LANSA Integrator provides a framework that allows easy integration between Java programs and business applications using the Java Service Manager and a range of shipped Java services. Included amongst the shipped services are the SOAP Agent and SOAP Server services used to implement Web services. SOAP is an XML-based protocol for exchanging information over HTTP.

Using these services, organizations can enter the world of Web services with relative ease. LANSA Integrator offers a wizard-based approach to Web service development and hides the complexities of the protocols to present a simplified interface to developers. LANSA Integrator facilitates the mapping of XML data and automatically generates the supporting Java and XML objects.

The diagrams and code examples in this article are based on the SOAP Server and SOAP Agent Step-by-Step tutorials. You can find links to these tutorials in the online version of this article in the White Papers & Reports section of the LANSA Web site.

What are SOAP Agents and SOAP Servers?

LANSA Integrator supports two types of Web service projects, SOAP Agents and SOAP Servers.

You define a SOAP Agent project when you want to consume (call) an existing Web service from your LANSA or 3GL application. In this case, the operations and parameters of the Web service are externally defined and you have to write your application to conform to that definition.

The publisher of the Web service will usually provide this definition in an XML document containing meta-data describing the Web service in a standard format using Web Service Description Language (WSDL). The LANSA Integrator SOAP Wizard takes care of importing the definition for you.

You define a SOAP Server project when you wish to publish a Web service from your LANSA or 3GL application that other applications can call. In this case, you usually have control over the definition of the operations and parameters that you describe using the SOAP Wizard. LANSA Integrator will then publish the description of your Web service for you using WSDL.

Figure 1: The LANSA Integrator Studio is a development environment
for specifying mappings and other information for solutions using
LANSA Integrator services and is also the central point for managing
and deploying LANSA Integrator services and solutions.

Figure 2: With the SOAP Wizard, you define or select Web service
operations and map Web service parameters to program variables.
The names in brackets are program variables that provide or receive
the value of the corresponding Web service parameters.

Figure 3: In a LANSA application, you invoke LANSA Integrator services
using the LANSA Built-in Functions. You can do this from RDML/RDMLX
functions, forms, or reusable parts. Note: exception handling code has
been omitted for brevity and clarity.

How do You Implement Web Services with LANSA Integrator?

Whether you are creating a SOAP Agent or SOAP Server project, you will complete the same basic steps using the LANSA Integrator SOAP Wizard and Studio to define your SOAP solution:

Step 1: Create a new solution using the LANSA Integrator Studio
The LANSA Integrator Studio (see Figure 1) provides a development environment for specifying configuration, mappings and other information for Web and Java services and acts as a central point for managing and deploying LANSA Integrator services and solutions.

You begin your Web services project by creating a new solution in the LANSA Integrator Studio. If you are creating a SOAP Agent solution, LANSA Integrator will prompt you to provide the WSDL for the Web service that you wish to use.

Step 2: Select Web Service Operations and Map Parameters
Using the SOAP Wizard (see Figure 2) you select the operations of the Web service you wish to consume in a SOAP Agent solution or define the operations and parameters of the Web service used in a SOAP Server solution.

In both cases, you map the inbound and outbound parameters for each operation to program variables in the way that best suits how you process them in your application.

Step 3: Create Your Application Code
LANSA Integrator Studio can help you get started by generating the outline RDML code for your application to use the SOAP solution you have defined.

In a LANSA RDML/RDMLX function, form, or reuseable part, you invoke LANSA Integrator services using LANSA Built-in Functions that are supplied for the purpose.

Although not illustrated here, you can also invoke LANSA Integrator services from 3GL applications — for example from an ILE RPG application — using a straightforward API.

The preceding steps represent the main application development tasks associated with implementing Web services using LANSA Integrator.

Naturally, there are further tasks associated with configuration, building and deploying the solution. The LANSA Integrator Studio assists with these tasks and they are described in more detail in LANSA Integrator documentation and tutorials.

From publishing and consuming Web services to easily formatting and
distributing documents, LANSA Integrator is the practical choice to
transfer and convert data in any format between your applications
and those of your trading partners – regardless of platform.

SOAP Agent Code Example

Let's review the basic structure of the LANSA code necessary to call a simple Web service (see Figure 3):

Connect and load: This step readies the program for calling the Web service by opening a Java Service Manager (JSM) connection and loading the SOAP Agent service. It then loads the EMPLOYEEAGENT Web service solution that was defined with the LANSA Integrator SOAP Wizard.
Set operation and parameters: Next, you specify that you wish to call the GETEMPLOYEES operation of the Web service. The two SET PARAMETER commands "bind" the program variables #DEPTMENT and #SECTION to the corresponding parameters of the operation.
The Java Service Manager has access to the variables in the LANSA program by means of the SERVICE_EXCHANGE (*FIELD) keyword; it then knows which field to map to which parameter via the mappings that were specified in the SOAP Wizard.
Execute / call: This code in this step executes (calls) the Web service and waits for the response.
Retrieve and process results: This code executes the GET service command to retrieve the information for employees belonging to the department and section that were specified in the operation parameters.
Unload and disconnect: When complete, you unload the service and close the connection to the JSM.

SOAP Server Extends the Reach of your Applications

The LANSA code for a SOAP Server project has a very similar structure to that used for SOAP Agent. Your LANSA function will typically be invoked by an HTTP Server when it receives the Web service request.

The LANSA function needs to perform similar steps to connect to the JSM and load the SOAP Server service, identify and receive the request, process the request, then prepare and send the response and unload and disconnect from the JSM.

The middle part, where your application-specific logic processes the request, is the most interesting part. This can include calls to existing LANSA or 3GL programs. You can expose the key functionality of existing applications to other applications without changing the original application code.

LANSA Integrator Supports Many Other Java services

LANSA Integrator takes the complexity out of implementing Web services for a LANSA or traditional 3GL developer. But LANSA Integrator is not just about Web services.

In the simplest terms, LANSA Integrator provides a framework that allows easy integration between Java programs and business applications written using LANSA or 3GLs such as C, RPG or COBOL. It consists of the Java Service Manager and a range of shipped services.

The SOAP Agent and SOAP Server services are just two of the services supplied by LANSA. LANSA Integrator comes with a range of services that handle common integration tasks such as processing XML, transporting data over common protocols such as FTP, HTTP or by e-mail and for creating and reading common file types such as PDF, ZIP, CSV and Excel workbooks.

These services expose a simple interface to the application developer that hides the complexity of interacting with a Java program or of dealing with the intricacies of the underlying transport method or protocol. It is also possible to write your own Java services.

Web Services in Action at LANSA Customer Sites

E.P. Barrus Ltd, located in the U.K., designs and manufactures engines and distributes a diverse range of products including MTD lawn and garden machinery, moto-roma scooters and motorcycles, Mercury, Mariner and Yanmar marine and industrial engines. Barrus uses LANSA Integrator to exchange EDI messages with its trading partners, including B&Q, the largest do-it-yourself chain in Europe and the third largest in the world. Barrus uses LANSA Integrator on its dealer Web site to utilize Web services from Epitomy, a company specializing in exploding diagrams, so dealers can dissect engine diagrams to select the part they need. A SOAP message is sent back to Barrus' Web site so the dealer can complete the order. Read the E.P. Barrus Case Study

The Board of Studies New South Wales is responsible for the content, distribution and logistics of syllabus materials for High Schools in NSW, the most populous state in Australia. The Board offers a growing number of browser-based services used by around 900 high schools to submit and maintain enrollment and achievement details for students. With LANSA Integrator, the Board is extending its browser-based services with Web services to take away the need for data entry by schools and implementing Web services to and from TAFE NSW, Australia's largest Technical And Further Educational institution, to make the exchange of a huge amount of information about students and courses, currently exchanged and reconciled manually, seamless and automatic. The Board also uses LANSA Integrator to access Web services for credit card payments. Read the Board of Studies Case Study

COMMON, the world's largest group of IBM and IBM-compatible information technology users with over 6,500 members, uses LANSA Integrator for Web services to tie the conference registration fee with hotel registration. COMMON's housing company, Passkey, provided LANSA with the WSDL to identify the rules and methods to call their API. LANSA Integrator created a SOAP transaction over HTTPS using the WSDL to send and retrieve data via the API. When the attendee selects a conference hotel, the Web services API verifies the housing registration code and determines the corresponding conference registration fee and gives a discount to attendees who stay at a designated hotel before the payment process begins.

REHAU logo REHAU AG+Co in Germany is one of the largest polymer processing companies in the world, manufacturing components for the construction, automotive and medical sectors and virtually every other industry. REHAU's small development team used Visual LANSA to develop its ERP system, deployed on 21 iSeries machines in 23 languages and used by staff at 170 locations worldwide. REHAU's local iSeries machines exchange transactions and statistics on large building projects and customers that affect multiple regions, with a combination of LANSA Integrator's SQL Service and Web services. LANSA Integrator also supports Web services and XML transactions with third-party systems and SAP Financials. Read the Rehau Case Study

Swinburne University logo The Swinburne University of Technology, in Melbourne, Australia, has a strong reputation as a provider of career-orientated education and as a university with a commitment to research. When the Australian Government implemented the Commonwealth Higher Education Student Support Number (CHESSN), the Swinburne University of Technology used LANSA-based Web services, with the help of local LANSA business partner Watershed Systems, to comply with the legislated requirements within the given time frame. The CHESSN interface between the Government and higher education providers is based on Web services and allows for a two-way flow of data.

Terminix logo The Terminix International Company in the USA is part of the ServiceMaster family of brands and the largest pest control company in the world. Terminix's central LANSA-based application, used at over 400 locations by 12,000 employees and 5,500 service specialists on the road, also interacts with an increasing number of third-party systems using LANSA Integrator and Web services. For example, Terminix uses Web services to pull in leads generated by the ServiceMaster group on an almost real-time basis and uses address verification software and GPS facilities for efficient scheduling of services. As new addresses are entered in the database, LANSA Integrator triggers a Web service from the ServiceMaster enterprise group to get the associated latitude and longitude and automatically corrects the address to meet U.S. Postal Service standards. Web services from Point Serve, a routing and scheduling specialist, are used to organize appointments into tight routes to minimize technician's drive time. Read the Terminix Case Study