It's difficult to get through a trade magazine these days without reading about XML and Web Services. Unfortunately, the cited examples usually show how to call "Hello World" or Fahrenheit to Celsius conversion type applications. While these are incredibly useful applications <grin>, they don't really illustrate the use of Web Services to address real-world business-to-business requirements.

This article will guide you through some real-world Web service scenarios and provide food for thought regarding how to extend your organization's data and business logic through Web Services. We will define criteria to be used when deciding whether to adopt Web Services or other more traditional communication methods and provide a few pointers on how a new project involving Web Services may be approached.

Sometimes it's easier to determine future direction by reviewing where we've come from and documenting where we're at presently. To determine this, we may ask ourselves: What has your company tried today that hasn't been as successful as it was projected to be? What went wrong with that project or implementation and how will that slant your next efforts? How does cross-platform communication happen today within the organization? It is quite possible that an existing cross-platform communication mechanism already exists that may be re-used without having to adopt Web Services. A short list of scenarios that we've encountered follows. The list may spark some thoughts in your mind as you mentally develop your own list. Along with each traditional communication approach, we've also listed some notes on weaknesses of each method.

Traditional Communication

Use FTP to send a file across the wire and then run a remote command (i.e. ftp>QUOTE RCMD MYCLPGM) to have an RPG program process the file. Flaw: Communication back to initiator can't happen easily. No standardized format for data (e.g. XML). No standardized way to describe the data (e.g. XSD).

Employ HTTP form hijacking by way of dynamically building a URL query string (http://company.com/page.cgi?var1=val1&var1=val2). Flaw: Parameter passing is not relational or robust. Response page from form submission will be HTML that could potentially change at a Web developer's whim. It's not guaranteed that what works today will be there tomorrow.

Try raw sockets from client to server (ugly, but fast). Flaw: This can get complicated because the communication infrastructure must be built from the ground up. You will find yourself building from scratch a lot of the features already available with HTTP and the Apache server.

Use a networked folder to place a request document and poll the folder for a response. Flaw: Polling for responses can be CPU intensive for both parties and can lead to infrastructure problems if widely implemented.

Also possible is SQL Stored Procedures where you use a database as an intermediary place to drop off or pick up data, then utilize stored procedures to manipulate the data. This is a mature technology allowing Java or .NET to very easily connect to RPG programs and DB2 tables. Flaw: While this does work, there are many obvious drawbacks to using a storage tool for communication with the most prominent being that each program needing to gain access has a stored password that can connect directly to your database! On the bright side, SQL Stored Procedures are great for black box applications where you have control over all parts of the equation and third-party access is not necessary.

With SMTP you can send emails from one server to the inbox of another and parse the emails for their content. Flaw: Communications may be delayed by intermediary SMTP queues. Scan and forward servers may change the envelope or delete content, and parsing emails with complex data is time consuming and inefficient.

And last, but not least, EDI where you can employ a value added network, ANSI electronic data interchange standard X.12, or binary synchronous communications to transfer data. EDI is currently the granddaddy of computer-to-computer data communication; however, as we all know, composing, transferring, receiving, and parsing EDI data is often a complex endeavor.

Deciding on Web Services

When deciding whether to utilize Web Services, it is advisable first to identify the requirement that legacy methods will not accommodate. Often the biggest reason for implementing Web Services lies in the need to gain real-time access (with response) to a remote resource in an automated, "program-call" fashion that provides lots of flexibility moving forward. Another reason may be simply that your business partner requires the transfer of an XML document via HTTP (as opposed to a fixed file via FTP). A third reason may be that your IT department simply has read one too many articles about Web Services and wants to implement one!

In the past few years, XML and Web Services have become quite popular. Web Services are fast becoming to computers what the English language is to the European Union-the common language that the majority fluently understands without much translation. For example, there are native RPG tools that make it easier for RPG developers to compose, transmit, receive, and parse XML documents. The use of these standard documents is only a right-click away in the Visual Studio .NET environment.

In the world of rapid change that we live in, rapid development with abstraction tools provides quick turnaround and minimal testing. From an architectural perspective, the loosely coupled method of transferring XML documents by HTTP may be more flexible than attempting to use ODBC connections or other more stateful methods. On the other hand, if the Web service will not leave the security and stability of the local LAN, and the communication involves a database anyway, cross-platform communications using SQL Stored Procedures provides a more tightly coupled, and possibly better, approach. If the communication is internal, and the same platform is on both ends, there may be a proprietary communication mechanism that is easier to implement in the native programmatic environment.

When Not to Use Web Services

• For Data Replication

This is a huge waste of bandwidth. For instance, to send a nine-digit customer number, it could take five times the data (e.g. <ProductionCustomerNumber>123456789</ProductionCustomerNumber>)

• To Replace EDI

Working software should never be replaced simply for the sake of hype. EDI remains the most prominent form of data exchange and will be around for quite some time. RPG is still alive isn't it? Only when EDI has dipped below 30 percent usage should you consider scrapping/replacing it. EDI package vendors are very aware of XML and ofttimes have translators so you can take X.12 to and from XML formats. Also note that EDI serves more of a "batch" process need than one of interactive Web-based communications.

Choosing the Right Time and Resources

It is not necessary to have a Web Services project on the horizon to start learning about the technologies now. Invest the time to read trade magazine articles (found at www.MCPressOnline.com, www.IBMSystemsmag.com, and www.SystemiNetwork.com) so you can be on top of the latest buzz and see how Web Services are progressing. Go through WDSC Web service tutorials (in WDSC menu, Help>Tutorials Gallery). And to educate yourself via newer resources, set up Google Alerts (http://www.google.com/alerts) for "iSeries Web Services," a great way to have content delivered to your desktop. The site, www.w3schools.com has some great short tutorials that take you through the plethora of Web service technologies-perfect for lunchtime reading. Because Web Services are becoming so popular, the question is no longer whether you will implement Web Services, but rather when.

Following are a few real-world examples to illustrate practical uses of Web Services in order to meet common business requirements:

Real-World Example 1

Need: ABC Company needs to verify that potential customers have a high enough credit rating to provide them with homeowner insurance and adjust the premiums accordingly.

Process: The customer navigates her browser to ABCCompany.com and goes through a wizard-like process that gathers personal information. That information is captured, and behind the scenes it is put into XML, and then an HTTPS POST to https://Equifax.com/webservices/checkcredit.cgi occurs. Equifax receives XML, submits a process to batch on their machine, and then responds back with an XML document containing a unique transaction id. That transaction id is used to compose a second XML document on ABC Company's iSeries, which is sent to Equifax to poll for the credit report. If the credit report is done processing, it will be passed back; if not, it will give a message that it is still processing and to check back later. This process continues until the credit report is available (it usually takes only 2-8 seconds). Last, the credit report is used to determine if the user on the Web page will be allowed to continue and be offered an insurance policy with ABC Company. (Note that polling was introduced here, which is not a recommended practice in Web Services because of resource consumption).

Technologies/Specifications: HTTP, SSL (client- and server-side certificates), XML. Specifications are documented by PDF and XSD. No WSDL. No SOAP. ABC Company used RPG on the iSeries to do all communications, XML composing, and XML parsing.

ROI: ABC Company is now able to automate the process of writing new homeowner insurance policies without human intervention. The ability to check the credit of potential customers also keeps unprofitable policies from being written.

Real World Example 2

Need: ABC Company needs to reduce the cost of creating, inserting, and mailing paper invoices to its dealers for parts it is ordering. ABC Company enlists a third party, WeMailInvoices, that offers this service and has an SLA** (Service Level Agreement) which coincides with the dedication to its dealers for prompt creation and delivery of invoices.

Process: Once an hour, ABC Company reads through a DB2 table and batches together invoices to be sent to WeMailInvoices. As records are read, an XML document is composed. Next, the document is sent via HTTPS POST to WeMailInvoices. WeMailInvoices writes it to its database for further processing and provides an XML response back to ABC Company, which marks the invoices as having been successfully sent.

Technologies/Specifications: HTTP, SSL (server side only), XML. XML specification created by ABC Company and third-party complied. ABC Company used RPG on the iSeries to do all communications, XML composing, and XML parsing.

ROI: By outsourcing its paper invoice processes, ABC Company was able to save $15K/month, which paid for the development of Web Services in 3 months.

Real World Example 3

Need: ABC Company needs to provide item-pricing information residing on its iSeries in RPG logic to in-house .NET programmers who are creating a new GUI front-end for order entry. The process to calculate an items price list entails 15 DB2 tables and a lot of business logic. It was decided therefore to re-utilize the already tried-and-true RPG code on the iSeries. ABC Company has plans to expand into more Web Services as needs arise and chose this approach because of the variety of languages and platforms within the organization.

Process: The thick client GUI is displayed to ABC Company's "Order Taker." The Order Taker enters items that the customer requests over the phone. Requests are made to the iSeries as needed to calculate item prices. Each request entails a SOAP/XML HTTP POST sent to the Apache server to request an item calculation. A response is immediately provided, and the item's price is displayed on the Order Taker's screen. Roundtrip Web service has sub-second response times.

Technologies/Specifications: HTTP (Apache on iSeries), SOAP/XML. WSDL was used to define the Web service and XSD to define the XML messages. ABC Company used RPG on the iSeries to do all XML receiving, XML composing, and XML parsing. WSDL is stored on the iSeries under Apache (i.e. http://iseriesip:8181/calcitemprice.wsdl) for easy consumption from the Visual Studio .NET environment.

ROI: Re-utilizing the business logic that exists on the iSeries allows the company to "get to market faster" with a solution than if it had to re-implement the same material in .NET, which would require a large amount of knowledge transfer. It also provides a single point of entry for any programming within ABC Company to calculate an item price.

A Web Service Project

If you are being asked to communicate with a Web service that is already in place, where your iSeries is the client and the Web service is on a remote server, learn what technologies are involved at a high level. Most times it will be HTTP/S, XML, XSD and sometimes WSDL/SOAP, but we are also seeing MQSeries on the rise as a transport mechanism. In the barest form, you will need an example XML document and the URL where the Web service is located.

If SSL is being used, set up the *SYSTEM certificate store in the DCM (Digital Certificate Manager), which is available in the HTTP *ADMIN instance (i.e. http://myiseriesip:2001). (Contact the author for a tutorial on how to do this).

Ask for any login profiles/keys that will enable you to utilize the Web service. This login information is usually sent in the XML document but sometimes HTTP Basic Authentication is used, which resides more at the Apache server level. Login information is multi purpose - validate you have access to the Web service and ensure charges are applied correctly (if it is a pay per use style Web service).

If a WSDL is provided, use that to discover what the different "actions" (read RPG sub procedures) are along with their messages (read data structures/parameters). Use WDSC's Web Service Explorer to do some initial calls to the Web service or download my free Web Service Unit Tester from http://www.mowyourlawn.com/, which gives you full access to the request and response XML for raw data testing.

If you are creating the Web service to be offered from your iSeries, it is best to figure out technologies before you take on a big project since you are the one in charge of determining what should be used and how it should be put together. Doing some initial testing of tools allows you to rule out what will not work without tying yourself to a vendor/language/methodology/process/framework. It will also give you insight into what will be required if new technologies are adopted later. For instance, you can utilize the Java-to-RPG Web service wizards in WDSC, but that inherently means that your change-management system will need to facilitate Java infrastructure/deployment, that your QA team will need to be versed on how to test the new environments, and that your help desk will need to know how to support the new processes.

Taking baby steps allows the testing of performance without getting caught up in business rules. Besides being fun, slapping together an application that tries to break stuff will give you insight as to what your limitations or weaknesses might be.

Once you have chosen a tool and/or technologies, you need to determine the "actions" you want to offer (e.g. CalcItemPrice, IsCustomerValid). Brainstorming these actions can be done simply with Microsoft Word, and the results can later be re-entered into the WDSC WSDL editor if you choose to go the WSDL route (but you don't have to). You could relate this process to creating an RPG service program and determining which sub procedures will be EXPORTed.

Next, determine the messages that will be passed back and forth for each action using WDSC's GUI XSD (XML Schema Definition) editor. Creating an XSD is similar to creating an RPG data structure or DB2 table. You are simply putting rules around the XML data names and their types.

Last, publish the Web service information to an appropriate server. This does not need to be a UDDI server. It can be as simple as an HTML page on your network with a PDF describing the location, actions, and messages for the Web service.

Aaron Bartell and Quentin Krengel are part of Krengel Technology (http://www.krengeltech.com/), which recently developed RPG-XML Suite (http://www.rpg-xml.com/), a tool that enables RPG programmers to easily leverage XML Web Services on the System i5 platform with zero Java involved. Aaron can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. Quentin can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.