Introduction

In an on demand business, enterprise-level applications need to integrate with services provided by other applications, both inside and outside the enterprise. In this article, we illustrate how to use the new SOAP for CICS feature offered by the CICS TS to integrate legacy applications with business processes running in IBM® WebSphere® Business Integration Server Foundation.

In Part 10 of this series, we showed how to create a message adapter in CICS TS for XML to COMMAREA conversion and other service provider-side artifacts. In this article, we illustrate how to create the service requester-side artifacts, and we include the step-by-step methods needed to integrate the legacy services with a BPEL workflow process.

Back to top

Service requester-side changes

We used WebSphere Studio Application Developer Integration Edition and WebSphere Studio Enterprise Developer (Enterprise Developer) tools to generate the requester-side artifacts that are needed to integrate the services provided by the CICS SOAP-enabled transactions. We used WebSphere Studio Application Developer Integration Edition for workflow artifacts development and Enterprise Developer for converting COBOL copybooks to XML schema elements. See Resources for more information on the WebSphere Studio Application Developer Integration Edition and Enterprise Developer.

A Web service consumer/client uses a Web Services Description Language (WSDL) file that describes the services exposed by the CICS server and the definition of data exchanged between the client and the service.

You can use Enterprise Developer for performing the following steps:

1. Create XML schema files from the COBOL copybook ,which represents the input and output business logic program COMMAREA (see the sidebar Limitations of Enterprise Developer tools -- generated COMMAREA XML schema).
2. Generate a WSDL file for the services exposed by the CICS server that includes the XML schema elements from the above step.

Note that in a top-down approach, in addition to Enterprise Developer, you could use IBM WebSphere Business Integration Server Foundation to build a WSDL file that represents the services provided by the CICS SOAP-enabled transactions.

Listing 1 shows the WSDL file that represents the CICS order validation program.

				


<wsdl:definitions name="CoatsCicsServices" 
           targetNamespace=http://tempuri.org/CoatsCicsServices/ 
xmlns:tns="http://tempuri.org/CoatsCicsServices/" 
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsd1="http://www.coats.com/schemas/ValidateOrderIInterface" 
xmlns:xsd2="http://www.coats.com/schemas/ValidateOrderOInterface">
<wsdl:types>
   <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <xsd:import namespace="http://www.coats.com/schemas/ValidateOrderOInterface"     
schemaLocation="../www/schemas/ValidateOrderOInterface/ValidateOrderResponse.xsd">
      </xsd:import>
      <xsd:import namespace="http://www.coats.com/schemas/ValidateOrderIInterface" 
schemaLocation="../www/schemas/ValidateOrderIInterface/ValidateOrderRequest.xsd">
      </xsd:import>
   </xsd:schema>
</wsdl:types>
<wsdl:message name="ValidateOrderIMessage">
    <wsdl:part name="ValidateOrderRequest" type="xsd1:ValidateOrderRequest">
          </wsdl:part>
</wsdl:message>
<wsdl:message name="ValidateOrderOMessage">
    <wsdl:part name="ValidateOrderResponse" type="xsd2:ValidateOrderResponse">
          </wsdl:part>
</wsdl:message>
<wsdl:portType name="ValidateOrderPortType">
    <wsdl:operation name="ValidateOrderOperation">
       <wsdl:input message="tns:ValidateOrderIMessage" 
                  name="ValidateOrderOperationInput">
         </wsdl:input>
       <wsdl:output message="tns:ValidateOrderOMessage" 
                  name="ValidateOrderOperationOutput">
       </wsdl:output>
    </wsdl:operation>
</wsdl:portType>
<wsdl:binding name="CoatsSOAPBinding" type="tns:ValidateOrderPortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
    <wsdl:operation name="ValidateOrderOperation">
        <soap:operation 
              soapAction="http://tempuri.org/CoatsCicsServices/ValidateOrderOperation" />
        <wsdl:input name="ValidateOrderOperationInput">
            <soap:body use="literal" parts="ValidateOrderRequest"/>
        </wsdl:input>
        <wsdl:output name="ValidateOrderOperationOutput">
            <soap:body use="literal" parts="ValidateOrderResponse"/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>
<wsdl:service name="CoatsSOAPService">
    <wsdl:port name="CoatsSOAPServicePort" binding="tns:CoatsSOAPBinding">
        <soap:address 
              location="http://cics.server.host:5432/CICS/XWBA/DFHWSDSH/ORDVLDT" />
     </wsdl:port>
</wsdl:service>
</wsdl:definitions> 

The following sections illustrate the steps needed to integrate the CICS services represented in the WSDL file (Listing 1) with a workflow. WebSphere Studio Application Developer Integration Edition Version 5.1.1 was used to develop a WebSphere Process Choreographer BPEL workflow. The major steps are:

1. Set up the WebSphere Studio Application Developer Integration Edition workspace with CICS service WSDL and XML schema files
2. Create client-side proxies from WSDL.
3. Create a wrapper service implementation, WSDL, and binding for the client proxy.
4. Create a business process workflow to invoke the CICS service.
5. Generate the BPEL deploy code.

Back to top

Step 1. Set up the WebSphere Studio Application Developer Integration Edition workspace with CICS service WSDL and XML schema files

If the WSDL was created outside Step 1, import it. You also need to import the XML schema files referenced by the WSDL file that specify the request and response message formats.

As shown in Listing 1, the service port address specified in the WSDL file is: location=http://cics.server.host:5432/CICS/XWBA/DFHWSDSH/ORDVLDT. Your CICS host is located at cics.server.host and is listening on port 5432 for incoming HTTP requests. The CICS region specified is XWBA and the message adapter program is called ORDVLDT. This is a fictitious URL, so the sample application below demonstrates a technique and is not intended to produce a working CICS service.

Figure 1 shows the workspace after creating or importing the CICS service WSDL file and the XML schema for its input and output. The XML schema package names reflect those specified by the type of WSDL namespaces. As mentioned in Part 10 of this series, these namespace declarations are required to map the request/response to the correct proxy code used for marshalling/unmarshalling XML to native runtime classes.

Back to top

Step 2. Create the client proxy

The WebSphere Application Server Enterprise Process Choreographer workflow acts as the Web service client/consumer by setting up and calling the SOAP CICS Web service. It also uses the returned results in the workflow activities that follow. In WebSphere Studio Application Developer Integration Edition, the Web service client code can be automatically generated from the WSDL file. To complete this step, right-click on the WSDL file and choose Enterprise Services-Generate Service Proxy. This option launches a wizard, as shown in Figure 2. For your example scenario, you need to select the Web Services Invocation Framework (WSIF) proxy type.

This option displays another dialog box, as shown in Figure 3. You need to make sure to select Generate helper classes. This generates the Java™ classes needed to marshall and unmarshall the SOAP XML for the CICS SOAP request and response. Also, select a package name for the generated proxy class.

Click Next to display another dialog, as shown in Figure 4. Select Client stub proxy style and select the WSDL operations that will be accessed from the workflow. Click Finish.

Figure 5 shows the newly generated Web service proxy files. Before generating the proxy, only the highlighted WSDL and XML schema existed. After the generation, the proxy and helper classes have been created.

Back to top

Step 3. Create a wrapper service, WSDL, and service binding for the client proxy

Create a new Java class with methods for each of the WSDL operations. In this example, you'll only have one method. The helper classes you generated in the previous step are used to map data elements between XML and Java. Figure 6 shows a view of this mapping to the request message. The response message is mapped in a similar fashion.

The implementation code of your wrapper Web service client uses the Java classes corresponding to the XML schema to build the SOAP CICS request.

Listing 2 shows sample code that builds the Java classes for the SOAP message and calls the proxy to invoke the CICS service. You have one method, ValidateOrder, that corresponds to the WSDL operation you have selected. You build the request XML document starting from the innermost element and work your way out to the root element. You also use the generated helper classes to process the response. As shown in Listing 2, the response message works the opposite way. Here you start at the root XML element and work your way down through the elements it contains.

				
public class COATSAccess {
  public void ValidateOrder(String requestType) {
    // set up CICS SOAP request 
    ValidateOrderPortTypeProxy aProxy = new ValidateOrderPortTypeProxy();
    FeatureList.FeatureListItemElementLocal featureListElement1 = new
    FeatureList.FeatureListItemElementLocal();
    featureListElement1.setFeatureCode("Storage");
    featureListElement1.setQuantity(2);
    FeatureList featureList = new FeatureList();
    featureList.setFeatureListItem(0, featureListElement1);
    FeatureList.FeatureListItemElementLocal featureListElement2 = new
    FeatureList.FeatureListItemElementLocal();
    featureListElement2.setFeatureCode("Memory");
    featureListElement2.setQuantity(6);
    featureList.setFeatureListItem(1, featureListElement2);
    
    ValidateOrderRequest validateOrderRequest = new ValidateOrderRequest();
    validateOrderRequest.setOrderNumber("1234567");
    validateOrderRequest.setType("Online");
    validateOrderRequest.setFeatList(featureList);
    
     // call the CICS SOAP web service
    ValidateOrderResponse validateOrderResponse = 
aProxy.ValidateOrderOperation(validateOrderRequest);

    // process CICS SOAP response  
   OrderMessages orderResponse = validateOrderResponse.getMessages();
   OrderMessageElementLocal[] orderMessages = orderResponse.getOrderMessage();
    System.out.println("CICS Web Service SOAP Response: " +
                       "Return Code:" + validateOrderResponse.getReturnCode() );
    for (int i = 0; i < orderMessages.length; i++) {
        System.out.println("Message Prefix: " + orderMessages[i].getMessagePrefix() +
			  ", Text: " + orderMessages[i].getMessageText());
    }
  }
}

Now generate a service WSDL from this Java class. Right-click the wrapper class and select the New-Service Built From tool option. Select the correct options and generate the WSDL for the exposed service methods, as shown in Figure 7.

This creates a COATSAccessJavaService.wsdl file. Now, you need to generate the binding and deployment files from the WSDL. Right-click on this WSDL file and select Enterprise Services-Generate Deploy Code. As shown in Figure 8, choose SOAP as the inbound binding and click Finish.

Back to top

Step 4: Create a business process workflow to invoke the CICS service

This section illustrates how to create a simple business process to invoke the CICS service wrapper created in Step 3. This service wrapper in turn calls the CICS service using the SOAP client proxy created in Step 2.

Select File > New > Business Process from the WebSphere Studio Application Developer Integration Edition workbench. Figure 9 shows a dialog to provide a name and package for the new BPEL process.

As shown in the Figure 10, choose a Sequence-based BPEL and click Finish. This generates a BPEL and opens the BPEL editor in WebSphere Studio Application Developer Integration Edition.

As shown in Figure 11, insert a new partner link named ValidateOrder. On the Implementation tab, click New next to Partner Link Type.

This option displays a dialog box, as shown in Figure 12. Choose One Role. Name the role "validate" and click Browse. Locate your service wrapper WSDL file (COATSAccess.wsdl) and click OK.

As shown in Figure 13, create two process variables -- one for input (ValidateIn) into the service invoke and one for the output (ValidateOut).

Click the "ValidateIn" variable and then click Browse to the right of file in the Message tab. Locate the WSDL for the wrapper service and then choose the input request, as shown in Figure 14.

Follow the same process for ValidateOut and point it to the "ValidateOrderResponse" part in the WSDL file.

Now, add an invoke activity between "Receive" and "Reply" activities to call the CICS service from the process. Wire the new InvokeOrderValidation activity to the partner link and operation and to the input and output process variables you created above, as shown in Figure 15.

Back to top

Step 5. Generate the BPEL deploy code

Right-click the process BPEL file (OrderValidate.bpel) and select Enterprise Services-Generate Deploy Code.

Click the Referenced Partners (ValidateOrder) and click "Browse" to locate the service WSDL file ("COATSAccessJavaService.wsdl") for the Java service wrapper you created in Step 3. Then click OK to generate BPEL deploy code.

You're now ready to run the process, which calls the CICS Web service.

Back to top

Conclusion

In this article, we showed step-by-step methods for developing the artifacts needed to invoke legacy CICS business logic from a workflow process using the SOAP for CICS feature. We showed how to develop service requester-side artifacts and how to integrate the CICS services with the workflow. In addition, we described the use of various tools including Enterprise Developer, WebSphere Studio Application Developer Integration Edition, and runtime environments, such as WebSphere Business Integration Server Foundation and CICS.

Resources

• Check out "On demand business process life cycle: Build reusable assets to transform an order processing system" (developerWorks, December 2004) for a complete listing of articles in this series.
  
  
• Get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere. You can download evaluation versions of the products at no charge, or select the Linux® or Windows® version of developerWorks' Software Evaluation Kit.
  
  
• Extend and integrate your existing IT assets using WebSphere Studio Application Developer Integration Edition, a next generation integrated development environment (IDE), and deploy them to WebSphere Business Integration Server Foundation.
  
  
• Use Enterprise Developer to enable your CICS application as a Web service provider with "XML and Web Services for the Enterprise: Providing XML and Web Services Interface To a CICS Application".
  
  
• Learn about enabling CICS for the Internet with "Architecting e-business Access to CICS Update".
  
  
• Download the SOAP for CICS: User's Guide (SC34-6315) from the IBM Publications Center.
  
  
• For more information about SOAP, read the SOAP World Wide Web Consortium SOAP specification.
  
  
• Browse the WebSphere Application Developer -- Integration Edition InfoCenter.
  
  
• Explore the enhanced features available with CICS TS V3.1.
  
  
• Browse for books on these and other technical topics.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Want more? The developerWorks SOA and Web services zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Service requester-side changes
• Step 1. Set up the WebSphere Studio Application Developer Integration Edition workspace with CICS service WSDL and XML schema files
• Step 2. Create the client proxy
• Step 3. Create a wrapper service, WSDL, and service binding for the client proxy
• Step 4: Create a business process workflow to invoke the CICS service
• Step 5. Generate the BPEL deploy code
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

Rational Tester for SOA Quality is an automated web services testing and SOA testing tool that supports Web services SOAP, HTTP(S), JMS, WS-Security, UDDI, and RESTful standards.

---

• Try: The no-charge Rational Service Tester for SOA Quality helps quality assurance professionals validate web service based SOA application..
• Article: See the whats new with Rational Service Tester for SOA Quality, and its Generic Service Client, which provides a single client to interact with any SOA service type.
• Tutorial: Get hands-on experience with this Transport for SOAP feature tutorial using Rational Tester for SOA Quality.
• Buy: Rational Service Tester for SOA Quality

My developerWorks community

Dig deeper into SOA and Web services on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers